ironnotify-java/README.md

<p align="center">
  <a href="https://ironnotify.com">
    <img src="https://ironnotify.com/logo.png" alt="IronNotify" width="120" />
  </a>
</p>

<h1 align="center">IronNotify SDK for Java</h1>

<p align="center">
  <strong>Event notifications and alerts for Java applications</strong>
</p>

<p align="center">
  <a href="https://search.maven.org/artifact/com.ironservices/notify"><img src="https://img.shields.io/maven-central/v/com.ironservices/notify.svg" alt="Maven Central"></a>
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
</p>

<p align="center">
  <a href="https://ironnotify.com">Website</a> •
  <a href="https://ironnotify.com/docs">Documentation</a> •
  <a href="https://ironnotify.com/docs/java">Java Guide</a> •
  <a href="https://git.marketally.com/ironservices">Git</a>
</p>

---

**IronNotify** helps you send event notifications and alerts to your users instantly. Built for developers who want simple, powerful notification infrastructure without the complexity.

## Installation

### Maven

```xml
<dependency>
    <groupId>com.ironservices</groupId>
    <artifactId>notify</artifactId>
    <version>1.0.0</version>
</dependency>
```

### Gradle

```groovy
implementation 'com.ironservices:notify:1.0.0'
```

## Quick Start

### Send a Simple Notification

```java
import com.ironservices.notify.*;
import java.util.Map;

public class Main {
    public static void main(String[] args) {
        // Initialize
        IronNotify.init("ak_live_xxxxx");

        // Send a simple notification
        SendResult result = IronNotify.notify(
            "order.created",
            "New Order Received",
            "Order #1234 has been placed",
            SeverityLevel.SUCCESS,
            Map.of("order_id", "1234", "amount", 99.99)
        );

        if (result.isSuccess()) {
            System.out.println("Notification sent: " + result.getNotificationId());
        }

        // Shutdown when done
        IronNotify.shutdown();
    }
}
```

### Fluent Event Builder

```java
import com.ironservices.notify.*;
import java.time.Duration;

public class Main {
    public static void main(String[] args) {
        IronNotify.init("ak_live_xxxxx");

        // Build complex notifications with the fluent API
        SendResult result = IronNotify.event("payment.failed")
            .withTitle("Payment Failed")
            .withMessage("Payment could not be processed")
            .withSeverity(SeverityLevel.ERROR)
            .withMetadata("order_id", "1234")
            .withMetadata("reason", "Card declined")
            .withAction("Retry Payment", "/orders/1234/retry", null, "primary")
            .withAction(EventBuilder.action("Contact Support")
                .handler("open_support")
                .build())
            .forUser("user-123")
            .withDeduplicationKey("payment-failed-1234")
            .expiresIn(Duration.ofHours(24))
            .send();

        if (result.isQueued()) {
            System.out.println("Notification queued for later");
        }

        IronNotify.shutdown();
    }
}
```

### Async Support

```java
import com.ironservices.notify.*;
import java.util.concurrent.CompletableFuture;

public class Main {
    public static void main(String[] args) {
        IronNotify.init("ak_live_xxxxx");

        // Async notification
        CompletableFuture<SendResult> future = IronNotify.notifyAsync(
            "user.signup",
            "New User Registered"
        );

        future.thenAccept(result -> {
            System.out.println("Notification sent: " + result.isSuccess());
        });

        // Async event builder
        IronNotify.event("order.shipped")
            .withTitle("Order Shipped")
            .forUser("user-123")
            .sendAsync()
            .thenAccept(result -> System.out.println("Done!"));

        // Wait for async operations
        future.join();
        IronNotify.shutdown();
    }
}
```

### Using the Client Directly

```java
import com.ironservices.notify.*;

public class Main {
    public static void main(String[] args) {
        NotifyClient client = new NotifyClient(
            NotifyOptions.builder()
                .apiKey("ak_live_xxxxx")
                .debug(true)
                .build()
        );

        // Send notification
        SendResult result = client.notify("event.type", "Title");

        // Use event builder
        result = client.event("event.type")
            .withTitle("Title")
            .send();

        // Clean up
        client.close();
    }
}
```

## Configuration

```java
import com.ironservices.notify.*;
import java.time.Duration;

NotifyClient client = new NotifyClient(
    NotifyOptions.builder()
        .apiKey("ak_live_xxxxx")
        .apiBaseUrl("https://api.ironnotify.com")
        .webSocketUrl("wss://ws.ironnotify.com")
        .debug(false)
        .enableOfflineQueue(true)
        .maxOfflineQueueSize(100)
        .autoReconnect(true)
        .maxReconnectAttempts(5)
        .reconnectDelay(Duration.ofSeconds(1))
        .httpTimeout(Duration.ofSeconds(30))
        .build()
);
```

