onebrowser 0.5.0 → 0.7.0

package/README.md

@@ -1,6 +1,6 @@
 # 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.
+One interface to remote browser providers. A provider is an adapter; an account is one API key at a provider, and sessions are opened with an account. Every session is recorded in a ledger, which each account's usage and quota are read from.
 
 ```sh
 npm install onebrowser
@@ -10,20 +10,21 @@ npm install onebrowser
 import { OneBrowser, QuotaError } from 'onebrowser';
 
 const browsers = new OneBrowser({ client: 'my-crawler' });
-const session = await browsers.openSession({ provider: 'steel', proxyCountry: 'DE' });
+const [steel] = browsers.accounts('steel'); // one account per key in STEEL_API_KEY
+const session = await steel.openSession({ 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.readQuota('steel'); // { remaining, unbilled, unit: 'USD', renewsAt: null }
-browsers.quota('steel'); // the same now, from that reading: sessions opened since count at once
-browsers.maxSessionCost('steel'); // what a session with the default options costs at most, in USD
+await steel.readQuota(); // { remaining, unbilled, unit: 'USD', renewsAt: null }
+steel.quota(); // the same now, from that reading: sessions opened since count at once
+steel.maxSessionCost(); // what a session with the default options costs at most, in USD
 await browsers.syncUsage(); // stores the providers' records of ended sessions in the ledger
-browsers.usage({ since: Date.parse('2026-11-01') }); // [{ day, provider, client, sessions, minutes, … }]
+browsers.usage({ since: Date.parse('2026-11-01') }); // [{ day, provider, account, client, sessions, minutes, … }]
 await browsers.close();
 ```
 
-Choosing a provider, capping sessions and stopping before a quota runs out are the program's policy. onebrowser opens the sessions it is asked for and gives the program what it needs to decide: what the quota has left, what a session costs at most, and `QuotaError` when a provider refuses a session for the account's quota.
+Choosing an account, capping sessions and stopping before a quota runs out are the program's policy. onebrowser opens the sessions it is asked for and gives the program what it needs to decide: the accounts it has keys for, what each quota has left, what a session costs at most, 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), [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.
 
