@websitescreenshotworld/sdk 0.0.0-stage → 0.1.0

package/dist/cjs/models/defaults.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseDefaults = parseDefaults;
+exports.parseCatalog = parseCatalog;
+const wire_js_1 = require("../wire.js");
+function parseDefaults(wire) {
+    const defaults = {
+        specVersion: wire.spec_version,
+        responseType: wire.response_type,
+        mediaCategory: wire.media_category,
+        format: wire.format,
+        formats: wire.formats,
+        deviceCategory: wire.device_category,
+        emulatedDevice: wire.emulated_device,
+        viewport: wire.viewport && {
+            width: wire.viewport.width,
+            height: wire.viewport.height,
+            deviceScaleFactor: wire.viewport.device_scale_factor,
+        },
+        zoom: wire.zoom,
+        scrollMode: wire.scroll_mode,
+        autoHeight: wire.auto_height,
+        autoHeightMaxHeight: wire.auto_height_max_height,
+        autoHeightMaxHeightWebp: wire.auto_height_max_height_webp,
+        blockAds: wire.block_ads,
+        blockPopUps: wire.block_pop_ups,
+        pressEscape: wire.press_escape,
+        pageTimeoutMs: wire.page_timeout_ms,
+        scrollingDelayMs: wire.scrolling_delay_ms,
+        geolocation: wire.geolocation,
+        geolocationAccuracy: wire.geolocation_accuracy,
+        waitForCloudSync: wire.wait_for_cloud_sync,
+        timestampWatermark: (0, wire_js_1.camelCaseKeys)(wire.timestamp_watermark),
+        pageSource: (0, wire_js_1.camelCaseKeys)(wire.page_source),
+        limits: (0, wire_js_1.camelCaseKeys)(wire.limits),
+        leftToTheBrowser: wire.left_to_the_browser,
+    };
+    // Fields the API did not send stay absent rather than showing up as `undefined`.
+    return Object.fromEntries(Object.entries(defaults).filter(([, value]) => value !== undefined));
+}
+function parseCatalog(wire) {
+    return {
+        emulatedDevices: wire.emulated_devices,
+        proxyCountries: wire.proxy_countries,
+    };
+}

package/dist/cjs/models/tokens.d.ts

