SegOps AIDocs

Go SDK

Thread-safe event client with built-in batching, retries, and graceful shutdown. Zero external dependencies. Requires Go 1.22+.

Installation#

bash
go get github.com/segops/sdk-go

Quick Start#

go
package main

import (
    "context"
    "log"

    "github.com/segops/sdk-go"
)

func main() {
    client := segops.New(segops.Options{
        APIURL: "https://api.segops.ai",
        APIKey: "sk_...",
    })
    defer func() {
        if err := client.Shutdown(context.Background()); err != nil {
            log.Println("shutdown:", err)
        }
    }()

    client.Track(segops.Event{
        UserID:    "user-123",
        EventType: "order_placed",
        Payload: map[string]any{
            "order_id": "ord-456",
            "total":    89.95,
        },
    })

    client.Identify(segops.Context{
        UserID: "user-123",
        Traits: map[string]any{
            "email":   "[email protected]",
            "plan":    "starter",
            "company": "Acme Corp",
        },
    })
}

Options#

go
type Options struct {
    APIURL     string        // Base URL, e.g. "https://api.segops.ai"
    APIKey     string        // API key (sk_…)
    BatchSize  int           // Default: 20
    FlushEvery time.Duration // Default: 5s
    MaxRetries int           // Default: 3
    Logger     *log.Logger   // Default: log.Default()
}
FieldDefaultDescription
APIURL—Base URL of your SegOps deployment
APIKey—API key with ingest permission
BatchSize20Max events before an automatic flush
FlushEvery5sPeriodic flush interval
MaxRetries3Retry attempts on 5xx (exponential back-off: 0ms, 500ms, 1s)
Loggerlog.Default()Logger for flush errors

Methods#

Track(e Event)

Enqueue an event. Non-blocking, safe for concurrent use.

go
client.Track(segops.Event{
    UserID:    "user-123",
    EventType: "page_viewed",
    // OccurredAt defaults to time.Now() when omitted
    Payload: map[string]any{"path": "/home"},
})

Identify(ctx Context)

Record user traits as a context_identified event.

go
client.Identify(segops.Context{
    UserID: "user-123",
    Traits: map[string]any{
        "email":   "[email protected]",
        "plan":    "starter",
        "company": "Acme Corp",
    },
})

Flush(ctx context.Context) error

Flush all buffered events immediately. Blocks until the HTTP request completes.

go
if err := client.Flush(ctx); err != nil {
    log.Println("flush failed:", err)
}

Shutdown(ctx context.Context) error

Stop the background goroutine and flush any remaining events. Always call before the process exits.

go
defer client.Shutdown(context.Background())

Types#

go
// Event is a single user event.
type Event struct {
    UserID     string         // Required
    EventType  string         // Required; snake_case
    OccurredAt string         // Optional; RFC 3339. Defaults to now.
    Payload    map[string]any // Optional
}

// Context carries user identity / trait updates.
type Context struct {
    UserID string
    Traits map[string]any
}

Error Handling#

The background goroutine logs flush errors via the configured Logger. Individual Flush and Shutdown calls return error directly. Transient 5xx responses are retried with exponential back-off: 0 ms, 500 ms, 1 s.