@agent-score/commerce 1.3.0 → 1.3.2

package/dist/payment/index.d.mts

@@ -298,6 +298,31 @@ interface X402Server {
  *   });
  */
 declare function createX402Server(opts?: CreateX402ServerOptions): Promise<X402Server>;
+interface BuildX402AcceptsForOptions {
+    network: string;
+    price: string;
+    payTo: string;
+    scheme?: string;
+    maxTimeoutSeconds?: number;
+    extensions?: string[];
+}
+/**
+ * Build x402 `accepts[]` entries for a 402 challenge body.
+ *
+ * Wraps `server.buildPaymentRequirements(...)` so merchants don't have to:
+ *
+ * 1. Construct the resource-config object themselves
+ * 2. Remember to serialize each Pydantic-equivalent requirement back to a
+ *    plain object before stitching it into the 402 body
+ * 3. Hardcode `extra` (which differs by the actual on-chain contract — base
+ *    mainnet USDC has `name: "USD Coin"`, base sepolia USDC has `name: "USDC"`;
+ *    EIP-712 domain hashes differ, so getting this wrong silently breaks every
+ *    signature verify at the facilitator)
+ *
+ * Returns a list of plain objects in the shape that x402 expects on the wire —
+ * drop them straight into the `accepts` field of the 402 challenge body.
+ */
+declare function buildX402AcceptsFor402(server: X402Server, opts: BuildX402AcceptsForOptions): Promise<unknown[]>;
 
 /**
  * `processX402Settle`: single-call x402 verify+settle for merchants.
@@ -626,6 +651,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>;
@@ -800,4 +847,4 @@ declare function settlementOverrideHeader(overrides: SettlementOverrides): {
     value: string;
 };
 
-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 };
+export { type BuildIdempotencyKeyInput, type BuildPaymentDirectiveInput, type BuildPaymentHeadersInput, type BuildX402AcceptsForOptions, 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, buildX402AcceptsFor402, classifyX402SettleResult, createMppxServer, createX402Server, dispatchSettlementByNetwork, lookupRail, networkFamily, networks, paymentDirective, processX402Settle, rails, registerX402SchemesV1V2, settlementOverrideHeader, validateX402NetworkConfig, verifyX402Request, wrapSolanaChargeWithFinalizedBlockhash };

package/dist/payment/index.d.ts

@@ -298,6 +298,31 @@ interface X402Server {
  *   });
  */
 declare function createX402Server(opts?: CreateX402ServerOptions): Promise<X402Server>;
