@oya-ai/browser 1.0.86 → 1.0.88

package/README.md

@@ -150,6 +150,28 @@ Use `{{name}}` references in prompts instead of interpolating values into the pr
 
 For prompt runs, pass credentials in `secrets`. For replay, pass all variables in `data`: the saved playbook tracks which variables are secret, including during healing. Placeholder-based inputs remain variables in the saved flow. This is not a blanket redaction guarantee for page content, screenshots, agent replies, or application logs; inspect exported code before sharing it.
 
+### Files
+
+`file()` puts a file in `data`. The agent attaches it with its upload tool: hand it the element id of whatever you can see — the "Choose file" button, the drop zone, the field itself — and the real `<input type="file">` is found from there, including the hidden ones most upload widgets use.
+
+```js
+import { Oya, file } from "@oya-ai/browser";
+
+await browser.ask("Attach my resume to the application and submit it", {
+  data: { name: "Ada Lovelace", resume: await file("./cv.pdf") },
+});
+```
+
+A string argument is a path on disk (Node only); a `Blob`, a `File`, or a `Uint8Array` works anywhere. `name` sets the filename the site sees and `type` overrides the MIME guessed from the extension. The ceiling is 10MB per file, and the bytes travel inline with the run — nothing is stored server-side after it ends.
+
+Files work in `data` for `ask()`, `submit()`, and `play()`; `secrets` rejects them, because a file is never typed through a placeholder. A run recorded with `toPlaybook()` keeps the upload as a variable, so the replay takes a different file:
+
+```js
+await browser.play("job-application", { name: "Ada Lovelace", resume: await file("./other.pdf") });
+```
+
+The generated Playwright module calls `setInputFiles`, where the same variable is a plain path rather than a `file()` value.
+
 ### Review a repaired playbook
 
 Replay normally runs recorded steps without an LLM. With `autoHeal: true` (the default), a broken step can hand over to the agent, which saves a repair as `<name>:draft`. Promotion replaces the saved playbook with that draft.
