onebrowser 0.4.0 → 0.6.0

package/src/index.js

@@ -1,240 +1,108 @@
-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, checkSettings } from './providers/index.js';
-import { KEEP_ALIVE_MS, Session } from './session.js';
+import { ADAPTERS, checkAdapter, fullSettings } from './providers/index.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, // null: the provider's default egress
-  idleTimeoutSec: 60, // a session whose client is gone (its process was killed) ends this long after at the latest
-  maxDurationMs: 15 * 60_000,
-};
-
-/**
- * The session options of openSession() with the defaults filled in (SESSION_DEFAULTS); throws when one is unknown
- * or out of range, so that a program can check its configuration before it opens any session:
- *   proxyCountry     country code: the provider's proxy there; null: its default egress
- *   idleTimeoutSec   a session whose client is gone ends this long after at the latest; at least twice the
- *                    keep-alive interval (session.js)
- *   maxDurationMs    the session ends this long after it was opened at the latest
- */
-export function sessionOptions(options = {}) {
-  const unknown = Object.keys(options).filter((k) => !Object.hasOwn(SESSION_DEFAULTS, k));
-  if (unknown.length) throw new Error(`unknown session option ${unknown.join(', ')} (expected ${Object.keys(SESSION_DEFAULTS).join(', ')})`);
-  const o = { ...SESSION_DEFAULTS, ...options };
-  if (!(Number.isFinite(o.idleTimeoutSec) && o.idleTimeoutSec * 1000 >= 2 * KEEP_ALIVE_MS)) {
-    throw new Error(`idleTimeoutSec must be at least ${(2 * KEEP_ALIVE_MS) / 1000} (twice the keep-alive interval), not ${o.idleTimeoutSec}`);
-  }
-  if (!(Number.isFinite(o.maxDurationMs) && o.maxDurationMs > 0)) throw new Error(`maxDurationMs must be a number > 0, not ${o.maxDurationMs}`);
-  return o;
-}
-
 /**
- * How long a session with these options (sessionOptions) lasts at most, whatever becomes of its process: this
- * process ends it at maxDurationMs, and its provider idleTimeoutSec after its client left, should the process die
- * or its release fail before
- */
-const sessionMsAtMost = (o) => o.maxDurationMs + o.idleTimeoutSec * 1000;
-
-/**
- * Remote browsers from several providers behind one interface: a session is asked for by provider name, the way
- * an LLM request names its model. Every session is recorded in a ledger (ledger.js), which the usage of each
- * provider account and, for providers that cannot report it themselves, its quota are read from.
- *
- * What is left of an account's quota is what its provider reads, less what the sessions it has not billed yet
- * cost (quota()): the ledger knows those, and each provider's price (cost.js) what they cost. So a program can
- * tell, before it opens a session, whether the account can pay for it.
+ * 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.
  *
- * Which provider to use, how many sessions to hold and when to stop using one are the caller's decisions:
- * OneBrowser opens the sessions it is asked for.
- *
- * new OneBrowser({ client, ledgerPath, providers, adapters })
- *   client       the program using it, recorded with each session (several programs may share one ledger)
- *   ledgerPath   SQLite file of the ledger (default: defaultLedgerPath() in ledger.js; ':memory:' for tests),
- *                opened when first needed
- *   providers    settings per provider name: apiKey (else from the environment, see credentials.js), and the
- *                adapter's own settings on top of its defaults (providers/<name>.js)
- *   adapters     further adapters by provider name, or replacements of built-in ones (providers/index.js)
+ * 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.
  */
 export class OneBrowser {
-  #providers = new Map(); // name → { adapter, settings: its defaults with the given ones on top, apiKey: the one given }
+  #providers = []; // names, in the adapters' order
+  #accounts = [];
   #ledger = null;
-  #open = new Set();
-  #readings = new Map(); // provider → its last quota reading (#reading)
 
   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] ?? {};
