@seedhape/core 0.1.0

package/dist/mpp.js

@@ -0,0 +1,164 @@
+/**
+ * MPP (Machine Payments Protocol) HTTP Authentication Scheme primitives.
+ *
+ * This module deliberately implements only the provider-neutral wire format.
+ * A parsed credential is untrusted input; a payment-method adapter must verify
+ * it, enforce the shared spending policy, and settle before fulfillment.
+ */
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+function encode(value) {
+    return Buffer.from(encoder.encode(JSON.stringify(value))).toString("base64url");
+}
+function decode(value, label) {
+    try {
+        const parsed = JSON.parse(decoder.decode(Buffer.from(value, "base64url")));
+        return parsed;
+    }
+    catch {
+        throw new Error(`Invalid MPP ${label} encoding.`);
+    }
+}
+function quote(value) {
+    return `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
+}
+function unquote(value) {
+    if (!value.startsWith('"') || !value.endsWith('"'))
+        throw new Error("Invalid MPP quoted value.");
+    return value.slice(1, -1).replaceAll('\\"', '"').replaceAll("\\\\", "\\");
+}
+function splitAuthParams(value) {
+    const parts = [];
+    let start = 0;
+    let quoted = false;
+    let escaped = false;
+    for (let index = 0; index < value.length; index += 1) {
+        const character = value[index];
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (quoted && character === "\\") {
+            escaped = true;
+            continue;
+        }
+        if (character === '"') {
+            quoted = !quoted;
+            continue;
+        }
+        if (!quoted && character === ",") {
+            parts.push(value.slice(start, index).trim());
+            start = index + 1;
+        }
+    }
+    if (quoted || escaped)
+        throw new Error("Invalid MPP authentication parameters.");
+    parts.push(value.slice(start).trim());
+    return parts.filter(Boolean);
+}
+/** Serialize a `WWW-Authenticate: Payment ...` challenge. */
+export function formatMppChallenge(challenge) {
+    if (!challenge.id || !challenge.realm || !challenge.method || !challenge.intent) {
+        throw new Error("MPP challenge requires id, realm, method, and intent.");
+    }
+    const { id, realm, method, intent, request, expires, ...extensions } = challenge;
+    const params = [`id=${quote(id)}`, `realm=${quote(realm)}`, `method=${quote(method)}`, `intent=${quote(intent)}`, `request=${quote(encode(request))}`];
+    if (expires !== undefined)
+        params.push(`expires=${String(expires)}`);
+    for (const [key, value] of Object.entries(extensions)) {
+        if (!/^[a-zA-Z][a-zA-Z0-9_-]*$/.test(key))
+            throw new Error(`Invalid MPP extension name: ${key}`);
+        if (typeof value !== "string")
+            throw new Error(`MPP extension ${key} must be a string.`);
+        params.push(`${key}=${quote(value)}`);
+    }
+    return `Payment ${params.join(", ")}`;
+}
+/** Parse a `WWW-Authenticate: Payment ...` challenge and reject duplicates. */
+export function parseMppChallenge(header) {
+    const match = /^Payment\s+(.+)$/i.exec(header.trim());
+    if (!match)
+        throw new Error("Expected an MPP Payment challenge.");
+    const values = new Map();
+    for (const part of splitAuthParams(match[1])) {
+        const separator = part.indexOf("=");
+        if (separator <= 0)
+            throw new Error("Invalid MPP authentication parameter.");
+        const key = part.slice(0, separator).trim();
+        const raw = part.slice(separator + 1).trim();
+        if (values.has(key))
+            throw new Error(`Duplicate MPP authentication parameter: ${key}`);
+        values.set(key, raw.startsWith('"') ? unquote(raw) : raw);
+    }
+    const required = ["id", "realm", "method", "intent", "request"];
+    for (const key of required)
+        if (!values.has(key))
+            throw new Error(`MPP challenge is missing ${key}.`);
+    const expiresRaw = values.get("expires");
+    const expires = expiresRaw === undefined ? undefined : Number(expiresRaw);
+    if (expiresRaw !== undefined && !Number.isSafeInteger(expires))
+        throw new Error("MPP challenge expires must be an integer.");
+    const request = decode(values.get("request"), "challenge request");
+    if (!request || typeof request !== "object" || Array.isArray(request))
+        throw new Error("MPP challenge request must be an object.");
+    const challenge = { id: values.get("id"), realm: values.get("realm"), method: values.get("method"), intent: values.get("intent"), request };
+    if (expires !== undefined)
+        challenge.expires = expires;
+    for (const [key, value] of values)
+        if (!required.includes(key) && key !== "expires")
+            challenge[key] = value;
+    return challenge;
+}
+/** Serialize an MPP `Authorization: Payment <base64url>` credential. */
+export function formatMppCredential(credential) {
+    if (!credential.challenge || !credential.payload)
+        throw new Error("MPP credential requires challenge and payload.");
+    return `Payment ${encode(credential)}`;
+}
+/** Parse an MPP `Authorization: Payment <base64url>` credential. */
+export function parseMppCredential(header) {
+    const match = /^Payment\s+([^\s]+)$/i.exec(header.trim());
+    if (!match)
+        throw new Error("Expected an MPP Payment credential.");
+    const credential = decode(match[1], "credential");
+    if (!credential || typeof credential !== "object" || !credential.challenge || !credential.payload)
+        throw new Error("MPP credential must contain challenge and payload.");
+    return credential;
+}
+/** Serialize an MPP `Payment-Receipt` response header. */
+export function formatMppReceipt(receipt) {
+    if (!receipt.status || !receipt.method || !receipt.reference || !Number.isSafeInteger(receipt.timestamp))
+        throw new Error("MPP receipt requires status, method, timestamp, and reference.");
+    return encode(receipt);
+}
+/** Parse an MPP `Payment-Receipt` response header. */
+export function parseMppReceipt(header) {
+    const receipt = decode(header.trim(), "receipt");
+    if (!receipt || typeof receipt !== "object" || !receipt.status || !receipt.method || !receipt.reference || !Number.isSafeInteger(receipt.timestamp))
+        throw new Error("Invalid MPP receipt.");
+    return receipt;
+}
+/**
+ * Execute one MPP-protected request. Credential creation is injected so the
+ * caller can enforce its own user mandate, budget, and provider policy before
+ * producing a payment credential. The transport retries at most once after a
+ * valid 402 challenge and never retries an ambiguous response.
+ */
+export async function fetchWithMpp(input, init, createCredential, fetchImpl = fetch) {
+    const initial = await fetchImpl(input, init);
+    if (initial.status !== 402)
+        return { response: initial };
+    const challengeHeader = initial.headers.get("www-authenticate");
+    if (!challengeHeader)
+        throw new Error("MPP payment challenge is missing WWW-Authenticate.");
+    const challenge = parseMppChallenge(challengeHeader);
+    if (challenge.expires !== undefined && challenge.expires <= Math.floor(Date.now() / 1000))
+        throw new Error("MPP payment challenge has expired.");
+    const credential = await createCredential(challenge);
+    const headers = new Headers(init?.headers);
+    headers.set("authorization", formatMppCredential(credential));
+    const response = await fetchImpl(input, { ...init, headers });
+    const receiptHeader = response.headers.get("payment-receipt");
+    return { response, challenge, ...(receiptHeader ? { receipt: parseMppReceipt(receiptHeader) } : {}) };
+}
+//# sourceMappingURL=mpp.js.map

package/dist/mpp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mpp.js","sourceRoot":"","sources":["../src/mpp.ts"],"names":[],"mappings":"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"}

package/dist/orchestrator.d.ts

@@ -0,0 +1,115 @@
+/**
+ * The payment orchestrator. This is where the four subsystems meet:
+ * AP2 mandates, the policy engine, the x402 wire protocol, and the India
+ * tax ledger.
+ *
+ * Ordering matters and is deliberate:
+ *
+ *   quote → build cart mandate → policy check → build payment mandate →
+ *   sign → send → record → settle
+ *
+ * The policy check happens after the cart mandate exists but before any
+ * signature. That means a declined payment leaves a signed record of what was
+ * refused and why, with no signature that could be replayed. The audit trail
+ * covers refusals as well as spends, which is what makes it useful in a dispute.
+ */
+import { PolicyEngine } from "./ap2/policy.js";
+import type { FxProvider } from "./india/fx.js";
+import { type Ap2SignerConfig } from "./ap2/official.js";
+import type { Store } from "./store.js";
+import type { WalletProvider } from "./wallet/provider.js";
+import type { ComposablePaymentProvider } from "./wallet/providers.js";
+import type { OutboundRequestPolicy } from "./x402/outbound.js";
+import type { Address, AssetRef, Hex, MandateHash, PolicyDecision, SpendRecord } from "./types.js";
+export interface OrchestratorConfig {
+    userId: string;
+    store: Store;
+    wallet: WalletProvider;
+    policy: PolicyEngine;
+    fx: FxProvider;
+    asset: AssetRef;
+    absoluteMaxPerPayment: bigint;
+    outboundPolicy?: OutboundRequestPolicy;
+    paymentProviders?: readonly ComposablePaymentProvider[];
+    ap2?: {
+        loadSigner: () => Promise<Ap2SignerConfig>;
+    };
+    /**
+     * Called when a payment is legal under the mandate but flagged for review.
+     * Returning false aborts. A local MCP server can surface this to the human;
+     * a headless deployment should default to false, never true.
+     */
+    confirmUnusual?: (decision: PolicyDecision, detail: {
+        host: string;
+        amount: bigint;
+        resource: string;
+    }) => Promise<boolean>;
+}
+export interface PayResult {
+    ok: boolean;
+    spendId: string;
+    status: SpendRecord["status"];
+    /** Body returned by the merchant once paid. */
+    body?: string;
+    contentType?: string;
+    amount?: bigint;
+    inrPaise?: bigint;
+    txHash?: Hex;
+    decision?: PolicyDecision;
+    error?: string;
+}
+export declare class Orchestrator {
+    private readonly cfg;
+    private readonly client;
+    constructor(cfg: OrchestratorConfig);
+    /** Price a resource without paying and without touching the ledger. */
+    quote(url: string): Promise<{
+        accepts: {
+            inrPaise: string;
+            scheme: "exact" | string;
+            network: string;
+            maxAmountRequired: string;
+            amount?: string;
+            resource: string;
+            description: string;
+            mimeType?: string;
+            payTo: string;
+            maxTimeoutSeconds: number;
+            asset: string;
+            extra?: {
+                name?: string;
+                version?: string;
+                decimals?: number;
+                assetTransferMethod?: "eip3009" | "erc7710" | "permit2" | "coinbase-spend-permission" | string;
+                facilitatorAddresses?: Address[];
+                feePayer?: string;
+                recentBlockhash?: string;
+                lastValidBlockHeight?: string;
+                memo?: string;
+                [key: string]: unknown;
+            };
+            outputSchema?: unknown;
+        }[];
+        x402Version: number;
+        resource?: {
+            url: string;
+            description?: string;
+            mimeType?: string;
+            [key: string]: unknown;
+        };
+        extensions?: Record<string, unknown>;
+        error?: string;
+        ap2CheckoutJwt?: string;
+    } | null>;
+    /**
+     * Fetch a resource under a specific intent mandate, paying if required.
+     */
+    pay(url: string, intentHash: MandateHash, init?: RequestInit): Promise<PayResult>;
+    /**
+     * Consume cost-basis lots FIFO. Runs after settlement so a failed payment
+     * never disturbs the tax ledger.
+     */
+    private recordDisposal;
+    private selectRequirement;
+}
+//# sourceMappingURL=orchestrator.d.ts.map

package/dist/orchestrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../src/orchestrator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAUH,OAAO,EAAE,YAAY,EAAsB,MAAM,iBAAiB,CAAC;AAGnE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAGhD,OAAO,EAAmE,KAAK,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAC1H,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AACvE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,KAAK,EACV,OAAO,EACP,QAAQ,EAER,GAAG,EACH,WAAW,EAEX,cAAc,EACd,WAAW,EACZ,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,KAAK,CAAC;IACb,MAAM,EAAE,cAAc,CAAC;IACvB,MAAM,EAAE,YAAY,CAAC;IACrB,EAAE,EAAE,UAAU,CAAC;IACf,KAAK,EAAE,QAAQ,CAAC;IAChB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,cAAc,CAAC,EAAE,qBAAqB,CAAC;IACvC,gBAAgB,CAAC,EAAE,SAAS,yBAAyB,EAAE,CAAC;IACxD,GAAG,CAAC,EAAE;QAAE,UAAU,EAAE,MAAM,OAAO,CAAC,eAAe,CAAC,CAAA;KAAE,CAAC;IACrD;;;;OAIG;IACH,cAAc,CAAC,EAAE,CACf,QAAQ,EAAE,cAAc,EACxB,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,KACvD,OAAO,CAAC,OAAO,CAAC,CAAC;CACvB;AAED,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,WAAW,CAAC,QAAQ,CAAC,CAAC;IAC9B,+CAA+C;IAC/C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,GAAG,CAAC;IACb,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,qBAAa,YAAY;IAGX,OAAO,CAAC,QAAQ,CAAC,GAAG;IAFhC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAa;gBAEP,GAAG,EAAE,kBAAkB;IAYpD,uEAAuE;IACjE,KAAK,CAAC,GAAG,EAAE,MAAM;;;;;;;;;;;;;;oBA1Ec,CAAC;uBAAqB,CAAC;wBAC9C,CAAC;mCAAiC,CAAC;oCAEvC,CAAA;wBAAyB,CAAC;+BACpB,CAAC;oCACV,CAAC;oBAAkB,CAAC;;;;;;;;uBAGnB,CAAC;oBAAsB,CAAC;;;;;;;IAmFhC;;OAEG;IACG,GAAG,CACP,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,WAAW,EACvB,IAAI,GAAE,WAAgB,GACrB,OAAO,CAAC,SAAS,CAAC;IA8SrB;;;OAGG;YACW,cAAc;IAoB5B,OAAO,CAAC,iBAAiB;CAY1B"}

package/dist/orchestrator.js

@@ -0,0 +1,351 @@
+/**
+ * The payment orchestrator. This is where the four subsystems meet:
+ * AP2 mandates, the policy engine, the x402 wire protocol, and the India
+ * tax ledger.
+ *
+ * Ordering matters and is deliberate:
+ *
+ *   quote → build cart mandate → policy check → build payment mandate →
+ *   sign → send → record → settle
+ *
+ * The policy check happens after the cart mandate exists but before any
+ * signature. That means a declined payment leaves a signed record of what was
+ * refused and why, with no signature that could be replayed. The audit trail
+ * covers refusals as well as spends, which is what makes it useful in a dispute.
+ */
+import { randomUUID } from "node:crypto";
+import { toHex } from "viem";
+import { randomBytes } from "node:crypto";
+import { hashCartMandate, hashPaymentMandate, payloadHash, } from "./ap2/mandates.js";
+import { X402Client, chainIdFor, PaymentDeclinedError } from "./x402/client.js";
+import { toInrPaise } from "./india/fx.js";
+import { consumeFifo, InsufficientLotsError } from "./india/vda-tax.js";
+import { importAp2PublicKey, issueClosedAp2MandateBundle, verifyAp2SdJwt } from "./ap2/official.js";
+export class Orchestrator {
+    cfg;
+    client;
+    constructor(cfg) {
+        this.cfg = cfg;
+        this.client = new X402Client({
+            signer: cfg.wallet,
+            allowedNetworks: [cfg.asset.network],
+            allowedAssets: [cfg.asset.address],
+            absoluteMaxPerPayment: cfg.absoluteMaxPerPayment,
+            outboundPolicy: cfg.outboundPolicy,
+            authorise: async () => ({ approved: true }), // gate lives in `pay`, below
+            paymentProviders: cfg.paymentProviders,
+        });
+    }
+    /** Price a resource without paying and without touching the ledger. */
+    async quote(url) {
+        const challenge = await this.client.quote(url);
+        if (!challenge)
+            return null;
+        const fx = await this.cfg.fx.usdcInr();
+        return {
+            ...challenge,
+            accepts: challenge.accepts.map((a) => ({
+                ...a,
+                inrPaise: toInrPaise(BigInt(a.maxAmountRequired), this.cfg.asset.decimals, fx.rateScaled).toString(),
+            })),
+        };
+    }
+    /**
+     * Fetch a resource under a specific intent mandate, paying if required.
+     */
+    async pay(url, intentHash, init = {}) {
+        if (await this.cfg.store.isSpendingPaused(this.cfg.userId)) {
+            return {
+                ok: false,
+                spendId: "",
+                status: "blocked",
+                error: "Spending is paused for this account. Resume spending before starting a new payment.",
+            };
+        }
+        const intent = await this.cfg.store.getIntent(intentHash);
+        if (!intent) {
+            return {
+                ok: false,
+                spendId: "",
+                status: "blocked",
+                error: `No mandate found with hash ${intentHash}. List your mandates first.`,
+            };
+        }
+        const walletOwner = /^wallet:(0x[0-9a-fA-F]{40})$/.exec(this.cfg.userId)?.[1];
+        if (walletOwner && intent.mandate.subject.toLowerCase() !== walletOwner.toLowerCase()) {
+            return {
+                ok: false,
+                spendId: "",
+                status: "blocked",
+                error: "This mandate does not belong to the authenticated connected wallet.",
+            };
+        }
+        const spendId = randomUUID();
+        const host = new URL(url).host;
+        const now = Math.floor(Date.now() / 1000);
+        // --- 1. Probe for the price ---
+        const challenge = await this.client.quote(url);
+        if (!challenge) {
+            // Not a paid resource. Pass through without touching the ledger.
+            const res = await fetch(url, init);
+            return {
+                ok: res.ok,
+                spendId,
+                status: "settled",
+                body: await res.text(),
+                contentType: res.headers.get("content-type") ?? undefined,
+                amount: 0n,
+                inrPaise: 0n,
+            };
+        }
+        const requirement = this.selectRequirement(challenge.accepts);
+        if (!requirement) {
+            return {
+                ok: false,
+                spendId,
+                status: "blocked",
+                error: `${host} offers no payment option this wallet can use. It accepts: ` +
+                    challenge.accepts.map((a) => `${a.scheme} on ${a.network}`).join("; ") +
+                    `. This wallet pays ${this.cfg.asset.symbol} on ${this.cfg.asset.network}.`,
+            };
+        }
+        // The standalone X402Client supports Solana signing. The AP2 orchestrator's
+        // EIP-712 cart/payment mandates remain EVM-specific until their schemas are
+        // migrated to chain-neutral account identifiers.
+        if (requirement.network.startsWith("solana:")) {
+            return {
+                ok: false,
+                spendId,
+                status: "blocked",
+                error: "Solana x402 is supported by X402Client, but AP2-orchestrated Solana mandates are not enabled yet.",
+            };
+        }
+        const amount = BigInt(requirement.maxAmountRequired);
+        const fx = await this.cfg.fx.usdcInr();
+        const inrPaise = toInrPaise(amount, this.cfg.asset.decimals, fx.rateScaled);
+        // --- 2. Cart mandate: bind the merchant's quote to the intent ---
+        const chainId = chainIdFor(requirement.network);
+        const cart = {
+            intentHash,
+            payTo: requirement.payTo,
+            resource: requirement.resource || url,
+            description: requirement.description ?? "",
+            amount,
+            asset: this.cfg.asset,
+            quotedAt: now,
+            expiry: now + (requirement.maxTimeoutSeconds || 300),
+            nonce: toHex(randomBytes(32)),
+            chainId,
+        };
+        const cartHash = hashCartMandate(cart);
+        // --- 3. Policy. No signature exists yet at this point. ---
+        const ctx = {
+            now,
+            history: await this.cfg.store.spendsForIntent(intentHash, now - intent.mandate.periodSeconds),
+            medianPriceForResource: await this.cfg.store.medianPriceForResource(this.cfg.userId, cart.resource),
+            medianPriceOverall: await this.cfg.store.medianPriceOverall(this.cfg.userId),
+            knownHosts: await this.cfg.store.knownHosts(this.cfg.userId),
+        };
+        const decision = this.cfg.policy.evaluate(intent, {
+            resource: cart.resource,
+            host,
+            payTo: requirement.payTo,
+            amount,
+            assetAddress: requirement.asset,
+            network: requirement.network,
+        }, ctx);
+        const baseRecord = {
+            id: spendId,
+            userId: this.cfg.userId,
+            intentHash,
+            cartHash,
+            resource: cart.resource,
+            host,
+            payTo: requirement.payTo,
+            amount,
+            asset: this.cfg.asset,
+            inrPaise,
+            fxRateScaled: fx.rateScaled,
+            status: "blocked",
+            createdAt: now,
+        };
+        if (!decision.allowed) {
+            await this.cfg.store.putSpend({
+                ...baseRecord,
+                blockReason: decision.reasons.join(","),
+            });
+            return {
+                ok: false,
+                spendId,
+                status: "blocked",
+                decision,
+                error: decision.explanation,
+            };
+        }
+        if (decision.requiresConfirmation) {
+            const confirmed = await this.cfg.confirmUnusual?.(decision, {
+                host,
+                amount,
+                resource: cart.resource,
+            });
+            if (!confirmed) {
+                await this.cfg.store.putSpend({
+                    ...baseRecord,
+                    blockReason: "AWAITING_CONFIRMATION," + decision.reasons.join(","),
+                });
+                return {
+                    ok: false,
+                    spendId,
+                    status: "blocked",
+                    decision,
+                    error: decision.explanation +
+                        " Confirm explicitly to proceed; this payment was not sent.",
+                };
+            }
+        }
+        // --- 4. Check the on-chain permission actually covers this ---
+        const remaining = await this.cfg.wallet.remainingAllowance();
+        if (remaining !== null && remaining < amount) {
+            await this.cfg.store.putSpend({
+                ...baseRecord,
+                blockReason: "ONCHAIN_ALLOWANCE_EXHAUSTED",
+            });
+            return {
+                ok: false,
+                spendId,
+                status: "blocked",
+                error: `The on-chain spend permission has ${remaining} base units left this period, ` +
+                    `which is less than the ${amount} required. Top up the permission or wait for the period to roll.`,
+            };
+        }
+        const accountBudget = await this.cfg.store.getAccountBudget(this.cfg.userId);
+        if (accountBudget && accountBudget.currency.toUpperCase() !== this.cfg.asset.symbol.toUpperCase()) {
+            await this.cfg.store.putSpend({ ...baseRecord, blockReason: "ACCOUNT_BUDGET_CURRENCY_UNSUPPORTED" });
+            return { ok: false, spendId, status: "blocked", decision, error: `The account budget is denominated in ${accountBudget.currency}, but this payment is ${this.cfg.asset.symbol}. Add a compatible budget before paying.` };
+        }
+        const reservationStart = accountBudget?.periodStart ?? now - intent.mandate.periodSeconds;
+        const reservationLimit = accountBudget ? (accountBudget.amount < intent.mandate.maxPerPeriod ? accountBudget.amount : intent.mandate.maxPerPeriod) : intent.mandate.maxPerPeriod;
+        const reserved = await this.cfg.store.reserveSpend(this.cfg.userId, spendId, amount, reservationStart, reservationLimit, now);
+        if (!reserved) {
+            await this.cfg.store.putSpend({ ...baseRecord, blockReason: "PERIOD_VALUE_CAP_EXCEEDED" });
+            return { ok: false, spendId, status: "blocked", decision, error: "This payment would exceed the shared spending limit for the current period." };
+        }
+        let ap2Evidence;
+        if (intent.ap2) {
+            if (!challenge.ap2CheckoutJwt || !this.cfg.ap2) {
+                await this.cfg.store.putSpend({ ...baseRecord, blockReason: "AP2_CHECKOUT_MANDATE_UNAVAILABLE" });
+                return { ok: false, spendId, status: "blocked", error: "Merchant did not provide a signed AP2 Checkout JWT, or the AP2 issuer is not configured." };
+            }
+            const signer = await this.cfg.ap2.loadSigner();
+            const ap2PublicKey = await importAp2PublicKey(signer.publicJwk);
+            const openCheckoutPayload = await verifyAp2SdJwt(intent.ap2.checkout, ap2PublicKey, "mandate.checkout.open.1");
+            const openPaymentPayload = await verifyAp2SdJwt(intent.ap2.payment, ap2PublicKey, "mandate.payment.open.1");
+            const closed = await issueClosedAp2MandateBundle({
+                open: { checkout: { token: intent.ap2.checkout, issuerJwt: "", disclosures: [], payload: openCheckoutPayload }, payment: { token: intent.ap2.payment, issuerJwt: "", disclosures: [], payload: openPaymentPayload }, issuer: intent.ap2.issuer, issuedAt: intent.ap2.issuedAt, expiresAt: intent.ap2.expiresAt },
+                checkoutJwt: challenge.ap2CheckoutJwt, amount, decimals: this.cfg.asset.decimals, currency: this.cfg.asset.symbol,
+                payee: { id: requirement.payTo, name: requirement.extra?.name ?? host, website: `https://${host}`, payTo: requirement.payTo },
+                paymentInstrument: { id: "erc7710", type: "x402-erc7710", description: "Bound MetaMask delegated payment permission" },
+                issuer: signer.issuer, privateKey: signer.privateKey, publicJwk: signer.publicJwk, keyId: signer.keyId,
+                expiresAt: Math.min(intent.ap2.expiresAt, cart.expiry),
+            });
+            ap2Evidence = { checkoutMandate: closed.checkout.token, paymentMandate: closed.payment.token, checkoutJwt: challenge.ap2CheckoutJwt };
+        }
+        // --- 5. Sign and send ---
+        // Pause is checked again at the last local boundary. A pause committed
+        // while quote/policy work was in flight must prevent a new submission.
+        if (await this.cfg.store.isSpendingPaused(this.cfg.userId)) {
+            await this.cfg.store.putSpend({ ...baseRecord, blockReason: "SPENDING_PAUSED" });
+            return { ok: false, spendId, status: "blocked", decision, error: "Spending was paused before this payment could be sent." };
+        }
+        await this.cfg.store.putSpend({ ...baseRecord, status: "pending", ...(ap2Evidence ? { ap2: ap2Evidence } : {}) });
+        try {
+            const result = await this.client.fetch(url, init, ap2Evidence ? { ap2: ap2Evidence } : {});
+            const paymentMandate = {
+                intentHash,
+                cartHash,
+                payTo: requirement.payTo,
+                amount,
+                asset: this.cfg.asset,
+                payloadHash: payloadHash({ url, amount: amount.toString(), payTo: requirement.payTo }),
+                createdAt: now,
+                nonce: toHex(randomBytes(32)),
+                chainId,
+            };
+            const paymentHash = hashPaymentMandate(paymentMandate);
+            const settled = result.settlement?.success !== false && result.response.ok;
+            await this.cfg.store.updateSpend(spendId, {
+                paymentHash,
+                status: settled ? "settled" : "failed",
+                txHash: result.settlement?.transaction,
+                settledAt: Math.floor(Date.now() / 1000),
+                blockReason: settled ? undefined : result.settlement?.errorReason,
+            });
+            if (settled) {
+                await this.cfg.store.commitSpendReservation(spendId);
+                await this.recordDisposal(spendId, amount, inrPaise);
+            }
+            else {
+                await this.cfg.store.releaseSpendReservation(spendId);
+            }
+            return {
+                ok: settled,
+                spendId,
+                status: settled ? "settled" : "failed",
+                body: await result.response.text(),
+                contentType: result.response.headers.get("content-type") ?? undefined,
+                amount,
+                inrPaise,
+                txHash: result.settlement?.transaction,
+                decision,
+                error: settled
+                    ? undefined
+                    : (result.settlement?.errorReason ??
+                        `Merchant returned ${result.response.status} after payment.`),
+            };
+        }
+        catch (e) {
+            const msg = e instanceof PaymentDeclinedError ? e.message : String(e);
+            if (e instanceof PaymentDeclinedError) {
+                await this.cfg.store.releaseSpendReservation(spendId);
+            }
+            await this.cfg.store.updateSpend(spendId, {
+                status: e instanceof PaymentDeclinedError ? "failed" : "pending",
+                blockReason: msg.slice(0, 500),
+            });
+            return { ok: false, spendId, status: e instanceof PaymentDeclinedError ? "failed" : "pending", error: e instanceof PaymentDeclinedError ? msg : `Payment outcome is uncertain and is being reconciled: ${msg}` };
+        }
+    }
+    /**
+     * Consume cost-basis lots FIFO. Runs after settlement so a failed payment
+     * never disturbs the tax ledger.
+     */
+    async recordDisposal(spendId, amount, inrPaise) {
+        const lots = await this.cfg.store.listLots(this.cfg.userId);
+        try {
+            const disposal = consumeFifo(lots, amount, inrPaise);
+            for (const c of disposal.consumptions) {
+                const lot = lots.find((l) => l.id === c.lotId);
+                await this.cfg.store.updateLotRemaining(lot.id, lot.remaining);
+            }
+        }
+        catch (e) {
+            if (e instanceof InsufficientLotsError) {
+                // Do not fail the payment — it already settled on-chain. Surface the
+                // gap at report time instead, where the user can add a manual lot.
+                console.warn(`[tax] spend ${spendId}: cost basis short by ${e.shortfall} base units. ` +
+                    `Year-end report will flag this.`);
+            }
+            else
+                throw e;
+        }
+    }
+    selectRequirement(accepts) {
+        const viable = accepts.filter((a) => a.scheme === "exact" &&
+            a.network === this.cfg.asset.network &&
+            a.asset?.toLowerCase() === this.cfg.asset.address.toLowerCase());
+        if (viable.length === 0)
+            return null;
+        return viable.reduce((best, cur) => BigInt(cur.maxAmountRequired) < BigInt(best.maxAmountRequired) ? cur : best);
+    }
+}
+//# sourceMappingURL=orchestrator.js.map