@pageweaver/sdk 0.1.0

package/dist/webhooks.d.ts

@@ -0,0 +1,72 @@
+import { PageWeaverError } from "./errors";
+import type { DocumentStatus } from "./types";
+/** Header carrying the `sha256=<hex>` signature. */
+export declare const WEBHOOK_SIGNATURE_HEADER = "x-pageweaver-signature";
+/** Header carrying the event name. */
+export declare const WEBHOOK_EVENT_HEADER = "x-pageweaver-event";
+/** Header carrying the unix-seconds send time. */
+export declare const WEBHOOK_TIMESTAMP_HEADER = "x-pageweaver-timestamp";
+/** Terminal document events. */
+export type DocumentWebhookEventName = "document.completed" | "document.failed";
+/** Terminal bulk-run (batch) events. */
+export type BatchWebhookEventName = "batch.completed" | "batch.failed";
+export type WebhookEventName = DocumentWebhookEventName | BatchWebhookEventName;
+/** Body delivered for a single-document terminal event. `url` is a short-lived signed download URL. */
+export interface DocumentWebhookPayload {
+    event: DocumentWebhookEventName;
+    documentId: string;
+    templateId: string | null;
+    version: number | null;
+    status: Extract<DocumentStatus, "done" | "failed">;
+    url?: string;
+    error?: string;
+    createdAt: string;
+}
+/** Body delivered for a bulk-run terminal event. `bundleUrl` is a signed URL to the assembled ZIP. */
+export interface BatchWebhookPayload {
+    event: BatchWebhookEventName;
+    batchId: string;
+    templateId: string;
+    version: number;
+    status: "completed" | "failed";
+    totalRows: number;
+    succeeded: number;
+    failed: number;
+    invalidRows: number;
+    bundleUrl?: string;
+    createdAt: string;
+}
+export type WebhookPayload = DocumentWebhookPayload | BatchWebhookPayload;
+/** Type guard: narrow a verified event to a document payload. */
+export declare function isDocumentEvent(p: WebhookPayload): p is DocumentWebhookPayload;
+/** Type guard: narrow a verified event to a batch payload. */
+export declare function isBatchEvent(p: WebhookPayload): p is BatchWebhookPayload;
+/** Compute the `sha256=<hex>` signature for a body. Exposed mainly for tests. */
+export declare function signWebhookBody(secret: string, rawBody: string): string;
+/** Constant-time check of a `sha256=<hex>` signature against the raw body. Never throws. */
+export declare function verifyWebhookSignature(secret: string, rawBody: string, signature: string | undefined | null): boolean;
+/** Thrown when a webhook signature does not match the body. */
+export declare class PageWeaverWebhookSignatureError extends PageWeaverError {
+    constructor();
+}
+export interface VerifyWebhookOptions {
+    /** Your account webhook signing secret (`whsec_...`). */
+    secret: string;
+    /**
+     * The exact raw request body bytes, as a string. Use the unparsed body (e.g. `express.raw`),
+     * not a re-serialized object: re-stringifying can change the bytes and break the signature.
+     */
+    body: string;
+    /** The `X-PageWeaver-Signature` header value (a single string or the header array). */
+    signature: string | string[] | undefined | null;
+}
+/**
+ * Verify a webhook signature and return the parsed, typed event. Throws
+ * {@link PageWeaverWebhookSignatureError} if the signature is missing or wrong.
+ *
+ * ```ts
+ * const event = verifyWebhook({ secret, body: rawBody, signature: req.headers["x-pageweaver-signature"] });
+ * if (isDocumentEvent(event) && event.status === "done") { ... }
+ * ```
+ */
+export declare function verifyWebhook(opts: VerifyWebhookOptions): WebhookPayload;