@@ -0,0 +1,92 @@
+/** Where a capture is in its life. */
+export declare const CaptureStatus: {
+    readonly Pending: "pending";
+    /** An async capture accepted and waiting for a browser. */
+    readonly Queued: "queued";
+    /** An async capture a browser is taking now. */
+    readonly Running: "running";
+    readonly Succeeded: "succeeded";
+    /** The end state of `captureFile`: the file went back in the answer and is not kept. */
+    readonly Delivered: "delivered";
+    readonly Failed: "failed";
+    readonly TimedOut: "timed_out";
+    readonly Expired: "expired";
+};
+export type CaptureStatus = (typeof CaptureStatus)[keyof typeof CaptureStatus] | (string & {});
+/** How the API answered a capture. */
+export declare const ResponseType: {
+    readonly Json: "json";
+    readonly ByFormat: "by_format";
+    readonly CloudStorage: "cloud_storage";
+};
+export type ResponseType = (typeof ResponseType)[keyof typeof ResponseType] | (string & {});
+export declare const MediaCategory: {
+    readonly Image: "image";
+    readonly Video: "video";
+    readonly Pdf: "pdf";
+};
+export type MediaCategory = (typeof MediaCategory)[keyof typeof MediaCategory] | (string & {});
+/** The file format. It must belong to the capture's media category. */
+export declare const CaptureFormat: {
+    readonly Png: "png";
+    readonly Jpeg: "jpeg";
+    readonly Webp: "webp";
+    readonly Tiff: "tiff";
+    readonly Mp4: "mp4";
+    readonly Webm: "webm";
+    readonly Mov: "mov";
+    readonly Gif: "gif";
+    readonly ImagePdf: "image_pdf";
+    readonly DocumentPdf: "document_pdf";
+};
+export type CaptureFormat = (typeof CaptureFormat)[keyof typeof CaptureFormat] | (string & {});
+export declare const DeviceCategory: {
+    readonly Desktop: "desktop";
+    readonly Mobile: "mobile";
+};
+export type DeviceCategory = (typeof DeviceCategory)[keyof typeof DeviceCategory] | (string & {});
+export declare const ScrollMode: {
+    /** Only what fits in the viewport. */
+    readonly Viewport: "viewport";
+    /** The full page. */
+    readonly Scroll: "scroll";
+};
+export type ScrollMode = (typeof ScrollMode)[keyof typeof ScrollMode] | (string & {});
+export declare const WatermarkLocation: {
+    readonly Top: "top";
+    readonly Bottom: "bottom";
+};
+export type WatermarkLocation = (typeof WatermarkLocation)[keyof typeof WatermarkLocation] | (string & {});
+export declare const PageSourceFormat: {
+    readonly Html: "html";
+    readonly Json: "json";
+    readonly Text: "text";
+};
+export type PageSourceFormat = (typeof PageSourceFormat)[keyof typeof PageSourceFormat] | (string & {});
+/** Where an upload to your bucket stands. */
+export declare const S3DeliveryStatus: {
+    readonly NotStarted: "not_started";
+    readonly InProgress: "in_progress";
+    readonly Completed: "completed";
+    readonly Failed: "failed";
+};
+export type S3DeliveryStatus = (typeof S3DeliveryStatus)[keyof typeof S3DeliveryStatus] | (string & {});
+/** What a trigger-now call did. */
+export declare const TriggerStatus: {
+    readonly Triggered: "triggered";
+    /** A capture was already queued or running; nothing new was started or charged. */
+    readonly AlreadyPending: "already_pending";
+};
+export type TriggerStatus = (typeof TriggerStatus)[keyof typeof TriggerStatus] | (string & {});
+/** Who started a scheduled web page's pending capture. */
+export declare const TriggeredBy: {
+    readonly Api: "api";
+    readonly Ui: "ui";
+};
+export type TriggeredBy = (typeof TriggeredBy)[keyof typeof TriggeredBy] | (string & {});
+/** The product a webhook event comes from. */
+export declare const Product: {
+    readonly InstantSnap: "instant_snap";
+    readonly AutoSchedule: "auto_schedule";
+};
+export type Product = (typeof Product)[keyof typeof Product] | (string & {});

package/dist/cjs/models/tokens.js

