ironnotify-go/README.md

IronNotify SDK for Go

Event notifications and alerts SDK for Go applications. Send notifications, receive real-time updates, and manage notification state.

Installation

go get github.com/IronServices/ironnotify-go

Quick Start

Send a Simple Notification

package main

import (
    "fmt"
    ironnotify "github.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

package main

import (
    "time"
    ironnotify "github.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

package main

import (
    ironnotify "github.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

import ironnotify "github.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

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

Actions

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:

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

Grouping

Group related notifications:

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

Expiration

// 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

// 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

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

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

Get Unread Count

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

Real-Time Notifications

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:

// 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.

License

MIT License - see LICENSE for details.