@scrapa/sdk 0.1.0

package/src/generated/operations.ts

@@ -0,0 +1,293 @@
+// GENERATED FILE — do not edit. Run `bun run sdk:gen`.
+// Source: apps/api/src/routes/v1 (the mounted operations)
+//
+// One method per capability, grouped the way the docs group them, returning the
+// DTO the operation declares. `Scrapa` in ../client.ts supplies request().
+
+import type { RequestOptions, RequestSpec } from "../client.ts";
+import type {
+    BatchDto,
+    BatchQuoteDto,
+    CreatedBatchDto,
+    LiveSessionDto,
+    ScrapeQuoteDto,
+    ScrapeResultDto,
+    SearchResultDto,
+    SessionDto,
+    SessionQuoteDto,
+    UsageDto,
+} from "./contract.ts";
+import type {
+    CancelBatchParams,
+    CloseSessionParams,
+    CreateBatchParams,
+    CreateSessionParams,
+    GetBatchParams,
+    GetSessionParams,
+    ListBatchesParams,
+    ListSessionsParams,
+    QuoteBatchParams,
+    QuoteScrapeParams,
+    QuoteSessionParams,
+    ScrapeParams,
+    SearchParams,
+} from "./params.ts";
+
+/** The version this client reports in `x-scrapa-client`. */
+export const SDK_VERSION = "0.1.0";
+
+/** The hosted API. */
+export const DEFAULT_BASE_URL = "https://api.scrapa.app/v1";
+
+export abstract class GeneratedOperations {
+    protected abstract request<T>(
+        spec: RequestSpec,
+        params?: object,
+        opts?: RequestOptions,
+    ): Promise<T>;
+
+    /**
+     * Scrape a page
+     *
+     * Read one web page and hand it back as markdown, HTML, plain text, its links, a screenshot or
+     * a PDF. `engine: "auto"` (the default) makes a plain HTTP request first and re-reads the page
+     * in a real Chromium when the body turns out to be a JavaScript shell, so you pay for a
+     * browser only when the page needed one. Every request leaves through a residential proxy, or
+     * through your own with `proxy: { pool: "custom", server }`. The answer says which engine
+     * replied, where the page finally was and what it cost.
+     *
+     * Credits: 1 credit with the fetch engine, 5 with the browser (a screenshot or a PDF is included, never
+     * a surcharge), plus managed-proxy bandwidth past the first megabyte. A page the site blocked,
+     * a URL our policy refused and anything we broke all cost nothing.
+     *
+     * `POST /v1/scrape`
+     */
+    scrape(params: ScrapeParams, opts?: RequestOptions): Promise<ScrapeResultDto> {
+        return this.request({ method: "POST", path: "/scrape", idempotent: true }, params, opts);
+    }
+
+    /**
+     * Price a scrape
+     *
+     * What the same request would cost, without making it. Free, and refused by the same guards a
+     * real call meets — so a quote is never a price for a call that would be denied. `maxCost` is
+     * the ceiling: for `auto` it is the browser's price, which is only charged if the page turns
+     * out to need one.
+     *
+     * Credits: 0 credits — pricing a call is free.
+     *
+     * `POST /v1/scrape/quote`
+     */
+    quote(params: QuoteScrapeParams, opts?: RequestOptions): Promise<ScrapeQuoteDto> {
+        return this.request(
+            { method: "POST", path: "/scrape/quote", idempotent: true },
+            params,
+            opts,
+        );
+    }
+
+    /**
+     * Search the web
+     *
+     * Ask the web a question and get back ranked results — title, URL and the snippet the index
+     * holds — read live off a real search front through a residential exit, never a reseller's
+     * cache. `country` picks both the exit and the market, so `br` returns what somebody in Brazil
+     * would see. Narrow to your own list of hosts with `includeDomains`, ask for `topic: "news"`
+     * when you want dated journalism, and add `answer: true` when you want a paragraph written
+     * over the results instead of writing it yourself. To read a result, pass its URL to `scrape`.
+     *
+     * Credits: 4 credits per 10 results, so a `limit` above 10 costs two rows, plus 1 for `answer: true`. A
+     * search every front refused, and anything we broke, cost nothing; a search that ran and found
+     * nothing is charged, because the index answered. A repeat of the same search within a few
+     * minutes is free and says so with `cached: true`.
+     *
+     * `POST /v1/search`
+     */
+    search(params: SearchParams, opts?: RequestOptions): Promise<SearchResultDto> {
+        return this.request({ method: "POST", path: "/search", idempotent: true }, params, opts);
+    }
+
+    readonly batches = {
+        /**
+         * Start a batch
+         *
+         * Hand us a list of URLs and stop holding a connection open. Every one is read with the
+         * options you pass here — the same engines, the same exit and the same meter a single
+         * `scrape` uses — and a page the site blocked costs nothing here too. Nothing is charged
+         * when you submit: a batch spends as it goes, so use `quote` for the ceiling. Poll `get`
+         * for progress, or pass a `webhook` and we will call you instead. Results are readable for
+         * 24 hours.
+         *
+         * Credits: Creating a batch is free, and nothing is held: each URL then costs exactly what the same
+         * call would have cost on its own, and the pages the web refused cost nothing here too.
+         * What the batch has spent so far is on the batch itself, and it grows while it runs.
+         *
+         * `POST /v1/batches`
+         */
+        create: (params: CreateBatchParams, opts?: RequestOptions): Promise<CreatedBatchDto> =>
+            this.request({ method: "POST", path: "/batches", idempotent: false }, params, opts),
+        /**
+         * Price a batch
+         *
+         * What that submission would cost at most, without submitting it. `maxCost` prices every
+         * URL at the ceiling one page could reach, so the real bill comes in lower by whatever the
+         * web refuses for free and by every page that never needed a browser. Bandwidth is on top
+         * and cannot be quoted — it depends on what the pages weigh.
+         *
+         * Credits: 0 credits — pricing a batch is free.
+         *
+         * `POST /v1/batches/quote`
+         */
+        quote: (params: QuoteBatchParams, opts?: RequestOptions): Promise<BatchQuoteDto> =>
+            this.request(
+                { method: "POST", path: "/batches/quote", idempotent: true },
+                params,
+                opts,
+            ),
+        /**
+         * List your batches
+         *
+         * Your most recent batches, newest first — what each one is doing, how far it has got and
+         * what it has cost. Results are not included; ask `get` for one batch's pages.
+         *
+         * Credits: 0 credits — listing batches is free.
+         *
+         * `GET /v1/batches`
+         */
+        list: (params?: ListBatchesParams, opts?: RequestOptions): Promise<BatchDto[]> =>
+            this.request({ method: "GET", path: "/batches", idempotent: true }, params, opts),
+        /**
+         * Read one batch
+         *
+         * Where a batch got to: whether it is still running, how many of its URLs now have a
+         * verdict, how many of those the web or our policy refused, how many were never attempted,
+         * and what it has spent so far. Ask for `items` to get the results themselves — the pages
+         * and the refusals, in the order you submitted them, each one the same answer a single
+         * `scrape` would have given — up to 200 at a time, from wherever `from` says. A batch
+         * whose results have expired still answers with everything else, because somebody who paid
+         * for those pages must never be told the batch does not exist.
+         *
+         * Credits: 0 credits — reading a batch is free.
+         *
+         * `GET /v1/batches/{id}`
+         */
+        get: (params: GetBatchParams, opts?: RequestOptions): Promise<BatchDto> =>
+            this.request({ method: "GET", path: "/batches/{id}", idempotent: true }, params, opts),
+        /**
+         * Cancel a batch
+         *
+         * Stop a batch. A URL already being read finishes and is charged — it is a page we are
+         * already paying for — and every URL not yet started becomes `skipped`, which costs
+         * nothing and is not a verdict about the URL: submit those positions again whenever you
+         * like. Safe to repeat; a batch that has already ended answers with how it ended.
+         *
+         * Credits: 0 credits — cancelling is free, and it stops the spending.
+         *
+         * `DELETE /v1/batches/{id}`
+         */
+        cancel: (params: CancelBatchParams, opts?: RequestOptions): Promise<BatchDto> =>
+            this.request(
+                { method: "DELETE", path: "/batches/{id}", idempotent: true },
+                params,
+                opts,
+            ),
+    };
+
+    readonly sessions = {
+        /**
+         * Start a browser session
+         *
+         * Hold a real Chromium for as long as you asked for and answer with a CDP URL your own
+         * tools connect to: `chromium.connectOverCDP(connectUrl)` in Playwright,
+         * `puppeteer.connect({ browserWSEndpoint: connectUrl })` in Puppeteer. The browser is
+         * yours alone for the whole window, every byte it pulls leaves through the exit you
+         * picked, and the socket survives our deploys. The URL carries the session's token and is
+         * shown once — it cannot be rebuilt from the id.
+         *
+         * Credits: 2 credits per minute, reserved for the whole window when the session starts and settled
+         * by the minutes actually used when it closes — so closing early gives the rest back, and
+         * a browser that never came up costs nothing at all. Managed-proxy bandwidth past the
+         * first megabyte is added at close; your own proxy is never metered.
+         *
+         * `POST /v1/sessions`
+         */
+        create: (params?: CreateSessionParams, opts?: RequestOptions): Promise<LiveSessionDto> =>
+            this.request({ method: "POST", path: "/sessions", idempotent: false }, params, opts),
+        /**
+         * Price a session
+         *
+         * What holding a browser for that long would cost, without holding one. `maxCost` is the
+         * whole window at the per-minute rate — a ceiling, not a bill, because the minutes you do
+         * not use come back when the session closes.
+         *
+         * Credits: 0 credits — pricing a session is free.
+         *
+         * `POST /v1/sessions/quote`
+         */
+        quote: (params?: QuoteSessionParams, opts?: RequestOptions): Promise<SessionQuoteDto> =>
+            this.request(
+                { method: "POST", path: "/sessions/quote", idempotent: true },
+                params,
+                opts,
+            ),
+        /**
+         * List your sessions
+         *
+         * Your most recent sessions, newest first — the live ones and the ones that have ended,
+         * with what each of them cost.
+         *
+         * Credits: 0 credits — listing sessions is free.
+         *
+         * `GET /v1/sessions`
+         */
+        list: (params?: ListSessionsParams, opts?: RequestOptions): Promise<SessionDto[]> =>
+            this.request({ method: "GET", path: "/sessions", idempotent: true }, params, opts),
+        /**
+         * Read one session
+         *
+         * Where a session got to: whether it is still live, when it expires, what it has pulled
+         * and — once it has ended — what it finally cost. The connect URL is not repeated here; it
+         * is shown once, when the session starts.
+         *
+         * Credits: 0 credits — reading a session is free.
+         *
+         * `GET /v1/sessions/{id}`
+         */
+        get: (params: GetSessionParams, opts?: RequestOptions): Promise<SessionDto> =>
+            this.request({ method: "GET", path: "/sessions/{id}", idempotent: true }, params, opts),
+        /**
+         * Close a session
+         *
+         * Stop the browser and settle the bill: the minutes you held it are kept and the rest of
+         * the reservation goes back. Safe to repeat — a session that has already ended answers
+         * with how it ended.
+         *
+         * Credits: Closing is free. It is where the session's own bill lands: the unused minutes are
+         * refunded and the managed pool's bandwidth is charged.
+         *
+         * `DELETE /v1/sessions/{id}`
+         */
+        close: (params: CloseSessionParams, opts?: RequestOptions): Promise<SessionDto> =>
+            this.request(
+                { method: "DELETE", path: "/sessions/{id}", idempotent: true },
+                params,
+                opts,
+            ),
+    };
+
+    readonly usage = {
+        /**
+         * Usage this month
+         *
+         * Credits spent this billing month against the plan's grant, the purchased balance on top
+         * of it, managed-proxy megabytes against the plan's ceiling, when the month rolls over,
+         * and the same split per API key. Free, and worth reading before a bulk run.
+         *
+         * Credits: 0 credits.
+         *
+         * `GET /v1/usage`
+         */
+        get: (opts?: RequestOptions): Promise<UsageDto> =>
+            this.request({ method: "GET", path: "/usage", idempotent: true }, undefined, opts),
+    };
+}