onebrowser 0.1.1 → 0.3.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), [Anchor Browser](https://anchorbrowser.io) and [Firecrawl](https://www.firecrawl.dev); a program can add its own (see [Adding a provider](#adding-a-provider)). Node 22.13 or later.
 
 ## Interface
 
@@ -73,6 +73,8 @@ 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 |
+| `firecrawl` | its `location` in that country (default: the US) | `activityTtl` (no CDP commands), in whole seconds rounded down, at most 1 h | `ttl`, in whole seconds, at least 30 s and at most 1 h |
 
 ### Quota
 
@@ -83,6 +85,8 @@ 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` |
+| `firecrawl` | credits; the plan's credits renew at the end of each billing period | [`GET /v2/team/credit-usage`](https://docs.firecrawl.dev/api-reference/endpoint/credit-usage); a session refused with 402 throws `QuotaError` |
 
 ### API keys
 
@@ -123,7 +127,7 @@ A program can also pass an adapter of its own in `adapters`, without changing on
 
 `npm test` runs offline: fake adapters and fetch, no network, no browser.
 
-A release is a tag: bump `version` in `package.json` and add its entry to [CHANGELOG.md](CHANGELOG.md), then push the tag `vX.Y.Z`. The release workflow checks the tag against the version, runs the tests and publishes to npm with trusted publishing (no token stored).
+A release is a tag: bump `version` in `package.json`, carry it into `package-lock.json` with `npm install --package-lock-only`, add its entry to [CHANGELOG.md](CHANGELOG.md), then push the tag `vX.Y.Z`. The release workflow checks the tag against the version, runs the tests and publishes to npm with trusted publishing (no token stored).
 
 ## License
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "onebrowser",
-  "version": "0.1.1",
+  "version": "0.3.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", "firecrawl"],
   "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/firecrawl.js

@@ -0,0 +1,59 @@
+import { QuotaError } from '../errors.js';
+import { json } from './http.js';
+
+/**
+ * Firecrawl's Browser Sandbox (https://docs.firecrawl.dev/features/browser). A session browses from a US ISP IP
+ * by default, a different one per session; proxyCountry selects Firecrawl's location in that country (location).
+ * Closing the CDP connection does not end a session: Firecrawl ends it idleTimeoutSec after its last CDP command
+ * (activityTtl), and maxDurationMs after it was created in any case (ttl), both in whole seconds and at most 1 h.
+ * activityTtl is rounded down and ttl cut to 1 h, so that neither ends a session later than asked; ttl is rounded
+ * up, to at least 30 s, as this process closes the session at maxDurationMs. Its live view stream and its ad
+ * blocking, both on by default, are turned off. Sessions are paid from the account's credits; with too few,
+ * creating one answers 402.
+ */
+export const defaults = {
+  apiBase: 'https://api.firecrawl.dev/v2',
+};
+
+const TTL_SEC = { min: 30, max: 3600 }; // what Firecrawl takes for ttl; activityTtl has the same maximum
+
+const headers = (apiKey) => ({ Authorization: `Bearer ${apiKey}` });
+
+export async function createSession(settings, apiKey, { proxyCountry, idleTimeoutSec, maxDurationMs }) {
+  const body = {
+    ttl: Math.min(TTL_SEC.max, Math.max(TTL_SEC.min, Math.ceil(maxDurationMs / 1000))),
+    activityTtl: Math.min(TTL_SEC.max, Math.floor(idleTimeoutSec)),
+    streamWebView: false,
+    blockAds: false,
+  };
+  if (proxyCountry) body.location = { country: proxyCountry };
+  let s;
+  try {
+    s = await json(`${settings.apiBase}/interact`, { method: 'POST', headers: headers(apiKey), body, timeoutMs: 90_000 });
+  } catch (e) {
+    if (e.status === 402) throw new QuotaError(`credits used up: ${e.text}`);
+    throw e;
+  }
+  return { id: s.id, cdpUrl: s.cdpUrl, egress: `proxy ${proxyCountry ?? 'US'}` };
+}
+
+/** Succeeds also for a session that has already ended */
+export async function releaseSession(settings, apiKey, session) {
+  await json(`${settings.apiBase}/interact/${session.id}`, { method: 'DELETE', headers: headers(apiKey) });
+}
+
+/** The team's credits left, coupon credits included; the plan's credits renew at the end of its billing period */
+export async function quota(settings, apiKey) {
+  const { data } = await json(`${settings.apiBase}/team/credit-usage`, { headers: headers(apiKey) });
+  return { remaining: data.remainingCredits, unit: 'credits', renewsAt: data.billingPeriodEnd ? Date.parse(data.billingPeriodEnd) : null };
+}
+
+/** Usage of the sessions among `sessions` that have ended, fetched by id: the session list has no durations (GET /interact/{id} is not in Firecrawl's API docs) */
+export async function sessionUsage(settings, apiKey, sessions) {
+  const usage = [];
+  for (const { id } of sessions) {
+    const s = await json(`${settings.apiBase}/interact/${id}`, { headers: headers(apiKey) });
+    if (s.status !== 'running') usage.push({ id, durationMs: s.sessionDurationMs, proxyBytes: null });
+  }
+  return usage;
+}

package/src/providers/index.js

@@ -1,3 +1,5 @@
+import * as anchor from './anchor.js';
+import * as firecrawl from './firecrawl.js';
 import * as hyperbrowser from './hyperbrowser.js';
 import * as kernel from './kernel.js';
 import * as lightpanda from './lightpanda.js';
@@ -26,7 +28,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, firecrawl };
 
 const CONTRACT = ['createSession', 'releaseSession', 'sessionUsage', 'quota'];