onebrowser 0.2.0 → 0.4.0

package/README.md

@@ -15,15 +15,16 @@ const page = await session.newPage(); // Playwright; or any CDP client on sessio
 await page.goto('https://example.com');
 await session.close();
 
-await browsers.quota('steel'); // { remaining, unit: 'USD', renewsAt: null }
+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 browsers.close();
 ```
 
-**What it does not do**: choose a provider, cap the sessions held at once, spread sessions over providers, or stop using a provider whose quota runs low. Those are policy, and belong to the program using it. onebrowser opens the session it is asked for, and tells the program what it needs to decide: the quota, and `QuotaError` when a provider refuses a session for the account's quota.
+**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.
 
-Built in: [Steel](https://steel.dev), [TinyFish](https://tinyfish.ai), [Hyperbrowser](https://hyperbrowser.ai), [Lightpanda](https://lightpanda.io), [Kernel](https://www.kernel.sh) and [Anchor Browser](https://anchorbrowser.io); a program can add its own (see [Adding a provider](#adding-a-provider)). Node 22.13 or later.
+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.
 
 ## Interface
 
@@ -33,7 +34,7 @@ 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`, 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`: `apiKey`, `price` and `billingDelayMs` (see [Quota](#quota)), and the adapter's own settings (API base URLs, plan facts such as `monthlyHours`) |
 | `adapters` | Further adapters by provider name, or replacements of built-in ones |
 
 | Method | |
@@ -41,12 +42,13 @@ Built in: [Steel](https://steel.dev), [TinyFish](https://tinyfish.ai), [Hyperbro
 | `providers` | Names of the providers it can open sessions with |
 | `checkReady(provider)` | Throws when the provider is unknown or has no API key |
 | `openSession({ provider, proxyCountry, idleTimeoutSec, maxDurationMs })` | A new session, recorded in the ledger once the provider has created it. Throws `QuotaError` when the provider refuses it for the account's quota |
-| `quota(provider)` | `{ remaining, unit, renewsAt }` in the provider's own unit; `renewsAt` (ms) when it renews by itself, `null` when only a top-up renews it. Throws when it cannot be read |
+| `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` |
 | `close()` | Closes the sessions still open and the ledger |
 
-A session (`openSession`) has `id`, `provider`, `egress`, `cdpUrl` (it may carry the API key: never log it), `openedAt`, `closedAt`, and:
+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:
 
 - `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.
@@ -74,17 +76,25 @@ How each provider meets them:
 | `lightpanda` | its datacenter pool in that country | at once: a session is its CDP connection | Lightpanda's own limit is 15 min |
 | `kernel` | not supported (throws) | `timeout_seconds` after the CDP client left; until then a disconnected session stays in standby, counting toward the plan's concurrent browsers | this process only |
 | `anchor` | residential proxy | `idle_timeout` after the last CDP connection left, in whole minutes rounded down (at least 1) | `max_duration`, in whole minutes |
+| `firecrawl` | its `location` in that country (default: the US) | `activityTtl` (no CDP commands), in whole seconds rounded down, at most 1 h | `ttl`, in whole seconds, at least 30 s and at most 1 h |
 
 ### Quota
 
