@bankofai/x402-core 2.6.0-beta.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.
- package/README.md +293 -0
- package/dist/cjs/assetRegistry-CL0zA4s0.d.ts +831 -0
- package/dist/cjs/assetRegistry-CRVM0KEs.d.ts +831 -0
- package/dist/cjs/client/index.d.ts +329 -0
- package/dist/cjs/client/index.js +712 -0
- package/dist/cjs/client/index.js.map +1 -0
- package/dist/cjs/facilitator/index.d.ts +206 -0
- package/dist/cjs/facilitator/index.js +625 -0
- package/dist/cjs/facilitator/index.js.map +1 -0
- package/dist/cjs/http/index.d.ts +51 -0
- package/dist/cjs/http/index.js +1178 -0
- package/dist/cjs/http/index.js.map +1 -0
- package/dist/cjs/index.d.ts +13 -0
- package/dist/cjs/index.js +250 -0
- package/dist/cjs/index.js.map +1 -0
- package/dist/cjs/mechanisms-q7I6xfUE.d.ts +726 -0
- package/dist/cjs/schemas/index.d.ts +825 -0
- package/dist/cjs/schemas/index.js +212 -0
- package/dist/cjs/schemas/index.js.map +1 -0
- package/dist/cjs/server/index.d.ts +2 -0
- package/dist/cjs/server/index.js +1782 -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 +72 -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-BFVo1_74.d.ts +433 -0
- package/dist/cjs/x402HTTPResourceServer-DaU2yFzy.d.ts +434 -0
- package/dist/cjs/x402HTTPResourceServer-DswI2hZQ.d.ts +434 -0
- package/dist/esm/assetRegistry-CRVM0KEs.d.mts +831 -0
- package/dist/esm/chunk-BJTO5JO5.mjs +11 -0
- package/dist/esm/chunk-BJTO5JO5.mjs.map +1 -0
- package/dist/esm/chunk-DACUCTGT.mjs +891 -0
- package/dist/esm/chunk-DACUCTGT.mjs.map +1 -0
- package/dist/esm/chunk-DFUINDLZ.mjs +221 -0
- package/dist/esm/chunk-DFUINDLZ.mjs.map +1 -0
- package/dist/esm/chunk-HRQUGJ3Y.mjs +45 -0
- package/dist/esm/chunk-HRQUGJ3Y.mjs.map +1 -0
- package/dist/esm/chunk-TDLQZ6MP.mjs +86 -0
- package/dist/esm/chunk-TDLQZ6MP.mjs.map +1 -0
- package/dist/esm/client/index.d.mts +329 -0
- package/dist/esm/client/index.mjs +330 -0
- package/dist/esm/client/index.mjs.map +1 -0
- package/dist/esm/facilitator/index.d.mts +206 -0
- package/dist/esm/facilitator/index.mjs +398 -0
- package/dist/esm/facilitator/index.mjs.map +1 -0
- package/dist/esm/http/index.d.mts +51 -0
- package/dist/esm/http/index.mjs +29 -0
- package/dist/esm/http/index.mjs.map +1 -0
- package/dist/esm/index.d.mts +13 -0
- package/dist/esm/index.mjs +14 -0
- package/dist/esm/index.mjs.map +1 -0
- package/dist/esm/schemas/index.d.mts +825 -0
- package/dist/esm/schemas/index.mjs +158 -0
- package/dist/esm/schemas/index.mjs.map +1 -0
- package/dist/esm/server/index.d.mts +2 -0
- package/dist/esm/server/index.mjs +712 -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-B6uf_UDm.d.mts +434 -0
- package/package.json +139 -0
|
@@ -0,0 +1,329 @@
|
|
|
1
|
+
import { c as PaymentRequired, a as PaymentRequirements, P as PaymentPayload, N as Network, h as SchemeNetworkClient, S as SettleResponse } from '../assetRegistry-CRVM0KEs.mjs';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Client Hook Context Interfaces
|
|
5
|
+
*/
|
|
6
|
+
interface PaymentCreationContext {
|
|
7
|
+
paymentRequired: PaymentRequired;
|
|
8
|
+
selectedRequirements: PaymentRequirements;
|
|
9
|
+
}
|
|
10
|
+
interface PaymentCreatedContext extends PaymentCreationContext {
|
|
11
|
+
paymentPayload: PaymentPayload;
|
|
12
|
+
}
|
|
13
|
+
interface PaymentCreationFailureContext extends PaymentCreationContext {
|
|
14
|
+
error: Error;
|
|
15
|
+
}
|
|
16
|
+
/**
|
|
17
|
+
* Client Hook Type Definitions
|
|
18
|
+
*/
|
|
19
|
+
type BeforePaymentCreationHook = (context: PaymentCreationContext) => Promise<void | {
|
|
20
|
+
abort: true;
|
|
21
|
+
reason: string;
|
|
22
|
+
}>;
|
|
23
|
+
type AfterPaymentCreationHook = (context: PaymentCreatedContext) => Promise<void>;
|
|
24
|
+
type OnPaymentCreationFailureHook = (context: PaymentCreationFailureContext) => Promise<void | {
|
|
25
|
+
recovered: true;
|
|
26
|
+
payload: PaymentPayload;
|
|
27
|
+
}>;
|
|
28
|
+
type SelectPaymentRequirements = (x402Version: number, paymentRequirements: PaymentRequirements[]) => PaymentRequirements;
|
|
29
|
+
/**
|
|
30
|
+
* Extension that can enrich payment payloads on the client side.
|
|
31
|
+
*
|
|
32
|
+
* Client extensions are invoked after the scheme creates the base payment payload
|
|
33
|
+
* but before it is returned. This allows mechanism-specific logic (e.g., EVM EIP-2612
|
|
34
|
+
* permit signing) to enrich the payload's extensions data.
|
|
35
|
+
*/
|
|
36
|
+
interface ClientExtension {
|
|
37
|
+
/**
|
|
38
|
+
* Unique key identifying this extension (e.g., "eip2612GasSponsoring").
|
|
39
|
+
* Must match the extension key used in PaymentRequired.extensions.
|
|
40
|
+
*/
|
|
41
|
+
key: string;
|
|
42
|
+
/**
|
|
43
|
+
* Called after payload creation when the extension key is present in
|
|
44
|
+
* paymentRequired.extensions. Allows the extension to enrich the payload
|
|
45
|
+
* with extension-specific data (e.g., signing an EIP-2612 permit).
|
|
46
|
+
*
|
|
47
|
+
* @param paymentPayload - The payment payload to enrich
|
|
48
|
+
* @param paymentRequired - The original PaymentRequired response
|
|
49
|
+
* @returns The enriched payment payload
|
|
50
|
+
*/
|
|
51
|
+
enrichPaymentPayload?: (paymentPayload: PaymentPayload, paymentRequired: PaymentRequired) => Promise<PaymentPayload>;
|
|
52
|
+
}
|
|
53
|
+
/**
|
|
54
|
+
* A policy function that filters or transforms payment requirements.
|
|
55
|
+
* Policies are applied in order before the selector chooses the final option.
|
|
56
|
+
*
|
|
57
|
+
* @param x402Version - The x402 protocol version
|
|
58
|
+
* @param paymentRequirements - Array of payment requirements to filter/transform
|
|
59
|
+
* @returns Filtered array of payment requirements
|
|
60
|
+
*/
|
|
61
|
+
type PaymentPolicy = (x402Version: number, paymentRequirements: PaymentRequirements[]) => PaymentRequirements[];
|
|
62
|
+
/**
|
|
63
|
+
* Configuration for registering a payment scheme with a specific network
|
|
64
|
+
*/
|
|
65
|
+
interface SchemeRegistration {
|
|
66
|
+
/**
|
|
67
|
+
* The network identifier (e.g., 'eip155:8453', 'solana:mainnet')
|
|
68
|
+
*/
|
|
69
|
+
network: Network;
|
|
70
|
+
/**
|
|
71
|
+
* The scheme client implementation for this network
|
|
72
|
+
*/
|
|
73
|
+
client: SchemeNetworkClient;
|
|
74
|
+
/**
|
|
75
|
+
* The x402 protocol version to use for this scheme
|
|
76
|
+
*
|
|
77
|
+
* @default 2
|
|
78
|
+
*/
|
|
79
|
+
x402Version?: number;
|
|
80
|
+
}
|
|
81
|
+
/**
|
|
82
|
+
* Configuration options for the fetch wrapper
|
|
83
|
+
*/
|
|
84
|
+
interface x402ClientConfig {
|
|
85
|
+
/**
|
|
86
|
+
* Array of scheme registrations defining which payment methods are supported
|
|
87
|
+
*/
|
|
88
|
+
schemes: SchemeRegistration[];
|
|
89
|
+
/**
|
|
90
|
+
* Policies to apply to the client
|
|
91
|
+
*/
|
|
92
|
+
policies?: PaymentPolicy[];
|
|
93
|
+
/**
|
|
94
|
+
* Custom payment requirements selector function
|
|
95
|
+
* If not provided, uses the default selector (first available option)
|
|
96
|
+
*/
|
|
97
|
+
paymentRequirementsSelector?: SelectPaymentRequirements;
|
|
98
|
+
}
|
|
99
|
+
/**
|
|
100
|
+
* Core client for managing x402 payment schemes and creating payment payloads.
|
|
101
|
+
*
|
|
102
|
+
* Handles registration of payment schemes, policy-based filtering of payment requirements,
|
|
103
|
+
* and creation of payment payloads based on server requirements.
|
|
104
|
+
*/
|
|
105
|
+
declare class x402Client {
|
|
106
|
+
private readonly paymentRequirementsSelector;
|
|
107
|
+
private readonly registeredClientSchemes;
|
|
108
|
+
private readonly policies;
|
|
109
|
+
private readonly registeredExtensions;
|
|
110
|
+
private beforePaymentCreationHooks;
|
|
111
|
+
private afterPaymentCreationHooks;
|
|
112
|
+
private onPaymentCreationFailureHooks;
|
|
113
|
+
/**
|
|
114
|
+
* Creates a new x402Client instance.
|
|
115
|
+
*
|
|
116
|
+
* @param paymentRequirementsSelector - Function to select payment requirements from available options
|
|
117
|
+
*/
|
|
118
|
+
constructor(paymentRequirementsSelector?: SelectPaymentRequirements);
|
|
119
|
+
/**
|
|
120
|
+
* Creates a new x402Client instance from a configuration object.
|
|
121
|
+
*
|
|
122
|
+
* @param config - The client configuration including schemes, policies, and payment requirements selector
|
|
123
|
+
* @returns A configured x402Client instance
|
|
124
|
+
*/
|
|
125
|
+
static fromConfig(config: x402ClientConfig): x402Client;
|
|
126
|
+
/**
|
|
127
|
+
* Registers a scheme client for the current x402 version.
|
|
128
|
+
*
|
|
129
|
+
* @param network - The network to register the client for
|
|
130
|
+
* @param client - The scheme network client to register
|
|
131
|
+
* @returns The x402Client instance for chaining
|
|
132
|
+
*/
|
|
133
|
+
register(network: Network, client: SchemeNetworkClient): x402Client;
|
|
134
|
+
/**
|
|
135
|
+
* Registers a scheme client for x402 version 1.
|
|
136
|
+
*
|
|
137
|
+
* @param network - The v1 network identifier (e.g., 'base-sepolia', 'solana-devnet')
|
|
138
|
+
* @param client - The scheme network client to register
|
|
139
|
+
* @returns The x402Client instance for chaining
|
|
140
|
+
*/
|
|
141
|
+
registerV1(network: string, client: SchemeNetworkClient): x402Client;
|
|
142
|
+
/**
|
|
143
|
+
* Registers a policy to filter or transform payment requirements.
|
|
144
|
+
*
|
|
145
|
+
* Policies are applied in order after filtering by registered schemes
|
|
146
|
+
* and before the selector chooses the final payment requirement.
|
|
147
|
+
*
|
|
148
|
+
* @param policy - Function to filter/transform payment requirements
|
|
149
|
+
* @returns The x402Client instance for chaining
|
|
150
|
+
*
|
|
151
|
+
* @example
|
|
152
|
+
* ```typescript
|
|
153
|
+
* // Prefer cheaper options
|
|
154
|
+
* client.registerPolicy((version, reqs) =>
|
|
155
|
+
* reqs.filter(r => BigInt(r.value) < BigInt('1000000'))
|
|
156
|
+
* );
|
|
157
|
+
*
|
|
158
|
+
* // Prefer specific networks
|
|
159
|
+
* client.registerPolicy((version, reqs) =>
|
|
160
|
+
* reqs.filter(r => r.network.startsWith('eip155:'))
|
|
161
|
+
* );
|
|
162
|
+
* ```
|
|
163
|
+
*/
|
|
164
|
+
registerPolicy(policy: PaymentPolicy): x402Client;
|
|
165
|
+
/**
|
|
166
|
+
* Registers a client extension that can enrich payment payloads.
|
|
167
|
+
*
|
|
168
|
+
* Extensions are invoked after the scheme creates the base payload and the
|
|
169
|
+
* payload is wrapped with extensions/resource/accepted data. If the extension's
|
|
170
|
+
* key is present in `paymentRequired.extensions`, the extension's
|
|
171
|
+
* `enrichPaymentPayload` hook is called to modify the payload.
|
|
172
|
+
*
|
|
173
|
+
* @param extension - The client extension to register
|
|
174
|
+
* @returns The x402Client instance for chaining
|
|
175
|
+
*/
|
|
176
|
+
registerExtension(extension: ClientExtension): x402Client;
|
|
177
|
+
/**
|
|
178
|
+
* Register a hook to execute before payment payload creation.
|
|
179
|
+
* Can abort creation by returning { abort: true, reason: string }
|
|
180
|
+
*
|
|
181
|
+
* @param hook - The hook function to register
|
|
182
|
+
* @returns The x402Client instance for chaining
|
|
183
|
+
*/
|
|
184
|
+
onBeforePaymentCreation(hook: BeforePaymentCreationHook): x402Client;
|
|
185
|
+
/**
|
|
186
|
+
* Register a hook to execute after successful payment payload creation.
|
|
187
|
+
*
|
|
188
|
+
* @param hook - The hook function to register
|
|
189
|
+
* @returns The x402Client instance for chaining
|
|
190
|
+
*/
|
|
191
|
+
onAfterPaymentCreation(hook: AfterPaymentCreationHook): x402Client;
|
|
192
|
+
/**
|
|
193
|
+
* Register a hook to execute when payment payload creation fails.
|
|
194
|
+
* Can recover from failure by returning { recovered: true, payload: PaymentPayload }
|
|
195
|
+
*
|
|
196
|
+
* @param hook - The hook function to register
|
|
197
|
+
* @returns The x402Client instance for chaining
|
|
198
|
+
*/
|
|
199
|
+
onPaymentCreationFailure(hook: OnPaymentCreationFailureHook): x402Client;
|
|
200
|
+
/**
|
|
201
|
+
* Creates a payment payload based on a PaymentRequired response.
|
|
202
|
+
*
|
|
203
|
+
* Automatically extracts x402Version, resource, and extensions from the PaymentRequired
|
|
204
|
+
* response and constructs a complete PaymentPayload with the accepted requirements.
|
|
205
|
+
*
|
|
206
|
+
* @param paymentRequired - The PaymentRequired response from the server
|
|
207
|
+
* @returns Promise resolving to the complete payment payload
|
|
208
|
+
*/
|
|
209
|
+
createPaymentPayload(paymentRequired: PaymentRequired): Promise<PaymentPayload>;
|
|
210
|
+
/**
|
|
211
|
+
* Merges server-declared extensions with scheme-provided extensions.
|
|
212
|
+
* Scheme extensions overlay on top of server extensions at each key,
|
|
213
|
+
* preserving server-provided schema while overlaying scheme-provided info.
|
|
214
|
+
*
|
|
215
|
+
* @param serverExtensions - Extensions declared by the server in the 402 response
|
|
216
|
+
* @param schemeExtensions - Extensions provided by the scheme client (e.g. EIP-2612)
|
|
217
|
+
* @returns The merged extensions object, or undefined if both inputs are undefined
|
|
218
|
+
*/
|
|
219
|
+
private mergeExtensions;
|
|
220
|
+
/**
|
|
221
|
+
* Enriches a payment payload by calling registered extension hooks.
|
|
222
|
+
* For each extension key present in the PaymentRequired response,
|
|
223
|
+
* invokes the corresponding extension's enrichPaymentPayload callback.
|
|
224
|
+
*
|
|
225
|
+
* @param paymentPayload - The payment payload to enrich with extension data
|
|
226
|
+
* @param paymentRequired - The PaymentRequired response containing extension declarations
|
|
227
|
+
* @returns The enriched payment payload with extension data applied
|
|
228
|
+
*/
|
|
229
|
+
private enrichPaymentPayloadWithExtensions;
|
|
230
|
+
/**
|
|
231
|
+
* Selects appropriate payment requirements based on registered clients and policies.
|
|
232
|
+
*
|
|
233
|
+
* Selection process:
|
|
234
|
+
* 1. Filter by registered schemes (network + scheme support)
|
|
235
|
+
* 2. Apply all registered policies in order
|
|
236
|
+
* 3. Use selector to choose final requirement
|
|
237
|
+
*
|
|
238
|
+
* @param x402Version - The x402 protocol version
|
|
239
|
+
* @param paymentRequirements - Array of available payment requirements
|
|
240
|
+
* @returns The selected payment requirements
|
|
241
|
+
*/
|
|
242
|
+
private selectPaymentRequirements;
|
|
243
|
+
/**
|
|
244
|
+
* Internal method to register a scheme client.
|
|
245
|
+
*
|
|
246
|
+
* @param x402Version - The x402 protocol version
|
|
247
|
+
* @param network - The network to register the client for
|
|
248
|
+
* @param client - The scheme network client to register
|
|
249
|
+
* @returns The x402Client instance for chaining
|
|
250
|
+
*/
|
|
251
|
+
private _registerScheme;
|
|
252
|
+
}
|
|
253
|
+
|
|
254
|
+
/**
|
|
255
|
+
* Context provided to onPaymentRequired hooks.
|
|
256
|
+
*/
|
|
257
|
+
interface PaymentRequiredContext {
|
|
258
|
+
paymentRequired: PaymentRequired;
|
|
259
|
+
}
|
|
260
|
+
/**
|
|
261
|
+
* Hook called when a 402 response is received, before payment processing.
|
|
262
|
+
* Return headers to try before payment, or void to proceed directly to payment.
|
|
263
|
+
*/
|
|
264
|
+
type PaymentRequiredHook = (context: PaymentRequiredContext) => Promise<{
|
|
265
|
+
headers: Record<string, string>;
|
|
266
|
+
} | void>;
|
|
267
|
+
/**
|
|
268
|
+
* HTTP-specific client for handling x402 payment protocol over HTTP.
|
|
269
|
+
*
|
|
270
|
+
* Wraps a x402Client to provide HTTP-specific encoding/decoding functionality
|
|
271
|
+
* for payment headers and responses while maintaining the builder pattern.
|
|
272
|
+
*/
|
|
273
|
+
declare class x402HTTPClient {
|
|
274
|
+
private readonly client;
|
|
275
|
+
private paymentRequiredHooks;
|
|
276
|
+
/**
|
|
277
|
+
* Creates a new x402HTTPClient instance.
|
|
278
|
+
*
|
|
279
|
+
* @param client - The underlying x402Client for payment logic
|
|
280
|
+
*/
|
|
281
|
+
constructor(client: x402Client);
|
|
282
|
+
/**
|
|
283
|
+
* Register a hook to handle 402 responses before payment.
|
|
284
|
+
* Hooks run in order; first to return headers wins.
|
|
285
|
+
*
|
|
286
|
+
* @param hook - The hook function to register
|
|
287
|
+
* @returns This instance for chaining
|
|
288
|
+
*/
|
|
289
|
+
onPaymentRequired(hook: PaymentRequiredHook): this;
|
|
290
|
+
/**
|
|
291
|
+
* Run hooks and return headers if any hook provides them.
|
|
292
|
+
*
|
|
293
|
+
* @param paymentRequired - The payment required response from the server
|
|
294
|
+
* @returns Headers to use for retry, or null to proceed to payment
|
|
295
|
+
*/
|
|
296
|
+
handlePaymentRequired(paymentRequired: PaymentRequired): Promise<Record<string, string> | null>;
|
|
297
|
+
/**
|
|
298
|
+
* Encodes a payment payload into appropriate HTTP headers based on version.
|
|
299
|
+
*
|
|
300
|
+
* @param paymentPayload - The payment payload to encode
|
|
301
|
+
* @returns HTTP headers containing the encoded payment signature
|
|
302
|
+
*/
|
|
303
|
+
encodePaymentSignatureHeader(paymentPayload: PaymentPayload): Record<string, string>;
|
|
304
|
+
/**
|
|
305
|
+
* Extracts payment required information from HTTP response.
|
|
306
|
+
*
|
|
307
|
+
* @param getHeader - Function to retrieve header value by name (case-insensitive)
|
|
308
|
+
* @param body - Optional response body for v1 compatibility
|
|
309
|
+
* @returns The payment required object
|
|
310
|
+
*/
|
|
311
|
+
getPaymentRequiredResponse(getHeader: (name: string) => string | null | undefined, body?: unknown): PaymentRequired;
|
|
312
|
+
/**
|
|
313
|
+
* Extracts payment settlement response from HTTP headers.
|
|
314
|
+
*
|
|
315
|
+
* @param getHeader - Function to retrieve header value by name (case-insensitive)
|
|
316
|
+
* @returns The settlement response object
|
|
317
|
+
*/
|
|
318
|
+
getPaymentSettleResponse(getHeader: (name: string) => string | null | undefined): SettleResponse;
|
|
319
|
+
/**
|
|
320
|
+
* Creates a payment payload for the given payment requirements.
|
|
321
|
+
* Delegates to the underlying x402Client.
|
|
322
|
+
*
|
|
323
|
+
* @param paymentRequired - The payment required response from the server
|
|
324
|
+
* @returns Promise resolving to the payment payload
|
|
325
|
+
*/
|
|
326
|
+
createPaymentPayload(paymentRequired: PaymentRequired): Promise<PaymentPayload>;
|
|
327
|
+
}
|
|
328
|
+
|
|
329
|
+
export { type AfterPaymentCreationHook, type BeforePaymentCreationHook, type ClientExtension, type OnPaymentCreationFailureHook, type PaymentCreatedContext, type PaymentCreationContext, type PaymentCreationFailureContext, type PaymentPolicy, type PaymentRequiredContext, type PaymentRequiredHook, type SchemeRegistration, type SelectPaymentRequirements, x402Client, type x402ClientConfig, x402HTTPClient };
|
|
@@ -0,0 +1,330 @@
|
|
|
1
|
+
import {
|
|
2
|
+
x402HTTPClient
|
|
3
|
+
} from "../chunk-DACUCTGT.mjs";
|
|
4
|
+
import {
|
|
5
|
+
x402Version
|
|
6
|
+
} from "../chunk-DFUINDLZ.mjs";
|
|
7
|
+
import "../chunk-HRQUGJ3Y.mjs";
|
|
8
|
+
import {
|
|
9
|
+
findByNetworkAndScheme,
|
|
10
|
+
findSchemesByNetwork
|
|
11
|
+
} from "../chunk-TDLQZ6MP.mjs";
|
|
12
|
+
import "../chunk-BJTO5JO5.mjs";
|
|
13
|
+
|
|
14
|
+
// src/client/x402Client.ts
|
|
15
|
+
var x402Client = class _x402Client {
|
|
16
|
+
/**
|
|
17
|
+
* Creates a new x402Client instance.
|
|
18
|
+
*
|
|
19
|
+
* @param paymentRequirementsSelector - Function to select payment requirements from available options
|
|
20
|
+
*/
|
|
21
|
+
constructor(paymentRequirementsSelector) {
|
|
22
|
+
this.registeredClientSchemes = /* @__PURE__ */ new Map();
|
|
23
|
+
this.policies = [];
|
|
24
|
+
this.registeredExtensions = /* @__PURE__ */ new Map();
|
|
25
|
+
this.beforePaymentCreationHooks = [];
|
|
26
|
+
this.afterPaymentCreationHooks = [];
|
|
27
|
+
this.onPaymentCreationFailureHooks = [];
|
|
28
|
+
this.paymentRequirementsSelector = paymentRequirementsSelector || ((x402Version2, accepts) => accepts[0]);
|
|
29
|
+
}
|
|
30
|
+
/**
|
|
31
|
+
* Creates a new x402Client instance from a configuration object.
|
|
32
|
+
*
|
|
33
|
+
* @param config - The client configuration including schemes, policies, and payment requirements selector
|
|
34
|
+
* @returns A configured x402Client instance
|
|
35
|
+
*/
|
|
36
|
+
static fromConfig(config) {
|
|
37
|
+
const client = new _x402Client(config.paymentRequirementsSelector);
|
|
38
|
+
config.schemes.forEach((scheme) => {
|
|
39
|
+
if (scheme.x402Version === 1) {
|
|
40
|
+
client.registerV1(scheme.network, scheme.client);
|
|
41
|
+
} else {
|
|
42
|
+
client.register(scheme.network, scheme.client);
|
|
43
|
+
}
|
|
44
|
+
});
|
|
45
|
+
config.policies?.forEach((policy) => {
|
|
46
|
+
client.registerPolicy(policy);
|
|
47
|
+
});
|
|
48
|
+
return client;
|
|
49
|
+
}
|
|
50
|
+
/**
|
|
51
|
+
* Registers a scheme client for the current x402 version.
|
|
52
|
+
*
|
|
53
|
+
* @param network - The network to register the client for
|
|
54
|
+
* @param client - The scheme network client to register
|
|
55
|
+
* @returns The x402Client instance for chaining
|
|
56
|
+
*/
|
|
57
|
+
register(network, client) {
|
|
58
|
+
return this._registerScheme(x402Version, network, client);
|
|
59
|
+
}
|
|
60
|
+
/**
|
|
61
|
+
* Registers a scheme client for x402 version 1.
|
|
62
|
+
*
|
|
63
|
+
* @param network - The v1 network identifier (e.g., 'base-sepolia', 'solana-devnet')
|
|
64
|
+
* @param client - The scheme network client to register
|
|
65
|
+
* @returns The x402Client instance for chaining
|
|
66
|
+
*/
|
|
67
|
+
registerV1(network, client) {
|
|
68
|
+
return this._registerScheme(1, network, client);
|
|
69
|
+
}
|
|
70
|
+
/**
|
|
71
|
+
* Registers a policy to filter or transform payment requirements.
|
|
72
|
+
*
|
|
73
|
+
* Policies are applied in order after filtering by registered schemes
|
|
74
|
+
* and before the selector chooses the final payment requirement.
|
|
75
|
+
*
|
|
76
|
+
* @param policy - Function to filter/transform payment requirements
|
|
77
|
+
* @returns The x402Client instance for chaining
|
|
78
|
+
*
|
|
79
|
+
* @example
|
|
80
|
+
* ```typescript
|
|
81
|
+
* // Prefer cheaper options
|
|
82
|
+
* client.registerPolicy((version, reqs) =>
|
|
83
|
+
* reqs.filter(r => BigInt(r.value) < BigInt('1000000'))
|
|
84
|
+
* );
|
|
85
|
+
*
|
|
86
|
+
* // Prefer specific networks
|
|
87
|
+
* client.registerPolicy((version, reqs) =>
|
|
88
|
+
* reqs.filter(r => r.network.startsWith('eip155:'))
|
|
89
|
+
* );
|
|
90
|
+
* ```
|
|
91
|
+
*/
|
|
92
|
+
registerPolicy(policy) {
|
|
93
|
+
this.policies.push(policy);
|
|
94
|
+
return this;
|
|
95
|
+
}
|
|
96
|
+
/**
|
|
97
|
+
* Registers a client extension that can enrich payment payloads.
|
|
98
|
+
*
|
|
99
|
+
* Extensions are invoked after the scheme creates the base payload and the
|
|
100
|
+
* payload is wrapped with extensions/resource/accepted data. If the extension's
|
|
101
|
+
* key is present in `paymentRequired.extensions`, the extension's
|
|
102
|
+
* `enrichPaymentPayload` hook is called to modify the payload.
|
|
103
|
+
*
|
|
104
|
+
* @param extension - The client extension to register
|
|
105
|
+
* @returns The x402Client instance for chaining
|
|
106
|
+
*/
|
|
107
|
+
registerExtension(extension) {
|
|
108
|
+
this.registeredExtensions.set(extension.key, extension);
|
|
109
|
+
return this;
|
|
110
|
+
}
|
|
111
|
+
/**
|
|
112
|
+
* Register a hook to execute before payment payload creation.
|
|
113
|
+
* Can abort creation by returning { abort: true, reason: string }
|
|
114
|
+
*
|
|
115
|
+
* @param hook - The hook function to register
|
|
116
|
+
* @returns The x402Client instance for chaining
|
|
117
|
+
*/
|
|
118
|
+
onBeforePaymentCreation(hook) {
|
|
119
|
+
this.beforePaymentCreationHooks.push(hook);
|
|
120
|
+
return this;
|
|
121
|
+
}
|
|
122
|
+
/**
|
|
123
|
+
* Register a hook to execute after successful payment payload creation.
|
|
124
|
+
*
|
|
125
|
+
* @param hook - The hook function to register
|
|
126
|
+
* @returns The x402Client instance for chaining
|
|
127
|
+
*/
|
|
128
|
+
onAfterPaymentCreation(hook) {
|
|
129
|
+
this.afterPaymentCreationHooks.push(hook);
|
|
130
|
+
return this;
|
|
131
|
+
}
|
|
132
|
+
/**
|
|
133
|
+
* Register a hook to execute when payment payload creation fails.
|
|
134
|
+
* Can recover from failure by returning { recovered: true, payload: PaymentPayload }
|
|
135
|
+
*
|
|
136
|
+
* @param hook - The hook function to register
|
|
137
|
+
* @returns The x402Client instance for chaining
|
|
138
|
+
*/
|
|
139
|
+
onPaymentCreationFailure(hook) {
|
|
140
|
+
this.onPaymentCreationFailureHooks.push(hook);
|
|
141
|
+
return this;
|
|
142
|
+
}
|
|
143
|
+
/**
|
|
144
|
+
* Creates a payment payload based on a PaymentRequired response.
|
|
145
|
+
*
|
|
146
|
+
* Automatically extracts x402Version, resource, and extensions from the PaymentRequired
|
|
147
|
+
* response and constructs a complete PaymentPayload with the accepted requirements.
|
|
148
|
+
*
|
|
149
|
+
* @param paymentRequired - The PaymentRequired response from the server
|
|
150
|
+
* @returns Promise resolving to the complete payment payload
|
|
151
|
+
*/
|
|
152
|
+
async createPaymentPayload(paymentRequired) {
|
|
153
|
+
const clientSchemesByNetwork = this.registeredClientSchemes.get(paymentRequired.x402Version);
|
|
154
|
+
if (!clientSchemesByNetwork) {
|
|
155
|
+
throw new Error(`No client registered for x402 version: ${paymentRequired.x402Version}`);
|
|
156
|
+
}
|
|
157
|
+
const requirements = this.selectPaymentRequirements(paymentRequired.x402Version, paymentRequired.accepts);
|
|
158
|
+
const context = {
|
|
159
|
+
paymentRequired,
|
|
160
|
+
selectedRequirements: requirements
|
|
161
|
+
};
|
|
162
|
+
for (const hook of this.beforePaymentCreationHooks) {
|
|
163
|
+
const result = await hook(context);
|
|
164
|
+
if (result && "abort" in result && result.abort) {
|
|
165
|
+
throw new Error(`Payment creation aborted: ${result.reason}`);
|
|
166
|
+
}
|
|
167
|
+
}
|
|
168
|
+
try {
|
|
169
|
+
const schemeNetworkClient = findByNetworkAndScheme(clientSchemesByNetwork, requirements.scheme, requirements.network);
|
|
170
|
+
if (!schemeNetworkClient) {
|
|
171
|
+
throw new Error(`No client registered for scheme: ${requirements.scheme} and network: ${requirements.network}`);
|
|
172
|
+
}
|
|
173
|
+
const partialPayload = await schemeNetworkClient.createPaymentPayload(
|
|
174
|
+
paymentRequired.x402Version,
|
|
175
|
+
requirements,
|
|
176
|
+
{ extensions: paymentRequired.extensions }
|
|
177
|
+
);
|
|
178
|
+
let paymentPayload;
|
|
179
|
+
if (partialPayload.x402Version == 1) {
|
|
180
|
+
paymentPayload = partialPayload;
|
|
181
|
+
} else {
|
|
182
|
+
const mergedExtensions = this.mergeExtensions(
|
|
183
|
+
paymentRequired.extensions,
|
|
184
|
+
partialPayload.extensions
|
|
185
|
+
);
|
|
186
|
+
paymentPayload = {
|
|
187
|
+
x402Version: partialPayload.x402Version,
|
|
188
|
+
payload: partialPayload.payload,
|
|
189
|
+
extensions: mergedExtensions,
|
|
190
|
+
resource: paymentRequired.resource,
|
|
191
|
+
accepted: requirements
|
|
192
|
+
};
|
|
193
|
+
}
|
|
194
|
+
paymentPayload = await this.enrichPaymentPayloadWithExtensions(paymentPayload, paymentRequired);
|
|
195
|
+
const createdContext = {
|
|
196
|
+
...context,
|
|
197
|
+
paymentPayload
|
|
198
|
+
};
|
|
199
|
+
for (const hook of this.afterPaymentCreationHooks) {
|
|
200
|
+
await hook(createdContext);
|
|
201
|
+
}
|
|
202
|
+
return paymentPayload;
|
|
203
|
+
} catch (error) {
|
|
204
|
+
const failureContext = {
|
|
205
|
+
...context,
|
|
206
|
+
error
|
|
207
|
+
};
|
|
208
|
+
for (const hook of this.onPaymentCreationFailureHooks) {
|
|
209
|
+
const result = await hook(failureContext);
|
|
210
|
+
if (result && "recovered" in result && result.recovered) {
|
|
211
|
+
return result.payload;
|
|
212
|
+
}
|
|
213
|
+
}
|
|
214
|
+
throw error;
|
|
215
|
+
}
|
|
216
|
+
}
|
|
217
|
+
/**
|
|
218
|
+
* Merges server-declared extensions with scheme-provided extensions.
|
|
219
|
+
* Scheme extensions overlay on top of server extensions at each key,
|
|
220
|
+
* preserving server-provided schema while overlaying scheme-provided info.
|
|
221
|
+
*
|
|
222
|
+
* @param serverExtensions - Extensions declared by the server in the 402 response
|
|
223
|
+
* @param schemeExtensions - Extensions provided by the scheme client (e.g. EIP-2612)
|
|
224
|
+
* @returns The merged extensions object, or undefined if both inputs are undefined
|
|
225
|
+
*/
|
|
226
|
+
mergeExtensions(serverExtensions, schemeExtensions) {
|
|
227
|
+
if (!schemeExtensions) return serverExtensions;
|
|
228
|
+
if (!serverExtensions) return schemeExtensions;
|
|
229
|
+
const merged = { ...serverExtensions };
|
|
230
|
+
for (const [key, schemeValue] of Object.entries(schemeExtensions)) {
|
|
231
|
+
const serverValue = merged[key];
|
|
232
|
+
if (serverValue && typeof serverValue === "object" && schemeValue && typeof schemeValue === "object") {
|
|
233
|
+
merged[key] = { ...serverValue, ...schemeValue };
|
|
234
|
+
} else {
|
|
235
|
+
merged[key] = schemeValue;
|
|
236
|
+
}
|
|
237
|
+
}
|
|
238
|
+
return merged;
|
|
239
|
+
}
|
|
240
|
+
/**
|
|
241
|
+
* Enriches a payment payload by calling registered extension hooks.
|
|
242
|
+
* For each extension key present in the PaymentRequired response,
|
|
243
|
+
* invokes the corresponding extension's enrichPaymentPayload callback.
|
|
244
|
+
*
|
|
245
|
+
* @param paymentPayload - The payment payload to enrich with extension data
|
|
246
|
+
* @param paymentRequired - The PaymentRequired response containing extension declarations
|
|
247
|
+
* @returns The enriched payment payload with extension data applied
|
|
248
|
+
*/
|
|
249
|
+
async enrichPaymentPayloadWithExtensions(paymentPayload, paymentRequired) {
|
|
250
|
+
if (!paymentRequired.extensions || this.registeredExtensions.size === 0) {
|
|
251
|
+
return paymentPayload;
|
|
252
|
+
}
|
|
253
|
+
let enriched = paymentPayload;
|
|
254
|
+
for (const [key, extension] of this.registeredExtensions) {
|
|
255
|
+
if (key in paymentRequired.extensions && extension.enrichPaymentPayload) {
|
|
256
|
+
enriched = await extension.enrichPaymentPayload(enriched, paymentRequired);
|
|
257
|
+
}
|
|
258
|
+
}
|
|
259
|
+
return enriched;
|
|
260
|
+
}
|
|
261
|
+
/**
|
|
262
|
+
* Selects appropriate payment requirements based on registered clients and policies.
|
|
263
|
+
*
|
|
264
|
+
* Selection process:
|
|
265
|
+
* 1. Filter by registered schemes (network + scheme support)
|
|
266
|
+
* 2. Apply all registered policies in order
|
|
267
|
+
* 3. Use selector to choose final requirement
|
|
268
|
+
*
|
|
269
|
+
* @param x402Version - The x402 protocol version
|
|
270
|
+
* @param paymentRequirements - Array of available payment requirements
|
|
271
|
+
* @returns The selected payment requirements
|
|
272
|
+
*/
|
|
273
|
+
selectPaymentRequirements(x402Version2, paymentRequirements) {
|
|
274
|
+
const clientSchemesByNetwork = this.registeredClientSchemes.get(x402Version2);
|
|
275
|
+
if (!clientSchemesByNetwork) {
|
|
276
|
+
throw new Error(`No client registered for x402 version: ${x402Version2}`);
|
|
277
|
+
}
|
|
278
|
+
const supportedPaymentRequirements = paymentRequirements.filter((requirement) => {
|
|
279
|
+
let clientSchemes = findSchemesByNetwork(clientSchemesByNetwork, requirement.network);
|
|
280
|
+
if (!clientSchemes) {
|
|
281
|
+
return false;
|
|
282
|
+
}
|
|
283
|
+
return clientSchemes.has(requirement.scheme);
|
|
284
|
+
});
|
|
285
|
+
if (supportedPaymentRequirements.length === 0) {
|
|
286
|
+
throw new Error(`No network/scheme registered for x402 version: ${x402Version2} which comply with the payment requirements. ${JSON.stringify({
|
|
287
|
+
x402Version: x402Version2,
|
|
288
|
+
paymentRequirements,
|
|
289
|
+
x402Versions: Array.from(this.registeredClientSchemes.keys()),
|
|
290
|
+
networks: Array.from(clientSchemesByNetwork.keys()),
|
|
291
|
+
schemes: Array.from(clientSchemesByNetwork.values()).map((schemes) => Array.from(schemes.keys())).flat()
|
|
292
|
+
})}`);
|
|
293
|
+
}
|
|
294
|
+
let filteredRequirements = supportedPaymentRequirements;
|
|
295
|
+
for (const policy of this.policies) {
|
|
296
|
+
filteredRequirements = policy(x402Version2, filteredRequirements);
|
|
297
|
+
if (filteredRequirements.length === 0) {
|
|
298
|
+
throw new Error(`All payment requirements were filtered out by policies for x402 version: ${x402Version2}`);
|
|
299
|
+
}
|
|
300
|
+
}
|
|
301
|
+
return this.paymentRequirementsSelector(x402Version2, filteredRequirements);
|
|
302
|
+
}
|
|
303
|
+
/**
|
|
304
|
+
* Internal method to register a scheme client.
|
|
305
|
+
*
|
|
306
|
+
* @param x402Version - The x402 protocol version
|
|
307
|
+
* @param network - The network to register the client for
|
|
308
|
+
* @param client - The scheme network client to register
|
|
309
|
+
* @returns The x402Client instance for chaining
|
|
310
|
+
*/
|
|
311
|
+
_registerScheme(x402Version2, network, client) {
|
|
312
|
+
if (!this.registeredClientSchemes.has(x402Version2)) {
|
|
313
|
+
this.registeredClientSchemes.set(x402Version2, /* @__PURE__ */ new Map());
|
|
314
|
+
}
|
|
315
|
+
const clientSchemesByNetwork = this.registeredClientSchemes.get(x402Version2);
|
|
316
|
+
if (!clientSchemesByNetwork.has(network)) {
|
|
317
|
+
clientSchemesByNetwork.set(network, /* @__PURE__ */ new Map());
|
|
318
|
+
}
|
|
319
|
+
const clientByScheme = clientSchemesByNetwork.get(network);
|
|
320
|
+
if (!clientByScheme.has(client.scheme)) {
|
|
321
|
+
clientByScheme.set(client.scheme, client);
|
|
322
|
+
}
|
|
323
|
+
return this;
|
|
324
|
+
}
|
|
325
|
+
};
|
|
326
|
+
export {
|
|
327
|
+
x402Client,
|
|
328
|
+
x402HTTPClient
|
|
329
|
+
};
|
|
330
|
+
//# sourceMappingURL=index.mjs.map
|