@scrapa/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 scrapa.app
+
+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

@@ -0,0 +1,232 @@
+# @scrapa/sdk
+
+The official TypeScript client for [scrapa.app](https://scrapa.app) — read any web page as
+markdown, HTML, text, links, a screenshot or a PDF, through a plain HTTP request or a real
+browser, whichever the page turns out to need. Search the web through the same key, and hold
+a real Chromium your own Playwright or Puppeteer drives.
+
+```bash
+npm i @scrapa/sdk
+```
+
+```ts
+import { Scrapa } from "@scrapa/sdk";
+
+const scrapa = new Scrapa(process.env.SCRAPA_API_KEY!);
+
+const page = await scrapa.scrape({ url: "https://example.com" });
+console.log(page.markdown);
+```
+
+Every method, every argument and every field is generated from the API's own definitions, so
+what your editor autocompletes is what the server accepts. Node 20+, Bun, Deno, workers and
+the browser — anywhere `fetch` exists.
+
+## Reading a page
+
+`scrape()` takes a URL and gives you the page. `engine` defaults to `auto`: a plain HTTP
+request first, re-read in a real Chromium only when the body turns out to be a JavaScript
+shell — which is the difference between 1 credit and 5.
+
+```ts
+const page = await scrapa.scrape({
+    url: "https://news.ycombinator.com",
+    formats: ["markdown", "links"],
+});
+
+page.engine; // "fetch" — this one did not need a browser
+page.links; // every absolute link, in document order
+page.metadata.title;
+```
+
+Ask for a screenshot or a PDF and the browser is used whatever `engine` says. Both come back
+base64-encoded, and asking for both costs no more than asking for one.
+
+```ts
+const shot = await scrapa.scrape({ url: "https://stripe.com", formats: ["screenshot"] });
+await writeFile("stripe.png", Buffer.from(shot.screenshot!, "base64"));
+```
+
+## Searching the web
+
+`search()` runs a real search and hands back results we read ourselves. That is not a
+detail — every search vendor forbids redistributing their results through another API, so
+our own fetch is the only kind you are allowed to build on.
+
+```ts
+const found = await scrapa.search({
+    query: "melhores frameworks typescript 2026",
+    limit: 10,
+    proxy: { country: "br" }, // picks the exit AND the market: Brazilian results, in Portuguese
+});
+
+found.results[0].url; // array order IS the ranking — no score to sort by, because none is real
+found.cached; // the same question inside the window costs nothing and says so
+```
+
+`topic: "news"` is the one topic that reliably carries `publishedAt`. `includeDomains` is
+asked of the front *and* enforced on the answer, so what comes back is on your list whatever
+the front did with the operator. `answer: true` adds a paragraph written over the hits. To
+read any result, hand its URL straight to `scrape()`.
+
+A search every front refused costs nothing. A search that ran and found nothing is charged —
+the index answered, and "nothing published that" is an answer.
+
+## Driving a real browser
+
+A session is one Chromium held for you, with a CDP URL your own tools connect to. We hand
+back a URL rather than a client, so everything you already know how to do with Playwright or
+Puppeteer keeps working.
+
+```ts
+import { chromium } from "playwright";
+
+const session = await scrapa.sessions.create({ timeoutMin: 10 });
+const browser = await chromium.connectOverCDP(session.connectUrl);
+
+try {
+    const page = await browser.newPage();
+    await page.goto("https://example.com");
+    await page.getByRole("button", { name: "Accept" }).click();
+} finally {
+    await browser.close();
+    await scrapa.sessions.close({ id: session.id });
+}
+```
+
+`create()` returns only once Chromium is actually up, so `connectUrl` is a required field and
+needs no `!`. It carries the session's token, is shown once and cannot be rebuilt from the id
+— which is why `get()` does not repeat it.
+
+Minutes are reserved for the whole window and settled by what you used, so closing early
+hands the rest back. A browser that never came up costs nothing at all, and if you forget to
+close one, it is reaped at `expiresAt` and settled the same way.
+
+## Reading a list of pages
+
+A batch is N scrapes on our schedule instead of your connection. Same options, same engines,
+same meter — what you buy is not holding a socket open for an hour.
+
+```ts
+const batch = await scrapa.batches.create({
+    urls: sitemap.map((entry) => entry.loc),
+    formats: ["markdown"],
+});
+
+let status = await scrapa.batches.get({ id: batch.id });
+while (status.completed < status.total) {
+    await new Promise((resolve) => setTimeout(resolve, 5_000));
+    status = await scrapa.batches.get({ id: batch.id });
+}
+
+for (let from = 0; from < status.total; ) {
+    const page = await scrapa.batches.get({ id: batch.id, items: true, from });
+    for (const item of page.items ?? []) {
+        if (item.status === "done") save(item.url, item.result!.markdown);
+    }
+    from += page.items?.length ?? status.total;
+}
+```
+
+Nothing is charged when you submit and nothing is reserved: each URL then costs what the same
+call would have cost alone, and `cost` on the batch is what it has spent so far. Because
+nothing is held up front, a batch can outlive the credits that started it — those URLs come
+back `skipped` rather than `failed`, which is not a verdict about the URL, and you can submit
+exactly those positions again.
+
+`completed` counts every URL that reached an end, so it is what you compare against `total`;
+`failed` and `skipped` both live inside it. Results are readable for 24 hours, up to two
+hundred items per read.
+
+Rather not poll? Pass a `webhook` and we will POST when it is done. The signing secret comes
+back once, on the create — verify a delivery with HMAC-SHA256 over `<timestamp>.<raw body>`
+against the `v1=` value in the `scrapa-signature` header.
+
+## What it costs, per call
+
+Every metered answer carries what it cost and what is left. Methods hand you the page itself,
+so the meter arrives through a callback — per call, rather than a mutable field two concurrent
+scrapes would fight over.
+
+```ts
+await scrapa.scrape(
+    { url: "https://example.com" },
+    { onUsage: ({ cost, creditsRemaining }) => console.log(cost, creditsRemaining) },
+);
+
+// …or price the call without making it:
+const { cost, maxCost } = await scrapa.quote({ url: "https://example.com" });
+```
+
+`maxCost` is the ceiling: with `auto` it is the browser's price, charged only if the page
+turns out to need one.
+
+## When something says no
+
+A refusal tells you *who* said no, and that decides what you do next.
+
+```ts
+import { ScrapaError } from "@scrapa/sdk";
+
+try {
+    await scrapa.scrape({ url });
+} catch (error) {
+    if (!(error instanceof ScrapaError)) throw error;
+    switch (error.outcome) {
+        case "blocked": // the site said no — try another pool, country or engine
+            return scrapa.scrape({ url, proxy: { pool: "residential", country: "de" } });
+        case "denied": // our policy said no — retrying cannot help, change the URL
+            return null;
+        case "broken": // we broke it, and already refunded it — worth one retry
+            return scrapa.scrape({ url });
+    }
+    throw error; // your own mistake: a bad field, a missing key, a spent quota
+}
+```
+
+`error.cost` is `0` on every one of those, because a page you did not get is a page you do not
+pay for. `error.code` carries the exact reason, `error.retryAfter` says when a limit clears,
+and `error.requestId` is what support needs to find the call.
+
+The client repeats a call only when a repeat can fix it: something we broke (already refunded)
+or a rate limit that says when it clears. It never repeats a call that timed out on your side,
+because that one may already have read the page — you get the error and decide.
+
+## Bringing your own proxy
+
+```ts
+await scrapa.scrape({
+    url: "https://example.com",
+    proxy: { pool: "custom", server: "http://user:pass@proxy.example:8080" },
+});
+```
+
+Free on every plan, including the free one, and the bytes are never billed.
+
+## Reading the meter
+
+```ts
+const usage = await scrapa.usage.get();
+usage.creditsUsed; // this billing month
+usage.creditsIncluded;
+usage.creditBalance; // purchased credits, which never expire
+usage.resetAt;
+```
+
+## Options
+
+```ts
+new Scrapa({
+    apiKey: "sc_…",
+    baseUrl: "https://api.scrapa.app/v1", // point at another deployment
+    timeout: 65_000, // per attempt, above the API's own ceiling
+    maxRetries: 2, // 0 disables
+    fetch: myFetch, // a proxy agent, a test double
+});
+```
+
+Full reference: [docs.scrapa.app](https://docs.scrapa.app).
+
+## Licence
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,47 @@
+import { type UsageMeta } from "./generated/contract.ts";
+import { GeneratedOperations } from "./generated/operations.ts";
+export interface ScrapaOptions {
+    /** An `sc_` key from the console. */
+    apiKey: string;
+    /** Defaults to the hosted API. */
+    baseUrl?: string;
+    /** Per-attempt timeout in ms. Default 65000 — above the API's own 60s ceiling for a
+     *  scrape, so this fires only when something is genuinely wrong. */
+    timeout?: number;
+    /** Extra attempts for the failures a repeat can fix. Default 2, 0 disables. */
+    maxRetries?: number;
+    /** Swap the fetch implementation (tests, a proxy, a custom agent). */
+    fetch?: typeof globalThis.fetch;
+}
+/** What a generated method hands the transport. */
+export interface RequestSpec {
+    method: "GET" | "POST" | "DELETE";
+    /** `/sessions/{id}` — a `{name}` is filled from the params and dropped from the rest. */
+    path: string;
+    /** Safe to repeat: a refunded failure can be retried without charging twice. */
+    idempotent: boolean;
+}
+/** Per-call overrides. */
+export interface RequestOptions {
+    /** Abort this call — yours to control, and the API stops paying for egress when it fires. */
+    signal?: AbortSignal;
+    /** Override the client's timeout for one call. */
+    timeout?: number;
+    /** What the call cost and what is left, as the answer carries it. A method returns the
+     *  page itself, so this is where the meter goes for the callers who want it — per call,
+     *  rather than a mutable `lastUsage` that two concurrent scrapes would fight over. */
+    onUsage?: (usage: UsageMeta) => void;
+}
+export declare class Scrapa extends GeneratedOperations {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    private readonly maxRetries;
+    private readonly fetchImpl;
+    constructor(options: ScrapaOptions | string);
+    protected request<T>(spec: RequestSpec, params?: object, opts?: RequestOptions): Promise<T>;
+    /** How long to wait before repeating a call, or undefined to give up now. */
+    private retryDelay;
+    private attempt;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAUA,OAAO,EAA2B,KAAK,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAClF,OAAO,EAAoB,mBAAmB,EAAe,MAAM,2BAA2B,CAAC;AAE/F,MAAM,WAAW,aAAa;IAC1B,qCAAqC;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,kCAAkC;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;wEACoE;IACpE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+EAA+E;IAC/E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACnC;AAED,mDAAmD;AACnD,MAAM,WAAW,WAAW;IACxB,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,QAAQ,CAAC;IAClC,yFAAyF;IACzF,IAAI,EAAE,MAAM,CAAC;IACb,gFAAgF;IAChF,UAAU,EAAE,OAAO,CAAC;CACvB;AAED,0BAA0B;AAC1B,MAAM,WAAW,cAAc;IAC3B,6FAA6F;IAC7F,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,kDAAkD;IAClD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;0FAEsF;IACtF,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;CACxC;AAkCD,qBAAa,MAAO,SAAQ,mBAAmB;IAC3C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA0B;gBAExC,OAAO,EAAE,aAAa,GAAG,MAAM;cAqB3B,OAAO,CAAC,CAAC,EACrB,IAAI,EAAE,WAAW,EACjB,MAAM,GAAE,MAAW,EACnB,IAAI,GAAE,cAAmB,GAC1B,OAAO,CAAC,CAAC,CAAC;IAcb,6EAA6E;IAC7E,OAAO,CAAC,UAAU;YAcJ,OAAO;CAqFxB"}

package/dist/client.js

@@ -0,0 +1,182 @@
+// The transport under every generated method: one request, one `{ data }` unwrap, one error
+// taxonomy.
+//
+// The retry policy is the opinionated part, and it is narrow on purpose. A scrape that we
+// broke was already refunded, so repeating it costs nothing; a rate limit says when it
+// clears. But a call that timed out on YOUR side may well have answered on ours — repeating
+// it reads the page twice and charges twice — so the client hands that one back with its
+// code and lets you decide. The default timeout sits above the API's own ceiling, which is
+// what makes a client-side timeout genuinely exceptional rather than routine.
+import { ScrapaError } from "./errors.js";
+import { HEADERS } from "./generated/contract.js";
+import { DEFAULT_BASE_URL, GeneratedOperations, SDK_VERSION } from "./generated/operations.js";
+/** A Retry-After we would honour beyond this is not a retry, it is a hang: the caller gets
+ *  the error (with `retryAfter` on it) and schedules it themselves. */
+const MAX_RETRY_DELAY_MS = 10_000;
+/** What the API answers with when it never got to answer at all. */
+function statusCode(status) {
+    if (status === 503)
+        return "SERVICE_UNAVAILABLE";
+    if (status === 404)
+        return "NOT_FOUND";
+    if (status === 401)
+        return "UNAUTHORIZED";
+    return "INTERNAL_ERROR";
+}
+/** Seconds from `Retry-After`, or from the error's own details. */
+function retryAfterOf(header, details) {
+    const fromDetails = typeof details === "object" && details !== null
+        ? details.retryAfterSecs
+        : undefined;
+    if (typeof fromDetails === "number" && Number.isFinite(fromDetails))
+        return fromDetails;
+    const seconds = header === null ? NaN : Number(header);
+    return Number.isFinite(seconds) ? seconds : undefined;
+}
+function numberHeader(response, name) {
+    const raw = response.headers.get(name);
+    if (raw === null)
+        return undefined;
+    const value = Number(raw);
+    return Number.isFinite(value) ? value : undefined;
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export class Scrapa extends GeneratedOperations {
+    apiKey;
+    baseUrl;
+    timeout;
+    maxRetries;
+    fetchImpl;
+    constructor(options) {
+        super();
+        const opts = typeof options === "string" ? { apiKey: options } : options;
+        if (!opts.apiKey)
+            throw new TypeError("scrapa: an API key is required — create one at https://console.scrapa.app/keys");
+        this.apiKey = opts.apiKey;
+        // A trailing slash would double up against a path's leading one.
+        this.baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+        this.timeout = opts.timeout ?? 65_000;
+        this.maxRetries = opts.maxRetries ?? 2;
+        const impl = opts.fetch ?? globalThis.fetch;
+        if (typeof impl !== "function")
+            throw new TypeError("scrapa: no global fetch — use Node 20+, or pass `fetch` in the options.");
+        // Bound: an unbound global fetch throws "Illegal invocation" in browsers.
+        this.fetchImpl = opts.fetch ?? impl.bind(globalThis);
+    }
+    async request(spec, params = {}, opts = {}) {
+        const retries = spec.idempotent ? this.maxRetries : 0;
+        for (let attempt = 0;; attempt++) {
+            try {
+                return await this.attempt(spec, params, opts);
+            }
+            catch (error) {
+                if (!(error instanceof ScrapaError) || attempt >= retries)
+                    throw error;
+                const delay = this.retryDelay(error, attempt);
+                if (delay === undefined)
+                    throw error;
+                await sleep(delay);
+            }
+        }
+    }
+    /** How long to wait before repeating a call, or undefined to give up now. */
+    retryDelay(error, attempt) {
+        // A timeout on OUR side may have answered on theirs; repeating it would read the
+        // page — and charge for it — twice. The caller gets the error and decides.
+        const worthRepeating = error.retryable && error.code !== "TIMEOUT";
+        if (!worthRepeating)
+            return undefined;
+        if (error.retryAfter !== undefined) {
+            const ms = error.retryAfter * 1_000;
+            return ms > MAX_RETRY_DELAY_MS ? undefined : ms;
+        }
+        // Exponential with jitter, so a fleet of clients does not resynchronise onto the
+        // same second after an outage.
+        return Math.min(250 * 2 ** attempt, 4_000) * (0.5 + Math.random());
+    }
+    async attempt(spec, params, opts) {
+        const rest = { ...params };
+        // A templated segment is spent on the URL, not sent again as a query parameter.
+        const path = spec.path.replace(/\{(\w+)\}/g, (_, key) => {
+            const value = rest[key];
+            delete rest[key];
+            return encodeURIComponent(String(value ?? ""));
+        });
+        const url = new URL(this.baseUrl + path);
+        const hasBody = spec.method === "POST";
+        if (!hasBody)
+            for (const [key, value] of Object.entries(rest))
+                if (value !== undefined && value !== null)
+                    url.searchParams.set(key, String(value));
+        const headers = {
+            authorization: `Bearer ${this.apiKey}`,
+            accept: "application/json",
+            [HEADERS.client]: `scrapa-js/${SDK_VERSION}`,
+        };
+        if (hasBody)
+            headers["content-type"] = "application/json";
+        const timeout = AbortSignal.timeout(opts.timeout ?? this.timeout);
+        let response;
+        try {
+            response = await this.fetchImpl(url.toString(), {
+                method: spec.method,
+                headers,
+                ...(hasBody ? { body: JSON.stringify(rest) } : undefined),
+                signal: opts.signal ? AbortSignal.any([opts.signal, timeout]) : timeout,
+            });
+        }
+        catch (cause) {
+            // The caller's own abort is theirs, not a failure of ours to describe.
+            if (opts.signal?.aborted)
+                throw cause;
+            const timedOut = cause instanceof Error && cause.name === "TimeoutError";
+            throw new ScrapaError({
+                code: (timedOut ? "TIMEOUT" : "NETWORK_ERROR"),
+                status: 0,
+                message: timedOut
+                    ? `scrapa: no answer within ${opts.timeout ?? this.timeout}ms — the page may still have been read and charged.`
+                    : `scrapa: could not reach ${url.host}.`,
+                cause,
+            });
+        }
+        const requestId = response.headers.get(HEADERS.requestId) ?? undefined;
+        const text = await response.text();
+        let payload;
+        try {
+            payload = text ? JSON.parse(text) : undefined;
+        }
+        catch {
+            payload = undefined;
+        }
+        if (response.ok) {
+            const answer = payload;
+            if (opts.onUsage && answer.meta)
+                opts.onUsage(answer.meta);
+            return answer.data;
+        }
+        const envelope = typeof payload === "object" && payload !== null
+            ? payload.error
+            : undefined;
+        const details = envelope?.details;
+        throw new ScrapaError({
+            code: envelope?.code ?? statusCode(response.status),
+            status: response.status,
+            // A proxy or a cold start can answer HTML; say what actually came back rather
+            // than pretending the body was ours.
+            message: typeof envelope?.message === "string"
+                ? envelope.message
+                : `scrapa: ${spec.method} ${spec.path} failed with ${response.status}.`,
+            messageKey: typeof envelope?.messageKey === "string" ? envelope.messageKey : undefined,
+            params: envelope?.params,
+            details: envelope ? details : text.slice(0, 500) || undefined,
+            retryAfter: retryAfterOf(response.headers.get(HEADERS.retryAfter), details),
+            requestId,
+            // Every metered answer says what it cost, refusals included: a blocked page
+            // reports 0, and that is how "blocked pages cost nothing" is verifiable rather
+            // than asserted.
+            cost: numberHeader(response, HEADERS.cost),
+            creditsRemaining: numberHeader(response, HEADERS.creditsRemaining),
+        });
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,50 @@
+import { type ErrorCode } from "./generated/contract.ts";
+/** Failures that never reached the API, so they carry no server code. */
+export type ClientErrorCode = "NETWORK_ERROR" | "TIMEOUT";
+export interface ScrapaErrorInit {
+    code: ErrorCode | ClientErrorCode;
+    message: string;
+    /** HTTP status, or 0 when no answer arrived. */
+    status: number;
+    messageKey?: string;
+    params?: Record<string, string | number>;
+    details?: unknown;
+    /** Seconds until the call is worth making again, when the API said. */
+    retryAfter?: number;
+    /** `X-Request-ID` — quote it to support and we can find the call. */
+    requestId?: string;
+    /** What this call cost. Zero on every refusal the API charges nothing for, which is
+     *  every refusal except a page that answered. */
+    cost?: number;
+    creditsRemaining?: number;
+    cause?: unknown;
+}
+export declare class ScrapaError extends Error {
+    readonly code: ErrorCode | ClientErrorCode;
+    readonly status: number;
+    readonly messageKey?: string;
+    readonly params?: Record<string, string | number>;
+    readonly details?: unknown;
+    readonly retryAfter?: number;
+    readonly requestId?: string;
+    readonly cost?: number;
+    readonly creditsRemaining?: number;
+    constructor(init: ScrapaErrorInit);
+    /**
+     * Who said no — the one thing that decides what to do next.
+     *
+     *   "blocked" the site refused the page. It cost you nothing: try another engine, pool
+     *             or country. The same call again will be refused again.
+     *   "denied"  our policy refused this URL (a private address, the acceptable-use list).
+     *             Retrying cannot help; change the URL.
+     *   "broken"  we broke it, and already refunded it. Worth one retry as-is.
+     *
+     * `undefined` for the refusals that were the caller's own doing — a bad field, a missing
+     * key, a spent quota — which are not outcomes of a page at all.
+     */
+    get outcome(): "blocked" | "denied" | "broken" | undefined;
+    /** True when repeating the identical call could work. A limit that clears by waiting
+     *  and anything we broke, never a verdict on the page itself. */
+    get retryable(): boolean;
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAOA,OAAO,EAAc,KAAK,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAErE,yEAAyE;AACzE,MAAM,MAAM,eAAe,GAAG,eAAe,GAAG,SAAS,CAAC;AAE1D,MAAM,WAAW,eAAe;IAC5B,IAAI,EAAE,SAAS,GAAG,eAAe,CAAC;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;IACzC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;qDACiD;IACjD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,KAAK,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,qBAAa,WAAY,SAAQ,KAAK;IAClC,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,eAAe,CAAC;IAC3C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;IAClD,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;gBAEvB,IAAI,EAAE,eAAe;IAcjC;;;;;;;;;;;OAWG;IACH,IAAI,OAAO,IAAI,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAEzD;IAED;qEACiE;IACjE,IAAI,SAAS,IAAI,OAAO,CAOvB;CACJ"}

package/dist/errors.js

@@ -0,0 +1,56 @@
+// Every failure this client can raise, as one class.
+//
+// The API answers a refusal with a machine-readable code, and acting on the code is the
+// whole point: it says WHO said no, which is what decides the caller's next move. The site
+// blocked the page (try another engine, pool or country), our policy refused the URL
+// (retrying cannot help), a limit needs waiting out, or we broke it (retry as-is, it was
+// refunded). Collapse that into `Error("Request failed")` and the caller is left guessing.
+import { OUTCOME_OF } from "./generated/contract.js";
+export class ScrapaError extends Error {
+    code;
+    status;
+    messageKey;
+    params;
+    details;
+    retryAfter;
+    requestId;
+    cost;
+    creditsRemaining;
+    constructor(init) {
+        super(init.message, init.cause !== undefined ? { cause: init.cause } : undefined);
+        this.name = "ScrapaError";
+        this.code = init.code;
+        this.status = init.status;
+        this.messageKey = init.messageKey;
+        this.params = init.params;
+        this.details = init.details;
+        this.retryAfter = init.retryAfter;
+        this.requestId = init.requestId;
+        this.cost = init.cost;
+        this.creditsRemaining = init.creditsRemaining;
+    }
+    /**
+     * Who said no — the one thing that decides what to do next.
+     *
+     *   "blocked" the site refused the page. It cost you nothing: try another engine, pool
+     *             or country. The same call again will be refused again.
+     *   "denied"  our policy refused this URL (a private address, the acceptable-use list).
+     *             Retrying cannot help; change the URL.
+     *   "broken"  we broke it, and already refunded it. Worth one retry as-is.
+     *
+     * `undefined` for the refusals that were the caller's own doing — a bad field, a missing
+     * key, a spent quota — which are not outcomes of a page at all.
+     */
+    get outcome() {
+        return OUTCOME_OF[this.code];
+    }
+    /** True when repeating the identical call could work. A limit that clears by waiting
+     *  and anything we broke, never a verdict on the page itself. */
+    get retryable() {
+        return (this.code === "NETWORK_ERROR" ||
+            this.code === "TIMEOUT" ||
+            this.code === "RATE_LIMIT_EXCEEDED" ||
+            this.outcome === "broken");
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,qDAAqD;AACrD,EAAE;AACF,wFAAwF;AACxF,2FAA2F;AAC3F,qFAAqF;AACrF,yFAAyF;AACzF,2FAA2F;AAC3F,OAAO,EAAE,UAAU,EAAkB,MAAM,yBAAyB,CAAC;AAwBrE,MAAM,OAAO,WAAY,SAAQ,KAAK;IACzB,IAAI,CAA8B;IAClC,MAAM,CAAS;IACf,UAAU,CAAU;IACpB,MAAM,CAAmC;IACzC,OAAO,CAAW;IAClB,UAAU,CAAU;IACpB,SAAS,CAAU;IACnB,IAAI,CAAU;IACd,gBAAgB,CAAU;IAEnC,YAAY,IAAqB;QAC7B,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QAClF,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;QAC1B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;QAClC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;QAC5B,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;QAClC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;QAChC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC,gBAAgB,CAAC;IAClD,CAAC;IAED;;;;;;;;;;;OAWG;IACH,IAAI,OAAO;QACP,OAAO,UAAU,CAAC,IAAI,CAAC,IAAiB,CAAC,CAAC;IAC9C,CAAC;IAED;qEACiE;IACjE,IAAI,SAAS;QACT,OAAO,CACH,IAAI,CAAC,IAAI,KAAK,eAAe;YAC7B,IAAI,CAAC,IAAI,KAAK,SAAS;YACvB,IAAI,CAAC,IAAI,KAAK,qBAAqB;YACnC,IAAI,CAAC,OAAO,KAAK,QAAQ,CAC5B,CAAC;IACN,CAAC;CACJ"}