uvd-x402-sdk 2.29.0 → 2.31.0

package/README.md

@@ -526,23 +526,32 @@ app.post('/api/premium', async (req, res) => {
     return res.status(status).set(headers).json(body);
   }
 
-  // Verify and settle
+  // Verify first, then settle when you're ready to fulfill the request
   const client = new FacilitatorClient();
   const requirements = buildPaymentRequirements({
     amount: '1.00',
     recipient: process.env.RECIPIENT,
+    resource: 'https://api.example.com/premium',
+    chainName: 'base',
+    x402Version: payment.x402Version,
   });
 
-  const result = await client.verifyAndSettle(payment, requirements);
+  const verifyResult = await client.verify(payment, requirements);
+  if (!verifyResult.isValid) {
+    return res.status(402).json({ error: verifyResult.invalidReason });
+  }
 
-  if (!result.verified) {
-    return res.status(402).json({ error: result.error });
+  const settleResult = await client.settle(payment, requirements);
+  if (!settleResult.success) {
+    return res.status(500).json({ error: settleResult.error });
   }
 
-  res.json({ data: 'premium content', txHash: result.transactionHash });
+  res.json({ data: 'premium content', txHash: settleResult.transactionHash });
 });
 ```
 
+`createPaymentMiddleware()` and `createHonoMiddleware()` verify by default and attach settlement context for manual control. Use `settlementStrategy: 'before-handler'` only if you intentionally want eager settlement before your handler runs.
+
 ## React
 
 ```tsx

package/dist/backend/index.d.mts

@@ -149,6 +149,52 @@ interface PaymentRequirementsOptions {
     /** x402 version to use */
     x402Version?: X402Version;
 }
