onebrowser 0.4.0 → 0.6.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,19 +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.quota('steel'); // { remaining, unbilled, unit: 'USD', renewsAt: null }
-browsers.maxSessionCost('steel', {}); // what a session with these options costs at most, in USD
-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 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, account, 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: what is left of the quota once the sessions not billed yet are paid for, 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.
 
@@ -34,34 +36,40 @@ 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` and `billingDelayMs` (see [Quota](#quota)), and the adapter's own settings (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, recorded in the ledger once the provider has created it. Throws `QuotaError` when the provider refuses it for the account's quota |
-| `quota(provider, { maxAgeMs })` | `{ remaining, unbilled, unit, renewsAt }` in the provider's own unit: what the provider reads less `unbilled`, what the sessions it may not show yet cost (see [Quota](#quota)); `renewsAt` (ms) when it renews by itself, `null` when only a top-up renews it. The provider is read anew unless a reading started at most `maxAgeMs` ago (default 0) or one in progress can be used, a failed one too; `unbilled` is worked out anew every time. Throws when the provider cannot be read |
-| `maxSessionCost(provider, options)` | What a session with these session options costs at most, in the unit of the provider's quota: as if it lasted `maxDurationMs` and then `idleTimeoutSec`, at the provider's price |
-| `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` |
+| `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` |
 | `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` (when it was asked for), `closedAt`, and:
+An account has `id` (`steel#3f9a1c`: the provider's name and the key's fingerprint), `provider`, `fingerprint`, 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.
+| 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:
 
-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()`).
+- `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 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
 
 | 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) |
+| `idleTimeoutSec` | 60 | A session whose client is gone (its process was killed) ends this long after at the latest, or after the provider's `minIdleTimeoutSec` if longer. 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.
@@ -80,9 +88,9 @@ How each provider meets them:
 
 ### Quota
 
-`quota()` answers what is left of the account's quota once every session not billed yet is paid for. The provider's reading shows the sessions that ended up to `billingDelayMs` before it; the ledger has the others, still open or ended since, and each costs the provider's `price`: an open session as if it lasted as long as it can (`maxDurationMs`, then `idleTimeoutSec`, should its process die), an ended one as long as it lasted. So a program can check, before each session, that the account can pay for one more (`maxSessionCost`), also between readings and with other programs on the machine opening sessions. Sessions opened elsewhere, through another machine's ledger, are not known until the provider bills them, and proxy traffic billed by the GB is not in the price.
+`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), and the session time billed in whole `stepSec`, rounded up (default 1), at least `minSec` (default 0). It bounds what sessions cost, so where a provider does not document its rounding the adapter takes the minute, rounded up. Both are settings: a program on another plan sets its own.
+`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.
 
 | Provider | Quota, unit | Read from | `price` | `billingDelayMs` |
 |---|---|---|---|---|
@@ -96,36 +104,38 @@ 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`). 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), with when it ends at the latest, closed when released, and completed with the provider's own record by `syncUsage()` once it has ended. A ledger made by an older onebrowser is brought up to date when it is opened.
+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()`. 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 `quota()` 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, 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: `price` and `billingDelayMs` (see [Quota](#quota)), and its own (API base URLs, plan facts).
+- `defaults`: `price`, `billingDelayMs`, `minIdleTimeoutSec` if the provider takes no idle timeout as short as asked (see [Quota](#quota)), and its own 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.endedSessionMsSince(ms)` is the session time of the provider's sessions in the ledger that have ended, for a provider that cannot report its own usage.
+- `quota(settings, apiKey, history) → { remaining, unit, renewsAt? }`: for a provider that cannot report its usage, `history.endedSessionMsSince(ms)` is the session time of the ledger's sessions that the reading shows.
 
 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.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "onebrowser",
-  "version": "0.4.0",
-  "description": "One interface to remote browser providers: sessions by provider name, a usage ledger, account quotas",
+  "version": "0.6.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().filter((a) => a.id === name);
+    if (own.length) 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.quota(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`);
       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/cost.js

@@ -1,20 +1,22 @@
 /**
- * A provider's price (its adapter's `price` setting, providers/index.js), in the unit its quota is read in:
+ * A provider's price (its `price` setting), in the unit its quota is read in:
  *   perHour     for the session time
  *   perSession  for each session, however short (default 0)
  *   stepSec     the session time is billed in whole steps of this, rounded up (default 1)
  *   minSec      and at least this much of it (default 0)
- * Where a provider's documentation does not say how it rounds, its adapter takes the minute, rounded up: the
- * price is used to bound what sessions cost, so it errs on the high side.
+ * It bounds what sessions cost, so where a provider does not document its rounding the adapter takes the minute.
  */
-export function checkPrice(price) {
+
+/** The price with its defaults filled in; throws when it is not one */
+export function fullPrice(price) {
   const { perHour, perSession = 0, stepSec = 1, minSec = 0, ...unknown } = price ?? {};
   const fine = [perHour, perSession, minSec].every((x) => Number.isFinite(x) && x >= 0) && Number.isFinite(stepSec) && stepSec > 0;
   if (!fine || Object.keys(unknown).length) throw new Error(`price must be { perHour, perSession, stepSec, minSec } of numbers ≥ 0 (stepSec > 0), not ${JSON.stringify(price)}`);
+  return { perHour, perSession, stepSec, minSec };
 }
 
-/** What a session that lasts durationMs costs at `price` */
-export function sessionCost({ perHour, perSession = 0, stepSec = 1, minSec = 0 }, durationMs) {
+/** What a session that lasts durationMs costs at `price` (fullPrice) */
+export function sessionCost({ perHour, perSession, stepSec, minSec }, durationMs) {
   const billedSec = Math.max(minSec, Math.ceil(durationMs / 1000 / stepSec) * stepSec);
   return perSession + (perHour * billedSec) / 3600;
 }

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))];
 }