@websitescreenshotworld/sdk 0.0.0-stage → 0.1.0

package/dist/cjs/webhooks/parse-event.d.ts

@@ -0,0 +1,10 @@
+import type { WebhookEvent } from "./events.js";
+export interface WireEnvelope {
+    id: string;
+    type: string;
+    created_at: string;
+    product: string;
+    data: unknown;
+}
+/** Turns a verified webhook body into its typed event. */
+export declare function parseEvent(wire: WireEnvelope): WebhookEvent;

package/dist/cjs/webhooks/parse-event.js

@@ -0,0 +1,149 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseEvent = parseEvent;
+const capture_js_1 = require("../models/capture.js");
+const wire_js_1 = require("../wire.js");
+/** Turns a verified webhook body into its typed event. */
+function parseEvent(wire) {
+    const { type, product, data } = wire;
+    const envelope = { id: wire.id, createdAt: (0, wire_js_1.parseDate)(wire.created_at) };
+    if (type === "capture.succeeded" || type === "capture.failed") {
+        if (product === "instant_snap") {
+            const capture = instantSnapCapture(data);
+            return { ...envelope, type, product, data: capture };
+        }
+        if (product === "auto_schedule") {
+            const capture = scheduledCapture(data);
+            return { ...envelope, type, product, data: capture };
+        }
+    }
+    switch (type) {
+        case "delivery.completed":
+            return {
+                ...envelope,
+                type,
+                product: "auto_schedule",
+                data: deliveryCompleted(data),
+            };
+        case "capture.changed":
+            return {
+                ...envelope,
+                type,
+                product: "auto_schedule",
+                data: captureChanged(data),
+            };
+        case "schedule.paused":
+            return {
+                ...envelope,
+                type,
+                product: "auto_schedule",
+                data: schedulePaused(data),
+            };
+        case "sitemap_run.completed":
+            return {
+                ...envelope,
+                type,
+                product: "auto_schedule",
+                data: sitemapRunCompleted(data),
+            };
+        case "ping":
+            return { ...envelope, type, product, data: ping(data) };
+        default:
+            // Includes a known capture type from a product this version does not know.
+            return {
+                ...envelope,
+                type,
+                product,
+                rawData: data,
+            };
+    }
+}
+function instantSnapCapture(wire) {
+    return {
+        ...(0, capture_js_1.parseCaptureFields)(wire),
+        pageSource: wire.page_source
+            ? (0, capture_js_1.parsePageSourceFields)(wire.page_source)
+            : null,
+        s3Delivery: wire.s3_delivery
+            ? (0, capture_js_1.parseS3DeliveryFields)(wire.s3_delivery)
+            : null,
+    };
+}
+function scheduledCapture(wire) {
+    return {
+        id: wire.id,
+        scheduleId: wire.schedule_id,
+        scheduleName: wire.schedule_name,
+        url: wire.url,
+        status: wire.status,
+        mediaCategory: wire.media_category,
+        format: wire.format ?? null,
+        pageHttpStatus: wire.page_http_status ?? null,
+        capturedAt: (0, wire_js_1.parseDate)(wire.captured_at),
+        finalUrl: wire.final_url ?? null,
+        mediaSha256: wire.media_sha256 ?? null,
+        pageSource: wire.page_source
+            ? {
+                format: wire.page_source.format,
+                sha256: wire.page_source.sha256 ?? null,
+            }
+            : null,
+        sitemapRunId: wire.sitemap_run_id ?? null,
+    };
+}
+function deliveryCompleted(wire) {
+    return {
+        ...scheduledCapture(wire),
+        destinations: (wire.destinations ?? []).map((destination) => ({
+            slot: destination.slot,
+            name: destination.name,
+            provider: destination.provider,
+            status: destination.status,
+            completedAt: (0, wire_js_1.parseDate)(destination.completed_at),
+        })),
+    };
+}
+function captureChanged(wire) {
+    return {
+        ...scheduledCapture(wire),
+        changePercent: wire.change_percent ?? null,
+        comparedToCaptureId: wire.compared_to_capture_id ?? null,
+        changeImageAvailable: wire.change_image_available ?? false,
+    };
+}
+function schedulePaused(wire) {
+    return {
+        scheduleId: wire.schedule_id,
+        scheduleName: wire.schedule_name,
+        url: wire.url,
+        reason: wire.reason,
+        pausedAt: (0, wire_js_1.parseDate)(wire.paused_at),
+    };
+}
+function sitemapRunCompleted(wire) {
+    return {
+        sitemapRunId: wire.sitemap_run_id,
+        scheduleId: wire.schedule_id,
+        scheduleName: wire.schedule_name,
+        sitemapUrl: wire.sitemap_url,
+        status: wire.status,
+        runAt: (0, wire_js_1.parseDate)(wire.run_at),
+        completedAt: (0, wire_js_1.parseDate)(wire.completed_at),
+        pagesListed: wire.pages_listed ?? null,
+        pagesMatched: wire.pages_matched ?? null,
+        pagesQueued: wire.pages_queued ?? null,
+        pagesSucceeded: wire.pages_succeeded ?? null,
+        pagesFailed: wire.pages_failed ?? null,
+        pagesOverLimit: wire.pages_over_limit ?? null,
+        pagesOverQuota: wire.pages_over_quota ?? null,
+        message: wire.message ?? null,
+    };
+}
+function ping(wire) {
+    return {
+        endpointId: wire.endpoint_id,
+        endpointName: wire.endpoint_name,
+        message: wire.message,
+        sentAt: (0, wire_js_1.parseDate)(wire.sent_at),
+    };
+}

