@pageweaver/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PageWeaver
+
+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,205 @@
+# @pageweaver/sdk
+
+Official TypeScript SDK for the [PageWeaver](https://pageweaver.io) PDF generation API. Create PDFs from versioned templates and typed JSON payloads (or from inline HTML), then poll or receive a webhook for the result.
+
+Works in any server-side JavaScript runtime with a global `fetch` (Node 18+, Bun, Deno, edge runtimes). Fully typed, zero runtime dependencies.
+
+## Install
+
+```bash
+npm install @pageweaver/sdk
+```
+
+## Quickstart
+
+```ts
+import { PageWeaver } from "@pageweaver/sdk";
+
+const pw = new PageWeaver({ apiKey: process.env.PAGEWEAVER_API_KEY! });
+
+// Create a document and wait for it to finish rendering.
+const doc = await pw.documents.createAndWait({
+  templateId: "tmpl_invoice",
+  payload: { invoiceNumber: "1042", total: 4200 },
+});
+
+// Download the finished PDF.
+const pdf = await pw.documents.download(doc.id);
+await fs.writeFile("invoice.pdf", pdf);
+```
+
+`createAndWait` submits the render, polls until it is done, and resolves with the finished document. If you would rather manage polling yourself, use `create` then `get` (or `waitFor`).
+
+## Configuration
+
+```ts
+const pw = new PageWeaver({
+  apiKey: "pk_live_...",              // required
+  baseUrl: "https://api.pageweaver.io", // default; use http://localhost:4000 for local dev
+  timeoutMs: 30000,                   // per-request timeout
+});
+```
+
+Your API key comes from the portal (`pk_test_...` for development, `pk_live_...` for production).
+
+## Creating documents
+
+### From a template
+
+```ts
+const doc = await pw.documents.create({
+  templateId: "tmpl_invoice",
+  payload: { invoiceNumber: "1042", lineItems: [{ name: "Widget", qty: 3 }] },
+  version: 4, // optional: pin a published version so future edits never change this output
+});
+// { id, status: "queued", version }
+```
+
+The payload is validated against the template's JSON Schema before the render is queued. A validation failure throws a `PageWeaverApiError` (status 400) whose `errors` field lists what was wrong.
+
+### From inline HTML
+
+```ts
+const doc = await pw.documents.create({
+  html: "<h1>Hello {{ name }}</h1>",
+  css: "h1 { color: #4f46e5 }",
+  payload: { name: "Ada" },
+});
+```
+
+Inline HTML may use Liquid tokens and reference your uploaded image assets by name. External images, stylesheets, and JavaScript are rejected.
+
+### Per-render options
+
+Every document property is overridable per request under the single `options` key, layered on the template's saved settings for that render only:
+
+```ts
+await pw.documents.create({
+  templateId: "tmpl_invoice",
+  payload,
+  options: {
+    page: { size: "A4", orientation: "portrait", margin: "18mm" },
+    metadata: { title: "Invoice #1042", author: "Acme Inc." },
+    footer: { center: "Page {{@page}} of {{@pages}}" },
+    watermark: { text: "DRAFT", opacity: 0.3 },
+    localization: { locale: "de-DE", timeZone: "Europe/Berlin", currency: "EUR" },
+  },
+});
+```
+
+## Polling
+
+```ts
+const created = await pw.documents.create({ templateId: "t", payload });
+
+// Block until terminal (done or failed), with backoff and a timeout.
+const done = await pw.documents.waitFor(created.id, {
+  intervalMs: 1000,
+  timeoutMs: 60000,
+});
+```
+
+`waitFor` throws `PageWeaverDocumentFailedError` if the document fails. Pass `throwOnFailure: false` to receive the failed document instead.
+
+## Downloading
+
+```ts
+// Unprotected document: the signed URL is resolved and fetched for you.
+const pdf = await pw.documents.download(doc.id);
+
+// Download-protected document: supply the download password.
+const pdf = await pw.documents.download(doc.id, { password: "the-download-password" });
+```
+
+`download` returns a `Uint8Array`. For a protected document created with `options.security.download`, the response to `create`/`get` includes the generated password in `download.password` (visible only to you, the owner).
+
+## Listing history
+
+```ts
+const page = await pw.documents.list({ status: "done", limit: 50 });
+// { items, nextCursor }
+
+// Or iterate every page automatically:
+for await (const item of pw.documents.listAll({ status: "failed" })) {
+  console.log(item.id, item.error);
+}
+```
+
+## Regenerate
+
+```ts
+const replay = await pw.documents.regenerate(doc.id);
+```
+
+Faithfully replays a prior document with the same version, payload, and options. Returns a new document id.
+
+## Discovery (read only)
+
+```ts
+await pw.templates.list();
+await pw.templates.get("tmpl_invoice");
+await pw.templates.versions("tmpl_invoice");
+
+await pw.schemas.list();
+await pw.schemas.get("schema_id", { version: 2 });
+
+await pw.usage.get(); // page consumption vs. your plan quota this period
+```
+
+## Webhooks
+
+Set `callbackUrl` on a create call (or a default in the portal) to receive a signed POST when a document reaches a terminal state. Verify the signature before trusting the payload:
+
+```ts
+import { verifyWebhook, isDocumentEvent } from "@pageweaver/sdk";
+
+// Express example. Give the verifier the RAW request body bytes.
+app.post("/webhooks/pageweaver", express.raw({ type: "application/json" }), (req, res) => {
+  try {
+    const event = verifyWebhook({
+      secret: process.env.PAGEWEAVER_WEBHOOK_SECRET!,
+      body: req.body.toString("utf8"),
+      signature: req.headers["x-pageweaver-signature"],
+    });
+
+    if (isDocumentEvent(event) && event.status === "done") {
+      console.log("Document ready:", event.documentId, event.url);
+    }
+    res.sendStatus(200);
+  } catch {
+    res.sendStatus(400); // invalid signature
+  }
+});
+```
+
+Always verify against the unparsed body. Re-serializing a parsed object can change the bytes and break the signature.
+
+## Errors
+
+Every error extends `PageWeaverError`:
+
+| Class | Thrown when |
+| --- | --- |
+| `PageWeaverApiError` | The API returned a non-2xx response. Carries `status`, `code`, `errors`, `body`. |
+| `PageWeaverConnectionError` | A network failure, or the request timed out. |
+| `PageWeaverTimeoutError` | `waitFor` exceeded its timeout before the document finished. |
+| `PageWeaverDocumentFailedError` | The document reached the `failed` state while waiting. Carries the `document`. |
+| `PageWeaverWebhookSignatureError` | A webhook signature did not match the body. |
+
+```ts
+import { PageWeaverApiError } from "@pageweaver/sdk";
+
+try {
+  await pw.documents.create({ templateId: "t", payload });
+} catch (err) {
+  if (err instanceof PageWeaverApiError && err.status === 400) {
+    console.error("Validation failed:", err.errors);
+  } else {
+    throw err;
+  }
+}
+```
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,34 @@
+import { type FetchLike } from "./http";
+import { DocumentsResource } from "./documents";
+import { TemplatesResource } from "./templates";
+import { SchemasResource } from "./schemas";
+import { UsageResource } from "./usage";
+export interface PageWeaverOptions {
+    /** Your secret API key: `pk_live_...` in production, `pk_test_...` in development. */
+    apiKey: string;
+    /**
+     * API base URL. Defaults to `https://api.pageweaver.io`. Point it at `http://localhost:4000`
+     * when developing against a local stack.
+     */
+    baseUrl?: string;
+    /** Per-request timeout in milliseconds. Default 30000. */
+    timeoutMs?: number;
+    /** Provide a custom `fetch` (defaults to the global one; requires Node 18+ otherwise). */
+    fetch?: FetchLike;
+}
+/**
+ * The PageWeaver API client.
+ *
+ * ```ts
+ * const pw = new PageWeaver({ apiKey: process.env.PAGEWEAVER_API_KEY! });
+ * const doc = await pw.documents.createAndWait({ templateId: "tmpl_invoice", payload: { total: 42 } });
+ * const pdf = await pw.documents.download(doc.id);
+ * ```
+ */
+export declare class PageWeaver {
+    readonly documents: DocumentsResource;
+    readonly templates: TemplatesResource;
+    readonly schemas: SchemasResource;
+    readonly usage: UsageResource;
+    constructor(options: PageWeaverOptions);
+}

package/dist/client.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PageWeaver = void 0;
+const http_1 = require("./http");
+const documents_1 = require("./documents");
+const templates_1 = require("./templates");
+const schemas_1 = require("./schemas");
+const usage_1 = require("./usage");
+/**
+ * The PageWeaver API client.
+ *
+ * ```ts
+ * const pw = new PageWeaver({ apiKey: process.env.PAGEWEAVER_API_KEY! });
+ * const doc = await pw.documents.createAndWait({ templateId: "tmpl_invoice", payload: { total: 42 } });
+ * const pdf = await pw.documents.download(doc.id);
+ * ```
+ */
+class PageWeaver {
+    documents;
+    templates;
+    schemas;
+    usage;
+    constructor(options) {
+        const http = new http_1.HttpClient(options);
+        this.documents = new documents_1.DocumentsResource(http);
+        this.templates = new templates_1.TemplatesResource(http);
+        this.schemas = new schemas_1.SchemasResource(http);
+        this.usage = new usage_1.UsageResource(http);
+    }
+}
+exports.PageWeaver = PageWeaver;
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":";;;AAAA,iCAAoD;AACpD,2CAAgD;AAChD,2CAAgD;AAChD,uCAA4C;AAC5C,mCAAwC;AAgBxC;;;;;;;;GAQG;AACH,MAAa,UAAU;IACZ,SAAS,CAAoB;IAC7B,SAAS,CAAoB;IAC7B,OAAO,CAAkB;IACzB,KAAK,CAAgB;IAE9B,YAAY,OAA0B;QACpC,MAAM,IAAI,GAAG,IAAI,iBAAU,CAAC,OAAO,CAAC,CAAC;QACrC,IAAI,CAAC,SAAS,GAAG,IAAI,6BAAiB,CAAC,IAAI,CAAC,CAAC;QAC7C,IAAI,CAAC,SAAS,GAAG,IAAI,6BAAiB,CAAC,IAAI,CAAC,CAAC;QAC7C,IAAI,CAAC,OAAO,GAAG,IAAI,yBAAe,CAAC,IAAI,CAAC,CAAC;QACzC,IAAI,CAAC,KAAK,GAAG,IAAI,qBAAa,CAAC,IAAI,CAAC,CAAC;IACvC,CAAC;CACF;AAbD,gCAaC"}

package/dist/documents.d.ts

@@ -0,0 +1,62 @@
+import type { HttpClient } from "./http";
+import type { CreateDocumentParams, CreateDocumentResult, Document, DocumentPage, ListDocumentsParams } from "./types";
+export interface WaitOptions {
+    /** Initial delay between polls, ms. Default 1000. */
+    intervalMs?: number;
+    /** Cap the (backing-off) poll delay, ms. Default 5000. */
+    maxIntervalMs?: number;
+    /** Multiplier applied to the delay after each poll. Default 1.5. */
+    backoff?: number;
+    /** Give up after this long, ms. Default 60000. */
+    timeoutMs?: number;
+    /** Throw {@link PageWeaverDocumentFailedError} if the document fails. Default true. */
+    throwOnFailure?: boolean;
+    /** Abort waiting early. */
+    signal?: AbortSignal;
+}
+export interface DownloadOptions {
+    /** The download password, for a download-protected document. */
+    password?: string;
+    signal?: AbortSignal;
+}
+/** Operations on documents: the core of the API. */
+export declare class DocumentsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Create a document from a template (with a validated payload) or from inline HTML. Returns
+     * `202` immediately with the document id and status "queued". Poll {@link get}, call
+     * {@link waitFor}, or use {@link createAndWait} to block until it is ready.
+     */
+    create(params: CreateDocumentParams, signal?: AbortSignal): Promise<CreateDocumentResult>;
+    /** Fetch the current state of a document. When `status` is "done" it carries a `download` block. */
+    get(id: string, signal?: AbortSignal): Promise<Document>;
+    /** One page of the document history, newest first. Use `nextCursor` to page. */
+    list(params?: ListDocumentsParams, signal?: AbortSignal): Promise<DocumentPage>;
+    /**
+     * Iterate every document across all pages, transparently following the cursor.
+     *
+     * ```ts
+     * for await (const doc of pw.documents.listAll({ status: "failed" })) { ... }
+     * ```
+     */
+    listAll(params?: Omit<ListDocumentsParams, "cursor">, signal?: AbortSignal): AsyncGenerator<DocumentPage["items"][number]>;
+    /**
+     * Faithfully replay a prior document: the same version (or inline source), payload, options, and
+     * download protection. Returns a new document id (`202`); counts as a new render.
+     */
+    regenerate(id: string, signal?: AbortSignal): Promise<CreateDocumentResult>;
+    /**
+     * Poll a document until it reaches a terminal state (or the timeout elapses). Resolves with the
+     * finished {@link Document}. By default it throws {@link PageWeaverDocumentFailedError} on failure;
+     * pass `throwOnFailure: false` to receive the failed document instead.
+     */
+    waitFor(id: string, opts?: WaitOptions): Promise<Document>;
+    /** Convenience: {@link create} then {@link waitFor}. Resolves with the finished document. */
+    createAndWait(params: CreateDocumentParams, opts?: WaitOptions): Promise<Document>;
+    /**
+     * Download the finished PDF bytes. For a download-protected document, pass `{ password }`. For an
+     * unprotected document, the short-lived signed URL is resolved and fetched automatically.
+     */
+    download(id: string, opts?: DownloadOptions): Promise<Uint8Array>;
+}

