@pdfcraft-dev/pdf 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gaurav Singh
+
+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,207 @@
+# @pdfcraft-dev/pdf
+
+**HTML to PDF in one call.** The official TypeScript client for [PDFCraft](https://pdfcraft.dev) —
+POST some HTML or a URL, get back a PDF rendered by real Chromium.
+
+[![npm](https://img.shields.io/npm/v/@pdfcraft-dev/pdf.svg)](https://www.npmjs.com/package/@pdfcraft-dev/pdf)
+[![zero dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg)](#what-you-are-installing)
+[![license](https://img.shields.io/npm/l/@pdfcraft-dev/pdf.svg)](./LICENSE)
+
+```bash
+npm install @pdfcraft-dev/pdf
+```
+
+```ts
+import { Renderer } from '@pdfcraft-dev/pdf';
+
+const pdfcraft = new Renderer(process.env.PDFCRAFT_API_KEY!);
+
+const pdf = await pdfcraft.render({ html: '<h1>Invoice 1042</h1>' });
+await writeFile('invoice.pdf', pdf);
+```
+
+That is the whole product. No browser to install, no Chromium in your Docker image, no
+`--disable-dev-shm-usage` to discover the hard way. Get a key at
+[pdfcraft.dev](https://pdfcraft.dev) — the free tier is 100 renders a month and needs no
+card.
+
+## What you are installing
+
+**Zero runtime dependencies.** 24 kB packed — about half of which is source maps, so stack
+traces from inside the client point at real TypeScript — and nothing beneath it in your
+lockfile. The client is `fetch` plus a retry loop; the types are generated from the same
+source file the API validates requests against, so they cannot drift from the server.
+
+Ships ESM and CommonJS. Works on Node 18+, Bun, Deno, Cloudflare Workers, Vercel Edge —
+anywhere there is a global `fetch`.
+
+## The four methods
+
+```ts
+const pdf = await pdfcraft.render({ html });            // Uint8Array (a Buffer in Node)
+const res = await pdfcraft.renderToUrl({ html });       // { url, expires_at, pages, bytes }
+const job = await pdfcraft.renderAsync({ html, callback_url });
+const sta = await pdfcraft.getRender(job.id);
+const use = await pdfcraft.usage();                     // { used, limit, resets_at }
+```
+
+`render` streams the bytes back on the same connection — one round trip, typically under
+a second. `renderToUrl` uploads to storage and hands you a signed link instead, which is
+what you want when the PDF is large or the caller is a browser. Both take the same input;
+the method you call decides the output, so there is no `output` field to get wrong.
+
+## Page options
+
+Every option the API accepts, fully typed, with autocomplete on the enums.
+
+```ts
+const pdf = await pdfcraft.render({
+  html: invoiceHtml,
+  options: {
+    format: 'A4',                                   // A4 A3 A5 Letter Legal Tabloid
+    landscape: false,
+    margin: { top: '20mm', right: '15mm', bottom: '20mm', left: '15mm' },
+    scale: 1.0,                                     // 0.1 – 2.0
+    printBackground: true,                          // on by default here, unlike a browser
+    pageRanges: '1-5',
+    headerHtml: '<div style="font-size:9px;width:100%;text-align:center">Acme Ltd</div>',
+    footerHtml: '<div style="font-size:9px"><span class="pageNumber"></span></div>',
+    waitFor: { selector: '#ready', networkIdle: true, delayMs: 0 },
+    emulateMedia: 'print',                          // print | screen
+    timeoutMs: 30_000,                              // ceiling 120_000
+  },
+  filename: 'invoice-1042.pdf',
+});
+```
+
+`headerHtml` and `footerHtml` support Chromium's print classes — `pageNumber`, `totalPages`,
+`date`, `title`, `url`. A footer needs a bottom margin big enough to sit in, or it will not
+appear at all.
+
+### Rendering a page behind a login
+
+```ts
+const { url } = await pdfcraft.renderToUrl({
+  url: 'https://app.example.com/reports/42',
+  headers: { Authorization: `Bearer ${token}` },
+  cookies: [{ name: 'session', value: sessionId }],
+});
+```
+
+### Waiting for the page to be ready
+
+A chart that renders from JavaScript is not finished when the DOM loads. Use whichever
+signal your page actually gives you:
+
+```ts
+options: { waitFor: { selector: '#chart-rendered' } }   // best: explicit
+options: { waitFor: { networkIdle: true } }             // good: no requests for 500ms
+options: { waitFor: { delayMs: 1500 } }                 // last resort: a guess
+```
+
+## Errors
+
+Every failure is a `PDFCraftError` with a stable `.code` you can branch on. The codes are
+part of the contract and will not be renamed inside a major version.
+
+```ts
+import { PDFCraftError } from '@pdfcraft-dev/pdf';
+
+try {
+  await pdfcraft.render({ html });
+} catch (error) {
+  if (error instanceof PDFCraftError) {
+    if (error.code === 'quota_exceeded') return showUpgradePrompt();
+    if (error.retryable) return queueForLater();
+    throw error;
+  }
+}
+```
+
+| `.code`            | HTTP | Means                                    | Billed?                                 |
+| ------------------ | ---- | ---------------------------------------- | --------------------------------------- |
+| `invalid_request`  | 400  | Bad option, or both/neither html and url | no                                      |
+| `invalid_api_key`  | 401  | Missing, malformed or revoked key        | no                                      |
+| `payment_required` | 402  | Subscription past due                    | no                                      |
+| `not_found`        | 404  | Unknown render id                        | no                                      |
+| `render_timeout`   | 408  | The page exceeded `timeoutMs`            | no                                      |
+| `render_failed`    | 422  | Navigation failed, selector never showed | **yes** — Chromium ran, your HTML broke |
+| `rate_limited`     | 429  | Too many requests per second             | no                                      |
+| `quota_exceeded`   | 429  | Monthly plan limit reached               | no                                      |
+| `internal_error`   | 500  | Our fault                                | no                                      |
+
+`error.retryable` is true for `network_error`, `429` and `5xx`. Retries on those happen
+automatically — up to three retries with exponential backoff, honouring `Retry-After`. Other
+`4xx` are never retried, because they fail identically however often you ask.
+
+## Idempotency
+
+Pass a key as the second argument. The same key inside 24 hours returns the original
+render instead of billing you twice — which matters when the thing calling you is a
+webhook handler or a job queue that retries.
+
+```ts
+await pdfcraft.render({ html }, `invoice-${invoiceId}`);
+```
+
+## Async renders
+
+For documents that take a while, or when you do not want to hold a connection open.
+
+```ts
+const { id } = await pdfcraft.renderAsync({
+  html,
+  callback_url: 'https://example.com/hooks/pdf',
+});
+
+// later, if you would rather poll than receive
+const { status, url } = await pdfcraft.getRender(id);
+```
+
+The callback is a POST with an `x-signature` header: HMAC-SHA256 of the **raw** request
+body, hex-encoded, keyed with your webhook secret from the dashboard. Verify it before
+trusting the payload.
+
+```ts
+import { createHmac, timingSafeEqual } from 'node:crypto';
+
+const expected = createHmac('sha256', process.env.PDFCRAFT_WEBHOOK_SECRET!)
+  .update(rawBody) // the raw bytes, not the parsed object
+  .digest('hex');
+
+const given = Buffer.from(req.headers['x-signature'] as string);
+const ok = given.length === expected.length && timingSafeEqual(Buffer.from(expected), given);
+```
+
+## Client options
+
+```ts
+new Renderer(apiKey, {
+  baseUrl: 'https://api.pdfcraft.dev', // point at a test double in your test suite
+  maxRetries: 3,
+  timeoutMs: 130_000,                  // just past the API's own 120s ceiling
+  fetch: myInstrumentedFetch,          // inject your own for logging or mocking
+});
+```
+
+Testing against a fake is the reason `fetch` is injectable — you should not need network
+access to run your unit tests.
+
+## Links
+
+- **Docs and live playground** — <https://pdfcraft.dev>
+- **Error reference** — <https://pdfcraft.dev/errors>
+- **Pricing** — <https://pdfcraft.dev/pricing>
+- **Status and support** — <mailto:support@pdfcraft.dev>
+
+## Contributing
+
+This repository is generated from the PDFCraft monorepo, where the client and the API share
+one source of truth for option types and error codes. That means **pull requests here get
+overwritten** on the next release.
+
+Bug reports and API feedback are very welcome as issues — that is what this repo is for.
+
+## License
+
+MIT © Gaurav Singh. See [LICENSE](./LICENSE).

package/dist/cjs/client.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Renderer = void 0;
+const errors_js_1 = require("./errors.js");
+const DEFAULTS = {
+    baseUrl: 'https://api.pdfcraft.dev',
+    maxRetries: 3,
+    timeoutMs: 130_000,
+};
+class Renderer {
+    apiKey;
+    baseUrl;
+    maxRetries;
+    timeoutMs;
+    doFetch;
+    constructor(apiKey, options = {}) {
+        if (!apiKey)
+            throw new errors_js_1.PDFCraftError('invalid_api_key', 'An API key is required.', 401);
+        this.apiKey = apiKey;
+        this.baseUrl = (options.baseUrl ?? DEFAULTS.baseUrl).replace(/\/+$/, '');
+        this.maxRetries = options.maxRetries ?? DEFAULTS.maxRetries;
+        this.timeoutMs = options.timeoutMs ?? DEFAULTS.timeoutMs;
+        this.doFetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+    }
+    /** The PDF bytes. In Node this is a Buffer, which is a Uint8Array. */
+    async render(input, idempotencyKey) {
+        const response = await this.send('/v1/render', { ...input, output: 'binary' }, idempotencyKey);
+        const bytes = new Uint8Array(await response.arrayBuffer());
+        return typeof Buffer === 'undefined' ? bytes : Buffer.from(bytes);
+    }
+    /** Uploads the PDF and returns a signed link instead of the bytes. */
+    async renderToUrl(input, idempotencyKey) {
+        const response = await this.send('/v1/render', { ...input, output: 'url' }, idempotencyKey);
+        return (await response.json());
+    }
+    /** Queues the render and calls back when it settles. */
+    async renderAsync(input, idempotencyKey) {
+        const response = await this.send('/v1/render/async', input, idempotencyKey);
+        return (await response.json());
+    }
+    async getRender(id) {
+        const response = await this.request(`/v1/renders/${encodeURIComponent(id)}`, { method: 'GET' });
+        return (await response.json());
+    }
+    async usage() {
+        const response = await this.request('/v1/usage', { method: 'GET' });
+        return (await response.json());
+    }
+    send(path, body, idempotencyKey) {
+        return this.request(path, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                ...(idempotencyKey ? { 'idempotency-key': idempotencyKey } : {}),
+            },
+            body: JSON.stringify(body),
+        });
+    }
+    async request(path, init) {
+        let lastError = null;
+        for (let attempt = 0; attempt <= this.maxRetries; attempt += 1) {
+            let response;
+            try {
+                response = await this.doFetch(`${this.baseUrl}${path}`, {
+                    ...init,
+                    headers: {
+                        authorization: `Bearer ${this.apiKey}`,
+                        'user-agent': 'pdfcraft-sdk-js/1.0.0',
+                        ...init.headers,
+                    },
+                    signal: AbortSignal.timeout(this.timeoutMs),
+                });
+            }
+            catch (cause) {
+                lastError = new errors_js_1.PDFCraftError('network_error', `Could not reach PDFCraft: ${cause}`, 0);
+                if (attempt === this.maxRetries)
+                    throw lastError;
+                await sleep(backoffMs(attempt));
+                continue;
+            }
+            if (response.ok)
+                return response;
+            const error = (0, errors_js_1.toError)(response.status, await response.text());
+            // 4xx other than 429 will fail identically no matter how many times we ask.
+            if (!error.retryable || attempt === this.maxRetries)
+                throw error;
+            lastError = error;
+            await sleep(retryAfterMs(response) ?? backoffMs(attempt));
+        }
+        throw lastError ?? new errors_js_1.PDFCraftError('internal_error', 'Request failed.', 500);
+    }
+}
+exports.Renderer = Renderer;
+function backoffMs(attempt) {
+    return Math.round(500 * 2 ** attempt * (0.75 + Math.random() * 0.5));
+}
+function retryAfterMs(response) {
+    const header = response.headers.get('retry-after');
+    if (!header)
+        return null;
+    const seconds = Number(header);
+    return Number.isFinite(seconds) ? Math.max(0, seconds) * 1000 : null;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=client.js.map

package/dist/cjs/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"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","sourcesContent":["// packages/sdk/src/client.ts\nimport type {\n  AsyncRenderAccepted,\n  AsyncRenderRequest,\n  RenderRequest,\n  RenderStatusResponse,\n  RenderUrlResponse,\n  UsageResponse,\n} from './contract/index.js';\nimport { PDFCraftError, toError } from './errors.js';\n\nexport interface RendererOptions {\n  /** Override for testing or a self-hosted gateway. */\n  baseUrl?: string;\n  /** Retries on 429 and 5xx only. Default 3. */\n  maxRetries?: number;\n  /** Per-request timeout in milliseconds. Default 130000, just past the API's own ceiling. */\n  timeoutMs?: number;\n  fetch?: typeof globalThis.fetch;\n}\n\nconst DEFAULTS = {\n  baseUrl: 'https://api.pdfcraft.dev',\n  maxRetries: 3,\n  timeoutMs: 130_000,\n};\n\n/**\n * The method you call decides the output mode, so passing `output` yourself\n * could only ever contradict it. Excluded from the type rather than ignored at\n * runtime: `render({ output: 'url' })` returning bytes is the kind of silent\n * surprise that costs someone an afternoon.\n */\nexport type RenderInput = Omit<RenderRequest, 'output'>;\nexport type AsyncRenderInput = Omit<AsyncRenderRequest, 'output'>;\n\nexport class Renderer {\n  private readonly apiKey: string;\n  private readonly baseUrl: string;\n  private readonly maxRetries: number;\n  private readonly timeoutMs: number;\n  private readonly doFetch: typeof globalThis.fetch;\n\n  constructor(apiKey: string, options: RendererOptions = {}) {\n    if (!apiKey) throw new PDFCraftError('invalid_api_key', 'An API key is required.', 401);\n    this.apiKey = apiKey;\n    this.baseUrl = (options.baseUrl ?? DEFAULTS.baseUrl).replace(/\\/+$/, '');\n    this.maxRetries = options.maxRetries ?? DEFAULTS.maxRetries;\n    this.timeoutMs = options.timeoutMs ?? DEFAULTS.timeoutMs;\n    this.doFetch = options.fetch ?? globalThis.fetch.bind(globalThis);\n  }\n\n  /** The PDF bytes. In Node this is a Buffer, which is a Uint8Array. */\n  async render(input: RenderInput, idempotencyKey?: string): Promise<Uint8Array> {\n    const response = await this.send('/v1/render', { ...input, output: 'binary' }, idempotencyKey);\n    const bytes = new Uint8Array(await response.arrayBuffer());\n    return typeof Buffer === 'undefined' ? bytes : Buffer.from(bytes);\n  }\n\n  /** Uploads the PDF and returns a signed link instead of the bytes. */\n  async renderToUrl(input: RenderInput, idempotencyKey?: string): Promise<RenderUrlResponse> {\n    const response = await this.send('/v1/render', { ...input, output: 'url' }, idempotencyKey);\n    return (await response.json()) as RenderUrlResponse;\n  }\n\n  /** Queues the render and calls back when it settles. */\n  async renderAsync(\n    input: AsyncRenderInput,\n    idempotencyKey?: string,\n  ): Promise<AsyncRenderAccepted> {\n    const response = await this.send('/v1/render/async', input, idempotencyKey);\n    return (await response.json()) as AsyncRenderAccepted;\n  }\n\n  async getRender(id: string): Promise<RenderStatusResponse> {\n    const response = await this.request(`/v1/renders/${encodeURIComponent(id)}`, { method: 'GET' });\n    return (await response.json()) as RenderStatusResponse;\n  }\n\n  async usage(): Promise<UsageResponse> {\n    const response = await this.request('/v1/usage', { method: 'GET' });\n    return (await response.json()) as UsageResponse;\n  }\n\n  private send(path: string, body: unknown, idempotencyKey?: string): Promise<Response> {\n    return this.request(path, {\n      method: 'POST',\n      headers: {\n        'content-type': 'application/json',\n        ...(idempotencyKey ? { 'idempotency-key': idempotencyKey } : {}),\n      },\n      body: JSON.stringify(body),\n    });\n  }\n\n  private async request(path: string, init: RequestInit): Promise<Response> {\n    let lastError: PDFCraftError | null = null;\n    for (let attempt = 0; attempt <= this.maxRetries; attempt += 1) {\n      let response: Response;\n      try {\n        response = await this.doFetch(`${this.baseUrl}${path}`, {\n          ...init,\n          headers: {\n            authorization: `Bearer ${this.apiKey}`,\n            'user-agent': 'pdfcraft-sdk-js/1.0.0',\n            ...(init.headers as Record<string, string> | undefined),\n          },\n          signal: AbortSignal.timeout(this.timeoutMs),\n        });\n      } catch (cause) {\n        lastError = new PDFCraftError('network_error', `Could not reach PDFCraft: ${cause}`, 0);\n        if (attempt === this.maxRetries) throw lastError;\n        await sleep(backoffMs(attempt));\n        continue;\n      }\n\n      if (response.ok) return response;\n\n      const error = toError(response.status, await response.text());\n      // 4xx other than 429 will fail identically no matter how many times we ask.\n      if (!error.retryable || attempt === this.maxRetries) throw error;\n      lastError = error;\n      await sleep(retryAfterMs(response) ?? backoffMs(attempt));\n    }\n    throw lastError ?? new PDFCraftError('internal_error', 'Request failed.', 500);\n  }\n}\n\nfunction backoffMs(attempt: number): number {\n  return Math.round(500 * 2 ** attempt * (0.75 + Math.random() * 0.5));\n}\n\nfunction retryAfterMs(response: Response): number | null {\n  const header = response.headers.get('retry-after');\n  if (!header) return null;\n  const seconds = Number(header);\n  return Number.isFinite(seconds) ? Math.max(0, seconds) * 1000 : null;\n}\n\nfunction sleep(ms: number): Promise<void> {\n  return new Promise((resolve) => setTimeout(resolve, ms));\n}\n"]}

package/dist/cjs/contract/errors.js

@@ -0,0 +1,91 @@
+"use strict";
+// packages/contract/src/errors.ts
+//
+// Every error the API can return. The exception filter maps domain errors onto
+// this table, the SDK exposes `.code` from it, and the docs error reference is
+// generated from it — each anchor matches the docs_url the API hands back.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ERROR_SPEC_BY_CODE = exports.ERROR_TABLE = exports.ERROR_CODES = exports.DOCS_ORIGIN = void 0;
+exports.docsUrlFor = docsUrlFor;
+exports.DOCS_ORIGIN = 'https://pdfcraft.dev';
+exports.ERROR_CODES = [
+    'invalid_request',
+    'invalid_api_key',
+    'payment_required',
+    'not_found',
+    'render_timeout',
+    'render_failed',
+    'rate_limited',
+    'quota_exceeded',
+    'internal_error',
+];
+exports.ERROR_TABLE = [
+    {
+        code: 'invalid_request',
+        status: 400,
+        billable: false,
+        when: 'Both html and url were supplied, or neither, or an option is out of range.',
+        whatToDo: 'Read the message — it names the offending field. Send exactly one of html or url.',
+    },
+    {
+        code: 'invalid_api_key',
+        status: 401,
+        billable: false,
+        when: 'The Authorization header is missing, malformed, or the key has been revoked.',
+        whatToDo: 'Send "Authorization: Bearer sk_live_…". Issue a fresh key from the dashboard.',
+    },
+    {
+        code: 'payment_required',
+        status: 402,
+        billable: false,
+        when: 'The last subscription payment failed, so the account is past_due.',
+        whatToDo: 'Update the card on the billing portal. Rendering resumes the moment payment clears.',
+    },
+    {
+        code: 'not_found',
+        status: 404,
+        billable: false,
+        when: 'No render with that id belongs to your account.',
+        whatToDo: 'Check the id. Ids from another account also return 404, never 403, so they cannot be probed.',
+    },
+    {
+        code: 'render_timeout',
+        status: 408,
+        billable: false,
+        when: 'The page did not finish within timeoutMs and was force-closed.',
+        whatToDo: 'Raise timeoutMs (max 120000), or relax waitFor — networkIdle on a page with a long-poll never settles.',
+    },
+    {
+        code: 'render_failed',
+        status: 422,
+        billable: true,
+        when: 'Chromium ran but the page threw, navigation failed, or waitFor.selector never appeared.',
+        whatToDo: 'Load the same HTML in a browser. This one is billable because the browser did the work.',
+    },
+    {
+        code: 'rate_limited',
+        status: 429,
+        billable: false,
+        when: 'More requests per second than the plan allows.',
+        whatToDo: 'Honour the Retry-After header and back off. Paid plans allow 20 req/s.',
+    },
+    {
+        code: 'quota_exceeded',
+        status: 429,
+        billable: false,
+        when: 'A free-plan account has used all 100 renders in the current period.',
+        whatToDo: 'Upgrade, or wait for resets_at from GET /v1/usage. Paid plans never hard-stop; they accrue overage.',
+    },
+    {
+        code: 'internal_error',
+        status: 500,
+        billable: false,
+        when: 'Something on our side broke.',
+        whatToDo: 'Retry with backoff. Never billed. If it persists, send us the render id.',
+    },
+];
+exports.ERROR_SPEC_BY_CODE = Object.fromEntries(exports.ERROR_TABLE.map((spec) => [spec.code, spec]));
+function docsUrlFor(code) {
+    return `${exports.DOCS_ORIGIN}/errors#${code}`;
+}
+//# sourceMappingURL=errors.js.map

package/dist/cjs/contract/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../src/contract/errors.ts"],"names":[],"mappings":";AAAA,kCAAkC;AAClC,EAAE;AACF,+EAA+E;AAC/E,+EAA+E;AAC/E,2EAA2E;;;AAqG3E,gCAEC;AArGY,QAAA,WAAW,GAAG,sBAAsB,CAAC;AAErC,QAAA,WAAW,GAAG;IACzB,iBAAiB;IACjB,iBAAiB;IACjB,kBAAkB;IAClB,WAAW;IACX,gBAAgB;IAChB,eAAe;IACf,cAAc;IACd,gBAAgB;IAChB,gBAAgB;CACR,CAAC;AAaE,QAAA,WAAW,GAAG;IACzB;QACE,IAAI,EAAE,iBAAiB;QACvB,MAAM,EAAE,GAAG;QACX,QAAQ,EAAE,KAAK;QACf,IAAI,EAAE,4EAA4E;QAClF,QAAQ,EAAE,mFAAmF;KAC9F;IACD;QACE,IAAI,EAAE,iBAAiB;QACvB,MAAM,EAAE,GAAG;QACX,QAAQ,EAAE,KAAK;QACf,IAAI,EAAE,8EAA8E;QACpF,QAAQ,EAAE,+EAA+E;KAC1F;IACD;QACE,IAAI,EAAE,kBAAkB;QACxB,MAAM,EAAE,GAAG;QACX,QAAQ,EAAE,KAAK;QACf,IAAI,EAAE,mEAAmE;QACzE,QAAQ,EAAE,qFAAqF;KAChG;IACD;QACE,IAAI,EAAE,WAAW;QACjB,MAAM,EAAE,GAAG;QACX,QAAQ,EAAE,KAAK;QACf,IAAI,EAAE,iDAAiD;QACvD,QAAQ,EACN,8FAA8F;KACjG;IACD;QACE,IAAI,EAAE,gBAAgB;QACtB,MAAM,EAAE,GAAG;QACX,QAAQ,EAAE,KAAK;QACf,IAAI,EAAE,gEAAgE;QACtE,QAAQ,EACN,wGAAwG;KAC3G;IACD;QACE,IAAI,EAAE,eAAe;QACrB,MAAM,EAAE,GAAG;QACX,QAAQ,EAAE,IAAI;QACd,IAAI,EAAE,yFAAyF;QAC/F,QAAQ,EACN,yFAAyF;KAC5F;IACD;QACE,IAAI,EAAE,cAAc;QACpB,MAAM,EAAE,GAAG;QACX,QAAQ,EAAE,KAAK;QACf,IAAI,EAAE,gDAAgD;QACtD,QAAQ,EAAE,wEAAwE;KACnF;IACD;QACE,IAAI,EAAE,gBAAgB;QACtB,MAAM,EAAE,GAAG;QACX,QAAQ,EAAE,KAAK;QACf,IAAI,EAAE,qEAAqE;QAC3E,QAAQ,EACN,qGAAqG;KACxG;IACD;QACE,IAAI,EAAE,gBAAgB;QACtB,MAAM,EAAE,GAAG;QACX,QAAQ,EAAE,KAAK;QACf,IAAI,EAAE,8BAA8B;QACpC,QAAQ,EAAE,0EAA0E;KACrF;CACsC,CAAC;AAE7B,QAAA,kBAAkB,GAA2C,MAAM,CAAC,WAAW,CAC1F,mBAAW,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CACb,CAAC;AAElC,SAAgB,UAAU,CAAC,IAAe;IACxC,OAAO,GAAG,mBAAW,WAAW,IAAI,EAAE,CAAC;AACzC,CAAC","sourcesContent":["// packages/contract/src/errors.ts\n//\n// Every error the API can return. The exception filter maps domain errors onto\n// this table, the SDK exposes `.code` from it, and the docs error reference is\n// generated from it — each anchor matches the docs_url the API hands back.\n\nexport const DOCS_ORIGIN = 'https://pdfcraft.dev';\n\nexport const ERROR_CODES = [\n  'invalid_request',\n  'invalid_api_key',\n  'payment_required',\n  'not_found',\n  'render_timeout',\n  'render_failed',\n  'rate_limited',\n  'quota_exceeded',\n  'internal_error',\n] as const;\n\nexport type ErrorCode = (typeof ERROR_CODES)[number];\n\nexport interface ErrorSpec {\n  readonly code: ErrorCode;\n  readonly status: number;\n  /** True when Chromium actually ran, which is what makes a render billable. */\n  readonly billable: boolean;\n  readonly when: string;\n  readonly whatToDo: string;\n}\n\nexport const ERROR_TABLE = [\n  {\n    code: 'invalid_request',\n    status: 400,\n    billable: false,\n    when: 'Both html and url were supplied, or neither, or an option is out of range.',\n    whatToDo: 'Read the message — it names the offending field. Send exactly one of html or url.',\n  },\n  {\n    code: 'invalid_api_key',\n    status: 401,\n    billable: false,\n    when: 'The Authorization header is missing, malformed, or the key has been revoked.',\n    whatToDo: 'Send \"Authorization: Bearer sk_live_…\". Issue a fresh key from the dashboard.',\n  },\n  {\n    code: 'payment_required',\n    status: 402,\n    billable: false,\n    when: 'The last subscription payment failed, so the account is past_due.',\n    whatToDo: 'Update the card on the billing portal. Rendering resumes the moment payment clears.',\n  },\n  {\n    code: 'not_found',\n    status: 404,\n    billable: false,\n    when: 'No render with that id belongs to your account.',\n    whatToDo:\n      'Check the id. Ids from another account also return 404, never 403, so they cannot be probed.',\n  },\n  {\n    code: 'render_timeout',\n    status: 408,\n    billable: false,\n    when: 'The page did not finish within timeoutMs and was force-closed.',\n    whatToDo:\n      'Raise timeoutMs (max 120000), or relax waitFor — networkIdle on a page with a long-poll never settles.',\n  },\n  {\n    code: 'render_failed',\n    status: 422,\n    billable: true,\n    when: 'Chromium ran but the page threw, navigation failed, or waitFor.selector never appeared.',\n    whatToDo:\n      'Load the same HTML in a browser. This one is billable because the browser did the work.',\n  },\n  {\n    code: 'rate_limited',\n    status: 429,\n    billable: false,\n    when: 'More requests per second than the plan allows.',\n    whatToDo: 'Honour the Retry-After header and back off. Paid plans allow 20 req/s.',\n  },\n  {\n    code: 'quota_exceeded',\n    status: 429,\n    billable: false,\n    when: 'A free-plan account has used all 100 renders in the current period.',\n    whatToDo:\n      'Upgrade, or wait for resets_at from GET /v1/usage. Paid plans never hard-stop; they accrue overage.',\n  },\n  {\n    code: 'internal_error',\n    status: 500,\n    billable: false,\n    when: 'Something on our side broke.',\n    whatToDo: 'Retry with backoff. Never billed. If it persists, send us the render id.',\n  },\n] as const satisfies readonly ErrorSpec[];\n\nexport const ERROR_SPEC_BY_CODE: Readonly<Record<ErrorCode, ErrorSpec>> = Object.fromEntries(\n  ERROR_TABLE.map((spec) => [spec.code, spec]),\n) as Record<ErrorCode, ErrorSpec>;\n\nexport function docsUrlFor(code: ErrorCode): string {\n  return `${DOCS_ORIGIN}/errors#${code}`;\n}\n\nexport interface ApiErrorBody {\n  error: {\n    code: ErrorCode;\n    message: string;\n    docs_url: string;\n  };\n}\n"]}

package/dist/cjs/contract/index.js

@@ -0,0 +1,23 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// GENERATED FILE — do not edit.
+// The same option, plan and error definitions the PDFCraft API validates
+// requests against. Regenerated by packages/contract/scripts/sync-sdk.mjs.
+__exportStar(require("./render-options.js"), exports);
+__exportStar(require("./request.js"), exports);
+__exportStar(require("./errors.js"), exports);
+//# sourceMappingURL=index.js.map

package/dist/cjs/contract/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/contract/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,gCAAgC;AAChC,yEAAyE;AACzE,2EAA2E;AAC3E,sDAAoC;AACpC,+CAA6B;AAC7B,8CAA4B","sourcesContent":["// GENERATED FILE — do not edit.\n// The same option, plan and error definitions the PDFCraft API validates\n// requests against. Regenerated by packages/contract/scripts/sync-sdk.mjs.\nexport * from './render-options.js';\nexport * from './request.js';\nexport * from './errors.js';\n"]}

package/dist/cjs/contract/render-options.js

@@ -0,0 +1,111 @@
+"use strict";
+// packages/contract/src/render-options.ts
+//
+// The one description of the render option surface. The API builds its validator
+// from RENDER_OPTIONS_SPEC and the docs site builds its reference table from the
+// same constant, so the two cannot drift. The SDK vendors this file verbatim at
+// build time (see packages/sdk/scripts/vendor-contract.mjs) to stay dependency-free.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SPEC_MATCHES_TYPES = exports.RENDER_OPTIONS_SPEC = exports.MAX_HTML_BYTES = exports.DEFAULT_TIMEOUT_MS = exports.MAX_TIMEOUT_MS = exports.EMULATE_MEDIA = exports.PAGE_FORMATS = void 0;
+exports.PAGE_FORMATS = ['A4', 'A3', 'A5', 'Letter', 'Legal', 'Tabloid'];
+exports.EMULATE_MEDIA = ['print', 'screen'];
+exports.MAX_TIMEOUT_MS = 120_000;
+exports.DEFAULT_TIMEOUT_MS = 30_000;
+exports.MAX_HTML_BYTES = 5_000_000;
+exports.RENDER_OPTIONS_SPEC = [
+    {
+        name: 'format',
+        type: { kind: 'enum', values: exports.PAGE_FORMATS },
+        default: 'A4',
+        description: 'Paper size. Ignored if the page CSS declares its own @page size.',
+    },
+    {
+        name: 'landscape',
+        type: { kind: 'boolean' },
+        default: false,
+        description: 'Rotate the paper to landscape orientation.',
+    },
+    {
+        name: 'margin',
+        type: {
+            kind: 'object',
+            fields: [
+                { name: 'top', type: { kind: 'css-length' }, description: 'e.g. "20mm", "1in", "72px".' },
+                { name: 'right', type: { kind: 'css-length' }, description: 'e.g. "15mm".' },
+                { name: 'bottom', type: { kind: 'css-length' }, description: 'e.g. "20mm".' },
+                { name: 'left', type: { kind: 'css-length' }, description: 'e.g. "15mm".' },
+            ],
+        },
+        description: 'Page margins. Any side may be omitted; omitted sides default to 0.',
+    },
+    {
+        name: 'scale',
+        type: { kind: 'number', min: 0.1, max: 2 },
+        default: 1,
+        description: 'Rendering scale factor.',
+    },
+    {
+        name: 'printBackground',
+        type: { kind: 'boolean' },
+        default: true,
+        description: 'Print background colours and images. Off by default in browsers; on by default here.',
+    },
+    {
+        name: 'pageRanges',
+        type: { kind: 'string', maxLength: 100, pattern: '^[0-9,\\-\\s]+$' },
+        description: 'Subset of pages to keep, e.g. "1-5" or "1,4,7-9". Empty means all pages.',
+    },
+    {
+        name: 'headerHtml',
+        type: { kind: 'string', maxLength: 50_000 },
+        description: 'HTML for the running header. Supports Chromium print classes: date, title, url, pageNumber, totalPages. Needs a top margin to be visible.',
+    },
+    {
+        name: 'footerHtml',
+        type: { kind: 'string', maxLength: 50_000 },
+        description: 'HTML for the running footer. Same classes as headerHtml; needs a bottom margin.',
+    },
+    {
+        name: 'waitFor',
+        type: {
+            kind: 'object',
+            fields: [
+                {
+                    name: 'selector',
+                    type: { kind: 'string', maxLength: 500 },
+                    description: 'Wait until this CSS selector is attached to the DOM.',
+                },
+                {
+                    name: 'networkIdle',
+                    type: { kind: 'boolean' },
+                    default: false,
+                    description: 'Wait until there have been no network connections for 500 ms.',
+                },
+                {
+                    name: 'delayMs',
+                    type: { kind: 'integer', min: 0, max: 30_000 },
+                    default: 0,
+                    description: 'Fixed pause after the other wait conditions are satisfied.',
+                },
+            ],
+        },
+        description: 'Conditions to satisfy before the PDF is taken. All of them apply, in order.',
+    },
+    {
+        name: 'emulateMedia',
+        type: { kind: 'enum', values: exports.EMULATE_MEDIA },
+        default: 'print',
+        description: 'Which CSS media type the page sees.',
+    },
+    {
+        name: 'timeoutMs',
+        type: { kind: 'integer', min: 1000, max: exports.MAX_TIMEOUT_MS },
+        default: exports.DEFAULT_TIMEOUT_MS,
+        description: 'Hard ceiling on the whole render. Exceeding it returns 408 render_timeout.',
+    },
+];
+// Compile-time drift guard: this assignment stops type-checking the moment
+// RENDER_OPTIONS_SPEC and RenderOptions describe different sets of options.
+const driftCheck = true;
+exports.SPEC_MATCHES_TYPES = driftCheck;
+//# sourceMappingURL=render-options.js.map

package/dist/cjs/contract/render-options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-options.js","sourceRoot":"","sources":["../../../src/contract/render-options.ts"],"names":[],"mappings":"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","sourcesContent":["// packages/contract/src/render-options.ts\n//\n// The one description of the render option surface. The API builds its validator\n// from RENDER_OPTIONS_SPEC and the docs site builds its reference table from the\n// same constant, so the two cannot drift. The SDK vendors this file verbatim at\n// build time (see packages/sdk/scripts/vendor-contract.mjs) to stay dependency-free.\n\nexport type OptionKind =\n  | { readonly kind: 'enum'; readonly values: readonly string[] }\n  | { readonly kind: 'boolean' }\n  | { readonly kind: 'number'; readonly min: number; readonly max: number }\n  | { readonly kind: 'integer'; readonly min: number; readonly max: number }\n  | { readonly kind: 'string'; readonly maxLength: number; readonly pattern?: string }\n  | { readonly kind: 'css-length' }\n  | { readonly kind: 'object'; readonly fields: readonly OptionField[] };\n\nexport interface OptionField {\n  readonly name: string;\n  readonly type: OptionKind;\n  readonly default?: string | number | boolean;\n  readonly description: string;\n}\n\nexport const PAGE_FORMATS = ['A4', 'A3', 'A5', 'Letter', 'Legal', 'Tabloid'] as const;\nexport const EMULATE_MEDIA = ['print', 'screen'] as const;\n\nexport const MAX_TIMEOUT_MS = 120_000;\nexport const DEFAULT_TIMEOUT_MS = 30_000;\nexport const MAX_HTML_BYTES = 5_000_000;\n\nexport const RENDER_OPTIONS_SPEC = [\n  {\n    name: 'format',\n    type: { kind: 'enum', values: PAGE_FORMATS },\n    default: 'A4',\n    description: 'Paper size. Ignored if the page CSS declares its own @page size.',\n  },\n  {\n    name: 'landscape',\n    type: { kind: 'boolean' },\n    default: false,\n    description: 'Rotate the paper to landscape orientation.',\n  },\n  {\n    name: 'margin',\n    type: {\n      kind: 'object',\n      fields: [\n        { name: 'top', type: { kind: 'css-length' }, description: 'e.g. \"20mm\", \"1in\", \"72px\".' },\n        { name: 'right', type: { kind: 'css-length' }, description: 'e.g. \"15mm\".' },\n        { name: 'bottom', type: { kind: 'css-length' }, description: 'e.g. \"20mm\".' },\n        { name: 'left', type: { kind: 'css-length' }, description: 'e.g. \"15mm\".' },\n      ],\n    },\n    description: 'Page margins. Any side may be omitted; omitted sides default to 0.',\n  },\n  {\n    name: 'scale',\n    type: { kind: 'number', min: 0.1, max: 2 },\n    default: 1,\n    description: 'Rendering scale factor.',\n  },\n  {\n    name: 'printBackground',\n    type: { kind: 'boolean' },\n    default: true,\n    description:\n      'Print background colours and images. Off by default in browsers; on by default here.',\n  },\n  {\n    name: 'pageRanges',\n    type: { kind: 'string', maxLength: 100, pattern: '^[0-9,\\\\-\\\\s]+$' },\n    description: 'Subset of pages to keep, e.g. \"1-5\" or \"1,4,7-9\". Empty means all pages.',\n  },\n  {\n    name: 'headerHtml',\n    type: { kind: 'string', maxLength: 50_000 },\n    description:\n      'HTML for the running header. Supports Chromium print classes: date, title, url, pageNumber, totalPages. Needs a top margin to be visible.',\n  },\n  {\n    name: 'footerHtml',\n    type: { kind: 'string', maxLength: 50_000 },\n    description: 'HTML for the running footer. Same classes as headerHtml; needs a bottom margin.',\n  },\n  {\n    name: 'waitFor',\n    type: {\n      kind: 'object',\n      fields: [\n        {\n          name: 'selector',\n          type: { kind: 'string', maxLength: 500 },\n          description: 'Wait until this CSS selector is attached to the DOM.',\n        },\n        {\n          name: 'networkIdle',\n          type: { kind: 'boolean' },\n          default: false,\n          description: 'Wait until there have been no network connections for 500 ms.',\n        },\n        {\n          name: 'delayMs',\n          type: { kind: 'integer', min: 0, max: 30_000 },\n          default: 0,\n          description: 'Fixed pause after the other wait conditions are satisfied.',\n        },\n      ],\n    },\n    description: 'Conditions to satisfy before the PDF is taken. All of them apply, in order.',\n  },\n  {\n    name: 'emulateMedia',\n    type: { kind: 'enum', values: EMULATE_MEDIA },\n    default: 'print',\n    description: 'Which CSS media type the page sees.',\n  },\n  {\n    name: 'timeoutMs',\n    type: { kind: 'integer', min: 1000, max: MAX_TIMEOUT_MS },\n    default: DEFAULT_TIMEOUT_MS,\n    description: 'Hard ceiling on the whole render. Exceeding it returns 408 render_timeout.',\n  },\n] as const satisfies readonly OptionField[];\n\nexport interface Margin {\n  top?: string;\n  right?: string;\n  bottom?: string;\n  left?: string;\n}\n\nexport interface WaitFor {\n  selector?: string;\n  networkIdle?: boolean;\n  delayMs?: number;\n}\n\nexport interface RenderOptions {\n  format?: (typeof PAGE_FORMATS)[number];\n  landscape?: boolean;\n  margin?: Margin;\n  scale?: number;\n  printBackground?: boolean;\n  pageRanges?: string;\n  headerHtml?: string;\n  footerHtml?: string;\n  waitFor?: WaitFor;\n  emulateMedia?: (typeof EMULATE_MEDIA)[number];\n  timeoutMs?: number;\n}\n\ntype SpecFieldName = (typeof RENDER_OPTIONS_SPEC)[number]['name'];\n\n// Compile-time drift guard: this assignment stops type-checking the moment\n// RENDER_OPTIONS_SPEC and RenderOptions describe different sets of options.\nconst driftCheck: [Exclude<keyof RenderOptions, SpecFieldName>] extends [never]\n  ? [Exclude<SpecFieldName, keyof RenderOptions>] extends [never]\n    ? true\n    : never\n  : never = true;\n\nexport const SPEC_MATCHES_TYPES: boolean = driftCheck;\n"]}