@outcrawl/sdk 0.1.0

package/dist/types/result.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Turning a wire response into an SDK result.
+ *
+ * One rule, applied everywhere: **every result carries `usage`.** Not a metrics
+ * endpoint — the number that will appear on the bill, attached to the thing
+ * that caused it. Where the core type already has a `usage` field it is used as
+ * it arrives; where it does not, the API returns it in an envelope and it is
+ * attached here.
+ *
+ * Attached non-enumerably, so a decorated array is still the array a caller
+ * expects from `JSON.stringify` and from a deep equality assertion, and
+ * `hits.usage` still works.
+ *
+ * Nothing here invents a number. A response with no usage at all gets `{}`,
+ * which reads as "nothing to report" rather than as a measured zero.
+ */
+import { type Usage } from './_deps/core/index.js';
+import type { HandsFactory } from './hands.js';
+import type { Transport } from './transport.js';
+/** What every capability method on the client is given. */
+export interface ClientContext {
+    transport: Transport;
+    hands: HandsFactory;
+}
+/** A single result, with usage guaranteed. */
+export type Result<T> = T & {
+    readonly usage: Usage;
+};
+/**
+ * A list result. The array is the ergonomic surface; `cursor` and `usage` ride
+ * alongside it, out of the way of iteration.
+ *
+ * `cursor` absent means the last page — never `null`, because absence and null
+ * would be two ways to spell one state.
+ */
+export type Paged<T> = readonly T[] & {
+    readonly cursor: string | undefined;
+    readonly usage: Usage;
+};
+/** Attach usage to an array without making it an element or a visible key. */
+export declare function withUsage<T>(items: readonly T[], usage: Usage): readonly T[] & {
+    readonly usage: Usage;
+};
+/** Decorate a response whose core type already carries `usage` inline. */
+export declare function inlineUsage<T extends object>(body: T): Result<T>;
+/**
+ * Unwrap `{ data, usage }` for the capabilities whose core type has no usage of
+ * its own — profiles, monitors, session exports and deletes.
+ *
+ * A bare body is accepted too, so a 204 delete or an unenveloped response is
+ * not a crash.
+ *
+ * THE ITEM'S OWN `usage` WINS, and that condition is load-bearing rather than
+ * defensive. `AgentRun` legitimately carries both a `data` and a `usage` field
+ * — the tokens, the inference time and the cache verdict for the run — and it
+ * arrives inside this envelope, measured on 2026-09-08 against production:
+ *
+ *   GET /v1/agent/{id}
+ *   -> { data: { …, usage: { inputTokens: 3886, outputTokens: 4817, … } },
+ *        usage: {} }
+ *
+ * The earlier version defined `usage` unconditionally, so every agent read
+ * through this SDK — `agent.get`, `job.status()`, `await job`, `cancel`,
+ * `control`, `answer` — replaced the run's real usage with the envelope's
+ * empty one, and a customer reconciling an agent bill saw `{}`. Found by
+ * running the packed tarball against production beside the Python client,
+ * which printed the tokens the TypeScript one had already discarded.
+ */
+export declare function unwrapItem<T extends object>(body: unknown): Result<T>;
+/** Turn core's `ListResponse<T>` into the array form the SDK hands back. */
+export declare function pagedFrom<T>(body: unknown): Paged<T>;
+/** Confirmation that a delete happened, with what it cost. */
+export interface Deleted {
+    id: string;
+}
+/**
+ * A delete confirmation. The id is echoed back from the request when the API
+ * answers 204 with no body, so the result is the same shape either way and a
+ * caller never has to branch on how empty the response was.
+ */
+export declare function deletedFrom(body: unknown, id: string): Result<Deleted>;
+/**
+ * Query objects go on the URL, so every value has to be a string. Undefined
+ * fields are dropped rather than sent as the string "undefined".
+ *
+ * Takes `object`, not `Record<string, unknown>`: core's query interfaces have
+ * no index signature, and widening them at every call site with a cast would
+ * put a cast on the one path where a wrong key matters.
+ */
+export declare function queryOf(query: object): Record<string, string>;

