@oya-ai/browser 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,548 @@
+/** 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>;
+}
+
+/** Everything the API returns or accepts, in one place. */
+/** 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;
+}
+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;
+}
+interface Fingerprint {
+    platform: string;
+    timezone: string;
+    locale: string;
+    screen: string;
+    webgl: string;
+    hardwareConcurrency: number;
+    deviceMemory: number;
+    canvasSeed: number;
+}
+/** Device choices made at creation. Fixed for the persona's life. */
+interface PersonaPrefs {
+    platform?: 'Win32' | 'MacIntel' | 'Linux x86_64';
+    timezone?: string;
+    locale?: string;
+}
+interface PersonaInfo {
+    id: string;
+    name: string;
+    isDefault: boolean;
+    activeBrowsers: number;
+    maxConcurrent: number | null;
+    proxy: {
+        geo: string | null;
+    } | null;
+    /** The proxy it is actually on, once assigned or pinned. */
+    exit: {
+        id: string;
+        label: string;
+        geo: string | null;
+        healthy: boolean;
+    } | null;
+    prefs: PersonaPrefs | null;
+    fingerprint: Fingerprint;
+    mfa: {
+        configured: boolean;
+        type?: string;
+    };
+    login: {
+        cookies: number;
+        sites: string[];
+        updatedAt: string | null;
+    };
+    createdAt: string;
+    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;
+}
+type MfaConfig = {
+    type: 'totp';
+    secret: string;
+} | {
+    type: 'email' | 'sms';
+    url: string;
+    headers?: Record<string, string>;
+    pattern?: string;
+    timeoutMs?: number;
+};
+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);
+}
+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';
+interface ControlSession {
+    id: string;
+    project: string;
+    provider: string;
+    persona: string | null;
+    state: 'queued' | 'provisioning' | 'ready' | 'disconnected' | 'stopping' | 'cleanup_pending' | 'stopped' | 'failed' | 'unknown_outcome';
+    managed: boolean;
+    createdAt: number;
+    updatedAt: number;
+    costUsd: number;
+    control: {
+        mode: 'agent' | 'human' | 'paused';
+        expiresAt?: number;
+    };
+    cleanupError?: string;
+}
+interface ProjectSettings {
+    recordingDays: number;
+    auditDays: number;
+    budgetUsd: number | null;
+    maxConcurrent: number | null;
+    rates: Record<string, number>;
+    policy: Record<string, unknown>;
+}
+interface ControlEvent {
+    id: number;
+    project: string;
+    type: string;
+    sessionId: string | null;
+    at: number;
+    detail: Record<string, unknown>;
+}
+interface ControlCredential {
+    id: string;
+    label: string;
+    role: ControlRole;
+    expiresAt: number | null;
+    revokedAt: number | null;
+}
+interface ControlOverview {
+    /** costUsd: estimated lifetime spend, metered from rate cards. */
+    project: {
+        id: string;
+        name: string;
+        settings: ProjectSettings;
+        costUsd?: number;
+    };
+    sessions: ControlSession[];
+    events: ControlEvent[];
+    draining: boolean;
+    credentials?: ControlCredential[];
+}
+
+/**
+ * One running browser.
+ *
+ * Element ids come from `analyze()` and are only valid until the page changes —
+ * the same contract the agent tools use. `click(13)` after a navigation is a
+ * bug; call `analyze()` again.
+ */
+declare class Browser {
+    private readonly http;
+    private readonly autoCaptcha;
+    readonly id: string;
+    readonly provider: string;
+    readonly persona: string;
+    /** Point Playwright, Puppeteer or browser-use here. */
+    readonly cdpUrl?: string;
+    constructor(http: Http, info: StartResult, autoCaptcha: boolean);
+    private command;
+    goto(url: string): Promise<void>;
+    /** The page as markdown plus numbered elements to act on. */
+    analyze(): Promise<Analysis>;
+    /** Only the visible elements, which is what an agent almost always wants. */
+    elements(): Promise<Element[]>;
+    click(elementId: number | string): Promise<void>;
+    type(elementId: number | string, text: string): Promise<{
+        suggestions_visible?: boolean;
+    }>;
+    private elementId;
+    pressKey(key: string): Promise<void>;
+    /** `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>;
+    waitFor(selector: string, timeout?: number): Promise<void>;
+    /** A `data:image/…;base64,` URL. PNG or JPEG depending on the driver. */
+    screenshot(): Promise<string>;
+    url(): Promise<string>;
+    tabs(): Promise<Array<{
+        id: string;
+        url: string;
+        title: string;
+        active: boolean;
+    }>>;
+    openTab(url?: string): Promise<string>;
+    switchTab(tabId: string): Promise<void>;
+    closeTab(tabId: string): Promise<void>;
+    /**
+     * Detect and clear a CAPTCHA. Providers that solve natively are left to do
+     * it; everything else goes to the configured solver.
+     */
+    solveCaptcha(): Promise<CaptchaResult>;
+    /**
+     * Answer an MFA prompt with the persona's configured factor. When nothing can
+     * answer it, `liveViewUrl` is where a person finishes by hand.
+     */
+    completeMfa(): Promise<MfaResult>;
+    /** Natural-language control, using this key's configured model. */
+    ask(prompt: string): Promise<string>;
+    /**
+     * Watch it work: an SSE stream of JPEG frames. EventSource cannot set
+     * headers, so the key travels as a query parameter — treat the URL itself as
+     * a credential.
+     */
+    liveViewUrl(): string;
+    /** Counters, health and the last 50 things this browser did. */
+    status(): Promise<BrowserDetail>;
+    /**
+     * Stop it, whatever it is: a cloud sandbox is destroyed so billing ends, a
+     * CDP session is handed back to its provider, a desktop browser disconnects.
+     */
+    stop(): Promise<StopResult>;
+    /** `await using browser = await oya.browser.start()` stops it however the block exits, errors included. */
+    [Symbol.asyncDispose](): Promise<void>;
+    /** @deprecated use stop() — close() only dropped the socket, and a cloud browser redialled. */
+    close(): Promise<void>;
+}
+
+/**
+ * @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.
+ */
+
+declare class Oya {
+    private readonly http;
+    constructor(options?: OyaOptions);
+    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[];
+        }>;
+        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"]>;
+        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;
+        }>;
+    };
+    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. */
+        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;
+        }>;
+        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) => Promise<void>;
+    };
+    /** This key's settings: LLM credentials, browser provider, solver. */
+    readonly config: {
+        get: <T = Record<string, unknown>>() => Promise<T>;
+        set: <T = Record<string, unknown>>(values: Record<string, unknown>) => Promise<T>;
+    };
+    /** 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. */
+        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;
+        }>;
+        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) => Promise<void>;
+    };
+    usage(): Promise<unknown>;
+    private waitUntilConnected;
+}
+
+export { type Activity, type Analysis, Browser, type BrowserDetail, type BrowserInfo, type CaptchaResult, type ControlCredential, type ControlEvent, type ControlOverview, type ControlRole, type ControlSession, type Element, type Fingerprint, type Health, type HumanInputAction, type MfaConfig, type MfaResult, Oya, OyaError, type OyaOptions, type PersonaInfo, type PersonaPrefs, type ProjectSettings, type Provider, type StartOptions, type StartResult, type StopResult, Oya as default };