# Go SDK

The official server-side Go SDK. The API mirrors the official Mixpanel Go SDK (`mixpanel-go`), so migrating is mostly a matter of swapping the import. Go 1.22+, zero dependencies, context-based.

## Install

```bash
go get github.com/cohorly-io/cohorly-go
```

## Initialize

```go
package main

import (
	"context"

	cohorly "github.com/cohorly-io/cohorly-go"
)

func main() {
	client := cohorly.NewClient("YOUR_PROJECT_TOKEN",
		cohorly.WithAPIHost("https://cohorly-service.velloalabs.com"))

	ctx := context.Background()
	err := client.Track(ctx, []*cohorly.Event{
		client.NewEvent("signup", "user-1", map[string]any{
			"plan": "premium",
		}),
	})
	if err != nil {
		// handle error
	}
}
```

## API

| Member                                                                     | Notes                                                                                                            |
| -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `NewClient(token, opts...)`                                                | Options: `WithAPIHost`, `WithHTTPClient`.                                                                        |
| `client.NewEvent(name, distinctID, props)`                                 | Stamps `time` (unix ms), `$insert_id`, `$lib`, `$lib_version`. `AddTime` / `AddInsertID` override for backfills. |
| `Track(ctx, events)`                                                       | Chunks transparently at the server's 500-event batch cap. Batches are atomic server-side, safe to retry as-is.   |
| `PeopleSet / PeopleSetOnce / PeopleIncrement / PeopleUnset / PeopleDelete` | Profile updates mapped to /engage ops.                                                                           |
| `Alias(ctx, alias, distinctID)`                                            | POST /alias.                                                                                                     |
| `NewBufferedClient(client, opts...)`                                       | Non-blocking `Enqueue` + background flush loop with the shared retry contract. `Close(ctx)` on shutdown.         |

## Buffered mode

```go
buffered := cohorly.NewBufferedClient(client,
	cohorly.WithFlushInterval(10*time.Second),
	cohorly.WithFlushBatchSize(50),
)

buffered.Enqueue(buffered.NewEvent("page_view", "user-1", nil))

// On shutdown: stop the loop and flush whatever is left.
if err := buffered.Close(ctx); err != nil {
	// remaining events could not be delivered
}
```

The buffered client implements the shared Cohorly retry contract:
exponential backoff on 429/5xx/network honoring
`Retry-After`, batch halving on 413, permanent drop on 400,
queue capped at 1000 (oldest dropped). It embeds
`*Client`, so the synchronous methods stay available.

## Error handling

```go
err := client.Track(ctx, events)
if errors.Is(err, cohorly.ErrInvalidToken) {
	// bad project token (HTTP 401)
}
var httpErr *cohorly.HTTPError
if errors.As(err, &httpErr) && httpErr.Status == 429 {
	time.Sleep(httpErr.RetryAfter)
	// safe to retry the same payload
}
```