@formfeed/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Philipp Staudt IT-Dienstleistungen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,63 @@
+# @formfeed/sdk
+
+The TypeScript client for the [Formfeed](https://formfeed.dev) API: generate PDFs and images from
+templates. It has no dependencies and uses only Web APIs (`fetch`, Web Crypto), so it runs in Node 22+,
+Deno, Bun, Cloudflare Workers and browsers.
+
+- Retries `429` and `503` with the server's `Retry-After`.
+- Sends an `Idempotency-Key` with every render, so a retried request never renders twice.
+- Turns API problems into `FormfeedError` with `code`, `status` and `request_id`.
+- Verifies webhook signatures.
+
+```bash
+npm install @formfeed/sdk
+```
+
+## Render a template
+
+```ts
+import { Formfeed } from '@formfeed/sdk';
+
+const client = new Formfeed({ apiKey: process.env.FORMFEED_API_KEY!, region: 'eu' });
+
+const render = await client.renders.create({
+  template: 'invoice-de',
+  data: { invoice: { number: '2026-0042', lines: [{ description: 'Consulting', qty: 8, price: 120 }] } },
+});
+console.log(render.download_url, render.page_count);
+
+const pdf = await client.renders.download(render); // the bytes
+```
+
+## Async renders and batches
+
+```ts
+const queued = await client.renders.create({ template: 'invoice-de', data, mode: 'async' });
+const done = await client.renders.waitFor(queued.id);
+
+const job = await client.renders.batch({
+  template: 'invoice-de',
+  items: orders.map((order) => ({ data: { invoice: order } })),
+  zip: true,
+});
+const finished = await client.jobs.waitFor(job.id);
+```
+
+## Webhooks
+
+```ts
+import { parseWebhookEvent } from '@formfeed/sdk';
+
+// pass the raw request body, not re-serialised JSON; throws when the signature does not match
+const event = await parseWebhookEvent(secret, request.headers.get('webhook-signature'), rawBody);
+if (event.type === 'render.completed') console.log(event.data); // the render object
+```
+
+## Documentation
+
+- [TypeScript SDK guide](https://docs.formfeed.dev/api/sdks/typescript)
+- [API reference](https://docs.formfeed.dev/api/overview)
+
+## Licence
+
+MIT

package/index.cjs

@@ -0,0 +1,267 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// packages/sdk-ts/src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Formfeed: () => Formfeed,
+  FormfeedError: () => FormfeedError,
+  parseWebhookEvent: () => parseWebhookEvent,
+  verifyWebhookSignature: () => verifyWebhookSignature
+});
+module.exports = __toCommonJS(index_exports);
+
+// packages/sdk-ts/src/lib/client.ts
+var FormfeedError = class extends Error {
+  constructor(code, message, status, problem = null, requestId = null) {
+    super(message);
+    this.code = code;
+    this.status = status;
+    this.problem = problem;
+    this.requestId = requestId;
+  }
+  name = "FormfeedError";
+};
+var hosts = {
+  eu: "https://api-eu.formfeed.dev/v1",
+  us: "https://api-us.formfeed.dev/v1"
+};
+var sleep = (ms, signal) => new Promise((resolve, reject) => {
+  const t = setTimeout(resolve, ms);
+  signal?.addEventListener("abort", () => {
+    clearTimeout(t);
+    reject(signal.reason ?? new Error("aborted"));
+  });
+});
+function randomKey() {
+  const c = globalThis.crypto;
+  if (c?.randomUUID) return c.randomUUID();
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+}
+var Formfeed = class {
+  baseUrl;
+  apiKey;
+  fetchImpl;
+  maxRetries;
+  timeoutMs;
+  constructor(options) {
+    if (!options.apiKey) throw new FormfeedError("invalid_request", "apiKey is required", 0);
+    this.apiKey = options.apiKey;
+    this.baseUrl = (options.baseUrl ?? hosts[options.region ?? "eu"]).replace(/\/$/, "");
+    this.fetchImpl = options.fetch ?? globalThis.fetch;
+    this.maxRetries = options.maxRetries ?? 3;
+    this.timeoutMs = options.timeoutMs ?? 12e4;
+    if (!this.fetchImpl) throw new FormfeedError("invalid_request", "fetch is not available; pass options.fetch", 0);
+  }
+  renders = {
+    /** Renders a template, HTML or URL. Sync by default; `mode: 'async'` returns a queued render. */
+    create: (request, options = {}) => this.request("POST", "/renders", request, {
+      ...options,
+      idempotencyKey: options.idempotencyKey ?? randomKey()
+    }),
+    get: (id, options = {}) => this.request("GET", `/renders/${encodeURIComponent(id)}`, void 0, options),
+    /** Polls until the render succeeded or failed (async renders). */
+    waitFor: async (id, options = {}) => {
+      const deadline = Date.now() + (options.timeoutMs ?? 12e4);
+      const interval = options.intervalMs ?? 1e3;
+      for (; ; ) {
+        const render = await this.renders.get(id, { signal: options.signal });
+        if (render.status === "succeeded" || render.status === "failed") return render;
+        if (Date.now() + interval > deadline)
+          throw new FormfeedError("timeout", `render ${id} did not finish within the wait time`, 0);
+        await sleep(interval, options.signal);
+      }
+    },
+    /** Downloads the output of a finished render as bytes. */
+    download: async (render, options = {}) => {
+      const target = typeof render === "string" ? await this.renders.get(render, options) : render;
+      if (!target.download_url)
+        throw new FormfeedError("not_ready", `render ${target.id} has no output (${target.status})`, 0);
+      const res = await this.fetchImpl(target.download_url, { signal: options.signal });
+      if (!res.ok) throw new FormfeedError("download_failed", `download answered HTTP ${res.status}`, res.status);
+      return new Uint8Array(await res.arrayBuffer());
+    },
+    /** Page of renders, newest first. */
+    list: (query = {}, options = {}) => {
+      const params = new URLSearchParams();
+      for (const [k, v] of Object.entries(query)) if (v !== void 0 && v !== null && v !== "") params.set(k, String(v));
+      const qs = params.toString();
+      return this.request("GET", `/renders${qs ? `?${qs}` : ""}`, void 0, options);
+    },
+    /** Every render matching the query, following the cursor. */
+    all: async (query = {}, options = {}) => {
+      const out = [];
+      let cursor = null;
+      do {
+        const page = await this.renders.list({ ...query, cursor }, options);
+        out.push(...page.data);
+        cursor = page.next_cursor;
+      } while (cursor);
+      return out;
+    },
+    /** Removes the stored files of a render before they expire. Needs the `file:delete` scope. */
+    deleteOutputs: (id, options = {}) => this.request("DELETE", `/renders/${encodeURIComponent(id)}/outputs`, void 0, options),
+    batch: (request, options = {}) => this.request("POST", "/renders/batch", request, {
+      ...options,
+      idempotencyKey: options.idempotencyKey ?? randomKey()
+    })
+  };
+  jobs = {
+    get: (id, options = {}) => this.request("GET", `/jobs/${encodeURIComponent(id)}`, void 0, options),
+    waitFor: async (id, options = {}) => {
+      const deadline = Date.now() + (options.timeoutMs ?? 6e5);
+      const interval = options.intervalMs ?? 2e3;
+      for (; ; ) {
+        const job = await this.jobs.get(id, { signal: options.signal });
+        if (job.status !== "queued" && job.status !== "processing") return job;
+        if (Date.now() + interval > deadline)
+          throw new FormfeedError("timeout", `job ${id} did not finish within the wait time`, 0);
+        await sleep(interval, options.signal);
+      }
+    }
+  };
+  webhooks = {
+    list: async (options = {}) => (await this.request("GET", "/webhooks", void 0, options)).data,
+    create: (input, options = {}) => this.request("POST", "/webhooks", input, options),
+    update: (id, patch, options = {}) => this.request("PUT", `/webhooks/${encodeURIComponent(id)}`, patch, options),
+    delete: (id, options = {}) => this.request("DELETE", `/webhooks/${encodeURIComponent(id)}`, void 0, options),
+    test: (id, options = {}) => this.request("POST", `/webhooks/${encodeURIComponent(id)}/test`, void 0, options)
+  };
+  templates = {
+    list: (query = {}, options = {}) => {
+      const params = new URLSearchParams();
+      for (const [k, v] of Object.entries(query)) if (v !== void 0 && v !== null && v !== "") params.set(k, String(v));
+      const qs = params.toString();
+      return this.request("GET", `/templates${qs ? `?${qs}` : ""}`, void 0, options);
+    },
+    /** Every template of the workspace, following the cursor. */
+    all: async (query = {}, options = {}) => {
+      const out = [];
+      let cursor = null;
+      do {
+        const page = await this.templates.list({ ...query, cursor }, options);
+        out.push(...page.data);
+        cursor = page.next_cursor;
+      } while (cursor);
+      return out;
+    },
+    get: (idOrSlug, options = {}) => this.request("GET", `/templates/${encodeURIComponent(idOrSlug)}`, void 0, options),
+    create: (input, options = {}) => this.request("POST", "/templates", input, options),
+    update: (idOrSlug, patch, options = {}) => this.request("PUT", `/templates/${encodeURIComponent(idOrSlug)}`, patch, options),
+    archive: (idOrSlug, options = {}) => this.request("DELETE", `/templates/${encodeURIComponent(idOrSlug)}`, void 0, options),
+    versions: {
+      list: async (idOrSlug, options = {}) => (await this.request("GET", `/templates/${encodeURIComponent(idOrSlug)}/versions`, void 0, options)).data,
+      /** `which`: 'published', 'latest' or a version number. Carries the files. */
+      get: (idOrSlug, which = "published", options = {}) => this.request("GET", `/templates/${encodeURIComponent(idOrSlug)}/versions/${which}`, void 0, options),
+      create: (idOrSlug, input, options = {}) => this.request("POST", `/templates/${encodeURIComponent(idOrSlug)}/versions`, input, options),
+      publish: (idOrSlug, number, options = {}) => this.request("POST", `/templates/${encodeURIComponent(idOrSlug)}/versions/${number}/publish`, void 0, options)
+    },
+    schema: (idOrSlug, options = {}) => this.request("GET", `/templates/${encodeURIComponent(idOrSlug)}/schema`, void 0, options)
+  };
+  account = {
+    get: (options = {}) => this.request("GET", "/account", void 0, options),
+    /** Units of the current period, or of `YYYY-MM`, with a daily series and a breakdown per template. */
+    usage: (period = "current", options = {}) => this.request("GET", `/usage?period=${encodeURIComponent(period)}`, void 0, options)
+  };
+  /** Raw request with auth, retries and problem mapping; use it for endpoints without a helper. */
+  async request(method, path, body, options = {}) {
+    const url = `${this.baseUrl}${path}`;
+    const headers = {
+      authorization: `Bearer ${this.apiKey}`,
+      accept: "application/json",
+      "user-agent": "formfeed-sdk-ts/0.1"
+    };
+    if (body !== void 0) headers["content-type"] = "application/json";
+    if (options.idempotencyKey) headers["idempotency-key"] = options.idempotencyKey;
+    let attempt = 0;
+    for (; ; ) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(new Error("request timed out")), this.timeoutMs);
+      options.signal?.addEventListener("abort", () => controller.abort(options.signal?.reason));
+      let res;
+      try {
+        res = await this.fetchImpl(url, {
+          method,
+          headers,
+          body: body === void 0 ? void 0 : JSON.stringify(body),
+          signal: controller.signal
+        });
+      } catch (e) {
+        clearTimeout(timer);
+        if (attempt < this.maxRetries && !options.signal?.aborted) {
+          attempt++;
+          await sleep(this.backoff(attempt, null), options.signal);
+          continue;
+        }
+        throw new FormfeedError("network_error", e instanceof Error ? e.message : String(e), 0);
+      }
+      clearTimeout(timer);
+      if ((res.status === 429 || res.status === 503) && attempt < this.maxRetries) {
+        attempt++;
+        await sleep(this.backoff(attempt, res.headers.get("retry-after")), options.signal);
+        continue;
+      }
+      if (res.status === 204) return void 0;
+      const text = await res.text();
+      const json = text ? JSON.parse(text) : null;
+      if (!res.ok) {
+        const problem = json ?? {};
+        throw new FormfeedError(
+          problem.code ?? `http_${res.status}`,
+          problem.detail ?? problem.title ?? `HTTP ${res.status}`,
+          res.status,
+          problem,
+          res.headers.get("x-request-id")
+        );
+      }
+      return json;
+    }
+  }
+  backoff(attempt, retryAfter) {
+    const fromHeader = retryAfter ? Number(retryAfter) * 1e3 : NaN;
+    const base = Number.isFinite(fromHeader) && fromHeader > 0 ? fromHeader : 500 * 2 ** (attempt - 1);
+    return Math.min(3e4, base + Math.random() * 250);
+  }
+};
+
+// packages/sdk-ts/src/lib/webhooks.ts
+var encoder = new TextEncoder();
+async function hmacHex(secret, message) {
+  const key = await crypto.subtle.importKey("raw", encoder.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+  const sig = await crypto.subtle.sign("HMAC", key, encoder.encode(message));
+  return [...new Uint8Array(sig)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+async function verifyWebhookSignature(secret, signatureHeader, rawBody, options = {}) {
+  if (!signatureHeader || !secret) return false;
+  const parts = new Map(signatureHeader.split(",").map((kv) => kv.trim().split("=")));
+  const t = Number(parts.get("t"));
+  const v1 = (parts.get("v1") ?? "").toLowerCase();
+  if (!Number.isFinite(t) || !/^[0-9a-f]{64}$/.test(v1)) return false;
+  const now = options.now ?? Math.floor(Date.now() / 1e3);
+  if (Math.abs(now - t) > (options.toleranceSeconds ?? 300)) return false;
+  const expected = await hmacHex(secret, `${t}.${rawBody}`);
+  let diff = 0;
+  for (let i = 0; i < expected.length; i++) diff |= expected.charCodeAt(i) ^ v1.charCodeAt(i);
+  return diff === 0;
+}
+async function parseWebhookEvent(secret, signatureHeader, rawBody, options = {}) {
+  if (!await verifyWebhookSignature(secret, signatureHeader, rawBody, options))
+    throw new Error("invalid webhook signature");
+  return JSON.parse(rawBody);
+}

package/index.js

@@ -0,0 +1,244 @@
+// packages/sdk-ts/src/lib/client.ts
+var FormfeedError = class extends Error {
+  constructor(code, message, status, problem = null, requestId = null) {
+    super(message);
+    this.code = code;
+    this.status = status;
+    this.problem = problem;
+    this.requestId = requestId;
+  }
+  name = "FormfeedError";
+};
+var hosts = {
+  eu: "https://api-eu.formfeed.dev/v1",
+  us: "https://api-us.formfeed.dev/v1"
+};
+var sleep = (ms, signal) => new Promise((resolve, reject) => {
+  const t = setTimeout(resolve, ms);
+  signal?.addEventListener("abort", () => {
+    clearTimeout(t);
+    reject(signal.reason ?? new Error("aborted"));
+  });
+});
+function randomKey() {
+  const c = globalThis.crypto;
+  if (c?.randomUUID) return c.randomUUID();
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+}
+var Formfeed = class {
+  baseUrl;
+  apiKey;
+  fetchImpl;
+  maxRetries;
+  timeoutMs;
+  constructor(options) {
+    if (!options.apiKey) throw new FormfeedError("invalid_request", "apiKey is required", 0);
+    this.apiKey = options.apiKey;
+    this.baseUrl = (options.baseUrl ?? hosts[options.region ?? "eu"]).replace(/\/$/, "");
+    this.fetchImpl = options.fetch ?? globalThis.fetch;
+    this.maxRetries = options.maxRetries ?? 3;
+    this.timeoutMs = options.timeoutMs ?? 12e4;
+    if (!this.fetchImpl) throw new FormfeedError("invalid_request", "fetch is not available; pass options.fetch", 0);
+  }
+  renders = {
+    /** Renders a template, HTML or URL. Sync by default; `mode: 'async'` returns a queued render. */
+    create: (request, options = {}) => this.request("POST", "/renders", request, {
+      ...options,
+      idempotencyKey: options.idempotencyKey ?? randomKey()
+    }),
+    get: (id, options = {}) => this.request("GET", `/renders/${encodeURIComponent(id)}`, void 0, options),
+    /** Polls until the render succeeded or failed (async renders). */
+    waitFor: async (id, options = {}) => {
+      const deadline = Date.now() + (options.timeoutMs ?? 12e4);
+      const interval = options.intervalMs ?? 1e3;
+      for (; ; ) {
+        const render = await this.renders.get(id, { signal: options.signal });
+        if (render.status === "succeeded" || render.status === "failed") return render;
+        if (Date.now() + interval > deadline)
+          throw new FormfeedError("timeout", `render ${id} did not finish within the wait time`, 0);
+        await sleep(interval, options.signal);
+      }
+    },
+    /** Downloads the output of a finished render as bytes. */
+    download: async (render, options = {}) => {
+      const target = typeof render === "string" ? await this.renders.get(render, options) : render;
+      if (!target.download_url)
+        throw new FormfeedError("not_ready", `render ${target.id} has no output (${target.status})`, 0);
+      const res = await this.fetchImpl(target.download_url, { signal: options.signal });
+      if (!res.ok) throw new FormfeedError("download_failed", `download answered HTTP ${res.status}`, res.status);
+      return new Uint8Array(await res.arrayBuffer());
+    },
+    /** Page of renders, newest first. */
+    list: (query = {}, options = {}) => {
+      const params = new URLSearchParams();
+      for (const [k, v] of Object.entries(query)) if (v !== void 0 && v !== null && v !== "") params.set(k, String(v));
+      const qs = params.toString();
+      return this.request("GET", `/renders${qs ? `?${qs}` : ""}`, void 0, options);
+    },
+    /** Every render matching the query, following the cursor. */
+    all: async (query = {}, options = {}) => {
+      const out = [];
+      let cursor = null;
+      do {
+        const page = await this.renders.list({ ...query, cursor }, options);
+        out.push(...page.data);
+        cursor = page.next_cursor;
+      } while (cursor);
+      return out;
+    },
+    /** Removes the stored files of a render before they expire. Needs the `file:delete` scope. */
+    deleteOutputs: (id, options = {}) => this.request("DELETE", `/renders/${encodeURIComponent(id)}/outputs`, void 0, options),
+    batch: (request, options = {}) => this.request("POST", "/renders/batch", request, {
+      ...options,
+      idempotencyKey: options.idempotencyKey ?? randomKey()
+    })
+  };
+  jobs = {
+    get: (id, options = {}) => this.request("GET", `/jobs/${encodeURIComponent(id)}`, void 0, options),
+    waitFor: async (id, options = {}) => {
+      const deadline = Date.now() + (options.timeoutMs ?? 6e5);
+      const interval = options.intervalMs ?? 2e3;
+      for (; ; ) {
+        const job = await this.jobs.get(id, { signal: options.signal });
+        if (job.status !== "queued" && job.status !== "processing") return job;
+        if (Date.now() + interval > deadline)
+          throw new FormfeedError("timeout", `job ${id} did not finish within the wait time`, 0);
+        await sleep(interval, options.signal);
+      }
+    }
+  };
+  webhooks = {
+    list: async (options = {}) => (await this.request("GET", "/webhooks", void 0, options)).data,
+    create: (input, options = {}) => this.request("POST", "/webhooks", input, options),
+    update: (id, patch, options = {}) => this.request("PUT", `/webhooks/${encodeURIComponent(id)}`, patch, options),
+    delete: (id, options = {}) => this.request("DELETE", `/webhooks/${encodeURIComponent(id)}`, void 0, options),
+    test: (id, options = {}) => this.request("POST", `/webhooks/${encodeURIComponent(id)}/test`, void 0, options)
+  };
+  templates = {
+    list: (query = {}, options = {}) => {
+      const params = new URLSearchParams();
+      for (const [k, v] of Object.entries(query)) if (v !== void 0 && v !== null && v !== "") params.set(k, String(v));
+      const qs = params.toString();
+      return this.request("GET", `/templates${qs ? `?${qs}` : ""}`, void 0, options);
+    },
+    /** Every template of the workspace, following the cursor. */
+    all: async (query = {}, options = {}) => {
+      const out = [];
+      let cursor = null;
+      do {
+        const page = await this.templates.list({ ...query, cursor }, options);
+        out.push(...page.data);
+        cursor = page.next_cursor;
+      } while (cursor);
+      return out;
+    },
+    get: (idOrSlug, options = {}) => this.request("GET", `/templates/${encodeURIComponent(idOrSlug)}`, void 0, options),
+    create: (input, options = {}) => this.request("POST", "/templates", input, options),
+    update: (idOrSlug, patch, options = {}) => this.request("PUT", `/templates/${encodeURIComponent(idOrSlug)}`, patch, options),
+    archive: (idOrSlug, options = {}) => this.request("DELETE", `/templates/${encodeURIComponent(idOrSlug)}`, void 0, options),
+    versions: {
+      list: async (idOrSlug, options = {}) => (await this.request("GET", `/templates/${encodeURIComponent(idOrSlug)}/versions`, void 0, options)).data,
+      /** `which`: 'published', 'latest' or a version number. Carries the files. */
+      get: (idOrSlug, which = "published", options = {}) => this.request("GET", `/templates/${encodeURIComponent(idOrSlug)}/versions/${which}`, void 0, options),
+      create: (idOrSlug, input, options = {}) => this.request("POST", `/templates/${encodeURIComponent(idOrSlug)}/versions`, input, options),
+      publish: (idOrSlug, number, options = {}) => this.request("POST", `/templates/${encodeURIComponent(idOrSlug)}/versions/${number}/publish`, void 0, options)
+    },
+    schema: (idOrSlug, options = {}) => this.request("GET", `/templates/${encodeURIComponent(idOrSlug)}/schema`, void 0, options)
+  };
+  account = {
+    get: (options = {}) => this.request("GET", "/account", void 0, options),
+    /** Units of the current period, or of `YYYY-MM`, with a daily series and a breakdown per template. */
+    usage: (period = "current", options = {}) => this.request("GET", `/usage?period=${encodeURIComponent(period)}`, void 0, options)
+  };
+  /** Raw request with auth, retries and problem mapping; use it for endpoints without a helper. */
+  async request(method, path, body, options = {}) {
+    const url = `${this.baseUrl}${path}`;
+    const headers = {
+      authorization: `Bearer ${this.apiKey}`,
+      accept: "application/json",
+      "user-agent": "formfeed-sdk-ts/0.1"
+    };
+    if (body !== void 0) headers["content-type"] = "application/json";
+    if (options.idempotencyKey) headers["idempotency-key"] = options.idempotencyKey;
+    let attempt = 0;
+    for (; ; ) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(new Error("request timed out")), this.timeoutMs);
+      options.signal?.addEventListener("abort", () => controller.abort(options.signal?.reason));
+      let res;
+      try {
+        res = await this.fetchImpl(url, {
+          method,
+          headers,
+          body: body === void 0 ? void 0 : JSON.stringify(body),
+          signal: controller.signal
+        });
+      } catch (e) {
+        clearTimeout(timer);
+        if (attempt < this.maxRetries && !options.signal?.aborted) {
+          attempt++;
+          await sleep(this.backoff(attempt, null), options.signal);
+          continue;
+        }
+        throw new FormfeedError("network_error", e instanceof Error ? e.message : String(e), 0);
+      }
+      clearTimeout(timer);
+      if ((res.status === 429 || res.status === 503) && attempt < this.maxRetries) {
+        attempt++;
+        await sleep(this.backoff(attempt, res.headers.get("retry-after")), options.signal);
+        continue;
+      }
+      if (res.status === 204) return void 0;
+      const text = await res.text();
+      const json = text ? JSON.parse(text) : null;
+      if (!res.ok) {
+        const problem = json ?? {};
+        throw new FormfeedError(
+          problem.code ?? `http_${res.status}`,
+          problem.detail ?? problem.title ?? `HTTP ${res.status}`,
+          res.status,
+          problem,
+          res.headers.get("x-request-id")
+        );
+      }
+      return json;
+    }
+  }
+  backoff(attempt, retryAfter) {
+    const fromHeader = retryAfter ? Number(retryAfter) * 1e3 : NaN;
+    const base = Number.isFinite(fromHeader) && fromHeader > 0 ? fromHeader : 500 * 2 ** (attempt - 1);
+    return Math.min(3e4, base + Math.random() * 250);
+  }
+};
+
+// packages/sdk-ts/src/lib/webhooks.ts
+var encoder = new TextEncoder();
+async function hmacHex(secret, message) {
+  const key = await crypto.subtle.importKey("raw", encoder.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+  const sig = await crypto.subtle.sign("HMAC", key, encoder.encode(message));
+  return [...new Uint8Array(sig)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+async function verifyWebhookSignature(secret, signatureHeader, rawBody, options = {}) {
+  if (!signatureHeader || !secret) return false;
+  const parts = new Map(signatureHeader.split(",").map((kv) => kv.trim().split("=")));
+  const t = Number(parts.get("t"));
+  const v1 = (parts.get("v1") ?? "").toLowerCase();
+  if (!Number.isFinite(t) || !/^[0-9a-f]{64}$/.test(v1)) return false;
+  const now = options.now ?? Math.floor(Date.now() / 1e3);
+  if (Math.abs(now - t) > (options.toleranceSeconds ?? 300)) return false;
+  const expected = await hmacHex(secret, `${t}.${rawBody}`);
+  let diff = 0;
+  for (let i = 0; i < expected.length; i++) diff |= expected.charCodeAt(i) ^ v1.charCodeAt(i);
+  return diff === 0;
+}
+async function parseWebhookEvent(secret, signatureHeader, rawBody, options = {}) {
+  if (!await verifyWebhookSignature(secret, signatureHeader, rawBody, options))
+    throw new Error("invalid webhook signature");
+  return JSON.parse(rawBody);
+}
+export {
+  Formfeed,
+  FormfeedError,
+  parseWebhookEvent,
+  verifyWebhookSignature
+};

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@formfeed/sdk",
+  "version": "0.1.0",
+  "description": "Formfeed API client: renders, templates, webhooks. No dependencies, Web APIs only.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./index.cjs",
+  "module": "./index.js",
+  "types": "./types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./types/index.d.ts",
+        "default": "./index.js"
+      },
+      "require": {
+        "types": "./types/index.d.cts",
+        "default": "./index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "*.js",
+    "*.cjs",
+    "types",
+    "README.md",
+    "LICENSE",
+    "THIRD_PARTY_LICENSES.md"
+  ],
+  "sideEffects": false,
+  "dependencies": {},
+  "keywords": [
+    "formfeed",
+    "pdf",
+    "pdf-generation",
+    "html-to-pdf",
+    "image-generation",
+    "templates",
+    "api",
+    "sdk"
+  ],
+  "homepage": "https://docs.formfeed.dev/api/sdks/typescript",
+  "author": {
+    "name": "Formfeed",
+    "email": "support@formfeed.dev",
+    "url": "https://formfeed.dev"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/formfeed-dev/formfeed.git",
+    "directory": "packages/sdk-ts"
+  },
+  "bugs": {
+    "url": "https://github.com/formfeed-dev/formfeed/issues",
+    "email": "support@formfeed.dev"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/types/index.d.cts

@@ -0,0 +1,4 @@
+export { Formfeed, FormfeedError } from './lib/client.cjs';
+export type { Template, TemplateCreate, TemplateFiles, TemplateKind, TemplateListOptions, TemplateVersion, TemplateVersionCreate, VersionStatus, BatchRequest, Engine, FormfeedOptions, Job, OutputFormat, Problem, Region, Render, RenderListOptions, RenderRequest, RenderStatus, RequestOptions, Usage, WaitOptions, WebhookEndpoint, } from './lib/client.cjs';
+export { parseWebhookEvent, verifyWebhookSignature } from './lib/webhooks.cjs';
+export type { VerifyOptions } from './lib/webhooks.cjs';

package/types/index.d.ts

@@ -0,0 +1,4 @@
+export { Formfeed, FormfeedError } from './lib/client.js';
+export type { Template, TemplateCreate, TemplateFiles, TemplateKind, TemplateListOptions, TemplateVersion, TemplateVersionCreate, VersionStatus, BatchRequest, Engine, FormfeedOptions, Job, OutputFormat, Problem, Region, Render, RenderListOptions, RenderRequest, RenderStatus, RequestOptions, Usage, WaitOptions, WebhookEndpoint, } from './lib/client.js';
+export { parseWebhookEvent, verifyWebhookSignature } from './lib/webhooks.js';
+export type { VerifyOptions } from './lib/webhooks.js';

package/types/lib/client.d.cts

@@ -0,0 +1,295 @@
+/**
+ * `@formfeed/sdk` (spec 10 §1): a fetch-based client for the public API. Runs in Node 18+, Deno,
+ * Bun, Workers and browsers (with a test key). Retries 429 and 503 with the server's Retry-After
+ * and jitter, generates an Idempotency-Key for every render, and turns RFC 9457 problems into
+ * typed errors.
+ */
+export type Region = 'eu' | 'us';
+export type Engine = 'jinja2' | 'liquid' | 'handlebars';
+export type OutputFormat = 'pdf' | 'png' | 'jpg' | 'webp';
+export type RenderStatus = 'queued' | 'rendering' | 'succeeded' | 'failed';
+export interface FormfeedOptions {
+    apiKey: string;
+    /** Region of the API host; ignored when `baseUrl` is given. */
+    region?: Region;
+    /** Full base URL including `/v1`, for self-hosted or local gateways. */
+    baseUrl?: string;
+    fetch?: typeof fetch;
+    /** Retries on 429 and 503; 0 disables. */
+    maxRetries?: number;
+    timeoutMs?: number;
+}
+export interface RenderRequest {
+    template?: string;
+    version?: string;
+    html?: string;
+    url?: string;
+    engine?: Engine;
+    data?: Record<string, unknown>;
+    output?: OutputFormat;
+    settings?: Record<string, unknown>;
+    filename?: string;
+    expires_in?: number | null;
+    access?: 'public' | 'signed';
+    mode?: 'sync' | 'async';
+    locale?: string | null;
+    webhook_url?: string | null;
+    meta?: Record<string, unknown>;
+    region?: Region;
+    dedupe?: boolean;
+}
+export interface Render {
+    id: string;
+    status: RenderStatus;
+    output: string;
+    download_url: string | null;
+    expires_at: string | null;
+    bytes: number | null;
+    page_count: number | null;
+    units: number;
+    region: string;
+    environment: 'live' | 'test';
+    template: {
+        id: string;
+        slug: string;
+        version: number;
+    } | null;
+    engine_version: string | null;
+    template_checksum: string | null;
+    output_sha256: string | null;
+    deduplicated: boolean;
+    timings: Record<string, number> | null;
+    error: {
+        code?: string;
+        message?: string;
+        [key: string]: unknown;
+    } | null;
+    meta: Record<string, unknown>;
+    created_at: string;
+    completed_at: string | null;
+}
+export interface BatchRequest {
+    template?: string;
+    items: RenderRequest[];
+    zip?: boolean;
+    webhook_url?: string | null;
+    meta?: Record<string, unknown>;
+}
+export interface Job {
+    id: string;
+    type: 'single' | 'batch';
+    status: 'queued' | 'processing' | 'completed' | 'partially_failed' | 'failed';
+    total: number;
+    succeeded: number;
+    failed: number;
+    zip_url: string | null;
+    zip_expires_at: string | null;
+    items: Render[];
+    meta: Record<string, unknown>;
+    created_at: string;
+    completed_at: string | null;
+}
+export interface WebhookEndpoint {
+    id: string;
+    url: string;
+    events: string[];
+    enabled: boolean;
+    description: string | null;
+    consecutive_failures: number;
+    /** Only present in the response of `create`. */
+    secret?: string;
+    created_at: string;
+    updated_at: string;
+}
+export type TemplateKind = 'pdf' | 'image';
+export type VersionStatus = 'draft' | 'published' | 'archived';
+export interface Template {
+    id: string;
+    slug: string;
+    name: string;
+    description: string | null;
+    kind: TemplateKind;
+    engine: Engine;
+    tags: string[];
+    published_version: number | null;
+    latest_version: number;
+    created_at: string;
+    updated_at: string;
+}
+/** The files of a version as the editor and the CLI keep them. */
+export interface TemplateFiles {
+    html: string;
+    css?: string;
+    head?: string;
+    settings?: Record<string, unknown>;
+    sample_data?: Record<string, unknown>;
+    /** Named sample data sets besides the default one, as the editor and the dev kit show them. */
+    data_sets?: Record<string, unknown> | null;
+    data_schema?: Record<string, unknown> | null;
+    i18n?: Record<string, unknown> | null;
+}
+export interface TemplateVersion extends Partial<TemplateFiles> {
+    id: string;
+    number: number;
+    status: VersionStatus;
+    checksum: string;
+    change_note: string | null;
+    created_at: string;
+    published_at: string | null;
+}
+export interface TemplateCreate extends TemplateFiles {
+    name: string;
+    slug: string;
+    description?: string | null;
+    kind: TemplateKind;
+    engine: Engine;
+    tags?: string[];
+    publish?: boolean;
+}
+export interface TemplateVersionCreate extends TemplateFiles {
+    change_note?: string;
+    /** Checksum of the version the draft was based on; the API answers 409 when the latest differs. */
+    base_checksum?: string;
+    publish?: boolean;
+}
+export interface Usage {
+    period: string;
+    included: number;
+    used: number;
+    overage_used: number;
+    overage_balance: number;
+    daily: Array<{
+        date: string;
+        units: number;
+        renders: number;
+    }>;
+    by_template: Array<{
+        template: string;
+        units: number;
+    }>;
+}
+export interface RenderListOptions {
+    template?: string;
+    status?: RenderStatus;
+    environment?: 'live' | 'test';
+    /** ISO timestamps bounding `created_at`. */
+    since?: string;
+    until?: string;
+    limit?: number;
+    cursor?: string | null;
+}
+export interface TemplateListOptions {
+    kind?: TemplateKind;
+    engine?: Engine;
+    tag?: string;
+    q?: string;
+    limit?: number;
+    cursor?: string | null;
+}
+export interface Problem {
+    type?: string;
+    title?: string;
+    status?: number;
+    detail?: string;
+    code?: string;
+    request_id?: string;
+    [key: string]: unknown;
+}
+export declare class FormfeedError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly problem: Problem | null;
+    readonly requestId: string | null;
+    readonly name = "FormfeedError";
+    constructor(code: string, message: string, status: number, problem?: Problem | null, requestId?: string | null);
+}
+export interface RequestOptions {
+    idempotencyKey?: string;
+    signal?: AbortSignal;
+}
+export interface WaitOptions {
+    timeoutMs?: number;
+    intervalMs?: number;
+    signal?: AbortSignal;
+}
+export declare class Formfeed {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly fetchImpl;
+    private readonly maxRetries;
+    private readonly timeoutMs;
+    constructor(options: FormfeedOptions);
+    readonly renders: {
+        /** Renders a template, HTML or URL. Sync by default; `mode: 'async'` returns a queued render. */
+        create: (request: RenderRequest, options?: RequestOptions) => Promise<Render>;
+        get: (id: string, options?: RequestOptions) => Promise<Render>;
+        /** Polls until the render succeeded or failed (async renders). */
+        waitFor: (id: string, options?: WaitOptions) => Promise<Render>;
+        /** Downloads the output of a finished render as bytes. */
+        download: (render: Render | string, options?: RequestOptions) => Promise<Uint8Array>;
+        /** Page of renders, newest first. */
+        list: (query?: RenderListOptions, options?: RequestOptions) => Promise<{
+            data: Render[];
+            next_cursor: string | null;
+        }>;
+        /** Every render matching the query, following the cursor. */
+        all: (query?: Omit<RenderListOptions, "cursor">, options?: RequestOptions) => Promise<Render[]>;
+        /** Removes the stored files of a render before they expire. Needs the `file:delete` scope. */
+        deleteOutputs: (id: string, options?: RequestOptions) => Promise<void>;
+        batch: (request: BatchRequest, options?: RequestOptions) => Promise<Job>;
+    };
+    readonly jobs: {
+        get: (id: string, options?: RequestOptions) => Promise<Job>;
+        waitFor: (id: string, options?: WaitOptions) => Promise<Job>;
+    };
+    readonly webhooks: {
+        list: (options?: RequestOptions) => Promise<WebhookEndpoint[]>;
+        create: (input: {
+            url: string;
+            events?: string[];
+            description?: string | null;
+        }, options?: RequestOptions) => Promise<WebhookEndpoint>;
+        update: (id: string, patch: {
+            url?: string;
+            events?: string[];
+            enabled?: boolean;
+            description?: string | null;
+        }, options?: RequestOptions) => Promise<WebhookEndpoint>;
+        delete: (id: string, options?: RequestOptions) => Promise<void>;
+        test: (id: string, options?: RequestOptions) => Promise<{
+            queued: boolean;
+        }>;
+    };
+    readonly templates: {
+        list: (query?: TemplateListOptions, options?: RequestOptions) => Promise<{
+            data: Template[];
+            next_cursor: string | null;
+        }>;
+        /** Every template of the workspace, following the cursor. */
+        all: (query?: Omit<TemplateListOptions, "cursor">, options?: RequestOptions) => Promise<Template[]>;
+        get: (idOrSlug: string, options?: RequestOptions) => Promise<Template>;
+        create: (input: TemplateCreate, options?: RequestOptions) => Promise<Template>;
+        update: (idOrSlug: string, patch: {
+            name?: string;
+            description?: string | null;
+            tags?: string[];
+        }, options?: RequestOptions) => Promise<Template>;
+        archive: (idOrSlug: string, options?: RequestOptions) => Promise<void>;
+        versions: {
+            list: (idOrSlug: string, options?: RequestOptions) => Promise<TemplateVersion[]>;
+            /** `which`: 'published', 'latest' or a version number. Carries the files. */
+            get: (idOrSlug: string, which?: "published" | "latest" | number, options?: RequestOptions) => Promise<TemplateVersion>;
+            create: (idOrSlug: string, input: TemplateVersionCreate, options?: RequestOptions) => Promise<TemplateVersion>;
+            publish: (idOrSlug: string, number: number, options?: RequestOptions) => Promise<TemplateVersion>;
+        };
+        schema: (idOrSlug: string, options?: RequestOptions) => Promise<Record<string, unknown>>;
+    };
+    readonly account: {
+        get: (options?: RequestOptions) => Promise<Record<string, unknown>>;
+        /** Units of the current period, or of `YYYY-MM`, with a daily series and a breakdown per template. */
+        usage: (period?: string, options?: RequestOptions) => Promise<Usage>;
+    };
+    /** Raw request with auth, retries and problem mapping; use it for endpoints without a helper. */
+    request<T>(method: string, path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    private backoff;
+}

package/types/lib/client.d.ts

@@ -0,0 +1,295 @@
+/**
+ * `@formfeed/sdk` (spec 10 §1): a fetch-based client for the public API. Runs in Node 18+, Deno,
+ * Bun, Workers and browsers (with a test key). Retries 429 and 503 with the server's Retry-After
+ * and jitter, generates an Idempotency-Key for every render, and turns RFC 9457 problems into
+ * typed errors.
+ */
+export type Region = 'eu' | 'us';
+export type Engine = 'jinja2' | 'liquid' | 'handlebars';
+export type OutputFormat = 'pdf' | 'png' | 'jpg' | 'webp';
+export type RenderStatus = 'queued' | 'rendering' | 'succeeded' | 'failed';
+export interface FormfeedOptions {
+    apiKey: string;
+    /** Region of the API host; ignored when `baseUrl` is given. */
+    region?: Region;
+    /** Full base URL including `/v1`, for self-hosted or local gateways. */
+    baseUrl?: string;
+    fetch?: typeof fetch;
+    /** Retries on 429 and 503; 0 disables. */
+    maxRetries?: number;
+    timeoutMs?: number;
+}
+export interface RenderRequest {
+    template?: string;
+    version?: string;
+    html?: string;
+    url?: string;
+    engine?: Engine;
+    data?: Record<string, unknown>;
+    output?: OutputFormat;
+    settings?: Record<string, unknown>;
+    filename?: string;
+    expires_in?: number | null;
+    access?: 'public' | 'signed';
+    mode?: 'sync' | 'async';
+    locale?: string | null;
+    webhook_url?: string | null;
+    meta?: Record<string, unknown>;
+    region?: Region;
+    dedupe?: boolean;
+}
+export interface Render {
+    id: string;
+    status: RenderStatus;
+    output: string;
+    download_url: string | null;
+    expires_at: string | null;
+    bytes: number | null;
+    page_count: number | null;
+    units: number;
+    region: string;
+    environment: 'live' | 'test';
+    template: {
+        id: string;
+        slug: string;
+        version: number;
+    } | null;
+    engine_version: string | null;
+    template_checksum: string | null;
+    output_sha256: string | null;
+    deduplicated: boolean;
+    timings: Record<string, number> | null;
+    error: {
+        code?: string;
+        message?: string;
+        [key: string]: unknown;
+    } | null;
+    meta: Record<string, unknown>;
+    created_at: string;
+    completed_at: string | null;
+}
+export interface BatchRequest {
+    template?: string;
+    items: RenderRequest[];
+    zip?: boolean;
+    webhook_url?: string | null;
+    meta?: Record<string, unknown>;
+}
+export interface Job {
+    id: string;
+    type: 'single' | 'batch';
+    status: 'queued' | 'processing' | 'completed' | 'partially_failed' | 'failed';
+    total: number;
+    succeeded: number;
+    failed: number;
+    zip_url: string | null;
+    zip_expires_at: string | null;
+    items: Render[];
+    meta: Record<string, unknown>;
+    created_at: string;
+    completed_at: string | null;
+}
+export interface WebhookEndpoint {
+    id: string;
+    url: string;
+    events: string[];
+    enabled: boolean;
+    description: string | null;
+    consecutive_failures: number;
+    /** Only present in the response of `create`. */
+    secret?: string;
+    created_at: string;
+    updated_at: string;
+}
+export type TemplateKind = 'pdf' | 'image';
+export type VersionStatus = 'draft' | 'published' | 'archived';
+export interface Template {
+    id: string;
+    slug: string;
+    name: string;
+    description: string | null;
+    kind: TemplateKind;
+    engine: Engine;
+    tags: string[];
+    published_version: number | null;
+    latest_version: number;
+    created_at: string;
+    updated_at: string;
+}
+/** The files of a version as the editor and the CLI keep them. */
+export interface TemplateFiles {
+    html: string;
+    css?: string;
+    head?: string;
+    settings?: Record<string, unknown>;
+    sample_data?: Record<string, unknown>;
+    /** Named sample data sets besides the default one, as the editor and the dev kit show them. */
+    data_sets?: Record<string, unknown> | null;
+    data_schema?: Record<string, unknown> | null;
+    i18n?: Record<string, unknown> | null;
+}
+export interface TemplateVersion extends Partial<TemplateFiles> {
+    id: string;
+    number: number;
+    status: VersionStatus;
+    checksum: string;
+    change_note: string | null;
+    created_at: string;
+    published_at: string | null;
+}
+export interface TemplateCreate extends TemplateFiles {
+    name: string;
+    slug: string;
+    description?: string | null;
+    kind: TemplateKind;
+    engine: Engine;
+    tags?: string[];
+    publish?: boolean;
+}
+export interface TemplateVersionCreate extends TemplateFiles {
+    change_note?: string;
+    /** Checksum of the version the draft was based on; the API answers 409 when the latest differs. */
+    base_checksum?: string;
+    publish?: boolean;
+}
+export interface Usage {
+    period: string;
+    included: number;
+    used: number;
+    overage_used: number;
+    overage_balance: number;
+    daily: Array<{
+        date: string;
+        units: number;
+        renders: number;
+    }>;
+    by_template: Array<{
+        template: string;
+        units: number;
+    }>;
+}
+export interface RenderListOptions {
+    template?: string;
+    status?: RenderStatus;
+    environment?: 'live' | 'test';
+    /** ISO timestamps bounding `created_at`. */
+    since?: string;
+    until?: string;
+    limit?: number;
+    cursor?: string | null;
+}
+export interface TemplateListOptions {
+    kind?: TemplateKind;
+    engine?: Engine;
+    tag?: string;
+    q?: string;
+    limit?: number;
+    cursor?: string | null;
+}
+export interface Problem {
+    type?: string;
+    title?: string;
+    status?: number;
+    detail?: string;
+    code?: string;
+    request_id?: string;
+    [key: string]: unknown;
+}
+export declare class FormfeedError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly problem: Problem | null;
+    readonly requestId: string | null;
+    readonly name = "FormfeedError";
+    constructor(code: string, message: string, status: number, problem?: Problem | null, requestId?: string | null);
+}
+export interface RequestOptions {
+    idempotencyKey?: string;
+    signal?: AbortSignal;
+}
+export interface WaitOptions {
+    timeoutMs?: number;
+    intervalMs?: number;
+    signal?: AbortSignal;
+}
+export declare class Formfeed {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly fetchImpl;
+    private readonly maxRetries;
+    private readonly timeoutMs;
+    constructor(options: FormfeedOptions);
+    readonly renders: {
+        /** Renders a template, HTML or URL. Sync by default; `mode: 'async'` returns a queued render. */
+        create: (request: RenderRequest, options?: RequestOptions) => Promise<Render>;
+        get: (id: string, options?: RequestOptions) => Promise<Render>;
+        /** Polls until the render succeeded or failed (async renders). */
+        waitFor: (id: string, options?: WaitOptions) => Promise<Render>;
+        /** Downloads the output of a finished render as bytes. */
+        download: (render: Render | string, options?: RequestOptions) => Promise<Uint8Array>;
+        /** Page of renders, newest first. */
+        list: (query?: RenderListOptions, options?: RequestOptions) => Promise<{
+            data: Render[];
+            next_cursor: string | null;
+        }>;
+        /** Every render matching the query, following the cursor. */
+        all: (query?: Omit<RenderListOptions, "cursor">, options?: RequestOptions) => Promise<Render[]>;
+        /** Removes the stored files of a render before they expire. Needs the `file:delete` scope. */
+        deleteOutputs: (id: string, options?: RequestOptions) => Promise<void>;
+        batch: (request: BatchRequest, options?: RequestOptions) => Promise<Job>;
+    };
+    readonly jobs: {
+        get: (id: string, options?: RequestOptions) => Promise<Job>;
+        waitFor: (id: string, options?: WaitOptions) => Promise<Job>;
+    };
+    readonly webhooks: {
+        list: (options?: RequestOptions) => Promise<WebhookEndpoint[]>;
+        create: (input: {
+            url: string;
+            events?: string[];
+            description?: string | null;
+        }, options?: RequestOptions) => Promise<WebhookEndpoint>;
+        update: (id: string, patch: {
+            url?: string;
+            events?: string[];
+            enabled?: boolean;
+            description?: string | null;
+        }, options?: RequestOptions) => Promise<WebhookEndpoint>;
+        delete: (id: string, options?: RequestOptions) => Promise<void>;
+        test: (id: string, options?: RequestOptions) => Promise<{
+            queued: boolean;
+        }>;
+    };
+    readonly templates: {
+        list: (query?: TemplateListOptions, options?: RequestOptions) => Promise<{
+            data: Template[];
+            next_cursor: string | null;
+        }>;
+        /** Every template of the workspace, following the cursor. */
+        all: (query?: Omit<TemplateListOptions, "cursor">, options?: RequestOptions) => Promise<Template[]>;
+        get: (idOrSlug: string, options?: RequestOptions) => Promise<Template>;
+        create: (input: TemplateCreate, options?: RequestOptions) => Promise<Template>;
+        update: (idOrSlug: string, patch: {
+            name?: string;
+            description?: string | null;
+            tags?: string[];
+        }, options?: RequestOptions) => Promise<Template>;
+        archive: (idOrSlug: string, options?: RequestOptions) => Promise<void>;
+        versions: {
+            list: (idOrSlug: string, options?: RequestOptions) => Promise<TemplateVersion[]>;
+            /** `which`: 'published', 'latest' or a version number. Carries the files. */
+            get: (idOrSlug: string, which?: "published" | "latest" | number, options?: RequestOptions) => Promise<TemplateVersion>;
+            create: (idOrSlug: string, input: TemplateVersionCreate, options?: RequestOptions) => Promise<TemplateVersion>;
+            publish: (idOrSlug: string, number: number, options?: RequestOptions) => Promise<TemplateVersion>;
+        };
+        schema: (idOrSlug: string, options?: RequestOptions) => Promise<Record<string, unknown>>;
+    };
+    readonly account: {
+        get: (options?: RequestOptions) => Promise<Record<string, unknown>>;
+        /** Units of the current period, or of `YYYY-MM`, with a daily series and a breakdown per template. */
+        usage: (period?: string, options?: RequestOptions) => Promise<Usage>;
+    };
+    /** Raw request with auth, retries and problem mapping; use it for endpoints without a helper. */
+    request<T>(method: string, path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    private backoff;
+}

package/types/lib/webhooks.d.cts

@@ -0,0 +1,19 @@
+export interface VerifyOptions {
+    /** Maximum age of the timestamp in seconds (default 300). */
+    toleranceSeconds?: number;
+    /** Unix seconds "now"; tests pass a fixed clock. */
+    now?: number;
+}
+/**
+ * Returns true when the header matches the raw body. Pass the body exactly as received (not
+ * re-serialised JSON): the signature covers the bytes on the wire.
+ */
+export declare function verifyWebhookSignature(secret: string, signatureHeader: string | null | undefined, rawBody: string, options?: VerifyOptions): Promise<boolean>;
+/** Parses a verified event body. Throws when the signature does not match. */
+export declare function parseWebhookEvent<T = {
+    id: string;
+    type: string;
+    created_at: string;
+    workspace_id: string | null;
+    data: unknown;
+}>(secret: string, signatureHeader: string | null | undefined, rawBody: string, options?: VerifyOptions): Promise<T>;

package/types/lib/webhooks.d.ts

@@ -0,0 +1,19 @@
+export interface VerifyOptions {
+    /** Maximum age of the timestamp in seconds (default 300). */
+    toleranceSeconds?: number;
+    /** Unix seconds "now"; tests pass a fixed clock. */
+    now?: number;
+}
+/**
+ * Returns true when the header matches the raw body. Pass the body exactly as received (not
+ * re-serialised JSON): the signature covers the bytes on the wire.
+ */
+export declare function verifyWebhookSignature(secret: string, signatureHeader: string | null | undefined, rawBody: string, options?: VerifyOptions): Promise<boolean>;
+/** Parses a verified event body. Throws when the signature does not match. */
+export declare function parseWebhookEvent<T = {
+    id: string;
+    type: string;
+    created_at: string;
+    workspace_id: string | null;
+    data: unknown;
+}>(secret: string, signatureHeader: string | null | undefined, rawBody: string, options?: VerifyOptions): Promise<T>;