@ironfang/renderwolf 0.1.0

package/README.md

@@ -0,0 +1,64 @@
+# @ironfang/renderwolf
+
+The official client for the [Renderwolf](https://ironfang.uk/renderwolf) API:
+screenshots, PDFs, QR codes, template images, clips and site previews from a
+URL or from HTML you send. Zero dependencies; Node 20 and later.
+
+```sh
+npm install @ironfang/renderwolf
+```
+
+```ts
+import { Renderwolf } from '@ironfang/renderwolf';
+
+const rw = new Renderwolf({ apiKey: process.env.IRONFANG_API_KEY! });
+
+const shot = await rw.screenshot({ url: 'https://example.com', full_page: true });
+await shot.saveTo('page.png');
+console.log(shot.credits, shot.renderMs, shot.requestId);
+```
+
+Every render returns the bytes plus what the API reports about them: content
+type, credits charged (zero on a cache hit), render time and the request id
+to quote to support.
+
+## Durable jobs
+
+```ts
+const job = await rw.jobs.submit(
+  { kind: 'pdf', request: { html: invoiceHtml, paper_format: 'a4' } },
+  { idempotencyKey: `invoice-${invoice.id}` },
+);
+const done = await rw.jobs.wait(job.id);
+if (done.status === 'succeeded') {
+  const pdf = await rw.jobs.result(job.id);
+  await pdf.saveTo(`invoice-${invoice.id}.pdf`);
+}
+```
+
+## Verifying a webhook
+
+Run the check over the raw request body, before parsing it.
+
+```ts
+import { verifyWebhook } from '@ironfang/renderwolf';
+
+const ok = await verifyWebhook({
+  secret: process.env.RENDERWOLF_WEBHOOK_SECRET!,
+  timestamp: req.headers['renderwolf-timestamp'],
+  signature: req.headers['renderwolf-signature'],
+  payload: rawBody,
+});
+```
+
+## Errors
+
+Failures throw `RenderwolfError` with `status`, the API's `code`
+(`quota_exhausted`, `render_failed`, ...) and `requestId`. Synchronous renders
+are never retried by the client: a render that timed out may already have
+been charged, and retrying it blind doubles the bill.
+
+## Keys
+
+Keep the key on a server. For anything a browser or an email needs to fetch
+directly, mint a signed URL with `rw.sign(...)` instead.

package/dist/client.d.ts

@@ -0,0 +1,114 @@
+import type { ClipRequest, Destination, DestinationDraft, ImageRequest, Job, JobSubmission, PdfRequest, QrRequest, RequestFilter, RequestRecord, ScreenshotRequest, SignRequest, SignedUrl, SitePreviewRequest, Usage } from './types.js';
+export declare const VERSION = "0.1.0";
+export interface ClientOptions {
+    /** Your `rw_live_...` key. Never ship this to a browser. */
+    apiKey: string;
+    /** Defaults to https://api.ironfang.uk/renderwolf. */
+    baseUrl?: string;
+    /** Per-request timeout. Renders can legitimately take tens of seconds; default 90s. */
+    timeoutMs?: number;
+    /** A fetch implementation, for tests or unusual runtimes. */
+    fetch?: typeof fetch;
+}
+export interface RequestOptions {
+    /** Cancel the request. A synchronous render that has started may still be charged. */
+    signal?: AbortSignal;
+    /** Your own correlation id, echoed as X-Request-ID and kept in request history. */
+    requestId?: string;
+    timeoutMs?: number;
+}
+/** A finished synchronous render with the facts the API reports about it. */
+export interface RenderResult {
+    bytes: Uint8Array;
+    contentType: string;
+    /** Credits this render cost. Zero when served from cache. */
+    credits: number;
+    renderMs: number;
+    cached: boolean;
+    /** The id to quote to support. */
+    requestId: string;
+    /** Every response header, for the ones not surfaced above. */
+    headers: Headers;
+    /** Write the bytes to a file. Node only; throws elsewhere. */
+    saveTo(path: string): Promise<void>;
+}
+/** A site preview: the poster frame and the scrolling video. */
+export interface SitePreviewResult {
+    poster: Uint8Array;
+    video: Uint8Array;
+    credits: number;
+    renderMs: number;
+    outputSeconds: number;
+    cached: boolean;
+    requestId: string;
+    headers: Headers;
+}
+export interface WaitOptions extends RequestOptions {
+    /** How often to poll. Default 2s. */
+    pollMs?: number;
+    /** Give up after this long. Default 10 minutes. */
+    timeoutMs?: number;
+}
+export declare class Renderwolf {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    constructor(opts: ClientOptions);
+    screenshot(req: ScreenshotRequest, opts?: RequestOptions): Promise<RenderResult>;
+    pdf(req: PdfRequest, opts?: RequestOptions): Promise<RenderResult>;
+    qr(req: QrRequest, opts?: RequestOptions): Promise<RenderResult>;
+    /** 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>;
+    sitePreview(req: SitePreviewRequest, opts?: RequestOptions): Promise<SitePreviewResult>;
+    private render;
+    readonly jobs: {
+        /**
+         * Submit a durable job. Pass `idempotencyKey` to make a retry of the same
+         * submission return the same job instead of a second one.
+         */
+        submit: (sub: JobSubmission, opts?: RequestOptions & {
+            idempotencyKey?: string;
+        }) => Promise<Job>;
+        get: (id: string, opts?: RequestOptions) => Promise<Job>;
+        list: (params?: {
+            status?: string;
+            cursor?: string;
+            limit?: number;
+        }, opts?: RequestOptions) => Promise<{
+            jobs: Job[];
+            next_cursor?: string;
+        }>;
+        cancel: (id: string, opts?: RequestOptions) => Promise<Job>;
+        /** Download a succeeded job's result. */
+        result: (id: string, opts?: RequestOptions) => Promise<RenderResult>;
+        /** Poll until the job is terminal. Resolves with the job whatever the outcome; check `status`. */
+        wait: (id: string, opts?: WaitOptions) => Promise<Job>;
+    };
+    readonly destinations: {
+        /**
+         * Register where finished jobs go. A webhook destination's
+         * `signing_secret` is returned here once and never again; keep it.
+         */
+        create: (dest: DestinationDraft, opts?: RequestOptions) => Promise<Destination>;
+        list: (opts?: RequestOptions) => Promise<{
+            destinations: Destination[];
+        }>;
+        /** Reach the destination now; a failure is reported in the body, not thrown. */
+        test: (id: string, opts?: RequestOptions) => Promise<{
+            ok: boolean;
+            error?: string;
+        }>;
+        remove: (id: string, opts?: RequestOptions) => Promise<void>;
+    };
+    /** Mint a signed render URL that an <img> or an email can fetch directly. */
+    sign(req: SignRequest, opts?: RequestOptions): Promise<SignedUrl>;
+    usage(opts?: RequestOptions): Promise<Usage>;
+    /** Request history for the last seven days. */
+    requests(filter?: RequestFilter, opts?: RequestOptions): Promise<{
+        requests: RequestRecord[];
+        retention_days: number;
+    }>;
+    private send;
+}

