@aitne/daemon 0.1.8 → 0.1.10

package/dist/services/browser-history/automation/purchase-handler.d.ts

@@ -0,0 +1,344 @@
+/**
+ * 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.
+ */
+import type Database from "better-sqlite3";
+import { type PurchaseCancelReason, type PurchaseTokenRow } from "../../../db/browser-automation-purchase-tokens-store.js";
+/**
+ * Capability handle — opaque at the type level. The runtime check is
+ * identity comparison against the module-private `PURCHASE_HANDLER_CAPABILITY`
+ * symbol; the value-level identity is what makes the credential
+ * unforgeable, not the TS type narrowing. Exposed as `symbol` (not
+ * `unique symbol`) so callers can hold a reference without depending
+ * on the const's exact typeof — the comparison still works.
+ */
+export type PurchaseHandlerCapability = symbol;
+/**
+ * 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 declare function __aitneB4_getPurchaseHandlerCapability(): PurchaseHandlerCapability;
+/**
+ * Wire-shape of every DM the handler emits — never the LLM. The
+ * implementation lives in `messaging/system-message-sender.ts` and is
+ * the only place agentic outbound code paths intersect with this
+ * surface; the capability arg guards entry.
+ */
+export interface PurchaseSystemMessageSender {
+    /**
+     * Deliver the pre-confirm screenshot + token + total + verify line
+     * to each channel in `channels`. Return the channels actually
+     * delivered to. The handler persists this list on the
+     * `purchase_tokens.delivered_channels` JSON column; only those
+     * channels can later validate a reply.
+     *
+     * On partial failure (some channels reachable, some not) returns
+     * the delivered subset so the user can still confirm via whichever
+     * channel the DM landed on. The handler logs the failure subset
+     * but does not abort the workflow — the user-facing flow accepts
+     * "any single primary channel delivers and the consent path works".
+     */
+    deliverPurchaseRequest(capability: PurchaseHandlerCapability, input: {
+        channels: readonly string[];
+        token: string;
+        jti: string;
+        siteKey: string;
+        displayedTotalMinor: number;
+        currency: string;
+        notesForUser: string | null;
+        preScreenshotPath: string;
+        expiresAt: number;
+    }): Promise<{
+        delivered: readonly string[];
+        failed: readonly string[];
+    }>;
+    /**
+     * After a reply consumes the token, post the "✅ Confirmed" reply on
+     * the consumed channel and the "✅ Approved on <channel>" follow-up
+     * to every other delivered channel. Idempotent — invoked exactly
+     * once per consume.
+     */
+    deliverPostConsumeFollowup(capability: PurchaseHandlerCapability, input: {
+        deliveredChannels: readonly string[];
+        consumedChannel: string;
+        jti: string;
+        siteKey: string;
+    }): Promise<void>;
+    /**
+     * Post a "⚠️ Cancelled — <reason>" follow-up on every delivered
+     * channel. Best-effort; failures are logged but do not propagate.
+     */
+    deliverCancellationFollowup(capability: PurchaseHandlerCapability, input: {
+        deliveredChannels: readonly string[];
+        jti: string;
+        siteKey: string;
+        reason: PurchaseCancelReason;
+    }): Promise<void>;
+    /**
+     * Reply on a single channel with a structured legitimacy line in
+     * response to the user's `!verify <tail>` slash command (§17.3).
+     * The handler invokes this from `handleVerifySlash`.
+     */
+    deliverVerifyReply(capability: PurchaseHandlerCapability, input: {
+        channel: string;
+        jti: string | null;
+        ok: boolean;
+        detail: string;
+    }): Promise<void>;
+}
+export interface PurchaseHandlerDeps {
+    db: Database.Database;
+    sender: PurchaseSystemMessageSender;
+    /** Override for tests; production uses `Date.now`. */
+    nowFn?: () => number;
+    /** Override for tests; production uses 500 ms. */
+    pollIntervalMs?: number;
+}
+export interface IssueTokenInput {
+    workflowInvocationId: string;
+    siteKey: string;
+    urlPattern: string;
+    /** Actual displayed total at screenshot time, in minor units. Becomes
+     *  the token's `max_amount_minor`. */
+    displayedTotalMinor: number;
+    currency: string;
+    preScreenshotPath: string;
+    notesForUser: string | null;
+    /** Originating channel for user-initiated workflows (DM → workflow);
+     *  null for scheduled / autonomous invocations. When non-null AND
+     *  the channel is in the primary set, the token is DMed ONLY to
+     *  that channel (single-channel ergonomic flow). Otherwise fan out
+     *  to every primary channel. */
+    originatingChannel: string | null;
+}
+export type IssueTokenResult = {
+    ok: true;
+    jti: string;
+    token: string;
+    expiresAt: number;
+    deliveredChannels: readonly string[];
+} | {
+    ok: false;
+    reason: "b4_disabled";
+} | {
+    ok: false;
+    reason: "site_not_enabled";
+} | {
+    ok: false;
+    reason: "no_primary_channels";
+} | {
+    ok: false;
+    reason: "pending_exists";
+    pendingJti: string;
+} | {
+    ok: false;
+    reason: "daily_token_cap_exceeded";
+    cap: number;
+    used: number;
+} | {
+    ok: false;
+    reason: "daily_spend_cap_exceeded";
+    capMinor: number;
+    currentMinor: number;
+    proposedMinor: number;
+} | {
+    ok: false;
+    reason: "currency_mismatch";
+    expected: string;
+    actual: string;
+} | {
+    ok: false;
+    reason: "delivery_failed";
+    jti: string;
+};
+export type AwaitReplyResult = {
+    status: "confirmed";
+    row: PurchaseTokenRow;
+} | {
+    status: "cancelled_by_user_reply";
+    row: PurchaseTokenRow;
+} | {
+    status: "cancelled_wrong_token";
+    row: PurchaseTokenRow;
+} | {
+    status: "cancelled_timeout";
+    row: PurchaseTokenRow;
+} | {
+    status: "cancelled_explicit";
+    row: PurchaseTokenRow;
+} | {
+    status: "cancelled_other";
+    row: PurchaseTokenRow;
+};
+export interface AwaitReplyInput {
+    jti: string;
+    abortSignal?: AbortSignal;
+}
+export interface FinalizeInput {
+    jti: string;
+    confirmedAmountMinor: number;
+    currency: string;
+    orderId: string | null;
+    postScreenshotPath: string;
+}
+/**
+ * Inbound-reply handler invoked from the messaging adapter when a
+ * body classifies as `token_reply`. Encapsulates: (a) the atomic
+ * consume CAS, (b) the audit-row insert, (c) the post-consume DM
+ * follow-up dispatch.
+ *
+ * Returns the categorical outcome for the adapter to render its
+ * one-line reply on the originating channel.
+ */
+export type HandleTokenReplyOutcome = {
+    kind: "consumed";
+    jti: string;
+    row: PurchaseTokenRow;
+} | {
+    kind: "wrong_channel";
+} | {
+    kind: "expired";
+} | {
+    kind: "already_consumed";
+} | {
+    kind: "already_cancelled";
+} | {
+    kind: "no_match";
+} | {
+    kind: "shape_invalid";
+};
+/**
+ * Inbound `!verify <tail>` handler — looks up the pending token by
+ * tail and replies on the originating channel with the legitimacy
+ * line. Pure-ish: writes only the verify-reply DM, no DB mutations.
+ */
+export type HandleVerifySlashOutcome = {
+    kind: "verified";
+    jti: string;
+    row: PurchaseTokenRow;
+} | {
+    kind: "no_match";
+};
+/**
+ * Cancellation modes — see `cancel()` JSDoc.
+ *
+ * `pending-only` (default) — pre-consume cancel, refuses if the user
+ * already typed the token (consumed_at IS NOT NULL). Used by the
+ * adapter-side cancel slash, the dashboard "Cancel pending" button,
+ * and DM-delivery failure paths.
+ *
+ * `any-non-terminal` — post-consume cancel, accepts the consumed-but-
+ * not-finalized state so the workflow can mark the row terminal when
+ * the click fails / cart drifts under the pause. Without this the row
+ * sticks in `pending+consumed_at!=null` forever and the user never
+ * gets a follow-up DM. MANAGED_CHROMIUM_IMPLEMENTATION_PLAN.md §17.3
+ * cancellation table: rows for `cancel_reason in (amount_mismatch,
+ * amount_exceeds_token, page_changed, playwright_error)` are reached
+ * via this mode.
+ */
+export type CancelMode = "pending-only" | "any-non-terminal";
+export interface PurchaseHandler {
+    issueToken(input: IssueTokenInput): Promise<IssueTokenResult>;
+    awaitReply(input: AwaitReplyInput): Promise<AwaitReplyResult>;
+    finalize(input: FinalizeInput): Promise<PurchaseTokenRow | null>;
+    /**
+     * Cancel a pending or consumed-but-not-finalized purchase token.
+     * `mode` defaults to `"pending-only"` (race-safe pre-consume); use
+     * `"any-non-terminal"` from inside the workflow's post-consume
+     * failure paths (page_changed / amount_mismatch / playwright_error
+     * after consume) so the CAS does not silently miss when consumed_at
+     * is set.
+     */
+    cancel(jti: string, reason: PurchaseCancelReason, mode?: CancelMode): Promise<PurchaseTokenRow | null>;
+    /**
+     * BROWSER_TASK_REDESIGN_PLAN.md §14.11 Q#6 — jti-prefix dispatcher
+     * read side. Look up a token by raw `!~xxxxxxxx` string so the
+     * messaging adapter's inbound classifier can decide BEFORE calling
+     * `handleTokenReply` whether B-4 or the lite-final-confirm surface
+     * owns the matching row. Both jtis are uuid v4 so a colliding match
+     * is bounded by uuid uniqueness; the dispatcher resolves ties by
+     * `issuedAt`. Returns null when no row exists in this store —
+     * cosmically cheap (single indexed SELECT) so calling unconditionally
+     * is fine. Mirrors `FinalConfirmHandler.lookupByRaw`.
+     */
+    lookupByRaw(raw: string): PurchaseTokenRow | null;
+    /** Adapter-side entry — see HandleTokenReplyOutcome above. */
+    handleTokenReply(input: {
+        body: string;
+        channelRef: string;
+        nowMs?: number;
+    }): Promise<HandleTokenReplyOutcome>;
+    /** Adapter-side entry for `!verify <tail>`. */
+    handleVerifySlash(input: {
+        tail: string;
+        channelRef: string;
+    }): Promise<HandleVerifySlashOutcome>;
+    /** Adapter-side entry for `!cancel-purchase` slash — cancels every
+     *  pending token whose delivered_channels includes the inbound
+     *  channel. */
+    handleCancelPurchaseSlash(input: {
+        channelRef: string;
+    }): Promise<readonly PurchaseTokenRow[]>;
+    /**
+     * MANAGED_CHROMIUM_IMPLEMENTATION_PLAN.md §17.3 cancellation row 1 —
+     * strict-cancel on non-token reply.
+     *
+     * When the user sends ANY message on a channel that received a
+     * pending purchase token AND the message is NOT one of the three
+     * recognised shapes (`!~xxxxxxxx` reply, `!verify <tail>`,
+     * `!cancel-purchase`), every pending token delivered to that channel
+     * is cancelled with reason `user_reply`. The user explicitly accepted
+     * this strict UX in rev3's directive — anything but the exact token
+     * aborts the workflow.
+     *
+     * Returns the rows that were cancelled (empty if none pending on the
+     * channel). Best-effort — DM dispatch failures are logged but do not
+     * propagate; the in-flight workflow's `awaitReply` poll sees the
+     * `cancelled_at` timestamp on its next 500ms tick and returns
+     * `cancelled_by_user_reply`.
+     *
+     * The adapter still forwards the inbound message to the DM agent —
+     * the cancel is silent from the LLM's perspective (the agent never
+     * sees the token / didn't know there was a pending purchase). The
+     * user sees the cancellation follow-up DM from
+     * `sendSystemMessage.deliverCancellationFollowup` so they know the
+     * purchase was aborted.
+     */
+    cancelPendingOnNonTokenReply(input: {
+        channelRef: string;
+    }): Promise<readonly PurchaseTokenRow[]>;
+}
+export declare function createPurchaseHandler(deps: PurchaseHandlerDeps): PurchaseHandler;