-| Provider | Quota, unit | Read from |
-|---|---|---|
-| `steel` | balance, USD | `GET /v1/credits/balance`, the endpoint of Steel's dashboard (not in its API docs) |
-| `tinyfish` | wallet, USD | [`GET /v1/wallet`](https://docs.tinyfish.ai/wallet); a session refused with 402 throws `QuotaError` |
-| `hyperbrowser` | credits | `GET /api/team/credit-info`, the endpoint of Hyperbrowser's SDK (not in its API docs) |
-| `lightpanda` | browser hours of the calendar month (`monthlyHours`, default: the free plan's) | the ledger's record of its sessions: its console shows the month's usage, but its token cannot read it. So the reading is whole while the account is used only through ledgers of this machine |
-| `kernel` | browser hours of the calendar month (`monthlyHours`, default: what the free plan's credits pay for) | the uptime of the account's sessions this month, from `GET /browsers`; a session refused with 403 (spending cap) throws `QuotaError` |
-| `anchor` | credits | `GET /v1/billing`; a session refused with 402 throws `QuotaError` |
+`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.
+
+`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.
+
+| 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 |
+
+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
 
@@ -92,30 +102,30 @@ How each provider meets them:
 
 ### The ledger
 
-One SQLite file per machine by default: `$ONEBROWSER_DB`, else `onebrowser/sessions.db` in `$XDG_DATA_HOME` (default `~/.local/share`). Every program that uses onebrowser on the machine shares it, each under its own `client`, so the record of a provider account's sessions is whole whichever program opened them; several processes may write to it at once. Each session is recorded when its provider has created it (it is billed from then on, also when connecting fails afterwards), closed when released, and completed with the provider's own record by `syncUsage()` once it has ended.
+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.
 
 ## Command line
 
 The provider accounts and the ledger belong to the machine rather than to one program, so the `onebrowser` command reads them without a program of your own. It opens no sessions.
 
 ```sh
-npx onebrowser quota                 # what each provider account with an API key has left
+npx onebrowser quota                 # 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 usage --json --env-file .env
 ```
 
-`usage` first fetches the providers' records of the sessions that have ended, as `syncUsage()` does. With `--json`, `quota` prints an array of what `quota()` returns, with the provider: `{ provider, remaining, unit, renewsAt }`, or `{ provider, error }` for a failed reading; `usage` prints `{ ledger, since, sessions, failed }`, where `sessions` is what `usage()` returns and `failed` what `syncUsage()` could not fetch. API keys are read as by the library, from the environment (`--env-file PATH` loads a file into it first). Exit status: 0 done, 1 a reading failed, 2 the command line is wrong.
+`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.
 
 ## Adding a provider
 
 Write `src/providers/<name>.js` and register it in `ADAPTERS` (`src/providers/index.js`, where the contract is):
 
-- `defaults`: its settings (API base URLs, plan facts).
+- `defaults`: its settings: `price` and `billingDelayMs` (see [Quota](#quota)), and its own (API base URLs, plan facts).
 - `createSession(settings, apiKey, { proxyCountry, idleTimeoutSec, maxDurationMs }) → { id, cdpUrl, egress }`: maps the session options onto the provider's parameters; throws `QuotaError` when the provider refuses the session for the account's quota.
 - `releaseSession(settings, apiKey, session)`.
 - `sessionUsage(settings, apiKey, [{ id, openedAt, closedAt }]) → [{ id, durationMs, proxyBytes }]`: the record of those sessions that have ended: the provider's own, or the ledger's timing for a provider whose records its API key cannot read.
-- `quota(settings, apiKey, history) → { remaining, unit, renewsAt? }`: `history.sessionMsSince(ms)` is the ledger's record of the provider's sessions, for a provider that cannot report its own usage.
+- `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.
 
 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.
 
@@ -125,7 +135,7 @@ A program can also pass an adapter of its own in `adapters`, without changing on
 
 `npm test` runs offline: fake adapters and fetch, no network, no browser.
 
-A release is a tag: bump `version` in `package.json` and add its entry to [CHANGELOG.md](CHANGELOG.md), then push the tag `vX.Y.Z`. The release workflow checks the tag against the version, runs the tests and publishes to npm with trusted publishing (no token stored).
+A release is a tag: bump `version` in `package.json`, carry it into `package-lock.json` with `npm install --package-lock-only`, add its entry to [CHANGELOG.md](CHANGELOG.md), then push the tag `vX.Y.Z`. The release workflow checks the tag against the version, runs the tests and publishes to npm with trusted publishing (no token stored).
 
 ## License
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "onebrowser",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "One interface to remote browser providers: sessions by provider name, a usage ledger, account quotas",
-  "keywords": ["browser", "remote-browser", "cdp", "playwright", "steel", "hyperbrowser", "lightpanda", "kernel", "tinyfish", "anchorbrowser"],
+  "keywords": ["browser", "remote-browser", "cdp", "playwright", "steel", "hyperbrowser", "lightpanda", "kernel", "tinyfish", "anchorbrowser", "firecrawl"],
   "license": "MIT",
   "author": "Richard Wang",
   "repository": { "type": "git", "url": "git+https://github.com/i-richardwang/onebrowser.git" },

package/src/cli.js

@@ -6,6 +6,8 @@ const DAY_MS = 864e5;
 
 const day = (ms) => new Date(ms).toISOString().slice(0, 10);
 
+const round = (x) => Number(x.toFixed(2));
+
 /** The command line is wrong: exit status 2 */
 class CommandLineError extends Error {}
 
@@ -32,7 +34,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})` : `${Number(q.remaining.toFixed(2))} ${q.unit} left${q.renewsAt ? `, renews ${day(q.renewsAt)}` : ''}`;
+          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`);
         }
       }
