x402-core-mantle 2.1.1-mantle
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.
- package/README.md +293 -0
- package/dist/cjs/client/index.d.ts +243 -0
- package/dist/cjs/client/index.js +413 -0
- package/dist/cjs/client/index.js.map +1 -0
- package/dist/cjs/facilitator/index.d.ts +192 -0
- package/dist/cjs/facilitator/index.js +398 -0
- package/dist/cjs/facilitator/index.js.map +1 -0
- package/dist/cjs/http/index.d.ts +52 -0
- package/dist/cjs/http/index.js +827 -0
- package/dist/cjs/http/index.js.map +1 -0
- package/dist/cjs/index.d.ts +3 -0
- package/dist/cjs/index.js +31 -0
- package/dist/cjs/index.js.map +1 -0
- package/dist/cjs/mechanisms-CzuGzYsS.d.ts +270 -0
- package/dist/cjs/server/index.d.ts +2 -0
- package/dist/cjs/server/index.js +1305 -0
- package/dist/cjs/server/index.js.map +1 -0
- package/dist/cjs/types/index.d.ts +1 -0
- package/dist/cjs/types/index.js +66 -0
- package/dist/cjs/types/index.js.map +1 -0
- package/dist/cjs/types/v1/index.d.ts +1 -0
- package/dist/cjs/types/v1/index.js +19 -0
- package/dist/cjs/types/v1/index.js.map +1 -0
- package/dist/cjs/utils/index.d.ts +48 -0
- package/dist/cjs/utils/index.js +116 -0
- package/dist/cjs/utils/index.js.map +1 -0
- package/dist/cjs/x402HTTPResourceServer-D1YtlH_r.d.ts +719 -0
- package/dist/esm/chunk-BJTO5JO5.mjs +11 -0
- package/dist/esm/chunk-BJTO5JO5.mjs.map +1 -0
- package/dist/esm/chunk-TDLQZ6MP.mjs +86 -0
- package/dist/esm/chunk-TDLQZ6MP.mjs.map +1 -0
- package/dist/esm/chunk-VE37GDG2.mjs +7 -0
- package/dist/esm/chunk-VE37GDG2.mjs.map +1 -0
- package/dist/esm/chunk-X4W4S5RB.mjs +39 -0
- package/dist/esm/chunk-X4W4S5RB.mjs.map +1 -0
- package/dist/esm/chunk-Z4QX3O5V.mjs +748 -0
- package/dist/esm/chunk-Z4QX3O5V.mjs.map +1 -0
- package/dist/esm/client/index.d.mts +243 -0
- package/dist/esm/client/index.mjs +260 -0
- package/dist/esm/client/index.mjs.map +1 -0
- package/dist/esm/facilitator/index.d.mts +192 -0
- package/dist/esm/facilitator/index.mjs +373 -0
- package/dist/esm/facilitator/index.mjs.map +1 -0
- package/dist/esm/http/index.d.mts +52 -0
- package/dist/esm/http/index.mjs +29 -0
- package/dist/esm/http/index.mjs.map +1 -0
- package/dist/esm/index.d.mts +3 -0
- package/dist/esm/index.mjs +8 -0
- package/dist/esm/index.mjs.map +1 -0
- package/dist/esm/mechanisms-CzuGzYsS.d.mts +270 -0
- package/dist/esm/server/index.d.mts +2 -0
- package/dist/esm/server/index.mjs +563 -0
- package/dist/esm/server/index.mjs.map +1 -0
- package/dist/esm/types/index.d.mts +1 -0
- package/dist/esm/types/index.mjs +10 -0
- package/dist/esm/types/index.mjs.map +1 -0
- package/dist/esm/types/v1/index.d.mts +1 -0
- package/dist/esm/types/v1/index.mjs +1 -0
- package/dist/esm/types/v1/index.mjs.map +1 -0
- package/dist/esm/utils/index.d.mts +48 -0
- package/dist/esm/utils/index.mjs +20 -0
- package/dist/esm/utils/index.mjs.map +1 -0
- package/dist/esm/x402HTTPResourceServer-BIfIK5HS.d.mts +719 -0
- package/package.json +129 -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.js';
|
|
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 };
|