Skip to main content

API reference

Quickstart: JavaScript / TypeScript

Use @jobbydev/sdk to drive the API from Node, the browser, Cloudflare Workers, Bun, or Deno.

Last updated

The @jobbydev/sdk package is a hand-written, zero- dependency client over the v1 surface. Works in Node 20+, browsers, Cloudflare Workers, Bun, and Deno. TypeScript-first.

Install

npm install @jobbydev/sdk
# or pnpm add @jobbydev/sdk
# or yarn add @jobbydev/sdk
# or bun add @jobbydev/sdk

Note: the SDK ships scaffold-only today (lives in this repo's sdks/js/directory). It's not yet on npm; publish gate is the post-Tier 8 audit.

Initialize

import { JobbydevClient } from "@jobbydev/sdk";

const jobby = new JobbydevClient({
  apiToken: process.env.JOBBYDEV_API_TOKEN!,
});

Discovery

const { data: events, rateLimit } = await jobby.listLiveEvents();
console.log(`${events.length} events live; ${rateLimit.remaining} reqs left`);

Join a queue

await jobby.queue.join("evt_abc123");
const { data: status } = await jobby.queue.status();
console.log(`Position #${status.rank}, ~${status.estimated_wait_seconds}s wait`);

Errors

import { JobbydevError } from "@jobbydev/sdk";

try {
  await jobby.matches.accept(matchId);
} catch (error) {
  if (error instanceof JobbydevError) {
    if (error.code === "OFF_SESSION_CONSENT_REQUIRED") {
      // surface a fresh-checkout URL the user can open
      const checkoutUrl = (error.details as any)?.checkout_url;
    }
    if (error.status === 429) {
      console.log(`Retry after ${error.retryAfterSeconds}s`);
    }
  }
  throw error;
}

Webhooks

await jobby.webhooks.create({
  target_url: "https://my-app.example.com/jobbydev",
  events: ["match.matched", "match.accepted", "match.declined"],
  description: "Slack bot for new matches",
});

Verify incoming signatures using the same HMAC scheme on the receiver side — see verifying webhook signatures.

Auto-retry on 429

const jobby = new JobbydevClient({
  apiToken: process.env.JOBBYDEV_API_TOKEN!,
  retryOn429: true, // single retry after Retry-After
});

For more sophisticated back-off, leave retryOn429 unset and inspect error.retryAfterSeconds + error.rateLimit in your own retry logic.

Browser usage

The SDK works in the browser, but think carefully about token exposure: a Personal Access Token in the browser is exposed to anyone who opens DevTools. Use server-side proxies for production browser apps; reserve direct-browser SDK usage for internal admin tools or per-user-token apps where the user knowingly pasted their own token.

Related reading