@@ -66,7 +68,8 @@ 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; default: every provider with an API key
+  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
                                    included (default 30), after fetching the providers' records of ended sessions
 

package/src/cost.js

@@ -0,0 +1,20 @@
+/**
+ * A provider's price (its adapter's `price` setting, providers/index.js), 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.
+ */
+export function checkPrice(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)}`);
+}
+
+/** What a session that lasts durationMs costs at `price` */
+export function sessionCost({ perHour, perSession = 0, stepSec = 1, minSec = 0 }, durationMs) {
+  const billedSec = Math.max(minSec, Math.ceil(durationMs / 1000 / stepSec) * stepSec);
+  return perSession + (perHour * billedSec) / 3600;
+}

package/src/index.js

@@ -1,7 +1,8 @@
+import { sessionCost } from './cost.js';
 import { readApiKey } from './credentials.js';
 import { QuotaError } from './errors.js';
 import { defaultLedgerPath, Ledger } from './ledger.js';
-import { ADAPTERS, checkAdapter } from './providers/index.js';
+import { ADAPTERS, checkAdapter, checkSettings } from './providers/index.js';
 import { KEEP_ALIVE_MS, Session } from './session.js';
 
 export { apiKeyEnv } from './credentials.js';
@@ -33,11 +34,22 @@ export function sessionOptions(options = {}) {
   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.
+ *
  * 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.
  *
@@ -53,6 +65,7 @@ export class OneBrowser {
   #providers = new Map(); // name → { adapter, settings: its defaults with the given ones on top, apiKey: the one given }
   #ledger = null;
   #open = new Set();
+  #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');
@@ -60,8 +73,10 @@ export class OneBrowser {
     this.ledgerPath = ledgerPath;
     for (const [name, adapter] of Object.entries({ ...ADAPTERS, ...adapters })) {
       checkAdapter(name, adapter);
-      const { apiKey, ...settings } = providers[name] ?? {};
-      this.#providers.set(name, { adapter, settings: { ...adapter.defaults, ...settings }, apiKey });
+      const { 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));
     if (unknown.length) throw new Error(`onebrowser: no adapter for provider ${unknown.join(', ')}`);
@@ -76,10 +91,16 @@ export class OneBrowser {
     return (this.#ledger ??= new Ledger(this.ledgerPath));
   }
 
-  /** The adapter, settings and API key of `provider`; throws when it is unknown or has no API key */
-  #ready(provider) {
+  /** 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) };
   }
 
@@ -96,6 +117,7 @@ export class OneBrowser {
   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);
@@ -104,7 +126,7 @@ export class OneBrowser {
       throw new Error(`failed to create a ${provider} session: ${e.message}`);
     }
     const session = new Session({
-      provider, remote, maxDurationMs: o.maxDurationMs,
+      provider, remote, openedAt, maxDurationMs: o.maxDurationMs,
       release: async (s) => {
         this.#open.delete(s);
         this.#store.closed(s);
@@ -112,7 +134,7 @@ export class OneBrowser {
       },
     });
     try {
-      this.#store.opened({ provider, id: session.id, client: this.client, openedAt: session.openedAt });
+      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;
@@ -122,14 +144,53 @@ export class OneBrowser {
   }
 
   /**
-   * What is left of the account's quota with `provider`: { remaining, unit, renewsAt } in the provider's own
-   * unit; renewsAt (ms) when it renews by itself, null when only a top-up renews it. Throws when it cannot be read.
+   * 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.
+   */
+  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 };
+  }
+
+  /**
+   * 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.
    */
-  async quota(provider) {
+  #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 q = await adapter.quota(settings, apiKey, this.#store.history(provider));
-    if (!(Number.isFinite(q?.remaining) && typeof q.unit === 'string')) throw new Error(`${provider} answered no quota: ${JSON.stringify(q)}`);
-    return { remaining: q.remaining, unit: q.unit, renewsAt: q.renewsAt ?? null };
+    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;
+  }
+
+  /**
+   * 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)));
   }
 
   /**

package/src/ledger.js

@@ -15,27 +15,59 @@ export function defaultLedgerPath() {
 }
 
 /**
- * sessions   every remote browser session: recorded when its provider has created it (it is billed from then on,
- *            even if connecting fails), closed when released, and completed with the provider's own record
- *            (duration, proxy traffic) once the session has ended and syncUsage has fetched it
+ * 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 SCHEMA = `
-CREATE TABLE IF NOT EXISTS sessions (
+const SESSIONS = `
+CREATE TABLE sessions (
   provider      TEXT NOT NULL,
   id            TEXT NOT NULL,            -- the session id its provider gave it
   client        TEXT NOT NULL,            -- the program that opened it (OneBrowser's client)
-  opened_at     TEXT NOT NULL,            -- when the provider created it
+  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
   duration_ms   INTEGER,                  -- the provider's record, once the session has ended
   proxy_bytes   INTEGER,                  -- proxy traffic in the provider's record
   synced_at     TEXT,                     -- when the provider's record was stored; empty = not yet
   PRIMARY KEY (provider, id)
 );
-CREATE INDEX IF NOT EXISTS idx_sessions_opened ON sessions(provider, opened_at);
+CREATE INDEX idx_sessions_opened ON sessions(provider, opened_at);
 `;
 
-/** Duration of a session: the provider's record, else the open-to-close timing of the process that opened it */
-const SESSION_MS = 'COALESCE(duration_ms, CAST((julianday(closed_at) - julianday(opened_at)) * 86400000 AS INTEGER))';
+/**
+ * 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.
+ */
+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;`,
+];
+
+/** ms from one ISO time to another */
+const msBetween = (from, to) => `CAST(ROUND((julianday(${to}) - julianday(${from})) * 86400000) AS INTEGER)`;
+
+/** How long a session lasted: the provider's record, else the open-to-close timing of the process that opened it */
+const SESSION_MS = `COALESCE(duration_ms, ${msBetween('opened_at', 'closed_at')})`;
+
+/** How long a session lasts at most: as SESSION_MS, or until it ends at the latest while it has no timing */
+const SESSION_MS_AT_MOST = `COALESCE(${SESSION_MS}, ${msBetween('opened_at', 'ends_by')})`;
+
+/** When a session has ended or ends at the latest */
+const ENDED_AT = 'COALESCE(closed_at, ends_by)';
 
 const iso = (ms) => new Date(ms).toISOString();
 const int = (x) => (x === null || x === undefined || !Number.isFinite(Number(x)) ? null : Math.trunc(Number(x)));
@@ -48,7 +80,22 @@ export class Ledger {
     if (file !== ':memory:') fs.mkdirSync(path.dirname(file), { recursive: true });
     this.#db = new DatabaseSync(file);
     this.#db.exec('PRAGMA journal_mode=WAL; PRAGMA busy_timeout=5000;'); // several processes share it
-    this.#db.exec(SCHEMA);
+    this.#migrate();
+  }
+
+  /** Takes the steps of MIGRATIONS the ledger has not taken, in one transaction: another process may be at 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;
+    }
   }
 
   #q(sql) {
@@ -57,8 +104,8 @@ export class Ledger {
     return s;
   }
 
-  opened({ provider, id, client, openedAt }) {
-    this.#q('INSERT INTO sessions (provider, id, client, opened_at) VALUES (?,?,?,?)').run(provider, id, client, iso(openedAt));
+  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));
   }
 
   closed({ provider, id, closedAt }) {
@@ -68,11 +115,20 @@ export class Ledger {
   /** The record of one provider's sessions, as a provider adapter reads it for its quota (providers/index.js) */
   history(provider) {
     return {
-      /** Session time (ms) of the sessions opened since `since` (ms) that have a duration */
-      sessionMsSince: (since) => this.#q(`SELECT COALESCE(SUM(${SESSION_MS}), 0) ms FROM sessions WHERE provider=? AND opened_at >= ?`).get(provider, iso(since)).ms,
+      /** Session time (ms) of the sessions opened since `since` (ms) that have ended, each at most as long as it can have lasted */
+      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,
     };
   }
 
+  /**
+   * 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));
+  }
+
   /** 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(

package/src/providers/anchor.js

@@ -12,6 +12,10 @@ import { json } from './http.js';
  */
 export const defaults = {
   apiBase: 'https://api.anchorbrowser.io/v1',
+  // 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 },
+  billingDelayMs: 5 * 60_000, // seen within 10 s
 };
 
 const headers = (apiKey) => ({ 'anchor-api-key': apiKey });

package/src/providers/firecrawl.js

@@ -0,0 +1,61 @@
+import { QuotaError } from '../errors.js';
+import { json } from './http.js';
+
+/**
+ * Firecrawl's Browser Sandbox (https://docs.firecrawl.dev/features/browser). A session browses from a US ISP IP
+ * by default, a different one per session; proxyCountry selects Firecrawl's location in that country (location).
+ * Closing the CDP connection does not end a session: Firecrawl ends it idleTimeoutSec after its last CDP command
+ * (activityTtl), and maxDurationMs after it was created in any case (ttl), both in whole seconds and at most 1 h.
+ * activityTtl is rounded down and ttl cut to 1 h, so that neither ends a session later than asked; ttl is rounded
+ * up, to at least 30 s, as this process closes the session at maxDurationMs. Its live view stream and its ad
+ * blocking, both on by default, are turned off. Sessions are paid from the account's credits; with too few,
+ * creating one answers 402.
+ */
+export const defaults = {
+  apiBase: 'https://api.firecrawl.dev/v2',
+  price: { perHour: 120, stepSec: 30, minSec: 60 }, // credits: 2 a minute, in whole credits rounded up, at least 1 minute
+  billingDelayMs: 5 * 60_000, // seen within 10 s
+};
+
+const TTL_SEC = { min: 30, max: 3600 }; // what Firecrawl takes for ttl; activityTtl has the same maximum
+
+const headers = (apiKey) => ({ Authorization: `Bearer ${apiKey}` });
+
+export async function createSession(settings, apiKey, { proxyCountry, idleTimeoutSec, maxDurationMs }) {
+  const body = {
+    ttl: Math.min(TTL_SEC.max, Math.max(TTL_SEC.min, Math.ceil(maxDurationMs / 1000))),
+    activityTtl: Math.min(TTL_SEC.max, Math.floor(idleTimeoutSec)),
+    streamWebView: false,
+    blockAds: false,
+  };
+  if (proxyCountry) body.location = { country: proxyCountry };
+  let s;
+  try {
+    s = await json(`${settings.apiBase}/interact`, { method: 'POST', headers: headers(apiKey), body, timeoutMs: 90_000 });
+  } catch (e) {
+    if (e.status === 402) throw new QuotaError(`credits used up: ${e.text}`);
+    throw e;
+  }
+  return { id: s.id, cdpUrl: s.cdpUrl, egress: `proxy ${proxyCountry ?? 'US'}` };
+}
+
+/** Succeeds also for a session that has already ended */
+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 */
+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 };
+}
+
+/** 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) */
+export async function sessionUsage(settings, apiKey, sessions) {
+  const usage = [];
+  for (const { id } of sessions) {
+    const s = await json(`${settings.apiBase}/interact/${id}`, { headers: headers(apiKey) });
+    if (s.status !== 'running') usage.push({ id, durationMs: s.sessionDurationMs, proxyBytes: null });
+  }
+  return usage;
+}

package/src/providers/hyperbrowser.js

@@ -9,6 +9,8 @@ import { json } from './http.js';
  */
 export const defaults = {
   apiBase: 'https://api.hyperbrowser.ai/api',
+  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
 };
 
 const headers = (apiKey) => ({ 'x-api-key': apiKey });

package/src/providers/index.js

@@ -1,4 +1,6 @@
+import { checkPrice } from '../cost.js';
 import * as anchor from './anchor.js';
+import * as firecrawl from './firecrawl.js';
 import * as hyperbrowser from './hyperbrowser.js';
 import * as kernel from './kernel.js';
 import * as lightpanda from './lightpanda.js';
@@ -7,9 +9,11 @@ import * as tinyfish from './tinyfish.js';
 
 /**
  * Provider adapters, by provider name: the only provider-specific code. Each exports:
- *   defaults                 its settings (API base URLs, plan facts such as monthlyHours); OneBrowser's
- *                            `providers` option overrides them per provider. The API key is not among them:
- *                            each function gets it as its own argument
+ *   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
@@ -27,7 +31,7 @@ import * as tinyfish from './tinyfish.js';
  * Their requests go through http.js, which turns every status other than 2xx into an HttpError: an adapter
  * handles only the statuses that mean something of their own.
  */
-export const ADAPTERS = { tinyfish, steel, hyperbrowser, lightpanda, kernel, anchor };
+export const ADAPTERS = { tinyfish, steel, hyperbrowser, lightpanda, kernel, anchor, firecrawl };
 
 const CONTRACT = ['createSession', 'releaseSession', 'sessionUsage', 'quota'];
 
@@ -36,3 +40,13 @@ export function checkAdapter(name, adapter) {
   const missing = CONTRACT.filter((f) => typeof adapter?.[f] !== 'function');
   if (missing.length) throw new Error(`provider ${name}: its adapter lacks ${missing.join(', ')}`);
 }
+
+/** 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) {
+  try {
+    checkPrice(settings.price);
+  } 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}`);
+}

