@oya-ai/browser 1.0.70 → 1.0.73

package/README.md

@@ -244,6 +244,23 @@ const oya = new Oya({
 | `setMfa(id, config)` | Store TOTP secret (sealed at rest with AES-256-GCM) |
 | `clearMfa(id)` | Remove MFA secret from persona |
 
+### Proxies (`oya.proxies`)
+
+| Method | Description |
+|:---|:---|
+| `create({ url, label?, geo?, kind?, maxPersonas? })` | Add a proxy from your vendor. Credentials are encrypted and never returned |
+| `list()` | Your proxies and shared ones, with exit IP, health and how many personas use each |
+| `check()` | Dial every proxy and record its real exit IP |
+| `remove(id)` | Delete a proxy and unpin the personas on it |
+
+```ts
+const proxy = await oya.proxies.create({
+  url: "http://user:pass_session-shopper1@gate.vendor.com:7000", // one sticky session per persona
+  label: "us-shopper-1", geo: "US", kind: "residential", maxPersonas: 1,
+});
+await oya.personas.pinProxy(persona.id, proxy.id);
+```
+
 ### Durable Governance & Control (`oya.control`)
 
 | Method | Description |

package/dist/index.cjs

@@ -223,6 +223,29 @@ var Browser = class {
     );
     return `${this.http.baseUrl}/api/live/${this.id}?ticket=${encodeURIComponent(ticket)}`;
   }
+  /**
+   * A shareable link to this browser's live view, for handing to a person or
+   * embedding in your own app. The token rides in the URL fragment, so it never
+   * reaches a server log or Referer header. `control: true` lets whoever opens
+   * it take over and act in the browser; otherwise it is view-only. The link
+   * expires (default one hour) and is revocable with `revokeShare(id)`.
+   *
+   * The credential is scoped to this one browser: it cannot see or touch the
+   * rest of your project. Anyone holding the link has that access until it
+   * expires or you revoke it, so treat it like a password.
+   */
+  async shareUrl({ control = false, expiresInSeconds = 3600 } = {}) {
+    const c = await this.http.request(
+      "POST",
+      `/api/control/sessions/${encodeURIComponent(this.id)}/share`,
+      { control, expiresIn: expiresInSeconds }
+    );
+    return { url: `${this.http.baseUrl}/live/${encodeURIComponent(this.id)}#t=${encodeURIComponent(c.token)}`, id: c.id, expiresAt: c.expiresAt };
+  }
+  /** 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)}`);
+  }
   /** Counters, health and the last 50 things this browser did. */
   status() {
     return this.http.request("GET", `/api/browsers/${this.id}`);
@@ -319,6 +342,19 @@ var Oya = class {
     removeWebhook: (id) => this.http.request("DELETE", `/api/control/webhooks/${encodeURIComponent(id)}`),
     replayDelivery: (id) => this.http.request("POST", `/api/control/deliveries/${encodeURIComponent(id)}/replay`, {})
   };
+  /**
+   * Proxy exits for your personas. A persona takes one at first connect (by its
+   * geo hint) or by `personas.pinProxy`, and keeps it.
+   */
+  proxies = {
+    list: async () => (await this.http.request("GET", "/api/proxies")).proxies,
+    create: (proxy) => this.http.request("POST", "/api/proxies", proxy),
+    remove: async (id) => {
+      await this.http.request("DELETE", `/api/proxies/${encodeURIComponent(id)}`);
+    },
+    /** Dial each proxy and learn its real exit IP. Failing ones cool down and are skipped. */
+    check: async () => (await this.http.request("POST", "/api/proxies/check", {})).results
+  };
   personas = {
     list: async () => (await this.http.request("GET", "/api/personas")).personas,
     get: (id) => this.http.request("GET", `/api/personas/${id}`),

package/dist/index.d.cts

@@ -126,6 +126,35 @@ interface PersonaPrefs {
     timezone?: string;
     locale?: string;
 }
+/** A proxy exit. Credentials go in on create and never come back out. */
+interface ProxyInfo {
+    id: string;
+    label: string;
+    kind: 'residential' | 'datacenter';
+    /** Two-letter country, optionally a region: "US", "US-CA". */
+    geo: string | null;
+    /** Provided by the host rather than this key. Cannot be removed. */
+    shared: boolean;
+    healthy: boolean;
+    /** Healthy and not cooling down after a failure. */
+    available: boolean;
+    /** Where traffic actually leaves, as of the last check. */
+    exitIp: string | null;
+    lastCheckedAt: string | null;
+    /** Personas on it now, out of `maxPersonas`. */
+    assigned: number;
+    maxPersonas: number;
+    cooldownMsRemaining: number;
+}
+interface ProxyCreate {
+    /** http(s)://user:pass@host:port from your vendor. Chromium cannot use SOCKS5 with a password. */
+    url: string;
+    label?: string;
+    geo?: string;
+    kind?: 'residential' | 'datacenter';
+    /** Personas that may share it. Keep 1 for a sticky-session URL so each keeps its own IP. */
+    maxPersonas?: number;
+}
 interface PersonaInfo {
     id: string;
     name: string;
@@ -349,6 +378,27 @@ declare class Browser {
      * 60 seconds. Mint one per viewer — the first connection spends it.
      */
     liveStreamUrl(): Promise<string>;
+    /**
+     * A shareable link to this browser's live view, for handing to a person or
+     * embedding in your own app. The token rides in the URL fragment, so it never
+     * reaches a server log or Referer header. `control: true` lets whoever opens
+     * it take over and act in the browser; otherwise it is view-only. The link
+     * expires (default one hour) and is revocable with `revokeShare(id)`.
+     *
+     * The credential is scoped to this one browser: it cannot see or touch the
+     * rest of your project. Anyone holding the link has that access until it
+     * expires or you revoke it, so treat it like a password.
+     */
+    shareUrl({ control, expiresInSeconds }?: {
+        control?: boolean;
+        expiresInSeconds?: number;
+    }): Promise<{
+        url: string;
+        id: string;
+        expiresAt: number | null;
+    }>;
+    /** Revoke a link from `shareUrl()` before it expires, by the id it returned. */
+    revokeShare(id: string): Promise<void>;
     /** Counters, health and the last 50 things this browser did. */
     status(): Promise<BrowserDetail>;
     /**
@@ -446,6 +496,22 @@ declare class Oya {
             ok: boolean;
         }>;
     };
+    /**
+     * Proxy exits for your personas. A persona takes one at first connect (by its
+     * geo hint) or by `personas.pinProxy`, and keeps it.
+     */
+    readonly proxies: {
+        list: () => Promise<ProxyInfo[]>;
+        create: (proxy: ProxyCreate) => Promise<ProxyInfo>;
+        remove: (id: string) => Promise<void>;
+        /** Dial each proxy and learn its real exit IP. Failing ones cool down and are skipped. */
+        check: () => Promise<Array<{
+            id: string;
+            ok: boolean;
+            exitIp?: string | null;
+            error?: string;
+        }>>;
+    };
     readonly personas: {
         list: () => Promise<PersonaInfo[]>;
         get: (id: string) => Promise<PersonaInfo>;
@@ -558,4 +624,4 @@ declare class Oya {
     private waitUntilConnected;
 }
 
-export { type Activity, type Analysis, Browser, type BrowserDetail, type BrowserInfo, type CaptchaResult, type ControlCredential, type ControlEvent, type ControlOverview, type ControlRole, type ControlSession, type Element, type Fingerprint, type Health, type HumanInputAction, type MfaConfig, type MfaResult, Oya, OyaError, type OyaOptions, type PersonaInfo, type PersonaPrefs, type ProjectSettings, type Provider, type StartOptions, type StartResult, type StopResult, Oya as default };
+export { type Activity, type Analysis, Browser, type BrowserDetail, type BrowserInfo, type CaptchaResult, type ControlCredential, type ControlEvent, type ControlOverview, type ControlRole, type ControlSession, type Element, type Fingerprint, type Health, type HumanInputAction, type MfaConfig, type MfaResult, Oya, OyaError, type OyaOptions, type PersonaInfo, type PersonaPrefs, type ProjectSettings, type Provider, type ProxyCreate, type ProxyInfo, type StartOptions, type StartResult, type StopResult, Oya as default };

package/dist/index.d.ts

@@ -126,6 +126,35 @@ interface PersonaPrefs {
     timezone?: string;
     locale?: string;
 }
+/** A proxy exit. Credentials go in on create and never come back out. */
+interface ProxyInfo {
+    id: string;
+    label: string;
+    kind: 'residential' | 'datacenter';
+    /** Two-letter country, optionally a region: "US", "US-CA". */
+    geo: string | null;
+    /** Provided by the host rather than this key. Cannot be removed. */
+    shared: boolean;
+    healthy: boolean;
+    /** Healthy and not cooling down after a failure. */
+    available: boolean;
+    /** Where traffic actually leaves, as of the last check. */
+    exitIp: string | null;
+    lastCheckedAt: string | null;
+    /** Personas on it now, out of `maxPersonas`. */
+    assigned: number;
+    maxPersonas: number;
+    cooldownMsRemaining: number;
+}
+interface ProxyCreate {
+    /** http(s)://user:pass@host:port from your vendor. Chromium cannot use SOCKS5 with a password. */
+    url: string;
+    label?: string;
+    geo?: string;
+    kind?: 'residential' | 'datacenter';
+    /** Personas that may share it. Keep 1 for a sticky-session URL so each keeps its own IP. */
+    maxPersonas?: number;
+}
 interface PersonaInfo {
     id: string;
     name: string;
@@ -349,6 +378,27 @@ declare class Browser {
      * 60 seconds. Mint one per viewer — the first connection spends it.
      */
     liveStreamUrl(): Promise<string>;
+    /**
+     * A shareable link to this browser's live view, for handing to a person or
+     * embedding in your own app. The token rides in the URL fragment, so it never
+     * reaches a server log or Referer header. `control: true` lets whoever opens
+     * it take over and act in the browser; otherwise it is view-only. The link
+     * expires (default one hour) and is revocable with `revokeShare(id)`.
+     *
+     * The credential is scoped to this one browser: it cannot see or touch the
+     * rest of your project. Anyone holding the link has that access until it
+     * expires or you revoke it, so treat it like a password.
+     */
+    shareUrl({ control, expiresInSeconds }?: {
+        control?: boolean;
+        expiresInSeconds?: number;
+    }): Promise<{
+        url: string;
+        id: string;
+        expiresAt: number | null;
+    }>;
+    /** Revoke a link from `shareUrl()` before it expires, by the id it returned. */
+    revokeShare(id: string): Promise<void>;
     /** Counters, health and the last 50 things this browser did. */
     status(): Promise<BrowserDetail>;
     /**
@@ -446,6 +496,22 @@ declare class Oya {
             ok: boolean;
         }>;
     };
+    /**
+     * Proxy exits for your personas. A persona takes one at first connect (by its
+     * geo hint) or by `personas.pinProxy`, and keeps it.
+     */
+    readonly proxies: {
+        list: () => Promise<ProxyInfo[]>;
+        create: (proxy: ProxyCreate) => Promise<ProxyInfo>;
+        remove: (id: string) => Promise<void>;
+        /** Dial each proxy and learn its real exit IP. Failing ones cool down and are skipped. */
+        check: () => Promise<Array<{
+            id: string;
+            ok: boolean;
+            exitIp?: string | null;
+            error?: string;
+        }>>;
+    };
     readonly personas: {
         list: () => Promise<PersonaInfo[]>;
         get: (id: string) => Promise<PersonaInfo>;
@@ -558,4 +624,4 @@ declare class Oya {
     private waitUntilConnected;
 }
 
-export { type Activity, type Analysis, Browser, type BrowserDetail, type BrowserInfo, type CaptchaResult, type ControlCredential, type ControlEvent, type ControlOverview, type ControlRole, type ControlSession, type Element, type Fingerprint, type Health, type HumanInputAction, type MfaConfig, type MfaResult, Oya, OyaError, type OyaOptions, type PersonaInfo, type PersonaPrefs, type ProjectSettings, type Provider, type StartOptions, type StartResult, type StopResult, Oya as default };
+export { type Activity, type Analysis, Browser, type BrowserDetail, type BrowserInfo, type CaptchaResult, type ControlCredential, type ControlEvent, type ControlOverview, type ControlRole, type ControlSession, type Element, type Fingerprint, type Health, type HumanInputAction, type MfaConfig, type MfaResult, Oya, OyaError, type OyaOptions, type PersonaInfo, type PersonaPrefs, type ProjectSettings, type Provider, type ProxyCreate, type ProxyInfo, type StartOptions, type StartResult, type StopResult, Oya as default };

package/dist/index.js

@@ -194,6 +194,29 @@ var Browser = class {
     );
     return `${this.http.baseUrl}/api/live/${this.id}?ticket=${encodeURIComponent(ticket)}`;
   }
+  /**
+   * A shareable link to this browser's live view, for handing to a person or
+   * embedding in your own app. The token rides in the URL fragment, so it never
+   * reaches a server log or Referer header. `control: true` lets whoever opens
+   * it take over and act in the browser; otherwise it is view-only. The link
+   * expires (default one hour) and is revocable with `revokeShare(id)`.
+   *
+   * The credential is scoped to this one browser: it cannot see or touch the
+   * rest of your project. Anyone holding the link has that access until it
+   * expires or you revoke it, so treat it like a password.
+   */
+  async shareUrl({ control = false, expiresInSeconds = 3600 } = {}) {
+    const c = await this.http.request(
+      "POST",
+      `/api/control/sessions/${encodeURIComponent(this.id)}/share`,
+      { control, expiresIn: expiresInSeconds }
+    );
+    return { url: `${this.http.baseUrl}/live/${encodeURIComponent(this.id)}#t=${encodeURIComponent(c.token)}`, id: c.id, expiresAt: c.expiresAt };
+  }
+  /** 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)}`);
+  }
   /** Counters, health and the last 50 things this browser did. */
   status() {
     return this.http.request("GET", `/api/browsers/${this.id}`);
@@ -290,6 +313,19 @@ var Oya = class {
     removeWebhook: (id) => this.http.request("DELETE", `/api/control/webhooks/${encodeURIComponent(id)}`),
     replayDelivery: (id) => this.http.request("POST", `/api/control/deliveries/${encodeURIComponent(id)}/replay`, {})
   };
+  /**
+   * Proxy exits for your personas. A persona takes one at first connect (by its
+   * geo hint) or by `personas.pinProxy`, and keeps it.
+   */
+  proxies = {
+    list: async () => (await this.http.request("GET", "/api/proxies")).proxies,
+    create: (proxy) => this.http.request("POST", "/api/proxies", proxy),
+    remove: async (id) => {
+      await this.http.request("DELETE", `/api/proxies/${encodeURIComponent(id)}`);
+    },
+    /** Dial each proxy and learn its real exit IP. Failing ones cool down and are skipped. */
+    check: async () => (await this.http.request("POST", "/api/proxies/check", {})).results
+  };
   personas = {
     list: async () => (await this.http.request("GET", "/api/personas")).personas,
     get: (id) => this.http.request("GET", `/api/personas/${id}`),

package/package.json

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