@oya-ai/browser 1.0.209 → 1.0.213

package/README.md

@@ -25,21 +25,30 @@ import { Oya } from '@oya-ai/browser';
 
 const browser = await new Oya().browser.start();
 await browser.goto('https://news.ycombinator.com');
-console.log(await browser.ask('What are the top 3 stories?'));
+console.log(await browser.ask('What are the top 3 stories and their points?'));
+await browser.stop();
 ```
 
-Two things to have first: an API key from [oyabrowser.com](https://oyabrowser.com)
-(or your own deployment) in `OYA_API_KEY`, and a browser to drive.
+The one thing to have first is an API key from [oyabrowser.com](https://oyabrowser.com)
+(or your own deployment) in `OYA_API_KEY`.
 
-**The fastest browser to have is one you already have.** Open the
-[Oya desktop browser](https://oyabrowser.com) and sign in with the same key: `start()`
-hands over the browser that is already connected when no provider is configured, so the
-five lines above work with nothing else set up. `stop()` leaves a browser you borrowed
-alone, because you did not start it.
+**Which browser `start()` gives you**, when no provider is configured: the
+[Oya desktop browser](https://oyabrowser.com) if it is open and signed in with the same
+key, else a new one in Oya Cloud. `stop()` leaves a browser you borrowed alone, because
+you did not start it. To run browsers somewhere else (your own Docker, Browserbase,
+Steel, Anchor, Browser Use, or a Chrome of your own over CDP), pass `{ provider }` or set
+a default with `npx @oya-ai/cli init`. Your code does not change.
 
-When you would rather it start one for you, run `npx @oya-ai/cli init` and pick where
-browsers run: Oya Cloud, your own Docker, Browserbase, Steel, Anchor, Browser Use, or a
-Chrome of your own over CDP. Your code does not change.
+**Which model `ask()` uses:** the key's saved one, or Oya's when it has none. Pick one in
+code, for this client only and never saved to the key:
+
+```js
+const oya = new Oya({
+  model: { provider: 'anthropic', name: 'claude-sonnet-5', apiKey: process.env.ANTHROPIC_API_KEY },
+});
+```
+
+Without `apiKey`, `name` runs on the credential your key already uses, which must be the same provider.
 
 **Where the key comes from**, in order: `new Oya({ apiKey })`, then `OYA_API_KEY`, then the
 file `oya login` wrote (`~/.oya/config.json`, or `OYA_CONFIG_HOME`), which is read on Node

package/dist/index.cjs

@@ -131,18 +131,20 @@ function saveKey(apiKey, baseUrl) {
 var OPTIONS_ORIGIN = { apiKeyFrom: "the apiKey option", baseUrlFrom: "the baseUrl option", savedKey: false };
 var Http = class {
   /** 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, apiKey, timeoutMs, fetchImpl, origin = OPTIONS_ORIGIN) {
+  constructor(baseUrl, apiKey, timeoutMs, fetchImpl, origin = OPTIONS_ORIGIN, defaults = {}) {
     this.baseUrl = baseUrl;
     this.apiKey = apiKey;
     this.timeoutMs = timeoutMs;
     this.fetchImpl = fetchImpl;
     this.origin = origin;
+    this.defaults = defaults;
   }
   baseUrl;
   apiKey;
   timeoutMs;
   fetchImpl;
   origin;
+  defaults;
   /** Sends one request and returns the parsed answer, or throws an OyaError when it failed. */
   async request(method, path, body, timeoutMs = this.timeoutMs, headers = {}) {
     const res = await this.send(`${this.baseUrl}${path}`, this.init(method, body, timeoutMs, headers), timeoutMs);
@@ -150,7 +152,11 @@ var Http = class {
   }
   /** The fetch options for one call, with this client's key on them. */
   init(method, body, timeoutMs, headers) {
-    return requestInit(method, body, timeoutMs, { Authorization: `Bearer ${this.apiKey}`, ...headers });
+    return requestInit(method, body, timeoutMs, {
+      Authorization: `Bearer ${this.apiKey}`,
+      ...this.defaults,
+      ...headers
+    });
   }
   /**
    * fetch's own failures say only "fetch failed" or "The operation was
@@ -235,7 +241,7 @@ function deploymentOf(url) {
   }
 }
 function noKey(saved, address) {
-  if (!saved.apiKey) return "No API key. Pass { apiKey }, set OYA_API_KEY, or run `npx @oya-ai/cli login`.";
+  if (!saved.apiKey) return "No API key. Get one at https://oyabrowser.com, then set OYA_API_KEY or pass { apiKey }.";
   const why = `the key saved in ~/.oya/config.json is for ${saved.baseUrl} and is only sent there`;
   return `No API key for ${address}: ${why}. Pass { apiKey }, set OYA_API_KEY, or run \`npx @oya-ai/cli login --url ${address}\`.`;
 }