+/**
+ * x402 payment option advertised in a 402 response.
+ *
+ * The SDK keeps the response shape richer than the minimal protocol fields so
+ * servers can preserve settlement-critical metadata such as payTo and extra.
+ */
+interface PaymentAcceptance {
+    network: string;
+    asset: string;
+    amount: string;
+    payTo?: string;
+    facilitator?: string;
+    resource?: string;
+    description?: string;
+    mimeType?: string;
+    maxTimeoutSeconds?: number;
+    outputSchema?: unknown;
+    extra?: unknown;
+}
+/**
+ * Verified payment context attached by server middleware.
+ */
+interface VerifiedPaymentState {
+    payment: X402Header;
+    requirements: PaymentRequirements;
+    verifyResult: VerifyResponse;
+    settle: () => Promise<SettleResponse>;
+}
+/**
+ * Shared server middleware options.
+ */
+interface PaymentMiddlewareOptions extends FacilitatorClientOptions {
+    /** Alias for baseUrl to keep middleware options ergonomic */
+    facilitatorUrl?: string;
+    /**
+     * Settlement behavior after verification.
+     * - manual: verify only; caller settles explicitly
+     * - before-handler: settle immediately before calling next()
+     */
+    settlementStrategy?: 'manual' | 'before-handler';
+}
+/**
+ * Custom resolver for selecting the correct payment requirement when multiple
+ * accepts are advertised.
+ */
+type PaymentRequirementResolver = (payment: X402Header, requirements: PaymentRequirements[]) => PaymentRequirements | null | Promise<PaymentRequirements | null>;
 /**
  * Parse X-PAYMENT or PAYMENT-SIGNATURE header value
  *
@@ -448,11 +494,7 @@ declare class FacilitatorClient {
  * ```
  */
 declare function create402Response(requirements: PaymentRequirementsOptions, options?: {
-    accepts?: Array<{
-        network: string;
-        asset: string;
-        amount: string;
-    }>;
+    accepts?: PaymentAcceptance[];
 }): {
     status: 402;
     headers: Record<string, string>;
@@ -476,15 +518,21 @@ declare function create402Response(requirements: PaymentRequirementsOptions, opt
  *   { facilitatorUrl: 'https://facilitator.uvd.xyz' }
  * );
  *
- * app.get('/premium/*', paymentMiddleware, (req, res) => {
+ * app.get('/premium/*', paymentMiddleware, async (req, res) => {
+ *   const settleResult = await req.x402?.settle();
+ *   if (!settleResult?.success) {
+ *     return res.status(500).json({ error: settleResult?.error });
+ *   }
+ *
  *   res.json({ premium: 'data' });
  * });
  * ```
  */
 declare function createPaymentMiddleware(getRequirements: (req: {
     headers: Record<string, string | string[] | undefined>;
-}) => PaymentRequirementsOptions, options?: FacilitatorClientOptions): (req: {
+}) => PaymentRequirementsOptions, options?: PaymentMiddlewareOptions): (req: {
     headers: Record<string, string | string[] | undefined>;
+    x402?: VerifiedPaymentState;
 }, res: {
     status: (code: number) => {
         json: (body: unknown) => void;
@@ -493,6 +541,56 @@ declare function createPaymentMiddleware(getRequirements: (req: {
         };
     };
 }, next: () => void) => Promise<void>;
+/**
+ * Options for creating a Hono x402 payment middleware
+ */
+interface HonoMiddlewareOptions extends PaymentMiddlewareOptions {
+    /** Payment requirements to advertise */
+    accepts: PaymentAcceptance[];
+    /** Response version to advertise (defaults to auto) */
+    x402Version?: X402Version | 'auto';
+    /** Custom requirement resolver for ambiguous multi-accept flows */
+    resolveRequirement?: PaymentRequirementResolver;
+}
+/**
+ * Create a Hono-compatible middleware for x402 payments.
+ *
+ * Handles the x402 payment flow:
+ * 1. Returns 402 with payment requirements if no X-PAYMENT header
+ * 2. Verifies the payment with the facilitator
+ * 3. Optionally settles before the handler when settlementStrategy is set
+ * 4. Passes control to the next handler on success
+ *
+ * @param options - Middleware options with facilitator URL and payment accepts
+ * @returns Hono middleware function
+ *
+ * @example
+ * ```ts
+ * import { createHonoMiddleware } from 'uvd-x402-sdk';
+ *
+ * const paywall = createHonoMiddleware({
+ *   accepts: [{
+ *     network: 'skale-base',
+ *     asset: '0x85889c8c714505E0c94b30fcfcF64fE3Ac8FCb20',
+ *     amount: '1000000',
+ *     payTo: '0xYourWallet',
+ *     extra: { name: 'Bridged USDC (SKALE Bridge)', version: '2' },
+ *   }],
+ * });
+ *
+ * app.get('/api/premium', paywall, (c) => {
+ *   return c.json({ message: 'Premium content!' });
+ * });
+ * ```
+ */
+declare function createHonoMiddleware(options: HonoMiddlewareOptions): (c: {
+    req: {
+        header: (name: string) => string | undefined;
+        url: string;
+    };
+    json: (body: unknown, status?: number) => unknown;
+    set?: (key: string, value: unknown) => void;
+}, next: () => Promise<void>) => Promise<unknown>;
 /**
  * Resource category for discovery
  */
@@ -2035,4 +2133,4 @@ declare class AdvancedEscrowClient {
     refundPostEscrow(paymentInfo: AdvancedPaymentInfo, amount?: string, tokenCollector?: string, collectorData?: string): Promise<AdvancedTransactionResult>;
 }
 
-export { type AdvancedAuthorizationResult, AdvancedEscrowClient, type AdvancedEscrowClientOptions, type AdvancedEscrowContracts, type AdvancedEscrowTaskTier, type AdvancedPaymentInfo, type AdvancedTransactionResult, type AgentId, type AgentIdentity, type AgentRegistration, type AgentRegistrationFile, type AgentService, BASE_MAINNET_CONTRACTS, type BazaarCategory, BazaarClient, type BazaarClientOptions, type BazaarDiscoverOptions, type BazaarDiscoverResponse, type BazaarNetwork, type BazaarRegisterOptions, type BazaarResource, type BazaarToken, type CreateEscrowOptions, DEPOSIT_LIMIT_USDC, type Dispute, type DisputeOutcome, ERC8004_CONTRACTS, ERC8004_EXTENSION_ID, ESCROW_CONTRACTS, ESCROW_TIMEOUT_MS, Erc8004Client, type Erc8004ClientOptions, type Erc8004Network, EscrowClient, type EscrowClientOptions, type EscrowPayment, type EscrowStateResponse, type EscrowStatus, FacilitatorClient, type FacilitatorClientOptions, type FeedbackEntry, type FeedbackParams, type FeedbackRequest, type FeedbackResponse, type IdentityMetadataResponse, type IdentityTotalSupplyResponse, type MetadataEntryParam, OPERATOR_ABI, PAYMENT_INFO_TYPEHASH, type PaymentRequirements, type PaymentRequirementsOptions, type ProofOfPayment, type RefundRequest, type RefundStatus, type RegisterAgentRequest, type RegisterAgentResponse, type ReputationResponse, type ReputationSummary, type RequestRefundOptions, type SettleRequest, type SettleResponse, type SettleResponseWithProof, TIER_TIMINGS, USDC_DOMAIN_NAME, type VerifyRequest, type VerifyResponse, X402_CORS_HEADERS, X402_HEADER_NAMES, ZERO_ADDRESS, buildErc8004PaymentRequirements, buildPaymentRequirements, buildSettleRequest, buildVerifyRequest, canRefundEscrow, canReleaseEscrow, create402Response, createPaymentMiddleware, escrowTimeRemaining, extractPaymentFromHeaders, getCorsHeaders, getEscrowContractsByChainId, getEscrowSupportedChainIds, isEscrowExpired, isEscrowSupportedOnChain, parsePaymentHeader };
+export { type AdvancedAuthorizationResult, AdvancedEscrowClient, type AdvancedEscrowClientOptions, type AdvancedEscrowContracts, type AdvancedEscrowTaskTier, type AdvancedPaymentInfo, type AdvancedTransactionResult, type AgentId, type AgentIdentity, type AgentRegistration, type AgentRegistrationFile, type AgentService, BASE_MAINNET_CONTRACTS, type BazaarCategory, BazaarClient, type BazaarClientOptions, type BazaarDiscoverOptions, type BazaarDiscoverResponse, type BazaarNetwork, type BazaarRegisterOptions, type BazaarResource, type BazaarToken, type CreateEscrowOptions, DEPOSIT_LIMIT_USDC, type Dispute, type DisputeOutcome, ERC8004_CONTRACTS, ERC8004_EXTENSION_ID, ESCROW_CONTRACTS, ESCROW_TIMEOUT_MS, Erc8004Client, type Erc8004ClientOptions, type Erc8004Network, EscrowClient, type EscrowClientOptions, type EscrowPayment, type EscrowStateResponse, type EscrowStatus, FacilitatorClient, type FacilitatorClientOptions, type FeedbackEntry, type FeedbackParams, type FeedbackRequest, type FeedbackResponse, type HonoMiddlewareOptions, type IdentityMetadataResponse, type IdentityTotalSupplyResponse, type MetadataEntryParam, OPERATOR_ABI, PAYMENT_INFO_TYPEHASH, type PaymentAcceptance, type PaymentMiddlewareOptions, type PaymentRequirementResolver, type PaymentRequirements, type PaymentRequirementsOptions, type ProofOfPayment, type RefundRequest, type RefundStatus, type RegisterAgentRequest, type RegisterAgentResponse, type ReputationResponse, type ReputationSummary, type RequestRefundOptions, type SettleRequest, type SettleResponse, type SettleResponseWithProof, TIER_TIMINGS, USDC_DOMAIN_NAME, type VerifiedPaymentState, type VerifyRequest, type VerifyResponse, X402_CORS_HEADERS, X402_HEADER_NAMES, ZERO_ADDRESS, buildErc8004PaymentRequirements, buildPaymentRequirements, buildSettleRequest, buildVerifyRequest, canRefundEscrow, canReleaseEscrow, create402Response, createHonoMiddleware, createPaymentMiddleware, escrowTimeRemaining, extractPaymentFromHeaders, getCorsHeaders, getEscrowContractsByChainId, getEscrowSupportedChainIds, isEscrowExpired, isEscrowSupportedOnChain, parsePaymentHeader };

package/dist/backend/index.d.ts

@@ -149,6 +149,52 @@ interface PaymentRequirementsOptions {
     /** x402 version to use */
     x402Version?: X402Version;
 }
+/**
+ * x402 payment option advertised in a 402 response.
+ *
+ * The SDK keeps the response shape richer than the minimal protocol fields so
+ * servers can preserve settlement-critical metadata such as payTo and extra.
+ */
+interface PaymentAcceptance {
+    network: string;
+    asset: string;
+    amount: string;
+    payTo?: string;
+    facilitator?: string;
+    resource?: string;
+    description?: string;
+    mimeType?: string;
+    maxTimeoutSeconds?: number;
+    outputSchema?: unknown;
+    extra?: unknown;
+}
+/**
+ * Verified payment context attached by server middleware.
+ */
+interface VerifiedPaymentState {
+    payment: X402Header;
+    requirements: PaymentRequirements;
+    verifyResult: VerifyResponse;
+    settle: () => Promise<SettleResponse>;
+}
+/**
+ * Shared server middleware options.
+ */
+interface PaymentMiddlewareOptions extends FacilitatorClientOptions {
+    /** Alias for baseUrl to keep middleware options ergonomic */
+    facilitatorUrl?: string;
+    /**
+     * Settlement behavior after verification.
+     * - manual: verify only; caller settles explicitly
+     * - before-handler: settle immediately before calling next()
+     */
+    settlementStrategy?: 'manual' | 'before-handler';
+}
+/**
+ * Custom resolver for selecting the correct payment requirement when multiple
+ * accepts are advertised.
+ */
+type PaymentRequirementResolver = (payment: X402Header, requirements: PaymentRequirements[]) => PaymentRequirements | null | Promise<PaymentRequirements | null>;
 /**
  * Parse X-PAYMENT or PAYMENT-SIGNATURE header value
  *
@@ -448,11 +494,7 @@ declare class FacilitatorClient {
  * ```
  */
 declare function create402Response(requirements: PaymentRequirementsOptions, options?: {
-    accepts?: Array<{
-        network: string;
-        asset: string;
-        amount: string;
-    }>;
+    accepts?: PaymentAcceptance[];
 }): {
     status: 402;
     headers: Record<string, string>;
@@ -476,15 +518,21 @@ declare function create402Response(requirements: PaymentRequirementsOptions, opt
  *   { facilitatorUrl: 'https://facilitator.uvd.xyz' }
  * );
  *
- * app.get('/premium/*', paymentMiddleware, (req, res) => {
+ * app.get('/premium/*', paymentMiddleware, async (req, res) => {
+ *   const settleResult = await req.x402?.settle();
+ *   if (!settleResult?.success) {
+ *     return res.status(500).json({ error: settleResult?.error });
+ *   }
+ *
  *   res.json({ premium: 'data' });
  * });
  * ```
  */
 declare function createPaymentMiddleware(getRequirements: (req: {
     headers: Record<string, string | string[] | undefined>;
-}) => PaymentRequirementsOptions, options?: FacilitatorClientOptions): (req: {
+}) => PaymentRequirementsOptions, options?: PaymentMiddlewareOptions): (req: {
     headers: Record<string, string | string[] | undefined>;
+    x402?: VerifiedPaymentState;
 }, res: {
     status: (code: number) => {
         json: (body: unknown) => void;
@@ -493,6 +541,56 @@ declare function createPaymentMiddleware(getRequirements: (req: {
         };
     };
 }, next: () => void) => Promise<void>;
+/**
+ * Options for creating a Hono x402 payment middleware
+ */
+interface HonoMiddlewareOptions extends PaymentMiddlewareOptions {
+    /** Payment requirements to advertise */
+    accepts: PaymentAcceptance[];
+    /** Response version to advertise (defaults to auto) */
+    x402Version?: X402Version | 'auto';
+    /** Custom requirement resolver for ambiguous multi-accept flows */
+    resolveRequirement?: PaymentRequirementResolver;
+}
+/**
+ * Create a Hono-compatible middleware for x402 payments.
+ *
+ * Handles the x402 payment flow:
+ * 1. Returns 402 with payment requirements if no X-PAYMENT header
+ * 2. Verifies the payment with the facilitator
+ * 3. Optionally settles before the handler when settlementStrategy is set
+ * 4. Passes control to the next handler on success
+ *
+ * @param options - Middleware options with facilitator URL and payment accepts
+ * @returns Hono middleware function
+ *
+ * @example
+ * ```ts
+ * import { createHonoMiddleware } from 'uvd-x402-sdk';
+ *
+ * const paywall = createHonoMiddleware({
+ *   accepts: [{
+ *     network: 'skale-base',
+ *     asset: '0x85889c8c714505E0c94b30fcfcF64fE3Ac8FCb20',
+ *     amount: '1000000',
+ *     payTo: '0xYourWallet',
+ *     extra: { name: 'Bridged USDC (SKALE Bridge)', version: '2' },
+ *   }],
+ * });
+ *
+ * app.get('/api/premium', paywall, (c) => {
+ *   return c.json({ message: 'Premium content!' });
+ * });
+ * ```
+ */
+declare function createHonoMiddleware(options: HonoMiddlewareOptions): (c: {
+    req: {
+        header: (name: string) => string | undefined;
+        url: string;
+    };
+    json: (body: unknown, status?: number) => unknown;
+    set?: (key: string, value: unknown) => void;
+}, next: () => Promise<void>) => Promise<unknown>;
 /**
  * Resource category for discovery
  */
@@ -2035,4 +2133,4 @@ declare class AdvancedEscrowClient {
     refundPostEscrow(paymentInfo: AdvancedPaymentInfo, amount?: string, tokenCollector?: string, collectorData?: string): Promise<AdvancedTransactionResult>;
 }
 
-export { type AdvancedAuthorizationResult, AdvancedEscrowClient, type AdvancedEscrowClientOptions, type AdvancedEscrowContracts, type AdvancedEscrowTaskTier, type AdvancedPaymentInfo, type AdvancedTransactionResult, type AgentId, type AgentIdentity, type AgentRegistration, type AgentRegistrationFile, type AgentService, BASE_MAINNET_CONTRACTS, type BazaarCategory, BazaarClient, type BazaarClientOptions, type BazaarDiscoverOptions, type BazaarDiscoverResponse, type BazaarNetwork, type BazaarRegisterOptions, type BazaarResource, type BazaarToken, type CreateEscrowOptions, DEPOSIT_LIMIT_USDC, type Dispute, type DisputeOutcome, ERC8004_CONTRACTS, ERC8004_EXTENSION_ID, ESCROW_CONTRACTS, ESCROW_TIMEOUT_MS, Erc8004Client, type Erc8004ClientOptions, type Erc8004Network, EscrowClient, type EscrowClientOptions, type EscrowPayment, type EscrowStateResponse, type EscrowStatus, FacilitatorClient, type FacilitatorClientOptions, type FeedbackEntry, type FeedbackParams, type FeedbackRequest, type FeedbackResponse, type IdentityMetadataResponse, type IdentityTotalSupplyResponse, type MetadataEntryParam, OPERATOR_ABI, PAYMENT_INFO_TYPEHASH, type PaymentRequirements, type PaymentRequirementsOptions, type ProofOfPayment, type RefundRequest, type RefundStatus, type RegisterAgentRequest, type RegisterAgentResponse, type ReputationResponse, type ReputationSummary, type RequestRefundOptions, type SettleRequest, type SettleResponse, type SettleResponseWithProof, TIER_TIMINGS, USDC_DOMAIN_NAME, type VerifyRequest, type VerifyResponse, X402_CORS_HEADERS, X402_HEADER_NAMES, ZERO_ADDRESS, buildErc8004PaymentRequirements, buildPaymentRequirements, buildSettleRequest, buildVerifyRequest, canRefundEscrow, canReleaseEscrow, create402Response, createPaymentMiddleware, escrowTimeRemaining, extractPaymentFromHeaders, getCorsHeaders, getEscrowContractsByChainId, getEscrowSupportedChainIds, isEscrowExpired, isEscrowSupportedOnChain, parsePaymentHeader };
+export { type AdvancedAuthorizationResult, AdvancedEscrowClient, type AdvancedEscrowClientOptions, type AdvancedEscrowContracts, type AdvancedEscrowTaskTier, type AdvancedPaymentInfo, type AdvancedTransactionResult, type AgentId, type AgentIdentity, type AgentRegistration, type AgentRegistrationFile, type AgentService, BASE_MAINNET_CONTRACTS, type BazaarCategory, BazaarClient, type BazaarClientOptions, type BazaarDiscoverOptions, type BazaarDiscoverResponse, type BazaarNetwork, type BazaarRegisterOptions, type BazaarResource, type BazaarToken, type CreateEscrowOptions, DEPOSIT_LIMIT_USDC, type Dispute, type DisputeOutcome, ERC8004_CONTRACTS, ERC8004_EXTENSION_ID, ESCROW_CONTRACTS, ESCROW_TIMEOUT_MS, Erc8004Client, type Erc8004ClientOptions, type Erc8004Network, EscrowClient, type EscrowClientOptions, type EscrowPayment, type EscrowStateResponse, type EscrowStatus, FacilitatorClient, type FacilitatorClientOptions, type FeedbackEntry, type FeedbackParams, type FeedbackRequest, type FeedbackResponse, type HonoMiddlewareOptions, type IdentityMetadataResponse, type IdentityTotalSupplyResponse, type MetadataEntryParam, OPERATOR_ABI, PAYMENT_INFO_TYPEHASH, type PaymentAcceptance, type PaymentMiddlewareOptions, type PaymentRequirementResolver, type PaymentRequirements, type PaymentRequirementsOptions, type ProofOfPayment, type RefundRequest, type RefundStatus, type RegisterAgentRequest, type RegisterAgentResponse, type ReputationResponse, type ReputationSummary, type RequestRefundOptions, type SettleRequest, type SettleResponse, type SettleResponseWithProof, TIER_TIMINGS, USDC_DOMAIN_NAME, type VerifiedPaymentState, type VerifyRequest, type VerifyResponse, X402_CORS_HEADERS, X402_HEADER_NAMES, ZERO_ADDRESS, buildErc8004PaymentRequirements, buildPaymentRequirements, buildSettleRequest, buildVerifyRequest, canRefundEscrow, canReleaseEscrow, create402Response, createHonoMiddleware, createPaymentMiddleware, escrowTimeRemaining, extractPaymentFromHeaders, getCorsHeaders, getEscrowContractsByChainId, getEscrowSupportedChainIds, isEscrowExpired, isEscrowSupportedOnChain, parsePaymentHeader };