x402-express-mantle 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (127) hide show
  1. package/README.md +155 -0
  2. package/lib/cjs/client/index.d.ts +243 -0
  3. package/lib/cjs/client/index.js +413 -0
  4. package/lib/cjs/client/index.js.map +1 -0
  5. package/lib/cjs/exact/client/index.d.ts +37 -0
  6. package/lib/cjs/exact/client/index.js +281 -0
  7. package/lib/cjs/exact/client/index.js.map +1 -0
  8. package/lib/cjs/exact/facilitator/index.d.ts +110 -0
  9. package/lib/cjs/exact/facilitator/index.js +714 -0
  10. package/lib/cjs/exact/facilitator/index.js.map +1 -0
  11. package/lib/cjs/exact/server/index.d.ts +87 -0
  12. package/lib/cjs/exact/server/index.js +209 -0
  13. package/lib/cjs/exact/server/index.js.map +1 -0
  14. package/lib/cjs/exact/v1/client/index.d.ts +33 -0
  15. package/lib/cjs/exact/v1/client/index.js +169 -0
  16. package/lib/cjs/exact/v1/client/index.js.map +1 -0
  17. package/lib/cjs/exact/v1/facilitator/index.d.ts +71 -0
  18. package/lib/cjs/exact/v1/facilitator/index.js +384 -0
  19. package/lib/cjs/exact/v1/facilitator/index.js.map +1 -0
  20. package/lib/cjs/facilitator/index.d.ts +192 -0
  21. package/lib/cjs/facilitator/index.js +398 -0
  22. package/lib/cjs/facilitator/index.js.map +1 -0
  23. package/lib/cjs/http/index.d.ts +52 -0
  24. package/lib/cjs/http/index.js +827 -0
  25. package/lib/cjs/http/index.js.map +1 -0
  26. package/lib/cjs/index.d.ts +145 -0
  27. package/lib/cjs/index.js +314 -0
  28. package/lib/cjs/index.js.map +1 -0
  29. package/lib/cjs/mechanisms-CzuGzYsS.d.ts +270 -0
  30. package/lib/cjs/scheme-MoBRXFM8.d.ts +29 -0
  31. package/lib/cjs/server/index.d.ts +2 -0
  32. package/lib/cjs/server/index.js +1305 -0
  33. package/lib/cjs/server/index.js.map +1 -0
  34. package/lib/cjs/signer-5OVDxViv.d.ts +79 -0
  35. package/lib/cjs/signer-BMkbhFYE.d.ts +123 -0
  36. package/lib/cjs/types/index.d.ts +1 -0
  37. package/lib/cjs/types/index.js +66 -0
  38. package/lib/cjs/types/index.js.map +1 -0
  39. package/lib/cjs/types/v1/index.d.ts +1 -0
  40. package/lib/cjs/types/v1/index.js +19 -0
  41. package/lib/cjs/types/v1/index.js.map +1 -0
  42. package/lib/cjs/utils/index.d.ts +48 -0
  43. package/lib/cjs/utils/index.js +116 -0
  44. package/lib/cjs/utils/index.js.map +1 -0
  45. package/lib/cjs/v1/index.d.ts +12 -0
  46. package/lib/cjs/v1/index.js +180 -0
  47. package/lib/cjs/v1/index.js.map +1 -0
  48. package/lib/cjs/x402HTTPResourceServer-D1YtlH_r.d.ts +719 -0
  49. package/lib/esm/chunk-3CEIVWNN.mjs +339 -0
  50. package/lib/esm/chunk-3CEIVWNN.mjs.map +1 -0
  51. package/lib/esm/chunk-BJTO5JO5.mjs +11 -0
  52. package/lib/esm/chunk-BJTO5JO5.mjs.map +1 -0
  53. package/lib/esm/chunk-EEA7DKZI.mjs +111 -0
  54. package/lib/esm/chunk-EEA7DKZI.mjs.map +1 -0
  55. package/lib/esm/chunk-FOUXRQAV.mjs +88 -0
  56. package/lib/esm/chunk-FOUXRQAV.mjs.map +1 -0
  57. package/lib/esm/chunk-IKSTWKEM.mjs +157 -0
  58. package/lib/esm/chunk-IKSTWKEM.mjs.map +1 -0
  59. package/lib/esm/chunk-JYZWCLMP.mjs +305 -0
  60. package/lib/esm/chunk-JYZWCLMP.mjs.map +1 -0
  61. package/lib/esm/chunk-PNSAJQCF.mjs +108 -0
  62. package/lib/esm/chunk-PNSAJQCF.mjs.map +1 -0
  63. package/lib/esm/chunk-PSA4YVU2.mjs +92 -0
  64. package/lib/esm/chunk-PSA4YVU2.mjs.map +1 -0
  65. package/lib/esm/chunk-QLXM7BIB.mjs +23 -0
  66. package/lib/esm/chunk-QLXM7BIB.mjs.map +1 -0
  67. package/lib/esm/chunk-TDLQZ6MP.mjs +86 -0
  68. package/lib/esm/chunk-TDLQZ6MP.mjs.map +1 -0
  69. package/lib/esm/chunk-VE37GDG2.mjs +7 -0
  70. package/lib/esm/chunk-VE37GDG2.mjs.map +1 -0
  71. package/lib/esm/chunk-WWACQNRQ.mjs +7 -0
  72. package/lib/esm/chunk-WWACQNRQ.mjs.map +1 -0
  73. package/lib/esm/chunk-X4W4S5RB.mjs +39 -0
  74. package/lib/esm/chunk-X4W4S5RB.mjs.map +1 -0
  75. package/lib/esm/chunk-Z4QX3O5V.mjs +748 -0
  76. package/lib/esm/chunk-Z4QX3O5V.mjs.map +1 -0
  77. package/lib/esm/chunk-ZYXTTU74.mjs +88 -0
  78. package/lib/esm/chunk-ZYXTTU74.mjs.map +1 -0
  79. package/lib/esm/client/index.d.mts +243 -0
  80. package/lib/esm/client/index.mjs +260 -0
  81. package/lib/esm/client/index.mjs.map +1 -0
  82. package/lib/esm/exact/client/index.d.mts +37 -0
  83. package/lib/esm/exact/client/index.mjs +36 -0
  84. package/lib/esm/exact/client/index.mjs.map +1 -0
  85. package/lib/esm/exact/facilitator/index.d.mts +110 -0
  86. package/lib/esm/exact/facilitator/index.mjs +350 -0
  87. package/lib/esm/exact/facilitator/index.mjs.map +1 -0
  88. package/lib/esm/exact/server/index.d.mts +87 -0
  89. package/lib/esm/exact/server/index.mjs +129 -0
  90. package/lib/esm/exact/server/index.mjs.map +1 -0
  91. package/lib/esm/exact/v1/client/index.d.mts +33 -0
  92. package/lib/esm/exact/v1/client/index.mjs +8 -0
  93. package/lib/esm/exact/v1/client/index.mjs.map +1 -0
  94. package/lib/esm/exact/v1/facilitator/index.d.mts +71 -0
  95. package/lib/esm/exact/v1/facilitator/index.mjs +8 -0
  96. package/lib/esm/exact/v1/facilitator/index.mjs.map +1 -0
  97. package/lib/esm/facilitator/index.d.mts +192 -0
  98. package/lib/esm/facilitator/index.mjs +373 -0
  99. package/lib/esm/facilitator/index.mjs.map +1 -0
  100. package/lib/esm/http/index.d.mts +52 -0
  101. package/lib/esm/http/index.mjs +29 -0
  102. package/lib/esm/http/index.mjs.map +1 -0
  103. package/lib/esm/index.d.mts +145 -0
  104. package/lib/esm/index.mjs +277 -0
  105. package/lib/esm/index.mjs.map +1 -0
  106. package/lib/esm/mechanisms-CzuGzYsS.d.mts +270 -0
  107. package/lib/esm/scheme-fjF-9LhT.d.mts +29 -0
  108. package/lib/esm/server/index.d.mts +2 -0
  109. package/lib/esm/server/index.mjs +563 -0
  110. package/lib/esm/server/index.mjs.map +1 -0
  111. package/lib/esm/signer-5OVDxViv.d.mts +79 -0
  112. package/lib/esm/signer-BMkbhFYE.d.mts +123 -0
  113. package/lib/esm/types/index.d.mts +1 -0
  114. package/lib/esm/types/index.mjs +10 -0
  115. package/lib/esm/types/index.mjs.map +1 -0
  116. package/lib/esm/types/v1/index.d.mts +1 -0
  117. package/lib/esm/types/v1/index.mjs +1 -0
  118. package/lib/esm/types/v1/index.mjs.map +1 -0
  119. package/lib/esm/utils/index.d.mts +48 -0
  120. package/lib/esm/utils/index.mjs +20 -0
  121. package/lib/esm/utils/index.mjs.map +1 -0
  122. package/lib/esm/v1/index.d.mts +12 -0
  123. package/lib/esm/v1/index.mjs +13 -0
  124. package/lib/esm/v1/index.mjs.map +1 -0
  125. package/lib/esm/x402HTTPResourceServer-BIfIK5HS.d.mts +719 -0
  126. package/package.json +39 -0
  127. package/src/index.js +4 -0
