@websitescreenshotworld/sdk 0.0.0-stage → 0.1.1

package/dist/esm/errors.d.ts

@@ -0,0 +1,56 @@
+import { type ErrorCode } from "./error-codes.js";
+/** What an error knows about the answer that caused it. */
+export interface ErrorDetails {
+    errorCode?: ErrorCode | null;
+    httpStatus?: number | null;
+    retryAfterSeconds?: number | null;
+    rawBody?: string | null;
+    cause?: unknown;
+}
+/**
+ * The base class of every error this library throws. An `error_code` this version does not know
+ * raises this class itself; known codes raise one of its subclasses.
+ */
+export declare class WebsiteScreenshotWorldError extends Error {
+    /** The API's error token, such as `rate_limited`. `null` when no answer came back. */
+    readonly errorCode: ErrorCode | null;
+    /** The HTTP status of the answer. `null` when no answer came back. */
+    readonly httpStatus: number | null;
+    /** How long the API asked to wait before trying again, in seconds. */
+    readonly retryAfterSeconds: number | null;
+    /** The body of the answer as received. */
+    readonly rawBody: string | null;
+    constructor(message: string, details?: ErrorDetails);
+}
+/** The API key is missing, malformed, revoked or belongs to the other product. */
+export declare class AuthenticationError extends WebsiteScreenshotWorldError {
+}
+/** The request was refused as invalid. Sending it again will not help. */
+export declare class InvalidRequestError extends WebsiteScreenshotWorldError {
+}
+/** The plan has run out of captures, or does not include what was asked for. */
+export declare class PlanLimitError extends WebsiteScreenshotWorldError {
+}
+/** The capture or web page does not exist for this account. */
+export declare class NotFoundError extends WebsiteScreenshotWorldError {
+}
+/** Too many requests, still refused after the retries ran out. */
+export declare class RateLimitError extends WebsiteScreenshotWorldError {
+}
+/** The website could not be captured, or the file was too large to return. Not retried. */
+export declare class CaptureError extends WebsiteScreenshotWorldError {
+}
+/** The service was busy or failed on its side. */
+export declare class ServiceError extends WebsiteScreenshotWorldError {
+}
+/**
+ * The request could not be sent, no answer came back, or the call ran out of time. The underlying
+ * error, when there is one, is the `cause`.
+ */
+export declare class ConnectionError extends WebsiteScreenshotWorldError {
+}
+/** A webhook's signature header is missing, malformed, too old or does not match the body. */
+export declare class SignatureVerificationError extends WebsiteScreenshotWorldError {
+}
+/** Creates the error class that `errorCode` raises. */
+export declare function errorFor(errorCode: string, message: string, details: Omit<ErrorDetails, "errorCode">): WebsiteScreenshotWorldError;

package/dist/esm/errors.js

