toolroll 0.9.103 → 0.9.105

package/dist/telegram-flow.js

@@ -1,24 +1,3 @@
-/**
- * Flow decisions on Telegram (v86). A card waiting at a "Person decides"
- * zone reaches the decider with the draft in front of it (when a Draft zone
- * sends it there) and three buttons: Approve, Edit, Send back.
- *
- * - Approve decides it through the same door as the console
- *   (decideFlowCard), as the paired person, for exactly the visit the
- *   message was about.
- * - Edit asks for the person's own version as a reply; it replaces the
- *   draft on the card and comes back with fresh buttons, so what is
- *   approved is always what they read.
- * - Send back asks what should change; the reply is the note.
- *
- * Every button is one opaque token for one visit of one card, placed on the
- * message it rides. A card that moved on answers so; a tap from anyone but
- * the paired person and chat never reaches here (telegram.ts checks it).
- *
- * A "Person chooses" visit (flow-send.ts) has one button per option the flow
- * names; a reply to that message instead of a tap is the note for where
- * replies go. Both go through chooseFlowCard, for exactly that visit.
- */
 import { randomBytes } from "node:crypto";
 import { LIMITS } from "./decision.js";
 import { keptDraft } from "./flow-draft.js";
@@ -28,10 +7,8 @@ import { deciderOf, FLOW_END, replyTarget } from "./flows.js";
 import { phoneLinkButton } from "./telegram-lead.js";
 import { CONFIRM_TTL_MS } from "./store.js";
 import { telegramButton } from "./contracts/telegram-callback.js";
-/** A flow decision's notice: one per visit, and again (`:ask:<ms>`) when the owner asks the lead to approve it. */
 export const FLOW_DECIDE_KEY = /^flow-decide:([1-9][0-9]{0,14}):([1-9][0-9]{0,9})(?::ask:[0-9]{1,15})?$/;
 const DRAFT_LIMIT = 4000;