package/dist/cjs/webhooks/webhook.d.ts

@@ -0,0 +1,26 @@
+import type { WebhookEvent } from "./events.js";
+/** Options for {@link Webhook.verify}. */
+export interface VerifyOptions {
+    /** How far the signature's timestamp may be from now, in seconds. Default 300. */
+    tolerance?: number;
+    /** The time to check the timestamp against. Defaults to the current time. */
+    now?: Date;
+}
+/**
+ * Checks a webhook delivery's `X-WSW-Signature` header against its raw body and returns the event.
+ *
+ * Pass the body exactly as received. A framework that parses the JSON and serialises it again
+ * changes the bytes, and the signature no longer matches.
+ *
+ * @param payload - The raw request body.
+ * @param signatureHeader - The `X-WSW-Signature` header.
+ * @param secret - The endpoint's signing secret, starting `whsec_`.
+ * @throws {@link SignatureVerificationError} when the header is missing or malformed, the timestamp
+ * is outside the tolerance, or no signature matches.
+ */
+declare function verify(payload: string | Uint8Array, signatureHeader: string | readonly string[] | null | undefined, secret: string, options?: VerifyOptions): WebhookEvent;
+/** Verifies webhook deliveries from both products. */
+export declare const Webhook: {
+    readonly verify: typeof verify;
+};
+export {};

