Skip to main content

​
Installing

The SDK is available on Github, so available via the standard go get 
go get -u github.com/sailhouse/sdk-go

​
Basic Usage

​
Importing

The sailhouse package has all the goodness in it. 
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, you can create a client easily with sailhouse.NewSailhouseClient(...) 
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 
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. 
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

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)
⌘I