@chainpayhq/sdk 0.0.0-stage → 0.1.0

package/dist/mandate.js

@@ -0,0 +1,157 @@
+import { Keypair, PublicKey } from "@solana/web3.js";
+import { DEFAULT_PROGRAM_ID, MANDATE_NONCE_PREFIX } from "./constants.js";
+import { encodeApproveChecked, encodeCreateMandate, encodeInitializeConfig, encodePauseMandate, encodeRevokeDelegate, encodeRevokeMandate, encodeRegisterAsset, encodeSetAssetStatus, encodeUpdateMandate, instruction, isMandateNonce, meta, publicKey, systemProgramMeta, tokenProgramAddress, writeU64, } from "./encoding.js";
+import { deriveAssetAddress, deriveConfigAddress, deriveMandateAddress, deriveVersionedMandateAddress, } from "./pda.js";
+export function createMandateNonce() {
+    const bytes = Keypair.generate().publicKey.toBytes();
+    bytes.set(MANDATE_NONCE_PREFIX, 0);
+    return new PublicKey(bytes).toBase58();
+}
+function normalizedMandateNonce(input) {
+    const mandateNonce = input.mandateNonce ?? createMandateNonce();
+    publicKey(mandateNonce);
+    if (!isMandateNonce(mandateNonce)) {
+        throw new Error("mandateNonce must be generated by ChainPay and include its nonce prefix");
+    }
+    return mandateNonce;
+}
+export function buildInitializeConfigInstruction(supportedMints, authority, programId = DEFAULT_PROGRAM_ID) {
+    if (supportedMints.length !== 3) {
+        throw new Error("initialize_config requires exactly three mint slots");
+    }
+    publicKey(authority);
+    supportedMints.forEach((mint) => publicKey(mint));
+    return instruction("initialize_config", programId, [
+        meta(deriveConfigAddress(programId), true),
+        meta(authority, true, true),
+        systemProgramMeta(),
+    ], encodeInitializeConfig(supportedMints));
+}
+export function validateMandateInput(input) {
+    publicKey(input.approvedAgent);
+    publicKey(input.sourceTokenAccount);
+    publicKey(input.allowedMint);
+    normalizedMandateNonce(input);
+    writeU64(input.maxPerPayment, "maxPerPayment");
+    writeU64(input.totalLimit, "totalLimit");
+    writeU64(input.expiresAtSlot, "expiresAtSlot");
+    writeU64(input.maxPaymentCount, "maxPaymentCount");
+    writeU64(input.cooldownSlots, "cooldownSlots");
+    if (input.maxPerPayment <= 0n) {
+        throw new Error("maxPerPayment must be positive");
+    }
+    if (input.totalLimit < input.maxPerPayment) {
+        throw new Error("totalLimit must cover maxPerPayment");
+    }
+    if (input.expiresAtSlot <= 0n) {
+        throw new Error("expiresAtSlot must be positive");
+    }
+    if (input.delegateAmount !== undefined) {
+        writeU64(input.delegateAmount, "delegateAmount");
+        if (input.delegateAmount <= 0n)
+            throw new Error("delegateAmount must be positive");
+    }
+}
+export function buildCreateMandateInstruction(input, owner, programId = DEFAULT_PROGRAM_ID) {
+    const mandateNonce = normalizedMandateNonce(input);
+    const normalizedInput = { ...input, mandateNonce };
+    validateMandateInput(normalizedInput);
+    const config = deriveConfigAddress(programId);
+    const asset = deriveAssetAddress(normalizedInput.allowedMint, programId);
+    const mandate = deriveVersionedMandateAddress(owner, normalizedInput.allowedMint, mandateNonce, programId);
+    const tokenProgram = tokenProgramAddress(normalizedInput.tokenProgram);
+    return instruction("create_mandate", programId, [
+        meta(config),
+        meta(asset),
+        meta(mandate, true),
+        meta(owner, true, true),
+        meta(normalizedInput.allowedMint),
+        meta(normalizedInput.sourceTokenAccount),
+        meta(tokenProgram),
+        systemProgramMeta(),
+    ], encodeCreateMandate(normalizedInput));
+}
+export function buildRegisterAssetInstruction(input, authority, programId = DEFAULT_PROGRAM_ID) {
+    publicKey(input.mint);
+    publicKey(authority);
+    return instruction("register_asset", programId, [
+        meta(deriveConfigAddress(programId)),
+        meta(deriveAssetAddress(input.mint, programId), true),
+        meta(authority, false, true),
+        meta(input.mint),
+        meta(tokenProgramAddress(input.tokenProgram)),
+        systemProgramMeta(),
+    ], encodeRegisterAsset(input.mint));
+}
+export function buildSetAssetStatusInstruction(mint, authority, enabled, programId = DEFAULT_PROGRAM_ID) {
+    publicKey(mint);
+    publicKey(authority);
+    return instruction("set_asset_status", programId, [
+        meta(deriveConfigAddress(programId)),
+        meta(deriveAssetAddress(mint, programId), true),
+        meta(authority, false, true),
+    ], encodeSetAssetStatus(enabled));
+}
+export function buildApproveDelegateInstruction(input) {
+    const mandate = input.mandate ?? deriveMandateAddress(input.owner);
+    const amount = input.delegateAmount ?? input.totalLimit;
+    writeU64(amount, "delegateAmount");
+    return instruction("approve_delegate", tokenProgramAddress(input.tokenProgram), [
+        meta(input.sourceTokenAccount, true),
+        meta(input.allowedMint),
+        meta(mandate),
+        meta(input.owner, false, true),
+    ], encodeApproveChecked(amount, input.decimals));
+}
+export function buildRevokeDelegateInstruction(sourceTokenAccount, owner, tokenProgram) {
+    return instruction("revoke_delegate", tokenProgramAddress(tokenProgram), [meta(sourceTokenAccount, true), meta(owner, false, true)], encodeRevokeDelegate());
+}
+export function buildCreateMandateTransaction(input, owner, programId = DEFAULT_PROGRAM_ID, decimals) {
+    const mandateNonce = normalizedMandateNonce(input);
+    const normalizedInput = { ...input, mandateNonce };
+    validateMandateInput(normalizedInput);
+    const mandateAddress = deriveVersionedMandateAddress(owner, input.allowedMint, mandateNonce, programId);
+    if (decimals === undefined) {
+        throw new Error("Token decimals are required to prepare delegate approval");
+    }
+    const create = buildCreateMandateInstruction(normalizedInput, owner, programId);
+    const approve = buildApproveDelegateInstruction({
+        ...normalizedInput,
+        owner,
+        mandate: mandateAddress,
+        decimals,
+    });
+    const transaction = {
+        instructions: [create, approve],
+        requiredSigners: [owner],
+        feePayer: owner,
+    };
+    return {
+        mandateAddress,
+        configAddress: deriveConfigAddress(programId),
+        transaction,
+    };
+}
+export function buildUpdateMandateInstruction(input, owner, programId = DEFAULT_PROGRAM_ID, mandateAddress) {
+    publicKey(owner);
+    publicKey(input.approvedAgent);
+    writeU64(input.maxPerPayment, "maxPerPayment");
+    writeU64(input.totalLimit, "totalLimit");
+    writeU64(input.expiresAtSlot, "expiresAtSlot");
+    writeU64(input.maxPaymentCount, "maxPaymentCount");
+    writeU64(input.cooldownSlots, "cooldownSlots");
+    if (input.maxPerPayment <= 0n)
+        throw new Error("maxPerPayment must be positive");
+    if (input.totalLimit < input.maxPerPayment)
+        throw new Error("totalLimit must cover maxPerPayment");
+    return instruction("update_mandate", programId, [
+        meta(mandateAddress ?? deriveMandateAddress(owner, programId), true),
+        meta(owner, false, true),
+    ], encodeUpdateMandate(input));
+}
+export function buildPauseMandateInstruction(owner, programId = DEFAULT_PROGRAM_ID, mandateAddress) {
+    return instruction("pause_mandate", programId, [meta(mandateAddress ?? deriveMandateAddress(owner, programId), true), meta(owner, false, true)], encodePauseMandate());
+}
+export function buildRevokeMandateInstruction(owner, programId = DEFAULT_PROGRAM_ID, mandateAddress) {
+    return instruction("revoke_mandate", programId, [meta(mandateAddress ?? deriveMandateAddress(owner, programId), true), meta(owner, false, true)], encodeRevokeMandate());
+}

