@oya-ai/browser 1.0.107 → 1.0.111

package/dist/index.d.cts

@@ -255,6 +255,8 @@ interface BrowserInfo {
 }
 /** A browser plus what it has been doing, from `browser.status()`. */
 interface BrowserDetail extends BrowserInfo {
+    /** The actions it does, sorted, one spelling each: an action not listed answers action_unsupported or action_unknown. */
+    actions: string[];
     /** Its most recent commands, newest first. */
     activity: Activity[];
 }
@@ -342,10 +344,6 @@ interface Config extends Omit<ConfigUpdate, 'llm_provider' | 'browser_provider'
     }>;
 }
 
-/**
- * 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. */
@@ -689,6 +687,31 @@ interface SiteCredentials {
     /** The password; stored sealed and never returned. */
     password: string;
 }
+/** A cookie in a persona's jar. */
+interface Cookie {
+    /** The cookie's name. */
+    name: string;
+    /** Its value: a session, so treat it as a secret. */
+    value: string;
+    /** The domain it is sent to; a leading dot includes subdomains. */
+    domain: string;
+    /** The path it is sent to. `/` when omitted. */
+    path?: string;
+    /** Sent over HTTPS only. */
+    secure?: boolean;
+    /** Hidden from page scripts. */
+    httpOnly?: boolean;
+    /** `Strict`, `Lax` or `None` (Playwright), or `strict`, `lax`, `no_restriction` (Chrome extensions). */
+    sameSite?: string;
+    /** When it expires, in seconds since the epoch. A session cookie has none. */
+    expirationDate?: number;
+    /** The same, as Playwright and Puppeteer spell it; `-1` for a session cookie. */
+    expires?: number;
+    /** Whether it is sent to this exact host only. */
+    hostOnly?: boolean;
+}
+/** The formats a jar is exported in: as stored, or ready for Playwright's `context.addCookies()`. */
+type CookieFormat = 'json' | 'playwright';
 
 /**
  * Types for the durable control plane: sessions and their lifecycle, human
@@ -696,6 +719,13 @@ interface SiteCredentials {
  */
 /** What a member or credential may do: read, operate browsers, or also administer the project. */
 type ControlRole = 'viewer' | 'operator' | 'administrator';
+/** How to recover a session: in place (the default), or replaced by a fresh one. */
+interface RecoverOptions {
+    /** Start a fresh session in its place. */
+    replace?: boolean;
+    /** cdp only: the Chrome the replacement runs on. */
+    wsUrl?: string;
+}
 /** 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. */
@@ -809,14 +839,24 @@ interface OyaOptions {
     fetch?: typeof globalThis.fetch;
 }
 
+/** Where the key and the address came from, so a message names the one to fix. */
+interface Origin {
+    /** The key's source, as a message names it: "the apiKey option", "OYA_API_KEY" or "~/.oya/config.json". */
+    apiKeyFrom: string;
+    /** The address's source, named the same way, or "default" for the hosted one. */
+    baseUrlFrom: string;
+    /** Whether a key is also saved by `oya login`, which an environment key overrides. */
+    savedKey: boolean;
+}
 /** 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);
+    readonly origin: Origin;
+    /** Stores where to call, with which key, how long to wait, which fetch to use, and where the key and address came from. */
+    constructor(baseUrl: string, apiKey: string, timeoutMs: number, fetchImpl: typeof globalThis.fetch, origin?: Origin);
     /** 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 fetch options for one call, with this client's key on them. */
@@ -991,6 +1031,17 @@ interface SiteLogins {
     /** Usernames only. */
     credentials: SiteLogin[];
 }
