@scrapa/sdk 0.1.0

package/src/generated/params.ts

@@ -0,0 +1,437 @@
+// GENERATED FILE — do not edit. Run `bun run sdk:gen`.
+// Source: apps/api/src/operations/*.ts (zod input schemas)
+//
+// What each call takes. These are the same schemas the API validates with, so a
+// value TypeScript accepts here is a value the server accepts too.
+
+/** Arguments for `scrape()`. */
+export interface ScrapeParams {
+    /** The page to read. An http(s) URL — private and loopback hosts are refused. */
+    url: string;
+    /** How to read it. "fetch" is a plain HTTP request; "browser" renders the page in a real
+     *  Chromium; "auto" fetches first and escalates to the browser when the body turns out to be a
+     *  JavaScript shell, billing whichever engine answered. */
+    engine?: "auto" | "fetch" | "browser";
+    /** Whether to try again a different way when the first attempt is blocked. `false` stops after
+     *  one try — the site's refusal is your answer, and it costs nothing. It is how you bound a
+     *  call: with `auto`, trying again is what charges the browser price instead of the fetch one. */
+    escalate?: boolean;
+    /** How many extra tries to give a page the site blocks, each from a different address. 0 (the
+     *  default) takes the site's first no as the answer. A blocked page costs nothing, so a try
+     *  that is blocked again is free — but it takes as long as the first one did, so the call can
+     *  run that many times longer. */
+    retry?: number;
+    /** What to hand back. "screenshot" and "pdf" come back as base64 and need the browser engine;
+     *  asking for both costs no more than one. */
+    formats?: ("markdown" | "html" | "text" | "links" | "screenshot" | "pdf")[];
+    /** What the page should answer with. Set `"json"` when you are reading an API: anything else
+     *  that comes back — a maintenance notice, a "checking your browser" page, a login form — is
+     *  then not your answer. It costs nothing, and we try again from another address instead of
+     *  handing you a page you cannot parse. Without it, whatever the page returns is your answer. */
+    expect?: "json";
+    /** Where the request leaves from. Defaults to the managed residential pool. */
+    proxy?: {
+        /** Which exit to leave through. "residential" is the managed pool, metered by the megabyte;
+         *  "custom" is your own proxy — free on every plan, bytes never billed. */
+        pool?: "residential" | "custom";
+        /** Your own proxy, `http(s)://[user:pass@]host:port`. Required for pool "custom", refused
+         *  for the managed one. */
+        server?: string;
+        /** Where the call should look like it comes from, ISO 3166-1 alpha-2 (`us`, `br`); `us`
+         *  unless you say. On the managed pool it also picks the exit; the browser's clock and
+         *  languages follow it on every pool. */
+        country?: string;
+    };
+    /** How to render it. Only the browser engine reads these — with `auto` they apply if the page
+     *  turns out to need one. */
+    browser?: {
+        /** When the page counts as loaded. "load" (the default) waits for images and stylesheets;
+         *  "domcontentloaded" is the fastest and stops at the HTML; "networkidle" waits until the
+         *  page stops asking for things. Every page gets a short settle after this whichever you
+         *  pick. */
+        waitUntil?: "load" | "domcontentloaded" | "networkidle";
+        /** Wait until this CSS selector is on the page — the dependable way to read something a
+         *  script draws. If it never shows up the call comes back as a timeout at no charge, rather
+         *  than the half-built page. */
+        waitForSelector?: string;
+        /** Wait this many milliseconds after the page settles, for the scripts no selector
+         *  describes. It comes out of `timeoutMs`, never on top of it. */
+        waitMs?: number;
+        /** The window size the page is rendered in, 1280×800 unless you say. Set it when a site
+         *  serves a different layout by width. */
+        viewport?: {
+            width: number;
+            height: number;
+        };
+        /** Screenshot the whole scrollable page instead of just the window. A long page makes a
+         *  large answer — the image comes back as base64 inside the response. */
+        fullPage?: boolean;
+    };
+    /** Extra request headers to send to the page — an authorization token, a cookie, a custom user
+     *  agent. The connection's own headers cannot be set. */
+    headers?: Record<string, string>;
+    /** How long to give the page before giving up, in milliseconds. A page that never arrives is a
+     *  free outcome. */
+    timeoutMs?: number;
+}
+
+/** Arguments for `quote()`. */
+export interface QuoteScrapeParams {
+    /** The page to read. An http(s) URL — private and loopback hosts are refused. */
+    url: string;
+    /** How to read it. "fetch" is a plain HTTP request; "browser" renders the page in a real
+     *  Chromium; "auto" fetches first and escalates to the browser when the body turns out to be a
+     *  JavaScript shell, billing whichever engine answered. */
+    engine?: "auto" | "fetch" | "browser";
+    /** Whether to try again a different way when the first attempt is blocked. `false` stops after
+     *  one try — the site's refusal is your answer, and it costs nothing. It is how you bound a
+     *  call: with `auto`, trying again is what charges the browser price instead of the fetch one. */
+    escalate?: boolean;
+    /** How many extra tries to give a page the site blocks, each from a different address. 0 (the
+     *  default) takes the site's first no as the answer. A blocked page costs nothing, so a try
+     *  that is blocked again is free — but it takes as long as the first one did, so the call can
+     *  run that many times longer. */
+    retry?: number;
+    /** What to hand back. "screenshot" and "pdf" come back as base64 and need the browser engine;
+     *  asking for both costs no more than one. */
+    formats?: ("markdown" | "html" | "text" | "links" | "screenshot" | "pdf")[];
+    /** What the page should answer with. Set `"json"` when you are reading an API: anything else
+     *  that comes back — a maintenance notice, a "checking your browser" page, a login form — is
+     *  then not your answer. It costs nothing, and we try again from another address instead of
+     *  handing you a page you cannot parse. Without it, whatever the page returns is your answer. */
+    expect?: "json";
+    /** Where the request leaves from. Defaults to the managed residential pool. */
+    proxy?: {
+        /** Which exit to leave through. "residential" is the managed pool, metered by the megabyte;
+         *  "custom" is your own proxy — free on every plan, bytes never billed. */
+        pool?: "residential" | "custom";
+        /** Your own proxy, `http(s)://[user:pass@]host:port`. Required for pool "custom", refused
+         *  for the managed one. */
+        server?: string;
+        /** Where the call should look like it comes from, ISO 3166-1 alpha-2 (`us`, `br`); `us`
+         *  unless you say. On the managed pool it also picks the exit; the browser's clock and
+         *  languages follow it on every pool. */
+        country?: string;
+    };
+    /** How to render it. Only the browser engine reads these — with `auto` they apply if the page
+     *  turns out to need one. */
+    browser?: {
+        /** When the page counts as loaded. "load" (the default) waits for images and stylesheets;
+         *  "domcontentloaded" is the fastest and stops at the HTML; "networkidle" waits until the
+         *  page stops asking for things. Every page gets a short settle after this whichever you
+         *  pick. */
+        waitUntil?: "load" | "domcontentloaded" | "networkidle";
+        /** Wait until this CSS selector is on the page — the dependable way to read something a
+         *  script draws. If it never shows up the call comes back as a timeout at no charge, rather
+         *  than the half-built page. */
+        waitForSelector?: string;
+        /** Wait this many milliseconds after the page settles, for the scripts no selector
+         *  describes. It comes out of `timeoutMs`, never on top of it. */
+        waitMs?: number;
+        /** The window size the page is rendered in, 1280×800 unless you say. Set it when a site
+         *  serves a different layout by width. */
+        viewport?: {
+            width: number;
+            height: number;
+        };
+        /** Screenshot the whole scrollable page instead of just the window. A long page makes a
+         *  large answer — the image comes back as base64 inside the response. */
+        fullPage?: boolean;
+    };
+    /** Extra request headers to send to the page — an authorization token, a cookie, a custom user
+     *  agent. The connection's own headers cannot be set. */
+    headers?: Record<string, string>;
+    /** How long to give the page before giving up, in milliseconds. A page that never arrives is a
+     *  free outcome. */
+    timeoutMs?: number;
+}
+
+/** Arguments for `search()`. */
+export interface SearchParams {
+    /** What to search for, in plain words — the same thing you would type. */
+    query: string;
+    /** How many results to hand back at most, 1–20. Billed per 10, so asking for more than 10 costs
+     *  a second row. Fewer can come back than you asked for — an index has what it has, and
+     *  `includeDomains` filters what it returns. */
+    limit?: number;
+    /** What kind of results. "general" is the web; "news" is dated journalism, and the only topic
+     *  that reliably carries `publishedAt`. */
+    topic?: "general" | "news";
+    /** Only pages from the last day, week, month or year. Absent is any time. */
+    timeRange?: "day" | "week" | "month" | "year";
+    /** Only results on these hosts, bare (`linkedin.com`) — subdomains included. Asked of the
+     *  search front AND enforced on the answer, so what comes back is on your list whatever the
+     *  front did with it. */
+    includeDomains?: string[];
+    /** Also write a short paragraph answering the query from the results, in the query's language.
+     *  Costs one extra credit; leave it off when your own model reads the snippets. */
+    answer?: boolean;
+    /** Where the search leaves from. `country` picks the exit AND the market the front answers for
+     *  — `br` gets Brazilian results in Portuguese. */
+    proxy?: {
+        /** Which exit to leave through. "residential" is the managed pool, metered by the megabyte;
+         *  "custom" is your own proxy — free on every plan, bytes never billed. */
+        pool?: "residential" | "custom";
+        /** Your own proxy, `http(s)://[user:pass@]host:port`. Required for pool "custom", refused
+         *  for the managed one. */
+        server?: string;
+        /** Where the call should look like it comes from, ISO 3166-1 alpha-2 (`us`, `br`); `us`
+         *  unless you say. On the managed pool it also picks the exit; the browser's clock and
+         *  languages follow it on every pool. */
+        country?: string;
+    };
+}
+
+/** Arguments for `batches.create()`. */
+export interface CreateBatchParams {
+    /** How to read it. "fetch" is a plain HTTP request; "browser" renders the page in a real
+     *  Chromium; "auto" fetches first and escalates to the browser when the body turns out to be a
+     *  JavaScript shell, billing whichever engine answered. */
+    engine?: "auto" | "fetch" | "browser";
+    /** Whether to try again a different way when the first attempt is blocked. `false` stops after
+     *  one try — the site's refusal is your answer, and it costs nothing. It is how you bound a
+     *  call: with `auto`, trying again is what charges the browser price instead of the fetch one. */
+    escalate?: boolean;
+    /** How many extra tries to give a page the site blocks, each from a different address. 0 (the
+     *  default) takes the site's first no as the answer. A blocked page costs nothing, so a try
+     *  that is blocked again is free — but it takes as long as the first one did, so the call can
+     *  run that many times longer. */
+    retry?: number;
+    /** What to hand back. "screenshot" and "pdf" come back as base64 and need the browser engine;
+     *  asking for both costs no more than one. */
+    formats?: ("markdown" | "html" | "text" | "links" | "screenshot" | "pdf")[];
+    /** What the page should answer with. Set `"json"` when you are reading an API: anything else
+     *  that comes back — a maintenance notice, a "checking your browser" page, a login form — is
+     *  then not your answer. It costs nothing, and we try again from another address instead of
+     *  handing you a page you cannot parse. Without it, whatever the page returns is your answer. */
+    expect?: "json";
+    /** Where the request leaves from. Defaults to the managed residential pool. */
+    proxy?: {
+        /** Which exit to leave through. "residential" is the managed pool, metered by the megabyte;
+         *  "custom" is your own proxy — free on every plan, bytes never billed. */
+        pool?: "residential" | "custom";
+        /** Your own proxy, `http(s)://[user:pass@]host:port`. Required for pool "custom", refused
+         *  for the managed one. */
+        server?: string;
+        /** Where the call should look like it comes from, ISO 3166-1 alpha-2 (`us`, `br`); `us`
+         *  unless you say. On the managed pool it also picks the exit; the browser's clock and
+         *  languages follow it on every pool. */
+        country?: string;
+    };
+    /** How to render it. Only the browser engine reads these — with `auto` they apply if the page
+     *  turns out to need one. */
+    browser?: {
+        /** When the page counts as loaded. "load" (the default) waits for images and stylesheets;
+         *  "domcontentloaded" is the fastest and stops at the HTML; "networkidle" waits until the
+         *  page stops asking for things. Every page gets a short settle after this whichever you
+         *  pick. */
+        waitUntil?: "load" | "domcontentloaded" | "networkidle";
+        /** Wait until this CSS selector is on the page — the dependable way to read something a
+         *  script draws. If it never shows up the call comes back as a timeout at no charge, rather
+         *  than the half-built page. */
+        waitForSelector?: string;
+        /** Wait this many milliseconds after the page settles, for the scripts no selector
+         *  describes. It comes out of `timeoutMs`, never on top of it. */
+        waitMs?: number;
+        /** The window size the page is rendered in, 1280×800 unless you say. Set it when a site
+         *  serves a different layout by width. */
+        viewport?: {
+            width: number;
+            height: number;
+        };
+        /** Screenshot the whole scrollable page instead of just the window. A long page makes a
+         *  large answer — the image comes back as base64 inside the response. */
+        fullPage?: boolean;
+    };
+    /** Extra request headers to send to the page — an authorization token, a cookie, a custom user
+     *  agent. The connection's own headers cannot be set. */
+    headers?: Record<string, string>;
+    /** How long to give the page before giving up, in milliseconds. A page that never arrives is a
+     *  free outcome. */
+    timeoutMs?: number;
+    /** The pages to read, in the order you want them back. How many one batch may carry depends on
+     *  your plan. Duplicates are kept: position, not URL, is what lines results up against what you
+     *  submitted. */
+    urls: string[];
+    /** Call this URL instead of making you poll. The signing secret is returned once, when the
+     *  batch is created. */
+    webhook?: {
+        /** Where to POST when something happens. An https URL you control; private and loopback
+         *  hosts are refused, the same as any other URL we fetch. */
+        url: string;
+        /** What to call about. "batch.completed" fires once, when every URL has a verdict.
+         *  "batch.item.completed" fires per URL — one request from us per item, which is what makes
+         *  a long batch usable before it ends, so ask for it deliberately. */
+        events?: ("batch.completed" | "batch.item.completed")[];
+    };
+}
+
+/** Arguments for `batches.quote()`. */
+export interface QuoteBatchParams {
+    /** How to read it. "fetch" is a plain HTTP request; "browser" renders the page in a real
+     *  Chromium; "auto" fetches first and escalates to the browser when the body turns out to be a
+     *  JavaScript shell, billing whichever engine answered. */
+    engine?: "auto" | "fetch" | "browser";
+    /** Whether to try again a different way when the first attempt is blocked. `false` stops after
+     *  one try — the site's refusal is your answer, and it costs nothing. It is how you bound a
+     *  call: with `auto`, trying again is what charges the browser price instead of the fetch one. */
+    escalate?: boolean;
+    /** How many extra tries to give a page the site blocks, each from a different address. 0 (the
+     *  default) takes the site's first no as the answer. A blocked page costs nothing, so a try
+     *  that is blocked again is free — but it takes as long as the first one did, so the call can
+     *  run that many times longer. */
+    retry?: number;
+    /** What to hand back. "screenshot" and "pdf" come back as base64 and need the browser engine;
+     *  asking for both costs no more than one. */
+    formats?: ("markdown" | "html" | "text" | "links" | "screenshot" | "pdf")[];
+    /** What the page should answer with. Set `"json"` when you are reading an API: anything else
+     *  that comes back — a maintenance notice, a "checking your browser" page, a login form — is
+     *  then not your answer. It costs nothing, and we try again from another address instead of
+     *  handing you a page you cannot parse. Without it, whatever the page returns is your answer. */
+    expect?: "json";
+    /** Where the request leaves from. Defaults to the managed residential pool. */
+    proxy?: {
+        /** Which exit to leave through. "residential" is the managed pool, metered by the megabyte;
+         *  "custom" is your own proxy — free on every plan, bytes never billed. */
+        pool?: "residential" | "custom";
+        /** Your own proxy, `http(s)://[user:pass@]host:port`. Required for pool "custom", refused
+         *  for the managed one. */
+        server?: string;
+        /** Where the call should look like it comes from, ISO 3166-1 alpha-2 (`us`, `br`); `us`
+         *  unless you say. On the managed pool it also picks the exit; the browser's clock and
+         *  languages follow it on every pool. */
+        country?: string;
+    };
+    /** How to render it. Only the browser engine reads these — with `auto` they apply if the page
+     *  turns out to need one. */
+    browser?: {
+        /** When the page counts as loaded. "load" (the default) waits for images and stylesheets;
+         *  "domcontentloaded" is the fastest and stops at the HTML; "networkidle" waits until the
+         *  page stops asking for things. Every page gets a short settle after this whichever you
+         *  pick. */
+        waitUntil?: "load" | "domcontentloaded" | "networkidle";
+        /** Wait until this CSS selector is on the page — the dependable way to read something a
+         *  script draws. If it never shows up the call comes back as a timeout at no charge, rather
+         *  than the half-built page. */
+        waitForSelector?: string;
+        /** Wait this many milliseconds after the page settles, for the scripts no selector
+         *  describes. It comes out of `timeoutMs`, never on top of it. */
+        waitMs?: number;
+        /** The window size the page is rendered in, 1280×800 unless you say. Set it when a site
+         *  serves a different layout by width. */
+        viewport?: {
+            width: number;
+            height: number;
+        };
+        /** Screenshot the whole scrollable page instead of just the window. A long page makes a
+         *  large answer — the image comes back as base64 inside the response. */
+        fullPage?: boolean;
+    };
+    /** Extra request headers to send to the page — an authorization token, a cookie, a custom user
+     *  agent. The connection's own headers cannot be set. */
+    headers?: Record<string, string>;
+    /** How long to give the page before giving up, in milliseconds. A page that never arrives is a
+     *  free outcome. */
+    timeoutMs?: number;
+    /** The pages to read, in the order you want them back. How many one batch may carry depends on
+     *  your plan. Duplicates are kept: position, not URL, is what lines results up against what you
+     *  submitted. */
+    urls: string[];
+    /** Call this URL instead of making you poll. The signing secret is returned once, when the
+     *  batch is created. */
+    webhook?: {
+        /** Where to POST when something happens. An https URL you control; private and loopback
+         *  hosts are refused, the same as any other URL we fetch. */
+        url: string;
+        /** What to call about. "batch.completed" fires once, when every URL has a verdict.
+         *  "batch.item.completed" fires per URL — one request from us per item, which is what makes
+         *  a long batch usable before it ends, so ask for it deliberately. */
+        events?: ("batch.completed" | "batch.item.completed")[];
+    };
+}
+
+/** Arguments for `batches.list()`. */
+export interface ListBatchesParams {
+    /** How many to return, newest first. Up to 100; 20 by default. */
+    limit?: number;
+}
+
+/** Arguments for `batches.get()`. */
+export interface GetBatchParams {
+    /** The batch's id, as create returned it. */
+    id: string;
+    /** Also return the results themselves, in the order you submitted them. Off by default: most
+     *  polls only want to know whether the batch has finished. */
+    items?: boolean;
+    /** Start the results at this position. Up to 200 come back at a time, so read the next page
+     *  with `from` plus however many you just got, and stop when you reach `total`. */
+    from?: number;
+}
+
+/** Arguments for `batches.cancel()`. */
+export interface CancelBatchParams {
+    /** The batch's id, as create returned it. */
+    id: string;
+}
+
+/** Arguments for `sessions.create()`. */
+export interface CreateSessionParams {
+    /** How long to hold the browser, in minutes. Credits for the whole window are reserved when the
+     *  session starts and the unused minutes are handed back when it closes, so asking for longer
+     *  than you need costs nothing extra. Defaults to 10; your plan sets the ceiling. */
+    timeoutMin?: number;
+    /** Where the session leaves from, fixed for its whole life. Defaults to the managed residential
+     *  pool. */
+    proxy?: {
+        /** Which exit to leave through. "residential" is the managed pool, metered by the megabyte;
+         *  "custom" is your own proxy — free on every plan, bytes never billed. */
+        pool?: "residential" | "custom";
+        /** Your own proxy, `http(s)://[user:pass@]host:port`. Required for pool "custom", refused
+         *  for the managed one. */
+        server?: string;
+        /** Where the call should look like it comes from, ISO 3166-1 alpha-2 (`us`, `br`); `us`
+         *  unless you say. On the managed pool it also picks the exit; the browser's clock and
+         *  languages follow it on every pool. */
+        country?: string;
+    };
+}
+
+/** Arguments for `sessions.quote()`. */
+export interface QuoteSessionParams {
+    /** How long to hold the browser, in minutes. Credits for the whole window are reserved when the
+     *  session starts and the unused minutes are handed back when it closes, so asking for longer
+     *  than you need costs nothing extra. Defaults to 10; your plan sets the ceiling. */
+    timeoutMin?: number;
+    /** Where the session leaves from, fixed for its whole life. Defaults to the managed residential
+     *  pool. */
+    proxy?: {
+        /** Which exit to leave through. "residential" is the managed pool, metered by the megabyte;
+         *  "custom" is your own proxy — free on every plan, bytes never billed. */
+        pool?: "residential" | "custom";
+        /** Your own proxy, `http(s)://[user:pass@]host:port`. Required for pool "custom", refused
+         *  for the managed one. */
+        server?: string;
+        /** Where the call should look like it comes from, ISO 3166-1 alpha-2 (`us`, `br`); `us`
+         *  unless you say. On the managed pool it also picks the exit; the browser's clock and
+         *  languages follow it on every pool. */
+        country?: string;
+    };
+}
+
+/** Arguments for `sessions.list()`. */
+export interface ListSessionsParams {
+    /** How many to return, newest first. Up to 100; 20 by default. */
+    limit?: number;
+}
+
+/** Arguments for `sessions.get()`. */
+export interface GetSessionParams {
+    /** The session's id, as create returned it. */
+    id: string;
+}
+
+/** Arguments for `sessions.close()`. */
+export interface CloseSessionParams {
+    /** The session's id, as create returned it. */
+    id: string;
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+// The published surface of `@scrapa/sdk`.
+export { Scrapa } from "./client.ts";
+export type { RequestOptions, RequestSpec, ScrapaOptions } from "./client.ts";
+export { ScrapaError } from "./errors.ts";
+export type { ClientErrorCode, ScrapaErrorInit } from "./errors.ts";
+export { DEFAULT_BASE_URL, SDK_VERSION } from "./generated/operations.ts";
+// Every DTO, error code and header the API speaks.
+export * from "./generated/contract.ts";
+export type * from "./generated/params.ts";