@@ -35,28 +36,35 @@ Built in: [Steel](https://steel.dev), [TinyFish](https://tinyfish.ai), [Hyperbro
 |---|---|
 | `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`, `price`, `billingDelayMs`, `minIdleTimeoutSec` (see [Quota](#quota)) and the adapter's own (API base URLs, plan facts such as `monthlyHours`) |
+| `providers` | Settings per provider name, on top of its adapter's `defaults`: `apiKeys` (see [Accounts](#accounts)), `price`, `billingDelayMs`, `minIdleTimeoutSec` (see [Quota](#quota)) and the adapter's own (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, in the ledger from when the provider has created it. Throws `QuotaError` when the provider refuses it for the account's quota |
-| `readQuota(provider, { maxAgeMs })` | Reads the provider's quota, unless a reading in progress or started at most `maxAgeMs` ago (default 0) can be used, a failed one too; then answers as `quota()` |
-| `quota(provider)` | What is left now, from the last reading: `{ remaining, unbilled, unit, renewsAt }` (see [Quota](#quota)). Throws until the provider has been read, and while its last reading failed |
-| `maxSessionCost(provider, options)` | What a session with these options costs at most, in the unit of the provider's quota |
-| `syncUsage()` | Stores the providers' records (duration, proxy traffic) of ended sessions: `{ reported, failed: [{ provider, error }] }` |
-| `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` |
+| `providers` | Names of the providers it has adapters for |
+| `accounts(provider?)` | The accounts with an API key, in the providers' order and then the keys': all of them, or the provider's (throws for an unknown provider) |
+| `syncUsage()` | Stores the providers' records (duration, proxy traffic) of ended sessions: `{ reported, failed: [{ account, error }] }` |
+| `usage({ since })` | Sessions opened since `since` (ms) per UTC day, account and client: `sessions`, `minutes` (the provider's record, else the open-to-close timing), `untimed`, `unsynced`, `proxyBytes` |
+| `sessions({ since })` | The ledger's sessions opened since `since` (ms), oldest first, each as recorded: `provider`, `account`, `id`, `client`, `openedAt`, `endsBy`, `closedAt`, `durationMs`, `proxyBytes`, `syncedAt` (times in ms; `closedAt` and `syncedAt` null until then, `durationMs` and `proxyBytes` null without the provider's record) |
+| `ledgerId` | The ledger's own id, kept for its life: a program that copies the ledger's record elsewhere tells it from another ledger's by it |
 | `close()` | Closes the sessions still open and the ledger |
 
-A session has `id`, `provider`, `egress`, `cdpUrl` (it may carry the API key: never log it), `openedAt` (when it was asked for), `closedAt` (when its provider released it), and:
+An account has `id` (`steel#3f9a1c`: the provider's name and the key's fingerprint), `provider`, `fingerprint`, and:
+
+| Method | |
+|---|---|
+| `openSession({ proxyCountry, idleTimeoutSec, maxDurationMs })` | A new session, in the ledger from when the provider has created it. Throws `QuotaError` when the provider refuses it for the account's quota |
+| `readQuota({ maxAgeMs })` | Reads the account's quota from the provider, unless a reading in progress or started at most `maxAgeMs` ago (default 0) can be used, a failed one too; then answers as `quota()` |
+| `quota()` | What is left now, from the last reading: `{ remaining, unbilled, unit, renewsAt }` (see [Quota](#quota)). Throws until the account has been read, and while its last reading failed |
+| `maxSessionCost(options)` | What a session with these options costs at most, in the unit of the quota |
+
+A session has `id`, `account`, `egress`, `cdpUrl` (it may carry the API key: never log it), `openedAt` (when it was asked for), `closedAt` (when its provider released it), 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 in use.
 - `newPage()`: a new page in the default context: the page a remote browser starts with cannot always be navigated.
 - `close()`: disconnects and releases it; every call answers as the first. Throws when the provider could not release it: the provider ends it by itself, and the ledger counts it as lasting as long as it can.
 
-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()`).
+A session and a `OneBrowser` are async-disposable: `await using session = await steel.openSession()` 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
 
@@ -82,7 +90,7 @@ How each provider meets them:
 
 ### Quota
 
-`quota()` is the last reading less `unbilled`: what the ledger's sessions that the reading does not show cost at the provider's `price`. A reading shows the sessions that ended `billingDelayMs` before it; the others are open ones, counted as lasting as long as they can (`maxDurationMs`, then `idleTimeoutSec`, at least the provider's `minIdleTimeoutSec`), and those ended since, counted as long as they lasted. So each session counts once from when its provider has created it, whichever program on the machine opened it, and a program can check before each session that the account pays for it (`maxSessionCost`). A provider that bills a session while it runs has part of it counted twice, on the safe side. Not counted: sessions opened through another machine's ledger, until the provider bills them, and proxy traffic billed by the GB.
+`quota()` is the last reading less `unbilled`: what the ledger's sessions of the account that the reading does not show cost at the provider's `price`. A reading shows the sessions that ended `billingDelayMs` before it; the others are open ones, counted as lasting as long as they can (`maxDurationMs`, then `idleTimeoutSec`, at least the provider's `minIdleTimeoutSec`), and those ended since, counted as long as they lasted. So each session counts once from when its provider has created it, whichever program on the machine opened it, and a program can check before each session that the account pays for it (`maxSessionCost`). A provider that bills a session while it runs has part of it counted twice, on the safe side. Not counted: sessions opened through another machine's ledger, until the provider bills them, and proxy traffic billed by the GB.
 
 `price` is in the quota's unit: `perHour`, `perSession` (default 0), the session time billed in whole `stepSec`, rounded up (default 1), and at least `minSec` (default 0). Where a provider does not document its rounding, the adapter takes the minute. `renewsAt` (ms) is when the quota renews by itself; `null` when only a top-up renews it. `price` and `billingDelayMs` are settings: a program on another plan sets its own.
 
@@ -98,26 +106,28 @@ How each provider meets them:
 
 Every provider read from its API showed a session's cost within about a minute of its end (2026-11); `billingDelayMs` leaves room for more.
 
-### API keys
+### Accounts
+
+An account is one API key at a provider: the quota, the plan's limits and the bill are the key's. The keys of a provider are `apiKeys` in its settings, else those in the environment variable `<PROVIDER>_API_KEY` (`STEEL_API_KEY`, …; `apiKeyEnv(provider)` names it), else those in the file named by `<PROVIDER>_API_KEY_FILE`, separated by commas, spaces or line breaks; each key makes one account, in that order, and a key given twice makes one. A provider without a key has no account.
 
-`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.
+An account is known by its `id`, the provider's name and the first 6 hex digits of the key's SHA-256 (`steel#3f9a1c`): the same for the same key in every program and run, without telling the key. The ledger records sessions under it, so an account's usage is whole however many programs open sessions with its key.
 
 ### The ledger
 
-One SQLite file per machine by default: `$ONEBROWSER_DB`, else `onebrowser/sessions.db` in `$XDG_DATA_HOME` (default `~/.local/share`), shared by every program on the machine under its own `client`. A session is recorded when its provider has created it (it is billed from then on), with when it ends at the latest; closed when its provider has released it; and completed with the provider's own record by `syncUsage()`. A ledger made by an earlier onebrowser is brought up to date when opened; one made by a later onebrowser is refused.
+One SQLite file per machine by default: `$ONEBROWSER_DB`, else `onebrowser/sessions.db` in `$XDG_DATA_HOME` (default `~/.local/share`), shared by every program on the machine under its own `client`. A session is recorded when its provider has created it (it is billed from then on), with its account and when it ends at the latest; closed when its provider has released it; and completed with the provider's own record by `syncUsage()`. Nothing removes a session from the ledger, so its record is whole from the ledger's first session on. Each ledger has an id of its own (`ledgerId`), given when it is made (or first opened by onebrowser 0.7 or later) and kept for its life. A ledger made by an earlier onebrowser is brought up to date when opened; one made by a later onebrowser is refused. Sessions recorded by onebrowser 0.5 or earlier have no account: they become the provider's only account's when it has one here, and stay without one while it has several.
 
 ## 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.
+The 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, once its sessions not billed yet are paid for
-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 quota                 # what each account has left, once its sessions not billed yet are paid for
+npx onebrowser quota steel kernel#a81f2c   # only these: a provider's accounts, or one account by id
+npx onebrowser usage --days 7        # the ledger's sessions per UTC day, account 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 `readQuota()` returns, with the provider: `{ provider, remaining, unbilled, 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.
+`usage` first fetches the providers' records of the sessions that have ended, as `syncUsage()` does. With `--json`, `quota` prints an array of what `readQuota()` returns, with the account: `{ account, provider, remaining, unbilled, unit, renewsAt }`, or `{ account, provider, error }` for a failed reading; `usage` prints `{ ledger, ledgerId, 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
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "onebrowser",
-  "version": "0.5.0",
-  "description": "One interface to remote browser providers: sessions by provider name, a usage ledger, account quotas",
+  "version": "0.7.0",
+  "description": "One interface to remote browser providers: sessions by account (an API key at a provider), a usage ledger, account quotas",
   "keywords": ["browser", "remote-browser", "cdp", "playwright", "steel", "hyperbrowser", "lightpanda", "kernel", "tinyfish", "anchorbrowser", "firecrawl"],
   "license": "MIT",
   "author": "Richard Wang",

package/src/account.js

@@ -0,0 +1,139 @@
+import { sessionCost } from './cost.js';
+import { fingerprint } from './credentials.js';
+import { QuotaError } from './errors.js';
+import { sessionMsAtMost, sessionOptions } from './options.js';
+import { Session } from './session.js';
+
+/**
+ * One API key at one provider: the account its sessions are billed to, with its own quota and its own record in
+ * the ledger. id, the provider's name and the key's fingerprint (`steel#3f9a1c`), names it in the ledger, in
+ * logs and on the command line; the key itself stays inside.
+ *
+ * ledger(): the shared Ledger (ledger.js), opened when first needed; client: the program, recorded with each
+ * session.
+ */
+export class Account {
+  #adapter;
+  #settings;
+  #apiKey;
+  #client;
+  #ledger;
+  #open = new Set();
+  #latest = null; // the latest quota reading, in progress or done
+  #done = null; // the latest reading done
+
+  constructor({ provider, adapter, settings, apiKey, client, ledger }) {
+    this.provider = provider;
+    this.fingerprint = fingerprint(apiKey);
+    this.id = `${provider}#${this.fingerprint}`;
+    this.#adapter = adapter;
+    this.#settings = settings;
+    this.#apiKey = apiKey;
+    this.#client = client;
+    this.#ledger = ledger;
+  }
+
+  /**
+   * A new session (options: sessionOptions()), in the ledger from when the provider has created it. Throws when
+   * the provider creates none; QuotaError when it refuses for the account's quota.
+   */
+  async openSession(options = {}) {
+    const o = sessionOptions(options);
+    const openedAt = Date.now();
+    let remote;
+    try {
+      remote = await this.#adapter.createSession(this.#settings, this.#apiKey, o);
+    } catch (e) {
+      if (e instanceof QuotaError) throw e;
+      throw new Error(`failed to create a ${this.provider} session: ${e.message}`);
+    }
+    const session = new Session({ account: this, remote, openedAt, maxDurationMs: o.maxDurationMs, release: (s) => this.#release(s) });
+    try {
+      this.#ledger().opened({ provider: this.provider, account: this.id, id: session.id, client: this.#client, openedAt, endsBy: openedAt + sessionMsAtMost(o, this.#settings) });
+    } catch (e) {
+      await session.close().catch(() => {}); // a session the ledger does not know is not handed out
+      throw e;
+    }
+    this.#open.add(session);
+    return session;
+  }
+
+  /** Releases `session` at the provider and records it closed: when it was released, so its whole billed time counts */
+  async #release(session) {
+    try {
+      await this.#adapter.releaseSession(this.#settings, this.#apiKey, session);
+      const closedAt = Date.now();
+      this.#ledger().closed({ account: this.id, id: session.id, closedAt });
+      return closedAt;
+    } finally {
+      this.#open.delete(session);
+    }
+  }
+
+  /**
+   * Reads the quota from the provider, unless a reading in progress or started at most maxAgeMs ago can be used
+   * (a failed one throws again); then answers as quota().
+   */
+  async readQuota({ maxAgeMs = 0 } = {}) {
+    const reading = this.#reading(maxAgeMs);
+    await reading.settled;
+    if (reading.error) throw reading.error;
+    return this.quota();
+  }
+
+  /**
+   * What is left of the quota now, in the provider's unit: { remaining, unbilled, unit, renewsAt }. The last
+   * reading shows the sessions that ended billingDelayMs before it; `unbilled` is what the ledger's others cost
+   * at the provider's price, open ones as if they lasted as long as they can, and remaining the reading less
+   * that. renewsAt (ms): when the quota renews by itself; null: only a top-up renews it. Throws until the
+   * provider has been read, and while the last reading failed.
+   */
+  quota() {
+    const reading = this.#done;
+    if (!reading) throw new Error(`the quota of ${this.id} has not been read yet (readQuota)`);
+    if (reading.error) throw reading.error;
+    const unbilled = this.#ledger().openSince(this.id, reading.billedBefore).reduce((cost, s) => cost + sessionCost(this.#settings.price, s.durationMs), 0);
+    const { remaining, unit, renewsAt = null } = reading.value;
+    return { remaining: remaining - unbilled, unbilled, unit, renewsAt };
+  }
+
+  /** The latest reading if it is in progress or at most maxAgeMs old, else a new one */
+  #reading(maxAgeMs) {
+    const latest = this.#latest;
+    if (latest && (latest !== this.#done || Date.now() - latest.startedAt <= maxAgeMs)) return latest;
+    const startedAt = Date.now();
+    const reading = { startedAt, billedBefore: startedAt - this.#settings.billingDelayMs, value: null, error: null };
+    this.#latest = reading;
+    reading.settled = (async () => {
+      try {
+        const q = await this.#adapter.quota(this.#settings, this.#apiKey, this.#ledger().history(this.id, reading.billedBefore));
+        if (!(Number.isFinite(q?.remaining) && typeof q.unit === 'string')) throw new Error(`${this.provider} answered no quota: ${JSON.stringify(q)}`);
+        reading.value = q;
+      } catch (e) {
+        reading.error = e;
+      }
+      this.#done = reading;
+    })();
+    return reading;
+  }
+
+  /** What a session with these options costs at most, in the unit of the quota */
+  maxSessionCost(options) {
+    return sessionCost(this.#settings.price, sessionMsAtMost(sessionOptions(options), this.#settings));
+  }
+
+  /** Stores the provider's records (duration, proxy traffic) of this account's ended sessions that have none yet; how many */
+  async syncUsage() {
+    const ledger = this.#ledger();
+    const rows = ledger.awaitingUsage(this.id);
+    if (!rows.length) return 0;
+    const usage = await this.#adapter.sessionUsage(this.#settings, this.#apiKey, rows);
+    ledger.tx(() => usage.forEach((u) => ledger.recordUsage(this.id, u)));
+    return usage.length;
+  }
+
+  /** Closes its sessions still open; their release errors are ignored: the provider ends those */
+  async close() {
+    await Promise.all([...this.#open].map((s) => s.close().catch(() => {})));
+  }
+}

package/src/cli.js

@@ -18,6 +18,18 @@ const GLOBAL_OPTIONS = {
   help: { type: 'boolean', short: 'h' },
 };
 
+/** The accounts `names` ask for: each name a provider's (it must have an API key) or one account's id */
+function askedAccounts(browsers, names) {
+  return names.flatMap((name) => {
+    const own = browsers.accounts().find((a) => a.id === name);
+    if (own) return [own];
+    if (!browsers.providers.includes(name)) throw new CommandLineError(`unknown provider or account ${name} (expected ${browsers.providers.join(', ')}, or an account id)`);
+    const accounts = browsers.accounts(name);
+    if (!accounts.length) throw new Error(`${name} has no API key: set ${apiKeyEnv(name)} or ${apiKeyEnv(name)}_FILE`);
+    return accounts;
+  });
+}
+
 /**
  * The commands: their own options, whether they take arguments, and run(browsers, values, args, { out, err })
  * → exit status
@@ -26,16 +38,16 @@ 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.readQuota(provider).then((q) => ({ provider, ...q }), (e) => ({ provider, error: e.message }))));
+      const accounts = names.length ? askedAccounts(browsers, names) : browsers.accounts();
+      if (!accounts.length) throw new Error(`no provider has an API key: set ${browsers.providers.map(apiKeyEnv).join(', ')}`);
+      const quotas = await Promise.all(
+        accounts.map((a) => a.readQuota().then((q) => ({ account: a.id, provider: a.provider, ...q }), (e) => ({ account: a.id, provider: a.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})` : `${round(q.remaining)} ${q.unit} left${q.unbilled ? ` (after ${round(q.unbilled)} not billed yet)` : ''}${q.renewsAt ? `, renews ${day(q.renewsAt)}` : ''}`;
-          out.write(`${q.provider.padEnd(14)} ${text}\n`);
+          out.write(`${q.account.padEnd(21)} ${text}\n`);
         }
       }
       return quotas.some((q) => q.error) ? 1 : 0;
@@ -49,15 +61,15 @@ const COMMANDS = {
       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`);
+      for (const f of failed) err.write(`${f.account}: 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`);
+      if (json) out.write(`${JSON.stringify({ ledger: browsers.ledgerPath, ledgerId: browsers.ledgerId, 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)));
+        for (const r of sessions) out.write(usageLine(`${r.day} ${r.account} ${r.client}`, r));
+        for (const [account, rows] of Map.groupBy(sessions, (r) => r.account)) {
+          if (rows.length > 1) out.write(usageLine(`total ${account}`, sumUsage(rows)));
         }
       }
       return failed.length ? 1 : 0;
@@ -68,9 +80,10 @@ const COMMANDS = {
 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, less what the sessions in the ledger
-                                   that it has not billed yet cost; 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
+  onebrowser quota [NAME...]       what each account has left, less what the sessions in the ledger that it has
+                                   not billed yet cost; NAME: a provider (every account with its API key) or an
+                                   account id such as steel#3f9a1c; default: every account
+  onebrowser usage [--days N]      sessions per UTC day, account and client in the last N UTC days, today
                                    included (default 30), after fetching the providers' records of ended sessions
 
 Options:
@@ -79,27 +92,19 @@ Options:
   -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')}
+${providers.map((p) => `  ${apiKeyEnv(p).padEnd(22)} API keys of ${p}, one per account, or ${apiKeyEnv(p)}_FILE naming a file that holds them`).join('\n')}
+                         (keys are separated by commas, spaces or line breaks)
   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` +
+  `  ${label.padEnd(40)} ${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)` : '') +

package/src/credentials.js

@@ -1,22 +1,27 @@
+import crypto from 'node:crypto';
 import fs from 'node:fs';
 
-/** The environment variable holding a provider's API key: STEEL_API_KEY for `steel` */
+/** The environment variable holding a provider's API keys: STEEL_API_KEY for `steel` */
 export const apiKeyEnv = (provider) => `${provider.toUpperCase()}_API_KEY`;
 
+/** What names the account an API key belongs to without telling the key: the first 6 hex digits of its SHA-256 */
+export const fingerprint = (apiKey) => crypto.createHash('sha256').update(apiKey).digest('hex').slice(0, 6);
+
+/** Keys written one after another, separated by commas, spaces or line breaks */
+const split = (text) => text.split(/[\s,]+/).filter(Boolean);
+
 /**
- * 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.
+ * A provider's API keys, one per account: `apiKeys` as given in its settings, else those in the environment
+ * variable apiKeyEnv(provider), else those in the file named by that variable with _FILE appended, in their
+ * order and each once. Separators: commas, spaces or line breaks. None is fine; the file must exist.
  */
-export function readApiKey(provider, apiKey) {
-  if (apiKey?.trim()) return apiKey.trim();
+export function readApiKeys(provider, apiKeys) {
   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');
+  let keys = apiKeys ?? split(process.env[env] ?? '');
+  if (!keys.length && file) {
+    if (!fs.existsSync(file)) throw new Error(`${provider} keys: ${env}_FILE names no file (${file})`);
+    keys = split(fs.readFileSync(file, 'utf8'));
   }
-  if (!key?.trim()) throw new Error(`missing ${provider} key: set ${env} or ${env}_FILE`);
-  return key.trim();
+  return [...new Set(keys.map((k) => k.trim()).filter(Boolean))];
 }

package/src/index.js

@@ -1,225 +1,116 @@
-import { sessionCost } from './cost.js';
-import { readApiKey } from './credentials.js';
+import { Account } from './account.js';
+import { readApiKeys } from './credentials.js';
 import { QuotaError } from './errors.js';
 import { defaultLedgerPath, Ledger } from './ledger.js';
 import { ADAPTERS, checkAdapter, fullSettings } from './providers/index.js';
-import { KEEP_ALIVE_MS, Session } from './session.js';
 
 export { apiKeyEnv } from './credentials.js';
+export { sessionOptions } from './options.js';
 export { QuotaError };
 
-/** Session options when openSession() is not given them */
-const SESSION_DEFAULTS = {
-  proxyCountry: null,
-  idleTimeoutSec: 60,
-  maxDurationMs: 15 * 60_000,
-};
-
 /**
- * The session options of openSession() with the defaults filled in; 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, or after the provider's
- *                    minIdleTimeoutSec if longer (≥ 2 × KEEP_ALIVE_MS)
- *   maxDurationMs    a 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;
-}
-
-/** How long a session lasts at most, whatever becomes of its process: closed at maxDurationMs, else ended by its provider once idle */
-const sessionMsAtMost = (o, settings) => o.maxDurationMs + Math.max(o.idleTimeoutSec, settings.minIdleTimeoutSec) * 1000;
-
-/**
- * Remote browsers from several providers behind one interface: a session is asked for by provider name. Every
- * session is recorded in a ledger (ledger.js) shared by the programs on the machine, so that each provider
- * account's usage, and what its quota has left at any moment, are known. Which provider to use, and when to
- * stop using one, are the caller's decisions.
+ * Remote browsers from several providers behind one interface. A provider is an adapter (providers/index.js);
+ * an account is one API key at a provider (account.js), which sessions are opened with. Every session is
+ * recorded in a ledger (ledger.js) shared by the programs on the machine, so that each account's usage, and
+ * what its quota has left at any moment, are known. Which account to use, and when to stop using one, are the
+ * caller's decisions.
  *
  * client: the program using it, recorded with each session; ledgerPath: the ledger's SQLite file, opened when
- * first needed; providers: settings per provider name on top of its adapter's defaults (providers/index.js),
- * apiKey among them (else credentials.js); adapters: further or replacement adapters by provider name.
+ * first needed; providers: settings per provider name on top of its adapter's defaults, apiKeys among them
+ * (else credentials.js); adapters: further or replacement adapters by provider name.
  */
 export class OneBrowser {
-  #providers = new Map(); // name → { adapter, settings, apiKey }
+  #providers = []; // names, in the adapters' order
+  #accounts = [];
   #ledger = null;
-  #open = new Set();
-  #readings = new Map(); // provider → { latest, done }: its latest quota reading, and the latest one done
 
   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, ...given } = providers[name] ?? {};
-      this.#providers.set(name, { adapter, settings: fullSettings(name, { ...adapter.defaults, ...given }), apiKey });
-    }
-    const unknown = Object.keys(providers).filter((name) => !this.#providers.has(name));
+    const all = { ...ADAPTERS, ...adapters };
+    const unknown = Object.keys(providers).filter((name) => !all[name]);
     if (unknown.length) throw new Error(`onebrowser: no adapter for provider ${unknown.join(', ')}`);
-  }
-
-  get providers() {
-    return [...this.#providers.keys()];
-  }
-
-  get #store() {
-    return (this.#ledger ??= new Ledger(this.ledgerPath));
-  }
-
-  #known(provider) {
-    const p = this.#providers.get(provider);
-    if (!p) throw new Error(`unknown provider ${provider} (expected ${this.providers.join(', ')})`);
-    return p;
-  }
-
-  #ready(provider) {
-    const p = this.#known(provider);
-    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` (options: sessionOptions()), in the ledger from when its provider has created
-   * it. Throws when the provider creates none; QuotaError when it refuses for the account's quota.
-   */
-  async openSession({ provider, ...options }) {
-    const { adapter, settings, apiKey } = this.#ready(provider);
-    const o = sessionOptions(options);
-    const openedAt = Date.now();
-    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, openedAt, maxDurationMs: o.maxDurationMs, release: (s) => this.#release(adapter, settings, apiKey, s) });
-    try {
-      this.#store.opened({ provider, id: session.id, client: this.client, openedAt, endsBy: openedAt + sessionMsAtMost(o, settings) });
-    } catch (e) {
-      await session.close().catch(() => {}); // a session the ledger does not know is not handed out
-      throw e;
+    for (const [provider, adapter] of Object.entries(all)) {
+      checkAdapter(provider, adapter);
+      const { apiKeys, ...given } = providers[provider] ?? {};
+      const settings = fullSettings(provider, { ...adapter.defaults, ...given });
+      this.#providers.push(provider);
+      for (const apiKey of readApiKeys(provider, apiKeys)) {
+        this.#accounts.push(new Account({ provider, adapter, settings, apiKey, client, ledger: () => this.#store }));
+      }
     }
-    this.#open.add(session);
-    return session;
   }
 
-  /** Releases `session` at its provider and records it closed: when it was released, so its whole billed time counts */
-  async #release(adapter, settings, apiKey, session) {
-    try {
-      await adapter.releaseSession(settings, apiKey, session);
-      const closedAt = Date.now();
-      this.#store.closed({ provider: session.provider, id: session.id, closedAt });
-      return closedAt;
-    } finally {
-      this.#open.delete(session);
+  /** The ledger, opened on first use; a provider with one account here claims its sessions recorded without one */
+  get #store() {
+    if (!this.#ledger) {
+      this.#ledger = new Ledger(this.ledgerPath);
+      for (const [provider, accounts] of Map.groupBy(this.#accounts, (a) => a.provider)) {
+        if (accounts.length === 1) this.#ledger.claim(provider, accounts[0].id);
+      }
     }
+    return this.#ledger;
   }
 
-  /**
-   * Reads the account's quota with `provider` from the provider, unless a reading in progress or started at most
-   * maxAgeMs ago can be used (a failed one throws again); then answers as quota().
-   */
-  async readQuota(provider, { maxAgeMs = 0 } = {}) {
-    const reading = this.#reading(provider, maxAgeMs);
-    await reading.settled;
-    if (reading.error) throw reading.error;
-    return this.quota(provider);
+  /** The ledger's own id, kept for the ledger's life: it tells its record from another ledger's */
+  get ledgerId() {
+    return this.#store.id;
   }
 
-  /**
-   * What is left of the account's quota now, in the provider's unit: { remaining, unbilled, unit, renewsAt }. The
-   * last reading shows the sessions that ended billingDelayMs before it; `unbilled` is what the ledger's others
-   * cost at the provider's price, open ones as if they lasted as long as they can, and remaining the reading less
-   * that. renewsAt (ms): when the quota renews by itself; null: only a top-up renews it. Throws until the
-   * provider has been read, and while its last reading failed.
-   */
-  quota(provider) {
-    const { settings } = this.#known(provider);
-    const reading = this.#readings.get(provider)?.done;
-    if (!reading) throw new Error(`the quota of ${provider} has not been read yet (readQuota)`);
-    if (reading.error) throw reading.error;
-    const unbilled = this.#store.openSince(provider, reading.billedBefore).reduce((cost, s) => cost + sessionCost(settings.price, s.durationMs), 0);
-    const { remaining, unit, renewsAt = null } = reading.value;
-    return { remaining: remaining - unbilled, unbilled, unit, renewsAt };
-  }
-
-  /** The latest reading of the provider's quota if it is in progress or at most maxAgeMs old, else a new one */
-  #reading(provider, maxAgeMs) {
-    const readings = this.#readings.get(provider) ?? { latest: null, done: null };
-    this.#readings.set(provider, readings);
-    const { latest } = readings;
-    const inProgress = latest && latest !== readings.done;
-    if (inProgress || (latest && Date.now() - latest.startedAt <= maxAgeMs)) return latest;
-    const { adapter, settings, apiKey } = this.#ready(provider);
-    const startedAt = Date.now();
-    const reading = { startedAt, billedBefore: startedAt - settings.billingDelayMs, value: null, error: null };
-    readings.latest = reading;
-    reading.settled = (async () => {
-      try {
-        const q = await adapter.quota(settings, apiKey, this.#store.history(provider, reading.billedBefore));
-        if (!(Number.isFinite(q?.remaining) && typeof q.unit === 'string')) throw new Error(`${provider} answered no quota: ${JSON.stringify(q)}`);
-        reading.value = q;
-      } catch (e) {
-        reading.error = e;
-      }
-      readings.done = reading;
-    })();
-    return reading;
+  /** Names of the providers it has adapters for */
+  get providers() {
+    return [...this.#providers];
   }
 
-  /** What a session with these options costs at most, in the unit of the provider's quota */
-  maxSessionCost(provider, options) {
-    const { settings } = this.#known(provider);
-    return sessionCost(settings.price, sessionMsAtMost(sessionOptions(options), settings));
+  /** The accounts with an API key, in the providers' order and then the keys': all, or `provider`'s (throws for an unknown one) */
+  accounts(provider) {
+    if (provider === undefined) return [...this.#accounts];
+    if (!this.#providers.includes(provider)) throw new Error(`unknown provider ${provider} (expected ${this.#providers.join(', ')})`);
+    return this.#accounts.filter((a) => a.provider === provider);
   }
 
   /**
    * Stores the providers' records (duration, proxy traffic) of the ledger's ended sessions that have none yet:
-   * { reported, failed: [{ provider, error }] }. What cannot be fetched now, and the sessions of providers it has
-   * no adapter for, are left for a later call.
+   * { reported, failed: [{ account, error }] }. What cannot be fetched now, and the sessions of accounts without
+   * a key here, are left for a later call.
    */
   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)) {
+    for (const account of this.#accounts) {
       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;
+        reported += await account.syncUsage();
       } catch (e) {
-        failed.push({ provider, error: e.message });
+        failed.push({ account: account.id, 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: the provider's record
-   * (syncUsage), else the open-to-close timing; untimed: sessions with neither; unsynced: those without the record.
+   * Sessions opened since `since` (ms), per UTC day, account and client:
+   * [{ day, provider, account, client, sessions, minutes, untimed, unsynced, proxyBytes }]. minutes: the
+   * provider's record (syncUsage), else the open-to-close timing; untimed: sessions with neither; unsynced:
+   * those without the record. account: the provider's name alone for sessions whose account is not known.
    */
   usage({ since }) {
     return this.#store.usage(since);
   }
 
-  /** Closes every session still open (their release errors are ignored: the providers end those) and the ledger */
+  /**
+   * The ledger's sessions opened since `since` (ms), oldest first, each as recorded:
+   * [{ provider, account, id, client, openedAt, endsBy, closedAt, durationMs, proxyBytes, syncedAt }], times in
+   * ms (closedAt, syncedAt null until then; durationMs and proxyBytes null without the provider's record). account:
+   * the provider's name alone for a session whose account is not known.
+   */
+  sessions({ since }) {
+    return this.#store.sessions(since);
+  }
+
+  /** Closes every session still open and the ledger */
   async close() {
-    await Promise.all([...this.#open].map((s) => s.close().catch(() => {})));
+    await Promise.all(this.#accounts.map((a) => a.close()));
     this.#ledger?.close();
     this.#ledger = null;
   }

package/src/ledger.js

@@ -1,12 +1,13 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { randomUUID } from 'node:crypto';
 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.
+ * that the record of an account's sessions is whole, whichever project opened them.
  */
 export function defaultLedgerPath() {
   if (process.env.ONEBROWSER_DB) return process.env.ONEBROWSER_DB;
@@ -18,6 +19,8 @@ export function defaultLedgerPath() {
 const SCHEMA = `
 CREATE TABLE sessions (
   provider      TEXT NOT NULL,
+  account       TEXT,                     -- the account it is billed to (Account.id); empty when recorded before the
+                                          -- ledger had accounts (schema 2) and not claimed since (claim())
   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 it was asked for; its provider created it right after
@@ -28,17 +31,17 @@ CREATE TABLE sessions (
   synced_at     TEXT,                     -- when the provider's record was stored; empty = not yet
   PRIMARY KEY (provider, id)
 );
-CREATE INDEX idx_sessions_opened ON sessions(provider, opened_at);
+CREATE INDEX idx_sessions_opened ON sessions(account, opened_at);
 `;
 
 /**
  * The version of SCHEMA (PRAGMA user_version), and the step to it from each earlier one: a ledger outlives the
- * onebrowser that made it. onebrowser 0.1–0.3 made version 1 and left user_version 0.
+ * onebrowser that made it. onebrowser 0.1–0.3 made version 1 and left user_version 0; 0.4 and 0.5 made 2. Each
+ * step makes its version as that version was, whatever SCHEMA has become since.
  */
-const VERSION = 2;
+const VERSION = 3;
 const UPGRADES = {
-  // 1 → 2: ends_by, as if the sessions of 1 had the default session options (15 min, then 60 s idle). Each step
-  // makes its version as that version was, whatever SCHEMA has become since.
+  // 1 → 2: ends_by, as if the sessions of 1 had the default session options (15 min, then 60 s idle)
   1: `ALTER TABLE sessions RENAME TO sessions_1;
       DROP INDEX idx_sessions_opened;
       CREATE TABLE sessions (
@@ -50,8 +53,26 @@ const UPGRADES = {
         SELECT provider, id, client, opened_at, strftime('%Y-%m-%dT%H:%M:%fZ', opened_at, '+16 minutes'), closed_at, duration_ms, proxy_bytes, synced_at
         FROM sessions_1;
       DROP TABLE sessions_1;`,
+  // 2 → 3: account, not known for the sessions so far (claim() settles those of a provider with one account)
+  2: `ALTER TABLE sessions RENAME TO sessions_2;
+      DROP INDEX idx_sessions_opened;
+      CREATE TABLE sessions (
+        provider TEXT NOT NULL, account TEXT, id TEXT NOT NULL, client TEXT NOT NULL, opened_at TEXT NOT NULL, ends_by TEXT NOT NULL,
+        closed_at TEXT, duration_ms INTEGER, proxy_bytes INTEGER, synced_at TEXT, PRIMARY KEY (provider, id)
+      );
+      CREATE INDEX idx_sessions_opened ON sessions(account, opened_at);
+      INSERT INTO sessions (provider, id, client, opened_at, ends_by, closed_at, duration_ms, proxy_bytes, synced_at)
+        SELECT provider, id, client, opened_at, ends_by, closed_at, duration_ms, proxy_bytes, synced_at FROM sessions_2;
+      DROP TABLE sessions_2;`,
 };
 
+/**
+ * Beside the schema, meta holds the ledger's own id (`id`): a program that copies the ledger's record elsewhere
+ * tells it from another ledger's by it. It came with onebrowser 0.7 without a schema step, made whenever it is
+ * missing, so that a ledger a 0.7 has opened still opens in 0.6, which knows schema 3 too and ignores the table.
+ */
+const META = 'CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT NOT NULL) WITHOUT ROWID;';
+
 /** ms from one ISO time to another */
 const msBetween = (from, to) => `CAST(ROUND((julianday(${to}) - julianday(${from})) * 86400000) AS INTEGER)`;
 
@@ -83,16 +104,29 @@ export class Ledger {
   /** Makes the ledger, or brings an earlier one up to date, in one transaction: another process may be opening it too */
   #migrate() {
     const version = () => this.#db.prepare('PRAGMA user_version').get().user_version;
-    if (version() === VERSION) return;
-    this.tx(() => {
-      if (!this.#db.prepare("SELECT 1 FROM sqlite_schema WHERE type = 'table' AND name = 'sessions'").get()) this.#db.exec(SCHEMA);
-      else {
-        const from = version() || 1;
-        if (from > VERSION) throw new Error(`onebrowser: the ledger ${this.#file} was made by a later onebrowser (schema ${from}; this one knows ${VERSION})`);
-        for (let v = from; v < VERSION; v++) this.#db.exec(UPGRADES[v]);
-      }
-      this.#db.exec(`PRAGMA user_version = ${VERSION}`);
-    });
+    const has = (table) => this.#db.prepare("SELECT 1 FROM sqlite_schema WHERE type = 'table' AND name = ?").get(table);
+    if (version() !== VERSION) {
+      this.tx(() => {
+        if (!has('sessions')) this.#db.exec(SCHEMA);
+        else {
+          const from = version() || 1;
+          if (from > VERSION) throw new Error(`onebrowser: the ledger ${this.#file} was made by a later onebrowser (schema ${from}; this one knows ${VERSION})`);
+          for (let v = from; v < VERSION; v++) this.#db.exec(UPGRADES[v]);
+        }
+        this.#db.exec(`PRAGMA user_version = ${VERSION}`);
+      });
+    }
+    if (!has('meta')) {
+      this.tx(() => {
+        this.#db.exec(META);
+        this.#db.prepare("INSERT OR IGNORE INTO meta (key, value) VALUES ('id', ?)").run(randomUUID());
+      });
+    }
+  }
+
+  /** This ledger's id, given when it was made or first opened by a onebrowser that has ids, and kept for life */
+  get id() {
+    return this.#q("SELECT value FROM meta WHERE key = 'id'").get().value;
   }
 
   #q(sql) {
@@ -101,37 +135,40 @@ export class Ledger {
     return s;
   }
 
-  opened({ provider, id, client, openedAt, endsBy }) {
-    this.#q('INSERT INTO sessions (provider, id, client, opened_at, ends_by) VALUES (?,?,?,?,?)').run(provider, id, client, iso(openedAt), iso(endsBy));
+  opened({ provider, account, id, client, openedAt, endsBy }) {
+    this.#q('INSERT INTO sessions (provider, account, id, client, opened_at, ends_by) VALUES (?,?,?,?,?,?)').run(provider, account, id, client, iso(openedAt), iso(endsBy));
+  }
+
+  closed({ account, id, closedAt }) {
+    this.#q('UPDATE sessions SET closed_at=? WHERE account=? AND id=? AND closed_at IS NULL').run(iso(closedAt), account, id);
   }
 
-  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 provider's sessions without an account (recorded before schema 3) are `account`'s: the provider's only one */
+  claim(provider, account) {
+    this.#q('UPDATE sessions SET account=? WHERE provider=? AND account IS NULL').run(account, provider);
   }
 
-  /** The provider's sessions that a quota reading shows, those that ended before `billedBefore` (ms); openSince() has the rest */
-  history(provider, billedBefore) {
+  /** The account's sessions that a quota reading shows, those that ended before `billedBefore` (ms); openSince() has the rest */
+  history(account, billedBefore) {
     return {
       /** Their session time (ms) since `since` (ms), each as long as it can have lasted while it has no timing */
       endedSessionMsSince: (since) =>
-        this.#q(`SELECT COALESCE(SUM(${SESSION_MS_AT_MOST}), 0) ms FROM sessions WHERE provider=? AND opened_at >= ? AND ${ENDED_AT} < ?`).get(provider, iso(since), iso(billedBefore)).ms,
+        this.#q(`SELECT COALESCE(SUM(${SESSION_MS_AT_MOST}), 0) ms FROM sessions WHERE account=? AND opened_at >= ? AND ${ENDED_AT} < ?`).get(account, iso(since), iso(billedBefore)).ms,
     };
   }
 
-  /** The provider's sessions open at any time since `at` (ms): [{ durationMs }], as long as they can last while untimed */
-  openSince(provider, at) {
-    return this.#q(`SELECT ${SESSION_MS_AT_MOST} durationMs FROM sessions WHERE provider=? AND ${ENDED_AT} >= ?`).all(provider, iso(at));
+  /** The account's sessions open at any time since `at` (ms): [{ durationMs }], as long as they can last while untimed */
+  openSince(account, at) {
+    return this.#q(`SELECT ${SESSION_MS_AT_MOST} durationMs FROM sessions WHERE account=? AND ${ENDED_AT} >= ?`).all(account, iso(at));
   }
 
-  /** Sessions of `providers` without their provider's record 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));
+  /** The account's sessions without their provider's record yet: [{ id, openedAt, closedAt }] (ISO times) */
+  awaitingUsage(account) {
+    return this.#q('SELECT id, opened_at openedAt, closed_at closedAt FROM sessions WHERE synced_at IS NULL AND account=? ORDER BY opened_at').all(account);
   }
 
-  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);
+  recordUsage(account, { id, durationMs, proxyBytes }) {
+    this.#q('UPDATE sessions SET duration_ms=?, proxy_bytes=?, synced_at=? WHERE account=? AND id=?').run(int(durationMs), int(proxyBytes), iso(Date.now()), account, id);
   }
 
   /** Runs fn in a transaction that takes the write lock at once: another process may be writing too */
@@ -150,13 +187,24 @@ export class Ledger {
   /** See OneBrowser.usage() */
   usage(since) {
     return this.#q(
-      `SELECT substr(opened_at, 1, 10) day, provider, client, COUNT(*) sessions,
+      `SELECT substr(opened_at, 1, 10) day, provider, COALESCE(account, provider) account, 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`,
+       FROM sessions WHERE opened_at >= ? GROUP BY day, provider, account, client ORDER BY day, provider, account, client`,
     ).all(iso(since));
   }
 
+  /** See OneBrowser.sessions() */
+  sessions(since) {
+    return this.#q(
+      `SELECT provider, COALESCE(account, provider) account, id, client, opened_at openedAt, ends_by endsBy, closed_at closedAt,
+              duration_ms durationMs, proxy_bytes proxyBytes, synced_at syncedAt
+       FROM sessions WHERE opened_at >= ? ORDER BY opened_at, provider, id`,
+    )
+      .all(iso(since))
+      .map((r) => ({ ...r, openedAt: Date.parse(r.openedAt), endsBy: Date.parse(r.endsBy), closedAt: r.closedAt && Date.parse(r.closedAt), syncedAt: r.syncedAt && Date.parse(r.syncedAt) }));
+  }
+
   close() {
     this.#db.close();
   }

package/src/options.js

@@ -0,0 +1,30 @@
+import { KEEP_ALIVE_MS } from './session.js';
+
+/** Session options when openSession() is not given them */
+const SESSION_DEFAULTS = {
+  proxyCountry: null,
+  idleTimeoutSec: 60,
+  maxDurationMs: 15 * 60_000,
+};
+
+/**
+ * The session options of openSession() with the defaults filled in; 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, or after the provider's
+ *                    minIdleTimeoutSec if longer (≥ 2 × KEEP_ALIVE_MS)
+ *   maxDurationMs    a 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;
+}
+
+/** How long a session lasts at most, whatever becomes of its process: closed at maxDurationMs, else ended by its provider once idle */
+export const sessionMsAtMost = (o, settings) => o.maxDurationMs + Math.max(o.idleTimeoutSec, settings.minIdleTimeoutSec) * 1000;

package/src/session.js

@@ -5,11 +5,12 @@ export const KEEP_ALIVE_MS = 15_000;
 const firstLine = (e) => String(e.message).split('\n')[0];
 
 /**
- * A remote browser session (OneBrowser.openSession), used over CDP: cdpUrl with any client (it may carry the API
+ * A remote browser session (Account.openSession), used over CDP: cdpUrl with any client (it may carry the API
  * key: never log it), or connect() / newPage() with Playwright. This process closes it maxDurationMs after it was
  * opened; one whose process died is ended by its provider idleTimeoutSec (at least its minIdleTimeoutSec) after
  * its client left.
- * openedAt: when it was asked for; closedAt: when its provider released it, null until then.
+ * account: the Account it is billed to; openedAt: when it was asked for; closedAt: when its provider released
+ * it, null until then.
  */
 export class Session {
   #release;
@@ -18,9 +19,9 @@ export class Session {
   #keepAlive = null;
   #deadline;
 
-  /** release(session) → closedAt: releases it at its provider and records it closed (OneBrowser) */
-  constructor({ provider, remote, openedAt, maxDurationMs, release }) {
-    this.provider = provider;
+  /** release(session) → closedAt: releases it at its provider and records it closed (Account) */
+  constructor({ account, remote, openedAt, maxDurationMs, release }) {
+    this.account = account;
     this.id = remote.id;
     this.egress = remote.egress;
     this.cdpUrl = remote.cdpUrl;
@@ -33,7 +34,7 @@ export class Session {
 
   /** Playwright's Browser over this session's CDP connection, made once; a keep-alive runs while it is connected */
   connect() {
-    if (this.#closing) return Promise.reject(new Error(`${this.provider} session ${this.id} is closed`));
+    if (this.#closing) return Promise.reject(new Error(`${this.account.id} session ${this.id} is closed`));
     this.#browser ??= this.#connect();
     return this.#browser;
   }
@@ -44,11 +45,11 @@ export class Session {
     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)}`);
+      throw new Error(`failed to connect to the ${this.account.provider} browser: ${firstLine(e)}`);
     }
     try {
       const cdp = await browser.newBrowserCDPSession();
-      if (this.#closing) throw new Error(`${this.provider} session ${this.id} is closed`);
+      if (this.#closing) throw new Error(`${this.account.id} session ${this.id} is closed`);
       this.#keepAlive = setInterval(() => cdp.send('Browser.getVersion').catch(() => {}), KEEP_ALIVE_MS);
       this.#keepAlive.unref();
     } catch (e) {