> ## 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.

# TypeScript / JavaScript

## Installing

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

```sh theme={null}
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](/reference/tokens), you can create a client from the class.

```typescript theme={null}
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.

```ts theme={null}
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.

```ts theme={null}
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

```typescript theme={null}
// 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)