onebrowser 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Richard Wang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,130 @@
+# onebrowser
+
+One interface to remote browser providers. A session is asked for by provider name, the way an LLM request names its model. Every session is recorded in a ledger, which each provider account's usage and quota are read from.
+
+```sh
+npm install onebrowser
+```
+
+```js
+import { OneBrowser, QuotaError } from 'onebrowser';
+
+const browsers = new OneBrowser({ client: 'my-crawler' });
+const session = await browsers.openSession({ provider: 'steel', proxyCountry: 'DE' });
+const page = await session.newPage(); // Playwright; or any CDP client on session.cdpUrl
+await page.goto('https://example.com');
+await session.close();
+
+await browsers.quota('steel'); // { remaining, unit: 'USD', renewsAt: null }
+await browsers.syncUsage(); // fetches the providers' records of ended sessions into the ledger
+browsers.usage({ since: Date.parse('2026-11-01') }); // [{ day, provider, client, sessions, minutes, … }]
+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.
+
+## Interface
+
+`new OneBrowser({ client, ledgerPath, providers, adapters })`
+
+| Option | |
+|---|---|
+| `client` | The program using it, recorded with each session; required |
+| `ledgerPath` | SQLite file of the ledger (default below; `':memory:'` for tests). Opened when first needed |
+| `providers` | Settings per provider name, on top of its adapter's `defaults`: `apiKey`, and the adapter's own settings (API base URLs, plan facts such as `monthlyHours`) |
+| `adapters` | Further adapters by provider name, or replacements of built-in ones |
+
+| Method | |
+|---|---|
+| `providers` | Names of the providers it can open sessions with |
+| `checkReady(provider)` | Throws when the provider is unknown or has no API key |
+| `openSession({ provider, proxyCountry, idleTimeoutSec, maxDurationMs })` | A new session, recorded in the ledger once the provider has created it. Throws `QuotaError` when the provider refuses it for the account's quota |
+| `quota(provider)` | `{ remaining, unit, renewsAt }` in the provider's own unit; `renewsAt` (ms) when it renews by itself, `null` when only a top-up renews it. Throws when it cannot be read |
+| `syncUsage()` | Stores the providers' records (duration, proxy traffic) of the ended sessions that have none yet: `{ reported, failed: [{ provider, error }] }`. Sessions of a provider it has no adapter for (another program's own) are left to the programs that have one |
+| `usage({ since })` | Sessions opened since `since` (ms) per UTC day, provider and client: `sessions`, `minutes` (the provider's record, else the open-to-close timing), `untimed`, `unsynced`, `proxyBytes` |
+| `close()` | Closes the sessions still open and the ledger |
+
+A session (`openSession`) has `id`, `provider`, `egress`, `cdpUrl` (it may carry the API key: never log it), `openedAt`, `closedAt`, and:
+
+- `connect()`: Playwright's `Browser` over its CDP connection, made once. A keep-alive command every 15 s keeps the provider's idle timeout from ending a session that is in use.
+- `newPage()`: always a new page in the default context: the page a remote browser starts with is not always one that can be navigated.
+- `close()`: disconnects and releases it; only the first call does. The ledger records it closed in any case. Throws when the provider could not release it: the provider then ends it by itself.
+
+A session and a `OneBrowser` are async-disposable: `await using session = await browsers.openSession({ provider: 'steel' })` closes the session at the end of its block (Node 24 or later; on Node 22 call `close()`).
+
+### Session options: one meaning on every provider
+
+| Option | Default | Meaning |
+|---|---|---|
+| `proxyCountry` | `null` | A country code: the provider's proxy in that country. `null`: its default egress |
+| `idleTimeoutSec` | 60 | A session whose client is gone (its process was killed) ends this long after at the latest. At least 30 (twice the keep-alive interval) |
+| `maxDurationMs` | 15 min | The session ends this long after it was opened at the latest: this process closes it then, and the provider's own limit is set to it where its API takes one |
+
+`sessionOptions(options)` returns them with the defaults filled in and throws when one is unknown or out of range, so that a program can check its configuration before it opens any session.
+
+How each provider meets them:
+
+| Provider | `proxyCountry` | `idleTimeoutSec` | `maxDurationMs` |
+|---|---|---|---|
+| `steel` | residential proxy | `inactivityTimeout` (no CDP commands) | `timeout` |
+| `tinyfish` | residential proxy | `timeout_seconds` (no CDP commands) | this process only |
+| `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 |
+
+### Quota
+
+| Provider | Quota, unit | Read from |
+|---|---|---|
+| `steel` | balance, USD | `GET /v1/credits/balance`, the endpoint of Steel's dashboard (not in its API docs) |
+| `tinyfish` | wallet, USD | [`GET /v1/wallet`](https://docs.tinyfish.ai/wallet); a session refused with 402 throws `QuotaError` |
+| `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` |
+
+### API keys
+
+`apiKey` in the provider's settings, else the environment variable `<PROVIDER>_API_KEY` (`STEEL_API_KEY`, …; `apiKeyEnv(provider)` names it), else the file named by `<PROVIDER>_API_KEY_FILE`. An empty value counts as unset.
+
+### The ledger
+
+One SQLite file per machine by default: `$ONEBROWSER_DB`, else `onebrowser/sessions.db` in `$XDG_DATA_HOME` (default `~/.local/share`). Every program that uses onebrowser on the machine shares it, each under its own `client`, so the record of a provider account's sessions is whole whichever program opened them; several processes may write to it at once. Each session is recorded when its provider has created it (it is billed from then on, also when connecting fails afterwards), closed when released, and completed with the provider's own record by `syncUsage()` once it has ended.
+
+## Command line
+
+The provider accounts and the ledger belong to the machine rather than to one program, so the `onebrowser` command reads them without a program of your own. It opens no sessions.
+
+```sh
+npx onebrowser quota                 # what each provider account with an API key has left
+npx onebrowser quota steel kernel    # only these; one without an API key is a failed reading
+npx onebrowser usage --days 7        # the ledger's sessions per UTC day, provider and client, today included
+npx onebrowser usage --json --env-file .env
+```
+
+`usage` first fetches the providers' records of the sessions that have ended, as `syncUsage()` does. With `--json`, `quota` prints an array of what `quota()` returns, with the provider: `{ provider, remaining, unit, renewsAt }`, or `{ provider, error }` for a failed reading; `usage` prints `{ ledger, since, sessions, failed }`, where `sessions` is what `usage()` returns and `failed` what `syncUsage()` could not fetch. API keys are read as by the library, from the environment (`--env-file PATH` loads a file into it first). Exit status: 0 done, 1 a reading failed, 2 the command line is wrong.
+
+## Adding a provider
+
+Write `src/providers/<name>.js` and register it in `ADAPTERS` (`src/providers/index.js`, where the contract is):
+
+- `defaults`: its settings (API base URLs, plan facts).
+- `createSession(settings, apiKey, { proxyCountry, idleTimeoutSec, maxDurationMs }) → { id, cdpUrl, egress }`: maps the session options onto the provider's parameters; throws `QuotaError` when the provider refuses the session for the account's quota.
+- `releaseSession(settings, apiKey, session)`.
+- `sessionUsage(settings, apiKey, [{ id, openedAt, closedAt }]) → [{ id, durationMs, proxyBytes }]`: the record of those sessions that have ended: the provider's own, or the ledger's timing for a provider whose records its API key cannot read.
+- `quota(settings, apiKey, history) → { remaining, unit, renewsAt? }`: `history.sessionMsSince(ms)` is the ledger's record of the provider's sessions, for a provider that cannot report its own usage.
+
+Requests go through `src/providers/http.js`: every status other than 2xx is an `HttpError` (with `status`), so an adapter handles only the statuses that mean something of their own, such as a quota refusal.
+
+A program can also pass an adapter of its own in `adapters`, without changing onebrowser.
+
+## Development
+
+`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).
+
+## License
+
+[MIT](LICENSE)

package/bin/onebrowser.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { run } from '../src/cli.js';
+
+process.exitCode = await run(process.argv.slice(2));

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "onebrowser",
+  "version": "0.1.1",
+  "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"],
+  "license": "MIT",
+  "author": "Richard Wang",
+  "repository": { "type": "git", "url": "git+https://github.com/i-richardwang/onebrowser.git" },
+  "homepage": "https://github.com/i-richardwang/onebrowser#readme",
+  "bugs": "https://github.com/i-richardwang/onebrowser/issues",
+  "type": "module",
+  "exports": "./src/index.js",
+  "bin": { "onebrowser": "bin/onebrowser.js" },
+  "files": ["src", "bin"],
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "engines": { "node": ">=22.13" },
+  "dependencies": {
+    "playwright-core": "^1.48.0"
+  }
+}

package/src/cli.js

@@ -0,0 +1,138 @@
+import { parseArgs } from 'node:util';
+import { apiKeyEnv } from './credentials.js';
+import { OneBrowser } from './index.js';
+
+const DAY_MS = 864e5;
+
+const day = (ms) => new Date(ms).toISOString().slice(0, 10);
+
+/** The command line is wrong: exit status 2 */
+class CommandLineError extends Error {}
+
+/** Options of every command */
+const GLOBAL_OPTIONS = {
+  json: { type: 'boolean' },
+  'env-file': { type: 'string' },
+  help: { type: 'boolean', short: 'h' },
+};
+
+/**
+ * The commands: their own options, whether they take arguments, and run(browsers, values, args, { out, err })
+ * → exit status
+ */
+const COMMANDS = {
+  quota: {
+    positionals: true,
+    async run(browsers, { json }, names, { out }) {
+      const unknown = names.filter((n) => !browsers.providers.includes(n));
+      if (unknown.length) throw new CommandLineError(`unknown provider ${unknown.join(', ')} (expected ${browsers.providers.join(', ')})`);
+      const asked = names.length ? names : browsers.providers.filter((p) => isReady(browsers, p));
+      if (!asked.length) throw new Error(`no provider has an API key: set ${browsers.providers.map(apiKeyEnv).join(', ')}`);
+      const quotas = await Promise.all(asked.map((provider) => browsers.quota(provider).then((q) => ({ provider, ...q }), (e) => ({ provider, error: e.message }))));
+      if (json) out.write(`${JSON.stringify(quotas, null, 2)}\n`);
+      else {
+        for (const q of quotas) {
+          const text = q.error ? `unknown (${q.error})` : `${Number(q.remaining.toFixed(2))} ${q.unit} left${q.renewsAt ? `, renews ${day(q.renewsAt)}` : ''}`;
+          out.write(`${q.provider.padEnd(14)} ${text}\n`);
+        }
+      }
+      return quotas.some((q) => q.error) ? 1 : 0;
+    },
+  },
+
+  usage: {
+    options: { days: { type: 'string', default: '30' } },
+    async run(browsers, { days, json }, args, { out, err }) {
+      const n = Number(days);
+      if (!(Number.isInteger(n) && n >= 1)) throw new CommandLineError(`--days must be a whole number ≥ 1, not ${days}`);
+      const since = new Date().setUTCHours(0, 0, 0, 0) - (n - 1) * DAY_MS;
+      const { failed } = await browsers.syncUsage();
+      for (const f of failed) err.write(`${f.provider}: the provider's records were not fetched (${f.error})\n`);
+      const sessions = browsers.usage({ since });
+      if (json) out.write(`${JSON.stringify({ ledger: browsers.ledgerPath, since: day(since), sessions, failed }, null, 2)}\n`);
+      else {
+        out.write(`sessions since ${day(since)} in ${browsers.ledgerPath}:\n`);
+        if (!sessions.length) out.write('  none\n');
+        for (const r of sessions) out.write(usageLine(`${r.day} ${r.provider} ${r.client}`, r));
+        for (const [provider, rows] of Map.groupBy(sessions, (r) => r.provider)) {
+          if (rows.length > 1) out.write(usageLine(`total ${provider}`, sumUsage(rows)));
+        }
+      }
+      return failed.length ? 1 : 0;
+    },
+  },
+};
+
+const help = (providers) => `onebrowser: the quotas of remote browser provider accounts, and the sessions in this machine's ledger
+
+Usage:
+  onebrowser quota [PROVIDER...]   what each provider account has left; default: every provider with an API key
+  onebrowser usage [--days N]      sessions per UTC day, provider and client in the last N UTC days, today
+                                   included (default 30), after fetching the providers' records of ended sessions
+
+Options:
+  --json             JSON on stdout instead of text
+  --env-file PATH    read environment variables (API keys) from PATH first
+  -h, --help
+
+Environment:
+${providers.map((p) => `  ${apiKeyEnv(p).padEnd(22)} API key of ${p}, or ${apiKeyEnv(p)}_FILE naming a file that holds it`).join('\n')}
+  ONEBROWSER_DB          the ledger file (default: onebrowser/sessions.db in $XDG_DATA_HOME, else ~/.local/share)
+
+Exit status: 0 done, 1 a reading failed, 2 the command line is wrong.
+`;
+
+function isReady(browsers, provider) {
+  try {
+    browsers.checkReady(provider);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const USAGE_FIELDS = ['sessions', 'minutes', 'untimed', 'unsynced', 'proxyBytes'];
+
+const sumUsage = (rows) => Object.fromEntries(USAGE_FIELDS.map((k) => [k, rows.reduce((t, r) => t + r[k], 0)]));
+
+const usageLine = (label, r) =>
+  `  ${label.padEnd(36)} ${String(r.sessions).padStart(5)} sessions ${r.minutes.toFixed(1).padStart(8)} min` +
+  ` ${(r.proxyBytes / 1e6).toFixed(1).padStart(7)} MB proxy` +
+  (r.untimed ? `  (${r.untimed} untimed)` : '') +
+  (r.unsynced ? `  (${r.unsynced} not reported by the provider yet)` : '') +
+  '\n';
+
+/** The command and its parsed options: parsed once to find the command, then again with only its own options */
+function parseCommandLine(argv) {
+  const every = Object.assign({}, GLOBAL_OPTIONS, ...Object.values(COMMANDS).map((c) => c.options));
+  const [name] = parseArgs({ args: argv, options: every, allowPositionals: true }).positionals;
+  if (name !== undefined && !Object.hasOwn(COMMANDS, name)) throw new CommandLineError(`unknown command ${name} (expected ${Object.keys(COMMANDS).join(', ')})`);
+  const command = COMMANDS[name]; // none without a name: the help
+  const { values, positionals } = parseArgs({ args: argv, options: { ...GLOBAL_OPTIONS, ...command?.options }, allowPositionals: true });
+  const args = positionals.slice(1);
+  if (args.length && !command?.positionals) throw new CommandLineError(`${name} takes no arguments, not ${args.join(' ')}`);
+  return { command, values, args };
+}
+
+/**
+ * The onebrowser command (bin/onebrowser.js): runs `argv` and returns the exit status. browsers: the OneBrowser
+ * to read (default: one with the built-in providers and the default ledger); it is closed when done.
+ */
+export async function run(argv, { out = process.stdout, err = process.stderr, browsers } = {}) {
+  try {
+    const { command, values, args } = parseCommandLine(argv);
+    if (values['env-file']) process.loadEnvFile(values['env-file']);
+    browsers ??= new OneBrowser({ client: 'onebrowser' });
+    if (values.help || !command) {
+      (values.help ? out : err).write(help(browsers.providers));
+      return values.help ? 0 : 2;
+    }
+    return await command.run(browsers, values, args, { out, err });
+  } catch (e) {
+    const misuse = e instanceof CommandLineError || e.code?.startsWith('ERR_PARSE_ARGS');
+    err.write(`onebrowser: ${e.message}\n${misuse ? 'see onebrowser --help\n' : ''}`);
+    return misuse ? 2 : 1;
+  } finally {
+    await browsers?.close();
+  }
+}

package/src/credentials.js

@@ -0,0 +1,22 @@
+import fs from 'node:fs';
+
+/** The environment variable holding a provider's API key: STEEL_API_KEY for `steel` */
+export const apiKeyEnv = (provider) => `${provider.toUpperCase()}_API_KEY`;
+
+/**
+ * API key of a provider: `apiKey` as given in its settings, else the environment variable apiKeyEnv(provider),
+ * else the file named by that variable with _FILE appended. An empty value counts as unset. Throws when there is
+ * none.
+ */
+export function readApiKey(provider, apiKey) {
+  if (apiKey?.trim()) return apiKey.trim();
+  const env = apiKeyEnv(provider);
+  const file = process.env[`${env}_FILE`];
+  let key = process.env[env];
+  if (!key && file) {
+    if (!fs.existsSync(file)) throw new Error(`${provider} key: ${env}_FILE names no file (${file})`);
+    key = fs.readFileSync(file, 'utf8');
+  }
+  if (!key?.trim()) throw new Error(`missing ${provider} key: set ${env} or ${env}_FILE`);
+  return key.trim();
+}

package/src/errors.js

@@ -0,0 +1,2 @@
+/** A provider refused a session because the account's quota is used up */
+export class QuotaError extends Error {}

package/src/index.js

@@ -0,0 +1,180 @@
+import { readApiKey } from './credentials.js';
+import { QuotaError } from './errors.js';
+import { defaultLedgerPath, Ledger } from './ledger.js';
+import { ADAPTERS, checkAdapter } from './providers/index.js';
+import { KEEP_ALIVE_MS, Session } from './session.js';
+
+export { apiKeyEnv } from './credentials.js';
+export { QuotaError };
+
+/** Session options when openSession() is not given them */
+const SESSION_DEFAULTS = {
+  proxyCountry: null, // null: the provider's default egress
+  idleTimeoutSec: 60, // a session whose client is gone (its process was killed) ends this long after at the latest
+  maxDurationMs: 15 * 60_000,
+};
+
+/**
+ * The session options of openSession() with the defaults filled in (SESSION_DEFAULTS); throws when one is unknown
+ * or out of range, so that a program can check its configuration before it opens any session:
+ *   proxyCountry     country code: the provider's proxy there; null: its default egress
+ *   idleTimeoutSec   a session whose client is gone ends this long after at the latest; at least twice the
+ *                    keep-alive interval (session.js)
+ *   maxDurationMs    the session ends this long after it was opened at the latest
+ */
+export function sessionOptions(options = {}) {
+  const unknown = Object.keys(options).filter((k) => !Object.hasOwn(SESSION_DEFAULTS, k));
+  if (unknown.length) throw new Error(`unknown session option ${unknown.join(', ')} (expected ${Object.keys(SESSION_DEFAULTS).join(', ')})`);
+  const o = { ...SESSION_DEFAULTS, ...options };
+  if (!(Number.isFinite(o.idleTimeoutSec) && o.idleTimeoutSec * 1000 >= 2 * KEEP_ALIVE_MS)) {
+    throw new Error(`idleTimeoutSec must be at least ${(2 * KEEP_ALIVE_MS) / 1000} (twice the keep-alive interval), not ${o.idleTimeoutSec}`);
+  }
+  if (!(Number.isFinite(o.maxDurationMs) && o.maxDurationMs > 0)) throw new Error(`maxDurationMs must be a number > 0, not ${o.maxDurationMs}`);
+  return o;
+}
+
+/**
+ * Remote browsers from several providers behind one interface: a session is asked for by provider name, the way
+ * an LLM request names its model. Every session is recorded in a ledger (ledger.js), which the usage of each
+ * provider account and, for providers that cannot report it themselves, its quota are read from.
+ *
+ * Which provider to use, how many sessions to hold and when to stop using one are the caller's decisions:
+ * OneBrowser opens the sessions it is asked for.
+ *
+ * new OneBrowser({ client, ledgerPath, providers, adapters })
+ *   client       the program using it, recorded with each session (several programs may share one ledger)
+ *   ledgerPath   SQLite file of the ledger (default: defaultLedgerPath() in ledger.js; ':memory:' for tests),
+ *                opened when first needed
+ *   providers    settings per provider name: apiKey (else from the environment, see credentials.js), and the
+ *                adapter's own settings on top of its defaults (providers/<name>.js)
+ *   adapters     further adapters by provider name, or replacements of built-in ones (providers/index.js)
+ */
+export class OneBrowser {
+  #providers = new Map(); // name → { adapter, settings: its defaults with the given ones on top, apiKey: the one given }
+  #ledger = null;
+  #open = new Set();
+
+  constructor({ client, ledgerPath = defaultLedgerPath(), providers = {}, adapters = {} }) {
+    if (!client?.trim()) throw new Error('onebrowser: client must name the program using it');
+    this.client = client;
+    this.ledgerPath = ledgerPath;
+    for (const [name, adapter] of Object.entries({ ...ADAPTERS, ...adapters })) {
+      checkAdapter(name, adapter);
+      const { apiKey, ...settings } = providers[name] ?? {};
+      this.#providers.set(name, { adapter, settings: { ...adapter.defaults, ...settings }, apiKey });
+    }
+    const unknown = Object.keys(providers).filter((name) => !this.#providers.has(name));
+    if (unknown.length) throw new Error(`onebrowser: no adapter for provider ${unknown.join(', ')}`);
+  }
+
+  /** Names of the providers it can open sessions with */
+  get providers() {
+    return [...this.#providers.keys()];
+  }
+
+  get #store() {
+    return (this.#ledger ??= new Ledger(this.ledgerPath));
+  }
+
+  /** The adapter, settings and API key of `provider`; throws when it is unknown or has no API key */
+  #ready(provider) {
+    const p = this.#providers.get(provider);
+    if (!p) throw new Error(`unknown provider ${provider} (expected ${this.providers.join(', ')})`);
+    return { ...p, apiKey: readApiKey(provider, p.apiKey) };
+  }
+
+  /** Throws when sessions cannot be opened with `provider`: unknown, or no API key */
+  checkReady(provider) {
+    this.#ready(provider);
+  }
+
+  /**
+   * A new session with `provider`, recorded in the ledger once the provider has created it; options: see
+   * sessionOptions(). Throws when the provider does not create one; QuotaError when it refuses for the account's
+   * quota.
+   */
+  async openSession({ provider, ...options }) {
+    const { adapter, settings, apiKey } = this.#ready(provider);
+    const o = sessionOptions(options);
+    let remote;
+    try {
+      remote = await adapter.createSession(settings, apiKey, o);
+    } catch (e) {
+      if (e instanceof QuotaError) throw e;
+      throw new Error(`failed to create a ${provider} session: ${e.message}`);
+    }
+    const session = new Session({
+      provider, remote, maxDurationMs: o.maxDurationMs,
+      release: async (s) => {
+        this.#open.delete(s);
+        this.#store.closed(s);
+        await adapter.releaseSession(settings, apiKey, s);
+      },
+    });
+    try {
+      this.#store.opened({ provider, id: session.id, client: this.client, openedAt: session.openedAt });
+    } catch (e) {
+      await session.close().catch(() => {}); // a session the ledger has no record of is not handed out
+      throw e;
+    }
+    this.#open.add(session);
+    return session;
+  }
+
+  /**
+   * What is left of the account's quota with `provider`: { remaining, unit, renewsAt } in the provider's own
+   * unit; renewsAt (ms) when it renews by itself, null when only a top-up renews it. Throws when it cannot be read.
+   */
+  async quota(provider) {
+    const { adapter, settings, apiKey } = this.#ready(provider);
+    const q = await adapter.quota(settings, apiKey, this.#store.history(provider));
+    if (!(Number.isFinite(q?.remaining) && typeof q.unit === 'string')) throw new Error(`${provider} answered no quota: ${JSON.stringify(q)}`);
+    return { remaining: q.remaining, unit: q.unit, renewsAt: q.renewsAt ?? null };
+  }
+
+  /**
+   * Stores each provider's record (duration, proxy traffic) of the sessions in the ledger that have ended and have
+   * none yet; sessions still running wait for a later call. A provider that cannot be reached, or has no API key,
+   * is left for a later call too. Sessions of a provider it has no adapter for (another program's own) are left
+   * to the programs that have one. Returns { reported: sessions completed, failed: [{ provider, error }] }.
+   */
+  async syncUsage() {
+    const store = this.#store;
+    let reported = 0;
+    const failed = [];
+    for (const [provider, rows] of Map.groupBy(store.awaitingUsage(this.providers), (s) => s.provider)) {
+      try {
+        const { adapter, settings, apiKey } = this.#ready(provider);
+        const usage = await adapter.sessionUsage(settings, apiKey, rows);
+        store.tx(() => usage.forEach((u) => store.recordUsage(provider, u)));
+        reported += usage.length;
+      } catch (e) {
+        failed.push({ provider, error: e.message });
+      }
+    }
+    return { reported, failed };
+  }
+
+  /**
+   * Sessions opened since `since` (ms), per UTC day, provider and client:
+   * [{ day, provider, client, sessions, minutes, untimed, unsynced, proxyBytes }]. Minutes are the provider's
+   * record where syncUsage has stored it, otherwise the open-to-close timing of the process that opened the
+   * session; untimed: sessions with neither (their process ended before closing them and the provider has not
+   * reported them yet); unsynced: sessions without the provider's record.
+   */
+  usage({ since }) {
+    return this.#store.usage(since);
+  }
+
+  /** Closes every session still open (their release errors are ignored: the providers end those) and the ledger */
+  async close() {
+    await Promise.all([...this.#open].map((s) => s.close().catch(() => {})));
+    this.#ledger?.close();
+    this.#ledger = null;
+  }
+
+  /** close(), for `await using browsers = new OneBrowser(…)` */
+  [Symbol.asyncDispose]() {
+    return this.close();
+  }
+}

package/src/ledger.js

@@ -0,0 +1,112 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+
+/**
+ * Where the ledger lives unless a path is given: $ONEBROWSER_DB, else onebrowser/sessions.db in the user's data
+ * directory ($XDG_DATA_HOME, default ~/.local/share). One ledger per machine is shared by every project on it, so
+ * that the record of a provider account's sessions is whole, whichever project opened them.
+ */
+export function defaultLedgerPath() {
+  if (process.env.ONEBROWSER_DB) return process.env.ONEBROWSER_DB;
+  const data = process.env.XDG_DATA_HOME || path.join(os.homedir(), '.local', 'share');
+  return path.join(data, 'onebrowser', 'sessions.db');
+}
+
+/**
+ * sessions   every remote browser session: recorded when its provider has created it (it is billed from then on,
+ *            even if connecting fails), closed when released, and completed with the provider's own record
+ *            (duration, proxy traffic) once the session has ended and syncUsage has fetched it
+ */
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS sessions (
+  provider      TEXT NOT NULL,
+  id            TEXT NOT NULL,            -- the session id its provider gave it
+  client        TEXT NOT NULL,            -- the program that opened it (OneBrowser's client)
+  opened_at     TEXT NOT NULL,            -- when the provider created it
+  closed_at     TEXT,                     -- when it was released; empty if its process ended first
+  duration_ms   INTEGER,                  -- the provider's record, once the session has ended
+  proxy_bytes   INTEGER,                  -- proxy traffic in the provider's record
+  synced_at     TEXT,                     -- when the provider's record was stored; empty = not yet
+  PRIMARY KEY (provider, id)
+);
+CREATE INDEX IF NOT EXISTS idx_sessions_opened ON sessions(provider, opened_at);
+`;
+
+/** Duration of a session: the provider's record, else the open-to-close timing of the process that opened it */
+const SESSION_MS = 'COALESCE(duration_ms, CAST((julianday(closed_at) - julianday(opened_at)) * 86400000 AS INTEGER))';
+
+const iso = (ms) => new Date(ms).toISOString();
+const int = (x) => (x === null || x === undefined || !Number.isFinite(Number(x)) ? null : Math.trunc(Number(x)));
+
+export class Ledger {
+  #db;
+  #stmts = new Map();
+
+  constructor(file) {
+    if (file !== ':memory:') fs.mkdirSync(path.dirname(file), { recursive: true });
+    this.#db = new DatabaseSync(file);
+    this.#db.exec('PRAGMA journal_mode=WAL; PRAGMA busy_timeout=5000;'); // several processes share it
+    this.#db.exec(SCHEMA);
+  }
+
+  #q(sql) {
+    let s = this.#stmts.get(sql);
+    if (!s) this.#stmts.set(sql, (s = this.#db.prepare(sql)));
+    return s;
+  }
+
+  opened({ provider, id, client, openedAt }) {
+    this.#q('INSERT INTO sessions (provider, id, client, opened_at) VALUES (?,?,?,?)').run(provider, id, client, iso(openedAt));
+  }
+
+  closed({ provider, id, closedAt }) {
+    this.#q('UPDATE sessions SET closed_at=? WHERE provider=? AND id=? AND closed_at IS NULL').run(iso(closedAt), provider, id);
+  }
+
+  /** The record of one provider's sessions, as a provider adapter reads it for its quota (providers/index.js) */
+  history(provider) {
+    return {
+      /** Session time (ms) of the sessions opened since `since` (ms) that have a duration */
+      sessionMsSince: (since) => this.#q(`SELECT COALESCE(SUM(${SESSION_MS}), 0) ms FROM sessions WHERE provider=? AND opened_at >= ?`).get(provider, iso(since)).ms,
+    };
+  }
+
+  /** Sessions with one of `providers` whose provider's record has not been stored yet: [{ provider, id, openedAt, closedAt }] (ISO times) */
+  awaitingUsage(providers) {
+    return this.#q(
+      'SELECT provider, id, opened_at openedAt, closed_at closedAt FROM sessions WHERE synced_at IS NULL AND provider IN (SELECT value FROM json_each(?)) ORDER BY opened_at',
+    ).all(JSON.stringify(providers));
+  }
+
+  recordUsage(provider, { id, durationMs, proxyBytes }) {
+    this.#q('UPDATE sessions SET duration_ms=?, proxy_bytes=?, synced_at=? WHERE provider=? AND id=?').run(int(durationMs), int(proxyBytes), iso(Date.now()), provider, id);
+  }
+
+  tx(fn) {
+    this.#db.exec('BEGIN');
+    try {
+      const r = fn();
+      this.#db.exec('COMMIT');
+      return r;
+    } catch (e) {
+      this.#db.exec('ROLLBACK');
+      throw e;
+    }
+  }
+
+  /** See OneBrowser.usage() */
+  usage(since) {
+    return this.#q(
+      `SELECT substr(opened_at, 1, 10) day, provider, client, COUNT(*) sessions,
+              COALESCE(SUM(${SESSION_MS}), 0) / 60000.0 minutes, SUM(${SESSION_MS} IS NULL) untimed,
+              SUM(synced_at IS NULL) unsynced, COALESCE(SUM(proxy_bytes), 0) proxyBytes
+       FROM sessions WHERE opened_at >= ? GROUP BY day, provider, client ORDER BY day, provider, client`,
+    ).all(iso(since));
+  }
+
+  close() {
+    this.#db.close();
+  }
+}

package/src/providers/http.js

@@ -0,0 +1,31 @@
+/** A provider API answered with a status other than 2xx; text: the start of its answer */
+export class HttpError extends Error {
+  constructor(status, answer) {
+    const text = answer.slice(0, 300);
+    super(`HTTP ${status}: ${text}`);
+    this.status = status;
+    this.text = text;
+  }
+}
+
+/**
+ * One request to a provider API: { body (its JSON; null when empty), headers }. `body` is sent as JSON. Throws
+ * HttpError for a status other than 2xx, so that an adapter handles only the statuses that mean something of
+ * their own (a quota refusal, a session already gone).
+ */
+export async function request(url, { method = 'GET', headers = {}, body, timeoutMs = 30_000 } = {}) {
+  const r = await fetch(url, {
+    method,
+    headers: body === undefined ? headers : { ...headers, 'Content-Type': 'application/json' },
+    body: body === undefined ? undefined : JSON.stringify(body),
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+  const text = await r.text();
+  if (!r.ok) throw new HttpError(r.status, text);
+  return { body: text ? JSON.parse(text) : null, headers: r.headers };
+}
+
+/** request() → the response's JSON */
+export async function json(url, options) {
+  return (await request(url, options)).body;
+}

package/src/providers/hyperbrowser.js

@@ -0,0 +1,42 @@
+import { json } from './http.js';
+
+/**
+ * Hyperbrowser (https://hyperbrowser.ai/docs). Without a proxy a session uses one of Hyperbrowser's US
+ * datacenter IPs, drawn from a pool: consecutive sessions usually differ, but an IP can come back.
+ * proxyCountry selects its residential proxy (paid plans only). It has no idle timeout: a session ends when its
+ * CDP connection closes, which meets any idleTimeoutSec, and after maxDurationMs in any case, which Hyperbrowser
+ * takes in whole minutes.
+ */
+export const defaults = {
+  apiBase: 'https://api.hyperbrowser.ai/api',
+};
+
+const headers = (apiKey) => ({ 'x-api-key': apiKey });
+
+export async function createSession(settings, apiKey, { proxyCountry, maxDurationMs }) {
+  const body = { timeoutMinutes: Math.ceil(maxDurationMs / 60_000) };
+  if (proxyCountry) Object.assign(body, { useProxy: true, proxyCountry });
+  const s = await json(`${settings.apiBase}/session`, { method: 'POST', headers: headers(apiKey), body, timeoutMs: 90_000 });
+  return { id: s.id, cdpUrl: s.wsEndpoint, egress: proxyCountry ? `proxy ${proxyCountry}` : 'datacenter IP' };
+}
+
+/** Succeeds also for a session that has already ended (its CDP connection closed first) */
+export async function releaseSession(settings, apiKey, session) {
+  await json(`${settings.apiBase}/session/${session.id}/stop`, { method: 'PUT', headers: headers(apiKey) });
+}
+
+/** The team's credits left (the endpoint of Hyperbrowser's SDK; it is not in Hyperbrowser's API docs) */
+export async function quota(settings, apiKey) {
+  const { remaining } = await json(`${settings.apiBase}/team/credit-info`, { headers: headers(apiKey) });
+  return { remaining, unit: 'credits' };
+}
+
+/** Usage of the sessions among `sessions` that have ended (have an endTime), fetched by id. Times are epoch ms, as numbers or strings */
+export async function sessionUsage(settings, apiKey, sessions) {
+  const usage = [];
+  for (const { id } of sessions) {
+    const s = await json(`${settings.apiBase}/session/${id}`, { headers: headers(apiKey) });
+    if (s.endTime) usage.push({ id, durationMs: Number(s.endTime) - Number(s.startTime), proxyBytes: Number(s.proxyDataConsumed) });
+  }
+  return usage;
+}

package/src/providers/index.js

@@ -0,0 +1,37 @@
+import * as hyperbrowser from './hyperbrowser.js';
+import * as kernel from './kernel.js';
+import * as lightpanda from './lightpanda.js';
+import * as steel from './steel.js';
+import * as tinyfish from './tinyfish.js';
+
+/**
+ * Provider adapters, by provider name: the only provider-specific code. Each exports:
+ *   defaults                 its settings (API base URLs, plan facts such as monthlyHours); OneBrowser's
+ *                            `providers` option overrides them per provider. The API key is not among them:
+ *                            each function gets it as its own argument
+ *   createSession(settings, apiKey, options) → { id, cdpUrl, egress }
+ *       options: { proxyCountry, idleTimeoutSec, maxDurationMs } (OneBrowser.openSession), mapped onto the
+ *       provider's own parameters. Throws on failure; QuotaError (errors.js) when the provider refuses the
+ *       session because the account's quota is used up
+ *   releaseSession(settings, apiKey, session)   ends the session; throws on failure
+ *   sessionUsage(settings, apiKey, [{ id, openedAt, closedAt }]) → [{ id, durationMs, proxyBytes }]
+ *       the record of those sessions that have ended: the provider's own, or, for a provider whose records the
+ *       API key cannot read, the ledger's timing (closedAt is empty for a session no process closed); throws on
+ *       failure
+ *   quota(settings, apiKey, history) → { remaining, unit, renewsAt? }
+ *       what is left of the account's quota, in the provider's own unit (USD, credits, hours, …), and when it
+ *       renews if it does by itself (ms); history: the ledger's record of the provider's sessions
+ *       (Ledger.history). Throws when it cannot be read
+ *
+ * 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 };
+
+const CONTRACT = ['createSession', 'releaseSession', 'sessionUsage', 'quota'];
+
+/** Throws unless `adapter` has the whole contract */
+export function checkAdapter(name, adapter) {
+  const missing = CONTRACT.filter((f) => typeof adapter?.[f] !== 'function');
+  if (missing.length) throw new Error(`provider ${name}: its adapter lacks ${missing.join(', ')}`);
+}

package/src/providers/kernel.js

@@ -0,0 +1,68 @@
+import { QuotaError } from '../errors.js';
+import { json, request } from './http.js';
+import { utcMonth } from './month.js';
+
+/**
+ * Kernel (https://www.kernel.sh/docs). Sessions are headless: Kernel's default is a headful browser, billed at
+ * a higher rate. A session uses the IP of the Kernel machine it runs on, a different one per session. Kernel's
+ * proxies are resources of their own, on paid plans, so proxyCountry is not supported. Closing the CDP
+ * connection does not end a session: Kernel keeps it in standby, unbilled but counting toward the plan's
+ * concurrent browsers, and deletes it idleTimeoutSec after its CDP client left (timeout_seconds), unless it is
+ * released before. It takes no limit on a session's length. An account at its spending cap is refused new
+ * sessions with 403.
+ */
+export const defaults = {
+  apiBase: 'https://api.onkernel.com',
+  monthlyHours: 80, // headless browser hours a month that the free plan's credits pay for, rounded down
+};
+
+const headers = (apiKey) => ({ Authorization: `Bearer ${apiKey}` });
+
+export async function createSession(settings, apiKey, { proxyCountry, idleTimeoutSec }) {
+  if (proxyCountry) throw new Error('proxyCountry is not supported by the kernel provider');
+  let s;
+  try {
+    s = await json(`${settings.apiBase}/browsers`, { method: 'POST', headers: headers(apiKey), body: { headless: true, timeout_seconds: idleTimeoutSec }, timeoutMs: 90_000 });
+  } catch (e) {
+    if (e.status === 403) throw new QuotaError(`spending cap reached: ${e.text}`);
+    throw e;
+  }
+  return { id: s.session_id, cdpUrl: s.cdp_ws_url, egress: 'datacenter IP' };
+}
+
+/** 404: Kernel has deleted the session already */
+export async function releaseSession(settings, apiKey, session) {
+  try {
+    await json(`${settings.apiBase}/browsers/${session.id}`, { method: 'DELETE', headers: headers(apiKey) });
+  } catch (e) {
+    if (e.status !== 404) throw e;
+  }
+}
+
+/**
+ * Browser hours left of the month's monthlyHours, after the uptime of every session of the account this month:
+ * Kernel's own records, which include sessions opened by any program. The sessions are listed newest first, so
+ * the listing stops at a page that holds none of this month. The hours are assumed to renew with each calendar
+ * month (UTC).
+ */
+export async function quota(settings, apiKey) {
+  const month = utcMonth();
+  let usedMs = 0;
+  for (let offset = 0; ; offset += 100) {
+    const r = await request(`${settings.apiBase}/browsers?status=all&limit=100&offset=${offset}`, { headers: headers(apiKey) });
+    const ofMonth = r.body.filter((s) => Date.parse(s.created_at) >= month.start);
+    usedMs += ofMonth.reduce((ms, s) => ms + (s.usage?.uptime_ms ?? 0), 0);
+    if (!ofMonth.length || r.headers.get('x-has-more') !== 'true') break;
+  }
+  return { remaining: settings.monthlyHours - usedMs / 3_600_000, unit: 'hours', renewsAt: month.next };
+}
+
+/** Usage of the sessions among `sessions` that Kernel has deleted and finished billing, fetched by id */
+export async function sessionUsage(settings, apiKey, sessions) {
+  const usage = [];
+  for (const { id } of sessions) {
+    const s = await json(`${settings.apiBase}/browsers/${id}?include_deleted=true`, { headers: headers(apiKey) });
+    if (s.usage_status === 'ready') usage.push({ id, durationMs: s.usage.uptime_ms, proxyBytes: null });
+  }
+  return usage;
+}

package/src/providers/lightpanda.js

@@ -0,0 +1,55 @@
+import { randomUUID } from 'node:crypto';
+import { utcMonth } from './month.js';
+
+/** Lightpanda closes a CDP connection after this long, whatever maxDurationMs asks for */
+const MAX_CONNECTION_MS = 15 * 60_000;
+
+/**
+ * Lightpanda Cloud (https://lightpanda.io/docs). It has no session API: a session is one CDP connection to
+ * connectBase, and it ends when that connection closes, which meets any idleTimeoutSec, and at the latest after
+ * MAX_CONNECTION_MS. Its `datacenter` proxy gives each session one IP from a shared pool, a different one per
+ * session; proxyCountry asks the pool for IPs in that country. Its engine is Lightpanda's own, not Chromium.
+ */
+export const defaults = {
+  connectBase: 'wss://euwest.cloud.lightpanda.io/ws',
+  monthlyHours: 10, // browser hours a month on the free plan
+};
+
+export async function createSession(settings, apiKey, { proxyCountry }) {
+  const query = new URLSearchParams({ token: apiKey, proxy: 'datacenter' });
+  if (proxyCountry) query.set('country', proxyCountry.toLowerCase());
+  return {
+    id: randomUUID(),
+    cdpUrl: `${settings.connectBase}?${query}`,
+    egress: proxyCountry ? `datacenter IP, ${proxyCountry}` : 'datacenter IP',
+  };
+}
+
+/** Closing the CDP connection has ended the session */
+export async function releaseSession() {}
+
+/**
+ * Browser hours left of the month's monthlyHours. Lightpanda's console shows the month's usage, but the token
+ * cannot read it: the month's usage is the ledger's record of the sessions (history), which is all of it while
+ * the account is used through ledgers of this machine only. The hours are assumed to renew with each calendar
+ * month (UTC).
+ */
+export async function quota(settings, apiKey, history) {
+  const month = utcMonth();
+  const usedHours = history.sessionMsSince(month.start) / 3_600_000;
+  return { remaining: settings.monthlyHours - usedHours, unit: 'hours', renewsAt: month.next };
+}
+
+/**
+ * Lightpanda shows its records of sessions only in its console, which the token cannot read, so a session's
+ * record is the ledger's timing, which is exact: the session lasted as long as its CDP connection. A session no
+ * process closed (its process was killed) has ended once MAX_CONNECTION_MS have passed, untimed.
+ */
+export async function sessionUsage(settings, apiKey, sessions) {
+  const usage = [];
+  for (const { id, openedAt, closedAt } of sessions) {
+    if (closedAt) usage.push({ id, durationMs: Date.parse(closedAt) - Date.parse(openedAt), proxyBytes: null });
+    else if (Date.now() - Date.parse(openedAt) > MAX_CONNECTION_MS) usage.push({ id, durationMs: null, proxyBytes: null });
+  }
+  return usage;
+}

package/src/providers/month.js

@@ -0,0 +1,5 @@
+/** The current calendar month (UTC): its first ms, and the first ms of the next month */
+export function utcMonth() {
+  const d = new Date();
+  return { start: Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), 1), next: Date.UTC(d.getUTCFullYear(), d.getUTCMonth() + 1, 1) };
+}

package/src/providers/steel.js

@@ -0,0 +1,44 @@
+import { json } from './http.js';
+
+/**
+ * Steel.dev (https://docs.steel.dev). Without a proxy a session uses one of Steel's US datacenter IPs,
+ * a different one per session; proxyCountry selects a Steel residential proxy. Steel ends a session after
+ * idleTimeoutSec without CDP commands (inactivityTimeout), and after maxDurationMs in any case (timeout).
+ */
+export const defaults = {
+  apiBase: 'https://api.steel.dev/v1',
+  connectBase: 'wss://connect.steel.dev',
+};
+
+const headers = (apiKey) => ({ 'steel-api-key': apiKey });
+
+export async function createSession(settings, apiKey, { proxyCountry, idleTimeoutSec, maxDurationMs }) {
+  const body = { timeout: maxDurationMs, inactivityTimeout: idleTimeoutSec * 1000, optimizeBandwidth: true };
+  if (proxyCountry) body.useProxy = { geolocation: { country: proxyCountry } };
+  const s = await json(`${settings.apiBase}/sessions`, { method: 'POST', headers: headers(apiKey), body, timeoutMs: 90_000 });
+  return {
+    id: s.id,
+    cdpUrl: `${settings.connectBase}?apiKey=${apiKey}&sessionId=${s.id}`,
+    egress: proxyCountry ? `proxy ${proxyCountry}` : 'datacenter IP',
+  };
+}
+
+export async function releaseSession(settings, apiKey, session) {
+  await json(`${settings.apiBase}/sessions/${session.id}/release`, { method: 'POST', headers: headers(apiKey), body: {} });
+}
+
+/** The account's balance in USD, as Steel's dashboard reads it (the endpoint is not in Steel's API docs) */
+export async function quota(settings, apiKey) {
+  const { balanceCents } = await json(`${settings.apiBase}/credits/balance`, { headers: headers(apiKey) });
+  return { remaining: balanceCents / 100, unit: 'USD' };
+}
+
+/** Usage of the sessions among `sessions` that have ended, fetched by id: the session list cannot be filtered by time */
+export async function sessionUsage(settings, apiKey, sessions) {
+  const usage = [];
+  for (const { id } of sessions) {
+    const s = await json(`${settings.apiBase}/sessions/${id}`, { headers: headers(apiKey) });
+    if (s.status !== 'live') usage.push({ id, durationMs: s.duration, proxyBytes: s.proxyBytesUsed });
+  }
+  return usage;
+}

package/src/providers/tinyfish.js

@@ -0,0 +1,55 @@
+import { QuotaError } from '../errors.js';
+import { json } from './http.js';
+
+/**
+ * TinyFish Browser API (https://docs.tinyfish.ai/browser-api): residential proxy per session, country chosen by
+ * proxy_config.country_code. TinyFish ends a session after idleTimeoutSec without CDP commands (timeout_seconds);
+ * it takes no limit on a session's length. Sessions are paid from the account's wallet; with too little in it,
+ * creating one answers 402.
+ */
+export const defaults = {
+  apiBase: 'https://api.browser.tinyfish.ai',
+  walletUrl: 'https://agent.tinyfish.ai/v1/wallet',
+};
+
+const headers = (apiKey) => ({ 'X-API-Key': apiKey });
+
+export async function createSession(settings, apiKey, { proxyCountry, idleTimeoutSec }) {
+  const body = { timeout_seconds: idleTimeoutSec };
+  if (proxyCountry) body.proxy_config = { country_code: proxyCountry };
+  let s;
+  try {
+    s = await json(settings.apiBase, { method: 'POST', headers: headers(apiKey), body, timeoutMs: 90_000 });
+  } catch (e) {
+    if (e.status === 402) throw new QuotaError(`wallet too low: ${e.text}`);
+    throw e;
+  }
+  return { id: s.session_id, cdpUrl: s.cdp_url, egress: proxyCountry ? `proxy ${proxyCountry}` : 'default egress' };
+}
+
+export async function releaseSession(settings, apiKey, session) {
+  await json(`${settings.apiBase}/${session.id}`, { method: 'DELETE', headers: headers(apiKey) });
+}
+
+/** The wallet's balance (https://docs.tinyfish.ai/wallet) */
+export async function quota(settings, apiKey) {
+  const w = await json(settings.walletUrl, { headers: headers(apiKey) });
+  return { remaining: Number(w.available_balance), unit: w.currency };
+}
+
+/**
+ * Usage of the sessions among `sessions` that have ended, from the paged usage list of the account. The list
+ * starts a minute before the earliest was opened: the provider's start time precedes the ledger's.
+ */
+export async function sessionUsage(settings, apiKey, sessions) {
+  const wanted = new Set(sessions.map((s) => s.id));
+  const since = new Date(Math.min(...sessions.map((s) => Date.parse(s.openedAt))) - 60_000).toISOString();
+  const usage = [];
+  for (let page = 1; ; page++) {
+    const body = await json(`${settings.apiBase}/usage?start_after=${since}&status=ended&limit=1000&page=${page}`, { headers: headers(apiKey) });
+    for (const s of body.items) {
+      if (wanted.has(s.session_id)) usage.push({ id: s.session_id, durationMs: s.duration_ms, proxyBytes: (s.proxy_trg_rx_bytes ?? 0) + (s.proxy_trg_tx_bytes ?? 0) });
+    }
+    if (!body.has_more) return usage;
+  }
+}

package/src/session.js

@@ -0,0 +1,97 @@
+/**
+ * A CDP command this often while connected keeps a provider's idle timeout from ending a session that is in use
+ * (also while a page waits long for an answer). OneBrowser requires idleTimeoutSec to be at least twice as long.
+ */
+export const KEEP_ALIVE_MS = 15_000;
+
+/** Playwright errors carry a multi-line call log; the first line says what failed */
+const firstLine = (e) => String(e.message).split('\n')[0];
+
+/**
+ * One remote browser session, as OneBrowser.openSession() opened it: created by its provider and recorded in the
+ * ledger. Use it over CDP: through cdpUrl with any CDP client, or through connect() / newPage() with Playwright.
+ * It ends at the latest maxDurationMs after it was opened: this process closes it then (a client using it sees
+ * its connection drop). close() releases it; one never closed (its process was killed) is ended by its provider
+ * idleTimeoutSec after its client left.
+ *
+ *   id, provider, egress     the provider's session id, its name, and the egress the session uses
+ *   cdpUrl                   CDP WebSocket URL (it may carry the API key: never log it)
+ *   openedAt, closedAt       ms; closedAt is null while open
+ */
+export class Session {
+  #release;
+  #browser = null; // the connection in progress or made: a promise of Playwright's Browser
+  #keepAlive = null;
+  #deadline;
+
+  /** release(session): records the session closed and releases it at its provider (OneBrowser) */
+  constructor({ provider, remote, maxDurationMs, release }) {
+    this.provider = provider;
+    this.id = remote.id;
+    this.egress = remote.egress;
+    this.cdpUrl = remote.cdpUrl;
+    this.openedAt = Date.now();
+    this.closedAt = null;
+    this.#release = release;
+    this.#deadline = setTimeout(() => this.close().catch(() => {}), maxDurationMs); // a release that fails here leaves the session to the provider's idle timeout
+    this.#deadline.unref();
+  }
+
+  /** Playwright's Browser over this session's CDP connection, made once; the keep-alive runs while it is connected */
+  connect() {
+    if (this.closedAt) return Promise.reject(new Error(`${this.provider} session ${this.id} is closed`));
+    this.#browser ??= this.#connect();
+    return this.#browser;
+  }
+
+  async #connect() {
+    const { chromium } = await import('playwright-core');
+    let browser;
+    try {
+      browser = await chromium.connectOverCDP(this.cdpUrl, { timeout: 60_000 });
+    } catch (e) {
+      throw new Error(`failed to connect to the ${this.provider} browser: ${firstLine(e)}`);
+    }
+    try {
+      const cdp = await browser.newBrowserCDPSession();
+      if (this.closedAt) throw new Error(`${this.provider} session ${this.id} is closed`); // closed while connecting
+      this.#keepAlive = setInterval(() => cdp.send('Browser.getVersion').catch(() => {}), KEEP_ALIVE_MS);
+      this.#keepAlive.unref();
+    } catch (e) {
+      await browser.close().catch(() => {});
+      throw e;
+    }
+    return browser;
+  }
+
+  /**
+   * A new page in the browser's default context. Always a new one: the page a remote browser starts with is not
+   * always one that can be navigated.
+   */
+  async newPage() {
+    const browser = await this.connect();
+    const context = browser.contexts()[0] ?? (await browser.newContext());
+    return context.newPage();
+  }
+
+  /**
+   * Disconnects and releases the session at its provider; only the first call does. The ledger records it closed
+   * in any case. Throws when the provider could not release it: the provider then ends it by itself,
+   * idleTimeoutSec after the disconnect.
+   */
+  async close() {
+    if (this.closedAt) return;
+    this.closedAt = Date.now();
+    clearTimeout(this.#deadline);
+    clearInterval(this.#keepAlive);
+    const browser = this.#browser;
+    this.#browser = null;
+    await browser?.then((b) => b.close()).catch(() => {});
+    await this.#release(this);
+  }
+
+  /** close(): `await using session = await browsers.openSession(…)` releases it at the end of the block */
+  [Symbol.asyncDispose]() {
+    return this.close();
+  }
+}