package/dist/types/rules.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Rules — what a customer forbids, in their own words, and which of those we
+ * actually ENFORCE.
+ *
+ * The two methods return the same thing, and that is the design rather than a
+ * shortcut: {@link Rules.set} answers the classification of the rules it just
+ * stored, so a caller learns the split on the call that set them instead of on
+ * a later read they might never make.
+ *
+ * ── READ `class`, NOT `text` ─────────────────────────────────────────────────
+ *
+ * `class: 'enforced'` means the sentence compiled to a gate `@outcrawl/runtime`
+ * checks before every action, and a matching action is REFUSED before it
+ * reaches the page. `class: 'guidance'` means it is a line in the agent's
+ * prompt, which a model weighs against everything else it was told and may
+ * trade away under pressure.
+ *
+ * Three kinds compile to gates: a spend ceiling, a site allow/deny list, and a
+ * confirmation requirement on something irreversible. Anything else is
+ * guidance. When a sentence LOOKS enforceable and did not compile —
+ * an amount with no currency, a host with no direction, two constraints in one
+ * sentence — `unenforceable` says so in words. **That field is the one to
+ * check**: it is present exactly when we suspect a customer believes a rule is
+ * enforced and it is not.
+ */
+import { type RulesView } from './_deps/core/index.js';
+import { type ClientContext, type Result } from './result.js';
+export declare class Rules {
+    #private;
+    constructor(ctx: ClientContext);
+    /** The workspace rules and, per rule, whether it is enforced or guidance. */
+    get(): Promise<Result<RulesView>>;
+    /**
+     * REPLACE the workspace rules, and read the classification back.
+     *
+     * Replace and not append: there is no add-one route, because a rule set is
+     * read and rendered whole and a partial write is a workspace bound by half
+     * of two sets. Send the rules you want.
+     */
+    set(rules: readonly string[]): Promise<Result<RulesView>>;
+}

package/dist/types/scrape.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Scrape, crawl and search — the three capabilities that read pages rather than
+ * drive them.
+ *
+ * All three go through the registry: the method and path come from the
+ * capability row, never written out here.
+ */
+import type { CrawlJob, CrawlPage, CrawlRequest, ScrapeRequest, ScrapeResult, SearchHit, SearchRequest, Usage } from './_deps/core/index.js';
+import { type ClientContext, type Result } from './result.js';
+export type ScrapeOptions = Omit<ScrapeRequest, 'url'>;
+export type CrawlOptions = Omit<CrawlRequest, 'url'>;
+export type SearchOptions = Omit<SearchRequest, 'query'>;
+/** Search results, with the usage they cost attached to the set. */
+export type SearchHits = readonly SearchHit[] & {
+    readonly usage: Usage;
+};
+/**
+ * Fetch one URL and return clean content in the requested formats.
+ *
+ * Every request leaves through the browser's own network stack — same JA4, same
+ * HTTP/2 profile, same cookie jar — so there is no cheap-fetch-then-escalate
+ * path to burn an exit's reputation on a request that was already flagged. The
+ * saving is in stopping early, which is what `metadata.escalated` reports.
+ */
+export declare function scrape(ctx: ClientContext, url: string, options?: ScrapeOptions): Promise<Result<ScrapeResult>>;
+/**
+ * Search, optionally with every hit rendered through the scrape pipeline.
+ *
+ * Thin by design — the index is not our fight. What we add is that results come
+ * back rendered by us, which is the one thing the search vendors do not do.
+ */
+export declare function search(ctx: ClientContext, query: string, options?: SearchOptions): Promise<SearchHits>;
+/**
+ * A running crawl.
+ *
+ * Iterating it streams pages as they are scraped. Results are never batched: a
+ * caller sees page one while page one hundred is still in the frontier, which
+ * is the only delivery model that makes a hundred-page crawl usable.
+ */
+export declare class CrawlHandle implements AsyncIterable<CrawlPage> {
+    #private;
+    readonly id: string;
+    readonly url: string;
+    readonly createdAt: string;
+    constructor(job: CrawlJob, source: AsyncIterator<unknown>);
+    get status(): CrawlJob['status'];
+    /** Pages completed so far. Crawls stream, so this moves as you iterate. */
+    get completed(): number;
+    /** Pages the frontier knows about — an estimate until the crawl ends. */
+    get discovered(): number;
+    get usage(): Usage;
+    [Symbol.asyncIterator](): AsyncIterator<CrawlPage>;
+}
+/**
+ * Start a crawl.
+ *
+ * One capability, one call. The registry row declares the response framing, so
+ * this reads a stream because `crawl.framing` says `'ndjson'` and not because
+ * anyone here decided crawls stream: a header frame naming the job, then one
+ * `CrawlPage` per line as the frontier produces them. Awaiting `crawl()`
+ * resolves on the header, so a caller has the id and can begin iterating
+ * without a second round trip.
+ *
+ * If the row is ever declared `'json'`, this makes one plain request and the
+ * handle yields nothing — no invented pages, and no polling of a route the
+ * registry does not declare.
+ */
+export declare function crawl(ctx: ClientContext, url: string, options?: CrawlOptions): Promise<CrawlHandle>;