package/dist/client.js

@@ -0,0 +1,257 @@
+import { RenderwolfError } from './errors.js';
+export const VERSION = '0.1.0';
+export class Renderwolf {
+    apiKey;
+    baseUrl;
+    timeoutMs;
+    fetchImpl;
+    constructor(opts) {
+        if (!opts.apiKey) {
+            throw new RenderwolfError('an API key is required', { status: 0, code: 'missing_api_key' });
+        }
+        this.apiKey = opts.apiKey;
+        this.baseUrl = (opts.baseUrl ?? 'https://api.ironfang.uk/renderwolf').replace(/\/+$/, '');
+        this.timeoutMs = opts.timeoutMs ?? 90_000;
+        this.fetchImpl = opts.fetch ?? globalThis.fetch;
+    }
+    /* ------------------------------ renders ------------------------------ */
+    screenshot(req, opts = {}) {
+        return this.render('/v1/screenshot', req, opts);
+    }
+    pdf(req, opts = {}) {
+        return this.render('/v1/pdf', req, opts);
+    }
+    qr(req, opts = {}) {
+        return this.render('/v1/qr', req, opts);
+    }
+    /** Render one of your stored templates with variables filled in. */
+    image(templateId, req = {}, opts = {}) {
+        return this.render(`/v1/image/${encodeURIComponent(templateId)}`, req, opts);
+    }
+    clip(req, opts = {}) {
+        return this.render('/v1/video', req, opts);
+    }
+    async sitePreview(req, opts = {}) {
+        const resp = await this.send('POST', '/v1/site-preview', req, opts);
+        const form = await resp.formData();
+        const poster = form.get('poster');
+        const video = form.get('video');
+        if (!(poster instanceof Blob) || !(video instanceof Blob)) {
+            throw new RenderwolfError('the response did not include both preview files', {
+                status: resp.status, code: 'bad_response', requestId: requestIdOf(resp),
+            });
+        }
+        return {
+            poster: new Uint8Array(await poster.arrayBuffer()),
+            video: new Uint8Array(await video.arrayBuffer()),
+            credits: num(resp.headers.get('X-Renderwolf-Credits')),
+            renderMs: num(resp.headers.get('X-Renderwolf-Render-Ms')),
+            outputSeconds: num(resp.headers.get('X-Renderwolf-Output-Seconds')),
+            cached: resp.headers.get('X-Renderwolf-Cache') === 'hit',
+            requestId: requestIdOf(resp),
+            headers: resp.headers,
+        };
+    }
+    async render(path, body, opts) {
+        const resp = await this.send('POST', path, body, opts);
+        const bytes = new Uint8Array(await resp.arrayBuffer());
+        return {
+            bytes,
+            contentType: (resp.headers.get('Content-Type') ?? 'application/octet-stream').split(';')[0].trim(),
+            credits: num(resp.headers.get('X-Renderwolf-Credits')),
+            renderMs: num(resp.headers.get('X-Renderwolf-Render-Ms')),
+            cached: resp.headers.get('X-Renderwolf-Cache') === 'hit',
+            requestId: requestIdOf(resp),
+            headers: resp.headers,
+            saveTo: (target) => saveBytes(target, bytes),
+        };
+    }
+    /* -------------------------------- jobs -------------------------------- */
+    jobs = {
+        /**
+         * Submit a durable job. Pass `idempotencyKey` to make a retry of the same
+         * submission return the same job instead of a second one.
+         */
+        submit: async (sub, opts = {}) => {
+            const headers = {};
+            if (opts.idempotencyKey)
+                headers['Idempotency-Key'] = opts.idempotencyKey;
+            const resp = await this.send('POST', '/v1/jobs', sub, opts, headers);
+            return (await resp.json());
+        },
+        get: async (id, opts = {}) => {
+            const resp = await this.send('GET', `/v1/jobs/${encodeURIComponent(id)}`, undefined, opts);
+            return (await resp.json());
+        },
+        list: async (params = {}, opts = {}) => {
+            const resp = await this.send('GET', '/v1/jobs' + query(params), undefined, opts);
+            return (await resp.json());
+        },
+        cancel: async (id, opts = {}) => {
+            const resp = await this.send('DELETE', `/v1/jobs/${encodeURIComponent(id)}`, undefined, opts);
+            return (await resp.json());
+        },
+        /** Download a succeeded job's result. */
+        result: async (id, opts = {}) => {
+            const resp = await this.send('GET', `/v1/jobs/${encodeURIComponent(id)}/result`, undefined, opts);
+            const bytes = new Uint8Array(await resp.arrayBuffer());
+            return {
+                bytes,
+                contentType: (resp.headers.get('Content-Type') ?? 'application/octet-stream').split(';')[0].trim(),
+                credits: 0,
+                renderMs: 0,
+                cached: false,
+                requestId: requestIdOf(resp),
+                headers: resp.headers,
+                saveTo: (target) => saveBytes(target, bytes),
+            };
+        },
+        /** Poll until the job is terminal. Resolves with the job whatever the outcome; check `status`. */
+        wait: async (id, opts = {}) => {
+            const pollMs = opts.pollMs ?? 2_000;
+            const deadline = Date.now() + (opts.timeoutMs ?? 600_000);
+            for (;;) {
+                const job = await this.jobs.get(id, { ...(opts.signal ? { signal: opts.signal } : {}) });
+                if (job.status === 'succeeded' || job.status === 'failed' || job.status === 'cancelled') {
+                    return job;
+                }
+                if (Date.now() >= deadline) {
+                    throw new RenderwolfError(`job ${id} did not finish within the wait timeout`, { status: 0, code: 'timeout' });
+                }
+                await sleep(pollMs, opts.signal);
+            }
+        },
+    };
+    /* --------------------------- destinations ---------------------------- */
+    destinations = {
+        /**
+         * Register where finished jobs go. A webhook destination's
+         * `signing_secret` is returned here once and never again; keep it.
+         */
+        create: async (dest, opts = {}) => {
+            const resp = await this.send('POST', '/v1/destinations', dest, opts);
+            return (await resp.json());
+        },
+        list: async (opts = {}) => {
+            const resp = await this.send('GET', '/v1/destinations', undefined, opts);
+            return (await resp.json());
+        },
+        /** Reach the destination now; a failure is reported in the body, not thrown. */
+        test: async (id, opts = {}) => {
+            const resp = await this.send('POST', `/v1/destinations/${encodeURIComponent(id)}/test`, undefined, opts);
+            return (await resp.json());
+        },
+        remove: async (id, opts = {}) => {
+            await this.send('DELETE', `/v1/destinations/${encodeURIComponent(id)}`, undefined, opts);
+        },
+    };
+    /* ------------------------------ the rest ------------------------------ */
+    /** Mint a signed render URL that an <img> or an email can fetch directly. */
+    async sign(req, opts = {}) {
+        const resp = await this.send('POST', '/v1/sign', req, opts);
+        return (await resp.json());
+    }
+    async usage(opts = {}) {
+        const resp = await this.send('GET', '/v1/usage', undefined, opts);
+        return (await resp.json());
+    }
+    /** Request history for the last seven days. */
+    async requests(filter = {}, opts = {}) {
+        const resp = await this.send('GET', '/v1/requests' + query(filter), undefined, opts);
+        return (await resp.json());
+    }
+    /* ------------------------------ transport ------------------------------ */
+    async send(method, path, body, opts, extra = {}) {
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            Accept: 'application/json, */*',
+            'X-Ironfang-Client': `renderwolf-js/${VERSION}`,
+            ...extra,
+        };
+        if (body !== undefined)
+            headers['Content-Type'] = 'application/json';
+        if (opts.requestId)
+            headers['X-Request-ID'] = opts.requestId;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(new DOMException('timeout', 'TimeoutError')), opts.timeoutMs ?? this.timeoutMs);
+        const onAbort = () => controller.abort(opts.signal?.reason);
+        opts.signal?.addEventListener('abort', onAbort, { once: true });
+        if (opts.signal?.aborted)
+            onAbort();
+        let resp;
+        try {
+            resp = await this.fetchImpl(this.baseUrl + path, {
+                method, headers, signal: controller.signal,
+                ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+            });
+        }
+        catch (err) {
+            // No retry here on purpose: a synchronous render that timed out may
+            // have been charged, and retrying it blind doubles the bill.
+            if (controller.signal.aborted) {
+                const reason = controller.signal.reason;
+                const timedOut = reason instanceof DOMException && reason.name === 'TimeoutError';
+                throw new RenderwolfError(timedOut ? `request timed out after ${opts.timeoutMs ?? this.timeoutMs}ms` : 'request aborted', { status: 0, code: timedOut ? 'timeout' : 'aborted' });
+            }
+            throw new RenderwolfError(err instanceof Error ? err.message : 'network error', { status: 0, code: 'network_error' });
+        }
+        finally {
+            clearTimeout(timer);
+            opts.signal?.removeEventListener('abort', onAbort);
+        }
+        if (!resp.ok) {
+            throw await errorFrom(resp);
+        }
+        return resp;
+    }
+}
+async function errorFrom(resp) {
+    let code = `http_${resp.status}`;
+    let message = `request failed with HTTP ${resp.status}`;
+    try {
+        const body = (await resp.json());
+        if (body?.error?.code)
+            code = body.error.code;
+        if (body?.error?.message)
+            message = body.error.message;
+    }
+    catch {
+        // Not JSON; the status is all there is.
+    }
+    return new RenderwolfError(message, { status: resp.status, code, requestId: requestIdOf(resp) });
+}
+function requestIdOf(resp) {
+    return resp.headers.get('X-Ironfang-Request-ID') ?? '';
+}
+function num(v) {
+    const n = Number(v ?? 0);
+    return Number.isFinite(n) ? n : 0;
+}
+function query(params) {
+    const q = new URLSearchParams();
+    for (const [k, v] of Object.entries(params)) {
+        if (v !== undefined && v !== null && v !== '')
+            q.set(k, String(v));
+    }
+    const s = q.toString();
+    return s ? `?${s}` : '';
+}
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted)
+            return reject(new RenderwolfError('wait aborted', { status: 0, code: 'aborted' }));
+        const t = setTimeout(() => { signal?.removeEventListener('abort', onAbort); resolve(); }, ms);
+        const onAbort = () => { clearTimeout(t); reject(new RenderwolfError('wait aborted', { status: 0, code: 'aborted' })); };
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+async function saveBytes(path, bytes) {
+    let fs;
+    try {
+        fs = await import('node:fs/promises');
+    }
+    catch {
+        throw new RenderwolfError('saveTo needs a filesystem; use the bytes directly here', { status: 0, code: 'unsupported' });
+    }
+    await fs.writeFile(path, bytes);
+}