@@ -0,0 +1,85 @@
+"use strict";
+// Each token is a set of named constants plus a type that also accepts any other string, so a value
+// the API adds later still comes through while the known ones keep their autocompletion.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Product = exports.TriggeredBy = exports.TriggerStatus = exports.S3DeliveryStatus = exports.PageSourceFormat = exports.WatermarkLocation = exports.ScrollMode = exports.DeviceCategory = exports.CaptureFormat = exports.MediaCategory = exports.ResponseType = exports.CaptureStatus = void 0;
+/** Where a capture is in its life. */
+exports.CaptureStatus = {
+    Pending: "pending",
+    /** An async capture accepted and waiting for a browser. */
+    Queued: "queued",
+    /** An async capture a browser is taking now. */
+    Running: "running",
+    Succeeded: "succeeded",
+    /** The end state of `captureFile`: the file went back in the answer and is not kept. */
+    Delivered: "delivered",
+    Failed: "failed",
+    TimedOut: "timed_out",
+    Expired: "expired",
+};
+/** How the API answered a capture. */
+exports.ResponseType = {
+    Json: "json",
+    ByFormat: "by_format",
+    CloudStorage: "cloud_storage",
+};
+exports.MediaCategory = {
+    Image: "image",
+    Video: "video",
+    Pdf: "pdf",
+};
+/** The file format. It must belong to the capture's media category. */
+exports.CaptureFormat = {
+    Png: "png",
+    Jpeg: "jpeg",
+    Webp: "webp",
+    Tiff: "tiff",
+    Mp4: "mp4",
+    Webm: "webm",
+    Mov: "mov",
+    Gif: "gif",
+    ImagePdf: "image_pdf",
+    DocumentPdf: "document_pdf",
+};
+exports.DeviceCategory = {
+    Desktop: "desktop",
+    Mobile: "mobile",
+};
+exports.ScrollMode = {
+    /** Only what fits in the viewport. */
+    Viewport: "viewport",
+    /** The full page. */
+    Scroll: "scroll",
+};
+exports.WatermarkLocation = {
+    Top: "top",
+    Bottom: "bottom",
+};
+exports.PageSourceFormat = {
+    Html: "html",
+    Json: "json",
+    Text: "text",
+};
+/** Where an upload to your bucket stands. */
+exports.S3DeliveryStatus = {
+    NotStarted: "not_started",
+    InProgress: "in_progress",
+    Completed: "completed",
+    Failed: "failed",
+};
+/** What a trigger-now call did. */
+exports.TriggerStatus = {
+    Triggered: "triggered",
+    /** A capture was already queued or running; nothing new was started or charged. */
+    AlreadyPending: "already_pending",
+};
+/** Who started a scheduled web page's pending capture. */
+exports.TriggeredBy = {
+    Api: "api",
+    Ui: "ui",
+};
+/** The product a webhook event comes from. */
+exports.Product = {
+    InstantSnap: "instant_snap",
+    AutoSchedule: "auto_schedule",
+};

package/dist/cjs/models/trigger-result.d.ts

@@ -0,0 +1,20 @@
+import type { TriggerStatus, TriggeredBy } from "./tokens.js";
+/** What `autoSchedule.triggerNow` did. The capture's outcome arrives later by webhook. */
+export interface TriggerResult {
+    /** `triggered`, or `already_pending` when a capture was already queued or running. */
+    status: TriggerStatus;
+    webPageId: string;
+    triggeredBy: TriggeredBy;
+    /** When the capture was queued; for `already_pending`, when the earlier trigger was. */
+    triggeredAt: Date;
+    /** One sentence for a person. */
+    message: string;
+}
+export interface WireTriggerResult {
+    status: string;
+    web_page_id: string;
+    triggered_by: string;
+    triggered_at: string;
+    message: string;
+}
+export declare function parseTriggerResult(wire: WireTriggerResult): TriggerResult;

package/dist/cjs/models/trigger-result.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseTriggerResult = parseTriggerResult;
+const wire_js_1 = require("../wire.js");
+function parseTriggerResult(wire) {
+    return {
+        status: wire.status,
+        webPageId: wire.web_page_id,
+        triggeredBy: wire.triggered_by,
+        triggeredAt: (0, wire_js_1.parseDate)(wire.triggered_at),
+        message: wire.message,
+    };
+}

package/dist/cjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/dist/cjs/transport.d.ts