-      const settings = { ...adapter.defaults, ...given };
-      checkSettings(name, settings);
-      this.#providers.set(name, { adapter, settings, 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(', ')}`);
-  }
-
-  /** Names of the providers it can open sessions with */
-  get providers() {
-    return [...this.#providers.keys()];
-  }
-
-  get #store() {
-    return (this.#ledger ??= new Ledger(this.ledgerPath));
-  }
-
-  /** The adapter, settings and the API key given of `provider`; throws when it is unknown */
-  #known(provider) {
-    const p = this.#providers.get(provider);
-    if (!p) throw new Error(`unknown provider ${provider} (expected ${this.providers.join(', ')})`);
-    return p;
-  }
-
-  /** The adapter, settings and API key of `provider`; throws when it is unknown or has no API key */
-  #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`, recorded in the ledger once the provider has created it; options: see
-   * sessionOptions(). Throws when the provider does not create one; QuotaError when it refuses for the account's
-   * quota.
-   */
-  async openSession({ provider, ...options }) {
-    const { adapter, settings, apiKey } = this.#ready(provider);
-    const o = sessionOptions(options);
-    const openedAt = Date.now(); // the provider bills the session from some time after this
-    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: async (s) => {
-        this.#open.delete(s);
-        this.#store.closed(s);
-        await adapter.releaseSession(settings, apiKey, s);
-      },
-    });
-    try {
-      this.#store.opened({ provider, id: session.id, client: this.client, openedAt, endsBy: openedAt + sessionMsAtMost(o) });
-    } catch (e) {
-      await session.close().catch(() => {}); // a session the ledger has no record of 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;
   }
 
   /**
-   * What is left of the account's quota with `provider`, in the provider's own unit: { remaining, unbilled, unit,
-   * renewsAt }. remaining: what the provider reads, less `unbilled`: what the sessions in the ledger that the
-   * reading may not show yet cost, each at the provider's price (cost.js). Those are the sessions that had not
-   * ended billingDelayMs before the reading: open ones as if they lasted as long as they can, ended ones as long
-   * as they lasted. renewsAt (ms) when the quota renews by itself, null when only a top-up renews it.
-   *
-   * The provider is read anew unless a reading started at most maxAgeMs ago, or still in progress, can be used
-   * (a failed one too: it throws again); what is unbilled is worked out from the ledger every time, so it includes
-   * the sessions opened since, by any program sharing the ledger. Throws when the provider cannot be read.
+   * 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.
    */
-  async quota(provider, { maxAgeMs = 0 } = {}) {
-    const { settings } = this.#known(provider);
-    const reading = this.#reading(provider, maxAgeMs);
-    const answer = await reading.answer;
-    const sessions = this.#store.openAfter(provider, reading.startedAt - settings.billingDelayMs);
-    const unbilled = sessions.reduce((cost, s) => cost + sessionCost(settings.price, s.durationMs), 0);
-    return { remaining: answer.remaining - unbilled, unbilled, unit: answer.unit, renewsAt: answer.renewsAt ?? null };
+  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;
   }
 
