> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sailhouse.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Go

## Installing

The SDK is available on [Github](https://github.com/sailhouse/sdk-go), so available via the standard `go get`

```bash theme={null}
go get -u github.com/sailhouse/sdk-go
```

## Basic Usage

### Importing

The `sailhouse` package has all the goodness in it.

```go theme={null}
import (
    "github.com/sailhouse/sdk-go/sailhouse"
)
```

### Initialising the Client

The package has a `SailhouseClient` struct which holds all the methods for interacting with the Sailhouse platform.

Provided you have generated a [token](/reference/tokens), you can create a client easily with `sailhouse.NewSailhouseClient(...)`

```go theme={null}
package main

import (
    "os"

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

func main() {
    client := sailhouse.NewSailhouseClient(os.Getenv("SAILHOUSE_TOKEN"))

    // do awesome things 🚀
}
```

### Sending an event

The client has a `Publish(...)` method on it for easily sending data to a given topic

```go theme={null}
data := map[string]interface{}{
    "text": "example contents",
    "object": map[string]interface{}{
        "key": "value",
    },
}

ctx := context.Background()

err := client.Publish(ctx, "some-topic", data)
if err != nil {
    panic(err)
}
```

The `data` arg must be able to be marshalled into JSON via `json.Marshal`. If this fails, it will return an error, and the event will not be sent.

### Receiving events from a pull subscription

The client also has a `GetEvents(...)` method for requesting the events sent to a given subscription for a topic.

```go theme={null}
type Message struct {
	Text string `json:"text"`
}

func main() {
    ctx := context.Background()
    res, err := client.GetEvents(
        ctx,
        "awesome-example",
        "awesome-pull",
        sailhouse.WithLimit(20)
    )
    if err != nil {
        panic(err)
    }

    for _, event := range res.Events {
        var message Message

        // Cast the event data into the `Message` struct
        err := event.As(&message)
        if err != nil {
            panic(err)
        }

        fmt.Println(message.Text)

        // Acknowledge the message so that the event is not
        // returned again
        event.Ack()
    }
}
```

## Admin Operations

The admin client provides methods for managing subscriptions programmatically.

### Registering Push Subscriptions

```go theme={null}
import (
    "context"
    "github.com/sailhouse/sdk-go/sailhouse"
)

// Basic push subscription
err := client.Admin.RegisterPushSubscription(ctx, &sailhouse.PushSubscriptionRequest{
    Topic:        "user-events",
    Subscription: "welcome-email",
    Endpoint:     "https://api.example.com/webhooks/welcome",
})
if err != nil {
    panic(err)
}

// With simple filter
err = client.Admin.RegisterPushSubscription(ctx, &sailhouse.PushSubscriptionRequest{
    Topic:        "user-events", 
    Subscription: "premium-users",
    Endpoint:     "https://api.example.com/webhooks/premium",
    Filter: &sailhouse.Filter{
        Path:  "user.type",
        Value: "premium",
    },
})
if err != nil {
    panic(err)
}

// With advanced filter
err = client.Admin.RegisterPushSubscription(ctx, &sailhouse.PushSubscriptionRequest{
    Topic:        "user-events",
    Subscription: "active-premium-users", 
    Endpoint:     "https://api.example.com/webhooks/active-premium",
    Filter: &sailhouse.ComplexFilter{
        Filters: []sailhouse.FilterCondition{
            {
                Path:      "user.type",
                Condition: "equals",
                Value:     "premium",
            },
            {
                Path:      "user.status",
                Condition: "not_equals", 
                Value:     "inactive",
            },
        },
        Operator: "and",
    },
    RateLimit:     "100/h",
    Deduplication: "5m",
})
if err != nil {
    panic(err)
}
```

### Rate Limiting and Deduplication

* **Rate Limit**: Controls delivery frequency using formats like "100/h" (100 per hour), "10/m" (10 per minute)
* **Deduplication**: Prevents duplicate deliveries within a time window using formats like "5m" (5 minutes), "1h" (1 hour)

```
```