@@ -0,0 +1,55 @@
+/** Options every call accepts as its last argument. */
+export interface RequestOptions {
+    /**
+     * Milliseconds the call may take, retries and the waits between them included. Defaults to the
+     * client's `captureTimeout` for captures and `timeout` for everything else.
+     */
+    timeout?: number;
+    /**
+     * Stops the call, and any retry it would make, as soon as it aborts; the call then rejects with
+     * the signal's reason. Once a file has started to arrive, cancel its stream instead.
+     */
+    signal?: AbortSignal;
+}
+/** Options the capture calls accept as their last argument. */
+export interface CaptureRequestOptions extends RequestOptions {
+    /**
+     * Makes the capture safe to repeat within 24 hours. A random UUID is used when none is given;
+     * either way, every retry of this call sends the same key.
+     */
+    idempotencyKey?: string;
+}
+export interface TransportOptions {
+    /** Looked up on each request when left out, so a global fetch replaced later is used. */
+    fetch: typeof fetch | undefined;
+    maxRetries: number;
+    userAgent: string;
+}
+/** One API call, which may take several attempts. */
+export interface Call {
+    method: "GET" | "POST";
+    url: string;
+    /** Left out for the one endpoint that needs no key. */
+    apiKey?: string;
+    /** A JSON body; left out for calls without one. */
+    body?: unknown;
+    idempotencyKey?: string;
+    /** The answer is a file rather than JSON. */
+    file?: boolean;
+    timeout: number;
+    signal?: AbortSignal | undefined;
+}
+/** Sends calls with the shared headers, timeouts and retries. */
+export declare class Transport {
+    #private;
+    constructor(options: TransportOptions);
+    /** Makes the call and parses its JSON answer. */
+    json(call: Call): Promise<unknown>;
+    /** Makes the call and returns the answer as soon as its headers arrive, with the body unread. */
+    file(call: Call): Promise<Response>;
+}
+/**
+ * How long to wait before the next attempt: the API's hint when it gave one, capped at a minute,
+ * otherwise a short backoff with jitter so that clients refused together do not return together.
+ */
+export declare function retryDelay(retryAfterSeconds: number | null, attempt: number): number;

package/dist/cjs/transport.js