+/** `PUT /api/pool/cookies`: what an import did. */
+interface CookiesImported {
+    /** The persona the cookies went to. */
+    persona: string;
+    /** Cookies merged into the jar. */
+    imported: number;
+    /** Cookies left out: no name, value or domain, or already expired. */
+    skipped: number;
+    /** Cookies in the jar afterwards. */
+    total: number;
+}
 
 /**
  * The shapes Browser's methods take and return that are not part of the
@@ -1286,7 +1337,7 @@ declare class Oya {
         removeMember: (userId: string) => Promise<Ack>;
         createCredential: (options: CredentialRequest) => Promise<NewCredential>;
         revokeCredential: (id: string) => Promise<Ack>;
-        recover: (id: string, replace?: boolean) => Promise<unknown>;
+        recover: (id: string, options?: boolean | RecoverOptions) => Promise<unknown>;
         ticket: (id: string) => Promise<Ticket>;
         events: (after?: number) => Promise<EventPage>;
         cancel: (id: string) => Promise<ControlSession>;
@@ -1316,6 +1367,10 @@ declare class Oya {
     };
     /** Identities: fingerprint, cookie jar and proxy bound together, plus their stored factors and logins. */
     readonly personas: {
+        copyCookies: (from: string, to: string) => Promise<CookiesImported>;
+        clearCookies: (id: string) => Promise<void>;
+        cookies: (id: string, format?: CookieFormat) => Promise<Cookie[]>;
+        importCookies: (id: string, list: Cookie[]) => Promise<CookiesImported>;
         setCredentials: (id: string, config: SiteCredentials) => Promise<CredentialsSaved>;
         credentials: (id: string) => Promise<SiteLogins>;
         clearCredentials: (id: string, domain: string) => Promise<void>;
@@ -1348,6 +1403,10 @@ declare class Oya {
     };
     /** Saved profiles. `personas` is retained as an alias for existing clients. */
     readonly profiles: {
+        copyCookies: (from: string, to: string) => Promise<CookiesImported>;
+        clearCookies: (id: string) => Promise<void>;
+        cookies: (id: string, format?: CookieFormat) => Promise<Cookie[]>;
+        importCookies: (id: string, list: Cookie[]) => Promise<CookiesImported>;
         setCredentials: (id: string, config: SiteCredentials) => Promise<CredentialsSaved>;
         credentials: (id: string) => Promise<SiteLogins>;
         clearCredentials: (id: string, domain: string) => Promise<void>;
@@ -1369,4 +1428,4 @@ declare class Oya {
     private waitUntilConnected;
 }
 
-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 };
+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 Cookie, type CookieFormat, 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, type RecoverOptions, Run, type RunData, type RunInfo, type RunResult, type SiteCredentials, type StartOptions, type StartResult, type StopResult, type SubmitOptions, Oya as default, file };

package/dist/index.d.ts

@@ -255,6 +255,8 @@ interface BrowserInfo {
 }
 /** A browser plus what it has been doing, from `browser.status()`. */
 interface BrowserDetail extends BrowserInfo {
+    /** The actions it does, sorted, one spelling each: an action not listed answers action_unsupported or action_unknown. */
+    actions: string[];
     /** Its most recent commands, newest first. */
     activity: Activity[];
 }
@@ -342,10 +344,6 @@ interface Config extends Omit<ConfigUpdate, 'llm_provider' | 'browser_provider'
     }>;
 }
 
-/**
- * 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. */
@@ -689,6 +687,31 @@ interface SiteCredentials {
     /** The password; stored sealed and never returned. */
     password: string;
 }
+/** A cookie in a persona's jar. */
+interface Cookie {
+    /** The cookie's name. */
+    name: string;
+    /** Its value: a session, so treat it as a secret. */
+    value: string;
+    /** The domain it is sent to; a leading dot includes subdomains. */
+    domain: string;
+    /** The path it is sent to. `/` when omitted. */
+    path?: string;
+    /** Sent over HTTPS only. */
+    secure?: boolean;
+    /** Hidden from page scripts. */
+    httpOnly?: boolean;
+    /** `Strict`, `Lax` or `None` (Playwright), or `strict`, `lax`, `no_restriction` (Chrome extensions). */
+    sameSite?: string;
+    /** When it expires, in seconds since the epoch. A session cookie has none. */
+    expirationDate?: number;
+    /** The same, as Playwright and Puppeteer spell it; `-1` for a session cookie. */
+    expires?: number;
+    /** Whether it is sent to this exact host only. */
+    hostOnly?: boolean;
+}
+/** The formats a jar is exported in: as stored, or ready for Playwright's `context.addCookies()`. */
+type CookieFormat = 'json' | 'playwright';
 
 /**
  * Types for the durable control plane: sessions and their lifecycle, human
@@ -696,6 +719,13 @@ interface SiteCredentials {
  */
 /** What a member or credential may do: read, operate browsers, or also administer the project. */
 type ControlRole = 'viewer' | 'operator' | 'administrator';