package/dist/cjs/webhooks/webhook.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Webhook = void 0;
+const node_crypto_1 = require("node:crypto");
+const errors_js_1 = require("../errors.js");
+const parse_event_js_1 = require("./parse-event.js");
+const DEFAULT_TOLERANCE_SECONDS = 300;
+const SIGNATURE_HEX = /^[0-9a-f]{64}$/;
+/**
+ * Checks a webhook delivery's `X-WSW-Signature` header against its raw body and returns the event.
+ *
+ * Pass the body exactly as received. A framework that parses the JSON and serialises it again
+ * changes the bytes, and the signature no longer matches.
+ *
+ * @param payload - The raw request body.
+ * @param signatureHeader - The `X-WSW-Signature` header.
+ * @param secret - The endpoint's signing secret, starting `whsec_`.
+ * @throws {@link SignatureVerificationError} when the header is missing or malformed, the timestamp
+ * is outside the tolerance, or no signature matches.
+ */
+function verify(payload, signatureHeader, secret, options = {}) {
+    const header = parseSignatureHeader(typeof signatureHeader === "string"
+        ? signatureHeader
+        : (signatureHeader ?? []).join(","));
+    if (header.timestamp === null) {
+        throw new errors_js_1.SignatureVerificationError("The signature header has no valid timestamp.");
+    }
+    if (header.signatures.length === 0) {
+        throw new errors_js_1.SignatureVerificationError("The signature header has no v1 signature.");
+    }
+    const tolerance = options.tolerance ?? DEFAULT_TOLERANCE_SECONDS;
+    const now = Math.floor((options.now ?? new Date()).getTime() / 1000);
+    if (Math.abs(now - header.timestamp) > tolerance) {
+        throw new errors_js_1.SignatureVerificationError("The signature's timestamp is outside the tolerance.");
+    }
+    const body = typeof payload === "string" ? Buffer.from(payload, "utf8") : payload;
+    const expected = Buffer.from((0, node_crypto_1.createHmac)("sha256", Buffer.from(secret, "utf8"))
+        .update(`${String(header.timestamp)}.`, "utf8")
+        .update(body)
+        .digest("hex"), "utf8");
+    const matches = header.signatures.some((signature) => (0, node_crypto_1.timingSafeEqual)(expected, Buffer.from(signature, "utf8")));
+    if (!matches) {
+        throw new errors_js_1.SignatureVerificationError("No signature in the header matches the body.");
+    }
+    return (0, parse_event_js_1.parseEvent)(parseBody(new TextDecoder().decode(body)));
+}
+function parseSignatureHeader(value) {
+    const header = { timestamp: null, signatures: [] };
+    let sawTimestamp = false;
+    for (const part of value.split(",")) {
+        const separator = part.indexOf("=");
+        if (separator === -1)
+            continue;
+        const name = part.slice(0, separator).trim();
+        const content = part.slice(separator + 1).trim();
+        if (name === "t" && !sawTimestamp) {
+            sawTimestamp = true;
+            header.timestamp = /^\d+$/.test(content) ? Number(content) : null;
+        }
+        else if (name === "v1") {
+            const signature = content.toLowerCase();
+            // A value that cannot be a digest is skipped so the comparison always sees equal lengths.
+            if (SIGNATURE_HEX.test(signature))
+                header.signatures.push(signature);
+        }
+    }
+    return header;
+}
+function parseBody(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch (cause) {
+        throw new errors_js_1.WebsiteScreenshotWorldError("The webhook body is signed but is not JSON.", { cause });
+    }
+}
+/** Verifies webhook deliveries from both products. */
+exports.Webhook = { verify };

package/dist/cjs/wire.d.ts

@@ -0,0 +1,15 @@
+/** A JSON object as the API sends or receives it, with snake_case keys. */
+export type WireObject = Record<string, unknown>;
+/**
+ * Turns camelCase options into the API's snake_case body. Options left `undefined` or `null` are not
+ * sent; `false`, `0` and `""` are.
+ */
+export declare function toWire(options: object): WireObject;
+/** Re-cases the keys of an object the library does not model field by field. */
+export declare function camelCaseKeys(value: unknown): unknown;
+/**
+ * Parses an ISO 8601 date-time with any number of fraction digits and either `Z` or an offset.
+ * Returns `null` for `null` or a missing value.
+ */
+export declare function parseDate(value: string): Date;
+export declare function parseDate(value: string | null | undefined): Date | null;

