@tickbird/sdk

Official TypeScript SDK for Tickbird — a typed REST client and webhook helpers. Runs on Node 18+, Cloudflare Workers, Deno, Bun, and browsers.

npm install @tickbird/sdk

REST client

import { createClient } from "@tickbird/sdk";

const tb = createClient({ token: process.env.TICKBIRD_TOKEN! }); // a tpat_… PAT

const { data, error } = await tb.timer.state({ path: { orgId } });
// e.g. tb.projects.list(...), tb.accounts.create(...), tb.timeEntries.log(...)
if (error) {
  // typed { status, body } — errors are returned, not thrown
} else {
  // typed response
}

createClient accepts an optional baseUrl (defaults to the production host) and configures the shared underlying client; the most recent call wins per process. The raw @hey-api/client-fetch client is exposed as tb.client for interceptors and custom requests.

Webhooks

Import from the dedicated, client-free entry point — @tickbird/sdk/webhooks pulls in no HTTP code:

import { constructEvent } from "@tickbird/sdk/webhooks";

// Pass the RAW request body — re-serialized JSON breaks the signature.
const event = await constructEvent({
  body: rawBody,
  headers: request.headers, // a Headers instance or a plain record
  secret: process.env.TICKBIRD_WEBHOOK_SECRET!, // whsec_…
});

switch (event.type) {
  case "timer.committed":
    event.data.totalSeconds; // number — narrowed by event.type
    break;
  case "project.archived":
    event.data.archived; // boolean
    break;
}

constructEvent verifies the Tickbird-Signature (HMAC-SHA256, v1=<hex>) and rejects replays outside a 300s tolerance (configurable via toleranceSeconds), throwing WebhookSignatureVerificationError on any failure. For lower-level use, verifyWebhookSignature(...) returns a boolean.

Keeping the client in sync

The client is generated from the live OpenAPI description. Regenerate after API changes:

# against a running local API
pnpm --filter @tickbird/sdk codegen
# or a deployed host
TICKBIRD_OPENAPI_URL=https://tickbird.app/api/v1/openapi.json pnpm --filter @tickbird/sdk codegen