@oya-ai/browser 1.0.71 → 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

@@ -342,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;
@@ -467,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>;
@@ -579,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;
@@ -467,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>;
@@ -579,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

@@ -313,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.71",
+  "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",