@oya-ai/browser 0.1.0

package/dist/index.cjs

@@ -0,0 +1,361 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Browser: () => Browser,
+  Oya: () => Oya,
+  OyaError: () => OyaError,
+  default: () => index_default
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/types.ts
+var OyaError = class extends Error {
+  status;
+  body;
+  constructor(message, status, body) {
+    super(message);
+    this.name = "OyaError";
+    this.status = status;
+    this.body = body;
+  }
+};
+
+// src/client.ts
+var Http = class {
+  constructor(baseUrl, apiKey, timeoutMs, fetchImpl) {
+    this.baseUrl = baseUrl;
+    this.apiKey = apiKey;
+    this.timeoutMs = timeoutMs;
+    this.fetchImpl = fetchImpl;
+  }
+  baseUrl;
+  apiKey;
+  timeoutMs;
+  fetchImpl;
+  async request(method, path, body, timeoutMs = this.timeoutMs, headers = {}) {
+    const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+      method,
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+        ...headers,
+        ...body === void 0 ? {} : { "Content-Type": "application/json" }
+      },
+      body: body === void 0 ? void 0 : JSON.stringify(body),
+      signal: AbortSignal.timeout(timeoutMs)
+    });
+    const text = await res.text();
+    let payload;
+    try {
+      payload = text ? JSON.parse(text) : null;
+    } catch {
+      payload = text;
+    }
+    if (!res.ok) {
+      let message = payload?.error || `${method} ${path} failed (${res.status})`;
+      if (message === "Invalid API key") message += ` for ${this.baseUrl}. Check OYA_API_KEY: a value exported in your shell beats .env.`;
+      throw new OyaError(message, res.status, payload);
+    }
+    return payload;
+  }
+};
+
+// src/browser.ts
+var NAVIGATE_TIMEOUT_MS = 12e4;
+var Browser = class {
+  constructor(http, info, autoCaptcha) {
+    this.http = http;
+    this.autoCaptcha = autoCaptcha;
+    this.id = info.id;
+    this.provider = info.provider;
+    this.persona = info.persona;
+    this.cdpUrl = info.cdpUrl;
+  }
+  http;
+  autoCaptcha;
+  id;
+  provider;
+  persona;
+  /** Point Playwright, Puppeteer or browser-use here. */
+  cdpUrl;
+  async command(action, params = {}, timeoutMs) {
+    const result = await this.http.request(
+      "POST",
+      `/api/browsers/${this.id}/command`,
+      { action, params },
+      timeoutMs
+    );
+    if (result.ok === false) throw new OyaError(result.error || `${action} failed`, 422, result);
+    return result.data;
+  }
+  async goto(url) {
+    await this.command("navigate", { url }, NAVIGATE_TIMEOUT_MS);
+    if (this.autoCaptcha) {
+      const result = await this.solveCaptcha();
+      if (result.present && !result.solved && !result.invisible) throw new OyaError(result.error || "CAPTCHA needs attention. Call solveCaptcha() again or open the live view.", 409, result);
+    }
+  }
+  /** The page as markdown plus numbered elements to act on. */
+  async analyze() {
+    return this.command("analyze");
+  }
+  /** Only the visible elements, which is what an agent almost always wants. */
+  async elements() {
+    return (await this.analyze()).elements.filter((e) => e.visible);
+  }
+  async click(elementId) {
+    const id = this.elementId(elementId);
+    await this.command("click", { element_id: id, selector: `[data-ac-id="${id}"]` });
+  }
+  async type(elementId, text) {
+    const id = this.elementId(elementId);
+    return this.command("type", { element_id: id, selector: `[data-ac-id="${id}"]`, text });
+  }
+  elementId(value) {
+    const id = Number(value);
+    if (typeof value !== "number" && typeof value !== "string" || value === "" || !Number.isInteger(id) || id < 0) {
+      throw new OyaError("Use a numeric element id from browser.analyze().", 400, null);
+    }
+    return id;
+  }
+  async pressKey(key) {
+    await this.command("press_key", { key });
+  }
+  /** `at` aims the wheel at an inner scroller (a results panel, a chat pane) instead of the page. */
+  async scroll(direction, amount, at) {
+    await this.command("scroll", at ? { direction, amount: amount ?? 500, ...at, smooth: false } : { direction, amount });
+  }
+  async waitFor(selector, timeout = 3e4) {
+    await this.command("wait", { selector, timeout }, timeout + 5e3);
+  }
+  /** A `data:image/…;base64,` URL. PNG or JPEG depending on the driver. */
+  async screenshot() {
+    const data = await this.command("screenshot");
+    return data.screenshot;
+  }
+  async url() {
+    const tabs = await this.tabs();
+    return tabs.find((t) => t.active)?.url || "";
+  }
+  async tabs() {
+    const data = await this.command("list_tabs");
+    return data.tabs || [];
+  }
+  async openTab(url) {
+    const data = await this.command("open_tab", { url }, NAVIGATE_TIMEOUT_MS);
+    return data.tab_id;
+  }
+  async switchTab(tabId) {
+    await this.command("switch_tab", { tab_id: tabId });
+  }
+  async closeTab(tabId) {
+    await this.command("close_tab", { tab_id: tabId });
+  }
+  /**
+   * Detect and clear a CAPTCHA. Providers that solve natively are left to do
+   * it; everything else goes to the configured solver.
+   */
+  solveCaptcha() {
+    return this.http.request("POST", `/api/browsers/${this.id}/captcha`, {}, 18e4);
+  }
+  /**
+   * Answer an MFA prompt with the persona's configured factor. When nothing can
+   * answer it, `liveViewUrl` is where a person finishes by hand.
+   */
+  async completeMfa() {
+    const result = await this.http.request("POST", `/api/browsers/${this.id}/mfa`, {}, 18e4);
+    if (result.liveViewUrl) result.liveViewUrl = new URL(result.liveViewUrl, this.http.baseUrl).href;
+    return result;
+  }
+  /** Natural-language control, using this key's configured model. */
+  async ask(prompt) {
+    const res = await this.http.request(
+      "POST",
+      `/api/browsers/${this.id}/chat`,
+      { messages: [{ role: "user", content: prompt }] },
+      6e5
+    );
+    return res.text;
+  }
+  /**
+   * Watch it work: an SSE stream of JPEG frames. EventSource cannot set
+   * headers, so the key travels as a query parameter — treat the URL itself as
+   * a credential.
+   */
+  liveViewUrl() {
+    return `${this.http.baseUrl}/api/live/${this.id}?key=${encodeURIComponent(this.http.apiKey)}`;
+  }
+  /** Counters, health and the last 50 things this browser did. */
+  status() {
+    return this.http.request("GET", `/api/browsers/${this.id}`);
+  }
+  /**
+   * Stop it, whatever it is: a cloud sandbox is destroyed so billing ends, a
+   * CDP session is handed back to its provider, a desktop browser disconnects.
+   */
+  stop() {
+    return this.http.request("POST", `/api/browsers/${this.id}/stop`, {}, 6e4);
+  }
+  /** `await using browser = await oya.browser.start()` stops it however the block exits, errors included. */
+  async [Symbol.asyncDispose]() {
+    await this.stop();
+  }
+  /** @deprecated use stop() — close() only dropped the socket, and a cloud browser redialled. */
+  async close() {
+    await this.stop();
+  }
+};
+
+// src/index.ts
+var DEFAULT_BASE_URL = "https://browser.getoya.ai";
+var READY_POLL_MS = 2e3;
+var env = (name) => globalThis.process?.env?.[name];
+var Oya = class {
+  http;
+  constructor(options = {}) {
+    const apiKey = options.apiKey || env("OYA_API_KEY");
+    if (!apiKey) {
+      throw new Error("No API key. Pass { apiKey } or set OYA_API_KEY \u2014 run `oya login` to get one.");
+    }
+    const baseUrl = (options.baseUrl || env("OYA_BASE_URL") || DEFAULT_BASE_URL).replace(/\/+$/, "");
+    const fetchImpl = options.fetch || globalThis.fetch;
+    if (!fetchImpl) throw new Error("No fetch available \u2014 pass { fetch } or use Node 18+.");
+    this.http = new Http(baseUrl, apiKey, options.timeoutMs ?? 6e4, fetchImpl.bind(globalThis));
+  }
+  browser = {
+    /** Start a browser and wait until it can take commands. */
+    start: async (options = {}) => {
+      const started = await this.http.request("POST", "/api/browsers/start", {
+        profile: options.profile || options.persona,
+        provider: options.provider,
+        wsUrl: options.wsUrl,
+        name: options.name,
+        queueMs: options.queueMs,
+        priority: options.priority,
+        budgetUsd: options.budgetUsd,
+        governed: options.governed,
+        policy: options.policy
+      }, 12e4, { "Idempotency-Key": options.idempotencyKey || globalThis.crypto.randomUUID() });
+      if (started.status === "starting") {
+        await this.waitUntilConnected(started.id, options.readyTimeoutMs ?? 12e4 + (options.queueMs || 0));
+        const connected = await this.http.request("GET", `/api/browsers/${encodeURIComponent(started.id)}`);
+        started.cdpUrl = connected.cdpUrl;
+      }
+      return new Browser(this.http, started, options.captcha === "auto");
+    },
+    /** Reattach to a browser that is already running. */
+    get: async (id) => {
+      const found = await this.http.request("GET", `/api/browsers/${encodeURIComponent(id)}`);
+      return new Browser(this.http, {
+        id: found.id,
+        provider: found.provider || "cdp",
+        persona: found.persona || "default",
+        status: "ready",
+        cdpUrl: found.cdpUrl
+      }, false);
+    },
+    list: () => this.http.request("GET", "/api/browsers"),
+    /** Stop some (`ids`) or every browser on this key. Each reports separately. */
+    stop: (ids) => this.http.request("POST", "/api/browsers/stop", ids === "all" ? { all: true } : { ids }, 12e4),
+    stopAll: async () => (await this.browser.stop("all")).stopped
+  };
+  /** Durable operational controls, including disconnected and cleanup-pending sessions. */
+  control = {
+    overview: () => this.http.request("GET", "/api/control"),
+    sessions: () => this.http.request("GET", "/api/control/sessions"),
+    session: (id) => this.http.request("GET", `/api/control/sessions/${encodeURIComponent(id)}`),
+    settings: (changes) => this.http.request("PATCH", "/api/control/project", changes),
+    cancel: (id) => this.http.request("POST", `/api/control/sessions/${encodeURIComponent(id)}/cancel`, {}),
+    stop: (id, force = false) => this.http.request("POST", `/api/control/sessions/${encodeURIComponent(id)}/stop`, { force }),
+    takeover: (id, action) => this.http.request("POST", `/api/control/sessions/${encodeURIComponent(id)}/control`, { action }),
+    input: (id, action, params) => this.http.request("POST", `/api/control/sessions/${encodeURIComponent(id)}/input`, { action, params }),
+    recover: (id, replace = false) => this.http.request("POST", `/api/control/sessions/${encodeURIComponent(id)}/recover`, { replace }),
+    ticket: (id) => this.http.request("POST", `/api/control/sessions/${encodeURIComponent(id)}/ticket`, {}),
+    events: (after = 0) => this.http.request("GET", `/api/control/events?after=${after}`),
+    createCredential: (options) => this.http.request("POST", "/api/control/credentials", options),
+    revokeCredential: (id) => this.http.request("DELETE", `/api/control/credentials/${encodeURIComponent(id)}`),
+    members: () => this.http.request("GET", "/api/control/members"),
+    inviteMember: (role = "operator") => this.http.request("POST", "/api/control/members/invite", { role }),
+    removeMember: (userId) => this.http.request("DELETE", `/api/control/members/${encodeURIComponent(userId)}`),
+    createWebhook: (url, types = []) => this.http.request("POST", "/api/control/webhooks", { url, types }),
+    removeWebhook: (id) => this.http.request("DELETE", `/api/control/webhooks/${encodeURIComponent(id)}`),
+    replayDelivery: (id) => this.http.request("POST", `/api/control/deliveries/${encodeURIComponent(id)}/replay`, {})
+  };
+  personas = {
+    list: async () => (await this.http.request("GET", "/api/personas")).personas,
+    get: (id) => this.http.request("GET", `/api/personas/${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 = {}) => this.http.request("POST", "/api/personas", options),
+    /** Name, concurrency cap and proxy hint. Never the device — clone for that. */
+    update: (id, changes) => this.http.request("PUT", `/api/personas/${id}`, changes),
+    /** A new persona of the same kind of device: same choices, fresh identity, empty jar. */
+    clone: (id, options = {}) => this.http.request("POST", `/api/personas/${id}/clone`, options),
+    /** The fingerprint these choices would produce. Persists nothing. */
+    preview: async (prefs = {}) => (await this.http.request("POST", "/api/personas/preview", { prefs })).fingerprint,
+    /** Platforms, and the timezones and locales each may coherently claim. */
+    options: () => this.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) => this.http.request("PUT", `/api/personas/${id}/proxy`, { proxyId }),
+    remove: async (id) => {
+      await this.http.request("DELETE", `/api/personas/${id}`);
+    },
+    /** Store the second factor for this identity. Sealed at rest, never read back. */
+    setMfa: (id, config) => this.http.request("PUT", `/api/personas/${id}/mfa`, config),
+    clearMfa: async (id) => {
+      await this.http.request("DELETE", `/api/personas/${id}/mfa`);
+    }
+  };
+  /** This key's settings: LLM credentials, browser provider, solver. */
+  config = {
+    get: () => this.http.request("GET", "/api/config"),
+    set: (values) => this.http.request("POST", "/api/config", values)
+  };
+  /** Saved profiles. `personas` is retained as an alias for existing clients. */
+  profiles = this.personas;
+  usage() {
+    return this.http.request("GET", "/api/usage");
+  }
+  async waitUntilConnected(id, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      const all = await this.browser.list();
+      if (all.some((b) => b.id === id && b.health !== "dead")) return;
+      try {
+        const session = await this.control.session(id);
+        if (["failed", "stopped", "unknown_outcome"].includes(session.state)) throw new OyaError(`Browser creation ended in ${session.state}`, 409, session);
+      } catch (e) {
+        if (!(e instanceof OyaError) || e.status !== 404) throw e;
+      }
+      await new Promise((r) => setTimeout(r, READY_POLL_MS));
+    }
+    throw new OyaError(`Browser ${id} did not come up within ${Math.round(timeoutMs / 1e3)}s`, 504, null);
+  }
+};
+var index_default = Oya;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Browser,
+  Oya,
+  OyaError
+});