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)