toolroll 0.9.103 → 0.9.105

package/dist/chat-core.js

@@ -1,14 +1,4 @@
-/**
- * The chat core every app shares (Telegram, Slack, Discord, Teams): who is paired, the one-time codes that pair
- * them, the rooms they follow, one live worker per installation, and the small facts a transport remembers. One
- * object is bound to one provider, and every query it runs names that provider (`:provider`), so an id or a member
- * from one app never reaches another app's rows. Adapters keep only their transport: sign-in, receiving (webhooks or
- * polling), formatting and sending.
- *
- * Imports the store's types only, so the store can build its Telegram methods on it.
- */
 import { createHash } from "node:crypto";
-/** The result a waiting event is dropped with when its chat is disconnected (kept only when it had none). */
 const REVOKED = "revoked";
 export const chatHash = (text) => createHash("sha256").update(text).digest("hex");
 export const PAIRING_CODE_TTL_MS = 10 * 60_000;
@@ -35,7 +25,6 @@ export class ChatCore {
     get db() {
         return this.store.handle;
     }
-    /** A statement bound to this provider. Its SQL must name `:provider`; one that doesn't is refused before it runs. */
     prepare(sql) {
         if (!/:provider\b/.test(sql))
             throw new Error(`a chat query must name its provider: ${sql.slice(0, 80)}`);
@@ -46,42 +35,33 @@ export class ChatCore {
             all: (...params) => statement.all(bound, ...params),
         };
     }
-    /** The next number in this provider's run of a table (rows keep the numbers they were given). */
     nextId(table) {
         return Number(this.prepare(`SELECT COALESCE(MAX(id), 0) + 1 AS n FROM ${table} WHERE provider = :provider`).get()?.["n"] ?? 1);
     }
-    // ---- pairings ---------------------------------------------------------------------------------------------------
-    /** Every unrevoked binding of an installation, oldest first (liveness is checked per binding with `live`). */
     bindings(installation) {
         return this.prepare("SELECT * FROM chat_binding WHERE provider = :provider AND installation = ? AND revoked IS NULL ORDER BY id")
             .all(installation).map(readChatBinding);
     }
-    /** The unrevoked binding one member holds, if any. */
     bindingFor(installation, member) {
         const row = this.prepare("SELECT * FROM chat_binding WHERE provider = :provider AND installation = ? AND member = ? AND revoked IS NULL").get(installation, member);
         return row === undefined ? null : readChatBinding(row);
     }
-    /** The exact binding, while unrevoked. */
     bindingById(id) {
         const row = this.prepare("SELECT * FROM chat_binding WHERE provider = :provider AND id = ? AND revoked IS NULL").get(id);
         return row === undefined ? null : readChatBinding(row);
     }
-    /** The oldest unrevoked binding: the single-person reading kept for status lines and fixtures. */
     binding(installation) {
         return this.bindings(installation)[0] ?? null;
     }
-    /** Unrevoked, and its person still an approver, unrevoked, at the generation it was paired under. */
     live(binding) {
         const current = this.bindingById(binding.id);
         const account = this.store.accountOf(binding.approver);
         return current !== null && current.approver === binding.approver && current.generation === binding.generation &&
             account?.role === "approver" && account.revokedAt === null && account.generation === binding.generation;
     }
-    /** Every live binding of an installation, oldest first. */
     liveBindings(installation) {
         return this.bindings(installation).filter(binding => this.live(binding));
     }
-    /** Mint-time half of pairing: a fresh code replaces this person's outstanding ones (a teammate's stay theirs). */
     savePairing(code, now, ttlMs = PAIRING_CODE_TTL_MS) {
         this.store.transact(() => {
             this.prepare("UPDATE chat_pair SET consumed = ? WHERE provider = :provider AND approver = ? AND consumed IS NULL").run(now.toISOString(), code.approver);
@@ -89,14 +69,6 @@ export class ChatCore {
                 .run(code.hash, code.installation, code.approver, code.generation, now.toISOString(), code.by, new Date(now.getTime() + ttlMs).toISOString());
         });
     }
-    /**
-     * Consume a code and create the binding, in one transaction, by the same rules in every app: the code is unexpired,
-     * unconsumed and for this installation; its person is still an approver at the generation it was minted under; the
-     * member holds no other live pairing here, and the person no other live pairing on this installation. The
-     * conditional UPDATE is the consumption: exactly one caller wins however many race. The same event replayed (an app
-     * redelivering) finds its finished binding. Success retires the person's other outstanding codes. `first`: the
-     * member never paired with this installation before (a first pairing starts its notifications from now).
-     */
     consumePairing(attempt, now) {
         return this.store.transact(() => {
             const stamp = now.toISOString();
@@ -133,7 +105,6 @@ export class ChatCore {
             return { ok: true, binding: this.bindingById(id), replay: false, first };
         });
     }
-    /** End one person's pairing and everything their chat could still do: its buttons, prompts, queued messages and unsent parts. */
     revokeBinding(binding, now = new Date(), by = null) {
         return this.store.transact(() => {
             const stamp = now.toISOString();
@@ -149,7 +120,6 @@ export class ChatCore {
             return revoked;
         });
     }
-    /** End every pairing of an installation (its app was disconnected), and every code still waiting for one. */
     revoke(installation, now = new Date(), by = null) {
         this.store.transact(() => {
             for (const binding of this.bindings(installation))
@@ -160,7 +130,6 @@ export class ChatCore {
         AND event IN (SELECT id FROM chat_event WHERE provider = :provider AND installation = ?)`).run(installation);
         });
     }
-    // ---- rooms (team conversations) ---------------------------------------------------------------------------------
     room(installation, chat) {
         const row = this.prepare("SELECT * FROM chat_room WHERE provider = :provider AND installation = ? AND chat = ? AND revoked IS NULL").get(installation, chat);
         return row === undefined ? null : readRoom(row);
@@ -168,11 +137,6 @@ export class ChatCore {
     rooms(installation) {
         return this.prepare("SELECT * FROM chat_room WHERE provider = :provider AND installation = ? AND revoked IS NULL ORDER BY id").all(installation).map(readRoom);
     }
-    /**
-     * Point a chat at a team conversation: an earlier choice for the same chat is revoked in the same transaction, and
-     * delivery starts from now (the conversation's history is read in the console, never replayed into a chat that
-     * just arrived). A conversation another group of this app already follows refuses.
-     */
     bindRoom(args, now) {
         return this.store.transact(() => this.store.savepoint(() => {
             const stamp = now.toISOString();
@@ -194,11 +158,9 @@ export class ChatCore {
     unbindRoom(installation, chat, by, now) {
         return Number(this.prepare("UPDATE chat_room SET revoked = ?, revoked_by = ? WHERE provider = :provider AND installation = ? AND chat = ? AND revoked IS NULL").run(now.toISOString(), by, installation, chat).changes) > 0;
     }
-    /** Forward only: a cursor never moves back, and a revoked room keeps its last position. */
     advanceRoomCursor(id, messageId) {
         return Number(this.prepare("UPDATE chat_room SET cursor = ? WHERE provider = :provider AND id = ? AND cursor < ? AND revoked IS NULL").run(messageId, id, messageId).changes) > 0;
     }
-    /** The shared rooms engine's view of this installation's rooms (chat-rooms.ts). */
     roomBackend(installation, now) {
         const roomOf = (room) => room === null ? null : { id: room.id, chatId: room.chat, kind: room.kind, conversation: room.conversation, boundBy: room.boundBy, binding: room.binding, cursor: room.cursor };
         return {
@@ -211,11 +173,6 @@ export class ChatCore {
             grant: id => { const binding = this.bindingById(id); return binding === null || !this.live(binding) ? null : { approver: binding.approver, generation: binding.generation, chatId: binding.channel }; },
         };
     }
-    // ---- the worker -------------------------------------------------------------------------------------------------
-    /**
-     * Take or renew the installation's one worker lease. A holder renews at its generation; an expired holder is taken
-     * over at the next generation, and the poll cursor rides the lease, so a stale generation can neither poll nor move it.
-     */
     acquire(installation, owner, ttlMs, now) {
         return this.store.transact(() => {
             const stamp = now.toISOString(), until = new Date(now.getTime() + ttlMs).toISOString();
@@ -232,45 +189,36 @@ export class ChatCore {
             return { ok: true, generation, cursor: Number(row["cursor"]) };
         });
     }
-    /** Hand the lease back (it ends now), so the next worker is not told busy for the rest of its time. */
     release(installation, owner, now) {
         this.prepare("UPDATE chat_runtime SET lease_until = ? WHERE provider = :provider AND installation = ? AND owner = ?").run(now.toISOString(), installation, owner);
     }
     owns(installation, owner, now = new Date()) {
         return this.prepare("SELECT 1 AS hit FROM chat_runtime WHERE provider = :provider AND installation = ? AND owner = ? AND lease_until > ?").get(installation, owner, now.toISOString()) !== undefined;
     }
-    /** The poll cursor moves forward only, and only under the generation that read it. */
     advanceCursor(installation, owner, generation, cursor, now) {
         return Number(this.prepare(`UPDATE chat_runtime SET cursor = ?, heartbeat = ? WHERE provider = :provider AND installation = ? AND owner = ? AND generation = ? AND cursor < ?`)
             .run(cursor, now.toISOString(), installation, owner, generation, cursor).changes) > 0;
     }
-    /** When the app said to wait (a rate limit): "" when it hasn't. */
     retryAt(installation) {
         return String(this.prepare("SELECT retry_at FROM chat_runtime WHERE provider = :provider AND installation = ?").get(installation)?.["retry_at"] ?? "");
     }
-    /** Wait at least until then before the next send; a later wait already asked for stands. */
     deferUntil(installation, until) {
         this.prepare(`INSERT INTO chat_runtime (provider, installation, retry_at) VALUES (:provider, ?, ?)
       ON CONFLICT (provider, installation) DO UPDATE SET retry_at = CASE WHEN retry_at IS NULL OR retry_at < excluded.retry_at THEN excluded.retry_at ELSE retry_at END`).run(installation, until);
     }
-    /** What is wrong with the connection right now (null: nothing), as the lease holder last saw it. */
     setProblem(installation, owner, problem) {
         this.prepare("UPDATE chat_runtime SET problem = ? WHERE provider = :provider AND installation = ? AND owner = ?").run(problem, installation, owner);
     }
-    /** The worker reached the app. */
     setConnected(installation, owner, now) {
         this.prepare("UPDATE chat_runtime SET connected = ?, problem = NULL WHERE provider = :provider AND installation = ? AND owner = ?").run(now.toISOString(), installation, owner);
     }
-    /** The worker stopped: no holder, no connection. */
     stop(installation, owner) {
         this.prepare("UPDATE chat_runtime SET owner = NULL, lease_until = NULL, connected = NULL WHERE provider = :provider AND installation = ? AND owner = ?").run(installation, owner);
     }
-    /** The connection as settings show it. */
     runtime(installation) {
         const row = this.prepare("SELECT connected, problem, lease_until FROM chat_runtime WHERE provider = :provider AND installation = ?").get(installation);
         return row === undefined ? null : { connected: str(row["connected"]), problem: str(row["problem"]), leaseUntil: str(row["lease_until"]) };
     }
-    /** Where the app pushes this installation's updates (null: the worker asks for them), and what's wrong, if anything. */
     setPush(installation, push, now) {
         this.prepare("UPDATE chat_runtime SET push_url = ?, push_problem = ?, push_at = ? WHERE provider = :provider AND installation = ?").run(push.url, push.problem, now.toISOString(), installation);
     }
@@ -278,12 +226,9 @@ export class ChatCore {
         const row = this.prepare("SELECT push_url, push_problem, push_at, owner FROM chat_runtime WHERE provider = :provider AND installation = ?").get(installation);
         return row === undefined || row["owner"] === null && row["push_at"] === null ? null : { url: str(row["push_url"]), problem: str(row["push_problem"]), at: str(row["push_at"]) };
     }
-    // ---- small facts ------------------------------------------------------------------------------------------------
-    /** Small transport facts an app must remember per chat (a Teams service URL). Never credentials. */
     meta(installation, key) {
         return str(this.prepare("SELECT value FROM chat_meta WHERE provider = :provider AND installation = ? AND key = ?").get(installation, key)?.["value"]);
     }
-    /** Every small fact whose key starts with this prefix (a fixed, LIKE-safe word). */
     metaStartingWith(installation, prefix) {
         return this.prepare("SELECT key, value FROM chat_meta WHERE provider = :provider AND installation = ? AND substr(key, 1, ?) = ? ORDER BY key")
             .all(installation, prefix.length, prefix).map(row => ({ key: String(row["key"]), value: String(row["value"]) }));