@@ -247,7 +253,18 @@ function createHttp(options) {
   if (!fetchImpl) throw new Error("No fetch available, pass { fetch } or use Node 18+.");
   const origin = { apiKeyFrom: key.from, baseUrlFrom: address.from, savedKey: !!saved.apiKey };
   const timeout = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-  return new Http(webAddress(address), key.value, timeout, fetchImpl.bind(globalThis), origin);
+  return new Http(webAddress(address), key.value, timeout, fetchImpl.bind(globalThis), origin, modelHeaders(options));
+}
+var MODEL_FIX = "Check the model option.";
+function modelHeaders({ model }) {
+  if (!model) return {};
+  const fields = [
+    ["provider", "X-Oya-Llm-Provider"],
+    ["name", "X-Oya-Llm-Model"],
+    ["apiKey", "X-Oya-Llm-Api-Key"]
+  ];
+  const set = fields.filter(([field]) => model[field]);
+  return Object.fromEntries(set.map(([field, name]) => [name, headerSafe(model[field], `model.${field}`, MODEL_FIX)]));
 }
 var LOCAL_HOST = /^(localhost|127\.)/i;
 function webAddress({ value, from }) {

package/dist/index.d.cts

@@ -986,6 +986,7 @@ interface ControlOverview {
 /**
  * The options the `Oya` client is constructed with.
  */
+
 /** How to reach the control plane, and as whom. */
 interface OyaOptions {
     /** Defaults to OYA_API_KEY. */
@@ -996,6 +997,28 @@ interface OyaOptions {
     timeoutMs?: number;
     /** A fetch to use instead of the global one, for tests, proxies or old runtimes. */
     fetch?: typeof globalThis.fetch;
+    /**
+     * The model behind `ask()`, `extract()`, runs and healed replays, for this client
+     * only. Left out, the key's saved model is used (`oya init`, the console).
+     */
+    model?: ModelOptions;
+}
+/**
+ * A model picked in code, sent with every call and never saved to the key, so the
+ * console and the desktop app keep theirs.
+ */
+interface ModelOptions {
+    /** Whose model. */
+    provider: LlmProvider;
+    /** The model id, e.g. 'claude-sonnet-5'. The provider's default when left out. */
+    name?: string;
+    /**
+     * Your own key for that provider: calls go to the provider's own endpoint and are
+     * billed to you. Without one, `name` runs on the credential your key already uses
+     * (its saved one, else the server's), which must be `provider`'s; the server's own
+     * offers its priced models only.
+     */
+    apiKey?: string;
 }
 /** What `Oya.signup()` takes. */
 interface SignupOptions {
@@ -1045,8 +1068,9 @@ declare class Http {
     private readonly timeoutMs;
     private readonly fetchImpl;
     readonly origin: Origin;
+    private readonly defaults;
     /** 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);
+    constructor(baseUrl: string, apiKey: string, timeoutMs: number, fetchImpl: typeof globalThis.fetch, origin?: Origin, defaults?: Record<string, string>);
     /** 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. */
@@ -1657,4 +1681,4 @@ declare class Oya {
 }
 
 export { Browser, MAX_FILE_BYTES, Oya, OyaError, Run, Oya as default, file };
-export type { Activity, Analysis, AnalyzeOptions, AttentionRequest, Block, BrowserDetail, BrowserInfo, CaptchaResult, CaptchaSolver, Config, ConfigUpdate, ControlCredential, ControlEvent, ControlOverview, ControlRole, ControlSession, Cookie, CookieFormat, DesktopOptions, EcsAuth, EcsConfig, Element, FileValue, Fingerprint, Health, HumanInputAction, ImportOptions, LlmCatalogEntry, LlmProvider, MfaConfig, MfaResult, OyaOptions, PageFormat, PersonaGroup, PersonaInfo, PersonaPrefs, PlayResult, Playbook, PlaybookAnswer, PlaybookExport, PlaybookSummary, ProjectSettings, Provider, ProxyCreate, ProxyInfo, RecoverOptions, RunData, RunInfo, RunResult, SandboxRuntime, Signup, SignupOptions, SiteCredentials, StartOptions, StartResult, StopResult, SubmitOptions };
+export type { Activity, Analysis, AnalyzeOptions, AttentionRequest, Block, BrowserDetail, BrowserInfo, CaptchaResult, CaptchaSolver, Config, ConfigUpdate, ControlCredential, ControlEvent, ControlOverview, ControlRole, ControlSession, Cookie, CookieFormat, DesktopOptions, EcsAuth, EcsConfig, Element, FileValue, Fingerprint, Health, HumanInputAction, ImportOptions, LlmCatalogEntry, LlmProvider, MfaConfig, MfaResult, ModelOptions, OyaOptions, PageFormat, PersonaGroup, PersonaInfo, PersonaPrefs, PlayResult, Playbook, PlaybookAnswer, PlaybookExport, PlaybookSummary, ProjectSettings, Provider, ProxyCreate, ProxyInfo, RecoverOptions, RunData, RunInfo, RunResult, SandboxRuntime, Signup, SignupOptions, SiteCredentials, StartOptions, StartResult, StopResult, SubmitOptions };

package/dist/index.d.ts

@@ -986,6 +986,7 @@ interface ControlOverview {
 /**
  * The options the `Oya` client is constructed with.
  */
+
 /** How to reach the control plane, and as whom. */
 interface OyaOptions {
     /** Defaults to OYA_API_KEY. */
@@ -996,6 +997,28 @@ interface OyaOptions {
     timeoutMs?: number;
     /** A fetch to use instead of the global one, for tests, proxies or old runtimes. */
     fetch?: typeof globalThis.fetch;
+    /**
+     * The model behind `ask()`, `extract()`, runs and healed replays, for this client
+     * only. Left out, the key's saved model is used (`oya init`, the console).
+     */
+    model?: ModelOptions;
+}
+/**
+ * A model picked in code, sent with every call and never saved to the key, so the
+ * console and the desktop app keep theirs.
+ */
+interface ModelOptions {
+    /** Whose model. */
+    provider: LlmProvider;
+    /** The model id, e.g. 'claude-sonnet-5'. The provider's default when left out. */
+    name?: string;
+    /**
+     * Your own key for that provider: calls go to the provider's own endpoint and are
+     * billed to you. Without one, `name` runs on the credential your key already uses
+     * (its saved one, else the server's), which must be `provider`'s; the server's own
+     * offers its priced models only.
+     */
+    apiKey?: string;
 }
 /** What `Oya.signup()` takes. */
 interface SignupOptions {
@@ -1045,8 +1068,9 @@ declare class Http {
     private readonly timeoutMs;
     private readonly fetchImpl;
     readonly origin: Origin;
+    private readonly defaults;
     /** 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);
+    constructor(baseUrl: string, apiKey: string, timeoutMs: number, fetchImpl: typeof globalThis.fetch, origin?: Origin, defaults?: Record<string, string>);
     /** 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. */
@@ -1657,4 +1681,4 @@ declare class Oya {
 }
 
 export { Browser, MAX_FILE_BYTES, Oya, OyaError, Run, Oya as default, file };
-export type { Activity, Analysis, AnalyzeOptions, AttentionRequest, Block, BrowserDetail, BrowserInfo, CaptchaResult, CaptchaSolver, Config, ConfigUpdate, ControlCredential, ControlEvent, ControlOverview, ControlRole, ControlSession, Cookie, CookieFormat, DesktopOptions, EcsAuth, EcsConfig, Element, FileValue, Fingerprint, Health, HumanInputAction, ImportOptions, LlmCatalogEntry, LlmProvider, MfaConfig, MfaResult, OyaOptions, PageFormat, PersonaGroup, PersonaInfo, PersonaPrefs, PlayResult, Playbook, PlaybookAnswer, PlaybookExport, PlaybookSummary, ProjectSettings, Provider, ProxyCreate, ProxyInfo, RecoverOptions, RunData, RunInfo, RunResult, SandboxRuntime, Signup, SignupOptions, SiteCredentials, StartOptions, StartResult, StopResult, SubmitOptions };
+export type { Activity, Analysis, AnalyzeOptions, AttentionRequest, Block, BrowserDetail, BrowserInfo, CaptchaResult, CaptchaSolver, Config, ConfigUpdate, ControlCredential, ControlEvent, ControlOverview, ControlRole, ControlSession, Cookie, CookieFormat, DesktopOptions, EcsAuth, EcsConfig, Element, FileValue, Fingerprint, Health, HumanInputAction, ImportOptions, LlmCatalogEntry, LlmProvider, MfaConfig, MfaResult, ModelOptions, OyaOptions, PageFormat, PersonaGroup, PersonaInfo, PersonaPrefs, PlayResult, Playbook, PlaybookAnswer, PlaybookExport, PlaybookSummary, ProjectSettings, Provider, ProxyCreate, ProxyInfo, RecoverOptions, RunData, RunInfo, RunResult, SandboxRuntime, Signup, SignupOptions, SiteCredentials, StartOptions, StartResult, StopResult, SubmitOptions };

package/dist/index.js

@@ -99,18 +99,20 @@ function saveKey(apiKey, baseUrl) {
 var OPTIONS_ORIGIN = { apiKeyFrom: "the apiKey option", baseUrlFrom: "the baseUrl option", savedKey: false };
 var Http = class {
   /** 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, apiKey, timeoutMs, fetchImpl, origin = OPTIONS_ORIGIN) {
+  constructor(baseUrl, apiKey, timeoutMs, fetchImpl, origin = OPTIONS_ORIGIN, defaults = {}) {
     this.baseUrl = baseUrl;
     this.apiKey = apiKey;
     this.timeoutMs = timeoutMs;
     this.fetchImpl = fetchImpl;
     this.origin = origin;
+    this.defaults = defaults;
   }
   baseUrl;
   apiKey;
   timeoutMs;
   fetchImpl;
   origin;
+  defaults;
   /** Sends one request and returns the parsed answer, or throws an OyaError when it failed. */
   async request(method, path, body, timeoutMs = this.timeoutMs, headers = {}) {
     const res = await this.send(`${this.baseUrl}${path}`, this.init(method, body, timeoutMs, headers), timeoutMs);
@@ -118,7 +120,11 @@ var Http = class {
   }
   /** The fetch options for one call, with this client's key on them. */
   init(method, body, timeoutMs, headers) {
-    return requestInit(method, body, timeoutMs, { Authorization: `Bearer ${this.apiKey}`, ...headers });
+    return requestInit(method, body, timeoutMs, {
+      Authorization: `Bearer ${this.apiKey}`,
+      ...this.defaults,
+      ...headers
+    });
   }
   /**
    * fetch's own failures say only "fetch failed" or "The operation was
@@ -203,7 +209,7 @@ function deploymentOf(url) {
   }
 }
 function noKey(saved, address) {
-  if (!saved.apiKey) return "No API key. Pass { apiKey }, set OYA_API_KEY, or run `npx @oya-ai/cli login`.";
+  if (!saved.apiKey) return "No API key. Get one at https://oyabrowser.com, then set OYA_API_KEY or pass { apiKey }.";
   const why = `the key saved in ~/.oya/config.json is for ${saved.baseUrl} and is only sent there`;
   return `No API key for ${address}: ${why}. Pass { apiKey }, set OYA_API_KEY, or run \`npx @oya-ai/cli login --url ${address}\`.`;
 }
@@ -215,7 +221,18 @@ function createHttp(options) {
   if (!fetchImpl) throw new Error("No fetch available, pass { fetch } or use Node 18+.");
   const origin = { apiKeyFrom: key.from, baseUrlFrom: address.from, savedKey: !!saved.apiKey };
   const timeout = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-  return new Http(webAddress(address), key.value, timeout, fetchImpl.bind(globalThis), origin);
+  return new Http(webAddress(address), key.value, timeout, fetchImpl.bind(globalThis), origin, modelHeaders(options));
+}
+var MODEL_FIX = "Check the model option.";
+function modelHeaders({ model }) {
+  if (!model) return {};
+  const fields = [
+    ["provider", "X-Oya-Llm-Provider"],
+    ["name", "X-Oya-Llm-Model"],
+    ["apiKey", "X-Oya-Llm-Api-Key"]
+  ];
+  const set = fields.filter(([field]) => model[field]);
+  return Object.fromEntries(set.map(([field, name]) => [name, headerSafe(model[field], `model.${field}`, MODEL_FIX)]));
 }
 var LOCAL_HOST = /^(localhost|127\.)/i;
 function webAddress({ value, from }) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oya-ai/browser",
-  "version": "1.0.209",
+  "version": "1.0.213",
   "description": "Rotate thousands of browsers behind one API, personas, proxies, stealth, CAPTCHA and MFA.",
   "license": "MIT",
   "homepage": "https://oyabrowser.com",