@@ -0,0 +1,98 @@
+import { ERROR_KINDS } from "./error-codes.js";
+/**
+ * The base class of every error this library throws. An `error_code` this version does not know
+ * raises this class itself; known codes raise one of its subclasses.
+ */
+export class WebsiteScreenshotWorldError extends Error {
+    static {
+        this.prototype.name = "WebsiteScreenshotWorldError";
+    }
+    /** The API's error token, such as `rate_limited`. `null` when no answer came back. */
+    errorCode;
+    /** The HTTP status of the answer. `null` when no answer came back. */
+    httpStatus;
+    /** How long the API asked to wait before trying again, in seconds. */
+    retryAfterSeconds;
+    /** The body of the answer as received. */
+    rawBody;
+    constructor(message, details = {}) {
+        super(message, details.cause === undefined ? undefined : { cause: details.cause });
+        this.errorCode = details.errorCode ?? null;
+        this.httpStatus = details.httpStatus ?? null;
+        this.retryAfterSeconds = details.retryAfterSeconds ?? null;
+        this.rawBody = details.rawBody ?? null;
+    }
+}
+/** The API key is missing, malformed, revoked or belongs to the other product. */
+export class AuthenticationError extends WebsiteScreenshotWorldError {
+    static {
+        this.prototype.name = "AuthenticationError";
+    }
+}
+/** The request was refused as invalid. Sending it again will not help. */
+export class InvalidRequestError extends WebsiteScreenshotWorldError {
+    static {
+        this.prototype.name = "InvalidRequestError";
+    }
+}
+/** The plan has run out of captures, or does not include what was asked for. */
+export class PlanLimitError extends WebsiteScreenshotWorldError {
+    static {
+        this.prototype.name = "PlanLimitError";
+    }
+}
+/** The capture or web page does not exist for this account. */
+export class NotFoundError extends WebsiteScreenshotWorldError {
+    static {
+        this.prototype.name = "NotFoundError";
+    }
+}
+/** Too many requests, still refused after the retries ran out. */
+export class RateLimitError extends WebsiteScreenshotWorldError {
+    static {
+        this.prototype.name = "RateLimitError";
+    }
+}
+/** The website could not be captured, or the file was too large to return. Not retried. */
+export class CaptureError extends WebsiteScreenshotWorldError {
+    static {
+        this.prototype.name = "CaptureError";
+    }
+}
+/** The service was busy or failed on its side. */
+export class ServiceError extends WebsiteScreenshotWorldError {
+    static {
+        this.prototype.name = "ServiceError";
+    }
+}
+/**
+ * The request could not be sent, no answer came back, or the call ran out of time. The underlying
+ * error, when there is one, is the `cause`.
+ */
+export class ConnectionError extends WebsiteScreenshotWorldError {
+    static {
+        this.prototype.name = "ConnectionError";
+    }
+}
+/** A webhook's signature header is missing, malformed, too old or does not match the body. */
+export class SignatureVerificationError extends WebsiteScreenshotWorldError {
+    static {
+        this.prototype.name = "SignatureVerificationError";
+    }
+}
+const CLASS_BY_KIND = {
+    authentication: AuthenticationError,
+    invalid_request: InvalidRequestError,
+    plan_limit: PlanLimitError,
+    not_found: NotFoundError,
+    rate_limit: RateLimitError,
+    capture: CaptureError,
+    service: ServiceError,
+};
+const KIND_BY_CODE = new Map(Object.entries(ERROR_KINDS).flatMap(([kind, codes]) => codes.map((code) => [code, kind])));
+/** Creates the error class that `errorCode` raises. */
+export function errorFor(errorCode, message, details) {
+    const kind = KIND_BY_CODE.get(errorCode);
+    const ErrorClass = kind === undefined ? WebsiteScreenshotWorldError : CLASS_BY_KIND[kind];
+    return new ErrorClass(message, { ...details, errorCode });
+}

package/dist/esm/files.d.ts

@@ -0,0 +1,6 @@
+/** Where a file is written: a path, a Node.js writable stream or a web `WritableStream`. */
+export type FileDestination = string | NodeJS.WritableStream | WritableStream<Uint8Array>;
+/** Streams `body` to `destination`. A file left half-written by a failure is removed. */
+export declare function writeBody(body: ReadableStream<Uint8Array>, destination: FileDestination, signal?: AbortSignal): Promise<void>;
+/** The file name from a `Content-Disposition` header, preferring the RFC 6266 `filename*` form. */
+export declare function filenameFrom(contentDisposition: string | null): string | null;

package/dist/esm/files.js

