@pdfcraft-dev/pdf 1.0.0

package/dist/esm/contract/render-options.d.ts

@@ -0,0 +1,191 @@
+export type OptionKind = {
+    readonly kind: 'enum';
+    readonly values: readonly string[];
+} | {
+    readonly kind: 'boolean';
+} | {
+    readonly kind: 'number';
+    readonly min: number;
+    readonly max: number;
+} | {
+    readonly kind: 'integer';
+    readonly min: number;
+    readonly max: number;
+} | {
+    readonly kind: 'string';
+    readonly maxLength: number;
+    readonly pattern?: string;
+} | {
+    readonly kind: 'css-length';
+} | {
+    readonly kind: 'object';
+    readonly fields: readonly OptionField[];
+};
+export interface OptionField {
+    readonly name: string;
+    readonly type: OptionKind;
+    readonly default?: string | number | boolean;
+    readonly description: string;
+}
+export declare const PAGE_FORMATS: readonly ["A4", "A3", "A5", "Letter", "Legal", "Tabloid"];
+export declare const EMULATE_MEDIA: readonly ["print", "screen"];
+export declare const MAX_TIMEOUT_MS = 120000;
+export declare const DEFAULT_TIMEOUT_MS = 30000;
+export declare const MAX_HTML_BYTES = 5000000;
+export declare const RENDER_OPTIONS_SPEC: readonly [{
+    readonly name: "format";
+    readonly type: {
+        readonly kind: "enum";
+        readonly values: readonly ["A4", "A3", "A5", "Letter", "Legal", "Tabloid"];
+    };
+    readonly default: "A4";
+    readonly description: "Paper size. Ignored if the page CSS declares its own @page size.";
+}, {
+    readonly name: "landscape";
+    readonly type: {
+        readonly kind: "boolean";
+    };
+    readonly default: false;
+    readonly description: "Rotate the paper to landscape orientation.";
+}, {
+    readonly name: "margin";
+    readonly type: {
+        readonly kind: "object";
+        readonly fields: readonly [{
+            readonly name: "top";
+            readonly type: {
+                readonly kind: "css-length";
+            };
+            readonly description: "e.g. \"20mm\", \"1in\", \"72px\".";
+        }, {
+            readonly name: "right";
+            readonly type: {
+                readonly kind: "css-length";
+            };
+            readonly description: "e.g. \"15mm\".";
+        }, {
+            readonly name: "bottom";
+            readonly type: {
+                readonly kind: "css-length";
+            };
+            readonly description: "e.g. \"20mm\".";
+        }, {
+            readonly name: "left";
+            readonly type: {
+                readonly kind: "css-length";
+            };
+            readonly description: "e.g. \"15mm\".";
+        }];
+    };
+    readonly description: "Page margins. Any side may be omitted; omitted sides default to 0.";
+}, {
+    readonly name: "scale";
+    readonly type: {
+        readonly kind: "number";
+        readonly min: 0.1;
+        readonly max: 2;
+    };
+    readonly default: 1;
+    readonly description: "Rendering scale factor.";
+}, {
+    readonly name: "printBackground";
+    readonly type: {
+        readonly kind: "boolean";
+    };
+    readonly default: true;
+    readonly description: "Print background colours and images. Off by default in browsers; on by default here.";
+}, {
+    readonly name: "pageRanges";
+    readonly type: {
+        readonly kind: "string";
+        readonly maxLength: 100;
+        readonly pattern: "^[0-9,\\-\\s]+$";
+    };
+    readonly description: "Subset of pages to keep, e.g. \"1-5\" or \"1,4,7-9\". Empty means all pages.";
+}, {
+    readonly name: "headerHtml";
+    readonly type: {
+        readonly kind: "string";
+        readonly maxLength: 50000;
+    };
+    readonly description: "HTML for the running header. Supports Chromium print classes: date, title, url, pageNumber, totalPages. Needs a top margin to be visible.";
+}, {
+    readonly name: "footerHtml";
+    readonly type: {
+        readonly kind: "string";
+        readonly maxLength: 50000;
+    };
+    readonly description: "HTML for the running footer. Same classes as headerHtml; needs a bottom margin.";
+}, {
+    readonly name: "waitFor";
+    readonly type: {
+        readonly kind: "object";
+        readonly fields: readonly [{
+            readonly name: "selector";
+            readonly type: {
+                readonly kind: "string";
+                readonly maxLength: 500;
+            };
+            readonly description: "Wait until this CSS selector is attached to the DOM.";
+        }, {
+            readonly name: "networkIdle";
+            readonly type: {
+                readonly kind: "boolean";
+            };
+            readonly default: false;
+            readonly description: "Wait until there have been no network connections for 500 ms.";
+        }, {
+            readonly name: "delayMs";
+            readonly type: {
+                readonly kind: "integer";
+                readonly min: 0;
+                readonly max: 30000;
+            };
+            readonly default: 0;
+            readonly description: "Fixed pause after the other wait conditions are satisfied.";
+        }];
+    };
+    readonly description: "Conditions to satisfy before the PDF is taken. All of them apply, in order.";
+}, {
+    readonly name: "emulateMedia";
+    readonly type: {
+        readonly kind: "enum";
+        readonly values: readonly ["print", "screen"];
+    };
+    readonly default: "print";
+    readonly description: "Which CSS media type the page sees.";
+}, {
+    readonly name: "timeoutMs";
+    readonly type: {
+        readonly kind: "integer";
+        readonly min: 1000;
+        readonly max: 120000;
+    };
+    readonly default: 30000;
+    readonly description: "Hard ceiling on the whole render. Exceeding it returns 408 render_timeout.";
+}];
+export interface Margin {
+    top?: string;
+    right?: string;
+    bottom?: string;
+    left?: string;
+}
+export interface WaitFor {
+    selector?: string;
+    networkIdle?: boolean;
+    delayMs?: number;
+}
+export interface RenderOptions {
+    format?: (typeof PAGE_FORMATS)[number];
+    landscape?: boolean;
+    margin?: Margin;
+    scale?: number;
+    printBackground?: boolean;
+    pageRanges?: string;
+    headerHtml?: string;
+    footerHtml?: string;
+    waitFor?: WaitFor;
+    emulateMedia?: (typeof EMULATE_MEDIA)[number];
+    timeoutMs?: number;
+}
+export declare const SPEC_MATCHES_TYPES: boolean;

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