@@ -179,12 +201,28 @@ const modelKey = process.env.GEMINI_API_KEY;
 if (!modelKey) throw new Error("Set GEMINI_API_KEY first.");
 const oya = new Oya();
 await oya.config.set({
-  llm_provider: "gemini", // "openai" | "anthropic" | "gemini" | "vertex"
+  llm_provider: "gemini", // LlmProvider: "openai" | "anthropic" | "gemini" | "vertex"
   openai_api_key: modelKey, // Shared field name for every supported provider.
   // chat_model: process.env.OYA_CHAT_MODEL, // Optional provider model override.
 });
 ```
 
+`config.set` takes `ConfigUpdate` and `config.get()` returns `Config`, so an editor offers the valid providers and a typo fails to compile rather than silently falling back:
+
+```ts
+import { Oya, type LlmProvider } from "@oya-ai/browser";
+
+await oya.config.set({ llm_provider: "vertx" });
+//                                   ~~~~~~~ Type '"vertx"' is not assignable to type
+//                                           'LlmProvider'. Did you mean '"vertex"'?
+
+const provider: LlmProvider = "vertex";   // for your own config plumbing
+const { effective } = await oya.config.get();
+console.log(effective.baseUrl, effective.model, effective.hasLlmKey);
+```
+
+`browser_provider` is typed as `Provider` and `captcha_solver` as `CaptchaSolver` the same way. The server enforces the same sets, so a non-TypeScript caller gets a 400 listing the valid values instead of a silent fallback. Pass `null` to clear a field.
+
 ### Gemini Enterprise (ex-Vertex AI)
 
 `llm_provider: "vertex"` targets express mode, whose API keys work against a global endpoint with no GCP project or location:

package/dist/index.cjs

@@ -21,10 +21,12 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   Browser: () => Browser,
+  MAX_FILE_BYTES: () => MAX_FILE_BYTES,
   Oya: () => Oya,
   OyaError: () => OyaError,
   Run: () => Run,
-  default: () => index_default
+  default: () => index_default,
+  file: () => file
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -203,9 +205,10 @@ var Browser = class {
     return res.text;
   }
   /**
-   * Save the last `ask()` on this browser as a named playbook. Values that came
-   * from the prompt (names, IDs, dates) become variables; `code` is the same
-   * flow as a Playwright module, to read or run yourself.
+   * 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
+   * `defaults`, so `play()` with nothing repeats the run and any one value can be
+   * swapped. `code` is the same flow as a Playwright module, to read or run yourself.
    */
   toPlaybook(name) {
     return this.http.request("POST", `/api/browsers/${this.id}/playbooks`, { name }, 12e4);
@@ -376,6 +379,63 @@ var Run = class {
   }
 };
 
+// src/file.ts
+var MAX_FILE_BYTES = 10 * 1024 * 1024;
+var NODE_FS = "node:fs/promises";
+var MIME = {
+  pdf: "application/pdf",
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  gif: "image/gif",
+  webp: "image/webp",
+  svg: "image/svg+xml",
+  heic: "image/heic",
+  txt: "text/plain",
+  csv: "text/csv",
+  json: "application/json",
+  xml: "application/xml",
+  html: "text/html",
+  doc: "application/msword",
+  docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  xls: "application/vnd.ms-excel",
+  xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  ppt: "application/vnd.ms-powerpoint",
+  pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+  zip: "application/zip"
+};
+var base64 = (bytes) => {
+  const buffer = globalThis.Buffer;
+  if (buffer) return buffer.from(bytes).toString("base64");
+  let binary = "";
+  for (let i = 0; i < bytes.length; i += 8192) binary += String.fromCharCode(...bytes.subarray(i, i + 8192));
+  return btoa(binary);
+};
+async function file(source, options = {}) {
+  let bytes;
+  let name = options.name;
+  if (typeof source === "string") {
+    const fs = await import(
+      /* webpackIgnore: true */
+      /* @vite-ignore */
+      NODE_FS
+    );
+    bytes = new Uint8Array(await fs.readFile(source));
+    name ||= source.split(/[\\/]/).pop() || "file";
+  } else if (source instanceof Uint8Array) {
+    bytes = source;
+  } else {
+    bytes = new Uint8Array(await source.arrayBuffer());
+    name ||= source.name;
+  }
+  name ||= "file";
+  if (bytes.length > MAX_FILE_BYTES) {
+    throw new Error(`${name} is ${Math.round(bytes.length / 1024 / 1024)}MB; the limit for a task file is ${MAX_FILE_BYTES / 1024 / 1024}MB.`);
+  }
+  const ext = name.includes(".") ? name.split(".").pop().toLowerCase() : "";
+  return { file: name, type: options.type || MIME[ext] || "application/octet-stream", b64: base64(bytes) };
+}
+
 // src/index.ts
 var DEFAULT_BASE_URL = "https://browser.getoya.ai";
 var READY_POLL_MS = 2e3;
@@ -506,10 +566,11 @@ var Oya = class {
    *
    * Bring your own LLM key (it pays for its own tokens, so no hourly chat quota applies):
    *   await oya.config.set({ llm_provider: 'gemini', openai_api_key: process.env.GEMINI_API_KEY });
-   * `llm_provider` is 'openai' | 'anthropic' | 'gemini' | 'vertex'; `chat_model` overrides
-   * its default model. 'vertex' is Gemini Enterprise (ex-Vertex AI) in express mode, which
-   * needs no GCP project; for a project-scoped endpoint, set `openai_base_url` to
-   * `.../endpoints/openapi` and pass an OAuth access token as `openai_api_key`.
+   * `llm_provider` is the {@link LlmProvider} union, so an editor offers the choices and a
+   * typo is a compile error; `chat_model` overrides its default model. 'vertex' is Gemini
+   * Enterprise (ex-Vertex AI) in express mode, which needs no GCP project; for a
+   * project-scoped endpoint, set `openai_base_url` to `.../endpoints/openapi` and pass an
+   * OAuth access token as `openai_api_key`. See {@link ConfigUpdate} for every field.
    */
   config = {
     get: () => this.http.request("GET", "/api/config"),
@@ -540,7 +601,9 @@ var index_default = Oya;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Browser,
+  MAX_FILE_BYTES,
   Oya,
   OyaError,
-  Run
+  Run,
+  file
 });

package/dist/index.d.cts

@@ -9,6 +9,60 @@ declare class Http {
 }
 
 /** Everything the API returns or accepts, in one place. */
+/** Which model drives `ask()` and the chat API. */
+type LlmProvider = 'openai' | 'anthropic'
+/** Gemini via AI Studio. */
+ | 'gemini'
+/** Gemini Enterprise, ex-Vertex AI. Express mode by default; set `openai_base_url` to a
+ *  project-scoped `.../endpoints/openapi` endpoint to use an enterprise project. */
+ | 'vertex';
+/** Empty disables solving. */
+type CaptchaSolver = 'capsolver' | '2captcha' | '';
+/**
+ * What a key can configure. Mirrors the server's field allowlist exactly: a field not
+ * listed here is ignored rather than stored, so the type is the whole surface.
+ * `null` clears a field and falls back to the deployment default.
+ */
+interface ConfigUpdate {
+    llm_provider?: LlmProvider | null;
+    /** The credential for whichever `llm_provider` is set — the field name is shared. */
+    openai_api_key?: string | null;
+    /** Only honoured alongside this key's own `openai_api_key`. */
+    openai_base_url?: string | null;
+    /** Overrides the provider's default model. */
+    chat_model?: string | null;
+    browser_provider?: Provider | null;
+    anchor_api_key?: string | null;
+    browserbase_api_key?: string | null;
+    browserbase_project_id?: string | null;
+    steel_api_key?: string | null;
+    browseruse_api_key?: string | null;
+    cdp_ws_url?: string | null;
+    captcha_solver?: CaptchaSolver | null;
+    captcha_api_key?: string | null;
+    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'> {
+    llm_provider?: LlmProvider | '';
+    browser_provider?: Provider | '';
+    captcha_solver?: CaptchaSolver;
+    /** What this key would actually use right now, deployment defaults included. */
+    effective: {
+        baseUrl: string;
+        model: string;
+        hasLlmKey: boolean;
+    };
+    /** True when the LLM key in play belongs to the deployment, not this key. */
+    inherited: boolean;
+    has_openai_key: boolean;
+    providers: Array<{
+        id: Provider;
+        label: string;
+        needs: string[];
+        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 {
@@ -58,6 +112,8 @@ interface Playbook {
     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>;
     steps: number;
     /** The same flow as a Playwright module: `export default async function run(page, vars)`. */
     code: string;
@@ -83,12 +139,28 @@ interface PlaybookSummary extends Playbook {
         healedFrom: number;
     }) | null;
 }
+/**
+ * A file attached to a task value. Build it with `file()`, never by hand. Only `data`
+ * takes one: a file is not typed through a placeholder, so `secrets` has nothing to hide
+ * and rejects it.
+ */
+interface FileValue {
+    /** The filename the site sees. */
+    file: string;
+    /** MIME type, guessed from the extension unless you pass one. */
+    type: string;
+    /** The bytes, base64. 10MB ceiling. */
+    b64: string;
+}
 /**
  * Task values, referred to as `{{name}}` in prompts. As `data` the agent can read them
  * (to split a name or pick the right option); as `secrets` it never sees them. Either
  * way they are typed through placeholders, so playbooks store no values.
+ *
+ * A {@link FileValue} from `file()` is the exception: the agent attaches it with its
+ * upload tool rather than typing it.
  */
-type RunData = Record<string, string | number>;
+type RunData = Record<string, string | number | FileValue>;
 interface AttentionRequest {
     id: string;
     /** captcha / mfa: finish it in the live view. agent: the agent's question. heal_failed: replay and the agent both gave up. */
@@ -444,9 +516,10 @@ declare class Browser {
         secrets?: RunData;
     }): Promise<string>;
     /**
-     * Save the last `ask()` on this browser as a named playbook. Values that came
-     * from the prompt (names, IDs, dates) become variables; `code` is the same
-     * flow as a Playwright module, to read or run yourself.
+     * 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
+     * `defaults`, so `play()` with nothing repeats the run and any one value can be
+     * swapped. `code` is the same flow as a Playwright module, to read or run yourself.
      */
     toPlaybook(name: string): Promise<Playbook>;
     /**
@@ -535,6 +608,28 @@ declare class Run {
     private watch;
 }
 
+/**
+ * Files as task values.
+ *
+ *   await browser.ask('Attach my resume', { data: { resume: await file('./cv.pdf') } });
+ *
+ * The bytes ride inline in the run request, so the agent's `upload_file` tool can put
+ * them into a page's file input. `secrets` cannot hold one — a file is never typed
+ * through a placeholder, so there is nothing to hide.
+ */
+
+/** Bigger than this and the server would refuse the body anyway. */
+declare const MAX_FILE_BYTES: number;
+/**
+ * A file for `data`. A string is a path on disk (Node only); a Blob, a File or raw bytes
+ * work anywhere. `name` is what the site sees, and `type` overrides the MIME guessed
+ * from the extension.
+ */
+declare function file(source: string | Uint8Array | Blob, options?: {
+    name?: string;
+    type?: string;
+}): Promise<FileValue>;
+
 /**
  * @oya-ai/browser — thousands of browsers, one API.
  *
@@ -699,14 +794,15 @@ declare class Oya {
      *
      * Bring your own LLM key (it pays for its own tokens, so no hourly chat quota applies):
      *   await oya.config.set({ llm_provider: 'gemini', openai_api_key: process.env.GEMINI_API_KEY });
-     * `llm_provider` is 'openai' | 'anthropic' | 'gemini' | 'vertex'; `chat_model` overrides
-     * its default model. 'vertex' is Gemini Enterprise (ex-Vertex AI) in express mode, which
-     * needs no GCP project; for a project-scoped endpoint, set `openai_base_url` to
-     * `.../endpoints/openapi` and pass an OAuth access token as `openai_api_key`.
+     * `llm_provider` is the {@link LlmProvider} union, so an editor offers the choices and a
+     * typo is a compile error; `chat_model` overrides its default model. 'vertex' is Gemini
+     * Enterprise (ex-Vertex AI) in express mode, which needs no GCP project; for a
+     * project-scoped endpoint, set `openai_base_url` to `.../endpoints/openapi` and pass an
+     * OAuth access token as `openai_api_key`. See {@link ConfigUpdate} for every field.
      */
     readonly config: {
-        get: <T = Record<string, unknown>>() => Promise<T>;
-        set: <T = Record<string, unknown>>(values: Record<string, unknown>) => Promise<T>;
+        get: <T = Config>() => Promise<T>;
+        set: <T = Config>(values: ConfigUpdate) => Promise<T>;
     };
     /** Saved profiles. `personas` is retained as an alias for existing clients. */
     readonly profiles: {
@@ -764,4 +860,4 @@ declare class Oya {
     private waitUntilConnected;
 }
 
-export { type Activity, type Analysis, type AttentionRequest, 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 PlayResult, type Playbook, type PlaybookSummary, type ProjectSettings, type Provider, type ProxyCreate, type ProxyInfo, Run, type RunData, type RunInfo, type RunResult, type StartOptions, type StartResult, type StopResult, type SubmitOptions, Oya as default };
+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 StartOptions, type StartResult, type StopResult, type SubmitOptions, Oya as default, file };

package/dist/index.d.ts

@@ -9,6 +9,60 @@ declare class Http {
 }
 
 /** Everything the API returns or accepts, in one place. */
+/** Which model drives `ask()` and the chat API. */
+type LlmProvider = 'openai' | 'anthropic'
+/** Gemini via AI Studio. */
+ | 'gemini'
+/** Gemini Enterprise, ex-Vertex AI. Express mode by default; set `openai_base_url` to a
+ *  project-scoped `.../endpoints/openapi` endpoint to use an enterprise project. */
+ | 'vertex';
+/** Empty disables solving. */
+type CaptchaSolver = 'capsolver' | '2captcha' | '';
+/**
+ * What a key can configure. Mirrors the server's field allowlist exactly: a field not
+ * listed here is ignored rather than stored, so the type is the whole surface.
+ * `null` clears a field and falls back to the deployment default.
+ */
+interface ConfigUpdate {
+    llm_provider?: LlmProvider | null;
+    /** The credential for whichever `llm_provider` is set — the field name is shared. */
+    openai_api_key?: string | null;
+    /** Only honoured alongside this key's own `openai_api_key`. */
+    openai_base_url?: string | null;
+    /** Overrides the provider's default model. */
+    chat_model?: string | null;
+    browser_provider?: Provider | null;
+    anchor_api_key?: string | null;
+    browserbase_api_key?: string | null;
+    browserbase_project_id?: string | null;
+    steel_api_key?: string | null;
+    browseruse_api_key?: string | null;
+    cdp_ws_url?: string | null;
+    captcha_solver?: CaptchaSolver | null;
+    captcha_api_key?: string | null;
+    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'> {
+    llm_provider?: LlmProvider | '';
+    browser_provider?: Provider | '';
+    captcha_solver?: CaptchaSolver;
+    /** What this key would actually use right now, deployment defaults included. */
+    effective: {
+        baseUrl: string;
+        model: string;
+        hasLlmKey: boolean;
+    };
+    /** True when the LLM key in play belongs to the deployment, not this key. */
+    inherited: boolean;
+    has_openai_key: boolean;
+    providers: Array<{
+        id: Provider;
+        label: string;
+        needs: string[];
+        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 {
@@ -58,6 +112,8 @@ interface Playbook {
     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>;
     steps: number;
     /** The same flow as a Playwright module: `export default async function run(page, vars)`. */
     code: string;
@@ -83,12 +139,28 @@ interface PlaybookSummary extends Playbook {
         healedFrom: number;
     }) | null;
 }
+/**
+ * A file attached to a task value. Build it with `file()`, never by hand. Only `data`
+ * takes one: a file is not typed through a placeholder, so `secrets` has nothing to hide
+ * and rejects it.
+ */
+interface FileValue {
+    /** The filename the site sees. */
+    file: string;
+    /** MIME type, guessed from the extension unless you pass one. */
+    type: string;
+    /** The bytes, base64. 10MB ceiling. */
+    b64: string;
+}
 /**
  * Task values, referred to as `{{name}}` in prompts. As `data` the agent can read them
  * (to split a name or pick the right option); as `secrets` it never sees them. Either
  * way they are typed through placeholders, so playbooks store no values.
+ *
+ * A {@link FileValue} from `file()` is the exception: the agent attaches it with its
+ * upload tool rather than typing it.
  */
-type RunData = Record<string, string | number>;
+type RunData = Record<string, string | number | FileValue>;
 interface AttentionRequest {
     id: string;
     /** captcha / mfa: finish it in the live view. agent: the agent's question. heal_failed: replay and the agent both gave up. */
@@ -444,9 +516,10 @@ declare class Browser {
         secrets?: RunData;
     }): Promise<string>;
     /**
-     * Save the last `ask()` on this browser as a named playbook. Values that came
-     * from the prompt (names, IDs, dates) become variables; `code` is the same
-     * flow as a Playwright module, to read or run yourself.
+     * 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
+     * `defaults`, so `play()` with nothing repeats the run and any one value can be
+     * swapped. `code` is the same flow as a Playwright module, to read or run yourself.
      */
     toPlaybook(name: string): Promise<Playbook>;
     /**
@@ -535,6 +608,28 @@ declare class Run {
     private watch;
 }
 
+/**
+ * Files as task values.
+ *
+ *   await browser.ask('Attach my resume', { data: { resume: await file('./cv.pdf') } });
+ *
+ * The bytes ride inline in the run request, so the agent's `upload_file` tool can put
+ * them into a page's file input. `secrets` cannot hold one — a file is never typed
+ * through a placeholder, so there is nothing to hide.
+ */
+
+/** Bigger than this and the server would refuse the body anyway. */
+declare const MAX_FILE_BYTES: number;
+/**
+ * A file for `data`. A string is a path on disk (Node only); a Blob, a File or raw bytes
+ * work anywhere. `name` is what the site sees, and `type` overrides the MIME guessed
+ * from the extension.
+ */
+declare function file(source: string | Uint8Array | Blob, options?: {
+    name?: string;
+    type?: string;
+}): Promise<FileValue>;
+
 /**
  * @oya-ai/browser — thousands of browsers, one API.
  *
@@ -699,14 +794,15 @@ declare class Oya {
      *
      * Bring your own LLM key (it pays for its own tokens, so no hourly chat quota applies):
      *   await oya.config.set({ llm_provider: 'gemini', openai_api_key: process.env.GEMINI_API_KEY });
-     * `llm_provider` is 'openai' | 'anthropic' | 'gemini' | 'vertex'; `chat_model` overrides
-     * its default model. 'vertex' is Gemini Enterprise (ex-Vertex AI) in express mode, which
-     * needs no GCP project; for a project-scoped endpoint, set `openai_base_url` to
-     * `.../endpoints/openapi` and pass an OAuth access token as `openai_api_key`.
+     * `llm_provider` is the {@link LlmProvider} union, so an editor offers the choices and a
+     * typo is a compile error; `chat_model` overrides its default model. 'vertex' is Gemini
+     * Enterprise (ex-Vertex AI) in express mode, which needs no GCP project; for a
+     * project-scoped endpoint, set `openai_base_url` to `.../endpoints/openapi` and pass an
+     * OAuth access token as `openai_api_key`. See {@link ConfigUpdate} for every field.
      */
     readonly config: {
-        get: <T = Record<string, unknown>>() => Promise<T>;
-        set: <T = Record<string, unknown>>(values: Record<string, unknown>) => Promise<T>;
+        get: <T = Config>() => Promise<T>;
+        set: <T = Config>(values: ConfigUpdate) => Promise<T>;
     };
     /** Saved profiles. `personas` is retained as an alias for existing clients. */
     readonly profiles: {
@@ -764,4 +860,4 @@ declare class Oya {
     private waitUntilConnected;
 }
 
-export { type Activity, type Analysis, type AttentionRequest, 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 PlayResult, type Playbook, type PlaybookSummary, type ProjectSettings, type Provider, type ProxyCreate, type ProxyInfo, Run, type RunData, type RunInfo, type RunResult, type StartOptions, type StartResult, type StopResult, type SubmitOptions, Oya as default };
+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 StartOptions, type StartResult, type StopResult, type SubmitOptions, Oya as default, file };

package/dist/index.js

@@ -173,9 +173,10 @@ var Browser = class {
     return res.text;
   }
   /**
-   * Save the last `ask()` on this browser as a named playbook. Values that came
-   * from the prompt (names, IDs, dates) become variables; `code` is the same
-   * flow as a Playwright module, to read or run yourself.
+   * 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
+   * `defaults`, so `play()` with nothing repeats the run and any one value can be
+   * swapped. `code` is the same flow as a Playwright module, to read or run yourself.
    */
   toPlaybook(name) {
     return this.http.request("POST", `/api/browsers/${this.id}/playbooks`, { name }, 12e4);
@@ -346,6 +347,63 @@ var Run = class {
   }
 };
 
+// src/file.ts
+var MAX_FILE_BYTES = 10 * 1024 * 1024;
+var NODE_FS = "node:fs/promises";
+var MIME = {
+  pdf: "application/pdf",
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  gif: "image/gif",
+  webp: "image/webp",
+  svg: "image/svg+xml",
+  heic: "image/heic",
+  txt: "text/plain",
+  csv: "text/csv",
+  json: "application/json",
+  xml: "application/xml",
+  html: "text/html",
+  doc: "application/msword",
+  docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  xls: "application/vnd.ms-excel",
+  xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  ppt: "application/vnd.ms-powerpoint",
+  pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+  zip: "application/zip"
+};
+var base64 = (bytes) => {
+  const buffer = globalThis.Buffer;
+  if (buffer) return buffer.from(bytes).toString("base64");
+  let binary = "";
+  for (let i = 0; i < bytes.length; i += 8192) binary += String.fromCharCode(...bytes.subarray(i, i + 8192));
+  return btoa(binary);
+};
+async function file(source, options = {}) {
+  let bytes;
+  let name = options.name;
+  if (typeof source === "string") {
+    const fs = await import(
+      /* webpackIgnore: true */
+      /* @vite-ignore */
+      NODE_FS
+    );
+    bytes = new Uint8Array(await fs.readFile(source));
+    name ||= source.split(/[\\/]/).pop() || "file";
+  } else if (source instanceof Uint8Array) {
+    bytes = source;
+  } else {
+    bytes = new Uint8Array(await source.arrayBuffer());
+    name ||= source.name;
+  }
+  name ||= "file";
+  if (bytes.length > MAX_FILE_BYTES) {
+    throw new Error(`${name} is ${Math.round(bytes.length / 1024 / 1024)}MB; the limit for a task file is ${MAX_FILE_BYTES / 1024 / 1024}MB.`);
+  }
+  const ext = name.includes(".") ? name.split(".").pop().toLowerCase() : "";
+  return { file: name, type: options.type || MIME[ext] || "application/octet-stream", b64: base64(bytes) };
+}
+
 // src/index.ts
 var DEFAULT_BASE_URL = "https://browser.getoya.ai";
 var READY_POLL_MS = 2e3;
@@ -476,10 +534,11 @@ var Oya = class {
    *
    * Bring your own LLM key (it pays for its own tokens, so no hourly chat quota applies):
    *   await oya.config.set({ llm_provider: 'gemini', openai_api_key: process.env.GEMINI_API_KEY });
-   * `llm_provider` is 'openai' | 'anthropic' | 'gemini' | 'vertex'; `chat_model` overrides
-   * its default model. 'vertex' is Gemini Enterprise (ex-Vertex AI) in express mode, which
-   * needs no GCP project; for a project-scoped endpoint, set `openai_base_url` to
-   * `.../endpoints/openapi` and pass an OAuth access token as `openai_api_key`.
+   * `llm_provider` is the {@link LlmProvider} union, so an editor offers the choices and a
+   * typo is a compile error; `chat_model` overrides its default model. 'vertex' is Gemini
+   * Enterprise (ex-Vertex AI) in express mode, which needs no GCP project; for a
+   * project-scoped endpoint, set `openai_base_url` to `.../endpoints/openapi` and pass an
+   * OAuth access token as `openai_api_key`. See {@link ConfigUpdate} for every field.
    */
   config = {
     get: () => this.http.request("GET", "/api/config"),
@@ -509,8 +568,10 @@ var Oya = class {
 var index_default = Oya;
 export {
   Browser,
+  MAX_FILE_BYTES,
   Oya,
   OyaError,
   Run,
-  index_default as default
+  index_default as default,
+  file
 };

package/package.json

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