​
Installing

The TypeScript SDK can be installed via your favourite package manager, e.g. pnpm

pnpm add @sailhouse/client

​
Basic Usage

​
Importing and initialising

The SailhouseClient class from the package has everything we need to get started.

Provided you have generated a token, you can create a client from the class.

import { SailhouseClient } from '@sailhouse/client';

const client = new SailhouseClient(process.env.SAILHOUSE_TOKEN);

// lets go 🎉

​
Sending an event

The client has an async publish method for sending data to a given topic.

await client.publish("some-topic", {
    text: "example contents",
    obj: {
        key: "value",
    },
});

The second argument can be any object. Ideally, this should just be a map, as the contents are stringified via JSON.stringify(...) and we don’t want that to get messy.

​
Recieving events from a pull subscription

The client has a getEvents method for pull subscriptions.

const { events } = await client.getEvents<Message>(
    "awesome-example",
    "awesome-pull"
);

await Promise.all(events.map(async (event) => {
// Do something with the event 🤔

await event.ack();
}));

​
Admin Operations

The admin client provides methods for managing subscriptions programmatically.

​
Registering Push Subscriptions

// Basic push subscription
await client.admin.registerPushSubscription(
  "user-events",
  "welcome-email", 
  "https://api.example.com/webhooks/welcome"
);

// With simple filter
await client.admin.registerPushSubscription(
  "user-events",
  "premium-users",
  "https://api.example.com/webhooks/premium",
  {
    filter: {
      path: "user.type",
      value: "premium"
    }
  }
);

// With advanced filter
await client.admin.registerPushSubscription(
  "user-events", 
  "active-premium-users",
  "https://api.example.com/webhooks/active-premium",
  {
    filter: {
      filters: [
        {
          path: "user.type",
          condition: "equals", 
          value: "premium"
        },
        {
          path: "user.status",
          condition: "not_equals",
          value: "inactive" 
        }
      ],
      operator: "and"
    },
    rate_limit: "100/h",
    deduplication: "5m"
  }
);

​
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)