package/dist/types/secrets.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Secrets — a credential an agent uses and never sees.
+ *
+ * **There is no `get` and there never will be.** A read route would be a route
+ * somebody is eventually asked to make return the value, and the reason this
+ * store is worth having is that no such route exists to widen. `list` answers
+ * everything a human needs in order to pick a handle: the handle, the kind, and
+ * a card's last four digits.
+ *
+ * A run reaches a secret only by naming its HANDLE in the submit
+ * (`AgentRequest.secrets`), and the substitution happens below the model, at
+ * the moment the keystrokes reach the page. `packages/core/src/secrets.ts`
+ * states the rule; this class is the management half of it, for a human.
+ */
+import type { Secret, SecretCreateRequest, SecretQuery } from './_deps/core/index.js';
+import { type ClientContext, type Deleted, type Paged, type Result } from './result.js';
+export declare class Secrets {
+    #private;
+    constructor(ctx: ClientContext);
+    /**
+     * Store one credential and get back the row WITHOUT its value.
+     *
+     * The response is the only receipt that the value was stored, and `hint` is
+     * the only part of it that says anything about what was stored.
+     */
+    create(request: SecretCreateRequest): Promise<Result<Secret>>;
+    list(query?: SecretQuery): Promise<Result<Paged<Secret>>>;
+    /**
+     * Delete a credential and the record of which runs used it.
+     *
+     * Takes effect on the next fill rather than at the end of the run: a run
+     * holding a grant finds nothing to resolve and refuses by name, which is
+     * what "delete my card now" has to mean.
+     */
+    delete(id: string): Promise<Result<Deleted>>;
+}