@@ -0,0 +1,108 @@
+// 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.
+export const PAGE_FORMATS = ['A4', 'A3', 'A5', 'Letter', 'Legal', 'Tabloid'];
+export const EMULATE_MEDIA = ['print', 'screen'];
+export const MAX_TIMEOUT_MS = 120_000;
+export const DEFAULT_TIMEOUT_MS = 30_000;
+export const MAX_HTML_BYTES = 5_000_000;
+export const RENDER_OPTIONS_SPEC = [
+    {
+        name: 'format',
+        type: { kind: 'enum', values: 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: EMULATE_MEDIA },
+        default: 'print',
+        description: 'Which CSS media type the page sees.',
+    },
+    {
+        name: 'timeoutMs',
+        type: { kind: 'integer', min: 1000, max: MAX_TIMEOUT_MS },
+        default: 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;
+export const SPEC_MATCHES_TYPES = driftCheck;
+//# sourceMappingURL=render-options.js.map

package/dist/esm/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"]}

package/dist/esm/contract/request.d.ts

@@ -0,0 +1,121 @@
+import { type RenderOptions } from './render-options.js';
+export declare const OUTPUT_MODES: readonly ["binary", "url"];
+export type OutputMode = (typeof OUTPUT_MODES)[number];
+export declare const RENDER_STATUSES: readonly ["queued", "rendering", "succeeded", "failed"];
+export type RenderStatus = (typeof RENDER_STATUSES)[number];
+export declare const RENDER_SOURCES: readonly ["html", "url"];
+export type RenderSource = (typeof RENDER_SOURCES)[number];
+export declare const ACCOUNT_STATUSES: readonly ["active", "past_due", "cancelled"];
+export type AccountStatus = (typeof ACCOUNT_STATUSES)[number];
+export interface Cookie {
+    name: string;
+    value: string;
+    domain?: string;
+    path?: string;
+}
+export interface RenderRequest {
+    /** Exactly one of html or url. */
+    html?: string;
+    url?: string;
+    options?: RenderOptions;
+    output?: OutputMode;
+    filename?: string;
+    /** url input only: extra request headers, so an authenticated page can be rendered. */
+    headers?: Record<string, string>;
+    /** url input only: cookies to seed the context with. */
+    cookies?: Cookie[];
+}
+export interface AsyncRenderRequest extends RenderRequest {
+    callback_url: string;
+}
+export interface RenderUrlResponse {
+    id: string;
+    url: string;
+    expires_at: string;
+    pages: number;
+    bytes: number;
+    duration_ms: number;
+}
+export interface AsyncRenderAccepted {
+    id: string;
+    status: 'queued';
+}
+export interface RenderStatusResponse {
+    id: string;
+    status: RenderStatus;
+    url?: string;
+    expires_at?: string;
+    pages?: number;
+    bytes?: number;
+    duration_ms?: number;
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+export interface UsageResponse {
+    used: number;
+    limit: number;
+    overage_count: number;
+    period_start: string;
+    resets_at: string;
+}
+/** Body sent to callback_url when an async render settles. */
+export interface WebhookPayload {
+    id: string;
+    status: 'succeeded' | 'failed';
+    url?: string;
+    pages?: number;
+    bytes?: number;
+    duration_ms: number;
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+/** Top-level request fields, for the generated docs reference. */
+export declare const REQUEST_FIELDS_SPEC: readonly [{
+    readonly name: "html";
+    readonly type: {
+        readonly kind: "string";
+        readonly maxLength: 5000000;
+    };
+    readonly description: "The document to render. Mutually exclusive with url; exactly one is required.";
+}, {
+    readonly name: "url";
+    readonly type: {
+        readonly kind: "string";
+        readonly maxLength: 2000;
+    };
+    readonly description: "A public http(s) URL to render. Mutually exclusive with html.";
+}, {
+    readonly name: "output";
+    readonly type: {
+        readonly kind: "enum";
+        readonly values: readonly ["binary", "url"];
+    };
+    readonly default: "binary";
+    readonly description: "\"binary\" streams application/pdf back; \"url\" uploads and returns a signed link.";
+}, {
+    readonly name: "filename";
+    readonly type: {
+        readonly kind: "string";
+        readonly maxLength: 255;
+    };
+    readonly default: "document.pdf";
+    readonly description: "Used for Content-Disposition on binary output and in the signed URL.";
+}, {
+    readonly name: "headers";
+    readonly type: {
+        readonly kind: "object";
+        readonly fields: readonly [];
+    };
+    readonly description: "url input only. Extra request headers, e.g. an Authorization header.";
+}, {
+    readonly name: "cookies";
+    readonly type: {
+        readonly kind: "object";
+        readonly fields: readonly [];
+    };
+    readonly description: "url input only. Array of {name, value, domain?, path?} seeded into the context.";
+}];

package/dist/esm/contract/request.js

@@ -0,0 +1,40 @@
+export const OUTPUT_MODES = ['binary', 'url'];
+export const RENDER_STATUSES = ['queued', 'rendering', 'succeeded', 'failed'];
+export const RENDER_SOURCES = ['html', 'url'];
+export const ACCOUNT_STATUSES = ['active', 'past_due', 'cancelled'];
+/** Top-level request fields, for the generated docs reference. */
+export const REQUEST_FIELDS_SPEC = [
+    {
+        name: 'html',
+        type: { kind: 'string', maxLength: 5_000_000 },
+        description: 'The document to render. Mutually exclusive with url; exactly one is required.',
+    },
+    {
+        name: 'url',
+        type: { kind: 'string', maxLength: 2000 },
+        description: 'A public http(s) URL to render. Mutually exclusive with html.',
+    },
+    {
+        name: 'output',
+        type: { kind: 'enum', values: OUTPUT_MODES },
+        default: 'binary',
+        description: '"binary" streams application/pdf back; "url" uploads and returns a signed link.',
+    },
+    {
+        name: 'filename',
+        type: { kind: 'string', maxLength: 255 },
+        default: 'document.pdf',
+        description: 'Used for Content-Disposition on binary output and in the signed URL.',
+    },
+    {
+        name: 'headers',
+        type: { kind: 'object', fields: [] },
+        description: 'url input only. Extra request headers, e.g. an Authorization header.',
+    },
+    {
+        name: 'cookies',
+        type: { kind: 'object', fields: [] },
+        description: 'url input only. Array of {name, value, domain?, path?} seeded into the context.',
+    },
+];
+//# sourceMappingURL=request.js.map

package/dist/esm/contract/request.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.js","sourceRoot":"","sources":["../../../src/contract/request.ts"],"names":[],"mappings":"AAGA,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,QAAQ,EAAE,KAAK,CAAU,CAAC;AAGvD,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,QAAQ,EAAE,WAAW,EAAE,WAAW,EAAE,QAAQ,CAAU,CAAC;AAGvF,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,MAAM,EAAE,KAAK,CAAU,CAAC;AAGvD,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,QAAQ,EAAE,UAAU,EAAE,WAAW,CAAU,CAAC;AAuE7E,kEAAkE;AAClE,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC;QACE,IAAI,EAAE,MAAM;QACZ,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE;QAC9C,WAAW,EAAE,+EAA+E;KAC7F;IACD;QACE,IAAI,EAAE,KAAK;QACX,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,EAAE;QACzC,WAAW,EAAE,+DAA+D;KAC7E;IACD;QACE,IAAI,EAAE,QAAQ;QACd,IAAI,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE;QAC5C,OAAO,EAAE,QAAQ;QACjB,WAAW,EAAE,iFAAiF;KAC/F;IACD;QACE,IAAI,EAAE,UAAU;QAChB,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,EAAE;QACxC,OAAO,EAAE,cAAc;QACvB,WAAW,EAAE,sEAAsE;KACpF;IACD;QACE,IAAI,EAAE,SAAS;QACf,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE;QACpC,WAAW,EAAE,sEAAsE;KACpF;IACD;QACE,IAAI,EAAE,SAAS;QACf,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE;QACpC,WAAW,EAAE,iFAAiF;KAC/F;CACwC,CAAC","sourcesContent":["// packages/contract/src/request.ts\nimport { type OptionField, type RenderOptions } from './render-options.js';\n\nexport const OUTPUT_MODES = ['binary', 'url'] as const;\nexport type OutputMode = (typeof OUTPUT_MODES)[number];\n\nexport const RENDER_STATUSES = ['queued', 'rendering', 'succeeded', 'failed'] as const;\nexport type RenderStatus = (typeof RENDER_STATUSES)[number];\n\nexport const RENDER_SOURCES = ['html', 'url'] as const;\nexport type RenderSource = (typeof RENDER_SOURCES)[number];\n\nexport const ACCOUNT_STATUSES = ['active', 'past_due', 'cancelled'] as const;\nexport type AccountStatus = (typeof ACCOUNT_STATUSES)[number];\n\nexport interface Cookie {\n  name: string;\n  value: string;\n  domain?: string;\n  path?: string;\n}\n\nexport interface RenderRequest {\n  /** Exactly one of html or url. */\n  html?: string;\n  url?: string;\n  options?: RenderOptions;\n  output?: OutputMode;\n  filename?: string;\n  /** url input only: extra request headers, so an authenticated page can be rendered. */\n  headers?: Record<string, string>;\n  /** url input only: cookies to seed the context with. */\n  cookies?: Cookie[];\n}\n\nexport interface AsyncRenderRequest extends RenderRequest {\n  callback_url: string;\n}\n\nexport interface RenderUrlResponse {\n  id: string;\n  url: string;\n  expires_at: string;\n  pages: number;\n  bytes: number;\n  duration_ms: number;\n}\n\nexport interface AsyncRenderAccepted {\n  id: string;\n  status: 'queued';\n}\n\nexport interface RenderStatusResponse {\n  id: string;\n  status: RenderStatus;\n  url?: string;\n  expires_at?: string;\n  pages?: number;\n  bytes?: number;\n  duration_ms?: number;\n  error?: { code: string; message: string };\n}\n\nexport interface UsageResponse {\n  used: number;\n  limit: number;\n  overage_count: number;\n  period_start: string;\n  resets_at: string;\n}\n\n/** Body sent to callback_url when an async render settles. */\nexport interface WebhookPayload {\n  id: string;\n  status: 'succeeded' | 'failed';\n  url?: string;\n  pages?: number;\n  bytes?: number;\n  duration_ms: number;\n  error?: { code: string; message: string };\n}\n\n/** Top-level request fields, for the generated docs reference. */\nexport const REQUEST_FIELDS_SPEC = [\n  {\n    name: 'html',\n    type: { kind: 'string', maxLength: 5_000_000 },\n    description: 'The document to render. Mutually exclusive with url; exactly one is required.',\n  },\n  {\n    name: 'url',\n    type: { kind: 'string', maxLength: 2000 },\n    description: 'A public http(s) URL to render. Mutually exclusive with html.',\n  },\n  {\n    name: 'output',\n    type: { kind: 'enum', values: OUTPUT_MODES },\n    default: 'binary',\n    description: '\"binary\" streams application/pdf back; \"url\" uploads and returns a signed link.',\n  },\n  {\n    name: 'filename',\n    type: { kind: 'string', maxLength: 255 },\n    default: 'document.pdf',\n    description: 'Used for Content-Disposition on binary output and in the signed URL.',\n  },\n  {\n    name: 'headers',\n    type: { kind: 'object', fields: [] },\n    description: 'url input only. Extra request headers, e.g. an Authorization header.',\n  },\n  {\n    name: 'cookies',\n    type: { kind: 'object', fields: [] },\n    description: 'url input only. Array of {name, value, domain?, path?} seeded into the context.',\n  },\n] as const satisfies readonly OptionField[];\n"]}

package/dist/esm/errors.d.ts

@@ -0,0 +1,10 @@
+import type { ErrorCode } from './contract/index.js';
+/** Every failure from the API arrives as one of these. Branch on `.code`. */
+export declare class PDFCraftError extends Error {
+    readonly code: ErrorCode | 'network_error';
+    readonly status: number;
+    readonly docsUrl: string | null;
+    readonly retryable: boolean;
+    constructor(code: ErrorCode | 'network_error', message: string, status: number, docsUrl?: string | null);
+}
+export declare function toError(status: number, body: string): PDFCraftError;

package/dist/esm/errors.js

@@ -0,0 +1,26 @@
+/** Every failure from the API arrives as one of these. Branch on `.code`. */
+export class PDFCraftError extends Error {
+    code;
+    status;
+    docsUrl;
+    retryable;
+    constructor(code, message, status, docsUrl = null) {
+        super(message);
+        this.name = 'PDFCraftError';
+        this.code = code;
+        this.status = status;
+        this.docsUrl = docsUrl;
+        this.retryable = code === 'network_error' || status === 429 || status >= 500;
+    }
+}
+export function toError(status, body) {
+    let parsed = {};
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        // Non-JSON body (a proxy error page, say) — fall through to the defaults.
+    }
+    return new PDFCraftError(parsed.error?.code ?? 'internal_error', parsed.error?.message ?? `PDFCraft responded ${status}`, status, parsed.error?.docs_url ?? null);
+}
+//# sourceMappingURL=errors.js.map

package/dist/esm/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAGA,6EAA6E;AAC7E,MAAM,OAAO,aAAc,SAAQ,KAAK;IAC7B,IAAI,CAA8B;IAClC,MAAM,CAAS;IACf,OAAO,CAAgB;IACvB,SAAS,CAAU;IAE5B,YACE,IAAiC,EACjC,OAAe,EACf,MAAc,EACd,UAAyB,IAAI;QAE7B,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,SAAS,GAAG,IAAI,KAAK,eAAe,IAAI,MAAM,KAAK,GAAG,IAAI,MAAM,IAAI,GAAG,CAAC;IAC/E,CAAC;CACF;AAMD,MAAM,UAAU,OAAO,CAAC,MAAc,EAAE,IAAY;IAClD,IAAI,MAAM,GAAc,EAAE,CAAC;IAC3B,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAc,CAAC;IACzC,CAAC;IAAC,MAAM,CAAC;QACP,0EAA0E;IAC5E,CAAC;IACD,OAAO,IAAI,aAAa,CACrB,MAAM,CAAC,KAAK,EAAE,IAAkB,IAAI,gBAAgB,EACrD,MAAM,CAAC,KAAK,EAAE,OAAO,IAAI,sBAAsB,MAAM,EAAE,EACvD,MAAM,EACN,MAAM,CAAC,KAAK,EAAE,QAAQ,IAAI,IAAI,CAC/B,CAAC;AACJ,CAAC","sourcesContent":["// packages/sdk/src/errors.ts\nimport type { ErrorCode } from './contract/index.js';\n\n/** Every failure from the API arrives as one of these. Branch on `.code`. */\nexport class PDFCraftError extends Error {\n  readonly code: ErrorCode | 'network_error';\n  readonly status: number;\n  readonly docsUrl: string | null;\n  readonly retryable: boolean;\n\n  constructor(\n    code: ErrorCode | 'network_error',\n    message: string,\n    status: number,\n    docsUrl: string | null = null,\n  ) {\n    super(message);\n    this.name = 'PDFCraftError';\n    this.code = code;\n    this.status = status;\n    this.docsUrl = docsUrl;\n    this.retryable = code === 'network_error' || status === 429 || status >= 500;\n  }\n}\n\ninterface WireError {\n  error?: { code?: string; message?: string; docs_url?: string };\n}\n\nexport function toError(status: number, body: string): PDFCraftError {\n  let parsed: WireError = {};\n  try {\n    parsed = JSON.parse(body) as WireError;\n  } catch {\n    // Non-JSON body (a proxy error page, say) — fall through to the defaults.\n  }\n  return new PDFCraftError(\n    (parsed.error?.code as ErrorCode) ?? 'internal_error',\n    parsed.error?.message ?? `PDFCraft responded ${status}`,\n    status,\n    parsed.error?.docs_url ?? null,\n  );\n}\n"]}

package/dist/esm/index.d.ts

@@ -0,0 +1,3 @@
+export { Renderer, type AsyncRenderInput, type RenderInput, type RendererOptions, } from './client.js';
+export { PDFCraftError } from './errors.js';
+export type { AsyncRenderAccepted, AsyncRenderRequest, Cookie, ErrorCode, Margin, OutputMode, RenderOptions, RenderRequest, RenderStatus, RenderStatusResponse, RenderUrlResponse, UsageResponse, WaitFor, WebhookPayload, } from './contract/index.js';

package/dist/esm/index.js

@@ -0,0 +1,4 @@
+// packages/sdk/src/index.ts
+export { Renderer, } from './client.js';
+export { PDFCraftError } from './errors.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,4BAA4B;AAC5B,OAAO,EACL,QAAQ,GAIT,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC","sourcesContent":["// packages/sdk/src/index.ts\nexport {\n  Renderer,\n  type AsyncRenderInput,\n  type RenderInput,\n  type RendererOptions,\n} from './client.js';\nexport { PDFCraftError } from './errors.js';\nexport type {\n  AsyncRenderAccepted,\n  AsyncRenderRequest,\n  Cookie,\n  ErrorCode,\n  Margin,\n  OutputMode,\n  RenderOptions,\n  RenderRequest,\n  RenderStatus,\n  RenderStatusResponse,\n  RenderUrlResponse,\n  UsageResponse,\n  WaitFor,\n  WebhookPayload,\n} from './contract/index.js';\n"]}

package/dist/esm/package.json

@@ -0,0 +1 @@
+{"type":"module"}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@pdfcraft-dev/pdf",
+  "version": "1.0.0",
+  "description": "HTML to PDF in one call. The official PDFCraft SDK.",
+  "license": "MIT",
+  "homepage": "https://pdfcraft.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/igaurav-dev/pdfcraft-dev.git"
+  },
+  "keywords": [
+    "pdf",
+    "pdf-api",
+    "html-to-pdf",
+    "html-to-pdf-api",
+    "url-to-pdf",
+    "pdf-generation",
+    "headless-chrome",
+    "puppeteer",
+    "playwright",
+    "invoice",
+    "chromium"
+  ],
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.esm.json && tsc -p tsconfig.cjs.json && node scripts/fixup.mjs",
+    "typecheck": "tsc -p tsconfig.esm.json --noEmit",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "22.18.9",
+    "typescript": "5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bugs": {
+    "url": "https://github.com/igaurav-dev/pdfcraft-dev/issues"
+  }
+}