-  /**
-   * The provider's quota reading, { startedAt, answer: a promise of the adapter's answer }: the last one if it
-   * started at most maxAgeMs ago or is still in progress, else a new one. A failed reading counts as one too: its
-   * error is the answer until maxAgeMs have passed.
-   */
-  #reading(provider, maxAgeMs) {
-    const last = this.#readings.get(provider);
-    if (last && (!last.done || Date.now() - last.startedAt <= maxAgeMs)) return last;
-    const { adapter, settings, apiKey } = this.#ready(provider);
-    const reading = { startedAt: Date.now(), done: false };
-    reading.answer = adapter
-      .quota(settings, apiKey, this.#store.history(provider))
-      .then((q) => {
-        if (!(Number.isFinite(q?.remaining) && typeof q.unit === 'string')) throw new Error(`${provider} answered no quota: ${JSON.stringify(q)}`);
-        return q;
-      })
-      .finally(() => (reading.done = true));
-    reading.answer.catch(() => {}); // awaited by the callers; not an unhandled rejection while cached
-    this.#readings.set(provider, reading);
-    return reading;
+  /** Names of the providers it has adapters for */
+  get providers() {
+    return [...this.#providers];
   }
 
-  /**
-   * What a session with `provider` and these session options (sessionOptions) costs at most, in the unit of its
-   * quota: as if it lasted as long as it can, at the provider's price
-   */
-  maxSessionCost(provider, options) {
-    return sessionCost(this.#known(provider).settings.price, sessionMsAtMost(sessionOptions(options)));
+  /** 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 each provider's record (duration, proxy traffic) of the sessions in the ledger that have ended and have
-   * none yet; sessions still running wait for a later call. A provider that cannot be reached, or has no API key,
-   * is left for a later call too. Sessions of a provider it has no adapter for (another program's own) are left
-   * to the programs that have one. Returns { reported: sessions completed, failed: [{ provider, error }] }.
+   * Stores the providers' records (duration, proxy traffic) of the ledger's ended sessions that have none yet:
+   * { 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 are the provider's
-   * record where syncUsage has stored it, otherwise the open-to-close timing of the process that opened the
-   * session; untimed: sessions with neither (their process ended before closing them and the provider has not
-   * reported them yet); unsynced: sessions without the provider's record.
+   * 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 */
+  /** 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;
   }
 
-  /** close(), for `await using browsers = new OneBrowser(…)` */
   [Symbol.asyncDispose]() {
     return this.close();
   }

package/src/ledger.js

@@ -6,7 +6,7 @@ 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;
@@ -14,48 +14,56 @@ export function defaultLedgerPath() {
   return path.join(data, 'onebrowser', 'sessions.db');
 }
 
-/**
- * sessions   every remote browser session: recorded when it is asked for, once its provider has created it (it
- *            is billed from then on, even if connecting fails), closed when released, and completed with the
- *            provider's own record (duration, proxy traffic) once the session has ended and syncUsage has
- *            fetched it
- */
-const SESSIONS = `
+/** 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
   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
   ends_by       TEXT NOT NULL,            -- when it has ended at the latest, whatever becomes of its process
-  closed_at     TEXT,                     -- when it was released; empty if its process ended first
+  closed_at     TEXT,                     -- when its provider released it; empty until then, and if it never was
   duration_ms   INTEGER,                  -- the provider's record, once the session has ended
   proxy_bytes   INTEGER,                  -- proxy traffic in the provider's record
   synced_at     TEXT,                     -- when the provider's record was stored; empty = not yet
   PRIMARY KEY (provider, id)
 );
-CREATE INDEX idx_sessions_opened ON sessions(provider, opened_at);
+CREATE INDEX idx_sessions_opened ON sessions(account, opened_at);
 `;
 
 /**
- * The schema's versions, each the step from the one before (PRAGMA user_version counts the steps taken). A ledger
- * is shared by every program on the machine and outlives the onebrowser version that created it, so an older
- * ledger is brought up to date when it is opened.
+ * 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; 0.4 and 0.5 made 2. Each
+ * step makes its version as that version was, whatever SCHEMA has become since.
  */
-const MIGRATIONS = [
-  // 1: the sessions, as onebrowser 0.1–0.3 kept them
-  `CREATE TABLE IF NOT EXISTS sessions (
-     provider TEXT NOT NULL, id TEXT NOT NULL, client TEXT NOT NULL, opened_at TEXT NOT NULL, closed_at TEXT,
-     duration_ms INTEGER, proxy_bytes INTEGER, synced_at TEXT, PRIMARY KEY (provider, id)
-   );`,
-  // 2: ends_by; the sessions of 1 were all opened with the session options' defaults: 15 min, then 60 s idle
-  `ALTER TABLE sessions RENAME TO sessions_1;
-   DROP INDEX IF EXISTS idx_sessions_opened;
-   ${SESSIONS}
-   INSERT INTO sessions (provider, id, client, opened_at, ends_by, closed_at, duration_ms, proxy_bytes, synced_at)
-     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;`,
-];
+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)
+  1: `ALTER TABLE sessions RENAME TO sessions_1;
+      DROP INDEX idx_sessions_opened;
+      CREATE TABLE sessions (
+        provider TEXT NOT NULL, 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(provider, 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, 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;`,
+};
 
 /** ms from one ISO time to another */
 const msBetween = (from, to) => `CAST(ROUND((julianday(${to}) - julianday(${from})) * 86400000) AS INTEGER)`;
@@ -73,29 +81,31 @@ const iso = (ms) => new Date(ms).toISOString();
 const int = (x) => (x === null || x === undefined || !Number.isFinite(Number(x)) ? null : Math.trunc(Number(x)));
 
 export class Ledger {
+  #file;
   #db;
   #stmts = new Map();
 
   constructor(file) {
     if (file !== ':memory:') fs.mkdirSync(path.dirname(file), { recursive: true });
+    this.#file = file;
     this.#db = new DatabaseSync(file);
     this.#db.exec('PRAGMA journal_mode=WAL; PRAGMA busy_timeout=5000;'); // several processes share it
     this.#migrate();
   }
 
-  /** Takes the steps of MIGRATIONS the ledger has not taken, in one transaction: another process may be at it too */
+  /** 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() === MIGRATIONS.length) return;
-    this.#db.exec('BEGIN IMMEDIATE');
-    try {
-      for (let v = version(); v < MIGRATIONS.length; v++) this.#db.exec(MIGRATIONS[v]);
-      this.#db.exec(`PRAGMA user_version = ${MIGRATIONS.length}`);
-      this.#db.exec('COMMIT');
-    } catch (e) {
-      this.#db.exec('ROLLBACK');
-      throw e;
-    }
+    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}`);
+    });
   }
 
   #q(sql) {
@@ -104,44 +114,45 @@ 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 whose account is not known are `account`'s */
+  claim(provider, account) {
+    this.#q('UPDATE sessions SET account=? WHERE provider=? AND account IS NULL').run(account, provider);
   }
 
-  /** The record of one provider's sessions, as a provider adapter reads it for its quota (providers/index.js) */
-  history(provider) {
+  /** The account's sessions that a quota reading shows, those that ended before `billedBefore` (ms); openSince() has the rest */
+  history(account, billedBefore) {
     return {
-      /** Session time (ms) of the sessions opened since `since` (ms) that have ended, each at most as long as it can have lasted */
+      /** 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(Date.now())).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 sessions of `provider` still open at `at` (ms): those open now, and those that have ended since.
-   * [{ durationMs }]: each as long as it lasted, or can last at most while it has no timing
-   */
-  openAfter(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 with one of `providers` whose provider's record has not been stored yet: [{ provider, id, openedAt, closedAt }] (ISO times) */
-  awaitingUsage(providers) {
-    return this.#q(
-      'SELECT provider, id, opened_at openedAt, closed_at closedAt FROM sessions WHERE synced_at IS NULL AND provider IN (SELECT value FROM json_each(?)) ORDER BY opened_at',
-    ).all(JSON.stringify(providers));
+  /** 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 */
   tx(fn) {
-    this.#db.exec('BEGIN');
+    this.#db.exec('BEGIN IMMEDIATE');
     try {
       const r = fn();
       this.#db.exec('COMMIT');
@@ -155,10 +166,10 @@ 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));
   }
 

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/providers/anchor.js

@@ -16,6 +16,7 @@ export const defaults = {
   // (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 },
   billingDelayMs: 5 * 60_000, // seen within 10 s
+  minIdleTimeoutSec: 60, // idle_timeout is in whole minutes, at least 1
 };
 
 const headers = (apiKey) => ({ 'anchor-api-key': apiKey });

package/src/providers/index.js

@@ -1,4 +1,4 @@
-import { checkPrice } from '../cost.js';
+import { fullPrice } from '../cost.js';
 import * as anchor from './anchor.js';
 import * as firecrawl from './firecrawl.js';
 import * as hyperbrowser from './hyperbrowser.js';
@@ -8,28 +8,22 @@ import * as steel from './steel.js';
 import * as tinyfish from './tinyfish.js';
 
 /**
- * Provider adapters, by provider name: the only provider-specific code. Each exports:
- *   defaults                 its settings; OneBrowser's `providers` option overrides them per provider (the API
- *                            key is not among them: each function gets it as its own argument):
- *       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 its cost, at the latest
- *       and its own          API base URLs, plan facts such as monthlyHours
- *   createSession(settings, apiKey, options) → { id, cdpUrl, egress }
- *       options: { proxyCountry, idleTimeoutSec, maxDurationMs } (OneBrowser.openSession), mapped onto the
- *       provider's own parameters. Throws on failure; QuotaError (errors.js) when the provider refuses the
- *       session because the account's quota is used up
- *   releaseSession(settings, apiKey, session)   ends the session; throws on failure
+ * Provider adapters by name: the only provider-specific code. Each exports:
+ *   defaults   its settings, which OneBrowser's `providers` option overrides:
+ *     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
+ *   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 record of those sessions that have ended: the provider's own, or, for a provider whose records the
- *       API key cannot read, the ledger's timing (closedAt is empty for a session no process closed); throws on
- *       failure
+ *       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 is left of the account's quota, in the provider's own unit (USD, credits, hours, …), and when it
- *       renews if it does by itself (ms); history: the ledger's record of the provider's sessions
- *       (Ledger.history). Throws when it cannot be read
- *
- * Their requests go through http.js, which turns every status other than 2xx into an HttpError: an adapter
- * handles only the statuses that mean something of their own.
+ *       what the account has left in the provider's unit, and when it renews by itself (ms); 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.
  */
 export const ADAPTERS = { tinyfish, steel, hyperbrowser, lightpanda, kernel, anchor, firecrawl };
 
@@ -41,12 +35,15 @@ export function checkAdapter(name, adapter) {
   if (missing.length) throw new Error(`provider ${name}: its adapter lacks ${missing.join(', ')}`);
 }
 
-/** Throws unless `settings` (an adapter's defaults with a program's settings on top) have a price and a billing delay */
-export function checkSettings(name, settings) {
+/** An adapter's settings with the defaults of those every adapter has; throws when one of them is missing or wrong */
+export function fullSettings(name, { price, billingDelayMs, minIdleTimeoutSec = 0, ...own }) {
+  const atLeast0 = (x) => Number.isFinite(x) && x >= 0;
   try {
-    checkPrice(settings.price);
+    const full = fullPrice(price);
+    if (!atLeast0(billingDelayMs)) throw new Error(`billingDelayMs must be a number ≥ 0, not ${billingDelayMs}`);
+    if (!atLeast0(minIdleTimeoutSec)) throw new Error(`minIdleTimeoutSec must be a number ≥ 0, not ${minIdleTimeoutSec}`);
+    return { ...own, price: full, billingDelayMs, minIdleTimeoutSec };
   } catch (e) {
     throw new Error(`provider ${name}: ${e.message}`);
   }
-  if (!(Number.isFinite(settings.billingDelayMs) && settings.billingDelayMs >= 0)) throw new Error(`provider ${name}: billingDelayMs must be a number ≥ 0, not ${settings.billingDelayMs}`);
 }