### Configuration Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `apiKey` | String | required | Your API key (ak_live_xxx or ak_test_xxx) |
| `apiBaseUrl` | String | https://api.ironnotify.com | API base URL |
| `webSocketUrl` | String | wss://ws.ironnotify.com | WebSocket URL |
| `debug` | boolean | false | Enable debug logging |
| `enableOfflineQueue` | boolean | true | Queue notifications when offline |
| `maxOfflineQueueSize` | int | 100 | Max offline queue size |
| `autoReconnect` | boolean | true | Auto-reconnect WebSocket |
| `maxReconnectAttempts` | int | 5 | Max reconnection attempts |
| `reconnectDelay` | Duration | 1s | Base reconnection delay |
| `httpTimeout` | Duration | 30s | HTTP request timeout |

## Severity Levels

```java
SeverityLevel.INFO     // "info"
SeverityLevel.SUCCESS  // "success"
SeverityLevel.WARNING  // "warning"
SeverityLevel.ERROR    // "error"
SeverityLevel.CRITICAL // "critical"
```

## Actions

```java
// Simple action with URL
IronNotify.event("order.shipped")
    .withTitle("Order Shipped")
    .withAction("Track Package", "https://tracking.example.com/123")
    .send();

// Action with handler
IronNotify.event("order.shipped")
    .withTitle("Order Shipped")
    .withAction("View Order", null, "view_order", "default")
    .send();

// Using action builder
IronNotify.event("order.shipped")
    .withTitle("Order Shipped")
    .withAction(EventBuilder.action("Track Package")
        .url("https://tracking.example.com/123")
        .style("primary")
        .build())
    .send();
```

## Deduplication

Prevent duplicate notifications:

```java
IronNotify.event("reminder")
    .withTitle("Daily Reminder")
    .withDeduplicationKey("daily-reminder-2024-01-15")
    .send();
```

## Grouping

Group related notifications:

```java
IronNotify.event("comment.new")
    .withTitle("New Comment")
    .withGroupKey("post-123-comments")
    .send();
```

## Expiration

```java
import java.time.Duration;
import java.time.Instant;

// Expires in 1 hour
IronNotify.event("flash_sale")
    .withTitle("Flash Sale!")
    .expiresIn(Duration.ofHours(1))
    .send();

// Expires at specific time
IronNotify.event("event_reminder")
    .withTitle("Event Tomorrow")
    .expiresAt(Instant.now().plus(Duration.ofDays(1)))
    .send();
```

## Managing Notifications

### Get Notifications

```java
import java.util.List;
import java.io.IOException;

// Get all notifications
List<Notification> notifications = client.getNotifications();

// With options
List<Notification> unread = client.getNotifications(10, 0, true);

// Async
client.getNotificationsAsync(10, 0, false)
    .thenAccept(list -> System.out.println("Got " + list.size() + " notifications"));
```

### Mark as Read

```java
// Mark single notification
client.markAsRead("notification-id");

// Mark all as read
client.markAllAsRead();
```

### Get Unread Count

```java
int count = client.getUnreadCount();
System.out.printf("You have %d unread notifications%n", count);
```

## Real-Time Notifications

```java
NotifyClient client = new NotifyClient(new NotifyOptions("ak_live_xxxxx"));

client.onNotification(notification -> {
    System.out.println("New notification: " + notification.getTitle());
});

client.onUnreadCountChange(count -> {
    System.out.println("Unread count: " + count);
});

client.onConnectionStateChange(state -> {
    System.out.println("Connection state: " + state);
});

client.connect();
client.subscribeToUser("user-123");
client.subscribeToApp();
```

## Offline Support

Notifications are automatically queued when offline:

```java
// This will be queued if offline
IronNotify.notify("event", "Title");

// Manually flush the queue
IronNotify.flush();

// Or async
IronNotify.flushAsync().join();
```

## Requirements

- Java 11+
- OkHttp 4.x
- Gson 2.x

## Thread Safety

The client is thread-safe and can be used from multiple threads concurrently.

## Documentation

For complete documentation, visit [ironnotify.com/docs](https://ironnotify.com/docs).

## Other SDKs

| Platform | Package |
|----------|---------|
| JavaScript/TypeScript | [@ironservices/notify](https://git.marketally.com/ironservices/ironnotify-js) |
| .NET | [IronNotify.Client](https://git.marketally.com/ironservices/ironnotify-dotnet) |
| Python | [ironnotify](https://git.marketally.com/ironservices/ironnotify-python) |
| Go | [ironnotify-go](https://git.marketally.com/ironservices/ironnotify-go) |
| Rust | [ironnotify](https://git.marketally.com/ironservices/ironnotify-rust) |

## Support

- **Documentation**: [ironnotify.com/docs](https://ironnotify.com/docs)
- **Email**: dev@ironservices.io
- **Issues**: [git.marketally.com/ironservices/ironnotify-java/issues](https://git.marketally.com/ironservices/ironnotify-java/issues)

## License

MIT License - see [LICENSE](LICENSE) for details.