@outcrawl/sdk 0.1.0

package/dist/types/_deps/core/errors.d.ts

@@ -0,0 +1,340 @@
+/**
+ * Typed errors.
+ *
+ * `code` is the wire contract: stable, machine-readable, never renamed once
+ * shipped. `message` is for humans and may change freely. Every error carries
+ * enough structured detail to act on — a `ProfileInUseError` that does not say
+ * when the lease expires just moves the guesswork to the caller.
+ */
+import type { CapName, ExitTarget, Timestamp } from './types.js';
+export declare const OUTCRAWL_ERROR_CODES: readonly ["unauthorized", "profile_in_use", "cap_exceeded", "exit_unavailable", "no_capacity", "tenant_scope", "bad_request", "not_found", "profile_not_found", "method_not_allowed", "capability_unavailable", "quota_exceeded", "concurrency_limit", "plan_required", "internal"];
+export type OutcrawlErrorCode = (typeof OUTCRAWL_ERROR_CODES)[number];
+/**
+ * What **we produce**. Every error this package throws serialises to exactly
+ * this, with a code drawn from the closed union above.
+ */
+export interface SerializedOutcrawlError {
+    code: OutcrawlErrorCode;
+    message: string;
+    details: Record<string, unknown>;
+}
+/**
+ * What **a client parses**. Deliberately wider: `code` is an open `string`.
+ *
+ * Strict in what we emit, lenient in what we accept. A client that rejects an
+ * error body because the code is newer than the client turns a 404 into a
+ * crash — and the failure lands during an incident, when a new code is most
+ * likely to be in flight and least likely to be welcome. Branch on the codes
+ * you know and fall through on the rest.
+ */
+export interface WireError {
+    code: string;
+    message: string;
+    details?: Record<string, unknown>;
+}
+/** Narrows an open wire code to the closed union, for exhaustive branching. */
+export declare function isKnownErrorCode(code: string): code is OutcrawlErrorCode;
+export declare abstract class OutcrawlError extends Error {
+    /** Stable across releases. Callers branch on this, never on `message`. */
+    readonly code: OutcrawlErrorCode;
+    /** Default HTTP status for the API layer. */
+    readonly status: number;
+    /** Structured, JSON-safe payload. Subclasses also expose it as typed fields. */
+    readonly details: Readonly<Record<string, unknown>>;
+    protected constructor(code: OutcrawlErrorCode, message: string, status: number, details: Readonly<Record<string, unknown>>);
+    toJSON(): SerializedOutcrawlError;
+}
+/**
+ * True for our errors, including ones raised by a second copy of this package
+ * in the same process — the SDK and the server can end up with their own — where
+ * `instanceof` is false despite an identical shape. Callers that only ever see
+ * errors from one copy can use `instanceof OutcrawlError` directly.
+ */
+export declare function isOutcrawlError(value: unknown): value is OutcrawlError;
+/**
+ * A profile is leased while in use. A second concurrent open throws rather than
+ * silently forking state, because the alternative is two sessions both writing
+ * cookies, last-writer-wins, and an account mysteriously logged out.
+ */
+export declare class ProfileInUseError extends OutcrawlError {
+    readonly profileId: string;
+    /** When the current lease expires on its own. Retry after this. */
+    readonly heldUntil: Date;
+    /** The session holding the lease, when the caller is allowed to see it. */
+    readonly heldBy: string | undefined;
+    constructor(profileId: string, heldUntil: Date, heldBy?: string);
+}
+/**
+ * A ceiling the caller set was reached. Caps, not refunds: the cost is bounded
+ * before it is incurred rather than argued about afterwards.
+ *
+ * An agent run that trips a cap mid-flight returns `status: 'partial' | 'failed'`
+ * with its data attached — this error is for a request that asks for more than
+ * the account or the call allows, refused before a browser is allocated.
+ */
+export declare class CapExceededError extends OutcrawlError {
+    /** Which ceiling: `steps`, `budget` or `duration`. */
+    readonly cap: CapName;
+    /** The ceiling that was set. Credits and durations are strings, steps a number. */
+    readonly limit: string | number;
+    /** What was reached or requested. Same units as `limit`. */
+    readonly observed: string | number;
+    constructor(cap: CapName, limit: string | number, observed: string | number);
+}
+/**
+ * No exit could be resolved for the requested geography — the country, region
+ * or city is not in the pool, or every exit there is currently unhealthy.
+ * Never silently substitute a neighbouring city: a profile whose exit moved is
+ * an identity that cannot exist.
+ */
+export declare class ExitUnavailableError extends OutcrawlError {
+    readonly target: ExitTarget;
+    readonly reason: string | undefined;
+    /** Set when the exit exists but is temporarily unhealthy. */
+    readonly retryAfter: Timestamp | undefined;
+    constructor(target: ExitTarget, reason?: string, retryAfter?: Timestamp);
+}
+/**
+ * A capability this deployment cannot serve, because nothing is configured
+ * behind it.
+ *
+ * The request was valid: the route exists, the arguments were accepted, and
+ * another worker with a different configuration would have answered it. What is
+ * missing is a dependency on this side — a result source for `search`, an exit
+ * provisioner for a request that names a geography — so the caller is told
+ * plainly rather than handed an incident id.
+ *
+ * Not retryable. The identical call against the same deployment fails
+ * identically until an operator configures something; the caller's only other
+ * move is a different request.
+ *
+ * `detail` exists to separate the two states that look the same from outside:
+ * a deployment that deliberately has no such dependency, and a build where
+ * nobody bound one. The second is now a type error at every seam in this
+ * repository, which is what lets this message promise it is the first.
+ */
+export declare class CapabilityUnavailableError extends OutcrawlError {
+    /** What was asked for: `search`, `a request that names an exit`. */
+    readonly capability: string;
+    /** What is not configured: `result source`, `exit provisioner`. */
+    readonly missing: string;
+    constructor(capability: string, missing: string, detail?: string);
+}
+/**
+ * A CDP connection touched a target outside its own tenant. This is the
+ * perimeter now that clients connect directly to workers: one connection may
+ * only ever drive its own BrowserContext, and enforcement sits at the two
+ * lookups every target resolution funnels through, so a method added in a
+ * future Chromium is scoped automatically rather than needing an allowlist.
+ */
+export declare class TenantScopeError extends OutcrawlError {
+    /** The CDP method that was refused, e.g. `Target.attachToTarget`. */
+    readonly method: string;
+    /** The target that was out of scope, when one was named. */
+    readonly targetId: string | undefined;
+    constructor(method: string, targetId?: string);
+}
+/** Why the router refused the caller. Never says which value was presented. */
+export type UnauthorizedReason = 'invalid_key' | 'ip_not_allowed' | 'missing_token';
+/**
+ * The router refused the request at the front door — before a worker is picked
+ * and before anything is billed.
+ */
+export declare class UnauthorizedError extends OutcrawlError {
+    readonly reason: UnauthorizedReason;
+    constructor(reason: UnauthorizedReason);
+}
+/**
+ * No worker could take the session: none is `ready` with free contexts and a
+ * cookie schema at least as new as the profile's. Cookie schema is the real
+ * compatibility key — an older worker cannot read a newer profile's stored
+ * state, and handing it one would silently lose the login rather than fail.
+ *
+ * Retryable: capacity is a moment-in-time property of the fleet, not of the
+ * request.
+ */
+export declare class NoCapacityError extends OutcrawlError {
+    /** The minimum cookie schema the caller's profile requires. */
+    readonly cookieSchema: number;
+    /** Set when the caller asked for a specific region. */
+    readonly region: string | undefined;
+    constructor(detail: {
+        cookieSchema: number;
+        region?: string;
+    });
+}
+/** Which ceiling refused the request. Both are per-account, never per-key. */
+export type QuotaCeiling = 'requests_per_minute' | 'monthly_credits';
+/**
+ * An account is over a ceiling its plan sets, refused before a worker is
+ * picked and before anything is billed.
+ *
+ * ## Why this is not `no_capacity`
+ *
+ * `no_capacity` is documented retryable *because the fleet is busy*, so a
+ * client that reads one backs off and tries again — correctly. Answering a
+ * quota refusal with it tells a customer who has exhausted their month to
+ * retry until the month ends, and it puts their traffic in the router's
+ * capacity metrics, where an operator then goes looking for workers that were
+ * never missing. Two facts, two codes.
+ *
+ * ## Why 429 and not 402
+ *
+ * `cap_exceeded` is 402 and means a ceiling the *caller* set for one call.
+ * This is a ceiling somebody set *for* the caller, and it lapses on its own at
+ * `resetAt` — which is precisely what 429 plus `Retry-After` describes. A 402
+ * says "pay"; this says "wait, and here is exactly how long".
+ *
+ * `limit` and `observed` are `string | number` for the same reason
+ * `CapExceededError` makes them so: a request count is an integer and credits
+ * are an exact decimal string that must never have been a float.
+ */
+export declare class QuotaExceededError extends OutcrawlError {
+    readonly ceiling: QuotaCeiling;
+    /** The ceiling the plan sets. */
+    readonly limit: string | number;
+    /** What the account has reached. Same units as `limit`. */
+    readonly observed: string | number;
+    /** When the ceiling lapses on its own. */
+    readonly resetAt: Timestamp;
+    /**
+     * `Retry-After`, in seconds, and always at least 1.
+     *
+     * Carried on the error rather than computed by whoever renders it, because
+     * the header and the instant have to agree: a caller that trusts the header
+     * and a dashboard that trusts `resetAt` disagreeing by a minute is a support
+     * ticket nobody can reproduce.
+     */
+    readonly retryAfterSeconds: number;
+    constructor(detail: {
+        ceiling: QuotaCeiling;
+        limit: string | number;
+        observed: string | number;
+        resetAt: Timestamp;
+        retryAfterSeconds: number;
+    });
+}
+/**
+ * The account is holding every browser its plan allows at once, refused before
+ * a worker is picked and before anything is billed.
+ *
+ * ## Why this is not `no_capacity`
+ *
+ * Because it is not about our hardware at all. `no_capacity` means no ready
+ * worker has a free context, which is a property of the FLEET at that instant
+ * and is fixed by machines; this means the customer is using everything they
+ * bought, which is a property of THEIR account and is fixed by ending a
+ * session or moving to a larger plan. Sharing a code between them tells a
+ * customer at their ceiling to blame us and wait, and it puts their traffic in
+ * the router's capacity metrics — where an operator then provisions Macs that
+ * will not help. Two facts, two codes, and this is the third one.
+ *
+ * ## Why this is not `quota_exceeded`
+ *
+ * Both of that error's ceilings lapse on their own: a rolling minute drains
+ * and a calendar month ends, so it carries a `resetAt` and a `Retry-After`
+ * that a client can obey. A concurrency slot lapses when the CUSTOMER closes a
+ * browser and at no other time, so there is no instant to name. Putting a
+ * number in `Retry-After` here would be an invention, and a client obeying an
+ * invented backoff is worse off than one told plainly that the next move is
+ * theirs — which is why `errorResponse` sets that header for `quota_exceeded`
+ * and deliberately not for this.
+ *
+ * ## Why 429 rather than 402 or 503
+ *
+ * 429 is literally "too many requests", and too many AT ONCE is the same
+ * family as too many per minute — a client that already handles one handles
+ * this. 402 (`cap_exceeded`) says "pay", which is wrong for a customer who has
+ * paid and is simply using it all. 503 says "we are broken", which is a lie
+ * about a healthy fleet.
+ *
+ * `plan` is named in the message because that is what makes the sentence
+ * actionable: `5` on its own is a number, and `plan builder allows 5` tells a
+ * customer which line of the pricing page to read and an operator which key to
+ * move. `observed` is the count at the instant of refusal, so support can tell
+ * "at the ceiling" from "nowhere near it, something else is wrong".
+ */
+export declare class ConcurrencyLimitError extends OutcrawlError {
+    /** The plan's name, as the pricing page spells it. */
+    readonly plan: string;
+    /** Browsers the plan allows at once. */
+    readonly limit: number;
+    /** Browsers the account was holding when it asked for one more. */
+    readonly observed: number;
+    constructor(detail: {
+        plan: string;
+        limit: number;
+        observed: number;
+    });
+}
+/**
+ * The key authenticated and names no plan this deployment can serve, so there
+ * is no ceiling to enforce and the request is refused.
+ *
+ * Three records reach this and the answer is the same for all three, because
+ * the operator's next action is: a key minted before plans existed, a key
+ * naming a tier that is not published, and a key carrying the pre-tier pair of
+ * loose ceiling numbers with no tier name at all.
+ *
+ * ## Why refusing is the only safe direction
+ *
+ * The alternative is treating an absent plan as unlimited, and the failure mode
+ * of that choice is a free fleet: one key opening sessions until the machines
+ * fall over, with the invoice as the first thing that notices. A key that
+ * cannot be metered against a ceiling is a key that must not be served, so an
+ * absent plan fails closed here rather than defaulting anywhere.
+ *
+ * ## Why it is not `unauthorized`
+ *
+ * Nothing is wrong with the credential. Reporting `invalid_key` would send a
+ * customer to rotate a perfectly good key, and rotation carries the plan over,
+ * so they would rotate forever. The party who can fix this is the operator who
+ * minted the key without one, and 403 with this code is what tells support
+ * which of the two to call.
+ *
+ * `keyId` is echoed deliberately. It is the half of the token that already
+ * travels in the clear so the record can be fetched by primary key, so it is
+ * not a secret, and it is the exact string an operator types into
+ * `outcrawl admin keys get`.
+ */
+export declare class PlanRequiredError extends OutcrawlError {
+    readonly keyId: string;
+    constructor(keyId: string);
+}
+/** Malformed or missing input. The caller can fix this and retry. */
+export declare class BadRequestError extends OutcrawlError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/** No such resource, or none this caller is allowed to know exists. */
+export declare class NotFoundError extends OutcrawlError {
+    readonly resource: string;
+    constructor(resource: string, id?: string);
+}
+/**
+ * A named profile does not exist, or belongs to another account.
+ *
+ * Deliberately indistinguishable from the not-belonging case: profiles are
+ * named by the customer, so a distinct "exists but is not yours" would let one
+ * account enumerate another's profile labels.
+ */
+export declare class ProfileNotFoundError extends OutcrawlError {
+    readonly profileId: string;
+    constructor(profileId: string);
+}
+/** Wrong HTTP method. `allow` populates the `Allow` header RFC 9110 requires. */
+export declare class MethodNotAllowedError extends OutcrawlError {
+    readonly allow: readonly string[];
+    constructor(method: string, allow: readonly string[]);
+}
+/**
+ * Something broke on our side.
+ *
+ * `message` is fixed and carries no detail on purpose — an internal error is
+ * the one place where a helpful message leaks a stack, a query or a hostname to
+ * whoever provoked it. Diagnostics go to logs under `incidentId`, which the
+ * caller can quote to support.
+ */
+export declare class InternalError extends OutcrawlError {
+    readonly incidentId: string | undefined;
+    constructor(incidentId?: string);
+}

