@oya-ai/browser 1.0.97 → 1.0.101

package/dist/index.d.ts

@@ -1,14 +1,262 @@
-/** The one HTTP path. Everything else in this package is a wrapper over it. */
-declare class Http {
-    readonly baseUrl: string;
-    readonly apiKey: string;
-    private readonly timeoutMs;
-    private readonly fetchImpl;
-    constructor(baseUrl: string, apiKey: string, timeoutMs: number, fetchImpl: typeof globalThis.fetch);
-    request<T>(method: string, path: string, body?: unknown, timeoutMs?: number, headers?: Record<string, string>): Promise<T>;
+/**
+ * Types for browsers themselves: starting one, what a page looks like to the
+ * SDK, the results of CAPTCHA and MFA handling, and the fleet listing.
+ */
+/** Where a browser comes from. Configuration, not something a caller must know. */
+type Provider = 'oya-cloud' | 'oya-selfhosted' | 'browseruse' | 'browserbase' | 'steel' | 'anchor' | 'cdp';
+/** How `oya.browser.start()` should start a browser. Every field is optional. */
+interface StartOptions {
+    /** Reuse this value when retrying the same logical creation. */
+    idempotencyKey?: string;
+    /** Wait for capacity for up to five minutes; zero rejects immediately. */
+    queueMs?: number;
+    /** Spend ceiling for this browser, in US dollars. */
+    budgetUsd?: number;
+    /** Run under the project's governance: policies, budgets and recordings. */
+    governed?: boolean;
+    /** Egress and recording rules for a governed browser. */
+    policy?: {
+        /** Hosts the browser may reach; everything else is blocked. */
+        allowedHosts?: string[];
+        /** Hosts where a person, not the agent, must act. */
+        humanHosts?: string[];
+        /** Where the browser must run. */
+        region?: string;
+        /** Blur typed values out of the session recording. */
+        redactRecording?: boolean;
+    };
+    /** Place in the queue when capacity is short. */
+    priority?: 'low' | 'normal' | 'high';
+    /** Saved login profile. Defaults to the desktop's default profile. */
+    profile?: string;
+    /**
+     * Which identity to run as. A persona is one device: fingerprint, cookie jar
+     * and proxy bound together and stable for its life.
+     *   'default' — this key's own persona (the default)
+     *   'auto'    — the least recently used persona under its concurrency cap
+     *   <id>      — a specific persona
+     */
+    persona?: 'default' | 'auto' | (string & {});
+    /** Solve CAPTCHAs as they appear rather than waiting to be asked. */
+    captcha?: 'auto' | 'off';
+    /** Override the key's configured provider for this browser only. */
+    provider?: Provider;
+    /** Required only for the 'cdp' provider. */
+    wsUrl?: string;
+    /** A label for the fleet listing. */
+    name?: string;
+    /** How long to wait for a cloud browser to dial in. Default 120s. */
+    readyTimeoutMs?: number;
+}
+/** What the server answers when a browser starts. */
+interface StartResult {
+    /** The browser's id, for every later call. */
+    id: string;
+    /** Which provider runs it. */
+    provider: string;
+    /** Which persona it runs as. */
+    persona: string;
+    /** 'starting' while a cloud browser has yet to dial in. */
+    status: 'ready' | 'starting';
+    /** Point Playwright, Puppeteer or browser-use at this. */
+    cdpUrl?: string;
+    /** Anything the server wants the caller to know about this start. */
+    note?: string;
+}
+/** One element on the page, numbered by `analyze()`. */
+interface Element {
+    /** The number to pass to `click()` and `type()`. Valid until the page changes. */
+    id: number;
+    /** What kind of control it is: link, button, input and so on. */
+    type: string;
+    /** Visible label, capped at 80 characters by the analyzer. */
+    text?: string;
+    /** Where a link goes. */
+    href?: string;
+    /** The current value of a field. */
+    value?: string;
+    /** Whether a checkbox or radio is ticked. */
+    checked?: boolean;
+    /** Whether it refuses input. */
+    disabled?: boolean;
+    /** Whether it is on screen. */
+    visible: boolean;
+    /** The HTML tag name. */
+    tag?: string;
+    /** The element's DOM `id`. Usually the most stable handle a site offers. */
+    domId?: string;
+    /** Its `aria-label`. */
+    ariaLabel?: string;
+    /** `data-testid`, when the site ships one. */
+    testId?: string;
+    /** Its `name` attribute. */
+    name?: string;
+    /** A field's placeholder text. */
+    placeholder?: string;
+    /** Action of the enclosing form. */
+    formName?: string;
+}
+/** How `analyze()` writes the page: markdown (the default) or toon (toonformat.dev). */
+type PageFormat = 'markdown' | 'toon' | 'jsonl';
+/** What `analyze()` accepts. */
+interface AnalyzeOptions {
+    /** How the page is written: markdown (the default) or toon. */
+    format?: PageFormat;
+}
+/** One block of a page, in reading order: a heading, paragraph, list item, table row, image or element. */
+interface Block {
+    /** The element's id, for interactive elements; act on it with click and type. */
+    id?: number;
+    /** The part of the page it is in: nav, main, form/…, dialog, or empty. */
+    region: string;
+    /** What it is: h1-h6, text, item, row, header, quote, code, image, or an element kind (link, button, input:email…). */
+    kind: string;
+    /** Its text, or an element's name. */
+    text?: string;
+    /** Where a link goes, or what a field holds now. */
+    target?: string;
+    /** An element's state: checked, disabled, required, off-screen, hint… */
+    state?: string;
+}
+/** The page as `analyze()` sees it. */
+interface Analysis {
+    /** The format `page` is written in. */
+    format?: PageFormat;
+    /** The page, written in `format`. */
+    page?: string;
+    /** The page as markdown; present when the format is markdown (the default). */
+    markdown?: string;
+    /** The page's facts: url, title, scroll, and when they apply panelScroll, modal, covered, truncated. */
+    facts?: Record<string, string | number>;
+    /** The page as data: every block in reading order, whatever the format. */
+    blocks?: Block[];
+    /** Every numbered element, visible or not. */
+    elements: Element[];
+    /** The window size, in CSS pixels. */
+    viewport?: {
+        /** Width in CSS pixels. */
+        width: number;
+        /** Height in CSS pixels. */
+        height: number;
+    };
+    /** How far the page is scrolled. */
+    scroll?: {
+        /** Horizontal offset in CSS pixels. */
+        x: number;
+        /** Vertical offset in CSS pixels. */
+        y: number;
+    };
+    /** True when the page was too long to send in full. */
+    truncated?: boolean;
+}
+/** What `solveCaptcha()` found and did. */
+interface CaptchaResult {
+    /** Whether a CAPTCHA was on the page. */
+    present: boolean;
+    /** Whether it was cleared. */
+    solved: boolean;
+    /** 'provider' when the vendor solved it, 'solver' when we did, 'none' otherwise. */
+    method: 'provider' | 'solver' | 'none';
+    /** Which kind of CAPTCHA it was. */
+    type?: string;
+    /** Invisible reCAPTCHA v3 scores the visit passively; there is nothing on screen to clear. */
+    invisible?: boolean;
+    /** The site key the solver was given. */
+    sitekey?: string | null;
+    /** Why it was not solved. */
+    error?: string;
+}
+/** What `completeMfa()` found and did. */
+interface MfaResult {
+    /** Whether an MFA prompt was on the page. */
+    present: boolean;
+    /** Whether it was answered and accepted. */
+    completed: boolean;
+    /** Which factor answered it, or 'handoff' when a person must. */
+    method?: 'totp' | 'email' | 'sms' | 'handoff' | 'none';
+    /** Whether the code was typed in. */
+    filled?: boolean;
+    /** Whether the form was submitted. */
+    submitted?: boolean;
+    /** Open this to finish by hand when nothing automated can. */
+    liveViewUrl?: string | null;
+    /** Why it could not be completed. */
+    error?: string;
+}
+/** How a browser is doing, judged from its recent commands and heartbeats. */
+type Health = 'ok' | 'stale' | 'errors' | 'dead';
+/** One thing a browser did. */
+interface Activity {
+    /** When, as an ISO timestamp. */
+    ts: string;
+    /** The command's name. */
+    action: string;
+    /** A one-line account of it. */
+    summary: string;
+    /** Whether it succeeded. */
+    ok: boolean;
+    /** How long it took. */
+    ms: number;
+    /** Why it failed. */
+    error?: string;
+}
+/** The outcome of stopping one browser. */
+interface StopResult {
+    /** The browser. */
+    id: string;
+    /** Whether it stopped. */
+    ok: boolean;
+    /** Which provider ran it. */
+    provider?: string | null;
+    /** For a cloud browser, whether its sandbox was destroyed (and billing ended). */
+    sandboxRemoved?: boolean | null;
+    /** Why it did not stop. */
+    error?: string;
+}
+/** One browser in the fleet listing. */
+interface BrowserInfo {
+    /** The browser's id. */
+    id: string;
+    /** Its label. */
+    name: string;
+    /** An Oya Browser on the control socket, or a third-party browser over CDP. */
+    clientType: 'oya' | 'cdp';
+    /** Which provider runs it. */
+    provider: string | null;
+    /** The persona id it runs as. */
+    persona: string | null;
+    /** That persona's name. */
+    personaName: string | null;
+    /** How it is doing. */
+    health: Health;
+    /** When it connected. */
+    connectedAt: string;
+    /** When it was last heard from. */
+    lastSeen: string;
+    /** The page it is on. */
+    currentUrl: string;
+    /** Commands run so far. */
+    commands: number;
+    /** Commands that failed. */
+    errors: number;
+    /** Commands in flight. */
+    pending: number;
+    /** When it last ran a command. */
+    lastCommandAt: string | null;
+    /** The last failure's message. */
+    lastError: string | null;
+}
+/** A browser plus what it has been doing, from `browser.status()`. */
+interface BrowserDetail extends BrowserInfo {
+    /** Its most recent commands, newest first. */
+    activity: Activity[];
 }
 
-/** Everything the API returns or accepts, in one place. */
+/**
+ * Types for a key's settings: the LLM behind `ask()`, the browser provider and
+ * the CAPTCHA solver, as `config.set()` accepts them and `config.get()` returns them.
+ */
+
 /** Which model drives `ask()` and the chat API. */
 type LlmProvider = 'openai' | 'anthropic'
 /** Gemini via AI Studio. */
@@ -24,6 +272,7 @@ type CaptchaSolver = 'capsolver' | '2captcha' | '';
  * `null` clears a field and falls back to the deployment default.
  */
 interface ConfigUpdate {
+    /** Which LLM vendor `ask()` and the chat API call. */
     llm_provider?: LlmProvider | null;
     /** The credential for whichever `llm_provider` is set — the field name is shared. */
     openai_api_key?: string | null;
@@ -31,111 +280,119 @@ interface ConfigUpdate {
     openai_base_url?: string | null;
     /** Overrides the provider's default model. */
     chat_model?: string | null;
+    /** Where this key's browsers run unless `start()` names a provider. */
     browser_provider?: Provider | null;
+    /** Anchor's API key, for the 'anchor' provider. */
     anchor_api_key?: string | null;
+    /** Browserbase's API key, for the 'browserbase' provider. */
     browserbase_api_key?: string | null;
+    /** The Browserbase project browsers are created in. */
     browserbase_project_id?: string | null;
+    /** Steel's API key, for the 'steel' provider. */
     steel_api_key?: string | null;
+    /** Browser Use Cloud's API key, for the 'browseruse' provider. */
     browseruse_api_key?: string | null;
+    /** The DevTools WebSocket URL of your own Chrome, for the 'cdp' provider. */
     cdp_ws_url?: string | null;
+    /** Which CAPTCHA solving service to call. */
     captcha_solver?: CaptchaSolver | null;
+    /** The solving service's API key. */
     captcha_api_key?: string | null;
+    /** Set once onboarding has been completed, so the console stops offering it. */
     onboarded?: string | null;
 }
 /** What `config.get()` returns. Secrets read back masked, never in full. */
 interface Config extends Omit<ConfigUpdate, 'llm_provider' | 'browser_provider' | 'captcha_solver'> {
+    /** The configured LLM vendor, or empty for the deployment default. */
     llm_provider?: LlmProvider | '';
+    /** The configured browser provider, or empty for the deployment default. */
     browser_provider?: Provider | '';
+    /** The configured CAPTCHA solver; empty when solving is off. */
     captcha_solver?: CaptchaSolver;
     /** What this key would actually use right now, deployment defaults included. */
     effective: {
+        /** The LLM endpoint in use. */
         baseUrl: string;
+        /** The model in use. */
         model: string;
+        /** Whether any LLM credential is available. */
         hasLlmKey: boolean;
     };
     /** True when the LLM key in play belongs to the deployment, not this key. */
     inherited: boolean;
+    /** Whether this key has its own LLM credential stored. */
     has_openai_key: boolean;
+    /** Every browser provider, what it needs configured, and whether it is. */
     providers: Array<{
+        /** The provider. */
         id: Provider;
+        /** Its display name. */
         label: string;
+        /** The config fields it requires. */
         needs: string[];
+        /** Whether those fields are set. */
         configured: boolean;
     }>;
 }
-/** Where a browser comes from. Configuration, not something a caller must know. */
-type Provider = 'oya-cloud' | 'oya-selfhosted' | 'browseruse' | 'browserbase' | 'steel' | 'anchor' | 'cdp';
-interface StartOptions {
-    /** Reuse this value when retrying the same logical creation. */
-    idempotencyKey?: string;
-    /** Wait for capacity for up to five minutes; zero rejects immediately. */
-    queueMs?: number;
-    budgetUsd?: number;
-    governed?: boolean;
-    policy?: {
-        allowedHosts?: string[];
-        humanHosts?: string[];
-        region?: string;
-        redactRecording?: boolean;
-    };
-    priority?: 'low' | 'normal' | 'high';
-    /** Saved login profile. Defaults to the desktop's default profile. */
-    profile?: string;
-    /**
-     * Which identity to run as. A persona is one device: fingerprint, cookie jar
-     * and proxy bound together and stable for its life.
-     *   'default' — this key's own persona (the default)
-     *   'auto'    — the least recently used persona under its concurrency cap
-     *   <id>      — a specific persona
-     */
-    persona?: 'default' | 'auto' | (string & {});
-    /** Solve CAPTCHAs as they appear rather than waiting to be asked. */
-    captcha?: 'auto' | 'off';
-    /** Override the key's configured provider for this browser only. */
-    provider?: Provider;
-    /** Required only for the 'cdp' provider. */
-    wsUrl?: string;
-    name?: string;
-    /** How long to wait for a cloud browser to dial in. Default 120s. */
-    readyTimeoutMs?: number;
-}
-interface StartResult {
-    id: string;
-    provider: string;
-    persona: string;
-    status: 'ready' | 'starting';
-    /** Point Playwright, Puppeteer or browser-use at this. */
-    cdpUrl?: string;
-    note?: string;
+
+/**
+ * OyaError: the one error type the SDK throws for a failed call, carrying the
+ * HTTP status and the server's answer so a caller can branch on either.
+ */
+/** A failed API call or browser command. */
+declare class OyaError extends Error {
+    /** The HTTP status, or the SDK's own status for errors it raises itself. */
+    readonly status: number;
+    /** The server's response body, parsed when it was JSON. */
+    readonly body: unknown;
+    /** Records the message, status and body. */
+    constructor(message: string, status: number, body: unknown);
 }
+
+/**
+ * Types for agent work: task values and files, playbooks and their replays,
+ * and background runs with their attention requests.
+ */
+
+/** A saved flow, replayable without an LLM. */
 interface Playbook {
+    /** The name it is played by. */
     name: string;
     /** Inputs `play()` accepts; any left out reuse the recorded value. */
     variables: string[];
     /** What each variable was recorded with. A secret has none — it never left the page. */
     defaults: Record<string, string>;
+    /** How many steps it replays. */
     steps: number;
     /** The same flow as a Playwright module: `export default async function run(page, vars)`. */
     code: string;
 }
+/** What a `play()` did. */
 interface PlayResult {
     /** Steps replayed before finishing or handing over to the agent. */
     steps: number;
+    /** Steps in the playbook. */
     total: number;
     /** A step no longer fit the page and the agent finished the task. */
     fellBack: boolean;
     /** The agent's fix was saved as `draft`; promote it with `oya.playbooks.promote(name)`. */
     healed?: boolean;
+    /** The draft's name, when one was saved. */
     draft?: string;
     /** The agent's summary, when it fell back. */
     text?: string;
 }
+/** A playbook in the listing, with its history and any pending fix. */
 interface PlaybookSummary extends Playbook {
+    /** When it was saved. */
     createdAt: string | null;
+    /** When a draft last replaced it. */
     promotedAt: string | null;
     /** A healed replay's fix, waiting for `promote()` or `remove('<name>:draft')`. */
     draft: (Playbook & {
+        /** When the replay was healed. */
         healedAt: string;
+        /** The step the replay broke at. */
         healedFrom: number;
     }) | null;
 }
@@ -161,29 +418,46 @@ interface FileValue {
  * upload tool rather than typing it.
  */
 type RunData = Record<string, string | number | FileValue>;
+/** A run is waiting on a person. */
 interface AttentionRequest {
+    /** Identifies this request; a new one means a new problem. */
     id: string;
     /** captcha / login / mfa: finish it in the live view. agent: the agent's question. heal_failed: replay and the agent both gave up. */
     reason: 'captcha' | 'login' | 'mfa' | 'agent' | 'heal_failed';
+    /** What is needed, in words. */
     message: string;
+    /** Where to finish it by hand. */
     liveViewUrl?: string;
+    /** When it was raised, in epoch milliseconds. */
     at: number;
 }
+/** What a finished run produced: a replay's result, an agent's answer, or both. */
 type RunResult = Partial<PlayResult> & {
+    /** The agent's answer. */
     text?: string;
 };
+/** A background run's state. */
 interface RunInfo {
+    /** The run's id. */
     id: string;
+    /** The browser it runs on. */
     browserId: string;
+    /** Where it is. */
     status: 'running' | 'needs_attention' | 'succeeded' | 'failed';
+    /** When it started, in epoch milliseconds. */
     createdAt: number;
+    /** When it ended. */
     endedAt?: number;
+    /** The open request for a person, if any. */
     attention: AttentionRequest | null;
+    /** What it produced, once it succeeded. */
     result?: RunResult;
+    /** Why it failed. */
     error?: string;
     /** HTTP-style status of a failure: 429 when a quota stopped the run. */
     errorStatus?: number;
 }
+/** The inputs and callbacks for `browser.submit()`. */
 interface SubmitOptions {
     /** Task values the agent can read; for a playbook, its variables (secret ones included). */
     data?: RunData;
@@ -191,7 +465,9 @@ interface SubmitOptions {
     secrets?: RunData;
     /** Playbooks only: let the agent finish a broken replay and save its fix as a draft. Default true. */
     autoHeal?: boolean;
+    /** Fires once with the result when the run succeeds. */
     onSuccess?: (result: RunResult) => unknown;
+    /** Fires once when the run fails, or when it can no longer be polled. */
     onFailure?: (error: OyaError) => unknown;
     /** Call `respond()` once it is handled: `'done'` after finishing by hand, or your answer to the agent. */
     onHumanAttention?: (request: AttentionRequest & {
@@ -202,165 +478,151 @@ interface SubmitOptions {
     /** How often to check on the run. Default 2000. */
     pollMs?: number;
 }
-interface Element {
-    id: number;
-    type: string;
-    /** Visible label, capped at 80 characters by the analyzer. */
-    text?: string;
-    href?: string;
-    value?: string;
-    checked?: boolean;
-    disabled?: boolean;
-    visible: boolean;
-    tag?: string;
-    /** The element's DOM `id`. Usually the most stable handle a site offers. */
-    domId?: string;
-    ariaLabel?: string;
-    /** `data-testid`, when the site ships one. */
-    testId?: string;
-    name?: string;
-    placeholder?: string;
-    /** Action of the enclosing form. */
-    formName?: string;
-}
-interface Analysis {
-    /** The page as markdown. */
-    markdown: string;
-    elements: Element[];
-    viewport?: {
-        width: number;
-        height: number;
-    };
-    scroll?: {
-        x: number;
-        y: number;
-    };
-    truncated?: boolean;
-}
-interface CaptchaResult {
-    present: boolean;
-    solved: boolean;
-    /** 'provider' when the vendor solved it, 'solver' when we did, 'none' otherwise. */
-    method: 'provider' | 'solver' | 'none';
-    type?: string;
-    /** Invisible reCAPTCHA v3 scores the visit passively; there is nothing on screen to clear. */
-    invisible?: boolean;
-    sitekey?: string | null;
-    error?: string;
-}
-interface MfaResult {
-    present: boolean;
-    completed: boolean;
-    method?: 'totp' | 'email' | 'sms' | 'handoff' | 'none';
-    filled?: boolean;
-    submitted?: boolean;
-    /** Open this to finish by hand when nothing automated can. */
-    liveViewUrl?: string | null;
-    error?: string;
-}
+
+/**
+ * Types for identities: a persona's device and fingerprint, the proxies it
+ * exits through, and the second factors and site logins stored for it.
+ */
+/** The device a persona presents. Fixed for its life. */
 interface Fingerprint {
+    /** `navigator.platform`. */
     platform: string;
+    /** IANA timezone. */
     timezone: string;
+    /** BCP 47 locale. */
     locale: string;
+    /** Screen size, as `WIDTHxHEIGHT`. */
     screen: string;
+    /** The GPU the WebGL renderer reports. */
     webgl: string;
+    /** Logical CPU cores reported. */
     hardwareConcurrency: number;
+    /** Device memory reported, in GB. */
     deviceMemory: number;
+    /** Seed for the persona's stable canvas noise. */
     canvasSeed: number;
 }
 /** Device choices made at creation. Fixed for the persona's life. */
 interface PersonaPrefs {
+    /** Which operating system to present. */
     platform?: 'Win32' | 'MacIntel' | 'Linux x86_64';
+    /** IANA timezone; must be one the platform can coherently claim. */
     timezone?: string;
+    /** BCP 47 locale; must be one the platform can coherently claim. */
     locale?: string;
 }
 /** A proxy exit. Credentials go in on create and never come back out. */
 interface ProxyInfo {
+    /** The proxy's id. */
     id: string;
+    /** Its display name. */
     label: string;
+    /** Residential IPs look like homes; datacenter ones are cheaper and easier to flag. */
     kind: 'residential' | 'datacenter';
     /** Two-letter country, optionally a region: "US", "US-CA". */
     geo: string | null;
     /** Provided by the host rather than this key. Cannot be removed. */
     shared: boolean;
+    /** Whether its last check passed. */
     healthy: boolean;
     /** Healthy and not cooling down after a failure. */
     available: boolean;
     /** Where traffic actually leaves, as of the last check. */
     exitIp: string | null;
+    /** When it was last checked. */
     lastCheckedAt: string | null;
     /** Personas on it now, out of `maxPersonas`. */
     assigned: number;
+    /** How many personas may share it. */
     maxPersonas: number;
+    /** How long until a failed proxy is tried again. */
     cooldownMsRemaining: number;
 }
+/** A proxy to add. */
 interface ProxyCreate {
     /** http(s)://user:pass@host:port from your vendor. Chromium cannot use SOCKS5 with a password. */
     url: string;
+    /** A display name. */
     label?: string;
+    /** Two-letter country, optionally a region, used to match personas' geo hints. */
     geo?: string;
+    /** Residential or datacenter. */
     kind?: 'residential' | 'datacenter';
     /** Personas that may share it. Keep 1 for a sticky-session URL so each keeps its own IP. */
     maxPersonas?: number;
 }
+/** A persona: one device, its cookie jar and its proxy. */
 interface PersonaInfo {
+    /** The persona's id. */
     id: string;
+    /** Its display name. */
     name: string;
+    /** Whether it is this key's own default persona. */
     isDefault: boolean;
+    /** Browsers running as it now. */
     activeBrowsers: number;
+    /** How many may run as it at once; null for no cap. */
     maxConcurrent: number | null;
+    /** Where its proxy should be, before one is assigned. */
     proxy: {
+        /** Two-letter country, optionally a region. */
         geo: string | null;
     } | null;
     /** The proxy it is actually on, once assigned or pinned. */
     exit: {
+        /** The proxy's id. */
         id: string;
+        /** Its display name. */
         label: string;
+        /** Its country and region. */
         geo: string | null;
+        /** Whether its last check passed. */
         healthy: boolean;
     } | null;
+    /** The device choices it was created with. */
     prefs: PersonaPrefs | null;
+    /** The device it presents. */
     fingerprint: Fingerprint;
+    /** Its persona-wide second factor. */
     mfa: {
+        /** Whether a factor is stored. */
         configured: boolean;
+        /** Which kind of factor. */
         type?: string;
+        /** The site it is filed against, if any. */
         domain?: string;
     };
     /** Per-site factors and stored logins. Usernames and types only, never secrets. */
     sites: {
+        /** Second factors filed against one site. */
         mfa: {
+            /** The site. */
             domain: string;
+            /** Which kind of factor. */
             type: string;
         }[];
+        /** Stored site logins. */
         credentials: {
+            /** The site. */
             domain: string;
+            /** The account name. */
             username: string;
         }[];
     };
+    /** What its cookie jar holds. */
     login: {
+        /** Cookies in the jar. */
         cookies: number;
+        /** Sites it holds a session for. */
         sites: string[];
+        /** When the jar last changed. */
         updatedAt: string | null;
     };
+    /** When it was created. */
     createdAt: string;
+    /** When a browser last ran as it. */
     lastUsedAt: string | null;
 }
-type Health = 'ok' | 'stale' | 'errors' | 'dead';
-interface Activity {
-    ts: string;
-    action: string;
-    summary: string;
-    ok: boolean;
-    ms: number;
-    error?: string;
-}
-interface StopResult {
-    id: string;
-    ok: boolean;
-    provider?: string | null;
-    sandboxRemoved?: boolean | null;
-    error?: string;
-}
 /**
  * A second factor. `domain` files it against one site, because a persona driving
  * several portals meets several kinds of factor; without it the record is the
@@ -375,122 +637,452 @@ interface StopResult {
  * `pattern` is only the fallback for when no LLM key is set or the call fails.
  */
 type MfaConfig = {
+    /** The site this factor answers for; without it, the persona-wide default. */
     domain?: string;
 } & ({
+    /** An authenticator app's time-based codes. */
     type: 'totp';
+    /** The base32 seed. */
     secret: string;
 } | {
+    /** Codes delivered to an endpoint you host. */
     type: 'email' | 'sms';
+    /** The endpoint polled for the latest message. */
     url: string;
+    /** Headers sent with each poll. */
     headers?: Record<string, string>;
+    /** Fallback regex for the code, used when no LLM is available. */
     pattern?: string;
+    /** How long to wait for a code. */
     timeoutMs?: number;
 } | {
+    /** Codes read from a Gmail or Microsoft 365 mailbox. */
     type: 'gmail' | 'graph';
+    /** The mailbox's OAuth refresh token. */
     refreshToken: string;
+    /** The OAuth client the token was issued to. */
     clientId: string;
+    /** That client's secret, when it has one. */
     clientSecret?: string;
+    /** The Microsoft tenant, for `graph`. */
     tenant?: string;
+    /** A mailbox search narrowing which messages are read. */
     query?: string;
+    /** Fallback regex for the code, used when no LLM is available. */
     pattern?: string;
+    /** How long to wait for a code. */
     timeoutMs?: number;
 });
 /** A site login. The password is write-only: no API ever reads it back. */
 interface SiteCredentials {
+    /** The site it signs in to. */
     domain: string;
+    /** The account name. */
     username: string;
+    /** The password; stored sealed and never returned. */
     password: string;
 }
-interface BrowserInfo {
-    id: string;
-    name: string;
-    clientType: 'oya' | 'cdp';
-    provider: string | null;
-    persona: string | null;
-    personaName: string | null;
-    health: Health;
-    connectedAt: string;
-    lastSeen: string;
-    currentUrl: string;
-    commands: number;
-    errors: number;
-    pending: number;
-    lastCommandAt: string | null;
-    lastError: string | null;
-}
-interface BrowserDetail extends BrowserInfo {
-    activity: Activity[];
-}
-interface OyaOptions {
-    /** Defaults to OYA_API_KEY. */
-    apiKey?: string;
-    /** Defaults to OYA_BASE_URL, then https://browser.getoya.ai. */
-    baseUrl?: string;
-    /** Per-request timeout. Navigation gets its own, longer budget. */
-    timeoutMs?: number;
-    fetch?: typeof globalThis.fetch;
-}
-declare class OyaError extends Error {
-    readonly status: number;
-    readonly body: unknown;
-    constructor(message: string, status: number, body: unknown);
-}
+
+/**
+ * Types for the durable control plane: sessions and their lifecycle, human
+ * takeover, project settings, lifecycle events and service credentials.
+ */
+/** What a member or credential may do: read, operate browsers, or also administer the project. */
 type ControlRole = 'viewer' | 'operator' | 'administrator';
 /** What a human holding the control lease may send. Mirrors the server's allowlist. */
 type HumanInputAction = 'click' | 'type' | 'press_key' | 'scroll' | 'click_coordinates' | 'double_click' | 'drag' | 'mouse_move' | 'scroll_at' | 'type_text' | 'keyboard_type' | 'navigate' | 'back' | 'forward' | 'reload' | 'screenshot' | 'analyze' | 'read_page';
+/** A browser session as the control plane records it, including ones no longer connected. */
 interface ControlSession {
+    /** The session's id, which is also the browser's. */
     id: string;
+    /** The project it belongs to. */
     project: string;
+    /** Which provider runs it. */
     provider: string;
+    /** The persona it runs as. */
     persona: string | null;
+    /** Where it is in its lifecycle. */
     state: 'queued' | 'provisioning' | 'ready' | 'disconnected' | 'stopping' | 'cleanup_pending' | 'stopped' | 'failed' | 'unknown_outcome';
+    /** Whether the control plane provisioned it (and so must clean it up). */
     managed: boolean;
+    /** When it was created, in epoch milliseconds. */
     createdAt: number;
+    /** When its state last changed. */
     updatedAt: number;
+    /** Estimated spend so far, in US dollars. */
     costUsd: number;
+    /** Who is driving it. */
     control: {
+        /** The agent, a person, or nobody while paused. */
         mode: 'agent' | 'human' | 'paused';
+        /** When a human lease runs out. */
         expiresAt?: number;
     };
+    /** Why cleanup has not finished. */
     cleanupError?: string;
 }
+/** A project's limits, retention and rate cards. */
 interface ProjectSettings {
+    /** Days recordings are kept. */
     recordingDays: number;
+    /** Days audit events are kept. */
     auditDays: number;
+    /** Spend ceiling in US dollars; null for none. */
     budgetUsd: number | null;
+    /** Browsers that may run at once; null for no cap. */
     maxConcurrent: number | null;
+    /** Price per unit, by what is metered. */
     rates: Record<string, number>;
+    /** The default policy for governed browsers. */
     policy: Record<string, unknown>;
 }
+/** One durable lifecycle event. */
 interface ControlEvent {
+    /** Increasing id, used as the read cursor. */
     id: number;
+    /** The project it belongs to. */
     project: string;
+    /** What happened. */
     type: string;
+    /** The session it concerns, if any. */
     sessionId: string | null;
+    /** When, in epoch milliseconds. */
     at: number;
+    /** Event-specific fields. */
     detail: Record<string, unknown>;
 }
+/** A service credential. Its token is shown once, at creation. */
 interface ControlCredential {
+    /** The credential's id, for revoking it. */
     id: string;
+    /** What it is for. */
     label: string;
+    /** What it may do. */
     role: ControlRole;
+    /** When it stops working; null for never. */
     expiresAt: number | null;
+    /** When it was revoked, if it was. */
     revokedAt: number | null;
 }
+/** The project at a glance: settings, sessions, recent events. */
 interface ControlOverview {
     /** costUsd: estimated lifetime spend, metered from rate cards. */
     project: {
+        /** The project's id. */
         id: string;
+        /** Its name. */
         name: string;
+        /** Its limits and retention. */
         settings: ProjectSettings;
+        /** Estimated lifetime spend, in US dollars. */
         costUsd?: number;
     };
+    /** Every session the control plane knows about. */
     sessions: ControlSession[];
+    /** Recent lifecycle events. */
     events: ControlEvent[];
+    /** True while the server is draining for a restart. */
     draining: boolean;
+    /** Service credentials, for administrators. */
     credentials?: ControlCredential[];
 }
 
+/**
+ * The options the `Oya` client is constructed with.
+ */
+/** How to reach the control plane, and as whom. */
+interface OyaOptions {
+    /** Defaults to OYA_API_KEY. */
+    apiKey?: string;
+    /** Defaults to OYA_BASE_URL, then https://browser.getoya.ai. */
+    baseUrl?: string;
+    /** Per-request timeout. Navigation gets its own, longer budget. */
+    timeoutMs?: number;
+    /** A fetch to use instead of the global one, for tests, proxies or old runtimes. */
+    fetch?: typeof globalThis.fetch;
+}
+
+/** The one HTTP path. Everything else in this package is a wrapper over it. */
+declare class Http {
+    readonly baseUrl: string;
+    readonly apiKey: string;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    /** Stores where to call, with which key, how long to wait and which fetch to use. */
+    constructor(baseUrl: string, apiKey: string, timeoutMs: number, fetchImpl: typeof globalThis.fetch);
+    /** Sends one request and returns the parsed answer, or throws an OyaError when it failed. */
+    request<T>(method: string, path: string, body?: unknown, timeoutMs?: number, headers?: Record<string, string>): Promise<T>;
+}
+
+/**
+ * The shapes the client's namespaces (`oya.browser`, `oya.control`,
+ * `oya.personas` …) take and return that are not part of the exported types,
+ * named so each field can say what it is.
+ */
+
+/** What stopping several browsers did. */
+interface StopManyResult {
+    /** How many stopped. */
+    stopped: number;
+    /** Each browser's outcome. */
+    results: StopResult[];
+}
+/** A plain acknowledgement. */
+interface Ack {
+    /** Whether it was done. */
+    ok: boolean;
+}
+/** A single-use live-stream ticket. */
+interface Ticket {
+    /** The ticket. */
+    ticket: string;
+    /** Seconds until it expires. */
+    expiresIn: number;
+}
+/** A page of lifecycle events. */
+interface EventPage {
+    /** Events after the cursor asked for. */
+    events: ControlEvent[];
+    /** Pass this as `after` to read on. */
+    cursor: number;
+}
+/** A service credential to mint. */
+interface CredentialRequest {
+    /** What it may do. */
+    role: ControlRole;
+    /** What it is for. */
+    label?: string;
+    /** When it stops working, in epoch milliseconds. */
+    expiresAt?: number;
+}
+/** A new service credential, with its token: shown this once. */
+interface NewCredential extends ControlCredential {
+    /** The secret to authenticate with. */
+    token: string;
+}
+/** One project member. */
+interface Member {
+    /** The member's user id. */
+    userId: string;
+    /** What they may do. */
+    role: ControlRole;
+}
+/** The project's owner and members. */
+interface MemberList {
+    /** The owner's user id. */
+    owner: string | null;
+    /** Everyone else. */
+    members: Member[];
+}
+/** An invitation code. */
+interface Invite {
+    /** The code to hand to the invitee. */
+    code: string;
+    /** Seconds until it expires. */
+    expiresIn: number;
+}
+/** A registered webhook. */
+interface Webhook {
+    /** Its id, for removing it. */
+    id: string;
+    /** The key its deliveries are signed with. */
+    secret: string;
+}
+/** One proxy's check. */
+interface ProxyCheck {
+    /** The proxy. */
+    id: string;
+    /** Whether it answered. */
+    ok: boolean;
+    /** Where its traffic actually leaves. */
+    exitIp?: string | null;
+    /** Why it failed. */
+    error?: string;
+}
+/** Where a persona's proxy should be. */
+interface GeoHint {
+    /** Two-letter country, optionally a region. */
+    geo?: string;
+}
+/** A persona to create. */
+interface PersonaCreate {
+    /** Its display name. */
+    name?: string;
+    /** Device choices, fixed for its life. */
+    prefs?: PersonaPrefs;
+    /** Where its proxy should be. */
+    proxy?: GeoHint;
+    /** How many browsers may run as it at once; null for no cap. */
+    maxConcurrent?: number | null;
+}
+/** What may change on a persona. Never the device. */
+interface PersonaUpdate {
+    /** Its display name. */
+    name?: string;
+    /** How many browsers may run as it at once; null for no cap. */
+    maxConcurrent?: number | null;
+    /** Where its proxy should be; null clears the hint. */
+    proxy?: GeoHint | null;
+}
+/** Options for a clone. */
+interface CloneOptions {
+    /** The new persona's name. */
+    name?: string;
+}
+/** What a persona may claim, per platform. */
+interface PersonaOptions {
+    /** The platforms on offer. */
+    platforms: string[];
+    /** Timezones each platform may coherently claim. */
+    timezones: Record<string, string[]>;
+    /** Locales each platform may coherently claim. */
+    locales: Record<string, string[]>;
+}
+/** The proxy a persona is pinned to. */
+interface PinnedProxy {
+    /** The proxy's id. */
+    id: string;
+    /** Its display name. */
+    label: string;
+}
+/** The outcome of pinning a proxy. */
+interface ProxyPin {
+    /** Whether it was saved. */
+    ok: boolean;
+    /** The proxy now pinned, or null when assignment is left to connect time. */
+    proxy: PinnedProxy | null;
+}
+/** A stored second factor, as confirmed. */
+interface MfaSaved {
+    /** Whether it is stored. */
+    configured: boolean;
+    /** Which kind of factor. */
+    type: string;
+}
+/** A site login the persona can use. Never the password. */
+interface SiteLogin {
+    /** The site. */
+    domain: string;
+    /** The account name. */
+    username: string;
+}
+/** A stored site login, as confirmed. */
+interface CredentialsSaved extends SiteLogin {
+    /** Whether it is stored. */
+    configured: boolean;
+}
+/** The sites a persona can sign in to. */
+interface SiteLogins {
+    /** Usernames only. */
+    credentials: SiteLogin[];
+}
+
+/**
+ * The shapes Browser's methods take and return that are not part of the
+ * exported types: tab listings, dialog answers, share links and the like.
+ * Named here so each field can say what it is.
+ */
+
+/** What `type()` reports back. */
+interface TypeResult {
+    /** An autocomplete list opened under the field; pick from it before moving on. */
+    suggestions_visible?: boolean;
+}
+/** The dialog `handleDialog()` answered. */
+interface DialogResult {
+    /** alert, confirm, prompt or beforeunload. */
+    type: string;
+    /** The dialog's text. */
+    message: string;
+    /** Whether it was accepted. */
+    accepted: boolean;
+}
+/** A point on the page, in CSS pixels. */
+interface Point {
+    /** From the left edge. */
+    x: number;
+    /** From the top edge. */
+    y: number;
+}
+/** One open tab. */
+interface Tab {
+    /** The tab's id, for `switchTab()` and `closeTab()`. */
+    id: string;
+    /** The page it shows. */
+    url: string;
+    /** The page's title. */
+    title: string;
+    /** Whether it is the tab commands act on. */
+    active: boolean;
+}
+/** Task values for `ask()`. */
+interface AskValues {
+    /** Values the agent can read. */
+    data?: RunData;
+    /** Values the agent never sees. */
+    secrets?: RunData;
+}
+/** How `play()` handles a step that no longer fits. */
+interface PlayOptions {
+    /** Let the agent finish the task and save its fix as a draft. Default true. */
+    autoHeal?: boolean;
+}
+/** What `submit()` runs: a prompt for the agent, or a saved playbook. */
+type Task = {
+    /** A natural-language task for the agent. */
+    prompt: string;
+} | {
+    /** The name of a saved playbook. */
+    playbook: string;
+};
+/** How a `shareUrl()` link works. */
+interface ShareOptions {
+    /** Let whoever opens it act in the browser. Default view-only. */
+    control?: boolean;
+    /** How long it lasts. Default one hour. */
+    expiresInSeconds?: number;
+}
+/** A link from `shareUrl()`. */
+interface ShareLink {
+    /** The link to hand out. */
+    url: string;
+    /** Its credential's id, for `revokeShare()`. */
+    id: string;
+    /** When it stops working, in epoch milliseconds; null for never. */
+    expiresAt: number | null;
+}
+
+/** The callbacks a run can fire. */
+type RunCallbacks = Pick<SubmitOptions, 'onSuccess' | 'onFailure' | 'onHumanAttention' | 'onHealed'>;
+
+/**
+ * Run: a task submitted with `browser.submit()`, running in the background.
+ * The polling itself lives in run-watch.ts.
+ */
+
+/** A submitted task. Callbacks fire as it changes; `done` settles when it ends. */
+declare class Run {
+    private readonly http;
+    readonly id: string;
+    /** Settles with the result when the run succeeds, or rejects when it fails. */
+    readonly done: Promise<RunResult>;
+    /** Starts watching the run straight away. */
+    constructor(http: Http, id: string, callbacks: RunCallbacks, pollMs?: number);
+    /** The run's current state. */
+    status(): Promise<RunInfo>;
+    /** Answer the open attention request: `'done'` after handling it by hand, or your reply to the agent. */
+    respond(response?: string): Promise<void>;
+    /** Polls until the run ends, firing callbacks on the way. */
+    private watch;
+}
+
+/**
+ * Browser: one running browser, driven through the API. Page actions go
+ * through the command endpoint; CAPTCHA, MFA, agent runs, playbooks and live
+ * view links have their own endpoints. The small rules the methods share
+ * (element ids, aimed scrolls, agent errors) are the functions below the class.
+ */
+
 /**
  * One running browser.
  *
@@ -501,54 +1093,59 @@ interface ControlOverview {
 declare class Browser {
     private readonly http;
     private readonly autoCaptcha;
+    /** The browser's id. */
     readonly id: string;
+    /** Which provider runs it. */
     readonly provider: string;
+    /** Which persona it runs as. */
     readonly persona: string;
     /** Point Playwright, Puppeteer or browser-use here. */
     readonly cdpUrl?: string;
+    /** Wraps a started browser; `autoCaptcha` solves CAPTCHAs after every `goto()`. */
     constructor(http: Http, info: StartResult, autoCaptcha: boolean);
+    /** Runs one browser command; a command that ran and failed throws. */
     private command;
+    /** Navigates, then clears any CAPTCHA when `captcha: 'auto'` was asked for. */
     goto(url: string): Promise<void>;
-    /** The page as markdown plus numbered elements to act on. */
-    analyze(): Promise<Analysis>;
+    /**
+     * The page, written as markdown (the default), TOON or JSONL, plus its blocks and
+     * the numbered elements to act on.
+     */
+    analyze(options?: AnalyzeOptions): Promise<Analysis>;
     /** Only the visible elements, which is what an agent almost always wants. */
     elements(): Promise<Element[]>;
+    /** Clicks an element by its id from `analyze()`. */
     click(elementId: number | string): Promise<void>;
-    type(elementId: number | string, text: string): Promise<{
-        suggestions_visible?: boolean;
-    }>;
+    /** Types into an element by its id from `analyze()`. */
+    type(elementId: number | string, text: string): Promise<TypeResult>;
+    /** A valid element id, or an OyaError saying where ids come from. */
     private elementId;
+    /** Presses one key, such as Enter or Escape. */
     pressKey(key: string): Promise<void>;
     /**
      * Answer a native dialog holding the page. alert() and beforeunload are
      * answered for you; a confirm() or prompt() waits for this, and every other
      * command fails fast with the dialog's text until it is answered.
      */
-    handleDialog(accept: boolean, promptText?: string): Promise<{
-        type: string;
-        message: string;
-        accepted: boolean;
-    }>;
+    handleDialog(accept: boolean, promptText?: string): Promise<DialogResult>;
     /** `at` aims the wheel at an inner scroller (a results panel, a chat pane) instead of the page. */
-    scroll(direction: 'up' | 'down' | 'top' | 'bottom', amount?: number, at?: {
-        x: number;
-        y: number;
-    }): Promise<void>;
+    scroll(direction: 'up' | 'down' | 'top' | 'bottom', amount?: number, at?: Point): Promise<void>;
+    /** Waits until `selector` matches, up to `timeout` milliseconds. */
     waitFor(selector: string, timeout?: number): Promise<void>;
     /** A `data:image/…;base64,` URL. PNG or JPEG depending on the driver. */
     screenshot(): Promise<string>;
+    /** The active tab's URL, or empty when there is none. */
     url(): Promise<string>;
-    tabs(): Promise<Array<{
-        id: string;
-        url: string;
-        title: string;
-        active: boolean;
-    }>>;
+    /** Every open tab. */
+    tabs(): Promise<Array<Tab>>;
+    /** Opens a tab, optionally at `url`, and returns its id. */
     openTab(url?: string): Promise<string>;
+    /** Makes a tab the one commands act on. */
     switchTab(tabId: string): Promise<void>;
+    /** Closes a tab. */
     closeTab(tabId: string): Promise<void>;
     /**
-    x * Detect and clear a CAPTCHA. Providers that solve natively are left to do
+     * Detect and clear a CAPTCHA. Providers that solve natively are left to do
      * it; everything else goes to the configured solver.
      */
     solveCaptcha(): Promise<CaptchaResult>;
@@ -563,10 +1160,7 @@ declare class Browser {
      * the matching option; `secrets` it never sees. It types both through placeholders,
      * with filters like `{{name|first}}`, so a playbook saved from the run stores no values.
      */
-    ask(prompt: string, { data, secrets }?: {
-        data?: RunData;
-        secrets?: RunData;
-    }): Promise<string>;
+    ask(prompt: string, { data, secrets }?: AskValues): Promise<string>;
     /**
      * Save the last `ask()` on this browser as a named playbook. Every value that was
      * typed, picked or clicked becomes a variable, with what the run used kept in
@@ -581,31 +1175,17 @@ declare class Browser {
      * saved as a draft (`healed`, `draft`); off, the step's error is thrown.
      * Play `'<name>:draft'` to try a draft before promoting it.
      */
-    play(name: string, data?: RunData, { autoHeal }?: {
-        autoHeal?: boolean;
-    }): Promise<PlayResult>;
+    play(name: string, data?: RunData, { autoHeal }?: PlayOptions): Promise<PlayResult>;
     /**
      * Start a prompt or playbook in the background and hear back through callbacks.
      * `onHumanAttention` fires for an unsolved CAPTCHA, an unfinished MFA, the agent
      * asking for help, or a replay the agent could not heal; the run waits (up to 30
      * minutes) until you call `respond()`.
      */
-    submit(task: {
-        prompt: string;
-    } | {
-        playbook: string;
-    }, options?: SubmitOptions): Promise<Run>;
+    submit(task: Task, options?: SubmitOptions): Promise<Run>;
     /**
-     * Watch it work: the console, opened on this browser.
-     *
-     * This used to return the raw frame stream with the project's API key in the
-     * query string — a permanent credential in browser history, Referer headers
-     * and every proxy log on the way, and a URL that renders as a wall of
-     * text/event-stream if a person actually opens it. It is the console deep
-     * link now, the same one the server hands back from `completeMfa()`, and it
-     * carries no credential at all.
-     *
-     * For the frames themselves, use `liveStreamUrl()`.
+     * Watch it work: the console, opened on this browser. It carries no
+     * credential. For the frames themselves, use `liveStreamUrl()`.
      */
     liveViewUrl(): string;
     /**
@@ -625,14 +1205,7 @@ declare class Browser {
      * rest of your project. Anyone holding the link has that access until it
      * expires or you revoke it, so treat it like a password.
      */
-    shareUrl({ control, expiresInSeconds }?: {
-        control?: boolean;
-        expiresInSeconds?: number;
-    }): Promise<{
-        url: string;
-        id: string;
-        expiresAt: number | null;
-    }>;
+    shareUrl({ control, expiresInSeconds }?: ShareOptions): Promise<ShareLink>;
     /** Revoke a link from `shareUrl()` before it expires, by the id it returned. */
     revokeShare(id: string): Promise<void>;
     /** Counters, health and the last 50 things this browser did. */
@@ -647,18 +1220,6 @@ declare class Browser {
     /** @deprecated use stop() — close() only dropped the socket, and a cloud browser redialled. */
     close(): Promise<void>;
 }
-type RunCallbacks = Pick<SubmitOptions, 'onSuccess' | 'onFailure' | 'onHumanAttention' | 'onHealed'>;
-/** A submitted task. Callbacks fire as it changes; `done` settles when it ends. */
-declare class Run {
-    private readonly http;
-    readonly id: string;
-    readonly done: Promise<RunResult>;
-    constructor(http: Http, id: string, callbacks: RunCallbacks, pollMs?: number);
-    status(): Promise<RunInfo>;
-    /** Answer the open attention request: `'done'` after handling it by hand, or your reply to the agent. */
-    respond(response?: string): Promise<void>;
-    private watch;
-}
 
 /**
  * Files as task values.
@@ -678,100 +1239,52 @@ declare const MAX_FILE_BYTES: number;
  * from the extension.
  */
 declare function file(source: string | Uint8Array | Blob, options?: {
+    /** The filename the site sees. */
     name?: string;
+    /** The MIME type, instead of the one guessed from the extension. */
     type?: string;
 }): Promise<FileValue>;
 
-/**
- * @oya-ai/browser — thousands of browsers, one API.
- *
- *   import { Oya } from '@oya-ai/browser';
- *
- *   const oya = new Oya();                                    // OYA_API_KEY
- *   const browser = await oya.browser.start({ persona: 'auto', captcha: 'auto' });
- *   await browser.goto('https://example.com');
- *
- * Which provider actually runs the browser — Oya Cloud, your own machines,
- * Browser Use, Browserbase, Steel, Anchor, or a CDP URL you hand us — is
- * configuration on your API key, not something this code has to know.
- */
-
+/** The client: one API key, every browser behind it. */
 declare class Oya {
+    /** The one HTTP path every call goes through. */
     private readonly http;
+    /** Reads the key and URL from `options`, then OYA_API_KEY and OYA_BASE_URL. Throws without a key. */
     constructor(options?: OyaOptions);
+    /** Start, reattach to, list and stop browsers. */
     readonly browser: {
-        /** Start a browser and wait until it can take commands. */
         start: (options?: StartOptions) => Promise<Browser>;
-        /** Reattach to a browser that is already running. */
         get: (id: string) => Promise<Browser>;
         list: () => Promise<BrowserInfo[]>;
-        /** Stop some (`ids`) or every browser on this key. Each reports separately. */
-        stop: (ids: string[] | "all") => Promise<{
-            stopped: number;
-            results: StopResult[];
-        }>;
+        stop: (ids: string[] | "all") => Promise<StopManyResult>;
         stopAll: () => Promise<number>;
     };
     /** Durable operational controls, including disconnected and cleanup-pending sessions. */
     readonly control: {
-        overview: () => Promise<ControlOverview>;
-        sessions: () => Promise<ControlSession[]>;
-        session: (id: string) => Promise<ControlSession>;
-        settings: (changes: Partial<ProjectSettings>) => Promise<ControlOverview["project"]>;
+        createWebhook: (url: string, types?: string[]) => Promise<Webhook>;
+        removeWebhook: (id: string) => Promise<Ack>;
+        replayDelivery: (id: string) => Promise<Ack>;
+        members: () => Promise<MemberList>;
+        inviteMember: (role?: ControlRole) => Promise<Invite>;
+        removeMember: (userId: string) => Promise<Ack>;
+        createCredential: (options: CredentialRequest) => Promise<NewCredential>;
+        revokeCredential: (id: string) => Promise<Ack>;
+        recover: (id: string, replace?: boolean) => Promise<unknown>;
+        ticket: (id: string) => Promise<Ticket>;
+        events: (after?: number) => Promise<EventPage>;
         cancel: (id: string) => Promise<ControlSession>;
         stop: (id: string, force?: boolean) => Promise<StopResult>;
         takeover: (id: string, action: "acquire" | "release" | "resume") => Promise<ControlSession["control"]>;
         input: (id: string, action: HumanInputAction, params: Record<string, unknown>) => Promise<unknown>;
-        recover: (id: string, replace?: boolean) => Promise<unknown>;
-        ticket: (id: string) => Promise<{
-            ticket: string;
-            expiresIn: number;
-        }>;
-        events: (after?: number) => Promise<{
-            events: ControlEvent[];
-            cursor: number;
-        }>;
-        createCredential: (options: {
-            role: ControlRole;
-            label?: string;
-            expiresAt?: number;
-        }) => Promise<ControlCredential & {
-            token: string;
-        }>;
-        revokeCredential: (id: string) => Promise<{
-            ok: boolean;
-        }>;
-        members: () => Promise<{
-            owner: string | null;
-            members: {
-                userId: string;
-                role: ControlRole;
-            }[];
-        }>;
-        inviteMember: (role?: ControlRole) => Promise<{
-            code: string;
-            expiresIn: number;
-        }>;
-        removeMember: (userId: string) => Promise<{
-            ok: boolean;
-        }>;
-        createWebhook: (url: string, types?: string[]) => Promise<{
-            id: string;
-            secret: string;
-        }>;
-        removeWebhook: (id: string) => Promise<{
-            ok: boolean;
-        }>;
-        replayDelivery: (id: string) => Promise<{
-            ok: boolean;
-        }>;
+        overview: () => Promise<ControlOverview>;
+        sessions: () => Promise<ControlSession[]>;
+        session: (id: string) => Promise<ControlSession>;
+        settings: (changes: Partial<ProjectSettings>) => Promise<ControlOverview["project"]>;
     };
     /** Playbooks saved with `browser.toPlaybook()`. */
     readonly playbooks: {
         list: () => Promise<PlaybookSummary[]>;
-        /** Delete a playbook and its draft, or only the draft with `'<name>:draft'`. */
         remove: (name: string) => Promise<void>;
-        /** Replace a playbook with the draft a healed replay saved. Try it first with `browser.play('<name>:draft')`. */
         promote: (name: string) => Promise<Playbook>;
     };
     /**
@@ -782,84 +1295,24 @@ declare class Oya {
         list: () => Promise<ProxyInfo[]>;
         create: (proxy: ProxyCreate) => Promise<ProxyInfo>;
         remove: (id: string) => Promise<void>;
-        /** Dial each proxy and learn its real exit IP. Failing ones cool down and are skipped. */
-        check: () => Promise<Array<{
-            id: string;
-            ok: boolean;
-            exitIp?: string | null;
-            error?: string;
-        }>>;
+        check: () => Promise<Array<ProxyCheck>>;
     };
+    /** Identities: fingerprint, cookie jar and proxy bound together, plus their stored factors and logins. */
     readonly personas: {
-        list: () => Promise<PersonaInfo[]>;
-        get: (id: string) => Promise<PersonaInfo>;
-        /**
-         * Create an identity. The device — platform, timezone, locale — is chosen
-         * here and fixed for its life; `preview()` shows what a choice produces.
-         */
-        create: (options?: {
-            name?: string;
-            prefs?: PersonaPrefs;
-            proxy?: {
-                geo?: string;
-            };
-            maxConcurrent?: number | null;
-        }) => Promise<PersonaInfo>;
-        /** Name, concurrency cap and proxy hint. Never the device — clone for that. */
-        update: (id: string, changes: {
-            name?: string;
-            maxConcurrent?: number | null;
-            proxy?: {
-                geo?: string;
-            } | null;
-        }) => Promise<PersonaInfo>;
-        /** A new persona of the same kind of device: same choices, fresh identity, empty jar. */
-        clone: (id: string, options?: {
-            name?: string;
-        }) => Promise<PersonaInfo>;
-        /** The fingerprint these choices would produce. Persists nothing. */
+        setCredentials: (id: string, config: SiteCredentials) => Promise<CredentialsSaved>;
+        credentials: (id: string) => Promise<SiteLogins>;
+        clearCredentials: (id: string, domain: string) => Promise<void>;
+        setMfa: (id: string, config: MfaConfig) => Promise<MfaSaved>;
+        clearMfa: (id: string, domain?: string) => Promise<void>;
         preview: (prefs?: PersonaPrefs) => Promise<Fingerprint>;
-        /** Platforms, and the timezones and locales each may coherently claim. */
-        options: () => Promise<{
-            platforms: string[];
-            timezones: Record<string, string[]>;
-            locales: Record<string, string[]>;
-        }>;
-        /** Pin the persona to one of your proxies, or `null` to let assignment happen at connect. */
-        pinProxy: (id: string, proxyId: string | null) => Promise<{
-            ok: boolean;
-            proxy: {
-                id: string;
-                label: string;
-            } | null;
-        }>;
+        options: () => Promise<PersonaOptions>;
+        pinProxy: (id: string, proxyId: string | null) => Promise<ProxyPin>;
         remove: (id: string) => Promise<void>;
-        /** Store the second factor for this identity. Sealed at rest, never read back. */
-        setMfa: (id: string, config: MfaConfig) => Promise<{
-            configured: boolean;
-            type: string;
-        }>;
-        clearMfa: (id: string, domain?: string) => Promise<void>;
-        /**
-         * Store a site login for this identity. Sealed at rest, never read back.
-         *
-         * Signing in once on the desktop and inheriting the cookies is still the
-         * better path. This is for portals that expire a session server-side
-         * between runs, where an unattended run has nothing else to recover with.
-         */
-        setCredentials: (id: string, config: SiteCredentials) => Promise<{
-            configured: boolean;
-            domain: string;
-            username: string;
-        }>;
-        /** Which sites this identity can sign in to. Usernames only. */
-        credentials: (id: string) => Promise<{
-            credentials: {
-                domain: string;
-                username: string;
-            }[];
-        }>;
-        clearCredentials: (id: string, domain: string) => Promise<void>;
+        list: () => Promise<PersonaInfo[]>;
+        get: (id: string) => Promise<PersonaInfo>;
+        create: (options?: PersonaCreate) => Promise<PersonaInfo>;
+        update: (id: string, changes: PersonaUpdate) => Promise<PersonaInfo>;
+        clone: (id: string, options?: CloneOptions) => Promise<PersonaInfo>;
     };
     /**
      * This key's settings: LLM credentials, browser provider, solver.
@@ -878,78 +1331,25 @@ declare class Oya {
     };
     /** Saved profiles. `personas` is retained as an alias for existing clients. */
     readonly profiles: {
-        list: () => Promise<PersonaInfo[]>;
-        get: (id: string) => Promise<PersonaInfo>;
-        /**
-         * Create an identity. The device — platform, timezone, locale — is chosen
-         * here and fixed for its life; `preview()` shows what a choice produces.
-         */
-        create: (options?: {
-            name?: string;
-            prefs?: PersonaPrefs;
-            proxy?: {
-                geo?: string;
-            };
-            maxConcurrent?: number | null;
-        }) => Promise<PersonaInfo>;
-        /** Name, concurrency cap and proxy hint. Never the device — clone for that. */
-        update: (id: string, changes: {
-            name?: string;
-            maxConcurrent?: number | null;
-            proxy?: {
-                geo?: string;
-            } | null;
-        }) => Promise<PersonaInfo>;
-        /** A new persona of the same kind of device: same choices, fresh identity, empty jar. */
-        clone: (id: string, options?: {
-            name?: string;
-        }) => Promise<PersonaInfo>;
-        /** The fingerprint these choices would produce. Persists nothing. */
+        setCredentials: (id: string, config: SiteCredentials) => Promise<CredentialsSaved>;
+        credentials: (id: string) => Promise<SiteLogins>;
+        clearCredentials: (id: string, domain: string) => Promise<void>;
+        setMfa: (id: string, config: MfaConfig) => Promise<MfaSaved>;
+        clearMfa: (id: string, domain?: string) => Promise<void>;
         preview: (prefs?: PersonaPrefs) => Promise<Fingerprint>;
-        /** Platforms, and the timezones and locales each may coherently claim. */
-        options: () => Promise<{
-            platforms: string[];
-            timezones: Record<string, string[]>;
-            locales: Record<string, string[]>;
-        }>;
-        /** Pin the persona to one of your proxies, or `null` to let assignment happen at connect. */
-        pinProxy: (id: string, proxyId: string | null) => Promise<{
-            ok: boolean;
-            proxy: {
-                id: string;
-                label: string;
-            } | null;
-        }>;
+        options: () => Promise<PersonaOptions>;
+        pinProxy: (id: string, proxyId: string | null) => Promise<ProxyPin>;
         remove: (id: string) => Promise<void>;
-        /** Store the second factor for this identity. Sealed at rest, never read back. */
-        setMfa: (id: string, config: MfaConfig) => Promise<{
-            configured: boolean;
-            type: string;
-        }>;
-        clearMfa: (id: string, domain?: string) => Promise<void>;
-        /**
-         * Store a site login for this identity. Sealed at rest, never read back.
-         *
-         * Signing in once on the desktop and inheriting the cookies is still the
-         * better path. This is for portals that expire a session server-side
-         * between runs, where an unattended run has nothing else to recover with.
-         */
-        setCredentials: (id: string, config: SiteCredentials) => Promise<{
-            configured: boolean;
-            domain: string;
-            username: string;
-        }>;
-        /** Which sites this identity can sign in to. Usernames only. */
-        credentials: (id: string) => Promise<{
-            credentials: {
-                domain: string;
-                username: string;
-            }[];
-        }>;
-        clearCredentials: (id: string, domain: string) => Promise<void>;
+        list: () => Promise<PersonaInfo[]>;
+        get: (id: string) => Promise<PersonaInfo>;
+        create: (options?: PersonaCreate) => Promise<PersonaInfo>;
+        update: (id: string, changes: PersonaUpdate) => Promise<PersonaInfo>;
+        clone: (id: string, options?: CloneOptions) => Promise<PersonaInfo>;
     };
+    /** What this key has spent. */
     usage(): Promise<unknown>;
+    /** Waits for a starting browser to dial in, through this client's own list and session calls. */
     private waitUntilConnected;
 }
 
-export { type Activity, type Analysis, type AttentionRequest, Browser, type BrowserDetail, type BrowserInfo, type CaptchaResult, type CaptchaSolver, type Config, type ConfigUpdate, type ControlCredential, type ControlEvent, type ControlOverview, type ControlRole, type ControlSession, type Element, type FileValue, type Fingerprint, type Health, type HumanInputAction, type LlmProvider, MAX_FILE_BYTES, type MfaConfig, type MfaResult, Oya, OyaError, type OyaOptions, type PersonaInfo, type PersonaPrefs, type PlayResult, type Playbook, type PlaybookSummary, type ProjectSettings, type Provider, type ProxyCreate, type ProxyInfo, Run, type RunData, type RunInfo, type RunResult, type SiteCredentials, type StartOptions, type StartResult, type StopResult, type SubmitOptions, Oya as default, file };
+export { type Activity, type Analysis, type AnalyzeOptions, type AttentionRequest, type Block, Browser, type BrowserDetail, type BrowserInfo, type CaptchaResult, type CaptchaSolver, type Config, type ConfigUpdate, type ControlCredential, type ControlEvent, type ControlOverview, type ControlRole, type ControlSession, type Element, type FileValue, type Fingerprint, type Health, type HumanInputAction, type LlmProvider, MAX_FILE_BYTES, type MfaConfig, type MfaResult, Oya, OyaError, type OyaOptions, type PageFormat, type PersonaInfo, type PersonaPrefs, type PlayResult, type Playbook, type PlaybookSummary, type ProjectSettings, type Provider, type ProxyCreate, type ProxyInfo, Run, type RunData, type RunInfo, type RunResult, type SiteCredentials, type StartOptions, type StartResult, type StopResult, type SubmitOptions, Oya as default, file };