ironnotify-go/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 Go</h1>

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

<p align="center">
  <a href="https://pkg.go.dev/git.marketally.com/ironservices/ironnotify-go"><img src="https://pkg.go.dev/badge/git.marketally.com/ironservices/ironnotify-go.svg" alt="Go Reference"></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/go">Go 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

```bash
go get git.marketally.com/ironservices/ironnotify-go
```

## Quick Start

### Send a Simple Notification

```go
package main

import (
    "fmt"
    ironnotify "git.marketally.com/ironservices/ironnotify-go"
)

func main() {
    // Initialize
    err := ironnotify.Init("ak_live_xxxxx")
    if err != nil {
        panic(err)
    }
    defer ironnotify.Close()

    // Send a simple notification
    result := ironnotify.Notify(
        "order.created",
        "New Order Received",
        ironnotify.WithMessage("Order #1234 has been placed"),
        ironnotify.WithSeverity(ironnotify.SeveritySuccess),
        ironnotify.WithMetadataOpt(map[string]any{
            "order_id": "1234",
            "amount":   99.99,
        }),
    )

    if result.Success {
        fmt.Println("Notification sent:", result.NotificationID)
    }
}
```

### Fluent Event Builder

```go
package main

import (
    "time"
    ironnotify "git.marketally.com/ironservices/ironnotify-go"
)

func main() {
    ironnotify.Init("ak_live_xxxxx")
    defer ironnotify.Close()

    // Build complex notifications with the fluent API
    result := ironnotify.Event("payment.failed").
        WithTitle("Payment Failed").
        WithMessage("Payment could not be processed").
        WithSeverity(ironnotify.SeverityError).
        WithMetadata("order_id", "1234").
        WithMetadata("reason", "Card declined").
        WithAction("Retry Payment", ironnotify.ActionURL("/orders/1234/retry"), ironnotify.ActionStyle("primary")).
        WithAction("Contact Support", ironnotify.ActionHandler("open_support")).
        ForUser("user-123").
        WithDeduplicationKey("payment-failed-1234").
        ExpiresIn(24 * time.Hour).
        Send()

    if result.Queued {
        // Notification was queued for later (offline mode)
    }
}
```

### Using the Client Directly

```go
package main

import (
    ironnotify "git.marketally.com/ironservices/ironnotify-go"
)

func main() {
    client, err := ironnotify.NewClient(ironnotify.Options{
        APIKey: "ak_live_xxxxx",
        Debug:  true,
    })
    if err != nil {
        panic(err)
    }
    defer client.Close()

    // Send notification
    result := client.Notify("event.type", "Title")

    // Use event builder
    result = client.Event("event.type").
        WithTitle("Title").
        Send()

    // Get notifications
    notifications, err := client.GetNotifications(10, 0, false)
}
```

## Configuration

```go
import ironnotify "git.marketally.com/ironservices/ironnotify-go"

client, _ := ironnotify.NewClient(ironnotify.Options{
    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:       time.Second,
    HTTPTimeout:          30 * time.Second,
})
```

### 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` | bool | false | Enable debug logging |
| `EnableOfflineQueue` | bool | true | Queue notifications when offline |
| `MaxOfflineQueueSize` | int | 100 | Max offline queue size |
| `AutoReconnect` | bool | true | Auto-reconnect WebSocket |
| `MaxReconnectAttempts` | int | 5 | Max reconnection attempts |
| `ReconnectDelay` | Duration | 1s | Base reconnection delay |
| `HTTPTimeout` | Duration | 30s | HTTP request timeout |

## Severity Levels

```go
ironnotify.SeverityInfo     // "info"
ironnotify.SeveritySuccess  // "success"
ironnotify.SeverityWarning  // "warning"
ironnotify.SeverityError    // "error"
ironnotify.SeverityCritical // "critical"
```

## Actions

```go
ironnotify.Event("order.shipped").
    WithTitle("Order Shipped").
    WithAction("Track Package",
        ironnotify.ActionURL("https://tracking.example.com/123"),
        ironnotify.ActionStyle("primary")).
    WithAction("View Order",
        ironnotify.ActionHandler("view_order")).
    Send()
```

## Deduplication

Prevent duplicate notifications:

```go
ironnotify.Event("reminder").
    WithTitle("Daily Reminder").
    WithDeduplicationKey("daily-reminder-2024-01-15").
    Send()
```

## Grouping

Group related notifications:

```go
ironnotify.Event("comment.new").
    WithTitle("New Comment").
    WithGroupKey("post-123-comments").
    Send()
```

## Expiration

```go
// Expires in 1 hour
ironnotify.Event("flash_sale").
    WithTitle("Flash Sale!").
    ExpiresIn(time.Hour).
    Send()

// Expires at specific time
ironnotify.Event("event_reminder").
    WithTitle("Event Tomorrow").
    ExpiresAt(time.Now().Add(24 * time.Hour)).
    Send()
```

## Managing Notifications

### Get Notifications

```go
// Get all notifications
notifications, err := client.GetNotifications(0, 0, false)

// With pagination and filters
unread, err := client.GetNotifications(10, 0, true) // limit=10, unread only

// With context
notifications, err := client.GetNotificationsContext(ctx, 10, 0, false)
```

### Mark as Read

```go
// Mark single notification
err := client.MarkAsRead("notification-id")

// Mark all as read
err := client.MarkAllAsRead()
```

### Get Unread Count

```go
count, err := client.GetUnreadCount()
fmt.Printf("You have %d unread notifications\n", count)
```

## Real-Time Notifications

```go
client.OnNotification(func(n ironnotify.Notification) {
    fmt.Printf("New notification: %s\n", n.Title)
})

client.OnUnreadCountChange(func(count int) {
    fmt.Printf("Unread count: %d\n", count)
})

client.OnConnectionStateChange(func(state ironnotify.ConnectionState) {
    fmt.Printf("Connection state: %s\n", state)
})

client.Connect()
client.SubscribeToUser("user-123")
client.SubscribeToApp()
```

## Offline Support

Notifications are automatically queued when offline:

```go
// This will be queued if offline
ironnotify.Notify("event", "Title")

// Manually flush the queue
ironnotify.Flush()

// Or with context
client.FlushContext(ctx)
```

## Thread Safety

The client is thread-safe and can be used from multiple goroutines 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) |
| Java | [ironnotify-java](https://git.marketally.com/ironservices/ironnotify-java) |
| 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-go/issues](https://git.marketally.com/ironservices/ironnotify-go/issues)

## License

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