@@ -0,0 +1,41 @@
+import { createWriteStream } from "node:fs";
+import { rm } from "node:fs/promises";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+/** Streams `body` to `destination`. A file left half-written by a failure is removed. */
+export async function writeBody(body, destination, signal) {
+    const options = signal === undefined ? {} : { signal };
+    if (destination instanceof WritableStream) {
+        await body.pipeTo(destination, options);
+        return;
+    }
+    const source = Readable.fromWeb(body);
+    if (typeof destination !== "string") {
+        await pipeline(source, destination, options);
+        return;
+    }
+    try {
+        await pipeline(source, createWriteStream(destination), options);
+    }
+    catch (error) {
+        await rm(destination, { force: true });
+        throw error;
+    }
+}
+/** The file name from a `Content-Disposition` header, preferring the RFC 6266 `filename*` form. */
+export function filenameFrom(contentDisposition) {
+    if (contentDisposition === null)
+        return null;
+    const extended = /filename\*\s*=\s*([^']*)'[^']*'([^;]+)/i.exec(contentDisposition);
+    if (extended?.[2] !== undefined) {
+        try {
+            return decodeURIComponent(extended[2].trim());
+        }
+        catch {
+            // A malformed percent-encoding: the plain form below may still hold a usable name.
+        }
+    }
+    const plain = /filename\s*=\s*(?:"((?:\\.|[^"\\])*)"|([^;]+))/i.exec(contentDisposition);
+    const name = plain?.[1]?.replace(/\\(.)/g, "$1") ?? plain?.[2]?.trim();
+    return name === undefined || name === "" ? null : name;
+}

package/dist/esm/index.d.ts

@@ -0,0 +1,16 @@
+export { WebsiteScreenshotWorld, type ClientOptions } from "./client.js";
+export type { InstantSnap, WaitOptions } from "./instant-snap.js";
+export type { AutoSchedule } from "./auto-schedule.js";
+export type { CaptureRequestOptions, RequestOptions } from "./transport.js";
+export type { FileDestination } from "./files.js";
+export type { CaptureFileOptions, CaptureOptions, CaptureToBucketOptions, GeolocationOptions, PageSourceOptions, ProxyOptions, S3DeliveryOptions, SelectorOptions, TimestampWatermarkOptions, ViewportOptions, } from "./models/capture-options.js";
+export type { Capture, CaptureFields, PageSource, S3Delivery, } from "./models/capture.js";
+export type { CaptureFile } from "./models/capture-file.js";
+export type { Catalog, DefaultViewport, Defaults } from "./models/defaults.js";
+export type { TriggerResult } from "./models/trigger-result.js";
+export { CaptureFormat, CaptureStatus, DeviceCategory, MediaCategory, PageSourceFormat, Product, ResponseType, S3DeliveryStatus, ScrollMode, TriggeredBy, TriggerStatus, WatermarkLocation, } from "./models/tokens.js";
+export { ErrorCode } from "./error-codes.js";
+export { AuthenticationError, CaptureError, ConnectionError, InvalidRequestError, NotFoundError, PlanLimitError, RateLimitError, ServiceError, SignatureVerificationError, WebsiteScreenshotWorldError, type ErrorDetails, } from "./errors.js";
+export { Webhook, type VerifyOptions } from "./webhooks/webhook.js";
+export { WebhookEventType, type AutoScheduleCaptureEvent, type CaptureChangedData, type CaptureChangedEvent, type DeliveryCompletedData, type DeliveryCompletedEvent, type Destination, type InstantSnapCaptureData, type InstantSnapCaptureEvent, type PingData, type PingEvent, type ScheduledCapture, type SchedulePausedData, type SchedulePausedEvent, type SitemapRunCompletedData, type SitemapRunCompletedEvent, type UnknownWebhookEvent, type WebhookEvent, } from "./webhooks/events.js";
+export { VERSION } from "./version.js";

package/dist/esm/index.js

@@ -0,0 +1,7 @@
+export { WebsiteScreenshotWorld } from "./client.js";
+export { CaptureFormat, CaptureStatus, DeviceCategory, MediaCategory, PageSourceFormat, Product, ResponseType, S3DeliveryStatus, ScrollMode, TriggeredBy, TriggerStatus, WatermarkLocation, } from "./models/tokens.js";
+export { ErrorCode } from "./error-codes.js";
+export { AuthenticationError, CaptureError, ConnectionError, InvalidRequestError, NotFoundError, PlanLimitError, RateLimitError, ServiceError, SignatureVerificationError, WebsiteScreenshotWorldError, } from "./errors.js";
+export { Webhook } from "./webhooks/webhook.js";
+export { WebhookEventType, } from "./webhooks/events.js";
+export { VERSION } from "./version.js";

package/dist/esm/instant-snap.d.ts

@@ -0,0 +1,99 @@
+import { type FileDestination } from "./files.js";
+import { type CaptureFile } from "./models/capture-file.js";
+import type { CaptureFileOptions, CaptureOptions, CaptureToBucketOptions } from "./models/capture-options.js";
+import { type Capture } from "./models/capture.js";
+import { type Catalog, type Defaults } from "./models/defaults.js";
+import type { CaptureRequestOptions, RequestOptions, Transport } from "./transport.js";
+/** Options for {@link InstantSnap.wait}. */
+export interface WaitOptions {
+    /**
+     * Seconds to keep reading the capture. When they run out, `wait` returns the capture as last
+     * read, still unfinished, rather than throwing. Default 360.
+     */
+    timeoutSeconds?: number;
+    /** Seconds between reads. Default 3; `0` reads again at once. */
+    pollIntervalSeconds?: number;
+    /**
+     * Stops waiting, and the read in progress, as soon as it aborts; `wait` then rejects with the
+     * signal's reason.
+     */
+    signal?: AbortSignal;
+}
+/** What {@link InstantSnap} needs from the client. */
+export interface InstantSnapConfig {
+    transport: Transport;
+    apiKey: string | undefined;
+    baseUrl: string;
+    timeout: number;
+    captureTimeout: number;
+}
+/** On-demand captures: an image, a video or a PDF of a web page. */
+export declare class InstantSnap {
+    #private;
+    /**
+     * Captures a page and returns the capture, with a `downloadUrl` valid for 60 minutes.
+     *
+     * @example
+     * ```ts
+     * const capture = await client.instantSnap.capture({ url: "https://example.com", format: "webp" });
+     * ```
+     */
+    capture(options: CaptureOptions, requestOptions?: CaptureRequestOptions): Promise<Capture>;
+    /**
+     * Captures a page and returns the file itself as a stream, with its metadata. The API does not
+     * keep the file, so read or save it before discarding the result.
+     */
+    captureFile(options: CaptureFileOptions, requestOptions?: CaptureRequestOptions): Promise<CaptureFile>;
+    /** Captures a page and uploads the file to your S3-compatible bucket. */
+    captureToBucket(options: CaptureToBucketOptions, requestOptions?: CaptureRequestOptions): Promise<Capture>;
+    /**
+     * Queues a capture and returns at once with it, `status` `queued`; it runs when a browser is
+     * free. Read it with {@link InstantSnap.wait} or {@link InstantSnap.get}, or receive it at
+     * `callbackUrl`.
+     *
+     * `options.timeout` sets the browser time it may take, 30 to 300 seconds. The call itself uses
+     * the client's `timeout`, not `captureTimeout`, since nothing is captured while it waits. A
+     * capture still queued 15 minutes later ends `failed` with `capture_expired`, not charged.
+     *
+     * @throws `RateLimitError` with `errorCode` `queue_full` when too many async captures are
+     * already waiting or running. It is not retried; `retryAfterSeconds` says when to try again.
+     *
+     * @example
+     * ```ts
+     * const queued = await client.instantSnap.submit({ url: "https://example.com", timeout: 240 });
+     * const capture = await client.instantSnap.wait(queued.id);
+     * ```
+     */
+    submit(options: CaptureOptions, requestOptions?: CaptureRequestOptions): Promise<Capture>;
+    /**
+     * Queues a capture that uploads the file to your S3-compatible bucket, and returns at once with
+     * it, `status` `queued`. Otherwise as {@link InstantSnap.submit}.
+     */
+    submitToBucket(options: CaptureToBucketOptions, requestOptions?: CaptureRequestOptions): Promise<Capture>;
+    /**
+     * Reads a capture with `get` every `pollIntervalSeconds` until its status is no longer `queued`,
+     * `running` or `pending`, and returns it. When `timeoutSeconds` runs out first, returns the
+     * capture as last read, still unfinished, so you can decide whether to wait again. An error from
+     * `get` is thrown as it is.
+     *
+     * @param capture - A capture's id, or the capture itself, such as the one `submit` returned.
+     */
+    wait(capture: string | {
+        id: string;
+    }, options?: WaitOptions): Promise<Capture>;
+    /** Reads a capture back, with a fresh `downloadUrl`. */
+    get(id: string, requestOptions?: RequestOptions): Promise<Capture>;
+    /**
+     * Downloads a capture's file, or its page source, to a path or a stream.
+     *
+     * @param source - A capture from `capture` or `get`, or its `pageSource`.
+     * @param destination - A file path, a Node.js writable stream or a web `WritableStream`.
+     */
+    download(source: {
+        downloadUrl: string | null;
+    }, destination: FileDestination, requestOptions?: RequestOptions): Promise<void>;
+    /** The values a capture takes for fields it does not set, and the limits. Needs no API key. */
+    defaults(requestOptions?: RequestOptions): Promise<Defaults>;
+    /** The devices `emulatedDevice` accepts and the countries `proxy.country` accepts. */
+    catalog(requestOptions?: RequestOptions): Promise<Catalog>;
+}

package/dist/esm/instant-snap.js

@@ -0,0 +1,201 @@
+import { randomUUID } from "node:crypto";
+import { AuthenticationError } from "./errors.js";
+import { writeBody } from "./files.js";
+import { captureFileFrom } from "./models/capture-file.js";
+import { parseCapture, } from "./models/capture.js";
+import { parseCatalog, parseDefaults, } from "./models/defaults.js";
+import { toWire } from "./wire.js";
+const CAPTURES_PATH = "/instant-snap/v1/captures";
+const DEFAULT_WAIT_TIMEOUT_SECONDS = 360;
+const DEFAULT_POLL_INTERVAL_SECONDS = 3;
+/** The statuses of a capture that has not finished yet. */
+const UNFINISHED_STATUSES = new Set([
+    "queued",
+    "running",
+    "pending",
+]);
+/** On-demand captures: an image, a video or a PDF of a web page. */
+export class InstantSnap {
+    #config;
+    /** @internal Use `client.instantSnap`. */
+    constructor(config) {
+        this.#config = config;
+    }
+    /**
+     * Captures a page and returns the capture, with a `downloadUrl` valid for 60 minutes.
+     *
+     * @example
+     * ```ts
+     * const capture = await client.instantSnap.capture({ url: "https://example.com", format: "webp" });
+     * ```
+     */
+    async capture(options, requestOptions = {}) {
+        const wire = await this.#transport.json(this.#captureCall(options, "json", requestOptions));
+        return parseCapture(wire);
+    }
+    /**
+     * Captures a page and returns the file itself as a stream, with its metadata. The API does not
+     * keep the file, so read or save it before discarding the result.
+     */
+    async captureFile(options, requestOptions = {}) {
+        const response = await this.#transport.file(this.#captureCall(options, "by_format", requestOptions));
+        return captureFileFrom(response);
+    }
+    /** Captures a page and uploads the file to your S3-compatible bucket. */
+    async captureToBucket(options, requestOptions = {}) {
+        const wire = await this.#transport.json(this.#captureCall(options, "cloud_storage", requestOptions));
+        return parseCapture(wire);
+    }
+    /**
+     * Queues a capture and returns at once with it, `status` `queued`; it runs when a browser is
+     * free. Read it with {@link InstantSnap.wait} or {@link InstantSnap.get}, or receive it at
+     * `callbackUrl`.
+     *
+     * `options.timeout` sets the browser time it may take, 30 to 300 seconds. The call itself uses
+     * the client's `timeout`, not `captureTimeout`, since nothing is captured while it waits. A
+     * capture still queued 15 minutes later ends `failed` with `capture_expired`, not charged.
+     *
+     * @throws `RateLimitError` with `errorCode` `queue_full` when too many async captures are
+     * already waiting or running. It is not retried; `retryAfterSeconds` says when to try again.
+     *
+     * @example
+     * ```ts
+     * const queued = await client.instantSnap.submit({ url: "https://example.com", timeout: 240 });
+     * const capture = await client.instantSnap.wait(queued.id);
+     * ```
+     */
+    async submit(options, requestOptions = {}) {
+        const wire = await this.#transport.json(this.#captureCall(options, "json", requestOptions, true));
+        return parseCapture(wire);
+    }
+    /**
+     * Queues a capture that uploads the file to your S3-compatible bucket, and returns at once with
+     * it, `status` `queued`. Otherwise as {@link InstantSnap.submit}.
+     */
+    async submitToBucket(options, requestOptions = {}) {
+        const wire = await this.#transport.json(this.#captureCall(options, "cloud_storage", requestOptions, true));
+        return parseCapture(wire);
+    }
+    /**
+     * Reads a capture with `get` every `pollIntervalSeconds` until its status is no longer `queued`,
+     * `running` or `pending`, and returns it. When `timeoutSeconds` runs out first, returns the
+     * capture as last read, still unfinished, so you can decide whether to wait again. An error from
+     * `get` is thrown as it is.
+     *
+     * @param capture - A capture's id, or the capture itself, such as the one `submit` returned.
+     */
+    async wait(capture, options = {}) {
+        const id = typeof capture === "string" ? capture : capture.id;
+        const timeoutMs = (options.timeoutSeconds ?? DEFAULT_WAIT_TIMEOUT_SECONDS) * 1000;
+        const intervalMs = (options.pollIntervalSeconds ?? DEFAULT_POLL_INTERVAL_SECONDS) * 1000;
+        const { signal } = options;
+        const expiresAt = performance.now() + timeoutMs;
+        for (;;) {
+            const current = await this.get(id, { signal });
+            const remaining = expiresAt - performance.now();
+            if (!UNFINISHED_STATUSES.has(current.status) || remaining <= 0) {
+                return current;
+            }
+            if (intervalMs > 0)
+                await sleep(Math.min(intervalMs, remaining), signal);
+        }
+    }
+    /** Reads a capture back, with a fresh `downloadUrl`. */
+    async get(id, requestOptions = {}) {
+        const wire = await this.#transport.json({
+            method: "GET",
+            url: this.#url(`${CAPTURES_PATH}/${encodeURIComponent(id)}`),
+            apiKey: this.#apiKey(),
+            timeout: requestOptions.timeout ?? this.#config.timeout,
+            signal: requestOptions.signal,
+        });
+        return parseCapture(wire);
+    }
+    /**
+     * Downloads a capture's file, or its page source, to a path or a stream.
+     *
+     * @param source - A capture from `capture` or `get`, or its `pageSource`.
+     * @param destination - A file path, a Node.js writable stream or a web `WritableStream`.
+     */
+    async download(source, destination, requestOptions = {}) {
+        if (source.downloadUrl === null) {
+            throw new TypeError("This capture has no downloadUrl. Read it again with get() for a fresh one.");
+        }
+        // The link is signed, so the API key stays with the API and is not sent to the file host.
+        const response = await this.#transport.file({
+            method: "GET",
+            url: source.downloadUrl,
+            file: true,
+            timeout: requestOptions.timeout ?? this.#config.timeout,
+            signal: requestOptions.signal,
+        });
+        const body = response.body ?? new Blob([]).stream();
+        await writeBody(body, destination, requestOptions.signal);
+    }
+    /** The values a capture takes for fields it does not set, and the limits. Needs no API key. */
+    async defaults(requestOptions = {}) {
+        const wire = await this.#transport.json({
+            method: "GET",
+            url: this.#url("/instant-snap/v1/defaults"),
+            timeout: requestOptions.timeout ?? this.#config.timeout,
+            signal: requestOptions.signal,
+        });
+        return parseDefaults(wire);
+    }
+    /** The devices `emulatedDevice` accepts and the countries `proxy.country` accepts. */
+    async catalog(requestOptions = {}) {
+        const wire = await this.#transport.json({
+            method: "GET",
+            url: this.#url("/instant-snap/v1/catalog"),
+            apiKey: this.#apiKey(),
+            timeout: requestOptions.timeout ?? this.#config.timeout,
+            signal: requestOptions.signal,
+        });
+        return parseCatalog(wire);
+    }
+    get #transport() {
+        return this.#config.transport;
+    }
+    #captureCall(options, responseType, requestOptions, async = false) {
+        const body = { ...toWire(options), response_type: responseType };
+        return {
+            method: "POST",
+            url: this.#url(CAPTURES_PATH),
+            apiKey: this.#apiKey(),
+            body: async ? { ...body, async: true } : body,
+            idempotencyKey: requestOptions.idempotencyKey ?? randomUUID(),
+            file: responseType === "by_format",
+            // An async capture is answered at once, so it takes the ordinary timeout.
+            timeout: requestOptions.timeout ??
+                (async ? this.#config.timeout : this.#config.captureTimeout),
+            signal: requestOptions.signal,
+        };
+    }
+    #url(path) {
+        return `${this.#config.baseUrl}${path}`;
+    }
+    #apiKey() {
+        if (this.#config.apiKey === undefined) {
+            throw new AuthenticationError("No Instant Snap API key: pass instantSnapApiKey to the client or set WSW_INSTANT_SNAP_API_KEY.");
+        }
+        return this.#config.apiKey;
+    }
+}
+/** Waits `milliseconds`, or rejects with the signal's reason as soon as it aborts. */
+function sleep(milliseconds, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted === true) {
+            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 });
+    });
+}