package/src/providers/kernel.js

@@ -14,6 +14,8 @@ 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
+  price: { perHour: 1 }, // the quota is in headless browser hours, billed by the second
+  billingDelayMs: 5 * 60_000, // seen within 10 s
 };
 
 const headers = (apiKey) => ({ Authorization: `Bearer ${apiKey}` });
@@ -42,8 +44,8 @@ export async function releaseSession(settings, apiKey, session) {
 /**
  * Browser hours left of the month's monthlyHours, after the uptime of every session of the account this month:
  * Kernel's own records, which include sessions opened by any program. The sessions are listed newest first, so
- * the listing stops at a page that holds none of this month. The hours are assumed to renew with each calendar
- * month (UTC).
+ * the listing stops at a page that holds none of this month. Kernel counts usage from the first of each month,
+ * 00:00 UTC (https://www.kernel.sh/docs/info/spending-caps), and has no API that reads what its credits leave.
  */
 export async function quota(settings, apiKey) {
   const month = utcMonth();

package/src/providers/lightpanda.js

@@ -13,6 +13,8 @@ const MAX_CONNECTION_MS = 15 * 60_000;
 export const defaults = {
   connectBase: 'wss://euwest.cloud.lightpanda.io/ws',
   monthlyHours: 10, // browser hours a month on the free plan
+  price: { perHour: 1 }, // the quota is in browser hours, billed by the second
+  billingDelayMs: 0, // the quota is the ledger's record
 };
 
 export async function createSession(settings, apiKey, { proxyCountry }) {
@@ -30,13 +32,13 @@ export async function releaseSession() {}
 
 /**
  * Browser hours left of the month's monthlyHours. Lightpanda's console shows the month's usage, but the token
- * cannot read it: the month's usage is the ledger's record of the sessions (history), which is all of it while
- * the account is used through ledgers of this machine only. The hours are assumed to renew with each calendar
- * month (UTC).
+ * cannot read it: the month's usage is the ledger's record of the sessions that have ended (history), which is
+ * all of it while the account is used through ledgers of this machine only. The hours are assumed to renew with
+ * each calendar month (UTC).
  */
 export async function quota(settings, apiKey, history) {
   const month = utcMonth();
-  const usedHours = history.sessionMsSince(month.start) / 3_600_000;
+  const usedHours = history.endedSessionMsSince(month.start) / 3_600_000;
   return { remaining: settings.monthlyHours - usedHours, unit: 'hours', renewsAt: month.next };
 }
 

package/src/providers/steel.js

@@ -8,6 +8,8 @@ import { json } from './http.js';
 export const defaults = {
   apiBase: 'https://api.steel.dev/v1',
   connectBase: 'wss://connect.steel.dev',
+  price: { perHour: 0.1, stepSec: 60 }, // USD on the Launch plan, by the minute rounded up
+  billingDelayMs: 5 * 60_000, // seen within 11 s
 };
 
 const headers = (apiKey) => ({ 'steel-api-key': apiKey });

package/src/providers/tinyfish.js

@@ -10,6 +10,8 @@ import { json } from './http.js';
 export const defaults = {
   apiBase: 'https://api.browser.tinyfish.ai',
   walletUrl: 'https://agent.tinyfish.ai/v1/wallet',
+  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
 };
 
 const headers = (apiKey) => ({ 'X-API-Key': apiKey });

package/src/session.js

@@ -16,7 +16,8 @@ const firstLine = (e) => String(e.message).split('\n')[0];
  *
  *   id, provider, egress     the provider's session id, its name, and the egress the session uses
  *   cdpUrl                   CDP WebSocket URL (it may carry the API key: never log it)
- *   openedAt, closedAt       ms; closedAt is null while open
+ *   openedAt, closedAt       ms: when it was asked for (its provider created it right after), when it was
+ *                            closed; closedAt is null while open
  */
 export class Session {
   #release;
@@ -25,15 +26,15 @@ export class Session {
   #deadline;
 
   /** release(session): records the session closed and releases it at its provider (OneBrowser) */
-  constructor({ provider, remote, maxDurationMs, release }) {
+  constructor({ provider, remote, openedAt, maxDurationMs, release }) {
     this.provider = provider;
     this.id = remote.id;
     this.egress = remote.egress;
     this.cdpUrl = remote.cdpUrl;
-    this.openedAt = Date.now();
+    this.openedAt = openedAt;
     this.closedAt = null;
     this.#release = release;
-    this.#deadline = setTimeout(() => this.close().catch(() => {}), maxDurationMs); // a release that fails here leaves the session to the provider's idle timeout
+    this.#deadline = setTimeout(() => this.close().catch(() => {}), openedAt + maxDurationMs - Date.now()); // a release that fails here leaves the session to the provider's idle timeout
     this.#deadline.unref();
   }