@oya-ai/browser 1.0.110 → 1.0.111

package/README.md

@@ -310,7 +310,7 @@ await browser.goto('https://github.com/trending');
 
 // Analyze page: returns markdown and visible numbered elements
 const { markdown, elements } = await browser.analyze();
-console.log(markdown.slice(0, 300));
+console.log((markdown ?? '').slice(0, 300));
 
 // Interact using numbered element IDs:
 const firstRepo = elements.find((el) => el.tag === 'a' && el.href?.includes('/stargazers'));
@@ -468,10 +468,10 @@ const oya = new Oya({
 | `remove(id)`                                        | Delete persona and associated cookie jar                          |
 | `setMfa(id, config)`                                | Store TOTP secret (sealed at rest with AES-256-GCM)               |
 | `clearMfa(id)`                                      | Remove MFA secret from persona                                    |
-| `cookies(id, format?)` | Export the persona's logins; `'playwright'` fits `addCookies()` |
-| `importCookies(id, cookies)` | Merge cookies into the jar (from a file, a script, anywhere) |
-| `copyCookies(from, to)` | Copy one persona's logins into another |
-| `clearCookies(id)` | Forget every cookie: signs the persona out everywhere |
+| `cookies(id, format?)`                              | Export the persona's logins; `'playwright'` fits `addCookies()`   |
+| `importCookies(id, cookies)`                        | Merge cookies into the jar (from a file, a script, anywhere)      |
+| `copyCookies(from, to)`                             | Copy one persona's logins into another                            |
+| `clearCookies(id)`                                  | Forget every cookie: signs the persona out everywhere             |
 
 ### Proxies (`oya.proxies`)
 

package/dist/index.cjs

@@ -30,6 +30,47 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/constants.ts
+var DEFAULT_BASE_URL = "https://oyabrowser.com";
+var DEFAULT_TIMEOUT_MS = 6e4;
+var START_TIMEOUT_MS = 12e4;
+var READY_TIMEOUT_MS = 12e4;
+var READY_POLL_MS = 2e3;
+var NAVIGATE_TIMEOUT_MS = 12e4;
+var CHALLENGE_TIMEOUT_MS = 18e4;
+var AGENT_TIMEOUT_MS = 6e5;
+var PLAYBOOK_TIMEOUT_MS = 12e4;
+var STOP_TIMEOUT_MS = 6e4;
+var WAIT_FOR_DEFAULT_MS = 3e4;
+var WAIT_FOR_GRACE_MS = 5e3;
+var AIMED_SCROLL_AMOUNT = 500;
+var RUN_POLL_MS = 2e3;
+var MAX_RUN_POLL_ERRORS = 5;
+var BYTES_PER_MB = 1048576;
+var MAX_FILE_MB = 10;
+var BASE64_CHUNK_BYTES = 8192;
+var MS_PER_SECOND = 1e3;
+var LATIN1_MAX = 255;
+var SPACE = 32;
+var TAB = 9;
+var DEL = 127;
+var HEX = 16;
+var CODE_POINT_DIGITS = 4;
+var Status = {
+  /** The caller passed something unusable, such as a non-numeric element id. */
+  BAD_REQUEST: 400,
+  /** The server does not know that session. */
+  NOT_FOUND: 404,
+  /** The browser is in a state that needs attention first. */
+  CONFLICT: 409,
+  /** A browser command ran and failed. */
+  UNPROCESSABLE: 422,
+  /** A run failed without saying why. */
+  SERVER_ERROR: 500,
+  /** A browser did not come up in time. */
+  GATEWAY_TIMEOUT: 504
+};
+
 // src/errors.ts
 var OyaError = class extends Error {
   /** The HTTP status, or the SDK's own status for errors it raises itself. */
@@ -44,6 +85,10 @@ var OyaError = class extends Error {
     this.body = body;
   }
 };
+function refusal(message, field, suggestion) {
+  const body = { error: message, code: "invalid_request", field, ...suggestion ? { suggestion } : {} };
+  return new OyaError(message, Status.BAD_REQUEST, body);
+}
 
 // src/cli-config.ts
 var node = () => globalThis.process;
@@ -67,58 +112,26 @@ function savedConfig() {
   }
 }
 
-// src/constants.ts
-var DEFAULT_BASE_URL = "https://oyabrowser.com";
-var DEFAULT_TIMEOUT_MS = 6e4;
-var START_TIMEOUT_MS = 12e4;
-var READY_TIMEOUT_MS = 12e4;
-var READY_POLL_MS = 2e3;
-var NAVIGATE_TIMEOUT_MS = 12e4;
-var CHALLENGE_TIMEOUT_MS = 18e4;
-var AGENT_TIMEOUT_MS = 6e5;
-var PLAYBOOK_TIMEOUT_MS = 12e4;
-var STOP_TIMEOUT_MS = 6e4;
-var WAIT_FOR_DEFAULT_MS = 3e4;
-var WAIT_FOR_GRACE_MS = 5e3;
-var AIMED_SCROLL_AMOUNT = 500;
-var RUN_POLL_MS = 2e3;
-var MAX_RUN_POLL_ERRORS = 5;
-var BYTES_PER_MB = 1048576;
-var MAX_FILE_MB = 10;
-var BASE64_CHUNK_BYTES = 8192;
-var MS_PER_SECOND = 1e3;
-var Status = {
-  /** The caller passed something unusable, such as a non-numeric element id. */
-  BAD_REQUEST: 400,
-  /** The server does not know that session. */
-  NOT_FOUND: 404,
-  /** The browser is in a state that needs attention first. */
-  CONFLICT: 409,
-  /** A browser command ran and failed. */
-  UNPROCESSABLE: 422,
-  /** A run failed without saying why. */
-  SERVER_ERROR: 500,
-  /** A browser did not come up in time. */
-  GATEWAY_TIMEOUT: 504
-};
-
 // src/client.ts
+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 and which fetch to use. */
-  constructor(baseUrl, apiKey, timeoutMs, fetchImpl) {
+  /** 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) {
     this.baseUrl = baseUrl;
     this.apiKey = apiKey;
     this.timeoutMs = timeoutMs;
     this.fetchImpl = fetchImpl;
+    this.origin = origin;
   }
   baseUrl;
   apiKey;
   timeoutMs;
   fetchImpl;
+  origin;
   /** 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);
-    return readAnswer(res, `${method} ${path}`, this.baseUrl);
+    return readAnswer(res, `${method} ${path}`, this);
   }
   /** The fetch options for one call, with this client's key on them. */
   init(method, body, timeoutMs, headers) {
@@ -133,23 +146,34 @@ var Http = class {
     try {
       return await this.fetchImpl(url, init);
     } catch (err) {
-      throw new OyaError(unreachable(this.baseUrl, timeoutMs, err), 0, { error: String(err?.message) });
+      throw noAnswer(this, timeoutMs, err);
     }
   }
 };
-function unreachable(baseUrl, timeoutMs, err) {
-  const cause = err?.name === "TimeoutError" || /abort/i.test(String(err?.message));
-  if (cause) return `No answer from ${baseUrl} within ${timeoutMs}ms. Is it reachable, and is the call this slow?`;
-  return `Could not reach ${baseUrl}. Is the server running, and is OYA_BASE_URL right?`;
+var timedOut = (err) => err?.name === "TimeoutError" || /abort/i.test(String(err?.message));
+function causeOf(err) {
+  const cause = err?.cause;
+  return cause?.code ?? cause?.errors?.[0]?.code;
+}
+function noAnswer(http, timeoutMs, err) {
+  const code = timedOut(err) ? "timeout" : "unreachable";
+  const body = { error: String(err?.message), code, ...causeOf(err) ? { cause: causeOf(err) } : {} };
+  return new OyaError(unreachable(http, timeoutMs, code), 0, body);
+}
+function unreachable({ baseUrl, origin }, timeoutMs, code) {
+  if (code === "timeout")
+    return `No answer from ${baseUrl} within ${timeoutMs}ms. Is it reachable, and is the call this slow?`;
+  if (origin.baseUrlFrom === "default") return `Could not reach ${baseUrl}. Check your connection.`;
+  return `Could not reach ${baseUrl}. Is the server running, and is ${origin.baseUrlFrom} right?`;
 }
 function requestInit(method, body, timeoutMs, headers) {
   const json = body === void 0 ? {} : { "Content-Type": "application/json" };
   const payload = body === void 0 ? void 0 : JSON.stringify(body);
   return { method, headers: { ...headers, ...json }, body: payload, signal: AbortSignal.timeout(timeoutMs) };
 }
-async function readAnswer(res, call2, baseUrl) {
+async function readAnswer(res, call2, http) {
   const payload = parseBody(await res.text());
-  if (!res.ok) throw failure(call2, res.status, payload, baseUrl);
+  if (!res.ok) throw failure(call2, res.status, payload, http);
   return payload;
 }
 function parseBody(text) {
@@ -159,22 +183,74 @@ function parseBody(text) {
     return text;
   }
 }
-function failure(call2, status, payload, baseUrl) {
-  let message = payload?.error || `${call2} failed (${status})`;
-  if (message === "Invalid API key") {
-    message += ` for ${baseUrl}. Check OYA_API_KEY: a value exported in your shell beats .env.`;
-  }
-  return new OyaError(message, status, payload);
+function failure(call2, status, payload, http) {
+  const message = payload?.error || `${call2} failed (${status})`;
+  return new OyaError(message === "Invalid API key" ? invalidKey(http) : message, status, payload);
+}
+function invalidKey({ baseUrl, origin }) {
+  const overrides = origin.apiKeyFrom === "OYA_API_KEY" && origin.savedKey;
+  const rest = overrides ? ", which overrides the one saved in ~/.oya/config.json" : "";
+  return `Invalid API key for ${baseUrl}. The key came from ${origin.apiKeyFrom}${rest}.`;
 }
 var env = (name) => globalThis.process?.env?.[name];
+function firstOf(option, name, saved, optionName) {
+  if (option) return { value: option, from: `the ${optionName} option` };
+  if (env(name)) return { value: env(name), from: name };
+  return { value: saved, from: "~/.oya/config.json" };
+}
+function addressOf(options, saved) {
+  const found = firstOf(options.baseUrl, "OYA_BASE_URL", saved, "baseUrl");
+  return found.value ? found : { value: DEFAULT_BASE_URL, from: "default" };
+}
+function keyOf(options, saved) {
+  const found = firstOf(options.apiKey, "OYA_API_KEY", saved, "apiKey");
+  if (!found.value) throw new Error("No API key. Pass { apiKey }, set OYA_API_KEY, or run `npx @oya-ai/cli login`.");
+  return { ...found, value: headerSafe(found.value, "apiKey", "Copy the key again.") };
+}
 function createHttp(options) {
   const saved = savedConfig();
-  const apiKey = options.apiKey || env("OYA_API_KEY") || saved.apiKey;
-  if (!apiKey) throw new Error("No API key. Pass { apiKey }, set OYA_API_KEY, or run `npx @oya-ai/cli login`.");
-  const baseUrl = (options.baseUrl || env("OYA_BASE_URL") || saved.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, "");
+  const key = keyOf(options, saved.apiKey);
+  const address = addressOf(options, saved.baseUrl);
   const fetchImpl = options.fetch || globalThis.fetch;
   if (!fetchImpl) throw new Error("No fetch available, pass { fetch } or use Node 18+.");
-  return new Http(baseUrl, apiKey, options.timeoutMs ?? DEFAULT_TIMEOUT_MS, fetchImpl.bind(globalThis));
+  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);
+}
+var LOCAL_HOST = /^(localhost|127\.)/i;
+function webAddress({ value, from }) {
+  const url = value.trim().replace(/\/+$/, "");
+  if (/^https?:\/\//i.test(url)) return url;
+  const name = from.startsWith("the ") ? "baseUrl" : from === "OYA_BASE_URL" ? from : `baseUrl in ${from}`;
+  const suggestion = suggestionFor(url);
+  const tryIt = suggestion ? ` Try ${suggestion}.` : "";
+  throw refusal(`${name} must start with http:// or https://, not "${url}".${tryIt}`, "baseUrl", suggestion);
+}
+function suggestionFor(url) {
+  if (/^[a-z][a-z0-9+.-]*:/i.test(url) && !/^[^:/]+:\d+(\/|$)/.test(url)) return void 0;
+  return `${LOCAL_HOST.test(url) ? "http" : "https"}://${url}`;
+}
+function notInAHeader(ch) {
+  const code = ch.codePointAt(0);
+  return code < SPACE && code !== TAB || code === DEL || code > LATIN1_MAX;
+}
+function headerSafe(value, field, ending) {
+  const trimmed = value.trim();
+  const chars = Array.from(trimmed);
+  const at = chars.findIndex(notInAHeader);
+  if (at < 0) return trimmed;
+  const leading = Array.from(value).length - Array.from(value.trimStart()).length;
+  const where = `position ${leading + at + 1} (${codePoint(chars[at])})`;
+  throw refusal(`${field} has a character HTTP headers cannot carry at ${where}. ${ending}`, field);
+}
+var codePoint = (ch) => `U+${ch.codePointAt(0).toString(HEX).toUpperCase().padStart(CODE_POINT_DIGITS, "0")}`;
+var shown = (value) => typeof value === "string" ? JSON.stringify(value) : String(value);
+function segment(value, field = "id") {
+  if (typeof value !== "string" || !value)
+    throw refusal(`${field} must be a non-empty string, not ${shown(value)}`, field);
+  if (value.includes("/") || value === "." || value === "..")
+    throw refusal(`${field} must be a single path segment (no "/" and not "." or ".."), not ${shown(value)}`, field);
+  return encodeURIComponent(value);
 }
 
 // src/run-watch.ts
@@ -413,7 +489,7 @@ var Browser = class {
    * Play `'<name>:draft'` to try a draft before promoting it.
    */
   async play(name, data = {}, { autoHeal = true } = {}) {
-    const path = `/api/browsers/${this.id}/playbooks/${encodeURIComponent(name)}/play`;
+    const path = `/api/browsers/${this.id}/playbooks/${segment(name, "name")}/play`;
     return agentAnswer(
       await this.http.request("POST", path, { variables: data, autoHeal }, AGENT_TIMEOUT_MS)
     );
@@ -464,7 +540,7 @@ var Browser = class {
   }
   /** Revoke a link from `shareUrl()` before it expires, by the id it returned. */
   async revokeShare(id) {
-    await this.http.request("DELETE", `/api/control/credentials/${encodeURIComponent(id)}`);
+    await this.http.request("DELETE", `/api/control/credentials/${segment(id)}`);
   }
   /** Counters, health and the last 50 things this browser did. */
   status() {
@@ -520,8 +596,9 @@ function startBody(options) {
   const { profile, persona, provider, wsUrl, name, queueMs, priority, budgetUsd, governed, policy } = options;
   return { profile: profile || persona, provider, wsUrl, name, queueMs, priority, budgetUsd, governed, policy };
 }
+var idempotencyKeyOf = ({ idempotencyKey }) => idempotencyKey ? headerSafe(idempotencyKey, "idempotencyKey", 'Use letters, digits, "-" and "_".') : globalThis.crypto.randomUUID();
 async function start(http, wait, options) {
-  const headers = { "Idempotency-Key": options.idempotencyKey || globalThis.crypto.randomUUID() };
+  const headers = { "Idempotency-Key": idempotencyKeyOf(options) };
   const path = "/api/browsers/start";
   const started = await http().request("POST", path, startBody(options), START_TIMEOUT_MS, headers);
   if (started.status === "starting") {
@@ -530,7 +607,7 @@ async function start(http, wait, options) {
   }
   return new Browser(http(), started, options.captcha === "auto");
 }
-var fetchBrowser = (http, id) => http().request("GET", `/api/browsers/${encodeURIComponent(id)}`);
+var fetchBrowser = (http, id) => http().request("GET", `/api/browsers/${segment(id)}`);
 async function reattach(http, id) {
   const found = await fetchBrowser(http, id);
   return new Browser(http(), asStarted(found), false);
@@ -542,69 +619,79 @@ function asStarted(found) {
 var stopBrowsers = (http, ids) => http().request("POST", "/api/browsers/stop", ids === "all" ? { all: true } : { ids }, START_TIMEOUT_MS);
 var browserApi = (http, wait) => ({
   /** Start a browser and wait until it can take commands. */
-  start: (options = {}) => start(http, wait, options),
+  start: async (options = {}) => start(http, wait, options),
   /** Reattach to a browser that is already running. */
-  get: (id) => reattach(http, id),
+  get: async (id) => reattach(http, id),
   /** Every browser on this key. */
-  list: () => http().request("GET", "/api/browsers"),
+  list: async () => http().request("GET", "/api/browsers"),
   /** Stop some (`ids`) or every browser on this key. Each reports separately. */
-  stop: (ids) => stopBrowsers(http, ids),
+  stop: async (ids) => stopBrowsers(http, ids),
   /** Stop every browser on this key; returns how many stopped. */
   stopAll: async () => (await stopBrowsers(http, "all")).stopped
 });
 
 // src/api/control.ts
-var session = (id, action = "") => `/api/control/sessions/${encodeURIComponent(id)}${action}`;
-var item = (kind, id) => `/api/control/${kind}/${encodeURIComponent(id)}`;
+var session = (id, action = "") => `/api/control/sessions/${segment(id)}${action}`;
+var item = (kind, id) => `/api/control/${kind}/${segment(id)}`;
 var sessionCalls = (http) => ({
   /** Settings, sessions and recent events at a glance. */
-  overview: () => http().request("GET", "/api/control"),
+  overview: async () => http().request("GET", "/api/control"),
   /** Every session, including disconnected and cleanup-pending ones. */
-  sessions: () => http().request("GET", "/api/control/sessions"),
+  sessions: async () => http().request("GET", "/api/control/sessions"),
   /** One session. */
-  session: (id) => http().request("GET", session(id)),
+  session: async (id) => http().request("GET", session(id)),
   /** Update limits, rate cards and retention. */
-  settings: (changes) => http().request("PATCH", "/api/control/project", changes)
+  settings: async (changes) => http().request("PATCH", "/api/control/project", changes)
 });
 var lifecycleCalls = (http) => ({
-  /** Cancel queued or provisioning work. */
-  cancel: (id) => http().request("POST", session(id, "/cancel"), {}),
+  /** Stop a session in any state; answers its final state. */
+  cancel: async (id) => http().request("POST", session(id, "/cancel"), {}),
   /** Stop a session; `force` stops despite a profile-save error, or reconciles. */
-  stop: (id, force = false) => http().request("POST", session(id, "/stop"), { force }),
+  stop: async (id, force = false) => http().request("POST", session(id, "/stop"), { force }),
   /** Acquire or release human control, or acknowledge the agent's resume. */
-  takeover: (id, action) => http().request("POST", session(id, "/control"), { action }),
+  takeover: async (id, action) => http().request("POST", session(id, "/control"), { action }),
   /** Send one input as the human holding the control lease. */
-  input: (id, action, params) => http().request("POST", session(id, "/input"), { action, params })
+  input: async (id, action, params) => http().request("POST", session(id, "/input"), { action, params })
 });
+function recoverBody(options) {
+  const { replace = false, wsUrl } = typeof options === "boolean" ? { replace: options } : options ?? {};
+  if (wsUrl && !replace)
+    throw refusal("wsUrl is only used with replace: true; recovering in place keeps the endpoint it had.", "wsUrl");
+  return wsUrl ? { replace, wsUrl } : { replace };
+}
 var recoveryCalls = (http) => ({
-  /** Explicitly recover a session, or replace it with a fresh one. */
-  recover: (id, replace = false) => http().request("POST", session(id, "/recover"), { replace }),
+  /**
+   * Explicitly recover a session, or replace it with a fresh one. A cdp
+   * session's replacement needs the Chrome it runs on: `{ replace: true, wsUrl }`.
+   * `recover(id, true)` still means replace.
+   */
+  recover: async (id, options = {}) => http().request("POST", session(id, "/recover"), recoverBody(options)),
   /** A single-use ticket for the live stream. */
-  ticket: (id) => http().request("POST", session(id, "/ticket"), {}),
+  ticket: async (id) => http().request("POST", session(id, "/ticket"), {}),
   /** Durable lifecycle events after a cursor. */
-  events: (after = 0) => http().request("GET", `/api/control/events?after=${after}`)
+  events: async (after = 0) => http().request("GET", `/api/control/events?after=${after}`)
 });
 var credentialCalls = (http) => ({
   /** Mint a service credential. Its token is returned this once. */
-  createCredential: (options) => http().request("POST", "/api/control/credentials", options),
+  createCredential: async (options) => http().request("POST", "/api/control/credentials", options),
   /** Revoke a service credential. */
-  revokeCredential: (id) => http().request("DELETE", item("credentials", id))
+  revokeCredential: async (id) => http().request("DELETE", item("credentials", id))
 });
 var memberCalls = (http) => ({
   /** The owner and every member. */
-  members: () => http().request("GET", "/api/control/members"),
+  members: async () => http().request("GET", "/api/control/members"),
   /** An invitation code for a new member. */
-  inviteMember: (role = "operator") => http().request("POST", "/api/control/members/invite", { role }),
+  inviteMember: async (role = "operator") => http().request("POST", "/api/control/members/invite", { role }),
   /** Remove a member. */
-  removeMember: (userId) => http().request("DELETE", item("members", userId))
+  removeMember: async (userId) => http().request("DELETE", item("members", userId))
 });
 var webhookCalls = (http) => ({
   /** Register a webhook; `types` limits which events it receives. */
-  createWebhook: (url, types = []) => http().request("POST", "/api/control/webhooks", { url, types }),
+  createWebhook: async (url, types = []) => http().request("POST", "/api/control/webhooks", { url, types }),
   /** Disable a webhook. */
-  removeWebhook: (id) => http().request("DELETE", item("webhooks", id)),
+  removeWebhook: async (id) => http().request("DELETE", item("webhooks", id)),
   /** Send a delivery again. */
-  replayDelivery: (id) => http().request("POST", `${item("deliveries", id)}/replay`, {})
+  replayDelivery: async (id) => http().request("POST", `${item("deliveries", id)}/replay`, {})
 });
 var controlApi = (http) => ({
   ...sessionCalls(http),
@@ -616,7 +703,7 @@ var controlApi = (http) => ({
 });
 
 // src/api/playbooks.ts
-var playbook = (name) => `/api/playbooks/${encodeURIComponent(name)}`;
+var playbook = (name) => `/api/playbooks/${segment(name, "name")}`;
 var playbookApi = (http) => ({
   /** Every saved playbook, with any draft waiting on it. */
   list: async () => (await http().request("GET", "/api/playbooks")).playbooks,
@@ -625,7 +712,7 @@ var playbookApi = (http) => ({
     await http().request("DELETE", playbook(name));
   },
   /** Replace a playbook with the draft a healed replay saved. Try it first with `browser.play('<name>:draft')`. */
-  promote: (name) => http().request("POST", `${playbook(name)}/promote`, {})
+  promote: async (name) => http().request("POST", `${playbook(name)}/promote`, {})
 });
 
 // src/api/proxies.ts
@@ -633,10 +720,10 @@ var proxyApi = (http) => ({
   /** Every proxy this key can use, shared ones included. */
   list: async () => (await http().request("GET", "/api/proxies")).proxies,
   /** Add a proxy. Its credentials are never read back. */
-  create: (proxy) => http().request("POST", "/api/proxies", proxy),
+  create: async (proxy) => http().request("POST", "/api/proxies", proxy),
   /** Remove one of this key's proxies. */
   remove: async (id) => {
-    await http().request("DELETE", `/api/proxies/${encodeURIComponent(id)}`);
+    await http().request("DELETE", `/api/proxies/${segment(id)}`);
   },
   /** Dial each proxy and learn its real exit IP. Failing ones cool down and are skipped. */
   check: async () => (await http().request("POST", "/api/proxies/check", {})).results
@@ -647,35 +734,38 @@ var identityCalls = (http) => ({
   /** Every persona on this key. */
   list: async () => (await http().request("GET", "/api/personas")).personas,
   /** One persona. */
-  get: (id) => http().request("GET", `/api/personas/${id}`),
+  get: async (id) => http().request("GET", `/api/personas/${segment(id)}`),
   /**
    * Create an identity. The device, platform, timezone, locale, is chosen
    * here and fixed for its life; `preview()` shows what a choice produces.
    */
-  create: (options = {}) => http().request("POST", "/api/personas", options),
+  create: async (options = {}) => http().request("POST", "/api/personas", options),
   /** Name, concurrency cap and proxy hint. Never the device, clone for that. */
-  update: (id, changes) => http().request("PUT", `/api/personas/${id}`, changes),
+  update: async (id, changes) => http().request("PUT", `/api/personas/${segment(id)}`, changes),
   /** A new persona of the same kind of device: same choices, fresh identity, empty jar. */
-  clone: (id, options = {}) => http().request("POST", `/api/personas/${id}/clone`, options)
+  clone: async (id, options = {}) => http().request("POST", `/api/personas/${segment(id)}/clone`, options)
 });
 var deviceCalls = (http) => ({
   /** The fingerprint these choices would produce. Persists nothing. */
   preview: async (prefs = {}) => (await http().request("POST", "/api/personas/preview", { prefs })).fingerprint,
   /** Platforms, and the timezones and locales each may coherently claim. */
-  options: () => http().request("GET", "/api/personas/options"),
+  options: async () => http().request("GET", "/api/personas/options"),
   /** Pin the persona to one of your proxies, or `null` to let assignment happen at connect. */
-  pinProxy: (id, proxyId) => http().request("PUT", `/api/personas/${id}/proxy`, { proxyId }),
+  pinProxy: async (id, proxyId) => http().request("PUT", `/api/personas/${segment(id)}/proxy`, { proxyId }),
   /** Delete a persona. */
   remove: async (id) => {
-    await http().request("DELETE", `/api/personas/${id}`);
+    await http().request("DELETE", `/api/personas/${segment(id)}`);
   }
 });
 var mfaCalls = (http) => ({
   /** Store the second factor for this identity. Sealed at rest, never read back. */
-  setMfa: (id, config) => http().request("PUT", `/api/personas/${id}/mfa`, config),
+  setMfa: async (id, config) => http().request("PUT", `/api/personas/${segment(id)}/mfa`, config),
   /** Remove the persona-wide factor, or the one filed against `domain`. */
   clearMfa: async (id, domain) => {
-    await http().request("DELETE", `/api/personas/${id}/mfa${domain ? `?domain=${encodeURIComponent(domain)}` : ""}`);
+    await http().request(
+      "DELETE",
+      `/api/personas/${segment(id)}/mfa${domain ? `?domain=${encodeURIComponent(domain)}` : ""}`
+    );
   }
 });
 var loginCalls = (http) => ({
@@ -686,20 +776,20 @@ var loginCalls = (http) => ({
    * 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, config) => http().request("PUT", `/api/personas/${id}/credentials`, config),
+  setCredentials: async (id, config) => http().request("PUT", `/api/personas/${segment(id)}/credentials`, config),
   /** Which sites this identity can sign in to. Usernames only. */
-  credentials: (id) => http().request("GET", `/api/personas/${id}/credentials`),
+  credentials: async (id) => http().request("GET", `/api/personas/${segment(id)}/credentials`),
   /** Remove the login stored for one site. */
   clearCredentials: async (id, domain) => {
-    await http().request("DELETE", `/api/personas/${id}/credentials?domain=${encodeURIComponent(domain)}`);
+    await http().request("DELETE", `/api/personas/${segment(id)}/credentials?domain=${encodeURIComponent(domain)}`);
   }
 });
-var jarPath = (id) => `/api/pool/cookies?persona=${encodeURIComponent(id)}`;
+var jarPath = (id) => `/api/pool/cookies?persona=${segment(id)}`;
 var jarCalls = (http) => ({
   /** Every cookie in the jar; `format: 'playwright'` is ready for `context.addCookies()`. */
-  cookies: async (id, format = "json") => (await http().request("GET", `${jarPath(id)}&format=${format}`)).cookies,
+  cookies: async (id, format = "json") => (await http().request("GET", `${jarPath(id)}&format=${encodeURIComponent(format)}`)).cookies,
   /** Merge cookies into the jar. The persona's browsers pick them up on their next visit to each site. */
-  importCookies: (id, list) => http().request("PUT", jarPath(id), { cookies: list })
+  importCookies: async (id, list) => http().request("PUT", jarPath(id), { cookies: list })
 });
 var cookieCalls = (http) => ({
   ...jarCalls(http),

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. */
@@ -721,6 +719,13 @@ type CookieFormat = 'json' | 'playwright';
  */
 /** 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. */
@@ -834,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. */
@@ -1322,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>;
@@ -1413,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 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, 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. */
@@ -721,6 +719,13 @@ type CookieFormat = 'json' | 'playwright';
  */
 /** 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. */
@@ -834,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. */
@@ -1322,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>;
@@ -1413,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 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, 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.js

@@ -1,3 +1,44 @@
+// src/constants.ts
+var DEFAULT_BASE_URL = "https://oyabrowser.com";
+var DEFAULT_TIMEOUT_MS = 6e4;
+var START_TIMEOUT_MS = 12e4;
+var READY_TIMEOUT_MS = 12e4;
+var READY_POLL_MS = 2e3;
+var NAVIGATE_TIMEOUT_MS = 12e4;
+var CHALLENGE_TIMEOUT_MS = 18e4;
+var AGENT_TIMEOUT_MS = 6e5;
+var PLAYBOOK_TIMEOUT_MS = 12e4;
+var STOP_TIMEOUT_MS = 6e4;
+var WAIT_FOR_DEFAULT_MS = 3e4;
+var WAIT_FOR_GRACE_MS = 5e3;
+var AIMED_SCROLL_AMOUNT = 500;
+var RUN_POLL_MS = 2e3;
+var MAX_RUN_POLL_ERRORS = 5;
+var BYTES_PER_MB = 1048576;
+var MAX_FILE_MB = 10;
+var BASE64_CHUNK_BYTES = 8192;
+var MS_PER_SECOND = 1e3;
+var LATIN1_MAX = 255;
+var SPACE = 32;
+var TAB = 9;
+var DEL = 127;
+var HEX = 16;
+var CODE_POINT_DIGITS = 4;
+var Status = {
+  /** The caller passed something unusable, such as a non-numeric element id. */
+  BAD_REQUEST: 400,
+  /** The server does not know that session. */
+  NOT_FOUND: 404,
+  /** The browser is in a state that needs attention first. */
+  CONFLICT: 409,
+  /** A browser command ran and failed. */
+  UNPROCESSABLE: 422,
+  /** A run failed without saying why. */
+  SERVER_ERROR: 500,
+  /** A browser did not come up in time. */
+  GATEWAY_TIMEOUT: 504
+};
+
 // src/errors.ts
 var OyaError = class extends Error {
   /** The HTTP status, or the SDK's own status for errors it raises itself. */
@@ -12,6 +53,10 @@ var OyaError = class extends Error {
     this.body = body;
   }
 };
+function refusal(message, field, suggestion) {
+  const body = { error: message, code: "invalid_request", field, ...suggestion ? { suggestion } : {} };
+  return new OyaError(message, Status.BAD_REQUEST, body);
+}
 
 // src/cli-config.ts
 var node = () => globalThis.process;
@@ -35,58 +80,26 @@ function savedConfig() {
   }
 }
 
-// src/constants.ts
-var DEFAULT_BASE_URL = "https://oyabrowser.com";
-var DEFAULT_TIMEOUT_MS = 6e4;
-var START_TIMEOUT_MS = 12e4;
-var READY_TIMEOUT_MS = 12e4;
-var READY_POLL_MS = 2e3;
-var NAVIGATE_TIMEOUT_MS = 12e4;
-var CHALLENGE_TIMEOUT_MS = 18e4;
-var AGENT_TIMEOUT_MS = 6e5;
-var PLAYBOOK_TIMEOUT_MS = 12e4;
-var STOP_TIMEOUT_MS = 6e4;
-var WAIT_FOR_DEFAULT_MS = 3e4;
-var WAIT_FOR_GRACE_MS = 5e3;
-var AIMED_SCROLL_AMOUNT = 500;
-var RUN_POLL_MS = 2e3;
-var MAX_RUN_POLL_ERRORS = 5;
-var BYTES_PER_MB = 1048576;
-var MAX_FILE_MB = 10;
-var BASE64_CHUNK_BYTES = 8192;
-var MS_PER_SECOND = 1e3;
-var Status = {
-  /** The caller passed something unusable, such as a non-numeric element id. */
-  BAD_REQUEST: 400,
-  /** The server does not know that session. */
-  NOT_FOUND: 404,
-  /** The browser is in a state that needs attention first. */
-  CONFLICT: 409,
-  /** A browser command ran and failed. */
-  UNPROCESSABLE: 422,
-  /** A run failed without saying why. */
-  SERVER_ERROR: 500,
-  /** A browser did not come up in time. */
-  GATEWAY_TIMEOUT: 504
-};
-
 // src/client.ts
+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 and which fetch to use. */
-  constructor(baseUrl, apiKey, timeoutMs, fetchImpl) {
+  /** 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) {
     this.baseUrl = baseUrl;
     this.apiKey = apiKey;
     this.timeoutMs = timeoutMs;
     this.fetchImpl = fetchImpl;
+    this.origin = origin;
   }
   baseUrl;
   apiKey;
   timeoutMs;
   fetchImpl;
+  origin;
   /** 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);
-    return readAnswer(res, `${method} ${path}`, this.baseUrl);
+    return readAnswer(res, `${method} ${path}`, this);
   }
   /** The fetch options for one call, with this client's key on them. */
   init(method, body, timeoutMs, headers) {
@@ -101,23 +114,34 @@ var Http = class {
     try {
       return await this.fetchImpl(url, init);
     } catch (err) {
-      throw new OyaError(unreachable(this.baseUrl, timeoutMs, err), 0, { error: String(err?.message) });
+      throw noAnswer(this, timeoutMs, err);
     }
   }
 };
-function unreachable(baseUrl, timeoutMs, err) {
-  const cause = err?.name === "TimeoutError" || /abort/i.test(String(err?.message));
-  if (cause) return `No answer from ${baseUrl} within ${timeoutMs}ms. Is it reachable, and is the call this slow?`;
-  return `Could not reach ${baseUrl}. Is the server running, and is OYA_BASE_URL right?`;
+var timedOut = (err) => err?.name === "TimeoutError" || /abort/i.test(String(err?.message));
+function causeOf(err) {
+  const cause = err?.cause;
+  return cause?.code ?? cause?.errors?.[0]?.code;
+}
+function noAnswer(http, timeoutMs, err) {
+  const code = timedOut(err) ? "timeout" : "unreachable";
+  const body = { error: String(err?.message), code, ...causeOf(err) ? { cause: causeOf(err) } : {} };
+  return new OyaError(unreachable(http, timeoutMs, code), 0, body);
+}
+function unreachable({ baseUrl, origin }, timeoutMs, code) {
+  if (code === "timeout")
+    return `No answer from ${baseUrl} within ${timeoutMs}ms. Is it reachable, and is the call this slow?`;
+  if (origin.baseUrlFrom === "default") return `Could not reach ${baseUrl}. Check your connection.`;
+  return `Could not reach ${baseUrl}. Is the server running, and is ${origin.baseUrlFrom} right?`;
 }
 function requestInit(method, body, timeoutMs, headers) {
   const json = body === void 0 ? {} : { "Content-Type": "application/json" };
   const payload = body === void 0 ? void 0 : JSON.stringify(body);
   return { method, headers: { ...headers, ...json }, body: payload, signal: AbortSignal.timeout(timeoutMs) };
 }
-async function readAnswer(res, call2, baseUrl) {
+async function readAnswer(res, call2, http) {
   const payload = parseBody(await res.text());
-  if (!res.ok) throw failure(call2, res.status, payload, baseUrl);
+  if (!res.ok) throw failure(call2, res.status, payload, http);
   return payload;
 }
 function parseBody(text) {
@@ -127,22 +151,74 @@ function parseBody(text) {
     return text;
   }
 }
-function failure(call2, status, payload, baseUrl) {
-  let message = payload?.error || `${call2} failed (${status})`;
-  if (message === "Invalid API key") {
-    message += ` for ${baseUrl}. Check OYA_API_KEY: a value exported in your shell beats .env.`;
-  }
-  return new OyaError(message, status, payload);
+function failure(call2, status, payload, http) {
+  const message = payload?.error || `${call2} failed (${status})`;
+  return new OyaError(message === "Invalid API key" ? invalidKey(http) : message, status, payload);
+}
+function invalidKey({ baseUrl, origin }) {
+  const overrides = origin.apiKeyFrom === "OYA_API_KEY" && origin.savedKey;
+  const rest = overrides ? ", which overrides the one saved in ~/.oya/config.json" : "";
+  return `Invalid API key for ${baseUrl}. The key came from ${origin.apiKeyFrom}${rest}.`;
 }
 var env = (name) => globalThis.process?.env?.[name];
+function firstOf(option, name, saved, optionName) {
+  if (option) return { value: option, from: `the ${optionName} option` };
+  if (env(name)) return { value: env(name), from: name };
+  return { value: saved, from: "~/.oya/config.json" };
+}
+function addressOf(options, saved) {
+  const found = firstOf(options.baseUrl, "OYA_BASE_URL", saved, "baseUrl");
+  return found.value ? found : { value: DEFAULT_BASE_URL, from: "default" };
+}
+function keyOf(options, saved) {
+  const found = firstOf(options.apiKey, "OYA_API_KEY", saved, "apiKey");
+  if (!found.value) throw new Error("No API key. Pass { apiKey }, set OYA_API_KEY, or run `npx @oya-ai/cli login`.");
+  return { ...found, value: headerSafe(found.value, "apiKey", "Copy the key again.") };
+}
 function createHttp(options) {
   const saved = savedConfig();
-  const apiKey = options.apiKey || env("OYA_API_KEY") || saved.apiKey;
-  if (!apiKey) throw new Error("No API key. Pass { apiKey }, set OYA_API_KEY, or run `npx @oya-ai/cli login`.");
-  const baseUrl = (options.baseUrl || env("OYA_BASE_URL") || saved.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, "");
+  const key = keyOf(options, saved.apiKey);
+  const address = addressOf(options, saved.baseUrl);
   const fetchImpl = options.fetch || globalThis.fetch;
   if (!fetchImpl) throw new Error("No fetch available, pass { fetch } or use Node 18+.");
-  return new Http(baseUrl, apiKey, options.timeoutMs ?? DEFAULT_TIMEOUT_MS, fetchImpl.bind(globalThis));
+  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);
+}
+var LOCAL_HOST = /^(localhost|127\.)/i;
+function webAddress({ value, from }) {
+  const url = value.trim().replace(/\/+$/, "");
+  if (/^https?:\/\//i.test(url)) return url;
+  const name = from.startsWith("the ") ? "baseUrl" : from === "OYA_BASE_URL" ? from : `baseUrl in ${from}`;
+  const suggestion = suggestionFor(url);
+  const tryIt = suggestion ? ` Try ${suggestion}.` : "";
+  throw refusal(`${name} must start with http:// or https://, not "${url}".${tryIt}`, "baseUrl", suggestion);
+}
+function suggestionFor(url) {
+  if (/^[a-z][a-z0-9+.-]*:/i.test(url) && !/^[^:/]+:\d+(\/|$)/.test(url)) return void 0;
+  return `${LOCAL_HOST.test(url) ? "http" : "https"}://${url}`;
+}
+function notInAHeader(ch) {
+  const code = ch.codePointAt(0);
+  return code < SPACE && code !== TAB || code === DEL || code > LATIN1_MAX;
+}
+function headerSafe(value, field, ending) {
+  const trimmed = value.trim();
+  const chars = Array.from(trimmed);
+  const at = chars.findIndex(notInAHeader);
+  if (at < 0) return trimmed;
+  const leading = Array.from(value).length - Array.from(value.trimStart()).length;
+  const where = `position ${leading + at + 1} (${codePoint(chars[at])})`;
+  throw refusal(`${field} has a character HTTP headers cannot carry at ${where}. ${ending}`, field);
+}
+var codePoint = (ch) => `U+${ch.codePointAt(0).toString(HEX).toUpperCase().padStart(CODE_POINT_DIGITS, "0")}`;
+var shown = (value) => typeof value === "string" ? JSON.stringify(value) : String(value);
+function segment(value, field = "id") {
+  if (typeof value !== "string" || !value)
+    throw refusal(`${field} must be a non-empty string, not ${shown(value)}`, field);
+  if (value.includes("/") || value === "." || value === "..")
+    throw refusal(`${field} must be a single path segment (no "/" and not "." or ".."), not ${shown(value)}`, field);
+  return encodeURIComponent(value);
 }
 
 // src/run-watch.ts
@@ -381,7 +457,7 @@ var Browser = class {
    * Play `'<name>:draft'` to try a draft before promoting it.
    */
   async play(name, data = {}, { autoHeal = true } = {}) {
-    const path = `/api/browsers/${this.id}/playbooks/${encodeURIComponent(name)}/play`;
+    const path = `/api/browsers/${this.id}/playbooks/${segment(name, "name")}/play`;
     return agentAnswer(
       await this.http.request("POST", path, { variables: data, autoHeal }, AGENT_TIMEOUT_MS)
     );
@@ -432,7 +508,7 @@ var Browser = class {
   }
   /** Revoke a link from `shareUrl()` before it expires, by the id it returned. */
   async revokeShare(id) {
-    await this.http.request("DELETE", `/api/control/credentials/${encodeURIComponent(id)}`);
+    await this.http.request("DELETE", `/api/control/credentials/${segment(id)}`);
   }
   /** Counters, health and the last 50 things this browser did. */
   status() {
@@ -488,8 +564,9 @@ function startBody(options) {
   const { profile, persona, provider, wsUrl, name, queueMs, priority, budgetUsd, governed, policy } = options;
   return { profile: profile || persona, provider, wsUrl, name, queueMs, priority, budgetUsd, governed, policy };
 }
+var idempotencyKeyOf = ({ idempotencyKey }) => idempotencyKey ? headerSafe(idempotencyKey, "idempotencyKey", 'Use letters, digits, "-" and "_".') : globalThis.crypto.randomUUID();
 async function start(http, wait, options) {
-  const headers = { "Idempotency-Key": options.idempotencyKey || globalThis.crypto.randomUUID() };
+  const headers = { "Idempotency-Key": idempotencyKeyOf(options) };
   const path = "/api/browsers/start";
   const started = await http().request("POST", path, startBody(options), START_TIMEOUT_MS, headers);
   if (started.status === "starting") {
@@ -498,7 +575,7 @@ async function start(http, wait, options) {
   }
   return new Browser(http(), started, options.captcha === "auto");
 }
-var fetchBrowser = (http, id) => http().request("GET", `/api/browsers/${encodeURIComponent(id)}`);
+var fetchBrowser = (http, id) => http().request("GET", `/api/browsers/${segment(id)}`);
 async function reattach(http, id) {
   const found = await fetchBrowser(http, id);
   return new Browser(http(), asStarted(found), false);
@@ -510,69 +587,79 @@ function asStarted(found) {
 var stopBrowsers = (http, ids) => http().request("POST", "/api/browsers/stop", ids === "all" ? { all: true } : { ids }, START_TIMEOUT_MS);
 var browserApi = (http, wait) => ({
   /** Start a browser and wait until it can take commands. */
-  start: (options = {}) => start(http, wait, options),
+  start: async (options = {}) => start(http, wait, options),
   /** Reattach to a browser that is already running. */
-  get: (id) => reattach(http, id),
+  get: async (id) => reattach(http, id),
   /** Every browser on this key. */
-  list: () => http().request("GET", "/api/browsers"),
+  list: async () => http().request("GET", "/api/browsers"),
   /** Stop some (`ids`) or every browser on this key. Each reports separately. */
-  stop: (ids) => stopBrowsers(http, ids),
+  stop: async (ids) => stopBrowsers(http, ids),
   /** Stop every browser on this key; returns how many stopped. */
   stopAll: async () => (await stopBrowsers(http, "all")).stopped
 });
 
 // src/api/control.ts
-var session = (id, action = "") => `/api/control/sessions/${encodeURIComponent(id)}${action}`;
-var item = (kind, id) => `/api/control/${kind}/${encodeURIComponent(id)}`;
+var session = (id, action = "") => `/api/control/sessions/${segment(id)}${action}`;
+var item = (kind, id) => `/api/control/${kind}/${segment(id)}`;
 var sessionCalls = (http) => ({
   /** Settings, sessions and recent events at a glance. */
-  overview: () => http().request("GET", "/api/control"),
+  overview: async () => http().request("GET", "/api/control"),
   /** Every session, including disconnected and cleanup-pending ones. */
-  sessions: () => http().request("GET", "/api/control/sessions"),
+  sessions: async () => http().request("GET", "/api/control/sessions"),
   /** One session. */
-  session: (id) => http().request("GET", session(id)),
+  session: async (id) => http().request("GET", session(id)),
   /** Update limits, rate cards and retention. */
-  settings: (changes) => http().request("PATCH", "/api/control/project", changes)
+  settings: async (changes) => http().request("PATCH", "/api/control/project", changes)
 });
 var lifecycleCalls = (http) => ({
-  /** Cancel queued or provisioning work. */
-  cancel: (id) => http().request("POST", session(id, "/cancel"), {}),
+  /** Stop a session in any state; answers its final state. */
+  cancel: async (id) => http().request("POST", session(id, "/cancel"), {}),
   /** Stop a session; `force` stops despite a profile-save error, or reconciles. */
-  stop: (id, force = false) => http().request("POST", session(id, "/stop"), { force }),
+  stop: async (id, force = false) => http().request("POST", session(id, "/stop"), { force }),
   /** Acquire or release human control, or acknowledge the agent's resume. */
-  takeover: (id, action) => http().request("POST", session(id, "/control"), { action }),
+  takeover: async (id, action) => http().request("POST", session(id, "/control"), { action }),
   /** Send one input as the human holding the control lease. */
-  input: (id, action, params) => http().request("POST", session(id, "/input"), { action, params })
+  input: async (id, action, params) => http().request("POST", session(id, "/input"), { action, params })
 });
+function recoverBody(options) {
+  const { replace = false, wsUrl } = typeof options === "boolean" ? { replace: options } : options ?? {};
+  if (wsUrl && !replace)
+    throw refusal("wsUrl is only used with replace: true; recovering in place keeps the endpoint it had.", "wsUrl");
+  return wsUrl ? { replace, wsUrl } : { replace };
+}
 var recoveryCalls = (http) => ({
-  /** Explicitly recover a session, or replace it with a fresh one. */
-  recover: (id, replace = false) => http().request("POST", session(id, "/recover"), { replace }),
+  /**
+   * Explicitly recover a session, or replace it with a fresh one. A cdp
+   * session's replacement needs the Chrome it runs on: `{ replace: true, wsUrl }`.
+   * `recover(id, true)` still means replace.
+   */
+  recover: async (id, options = {}) => http().request("POST", session(id, "/recover"), recoverBody(options)),
   /** A single-use ticket for the live stream. */
-  ticket: (id) => http().request("POST", session(id, "/ticket"), {}),
+  ticket: async (id) => http().request("POST", session(id, "/ticket"), {}),
   /** Durable lifecycle events after a cursor. */
-  events: (after = 0) => http().request("GET", `/api/control/events?after=${after}`)
+  events: async (after = 0) => http().request("GET", `/api/control/events?after=${after}`)
 });
 var credentialCalls = (http) => ({
   /** Mint a service credential. Its token is returned this once. */
-  createCredential: (options) => http().request("POST", "/api/control/credentials", options),
+  createCredential: async (options) => http().request("POST", "/api/control/credentials", options),
   /** Revoke a service credential. */
-  revokeCredential: (id) => http().request("DELETE", item("credentials", id))
+  revokeCredential: async (id) => http().request("DELETE", item("credentials", id))
 });
 var memberCalls = (http) => ({
   /** The owner and every member. */
-  members: () => http().request("GET", "/api/control/members"),
+  members: async () => http().request("GET", "/api/control/members"),
   /** An invitation code for a new member. */
-  inviteMember: (role = "operator") => http().request("POST", "/api/control/members/invite", { role }),
+  inviteMember: async (role = "operator") => http().request("POST", "/api/control/members/invite", { role }),
   /** Remove a member. */
-  removeMember: (userId) => http().request("DELETE", item("members", userId))
+  removeMember: async (userId) => http().request("DELETE", item("members", userId))
 });
 var webhookCalls = (http) => ({
   /** Register a webhook; `types` limits which events it receives. */
-  createWebhook: (url, types = []) => http().request("POST", "/api/control/webhooks", { url, types }),
+  createWebhook: async (url, types = []) => http().request("POST", "/api/control/webhooks", { url, types }),
   /** Disable a webhook. */
-  removeWebhook: (id) => http().request("DELETE", item("webhooks", id)),
+  removeWebhook: async (id) => http().request("DELETE", item("webhooks", id)),
   /** Send a delivery again. */
-  replayDelivery: (id) => http().request("POST", `${item("deliveries", id)}/replay`, {})
+  replayDelivery: async (id) => http().request("POST", `${item("deliveries", id)}/replay`, {})
 });
 var controlApi = (http) => ({
   ...sessionCalls(http),
@@ -584,7 +671,7 @@ var controlApi = (http) => ({
 });
 
 // src/api/playbooks.ts
-var playbook = (name) => `/api/playbooks/${encodeURIComponent(name)}`;
+var playbook = (name) => `/api/playbooks/${segment(name, "name")}`;
 var playbookApi = (http) => ({
   /** Every saved playbook, with any draft waiting on it. */
   list: async () => (await http().request("GET", "/api/playbooks")).playbooks,
@@ -593,7 +680,7 @@ var playbookApi = (http) => ({
     await http().request("DELETE", playbook(name));
   },
   /** Replace a playbook with the draft a healed replay saved. Try it first with `browser.play('<name>:draft')`. */
-  promote: (name) => http().request("POST", `${playbook(name)}/promote`, {})
+  promote: async (name) => http().request("POST", `${playbook(name)}/promote`, {})
 });
 
 // src/api/proxies.ts
@@ -601,10 +688,10 @@ var proxyApi = (http) => ({
   /** Every proxy this key can use, shared ones included. */
   list: async () => (await http().request("GET", "/api/proxies")).proxies,
   /** Add a proxy. Its credentials are never read back. */
-  create: (proxy) => http().request("POST", "/api/proxies", proxy),
+  create: async (proxy) => http().request("POST", "/api/proxies", proxy),
   /** Remove one of this key's proxies. */
   remove: async (id) => {
-    await http().request("DELETE", `/api/proxies/${encodeURIComponent(id)}`);
+    await http().request("DELETE", `/api/proxies/${segment(id)}`);
   },
   /** Dial each proxy and learn its real exit IP. Failing ones cool down and are skipped. */
   check: async () => (await http().request("POST", "/api/proxies/check", {})).results
@@ -615,35 +702,38 @@ var identityCalls = (http) => ({
   /** Every persona on this key. */
   list: async () => (await http().request("GET", "/api/personas")).personas,
   /** One persona. */
-  get: (id) => http().request("GET", `/api/personas/${id}`),
+  get: async (id) => http().request("GET", `/api/personas/${segment(id)}`),
   /**
    * Create an identity. The device, platform, timezone, locale, is chosen
    * here and fixed for its life; `preview()` shows what a choice produces.
    */
-  create: (options = {}) => http().request("POST", "/api/personas", options),
+  create: async (options = {}) => http().request("POST", "/api/personas", options),
   /** Name, concurrency cap and proxy hint. Never the device, clone for that. */
-  update: (id, changes) => http().request("PUT", `/api/personas/${id}`, changes),
+  update: async (id, changes) => http().request("PUT", `/api/personas/${segment(id)}`, changes),
   /** A new persona of the same kind of device: same choices, fresh identity, empty jar. */
-  clone: (id, options = {}) => http().request("POST", `/api/personas/${id}/clone`, options)
+  clone: async (id, options = {}) => http().request("POST", `/api/personas/${segment(id)}/clone`, options)
 });
 var deviceCalls = (http) => ({
   /** The fingerprint these choices would produce. Persists nothing. */
   preview: async (prefs = {}) => (await http().request("POST", "/api/personas/preview", { prefs })).fingerprint,
   /** Platforms, and the timezones and locales each may coherently claim. */
-  options: () => http().request("GET", "/api/personas/options"),
+  options: async () => http().request("GET", "/api/personas/options"),
   /** Pin the persona to one of your proxies, or `null` to let assignment happen at connect. */
-  pinProxy: (id, proxyId) => http().request("PUT", `/api/personas/${id}/proxy`, { proxyId }),
+  pinProxy: async (id, proxyId) => http().request("PUT", `/api/personas/${segment(id)}/proxy`, { proxyId }),
   /** Delete a persona. */
   remove: async (id) => {
-    await http().request("DELETE", `/api/personas/${id}`);
+    await http().request("DELETE", `/api/personas/${segment(id)}`);
   }
 });
 var mfaCalls = (http) => ({
   /** Store the second factor for this identity. Sealed at rest, never read back. */
-  setMfa: (id, config) => http().request("PUT", `/api/personas/${id}/mfa`, config),
+  setMfa: async (id, config) => http().request("PUT", `/api/personas/${segment(id)}/mfa`, config),
   /** Remove the persona-wide factor, or the one filed against `domain`. */
   clearMfa: async (id, domain) => {
-    await http().request("DELETE", `/api/personas/${id}/mfa${domain ? `?domain=${encodeURIComponent(domain)}` : ""}`);
+    await http().request(
+      "DELETE",
+      `/api/personas/${segment(id)}/mfa${domain ? `?domain=${encodeURIComponent(domain)}` : ""}`
+    );
   }
 });
 var loginCalls = (http) => ({
@@ -654,20 +744,20 @@ var loginCalls = (http) => ({
    * 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, config) => http().request("PUT", `/api/personas/${id}/credentials`, config),
+  setCredentials: async (id, config) => http().request("PUT", `/api/personas/${segment(id)}/credentials`, config),
   /** Which sites this identity can sign in to. Usernames only. */
-  credentials: (id) => http().request("GET", `/api/personas/${id}/credentials`),
+  credentials: async (id) => http().request("GET", `/api/personas/${segment(id)}/credentials`),
   /** Remove the login stored for one site. */
   clearCredentials: async (id, domain) => {
-    await http().request("DELETE", `/api/personas/${id}/credentials?domain=${encodeURIComponent(domain)}`);
+    await http().request("DELETE", `/api/personas/${segment(id)}/credentials?domain=${encodeURIComponent(domain)}`);
   }
 });
-var jarPath = (id) => `/api/pool/cookies?persona=${encodeURIComponent(id)}`;
+var jarPath = (id) => `/api/pool/cookies?persona=${segment(id)}`;
 var jarCalls = (http) => ({
   /** Every cookie in the jar; `format: 'playwright'` is ready for `context.addCookies()`. */
-  cookies: async (id, format = "json") => (await http().request("GET", `${jarPath(id)}&format=${format}`)).cookies,
+  cookies: async (id, format = "json") => (await http().request("GET", `${jarPath(id)}&format=${encodeURIComponent(format)}`)).cookies,
   /** Merge cookies into the jar. The persona's browsers pick them up on their next visit to each site. */
-  importCookies: (id, list) => http().request("PUT", jarPath(id), { cookies: list })
+  importCookies: async (id, list) => http().request("PUT", jarPath(id), { cookies: list })
 });
 var cookieCalls = (http) => ({
   ...jarCalls(http),

package/package.json

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