package/dist/types/_deps/core/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `@outcrawl/core` — the shared contract.
+ *
+ * Wire types, the capability registry every surface is checked against, and the
+ * typed errors. No dependencies and no runtime beyond validation, because every
+ * other package imports this one.
+ */
+export * from './types.js';
+export * from './agent-alias.js';
+export * from './brand.js';
+export * from './certificate.js';
+export * from './cron.js';
+export * from './money.js';
+export * from './rules.js';
+export * from './secrets.js';
+export * from './registry.js';
+export * from './errors.js';

package/dist/types/_deps/core/money.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Exact decimal arithmetic on strings.
+ *
+ * Money and meters are never floats. `BilledResources.credits` and
+ * `UsageEventRow.quantity` are decimal strings precisely so a value cannot pass
+ * through binary64 and come back a fraction of a cent different, and every
+ * operation on them has to preserve that.
+ *
+ * This lives in core because three places need it — the agent loop's budget
+ * cap, the API's meter, and billing — and two independent implementations of
+ * money addition is how they disagree by a cent in a reconciliation nobody can
+ * attribute. It is the same argument as `ListResponse` and `WallClock`, with a
+ * worse failure mode: a wrong number that looks right.
+ *
+ * Everything here is bigint underneath. No `Number` appears in an arithmetic
+ * path, only in the scale bookkeeping, where the values are small integers.
+ */
+export declare const ZERO_CREDITS = "0";
+export declare function isDecimalString(value: unknown): value is string;
+/** Exact addition. The result keeps the wider of the two scales. */
+export declare function addDecimal(a: string, b: string): string;
+/**
+ * Exact multiplication. The result's scale is the **sum** of the two scales,
+ * which is the only scale at which a product is exact: `0.001 * 0.002` is
+ * `0.000002`, and any narrower result has rounded.
+ *
+ * No rounding is applied here on purpose. A rate card times a quantity is a
+ * number three different consumers reconcile against — the meter, the token
+ * cost of a model call, and a captcha rate card amortised per solve — and each
+ * rounds at a different point for a different reason. Rounding here would make
+ * that decision once, silently, in the wrong place.
+ */
+export declare function multiplyDecimal(a: string, b: string): string;
+/** -1, 0 or 1. `compareDecimal('0.30', '0.3') === 0`: scale is not value. */
+export declare function compareDecimal(a: string, b: string): number;
+/**
+ * The published price of one second of an agent run, and of one page it loads.
+ *
+ * ── Why this is in core and not only in the rate card ───────────────────────
+ *
+ * Because `AgentCaps.budget` is a promise about the number on the INVOICE, and
+ * until this existed the two were different quantities. `CapLedger` was charged
+ * only from `ModelChoice.credits` — model spend, priced in `@outcrawl/model`'s
+ * USD card — and `ModelClientOptions.creditsPerUsd` is deliberately unset in
+ * production, because the plan tiers price a credit at 204/251/313 to the
+ * dollar and the worker does not know the caller's tier. So `creditsFor`
+ * returned `undefined`, the loop's `if (choice.credits !== undefined)` guard
+ * never fired, and the ledger held `'0'` for the whole run. `tripped()` ran on
+ * every step and compared `'0' >= '0.50'` forever.
+ *
+ * The cap was not failing to hold the line. It was measuring a quantity that is
+ * always zero, while the customer was billed for three others. Measured on
+ * production 2026-09-08: 26 runs carried a budget, 12 exceeded it, worst 4.20x,
+ * and `max-budget` had never once been the stop reason.
+ *
+ * The invoice is `page_load + agent_seconds + context_seconds` — the exact rows
+ * `meterAgentRun` writes in `@outcrawl/api`. On `run_7a643435`, cap `0.50`:
+ *
+ *     page_load        1 x 1        = 1.000000
+ *     agent_seconds    7.606 @ 5/60 = 0.633833
+ *     context_seconds  7.606 @ 1/60 = 0.126767
+ *     tokens           9,954        = 0          <- the rate card has no token line
+ *                                    ----------
+ *                                     1.760600   = 3.52x the cap
+ *
+ * So the run's price is a rate on TIME plus a rate on PAGES, and the loop can
+ * evaluate both while it is still running. It cannot reach the rate card:
+ * `@outcrawl/persistence` depends on `@outcrawl/runtime`, so the runtime
+ * importing it back is a cycle. Injecting the rate from the host was the option
+ * rejected — a host that forgets to pass it silently unbinds the cap, which is
+ * `creditsPerUsd`'s defect wearing a different name. So the number lives here,
+ * where both sides can reach it, and `test/rate-card.test.ts` in
+ * `@outcrawl/persistence` asserts these two constants against
+ * `OUTCRAWL_CREDIT_RATES` so a reprice cannot move one without the other.
+ *
+ * `'0.1'` and not the ratio `6/60`: it is the SUM of the two per-minute rates
+ * the invoice charges — Agent at +5 and the browser it holds at 1 — and six
+ * over sixty is exactly a tenth, so pricing a second needs no division and
+ * therefore no rounding scale. That matters because `multiplyDecimal` is exact
+ * and division is not: `divide` in the rate card has to choose six places, and a
+ * cap that rounded UP would stop a run fractionally before its ceiling while a
+ * cap that rounded DOWN would let it past. Neither is defensible in a ceiling,
+ * and at a tenth per second the question does not arise.
+ *
+ * The invoice still prices the two minute-rates as separate rows and rounds each
+ * to six places, so the ledger's figure and the bill's can differ by at most one
+ * unit in the last place of each row — 2e-6 credits. On `run_7a643435` the two
+ * roundings cancelled exactly: `0.633833 + 0.126767 = 0.760600`, and
+ * `7.606 x 0.1 = 0.7606`, the same number. That residual is an artefact of the
+ * invoice showing two lines, not a second opinion about the price.
+ */
+export declare const RUN_CREDITS_PER_SECOND = "0.1";
+/** One rendered page, at the published Scrape rate. See {@link RUN_CREDITS_PER_SECOND}. */
+export declare const RUN_CREDITS_PER_PAGE = "1";
+/**
+ * What a run is charged for, as one value a ledger can be constructed with.
+ *
+ * Both fields are required. An optional rate reads as "this deployment does not
+ * charge for time", which is the shape that made the budget cap a no-op.
+ */
+export interface RunPricing {
+    /** Credits per second of run time. */
+    readonly creditsPerSecond: string;
+    /** Credits per page load. */
+    readonly creditsPerPage: string;
+}
+/** The published price list, as {@link RunPricing}. */
+export declare const OUTCRAWL_RUN_PRICING: RunPricing;