onebrowser 0.6.0 → 0.7.0

package/README.md

@@ -45,6 +45,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:
@@ -112,7 +114,7 @@ An account is known by its `id`, the provider's name and the first 6 hex digits
 
 ### 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: `$ONEBROWSER_DB`, else `onebrowser/sessions.db` in `$XDG_DATA_HOME` (default `~/.local/share`), shared by every program on the machine under its own `client`. A session is recorded when its provider has created it (it is billed from then on), with its account and when it ends at the latest; closed when its provider has released it; and completed with the provider's own record by `syncUsage()`. Nothing removes a session from the ledger, so its record is whole from the ledger's first session on. Each ledger has an id of its own (`ledgerId`), given when it is made (or first opened by onebrowser 0.7 or later) and kept for its life. A ledger made by an earlier onebrowser is brought up to date when opened; one made by a later onebrowser is refused. Sessions recorded by onebrowser 0.5 or earlier have no account: they become the provider's only account's when it has one here, and stay without one while it has several.
 
 ## Command line
 
@@ -125,7 +127,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 }`, or `{ account, provider, error }` for a failed reading; `usage` prints `{ ledger, ledgerId, since, sessions, failed }`, where `sessions` is what `usage()` returns and `failed` what `syncUsage()` could not fetch. API keys are read as by the library, from the environment (`--env-file PATH` loads a file into it first). Exit status: 0 done, 1 a reading failed, 2 the command line is wrong.
 
 ## Adding a provider
 

package/package.json

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

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`);
@@ -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');

package/src/index.js

@@ -42,10 +42,7 @@ export class OneBrowser {
     }
   }
 
-  /**
-   * 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 +53,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 +98,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.js

@@ -1,6 +1,7 @@
 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';
 
 /**
@@ -18,8 +19,8 @@ export function defaultLedgerPath() {
 const SCHEMA = `
 CREATE TABLE sessions (
   provider      TEXT NOT NULL,
-  account       TEXT,                     -- the account it is billed to (Account.id); empty when 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 +66,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 +104,29 @@ export class Ledger {
   /** Makes the ledger, or brings an earlier one up to date, in one transaction: another process may be opening it too */
   #migrate() {
     const version = () => this.#db.prepare('PRAGMA user_version').get().user_version;
-    if (version() === VERSION) return;
-    this.tx(() => {
-      if (!this.#db.prepare("SELECT 1 FROM sqlite_schema WHERE type = 'table' AND name = 'sessions'").get()) this.#db.exec(SCHEMA);
-      else {
-        const from = version() || 1;
-        if (from > VERSION) throw new Error(`onebrowser: the ledger ${this.#file} was made by a later onebrowser (schema ${from}; this one knows ${VERSION})`);
-        for (let v = from; v < VERSION; v++) this.#db.exec(UPGRADES[v]);
-      }
-      this.#db.exec(`PRAGMA user_version = ${VERSION}`);
-    });
+    const has = (table) => this.#db.prepare("SELECT 1 FROM sqlite_schema WHERE type = 'table' AND name = ?").get(table);
+    if (version() !== VERSION) {
+      this.tx(() => {
+        if (!has('sessions')) this.#db.exec(SCHEMA);
+        else {
+          const from = version() || 1;
+          if (from > VERSION) throw new Error(`onebrowser: the ledger ${this.#file} was made by a later onebrowser (schema ${from}; this one knows ${VERSION})`);
+          for (let v = from; v < VERSION; v++) this.#db.exec(UPGRADES[v]);
+        }
+        this.#db.exec(`PRAGMA user_version = ${VERSION}`);
+      });
+    }
+    if (!has('meta')) {
+      this.tx(() => {
+        this.#db.exec(META);
+        this.#db.prepare("INSERT OR IGNORE INTO meta (key, value) VALUES ('id', ?)").run(randomUUID());
+      });
+    }
+  }
+
+  /** This ledger's id, given when it was made or first opened by a onebrowser that has ids, and kept for life */
+  get id() {
+    return this.#q("SELECT value FROM meta WHERE key = 'id'").get().value;
   }
 
   #q(sql) {
@@ -122,7 +143,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 +194,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();
   }