One API key for the boring infrastructure every app needs: scheduled jobs and a webhook relay today, with PDFs and email coming next. Built so coding agents (Claude Code, Cursor, and others) can wire it up without anyone reading docs.

npm install oakstack

Get an API key at oakstack.dev/dashboard/api-keys and set it as OAKSTACK_API_KEY.

import { Oakstack } from "oakstack";

const oakstack = new Oakstack(); // reads OAKSTACK_API_KEY

Zero dependencies. Works in Node 18+, Bun, Deno, Vercel Edge, and Cloudflare Workers.

Scheduled jobs: `oakstack.clock`

Oakstack calls a URL in your app on a cron schedule, retries failures, and logs every run.

const job = await oakstack.clock.jobs.create({
  name: "Nightly cleanup",
  schedule: "0 3 * * *", // minute hour day month weekday
  timezone: "America/Chicago", // default UTC
  url: "https://yourapp.com/api/cron/cleanup",
  body: JSON.stringify({ task: "cleanup" }),
});
// Save job.signingSecret as OAKSTACK_SIGNING_SECRET to verify calls (below).

await oakstack.clock.jobs.run(job.id); // test it now instead of waiting
const runs = await oakstack.clock.jobs.runs(job.id); // status, response, error per run

await oakstack.clock.jobs.pause(job.id);
await oakstack.clock.jobs.resume(job.id);
await oakstack.clock.jobs.update(job.id, { schedule: "*/15 * * * *" });
await oakstack.clock.jobs.delete(job.id);

Each failed call is retried 3 times (after about 30 seconds, 2 minutes, and 10 minutes). A job that fails 10 runs in a row pauses itself with a pausedReason.

Webhook relay: `oakstack.hook`

A permanent inbound URL for Stripe, GitHub, or any other sender. Every event is stored, then forwarded to your app with its original headers and body. Delivery is retried for about 11 hours, and any event can be replayed.

const endpoint = await oakstack.hook.endpoints.create({
  name: "Stripe",
  forwardUrl: "https://yourapp.com/api/webhooks/stripe",
});
console.log(endpoint.url); // https://oakstack.dev/h/... : give this to Stripe

const failed = await oakstack.hook.endpoints.events(endpoint.id, { status: "failed" });
const detail = await oakstack.hook.events.get(failed[0].id); // headers, body, every attempt
await oakstack.hook.events.replay(failed[0].id);

await oakstack.hook.endpoints.update(endpoint.id, { status: "paused" }); // holds events, loses none

Your app keeps verifying the sender's own signature (for example Stripe-Signature) exactly as before, because the original headers and the exact body bytes are forwarded unchanged.

Verifying requests from Oakstack

Every cron call and forwarded webhook carries an Oakstack-Signature header. Check it with the job's or endpoint's signingSecret:

import { verifySignature } from "oakstack";

export async function POST(req: Request) {
  const body = await req.text(); // the raw body, before parsing
  const ok = await verifySignature(
    process.env.OAKSTACK_SIGNING_SECRET!,
    req.headers.get("oakstack-signature"),
    body,
  );
  if (!ok) return new Response("bad signature", { status: 401 });
  // ...
  return Response.json({ ok: true });
}

The scheme is the same one Stripe uses: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>." + body>. Signatures older than 5 minutes are rejected.

Usage and limits

const { plan, usage } = await oakstack.usage();
// usage: [{ metric: "clock.jobs", label: "scheduled jobs", used: 2, limit: 3, kind: "count" }, ...]

Plans have hard limits that stop instead of overbilling. Hitting one throws OakstackError with errorName: "usage_limit_reached" and a message that says what to do next.

Errors and retries

Every API error throws OakstackError, with statusCode, errorName (machine-readable), and a message that says what to fix.
Network errors, 5xx responses, and rate limits are retried automatically, twice by default (maxRetries).
Every write carries an Idempotency-Key, so a retry can never create a duplicate. Pass your own to make a call safe across process restarts: oakstack.clock.jobs.create(params, { idempotencyKey: "setup-nightly-v1" }).

Options

new Oakstack({
  apiKey: "ok_live_...", // default: OAKSTACK_API_KEY
  baseUrl: "https://oakstack.dev", // default: OAKSTACK_BASE_URL, then this
  maxRetries: 2,
  timeoutMs: 30_000,
});