package/dist/types/sessions.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Sessions and replay — the differentiator, with a first-class surface rather
+ * than a URL buried in an agent result.
+ *
+ * Every run has a replay. A customer disputing a charge gets to watch exactly
+ * what their money bought, step by step, which turns the worst support
+ * conversation in this industry into a link.
+ *
+ * Note there is no `identity` filter, deliberately, and one is refused by name
+ * rather than ignored. The equivalent internal query — "every brave block this
+ * week" — lives on the operator side, where the identity loop is run. Customers
+ * see outcomes; we see which identity produced them.
+ */
+import { type BilledResources, type ResolvedExit, type SessionExport, type SessionOutcome, type SessionQuery, type SessionStatus, type SessionSummary, type Timestamp, type Usage } from './_deps/core/index.js';
+import type { ReplayEvent } from './_deps/replay/events.js';
+import { Browser } from './browser.js';
+import type { HandsFactory, RawPage } from './hands.js';
+import type { OutcrawlPage } from './page.js';
+import { type ClientContext, type Paged, type Result } from './result.js';
+/**
+ * A session filter the API cannot honour. Named, not ignored: a silently
+ * dropped filter returns the wrong sessions and looks like it worked.
+ */
+export declare class UnsupportedSessionFilterError extends Error {
+    readonly name = "UnsupportedSessionFilterError";
+    readonly filter: string;
+    constructor(filter: string, why: string);
+}
+export declare function assertSupportedFilter(query: object): void;
+/**
+ * Interactive control of a running session.
+ *
+ * The practical answer to an agent stuck on a consent dialog at 2am, and the
+ * thing screenshots and video cannot do. Input goes through the same human path
+ * as everywhere else — taking over must not change how the session looks.
+ */
+export declare class SessionControl {
+    #private;
+    constructor(page: OutcrawlPage<RawPage>, browser: Browser);
+    /** Playwright's surface, untouched and recorded, exactly as on a page. */
+    get raw(): RawPage;
+    click(selector: string): Promise<void>;
+    fill(selector: string, value: string): Promise<void>;
+    type(selector: string, text: string): Promise<void>;
+    hover(selector: string): Promise<void>;
+    press(selector: string, key: string): Promise<void>;
+    selectOption(selector: string, values: readonly string[]): Promise<void>;
+    /** Hand the session back to the agent. */
+    release(): Promise<void>;
+}
+export interface SessionDeps extends ClientContext {
+    hands: HandsFactory;
+}
+/** One session, and everything you can do with it. */
+export declare class Session {
+    #private;
+    /** The record as the API returned it. */
+    readonly summary: SessionSummary;
+    constructor(summary: SessionSummary, ctx: SessionDeps);
+    get id(): string;
+    get status(): SessionStatus;
+    get outcome(): SessionOutcome | undefined;
+    get task(): string | undefined;
+    get profileId(): string | undefined;
+    /** Where this session actually came out. Session-scoped, not profile-scoped. */
+    get exit(): ResolvedExit | undefined;
+    get startedAt(): Timestamp;
+    get endedAt(): Timestamp | undefined;
+    /** Wall clock, in milliseconds. */
+    get duration(): number;
+    get pages(): number;
+    /**
+     * Hosted player, or `undefined` when this run was not durably recorded.
+     *
+     * `undefined` and not a thrown error or an empty string: a host with no
+     * durable replay storage records into memory and frees it on exit, so it
+     * publishes no link at all rather than one that 404s for the whole retention
+     * window. `SessionSummary.replayUrl` is optional for that reason and this
+     * getter reports it faithfully — an empty string would be a dead link with
+     * extra steps.
+     */
+    get replayUrl(): string | undefined;
+    get usage(): Usage;
+    get billed(): BilledResources | undefined;
+    /**
+     * Export the session as a portable bundle that plays offline.
+     *
+     * With a destination it is written there; without one you get the descriptor
+     * and can fetch the URL yourself.
+     */
+    export(destination?: string): Promise<Result<SessionExport>>;
+    /**
+     * Stream events while the session is still running.
+     *
+     * The same registry row as `get`, switched to a stream by the field that row
+     * declares in `streamsWhen`. Same session, followed rather than snapshotted —
+     * one row, not a second one only the SDK would carry, and not a query
+     * parameter this package invented.
+     *
+     * Events use the `ReplayEvent` vocabulary of the recorded format, so a live
+     * consumer and a replay consumer are the same code.
+     */
+    live(signal?: AbortSignal): AsyncIterable<ReplayEvent>;
+    /**
+     * Take the wheel on a running session. Attaches to the existing page rather
+     * than opening a new one — the point is to unstick the run that is already
+     * there.
+     */
+    takeControl(): Promise<SessionControl>;
+}
+export declare class Sessions {
+    #private;
+    constructor(ctx: SessionDeps);
+    get(id: string): Promise<Session>;
+    /**
+     * The two queries that make replay pay for itself:
+     * `{ outcome: 'blocked', since: '7d' }` and
+     * `{ status: 'partial', task: '*checkout*' }`. Twenty replays to watch rather
+     * than twenty log lines to guess from.
+     */
+    list(query?: SessionQuery): Promise<Paged<SessionSummary>>;
+    /** Export by id, without fetching the session first. */
+    export(id: string, destination?: string): Promise<Result<SessionExport>>;
+}

package/dist/types/transport.d.ts