package/dist/cjs/wire.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toWire = toWire;
+exports.camelCaseKeys = camelCaseKeys;
+exports.parseDate = parseDate;
+/** Maps whose keys are data, not field names, and so are never re-cased. */
+const VERBATIM_KEYS = new Set(["headers", "cookies"]);
+function isPlainObject(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        !(value instanceof Date));
+}
+function snakeCase(key) {
+    return key.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
+}
+function camelCase(key) {
+    return key.replace(/_([a-z0-9])/g, (_, letter) => letter.toUpperCase());
+}
+function withoutUnset(map) {
+    return Object.fromEntries(Object.entries(map).filter(([, value]) => value !== undefined));
+}
+/**
+ * Turns camelCase options into the API's snake_case body. Options left `undefined` or `null` are not
+ * sent; `false`, `0` and `""` are.
+ */
+function toWire(options) {
+    const body = {};
+    for (const [key, value] of Object.entries(options)) {
+        if (value === undefined || value === null)
+            continue;
+        if (VERBATIM_KEYS.has(key) && isPlainObject(value)) {
+            body[snakeCase(key)] = withoutUnset(value);
+        }
+        else if (isPlainObject(value)) {
+            body[snakeCase(key)] = toWire(value);
+        }
+        else {
+            body[snakeCase(key)] = value;
+        }
+    }
+    return body;
+}
+/** Re-cases the keys of an object the library does not model field by field. */
+function camelCaseKeys(value) {
+    if (Array.isArray(value))
+        return value.map(camelCaseKeys);
+    if (!isPlainObject(value))
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([key, inner]) => [
+        camelCase(key),
+        camelCaseKeys(inner),
+    ]));
+}
+const ISO_DATE_TIME = /^(\d{4}-\d{2}-\d{2})[T ](\d{2}:\d{2}:\d{2})(?:[.,](\d+))?(Z|[+-]\d{2}(?::?\d{2})?)$/i;
+function parseDate(value) {
+    if (value === null || value === undefined)
+        return null;
+    const match = ISO_DATE_TIME.exec(value);
+    if (match === null)
+        return new Date(value);
+    const [, date = "", time = "", fraction = "", zone = ""] = match;
+    const milliseconds = fraction.padEnd(3, "0").slice(0, 3);
+    return new Date(`${date}T${time}.${milliseconds}${normalizeZone(zone.toUpperCase())}`);
+}
+function normalizeZone(zone) {
+    if (zone === "Z")
+        return zone;
+    const digits = zone.slice(1).replace(":", "");
+    return `${zone[0] ?? "+"}${digits.slice(0, 2)}:${digits.slice(2, 4).padEnd(2, "0")}`;
+}

package/dist/esm/auto-schedule.d.ts

@@ -0,0 +1,20 @@
+import { type TriggerResult } from "./models/trigger-result.js";
+import type { RequestOptions, Transport } from "./transport.js";
+/** What {@link AutoSchedule} needs from the client. */
+export interface AutoScheduleConfig {
+    transport: Transport;
+    apiKey: string | undefined;
+    baseUrl: string;
+    timeout: number;
+}
+/** Scheduled captures of the web pages set up in the dashboard. */
+export declare class AutoSchedule {
+    #private;
+    /**
+     * Starts a web page's capture now. The outcome arrives by webhook. Calling again while that
+     * capture is pending starts nothing new and answers `already_pending`.
+     *
+     * @param webPageId - The web page's id, which webhooks call `scheduleId`.
+     */
+    triggerNow(webPageId: string, requestOptions?: RequestOptions): Promise<TriggerResult>;
+}

package/dist/esm/auto-schedule.js

@@ -0,0 +1,30 @@
+import { AuthenticationError } from "./errors.js";
+import { parseTriggerResult, } from "./models/trigger-result.js";
+/** Scheduled captures of the web pages set up in the dashboard. */
+export class AutoSchedule {
+    #config;
+    /** @internal Use `client.autoSchedule`. */
+    constructor(config) {
+        this.#config = config;
+    }
+    /**
+     * Starts a web page's capture now. The outcome arrives by webhook. Calling again while that
+     * capture is pending starts nothing new and answers `already_pending`.
+     *
+     * @param webPageId - The web page's id, which webhooks call `scheduleId`.
+     */
+    async triggerNow(webPageId, requestOptions = {}) {
+        const { apiKey, baseUrl, transport, timeout } = this.#config;
+        if (apiKey === undefined) {
+            throw new AuthenticationError("No Auto Schedule API key: pass autoScheduleApiKey to the client or set WSW_AUTO_SCHEDULE_API_KEY.");
+        }
+        const wire = await transport.json({
+            method: "POST",
+            url: `${baseUrl}/auto-schedule/v1/web-pages/${encodeURIComponent(webPageId)}/trigger-now`,
+            apiKey,
+            timeout: requestOptions.timeout ?? timeout,
+            signal: requestOptions.signal,
+        });
+        return parseTriggerResult(wire);
+    }
+}