package/dist/ops-snapshot.d.ts

@@ -0,0 +1,157 @@
+import type { ChainPayClient } from "./client.js";
+import type { Address, Mandate, MandateStatus, PaymentReceipt, PaymentRequestPayload, PaymentStatus, ReceiptPolicy, ReceiptPolicySource } from "./types.js";
+export declare const DEFAULT_RECEIPT_LIMIT = 10;
+/**
+ * "Expires within about a day". Solana produces roughly 216,000 slots a day at
+ * ~400 ms each; the dashboard measures the live rate, this surface only needs
+ * a warning threshold.
+ */
+export declare const DEFAULT_EXPIRING_SOON_SLOTS = 216000n;
+export type OpsAttentionKind = "expiring_soon" | "paused" | "exhausted" | "revoked" | "expired";
+export type OpsMintTotal = {
+    mint: Address;
+    symbol: string;
+    decimals: number | null;
+    spent: string;
+    remaining: string;
+    spentBase: string;
+    remainingBase: string;
+};
+export type OpsMandateRow = {
+    address: Address;
+    status: MandateStatus;
+    mint: Address;
+    symbol: string;
+    decimals: number | null;
+    spent: string;
+    remaining: string;
+    totalLimit: string;
+    maxPerPayment: string;
+    spentBase: string;
+    remainingBase: string;
+    totalLimitBase: string;
+    maxPerPaymentBase: string;
+    expiresAtSlot: string;
+    approvedAgent: Address;
+};
+/**
+ * Spending-permission limits beside one receipt, as display amounts. `source`
+ * says where they came from; only "on-chain" was recorded on Solana. Limit
+ * fields are absent when the source is "not-recorded".
+ */
+export type OpsReceiptPolicy = {
+    source: ReceiptPolicySource;
+    maxPerPayment?: string;
+    totalLimit?: string;
+    /** Absent for a relay read taken after a later payment. */
+    spentAfter?: string;
+    paymentCountAfter?: string;
+    /** "0" means no payment-count cap. */
+    maxPaymentCount?: string;
+    expiresAtSlot?: string;
+    observedAtSlot?: string;
+};
+/** What was bought, from a merchant-signed request checked against the receipt. */
+export type OpsReceiptPurpose = Partial<Pick<PaymentRequestPayload, "invoice" | "description" | "lineItems">> & {
+    /** False when the receipt paid a different amount, mint, or recipient than the request named. */
+    matched?: boolean;
+};
+export declare function opsReceiptPolicy(policy: ReceiptPolicy, decimals: number | null): OpsReceiptPolicy;
+export type OpsReceiptRow = {
+    address: Address;
+    mandate: Address;
+    amount: string;
+    amountBase: string;
+    symbol: string;
+    decimals: number | null;
+    status: PaymentStatus;
+    executedAtSlot: string;
+    recipientTokenAccount: Address;
+    receiptUrl?: string;
+    policy: OpsReceiptPolicy;
+    purpose?: OpsReceiptPurpose;
+};
+export type OpsAttentionItem = {
+    kind: OpsAttentionKind;
+    mandate: Address;
+    detail: string;
+};
+export type OpsSnapshot = {
+    kind: "spend_overview";
+    owner: Address;
+    totals: OpsMintTotal[];
+    mandates: OpsMandateRow[];
+    receipts: OpsReceiptRow[];
+    attention: OpsAttentionItem[];
+    note: string;
+};
+export type OpsReceiptList = {
+    kind: "receipt_list";
+    owner: Address;
+    count: number;
+    receipts: OpsReceiptRow[];
+};
+export type PaymentLookupCard = {
+    kind: "payment_lookup";
+    found: boolean;
+    policy?: OpsReceiptPolicy;
+    purpose?: OpsReceiptPurpose;
+    receiptAddress?: Address;
+    amount?: string;
+    symbol?: string;
+    status?: string;
+    signature?: string;
+    mandate?: Address;
+    receiptUrl?: string;
+};
+export type LoadOpsSnapshotInput = {
+    owner: Address;
+    /** Keep only the mandates this caller may see. Absent means every mandate the owner has. */
+    mandateFilter?: (mandate: Mandate) => boolean;
+    receiptLimit?: number;
+    appUrl?: string;
+    currentSlot?: bigint;
+    expiringSoonSlots?: bigint;
+    /**
+     * Optional off-chain context for each listed receipt, such as a relay
+     * observation of the limits or the verified merchant request. Called only
+     * for receipts inside the limit. A failure leaves the row as it was.
+     */
+    receiptContext?: (receipt: PaymentReceipt) => Promise<OpsReceiptContext>;
+};
+export type OpsReceiptContext = {
+    /** Used only when the receipt carries no on-chain snapshot. */
+    relayPolicy?: ReceiptPolicy | null;
+    purpose?: OpsReceiptPurpose;
+};
+export declare function tokenLabel(mint: Address): string;
+export declare function shortAddress(value: string | undefined): string;
+export declare function receiptUrlForAddress(receiptAddress: string | undefined, appUrl?: string): string | undefined;
+export declare function humanTokenAmount(amount: bigint, decimals: number | null): {
+    display: string;
+    base: string;
+    decimals: number | null;
+};
+export declare function buildOpsSnapshot(input: {
+    owner: Address;
+    mandates: Mandate[];
+    receipts: PaymentReceipt[];
+    decimalsByMint: Record<string, number | null>;
+    currentSlot?: bigint;
+    appUrl?: string;
+    receiptLimit?: number;
+    expiringSoonSlots?: bigint;
+}): OpsSnapshot;
+export declare function loadOpsSnapshot(client: ChainPayClient, options: LoadOpsSnapshotInput): Promise<OpsSnapshot>;
+export declare function receiptListFromSnapshot(snapshot: OpsSnapshot): OpsReceiptList;
+export declare function formatOpsMarkdown(snapshot: OpsSnapshot): string;
+export declare function formatReceiptListMarkdown(list: OpsReceiptList): string;
+/** One plain line: the limits at payment and where they came from. */
+export declare function receiptPolicyLine(policy: OpsReceiptPolicy | undefined, symbol: string): string;
+export declare function formatPaymentLookupMarkdown(card: PaymentLookupCard): string;
+export declare function formatPreparePolicyMarkdown(action: "pause" | "revoke", mandate?: string): string;
+/** Compact terminal text. Same facts as the markdown card, no styling codes. */
+export declare function formatOpsAnsi(snapshot: OpsSnapshot): string;
+export declare function formatReceiptListAnsi(list: OpsReceiptList): string;
+export declare function formatPaymentLookupAnsi(card: PaymentLookupCard): string;
+export declare function formatPreparePolicyAnsi(action: "pause" | "revoke", mandate?: string): string;