+interface BuildX402AcceptsForOptions {
+    network: string;
+    price: string;
+    payTo: string;
+    scheme?: string;
+    maxTimeoutSeconds?: number;
+    extensions?: string[];
+}
+/**
+ * Build x402 `accepts[]` entries for a 402 challenge body.
+ *
+ * Wraps `server.buildPaymentRequirements(...)` so merchants don't have to:
+ *
+ * 1. Construct the resource-config object themselves
+ * 2. Remember to serialize each Pydantic-equivalent requirement back to a
+ *    plain object before stitching it into the 402 body
+ * 3. Hardcode `extra` (which differs by the actual on-chain contract — base
+ *    mainnet USDC has `name: "USD Coin"`, base sepolia USDC has `name: "USDC"`;
+ *    EIP-712 domain hashes differ, so getting this wrong silently breaks every
+ *    signature verify at the facilitator)
+ *
+ * Returns a list of plain objects in the shape that x402 expects on the wire —
+ * drop them straight into the `accepts` field of the 402 challenge body.
+ */
+declare function buildX402AcceptsFor402(server: X402Server, opts: BuildX402AcceptsForOptions): Promise<unknown[]>;
 
 /**
  * `processX402Settle`: single-call x402 verify+settle for merchants.
@@ -626,6 +651,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>;
@@ -800,4 +847,4 @@ declare function settlementOverrideHeader(overrides: SettlementOverrides): {
     value: string;
 };
 
-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 };
+export { type BuildIdempotencyKeyInput, type BuildPaymentDirectiveInput, type BuildPaymentHeadersInput, type BuildX402AcceptsForOptions, 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, buildX402AcceptsFor402, classifyX402SettleResult, createMppxServer, createX402Server, dispatchSettlementByNetwork, lookupRail, networkFamily, networks, paymentDirective, processX402Settle, rails, registerX402SchemesV1V2, settlementOverrideHeader, validateX402NetworkConfig, verifyX402Request, wrapSolanaChargeWithFinalizedBlockhash };

package/dist/payment/index.js

@@ -28,6 +28,7 @@ __export(payment_exports, {
   buildPaymentDirective: () => buildPaymentDirective,
   buildPaymentHeaders: () => buildPaymentHeaders,
   buildPaymentRequestBlob: () => buildPaymentRequestBlob,
+  buildX402AcceptsFor402: () => buildX402AcceptsFor402,
   classifyX402SettleResult: () => classifyX402SettleResult,
   createMppxServer: () => createMppxServer,
   createX402Server: () => createX402Server,
@@ -45,6 +46,7 @@ __export(payment_exports, {
   settlementOverrideHeader: () => settlementOverrideHeader,
   validateX402NetworkConfig: () => validateX402NetworkConfig,
   verifyX402Request: () => verifyX402Request,
+  wrapSolanaChargeWithFinalizedBlockhash: () => wrapSolanaChargeWithFinalizedBlockhash,
   wwwAuthenticateHeader: () => wwwAuthenticateHeader
 });
 module.exports = __toCommonJS(payment_exports);
@@ -279,6 +281,19 @@ async function createX402Server(opts = {}) {
   }
   return server;
 }
+async function buildX402AcceptsFor402(server, opts) {
+  const requirements = await server.buildPaymentRequirements(
+    {
+      scheme: opts.scheme ?? "exact",
+      network: opts.network,
+      price: opts.price,
+      payTo: opts.payTo,
+      maxTimeoutSeconds: opts.maxTimeoutSeconds ?? 300
+    },
+    opts.extensions
+  );
+  return Array.isArray(requirements) ? requirements : [];
+}
 async function dynamicImport(moduleName) {
   try {
     return await import(moduleName);
@@ -547,17 +562,17 @@ async function createMppxServer(opts) {
     const network = s.network ?? "mainnet-beta";
     const defaultMint = network === "mainnet-beta" ? USDC.solana.mainnet.mint : USDC.solana.devnet.mint;
     const defaultDecimals = network === "mainnet-beta" ? USDC.solana.mainnet.decimals : USDC.solana.devnet.decimals;
-    methods.push(
-      solanaMpp.charge({
-        recipient: s.recipient,
-        currency: s.currency ?? defaultMint,
-        decimals: s.decimals ?? defaultDecimals,
-        network,
-        ...s.rpcUrl ? { rpcUrl: s.rpcUrl } : {},
-        ...s.signer ? { signer: s.signer } : {},
-        ...s.tokenProgram ? { tokenProgram: s.tokenProgram } : {}
-      })
-    );
+    const baseMethod = solanaMpp.charge({
+      recipient: s.recipient,
+      currency: s.currency ?? defaultMint,
+      decimals: s.decimals ?? defaultDecimals,
+      network,
+      ...s.rpcUrl ? { rpcUrl: s.rpcUrl } : {},
+      ...s.signer ? { signer: s.signer } : {},
+      ...s.tokenProgram ? { tokenProgram: s.tokenProgram } : {}
+    });
+    const rpcUrl = s.rpcUrl ?? (network === "mainnet-beta" ? "https://api.mainnet-beta.solana.com" : network === "devnet" ? "https://api.devnet.solana.com" : "http://localhost:8899");
+    methods.push(wrapSolanaChargeWithFinalizedBlockhash(baseMethod, rpcUrl));
   }
   if (opts.rails?.stripe) {
     const stripeMethod = await createMppxStripe(opts.rails.stripe);
@@ -572,6 +587,37 @@ async function dynamicImport2(moduleName) {
     return null;
   }
 }
+function wrapSolanaChargeWithFinalizedBlockhash(baseMethod, rpcUrl) {
+  return {
+    ...baseMethod,
+    async request(args) {
+      const orig = await baseMethod.request(args);
+      if (args.credential || !orig || typeof orig !== "object") return orig;
+      try {
+        const res = await fetch(rpcUrl, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({
+            id: 1,
+            jsonrpc: "2.0",
+            method: "getLatestBlockhash",
+            params: [{ commitment: "finalized" }]
+          })
+        });
+        const data = await res.json();
+        const finalized = data?.result?.value?.blockhash;
+        if (finalized) {
+          return {
+            ...orig,
+            methodDetails: { ...orig.methodDetails ?? {}, recentBlockhash: finalized }
+          };
+        }
+      } catch {
+      }
+      return orig;
+    }
+  };
+}
 
 // src/payment/dispatch.ts
 async function dispatchSettlementByNetwork(payload, handlers) {
@@ -757,6 +803,7 @@ function settlementOverrideHeader(overrides) {
   buildPaymentDirective,
   buildPaymentHeaders,
   buildPaymentRequestBlob,
+  buildX402AcceptsFor402,
   classifyX402SettleResult,
   createMppxServer,
   createX402Server,
@@ -774,6 +821,7 @@ function settlementOverrideHeader(overrides) {
   settlementOverrideHeader,
   validateX402NetworkConfig,
   verifyX402Request,
+  wrapSolanaChargeWithFinalizedBlockhash,
   wwwAuthenticateHeader
 });
 //# sourceMappingURL=index.js.map