@agent-score/commerce 2.0.0 → 2.0.1

package/dist/payment/index.d.mts

@@ -552,6 +552,47 @@ type SolanaChargeMethod = {
  * Fine for agent-driven flows; manual signing flows still have plenty of margin.
  */
 declare function wrapSolanaChargeWithFinalizedBlockhash(baseMethod: SolanaChargeMethod, rpcUrl: string): SolanaChargeMethod;
+/**
+ * Result shape of `composeMppxRequest`. mppx's `mppx.compose(...)(request)`
+ * resolves to one of two variants — type-narrowed here so consumers can
+ * `if (result.status === 200) { result.withReceipt(...) }` without an
+ * `as any` cast.
+ */
+type MppxComposeResult = {
+    status: 200;
+    /** Wraps a Response with the `Payment-Receipt` header attached. */
+    withReceipt: (response: Response) => Response;
+    [k: string]: unknown;
+} | {
+    status: 402;
+    /** The 402 challenge Response mppx emitted (carries WWW-Authenticate). */
+    challenge: Response;
+    [k: string]: unknown;
+};
+/**
+ * Run `mppx.compose(...intents)(request)` with a typed return. Replaces the
+ * `(mppx as any).compose(...intents)(request)` cast every hand-rolled
+ * `composeMppx` hook ends up writing.
+ *
+ * @example
+ * ```ts
+ * const result = await composeMppxRequest(mppx, [
+ *   ['tempo/charge', { amount, currency, decimals, recipient }],
+ *   ['stripe/charge', { amount, currency: 'usd', decimals: 2 }],
+ * ], ctx.request.raw);
+ * if (result.status === 402) return { status: 402, headers: mppxChallengeHeaders(result) };
+ * return { status: 200, raw: result };
+ * ```
+ */
+declare function composeMppxRequest(mppx: unknown, intents: readonly unknown[], request: Request): Promise<MppxComposeResult>;
+/**
+ * Extract the 402 challenge response's headers as a plain `Record<string, string>`,
+ * the shape `MppxComposeOutcome.headers` accepts. Wraps the one-liner every
+ * hand-rolled compose hook writes.
+ */
+declare function mppxChallengeHeaders(result: {
+    challenge: Response;
+}): Record<string, string>;
 
 /**
  * Detect which payment-protocol family the inbound request carries.
@@ -838,4 +879,4 @@ declare function lazyMppxServer(opts: {
     secretKey: string;
 }): () => Promise<unknown>;
 
-export { type ClassifiedX402Error, type MppxRailSpec, type NetworkFamily, type PaymentHeadersRail, type PaymentHeadersResult, type ProcessX402SettleResult, type RailDefinition, type RailName, SETTLEMENT_OVERRIDES_HEADER, type SettlementHandlers, type SettlementOverrides, type SettlementPayloadLike, SignerNetwork, SolanaMppRailSpec, StripeRailSpec, TempoRailSpec, TempoSessionRailSpec, USDC, type VerifyX402RequestResult, X402BaseRailSpec, X402Server, type X402ServerLike, X402_SUPPORTED_BASE_NETWORKS, type ZeroSettleRail, type ZeroSettleResult, buildIdempotencyKey, buildPaymentDirective, buildPaymentHeaders, buildPaymentRequestBlob, classifyOrchestrationError, classifyX402SettleResult, createMppxServer, detectRailFromHeaders, dispatchSettlementByNetwork, lazyMppxServer, lazyX402Server, lookupRail, networkFamily, networks, paymentDirective, processX402Settle, rails, registerX402SchemesV1V2, settlementOverrideHeader, validateX402NetworkConfig, verifyX402Request, wrapSolanaChargeWithFinalizedBlockhash, zeroAmountCarveOut };
+export { type ClassifiedX402Error, type MppxComposeResult, type MppxRailSpec, type NetworkFamily, type PaymentHeadersRail, type PaymentHeadersResult, type ProcessX402SettleResult, type RailDefinition, type RailName, SETTLEMENT_OVERRIDES_HEADER, type SettlementHandlers, type SettlementOverrides, type SettlementPayloadLike, SignerNetwork, SolanaMppRailSpec, StripeRailSpec, TempoRailSpec, TempoSessionRailSpec, USDC, type VerifyX402RequestResult, X402BaseRailSpec, X402Server, type X402ServerLike, X402_SUPPORTED_BASE_NETWORKS, type ZeroSettleRail, type ZeroSettleResult, buildIdempotencyKey, buildPaymentDirective, buildPaymentHeaders, buildPaymentRequestBlob, classifyOrchestrationError, classifyX402SettleResult, composeMppxRequest, createMppxServer, detectRailFromHeaders, dispatchSettlementByNetwork, lazyMppxServer, lazyX402Server, lookupRail, mppxChallengeHeaders, networkFamily, networks, paymentDirective, processX402Settle, rails, registerX402SchemesV1V2, settlementOverrideHeader, validateX402NetworkConfig, verifyX402Request, wrapSolanaChargeWithFinalizedBlockhash, zeroAmountCarveOut };

package/dist/payment/index.d.ts

@@ -552,6 +552,47 @@ type SolanaChargeMethod = {
  * Fine for agent-driven flows; manual signing flows still have plenty of margin.
  */
 declare function wrapSolanaChargeWithFinalizedBlockhash(baseMethod: SolanaChargeMethod, rpcUrl: string): SolanaChargeMethod;
+/**
+ * Result shape of `composeMppxRequest`. mppx's `mppx.compose(...)(request)`
+ * resolves to one of two variants — type-narrowed here so consumers can
+ * `if (result.status === 200) { result.withReceipt(...) }` without an
+ * `as any` cast.
+ */
+type MppxComposeResult = {
+    status: 200;
+    /** Wraps a Response with the `Payment-Receipt` header attached. */
+    withReceipt: (response: Response) => Response;
+    [k: string]: unknown;
+} | {
+    status: 402;
+    /** The 402 challenge Response mppx emitted (carries WWW-Authenticate). */
+    challenge: Response;
+    [k: string]: unknown;
+};
+/**
+ * Run `mppx.compose(...intents)(request)` with a typed return. Replaces the
+ * `(mppx as any).compose(...intents)(request)` cast every hand-rolled
+ * `composeMppx` hook ends up writing.
+ *
+ * @example
+ * ```ts
+ * const result = await composeMppxRequest(mppx, [
+ *   ['tempo/charge', { amount, currency, decimals, recipient }],
+ *   ['stripe/charge', { amount, currency: 'usd', decimals: 2 }],
+ * ], ctx.request.raw);
+ * if (result.status === 402) return { status: 402, headers: mppxChallengeHeaders(result) };
+ * return { status: 200, raw: result };
+ * ```
+ */
+declare function composeMppxRequest(mppx: unknown, intents: readonly unknown[], request: Request): Promise<MppxComposeResult>;
+/**
+ * Extract the 402 challenge response's headers as a plain `Record<string, string>`,
+ * the shape `MppxComposeOutcome.headers` accepts. Wraps the one-liner every
+ * hand-rolled compose hook writes.
+ */
+declare function mppxChallengeHeaders(result: {
+    challenge: Response;
+}): Record<string, string>;
 
 /**
  * Detect which payment-protocol family the inbound request carries.
@@ -838,4 +879,4 @@ declare function lazyMppxServer(opts: {
     secretKey: string;
 }): () => Promise<unknown>;
 
-export { type ClassifiedX402Error, type MppxRailSpec, type NetworkFamily, type PaymentHeadersRail, type PaymentHeadersResult, type ProcessX402SettleResult, type RailDefinition, type RailName, SETTLEMENT_OVERRIDES_HEADER, type SettlementHandlers, type SettlementOverrides, type SettlementPayloadLike, SignerNetwork, SolanaMppRailSpec, StripeRailSpec, TempoRailSpec, TempoSessionRailSpec, USDC, type VerifyX402RequestResult, X402BaseRailSpec, X402Server, type X402ServerLike, X402_SUPPORTED_BASE_NETWORKS, type ZeroSettleRail, type ZeroSettleResult, buildIdempotencyKey, buildPaymentDirective, buildPaymentHeaders, buildPaymentRequestBlob, classifyOrchestrationError, classifyX402SettleResult, createMppxServer, detectRailFromHeaders, dispatchSettlementByNetwork, lazyMppxServer, lazyX402Server, lookupRail, networkFamily, networks, paymentDirective, processX402Settle, rails, registerX402SchemesV1V2, settlementOverrideHeader, validateX402NetworkConfig, verifyX402Request, wrapSolanaChargeWithFinalizedBlockhash, zeroAmountCarveOut };
+export { type ClassifiedX402Error, type MppxComposeResult, type MppxRailSpec, type NetworkFamily, type PaymentHeadersRail, type PaymentHeadersResult, type ProcessX402SettleResult, type RailDefinition, type RailName, SETTLEMENT_OVERRIDES_HEADER, type SettlementHandlers, type SettlementOverrides, type SettlementPayloadLike, SignerNetwork, SolanaMppRailSpec, StripeRailSpec, TempoRailSpec, TempoSessionRailSpec, USDC, type VerifyX402RequestResult, X402BaseRailSpec, X402Server, type X402ServerLike, X402_SUPPORTED_BASE_NETWORKS, type ZeroSettleRail, type ZeroSettleResult, buildIdempotencyKey, buildPaymentDirective, buildPaymentHeaders, buildPaymentRequestBlob, classifyOrchestrationError, classifyX402SettleResult, composeMppxRequest, createMppxServer, detectRailFromHeaders, dispatchSettlementByNetwork, lazyMppxServer, lazyX402Server, lookupRail, mppxChallengeHeaders, networkFamily, networks, paymentDirective, processX402Settle, rails, registerX402SchemesV1V2, settlementOverrideHeader, validateX402NetworkConfig, verifyX402Request, wrapSolanaChargeWithFinalizedBlockhash, zeroAmountCarveOut };

package/dist/payment/index.js

@@ -32,6 +32,7 @@ __export(payment_exports, {
   buildX402AcceptsFor402: () => buildX402AcceptsFor402,
   classifyOrchestrationError: () => classifyOrchestrationError,
   classifyX402SettleResult: () => classifyX402SettleResult,
+  composeMppxRequest: () => composeMppxRequest,
   createMppxServer: () => createMppxServer,
   createX402Server: () => createX402Server,
   detectRailFromHeaders: () => detectRailFromHeaders,
@@ -44,6 +45,7 @@ __export(payment_exports, {
   lazyX402Server: () => lazyX402Server,
   loadSolanaFeePayer: () => loadSolanaFeePayer,
   lookupRail: () => lookupRail,
+  mppxChallengeHeaders: () => mppxChallengeHeaders,
   networkFamily: () => networkFamily,
   networks: () => networks,
   paymentDirective: () => paymentDirective,
@@ -807,6 +809,21 @@ function wrapSolanaChargeWithFinalizedBlockhash(baseMethod, rpcUrl) {
     }
   };
 }
+async function composeMppxRequest(mppx, intents, request) {
+  if (!mppx || typeof mppx !== "object" || !("compose" in mppx)) {
+    throw new Error("composeMppxRequest: argument is not an mppx server instance");
+  }
+  const compose = mppx.compose;
+  if (typeof compose !== "function") {
+    throw new Error("composeMppxRequest: mppx.compose is not a function");
+  }
+  const typedCompose = compose;
+  const handler = typedCompose.apply(mppx, [...intents]);
+  return handler(request);
+}
+function mppxChallengeHeaders(result) {
+  return Object.fromEntries(result.challenge.headers);
+}
 
 // src/payment/dispatch.ts
 function detectRailFromHeaders(headers) {
@@ -1232,6 +1249,7 @@ async function loadSolanaFeePayer(opts) {
   buildX402AcceptsFor402,
   classifyOrchestrationError,
   classifyX402SettleResult,
+  composeMppxRequest,
   createMppxServer,
   createX402Server,
   detectRailFromHeaders,
@@ -1244,6 +1262,7 @@ async function loadSolanaFeePayer(opts) {
   lazyX402Server,
   loadSolanaFeePayer,
   lookupRail,
+  mppxChallengeHeaders,
   networkFamily,
   networks,
   paymentDirective,