@aitne/daemon 0.1.8 → 0.1.9

package/dist/services/browser-history/automation/purchase-handler.js

@@ -0,0 +1,666 @@
+/**
+ * Phase B-4 purchase handler — orchestrates the DM-issued single-use
+ * token flow that gates every B-4 workflow.
+ *
+ * MANAGED_CHROMIUM_IMPLEMENTATION_PLAN.md §17.3 / §17.4 / §13 step 50.
+ *
+ * The handler is the single chokepoint for issuing a `!~xxxxxxxx`
+ * confirmation token. The workflow (`confirm-cart-checkout.ts`) calls
+ * `issueToken()` AFTER the pre-confirm screenshot lands, then
+ * `awaitReply()` until the user types the exact token back in DM, then
+ * `finalize()` once the post-confirm click + screenshot are recorded.
+ *
+ * The agent CANNOT reach this module directly: it lives daemon-side
+ * with no API route, the only entry points are the B-4 purchase
+ * workflow's `run()` (orchestrated by `browser-task-runner.ts` post-
+ * Phase 6 — the legacy `workflow-runner.ts` was retired in
+ * BROWSER_TASK_REDESIGN_PLAN.md §9) and the dispatcher's
+ * `jti`-prefix dispatch path shared with `final-confirm-handler.ts`,
+ * and the system-message dispatch goes through a module-level
+ * capability the agent cannot mint (`PurchaseSystemMessageSender`).
+ * This is the structural anti-spoofing layer §17.7 specifies: "agent
+ * tools cannot construct a fake confirmation request because the
+ * credentialed sender refuses unauthenticated callers".
+ *
+ * I/O-shaped (DB writes, async DM dispatch, polling timer). The
+ * coverage gate excludes this module — the pure decision logic lives
+ * in `purchase-tokens.ts` (shape parsing, classifyPurchaseReply,
+ * classifyPurchaseTokenEcho) and is the covered surface. Integration
+ * tests against the browser-task runner exercise the full flow end-
+ * to-end.
+ */
+// B4_TOKEN_TTL_MS is consumed indirectly via `computePurchaseExpiry`.
+import { cancelPurchaseToken, consumePurchaseToken, finalizePurchaseToken, getPurchaseTokenByJti, getPurchaseTokenByRaw, issuePurchaseToken, listPendingTokensForChannel, } from "../../../db/browser-automation-purchase-tokens-store.js";
+import { insertPurchaseReply, } from "../../../db/browser-automation-purchase-replies-store.js";
+import { getB4Enabled, getSiteB4Config, } from "../../../db/browser-automation-b4-config-store.js";
+import { listPrimaryChannels, channelRef, } from "../../../db/browser-automation-purchase-primary-channels-store.js";
+import { createLogger } from "../../../logging.js";
+import { classifyPurchaseReply, computePurchaseExpiry, hashReplyBody, mintPurchaseToken, } from "./purchase-tokens.js";
+const logger = createLogger("purchase-handler");
+/** Default poll interval for `awaitReply`. The runner's
+ *  `perWorkflowTimeoutMs` already caps the absolute wait, so a 500 ms
+ *  cadence balances responsiveness against load (the user typically
+ *  replies in ~30-60 s). */
+const DEFAULT_POLL_INTERVAL_MS = 500;
+/** Maximum number of token-mint retries on UNIQUE collision. 40-bit
+ *  entropy makes a collision astronomically unlikely; 5 retries is
+ *  defence against a defective CSPRNG without burning the workflow's
+ *  perWorkflowTimeoutMs. */
+const MAX_MINT_RETRIES = 5;
+/**
+ * Module-level capability symbol. Held ONLY by the sender
+ * implementation paired with the handler at startup. The handler-side
+ * call site is intentionally typed to require the capability so any
+ * caller that does not hold it (i.e., everything outside the daemon's
+ * bootstrap path) fails the type check. At runtime the symbol acts as
+ * an unforgeable bearer credential — the symbol's identity is the
+ * proof.
+ *
+ * Why not a string or an HMAC: a string can be hard-coded into a
+ * misbehaving skill; an HMAC would still leave the verifier and the
+ * signer in the same trust boundary the threat model already assumes
+ * is honest (the daemon). A Symbol cannot be referenced from outside
+ * the module that creates it, which matches the actual property we
+ * want.
+ */
+const PURCHASE_HANDLER_CAPABILITY = Symbol("aitne.b4.purchase-handler.capability");
+/**
+ * Surface the sender side of the credential. The daemon-bootstrap
+ * code grabs this once at startup, passes it into the
+ * `createPurchaseHandler` factory + the sender implementation; nothing
+ * else is permitted to import this getter.
+ *
+ * The function is intentionally side-effect free so the test layer can
+ * still construct sender + handler in fixtures (and the daemon's
+ * single boot is the only production caller).
+ */
+export function __aitneB4_getPurchaseHandlerCapability() {
+    return PURCHASE_HANDLER_CAPABILITY;
+}
+export function createPurchaseHandler(deps) {
+    const now = deps.nowFn ?? (() => Date.now());
+    const pollIntervalMs = deps.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    const capability = PURCHASE_HANDLER_CAPABILITY;
+    async function issueToken(input) {
+        if (!getB4Enabled(deps.db)) {
+            return { ok: false, reason: "b4_disabled" };
+        }
+        const siteConfig = getSiteB4Config(deps.db, input.siteKey);
+        if (!siteConfig || !siteConfig.enabled) {
+            return { ok: false, reason: "site_not_enabled" };
+        }
+        // Resolve delivery set:
+        //   - originatingChannel non-null AND primary → that one channel only
+        //   - otherwise → fan out to every primary channel
+        // No primary channels at all → refuse to issue.
+        const primary = listPrimaryChannels(deps.db).map((row) => channelRef(row.platform, row.channelId));
+        if (primary.length === 0) {
+            return { ok: false, reason: "no_primary_channels" };
+        }
+        const delivery = input.originatingChannel && primary.includes(input.originatingChannel)
+            ? [input.originatingChannel]
+            : primary;
+        const issuedAt = now();
+        const expiresAt = computePurchaseExpiry(issuedAt);
+        // Mint loop with collision retries.
+        let attempt = 0;
+        let issuedRow = null;
+        let lastFailure = null;
+        while (attempt < MAX_MINT_RETRIES) {
+            attempt += 1;
+            const token = mintPurchaseToken();
+            const result = issuePurchaseToken(deps.db, {
+                token,
+                workflowInvocationId: input.workflowInvocationId,
+                siteKey: input.siteKey,
+                urlPattern: input.urlPattern,
+                maxAmountMinor: input.displayedTotalMinor,
+                currency: input.currency,
+                preScreenshotPath: input.preScreenshotPath,
+                notesForUser: input.notesForUser,
+                deliveredChannels: delivery,
+                issuedAt,
+                expiresAt,
+            });
+            lastFailure = result;
+            if (result.ok) {
+                issuedRow = result.row;
+                break;
+            }
+            if (result.reason !== "token_collision") {
+                // Non-collision failure → no point retrying.
+                break;
+            }
+        }
+        if (!issuedRow) {
+            // Map the DB-layer categorical failures onto the wire-shape.
+            if (!lastFailure || lastFailure.ok) {
+                // c8 ignore — every loop iteration writes a non-ok lastFailure
+                // when the row stays null; defensive default for type narrowing.
+                return { ok: false, reason: "delivery_failed", jti: "" };
+            }
+            switch (lastFailure.reason) {
+                case "site_not_enabled":
+                    return { ok: false, reason: "site_not_enabled" };
+                case "currency_mismatch":
+                    return {
+                        ok: false,
+                        reason: "currency_mismatch",
+                        expected: lastFailure.expected,
+                        actual: lastFailure.actual,
+                    };
+                case "daily_token_cap_exceeded":
+                    return {
+                        ok: false,
+                        reason: "daily_token_cap_exceeded",
+                        cap: lastFailure.cap,
+                        used: lastFailure.used,
+                    };
+                case "daily_spend_cap_exceeded":
+                    return {
+                        ok: false,
+                        reason: "daily_spend_cap_exceeded",
+                        capMinor: lastFailure.capMinor,
+                        currentMinor: lastFailure.currentMinor,
+                        proposedMinor: lastFailure.proposedMinor,
+                    };
+                case "pending_exists":
+                    return {
+                        ok: false,
+                        reason: "pending_exists",
+                        pendingJti: lastFailure.pendingJti,
+                    };
+                case "token_collision":
+                    // Exhausted retries — fail closed so the workflow surfaces
+                    // playwright_error rather than spinning forever.
+                    logger.error({ siteKey: input.siteKey, attempt }, "purchase token collision exhausted retries; refusing to issue");
+                    return { ok: false, reason: "delivery_failed", jti: "" };
+            }
+        }
+        // Deliver the DM. We post BEFORE returning so that on delivery
+        // failure we can cancel the token immediately and surface the
+        // failure to the workflow as a wire-level outcome — the workflow
+        // must NOT proceed to await a reply on a token the user never
+        // received.
+        let delivered = [];
+        let failed = [];
+        try {
+            const result = await deps.sender.deliverPurchaseRequest(capability, {
+                channels: issuedRow.deliveredChannels,
+                token: issuedRow.token ?? "",
+                jti: issuedRow.jti,
+                siteKey: issuedRow.siteKey,
+                displayedTotalMinor: issuedRow.maxAmountMinor,
+                currency: issuedRow.currency,
+                notesForUser: issuedRow.notesForUser,
+                preScreenshotPath: issuedRow.preScreenshotPath,
+                expiresAt: issuedRow.expiresAt,
+            });
+            delivered = result.delivered;
+            failed = result.failed;
+        }
+        catch (err) {
+            logger.error({ err, jti: issuedRow.jti, siteKey: issuedRow.siteKey }, "purchase DM delivery threw; cancelling token");
+            cancelPurchaseToken(deps.db, {
+                jti: issuedRow.jti,
+                reason: "playwright_error",
+                cancelledAt: now(),
+                onlyIfPending: true,
+            });
+            return { ok: false, reason: "delivery_failed", jti: issuedRow.jti };
+        }
+        if (delivered.length === 0) {
+            logger.error({
+                jti: issuedRow.jti,
+                siteKey: issuedRow.siteKey,
+                attempted: issuedRow.deliveredChannels,
+                failed,
+            }, "purchase DM delivery failed on all channels; cancelling token");
+            cancelPurchaseToken(deps.db, {
+                jti: issuedRow.jti,
+                reason: "playwright_error",
+                cancelledAt: now(),
+                onlyIfPending: true,
+            });
+            return { ok: false, reason: "delivery_failed", jti: issuedRow.jti };
+        }
+        if (failed.length > 0) {
+            logger.warn({ jti: issuedRow.jti, failed }, "purchase DM partial delivery — proceeding with the subset that landed");
+        }
+        logger.info({
+            jti: issuedRow.jti,
+            siteKey: issuedRow.siteKey,
+            deliveredCount: delivered.length,
+            expiresAt: issuedRow.expiresAt,
+        }, "B-4 purchase token issued and DM delivered");
+        return {
+            ok: true,
+            jti: issuedRow.jti,
+            token: issuedRow.token ?? "",
+            expiresAt: issuedRow.expiresAt,
+            deliveredChannels: delivered,
+        };
+    }
+    async function awaitReply(input) {
+        while (true) {
+            if (input.abortSignal?.aborted) {
+                const row = getPurchaseTokenByJti(deps.db, input.jti);
+                cancelPurchaseToken(deps.db, {
+                    jti: input.jti,
+                    reason: "timeout",
+                    cancelledAt: now(),
+                    onlyIfPending: true,
+                });
+                return {
+                    status: "cancelled_timeout",
+                    row: row ??
+                        (() => {
+                            throw new Error("awaitReply: token row vanished mid-await");
+                        })(),
+                };
+            }
+            const row = getPurchaseTokenByJti(deps.db, input.jti);
+            if (!row) {
+                throw new Error(`awaitReply: token row for jti=${input.jti} missing`);
+            }
+            // Confirmed terminal (the finalize side has already run — possible
+            // when the messaging adapter's consume + the workflow's finalize
+            // both fire before our next tick).
+            if (row.status === "confirmed") {
+                return { status: "confirmed", row };
+            }
+            // Consumed but not yet finalized → workflow can proceed.
+            if (row.consumedAt !== null && row.cancelledAt === null) {
+                return { status: "confirmed", row };
+            }
+            // Cancelled by adapter (wrong reply / wrong token / explicit).
+            if (row.cancelledAt !== null) {
+                switch (row.cancelReason) {
+                    case "user_reply":
+                        return { status: "cancelled_by_user_reply", row };
+                    case "wrong_token":
+                    case "wrong_channel":
+                        return { status: "cancelled_wrong_token", row };
+                    case "timeout":
+                        return { status: "cancelled_timeout", row };
+                    case "explicit":
+                    case "dashboard_cancel":
+                        return { status: "cancelled_explicit", row };
+                    default:
+                        return { status: "cancelled_other", row };
+                }
+            }
+            // Local TTL — beat the supervisor sweep so the workflow doesn't
+            // wait for the next sweep cycle.
+            if (now() > row.expiresAt) {
+                cancelPurchaseToken(deps.db, {
+                    jti: input.jti,
+                    reason: "timeout",
+                    cancelledAt: now(),
+                    onlyIfPending: true,
+                });
+                const expired = getPurchaseTokenByJti(deps.db, input.jti) ?? row;
+                return { status: "cancelled_timeout", row: expired };
+            }
+            await sleep(pollIntervalMs, input.abortSignal);
+        }
+    }
+    async function finalize(input) {
+        const row = finalizePurchaseToken(deps.db, {
+            jti: input.jti,
+            confirmedAmountMinor: input.confirmedAmountMinor,
+            currency: input.currency,
+            orderId: input.orderId,
+            postScreenshotPath: input.postScreenshotPath,
+            finalizedAt: now(),
+        });
+        if (!row) {
+            logger.warn({ jti: input.jti }, "purchase-handler.finalize CAS missed — already terminal?");
+        }
+        return row;
+    }
+    async function cancel(jti, reason, mode = "pending-only") {
+        const row = cancelPurchaseToken(deps.db, {
+            jti,
+            reason,
+            cancelledAt: now(),
+            onlyIfPending: mode === "pending-only",
+        });
+        if (row) {
+            try {
+                await deps.sender.deliverCancellationFollowup(capability, {
+                    deliveredChannels: row.deliveredChannels,
+                    jti: row.jti,
+                    siteKey: row.siteKey,
+                    reason,
+                });
+            }
+            catch (err) {
+                logger.warn({ err, jti, reason }, "cancellation follow-up DM failed (continuing)");
+            }
+        }
+        return row;
+    }
+    async function handleTokenReply(input) {
+        const nowMs = input.nowMs ?? now();
+        const bodyHash = hashReplyBody(input.body);
+        // Lookup the row by raw token. The pure classifier needs the row.
+        // We re-parse to also handle the `shape_invalid` short circuit
+        // without a DB roundtrip.
+        const parsed = input.body.trim();
+        const isShape = /^!~[A-Z2-7]{8}$/.test(parsed);
+        const row = isShape
+            ? lookupPurchaseTokenView(deps.db, parsed)
+            : null;
+        const decision = classifyPurchaseReply({
+            body: input.body,
+            channelRef: input.channelRef,
+            row,
+            nowMs,
+        });
+        const auditOutcome = decision.kind === "consume"
+            ? "consumed"
+            : decision.kind === "wrong_channel"
+                ? "wrong_channel"
+                : decision.kind === "expired"
+                    ? "expired"
+                    : decision.kind === "already_consumed"
+                        ? "already_consumed"
+                        : decision.kind === "already_cancelled"
+                            ? "already_cancelled"
+                            : decision.kind === "no_match"
+                                ? "no_match"
+                                : "shape_invalid";
+        const matchedJti = decision.kind === "consume" ||
+            decision.kind === "wrong_channel" ||
+            decision.kind === "expired" ||
+            decision.kind === "already_consumed" ||
+            decision.kind === "already_cancelled"
+            ? decision.row.jti
+            : null;
+        if (decision.kind === "consume") {
+            const consumed = consumePurchaseToken(deps.db, {
+                jti: decision.row.jti,
+                channelRef: input.channelRef,
+                consumedAt: nowMs,
+                nowMs,
+            });
+            if (!consumed) {
+                // Race lost to another concurrent reply on a different channel.
+                insertPurchaseReply(deps.db, {
+                    receivedAt: nowMs,
+                    channelRef: input.channelRef,
+                    messageBodyHash: bodyHash,
+                    matchedJti: decision.row.jti,
+                    outcome: "already_consumed",
+                });
+                return { kind: "already_consumed" };
+            }
+            insertPurchaseReply(deps.db, {
+                receivedAt: nowMs,
+                channelRef: input.channelRef,
+                messageBodyHash: bodyHash,
+                matchedJti: consumed.jti,
+                outcome: "consumed",
+            });
+            try {
+                await deps.sender.deliverPostConsumeFollowup(capability, {
+                    deliveredChannels: consumed.deliveredChannels,
+                    consumedChannel: input.channelRef,
+                    jti: consumed.jti,
+                    siteKey: consumed.siteKey,
+                });
+            }
+            catch (err) {
+                logger.warn({ err, jti: consumed.jti }, "post-consume follow-up DM failed (continuing)");
+            }
+            return { kind: "consumed", jti: consumed.jti, row: consumed };
+        }
+        insertPurchaseReply(deps.db, {
+            receivedAt: nowMs,
+            channelRef: input.channelRef,
+            messageBodyHash: bodyHash,
+            matchedJti,
+            outcome: auditOutcome,
+        });
+        if (decision.kind === "wrong_channel") {
+            // Channel leak / spoof — cancel the token defensively. The user
+            // typed the correct token but on a non-delivered channel, which
+            // either means they fat-fingered the channel or someone forwarded
+            // the DM. Either way it's safer to abort than confirm.
+            cancelPurchaseToken(deps.db, {
+                jti: decision.row.jti,
+                reason: "wrong_channel",
+                cancelledAt: nowMs,
+                onlyIfPending: true,
+            });
+            return { kind: "wrong_channel" };
+        }
+        if (decision.kind === "expired")
+            return { kind: "expired" };
+        if (decision.kind === "already_consumed")
+            return { kind: "already_consumed" };
+        if (decision.kind === "already_cancelled")
+            return { kind: "already_cancelled" };
+        if (decision.kind === "no_match")
+            return { kind: "no_match" };
+        return { kind: "shape_invalid" };
+    }
+    async function handleVerifySlash(input) {
+        const candidate = `!~${input.tail}`;
+        const row = lookupPurchaseTokenView(deps.db, candidate);
+        if (!row) {
+            await deps.sender.deliverVerifyReply(capability, {
+                channel: input.channelRef,
+                jti: null,
+                ok: false,
+                detail: "No pending purchase request matches that token.",
+            });
+            return { kind: "no_match" };
+        }
+        const full = getPurchaseTokenByJti(deps.db, row.jti);
+        if (!full) {
+            await deps.sender.deliverVerifyReply(capability, {
+                channel: input.channelRef,
+                jti: row.jti,
+                ok: false,
+                detail: "Token row vanished between lookup and verify.",
+            });
+            return { kind: "no_match" };
+        }
+        const lines = [
+            `Legitimate purchase request from Aitne.`,
+            `workflow=confirmCartCheckout site=${full.siteKey} jti=${full.jti}`,
+            `amount=${formatMinor(full.maxAmountMinor, full.currency)} expires=${new Date(full.expiresAt).toISOString()}`,
+        ];
+        if (full.notesForUser)
+            lines.push(`notes=${full.notesForUser}`);
+        await deps.sender.deliverVerifyReply(capability, {
+            channel: input.channelRef,
+            jti: full.jti,
+            ok: true,
+            detail: lines.join("\n"),
+        });
+        return { kind: "verified", jti: full.jti, row: full };
+    }
+    async function handleCancelPurchaseSlash(input) {
+        const nowMs = now();
+        const pending = listPendingTokensForChannel(deps.db, input.channelRef, nowMs);
+        const cancelled = [];
+        for (const row of pending) {
+            const updated = cancelPurchaseToken(deps.db, {
+                jti: row.jti,
+                reason: "explicit",
+                cancelledAt: nowMs,
+                onlyIfPending: true,
+            });
+            if (updated) {
+                cancelled.push(updated);
+                try {
+                    await deps.sender.deliverCancellationFollowup(capability, {
+                        deliveredChannels: updated.deliveredChannels,
+                        jti: updated.jti,
+                        siteKey: updated.siteKey,
+                        reason: "explicit",
+                    });
+                }
+                catch (err) {
+                    logger.warn({ err, jti: updated.jti }, "explicit-cancel follow-up DM failed (continuing)");
+                }
+            }
+        }
+        insertPurchaseReply(deps.db, {
+            receivedAt: nowMs,
+            channelRef: input.channelRef,
+            messageBodyHash: hashReplyBody("!cancel-purchase"),
+            matchedJti: cancelled[0]?.jti ?? null,
+            outcome: "cancel_workflow",
+        });
+        return cancelled;
+    }
+    async function cancelPendingOnNonTokenReply(input) {
+        const nowMs = now();
+        const pending = listPendingTokensForChannel(deps.db, input.channelRef, nowMs);
+        if (pending.length === 0)
+            return [];
+        const cancelled = [];
+        for (const row of pending) {
+            // `onlyIfPending: true` — refuse to retroactively cancel a row
+            // the user has already typed the token for. Without this, a
+            // race between the user's `!~xxxxxxxx` reply and a tail-message
+            // arriving on the same channel could cancel a row that just
+            // CAS-consumed.
+            const updated = cancelPurchaseToken(deps.db, {
+                jti: row.jti,
+                reason: "user_reply",
+                cancelledAt: nowMs,
+                onlyIfPending: true,
+            });
+            if (updated) {
+                cancelled.push(updated);
+                try {
+                    await deps.sender.deliverCancellationFollowup(capability, {
+                        deliveredChannels: updated.deliveredChannels,
+                        jti: updated.jti,
+                        siteKey: updated.siteKey,
+                        reason: "user_reply",
+                    });
+                }
+                catch (err) {
+                    logger.warn({ err, jti: updated.jti, channel: input.channelRef }, "non-token-reply cancellation DM failed (continuing)");
+                }
+            }
+        }
+        if (cancelled.length > 0) {
+            // Audit-trail: record one `_replies` row per cancelled token so
+            // the dashboard's spoofing/replay analysis surface can correlate
+            // the cancellation back to the inbound message. We do not store
+            // the message body (could contain attacker-controlled text); the
+            // hash domain is the literal sentinel string instead — enough
+            // to bucket non-token cancellations without leaking content.
+            for (const row of cancelled) {
+                insertPurchaseReply(deps.db, {
+                    receivedAt: nowMs,
+                    channelRef: input.channelRef,
+                    messageBodyHash: hashReplyBody("[non-token-reply-strict-cancel-sentinel]"),
+                    matchedJti: row.jti,
+                    outcome: "cancel_workflow",
+                });
+            }
+            logger.info({
+                channel: input.channelRef,
+                cancelledCount: cancelled.length,
+                jtis: cancelled.map((r) => r.jti),
+            }, "B-4 strict-cancel: non-token reply cancelled pending tokens (§17.3)");
+        }
+        return cancelled;
+    }
+    function lookupByRaw(raw) {
+        return getPurchaseTokenByRaw(deps.db, raw);
+    }
+    return {
+        issueToken,
+        awaitReply,
+        finalize,
+        cancel,
+        lookupByRaw,
+        handleTokenReply,
+        handleVerifySlash,
+        handleCancelPurchaseSlash,
+        cancelPendingOnNonTokenReply,
+    };
+}
+/** Pure shape-narrowing on the DB row → the validator view. Lives
+ *  inline so the messaging adapter can also call it via the
+ *  re-exported store helpers. */
+function lookupPurchaseTokenView(db, raw) {
+    const row = getPurchaseTokenByRaw(db, raw);
+    if (!row)
+        return null;
+    return {
+        jti: row.jti,
+        token: row.token,
+        workflowInvocationId: row.workflowInvocationId,
+        siteKey: row.siteKey,
+        status: row.status,
+        issuedAt: row.issuedAt,
+        expiresAt: row.expiresAt,
+        consumedAt: row.consumedAt,
+        cancelledAt: row.cancelledAt,
+        deliveredChannels: row.deliveredChannels,
+    };
+}
+/** ISO-4217 currencies with 0 decimal places. The default is 2; this
+ *  set is the subset where dividing by 100 would mis-format the major
+ *  unit. JPY is the only one in scope at MVP (B-4's first registered
+ *  site is amazon_jp); the others stay here so a future site addition
+ *  doesn't reintroduce the bug. Source: ISO-4217. */
+const ZERO_DECIMAL_CURRENCIES = new Set([
+    "JPY",
+    "KRW",
+    "VND",
+    "CLP",
+    "ISK",
+    "PYG",
+    "RWF",
+    "UGX",
+    "BIF",
+    "DJF",
+    "GNF",
+    "KMF",
+    "MGA",
+    "XAF",
+    "XOF",
+    "XPF",
+]);
+function formatMinor(amount, currency) {
+    const code = currency.toUpperCase();
+    const zeroDecimal = ZERO_DECIMAL_CURRENCIES.has(code);
+    const major = zeroDecimal
+        ? String(amount)
+        : (amount / 100).toFixed(2);
+    return `${code} ${major} (minor=${amount})`;
+}
+/** AbortSignal-aware sleep. Throws nothing on abort — the caller's
+ *  outer loop checks `aborted` and handles the abort path explicitly. */
+async function sleep(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted) {
+            resolve();
+            return;
+        }
+        const timer = setTimeout(() => {
+            cleanup();
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            cleanup();
+            resolve();
+        };
+        const cleanup = () => {
+            signal?.removeEventListener("abort", onAbort);
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}