@@ -0,0 +1,206 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Transport = void 0;
+exports.retryDelay = retryDelay;
+const error_codes_js_1 = require("./error-codes.js");
+const errors_js_1 = require("./errors.js");
+const MAX_RETRY_AFTER_SECONDS = 60;
+const BACKOFF_MS = [500, 1000];
+const JITTER = 0.25;
+// setTimeout fires at once for anything longer, so such a timeout means "no timeout".
+const MAX_TIMER_MS = 2 ** 31 - 1;
+/** Sends calls with the shared headers, timeouts and retries. */
+class Transport {
+    #options;
+    constructor(options) {
+        this.#options = options;
+    }
+    /** Makes the call and parses its JSON answer. */
+    json(call) {
+        return this.#send(call, async (response) => {
+            const text = await response.text();
+            try {
+                return JSON.parse(text);
+            }
+            catch (cause) {
+                throw new errors_js_1.WebsiteScreenshotWorldError("The API answered with a body that is not JSON.", { httpStatus: response.status, rawBody: text, cause });
+            }
+        });
+    }
+    /** Makes the call and returns the answer as soon as its headers arrive, with the body unread. */
+    file(call) {
+        return this.#send(call, (response) => Promise.resolve(response));
+    }
+    async #send(call, read) {
+        const deadline = new Deadline(call.timeout, call.signal);
+        try {
+            const init = this.#requestInit(call, deadline.signal);
+            for (let attempt = 0;; attempt++) {
+                const outcome = await this.#attempt(call.url, init, read, deadline);
+                if (outcome.done)
+                    return outcome.value;
+                const delay = retryDelay(outcome.error.retryAfterSeconds, attempt);
+                const retry = outcome.retryable &&
+                    attempt < this.#options.maxRetries &&
+                    deadline.allows(delay);
+                if (!retry)
+                    throw outcome.error;
+                await deadline.sleep(delay);
+            }
+        }
+        finally {
+            deadline.end();
+        }
+    }
+    async #attempt(url, init, read, deadline) {
+        try {
+            const fetch = this.#options.fetch ?? globalThis.fetch;
+            const response = await fetch(url, init);
+            if (response.ok)
+                return { done: true, value: await read(response) };
+            const error = await refusalFrom(response);
+            return {
+                done: false,
+                error,
+                retryable: error_codes_js_1.RETRYABLE_CODES.has(error.errorCode ?? ""),
+            };
+        }
+        catch (cause) {
+            deadline.throwIfStopped();
+            if (cause instanceof errors_js_1.WebsiteScreenshotWorldError)
+                throw cause;
+            const error = new errors_js_1.ConnectionError(`The request to ${new URL(url).origin} failed before an answer came back.`, { cause });
+            return { done: false, error, retryable: true };
+        }
+    }
+    #requestInit(call, signal) {
+        const headers = {
+            "User-Agent": this.#options.userAgent,
+        };
+        if (call.apiKey !== undefined)
+            headers["X-Api-Key"] = call.apiKey;
+        if (call.file !== true)
+            headers.Accept = "application/json";
+        if (call.body !== undefined)
+            headers["Content-Type"] = "application/json";
+        if (call.idempotencyKey !== undefined) {
+            headers["Idempotency-Key"] = call.idempotencyKey;
+        }
+        /* Redirects are never followed (code-review plan 7.4, 28 Oct 2026): fetch would send the
+           X-Api-Key to wherever a 3xx pointed. The API never redirects, and neither does the download
+           link, so a 3xx is answered as the refusal it is - "manual", not "error", which would surface
+           as a ConnectionError and be retried. */
+        const init = {
+            method: call.method,
+            headers,
+            signal,
+            redirect: "manual",
+        };
+        if (call.body !== undefined)
+            init.body = JSON.stringify(call.body);
+        return init;
+    }
+}
+exports.Transport = Transport;
+/**
+ * How long to wait before the next attempt: the API's hint when it gave one, capped at a minute,
+ * otherwise a short backoff with jitter so that clients refused together do not return together.
+ */
+function retryDelay(retryAfterSeconds, attempt) {
+    if (retryAfterSeconds !== null) {
+        return Math.min(retryAfterSeconds, MAX_RETRY_AFTER_SECONDS) * 1000;
+    }
+    const base = BACKOFF_MS[Math.min(attempt, BACKOFF_MS.length - 1)] ?? 1000;
+    return base * (1 + Math.random() * JITTER);
+}
+async function refusalFrom(response) {
+    const rawBody = await response.text();
+    const body = errorBodyFrom(rawBody);
+    const errorCode = body?.error_code ??
+        error_codes_js_1.FALLBACK_CODE_BY_STATUS[response.status] ??
+        error_codes_js_1.FALLBACK_CODE_FOR_OTHER_STATUS;
+    const message = typeof body?.error_message === "string"
+        ? body.error_message
+        : `The API answered with HTTP ${String(response.status)} and no error details.`;
+    const retryAfterSeconds = typeof body?.retry_after_seconds === "number"
+        ? body.retry_after_seconds
+        : retryAfterHeader(response.headers);
+    return (0, errors_js_1.errorFor)(errorCode, message, {
+        httpStatus: response.status,
+        retryAfterSeconds,
+        rawBody,
+    });
+}
+function errorBodyFrom(text) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    const isErrorBody = typeof value === "object" &&
+        value !== null &&
+        typeof value.error_code === "string";
+    return isErrorBody ? value : null;
+}
+function retryAfterHeader(headers) {
+    const value = headers.get("retry-after")?.trim();
+    return value !== undefined && /^\d+$/.test(value) ? Number(value) : null;
+}
+/** Ends a call when its timeout passes or the caller's signal aborts, whichever comes first. */
+class Deadline {
+    #controller = new AbortController();
+    #expiresAt;
+    #timer;
+    #callerSignal;
+    #onCallerAbort = () => {
+        this.#controller.abort(this.#callerSignal?.reason);
+    };
+    constructor(timeout, callerSignal) {
+        callerSignal?.throwIfAborted();
+        this.#callerSignal = callerSignal;
+        this.#expiresAt = performance.now() + timeout;
+        callerSignal?.addEventListener("abort", this.#onCallerAbort, {
+            once: true,
+        });
+        if (timeout <= MAX_TIMER_MS) {
+            this.#timer = setTimeout(() => {
+                this.#controller.abort(new errors_js_1.ConnectionError(`The call did not finish within ${String(timeout / 1000)} seconds.`));
+            }, timeout);
+        }
+    }
+    get signal() {
+        return this.#controller.signal;
+    }
+    /** Whether waiting `milliseconds` still leaves time for another attempt. */
+    allows(milliseconds) {
+        return performance.now() + milliseconds < this.#expiresAt;
+    }
+    /** Throws the reason the call was stopped, if it was. */
+    throwIfStopped() {
+        this.#controller.signal.throwIfAborted();
+    }
+    sleep(milliseconds) {
+        const signal = this.#controller.signal;
+        return new Promise((resolve, reject) => {
+            if (signal.aborted) {
+                reject(signal.reason);
+                return;
+            }
+            const onAbort = () => {
+                clearTimeout(timer);
+                reject(signal.reason);
+            };
+            const timer = setTimeout(() => {
+                signal.removeEventListener("abort", onAbort);
+                resolve();
+            }, milliseconds);
+            signal.addEventListener("abort", onAbort, { once: true });
+        });
+    }
+    end() {
+        clearTimeout(this.#timer);
+        this.#callerSignal?.removeEventListener("abort", this.#onCallerAbort);
+    }
+}