package/dist/errors.d.ts

@@ -0,0 +1,20 @@
+/**
+ * An error the API returned, or a failure to reach it.
+ *
+ * `code` is the API's stable error code (`bad_request`, `quota_exhausted`,
+ * `render_failed`, ...) or a client-side one (`network_error`, `timeout`,
+ * `aborted`). `requestId` is the id to quote to support; it is on every
+ * response the server produced, including errors.
+ */
+export declare class RenderwolfError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly requestId: string | undefined;
+    constructor(message: string, opts: {
+        status: number;
+        code: string;
+        requestId?: string | undefined;
+    });
+    /** The request was refused before any work was done. */
+    get isClientError(): boolean;
+}

package/dist/errors.js

@@ -0,0 +1,24 @@
+/**
+ * An error the API returned, or a failure to reach it.
+ *
+ * `code` is the API's stable error code (`bad_request`, `quota_exhausted`,
+ * `render_failed`, ...) or a client-side one (`network_error`, `timeout`,
+ * `aborted`). `requestId` is the id to quote to support; it is on every
+ * response the server produced, including errors.
+ */
+export class RenderwolfError extends Error {
+    status;
+    code;
+    requestId;
+    constructor(message, opts) {
+        super(message);
+        this.name = 'RenderwolfError';
+        this.status = opts.status;
+        this.code = opts.code;
+        this.requestId = opts.requestId;
+    }
+    /** The request was refused before any work was done. */
+    get isClientError() {
+        return this.status >= 400 && this.status < 500;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { Renderwolf, VERSION } from './client.js';
+export type { ClientOptions, RequestOptions, RenderResult, SitePreviewResult, WaitOptions } from './client.js';
+export { RenderwolfError } from './errors.js';
+export { verifyWebhook, signWebhook } from './webhook.js';
+export type { WebhookInput } from './webhook.js';
+export type * from './types.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { Renderwolf, VERSION } from './client.js';
+export { RenderwolfError } from './errors.js';
+export { verifyWebhook, signWebhook } from './webhook.js';

package/dist/types.d.ts

@@ -0,0 +1,243 @@
+/** Options shared by every browser-driven render. */
+export interface RenderCommon {
+    no_cache?: boolean;
+    block_ads?: boolean;
+    block_cookie_banners?: boolean;
+    hide_selectors?: string[];
+    headers?: Record<string, string>;
+    cookies?: {
+        name: string;
+        value?: string;
+        domain: string;
+        path?: string;
+    }[];
+    authorization?: string;
+    user_agent?: string;
+    wait_until?: 'load' | 'domcontentloaded' | 'networkidle';
+    wait_for_selector?: string;
+    timeout_ms?: number;
+    device_scale_factor?: number;
+}
+export interface ScreenshotRequest extends RenderCommon {
+    url?: string;
+    html?: string;
+    width?: number;
+    height?: number;
+    full_page?: boolean;
+    full_page_max_height?: number;
+    selector?: string;
+    clip?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    omit_background?: boolean;
+    dark_mode?: boolean;
+    format?: 'png' | 'jpeg' | 'webp';
+    quality?: number;
+    device?: 'desktop' | 'tablet' | 'mobile';
+    delay_ms?: number;
+}
+export interface PdfRequest extends RenderCommon {
+    url?: string;
+    html?: string;
+    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;
+}
+export interface QrRequest {
+    data: string;
+    size?: number;
+    ecc?: 'L' | 'M' | 'Q' | 'H';
+    dark?: string;
+    light?: string;
+    dots?: 'square' | 'circle';
+    eyes?: 'square' | 'rounded';
+    margin?: number;
+    invert?: boolean;
+    logo?: string;
+    logo_url?: string;
+    logo_size?: number;
+    logo_pad?: boolean;
+}
+export interface ImageRequest {
+    vars?: Record<string, unknown>;
+    format?: 'png' | 'jpeg' | 'webp';
+}
+export interface ClipRequest {
+    size?: 'vertical' | 'square' | 'landscape' | '720p';
+    duration?: number;
+    colour?: string;
+    background?: string;
+    watermark?: string;
+    audio?: string;
+    font_size?: number;
+    captions?: {
+        text: string;
+        start?: number;
+        end?: number;
+    }[];
+}
+export interface SitePreviewRequest extends RenderCommon {
+    url: string;
+    width?: number;
+    height?: number;
+    motion?: 'per_page' | 'single_sweep';
+    dark_mode?: boolean;
+    device?: 'desktop' | 'tablet' | 'mobile';
+    delay_ms?: number;
+}
+export type JobKind = 'screenshot' | 'pdf' | 'qr' | 'image' | 'clip' | 'site_preview';
+export type JobStatus = 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled';
+export interface JobDelivery {
+    webhook_destination?: string;
+    storage_destination?: string;
+    storage_key?: string;
+}
+export interface JobSubmission {
+    kind: JobKind;
+    request: Record<string, unknown>;
+    external_id?: string;
+    delivery?: JobDelivery;
+}
+export interface Job {
+    id: string;
+    kind: JobKind;
+    status: JobStatus;
+    external_id?: string;
+    batch_id?: string;
+    cancel_requested: boolean;
+    attempts: number;
+    created_at: string;
+    queued_at: string;
+    started_at?: string | null;
+    completed_at?: string | null;
+    credits: {
+        reserved: number;
+        charged: number;
+        refunded: number;
+    };
+    request_summary?: Record<string, unknown>;
+    delivery?: JobDelivery;
+    error?: {
+        code: string;
+        message: string;
+    };
+    result?: {
+        available: boolean;
+        content_type: string;
+        bytes: number;
+        sha256: string;
+        expires_at?: string | null;
+        url?: string;
+        url_expires_at?: string;
+    };
+}
+export interface SignRequest {
+    kind: 'screenshot' | 'image';
+    url?: string;
+    template?: string;
+    vars?: Record<string, unknown>;
+    width?: number;
+    height?: number;
+    full_page?: boolean;
+    ttl_hours?: number;
+}
+export interface SignedUrl {
+    url: string;
+    path: string;
+}
+export interface Usage {
+    period: string;
+    credits: number;
+    renders: number;
+    limit: number;
+    period_start: string;
+    period_end: string;
+    by_kind?: Record<string, {
+        credits: number;
+        count: number;
+    }>;
+    unattributed?: number;
+    daily?: {
+        day: string;
+        credits: number;
+        by_kind?: Record<string, number>;
+    }[];
+}
+/** One row of request history: what was asked for and what happened, never the values. */
+export interface RequestRecord {
+    id: string;
+    api_key_id?: string;
+    external_id?: string;
+    source: 'api' | 'dashboard' | 'delegated' | 'job';
+    kind: string;
+    job_id?: string;
+    batch_id?: string;
+    status: number;
+    outcome: 'ok' | 'error' | 'cancelled';
+    error_code?: string;
+    cache_hit: boolean;
+    credits_charged: number;
+    credits_refunded: number;
+    response_bytes: number;
+    content_type?: string;
+    duration_ms: number;
+    target_origin?: string;
+    target_path?: string;
+    option_fields: string[];
+    client?: string;
+    created_at: string;
+}
+export interface RequestFilter {
+    since?: string;
+    until?: string;
+    outcome?: 'ok' | 'error' | 'cancelled';
+    kind?: string;
+    cache?: 'hit' | 'miss';
+    key?: string;
+    error?: string;
+    id?: string;
+    limit?: number;
+    offset?: number;
+}
+export type DestinationDraft = {
+    type: 'webhook';
+    name: string;
+    url: string;
+} | {
+    type: 's3';
+    name: string;
+    endpoint?: string;
+    region: string;
+    bucket: string;
+    prefix?: string;
+    path_style?: boolean;
+    access_key: string;
+    secret_key: string;
+    session_token?: string;
+};
+export interface Destination {
+    id: string;
+    type: 'webhook' | 's3';
+    name: string;
+    enabled: boolean;
+    created_at?: string;
+    url?: string;
+    endpoint?: string;
+    region?: string;
+    bucket?: string;
+    prefix?: string;
+    /** Present on a webhook destination's creation response only. */
+    signing_secret?: string;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/webhook.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Verify a Renderwolf webhook delivery.
+ *
+ * Renderwolf signs each delivery with HMAC-SHA256 over `<timestamp>.<raw body>`
+ * using your endpoint's signing secret, and sends the result as
+ * `Renderwolf-Signature: v1=<hex>` with `Renderwolf-Timestamp` beside it. The
+ * check must run over the raw bytes as received: re-serialising parsed JSON
+ * changes them and the signature will not match.
+ */
+export interface WebhookInput {
+    /** The endpoint's signing secret, shown once when the destination was created. */
+    secret: string;
+    /** The `Renderwolf-Timestamp` header. */
+    timestamp: string;
+    /** The `Renderwolf-Signature` header. */
+    signature: string;
+    /** The request body exactly as received. */
+    payload: Uint8Array | string;
+    /**
+     * Reject deliveries whose timestamp is further than this from now, so a
+     * captured delivery cannot be replayed later. Default five minutes; pass
+     * 0 to skip the check (for tests with fixed timestamps).
+     */
+    toleranceSeconds?: number;
+    /** Override the clock, for tests. Seconds since the epoch. */
+    now?: number;
+}
+export declare function verifyWebhook(input: WebhookInput): Promise<boolean>;
+/** Compute the signature Renderwolf would send. Exposed for tests and for tooling that replays deliveries. */
+export declare function signWebhook(secret: string, timestamp: string, payload: Uint8Array | string): Promise<string>;

package/dist/webhook.js

@@ -0,0 +1,32 @@
+const encoder = new TextEncoder();
+export async function verifyWebhook(input) {
+    const tolerance = input.toleranceSeconds ?? 300;
+    if (tolerance > 0) {
+        const ts = Number(input.timestamp);
+        const now = input.now ?? Math.floor(Date.now() / 1000);
+        if (!Number.isFinite(ts) || Math.abs(now - ts) > tolerance) {
+            return false;
+        }
+    }
+    const expected = await signWebhook(input.secret, input.timestamp, input.payload);
+    return constantTimeEqual(expected, input.signature.trim());
+}
+/** Compute the signature Renderwolf would send. Exposed for tests and for tooling that replays deliveries. */
+export async function signWebhook(secret, timestamp, payload) {
+    const key = await crypto.subtle.importKey('raw', encoder.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    const body = typeof payload === 'string' ? encoder.encode(payload) : payload;
+    const signed = new Uint8Array(encoder.encode(timestamp + '.').length + body.length);
+    signed.set(encoder.encode(timestamp + '.'), 0);
+    signed.set(body, encoder.encode(timestamp + '.').length);
+    const mac = new Uint8Array(await crypto.subtle.sign('HMAC', key, signed));
+    return 'v1=' + Array.from(mac, (b) => b.toString(16).padStart(2, '0')).join('');
+}
+function constantTimeEqual(a, b) {
+    const x = encoder.encode(a);
+    const y = encoder.encode(b);
+    let diff = x.length ^ y.length;
+    for (let i = 0; i < Math.max(x.length, y.length); i++) {
+        diff |= (x[i] ?? 0) ^ (y[i] ?? 0);
+    }
+    return diff === 0;
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@ironfang/renderwolf",
+  "version": "0.1.0",
+  "description": "Renderwolf API client: screenshots, PDFs, QR codes, template images, clips and site previews from a URL or HTML.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "tsc -p tsconfig.test.json && node --test --test-reporter=spec dist-test/test/*.test.js",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "typescript": "^5.9.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ironfang-ltd/renderwolf-js"
+  },
+  "homepage": "https://ironfang.uk/renderwolf",
+  "keywords": [
+    "screenshot",
+    "pdf",
+    "qr",
+    "html-to-image",
+    "renderwolf",
+    "ironfang"
+  ]
+}