package/dist/esm/models/capture-file.d.ts

@@ -0,0 +1,35 @@
+import type { CaptureStatus } from "./tokens.js";
+/**
+ * A file returned by `instantSnap.captureFile`, with its metadata. The body is a stream that can be
+ * read once: through `body`, `arrayBuffer()` or `saveTo()`.
+ */
+export interface CaptureFile {
+    id: string;
+    /** `delivered`: the file is in this answer and the API does not keep it. */
+    status: CaptureStatus;
+    contentType: string | null;
+    /** The name the API suggests, from `Content-Disposition`. */
+    filename: string | null;
+    width: number | null;
+    height: number | null;
+    sizeBytes: number | null;
+    /** How long the capture took. */
+    durationMs: number | null;
+    /** The status the website answered with. */
+    pageHttpStatus: number | null;
+    specVersion: string | null;
+    capturedAt: Date | null;
+    /** Where the browser ended up. `null` when the page did not redirect or the URL is not plain ASCII. */
+    finalUrl: string | null;
+    /** Lowercase hex SHA-256 of the file. */
+    sha256: string | null;
+    /** How many parts the answer has, when it has more than one. */
+    partCount: number | null;
+    /** The file itself. */
+    readonly body: ReadableStream<Uint8Array>;
+    /** Reads the whole file into memory. */
+    arrayBuffer(): Promise<ArrayBuffer>;
+    /** Streams the file to `path`, replacing any file already there. */
+    saveTo(path: string): Promise<void>;
+}
+export declare function captureFileFrom(response: Response): CaptureFile;

