@agent-score/commerce 1.2.0 → 1.3.1

package/dist/payment/index.d.mts

@@ -1,5 +1,5 @@
 export { P as PaymentRequiredHeaderInput, a as aliasAmountFields, p as paymentRequiredHeader, w as wwwAuthenticateHeader } from '../wwwauthenticate-CU1eNvMQ.mjs';
-export { P as PaymentSigner, S as SignerNetwork, a as extractPaymentSigner, r as readX402PaymentHeader } from '../signer-Cvdwn6Cs.mjs';
+export { P as PaymentSigner, S as SignerNetwork, a as extractPaymentSigner, r as readX402PaymentHeader } from '../signer-kCAJUZwp.mjs';
 
 interface PaymentRequestInput {
     /** Symbolic rail name (e.g., 'tempo-mainnet', 'x402-base-mainnet') — fills in defaults */
@@ -190,15 +190,15 @@ declare const rails: {
         readonly decimals: 6;
         readonly asset: "0x036CbD53842c5426634e7929541eC2318f3dCF7e";
     };
-    readonly 'x402-solana-mainnet': {
-        readonly method: "x402";
+    readonly 'mpp-solana-mainnet': {
+        readonly method: "solana";
         readonly network: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
         readonly currency: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
         readonly decimals: 6;
         readonly asset: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
     };
-    readonly 'x402-solana-devnet': {
-        readonly method: "x402";
+    readonly 'mpp-solana-devnet': {
+        readonly method: "solana";
         readonly network: "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1";
         readonly currency: "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU";
         readonly decimals: 6;
@@ -244,7 +244,7 @@ interface X402ServerLike {
  */
 declare function registerX402SchemesV1V2(server: X402ServerLike, network: string, scheme: unknown): void;
 
-type X402SymbolicRail = 'x402-base-mainnet' | 'x402-base-sepolia' | 'x402-solana-mainnet' | 'x402-solana-devnet' | 'x402-base-mainnet-upto' | 'x402-base-sepolia-upto';
+type X402SymbolicRail = 'x402-base-mainnet' | 'x402-base-sepolia' | 'x402-base-mainnet-upto' | 'x402-base-sepolia-upto';
 type X402FacilitatorChoice = 'coinbase' | 'http' | unknown;
 interface CreateX402ServerOptions {
     /**
@@ -257,7 +257,7 @@ interface CreateX402ServerOptions {
     facilitator?: X402FacilitatorChoice;
     /**
      * Symbolic rail names to register schemes for. Each gets v1+v2 dual-register applied.
-     * Requires the corresponding peer dep installed (`@x402/evm` for base, `@x402/svm` for solana).
+     * Requires `@x402/evm` peer dep installed.
      */
     rails?: X402SymbolicRail[];
     /** Advanced: register custom {network, scheme} pairs (in addition to or instead of `rails`). */
@@ -293,26 +293,27 @@ interface X402Server {
  *
  *   const server = await createX402Server({
  *     facilitator: 'coinbase',
- *     rails: ['x402-base-mainnet', 'x402-solana-mainnet'],
+ *     rails: ['x402-base-mainnet'],
  *     bazaar: true,
  *   });
  */
 declare function createX402Server(opts?: CreateX402ServerOptions): Promise<X402Server>;
 
 /**
- * `processX402Settle` — single-call x402 verify+settle for merchants.
+ * `processX402Settle`: single-call x402 verify+settle for merchants.
  *
  * Wraps the four x402-server steps every x402-accepting merchant repeats:
- *   1. `buildPaymentRequirements(resourceConfig)` — builds the requirement entries the
+ *   1. `buildPaymentRequirements(resourceConfig)`: builds the requirement entries the
  *      facilitator validates against
- *   2. `enrichExtensions(extension, transportContext)` — folds in Bazaar (or other)
+ *   2. `enrichExtensions(extension, transportContext)`: folds in Bazaar (or other)
  *      extensions for the verify step
- *   3. `processPaymentRequest(payload, resourceConfig, resourceMeta, extensions)` —
+ *   3. `processPaymentRequest(payload, resourceConfig, resourceMeta, extensions)`:
  *      runs verify against the facilitator
- *   4. `settlePayment(payload, matchedRequirement)` — settles on-chain
+ *   4. `settlePayment(payload, matchedRequirement)`: settles on-chain
  *
  * Returns a tagged result so the caller can map errors to merchant-shaped responses
- * without owning the orchestration boilerplate.
+ * without owning the orchestration boilerplate. Use `classifyX402SettleResult` to
+ * map the tagged result to a recommended HTTP response.
  */
 
 interface ProcessX402SettleInput {
@@ -351,20 +352,88 @@ type ProcessX402SettleResult = {
         success: true;
         [key: string]: unknown;
     };
-} | {
+}
+/** No-requirements branch: `buildPaymentRequirements` returned an empty array, so
+ *  there is nothing to verify against. Indicates a merchant-side misconfiguration
+ *  (resource config doesn't match any registered scheme/network).
+ *  Recommended response: log `reason` server-side; map to a controlled 500 to the
+ *  consumer via `classifyX402SettleResult`. */
+ | {
     success: false;
     phase: 'no_requirements';
     reason: string;
-} | {
+}
+/** Verify-failed branch: the facilitator's verify step ran and returned
+ *  `{ success: false, ... }`. Payload is structurally invalid, expired, signed by
+ *  the wrong wallet, or otherwise rejected by facilitator policy.
+ *  Recommended response: log `verifyResult` server-side; map to a controlled 400
+ *  with `payment_proof_invalid` to the consumer via `classifyX402SettleResult`. */
+ | {
     success: false;
     phase: 'verify_failed';
     verifyResult: unknown;
-} | {
+}
+/** Settle-failed branch: verify succeeded but `settlePayment` threw (on-chain
+ *  rejection, RPC outage, facilitator broadcast failure, etc.). The agent's
+ *  credential was valid; funds did not move.
+ *  Recommended response: log raw `error` server-side; map to a controlled 503 with
+ *  `payment_provider_unavailable` to the consumer via `classifyX402SettleResult`. */
+ | {
     success: false;
     phase: 'settle_failed';
     error: unknown;
     matchedRequirement: unknown;
+} | {
+    success: false;
+    /** Facilitator threw an unexpected error during one of the verify-stage calls
+     *  (build requirements, extension enrich, or processPaymentRequest). Most common
+     *  cause: the facilitator client rejects the configured network. Coinbase's CDP
+     *  facilitator throws on Solana devnet because it only supports mainnet networks;
+     *  Stripe's SPT facilitator throws on EVM networks; etc.
+     *  Recommended response: log raw `error` server-side; map to a controlled 503
+     *  with `payment_provider_unavailable` to the consumer via `classifyX402SettleResult`
+     *  so the agent can pick a different rail. */
+    phase: 'facilitator_error';
+    /** Which verify-stage step threw. */
+    step: 'build_requirements' | 'enrich_extensions' | 'process_payment_request';
+    error: unknown;
 };
+/**
+ * The merchant-shaped response for a non-success `ProcessX402SettleResult`.
+ *
+ * `status` / `code` / `message` are safe to send back to the consumer. `nextSteps`
+ * is the agent-instructions block describing what the agent should do next. Raw
+ * facilitator errors stay server-side: do NOT serialize the original `error` /
+ * `verifyResult` / `reason` to the consumer; log them yourself.
+ */
+interface ClassifiedX402Error {
+    status: 400 | 500 | 503;
+    code: 'payment_proof_invalid' | 'payment_provider_unavailable' | 'payment_internal_error';
+    message: string;
+    nextSteps: {
+        action: string;
+        user_message: string;
+        retry_after_seconds?: number;
+    };
+}
+/**
+ * Map a `ProcessX402SettleResult` to the recommended merchant response.
+ *
+ * Returns `null` for `success: true`. For each error phase, returns a controlled
+ * status / code / message / nextSteps tuple. Replaces error-message string-sniffing
+ * with a phase-based dispatch so merchants stop coupling to facilitator-specific
+ * error text.
+ *
+ * Phase mapping:
+ * - `verify_failed` → 400 `payment_proof_invalid` / `regenerate_payment_credential`
+ * - `facilitator_error` → 503 `payment_provider_unavailable` / `try_different_rail`
+ * - `settle_failed` → 503 `payment_provider_unavailable` / `retry_or_swap_method`
+ * - `no_requirements` → 500 `payment_internal_error` / `contact_support`
+ *
+ * Always log the raw `result` server-side before responding; the returned object
+ * is intentionally facilitator-agnostic and never carries raw error detail.
+ */
+declare function classifyX402SettleResult(result: ProcessX402SettleResult): ClassifiedX402Error | null;
 declare function processX402Settle(input: ProcessX402SettleInput): Promise<ProcessX402SettleResult>;
 
 /**
@@ -372,32 +441,25 @@ declare function processX402Settle(input: ProcessX402SettleInput): Promise<Proce
  *
  * Two layers of validation every x402-accepting merchant repeats:
  *
- *   - **Boot-time**: validate the configured `X402_BASE_NETWORK` + `X402_SVM_NETWORK`
- *     env vars are in the supported set, and aren't pointing at the same network
- *     family. Failing loud at boot is much better than per-request "unsupported
+ *   - **Boot-time**: validate the configured `X402_BASE_NETWORK` env var is in the
+ *     supported set. Failing loud at boot is much better than per-request "unsupported
  *     network" errors after a misconfigured deploy.
  *
- *   - **Per-request**: when an x402 X-Payment header arrives, parse the base64
- *     payload, extract the signed network + payTo, validate against the merchant's
- *     accepted networks, validate the payTo address shape per network family, and
- *     check that the payTo was minted by THIS merchant (cache hit). Each step has
- *     its own denial code and `next_steps` shape — getting the message right by
- *     hand across 4 conditions is fiddly.
+ *   - **Per-request**: when an x402 X-Payment header arrives, parse the base64 payload,
+ *     extract the signed network + payTo, validate against the merchant's accepted
+ *     network, validate the payTo address shape, and check that the payTo was minted by
+ *     THIS merchant (cache hit). Each step has its own denial code and `next_steps`
+ *     shape — getting the message right by hand across 4 conditions is fiddly.
  */
 /** CAIP-2 networks the commerce SDK supports for x402 Base (EVM USDC). */
 declare const X402_SUPPORTED_BASE_NETWORKS: Set<string>;
-/** CAIP-2 networks the commerce SDK supports for x402 Solana (SPL Token USDC). */
-declare const X402_SUPPORTED_SVM_NETWORKS: Set<string>;
 interface ValidateX402NetworkConfigInput {
     /** CAIP-2 base network string (e.g. `'eip155:8453'`). */
     baseNetwork: string;
-    /** CAIP-2 SVM network string (e.g. `'solana:5eykt…'`). */
-    svmNetwork: string;
 }
 /**
- * Boot-time guard: throws if either network isn't supported, or if both point at the
- * same family (which would silently route Solana payments to the Base path or vice
- * versa). Call once at module init / server boot.
+ * Boot-time guard: throws if the base network isn't supported. Call once at module
+ * init / server boot.
  *
  * Throws `Error` with a message that names the unsupported value AND lists the valid
  * options — agents tracking down a misconfigured deploy don't need to grep for the
@@ -408,17 +470,11 @@ interface VerifyX402RequestInput {
     /** The incoming Request — `verifyX402Request` reads the X-Payment / payment-signature header. */
     request: Request;
     /** Async lookup that returns true when the address was minted by this merchant
-     *  (typically `piCache.hasAddress`). The cache check defends against agents replaying
-     *  credentials against attacker-controlled deposit addresses. */
+     *  (typically `piCache.hasAddress`). The check validates that the credential's
+     *  deposit address matches one the merchant actually minted. */
     isCachedAddress: (address: string) => Promise<boolean>;
-    /** The merchant's accepted networks per family. Both required — pass the same env
-     *  values you fed to `validateX402NetworkConfig`. */
-    acceptedNetworks: {
-        /** CAIP-2 base network — e.g. `'eip155:8453'`. */
-        base: string;
-        /** CAIP-2 SVM network — e.g. `'solana:5eykt…'`. */
-        svm: string;
-    };
+    /** The merchant's accepted Base network. CAIP-2, e.g. `'eip155:8453'`. */
+    acceptedNetwork: string;
 }
 type VerifyX402RequestResult = {
     ok: true;
@@ -434,8 +490,6 @@ type VerifyX402RequestResult = {
     signedNetwork: string;
     /** The on-chain pay-to address the agent signed for (already validated). */
     signedPayTo: string;
-    /** True when the signed network is Solana — useful for routing settlement. */
-    isSolana: boolean;
 } | {
     ok: false;
     /** Suitable as a JSON body for the merchant's denial response. Includes
@@ -461,8 +515,8 @@ type VerifyX402RequestResult = {
  * confirm the address was minted by this merchant. One call replaces ~45 lines of
  * inline header decode + regex validation + cache lookup.
  *
- * Returns `{ok: true, payload, signedNetwork, signedPayTo, isSolana}` when valid; the
- * caller passes `payload` straight into `processX402Settle`.
+ * Returns `{ok: true, payload, signedNetwork, signedPayTo}` when valid; the caller
+ * passes `payload` straight into `processX402Settle`.
  *
  * Returns `{ok: false, body, status}` when invalid — the merchant just does
  * `return c.json(body, status)` (or framework equivalent).
@@ -472,8 +526,9 @@ type VerifyX402RequestResult = {
  */
 declare function verifyX402Request(input: VerifyX402RequestInput): Promise<VerifyX402RequestResult>;
 
+type SolanaMppNetwork = 'mainnet-beta' | 'devnet' | 'localnet';
 interface CreateMppxServerOptions {
-    /** Symbolic rail config — commerce wires the boilerplate (tempo.charge, mppStripe.charge, etc.). */
+    /** Symbolic rail config — commerce wires the boilerplate (tempo.charge, mppStripe.charge, solana.charge, etc.). */
     rails?: {
         /** One-shot Tempo USDC charge (intent: 'charge'). */
         tempo?: {
@@ -483,6 +538,38 @@ interface CreateMppxServerOptions {
             /** Use Tempo testnet (Moderato). Default false. */
             testnet?: boolean;
         };
+        /**
+         * Solana SPL charge (intent: 'charge'). Bakes createAssociatedTokenIdempotent
+         * into the buyer's tx so payments work against any payTo, fresh or warmed.
+         *
+         * Requires `@solana/mpp` + `@solana/kit` peer deps.
+         * Underlying spec: paymentauth.org/draft-solana-charge-00.
+         */
+        solana?: {
+            /** Base58-encoded Solana recipient public key. */
+            recipient: string;
+            /** SPL token mint (base58). Default: USDC for the selected network. */
+            currency?: string;
+            /** Token decimals. Default 6 (USDC). */
+            decimals?: number;
+            /** Solana network. Default 'mainnet-beta'. */
+            network?: SolanaMppNetwork;
+            /** Custom RPC URL. Default: public RPC for the network. */
+            rpcUrl?: string;
+            /**
+             * Optional fee-payer signer for server-side fee sponsorship. When provided,
+             * the server's pubkey is advertised as `feePayerKey` in the 402 challenge and
+             * the server co-signs settle txs as fee payer (so buyers don't need SOL, and
+             * ATA-creation rent is server-funded). Construct via
+             * `@solana/kit`'s `createKeyPairSignerFromBytes` or equivalent.
+             *
+             * Typed as `unknown` to avoid a hard dep on @solana/kit at this layer; pass any
+             * `TransactionPartialSigner` from `@solana/kit`.
+             */
+            signer?: unknown;
+            /** SPL token program hint (TOKEN_PROGRAM or TOKEN_2022_PROGRAM). Auto-detected when omitted. */
+            tokenProgram?: string;
+        };
         /**
          * Tempo session (intent: 'session') — pay-as-you-go channel for repeated calls or
          * SSE-streamed responses. Vendor brings their own ChannelStore (DB-backed implementation
@@ -539,6 +626,28 @@ interface CreateMppxServerOptions {
  * `mppx` is an OPTIONAL peer dependency — install it only if you accept MPP rails.
  */
 declare function createMppxServer(opts: CreateMppxServerOptions): Promise<unknown>;
+type SolanaChargeRequestArgs = {
+    credential?: unknown;
+    request?: unknown;
+};
+type SolanaChargeMethod = {
+    request?: (args: SolanaChargeRequestArgs) => Promise<unknown>;
+} & Record<string, unknown>;
+/**
+ * Wraps `@solana/mpp.charge()`'s Method so the issued challenge carries a
+ * `finalized` blockhash instead of `confirmed`.
+ *
+ * `@solana/mpp` <= 0.5.2 fetches `getLatestBlockhash` with `commitment: 'confirmed'`
+ * but its broadcast `sendTransaction` sets `skipPreflight: false` without an
+ * overridden `preflightCommitment`. The RPC server's default preflight commitment
+ * is `finalized`, which rejects any blockhash that hasn't yet finalized with a
+ * "Blockhash not found" error. Handing the client a `finalized` blockhash up
+ * front sidesteps the mismatch.
+ *
+ * Trade-off: the signing window shrinks from ~58s (confirmed) to ~46s (finalized).
+ * Fine for agent-driven flows; manual signing flows still have plenty of margin.
+ */
+declare function wrapSolanaChargeWithFinalizedBlockhash(baseMethod: SolanaChargeMethod, rpcUrl: string): SolanaChargeMethod;
 
 interface SettlementHandlers<TPayload, TResult> {
     evm?: (payload: TPayload) => TResult | Promise<TResult>;
@@ -713,4 +822,4 @@ declare function settlementOverrideHeader(overrides: SettlementOverrides): {
     value: string;
 };
 
-export { type BuildIdempotencyKeyInput, type BuildPaymentDirectiveInput, type BuildPaymentHeadersInput, type CreateMppxServerOptions, type CreateX402ServerOptions, type NetworkFamily, type PaymentDirectiveInput, type PaymentHeadersRail, type PaymentHeadersResult, type PaymentRequestInput, type ProcessX402SettleInput, type ProcessX402SettleResult, type RailDefinition, type RailName, SETTLEMENT_OVERRIDES_HEADER, type SettlementHandlers, type SettlementOverrides, type SettlementPayloadLike, USDC, type ValidateX402NetworkConfigInput, type VerifyX402RequestInput, type VerifyX402RequestResult, type X402FacilitatorChoice, type X402Server, type X402ServerLike, type X402SymbolicRail, X402_SUPPORTED_BASE_NETWORKS, X402_SUPPORTED_SVM_NETWORKS, buildIdempotencyKey, buildPaymentDirective, buildPaymentHeaders, buildPaymentRequestBlob, createMppxServer, createX402Server, dispatchSettlementByNetwork, lookupRail, networkFamily, networks, paymentDirective, processX402Settle, rails, registerX402SchemesV1V2, settlementOverrideHeader, validateX402NetworkConfig, verifyX402Request };
+export { type BuildIdempotencyKeyInput, type BuildPaymentDirectiveInput, type BuildPaymentHeadersInput, type ClassifiedX402Error, type CreateMppxServerOptions, type CreateX402ServerOptions, type NetworkFamily, type PaymentDirectiveInput, type PaymentHeadersRail, type PaymentHeadersResult, type PaymentRequestInput, type ProcessX402SettleInput, type ProcessX402SettleResult, type RailDefinition, type RailName, SETTLEMENT_OVERRIDES_HEADER, type SettlementHandlers, type SettlementOverrides, type SettlementPayloadLike, type SolanaMppNetwork, USDC, type ValidateX402NetworkConfigInput, type VerifyX402RequestInput, type VerifyX402RequestResult, type X402FacilitatorChoice, type X402Server, type X402ServerLike, type X402SymbolicRail, X402_SUPPORTED_BASE_NETWORKS, buildIdempotencyKey, buildPaymentDirective, buildPaymentHeaders, buildPaymentRequestBlob, classifyX402SettleResult, createMppxServer, createX402Server, dispatchSettlementByNetwork, lookupRail, networkFamily, networks, paymentDirective, processX402Settle, rails, registerX402SchemesV1V2, settlementOverrideHeader, validateX402NetworkConfig, verifyX402Request, wrapSolanaChargeWithFinalizedBlockhash };