SDK reference · Assistants and evaluation
client.subscriptions
client.subscriptions.{ create, poll, ack, stream, deliver }deliver handles the whole loop: each event goes to your handler once it is written, and is acknowledged after the handler returns. To do it yourself, poll or stream new events, then acknowledge through the last one you handled.
create
create(name: string, key: string): Promise<Resource>Creates a subscription.
Parameters
keystring- An idempotency key. Retrying with the same key and input returns the first result instead of acting twice.
Returns Promise<Resource>
poll
poll(id: string): Promise<Page<DeliveryEvent>>Events not yet acknowledged.
Returns Promise<Page<DeliveryEvent>>
ack
ack(id: string, through: number, key: string): Promise<Resource>Acknowledges events through a sequence number.
Parameters
keystring- An idempotency key. Retrying with the same key and input returns the first result instead of acting twice.
Returns Promise<Resource>
stream
stream(id: string, options?: StreamOptions): AsyncGenerator<DeliveryEvent[]>Events as they are written, in batches, pushed over Server-Sent Events. It reconnects and resumes on its own. Acknowledge as when polling; what isn't acknowledged comes back on the next poll.
Parameters
idstring- The subscription's ID.
options.afternumberoptional- The last sequence already seen (default 0).
options.signalAbortSignaloptional- Stops the stream.
Returns AsyncGenerator<DeliveryEvent[]>
deliver
deliver(id: string, handle: (event: DeliveryEvent) => void | Promise<void>, options: DeliveryOptions): Promise<void>Hands each event to handle in order, at least once, as soon as it is written, and acknowledges it after handle returns. If handle throws, that event is retried later. While the push stream is down, it polls every pollMs. Returns when signal aborts.
Parameters
idstring- The subscription's ID.
handle(event: DeliveryEvent) => void | Promise<void>- Delivers one event. Make it safe to repeat: an event can arrive again after a crash.
options.cursor{ load(): number | Promise<number>; save(sequence: number): void | Promise<void> }- Where the last handled sequence is kept, so a restart resumes instead of replaying.
options.signalAbortSignal- Stops delivery.
options.pollMsnumberoptional- Polling interval while the stream is down (default 1 s).
options.onError(error: unknown) => voidoptional- A failed read, handler or acknowledgement; delivery retries.
Returns Promise<void>
await client.subscriptions.deliver(subscription.id, send, {
cursor: { load: () => saved.cursor, save: (n) => store.saveCursor(n) },
signal: shutdown.signal,
});