package/dist/esm/models/capture-file.js

@@ -0,0 +1,31 @@
+import { filenameFrom, writeBody } from "../files.js";
+import { parseDate } from "../wire.js";
+export function captureFileFrom(response) {
+    const headers = response.headers;
+    const header = (name) => headers.get(`x-instantsnap-${name}`);
+    const body = response.body ?? new Blob([]).stream();
+    return {
+        id: header("id") ?? "",
+        status: header("status") ?? "delivered",
+        contentType: headers.get("content-type"),
+        filename: filenameFrom(headers.get("content-disposition")),
+        width: integerOrNull(header("width")),
+        height: integerOrNull(header("height")),
+        sizeBytes: integerOrNull(header("size-bytes")),
+        durationMs: integerOrNull(header("duration-ms")),
+        pageHttpStatus: integerOrNull(header("page-http-status")),
+        specVersion: header("spec-version"),
+        capturedAt: parseDate(header("captured-at")),
+        finalUrl: header("final-url"),
+        sha256: header("sha256"),
+        partCount: integerOrNull(header("part-count")),
+        body,
+        arrayBuffer: () => new Response(body).arrayBuffer(),
+        saveTo: (path) => writeBody(body, path),
+    };
+}
+function integerOrNull(value) {
+    if (value === null || !/^\s*-?\d+\s*$/.test(value))
+        return null;
+    return Number(value);
+}