package/dist/ops-snapshot.js

@@ -0,0 +1,356 @@
+import { assetLabel } from "./known-assets.js";
+import { formatExactTokenAmount } from "./receipt.js";
+import { receiptPolicy } from "./receipt-export.js";
+export const DEFAULT_RECEIPT_LIMIT = 10;
+/**
+ * "Expires within about a day". Solana produces roughly 216,000 slots a day at
+ * ~400 ms each; the dashboard measures the live rate, this surface only needs
+ * a warning threshold.
+ */
+export const DEFAULT_EXPIRING_SOON_SLOTS = 216000n;
+export function opsReceiptPolicy(policy, decimals) {
+    if (policy.source === "not-recorded")
+        return { source: "not-recorded" };
+    const { limits } = policy;
+    const later = policy.source === "relay-observed" && policy.includesLaterPayments;
+    return {
+        source: policy.source,
+        maxPerPayment: humanTokenAmount(limits.maxPerPayment, decimals).display,
+        totalLimit: humanTokenAmount(limits.totalLimit, decimals).display,
+        ...(later ? {} : {
+            spentAfter: humanTokenAmount(limits.amountSpentAfter, decimals).display,
+            paymentCountAfter: limits.paymentCountAfter.toString(),
+        }),
+        maxPaymentCount: limits.maxPaymentCount.toString(),
+        expiresAtSlot: limits.expiresAtSlot.toString(),
+        ...(policy.source === "relay-observed" ? { observedAtSlot: policy.observedAtSlot.toString() } : {}),
+    };
+}
+export function tokenLabel(mint) {
+    return assetLabel(mint);
+}
+export function shortAddress(value) {
+    if (!value || value.length < 12)
+        return value ?? "unknown";
+    return `${value.slice(0, 4)}…${value.slice(-4)}`;
+}
+export function receiptUrlForAddress(receiptAddress, appUrl) {
+    if (!receiptAddress)
+        return undefined;
+    const origin = appUrl?.trim().replace(/\/$/, "");
+    if (!origin)
+        return undefined;
+    return `${origin}/verify/${encodeURIComponent(receiptAddress)}`;
+}
+export function humanTokenAmount(amount, decimals) {
+    const exact = formatExactTokenAmount(amount, decimals);
+    let display = exact.display;
+    if (exact.displayKind === "ui-amount" && display.includes(".")) {
+        display = display.replace(/0+$/, "").replace(/\.$/, "");
+    }
+    return { display, base: exact.baseUnits, decimals: exact.decimals };
+}
+function remainingBase(mandate) {
+    return mandate.totalLimit > mandate.amountSpent ? mandate.totalLimit - mandate.amountSpent : 0n;
+}
+export function buildOpsSnapshot(input) {
+    const receiptLimit = input.receiptLimit ?? DEFAULT_RECEIPT_LIMIT;
+    const soon = input.expiringSoonSlots ?? DEFAULT_EXPIRING_SOON_SLOTS;
+    const mandates = input.mandates.map((mandate) => {
+        const decimals = input.decimalsByMint[mandate.allowedMint] ?? null;
+        const symbol = tokenLabel(mandate.allowedMint);
+        const remaining = remainingBase(mandate);
+        const spent = humanTokenAmount(mandate.amountSpent, decimals);
+        const remain = humanTokenAmount(remaining, decimals);
+        const limit = humanTokenAmount(mandate.totalLimit, decimals);
+        const cap = humanTokenAmount(mandate.maxPerPayment, decimals);
+        return {
+            address: mandate.address,
+            status: mandate.status,
+            mint: mandate.allowedMint,
+            symbol,
+            decimals,
+            spent: spent.display,
+            remaining: remain.display,
+            totalLimit: limit.display,
+            maxPerPayment: cap.display,
+            spentBase: spent.base,
+            remainingBase: remain.base,
+            totalLimitBase: limit.base,
+            maxPerPaymentBase: cap.base,
+            expiresAtSlot: mandate.expiresAtSlot.toString(),
+            approvedAgent: mandate.approvedAgent,
+        };
+    });
+    const mints = [...new Set(input.mandates.map((mandate) => mandate.allowedMint))];
+    const totals = mints.map((mint) => {
+        const matching = input.mandates.filter((mandate) => mandate.allowedMint === mint);
+        const spent = matching.reduce((sum, mandate) => sum + mandate.amountSpent, 0n);
+        const remaining = matching
+            .filter((mandate) => mandate.status === "active")
+            .reduce((sum, mandate) => sum + remainingBase(mandate), 0n);
+        const decimals = input.decimalsByMint[mint] ?? null;
+        const spentAmt = humanTokenAmount(spent, decimals);
+        const remainAmt = humanTokenAmount(remaining, decimals);
+        return {
+            mint,
+            symbol: tokenLabel(mint),
+            decimals,
+            spent: spentAmt.display,
+            remaining: remainAmt.display,
+            spentBase: spentAmt.base,
+            remainingBase: remainAmt.base,
+        };
+    });
+    const receipts = [...input.receipts]
+        .sort((left, right) => (right.executedAtSlot > left.executedAtSlot ? 1 : right.executedAtSlot < left.executedAtSlot ? -1 : 0))
+        .slice(0, receiptLimit)
+        .map((receipt) => {
+        const decimals = input.decimalsByMint[receipt.mint] ?? null;
+        const amount = humanTokenAmount(receipt.amount, decimals);
+        const receiptUrl = receiptUrlForAddress(receipt.address, input.appUrl);
+        return {
+            address: receipt.address,
+            mandate: receipt.mandate,
+            amount: amount.display,
+            amountBase: amount.base,
+            symbol: tokenLabel(receipt.mint),
+            decimals,
+            status: receipt.status,
+            executedAtSlot: receipt.executedAtSlot.toString(),
+            recipientTokenAccount: receipt.recipientTokenAccount,
+            ...(receiptUrl ? { receiptUrl } : {}),
+            policy: opsReceiptPolicy(receiptPolicy(receipt), decimals),
+        };
+    });
+    const attention = [];
+    for (const mandate of input.mandates) {
+        if (mandate.status === "paused") {
+            attention.push({
+                kind: "paused",
+                mandate: mandate.address,
+                detail: "Paused — the agent cannot spend until the owner resumes this permission.",
+            });
+        }
+        else if (mandate.status === "revoked") {
+            attention.push({
+                kind: "revoked",
+                mandate: mandate.address,
+                detail: "Revoked — settled receipts remain; the agent cannot spend.",
+            });
+        }
+        else if (mandate.status === "expired") {
+            attention.push({
+                kind: "expired",
+                mandate: mandate.address,
+                detail: "Expired — the agent cannot spend. Create a new permission in the dashboard.",
+            });
+        }
+        else if (mandate.status === "active" && remainingBase(mandate) === 0n && mandate.totalLimit > 0n) {
+            attention.push({
+                kind: "exhausted",
+                mandate: mandate.address,
+                detail: "Remaining allowance is 0. The agent cannot spend more on this permission.",
+            });
+        }
+        else if (mandate.status === "active"
+            && input.currentSlot !== undefined
+            && mandate.expiresAtSlot > input.currentSlot
+            && mandate.expiresAtSlot - input.currentSlot <= soon) {
+            attention.push({
+                kind: "expiring_soon",
+                mandate: mandate.address,
+                detail: "Expires within about a day (slot estimate).",
+            });
+        }
+    }
+    return {
+        kind: "spend_overview",
+        owner: input.owner,
+        totals,
+        mandates,
+        receipts,
+        attention,
+        note: "Totals are mandate allowances, not wallet balance. Inbox requests stay in the dashboard until they settle on-chain.",
+    };
+}
+export async function loadOpsSnapshot(client, options) {
+    const owner = options.owner;
+    const loaded = await client.getMandatesByOwner(owner);
+    const mandates = options.mandateFilter ? loaded.filter(options.mandateFilter) : loaded;
+    const receipts = (await Promise.all(mandates.map((mandate) => client.getPaymentsByMandate(mandate.address)))).flat();
+    const mints = [...new Set([
+            ...mandates.map((mandate) => mandate.allowedMint),
+            ...receipts.map((receipt) => receipt.mint),
+        ])];
+    const decimalsByMint = {};
+    await Promise.all(mints.map(async (mint) => {
+        try {
+            decimalsByMint[mint] = await client.getMintDecimals(mint);
+        }
+        catch {
+            decimalsByMint[mint] = null;
+        }
+    }));
+    const currentSlot = options.currentSlot ?? await client.getCurrentSlot().catch(() => undefined);
+    const snapshot = buildOpsSnapshot({
+        owner,
+        mandates,
+        receipts,
+        decimalsByMint,
+        currentSlot,
+        appUrl: options.appUrl,
+        receiptLimit: options.receiptLimit,
+        expiringSoonSlots: options.expiringSoonSlots,
+    });
+    const receiptContext = options.receiptContext;
+    if (!receiptContext)
+        return snapshot;
+    const byAddress = new Map(receipts.map((receipt) => [receipt.address, receipt]));
+    const rows = await Promise.all(snapshot.receipts.map(async (row) => {
+        const receipt = byAddress.get(row.address);
+        if (!receipt)
+            return row;
+        try {
+            const context = await receiptContext(receipt);
+            return {
+                ...row,
+                policy: opsReceiptPolicy(receiptPolicy(receipt, context.relayPolicy), row.decimals),
+                ...(context.purpose ? { purpose: context.purpose } : {}),
+            };
+        }
+        catch {
+            return row;
+        }
+    }));
+    return { ...snapshot, receipts: rows };
+}
+export function receiptListFromSnapshot(snapshot) {
+    return {
+        kind: "receipt_list",
+        owner: snapshot.owner,
+        count: snapshot.receipts.length,
+        receipts: snapshot.receipts,
+    };
+}
+export function formatOpsMarkdown(snapshot) {
+    if (snapshot.mandates.length === 0) {
+        return [
+            "**No spending permissions found** for this wallet on ChainPay Devnet.",
+            "",
+            snapshot.note,
+            "",
+            "**Next step:** Create a mandate in the ChainPay dashboard, then reconnect the agent.",
+        ].join("\n");
+    }
+    const lines = ["**Spending overview**", ""];
+    if (snapshot.totals.length) {
+        lines.push("**Totals (mandate allowance, not wallet balance)**");
+        for (const total of snapshot.totals) {
+            lines.push(`- **${total.spent} ${total.symbol}** spent · **${total.remaining} ${total.symbol}** remaining`);
+        }
+        lines.push("");
+    }
+    lines.push(`**${snapshot.mandates.length} permission${snapshot.mandates.length === 1 ? "" : "s"}**`);
+    snapshot.mandates.forEach((mandate, index) => {
+        lines.push(`${index + 1}. **${mandate.symbol}** — ${mandate.status}`, `   Address: \`${shortAddress(mandate.address)}\``, `   - Per payment: **${mandate.maxPerPayment} ${mandate.symbol}**`, `   - Total allowance: **${mandate.totalLimit} ${mandate.symbol}** (**${mandate.spent} ${mandate.symbol}** spent, **${mandate.remaining} ${mandate.symbol}** remaining)`);
+    });
+    if (snapshot.attention.length) {
+        lines.push("", "**Needs attention**");
+        for (const item of snapshot.attention) {
+            lines.push(`- ${item.detail} (\`${shortAddress(item.mandate)}\`)`);
+        }
+    }
+    if (snapshot.receipts.length) {
+        lines.push("", `**Recent receipts (${snapshot.receipts.length})**`);
+        for (const receipt of snapshot.receipts) {
+            const verify = receipt.receiptUrl ? ` · [Verify](${receipt.receiptUrl})` : "";
+            lines.push(`- **${receipt.amount} ${receipt.symbol}** · \`${shortAddress(receipt.address)}\`${verify}`);
+        }
+    }
+    lines.push("", snapshot.note, "", "**Next step:** Ask for `list_receipts`, inspect one receipt, or prepare a pause in the owner wallet.");
+    return lines.join("\n");
+}
+export function formatReceiptListMarkdown(list) {
+    if (list.count === 0) {
+        return [
+            "**No receipts yet** for this permission.",
+            "",
+            "**Next step:** After a payment settles, call `list_receipts` again or open the public verify link from the settlement card.",
+        ].join("\n");
+    }
+    const lines = [`**${list.count} receipt${list.count === 1 ? "" : "s"}**`, ""];
+    list.receipts.forEach((receipt, index) => {
+        const verify = receipt.receiptUrl ? ` · [Verify](${receipt.receiptUrl})` : "";
+        lines.push(`${index + 1}. **${receipt.amount} ${receipt.symbol}** — ${receipt.status}`, ...(receipt.purpose?.description ? [`   For: ${receipt.purpose.description}`] : []), `   Receipt: \`${shortAddress(receipt.address)}\`${verify}`, `   Permission: \`${shortAddress(receipt.mandate)}\``, `   ${receiptPolicyLine(receipt.policy, receipt.symbol)}`);
+    });
+    lines.push("", "**Next step:** Open a verify link or call `get_payment` with a receipt address for the full card.");
+    return lines.join("\n");
+}
+const POLICY_SOURCE_LABEL = {
+    "on-chain": "recorded on Solana at payment",
+    "relay-observed": "seen by the ChainPay relay after payment, not stored on Solana",
+    "not-recorded": "not recorded for this receipt",
+};
+/** One plain line: the limits at payment and where they came from. */
+export function receiptPolicyLine(policy, symbol) {
+    if (!policy || policy.source === "not-recorded" || !policy.maxPerPayment || !policy.totalLimit) {
+        return `Limits at payment: ${POLICY_SOURCE_LABEL["not-recorded"]}`;
+    }
+    const spent = policy.spentAfter ? ` · ${policy.spentAfter} of ${policy.totalLimit} ${symbol} used after` : ` · ${policy.totalLimit} ${symbol} total`;
+    return `Limits at payment: ${policy.maxPerPayment} ${symbol} per payment${spent} (${POLICY_SOURCE_LABEL[policy.source]})`;
+}
+export function formatPaymentLookupMarkdown(card) {
+    if (!card.found) {
+        const address = card.receiptAddress ? ` at \`${shortAddress(card.receiptAddress)}\`` : "";
+        return `**Receipt not found**${address}.\n\n**Next step:** Confirm the address or call \`list_receipts\` for this permission.`;
+    }
+    const lines = [
+        "**Payment receipt** on Solana Devnet.",
+        ...(card.amount ? [`- Amount: **${card.amount}${card.symbol ? ` ${card.symbol}` : ""}**`] : []),
+        ...(card.receiptAddress ? [`- Receipt: \`${shortAddress(card.receiptAddress)}\``] : []),
+        ...(card.purpose?.description ? [`- For: ${card.purpose.description}`] : []),
+        ...(card.mandate ? [`- Permission: \`${shortAddress(card.mandate)}\``] : []),
+        ...(card.policy ? [`- ${receiptPolicyLine(card.policy, card.symbol ?? "")}`] : []),
+        ...(card.status ? [`- Status: ${card.status}`] : []),
+        ...(card.signature ? [`- Signature: \`${shortAddress(card.signature)}\``] : []),
+        ...(card.receiptUrl ? [`- Verify: ${card.receiptUrl}`] : []),
+        "",
+        "**Next step:** Share the verify link or open the receipt in ChainPay.",
+    ];
+    return lines.join("\n");
+}
+export function formatPreparePolicyMarkdown(action, mandate) {
+    const verb = action === "pause" ? "pause" : "revoke";
+    return [
+        `**Owner wallet signature required** — ${verb} this permission.`,
+        "",
+        "This change needs the owner wallet—not the agent connection.",
+        ...(mandate ? [`- Permission: \`${shortAddress(mandate)}\``] : []),
+        "",
+        "**Options**",
+        "1. Approve in the ChainPay dashboard wallet flow",
+        "2. Cancel and keep the current policy",
+        "",
+        "**Next step:** Wait for the owner to sign in the dashboard. This surface does not sign or submit.",
+    ].join("\n");
+}
+function stripMarkdown(value) {
+    return value
+        .replace(/\*\*/g, "")
+        .replace(/\[([^\]]+)\]\([^)]+\)/g, "$1")
+        .replace(/`/g, "");
+}
+/** Compact terminal text. Same facts as the markdown card, no styling codes. */
+export function formatOpsAnsi(snapshot) {
+    return stripMarkdown(formatOpsMarkdown(snapshot));
+}
+export function formatReceiptListAnsi(list) {
+    return stripMarkdown(formatReceiptListMarkdown(list));
+}
+export function formatPaymentLookupAnsi(card) {
+    return stripMarkdown(formatPaymentLookupMarkdown(card));
+}
+export function formatPreparePolicyAnsi(action, mandate) {
+    return stripMarkdown(formatPreparePolicyMarkdown(action, mandate));
+}