+/** How to recover a session: in place (the default), or replaced by a fresh one. */
+interface RecoverOptions {
+    /** Start a fresh session in its place. */
+    replace?: boolean;
+    /** cdp only: the Chrome the replacement runs on. */
+    wsUrl?: string;
+}
 /** 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. */
@@ -809,14 +839,24 @@ interface OyaOptions {
     fetch?: typeof globalThis.fetch;
 }
 
+/** Where the key and the address came from, so a message names the one to fix. */
+interface Origin {
+    /** The key's source, as a message names it: "the apiKey option", "OYA_API_KEY" or "~/.oya/config.json". */
+    apiKeyFrom: string;
+    /** The address's source, named the same way, or "default" for the hosted one. */
+    baseUrlFrom: string;
+    /** Whether a key is also saved by `oya login`, which an environment key overrides. */
+    savedKey: boolean;
+}
 /** 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);
+    readonly origin: Origin;
+    /** Stores where to call, with which key, how long to wait, which fetch to use, and where the key and address came from. */
+    constructor(baseUrl: string, apiKey: string, timeoutMs: number, fetchImpl: typeof globalThis.fetch, origin?: Origin);
     /** 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 fetch options for one call, with this client's key on them. */
@@ -991,6 +1031,17 @@ interface SiteLogins {
     /** Usernames only. */
     credentials: SiteLogin[];
 }
+/** `PUT /api/pool/cookies`: what an import did. */
+interface CookiesImported {
+    /** The persona the cookies went to. */
+    persona: string;
+    /** Cookies merged into the jar. */
+    imported: number;
+    /** Cookies left out: no name, value or domain, or already expired. */
+    skipped: number;
+    /** Cookies in the jar afterwards. */
+    total: number;
+}
 
 /**
  * The shapes Browser's methods take and return that are not part of the
@@ -1286,7 +1337,7 @@ declare class Oya {
         removeMember: (userId: string) => Promise<Ack>;
         createCredential: (options: CredentialRequest) => Promise<NewCredential>;
         revokeCredential: (id: string) => Promise<Ack>;
-        recover: (id: string, replace?: boolean) => Promise<unknown>;
+        recover: (id: string, options?: boolean | RecoverOptions) => Promise<unknown>;
         ticket: (id: string) => Promise<Ticket>;
         events: (after?: number) => Promise<EventPage>;
         cancel: (id: string) => Promise<ControlSession>;
@@ -1316,6 +1367,10 @@ declare class Oya {
     };
     /** Identities: fingerprint, cookie jar and proxy bound together, plus their stored factors and logins. */
     readonly personas: {
+        copyCookies: (from: string, to: string) => Promise<CookiesImported>;
+        clearCookies: (id: string) => Promise<void>;
+        cookies: (id: string, format?: CookieFormat) => Promise<Cookie[]>;
+        importCookies: (id: string, list: Cookie[]) => Promise<CookiesImported>;
         setCredentials: (id: string, config: SiteCredentials) => Promise<CredentialsSaved>;
         credentials: (id: string) => Promise<SiteLogins>;
         clearCredentials: (id: string, domain: string) => Promise<void>;
@@ -1348,6 +1403,10 @@ declare class Oya {
     };
     /** Saved profiles. `personas` is retained as an alias for existing clients. */
     readonly profiles: {
+        copyCookies: (from: string, to: string) => Promise<CookiesImported>;
+        clearCookies: (id: string) => Promise<void>;
+        cookies: (id: string, format?: CookieFormat) => Promise<Cookie[]>;
+        importCookies: (id: string, list: Cookie[]) => Promise<CookiesImported>;
         setCredentials: (id: string, config: SiteCredentials) => Promise<CredentialsSaved>;
         credentials: (id: string) => Promise<SiteLogins>;
         clearCredentials: (id: string, domain: string) => Promise<void>;
@@ -1369,4 +1428,4 @@ declare class Oya {
     private waitUntilConnected;
 }
 
-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 };
+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 Cookie, type CookieFormat, 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, type RecoverOptions, Run, type RunData, type RunInfo, type RunResult, type SiteCredentials, type StartOptions, type StartResult, type StopResult, type SubmitOptions, Oya as default, file };