package/dist/esm/client.d.ts

@@ -0,0 +1,41 @@
+import { AutoSchedule } from "./auto-schedule.js";
+import { InstantSnap } from "./instant-snap.js";
+/** Settings for {@link WebsiteScreenshotWorld}. Every one is optional. */
+export interface ClientOptions {
+    /** Defaults to the `WSW_INSTANT_SNAP_API_KEY` environment variable. */
+    instantSnapApiKey?: string;
+    /** Defaults to the `WSW_AUTO_SCHEDULE_API_KEY` environment variable. */
+    autoScheduleApiKey?: string;
+    /** Default `https://api.websitescreenshotworld.com`. */
+    instantSnapBaseUrl?: string;
+    /** Default `https://autoapi.websitescreenshotworld.com`. */
+    autoScheduleBaseUrl?: string;
+    /**
+     * Milliseconds a capture call may take, retries included. Default 180 000: the API itself may
+     * take up to 120 seconds.
+     */
+    captureTimeout?: number;
+    /** Milliseconds any other call may take, retries included. Default 30 000. */
+    timeout?: number;
+    /** How many times a failed attempt is retried when retrying can help. Default 2. */
+    maxRetries?: number;
+    /** A `fetch` to send requests with, for a proxy or instrumentation. Defaults to the global one. */
+    fetch?: typeof fetch;
+}
+/**
+ * The Website Screenshot World client. One client covers both products; either key may be left
+ * out, and calling a product without its key fails before anything is sent.
+ *
+ * @example
+ * ```ts
+ * const client = new WebsiteScreenshotWorld();
+ * const capture = await client.instantSnap.capture({ url: "https://example.com" });
+ * ```
+ */
+export declare class WebsiteScreenshotWorld {
+    /** On-demand captures. */
+    readonly instantSnap: InstantSnap;
+    /** Captures of scheduled web pages. */
+    readonly autoSchedule: AutoSchedule;
+    constructor(options?: ClientOptions);
+}

package/dist/esm/client.js

@@ -0,0 +1,54 @@
+import { AutoSchedule } from "./auto-schedule.js";
+import { InstantSnap } from "./instant-snap.js";
+import { Transport } from "./transport.js";
+import { VERSION } from "./version.js";
+const DEFAULT_INSTANT_SNAP_BASE_URL = "https://api.websitescreenshotworld.com";
+const DEFAULT_AUTO_SCHEDULE_BASE_URL = "https://autoapi.websitescreenshotworld.com";
+const DEFAULT_CAPTURE_TIMEOUT_MS = 180_000;
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_MAX_RETRIES = 2;
+/**
+ * The Website Screenshot World client. One client covers both products; either key may be left
+ * out, and calling a product without its key fails before anything is sent.
+ *
+ * @example
+ * ```ts
+ * const client = new WebsiteScreenshotWorld();
+ * const capture = await client.instantSnap.capture({ url: "https://example.com" });
+ * ```
+ */
+export class WebsiteScreenshotWorld {
+    /** On-demand captures. */
+    instantSnap;
+    /** Captures of scheduled web pages. */
+    autoSchedule;
+    constructor(options = {}) {
+        const transport = new Transport({
+            fetch: options.fetch,
+            maxRetries: options.maxRetries ?? DEFAULT_MAX_RETRIES,
+            userAgent: `websitescreenshotworld-node/${VERSION} (node ${process.versions.node})`,
+        });
+        const timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
+        this.instantSnap = new InstantSnap({
+            transport,
+            apiKey: apiKey(options.instantSnapApiKey, "WSW_INSTANT_SNAP_API_KEY"),
+            baseUrl: withoutTrailingSlash(options.instantSnapBaseUrl ?? DEFAULT_INSTANT_SNAP_BASE_URL),
+            timeout,
+            captureTimeout: options.captureTimeout ?? DEFAULT_CAPTURE_TIMEOUT_MS,
+        });
+        this.autoSchedule = new AutoSchedule({
+            transport,
+            apiKey: apiKey(options.autoScheduleApiKey, "WSW_AUTO_SCHEDULE_API_KEY"),
+            baseUrl: withoutTrailingSlash(options.autoScheduleBaseUrl ?? DEFAULT_AUTO_SCHEDULE_BASE_URL),
+            timeout,
+        });
+    }
+}
+/** The key given, else the environment's; an empty string counts as no key. */
+function apiKey(given, variable) {
+    const key = given === undefined || given === "" ? process.env[variable] : given;
+    return key === "" ? undefined : key;
+}
+function withoutTrailingSlash(url) {
+    return url.replace(/\/+$/, "");
+}