package/dist/documents.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DocumentsResource = void 0;
+const errors_1 = require("./errors");
+/** Statuses at which a document stops changing. */
+const TERMINAL = new Set(["done", "failed"]);
+/** Operations on documents: the core of the API. */
+class DocumentsResource {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * Create a document from a template (with a validated payload) or from inline HTML. Returns
+     * `202` immediately with the document id and status "queued". Poll {@link get}, call
+     * {@link waitFor}, or use {@link createAndWait} to block until it is ready.
+     */
+    create(params, signal) {
+        const { idempotencyKey, ...rest } = params;
+        const headers = idempotencyKey ? { "idempotency-key": idempotencyKey } : undefined;
+        return this.http.json("POST", "/v1/documents", {
+            body: rest,
+            headers,
+            signal,
+        });
+    }
+    /** Fetch the current state of a document. When `status` is "done" it carries a `download` block. */
+    get(id, signal) {
+        return this.http.json("GET", `/v1/documents/${encodeURIComponent(id)}`, { signal });
+    }
+    /** One page of the document history, newest first. Use `nextCursor` to page. */
+    list(params = {}, signal) {
+        return this.http.json("GET", "/v1/documents", {
+            query: {
+                status: params.status,
+                templateId: params.templateId,
+                cursor: params.cursor,
+                limit: params.limit,
+            },
+            signal,
+        });
+    }
+    /**
+     * Iterate every document across all pages, transparently following the cursor.
+     *
+     * ```ts
+     * for await (const doc of pw.documents.listAll({ status: "failed" })) { ... }
+     * ```
+     */
+    async *listAll(params = {}, signal) {
+        let cursor;
+        do {
+            const page = await this.list({ ...params, cursor: cursor ?? undefined }, signal);
+            for (const item of page.items)
+                yield item;
+            cursor = page.nextCursor;
+        } while (cursor);
+    }
+    /**
+     * Faithfully replay a prior document: the same version (or inline source), payload, options, and
+     * download protection. Returns a new document id (`202`); counts as a new render.
+     */
+    regenerate(id, signal) {
+        return this.http.json("POST", `/v1/documents/${encodeURIComponent(id)}/regenerate`, { signal });
+    }
+    /**
+     * Poll a document until it reaches a terminal state (or the timeout elapses). Resolves with the
+     * finished {@link Document}. By default it throws {@link PageWeaverDocumentFailedError} on failure;
+     * pass `throwOnFailure: false` to receive the failed document instead.
+     */
+    async waitFor(id, opts = {}) {
+        const intervalMs = opts.intervalMs ?? 1000;
+        const maxIntervalMs = opts.maxIntervalMs ?? 5000;
+        const backoff = opts.backoff ?? 1.5;
+        const timeoutMs = opts.timeoutMs ?? 60_000;
+        const throwOnFailure = opts.throwOnFailure ?? true;
+        const deadline = Date.now() + timeoutMs;
+        let delay = intervalMs;
+        let last = await this.get(id, opts.signal);
+        while (!TERMINAL.has(last.status)) {
+            if (Date.now() >= deadline) {
+                throw new errors_1.PageWeaverTimeoutError(id, last.status, timeoutMs);
+            }
+            const remaining = deadline - Date.now();
+            await sleep(Math.min(delay, remaining), opts.signal);
+            delay = Math.min(delay * backoff, maxIntervalMs);
+            last = await this.get(id, opts.signal);
+        }
+        if (last.status === "failed" && throwOnFailure) {
+            throw new errors_1.PageWeaverDocumentFailedError(last);
+        }
+        return last;
+    }
+    /** Convenience: {@link create} then {@link waitFor}. Resolves with the finished document. */
+    async createAndWait(params, opts = {}) {
+        const created = await this.create(params, opts.signal);
+        return this.waitFor(created.id, opts);
+    }
+    /**
+     * Download the finished PDF bytes. For a download-protected document, pass `{ password }`. For an
+     * unprotected document, the short-lived signed URL is resolved and fetched automatically.
+     */
+    async download(id, opts = {}) {
+        if (opts.password !== undefined) {
+            return this.http.bytes("GET", `/v1/documents/${encodeURIComponent(id)}/content`, {
+                headers: { "x-document-password": opts.password },
+                noAuth: true,
+                signal: opts.signal,
+            });
+        }
+        const doc = await this.get(id, opts.signal);
+        if (doc.status !== "done" || !doc.download?.url) {
+            throw new errors_1.PageWeaverDocumentFailedError(doc);
+        }
+        if (doc.download.protected) {
+            throw new errors_1.PageWeaverDocumentFailedError({
+                ...doc,
+                error: "Document is download-protected; supply a `password` to download it.",
+            });
+        }
+        return this.http.fetchUrlBytes(doc.download.url, opts.signal);
+    }
+}
+exports.DocumentsResource = DocumentsResource;
+/** Delay `ms`, rejecting early if the signal aborts. */
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted)
+            return reject(new Error("Aborted"));
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(new Error("Aborted"));
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+//# sourceMappingURL=documents.js.map

