@websitescreenshotworld/sdk 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+All notable changes to this package are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the package uses
+[semantic versioning](https://semver.org/).
+
+## [0.1.0] - 2026-11-09
+
+The first release.
+
+### Added
+
+- `WebsiteScreenshotWorld`, one client for both products, with keys read from
+  `WSW_INSTANT_SNAP_API_KEY` and `WSW_AUTO_SCHEDULE_API_KEY` when not passed, and an optional
+  `fetch` of your own.
+- Instant Snap: `capture`, `captureFile` (the file as a stream, with its metadata, `arrayBuffer()` and
+  `saveTo()`), `captureToBucket`, `get`, `download`, `defaults` and `catalog`, with every capture
+  option typed in camelCase.
+- Instant Snap async captures: `submit` and `submitToBucket`, answered at once with the capture
+  `queued`, and `wait`, which polls `get` until it has finished; the `timeout` capture option (30 to
+  300 seconds, async only); the `queued` and `running` statuses; and the `queue_full` (a
+  `RateLimitError`, not retried) and `capture_expired` error codes.
+- Auto Schedule: `triggerNow`.
+- The `pressEscape` capture option, and the `sitemap_schedule_not_triggerable` error code (an
+  `InvalidRequestError`: a sitemap schedule runs only on its schedule), from API version 1.1.0.
+- Redirects are never followed, so the API key is never sent anywhere else; a 3xx answer is raised
+  as an error.
+- `Webhook.verify`, which checks the `X-WSW-Signature` header and returns a typed event for each of
+  `capture.succeeded`, `capture.failed`, `delivery.completed`, `capture.changed`, `schedule.paused`,
+  `sitemap_run.completed` and `ping`, and an unknown event, with its raw data, for types added later.
+- `WebsiteScreenshotWorldError` and a subclass for each kind of error, with `errorCode`, `httpStatus`,
+  `retryAfterSeconds` and the raw body, plus `ErrorCode` constants.
+- Retries of rate limits, busy or unavailable service and lost connections, with an `Idempotency-Key`
+  on every capture; timeouts and `AbortSignal` cancellation per call.
+- Named constants for the API's tokens, such as `CaptureStatus` and `CaptureFormat`, with unknown
+  values passed through as strings.
+- ES module and CommonJS builds with type definitions, for Node.js 22 and later.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Silhouettec Solutions Private Limited
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,400 @@
-# Temporary Holding Version
+# Website Screenshot World for Node.js
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The official Node.js client for [Website Screenshot World](https://websitescreenshotworld.com): capture
+web pages on demand with **Instant Snap**, start a scheduled page's capture with **Auto Schedule**, and
+verify the webhooks both products send.
+
+- Written in TypeScript, with types for every option, answer and webhook event
+- ES modules and CommonJS, no runtime dependencies
+- Retries with idempotency keys, timeouts and `AbortSignal` cancellation built in
+
+## Install
+
+```sh
+npm install @websitescreenshotworld/sdk
+```
+
+## Quick start
+
+Create a client once and reuse it. The keys default to the `WSW_INSTANT_SNAP_API_KEY` and
+`WSW_AUTO_SCHEDULE_API_KEY` environment variables; you only need the key of the product you use.
+
+### Instant Snap
+
+```ts
+import { WebsiteScreenshotWorld } from "@websitescreenshotworld/sdk";
+
+const client = new WebsiteScreenshotWorld();
+
+const capture = await client.instantSnap.capture({
+  url: "https://example.com",
+  format: "webp",
+  viewport: { width: 1440 },
+});
+
+console.log(capture.id, capture.width, capture.height);
+console.log(capture.downloadUrl); // valid for 60 minutes
+```
+
+Every option of the API is available in camelCase: `mediaCategory`, `scrollMode`, `blockAds`,
+`timestampWatermark`, `pageSource` and the rest. Options you leave out take the API's defaults, which
+`client.instantSnap.defaults()` lists; `client.instantSnap.catalog()` lists the devices and proxy
+countries you can ask for. Names in `headers` and `cookies` are sent exactly as you write them.
+
+### Auto Schedule
+
+Web pages are set up in the dashboard. Start one's capture now with its id; the outcome arrives by
+webhook.
+
+```ts
+const result = await client.autoSchedule.triggerNow(
+  "7d4e2b1a-6c5f-4a3e-9d8c-2b1a0f9e8d7c",
+);
+
+if (result.status === "already_pending") {
+  console.log("A capture was already on its way:", result.message);
+}
+```
+
+## Saving a file
+
+`captureFile` returns the file in the answer itself, as a stream, along with its metadata. The API does
+not keep the file, so save or read it before you drop the result.
+
+```ts
+const file = await client.instantSnap.captureFile({
+  url: "https://example.com",
+  format: "png",
+});
+
+console.log(file.filename, file.contentType, file.sha256);
+await file.saveTo(`./${file.filename ?? "capture.png"}`);
+```
+
+`file.body` is a web `ReadableStream` you can pipe anywhere instead, and `file.arrayBuffer()` reads the
+whole file into memory. The stream can be read once.
+
+## Uploading to a bucket
+
+`captureToBucket` uploads the file to your own S3-compatible storage. Give it a `region` for AWS, or an
+`endpointUrl` for other providers.
+
+```ts
+const capture = await client.instantSnap.captureToBucket({
+  url: "https://example.com",
+  s3Delivery: {
+    accessKeyId: process.env.S3_ACCESS_KEY_ID ?? "",
+    secretAccessKey: process.env.S3_SECRET_ACCESS_KEY ?? "",
+    bucket: "captures",
+    region: "eu-west-2",
+    keyPrefix: "example/",
+    waitForSync: true,
+  },
+});
+
+console.log(capture.s3Delivery?.status, capture.s3Delivery?.key);
+```
+
+## Async captures
+
+`submit` and `submitToBucket` do not wait for the capture: the API accepts it at once and returns it with
+`status: "queued"`, and it runs when a browser is free (`running`, then `succeeded` or `failed`). `wait`
+reads it with `get` every few seconds until it has finished.
+
+```ts
+import { CaptureStatus } from "@websitescreenshotworld/sdk";
+
+const queued = await client.instantSnap.submit({
+  url: "https://example.com",
+  timeout: 240, // seconds of browser time, 30 to 300; the API uses 120 when left out
+});
+
+const capture = await client.instantSnap.wait(queued.id, {
+  timeoutSeconds: 600, // default 360
+  pollIntervalSeconds: 5, // default 3
+});
+
+if (capture.status === CaptureStatus.Succeeded) {
+  await client.instantSnap.download(capture, "./capture.png");
+}
+
+const toBucket = await client.instantSnap.submitToBucket({
+  url: "https://example.com",
+  s3Delivery: {
+    accessKeyId: process.env.S3_ACCESS_KEY_ID ?? "",
+    secretAccessKey: process.env.S3_SECRET_ACCESS_KEY ?? "",
+    bucket: "captures",
+    region: "eu-west-2",
+  },
+});
+console.log(toBucket.status); // "queued"; wait for it the same way
+```
+
+When `timeoutSeconds` runs out first, `wait` returns the capture as last read, still `queued` or
+`running`, rather than throwing, so you can wait again. It takes an `AbortSignal` as `signal`. Instead of
+waiting, you can also set `callbackUrl` and receive the `capture.succeeded` or `capture.failed` webhook.
+
+`timeout` is only for `submit` and `submitToBucket`; the API refuses it on the other capture calls. The
+submit call itself uses the client's `timeout` (30 seconds), not `captureTimeout`, since it is answered at
+once. A capture still queued 15 minutes after it was accepted ends `failed` with `capture_expired`, and is
+not charged. When your organization already has as many async captures waiting or running as it may, the
+API answers `queue_full`: the client throws it at once as a `RateLimitError` with `retryAfterSeconds`,
+without retrying.
+
+## Reading a capture back
+
+Files are kept for 24 hours. `get` returns the capture with a fresh `downloadUrl`, and `download` writes
+the file (or the page source) to a path, a Node.js stream or a web `WritableStream`.
+
+```ts
+const capture = await client.instantSnap.get(
+  "3f6c2a1e-9b8d-4c7e-a5f4-1d2e3c4b5a69",
+);
+
+await client.instantSnap.download(capture, "./capture.png");
+if (capture.pageSource !== null) {
+  await client.instantSnap.download(capture.pageSource, "./capture.html");
+}
+```
+
+## Errors and retries
+
+Every error is a `WebsiteScreenshotWorldError`, with `errorCode`, `message`, `httpStatus`,
+`retryAfterSeconds` and `rawBody`. Each kind of refusal has its own subclass:
+
+| Class                        | When                                                         |
+| ---------------------------- | ------------------------------------------------------------ |
+| `AuthenticationError`        | The API key is missing, invalid or for the other product     |
+| `InvalidRequestError`        | The request was invalid, such as an out-of-range option      |
+| `PlanLimitError`             | The plan has no captures left, or does not include a feature |
+| `NotFoundError`              | No such capture or web page for this account                 |
+| `RateLimitError`             | Too many requests even after retrying, or the queue is full  |
+| `CaptureError`               | The website could not be captured, or the file was too large |
+| `ServiceError`               | The service was busy or failed on its side                   |
+| `ConnectionError`            | No answer came back, or the call ran out of time             |
+| `SignatureVerificationError` | A webhook's signature did not check out                      |
+
+Decide what to do from `errorCode`, never from the status or the message. The `ErrorCode` constants name
+the codes the API sends today; a code added later arrives as the base class with its new code.
+
+```ts
+import {
+  CaptureError,
+  ErrorCode,
+  PlanLimitError,
+  WebsiteScreenshotWorldError,
+} from "@websitescreenshotworld/sdk";
+
+try {
+  await client.instantSnap.capture({ url: "https://example.com" });
+} catch (error) {
+  if (
+    error instanceof CaptureError &&
+    error.errorCode === ErrorCode.CaptureTimeout
+  ) {
+    // The page took too long to load: a longer pageTimeoutMs may help.
+  } else if (error instanceof PlanLimitError) {
+    // Out of captures, or the plan does not include an option that was asked for.
+  } else if (error instanceof WebsiteScreenshotWorldError) {
+    console.error(error.errorCode, error.message);
+  } else {
+    throw error;
+  }
+}
+```
+
+The client retries what is safe and likely to succeed: `rate_limited`, `capture_busy`,
+`service_unavailable`, `idempotency_key_in_use` and requests that got no answer. It waits as long as the
+API asks (up to a minute), otherwise 0.5 seconds and then 1 second, with a little jitter. It retries twice
+by default; set `maxRetries` to change that. A failed or timed-out capture is not retried, and neither is
+`queue_full` from `submit`: the queue stays full until captures finish, so you decide when to try again.
+
+## Idempotency keys
+
+Every capture carries an `Idempotency-Key`, and retries of that call reuse it, so a retry never captures
+twice. Pass your own key to make a capture safe to repeat across calls and processes for 24 hours:
+
+```ts
+const hero = await client.instantSnap.capture(
+  { url: "https://example.com" },
+  { idempotencyKey: "order-1234-hero" },
+);
+```
+
+Trigger-now needs no key: a second call while the first capture is pending answers `already_pending`.
+
+## Timeouts and cancellation
+
+A capture may take up to 120 seconds on the API's side, so capture calls time out after 180
+seconds and other calls after 30, retries included. Change them for the client or per call, and pass an
+`AbortSignal` to cancel:
+
+```ts
+const quick = new WebsiteScreenshotWorld({ captureTimeout: 60_000 });
+
+const controller = new AbortController();
+const pending = quick.instantSnap.capture(
+  { url: "https://example.com" },
+  { timeout: 90_000, signal: controller.signal },
+);
+controller.abort(); // `pending` rejects with the signal's reason
+```
+
+`submit` and `submitToBucket` use `timeout`, not `captureTimeout`. A timeout raises `ConnectionError`. Cancelling stops the call and any retry it would make at once.
+
+## Webhooks
+
+Each delivery is signed in its `X-WSW-Signature` header. `Webhook.verify` checks the signature against
+the raw body and returns the event, typed by `type` and, for captures, by `product`:
+
+```ts
+import { Webhook, type WebhookEvent } from "@websitescreenshotworld/sdk";
+
+const secret = process.env.WSW_WEBHOOK_SECRET ?? "";
+
+function handle(event: WebhookEvent): void {
+  switch (event.type) {
+    case "capture.succeeded":
+      if (event.product === "instant_snap") {
+        console.log(
+          "Instant Snap capture",
+          event.data.id,
+          event.data.mediaSha256,
+        );
+      } else if (event.product === "auto_schedule") {
+        console.log("Scheduled capture of", event.data.scheduleName);
+      }
+      break;
+    case "capture.changed":
+      console.log(event.data.url, "changed by", event.data.changePercent, "%");
+      break;
+    case "ping":
+      console.log(event.data.message);
+      break;
+    default:
+      // An event type added after this version: its type and raw data still arrive.
+      if ("rawData" in event) console.log(event.type, event.rawData);
+  }
+}
+```
+
+The other events are `capture.failed`, `delivery.completed`, `schedule.paused` and
+`sitemap_run.completed`; `WebhookEventType` names them all. `verify` throws `SignatureVerificationError`
+when the signature does not match or its timestamp is more than five minutes from now; pass
+`{ tolerance }` in seconds to change that.
+
+The signature covers the exact bytes that were sent, so give `verify` the raw body, not JSON your
+framework parsed and serialised again. The examples below reuse `secret` and `handle` from above.
+
+### Express
+
+```ts
+import express from "express";
+
+const app = express();
+
+app.post(
+  "/webhooks/wsw",
+  express.raw({ type: "application/json" }),
+  (request, response) => {
+    try {
+      const event = Webhook.verify(
+        request.body as Buffer,
+        request.get("X-WSW-Signature"),
+        secret,
+      );
+      handle(event);
+      response.sendStatus(204);
+    } catch {
+      response.sendStatus(400);
+    }
+  },
+);
+```
+
+### Fastify
+
+```ts
+import Fastify from "fastify";
+
+const fastify = Fastify();
+
+fastify.register(async (webhooks) => {
+  webhooks.addContentTypeParser(
+    "application/json",
+    { parseAs: "buffer" },
+    (_request, body, done) => {
+      done(null, body);
+    },
+  );
+
+  webhooks.post("/webhooks/wsw", async (request, reply) => {
+    try {
+      const event = Webhook.verify(
+        request.body as Buffer,
+        request.headers["x-wsw-signature"],
+        secret,
+      );
+      handle(event);
+      return reply.code(204).send();
+    } catch {
+      return reply.code(400).send();
+    }
+  });
+});
+```
+
+### Next.js (App Router)
+
+```ts
+// app/webhooks/wsw/route.ts
+export async function POST(request: Request): Promise<Response> {
+  try {
+    const event = Webhook.verify(
+      await request.text(),
+      request.headers.get("X-WSW-Signature"),
+      secret,
+    );
+    handle(event);
+    return new Response(null, { status: 204 });
+  } catch {
+    return new Response(null, { status: 400 });
+  }
+}
+```
+
+## Configuration
+
+| Option                | Default                                      |
+| --------------------- | -------------------------------------------- |
+| `instantSnapApiKey`   | `WSW_INSTANT_SNAP_API_KEY`                   |
+| `autoScheduleApiKey`  | `WSW_AUTO_SCHEDULE_API_KEY`                  |
+| `instantSnapBaseUrl`  | `https://api.websitescreenshotworld.com`     |
+| `autoScheduleBaseUrl` | `https://autoapi.websitescreenshotworld.com` |
+| `captureTimeout`      | `180_000` milliseconds                       |
+| `timeout`             | `30_000` milliseconds                        |
+| `maxRetries`          | `2`                                          |
+| `fetch`               | the global `fetch`                           |
+
+Either key can be left out. Calling a product without its key throws `AuthenticationError` before
+anything is sent.
+
+## Supported runtimes
+
+Node.js 22 and later, from ES modules or CommonJS. The type definitions need TypeScript 5.0 or later.
+
+## Development
+
+```sh
+npm ci
+npm test       # builds, then runs the unit tests and the shared conformance cases
+npm run lint   # ESLint, Prettier and the type checker
+```
+
+The tests start `spec/conformance/server.js` and read the shared cases in `spec/`, the
+[websitescreenshotworld-spec](https://github.com/websitescreenshotworld/websitescreenshotworld-spec) submodule, so
+clone with `git clone --recurse-submodules`, or run `git submodule update --init` in an existing clone.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/dist/cjs/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/cjs/auto-schedule.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AutoSchedule = void 0;
+const errors_js_1 = require("./errors.js");
+const trigger_result_js_1 = require("./models/trigger-result.js");
+/** Scheduled captures of the web pages set up in the dashboard. */
+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 errors_js_1.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 (0, trigger_result_js_1.parseTriggerResult)(wire);
+    }
+}
+exports.AutoSchedule = AutoSchedule;

package/dist/cjs/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/cjs/client.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebsiteScreenshotWorld = void 0;
+const auto_schedule_js_1 = require("./auto-schedule.js");
+const instant_snap_js_1 = require("./instant-snap.js");
+const transport_js_1 = require("./transport.js");
+const version_js_1 = require("./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" });
+ * ```
+ */
+class WebsiteScreenshotWorld {
+    /** On-demand captures. */
+    instantSnap;
+    /** Captures of scheduled web pages. */
+    autoSchedule;
+    constructor(options = {}) {
+        const transport = new transport_js_1.Transport({
+            fetch: options.fetch,
+            maxRetries: options.maxRetries ?? DEFAULT_MAX_RETRIES,
+            userAgent: `websitescreenshotworld-node/${version_js_1.VERSION} (node ${process.versions.node})`,
+        });
+        const timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
+        this.instantSnap = new instant_snap_js_1.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 auto_schedule_js_1.AutoSchedule({
+            transport,
+            apiKey: apiKey(options.autoScheduleApiKey, "WSW_AUTO_SCHEDULE_API_KEY"),
+            baseUrl: withoutTrailingSlash(options.autoScheduleBaseUrl ?? DEFAULT_AUTO_SCHEDULE_BASE_URL),
+            timeout,
+        });
+    }
+}
+exports.WebsiteScreenshotWorld = WebsiteScreenshotWorld;
+/** 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/cjs/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";