package/dist/esm/error-codes.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The `error_code` tokens the APIs answer with. Switch on these, never on the HTTP status or the
+ * message. A code added to the API later still comes through as a plain string.
+ */
+export declare const ErrorCode: {
+    readonly ApiKeyInvalid: "api_key_invalid";
+    readonly ValidationFailed: "validation_failed";
+    readonly S3DestinationInvalid: "s3_destination_invalid";
+    readonly WebPageIdInvalid: "web_page_id_invalid";
+    readonly IdempotencyKeyReused: "idempotency_key_reused";
+    /** The web page is a sitemap schedule, which runs only on its schedule. Not retried. */
+    readonly SitemapScheduleNotTriggerable: "sitemap_schedule_not_triggerable";
+    readonly QuotaExhausted: "quota_exhausted";
+    readonly FeatureNotAvailable: "feature_not_available";
+    readonly NoTriggerAllowance: "no_trigger_allowance";
+    readonly Forbidden: "forbidden";
+    readonly CaptureNotFound: "capture_not_found";
+    readonly WebPageNotFound: "web_page_not_found";
+    readonly NotFound: "not_found";
+    readonly RateLimited: "rate_limited";
+    /** Too many async captures are already waiting or running. Not retried. */
+    readonly QueueFull: "queue_full";
+    readonly CaptureFailed: "capture_failed";
+    readonly CaptureTimeout: "capture_timeout";
+    readonly PayloadTooLarge: "payload_too_large";
+    /** An async capture still waited for a browser 15 minutes after it was accepted. Not charged. */
+    readonly CaptureExpired: "capture_expired";
+    readonly CaptureBusy: "capture_busy";
+    readonly ServiceUnavailable: "service_unavailable";
+    readonly InternalError: "internal_error";
+    readonly RequestCancelled: "request_cancelled";
+    readonly IdempotencyKeyInUse: "idempotency_key_in_use";
+    readonly UnknownError: "unknown_error";
+};
+export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode] | (string & {});
+/** The kind of error each known code raises. Codes not listed raise the base error. */
+export declare const ERROR_KINDS: {
+    readonly authentication: readonly ["api_key_invalid"];
+    readonly invalid_request: readonly ["validation_failed", "s3_destination_invalid", "web_page_id_invalid", "idempotency_key_reused", "sitemap_schedule_not_triggerable"];
+    readonly plan_limit: readonly ["quota_exhausted", "feature_not_available", "no_trigger_allowance", "forbidden"];
+    readonly not_found: readonly ["capture_not_found", "web_page_not_found", "not_found"];
+    readonly rate_limit: readonly ["rate_limited", "queue_full"];
+    readonly capture: readonly ["capture_failed", "capture_timeout", "payload_too_large", "capture_expired"];
+    readonly service: readonly ["capture_busy", "service_unavailable", "internal_error", "request_cancelled", "idempotency_key_in_use"];
+};
+export type ErrorKind = keyof typeof ERROR_KINDS;
+/**
+ * Codes that are worth sending the same request again for. `queue_full` is not one: the async queue
+ * stays full until captures finish, so it is raised for the caller with `retryAfterSeconds`.
+ */
+export declare const RETRYABLE_CODES: ReadonlySet<string>;
+/** The code for a refusal that came without a JSON error body, usually from a proxy. */
+export declare const FALLBACK_CODE_BY_STATUS: Readonly<Record<number, string>>;
+export declare const FALLBACK_CODE_FOR_OTHER_STATUS = "unknown_error";

