onebrowser 0.6.0 → 0.8.0

package/README.md

@@ -16,7 +16,7 @@ const page = await session.newPage(); // Playwright; or any CDP client on sessio
 await page.goto('https://example.com');
 await session.close();
 
-await steel.readQuota(); // { remaining, unbilled, unit: 'USD', renewsAt: null }
+await steel.readQuota(); // { remaining, unbilled, unit: 'USD', renewsAt: null, total: 30 }
 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
@@ -30,13 +30,15 @@ Built in: [Steel](https://steel.dev), [TinyFish](https://tinyfish.ai), [Hyperbro
 
 ## Interface
 
-`new OneBrowser({ client, ledgerPath, providers, adapters })`
+`new OneBrowser({ client, env, envFile, ledgerPath, providers, adapters })`
 
 | Option | |
 |---|---|
 | `client` | The program using it, recorded with each session; required |
+| `env` | The variables it reads the API keys (see [Accounts](#accounts)) and the ledger's place (see [The ledger](#the-ledger)) from; default: `process.env` |
+| `envFile` | An env file whose variables it reads under those set in `env`, parsed as Node parses env files; a variable set but empty is unset. They stay out of the process's environment, so a program's child processes do not see the keys |
 | `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`: `apiKeys` (see [Accounts](#accounts)), `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` and `includedQuota`) |
 | `adapters` | Further adapters by provider name, or replacements of built-in ones |
 
 | Method | |
@@ -45,6 +47,8 @@ Built in: [Steel](https://steel.dev), [TinyFish](https://tinyfish.ai), [Hyperbro
 | `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 |
 
 An account has `id` (`steel#3f9a1c`: the provider's name and the key's fingerprint), `provider`, `fingerprint`, and:
@@ -53,7 +57,7 @@ An account has `id` (`steel#3f9a1c`: the provider's name and the key's fingerpri
 |---|---|
 | `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 |
+| `quota()` | What is left now, from the last reading: `{ remaining, unbilled, unit, renewsAt, total }` (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:
@@ -90,29 +94,31 @@ How each provider meets them:
 
 `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.
+`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. `total` is what the quota holds when whole, for showing how much of it is used: the plan's as the provider reports it, else the adapter's plan facts (`monthlyHours`, or `includedQuota`: the free plan's, or the grant a new account starts with); `null` when neither says. A top-up can leave `remaining` above it. `price`, `billingDelayMs` and the plan facts are settings: a program on another plan sets its own.
 
-| Provider | Quota, unit | Read from | `price` | `billingDelayMs` |
-|---|---|---|---|---|
-| `steel` | balance, USD | `GET /v1/credits/balance`, the endpoint of Steel's dashboard (not in its API docs) | $0.10 an hour (Launch plan), by the minute | 5 min |
-| `tinyfish` | wallet, USD | [`GET /v1/wallet`](https://docs.tinyfish.ai/wallet); a session refused with 402 throws `QuotaError` | $0.002 a minute, by the minute | 5 min |
-| `hyperbrowser` | credits | `GET /api/team/credit-info`, the endpoint of Hyperbrowser's SDK (not in its API docs) | 100 an hour, by the minute | 5 min |
-| `lightpanda` | browser hours of the calendar month (`monthlyHours`, default: the free plan's) | the ledger's record of its sessions that have ended: its console shows the month's usage, but its token cannot read it. So the reading is whole while the account is used only through ledgers of this machine | 1 per browser hour, by the second | 0 |
-| `kernel` | browser hours of the calendar month (`monthlyHours`, default: what the free plan's credits pay for), counted from the first of the month, 00:00 UTC | the uptime of the account's sessions this month, from `GET /browsers` (Kernel has no API for what its credits leave); a session refused with 403 (spending cap) throws `QuotaError` | 1 per browser hour, by the second | 5 min |
-| `anchor` | credits | `GET /v1/billing`; a session refused with 402 throws `QuotaError` | 0.01 a session and 0.15 an hour, by the minute: above what its sessions' records bill (its docs: 0.05 an hour) | 5 min |
-| `firecrawl` | credits; the plan's credits renew at the end of each billing period | [`GET /v2/team/credit-usage`](https://docs.firecrawl.dev/api-reference/endpoint/credit-usage); a session refused with 402 throws `QuotaError` | 2 a minute, in 30 s steps, at least a minute | 5 min |
+| Provider | Quota, unit | `total` | Read from | `price` | `billingDelayMs` |
+|---|---|---|---|---|---|
+| `steel` | balance, USD | `includedQuota`: 30, the Launch plan's one-time credits (valid 90 days) | `GET /v1/credits/balance`, the endpoint of Steel's dashboard (not in its API docs) | $0.10 an hour (Launch plan), by the minute | 5 min |
+| `tinyfish` | wallet, USD | `includedQuota`: 8, what a new wallet starts with | [`GET /v1/wallet`](https://docs.tinyfish.ai/wallet); a session refused with 402 throws `QuotaError` | $0.002 a minute, by the minute | 5 min |
+| `hyperbrowser` | credits | `includedQuota`: 5,000, a free account's ($5) | `GET /api/team/credit-info`, the endpoint of Hyperbrowser's SDK (not in its API docs) | 100 an hour, by the minute | 5 min |
+| `lightpanda` | browser hours of the calendar month (`monthlyHours`, default: the free plan's) | `monthlyHours`: 10 | the ledger's record of its sessions that have ended: its console shows the month's usage, but its token cannot read it. So the reading is whole while the account is used only through ledgers of this machine | 1 per browser hour, by the second | 0 |
+| `kernel` | browser hours of the calendar month (`monthlyHours`, default: what the free plan's credits pay for), counted from the first of the month, 00:00 UTC | `monthlyHours`: 80, what the free plan's $5 a month pays for | the uptime of the account's sessions this month, from `GET /browsers` (Kernel has no API for what its credits leave); a session refused with 403 (spending cap) throws `QuotaError` | 1 per browser hour, by the second | 5 min |
+| `anchor` | credits | `includedQuota`: 5, the free plan's each month | `GET /v1/billing`; a session refused with 402 throws `QuotaError` | 0.01 a session and 0.15 an hour, by the minute: above what its sessions' records bill (its docs: 0.05 an hour) | 5 min |
+| `firecrawl` | credits; the plan's credits renew at the end of each billing period | the plan's credits (`planCredits`), as read | [`GET /v2/team/credit-usage`](https://docs.firecrawl.dev/api-reference/endpoint/credit-usage); a session refused with 402 throws `QuotaError` | 2 a minute, in 30 s steps, at least a minute | 5 min |
 
 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.
 
 ### 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.
+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 its 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.
 
 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 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.
+One SQLite file per machine by default: the variable `ONEBROWSER_DB`, else `onebrowser/sessions.db` in `XDG_DATA_HOME` (ignored when relative, as the XDG spec has it; default `~/.local/share`), `~` standing for the home directory in either, 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.
+
+`defaultLedgerPath({ env, envFile })` says where a `OneBrowser` with these options keeps its ledger unless given a path, and `LEDGER_PATH_VARIABLES` which variables place it. A program that only looks for the ledger imports them from `onebrowser/ledger-path`, which loads no SQLite.
 
 ## Command line
 
@@ -125,7 +131,7 @@ npx onebrowser usage --days 7        # the ledger's sessions per UTC day, accoun
 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 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.
+`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, total }`, 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 and the ledger are read as by the library, from the environment and, with `--env-file PATH`, from that file (its `envFile`). Exit status: 0 done, 1 a reading failed, 2 the command line is wrong.
 
 ## Adding a provider
 
@@ -135,7 +141,7 @@ Write `src/providers/<name>.js` and register it in `ADAPTERS` (`src/providers/in
 - `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? }`: for a provider that cannot report its usage, `history.endedSessionMsSince(ms)` is the session time of the ledger's sessions that the reading shows.
+- `quota(settings, apiKey, history) → { remaining, unit, renewsAt?, total? }`: 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,6 +1,6 @@
 {
   "name": "onebrowser",
-  "version": "0.6.0",
+  "version": "0.8.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",
@@ -9,7 +9,10 @@
   "homepage": "https://github.com/i-richardwang/onebrowser#readme",
   "bugs": "https://github.com/i-richardwang/onebrowser/issues",
   "type": "module",
-  "exports": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./ledger-path": "./src/ledger-path.js"
+  },
   "bin": { "onebrowser": "bin/onebrowser.js" },
   "files": ["src", "bin"],
   "scripts": {

package/src/account.js

@@ -82,19 +82,21 @@ export class Account {
   }
 
   /**
-   * What is left of the quota now, in the provider's unit: { remaining, unbilled, unit, renewsAt }. The last
+   * What is left of the quota now, in the provider's unit: { remaining, unbilled, unit, renewsAt, total }. 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.
+   * that. renewsAt (ms): when the quota renews by itself; null: only a top-up renews it. total: what the quota
+   * holds when whole, the plan's or a free grant's, as the provider reports it or the adapter's plan facts give
+   * it, for showing how much of it is used; null when neither says. 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 };
+    const { remaining, unit, renewsAt, total } = reading.value;
+    return { remaining: remaining - unbilled, unbilled, unit, renewsAt, total };
   }
 
   /** The latest reading if it is in progress or at most maxAgeMs old, else a new one */
@@ -108,7 +110,7 @@ export class Account {
       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;
+        reading.value = { remaining: q.remaining, unit: q.unit, renewsAt: q.renewsAt ?? null, total: Number.isFinite(q.total) && q.total > 0 ? q.total : null };
       } catch (e) {
         reading.error = e;
       }

package/src/cli.js

@@ -21,8 +21,8 @@ const GLOBAL_OPTIONS = {
 /** 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;
+    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`);
@@ -46,7 +46,7 @@ const COMMANDS = {
       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)}` : ''}`;
+          const text = q.error ? `unknown (${q.error})` : `${round(q.remaining)}${q.total ? ` of ${round(q.total)}` : ''} ${q.unit} left${q.unbilled ? ` (after ${round(q.unbilled)} not billed yet)` : ''}${q.renewsAt ? `, renews ${day(q.renewsAt)}` : ''}`;
           out.write(`${q.account.padEnd(21)} ${text}\n`);
         }
       }
@@ -63,7 +63,7 @@ const COMMANDS = {
       const { failed } = await browsers.syncUsage();
       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');
@@ -88,7 +88,7 @@ Usage:
 
 Options:
   --json             JSON on stdout instead of text
-  --env-file PATH    read environment variables (API keys) from PATH first
+  --env-file PATH    read the variables below from PATH too; those set in the environment win
   -h, --help
 
 Environment:
@@ -129,8 +129,7 @@ function parseCommandLine(argv) {
 export async function run(argv, { out = process.stdout, err = process.stderr, browsers } = {}) {
   try {
     const { command, values, args } = parseCommandLine(argv);
-    if (values['env-file']) process.loadEnvFile(values['env-file']);
-    browsers ??= new OneBrowser({ client: 'onebrowser' });
+    browsers ??= new OneBrowser({ client: 'onebrowser', envFile: values['env-file'] });
     if (values.help || !command) {
       (values.help ? out : err).write(help(browsers.providers));
       return values.help ? 0 : 2;

package/src/credentials.js

@@ -11,16 +11,16 @@ export const fingerprint = (apiKey) => crypto.createHash('sha256').update(apiKey
 const split = (text) => text.split(/[\s,]+/).filter(Boolean);
 
 /**
- * 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
+ * A provider's API keys, one per account: `apiKeys` as given in its settings, else those in the variable
+ * apiKeyEnv(provider) of `variables`, 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 readApiKeys(provider, apiKeys) {
-  const env = apiKeyEnv(provider);
-  const file = process.env[`${env}_FILE`];
-  let keys = apiKeys ?? split(process.env[env] ?? '');
+export function readApiKeys(provider, apiKeys, variables) {
+  const name = apiKeyEnv(provider);
+  const file = variables[`${name}_FILE`];
+  let keys = apiKeys ?? split(variables[name] ?? '');
   if (!keys.length && file) {
-    if (!fs.existsSync(file)) throw new Error(`${provider} keys: ${env}_FILE names no file (${file})`);
+    if (!fs.existsSync(file)) throw new Error(`${provider} keys: ${name}_FILE names no file (${file})`);
     keys = split(fs.readFileSync(file, 'utf8'));
   }
   return [...new Set(keys.map((k) => k.trim()).filter(Boolean))];

package/src/index.js

@@ -1,10 +1,13 @@
 import { Account } from './account.js';
 import { readApiKeys } from './credentials.js';
 import { QuotaError } from './errors.js';
-import { defaultLedgerPath, Ledger } from './ledger.js';
+import { Ledger } from './ledger.js';
+import { ledgerPathIn } from './ledger-path.js';
 import { ADAPTERS, checkAdapter, fullSettings } from './providers/index.js';
+import { readVariables } from './variables.js';
 
 export { apiKeyEnv } from './credentials.js';
+export { defaultLedgerPath, LEDGER_PATH_VARIABLES } from './ledger-path.js';
 export { sessionOptions } from './options.js';
 export { QuotaError };
 
@@ -15,19 +18,22 @@ export { QuotaError };
  * 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, apiKeys among them
- * (else credentials.js); adapters: further or replacement adapters by provider name.
+ * client: the program using it, recorded with each session; env, envFile: the variables it reads the API keys
+ * and the ledger's place from (variables.js), the process's environment by default, over those of an env file
+ * if one is named; ledgerPath: the ledger's SQLite file, opened when first needed; providers: settings per
+ * provider name on top of its adapter's defaults, apiKeys among them; adapters: further or replacement adapters
+ * by provider name.
  */
 export class OneBrowser {
   #providers = []; // names, in the adapters' order
   #accounts = [];
   #ledger = null;
 
-  constructor({ client, ledgerPath = defaultLedgerPath(), providers = {}, adapters = {} }) {
+  constructor({ client, env = process.env, envFile, ledgerPath, providers = {}, adapters = {} }) {
     if (!client?.trim()) throw new Error('onebrowser: client must name the program using it');
+    const variables = readVariables(env, envFile);
     this.client = client;
-    this.ledgerPath = ledgerPath;
+    this.ledgerPath = ledgerPath ?? ledgerPathIn(variables);
     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(', ')}`);
@@ -36,16 +42,13 @@ export class OneBrowser {
       const { apiKeys, ...given } = providers[provider] ?? {};
       const settings = fullSettings(provider, { ...adapter.defaults, ...given });
       this.#providers.push(provider);
-      for (const apiKey of readApiKeys(provider, apiKeys)) {
+      for (const apiKey of readApiKeys(provider, apiKeys, variables)) {
         this.#accounts.push(new Account({ provider, adapter, settings, apiKey, client, ledger: () => this.#store }));
       }
     }
   }
 
-  /**
-   * The ledger, opened on first use. Sessions recorded before accounts were (onebrowser 0.5 and earlier) are
-   * the provider's only account's, when it has one here; with several, no one knows which they belong to.
-   */
+  /** 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);
@@ -56,6 +59,11 @@ export class OneBrowser {
     return this.#ledger;
   }
 
+  /** 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;
+  }
+
   /** Names of the providers it has adapters for */
   get providers() {
     return [...this.#providers];
@@ -96,6 +104,16 @@ export class OneBrowser {
     return this.#store.usage(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, 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.#accounts.map((a) => a.close()));

package/src/ledger-path.js

@@ -0,0 +1,27 @@
+import os from 'node:os';
+import path from 'node:path';
+import { readVariables } from './variables.js';
+
+// Where the ledger lives: the one part of onebrowser a program needs to find the ledger without opening it. The
+// package exports it on its own (onebrowser/ledger-path), which loads no SQLite.
+
+/** The variables that place the ledger, in the order they are read */
+export const LEDGER_PATH_VARIABLES = ['ONEBROWSER_DB', 'XDG_DATA_HOME'];
+
+/** A path as a variable holds it, `~` standing for the home directory: an env file's are not expanded by a shell */
+const expandHome = (p) => (p === '~' || p.startsWith('~/') ? path.join(os.homedir(), p.slice(1)) : p);
+
+/**
+ * Where the ledger lives unless a path is given, by onebrowser's variables (variables.js): ONEBROWSER_DB, else
+ * onebrowser/sessions.db in the user's data directory: XDG_DATA_HOME, which the XDG spec ignores when relative,
+ * else ~/.local/share. One ledger per machine is shared by every project on it, so that the record of an
+ * account's sessions is whole, whichever project opened them.
+ */
+export function ledgerPathIn(variables) {
+  if (variables.ONEBROWSER_DB) return expandHome(variables.ONEBROWSER_DB);
+  const data = variables.XDG_DATA_HOME && expandHome(variables.XDG_DATA_HOME);
+  return path.join(data && path.isAbsolute(data) ? data : path.join(os.homedir(), '.local', 'share'), 'onebrowser', 'sessions.db');
+}
+
+/** Where a OneBrowser given `env` and `envFile` (as its options) keeps its ledger unless it is given a path */
+export const defaultLedgerPath = ({ env = process.env, envFile } = {}) => ledgerPathIn(readVariables(env, envFile));

package/src/ledger.js

@@ -1,25 +1,14 @@
 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 an account's sessions is whole, whichever project opened them.
- */
-export function defaultLedgerPath() {
-  if (process.env.ONEBROWSER_DB) return process.env.ONEBROWSER_DB;
-  const data = process.env.XDG_DATA_HOME || path.join(os.homedir(), '.local', 'share');
-  return path.join(data, 'onebrowser', 'sessions.db');
-}
-
 /** Every remote browser session, from when its provider has created it: it is billed from then on, even if connecting fails */
 const SCHEMA = `
 CREATE TABLE sessions (
   provider      TEXT NOT NULL,
-  account       TEXT,                     -- the account it is billed to (Account.id); empty when not known: recorded
-                                          -- before onebrowser 0.6, by a provider with several accounts here since
+  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
@@ -65,6 +54,13 @@ const UPGRADES = {
       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)`;
 
@@ -96,16 +92,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) {
@@ -122,7 +131,7 @@ export class Ledger {
     this.#q('UPDATE sessions SET closed_at=? WHERE account=? AND id=? AND closed_at IS NULL').run(iso(closedAt), account, id);
   }
 
-  /** The provider's sessions whose account is not known are `account`'s */
+  /** 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);
   }
@@ -173,6 +182,17 @@ export class Ledger {
     ).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/providers/anchor.js

@@ -12,6 +12,7 @@ import { json } from './http.js';
  */
 export const defaults = {
   apiBase: 'https://api.anchorbrowser.io/v1',
+  includedQuota: 5, // credits the free plan includes each month (docs.anchorbrowser.io/pricing, 2026-11)
   // credits ($1 each): $0.01 a browser and, by its docs, $0.05 an hour by the minute; the sessions' own records
   // (credits_used) bill more, about $0.06 an hour and a step of $0.003 in the second minute, which this covers
   price: { perSession: 0.01, perHour: 0.15, stepSec: 60 },
@@ -45,7 +46,7 @@ export async function releaseSession(settings, apiKey, session) {
 /** The account's credits left, gifted ones included. Unlike the other endpoints, /billing answers without a `data` wrapper */
 export async function quota(settings, apiKey) {
   const { credits } = await json(`${settings.apiBase}/billing`, { headers: headers(apiKey) });
-  return { remaining: credits, unit: 'credits' };
+  return { remaining: credits, unit: 'credits', total: settings.includedQuota };
 }
 
 /** Usage of the sessions among `sessions` that have ended, fetched by id: duration in whole seconds */

package/src/providers/firecrawl.js

@@ -44,10 +44,13 @@ export async function releaseSession(settings, apiKey, session) {
   await json(`${settings.apiBase}/interact/${session.id}`, { method: 'DELETE', headers: headers(apiKey) });
 }
 
-/** The team's credits left, coupon credits included; the plan's credits renew at the end of its billing period */
+/**
+ * The team's credits left, coupon credits included; the plan's credits (planCredits, without coupon or
+ * pay-as-you-go ones) renew at the end of its billing period
+ */
 export async function quota(settings, apiKey) {
   const { data } = await json(`${settings.apiBase}/team/credit-usage`, { headers: headers(apiKey) });
-  return { remaining: data.remainingCredits, unit: 'credits', renewsAt: data.billingPeriodEnd ? Date.parse(data.billingPeriodEnd) : null };
+  return { remaining: data.remainingCredits, unit: 'credits', renewsAt: data.billingPeriodEnd ? Date.parse(data.billingPeriodEnd) : null, total: data.planCredits };
 }
 
 /** Usage of the sessions among `sessions` that have ended, fetched by id: the session list has no durations (GET /interact/{id} is not in Firecrawl's API docs) */

package/src/providers/hyperbrowser.js

@@ -9,6 +9,7 @@ import { json } from './http.js';
  */
 export const defaults = {
   apiBase: 'https://api.hyperbrowser.ai/api',
+  includedQuota: 5000, // credits a free account comes with, worth $5 (hyperbrowser.ai/pricing, 2026-11)
   price: { perHour: 100, stepSec: 60 }, // credits; its rounding is not documented
   billingDelayMs: 5 * 60_000, // billed while the session runs, seen within 10 s of its end
 };
@@ -30,7 +31,7 @@ export async function releaseSession(settings, apiKey, session) {
 /** The team's credits left (the endpoint of Hyperbrowser's SDK; it is not in Hyperbrowser's API docs) */
 export async function quota(settings, apiKey) {
   const { remaining } = await json(`${settings.apiBase}/team/credit-info`, { headers: headers(apiKey) });
-  return { remaining, unit: 'credits' };
+  return { remaining, unit: 'credits', total: settings.includedQuota };
 }
 
 /** Usage of the sessions among `sessions` that have ended (have an endTime), fetched by id. Times are epoch ms, as numbers or strings */

package/src/providers/index.js

@@ -13,14 +13,16 @@ import * as tinyfish from './tinyfish.js';
  *     price               what its sessions cost, in the unit of its quota (cost.js)
  *     billingDelayMs      how long after a session has ended its quota reading shows it, at the latest
  *     minIdleTimeoutSec   the shortest idle timeout it takes (default 0)
- *     and its own         API base URLs, plan facts such as monthlyHours
+ *     and its own         API base URLs, plan facts such as monthlyHours or includedQuota (what the plan, or
+ *                         the free grant, puts in the quota when the provider does not say)
  *   createSession(settings, apiKey, { proxyCountry, idleTimeoutSec, maxDurationMs }) → { id, cdpUrl, egress }
  *       throws QuotaError (errors.js) 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 provider's record of those that have ended, or the ledger's timing where its API key cannot read one
- *   quota(settings, apiKey, history) → { remaining, unit, renewsAt? }
- *       what the account has left in the provider's unit, and when it renews by itself (ms); history: the
+ *   quota(settings, apiKey, history) → { remaining, unit, renewsAt?, total? }
+ *       what the account has left in the provider's unit, when it renews by itself (ms), and what it holds when
+ *       whole, as the provider reports it or the plan facts give it; history: the
  *       ledger's sessions that the reading shows (Ledger.history), for a provider that cannot count its usage
  * Every function throws when it fails. Requests go through http.js, which throws HttpError for a status other
  * than 2xx.

package/src/providers/kernel.js

@@ -13,7 +13,7 @@ import { utcMonth } from './month.js';
  */
 export const defaults = {
   apiBase: 'https://api.onkernel.com',
-  monthlyHours: 80, // headless browser hours a month that the free plan's credits pay for, rounded down
+  monthlyHours: 80, // headless browser hours a month that the free plan's $5 of credits pay for, rounded down
   price: { perHour: 1 }, // the quota is in headless browser hours, billed by the second
   billingDelayMs: 5 * 60_000, // seen within 10 s
 };
@@ -56,7 +56,7 @@ export async function quota(settings, apiKey) {
     usedMs += ofMonth.reduce((ms, s) => ms + (s.usage?.uptime_ms ?? 0), 0);
     if (!ofMonth.length || r.headers.get('x-has-more') !== 'true') break;
   }
-  return { remaining: settings.monthlyHours - usedMs / 3_600_000, unit: 'hours', renewsAt: month.next };
+  return { remaining: settings.monthlyHours - usedMs / 3_600_000, unit: 'hours', renewsAt: month.next, total: settings.monthlyHours };
 }
 
 /** Usage of the sessions among `sessions` that Kernel has deleted and finished billing, fetched by id */

package/src/providers/lightpanda.js

@@ -39,7 +39,7 @@ export async function releaseSession() {}
 export async function quota(settings, apiKey, history) {
   const month = utcMonth();
   const usedHours = history.endedSessionMsSince(month.start) / 3_600_000;
-  return { remaining: settings.monthlyHours - usedHours, unit: 'hours', renewsAt: month.next };
+  return { remaining: settings.monthlyHours - usedHours, unit: 'hours', renewsAt: month.next, total: settings.monthlyHours };
 }
 
 /**

package/src/providers/steel.js

@@ -8,6 +8,7 @@ import { json } from './http.js';
 export const defaults = {
   apiBase: 'https://api.steel.dev/v1',
   connectBase: 'wss://connect.steel.dev',
+  includedQuota: 30, // USD: the Launch plan's one-time credits, valid for 90 days (steel.dev/pricing, 2026-11)
   price: { perHour: 0.1, stepSec: 60 }, // USD on the Launch plan, by the minute rounded up
   billingDelayMs: 5 * 60_000, // seen within 11 s
 };
@@ -32,7 +33,7 @@ export async function releaseSession(settings, apiKey, session) {
 /** The account's balance in USD, as Steel's dashboard reads it (the endpoint is not in Steel's API docs) */
 export async function quota(settings, apiKey) {
   const { balanceCents } = await json(`${settings.apiBase}/credits/balance`, { headers: headers(apiKey) });
-  return { remaining: balanceCents / 100, unit: 'USD' };
+  return { remaining: balanceCents / 100, unit: 'USD', total: settings.includedQuota };
 }
 
 /** Usage of the sessions among `sessions` that have ended, fetched by id: the session list cannot be filtered by time */

package/src/providers/tinyfish.js

@@ -10,6 +10,7 @@ import { json } from './http.js';
 export const defaults = {
   apiBase: 'https://api.browser.tinyfish.ai',
   walletUrl: 'https://agent.tinyfish.ai/v1/wallet',
+  includedQuota: 8, // USD: what a new account's wallet starts with (tinyfish.ai/pricing, 2026-11)
   price: { perHour: 0.12, stepSec: 60 }, // USD: $0.002 a minute, proxy included; its rounding is not documented
   billingDelayMs: 5 * 60_000, // seen within 64 s
 };
@@ -36,7 +37,7 @@ export async function releaseSession(settings, apiKey, session) {
 /** The wallet's balance (https://docs.tinyfish.ai/wallet) */
 export async function quota(settings, apiKey) {
   const w = await json(settings.walletUrl, { headers: headers(apiKey) });
-  return { remaining: Number(w.available_balance), unit: w.currency };
+  return { remaining: Number(w.available_balance), unit: w.currency, total: settings.includedQuota };
 }
 
 /**

package/src/variables.js

@@ -0,0 +1,19 @@
+import fs from 'node:fs';
+import { parseEnv } from 'node:util';
+
+/**
+ * The variables onebrowser reads its configuration from, the API keys (credentials.js) and the ledger's place
+ * (ledger-path.js): those set in `env`, over those of the env file at `envFile` if one is named, parsed as Node
+ * parses env files. A variable set but empty is unset, as onebrowser reads every variable, so it hides none of the
+ * file's.
+ */
+export function readVariables(env, envFile) {
+  if (envFile === undefined) return env;
+  let text;
+  try {
+    text = fs.readFileSync(envFile, 'utf8');
+  } catch (e) {
+    throw new Error(`cannot read the env file ${envFile}: ${e.message}`);
+  }
+  return { ...parseEnv(text), ...Object.fromEntries(Object.entries(env).filter(([, value]) => value)) };
+}