package/dist/documents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"documents.js","sourceRoot":"","sources":["../src/documents.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,43 @@
+import type { Document } from "./types";
+/** Base class for every error the SDK throws. Catch this to handle any SDK failure. */
+export declare class PageWeaverError extends Error {
+    constructor(message: string);
+}
+/**
+ * The API returned a non-2xx response. `status` is the HTTP status; `code`/`errors` are
+ * pulled from the JSON body when present (e.g. payload validation errors on a 400), and
+ * `body` is the raw parsed body for anything the typed fields don't cover.
+ */
+export declare class PageWeaverApiError extends PageWeaverError {
+    readonly status: number;
+    readonly code?: string;
+    readonly errors?: unknown;
+    readonly body: unknown;
+    constructor(args: {
+        status: number;
+        message: string;
+        code?: string;
+        errors?: unknown;
+        body: unknown;
+    });
+}
+/** A network-level failure: connection refused, DNS, or an aborted/timed-out request. */
+export declare class PageWeaverConnectionError extends PageWeaverError {
+    readonly cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}
+/** `waitFor`/`createAndWait` exceeded its timeout before the document reached a terminal state. */
+export declare class PageWeaverTimeoutError extends PageWeaverError {
+    readonly documentId: string;
+    readonly lastStatus: string;
+    constructor(documentId: string, lastStatus: string, timeoutMs: number);
+}
+/**
+ * The document reached the terminal `failed` state while waiting. Thrown by
+ * `waitFor`/`createAndWait` unless `throwOnFailure: false` is set. `document` carries the
+ * final response (including its `error` string).
+ */
+export declare class PageWeaverDocumentFailedError extends PageWeaverError {
+    readonly document: Document;
+    constructor(document: Document);
+}

package/dist/errors.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PageWeaverDocumentFailedError = exports.PageWeaverTimeoutError = exports.PageWeaverConnectionError = exports.PageWeaverApiError = exports.PageWeaverError = void 0;
+/** Base class for every error the SDK throws. Catch this to handle any SDK failure. */
+class PageWeaverError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PageWeaverError";
+        // Restore the prototype chain when compiled to ES5-ish targets.
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.PageWeaverError = PageWeaverError;
+/**
+ * The API returned a non-2xx response. `status` is the HTTP status; `code`/`errors` are
+ * pulled from the JSON body when present (e.g. payload validation errors on a 400), and
+ * `body` is the raw parsed body for anything the typed fields don't cover.
+ */
+class PageWeaverApiError extends PageWeaverError {
+    status;
+    code;
+    errors;
+    body;
+    constructor(args) {
+        super(args.message);
+        this.name = "PageWeaverApiError";
+        this.status = args.status;
+        this.code = args.code;
+        this.errors = args.errors;
+        this.body = args.body;
+    }
+}
+exports.PageWeaverApiError = PageWeaverApiError;
+/** A network-level failure: connection refused, DNS, or an aborted/timed-out request. */
+class PageWeaverConnectionError extends PageWeaverError {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.name = "PageWeaverConnectionError";
+        this.cause = cause;
+    }
+}
+exports.PageWeaverConnectionError = PageWeaverConnectionError;
+/** `waitFor`/`createAndWait` exceeded its timeout before the document reached a terminal state. */
+class PageWeaverTimeoutError extends PageWeaverError {
+    documentId;
+    lastStatus;
+    constructor(documentId, lastStatus, timeoutMs) {
+        super(`Timed out after ${timeoutMs}ms waiting for document ${documentId} (last status: ${lastStatus}).`);
+        this.name = "PageWeaverTimeoutError";
+        this.documentId = documentId;
+        this.lastStatus = lastStatus;
+    }
+}
+exports.PageWeaverTimeoutError = PageWeaverTimeoutError;
+/**
+ * The document reached the terminal `failed` state while waiting. Thrown by
+ * `waitFor`/`createAndWait` unless `throwOnFailure: false` is set. `document` carries the
+ * final response (including its `error` string).
+ */
+class PageWeaverDocumentFailedError extends PageWeaverError {
+    document;
+    constructor(document) {
+        super(`Document ${document.id} failed: ${document.error ?? "unknown error"}`);
+        this.name = "PageWeaverDocumentFailedError";
+        this.document = document;
+    }
+}
+exports.PageWeaverDocumentFailedError = PageWeaverDocumentFailedError;
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":";;;AAEA,uFAAuF;AACvF,MAAa,eAAgB,SAAQ,KAAK;IACxC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,gEAAgE;QAChE,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF;AAPD,0CAOC;AAED;;;;GAIG;AACH,MAAa,kBAAmB,SAAQ,eAAe;IAC5C,MAAM,CAAS;IACf,IAAI,CAAU;IACd,MAAM,CAAW;IACjB,IAAI,CAAU;IAEvB,YAAY,IAAyF;QACnG,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACpB,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;IACxB,CAAC;CACF;AAdD,gDAcC;AAED,yFAAyF;AACzF,MAAa,yBAA0B,SAAQ,eAAe;IAC1C,KAAK,CAAW;IAClC,YAAY,OAAe,EAAE,KAAe;QAC1C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,2BAA2B,CAAC;QACxC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;CACF;AAPD,8DAOC;AAED,mGAAmG;AACnG,MAAa,sBAAuB,SAAQ,eAAe;IAChD,UAAU,CAAS;IACnB,UAAU,CAAS;IAC5B,YAAY,UAAkB,EAAE,UAAkB,EAAE,SAAiB;QACnE,KAAK,CACH,mBAAmB,SAAS,2BAA2B,UAAU,kBAAkB,UAAU,IAAI,CAClG,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;QACrC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF;AAXD,wDAWC;AAED;;;;GAIG;AACH,MAAa,6BAA8B,SAAQ,eAAe;IACvD,QAAQ,CAAW;IAC5B,YAAY,QAAkB;QAC5B,KAAK,CAAC,YAAY,QAAQ,CAAC,EAAE,YAAY,QAAQ,CAAC,KAAK,IAAI,eAAe,EAAE,CAAC,CAAC;QAC9E,IAAI,CAAC,IAAI,GAAG,+BAA+B,CAAC;QAC5C,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;CACF;AAPD,sEAOC"}

