@ironfang/render 3.0.1 → 3.1.0

package/README.md

@@ -18,6 +18,16 @@ the HMAC key, while a Render secret is the hex of the 32-byte key deliveries
 are signed with, so it rejected every genuine delivery. Upgrade if you
 verify Render webhooks with it.
 
+3.0.2 types a template's `vars` as `Record<string, string>` in `image()` and
+`sign()`, as the API has always required: a number, boolean or object passed
+the type check and then came back as a 400. Code that passed one no longer
+compiles; pass it as text (`String(n)`).
+
+3.1.0 adds capture bundles (`bundle()`), stored document templates
+(`documentTemplates`), and the request fields for lazy content, success
+rules, PDF controls, language and time zone, with each render's `diagnostics`.
+Additions only; see the [changelog](CHANGELOG.md).
+
 ```sh
 npm install @ironfang/render
 ```
@@ -65,6 +75,28 @@ to 1,024 UTF-8 bytes and share the render timeout. Invalid input returns
 messages. A screenshot cache hit does not re-execute controls; use `no_cache`
 for fresh execution. [Full reference](https://ironfang.com/render/docs#page-controls).
 
+## Capture bundles
+
+One navigation, the outputs you choose: a screenshot, the rendered HTML, the
+page's text, Markdown and its metadata. HTML, text and metadata are read
+together after the page's readiness and actions; the screenshot follows.
+
+```ts
+const b = await client.bundle({
+  url: 'https://example.com/blog/post',
+  outputs: ['screenshot', 'markdown', 'metadata'],
+});
+console.log(b.manifest.metadata?.title, b.markdown);
+for (const o of b.manifest.outputs) {
+  if (o.status !== 'included') console.warn(o.name, o.status, o.reason);
+}
+```
+
+An output over its bound is `truncated` or `omitted` in the manifest, never
+dropped silently. Iframe content is not in the text outputs. A bundle counts one
+`render.screenshot`. Captured HTML is the page's own: never insert it into a
+page of yours.
+
 ## Durable jobs
 
 ```ts

package/dist/client.d.ts

@@ -1,5 +1,5 @@
-import type { ClipRequest, Destination, DestinationDraft, ImageRequest, Job, JobSubmission, PdfRequest, QrRequest, RequestFilter, RequestRecord, ScreenshotRequest, SignRequest, SignedUrl, SitePreviewRequest, UnmeteredUsage, Usage } from './types.js';
-export declare const VERSION = "3.0.1";
+import type { ClipRequest, Destination, DestinationDraft, DocumentRenderRequest, DocumentRevision, DocumentTemplate, DocumentTemplateInput, DocumentValidation, ImageRequest, Job, JobSubmission, PdfRequest, QrRequest, RequestFilter, RequestRecord, BundleManifest, BundleRequest, ScreenshotRequest, SignRequest, SignedUrl, SitePreviewRequest, UnmeteredUsage, Usage } from './types.js';
+export declare const VERSION = "3.1.0";
 export interface ClientOptions {
     /** Your `rw_live_...` key. Never ship this to a browser. */
     apiKey: string;
@@ -41,6 +41,24 @@ export interface RenderResult {
     /** Write the bytes to a file. Node only; throws elsewhere. */
     saveTo(path: string): Promise<void>;
 }
+/**
+ * A capture bundle. The text outputs are the page's own content: untrusted,
+ * never to be inserted into a page as HTML.
+ */
+export interface BundleResult {
+    manifest: BundleManifest;
+    /** Each output is undefined when the bundle does not include it. */
+    screenshot: Uint8Array | undefined;
+    renderedHtml: string | undefined;
+    text: string | undefined;
+    markdown: string | undefined;
+    /** `render.screenshot`. */
+    meter: string | undefined;
+    quantity: number;
+    renderMs: number;
+    requestId: string;
+    headers: Headers;
+}
 /** A site preview: the poster frame and the scrolling video. */
 export interface SitePreviewResult {
     poster: Uint8Array;
@@ -73,8 +91,49 @@ export declare class IronfangRender {
     /** Render one of your stored templates with variables filled in. */
     image(templateId: string, req?: ImageRequest, opts?: RequestOptions): Promise<RenderResult>;
     clip(req: ClipRequest, opts?: RequestOptions): Promise<RenderResult>;
+    /**
+     * Capture a bundle: the outputs you select - screenshot, rendered HTML,
+     * text, Markdown, metadata - from one navigation of the page.
+     */
+    bundle(req: BundleRequest, opts?: RequestOptions): Promise<BundleResult>;
     sitePreview(req: SitePreviewRequest, opts?: RequestOptions): Promise<SitePreviewResult>;
     private render;
+    /**
+     * Stored PDF templates with structured JSON data: a draft, published as
+     * immutable numbered revisions. Render a published revision with `render`,
+     * or as a job of kind `document`.
+     */
+    readonly documentTemplates: {
+        create: (tpl: DocumentTemplateInput, opts?: RequestOptions) => Promise<DocumentTemplate>;
+        list: (opts?: RequestOptions & {
+            archived?: boolean;
+        }) => Promise<{
+            templates: DocumentTemplate[];
+        }>;
+        get: (id: string, opts?: RequestOptions) => Promise<DocumentTemplate>;
+        /** Replace the draft. What is published changes only on `publish`. */
+        update: (id: string, tpl: DocumentTemplateInput, opts?: RequestOptions) => Promise<DocumentTemplate>;
+        /** Archive: no more edits or unversioned renders; revisions and accepted jobs are kept. */
+        archive: (id: string, opts?: RequestOptions) => Promise<void>;
+        /** Check the draft against data (or its sample data) without printing or billing. */
+        validate: (id: string, data?: Record<string, unknown>, opts?: RequestOptions) => Promise<DocumentValidation>;
+        /** Print the draft with data (or its sample data). A PDF render; throws on any failure. */
+        preview: (id: string, data?: Record<string, unknown>, opts?: RequestOptions) => Promise<RenderResult>;
+        /** Publish the draft as a new revision (or the latest again, if unchanged). */
+        publish: (id: string, opts?: RequestOptions) => Promise<DocumentRevision>;
+        /** Publish an existing revision again: a rollback. */
+        publishRevision: (id: string, revision: number, opts?: RequestOptions) => Promise<DocumentRevision>;
+        revisions: (id: string, opts?: RequestOptions) => Promise<{
+            revisions: DocumentRevision[];
+        }>;
+        revision: (id: string, revision: number, opts?: RequestOptions) => Promise<DocumentRevision>;
+        /**
+         * Print a revision - the published one unless `req.revision` names
+         * another - with `req.data`. Data problems throw `data_invalid` before
+         * anything is charged; the error's `fields` names each path.
+         */
+        render: (id: string, req: DocumentRenderRequest, opts?: RequestOptions) => Promise<RenderResult>;
+    };
     readonly jobs: {
         /**
          * Submit a durable job. Pass `idempotencyKey` to make a retry of the same

package/dist/client.js

@@ -1,5 +1,5 @@
 import { BILLING_CODES, IronfangBillingError, IronfangRenderError } from './errors.js';
-export const VERSION = '3.0.1';
+export const VERSION = '3.1.0';
 export class IronfangRender {
     apiKey;
     baseUrl;
@@ -31,6 +31,36 @@ export class IronfangRender {
     clip(req, opts = {}) {
         return this.render('/v1/video', req, opts);
     }
+    /**
+     * Capture a bundle: the outputs you select - screenshot, rendered HTML,
+     * text, Markdown, metadata - from one navigation of the page.
+     */
+    async bundle(req, opts = {}) {
+        const resp = await this.send('POST', '/v1/bundle', req, opts, idempotency(opts));
+        const form = await resp.formData();
+        const manifest = form.get('manifest');
+        if (manifest === null) {
+            throw new IronfangRenderError('the response did not include a manifest', {
+                status: resp.status, code: 'bad_response', requestId: requestIdOf(resp),
+            });
+        }
+        const text = async (name) => {
+            const part = form.get(name);
+            return part instanceof Blob ? await part.text() : undefined;
+        };
+        const shot = form.get('screenshot');
+        return {
+            manifest: JSON.parse(typeof manifest === 'string' ? manifest : await manifest.text()),
+            screenshot: shot instanceof Blob ? new Uint8Array(await shot.arrayBuffer()) : undefined,
+            renderedHtml: await text('rendered_html'),
+            text: await text('text'),
+            markdown: await text('markdown'),
+            ...usageOf(resp),
+            renderMs: num(resp.headers.get('X-Ironfang-Render-Ms')),
+            requestId: requestIdOf(resp),
+            headers: resp.headers,
+        };
+    }
     async sitePreview(req, opts = {}) {
         const resp = await this.send('POST', '/v1/site-preview', req, opts, idempotency(opts));
         const form = await resp.formData();
@@ -66,6 +96,66 @@ export class IronfangRender {
             saveTo: (target) => saveBytes(target, bytes),
         };
     }
+    /* -------------------------- document templates ------------------------ */
+    /**
+     * Stored PDF templates with structured JSON data: a draft, published as
+     * immutable numbered revisions. Render a published revision with `render`,
+     * or as a job of kind `document`.
+     */
+    documentTemplates = {
+        create: async (tpl, opts = {}) => {
+            const resp = await this.send('POST', '/v1/document-templates', tpl, opts);
+            return (await resp.json());
+        },
+        list: async (opts = {}) => {
+            const resp = await this.send('GET', `/v1/document-templates${opts.archived ? '?archived=true' : ''}`, undefined, opts);
+            return (await resp.json());
+        },
+        get: async (id, opts = {}) => {
+            const resp = await this.send('GET', `/v1/document-templates/${encodeURIComponent(id)}`, undefined, opts);
+            return (await resp.json());
+        },
+        /** Replace the draft. What is published changes only on `publish`. */
+        update: async (id, tpl, opts = {}) => {
+            const resp = await this.send('PUT', `/v1/document-templates/${encodeURIComponent(id)}`, tpl, opts);
+            return (await resp.json());
+        },
+        /** Archive: no more edits or unversioned renders; revisions and accepted jobs are kept. */
+        archive: async (id, opts = {}) => {
+            await this.send('DELETE', `/v1/document-templates/${encodeURIComponent(id)}`, undefined, opts);
+        },
+        /** Check the draft against data (or its sample data) without printing or billing. */
+        validate: async (id, data, opts = {}) => {
+            const resp = await this.send('POST', `/v1/document-templates/${encodeURIComponent(id)}/validate`, data ? { data } : {}, opts);
+            return (await resp.json());
+        },
+        /** Print the draft with data (or its sample data). A PDF render; throws on any failure. */
+        preview: (id, data, opts = {}) => this.render(`/v1/document-templates/${encodeURIComponent(id)}/preview`, data ? { data } : {}, opts),
+        /** Publish the draft as a new revision (or the latest again, if unchanged). */
+        publish: async (id, opts = {}) => {
+            const resp = await this.send('POST', `/v1/document-templates/${encodeURIComponent(id)}/publish`, undefined, opts);
+            return (await resp.json());
+        },
+        /** Publish an existing revision again: a rollback. */
+        publishRevision: async (id, revision, opts = {}) => {
+            const resp = await this.send('POST', `/v1/document-templates/${encodeURIComponent(id)}/revisions/${revision}/publish`, undefined, opts);
+            return (await resp.json());
+        },
+        revisions: async (id, opts = {}) => {
+            const resp = await this.send('GET', `/v1/document-templates/${encodeURIComponent(id)}/revisions`, undefined, opts);
+            return (await resp.json());
+        },
+        revision: async (id, revision, opts = {}) => {
+            const resp = await this.send('GET', `/v1/document-templates/${encodeURIComponent(id)}/revisions/${revision}`, undefined, opts);
+            return (await resp.json());
+        },
+        /**
+         * Print a revision - the published one unless `req.revision` names
+         * another - with `req.data`. Data problems throw `data_invalid` before
+         * anything is charged; the error's `fields` names each path.
+         */
+        render: (id, req, opts = {}) => this.render(`/v1/document-templates/${encodeURIComponent(id)}/render`, req, opts),
+    };
     /* -------------------------------- jobs -------------------------------- */
     jobs = {
         /**
@@ -216,6 +306,7 @@ async function errorFrom(resp) {
     let code = `http_${resp.status}`;
     let message = `request failed with HTTP ${resp.status}`;
     let detail = {};
+    let fields;
     try {
         const body = (await resp.json());
         if (body?.error?.code)
@@ -224,11 +315,13 @@ async function errorFrom(resp) {
             message = body.error.message;
         if (body?.error)
             detail = body.error;
+        if (Array.isArray(body?.fields))
+            fields = body.fields;
     }
     catch {
         // Not JSON; the status is all there is.
     }
-    const opts = { status: resp.status, code, requestId: requestIdOf(resp), retryAfter: retryAfterOf(resp) };
+    const opts = { status: resp.status, code, requestId: requestIdOf(resp), retryAfter: retryAfterOf(resp), fields };
     if (BILLING_CODES.includes(code)) {
         return new IronfangBillingError(message, {
             ...opts, product: text(detail.product), meter: text(detail.meter), resetAt: text(detail.reset_at),

package/dist/errors.d.ts

@@ -12,11 +12,25 @@ export declare class IronfangRenderError extends Error {
     readonly code: string;
     readonly requestId: string | undefined;
     readonly retryAfter: number | undefined;
+    /**
+     * Per-field problems, when the request failed on particular fields: for
+     * `data_invalid`, each path in a document template's data and what is wrong.
+     */
+    readonly fields: {
+        field: string;
+        code: string;
+        message: string;
+    }[] | undefined;
     constructor(message: string, opts: {
         status: number;
         code: string;
         requestId?: string | undefined;
         retryAfter?: number | undefined;
+        fields?: {
+            field: string;
+            code: string;
+            message: string;
+        }[] | undefined;
     });
     /** The request was refused before any work was done. */
     get isClientError(): boolean;

package/dist/errors.js

@@ -12,6 +12,11 @@ export class IronfangRenderError extends Error {
     code;
     requestId;
     retryAfter;
+    /**
+     * Per-field problems, when the request failed on particular fields: for
+     * `data_invalid`, each path in a document template's data and what is wrong.
+     */
+    fields;
     constructor(message, opts) {
         super(message);
         this.name = 'IronfangRenderError';
@@ -19,6 +24,7 @@ export class IronfangRenderError extends Error {
         this.code = opts.code;
         this.requestId = opts.requestId;
         this.retryAfter = opts.retryAfter;
+        this.fields = opts.fields;
     }
     /** The request was refused before any work was done. */
     get isClientError() {

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { IronfangRender, VERSION } from './client.js';
-export type { ClientOptions, RequestOptions, RenderResult, SitePreviewResult, WaitOptions } from './client.js';
+export type { ClientOptions, RequestOptions, BundleResult, RenderResult, SitePreviewResult, WaitOptions } from './client.js';
 export { IronfangBillingError, IronfangRenderError } from './errors.js';
 export { verifyWebhook, signWebhook } from './webhook.js';
 export type { WebhookInput } from './webhook.js';

package/dist/types.d.ts

@@ -31,6 +31,31 @@ export interface RenderCommon {
     wait_for_selector?: string;
     timeout_ms?: number;
     device_scale_factor?: number;
+    /**
+     * The browser's language, a BCP 47 tag such as `de-DE`: Intl formatting,
+     * `navigator.language(s)` and `Accept-Language`. An `Accept-Language` in
+     * `headers` is sent exactly as given instead. Not an IP address in that country.
+     */
+    locale?: string;
+    /** The browser's clock, an IANA zone such as `Europe/Berlin`. Default UTC. */
+    timezone?: string;
+}
+/**
+ * Opt-in rules for output that should count as a failure: a render one fails
+ * is a 422 `success_rule_failed` naming the rule (`error.rule`), and is not
+ * charged. Without rules a render behaves as before.
+ */
+export interface SuccessRules {
+    /** Target statuses that fail the render: `404`, `'5xx'` or `'400-499'`. Needs `url`. */
+    fail_on_status?: (number | string)[];
+    /** A CSS selector that must match an element in the ready page. Does not wait. */
+    require_selector?: string;
+    /** Text that must be displayed on the page: literal, any case, whitespace collapsed. */
+    require_text?: string[];
+    /** Text that must not be displayed on the page, matched as `require_text`. */
+    forbid_text?: string[];
+    /** Screenshots only: fail a capture that is a single flat colour. */
+    fail_on_blank?: boolean;
 }
 export interface ScreenshotRequest extends RenderCommon {
     url?: string;
@@ -39,6 +64,12 @@ export interface ScreenshotRequest extends RenderCommon {
     height?: number;
     full_page?: boolean;
     full_page_max_height?: number;
+    /**
+     * `scroll` walks a `full_page` capture down first, so lazy images and
+     * IntersectionObserver content are in it. Bounded (at most 10 s); omitted,
+     * the capture is taken as before. Requires `full_page`.
+     */
+    full_page_readiness?: 'scroll';
     selector?: string;
     clip?: {
         x: number;
@@ -52,6 +83,7 @@ export interface ScreenshotRequest extends RenderCommon {
     quality?: number;
     device?: 'desktop' | 'tablet' | 'mobile';
     delay_ms?: number;
+    success_rules?: SuccessRules;
 }
 export interface PdfRequest extends RenderCommon {
     url?: string;
@@ -68,6 +100,22 @@ export interface PdfRequest extends RenderCommon {
     header_html?: string;
     footer_html?: string;
     scale?: number;
+    /** A custom size with units, such as `210mm`; both or neither, never with `paper_format`. */
+    paper_width?: string;
+    paper_height?: string;
+    /** Let the page's own `@page { size }` decide the page size. */
+    prefer_css_page_size?: boolean;
+    /** Pages to keep, such as `1-3, 5, 8-`; the whole document is still bounded. */
+    page_ranges?: string;
+    /** The PDF's document properties. */
+    metadata?: {
+        title?: string;
+        author?: string;
+        subject?: string;
+        keywords?: string;
+    };
+    /** As on a screenshot, less `fail_on_blank`. */
+    success_rules?: Omit<SuccessRules, 'fail_on_blank'>;
 }
 export interface QrRequest {
     data: string;
@@ -85,7 +133,9 @@ export interface QrRequest {
     logo_pad?: boolean;
 }
 export interface ImageRequest {
-    vars?: Record<string, unknown>;
+    /** The template's placeholder values. Text only: the API refuses a number,
+     * boolean or object with 400, so pass `String(n)` for a number. */
+    vars?: Record<string, string>;
     format?: 'png' | 'jpeg' | 'webp';
 }
 export interface ClipRequest {
@@ -102,6 +152,57 @@ export interface ClipRequest {
         end?: number;
     }[];
 }
+/** The outputs a capture bundle can include. */
+export type BundleOutputName = 'screenshot' | 'rendered_html' | 'text' | 'markdown' | 'metadata';
+/**
+ * A capture bundle: every screenshot option, and the outputs wanted from the
+ * one navigation. `selector`, `clip`, `format`, `quality`, `omit_background`
+ * and `fail_on_blank` need `screenshot` among the outputs.
+ */
+export interface BundleRequest extends ScreenshotRequest {
+    outputs: BundleOutputName[];
+}
+/** One output's line in a bundle's manifest. */
+export interface BundleOutput {
+    name: BundleOutputName;
+    /** `truncated` is the start of it, to its limit; `omitted` is none of it. */
+    status: 'included' | 'truncated' | 'omitted';
+    reason?: 'too_large' | 'source_too_large' | 'unparseable';
+    part?: string;
+    filename?: string;
+    content_type?: string;
+    bytes?: number;
+    sha256?: string;
+    source_bytes?: number;
+    limit_bytes?: number;
+}
+/** A bundle's manifest: what it holds and how it was captured. */
+export interface BundleManifest {
+    version: 1;
+    /** The main document's final response; null for `html` input. */
+    target: {
+        status: number;
+        url: string;
+        redirects: number;
+    } | null;
+    capture: {
+        started_at: string;
+        page_read_at: string;
+        screenshot_at?: string;
+        finished_at: string;
+    };
+    outputs: BundleOutput[];
+    metadata?: {
+        title: string;
+        description?: string;
+        lang?: string;
+        canonical_url?: string;
+        robots?: string;
+        open_graph?: Record<string, string>;
+    };
+    /** Frames whose content is not in the HTML, text or Markdown. */
+    child_frames: number;
+}
 export interface SitePreviewRequest extends RenderCommon {
     url: string;
     width?: number;
@@ -111,7 +212,7 @@ export interface SitePreviewRequest extends RenderCommon {
     device?: 'desktop' | 'tablet' | 'mobile';
     delay_ms?: number;
 }
-export type JobKind = 'screenshot' | 'pdf' | 'qr' | 'image' | 'clip' | 'site_preview';
+export type JobKind = 'screenshot' | 'pdf' | 'qr' | 'image' | 'clip' | 'site_preview' | 'document' | 'bundle';
 export type JobStatus = 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled';
 export interface JobDelivery {
     webhook_destination?: string;
@@ -135,6 +236,43 @@ export interface JobSubmission {
     external_id?: string;
     delivery?: JobDelivery;
 }
+/**
+ * What a render learned about the page: on a job, its webhook and a request
+ * history row. A synchronous render gives the same as `X-Ironfang-*` headers.
+ */
+export interface RenderDiagnostics {
+    settle?: 'stable' | 'ceiling' | 'fixed' | 'skipped';
+    settle_ms?: number;
+    /** The page's own final HTTP status after redirects; absent for raw HTML. */
+    target_status?: number;
+    /** The final address, without credentials, query or fragment. */
+    target_url?: string;
+    target_redirects?: number;
+    navigate_ms?: number;
+    capture_ms?: number;
+    viewport?: {
+        width: number;
+        height: number;
+        scale: number;
+        mobile: boolean;
+    };
+    /** What a `full_page_readiness` pass did. */
+    readiness?: {
+        profile: 'scroll';
+        steps: number;
+        ms: number;
+        images_loading?: number;
+        images_broken?: number;
+    };
+    /**
+     * Output complete as a render but not the whole page: `height_capped`,
+     * `scroll_budget_exhausted`, `images_incomplete`, `images_broken`; and
+     * `bot_challenge` when the page is recognisably a challenge interstitial.
+     */
+    warnings?: string[];
+    /** The `success_rules` field that failed the render. */
+    failed_rule?: 'fail_on_status' | 'require_selector' | 'require_text' | 'forbid_text' | 'fail_on_blank';
+}
 export interface Job {
     id: string;
     kind: JobKind;
@@ -154,6 +292,8 @@ export interface Job {
         code: string;
         message: string;
     };
+    /** Once an attempt has loaded the page, failed attempts included. */
+    diagnostics?: RenderDiagnostics;
     result?: {
         available: boolean;
         content_type: string;
@@ -168,10 +308,18 @@ export interface SignRequest {
     kind: 'screenshot' | 'image';
     url?: string;
     template?: string;
-    vars?: Record<string, unknown>;
+    /** Placeholder values for an `image` URL: text only, as for `image()`. */
+    vars?: Record<string, string>;
     width?: number;
     height?: number;
     full_page?: boolean;
+    /** Screenshot only, with `full_page`: as on `ScreenshotRequest`. */
+    full_page_readiness?: 'scroll';
+    /** Screenshot only: as on `ScreenshotRequest`, signed into the URL. */
+    success_rules?: SuccessRules;
+    /** Screenshot only: as on `ScreenshotRequest`, signed into the URL. */
+    locale?: string;
+    timezone?: string;
     ttl_hours?: number;
 }
 export interface SignedUrl {
@@ -253,6 +401,8 @@ export interface RequestRecord {
     option_fields: string[];
     client?: string;
     created_at: string;
+    /** For a render that loaded a page; a cache hit has none. */
+    diagnostics?: RenderDiagnostics;
 }
 export interface RequestFilter {
     since?: string;
@@ -296,3 +446,79 @@ export interface Destination {
     /** Present on a webhook destination's creation response only. */
     signing_secret?: string;
 }
+/** How a document template prints, kept with each revision. As on `PdfRequest`. */
+export interface DocumentOptions {
+    landscape?: boolean;
+    paper_format?: 'a3' | 'a4' | 'a5' | 'letter' | 'legal' | 'tabloid';
+    margin?: {
+        top?: number;
+        right?: number;
+        bottom?: number;
+        left?: number;
+    };
+    print_background?: boolean;
+    header_html?: string;
+    footer_html?: string;
+    scale?: number;
+    /** A custom size with units, such as `210mm`; both or neither, never with `paper_format`. */
+    paper_width?: string;
+    paper_height?: string;
+    /** Let the page's own `@page { size }` decide the page size. */
+    prefer_css_page_size?: boolean;
+    /** Pages to keep, such as `1-3, 5, 8-`; the whole document is still bounded. */
+    page_ranges?: string;
+    /** The PDF's document properties. */
+    metadata?: {
+        title?: string;
+        author?: string;
+        subject?: string;
+        keywords?: string;
+    };
+}
+/**
+ * A stored PDF template's draft: html/template source over JSON data, a
+ * strict JSON Schema subset for the data, print options and sample data.
+ */
+export interface DocumentTemplateInput {
+    name: string;
+    source: string;
+    schema?: Record<string, unknown>;
+    options?: DocumentOptions;
+    sample_data?: Record<string, unknown>;
+}
+export interface DocumentTemplate extends DocumentTemplateInput {
+    id: string;
+    /** The revision unversioned renders use; null until first published. */
+    published_revision: number | null;
+    archived_at?: string;
+    created_at: string;
+    updated_at: string;
+}
+/** An immutable published version of a document template. */
+export interface DocumentRevision {
+    id: string;
+    template_id: string;
+    number: number;
+    /** Absent from lists. */
+    source?: string;
+    schema?: Record<string, unknown>;
+    options: DocumentOptions;
+    sha256: string;
+    created_at: string;
+}
+export interface DocumentRenderRequest {
+    data?: Record<string, unknown>;
+    /** A revision number; absent or 0 for the published one. */
+    revision?: number;
+}
+/** A field the data got wrong, for `data_invalid` (the error's `fields`). */
+export interface DocumentFieldError {
+    field: string;
+    code: 'required' | 'invalid';
+    message: string;
+}
+export interface DocumentValidation {
+    valid: boolean;
+    fields?: DocumentFieldError[];
+    error?: string;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ironfang/render",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "description": "Ironfang Render API client: screenshots, PDFs, QR codes, template images, clips and site previews from a URL or HTML.",
   "license": "MIT",
   "type": "module",