@@ -0,0 +1,719 @@
1
+ import { P as PaymentPayload, a as PaymentRequirements, V as VerifyResponse, S as SettleResponse, e as SupportedResponse, N as Network, f as SchemeNetworkServer, R as ResourceServerExtension, g as SupportedKind, h as Price, c as PaymentRequired } from './mechanisms-CzuGzYsS.mjs';
2
+
3
+ interface FacilitatorConfig {
4
+ url?: string;
5
+ createAuthHeaders?: () => Promise<{
6
+ verify: Record<string, string>;
7
+ settle: Record<string, string>;
8
+ supported: Record<string, string>;
9
+ }>;
10
+ }
11
+ /**
12
+ * Interface for facilitator clients
13
+ * Can be implemented for HTTP-based or local facilitators
14
+ */
15
+ interface FacilitatorClient {
16
+ /**
17
+ * Verify a payment with the facilitator
18
+ *
19
+ * @param paymentPayload - The payment to verify
20
+ * @param paymentRequirements - The requirements to verify against
21
+ * @returns Verification response
22
+ */
23
+ verify(paymentPayload: PaymentPayload, paymentRequirements: PaymentRequirements): Promise<VerifyResponse>;
24
+ /**
25
+ * Settle a payment with the facilitator
26
+ *
27
+ * @param paymentPayload - The payment to settle
28
+ * @param paymentRequirements - The requirements for settlement
29
+ * @returns Settlement response
30
+ */
31
+ settle(paymentPayload: PaymentPayload, paymentRequirements: PaymentRequirements): Promise<SettleResponse>;
32
+ /**
33
+ * Get supported payment kinds and extensions from the facilitator
34
+ *
35
+ * @returns Supported payment kinds and extensions
36
+ */
37
+ getSupported(): Promise<SupportedResponse>;
38
+ }
39
+ /**
40
+ * HTTP-based client for interacting with x402 facilitator services
41
+ * Handles HTTP communication with facilitator endpoints
42
+ */
43
+ declare class HTTPFacilitatorClient implements FacilitatorClient {
44
+ readonly url: string;
45
+ private readonly _createAuthHeaders?;
46
+ /**
47
+ * Creates a new HTTPFacilitatorClient instance.
48
+ *
49
+ * @param config - Configuration options for the facilitator client
50
+ */
51
+ constructor(config?: FacilitatorConfig);
52
+ /**
53
+ * Verify a payment with the facilitator
54
+ *
55
+ * @param paymentPayload - The payment to verify
56
+ * @param paymentRequirements - The requirements to verify against
57
+ * @returns Verification response
58
+ */
59
+ verify(paymentPayload: PaymentPayload, paymentRequirements: PaymentRequirements): Promise<VerifyResponse>;
60
+ /**
61
+ * Settle a payment with the facilitator
62
+ *
63
+ * @param paymentPayload - The payment to settle
64
+ * @param paymentRequirements - The requirements for settlement
65
+ * @returns Settlement response
66
+ */
67
+ settle(paymentPayload: PaymentPayload, paymentRequirements: PaymentRequirements): Promise<SettleResponse>;
68
+ /**
69
+ * Get supported payment kinds and extensions from the facilitator
70
+ *
71
+ * @returns Supported payment kinds and extensions
72
+ */
73
+ getSupported(): Promise<SupportedResponse>;
74
+ /**
75
+ * Creates authentication headers for a specific path.
76
+ *
77
+ * @param path - The path to create authentication headers for (e.g., "verify", "settle", "supported")
78
+ * @returns An object containing the authentication headers for the specified path
79
+ */
80
+ createAuthHeaders(path: string): Promise<{
81
+ headers: Record<string, string>;
82
+ }>;
83
+ /**
84
+ * Helper to convert objects to JSON-safe format.
85
+ * Handles BigInt and other non-JSON types.
86
+ *
87
+ * @param obj - The object to convert
88
+ * @returns The JSON-safe representation of the object
89
+ */
90
+ private toJsonSafe;
91
+ }
92
+
93
+ /**
94
+ * Configuration for a protected resource
95
+ * Only contains payment-specific configuration, not resource metadata
96
+ */
97
+ interface ResourceConfig {
98
+ scheme: string;
99
+ payTo: string;
100
+ price: Price;
101
+ network: Network;
102
+ maxTimeoutSeconds?: number;
103
+ }
104
+ /**
105
+ * Resource information for PaymentRequired response
106
+ */
107
+ interface ResourceInfo {
108
+ url: string;
109
+ description: string;
110
+ mimeType: string;
111
+ }
112
+ /**
113
+ * Lifecycle Hook Context Interfaces
114
+ */
115
+ interface VerifyContext {
116
+ paymentPayload: PaymentPayload;
117
+ requirements: PaymentRequirements;
118
+ }
119
+ interface VerifyResultContext extends VerifyContext {
120
+ result: VerifyResponse;
121
+ }
122
+ interface VerifyFailureContext extends VerifyContext {
123
+ error: Error;
124
+ }
125
+ interface SettleContext {
126
+ paymentPayload: PaymentPayload;
127
+ requirements: PaymentRequirements;
128
+ }
129
+ interface SettleResultContext extends SettleContext {
130
+ result: SettleResponse;
131
+ }
132
+ interface SettleFailureContext extends SettleContext {
133
+ error: Error;
134
+ }
135
+ /**
136
+ * Lifecycle Hook Type Definitions
137
+ */
138
+ type BeforeVerifyHook = (context: VerifyContext) => Promise<void | {
139
+ abort: true;
140
+ reason: string;
141
+ }>;
142
+ type AfterVerifyHook = (context: VerifyResultContext) => Promise<void>;
143
+ type OnVerifyFailureHook = (context: VerifyFailureContext) => Promise<void | {
144
+ recovered: true;
145
+ result: VerifyResponse;
146
+ }>;
147
+ type BeforeSettleHook = (context: SettleContext) => Promise<void | {
148
+ abort: true;
149
+ reason: string;
150
+ }>;
151
+ type AfterSettleHook = (context: SettleResultContext) => Promise<void>;
152
+ type OnSettleFailureHook = (context: SettleFailureContext) => Promise<void | {
153
+ recovered: true;
154
+ result: SettleResponse;
155
+ }>;
156
+ /**
157
+ * Core x402 protocol server for resource protection
158
+ * Transport-agnostic implementation of the x402 payment protocol
159
+ */
160
+ declare class x402ResourceServer {
161
+ private facilitatorClients;
162
+ private registeredServerSchemes;
163
+ private supportedResponsesMap;
164
+ private facilitatorClientsMap;
165
+ private registeredExtensions;
166
+ private beforeVerifyHooks;
167
+ private afterVerifyHooks;
168
+ private onVerifyFailureHooks;
169
+ private beforeSettleHooks;
170
+ private afterSettleHooks;
171
+ private onSettleFailureHooks;
172
+ /**
173
+ * Creates a new x402ResourceServer instance.
174
+ *
175
+ * @param facilitatorClients - Optional facilitator client(s) for payment processing
176
+ */
177
+ constructor(facilitatorClients?: FacilitatorClient | FacilitatorClient[]);
178
+ /**
179
+ * Register a scheme/network server implementation.
180
+ *
181
+ * @param network - The network identifier
182
+ * @param server - The scheme/network server implementation
183
+ * @returns The x402ResourceServer instance for chaining
184
+ */
185
+ register(network: Network, server: SchemeNetworkServer): x402ResourceServer;
186
+ /**
187
+ * Check if a scheme is registered for a given network.
188
+ *
189
+ * @param network - The network identifier
190
+ * @param scheme - The payment scheme name
191
+ * @returns True if the scheme is registered for the network, false otherwise
192
+ */
193
+ hasRegisteredScheme(network: Network, scheme: string): boolean;
194
+ /**
195
+ * Registers a resource service extension that can enrich extension declarations.
196
+ *
197
+ * @param extension - The extension to register
198
+ * @returns The x402ResourceServer instance for chaining
199
+ */
200
+ registerExtension(extension: ResourceServerExtension): this;
201
+ /**
202
+ * Enriches declared extensions using registered extension hooks.
203
+ *
204
+ * @param declaredExtensions - Extensions declared on the route
205
+ * @param transportContext - Transport-specific context (HTTP, A2A, MCP, etc.)
206
+ * @returns Enriched extensions map
207
+ */
208
+ enrichExtensions(declaredExtensions: Record<string, unknown>, transportContext: unknown): Record<string, unknown>;
209
+ /**
210
+ * Register a hook to execute before payment verification.
211
+ * Can abort verification by returning { abort: true, reason: string }
212
+ *
213
+ * @param hook - The hook function to register
214
+ * @returns The x402ResourceServer instance for chaining
215
+ */
216
+ onBeforeVerify(hook: BeforeVerifyHook): x402ResourceServer;
217
+ /**
218
+ * Register a hook to execute after successful payment verification.
219
+ *
220
+ * @param hook - The hook function to register
221
+ * @returns The x402ResourceServer instance for chaining
222
+ */
223
+ onAfterVerify(hook: AfterVerifyHook): x402ResourceServer;
224
+ /**
225
+ * Register a hook to execute when payment verification fails.
226
+ * Can recover from failure by returning { recovered: true, result: VerifyResponse }
227
+ *
228
+ * @param hook - The hook function to register
229
+ * @returns The x402ResourceServer instance for chaining
230
+ */
231
+ onVerifyFailure(hook: OnVerifyFailureHook): x402ResourceServer;
232
+ /**
233
+ * Register a hook to execute before payment settlement.
234
+ * Can abort settlement by returning { abort: true, reason: string }
235
+ *
236
+ * @param hook - The hook function to register
237
+ * @returns The x402ResourceServer instance for chaining
238
+ */
239
+ onBeforeSettle(hook: BeforeSettleHook): x402ResourceServer;
240
+ /**
241
+ * Register a hook to execute after successful payment settlement.
242
+ *
243
+ * @param hook - The hook function to register
244
+ * @returns The x402ResourceServer instance for chaining
245
+ */
246
+ onAfterSettle(hook: AfterSettleHook): x402ResourceServer;
247
+ /**
248
+ * Register a hook to execute when payment settlement fails.
249
+ * Can recover from failure by returning { recovered: true, result: SettleResponse }
250
+ *
251
+ * @param hook - The hook function to register
252
+ * @returns The x402ResourceServer instance for chaining
253
+ */
254
+ onSettleFailure(hook: OnSettleFailureHook): x402ResourceServer;
255
+ /**
256
+ * Initialize by fetching supported kinds from all facilitators
257
+ * Creates mappings for supported responses and facilitator clients
258
+ * Earlier facilitators in the array get precedence
259
+ */
260
+ initialize(): Promise<void>;
261
+ /**
262
+ * Get supported kind for a specific version, network, and scheme
263
+ *
264
+ * @param x402Version - The x402 version
265
+ * @param network - The network identifier
266
+ * @param scheme - The payment scheme
267
+ * @returns The supported kind or undefined if not found
268
+ */
269
+ getSupportedKind(x402Version: number, network: Network, scheme: string): SupportedKind | undefined;
270
+ /**
271
+ * Get facilitator extensions for a specific version, network, and scheme
272
+ *
273
+ * @param x402Version - The x402 version
274
+ * @param network - The network identifier
275
+ * @param scheme - The payment scheme
276
+ * @returns The facilitator extensions or empty array if not found
277
+ */
278
+ getFacilitatorExtensions(x402Version: number, network: Network, scheme: string): string[];
279
+ /**
280
+ * Build payment requirements for a protected resource
281
+ *
282
+ * @param resourceConfig - Configuration for the protected resource
283
+ * @returns Array of payment requirements
284
+ */
285
+ buildPaymentRequirements(resourceConfig: ResourceConfig): Promise<PaymentRequirements[]>;
286
+ /**
287
+ * Build payment requirements from multiple payment options
288
+ * This method handles resolving dynamic payTo/price functions and builds requirements for each option
289
+ *
290
+ * @param paymentOptions - Array of payment options to convert
291
+ * @param context - HTTP request context for resolving dynamic functions
292
+ * @returns Array of payment requirements (one per option)
293
+ */
294
+ buildPaymentRequirementsFromOptions<TContext = unknown>(paymentOptions: Array<{
295
+ scheme: string;
296
+ payTo: string | ((context: TContext) => string | Promise<string>);
297
+ price: Price | ((context: TContext) => Price | Promise<Price>);
298
+ network: Network;
299
+ maxTimeoutSeconds?: number;
300
+ }>, context: TContext): Promise<PaymentRequirements[]>;
301
+ /**
302
+ * Create a payment required response
303
+ *
304
+ * @param requirements - Payment requirements
305
+ * @param resourceInfo - Resource information
306
+ * @param error - Error message
307
+ * @param extensions - Optional extensions
308
+ * @returns Payment required response object
309
+ */
310
+ createPaymentRequiredResponse(requirements: PaymentRequirements[], resourceInfo: ResourceInfo, error?: string, extensions?: Record<string, unknown>): PaymentRequired;
311
+ /**
312
+ * Verify a payment against requirements
313
+ *
314
+ * @param paymentPayload - The payment payload to verify
315
+ * @param requirements - The payment requirements
316
+ * @returns Verification response
317
+ */
318
+ verifyPayment(paymentPayload: PaymentPayload, requirements: PaymentRequirements): Promise<VerifyResponse>;
319
+ /**
320
+ * Settle a verified payment
321
+ *
322
+ * @param paymentPayload - The payment payload to settle
323
+ * @param requirements - The payment requirements
324
+ * @returns Settlement response
325
+ */
326
+ settlePayment(paymentPayload: PaymentPayload, requirements: PaymentRequirements): Promise<SettleResponse>;
327
+ /**
328
+ * Find matching payment requirements for a payment
329
+ *
330
+ * @param availableRequirements - Array of available payment requirements
331
+ * @param paymentPayload - The payment payload
332
+ * @returns Matching payment requirements or undefined
333
+ */
334
+ findMatchingRequirements(availableRequirements: PaymentRequirements[], paymentPayload: PaymentPayload): PaymentRequirements | undefined;
335
+ /**
336
+ * Process a payment request
337
+ *
338
+ * @param paymentPayload - Optional payment payload if provided
339
+ * @param resourceConfig - Configuration for the protected resource
340
+ * @param resourceInfo - Information about the resource being accessed
341
+ * @param extensions - Optional extensions to include in the response
342
+ * @returns Processing result
343
+ */
344
+ processPaymentRequest(paymentPayload: PaymentPayload | null, resourceConfig: ResourceConfig, resourceInfo: ResourceInfo, extensions?: Record<string, unknown>): Promise<{
345
+ success: boolean;
346
+ requiresPayment?: PaymentRequired;
347
+ verificationResult?: VerifyResponse;
348
+ settlementResult?: SettleResponse;
349
+ error?: string;
350
+ }>;
351
+ /**
352
+ * Get facilitator client for a specific version, network, and scheme
353
+ *
354
+ * @param x402Version - The x402 version
355
+ * @param network - The network identifier
356
+ * @param scheme - The payment scheme
357
+ * @returns The facilitator client or undefined if not found
358
+ */
359
+ private getFacilitatorClient;
360
+ }
361
+
362
+ /**
363
+ * Framework-agnostic HTTP adapter interface
364
+ * Implementations provide framework-specific HTTP operations
365
+ */
366
+ interface HTTPAdapter {
367
+ getHeader(name: string): string | undefined;
368
+ getMethod(): string;
369
+ getPath(): string;
370
+ getUrl(): string;
371
+ getAcceptHeader(): string;
372
+ getUserAgent(): string;
373
+ /**
374
+ * Get query parameters from the request URL
375
+ *
376
+ * @returns Record of query parameter key-value pairs
377
+ */
378
+ getQueryParams?(): Record<string, string | string[]>;
379
+ /**
380
+ * Get a specific query parameter by name
381
+ *
382
+ * @param name - The query parameter name
383
+ * @returns The query parameter value(s) or undefined
384
+ */
385
+ getQueryParam?(name: string): string | string[] | undefined;
386
+ /**
387
+ * Get the parsed request body
388
+ * Framework adapters should parse JSON/form data appropriately
389
+ *
390
+ * @returns The parsed request body
391
+ */
392
+ getBody?(): unknown;
393
+ }
394
+ /**
395
+ * Paywall configuration for HTML responses
396
+ */
397
+ interface PaywallConfig {
398
+ appName?: string;
399
+ appLogo?: string;
400
+ sessionTokenEndpoint?: string;
401
+ currentUrl?: string;
402
+ testnet?: boolean;
403
+ }
404
+ /**
405
+ * Paywall provider interface for generating HTML
406
+ */
407
+ interface PaywallProvider {
408
+ generateHtml(paymentRequired: PaymentRequired, config?: PaywallConfig): string;
409
+ }
410
+ /**
411
+ * Dynamic payTo function that receives HTTP request context
412
+ */
413
+ type DynamicPayTo = (context: HTTPRequestContext) => string | Promise<string>;
414
+ /**
415
+ * Dynamic price function that receives HTTP request context
416
+ */
417
+ type DynamicPrice = (context: HTTPRequestContext) => Price | Promise<Price>;
418
+ /**
419
+ * Result of the unpaid response callback containing content type and body.
420
+ */
421
+ interface UnpaidResponseResult {
422
+ /**
423
+ * The content type for the response (e.g., 'application/json', 'text/plain').
424
+ */
425
+ contentType: string;
426
+ /**
427
+ * The response body to include in the 402 response.
428
+ */
429
+ body: unknown;
430
+ }
431
+ /**
432
+ * Dynamic function to generate a custom response for unpaid requests.
433
+ * Receives the HTTP request context and returns the content type and body to include in the 402 response.
434
+ */
435
+ type UnpaidResponseBody = (context: HTTPRequestContext) => UnpaidResponseResult | Promise<UnpaidResponseResult>;
436
+ /**
437
+ * A single payment option for a route
438
+ * Represents one way a client can pay for access to the resource
439
+ */
440
+ interface PaymentOption {
441
+ scheme: string;
442
+ payTo: string | DynamicPayTo;
443
+ price: Price | DynamicPrice;
444
+ network: Network;
445
+ maxTimeoutSeconds?: number;
446
+ extra?: Record<string, unknown>;
447
+ }
448
+ /**
449
+ * Route configuration for HTTP endpoints
450
+ *
451
+ * The 'accepts' field defines payment options for the route.
452
+ * Can be a single PaymentOption or an array of PaymentOptions for multiple payment methods.
453
+ */
454
+ interface RouteConfig {
455
+ accepts: PaymentOption | PaymentOption[];
456
+ resource?: string;
457
+ description?: string;
458
+ mimeType?: string;
459
+ customPaywallHtml?: string;
460
+ /**
461
+ * Optional callback to generate a custom response for unpaid API requests.
462
+ * This allows servers to return preview data, error messages, or other content
463
+ * when a request lacks payment.
464
+ *
465
+ * For browser requests (Accept: text/html), the paywall HTML takes precedence.
466
+ * This callback is only used for API clients.
467
+ *
468
+ * If not provided, defaults to { contentType: 'application/json', body: {} }.
469
+ *
470
+ * @param context - The HTTP request context
471
+ * @returns An object containing both contentType and body for the 402 response
472
+ */
473
+ unpaidResponseBody?: UnpaidResponseBody;
474
+ extensions?: Record<string, unknown>;
475
+ }
476
+ /**
477
+ * Routes configuration - maps path patterns to route configs
478
+ */
479
+ type RoutesConfig = Record<string, RouteConfig> | RouteConfig;
480
+ /**
481
+ * Compiled route for efficient matching
482
+ */
483
+ interface CompiledRoute {
484
+ verb: string;
485
+ regex: RegExp;
486
+ config: RouteConfig;
487
+ }
488
+ /**
489
+ * HTTP request context that encapsulates all request data
490
+ */
491
+ interface HTTPRequestContext {
492
+ adapter: HTTPAdapter;
493
+ path: string;
494
+ method: string;
495
+ paymentHeader?: string;
496
+ }
497
+ /**
498
+ * HTTP response instructions for the framework middleware
499
+ */
500
+ interface HTTPResponseInstructions {
501
+ status: number;
502
+ headers: Record<string, string>;
503
+ body?: unknown;
504
+ isHtml?: boolean;
505
+ }
506
+ /**
507
+ * Result of processing an HTTP request for payment
508
+ */
509
+ type HTTPProcessResult = {
510
+ type: "no-payment-required";
511
+ } | {
512
+ type: "payment-verified";
513
+ paymentPayload: PaymentPayload;
514
+ paymentRequirements: PaymentRequirements;
515
+ } | {
516
+ type: "payment-error";
517
+ response: HTTPResponseInstructions;
518
+ };
519
+ /**
520
+ * Result of processSettlement
521
+ */
522
+ type ProcessSettleSuccessResponse = SettleResponse & {
523
+ success: true;
524
+ headers: Record<string, string>;
525
+ requirements: PaymentRequirements;
526
+ };
527
+ type ProcessSettleFailureResponse = SettleResponse & {
528
+ success: false;
529
+ errorReason: string;
530
+ };
531
+ type ProcessSettleResultResponse = ProcessSettleSuccessResponse | ProcessSettleFailureResponse;
532
+ /**
533
+ * Represents a validation error for a specific route's payment configuration.
534
+ */
535
+ interface RouteValidationError {
536
+ /** The route pattern (e.g., "GET /api/weather") */
537
+ routePattern: string;
538
+ /** The payment scheme that failed validation */
539
+ scheme: string;
540
+ /** The network that failed validation */
541
+ network: Network;
542
+ /** The type of validation failure */
543
+ reason: "missing_scheme" | "missing_facilitator";
544
+ /** Human-readable error message */
545
+ message: string;
546
+ }
547
+ /**
548
+ * Error thrown when route configuration validation fails.
549
+ */
550
+ declare class RouteConfigurationError extends Error {
551
+ /** The validation errors that caused this exception */
552
+ readonly errors: RouteValidationError[];
553
+ /**
554
+ * Creates a new RouteConfigurationError with the given validation errors.
555
+ *
556
+ * @param errors - The validation errors that caused this exception.
557
+ */
558
+ constructor(errors: RouteValidationError[]);
559
+ }
560
+ /**
561
+ * HTTP-enhanced x402 resource server
562
+ * Provides framework-agnostic HTTP protocol handling
563
+ */
564
+ declare class x402HTTPResourceServer {
565
+ private ResourceServer;
566
+ private compiledRoutes;
567
+ private routesConfig;
568
+ private paywallProvider?;
569
+ /**
570
+ * Creates a new x402HTTPResourceServer instance.
571
+ *
572
+ * @param ResourceServer - The core x402ResourceServer instance to use
573
+ * @param routes - Route configuration for payment-protected endpoints
574
+ */
575
+ constructor(ResourceServer: x402ResourceServer, routes: RoutesConfig);
576
+ /**
577
+ * Initialize the HTTP resource server.
578
+ *
579
+ * This method initializes the underlying resource server (fetching facilitator support)
580
+ * and then validates that all route payment configurations have corresponding
581
+ * registered schemes and facilitator support.
582
+ *
583
+ * @throws RouteConfigurationError if any route's payment options don't have
584
+ * corresponding registered schemes or facilitator support
585
+ *
586
+ * @example
587
+ * ```typescript
588
+ * const httpServer = new x402HTTPResourceServer(server, routes);
589
+ * await httpServer.initialize();
590
+ * ```
591
+ */
592
+ initialize(): Promise<void>;
593
+ /**
594
+ * Register a custom paywall provider for generating HTML
595
+ *
596
+ * @param provider - PaywallProvider instance
597
+ * @returns This service instance for chaining
598
+ */
599
+ registerPaywallProvider(provider: PaywallProvider): this;
600
+ /**
601
+ * Process HTTP request and return response instructions
602
+ * This is the main entry point for framework middleware
603
+ *
604
+ * @param context - HTTP request context
605
+ * @param paywallConfig - Optional paywall configuration
606
+ * @returns Process result indicating next action for middleware
607
+ */
608
+ processHTTPRequest(context: HTTPRequestContext, paywallConfig?: PaywallConfig): Promise<HTTPProcessResult>;
609
+ /**
610
+ * Process settlement after successful response
611
+ *
612
+ * @param paymentPayload - The verified payment payload
613
+ * @param requirements - The matching payment requirements
614
+ * @returns ProcessSettleResultResponse - SettleResponse with headers if success or errorReason if failure
615
+ */
616
+ processSettlement(paymentPayload: PaymentPayload, requirements: PaymentRequirements): Promise<ProcessSettleResultResponse>;
617
+ /**
618
+ * Check if a request requires payment based on route configuration
619
+ *
620
+ * @param context - HTTP request context
621
+ * @returns True if the route requires payment, false otherwise
622
+ */
623
+ requiresPayment(context: HTTPRequestContext): boolean;
624
+ /**
625
+ * Normalizes a RouteConfig's accepts field into an array of PaymentOptions
626
+ * Handles both single PaymentOption and array formats
627
+ *
628
+ * @param routeConfig - Route configuration
629
+ * @returns Array of payment options
630
+ */
631
+ private normalizePaymentOptions;
632
+ /**
633
+ * Validates that all payment options in routes have corresponding registered schemes
634
+ * and facilitator support.
635
+ *
636
+ * @returns Array of validation errors (empty if all routes are valid)
637
+ */
638
+ private validateRouteConfiguration;
639
+ /**
640
+ * Get route configuration for a request
641
+ *
642
+ * @param path - Request path
643
+ * @param method - HTTP method
644
+ * @returns Route configuration or undefined if no match
645
+ */
646
+ private getRouteConfig;
647
+ /**
648
+ * Extract payment from HTTP headers (handles v1 and v2)
649
+ *
650
+ * @param adapter - HTTP adapter
651
+ * @returns Decoded payment payload or null
652
+ */
653
+ private extractPayment;
654
+ /**
655
+ * Check if request is from a web browser
656
+ *
657
+ * @param adapter - HTTP adapter
658
+ * @returns True if request appears to be from a browser
659
+ */
660
+ private isWebBrowser;
661
+ /**
662
+ * Create HTTP response instructions from payment required
663
+ *
664
+ * @param paymentRequired - Payment requirements
665
+ * @param isWebBrowser - Whether request is from browser
666
+ * @param paywallConfig - Paywall configuration
667
+ * @param customHtml - Custom HTML template
668
+ * @param unpaidResponse - Optional custom response (content type and body) for unpaid API requests
669
+ * @returns Response instructions
670
+ */
671
+ private createHTTPResponse;
672
+ /**
673
+ * Create HTTP payment required response (v1 puts in body, v2 puts in header)
674
+ *
675
+ * @param paymentRequired - Payment required object
676
+ * @returns Headers and body for the HTTP response
677
+ */
678
+ private createHTTPPaymentRequiredResponse;
679
+ /**
680
+ * Create settlement response headers
681
+ *
682
+ * @param settleResponse - Settlement response
683
+ * @param requirements - Payment requirements that were settled
684
+ * @returns Headers to add to response
685
+ */
686
+ private createSettlementHeaders;
687
+ /**
688
+ * Parse route pattern into verb and regex
689
+ *
690
+ * @param pattern - Route pattern like "GET /api/*" or "/api/[id]"
691
+ * @returns Parsed pattern with verb and regex
692
+ */
693
+ private parseRoutePattern;
694
+ /**
695
+ * Normalize path for matching
696
+ *
697
+ * @param path - Raw path from request
698
+ * @returns Normalized path
699
+ */
700
+ private normalizePath;
701
+ /**
702
+ * Generate paywall HTML for browser requests
703
+ *
704
+ * @param paymentRequired - Payment required response
705
+ * @param paywallConfig - Optional paywall configuration
706
+ * @param customHtml - Optional custom HTML template
707
+ * @returns HTML string
708
+ */
709
+ private generatePaywallHTML;
710
+ /**
711
+ * Extract display amount from payment requirements.
712
+ *
713
+ * @param paymentRequired - The payment required object
714
+ * @returns The display amount in decimal format
715
+ */
716
+ private getDisplayAmount;
717
+ }
718
+
719
+ export { type CompiledRoute as C, type DynamicPayTo as D, type FacilitatorClient as F, type HTTPAdapter as H, type PaywallConfig as P, type RouteConfig as R, type UnpaidResponseBody as U, type HTTPRequestContext as a, type HTTPResponseInstructions as b, type HTTPProcessResult as c, type PaywallProvider as d, type PaymentOption as e, type RoutesConfig as f, type DynamicPrice as g, type UnpaidResponseResult as h, type ProcessSettleResultResponse as i, type ProcessSettleSuccessResponse as j, type ProcessSettleFailureResponse as k, type RouteValidationError as l, RouteConfigurationError as m, HTTPFacilitatorClient as n, type FacilitatorConfig as o, x402ResourceServer as p, type ResourceConfig as q, type ResourceInfo as r, x402HTTPResourceServer as x };