@@ -0,0 +1,250 @@
+/**
+ * The transport seam.
+ *
+ * Everything the SDK does that leaves the process goes through {@link Transport}.
+ * That is not an abstraction for its own sake: it is the reason the whole client
+ * — including the Playwright page integration, `observe`/`act`, session live
+ * streams and interactive control — is testable with no network and no browser.
+ *
+ * There are two channels here and they are different in kind, exactly as the
+ * product surface says:
+ *
+ * - `request` / `stream` / `download` speak to the REST API, and every one of
+ *   those calls is addressed by a **capability name** from `@outcrawl/core`.
+ *   The method and path are read from the registry, never written out here, so
+ *   a route cannot drift from the registry row that declares it.
+ * - `connect` opens a live CDP session. The live `page` surface only exists in
+ *   the SDK because it needs a CDP connection in the caller's own process; API,
+ *   MCP and CLI reach the same capabilities through `agent` and `scrape`, which
+ *   run the loop on our side.
+ */
+import { type CapabilityName, type ExitTarget, type HttpMethod, type JsonSchema, type ObservedAction, type Timestamp, type Usage } from './_deps/core/index.js';
+import type { RawPage, WheelPath } from './hands.js';
+/**
+ * One call to one capability. `capability` is the registry key; `method` and
+ * `path` are read off the registry row by {@link resolveRequest} rather than
+ * supplied by the caller, so a fake transport in a test sees exactly the method
+ * and path the registry declares.
+ */
+export interface RequestSpec {
+    capability: CapabilityName;
+    method: HttpMethod;
+    /** Registry path with every `{param}` substituted. */
+    path: string;
+    query?: Readonly<Record<string, string>>;
+    body?: unknown;
+    signal?: AbortSignal;
+}
+export interface RequestInit_ {
+    params?: Readonly<Record<string, string>>;
+    query?: Readonly<Record<string, string>>;
+    body?: unknown;
+    signal?: AbortSignal;
+}
+/**
+ * Substitute `{id}`-style path parameters and build the {@link RequestSpec} for
+ * a capability. The registry is the only source of the method and the path
+ * template — nothing in this package writes a URL out by hand.
+ *
+ * Refuses a capability nothing serves, before building anything. This is the
+ * chokepoint rather than the individual client methods because it is the one
+ * place every REST call in the package already passes through: a method added
+ * later cannot reach an unserved route by forgetting to ask, and neither can a
+ * caller using this function directly from the `@outcrawl/sdk/transport`
+ * export.
+ */
+export declare function resolveRequest(capability: CapabilityName, init?: RequestInit_): RequestSpec;
+/** True when this row's default response framing is a stream. */
+export declare function alwaysStreams(capability: CapabilityName): boolean;
+/**
+ * The request field that switches a row to `ndjson`.
+ *
+ * Read from the registry rather than written out, because the last time a
+ * surface wrote one out it invented `live` six rows ahead of the registry that
+ * was supposed to be the single source of it.
+ */
+export declare function streamSwitch(capability: CapabilityName): string;
+/**
+ * What the transport is told when a browser is opened. Two fields, because a
+ * profile and a geography are the only two things a caller chooses. Identity,
+ * seed, fingerprint, timezone, languages and WebRTC address are minted by us;
+ * `assertNoIdentityOverride` in `browser.ts` refuses anything else by name
+ * before a socket is opened.
+ */
+export interface ConnectSpec {
+    profile?: string;
+    exit?: ExitTarget;
+    /**
+     * The caller declined this session's recording, with `record: false` on
+     * `oc.browser()`.
+     *
+     * `declineRecording: true` and not `record: false`, because only the refusal
+     * ever reaches the transport: absence already means recorded, so there is no
+     * second value for this field to carry and no way to spell the default.
+     * `HttpTransport.connect` turns it into `?record=false` on the allocation
+     * request; the router normalises that and signs the decision into the ticket,
+     * so nothing between here and the machine can strip it.
+     */
+    declineRecording?: true;
+    /** Attach to a session that is already running, for `session.takeControl()`. */
+    attachTo?: string;
+    signal?: AbortSignal;
+}
+/** Reviewable actions plus the usage the resolution cost. */
+export interface ObserveResponse {
+    actions: ObservedAction[];
+    usage: Usage;
+}
+export interface ExtractResponse {
+    data: unknown;
+    usage: Usage;
+}
+/**
+ * A live CDP session. `observe` and `extract` are session-scoped RPCs on our own
+ * endpoint rather than REST capabilities — that is the one documented
+ * difference in kind between the SDK and the other three surfaces.
+ */
+export interface Connection {
+    readonly sessionId: string;
+    /**
+     * Seeds the human-input timing so one identity keeps its typing pace and
+     * click character across sessions — real typing pace varies 3.6x between
+     * people, and an identity that returns at a different speed every visit is
+     * describing someone who is not the same person.
+     *
+     * Derived locally from the profile id the caller already named, never from
+     * the wire. A persona field on the allocation response would make identity a
+     * de facto part of the public API, and the next request after that is a
+     * customer asking to choose one. An ephemeral browser has no profile, so it
+     * falls back to the session id and its persona lasts exactly one session,
+     * which is all an ephemeral identity is.
+     */
+    readonly persona: string;
+    /** When the allocation ticket stops being redeemable. */
+    readonly expiresAt: string;
+    newPage(): Promise<RawPage>;
+    /**
+     * The browser's batched wheel entry point, `Outcrawl.dispatchWheelPath`.
+     *
+     * On the {@link Connection} rather than reached for through a raw CDP handle,
+     * because it is the one input path the SDK cannot express through Playwright:
+     * `Input.dispatchMouseWheel` has no parameter for a wheel event's phase, so it
+     * marks every event `began` and a page sees one cancelable wheel event and one
+     * `scrollend` per EVENT where a real device gives one of each per GESTURE.
+     * Measured on the shipped binary at 1600px: 3 of 108 cancelable and 3
+     * `scrollend` for three gestures through here, against 147 of 147 and 98 for
+     * the same library, profile and seed over `Input.dispatchMouseWheel`.
+     *
+     * Rejects while the session holds `Outcrawl.lock`, by design — the lock drops
+     * every input event before the renderer sees it, so a command that reported
+     * success would be lying.
+     */
+    dispatchWheelPath(path: WheelPath): Promise<unknown>;
+    /** Resolve an instruction to candidate actions. Executes none of them. */
+    observe(instruction: string, options?: {
+        cache?: boolean;
+    }): Promise<ObserveResponse>;
+    extract(instruction: string, schema?: JsonSchema): Promise<ExtractResponse>;
+    close(): Promise<void>;
+}
+/**
+ * A raw-input call, recorded against the session.
+ *
+ * `page.raw.click()` is the seam where a customer can accidentally undo the
+ * product: the click lands at Playwright's exact bounding-box centre with zero
+ * variance rather than going through `agenthands`. It stays available — setup
+ * steps where speed matters are a real need — but a run that used it is flagged
+ * rather than silently different, so a session that later gets blocked is not a
+ * mystery to whoever reads the replay.
+ */
+export interface RawInputMark {
+    kind: 'raw-input';
+    /** The Playwright method that was reached for, e.g. `click`. */
+    method: string;
+    /** The selector, or the namespace name for `mouse` / `keyboard`. */
+    target?: string;
+    at: Timestamp;
+}
+export interface Transport {
+    request<T>(spec: RequestSpec): Promise<T>;
+    /** Newline-delimited JSON: crawl pages, agent steps, live session events. */
+    stream(spec: RequestSpec): AsyncIterable<unknown>;
+    /** Fetch a bundle the API handed us a URL for, e.g. a session export. */
+    download(url: string, signal?: AbortSignal): Promise<Uint8Array>;
+    connect(spec: ConnectSpec): Promise<Connection>;
+    /**
+     * Annotate a live session out of band. Fire-and-forget by design: a mark must
+     * never be able to fail, slow or reorder a customer's click.
+     */
+    mark(sessionId: string, mark: RawInputMark): void;
+}
+/**
+ * An error body the client could not turn into a typed error — an unknown code
+ * from a newer server, or a response that was not an error envelope at all.
+ *
+ * Lenient on purpose. A client that rejected a body because the code is newer
+ * than the client would turn a 404 into a crash, during an incident, which is
+ * exactly when a new code is most likely to be in flight.
+ */
+export declare class OutcrawlApiError extends Error {
+    readonly name = "OutcrawlApiError";
+    readonly status: number;
+    readonly body: unknown;
+    /** The wire code, when there was one. Unknown to this client, not invalid. */
+    readonly code: string | undefined;
+    constructor(status: number, body: unknown, detail?: string);
+}
+/**
+ * Rebuild a typed error from the wire.
+ *
+ * The router returns core's `SerializedOutcrawlError` bare — `{ code, message,
+ * details }` with an HTTP status, no wrapper. Reconstructing the class rather
+ * than surfacing a generic HTTP failure is what makes
+ * `catch (e) { if (e instanceof ProfileInUseError) e.heldUntil }` work in a
+ * customer's own code, which is the entire value of the leased-profile
+ * contract: a retry that knows when to retry.
+ *
+ * Parsed as core's `WireError`, whose `code` is an open string — strict in what
+ * we emit, lenient in what we accept. A code this client does not know falls
+ * through to {@link OutcrawlApiError} carrying the code and body, rather than
+ * failing to parse.
+ */
+export declare function errorFromWire(status: number, body: unknown): Error;
+/** The slice of Playwright's `Browser` the SDK drives. */
+export interface CdpBrowser {
+    contexts(): CdpBrowserContext[];
+    newContext(): Promise<CdpBrowserContext>;
+    close(): Promise<void>;
+}
+export interface CdpBrowserContext {
+    pages(): RawPage[];
+    newPage(): Promise<RawPage>;
+    newCDPSession(page: RawPage): Promise<CdpSession>;
+}
+export interface CdpSession {
+    send(method: string, params?: Record<string, unknown>): Promise<unknown>;
+}
+export interface HttpTransportOptions {
+    apiKey: string;
+    /** Defaults to `https://outcrawl.ai`. */
+    baseUrl?: string;
+    /** Injected so the whole REST surface is exercisable without a network. */
+    fetch?: typeof globalThis.fetch;
+    /**
+     * Opens a CDP connection to a WebSocket endpoint. Defaults to Playwright's
+     * `chromium.connectOverCDP`, imported lazily so a caller who never opens a
+     * browser never loads Playwright — the SDK is optional, and so is its browser
+     * half.
+     */
+    connectOverCDP?: (wsEndpoint: string) => Promise<CdpBrowser>;
+}
+export declare class HttpTransport implements Transport {
+    #private;
+    readonly baseUrl: string;
+    constructor(options: HttpTransportOptions);
+    request<T>(spec: RequestSpec): Promise<T>;
+    stream(spec: RequestSpec): AsyncIterable<unknown>;
+    download(url: string, signal?: AbortSignal): Promise<Uint8Array>;
+    connect(spec: ConnectSpec): Promise<Connection>;
+    mark(sessionId: string, mark: RawInputMark): void;
+}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@outcrawl/sdk",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Outcrawl TypeScript client — scrape, crawl, search and drive real stealth browsers over CDP, on one credit balance.",
+  "keywords": [
+    "outcrawl",
+    "scraping",
+    "crawler",
+    "web-search",
+    "browser-automation",
+    "playwright",
+    "cdp",
+    "stealth",
+    "agent"
+  ],
+  "homepage": "https://outcrawl.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aeonmindai/outcrawl-browser.git",
+    "directory": "packages/sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/aeonmindai/outcrawl-browser/issues"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist/index.js",
+    "dist/types"
+  ],
+  "scripts": {
+    "build": "bun ./scripts/build.ts",
+    "prepack": "bun ./scripts/build.ts",
+    "test": "bun test ./test"
+  },
+  "peerDependencies": {
+    "agenthands": ">=1.1.1",
+    "playwright": "^1.56.0"
+  },
+  "peerDependenciesMeta": {
+    "agenthands": {
+      "optional": true
+    },
+    "playwright": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@outcrawl/core": "workspace:*",
+    "@outcrawl/integrations": "workspace:*",
+    "@outcrawl/proxy": "workspace:*",
+    "@outcrawl/replay": "workspace:*"
+  }
+}