toolroll 0.9.104 → 0.9.105

package/dist/chat-delivery-state.js

@@ -1,4 +1,3 @@
-/** Durable chat receipts on the shared chat core: what each app's chats sent us and what we plan to send them. */
 import { randomBytes } from "node:crypto";
 import { CONFIRM_TTL_MS, LEAD_ASK_TTL_MS } from "./store.js";
 import { ChatCore, chatHash } from "./chat-core.js";
@@ -7,22 +6,15 @@ import { unsentPart } from "./chat-message-states.js";
 import { readChatPart, savedChatEventBody, savedChatPart } from "./contracts/chat-content.js";
 export { savedChatPart, chatHash };
 const DAY_MS = 86_400_000;
-/** One app's chats on the shared core (the same object Telegram's run on): its events, planned parts and their buttons. */
 export class ChatState extends ChatMessages {
     constructor(store, provider) {
         super(store, provider);
     }
-    /** Pair-time half kept for the settings pages: mint a code for this installation and return it (only its hash is kept). */
     pairing(installation, approver, generation, now = new Date()) {
         const code = randomBytes(16).toString("hex");
         this.savePairing({ hash: chatHash(code), installation, approver, generation, by: approver }, now);
         return code;
     }
-    /**
-     * Consume a code sent in a chat (the shared rules, chat-core.ts). The installation's notice cursor starts from now
-     * on its FIRST pairing; a later person joins the running cursor (their own history is fenced by their binding's
-     * creation time).
-     */
     pair(identity, hash, member, channel, now, event = null) {
         return this.store.transact(() => {
             const paired = this.consumePairing({ hash, installation: identity.installation, team: identity.team ?? identity.app, app: identity.app, member, channel, event }, now);
@@ -33,11 +25,9 @@ export class ChatState extends ChatMessages {
             return paired.binding;
         });
     }
-    /** The 60-second lease the Slack, Discord and Teams workers renew. */
     lease(installation, owner, now) {
         return this.acquire(installation, owner, 60_000, now).ok;
     }
-    /** Save a received event with its body (contracts/chat-content.ts), versioned. False: it was already here. */
     enqueue(event) {
         return Number(this.prepare(`INSERT OR IGNORE INTO chat_event (provider, id, installation, binding, kind, channel, member, ts, thread, payload, created)
       VALUES (:provider, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
@@ -53,26 +43,15 @@ export class ChatState extends ChatMessages {
     defer(event, problem, until) {
         this.prepare("UPDATE chat_event SET next_at = ?, problem = ? WHERE provider = :provider AND id = ? AND state = 'queued'").run(until.toISOString(), problem, event);
     }
-    /**
-     * Mark an event handled: done (or dropped). For a message this runs when its reply is planned, before any part is
-     * sent; so on these apps done does not mean the person has the reply. Ask `unsent()` in chat-message-states.ts for
-     * that. Dropped is final: an event dropped while its handler was still working (the chat was disconnected) is
-     * never written back to done.
-     */
     finish(event, dropped = false) {
         this.prepare("UPDATE chat_event SET state = ?, payload = '{}' WHERE provider = :provider AND id = ? AND state <> 'dropped'").run(dropped ? "dropped" : "done", event);
     }
-    /** Point an event at the binding its pairing made. */
     setEventBinding(event, binding) {
         this.prepare("UPDATE chat_event SET binding = ? WHERE provider = :provider AND id = ?").run(binding, event);
     }
     part(id) {
         return this.prepare("SELECT * FROM chat_part WHERE provider = :provider AND id = ?").get(id) ?? null;
     }
-    /**
-     * The reply to an event, part by part, with each part's buttons minted with it; the event is then handled. Planned
-     * once. A dropped event gets no reply: nothing is saved, no button is minted, and the answer is false.
-     */
     plan(event, parts, now) {
         return this.store.transact(() => {
             if (this.prepare("SELECT state FROM chat_event WHERE provider = :provider AND id = ?").get(event)?.["state"] === "dropped")
@@ -110,34 +89,27 @@ export class ChatState extends ChatMessages {
             return true;
         });
     }
-    /** A proposal card's buttons on its part: earlier ones on that part are spent. Yes and Cancel last ten minutes. */
     tokens(part, proposal, phases, now) {
         this.prepare("UPDATE chat_action SET consumed = ? WHERE provider = :provider AND part = ? AND consumed IS NULL").run(now.toISOString(), part);
         for (const phase of phases)
             this.prepare("INSERT INTO chat_action (provider, token, part, proposal, phase, created, expires) VALUES (:provider, ?, ?, ?, ?, ?, ?)").run(randomBytes(16).toString("hex"), part, proposal, phase, now.toISOString(), new Date(now.getTime() + (phase === "yes" || phase === "cancel" ? CONFIRM_TTL_MS : DAY_MS)).toISOString());
     }
-    /** A proposal card's live buttons on one part, in the order they were minted. */
     partTokens(part, now) {
         return this.prepare("SELECT token, phase FROM chat_action WHERE provider = :provider AND part = ? AND consumed IS NULL AND expires > ? ORDER BY rowid")
             .all(part, now.toISOString()).map(row => ({ token: String(row["token"]), phase: String(row["phase"]) }));
     }
-    // ---- sending, the same for every app's worker ----------------------------------------------------------------------
-    /** The next part to send for an installation: notices only while notifications may go out. */
     nextPart(installation, notices, now, order = "id") {
         return this.prepare(`SELECT p.* FROM chat_part p JOIN chat_event e ON e.provider = p.provider AND e.id = p.event
       WHERE p.provider = :provider AND e.installation = ? AND p.state = 'pending' AND (e.kind <> 'notice' OR ? = 1)
         AND (p.next_at IS NULL OR p.next_at <= ?) ORDER BY ${order === "created" ? "p.created, " : ""}p.id LIMIT 1`)
             .get(installation, notices ? 1 : 0, now.toISOString()) ?? null;
     }
-    /** A part that will not go: why, in words the saved chat shows. */
     dropPart(id, problem) {
         this.prepare("UPDATE chat_part SET state = 'dropped', next_at = NULL, problem = ? WHERE provider = :provider AND id = ?").run(problem, id);
     }
-    /** Try again no earlier than then (a screenshot waiting for its result's message). */
     holdPart(id, until) {
         this.prepare("UPDATE chat_part SET next_at = ? WHERE provider = :provider AND id = ?").run(until, id);
     }
-    /** The app's upload identity for a part's file, and whether its bytes are up. */
     setPartFile(id, file, uploaded, message) {
         if (message !== undefined)
             this.prepare("UPDATE chat_part SET message = ? WHERE provider = :provider AND id = ?").run(message, id);
@@ -146,10 +118,6 @@ export class ChatState extends ChatMessages {
         if (uploaded !== undefined)
             this.prepare("UPDATE chat_part SET uploaded = ? WHERE provider = :provider AND id = ?").run(uploaded ? 1 : 0, id);
     }
-    /**
-     * Sent: on the app's own message id when it gave one (an uploaded file may not). A card's decide buttons
-     * (chat-decide.ts) now ride that message, and any older ones on it stop working; a "What should change?" names it.
-     */
     partSent(id, message, now, attempt = true) {
         this.store.transact(() => {
             this.prepare(`UPDATE chat_part SET state = 'sent', message = COALESCE(?, message), attempts = attempts + ?, problem = NULL, next_at = NULL, sent = ?
@@ -162,7 +130,6 @@ export class ChatState extends ChatMessages {
                 return;
             const content = read.value, chat = content.channel ?? (row?.["own"] == null ? null : String(row["own"]));
             if (chat !== null) {
-                // What the message shows now is all that acts on it: buttons it no longer shows stop working.
                 const tokens = JSON.stringify((content.decide?.rows ?? []).flat().flatMap(one => "token" in one ? [one.token] : []));
                 this.prepare(`UPDATE chat_decide_action SET consumed_at = ? WHERE channel = :provider AND chat = ? AND message = ? AND consumed_at IS NULL
           AND token NOT IN (SELECT value FROM json_each(?))`).run(now.toISOString(), chat, placed, tokens);
@@ -173,43 +140,27 @@ export class ChatState extends ChatMessages {
                 this.prepare("UPDATE chat_decide_prompt SET message = ? WHERE channel = :provider AND id = ? AND message IS NULL").run(placed, content.prompt);
         });
     }
-    /**
-     * Not sent this time: counted, named, and (when the answer was lost rather than refused) counted as uncertain. The
-     * part stays pending. A failed send never drops it on any app: it goes when the app says it can never be sent, or
-     * when the chat is disconnected.
-     */
     partFailed(id, failure) {
         this.prepare("UPDATE chat_part SET attempts = attempts + 1, uncertain = uncertain + ?, next_at = ?, problem = ? WHERE provider = :provider AND id = ?")
             .run(failure.uncertain ? 1 : 0, failure.until, failure.problem, id);
     }
-    /** One person's replies still waiting to send, and those that could not be delivered (settings show both). */
     partCounts(binding) {
         const row = this.prepare(`SELECT SUM(${unsentPart("p")}) AS pending, SUM(p.state = 'dropped') AS dropped FROM chat_part p
       JOIN chat_event e ON e.provider = p.provider AND e.id = p.event WHERE p.provider = :provider AND e.binding = ?`).get(binding);
         return { pending: Number(row?.["pending"] ?? 0), dropped: Number(row?.["dropped"] ?? 0) };
     }
-    /**
-     * Replace a part's content and send it again (a repaint after a tap). A dropped part stays dropped: it was given up
-     * on, or its chat disconnected, and new content doesn't bring it back. False then, so the caller can say it another way.
-     */
     repaint(id, content) {
         return Number(this.prepare("UPDATE chat_part SET payload = ?, state = 'pending', next_at = NULL WHERE provider = :provider AND id = ? AND state <> 'dropped'")
             .run(savedChatPart(content), id).changes) === 1;
     }
 }
-/** A saved part's content. One that can't be read is a delivery problem that names the field, never a guess. */
 export function partContent(payload) {
     const read = readChatPart(payload);
     if (!read.ok)
         throw new ChatDeliveryError(`This saved message can't be read: ${read.issues.map(issue => issue.line).join("; ")}`, 0, false, true);
     return read.value;
 }
-/** The least time before a failed part is sent again, by how many times it has failed. The last step repeats. */
 export const CHAT_RETRY_STEPS_MS = [5000, 15000, 60000, 300000];
-/**
- * When a part that failed to send is tried again: after the app's own wait or the step for its count of failures,
- * whichever is longer. One rule for Slack, Discord and Teams.
- */
 export function chatRetryAt(now, retryMs, attempts) {
     const step = CHAT_RETRY_STEPS_MS[Math.min(Math.max(attempts, 0), CHAT_RETRY_STEPS_MS.length - 1)];
     return new Date(now.getTime() + Math.max(retryMs, step)).toISOString();