package/dist/webhooks.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PageWeaverWebhookSignatureError = exports.WEBHOOK_TIMESTAMP_HEADER = exports.WEBHOOK_EVENT_HEADER = exports.WEBHOOK_SIGNATURE_HEADER = void 0;
+exports.isDocumentEvent = isDocumentEvent;
+exports.isBatchEvent = isBatchEvent;
+exports.signWebhookBody = signWebhookBody;
+exports.verifyWebhookSignature = verifyWebhookSignature;
+exports.verifyWebhook = verifyWebhook;
+const node_crypto_1 = require("node:crypto");
+const errors_1 = require("./errors");
+// PageWeaver signs each webhook delivery with HMAC-SHA256 over the exact request body, keyed by your
+// account webhook secret (`whsec_...`), and sends it in the `X-PageWeaver-Signature` header formatted
+// `sha256=<hex>`. Verify it on your endpoint before trusting the payload. This logic mirrors the
+// server's signer (packages/webhooks) and is inlined here so the SDK has no internal dependencies.
+/** Header carrying the `sha256=<hex>` signature. */
+exports.WEBHOOK_SIGNATURE_HEADER = "x-pageweaver-signature";
+/** Header carrying the event name. */
+exports.WEBHOOK_EVENT_HEADER = "x-pageweaver-event";
+/** Header carrying the unix-seconds send time. */
+exports.WEBHOOK_TIMESTAMP_HEADER = "x-pageweaver-timestamp";
+/** Type guard: narrow a verified event to a document payload. */
+function isDocumentEvent(p) {
+    return p.event === "document.completed" || p.event === "document.failed";
+}
+/** Type guard: narrow a verified event to a batch payload. */
+function isBatchEvent(p) {
+    return p.event === "batch.completed" || p.event === "batch.failed";
+}
+/** Compute the `sha256=<hex>` signature for a body. Exposed mainly for tests. */
+function signWebhookBody(secret, rawBody) {
+    return `sha256=${(0, node_crypto_1.createHmac)("sha256", secret).update(rawBody, "utf8").digest("hex")}`;
+}
+/** Constant-time check of a `sha256=<hex>` signature against the raw body. Never throws. */
+function verifyWebhookSignature(secret, rawBody, signature) {
+    if (!signature)
+        return false;
+    const expected = Buffer.from(signWebhookBody(secret, rawBody), "utf8");
+    const actual = Buffer.from(signature, "utf8");
+    return expected.length === actual.length && (0, node_crypto_1.timingSafeEqual)(expected, actual);
+}
+/** Thrown when a webhook signature does not match the body. */
+class PageWeaverWebhookSignatureError extends errors_1.PageWeaverError {
+    constructor() {
+        super("Invalid webhook signature.");
+        this.name = "PageWeaverWebhookSignatureError";
+    }
+}
+exports.PageWeaverWebhookSignatureError = PageWeaverWebhookSignatureError;
+/**
+ * Verify a webhook signature and return the parsed, typed event. Throws
+ * {@link PageWeaverWebhookSignatureError} if the signature is missing or wrong.
+ *
+ * ```ts
+ * const event = verifyWebhook({ secret, body: rawBody, signature: req.headers["x-pageweaver-signature"] });
+ * if (isDocumentEvent(event) && event.status === "done") { ... }
+ * ```
+ */
+function verifyWebhook(opts) {
+    const signature = Array.isArray(opts.signature) ? opts.signature[0] : opts.signature;
+    if (!verifyWebhookSignature(opts.secret, opts.body, signature)) {
+        throw new PageWeaverWebhookSignatureError();
+    }
+    return JSON.parse(opts.body);
+}
+//# sourceMappingURL=webhooks.js.map

package/dist/webhooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.js","sourceRoot":"","sources":["../src/webhooks.ts"],"names":[],"mappings":";;;AAoDA,0CAEC;AAGD,oCAEC;AAGD,0CAEC;AAGD,wDASC;AA+BD,sCAMC;AAjHD,6CAA0D;AAC1D,qCAA2C;AAG3C,qGAAqG;AACrG,sGAAsG;AACtG,iGAAiG;AACjG,mGAAmG;AAEnG,oDAAoD;AACvC,QAAA,wBAAwB,GAAG,wBAAwB,CAAC;AACjE,sCAAsC;AACzB,QAAA,oBAAoB,GAAG,oBAAoB,CAAC;AACzD,kDAAkD;AACrC,QAAA,wBAAwB,GAAG,wBAAwB,CAAC;AAqCjE,iEAAiE;AACjE,SAAgB,eAAe,CAAC,CAAiB;IAC/C,OAAO,CAAC,CAAC,KAAK,KAAK,oBAAoB,IAAI,CAAC,CAAC,KAAK,KAAK,iBAAiB,CAAC;AAC3E,CAAC;AAED,8DAA8D;AAC9D,SAAgB,YAAY,CAAC,CAAiB;IAC5C,OAAO,CAAC,CAAC,KAAK,KAAK,iBAAiB,IAAI,CAAC,CAAC,KAAK,KAAK,cAAc,CAAC;AACrE,CAAC;AAED,iFAAiF;AACjF,SAAgB,eAAe,CAAC,MAAc,EAAE,OAAe;IAC7D,OAAO,UAAU,IAAA,wBAAU,EAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;AACxF,CAAC;AAED,4FAA4F;AAC5F,SAAgB,sBAAsB,CACpC,MAAc,EACd,OAAe,EACf,SAAoC;IAEpC,IAAI,CAAC,SAAS;QAAE,OAAO,KAAK,CAAC;IAC7B,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,eAAe,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,CAAC;IACvE,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IAC9C,OAAO,QAAQ,CAAC,MAAM,KAAK,MAAM,CAAC,MAAM,IAAI,IAAA,6BAAe,EAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;AAChF,CAAC;AAED,+DAA+D;AAC/D,MAAa,+BAAgC,SAAQ,wBAAe;IAClE;QACE,KAAK,CAAC,4BAA4B,CAAC,CAAC;QACpC,IAAI,CAAC,IAAI,GAAG,iCAAiC,CAAC;IAChD,CAAC;CACF;AALD,0EAKC;AAcD;;;;;;;;GAQG;AACH,SAAgB,aAAa,CAAC,IAA0B;IACtD,MAAM,SAAS,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC;IACrF,IAAI,CAAC,sBAAsB,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,EAAE,SAAS,CAAC,EAAE,CAAC;QAC/D,MAAM,IAAI,+BAA+B,EAAE,CAAC;IAC9C,CAAC;IACD,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAmB,CAAC;AACjD,CAAC"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@pageweaver/sdk",
+  "version": "0.1.0",
+  "description": "Official TypeScript SDK for the PageWeaver PDF generation API.",
+  "license": "MIT",
+  "author": "PageWeaver",
+  "homepage": "https://pageweaver.io",
+  "keywords": [
+    "pageweaver",
+    "pdf",
+    "pdf-generation",
+    "html-to-pdf",
+    "sdk",
+    "api-client",
+    "typescript"
+  ],
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc -w -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "lint": "eslint src",
+    "test": "node --import tsx --test \"src/**/*.test.ts\"",
+    "sync:openapi": "node scripts/sync-openapi.mjs"
+  }
+}