-/** The card, if it is still at that visit, waiting at a decision. */
 export function flowDecisionAt(store, cardId, entry) {
     const card = store.getFlowCard(cardId);
     const flow = card === null ? null : store.getFlow(card.flow);
@@ -43,16 +20,10 @@ export function flowDecisionAt(store, cardId, entry) {
         return null;
     return { card, flow, stage, draft: draftFor(definition, stage) };
 }
-/** Where Approve and Send back take the card, on one line. */
 function decisionTerms(waiting) {
     const approve = waiting.stage.next === null ? "Approve → done" : `Approve → ${titleOf(waiting, waiting.stage.next)}`;
     return [approve, ...(waiting.stage.onFail === null ? [] : [`Send back → ${titleOf(waiting, waiting.stage.onFail)}, with your note`])].join(" · ");
 }
-/**
- * A flow decision as Telegram shows it: the action and where each button takes the card first, then the draft (as
- * the card holds it now, so what is approved is what is read) and why a subagent handed it over, then the flow and
- * zone. `said` is the saved notice's body: the words before its instruction are the subagent's handoff.
- */
 export function flowDecisionText(waiting, said, head = `Approve “${waiting.card.title}”`) {
     const at = said === null ? -1 : said.indexOf(`${waiting.stage.title}: approve`);
     const handoff = at > 0 ? said.slice(0, at).trim() : "";
@@ -66,7 +37,6 @@ export function flowDecisionText(waiting, said, head = `Approve “${waiting.car
         `${waiting.flow.name} · ${waiting.stage.title}`,
     ].join("\n");
 }
-/** Buttons for one visit, minted before the send; `place` stamps the message they landed on. */
 export function flowButtons(store, binding, waiting, now) {
     const mint = (action) => ({ action, token: randomBytes(16).toString("hex") });
     const approve = mint("approve");
@@ -78,19 +48,15 @@ export function flowButtons(store, binding, waiting, now) {
         .filter((one) => one !== null);
     return { keyboard: [[telegramButton("✅ Approve", approve.token)], ...(second.length === 0 ? [] : [second])], tokens: all.map(one => one.token) };
 }
-/** What a "Send to me" or "Person chooses" visit sent, read back for its message. */
 export function flowSentContent(store, card, entry) {
     const kept = store.flowSend(card, entry);
     return kept === null ? null : readFlowSend(kept.contentJson);
 }
-/** A sent visit's links as one row of buttons: Toolroll's pages under the trusted origin, and its pull request. */
 export function flowSendKeyboardRow(origin, content) {
     const pages = origin === null ? [] : flowSendPaths(content).flatMap(one => phoneLinkButton(origin, one) ?? []);
     const pull = content.links.flatMap(one => "url" in one ? [{ text: one.label, url: one.url }] : []);
     return [...pages.slice(0, 1), ...pull, ...pages.slice(1)].slice(0, 3);
 }
-/** A choice as Telegram shows it, first: what to choose, then where each option (and a reply) takes the card. The
- * options are the ones its buttons carry: offered when sent, and still offered. */
 export function flowChoiceHead(visit, content) {
     const titleIn = (id) => visit.definition.stages.find(one => one.id === id)?.title ?? id;
     const options = (content.options ?? []).flatMap(one => {
@@ -100,14 +66,11 @@ export function flowChoiceHead(visit, content) {
     const reply = content.reply === true ? replyTarget(visit.stage) : null;
     return [`Choose what happens to “${visit.card.title}”`, [...options, ...(reply === null ? [] : [`or reply → ${titleIn(reply)}, with your note`])].join(" · ")];
 }
-/** A choice's buttons for one visit, one option to a row, minted before the send; `place` stamps the message they landed on. */
 export function flowChoiceButtons(store, binding, visit, content, now) {
-    // Only the options the zone still offers as they were sent: a flow changed since sends no stale button.
     const options = (content.options ?? []).filter(one => visit.stage.options?.[one.choice]?.label === one.label).map(one => ({ ...one, token: randomBytes(16).toString("hex") }));
     store.createTelegramFlowChoices({ binding: binding.id, chatId: binding.chatId, card: visit.card.id, entry: visit.card.entry }, options, now);
     return { keyboard: options.map(one => [telegramButton(one.label, one.token)]), tokens: options.map(one => one.token) };
 }
-/** A tapped option, applied inside the update's transaction. */
 export function applyFlowChoiceTap(store, binding, choice, message, repos, now) {
     if (choice.consumedAt !== null || choice.expiresAt <= now.toISOString())
         return [{ kind: "ack", text: "That was already chosen, or these buttons are too old." }];
@@ -124,18 +87,14 @@ export function applyFlowChoiceTap(store, binding, choice, message, repos, now)
     if (!chosen.ok)
         return [{ kind: "ack", text: chosen.message.slice(0, 190) }];
     store.retireFlowChoices(choice.card, choice.entry, now);
-    // The door's words name the option already ("Ship it. Moved to Ship."); an ending says what happened instead.
     const said = chosen.said.startsWith(`${choice.label}.`) ? chosen.said : `You chose “${choice.label}”. ${chosen.said}`;
     return [{ kind: "ack", text: choice.label.slice(0, 190) }, { kind: "edit", text: `${message.text}\n\n✅ ${said}`.slice(0, 4000) }];
 }
-/** A card's own fresh buttons, as a repaint carries them. */
 function freshButtons(store, binding, waiting, now) {
     const minted = flowButtons(store, binding, waiting, now);
     return { keyboard: minted.keyboard.map(row => row.flatMap(one => "callback_data" in one && typeof one.callback_data === "string" ? [{ label: one.text, token: one.callback_data }] : [])), place: minted.tokens };
 }
 const FLOW_QUESTION = /\n\nApprove “[^\n]*”\? [^\n]*$/;
-/** Where a card is now, for a message whose buttons no longer act: named and linked only when it is in one of the
- * viewer's projects, and linked only while it still waits on someone. Never a live button. */
 export function flowWhereNow(store, cardId, repos) {
     const card = store.getFlowCard(cardId);
     const flow = card === null ? null : store.getFlow(card.flow);
@@ -155,10 +114,8 @@ export function flowWhereNow(store, cardId, repos) {
         return { said: `It's in ${where} now (${flow.name}): ${card.waiting.replace(/\.$/, "")}.`, keyboard: [[{ label: open.label, link: open }]] };
     return { said: `It moved on to ${where} (${flow.name}).`, keyboard: [] };
 }
-/** A tapped flow button, applied inside the update's transaction. */
 export function applyFlowTap(store, binding, action, message, repos, now) {
     if (action.consumedAt !== null || action.expiresAt <= now.toISOString()) {
-        // Spent or too old: say where the card is now, with a way to it while it still waits. The old button never acts again.
         const now_ = flowWhereNow(store, action.card, repos);
         return [{ kind: "ack", text: "These buttons were already used, or are too old." }, { kind: "edit", text: `${message.text.replace(FLOW_QUESTION, "")}\n\nThese buttons were already used, or are too old. ${now_.said}`.slice(0, 4000), keyboard: now_.keyboard }];
     }
@@ -172,7 +129,6 @@ export function applyFlowTap(store, binding, action, message, repos, now) {
     if (decider !== null && decider !== binding.approver)
         return [{ kind: "ack", text: `Only ${decider} decides here.` }];
     if (action.action === "approve") {
-        // The first tap asks; only the Yes decides, bound to exactly this visit of this card, on this message.
         if (repos === null)
             return [{ kind: "ack", text: "Couldn't check your projects just now. Try again in a moment." }];
         if (!repos.includes(waiting.flow.repo))
@@ -197,7 +153,6 @@ export function applyFlowTap(store, binding, action, message, repos, now) {
     return [{ kind: "ack", text: "What should change?" }, { kind: "prompt", prompt, placeholder: "What should change",
             text: `What should change on “${waiting.card.title}”? Reply to this message and it goes back to ${back} with your note.` }];
 }
-/** A Yes or Cancel this module armed, or null when the token isn't one. */
 export function flowConfirmOf(store, token) {
     if (!/^[0-9a-f]{32}$/.test(token))
         return null;
@@ -207,8 +162,6 @@ export function flowConfirmOf(store, token) {
     return { token: String(row["token"]), binding: Number(row["binding"]), chatId: String(row["chat"]), messageId: String(row["message"]), card: Number(row["card"]), entry: Number(row["entry"]),
         phase: String(row["action"]) === "cancel" ? "cancel" : "yes", expiresAt: String(row["expires"]), consumedAt: row["consumed"] == null ? null : String(row["consumed"]) };
 }
-/** The second tap, inside the update's transaction: Yes decides the card through the console's door, once; Cancel puts
- * the card's own buttons back. The caller has proved the binding, chat and message are the ones it was armed on. */
 export function applyFlowConfirm(store, binding, confirm, message, repos, now) {
     const body = message.text.replace(FLOW_QUESTION, "");
     const spend = () => store.telegramChat().prepare("UPDATE chat_flow_action SET consumed = ? WHERE provider = :provider AND action IN ('yes','cancel') AND card = ? AND entry = ? AND message = ? AND consumed IS NULL").run(now.toISOString(), confirm.card, confirm.entry, confirm.messageId);
@@ -216,7 +169,6 @@ export function applyFlowConfirm(store, binding, confirm, message, repos, now) {
         spend();
         const now_ = flowWhereNow(store, confirm.card, repos);
         const waiting = flowDecisionAt(store, confirm.card, confirm.entry);
-        // Too old, but the same visit still waits: fresh buttons, never the old Yes.
         if (waiting !== null && repos !== null && repos.includes(waiting.flow.repo)) {
             return [{ kind: "ack", text: "That Yes expired. Nothing was done." }, { kind: "edit", text: body, ...freshButtons(store, binding, waiting, now) }];
         }
@@ -239,11 +191,9 @@ export function applyFlowConfirm(store, binding, confirm, message, repos, now) {
     return [{ kind: "ack", text: "Approved" }, { kind: "edit", text: `${body}\n\n✅ ${decided.said}`.slice(0, 4000) }];
 }
 const titleOf = (waiting, id) => flowDefinitionOf(waiting.flow)?.stages.find(one => one.id === id)?.title ?? id;
-/** A reply to an Edit or Send back prompt, applied inside the update's transaction. */
 export function applyFlowReply(store, binding, prompt, text, repos, now) {
     if (prompt.binding !== binding.id)
         return [];
-    // A reply to a choice's message (flow-send.ts): the note for where replies go.
     const choosing = flowChoiceAt(store, prompt.card, prompt.entry);
     if (choosing !== null) {
         if (choosing.person !== binding.approver)
@@ -279,7 +229,6 @@ export function applyFlowReply(store, binding, prompt, text, repos, now) {
         const buttons = flowButtons(store, binding, fresh, now);
         return [{ kind: "decide", keyboard: buttons.keyboard, tokens: buttons.tokens, text: flowDecisionText(fresh, null, `Approve your version of “${waiting.card.title}”`) }];
     }
-    // A note over its limit is refused with the limit, never cut.
     if (said.length > LIMITS.note)
         return [{ kind: "say", text: `That's ${said.length.toLocaleString("en-US")} characters. Keep the note to ${LIMITS.note.toLocaleString("en-US")}, or send it back in Toolroll.` }];
     if (repos === null)