@oya-ai/browser 1.0.107 → 1.0.111

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,19 +744,36 @@ 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=${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=${encodeURIComponent(format)}`)).cookies,
+  /** Merge cookies into the jar. The persona's browsers pick them up on their next visit to each site. */
+  importCookies: async (id, list) => http().request("PUT", jarPath(id), { cookies: list })
+});
+var cookieCalls = (http) => ({
+  ...jarCalls(http),
+  /** Copy every login of persona `from` into persona `to`, which keeps its own device. */
+  copyCookies: async (from, to) => jarCalls(http).importCookies(to, await jarCalls(http).cookies(from)),
+  /** Forget every cookie in the jar: signs the persona out everywhere. */
+  clearCookies: async (id) => {
+    await http().request("DELETE", jarPath(id));
   }
 });
 var personaApi = (http) => ({
   ...identityCalls(http),
   ...deviceCalls(http),
   ...mfaCalls(http),
-  ...loginCalls(http)
+  ...loginCalls(http),
+  ...cookieCalls(http)
 });
 
 // src/api/config.ts

package/package.json

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