package/dist/esm/error-codes.js

@@ -0,0 +1,91 @@
+/**
+ * The `error_code` tokens the APIs answer with. Switch on these, never on the HTTP status or the
+ * message. A code added to the API later still comes through as a plain string.
+ */
+export const ErrorCode = {
+    ApiKeyInvalid: "api_key_invalid",
+    ValidationFailed: "validation_failed",
+    S3DestinationInvalid: "s3_destination_invalid",
+    WebPageIdInvalid: "web_page_id_invalid",
+    IdempotencyKeyReused: "idempotency_key_reused",
+    /** The web page is a sitemap schedule, which runs only on its schedule. Not retried. */
+    SitemapScheduleNotTriggerable: "sitemap_schedule_not_triggerable",
+    QuotaExhausted: "quota_exhausted",
+    FeatureNotAvailable: "feature_not_available",
+    NoTriggerAllowance: "no_trigger_allowance",
+    Forbidden: "forbidden",
+    CaptureNotFound: "capture_not_found",
+    WebPageNotFound: "web_page_not_found",
+    NotFound: "not_found",
+    RateLimited: "rate_limited",
+    /** Too many async captures are already waiting or running. Not retried. */
+    QueueFull: "queue_full",
+    CaptureFailed: "capture_failed",
+    CaptureTimeout: "capture_timeout",
+    PayloadTooLarge: "payload_too_large",
+    /** An async capture still waited for a browser 15 minutes after it was accepted. Not charged. */
+    CaptureExpired: "capture_expired",
+    CaptureBusy: "capture_busy",
+    ServiceUnavailable: "service_unavailable",
+    InternalError: "internal_error",
+    RequestCancelled: "request_cancelled",
+    IdempotencyKeyInUse: "idempotency_key_in_use",
+    UnknownError: "unknown_error",
+};
+/** The kind of error each known code raises. Codes not listed raise the base error. */
+export const ERROR_KINDS = {
+    authentication: ["api_key_invalid"],
+    invalid_request: [
+        "validation_failed",
+        "s3_destination_invalid",
+        "web_page_id_invalid",
+        "idempotency_key_reused",
+        "sitemap_schedule_not_triggerable",
+    ],
+    plan_limit: [
+        "quota_exhausted",
+        "feature_not_available",
+        "no_trigger_allowance",
+        "forbidden",
+    ],
+    not_found: ["capture_not_found", "web_page_not_found", "not_found"],
+    rate_limit: ["rate_limited", "queue_full"],
+    capture: [
+        "capture_failed",
+        "capture_timeout",
+        "payload_too_large",
+        "capture_expired",
+    ],
+    service: [
+        "capture_busy",
+        "service_unavailable",
+        "internal_error",
+        "request_cancelled",
+        "idempotency_key_in_use",
+    ],
+};
+/**
+ * Codes that are worth sending the same request again for. `queue_full` is not one: the async queue
+ * stays full until captures finish, so it is raised for the caller with `retryAfterSeconds`.
+ */
+export const RETRYABLE_CODES = new Set([
+    "rate_limited",
+    "capture_busy",
+    "service_unavailable",
+    "idempotency_key_in_use",
+]);
+/** The code for a refusal that came without a JSON error body, usually from a proxy. */
+export const FALLBACK_CODE_BY_STATUS = {
+    400: "validation_failed",
+    401: "api_key_invalid",
+    403: "forbidden",
+    404: "not_found",
+    409: "idempotency_key_in_use",
+    413: "payload_too_large",
+    429: "rate_limited",
+    500: "internal_error",
+    502: "service_unavailable",
+    503: "service_unavailable",
+    504: "service_unavailable",
+};
+export const FALLBACK_CODE_FOR_OTHER_STATUS = "unknown_error";