package/dist/http.d.ts

@@ -0,0 +1,41 @@
+/** A `fetch` implementation compatible with the global one (Node 18+, browsers, undici). */
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+export interface HttpClientOptions {
+    apiKey: string;
+    /** API base URL. Defaults to https://api.pageweaver.io; point it at http://localhost:4000 in dev. */
+    baseUrl?: string;
+    /** Per-request timeout in milliseconds. Default 30000. */
+    timeoutMs?: number;
+    /** Inject a custom fetch (defaults to the global). */
+    fetch?: FetchLike;
+}
+export interface RequestInitLite {
+    query?: Record<string, string | number | undefined>;
+    body?: unknown;
+    headers?: Record<string, string>;
+    /** Skip attaching the `x-api-key` header (used by the recipient-facing content endpoint). */
+    noAuth?: boolean;
+    signal?: AbortSignal;
+}
+/**
+ * Thin fetch wrapper: attaches the API key, serializes JSON, applies a timeout, and maps
+ * non-2xx responses to {@link PageWeaverApiError} and transport failures to
+ * {@link PageWeaverConnectionError}. Every resource is built on this.
+ */
+export declare class HttpClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    constructor(opts: HttpClientOptions);
+    /** Perform a request and parse a JSON response into `T`. */
+    json<T>(method: string, path: string, init?: RequestInitLite): Promise<T>;
+    /** Perform a request and return the raw response body as bytes (for PDF downloads). */
+    bytes(method: string, path: string, init?: RequestInitLite): Promise<Uint8Array>;
+    /** Fetch an absolute URL (e.g. a signed download URL) and return its bytes. */
+    fetchUrlBytes(url: string, signal?: AbortSignal): Promise<Uint8Array>;
+    private send;
+    /** Compose a timeout AbortController with an optional caller-supplied signal. */
+    private withTimeout;
+    private wrapTransport;
+}