package/dist/cjs/version.d.ts

@@ -0,0 +1,2 @@
+/** The version of this library. Kept equal to `version` in package.json. */
+export declare const VERSION = "0.1.0";

package/dist/cjs/version.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VERSION = void 0;
+/** The version of this library. Kept equal to `version` in package.json. */
+exports.VERSION = "0.1.0";

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

@@ -0,0 +1,128 @@
+import type { CaptureFields, PageSource, S3Delivery } from "../models/capture.js";
+import type { CaptureFormat, MediaCategory, PageSourceFormat, Product } from "../models/tokens.js";
+/** The event types this version knows. */
+export declare const WebhookEventType: {
+    readonly CaptureSucceeded: "capture.succeeded";
+    readonly CaptureFailed: "capture.failed";
+    readonly DeliveryCompleted: "delivery.completed";
+    readonly CaptureChanged: "capture.changed";
+    readonly SchedulePaused: "schedule.paused";
+    readonly SitemapRunCompleted: "sitemap_run.completed";
+    readonly Ping: "ping";
+};
+export type WebhookEventType = (typeof WebhookEventType)[keyof typeof WebhookEventType];
+interface EventEnvelope<Type extends string, EventProduct, Data> {
+    /** The delivery id; the same on every retry of this delivery. */
+    id: string;
+    type: Type;
+    createdAt: Date;
+    product: EventProduct;
+    data: Data;
+}
+/** An Instant Snap capture as its webhook carries it: no download links or access key. */
+export interface InstantSnapCaptureData extends CaptureFields {
+    pageSource: Omit<PageSource, "downloadUrl"> | null;
+    s3Delivery: Omit<S3Delivery, "accessKeyId"> | null;
+}
+/** A scheduled web page's capture. */
+export interface ScheduledCapture {
+    id: string;
+    /** The web page's id; `autoSchedule.triggerNow` calls it `webPageId`. */
+    scheduleId: string;
+    scheduleName: string;
+    url: string;
+    status: string;
+    mediaCategory: MediaCategory;
+    format: CaptureFormat | null;
+    pageHttpStatus: number | null;
+    capturedAt: Date | null;
+    finalUrl: string | null;
+    mediaSha256: string | null;
+    pageSource: {
+        format: PageSourceFormat;
+        sha256: string | null;
+    } | null;
+    /** Set when the capture was part of a sitemap run. */
+    sitemapRunId: string | null;
+}
+/** One place a scheduled capture was delivered to. */
+export interface Destination {
+    slot: number;
+    name: string;
+    provider: string;
+    status: string;
+    completedAt: Date | null;
+}
+export interface DeliveryCompletedData extends ScheduledCapture {
+    destinations: Destination[];
+}
+export interface CaptureChangedData extends ScheduledCapture {
+    /** How much of the image changed since the capture it was compared with. */
+    changePercent: number | null;
+    comparedToCaptureId: string | null;
+    changeImageAvailable: boolean;
+}
+export interface SchedulePausedData {
+    scheduleId: string;
+    scheduleName: string;
+    url: string;
+    /** Why the schedule stopped, such as `quota_exhausted`. */
+    reason: string;
+    pausedAt: Date | null;
+}
+export interface SitemapRunCompletedData {
+    sitemapRunId: string;
+    scheduleId: string;
+    scheduleName: string;
+    sitemapUrl: string;
+    status: string;
+    runAt: Date | null;
+    completedAt: Date | null;
+    pagesListed: number | null;
+    pagesMatched: number | null;
+    pagesQueued: number | null;
+    pagesSucceeded: number | null;
+    pagesFailed: number | null;
+    pagesOverLimit: number | null;
+    pagesOverQuota: number | null;
+    message: string | null;
+}
+export interface PingData {
+    endpointId: string;
+    endpointName: string;
+    message: string;
+    sentAt: Date | null;
+}
+type CaptureOutcome = "capture.succeeded" | "capture.failed";
+/** An Instant Snap capture finished. */
+export type InstantSnapCaptureEvent = EventEnvelope<CaptureOutcome, "instant_snap", InstantSnapCaptureData>;
+/** A scheduled web page's capture finished. */
+export type AutoScheduleCaptureEvent = EventEnvelope<CaptureOutcome, "auto_schedule", ScheduledCapture>;
+/** A scheduled capture reached all of its destinations. */
+export type DeliveryCompletedEvent = EventEnvelope<"delivery.completed", "auto_schedule", DeliveryCompletedData>;
+/** A scheduled capture differs from the one before it. */
+export type CaptureChangedEvent = EventEnvelope<"capture.changed", "auto_schedule", CaptureChangedData>;
+/** A schedule stopped running. */
+export type SchedulePausedEvent = EventEnvelope<"schedule.paused", "auto_schedule", SchedulePausedData>;
+/** Every page of a sitemap run has been captured or skipped. */
+export type SitemapRunCompletedEvent = EventEnvelope<"sitemap_run.completed", "auto_schedule", SitemapRunCompletedData>;
+/** A test delivery sent from the dashboard, by either product. */
+export type PingEvent = EventEnvelope<"ping", Product, PingData>;
+/**
+ * An event type this version does not know yet, with its payload as sent in `rawData`.
+ *
+ * Its `data` is never set: that keeps `event.data` precisely typed after `switch (event.type)`
+ * narrows to a known type, since TypeScript cannot exclude one string from a `string` type.
+ */
+export interface UnknownWebhookEvent {
+    id: string;
+    type: string;
+    createdAt: Date;
+    product: string;
+    data: never;
+    /** The event's `data` exactly as sent, with snake_case keys. */
+    rawData: Record<string, unknown>;
+}
+/** Every event `Webhook.verify` returns, told apart by `type` and, for captures, `product`. */
+export type WebhookEvent = InstantSnapCaptureEvent | AutoScheduleCaptureEvent | DeliveryCompletedEvent | CaptureChangedEvent | SchedulePausedEvent | SitemapRunCompletedEvent | PingEvent | UnknownWebhookEvent;
+export {};

package/dist/cjs/webhooks/events.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebhookEventType = void 0;
+/** The event types this version knows. */
+exports.WebhookEventType = {
+    CaptureSucceeded: "capture.succeeded",
+    CaptureFailed: "capture.failed",
+    DeliveryCompleted: "delivery.completed",
+    CaptureChanged: "capture.changed",
+    SchedulePaused: "schedule.paused",
+    SitemapRunCompleted: "sitemap_run.completed",
+    Ping: "ping",
+};