@scrapa/sdk 0.1.0

package/src/generated/contract.ts

@@ -0,0 +1,564 @@
+// GENERATED FILE — do not edit. Run `bun run sdk:gen`.
+// Source: packages/shared/src/http/index.ts, packages/shared/src/locale/index.ts, packages/shared/src/enums/index.ts, packages/shared/src/billing/catalog.ts, packages/shared/src/dto/account.ts, packages/shared/src/dto/scrape.ts, packages/shared/src/dto/batch.ts, packages/shared/src/dto/search.ts, packages/shared/src/dto/sessions.ts, packages/shared/src/dto/usage.ts
+//
+// The shapes the API speaks, lifted from the server's own contract.
+
+// ── from packages/shared/src/http/index.ts ───────────────────────────
+
+/**
+ * The closed set of error codes. A runtime list, not a bare union, so the SDK can narrow
+ * untrusted JSON into it and every surface can enumerate it (the docs errors table, the
+ * locale catalogs, exhaustiveness checks).
+ *
+ * THE WHOSE-FAULT VOCABULARY (DESIGN.md) is the organising principle: a caller's next move
+ * depends entirely on who said no, so the code says. `UPSTREAM_BLOCKED` / `NAV_TIMEOUT` are
+ * "the site said no" (retry differently — another engine, pool or country); `SSRF_DENIED` /
+ * `AUP_DENIED` are "our policy said no" (retrying cannot help, change the URL); a 5xx is
+ * "we broke it" (retry as-is, already refunded).
+ */
+export const ERROR_CODES = [
+    "VALIDATION_ERROR", // 400 — zod issues; details carry {path, code}[] only, never the rejected values
+    "INVALID_URL", // 400 — not an http(s) URL we can fetch; details {input, hint}
+    "SSRF_DENIED", // 400 — private/loopback/link-local/dotless host, the box itself, or a redirect there
+    "UNAUTHORIZED", // 401 — no credential presented
+    "INVALID_TOKEN", // 401 — a credential was presented but is unknown, revoked or the wrong kind
+    // 402 is PLAN_GATE alone. There is deliberately no PAYMENT_REQUIRED: every quantity
+    // scrapa sells — monthly credits, managed-proxy megabytes, concurrency, sessions —
+    // recurs, so WAITING always clears it and the honest answer is a 429 that says when.
+    // 402 is reserved for the one thing waiting cannot fix: a capability the plan does not
+    // include at all. A code with no caller is a promise in the docs nothing implements.
+    "PLAN_GATE", // 402 — a capability this plan does not include; details {gate, upgradeTo}
+    "FORBIDDEN", // 403 — suspended account / staff-only
+    "AUP_DENIED", // 403 — the target is on the acceptable-use denylist; details {category}
+    "NOT_FOUND", // 404 — generic, including "exists but not yours" (no existence leaks)
+    "SESSION_NOT_FOUND", // 404 — the browser session is unknown, closed or expired
+    "CONFLICT", // 409 — e.g. the api-key name cap race
+    "PAYLOAD_TOO_LARGE", // 413 — the request body is over the surface's limit
+    // ── 422: the request was fine, the WEB did not cooperate. Deliberately 4xx, not 5xx:
+    //    "5xx is reserved for what we broke" (AGENTS.md), and these cost the caller nothing.
+    //    422 also tells an HTTP client the truth — replaying the identical request gets the
+    //    identical refusal, so the fix is a different engine/pool/country, not a retry.
+    "UPSTREAM_BLOCKED", // 422 — an anti-bot wall, a captcha, a hard 403 from the target
+    "NAV_TIMEOUT", // 422 — the page never reached a usable state inside the budget
+    "RATE_LIMIT_EXCEEDED", // 429 — the per-minute burst bucket; Retry-After + details {limit}
+    "QUOTA_EXCEEDED", // 429 — a durable bound that WAITING clears; details {scope, limit, resetAt}
+    "INTERNAL_ERROR", // 500 — we broke it; the body is always generic, the cause stays server-side
+    "SERVICE_UNAVAILABLE", // 503 — a dependency (Postgres, Redis, the driver) is down; the meter fails closed here
+    "BILLING_UNAVAILABLE", // 503 — Stripe is not configured on this deployment: the catalog shows but cannot sell
+] as const;
+
+export type ErrorCode = (typeof ERROR_CODES)[number];
+
+/** The status each code answers with. The server's error factory, the SDK's fallback and
+ *  the docs' errors table all read this one map — three copies could drift, one cannot. */
+export const ERROR_STATUS = {
+    VALIDATION_ERROR: 400,
+    INVALID_URL: 400,
+    SSRF_DENIED: 400,
+    UNAUTHORIZED: 401,
+    INVALID_TOKEN: 401,
+    PLAN_GATE: 402,
+    FORBIDDEN: 403,
+    AUP_DENIED: 403,
+    NOT_FOUND: 404,
+    SESSION_NOT_FOUND: 404,
+    CONFLICT: 409,
+    PAYLOAD_TOO_LARGE: 413,
+    UPSTREAM_BLOCKED: 422,
+    NAV_TIMEOUT: 422,
+    RATE_LIMIT_EXCEEDED: 429,
+    QUOTA_EXCEEDED: 429,
+    INTERNAL_ERROR: 500,
+    SERVICE_UNAVAILABLE: 503,
+    BILLING_UNAVAILABLE: 503,
+} as const satisfies Record<ErrorCode, number>;
+
+/**
+ * The three no-charge outcomes, as DESIGN.md names them. Every code that costs the caller
+ * nothing maps to exactly one — this is the map the console reads to pick the hue and the
+ * word, and the SDK reads to tell a caller what to do next. A code absent from here was
+ * the caller's own mistake (a bad body, a missing key) and gets no colour.
+ *
+ *   blocked → the site said no    → try another engine, pool or country
+ *   denied  → our policy said no  → change the URL; retrying cannot help
+ *   broken  → we broke it         → retry as-is; it was already refunded
+ */
+export const OUTCOME_OF: Partial<Record<ErrorCode, "blocked" | "denied" | "broken">> = {
+    UPSTREAM_BLOCKED: "blocked",
+    NAV_TIMEOUT: "blocked",
+    SSRF_DENIED: "denied",
+    AUP_DENIED: "denied",
+    INTERNAL_ERROR: "broken",
+    SERVICE_UNAVAILABLE: "broken",
+    // Stripe unconfigured is entirely our side of the line: the catalog shows and cannot
+    // sell. The customer did nothing wrong, so it is the same hue and costs the same zero.
+    BILLING_UNAVAILABLE: "broken",
+};
+
+/**
+ * Response headers a client may read. One spelling for the server (CORS `exposeHeaders`
+ * is `Object.values(HEADERS)`), the SDK and the docs.
+ *
+ * `cost` and `creditsRemaining` ride on EVERY metered response including the free ones —
+ * a blocked page reports `x-request-cost: 0`, which is how the promise "blocked pages cost
+ * nothing" becomes something a caller can verify instead of something we assert.
+ */
+export const HEADERS = {
+    /** Credits this call actually cost. `0` on every no-charge outcome. */
+    cost: "x-request-cost",
+    /** Credits left after it — plan quota remaining plus the purchased balance. */
+    creditsRemaining: "x-credits-remaining",
+    requestId: "x-request-id",
+    /** Which engine answered (`fetch` | `browser`) — set from Phase 3. */
+    engine: "x-scrapa-engine",
+    /** What the SDK identifies itself as. */
+    client: "x-scrapa-client",
+    retryAfter: "retry-after",
+} as const;
+
+export interface PaginationMeta {
+    total: number;
+    limit: number;
+    offset: number;
+    hasMore: boolean;
+}
+
+/** Rides on every metered 2xx, mirroring the `x-request-cost` / `x-credits-remaining`
+ *  headers for clients that would rather read the body. `dryRun` marks a priced-but-not-run
+ *  call (`dryRun: true` on the request), which always costs 0. */
+export interface UsageMeta {
+    /** Credits charged by THIS call. 0 on a no-charge outcome and on a dry run. */
+    cost: number;
+    creditsRemaining: number;
+    requestId: string;
+    dryRun?: true;
+}
+
+/** Success envelope — every 2xx JSON body is exactly this shape. */
+export interface ApiSuccess<T> {
+    data: T;
+    meta?: PaginationMeta | UsageMeta;
+}
+
+/** Error envelope — byte-compatible with the server's `AppError.toJSON()`. */
+export interface ApiError {
+    error: {
+        code: ErrorCode;
+        /** English fallback, for logs, curl and agents. Not shown when `messageKey` resolves. */
+        message: string;
+        /** Stable key for clients that localize or brand their copy of this failure. */
+        messageKey?: string;
+        /** Interpolation values for `messageKey`. */
+        params?: Record<string, string | number>;
+        details?: unknown;
+    };
+}
+// ── from packages/shared/src/enums/index.ts ──────────────────────────
+
+/** Which exit a call leaves through. `residential` is the managed pool (metered bytes);
+ *  `custom` is the caller's own proxy URL — free on every plan, bytes never billed.
+ *  `datacenter` is a ROADMAP pool and deliberately absent: an enum value with nothing
+ *  behind it is a documented promise we cannot keep. */
+export const PROXY_POOLS = ["residential", "custom"] as const;
+
+export type ProxyPool = (typeof PROXY_POOLS)[number];
+
+/** How a page is fetched. `auto` tries a plain fetch and escalates to a real browser when
+ *  the body looks like a JavaScript shell, billing whichever engine answered. */
+export const ENGINES = ["auto", "fetch", "browser"] as const;
+
+export type Engine = (typeof ENGINES)[number];
+
+/** The engine that actually answered — never `auto`, which is a strategy, not an engine. */
+export type ResolvedEngine = Exclude<Engine, "auto">;
+
+/** What a scrape can hand back. `markdown` is the default because it is what an LLM, a
+ *  notebook and a human all read; `html` is the page as fetched; `text` is prose with the
+ *  markup gone; `links` every absolute anchor in document order. */
+export const SCRAPE_FORMATS = ["markdown", "html", "text", "links", "screenshot", "pdf"] as const;
+
+export type ScrapeFormat = (typeof SCRAPE_FORMATS)[number];
+
+/** A session's life. `starting` is the driver bringing Chromium up; `live` is the only
+ *  status whose `connectUrl` accepts a CDP client. The three end states answer one
+ *  question — who ended it — because that is what decides whether the reservation is
+ *  settled by the minutes used (`closed`, `expired`) or handed back whole (`failed`, which
+ *  is ours). A session that never reached `live` never charged a minute. */
+export const SESSION_STATUSES = ["starting", "live", "closed", "expired", "failed"] as const;
+
+export type SessionStatus = (typeof SESSION_STATUSES)[number];
+
+/** What a search is looking for. `general` is the web; `news` is dated journalism — a
+ *  different door at every engine, and the only one that reliably carries a date. */
+export const SEARCH_TOPICS = ["general", "news"] as const;
+
+export type SearchTopic = (typeof SEARCH_TOPICS)[number];
+
+/** Which front answered a search. Not a caller's choice — the ladder picks, and says which
+ *  one it was, because a result set's flavour follows its index. */
+export const SEARCH_ENGINES = ["bing", "brave"] as const;
+
+export type SearchEngine = (typeof SEARCH_ENGINES)[number];
+
+/** A batch's life. `queued` is accepted but not yet picked up; `running` has at least one
+ *  item in flight. The three end states answer the same question the session statuses do —
+ *  who ended it: `completed` ran every item to a verdict (some of which may be failures,
+ *  which is not the batch failing), `canceled` is the caller's own call, and `failed` is
+ *  ours and only ours. A batch does NOT fail because pages did. */
+export const BATCH_STATUSES = ["queued", "running", "completed", "canceled", "failed"] as const;
+
+export type BatchStatus = (typeof BATCH_STATUSES)[number];
+
+/** One URL's life inside a batch. `done` means a page came back and was charged for;
+ *  `failed` means it did not, and carries the same error a synchronous call would have
+ *  thrown — including the free outcomes, which cost nothing here exactly as they do there.
+ *  `skipped` is the item nobody ran: the batch was canceled, or the account's credits ran
+ *  out partway through, and neither is a verdict about the URL. */
+export const BATCH_ITEM_STATUSES = ["queued", "running", "done", "failed", "skipped"] as const;
+
+export type BatchItemStatus = (typeof BATCH_ITEM_STATUSES)[number];
+
+/** What we will call a webhook about. Two, because they answer two different questions:
+ *  `batch.completed` is "stop polling", and `batch.item.completed` is "you can start
+ *  working on this one now" — the reason a 5,000-URL batch is usable before it ends.
+ *
+ *  Per-item delivery is OPT-IN and completion is the default, because the per-item choice
+ *  is a caller asking for one HTTP request per URL from us and it should be a decision
+ *  rather than a surprise. */
+export const WEBHOOK_EVENTS = ["batch.completed", "batch.item.completed"] as const;
+
+export type WebhookEvent = (typeof WEBHOOK_EVENTS)[number];
+
+/** How a delivery ended. `delivered` is any 2xx. `failed` is every attempt spent — a
+ *  non-2xx, a timeout, a refused connection — and it is terminal: we do not hold a
+ *  customer's results hostage to their endpoint, the batch is readable over the API
+ *  regardless. */
+export const WEBHOOK_DELIVERY_STATUSES = ["pending", "delivered", "failed"] as const;
+
+export type WebhookDeliveryStatus = (typeof WEBHOOK_DELIVERY_STATUSES)[number];
+// ── from packages/shared/src/billing/catalog.ts ──────────────────────
+
+export type PlanId = "free" | "starter" | "pro" | "scale" | "internal";
+// ── from packages/shared/src/dto/scrape.ts ───────────────────────────
+
+/** What the page said about itself. Every field is null when the page did not say — never
+ *  guessed from the body, so a caller can trust a non-null value. */
+export interface ScrapeMetadataDto {
+    title: string | null;
+    description: string | null;
+    /** The document's `lang`, as written (`en`, `pt-BR`). */
+    language: string | null;
+    canonicalUrl: string | null;
+    siteName: string | null;
+    ogTitle: string | null;
+    ogDescription: string | null;
+    ogImage: string | null;
+    /** The response's `content-type`, media type only. */
+    contentType: string | null;
+    /** True when the fetched body looks like a JavaScript shell — a page whose content only
+     *  exists after scripts run. `auto` escalates to the browser engine on it; `fetch` reports
+     *  it so a caller can retry with `engine: "browser"` instead of trusting an empty page.
+     *  Always false from the browser engine, which ran the scripts. */
+    needsJs: boolean;
+}
+
+/** `POST /v1/scrape`'s answer. Only the requested formats are present; everything else is
+ *  always there. Artifacts (`screenshot`, `pdf`) are base64 in v1. */
+export interface ScrapeResultDto {
+    /** The URL as requested. */
+    url: string;
+    /** Where the page actually was, after redirects. */
+    finalUrl: string;
+    /** The target's HTTP status. A 404 page that answered is still a page that answered. */
+    status: number;
+    engine: ResolvedEngine;
+    pool: ProxyPool;
+    /** True when the first attempt did not answer and a second one did — an `auto` call
+     *  whose page turned out to need a browser, or a blocked page another renderer got
+     *  past. It is why the call cost what it cost; `escalate: false` is how you stop it.
+     *  Absent means the first attempt answered. */
+    escalated?: boolean;
+    /** How many times the page was asked for, when it took more than once — you asked for
+     *  `retry`, the site blocked us, and a later address got through. It is why the call took
+     *  as long as it did. Absent means once. */
+    attempts?: number;
+    /** What the managed pool carried for this call, and meters past the free megabyte.
+     *  `fetch`: the body, decompressed — what the caller received. `browser`: every response
+     *  the page pulled, as carried on the wire. An `auto` call that escalated counts both. */
+    bytes: number;
+    markdown?: string;
+    html?: string;
+    text?: string;
+    links?: string[];
+    screenshot?: string;
+    pdf?: string;
+    metadata: ScrapeMetadataDto;
+}
+
+/** `dryRun: true`'s answer — the price of the call, without making it. */
+export interface ScrapeQuoteDto {
+    engine: ResolvedEngine;
+    pool: ProxyPool;
+    formats: ScrapeFormat[];
+    /** Credits the engine charges when the page answers. For `auto`, the fetch row. */
+    cost: number;
+    /** The most the engine can charge before bandwidth: `cost` when the engine is fixed; the
+     *  browser row for `auto`, which escalates when the page needs a real browser. */
+    maxCost: number;
+    /** Managed-pool megabytes included per request before `perMb` applies. 0 on BYO. */
+    freeMb: number;
+    /** Credits per additional megabyte through the managed pool. 0 on BYO. */
+    perMb: number;
+}
+// ── from packages/shared/src/dto/batch.ts ────────────────────────────
+
+/**
+ * A batch: one set of URLs, read with one set of options, on our schedule rather than the
+ * caller's connection.
+ *
+ * The rule that shapes everything here is that **a batch is N scrapes and nothing more**.
+ * Each item is charged exactly what the same call would have cost synchronously, on the
+ * same terms — a blocked page is free inside a batch too — so there is no batch price, no
+ * discount and no surcharge to reason about. What the caller buys is not having to hold a
+ * connection open for an hour.
+ *
+ * `cost` and `bytes` therefore GROW while the batch runs. They are what it has spent so
+ * far, not an estimate and not a reservation: nothing is held up front, which is why a
+ * batch can outlive a month's credits and report honestly that it did (the remaining items
+ * go `skipped`, and skipped is not a verdict about the URL).
+ */
+export interface BatchDto {
+    id: string;
+    status: BatchStatus;
+    /** URLs accepted. Fixed at create — a batch never grows. */
+    total: number;
+    /** Items that have reached an end state, `skipped` included. `completed === total` is
+     *  what makes the batch itself complete. */
+    completed: number;
+    /** Of those, how many the web or our policy refused. A `failed` count equal to `total`
+     *  is still a `completed` batch: every URL got a verdict, and the verdicts were
+     *  refusals. Free ones — a blocked page costs nothing here too. */
+    failed: number;
+    /** Of those, how many were never attempted — the batch was cancelled, or the month's
+     *  credits ran out under it. Counted APART from `failed` because it is not a verdict
+     *  about the URL: submit these positions again and they will be read. */
+    skipped: number;
+    /** Which exit every item leaves through, fixed at create like a session's. */
+    pool: ProxyPool;
+    /** Credits spent SO FAR. Grows while the batch runs. */
+    cost: number;
+    /** Managed-pool bytes so far, on the same terms as a synchronous scrape's. */
+    bytes: number;
+    createdAt: string;
+    /** When the first item was picked up. */
+    startedAt?: string;
+    endedAt?: string;
+    /** When the RESULTS stop being readable. The batch's own row OUTLIVES them, which is
+     *  why there is no expiry error code: a batch past this date still answers with its
+     *  status, its counts and what it cost, just with no `items`. Somebody who paid for
+     *  five thousand pages must never be told "not found". */
+    expiresAt: string;
+    /** The items, when they were asked for. Absent — not empty — when they were not:
+     *  an empty array would read like a batch with no URLs. */
+    items?: BatchItemDto[];
+    /** Where we will call back, when one was configured. The secret is never echoed. */
+    webhook?: BatchWebhookDto;
+}
+
+/** One URL's outcome. Exactly the answer the same URL would have given synchronously,
+ *  including which of the two ways it could refuse. */
+export interface BatchItemDto {
+    /** Position in the submitted list, 0-based. The list's ORDER is preserved — it is how
+     *  a caller lines results back up against whatever they submitted. */
+    position: number;
+    url: string;
+    status: BatchItemStatus;
+    /** The page, when one answered. The same DTO `scrape()` returns. */
+    result?: ScrapeResultDto;
+    /** Why not, when it did not — the same code and sentence a synchronous call would have
+     *  thrown, so one error handler serves both doors. */
+    error?: { code: ErrorCode; message: string };
+    /** What this item cost. 0 on every free outcome, exactly as synchronously. */
+    cost: number;
+}
+
+/** The callback a batch was created with. */
+export interface BatchWebhookDto {
+    url: string;
+    events: WebhookEvent[];
+    /** The most recent attempt's verdict, so a caller debugging a silent endpoint can see
+     *  whether we ever reached it without opening a support ticket. */
+    status: WebhookDeliveryStatus;
+    /** The last attempt's HTTP status, when we got one at all. Absent means we never
+     *  reached the endpoint — DNS, TLS, a refused connection or a timeout. */
+    lastStatus?: number;
+    lastAttemptAt?: string;
+    /** Attempts spent on the MOST RECENT delivery, which is what `lastStatus` describes too.
+     *  A delivery is retried on a schedule; this is where that one got to. With per-item
+     *  events there are many deliveries against one batch, and this is not their sum. */
+    attempts: number;
+}
+
+/** `POST /v1/batches/quote` — the ceiling, not a bill. Every item is priced as the same
+ *  synchronous call would be, so this is `total` × that, and the real cost is lower by
+ *  whatever the web refuses for free. */
+export interface BatchQuoteDto {
+    total: number;
+    pool: ProxyPool;
+    /** What one item would cost at most — the browser row for `auto`, since that is the
+     *  ceiling a page can escalate to. */
+    perItemMaxCost: number;
+    /** `total` × `perItemMaxCost`. Bandwidth is on top and cannot be quoted: it depends on
+     *  what the pages weigh. */
+    maxCost: number;
+}
+
+/**
+ * What creating a batch answers with: the batch, plus the one thing that is never said
+ * again.
+ *
+ * We mint the signing secret rather than taking one, so a customer never puts a credential
+ * on the wire to us, and we keep it because signing a delivery needs the key itself. What
+ * they get is this single sight of it — the same bargain `sc_` keys make. Losing it means
+ * creating another batch, not reading it back.
+ */
+export interface CreatedBatchDto extends BatchDto {
+    /** `whsec_…`, present exactly when a webhook was configured. Verify a delivery with it:
+     *  HMAC-SHA256 over `<timestamp>.<raw body>`, compared against the `v1=` value in the
+     *  `scrapa-signature` header. */
+    webhookSecret?: string;
+}
+// ── from packages/shared/src/dto/search.ts ───────────────────────────
+
+/** One hit, as the index ranked it. The array's ORDER is the ranking — there is no score,
+ *  because no engine we read publishes one and a rank-derived float would be a made-up
+ *  number in a public contract. */
+export interface SearchHitDto {
+    /** 1-based rank within this answer. */
+    position: number;
+    url: string;
+    title: string;
+    /** The engine's own summary of the page, a couple of lines. Never the page itself —
+     *  read that with `POST /v1/scrape` on the URL. */
+    snippet: string;
+    /** When the engine dated it, ISO 8601. Null whenever it did not, which on the general
+     *  topic is most of the time — never guessed from the snippet. */
+    publishedAt: string | null;
+}
+
+/** `POST /v1/search`'s answer. */
+export interface SearchResultDto {
+    /** The query as asked, before any engine operator was added to it. */
+    query: string;
+    topic: SearchTopic;
+    /** Which front answered. */
+    engine: SearchEngine;
+    pool: ProxyPool;
+    /** What the managed pool carried, decompressed. 0 when the cheap rung answered, which
+     *  for the common query it does — a SERP is not billed bandwidth. */
+    bytes: number;
+    /** True when this answer came from the short-lived cache of an identical request, in
+     *  which case it cost nothing. */
+    cached: boolean;
+    /** The one-paragraph answer, when `answer: true` was asked for. Written by a model over
+     *  the hits below, in the query's language, and never a substitute for reading them. */
+    answer: string | null;
+    results: SearchHitDto[];
+}
+// ── from packages/shared/src/dto/sessions.ts ─────────────────────────
+
+/**
+ * A managed browser session: one Chromium PROCESS, held for the caller, driven over raw CDP
+ * by their own Playwright or Puppeteer. We hand back a URL, not a client — everything a
+ * customer already knows how to do with `connectOverCDP` keeps working, which is the whole
+ * point of the product.
+ */
+export interface SessionDto {
+    id: string;
+    status: SessionStatus;
+    /** Where a CDP client connects: `wss://api.scrapa.app/v1/sessions/<id>/cdp?token=…`.
+     *  Present only while the session can still be connected to — an ended session's URL
+     *  would be a link that looks alive and is not. The token is in the URL because that is
+     *  the only place a WebSocket client can put a credential. */
+    connectUrl?: string;
+    /** Which exit every byte of this session leaves through, fixed at create. A tenant
+     *  cannot change it later: the one CDP command we rewrite is the one that would try. */
+    pool: ProxyPool;
+    /** Minutes reserved at create, and the wall the reaper enforces. */
+    timeoutMin: number;
+    /** When the reaper will kill it, if nothing else does. */
+    expiresAt: string;
+    /** Credits held at create: `timeoutMin` × the session-minute row. Not yet spent. */
+    creditsReserved: number;
+    /** What the session actually cost, once it ended. Absent while it is still running —
+     *  a running session has no final price, and a zero would read like a free one. */
+    creditsSettled?: number;
+    /** Managed-pool bytes this session pulled. Metered at settle, like a scrape's. */
+    bytes: number;
+    createdAt: string;
+    /** When Chromium came up and the URL started accepting clients. */
+    startedAt?: string;
+    endedAt?: string;
+}
+
+/**
+ * What starting a session answers with: the same session, except that its URL is not
+ * optional. A create only returns once Chromium is up, so the one call whose whole point is
+ * the connect URL hands back a type that has one — `chromium.connectOverCDP(session.connectUrl)`
+ * with no `!` and no check for a field that cannot be missing.
+ */
+export interface LiveSessionDto extends SessionDto {
+    connectUrl: string;
+}
+
+/** `POST /v1/sessions` with `dryRun: true` — what holding a session would cost, without
+ *  starting one. The reservation is the whole `timeoutMin`; closing early hands the rest
+ *  back, so this is a ceiling, not a bill. */
+export interface SessionQuoteDto {
+    pool: ProxyPool;
+    timeoutMin: number;
+    /** Credits per minute held. */
+    perMinute: number;
+    /** `timeoutMin` × `perMinute` — reserved at create, settled by minutes used at close. */
+    maxCost: number;
+    /** Managed-pool megabytes included before `perMb` applies. 0 on BYO. */
+    freeMb: number;
+    /** Credits per additional megabyte through the managed pool. 0 on BYO. */
+    perMb: number;
+}
+// ── from packages/shared/src/dto/usage.ts ────────────────────────────
+
+/** One key's share of the month, for the console's per-key breakdown. Revoked keys stay in
+ *  the list: their spend still counts toward the account's month, and hiding them would make
+ *  the numbers stop adding up. */
+export interface UsageKeyDto {
+    id: string;
+    name: string;
+    prefix: string;
+    revoked: boolean;
+    /** Credits this key spent in the current billing month. */
+    credits: number;
+    /** Metered calls it made, free outcomes included — `calls` minus `credits` is where a
+     *  customer sees how much of their month cost them nothing. */
+    calls: number;
+}
+
+/** What `GET /v1/usage` and the console's meter both answer. One shape, two doors. */
+export interface UsageDto {
+    plan: PlanId;
+    /** The billing month this covers, `YYYY-MM`. */
+    month: string;
+    /** Credits spent against the plan quota this month. */
+    creditsUsed: number;
+    /** The plan's monthly grant. */
+    creditsIncluded: number;
+    /** Purchased credits left over (packs never expire). A separate pool from the quota:
+     *  collapsing the two would tell someone on packs they have 0 left while calls succeed. */
+    creditBalance: number;
+    /** Managed-proxy bytes used this month, MB, against the plan's hard ceiling. */
+    proxyMbUsed: number;
+    proxyMbIncluded: number;
+    /** When the quota rolls over — ISO. There is no cron: the month key simply changes. */
+    resetAt: string;
+    keys: UsageKeyDto[];
+}