onebrowser 0.1.1 → 0.2.0

package/README.md

@@ -23,7 +23,7 @@ await browsers.close();
 
 **What it does not do**: choose a provider, cap the sessions held at once, spread sessions over providers, or stop using a provider whose quota runs low. Those are policy, and belong to the program using it. onebrowser opens the session it is asked for, and tells the program what it needs to decide: the quota, and `QuotaError` when a provider refuses a session for the account's quota.
 
-Built in: [Steel](https://steel.dev), [TinyFish](https://tinyfish.ai), [Hyperbrowser](https://hyperbrowser.ai), [Lightpanda](https://lightpanda.io) and [Kernel](https://www.kernel.sh); a program can add its own (see [Adding a provider](#adding-a-provider)). Node 22.13 or later.
+Built in: [Steel](https://steel.dev), [TinyFish](https://tinyfish.ai), [Hyperbrowser](https://hyperbrowser.ai), [Lightpanda](https://lightpanda.io), [Kernel](https://www.kernel.sh) and [Anchor Browser](https://anchorbrowser.io); a program can add its own (see [Adding a provider](#adding-a-provider)). Node 22.13 or later.
 
 ## Interface
 
@@ -73,6 +73,7 @@ How each provider meets them:
 | `hyperbrowser` | residential proxy, paid plans | at once: a session ends with its CDP connection | `timeoutMinutes`, in whole minutes |
 | `lightpanda` | its datacenter pool in that country | at once: a session is its CDP connection | Lightpanda's own limit is 15 min |
 | `kernel` | not supported (throws) | `timeout_seconds` after the CDP client left; until then a disconnected session stays in standby, counting toward the plan's concurrent browsers | this process only |
+| `anchor` | residential proxy | `idle_timeout` after the last CDP connection left, in whole minutes rounded down (at least 1) | `max_duration`, in whole minutes |
 
 ### Quota
 
@@ -83,6 +84,7 @@ How each provider meets them:
 | `hyperbrowser` | credits | `GET /api/team/credit-info`, the endpoint of Hyperbrowser's SDK (not in its API docs) |
 | `lightpanda` | browser hours of the calendar month (`monthlyHours`, default: the free plan's) | the ledger's record of its sessions: its console shows the month's usage, but its token cannot read it. So the reading is whole while the account is used only through ledgers of this machine |
 | `kernel` | browser hours of the calendar month (`monthlyHours`, default: what the free plan's credits pay for) | the uptime of the account's sessions this month, from `GET /browsers`; a session refused with 403 (spending cap) throws `QuotaError` |
+| `anchor` | credits | `GET /v1/billing`; a session refused with 402 throws `QuotaError` |
 
 ### API keys
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "onebrowser",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "One interface to remote browser providers: sessions by provider name, a usage ledger, account quotas",
-  "keywords": ["browser", "remote-browser", "cdp", "playwright", "steel", "hyperbrowser", "lightpanda", "kernel", "tinyfish"],
+  "keywords": ["browser", "remote-browser", "cdp", "playwright", "steel", "hyperbrowser", "lightpanda", "kernel", "tinyfish", "anchorbrowser"],
   "license": "MIT",
   "author": "Richard Wang",
   "repository": { "type": "git", "url": "git+https://github.com/i-richardwang/onebrowser.git" },

package/src/providers/anchor.js

@@ -0,0 +1,54 @@
+import { QuotaError } from '../errors.js';
+import { json } from './http.js';
+
+/**
+ * Anchor Browser (https://docs.anchorbrowser.io). Without a proxy a session uses the IP of the machine it runs on,
+ * a different US datacenter IP per session; proxyCountry selects Anchor's residential proxy in that country.
+ * Closing the CDP connection does not end a session: Anchor ends it idleTimeoutSec after its last connection
+ * left (idle_timeout), and after maxDurationMs in any case (max_duration), both in whole minutes. idle_timeout is
+ * rounded down, to at least 1: its timer runs only once the client is gone, so ending sooner cuts off no session
+ * in use; max_duration is rounded up, as this process closes the session at maxDurationMs. Recording, on by
+ * default, is turned off. Sessions are paid from the account's credits; with too few, creating one answers 402.
+ */
+export const defaults = {
+  apiBase: 'https://api.anchorbrowser.io/v1',
+};
+
+const headers = (apiKey) => ({ 'anchor-api-key': apiKey });
+
+export async function createSession(settings, apiKey, { proxyCountry, idleTimeoutSec, maxDurationMs }) {
+  const session = {
+    recording: { active: false },
+    timeout: { idle_timeout: Math.max(1, Math.floor(idleTimeoutSec / 60)), max_duration: Math.ceil(maxDurationMs / 60_000) },
+  };
+  if (proxyCountry) session.proxy = { active: true, type: 'anchor_proxy', country_code: proxyCountry.toLowerCase() };
+  let s;
+  try {
+    s = (await json(`${settings.apiBase}/sessions`, { method: 'POST', headers: headers(apiKey), body: { session }, timeoutMs: 90_000 })).data;
+  } catch (e) {
+    if (e.status === 402) throw new QuotaError(`credits used up: ${e.text}`);
+    throw e;
+  }
+  return { id: s.id, cdpUrl: s.cdp_url, egress: proxyCountry ? `proxy ${proxyCountry}` : 'datacenter IP' };
+}
+
+/** Succeeds also for a session that has already ended */
+export async function releaseSession(settings, apiKey, session) {
+  await json(`${settings.apiBase}/sessions/${session.id}`, { method: 'DELETE', headers: headers(apiKey) });
+}
+
+/** The account's credits left, gifted ones included. Unlike the other endpoints, /billing answers without a `data` wrapper */
+export async function quota(settings, apiKey) {
+  const { credits } = await json(`${settings.apiBase}/billing`, { headers: headers(apiKey) });
+  return { remaining: credits, unit: 'credits' };
+}
+
+/** Usage of the sessions among `sessions` that have ended, fetched by id: duration in whole seconds */
+export async function sessionUsage(settings, apiKey, sessions) {
+  const usage = [];
+  for (const { id } of sessions) {
+    const { data: s } = await json(`${settings.apiBase}/sessions/${id}`, { headers: headers(apiKey) });
+    if (s.status !== 'running') usage.push({ id, durationMs: s.duration * 1000, proxyBytes: s.proxy_bytes });
+  }
+  return usage;
+}

package/src/providers/index.js

@@ -1,3 +1,4 @@
+import * as anchor from './anchor.js';
 import * as hyperbrowser from './hyperbrowser.js';
 import * as kernel from './kernel.js';
 import * as lightpanda from './lightpanda.js';
@@ -26,7 +27,7 @@ import * as tinyfish from './tinyfish.js';
  * Their requests go through http.js, which turns every status other than 2xx into an HttpError: an adapter
  * handles only the statuses that mean something of their own.
  */
-export const ADAPTERS = { tinyfish, steel, hyperbrowser, lightpanda, kernel };
+export const ADAPTERS = { tinyfish, steel, hyperbrowser, lightpanda, kernel, anchor };
 
 const CONTRACT = ['createSession', 'releaseSession', 'sessionUsage', 'quota'];