@oya-ai/browser 1.0.204 → 1.0.205

package/dist/index.cjs

@@ -636,7 +636,9 @@ function shareLink(baseUrl, id, token) {
 // src/api/browsers.ts
 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 };
+  const personaGroup = options.personaGroup || options.profileGroup;
+  const runs = { profile: profile || persona, personaGroup };
+  return { ...runs, 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) {
@@ -867,6 +869,23 @@ var personaApi = (http) => ({
   ...cookieCalls(http)
 });
 
+// src/api/persona-groups.ts
+var personaGroupApi = (http) => ({
+  /** Every group on this key. */
+  list: async () => (await http().request("GET", "/api/persona-groups")).groups,
+  /**
+   * A new group of this key's personas (not the default one). Its name is what a
+   * start passes, so it cannot change later; a name already used is a 409.
+   */
+  create: (name, personaIds = []) => http().request("POST", "/api/persona-groups", { name, personaIds }),
+  /** Replaces the group's members. */
+  update: (name, personaIds) => http().request("PUT", `/api/persona-groups/${segment(name, "name")}`, { personaIds }),
+  /** Deletes the group; its personas and their browsers are not touched. */
+  remove: async (name) => {
+    await http().request("DELETE", `/api/persona-groups/${segment(name, "name")}`);
+  }
+});
+
 // src/api/config.ts
 var configApi = (http) => ({
   /** This key's settings. Secrets read back masked. */
@@ -1109,6 +1128,13 @@ var Oya = class {
   config = configApi(() => this.http);
   /** Saved profiles. `personas` is retained as an alias for existing clients. */
   profiles = this.personas;
+  /**
+   * Persona groups: name a set of your personas, then start browsers with
+   * `oya.browser.start({ personaGroup: name })` to spread them across the set.
+   */
+  personaGroups = personaGroupApi(() => this.http);
+  /** The same as `personaGroups`, matching the `profiles` alias. */
+  profileGroups = this.personaGroups;
   /** What this key has spent. */
   usage() {
     return this.http.request("GET", "/api/usage");

package/dist/index.d.cts

@@ -37,6 +37,19 @@ interface StartOptions {
      *   <id>     , a specific persona
      */
     persona?: 'default' | 'auto' | (string & {});
+    /**
+     * A persona group to run as instead of one persona: the start runs as one of
+     * the group's personas, the one with the fewest running browsers, then the one
+     * used longest ago, skipping those at their cap. Make groups with
+     * `oya.personaGroups.create`. Not with `persona` or `profile`. When every
+     * member is full, `queueMs` waits on the least busy one.
+     *
+     * Needs Oya server 1.0.205 or later: an older server ignores it and starts as
+     * the default persona.
+     */
+    personaGroup?: string;
+    /** The same as `personaGroup`, matching the `profile` alias of `persona`. */
+    profileGroup?: string;
     /** Solve CAPTCHAs as they appear rather than waiting to be asked. */
     captcha?: 'auto' | 'off';
     /** Override the key's configured provider for this browser only. */
@@ -705,6 +718,8 @@ interface PersonaInfo {
     proxy: {
         /** Two-letter country, optionally a region. */
         geo: string | null;
+        /** Present and true when it runs with no proxy at all. */
+        direct?: boolean;
     } | null;
     /** The proxy it is actually on, once assigned or pinned. */
     exit: {
@@ -845,6 +860,17 @@ interface Cookie {
 }
 /** The formats a jar is exported in: as stored, or ready for Playwright's `context.addCookies()`. */
 type CookieFormat = 'json' | 'playwright';
+/** A named set of personas a browser start can run as instead of one persona. */
+interface PersonaGroup {
+    /** What `start({ personaGroup })` passes; unique per key, and cannot be renamed. */
+    name: string;
+    /** Its member personas that still exist. */
+    personaIds: string[];
+    /** When it was made (ISO). */
+    createdAt: string;
+    /** When its members last changed (ISO). */
+    updatedAt: string;
+}
 
 /**
  * Types for the durable control plane: sessions and their lifecycle, human
@@ -1122,6 +1148,8 @@ interface ProxyCheck {
 interface GeoHint {
     /** Two-letter country, optionally a region. */
     geo?: string;
+    /** Connect with no proxy at all: not an assigned proxy, not Oya residential. Traffic leaves from the browser's own network. Overrides geo. */
+    direct?: boolean;
 }
 /** A persona to create. */
 interface PersonaCreate {
@@ -1605,6 +1633,23 @@ declare class Oya {
         update: (id: string, changes: PersonaUpdate) => Promise<PersonaInfo>;
         clone: (id: string, options?: CloneOptions) => Promise<PersonaInfo>;
     };
+    /**
+     * Persona groups: name a set of your personas, then start browsers with
+     * `oya.browser.start({ personaGroup: name })` to spread them across the set.
+     */
+    readonly personaGroups: {
+        list: () => Promise<PersonaGroup[]>;
+        create: (name: string, personaIds?: string[]) => Promise<PersonaGroup>;
+        update: (name: string, personaIds: string[]) => Promise<PersonaGroup>;
+        remove: (name: string) => Promise<void>;
+    };
+    /** The same as `personaGroups`, matching the `profiles` alias. */
+    readonly profileGroups: {
+        list: () => Promise<PersonaGroup[]>;
+        create: (name: string, personaIds?: string[]) => Promise<PersonaGroup>;
+        update: (name: string, personaIds: string[]) => Promise<PersonaGroup>;
+        remove: (name: string) => Promise<void>;
+    };
     /** What this key has spent. */
     usage(): Promise<unknown>;
     /** Waits for a starting browser to dial in, through this client's own list and session calls. */
@@ -1612,4 +1657,4 @@ declare class Oya {
 }
 
 export { Browser, MAX_FILE_BYTES, Oya, OyaError, Run, Oya as default, file };
-export type { Activity, Analysis, AnalyzeOptions, AttentionRequest, Block, BrowserDetail, BrowserInfo, CaptchaResult, CaptchaSolver, Config, ConfigUpdate, ControlCredential, ControlEvent, ControlOverview, ControlRole, ControlSession, Cookie, CookieFormat, DesktopOptions, EcsAuth, EcsConfig, Element, FileValue, Fingerprint, Health, HumanInputAction, ImportOptions, LlmCatalogEntry, LlmProvider, MfaConfig, MfaResult, OyaOptions, PageFormat, PersonaInfo, PersonaPrefs, PlayResult, Playbook, PlaybookAnswer, PlaybookExport, PlaybookSummary, ProjectSettings, Provider, ProxyCreate, ProxyInfo, RecoverOptions, RunData, RunInfo, RunResult, SandboxRuntime, Signup, SignupOptions, SiteCredentials, StartOptions, StartResult, StopResult, SubmitOptions };
+export type { Activity, Analysis, AnalyzeOptions, AttentionRequest, Block, BrowserDetail, BrowserInfo, CaptchaResult, CaptchaSolver, Config, ConfigUpdate, ControlCredential, ControlEvent, ControlOverview, ControlRole, ControlSession, Cookie, CookieFormat, DesktopOptions, EcsAuth, EcsConfig, Element, FileValue, Fingerprint, Health, HumanInputAction, ImportOptions, LlmCatalogEntry, LlmProvider, MfaConfig, MfaResult, OyaOptions, PageFormat, PersonaGroup, PersonaInfo, PersonaPrefs, PlayResult, Playbook, PlaybookAnswer, PlaybookExport, PlaybookSummary, ProjectSettings, Provider, ProxyCreate, ProxyInfo, RecoverOptions, RunData, RunInfo, RunResult, SandboxRuntime, Signup, SignupOptions, SiteCredentials, StartOptions, StartResult, StopResult, SubmitOptions };

package/dist/index.d.ts

@@ -37,6 +37,19 @@ interface StartOptions {
      *   <id>     , a specific persona
      */
     persona?: 'default' | 'auto' | (string & {});
+    /**
+     * A persona group to run as instead of one persona: the start runs as one of
+     * the group's personas, the one with the fewest running browsers, then the one
+     * used longest ago, skipping those at their cap. Make groups with
+     * `oya.personaGroups.create`. Not with `persona` or `profile`. When every
+     * member is full, `queueMs` waits on the least busy one.
+     *
+     * Needs Oya server 1.0.205 or later: an older server ignores it and starts as
+     * the default persona.
+     */
+    personaGroup?: string;
+    /** The same as `personaGroup`, matching the `profile` alias of `persona`. */
+    profileGroup?: string;
     /** Solve CAPTCHAs as they appear rather than waiting to be asked. */
     captcha?: 'auto' | 'off';
     /** Override the key's configured provider for this browser only. */
@@ -705,6 +718,8 @@ interface PersonaInfo {
     proxy: {
         /** Two-letter country, optionally a region. */
         geo: string | null;
+        /** Present and true when it runs with no proxy at all. */
+        direct?: boolean;
     } | null;
     /** The proxy it is actually on, once assigned or pinned. */
     exit: {
@@ -845,6 +860,17 @@ interface Cookie {
 }
 /** The formats a jar is exported in: as stored, or ready for Playwright's `context.addCookies()`. */
 type CookieFormat = 'json' | 'playwright';
+/** A named set of personas a browser start can run as instead of one persona. */
+interface PersonaGroup {
+    /** What `start({ personaGroup })` passes; unique per key, and cannot be renamed. */
+    name: string;
+    /** Its member personas that still exist. */
+    personaIds: string[];
+    /** When it was made (ISO). */
+    createdAt: string;
+    /** When its members last changed (ISO). */
+    updatedAt: string;
+}
 
 /**
  * Types for the durable control plane: sessions and their lifecycle, human
@@ -1122,6 +1148,8 @@ interface ProxyCheck {
 interface GeoHint {
     /** Two-letter country, optionally a region. */
     geo?: string;
+    /** Connect with no proxy at all: not an assigned proxy, not Oya residential. Traffic leaves from the browser's own network. Overrides geo. */
+    direct?: boolean;
 }
 /** A persona to create. */
 interface PersonaCreate {
@@ -1605,6 +1633,23 @@ declare class Oya {
         update: (id: string, changes: PersonaUpdate) => Promise<PersonaInfo>;
         clone: (id: string, options?: CloneOptions) => Promise<PersonaInfo>;
     };
+    /**
+     * Persona groups: name a set of your personas, then start browsers with
+     * `oya.browser.start({ personaGroup: name })` to spread them across the set.
+     */
+    readonly personaGroups: {
+        list: () => Promise<PersonaGroup[]>;
+        create: (name: string, personaIds?: string[]) => Promise<PersonaGroup>;
+        update: (name: string, personaIds: string[]) => Promise<PersonaGroup>;
+        remove: (name: string) => Promise<void>;
+    };
+    /** The same as `personaGroups`, matching the `profiles` alias. */
+    readonly profileGroups: {
+        list: () => Promise<PersonaGroup[]>;
+        create: (name: string, personaIds?: string[]) => Promise<PersonaGroup>;
+        update: (name: string, personaIds: string[]) => Promise<PersonaGroup>;
+        remove: (name: string) => Promise<void>;
+    };
     /** What this key has spent. */
     usage(): Promise<unknown>;
     /** Waits for a starting browser to dial in, through this client's own list and session calls. */
@@ -1612,4 +1657,4 @@ declare class Oya {
 }
 
 export { Browser, MAX_FILE_BYTES, Oya, OyaError, Run, Oya as default, file };
-export type { Activity, Analysis, AnalyzeOptions, AttentionRequest, Block, BrowserDetail, BrowserInfo, CaptchaResult, CaptchaSolver, Config, ConfigUpdate, ControlCredential, ControlEvent, ControlOverview, ControlRole, ControlSession, Cookie, CookieFormat, DesktopOptions, EcsAuth, EcsConfig, Element, FileValue, Fingerprint, Health, HumanInputAction, ImportOptions, LlmCatalogEntry, LlmProvider, MfaConfig, MfaResult, OyaOptions, PageFormat, PersonaInfo, PersonaPrefs, PlayResult, Playbook, PlaybookAnswer, PlaybookExport, PlaybookSummary, ProjectSettings, Provider, ProxyCreate, ProxyInfo, RecoverOptions, RunData, RunInfo, RunResult, SandboxRuntime, Signup, SignupOptions, SiteCredentials, StartOptions, StartResult, StopResult, SubmitOptions };
+export type { Activity, Analysis, AnalyzeOptions, AttentionRequest, Block, BrowserDetail, BrowserInfo, CaptchaResult, CaptchaSolver, Config, ConfigUpdate, ControlCredential, ControlEvent, ControlOverview, ControlRole, ControlSession, Cookie, CookieFormat, DesktopOptions, EcsAuth, EcsConfig, Element, FileValue, Fingerprint, Health, HumanInputAction, ImportOptions, LlmCatalogEntry, LlmProvider, MfaConfig, MfaResult, OyaOptions, PageFormat, PersonaGroup, PersonaInfo, PersonaPrefs, PlayResult, Playbook, PlaybookAnswer, PlaybookExport, PlaybookSummary, ProjectSettings, Provider, ProxyCreate, ProxyInfo, RecoverOptions, RunData, RunInfo, RunResult, SandboxRuntime, Signup, SignupOptions, SiteCredentials, StartOptions, StartResult, StopResult, SubmitOptions };

package/dist/index.js

@@ -604,7 +604,9 @@ function shareLink(baseUrl, id, token) {
 // src/api/browsers.ts
 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 };
+  const personaGroup = options.personaGroup || options.profileGroup;
+  const runs = { profile: profile || persona, personaGroup };
+  return { ...runs, 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) {
@@ -835,6 +837,23 @@ var personaApi = (http) => ({
   ...cookieCalls(http)
 });
 
+// src/api/persona-groups.ts
+var personaGroupApi = (http) => ({
+  /** Every group on this key. */
+  list: async () => (await http().request("GET", "/api/persona-groups")).groups,
+  /**
+   * A new group of this key's personas (not the default one). Its name is what a
+   * start passes, so it cannot change later; a name already used is a 409.
+   */
+  create: (name, personaIds = []) => http().request("POST", "/api/persona-groups", { name, personaIds }),
+  /** Replaces the group's members. */
+  update: (name, personaIds) => http().request("PUT", `/api/persona-groups/${segment(name, "name")}`, { personaIds }),
+  /** Deletes the group; its personas and their browsers are not touched. */
+  remove: async (name) => {
+    await http().request("DELETE", `/api/persona-groups/${segment(name, "name")}`);
+  }
+});
+
 // src/api/config.ts
 var configApi = (http) => ({
   /** This key's settings. Secrets read back masked. */
@@ -1077,6 +1096,13 @@ var Oya = class {
   config = configApi(() => this.http);
   /** Saved profiles. `personas` is retained as an alias for existing clients. */
   profiles = this.personas;
+  /**
+   * Persona groups: name a set of your personas, then start browsers with
+   * `oya.browser.start({ personaGroup: name })` to spread them across the set.
+   */
+  personaGroups = personaGroupApi(() => this.http);
+  /** The same as `personaGroups`, matching the `profiles` alias. */
+  profileGroups = this.personaGroups;
   /** What this key has spent. */
   usage() {
     return this.http.request("GET", "/api/usage");

package/package.json

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