@outcrawl/sdk 0.1.0

package/dist/types/agent.d.ts

@@ -0,0 +1,313 @@
+/**
+ * Agent — a natural-language browser task under hard caps, as a JOB.
+ *
+ * `caps` is required, at the type level and at runtime. The customer sets a
+ * ceiling before spending rather than disputing a bill afterwards, and since
+ * failures cost more than successes — agents flail, retry and loop — the same
+ * cap protects our margin as much as their wallet. Published task success rates
+ * are 42–71%, so a run that ends `partial` is normal, and the schema-shaped
+ * data it did get comes back rather than being thrown away.
+ *
+ * `schema` is OPTIONAL and omitting it does not cost you the answer. With a
+ * schema, `run.data` is schema-shaped and satisfying it is the success signal.
+ * Without one it is the agent's own closing summary — a string — so a question
+ * asked in plain language is answered in plain language. A task that asks
+ * nothing, "click the unsubscribe link", returns no `data` at all; the field is
+ * optional and its absence is a success, not an error.
+ *
+ * ── What changed, and why every caller has to know ───────────────────────────
+ *
+ * `oc.agent(...)` used to BE the run: awaiting it blocked for as long as the
+ * task took and iterating it streamed steps off a held socket. Both were the
+ * same HTTP request, so both died at the platform's fifteen-minute forward
+ * timeout with no terminal frame.
+ *
+ * Submitting now returns in milliseconds with an id. The run outlives the
+ * request, hours are normal, and there is no duration ceiling. `await` still
+ * works and still gives you the finished run — see {@link AgentJob.then} — but
+ * it is a POLL over a durable row rather than a socket, so a dropped connection
+ * costs nothing and a killed browser costs nothing. `for await` still gives you
+ * the log as it happens — see {@link AgentEvents} — but it is a CURSOR TAIL
+ * over durable rows, so a consumer that dies resumes at the sequence it had
+ * reached instead of losing the run.
+ *
+ * The four job routes are reachable two ways, and both are the same code. From
+ * the handle a submit hands back, `job.status()`, when you have the run. From
+ * `oc.agent.get(id)` and friends, when all you have is an id off a queue or a
+ * webhook — a run outlives the process that submitted it, so an SDK that only
+ * spoke to submit handles could not read yesterday's run.
+ */
+import { type AgentEventLevel, type AgentRecord, type AgentRequest, type AgentRun, type AgentSubmission, type Usage } from './_deps/core/index.js';
+import { type ClientContext, type Paged, type Result } from './result.js';
+/**
+ * An agent request was rejected before a browser was allocated. Carries every
+ * problem at once rather than one per round trip.
+ */
+export declare class InvalidAgentRequestError extends Error {
+    readonly name = "InvalidAgentRequestError";
+    readonly errors: readonly string[];
+    constructor(errors: readonly string[]);
+}
+/** What {@link AgentHandle.events} takes: where to resume, and how much to say. */
+export interface AgentEventOptions {
+    /** Resume: everything with a greater `seq`. Omitted starts at the beginning. */
+    readonly after?: number;
+    readonly level?: AgentEventLevel;
+}
+/** What {@link AgentHandle.results} takes. */
+export interface AgentResultsOptions {
+    readonly cursor?: string;
+    readonly limit?: number;
+}
+/**
+ * What `POST /v1/agent/{id}/files` answers: the HANDLE and what was stored.
+ *
+ * `id` is the whole point — it is what an agent's `attachFile` action names,
+ * and the model addresses it and never the bytes. It is minted server-side and
+ * never chosen by a caller, because `up/<runId>/<fileId>` is a path in a
+ * bucket shared by every tenant.
+ *
+ * `bytes` is the DECODED length, so a caller can confirm the file arrived
+ * whole rather than trusting that base64 round-tripped.
+ */
+export interface AgentFile {
+    readonly id: string;
+    readonly run: string;
+    readonly name: string;
+    readonly contentType: string;
+    readonly bytes: number;
+}
+/**
+ * A run's log, as it happens.
+ *
+ * ── The paging is invisible and that is the whole design ─────────────────────
+ *
+ * The wire is a CURSOR TAIL: one request returns everything after a sequence
+ * number and ends, which is what lets a stateless Worker serve it and what
+ * makes a dropped connection free. Iterating this re-requests from the cursor
+ * the previous page ended on and stops when a page comes back `done`, so a
+ * caller writes `for await (const record of job.events())` and never sees a
+ * page boundary.
+ *
+ * It backs off while nothing is happening rather than hammering: a run thinking
+ * for two minutes about one page produces no records.
+ *
+ * Iterating twice is allowed and resumes rather than replaying — {@link cursor}
+ * is durable state on our side, not a socket. That is the difference from
+ * `CrawlHandle`, which refuses a second pass because a held stream genuinely
+ * cannot be read again.
+ */
+export declare class AgentEvents implements AsyncIterable<AgentRecord> {
+    #private;
+    constructor(ctx: ClientContext, id: () => Promise<string>, options?: AgentEventOptions);
+    /**
+     * The highest `seq` seen. Hand it back as `after` to resume exactly here: the
+     * store allocates `seq` gap-free per run, so a consumer that stops cannot
+     * miss a row it never saw.
+     */
+    get cursor(): number;
+    /** The run as its last header frame described it. Undefined before the first. */
+    get run(): AgentRun | undefined;
+    /**
+     * What the run has cost so far, off the header frame the tail opens with.
+     * Current rather than final while the run is live, like every other quantity
+     * on the row.
+     */
+    get usage(): Usage;
+    [Symbol.asyncIterator](): AsyncIterator<AgentRecord>;
+}
+/**
+ * A run on our side, reached by id.
+ *
+ * Four things a caller does with one: read it, watch it, page its output, stop
+ * it. Every one of them is a separate request against a durable row, so a
+ * handle is cheap, holds nothing open, and works for a run this process did not
+ * submit.
+ */
+export declare class AgentHandle {
+    #private;
+    constructor(ctx: ClientContext, id: string | (() => Promise<string>));
+    /** This run's id. */
+    id(): Promise<string>;
+    /** Status, plan, findings so far and cost so far. Safe to call in a loop. */
+    status(): Promise<Result<AgentRun>>;
+    /** Everything the run has done, in order, from a cursor. */
+    events(options?: AgentEventOptions): AgentEvents;
+    /**
+     * The records this run appended, a page at a time, oldest first.
+     *
+     * Records land DURING the run, so this answers before it has finished — which
+     * is the property that makes a killed run still deliver what it bought.
+     */
+    results(options?: AgentResultsOptions): Promise<Paged<AgentRecord>>;
+    /**
+     * Stop the run. Answers the run as it stands, so a caller learns in one round
+     * trip whether it had already finished — cancelling a completed run is a
+     * no-op and must not read as a failure.
+     *
+     * Work already performed is still billed. `caps` is the protection; this is
+     * the stop button.
+     */
+    cancel(): Promise<Result<AgentRun>>;
+    /**
+     * `POST /v1/agent/{id}/control` — take this run's browser, or hand it back.
+     *
+     * Taking PAUSES the agent where it stands and leaves the page open;
+     * `AgentRun.pause.viewerUrl` on the answer, once the machine has parked, is
+     * where a person drives it. Releasing resumes the run from whatever page
+     * they left it on — not from where the agent was, because a human who drove
+     * may well have navigated, and pretending otherwise is how a click lands on
+     * a page nobody read.
+     *
+     * Answers the RUN and not an acknowledgement, on `cancel`'s terms: the
+     * request is durable when this returns, the machine notices within a
+     * heartbeat, and a run that had already finished answers with its terminal
+     * status rather than throwing — asking for the wheel of a run that just
+     * settled is a race a caller cannot avoid.
+     *
+     * Parked time is not charged to `caps.duration` and is not billed.
+     */
+    control(action: 'take' | 'release', who?: string): Promise<Result<AgentRun>>;
+    /**
+     * `POST /v1/agent/{id}/answer` — reply to a question this run parked on.
+     *
+     * The question is on `AgentRun.pause` and on the event stream as a
+     * `question` record, so a caller that is not watching a socket still finds
+     * it. The answer becomes a finding the run cannot forget for the rest of its
+     * life, and the run resumes from the step it stopped on.
+     *
+     * Refused, naming the status, on a run that is not waiting on anything: an
+     * answer stored against a run that is not asking would be delivered to
+     * whatever it asks next.
+     */
+    answer(answer: string, answeredBy?: string): Promise<Result<AgentRun>>;
+    /**
+     * `POST /v1/agent/{id}/files` — hand this run a file, and get the HANDLE the
+     * agent attaches it with.
+     *
+     * Callable at any point in the run's life, including before it has taken a
+     * step: a run id exists the instant the submit is answered, and the bucket is
+     * the queue. Refused once the run has ENDED, because the terminal path has
+     * already destroyed this run's files and one accepted afterwards would
+     * outlive the run it belonged to.
+     *
+     * `bytes` is the file. Base64 is applied here rather than by the caller
+     * because the wire form is a JSON body and encoding it is not a decision a
+     * caller should have to make correctly — and getting it wrong produces a
+     * file that stores and then attaches corrupt.
+     *
+     * The file is DESTROYED when the run ends, on every ending. There is no
+     * download counterpart and that is deliberate, not missing.
+     */
+    addFile(file: {
+        readonly name: string;
+        readonly bytes: Uint8Array;
+        readonly contentType?: string;
+    }): Promise<Result<AgentFile>>;
+    /**
+     * Wait for the run to settle, and answer it.
+     *
+     * A poll over the row rather than a held socket, so it survives a dropped
+     * connection, a restarted process on our side, and a run that takes four
+     * hours.
+     */
+    settled(): Promise<Result<AgentRun>>;
+}
+/**
+ * A submitted run.
+ *
+ * Everything an {@link AgentHandle} does, plus the submit itself: `await` for
+ * the finished run, `for await` for the log while it happens. Both are now
+ * separate requests against a durable row, so unlike the held-socket version
+ * they are not exclusive — doing both is one run, not two.
+ */
+export declare class AgentJob extends AgentHandle implements PromiseLike<Result<AgentRun>>, AsyncIterable<AgentRecord> {
+    #private;
+    /**
+     * The submit response: the id, and that it is queued.
+     *
+     * A promise, because submitting is a round trip and this object is returned
+     * synchronously — `oc.agent(...)` cannot block. Everything else on this class
+     * awaits it, so a caller who only wants to fire and forget never has to.
+     */
+    readonly submitted: Promise<Result<AgentSubmission>>;
+    constructor(ctx: ClientContext, request: AgentRequest);
+    /**
+     * Await the finished run.
+     *
+     * Kept, because `const run = await oc.agent({...})` is the line every caller
+     * writes first and refusing to support it would make the simple case the
+     * awkward one. Memoised: two `await`s on the same job are one poll loop, not
+     * two.
+     */
+    then<TResult1 = Result<AgentRun>, TResult2 = never>(onfulfilled?: ((value: Result<AgentRun>) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): PromiseLike<TResult1 | TResult2>;
+    /**
+     * Iterate the run's log. `for await (const record of oc.agent({...}))` is the
+     * other line callers write, and it is {@link AgentHandle.events} underneath —
+     * the cursor tail, not a socket.
+     */
+    [Symbol.asyncIterator](): AsyncIterator<AgentRecord>;
+}
+/**
+ * Submit an agent run.
+ *
+ * The request is validated with core's own validator, which is the same check
+ * the API applies — so a JavaScript caller who omits `caps` is refused here,
+ * in their own process, with the reason, rather than by a 4xx after a round
+ * trip. TypeScript callers cannot omit it at all.
+ */
+export declare function agent(ctx: ClientContext, request: AgentRequest): AgentJob;
+/**
+ * `oc.agent` — callable, and the namespace for the job routes.
+ *
+ * Callable because submitting is what the capability IS, and `oc.agent.submit`
+ * would be a second spelling of it. A namespace as well because the registry
+ * declares seven more rows against the same run and an id from a webhook has
+ * to reach them: `oc.agent.get(id)` is the same request `job.status()` makes.
+ *
+ * **Every member is named after its row's last segment**, which is why the
+ * file route is `files` and not `addFile`: `test/registry.test.ts` walks the
+ * dotted capability name — `agent.files` — straight onto this object, and a
+ * member spelled differently is a row the coverage test reports as
+ * unreachable. `AgentHandle.addFile` keeps the readable name, because a handle
+ * already knows its run and reads as a verb on it.
+ */
+export interface AgentApi {
+    (request: AgentRequest): AgentJob;
+    /** A handle on a run this process did not submit. */
+    job(id: string): AgentHandle;
+    /** `GET /v1/agent/{id}` — where one run has got to. */
+    get(id: string): Promise<Result<AgentRun>>;
+    /** `GET /v1/agent/{id}/events` — the log, from a cursor. */
+    events(id: string, options?: AgentEventOptions): AgentEvents;
+    /** `GET /v1/agent/{id}/results` — the records it appended. */
+    results(id: string, options?: AgentResultsOptions): Promise<Paged<AgentRecord>>;
+    /** `POST /v1/agent/{id}/cancel` — stop spending. */
+    cancel(id: string): Promise<Result<AgentRun>>;
+    /**
+     * `POST /v1/agent/{id}/control` — take this run's browser, or hand it back.
+     *
+     * Taking pauses the agent where it stands and leaves the page open; the
+     * answer carries `AgentRun.pause.viewerUrl` once the machine has parked.
+     * Releasing resumes from whatever page the person left it on.
+     */
+    control(id: string, action: 'take' | 'release', who?: string): Promise<Result<AgentRun>>;
+    /**
+     * `POST /v1/agent/{id}/answer` — reply to a question this run parked on.
+     *
+     * Refused, naming the status, on a run that is not waiting on anything.
+     */
+    answer(id: string, answer: string, answeredBy?: string): Promise<Result<AgentRun>>;
+    /**
+     * `POST /v1/agent/{id}/files` — hand a run a file, at any point in its life.
+     *
+     * Answers the HANDLE, which is what the agent's `attachFile` action takes.
+     * The file is destroyed when the run ends. There is no download counterpart.
+     */
+    files(id: string, file: {
+        readonly name: string;
+        readonly bytes: Uint8Array;
+        readonly contentType?: string;
+    }): Promise<Result<AgentFile>>;
+}
+export declare function createAgentApi(ctx: ClientContext): AgentApi;

package/dist/types/availability.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Which capabilities this SDK will actually let a caller reach.
+ *
+ * The registry in `@outcrawl/core` answers "does this capability have a route".
+ * It deliberately does not answer "does anything run behind that route", and
+ * those are different questions: `monitors.*` has a registry row, a matched
+ * route, a request validator, a Postgres table, a tenant-scoped store and, as
+ * of tonight, a working scheduler — and the row a customer creates still never
+ * reaches any of it, because the API writes to memory and the scheduler reads
+ * Postgres. `POST /v1/monitors` answers `201` for a monitor that will never be
+ * checked and never notify anybody.
+ *
+ * That is the worst failure a client can have, because it is indistinguishable
+ * from success. It fails at the customer's integration, weeks later, as "my
+ * monitor never fired" — not at the call. So this table is the seam between
+ * "declared" and "served", and it is checked at the one place every REST call
+ * in this package passes through.
+ *
+ * THE TEST FOR ADDING A ROW HERE — and it is not "how broken does this feel":
+ *
+ *   Does the capability DO ANYTHING for the caller as it stands?
+ *
+ * If no, it is inert and belongs in this table. A monitor held in one machine's
+ * memory is inert: the scheduler reads Postgres and will never see it, so
+ * `create` is a promise that is never kept, and refusing is the honest answer.
+ * If yes, it stays `null` and its limits are DOCUMENTED, however uncomfortable
+ * they are. A profile held in that same memory genuinely works — it pins the
+ * identity and persists the cookies for as long as that machine is up — so
+ * refusing it would break something a customer can use today. Same defect
+ * underneath, opposite correct response, and what separates them is whether the
+ * feature does anything, not how bad the underlying state is. Getting this
+ * backwards ships an SDK that refuses working features, which is the same
+ * defect as one that offers broken features, pointed the other way.
+ *
+ * The field is REQUIRED for every capability and an available one declines it
+ * with an explicit `null`. That is the whole point: `satisfies
+ * Record<CapabilityName, …>` means a row added to the registry does not compile
+ * here until somebody states whether anything serves it. An optional field
+ * would have defaulted the answer to "available", which is the exact shape of
+ * the defect this file exists to prevent — the SDK claiming a capability the
+ * server does not have.
+ */
+import { type CapabilityName } from './_deps/core/index.js';
+/** Why a declared capability cannot be reached, and when it will be. */
+export interface Unavailable {
+    /**
+     * What is not built, in the words {@link CapabilityUnavailableError} uses
+     * after "no": `monitor scheduler` reads as "no monitor scheduler is
+     * configured".
+     */
+    readonly missing: string;
+    /**
+     * The rest of the story, appended to the error message verbatim. States what
+     * does exist, what does not, and when it will — with no invented date, since
+     * a date nobody committed to is another optional field filled in by guessing.
+     */
+    readonly detail: string;
+}
+/**
+ * `null` means served: the capability is reachable and the call goes out.
+ *
+ * Anything else is refused here, in the caller's own process, before a request
+ * is built. Refusing locally rather than letting the server answer is right for
+ * exactly one reason — the server answers these successfully today.
+ */
+export declare const CAPABILITY_AVAILABILITY: Readonly<Record<CapabilityName, Unavailable | null>>;
+/**
+ * Refuse a capability nothing serves.
+ *
+ * Throws {@link CapabilityUnavailableError} — the existing error, with the
+ * existing `capability_unavailable` code, rather than a second class carrying
+ * the same code. A caller already branching on that code for an unconfigured
+ * worker needs no new case, and `isOutcrawlError` keeps working.
+ *
+ * FAILS CLOSED on a capability the table does not declare. `satisfies` catches
+ * a missing row at compile time, but it cannot help a name that arrives at
+ * runtime — from a newer server, or a hand-built `resolveRequest` call through
+ * the published transport export. The first version of this function read
+ * `undefined` for such a name, took the `!== null` branch and then threw a
+ * `TypeError` about reading `missing` of undefined: refused, technically, but
+ * with an untyped error carrying no code, which every caller branching on
+ * `code` would have dropped into its generic handler. Undeclared now refuses
+ * by name, because "unknown means allowed" is how a client ends up claiming a
+ * capability nobody implemented.
+ */
+export declare function assertAvailable(capability: CapabilityName): void;

package/dist/types/browser.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Opening a browser.
+ *
+ * Two options exist and no more: a profile to pin identity and storage to, and
+ * geography. Everything else that shapes an identity — seed, chrome-or-brave,
+ * fingerprint, timezone, languages, WebRTC address — is minted by us and pinned
+ * for the profile's life, because every one of them is a way to build an
+ * identity that cannot exist, and incoherence is what gets caught, not any
+ * single value.
+ *
+ * So a script that passes `timezoneId` is refused here, loudly, by name. That
+ * is not pedantry: Playwright applies `timezoneId`, `locale`, `userAgent` and
+ * `viewport` itself over per-page CDP *after* the context exists, and the
+ * worker refuses the corresponding `Emulation.*` calls because those values are
+ * hard-pinned to the exit. Failing in the caller's process with the conflict
+ * named beats failing halfway through a checkout with a CDP error.
+ */
+import type { ExitSpec, ExitTarget } from './_deps/core/index.js';
+import type { HandsFactory, RawPage } from './hands.js';
+import { OutcrawlPage } from './page.js';
+import type { Connection, RawInputMark, Transport } from './transport.js';
+/**
+ * A client-side identity override was refused. Names the option and what
+ * already pins it, so the fix is obvious rather than a support ticket.
+ */
+export declare class IdentityOverrideError extends Error {
+    readonly name = "IdentityOverrideError";
+    /** The option that was passed. */
+    readonly option: string;
+    /** What pins the value instead. */
+    readonly pinnedBy: string;
+    constructor(option: string, pinnedBy: string);
+}
+/** The complete set of options a caller may pass. */
+export interface BrowserOptions {
+    /** A profile id or label. Supplies pinned identity and logged-in state. */
+    profile?: string;
+    /**
+     * `outcrawl://<country>[/<region>[/<city>]]`, or the same as a structured
+     * target. Country, region and city. Nothing else — an exit chosen by ASN or
+     * postcode is a handful of IPs whose reputation we cannot manage.
+     */
+    proxy?: ExitSpec;
+    /**
+     * Session recording, ON BY DEFAULT. Pass `false` to decline it.
+     *
+     * Recording a `/connect` session is automatic and this is the only way out.
+     * Absent means RECORDED, and so does `true`; only an explicit `false`
+     * declines. It travels as `?record=false` on the allocation request and is
+     * carried to the machine inside the signed ticket, so no relay hop can
+     * strip it and turn a refusal back into a recording.
+     *
+     * Honoured before anything is armed. A declined session never has a
+     * recorder attached to its pages, so there is no stored replay, no
+     * `replayUrl` on the session, and `sessions.export` answers `404`. It is not
+     * a recording deleted afterwards — the bytes never existed. The session is
+     * billed exactly as a recorded one is.
+     *
+     * Afterwards the session says which it was: `SessionSummary.recordingDeclined`
+     * is `true`, which is what separates a refusal from a recorder that failed.
+     *
+     * NOT an identity override, which is why it is allowed where `userAgent` and
+     * `timezoneId` are refused: it decides what we keep about the session, not
+     * what the browser presents to a site.
+     */
+    record?: boolean;
+}
+/**
+ * Refuse client-side identity overrides before a socket is opened.
+ *
+ * Unknown options are refused too, not ignored. A silently dropped option is
+ * indistinguishable from one that worked, and the customer finds out when a
+ * session is blocked rather than when they wrote the line.
+ */
+export declare function assertNoIdentityOverride(options: object, where: string): void;
+/** Normalise the one geography option into the structured form. */
+export declare function resolveExit(proxy: ExitSpec): ExitTarget;
+export interface BrowserDeps {
+    transport: Transport;
+    hands: HandsFactory;
+}
+/**
+ * A live browser. One tenant-scoped CDP connection: it can only ever see its
+ * own context.
+ */
+export declare class Browser {
+    #private;
+    constructor(connection: Connection, deps: BrowserDeps);
+    get sessionId(): string;
+    /**
+     * Every raw-input call this session made, in order. The same marks are sent
+     * to the session record, so a run is flagged both here and in the replay.
+     */
+    get rawCalls(): readonly RawInputMark[];
+    pages(): readonly OutcrawlPage<RawPage>[];
+    /**
+     * `newPage()` takes no options, deliberately. Playwright's does, and the ones
+     * it takes are exactly the identity overrides this product cannot honour —
+     * so they are refused by name rather than quietly dropped.
+     */
+    newPage(options?: Record<string, never>): Promise<OutcrawlPage<RawPage>>;
+    close(): Promise<void>;
+}
+export declare function openBrowser(deps: BrowserDeps, options?: BrowserOptions, extra?: {
+    attachTo?: string;
+    signal?: AbortSignal;
+}): Promise<Browser>;

package/dist/types/client.d.ts

@@ -0,0 +1,128 @@
+/**
+ * `Outcrawl` — the client.
+ *
+ * Three rules, and everything else follows from them:
+ *
+ * 1. **The SDK is optional.** An unmodified Playwright script pointed at
+ *    `wss://outcrawl.ai/connect` keeps working forever. This is ergonomics,
+ *    never the only door.
+ * 2. **Good defaults, not options.** Identity, seed, proxy and fingerprint are
+ *    minted, not chosen. Anything that can be configured wrong eventually is.
+ * 3. **Human input is the default, not a flag.** `page.click()` goes through
+ *    the measured human model; `page.raw.click()` is the escape hatch, and it
+ *    is recorded.
+ *
+ * Every REST method here is addressed by a capability name from
+ * `@outcrawl/core`. Method and path come from the registry row, so this client
+ * cannot reach a route the registry does not declare, and a capability added to
+ * the registry has an obvious, single place to land.
+ */
+import type { CreditBalance, ScrapeResult, UsageQuery, UsageReport } from './_deps/core/index.js';
+import { type AgentApi } from './agent.js';
+import { type Browser, type BrowserOptions } from './browser.js';
+import { type HandsFactory } from './hands.js';
+import { Integrations } from './integrations.js';
+import { Monitors } from './monitors.js';
+import { Profiles } from './profiles.js';
+import { Rules } from './rules.js';
+import { Secrets } from './secrets.js';
+import { type Result } from './result.js';
+import { type CrawlHandle, type CrawlOptions, type ScrapeOptions, type SearchHits, type SearchOptions } from './scrape.js';
+import { Sessions } from './sessions.js';
+import { type Transport } from './transport.js';
+/**
+ * The two environment variables every Outcrawl surface reads.
+ *
+ * One spelling across the CLI, the MCP server, this SDK and the Python one: a
+ * customer moving between them must not have to rename their environment.
+ * `@outcrawl/cli`'s `config.ts` declares the same two names, and the MCP
+ * server read `OUTCRAWL_BASE_URL` for a while — a second spelling for one
+ * concept, which is how a key the CLI reads and the MCP does not comes about.
+ */
+export declare const API_KEY_ENV = "OUTCRAWL_API_KEY";
+export declare const API_URL_ENV = "OUTCRAWL_API_URL";
+export interface OutcrawlOptions {
+    /**
+     * Required unless a `transport` is supplied, or `OUTCRAWL_API_KEY` is in the
+     * environment.
+     */
+    apiKey?: string;
+    /** Defaults to `OUTCRAWL_API_URL`, and then to `https://outcrawl.ai`. */
+    baseUrl?: string;
+    /**
+     * Replaces the whole network layer. The reason the SDK is testable end to end
+     * with no network and no browser.
+     */
+    transport?: Transport;
+    /**
+     * The human-input driver. Defaults to the built-in one, which already uses
+     * `agenthands` for the scroll model; replace it to drive input some other way.
+     * Not a way to turn human input off — there is no such option, because opt-in
+     * stealth is stealth nobody uses.
+     *
+     * The factory is handed a {@link HandsBinding}, not a bare persona: a driver
+     * also needs the browser's own wheel entry point, which is a property of the
+     * session rather than of the call.
+     */
+    hands?: HandsFactory;
+    /** Injected fetch, for the default transport. */
+    fetch?: typeof globalThis.fetch;
+}
+export declare class Outcrawl {
+    #private;
+    readonly transport: Transport;
+    /**
+     * Callable, and the namespace for the four job routes. `oc.agent(...)`
+     * submits; `oc.agent.get(id)` and friends reach a run by id.
+     */
+    readonly agent: AgentApi;
+    readonly profiles: Profiles;
+    /** The secrets store. No method returns a value; see `./secrets.ts`. */
+    readonly secrets: Secrets;
+    /**
+     * The workspace rules, and which of them are ENFORCED rather than advice.
+     * Read `class` and `unenforceable`, not just `text`; see `./rules.ts`.
+     */
+    readonly rules: Rules;
+    /**
+     * What a run can reach OUTSIDE the browser, once a submit names it.
+     * Connecting is not granting; see `./integrations.ts`.
+     */
+    readonly integrations: Integrations;
+    readonly sessions: Sessions;
+    readonly monitors: Monitors;
+    constructor(options?: OutcrawlOptions);
+    scrape(url: string, options?: ScrapeOptions): Promise<Result<ScrapeResult>>;
+    crawl(url: string, options?: CrawlOptions): Promise<CrawlHandle>;
+    search(query: string, options?: SearchOptions): Promise<SearchHits>;
+    /**
+     * Open a browser. With no profile the identity is ephemeral; with one it is
+     * pinned, along with its storage, and the profile is leased for the duration
+     * — a second concurrent open throws `ProfileInUseError` rather than silently
+     * forking cookies.
+     */
+    browser(options?: BrowserOptions): Promise<Browser>;
+    /**
+     * The same numbers already attached to each call, aggregated. Nothing appears
+     * here that was not visible on the call that caused it.
+     */
+    usage(query: UsageQuery): Promise<Result<UsageReport>>;
+    /**
+     * The credit balance, summed by the database off the append-only ledger and
+     * the meter — `granted - spent`, with what lapsed reported separately so
+     * "where did my 4,000 credits go" has an answer other than a single number.
+     *
+     * **Every figure is a decimal STRING and must stay one.** They are credits.
+     * Parsing them to a `number` reintroduces binary floating point to money,
+     * which is the whole reason the wire carries text. Compare and add them with
+     * a decimal library, or pass them straight through to your UI.
+     *
+     * `exhausted` is REPORTED, NOT ENFORCED, and this is the trap worth naming:
+     * nothing refuses work when the granted pool empties. Admission is decided
+     * against the plan's monthly allowance, and a grant deliberately does not
+     * move that. So `exhausted: true` means "the pool you were granted is spent",
+     * never "the next call will be refused" — treat it as a signal to top up, not
+     * as a gate you can rely on.
+     */
+    credits(): Promise<Result<CreditBalance>>;
+}