TypeScript SDK

Install the published @getratchet/sdk package with npm install @getratchet/sdk. Version 0.1.0 requires Node.js 22 or later. You can also use the HTTP quickstart and API reference.

Create separate project and environment scoped INGEST and WORKER keys in Settings. Keep them on your server.

Record a local tool call

import { createRatchet } from '@getratchet/sdk';

const ratchet = createRatchet({
  baseUrl: 'https://getratchet.waelfz.com',
  apiKey: process.env.GETRATCHET_INGEST_KEY!,
});
await ratchet.startRun('Customer onboarding');
const send = ratchet.wrap(sendWelcomeEmail, {
  name: 'send_welcome_email', endpoint: 'Email service',
  idempotencyKey: (input: { customerId: string }) => `welcome:${input.customerId}`,
});
await send({ customerId: 'cus_2048' });
await ratchet.finishRun();

wrap() runs your function inside your process. It records attempts, but cannot reconstruct the function after a crash.

Enqueue durable work

import { createRatchet } from '@getratchet/sdk';

const ratchet = createRatchet({
  baseUrl: 'https://getratchet.waelfz.com',
  apiKey: process.env.GETRATCHET_INGEST_KEY!,
});
await ratchet.startRun('Customer onboarding');
await ratchet.enqueue({ customerId: 'cus_2048' }, {
  name: 'send_welcome_email', version: '1', endpoint: 'Email service',
  idempotencyKey: 'welcome:cus_2048', timeoutMs: 30_000, maxAttempts: 5,
});
await ratchet.finishRun();

Run a separate worker

import { createRatchet } from '@getratchet/sdk';

const worker = createRatchet({
  baseUrl: 'https://getratchet.waelfz.com',
  apiKey: process.env.GETRATCHET_WORKER_KEY!,
});
worker.registerTool({
  name: 'send_welcome_email', version: '1',
  handler: async (input: { customerId: string }, { idempotencyKey, signal }) =>
    sendWelcomeEmail(input, { idempotencyKey, signal }),
});
await worker.worker.start({ concurrency: 4, signal: shutdownSignal });

Run the worker on infrastructure that remains active. Vercel hosts GetRatchet's API and console, not your handler. A missing exact name/version worker leaves the job queued. See worker operations for lease, retry, replay, and shutdown behavior. Durable execution is at least once, so the destination must deduplicate irreversible effects using the idempotency key.