@okxweb3/app-x402-core 0.1.2 → 0.2.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/dist/cjs/OKXFacilitatorClient-Bqyw9fzj.d.ts +69 -0
- package/dist/cjs/client/index.d.ts +1 -1
- package/dist/cjs/client/index.js +34 -0
- package/dist/cjs/client/index.js.map +1 -1
- package/dist/cjs/facilitator/index.d.ts +2 -2
- package/dist/cjs/facilitator/index.js +166 -4
- package/dist/cjs/facilitator/index.js.map +1 -1
- package/dist/cjs/http/index.d.ts +5 -3
- package/dist/cjs/http/index.js +1241 -7
- package/dist/cjs/http/index.js.map +1 -1
- package/dist/cjs/index-2gWfiUbK.d.ts +713 -0
- package/dist/cjs/index.d.ts +2 -2
- package/dist/cjs/index.js +166 -4
- package/dist/cjs/index.js.map +1 -1
- package/dist/cjs/{mechanisms-sojpSwWW.d.ts → mechanisms-LhI9qkRo.d.ts} +509 -1
- package/dist/cjs/server/index.d.ts +4 -2
- package/dist/cjs/server/index.js +1256 -7
- package/dist/cjs/server/index.js.map +1 -1
- package/dist/cjs/subscription/index.d.ts +3 -0
- package/dist/cjs/subscription/index.js +600 -0
- package/dist/cjs/subscription/index.js.map +1 -0
- package/dist/cjs/types/index.d.ts +1 -1
- package/dist/cjs/utils/index.d.ts +1 -1
- package/dist/cjs/{x402HTTPResourceServer-CcsAkcgI.d.ts → x402HTTPResourceServer-B0mXzV8r.d.ts} +114 -1
- package/dist/esm/OKXFacilitatorClient-z-cCE5Db.d.mts +69 -0
- package/dist/esm/chunk-4KASWSSY.mjs +257 -0
- package/dist/esm/chunk-4KASWSSY.mjs.map +1 -0
- package/dist/esm/chunk-CKXR4QVD.mjs +274 -0
- package/dist/esm/chunk-CKXR4QVD.mjs.map +1 -0
- package/dist/esm/{chunk-XBQG2CDV.mjs → chunk-EYS4TWVA.mjs} +617 -9
- package/dist/esm/chunk-EYS4TWVA.mjs.map +1 -0
- package/dist/esm/client/index.d.mts +1 -1
- package/dist/esm/client/index.mjs +3 -2
- package/dist/esm/client/index.mjs.map +1 -1
- package/dist/esm/facilitator/index.d.mts +2 -2
- package/dist/esm/facilitator/index.mjs +2 -1
- package/dist/esm/facilitator/index.mjs.map +1 -1
- package/dist/esm/http/index.d.mts +5 -3
- package/dist/esm/http/index.mjs +3 -2
- package/dist/esm/index-DKbqlTu_.d.mts +713 -0
- package/dist/esm/index.d.mts +2 -2
- package/dist/esm/index.mjs +2 -1
- package/dist/esm/{mechanisms-sojpSwWW.d.mts → mechanisms-LhI9qkRo.d.mts} +509 -1
- package/dist/esm/server/index.d.mts +4 -2
- package/dist/esm/server/index.mjs +3 -2
- package/dist/esm/subscription/index.d.mts +3 -0
- package/dist/esm/subscription/index.mjs +309 -0
- package/dist/esm/subscription/index.mjs.map +1 -0
- package/dist/esm/types/index.d.mts +1 -1
- package/dist/esm/utils/index.d.mts +1 -1
- package/dist/esm/{x402HTTPResourceServer-DBeutKxq.d.mts → x402HTTPResourceServer-56Tq3Jup.d.mts} +114 -1
- package/package.json +12 -1
- package/dist/cjs/OKXFacilitatorClient-BvyQB1QM.d.ts +0 -59
- package/dist/esm/OKXFacilitatorClient-D5E3LX50.d.mts +0 -59
- package/dist/esm/chunk-O3IYMTNT.mjs +0 -118
- package/dist/esm/chunk-O3IYMTNT.mjs.map +0 -1
- package/dist/esm/chunk-XBQG2CDV.mjs.map +0 -1
|
@@ -1,3 +1,467 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Subscription state: `active`, `canceled`, `completed`, `changed`.
|
|
3
|
+
*/
|
|
4
|
+
/**
|
|
5
|
+
* Local mirror of facilitator's SubscriptionState enum. Numeric mapping:
|
|
6
|
+
* 0 pending / 1 active / 2 completed / 3 canceled / 4 changed / 99 failed
|
|
7
|
+
*/
|
|
8
|
+
type SubscriptionState = "pending" | "active" | "completed" | "canceled" | "changed" | "failed";
|
|
9
|
+
/**
|
|
10
|
+
* Set on an ACTIVE sub when a downgrade has been scheduled but not yet
|
|
11
|
+
* activated. `state` lets the seller observe the terminal disposition
|
|
12
|
+
* (PENDING / ACTIVATED / CANCELED / EXPIRED) via GET /pending.
|
|
13
|
+
*/
|
|
14
|
+
interface PendingPlanChange {
|
|
15
|
+
subId: string;
|
|
16
|
+
newSubId: string;
|
|
17
|
+
effectiveFromPeriod: number;
|
|
18
|
+
/** 0 pending / 1 activated / 2 canceled / 3 expired. */
|
|
19
|
+
state: number;
|
|
20
|
+
}
|
|
21
|
+
/**
|
|
22
|
+
* Seller-side projection of a subscription. All fields come from the
|
|
23
|
+
* facilitator GET /subscriptions/detail endpoint; the store never holds
|
|
24
|
+
* data the facilitator can't refresh.
|
|
25
|
+
*
|
|
26
|
+
* Snapshot fields (`isActive` / `serviceEnded` / `currentPeriod` /
|
|
27
|
+
* `elapsedPeriods` / `nextChargeableAt`) are valid as of the last sync
|
|
28
|
+
* only; they drift with wall-clock time.
|
|
29
|
+
*/
|
|
30
|
+
interface Subscription {
|
|
31
|
+
subId: string;
|
|
32
|
+
payer: string;
|
|
33
|
+
merchant: string;
|
|
34
|
+
token: string;
|
|
35
|
+
amountPerPeriod: string;
|
|
36
|
+
/** 0 fixed_seconds / 1 calendar_month. */
|
|
37
|
+
periodMode: number;
|
|
38
|
+
periodSec: number;
|
|
39
|
+
/** Calendar-month billing anchor (Unix s). Undefined or 0 in fixed_seconds mode. */
|
|
40
|
+
billingAnchorAt?: number;
|
|
41
|
+
maxPeriods: number;
|
|
42
|
+
startAt: number;
|
|
43
|
+
state: SubscriptionState;
|
|
44
|
+
lastChargedPeriod: number;
|
|
45
|
+
totalPulled: string;
|
|
46
|
+
planId: string;
|
|
47
|
+
planTier: number;
|
|
48
|
+
changedToSubId?: string;
|
|
49
|
+
pendingPlanChange?: PendingPlanChange;
|
|
50
|
+
/** Derived snapshot — true iff state==ACTIVE && now < endAt. */
|
|
51
|
+
isActive?: boolean;
|
|
52
|
+
/** Derived snapshot — true iff state==ACTIVE && !isActive (expired, not yet finalized). */
|
|
53
|
+
serviceEnded?: boolean;
|
|
54
|
+
/** Derived snapshot — current period number, clamped to maxPeriods. */
|
|
55
|
+
currentPeriod?: number;
|
|
56
|
+
/** Derived snapshot — real elapsed period count, NOT clamped (use this for expiry checks). */
|
|
57
|
+
elapsedPeriods?: number;
|
|
58
|
+
/** Derived snapshot — next chargeable boundary (Unix s); null when all periods are charged. */
|
|
59
|
+
nextChargeableAt?: number;
|
|
60
|
+
}
|
|
61
|
+
interface AccessProof {
|
|
62
|
+
kind: "subscription-id";
|
|
63
|
+
subId: string;
|
|
64
|
+
payer: string;
|
|
65
|
+
timestamp: number;
|
|
66
|
+
signature: string;
|
|
67
|
+
}
|
|
68
|
+
/**
|
|
69
|
+
* `CancelAuth.initiator` enum — only payer / merchant.
|
|
70
|
+
*/
|
|
71
|
+
type CancelInitiator = "payer" | "merchant";
|
|
72
|
+
/**
|
|
73
|
+
* EIP-712 `CancelAuth` payload (subscription contract domain):
|
|
74
|
+
* `CancelAuth(uint8 action, bytes32 subId, uint8 initiator, bytes32 nonce, uint64 deadline)`
|
|
75
|
+
*
|
|
76
|
+
* `action` is locked to `0 = cancel_subscription`. `cancel_pending_change`
|
|
77
|
+
* uses the standalone `cancel-pending-change` endpoint with its own
|
|
78
|
+
* `PendingChangeCancelAuth` signature.
|
|
79
|
+
*/
|
|
80
|
+
interface CancelAuth {
|
|
81
|
+
action: 0;
|
|
82
|
+
subId: string;
|
|
83
|
+
initiator: 0 | 1;
|
|
84
|
+
nonce: string;
|
|
85
|
+
deadline: number;
|
|
86
|
+
signature: string;
|
|
87
|
+
}
|
|
88
|
+
/**
|
|
89
|
+
* EIP-712 `PendingChangeCancelAuth` payload (subscription contract domain).
|
|
90
|
+
* Payer-only.
|
|
91
|
+
*
|
|
92
|
+
* TypeHash:
|
|
93
|
+
* keccak256("PendingChangeCancelAuth(bytes32 subId,bytes32 newSubId,bytes32 nonce,uint64 deadline)")
|
|
94
|
+
*
|
|
95
|
+
* `newSubId` MUST equal the currently-PENDING `pendingPlanChange.newSubId`
|
|
96
|
+
* (the to-be-cancelled downgrade target); facilitator rejects with
|
|
97
|
+
* `pending_cancel_target_mismatch` otherwise.
|
|
98
|
+
*/
|
|
99
|
+
interface PendingChangeCancelAuth {
|
|
100
|
+
subId: string;
|
|
101
|
+
newSubId: string;
|
|
102
|
+
nonce: string;
|
|
103
|
+
deadline: number;
|
|
104
|
+
signature: string;
|
|
105
|
+
}
|
|
106
|
+
interface PlanInitialCharge {
|
|
107
|
+
periodCount: number;
|
|
108
|
+
totalAmount: string;
|
|
109
|
+
}
|
|
110
|
+
interface PlanCatalogEntry {
|
|
111
|
+
id: string;
|
|
112
|
+
tier: number;
|
|
113
|
+
amountPerPeriod: string;
|
|
114
|
+
/** 0 fixed_seconds (default) / 1 calendar_month. */
|
|
115
|
+
periodMode?: 0 | 1;
|
|
116
|
+
periodSec: number;
|
|
117
|
+
maxPeriods: number;
|
|
118
|
+
/**
|
|
119
|
+
* ERC-20 token address. Optional — if omitted, the EVM scheme fills from
|
|
120
|
+
* `getDefaultAsset(network)` (same per-network map exact / upto /
|
|
121
|
+
* aggr_deferred consume).
|
|
122
|
+
*/
|
|
123
|
+
asset?: string;
|
|
124
|
+
payTo: string;
|
|
125
|
+
initialCharge?: PlanInitialCharge;
|
|
126
|
+
name?: string;
|
|
127
|
+
}
|
|
128
|
+
type PlanCatalog = Record<string, PlanCatalogEntry>;
|
|
129
|
+
interface AccessRouteRequirements {
|
|
130
|
+
/**
|
|
131
|
+
* PlanIds that satisfy this route. Derived from the route's `accepts`
|
|
132
|
+
* payment options (`accepts[].extra.plan.id`). A subscription is allowed
|
|
133
|
+
* access iff its `planId` appears in this list.
|
|
134
|
+
*
|
|
135
|
+
* `undefined` means "no plan restriction" — any active subscription on
|
|
136
|
+
* the route passes (use sparingly).
|
|
137
|
+
*/
|
|
138
|
+
acceptedPlanIds?: string[];
|
|
139
|
+
/**
|
|
140
|
+
* Full `PaymentRequirements` for every plan the route accepts — the same
|
|
141
|
+
* list the seller declared as `RouteConfig.accepts`, resolved to wire
|
|
142
|
+
* format. Each entry carries the plan metadata in `extra.plan`
|
|
143
|
+
* (`{ id, tier, name }`) plus `extra.amountPerPeriod`, `extra.periodSec`,
|
|
144
|
+
* `extra.periodMode`, `extra.maxPeriods`, etc. — everything an
|
|
145
|
+
* `onBeforeAccess` hook needs to decide policy against catalog details
|
|
146
|
+
* (upgrade offers, tier ceilings, per-plan feature flags) without joining
|
|
147
|
+
* an external catalog table.
|
|
148
|
+
*/
|
|
149
|
+
accepts?: PaymentRequirements[];
|
|
150
|
+
}
|
|
151
|
+
/**
|
|
152
|
+
* Context passed to `OnBeforeAccessHook`. Carries the full stored
|
|
153
|
+
* `Subscription` (so the seller can inspect any field — payer, planId,
|
|
154
|
+
* lastChargedPeriod, changedToSubId, etc. — for arbitrary policy) plus
|
|
155
|
+
* the incoming HTTP request shape and route metadata.
|
|
156
|
+
*/
|
|
157
|
+
interface OnBeforeAccessContext {
|
|
158
|
+
subscription: Subscription;
|
|
159
|
+
request: {
|
|
160
|
+
path: string;
|
|
161
|
+
method: string;
|
|
162
|
+
headers: Record<string, string>;
|
|
163
|
+
};
|
|
164
|
+
route: AccessRouteRequirements;
|
|
165
|
+
}
|
|
166
|
+
/**
|
|
167
|
+
* Result of an `OnBeforeAccessHook`:
|
|
168
|
+
* - `{ ok: true }` → allow the request through
|
|
169
|
+
* - `{ ok: false }` → deny; `error` shows up in the 402 body, `retryAfter`
|
|
170
|
+
* (seconds) becomes a `Retry-After` header hint, `upgradeOffers` lets
|
|
171
|
+
* the seller point the buyer at an alternate plan
|
|
172
|
+
*
|
|
173
|
+
* Denial use cases: rate-limiting, quota exhaustion, bans / blacklists,
|
|
174
|
+
* per-plan feature gating beyond the simple `acceptedPlanIds` allowlist.
|
|
175
|
+
*/
|
|
176
|
+
type OnBeforeAccessResult = {
|
|
177
|
+
ok: true;
|
|
178
|
+
} | {
|
|
179
|
+
ok: false;
|
|
180
|
+
error?: string;
|
|
181
|
+
retryAfter?: number;
|
|
182
|
+
upgradeOffers?: PaymentRequirements[];
|
|
183
|
+
};
|
|
184
|
+
/**
|
|
185
|
+
* Route-level hook fired AFTER `verifyAccess` succeeded (signature +
|
|
186
|
+
* payer + plan-allowlist + period math) but BEFORE the handler runs.
|
|
187
|
+
* The seller uses it to implement custom access policy — e.g. a ban list
|
|
188
|
+
* keyed by subId or payer, per-plan feature flags, or dynamic quota.
|
|
189
|
+
*/
|
|
190
|
+
type OnBeforeAccessHook = (ctx: OnBeforeAccessContext) => Promise<OnBeforeAccessResult>;
|
|
191
|
+
type VerifyResultOk = {
|
|
192
|
+
ok: true;
|
|
193
|
+
};
|
|
194
|
+
type VerifyResultFail = {
|
|
195
|
+
ok: false;
|
|
196
|
+
error: string;
|
|
197
|
+
};
|
|
198
|
+
type VerifyResult = VerifyResultOk | VerifyResultFail;
|
|
199
|
+
interface VerifyChangeOk {
|
|
200
|
+
ok: true;
|
|
201
|
+
oldSubId: string;
|
|
202
|
+
direction: "upgrade" | "downgrade";
|
|
203
|
+
}
|
|
204
|
+
type VerifyChangeResult = VerifyChangeOk | VerifyResultFail;
|
|
205
|
+
interface VerifyAccessOk {
|
|
206
|
+
ok: true;
|
|
207
|
+
subscription: Subscription;
|
|
208
|
+
}
|
|
209
|
+
type VerifyAccessResult = VerifyAccessOk | VerifyResultFail;
|
|
210
|
+
/**
|
|
211
|
+
* Result of `verifyOwnership` — used by the change-route sniff path to
|
|
212
|
+
* confirm the AccessProof signer owns the named subscription, without
|
|
213
|
+
* imposing the plan-allowlist / period-math gating that `verifyAccess`
|
|
214
|
+
* applies for resource consumption.
|
|
215
|
+
*/
|
|
216
|
+
interface VerifyOwnershipOk {
|
|
217
|
+
ok: true;
|
|
218
|
+
subId: string;
|
|
219
|
+
payer: string;
|
|
220
|
+
subscription: Subscription;
|
|
221
|
+
}
|
|
222
|
+
type VerifyOwnershipResult = VerifyOwnershipOk | VerifyResultFail;
|
|
223
|
+
type SettleResultFail = {
|
|
224
|
+
success: false;
|
|
225
|
+
error: string;
|
|
226
|
+
/**
|
|
227
|
+
* Set when the chain operation may still complete asynchronously: the
|
|
228
|
+
* facilitator accepted the write call but returned `state=pending`, and the
|
|
229
|
+
* SDK's client-side polling (5×1s) timed out before settlement. Seller
|
|
230
|
+
* should remember `subId` and call `syncFromChain(subId)` later.
|
|
231
|
+
*/
|
|
232
|
+
subId?: string;
|
|
233
|
+
pending?: boolean;
|
|
234
|
+
};
|
|
235
|
+
interface SettleSubscribeOk {
|
|
236
|
+
success: true;
|
|
237
|
+
subId: string;
|
|
238
|
+
subscription: Subscription;
|
|
239
|
+
headers: Record<string, string>;
|
|
240
|
+
}
|
|
241
|
+
type SettleSubscribeResult = SettleSubscribeOk | SettleResultFail;
|
|
242
|
+
interface SettleChangeOk {
|
|
243
|
+
success: true;
|
|
244
|
+
oldSubId: string;
|
|
245
|
+
newSubId: string;
|
|
246
|
+
operationType: "upgrade" | "downgrade";
|
|
247
|
+
scheduledFromPeriod?: number;
|
|
248
|
+
headers: Record<string, string>;
|
|
249
|
+
}
|
|
250
|
+
type SettleChangeResult = SettleChangeOk | SettleResultFail;
|
|
251
|
+
interface SettleCancelOk {
|
|
252
|
+
success: true;
|
|
253
|
+
subId: string;
|
|
254
|
+
headers: Record<string, string>;
|
|
255
|
+
}
|
|
256
|
+
type SettleCancelResult = SettleCancelOk | SettleResultFail;
|
|
257
|
+
/**
|
|
258
|
+
* Result of `settleCancelPendingChange` — cancels a scheduled downgrade
|
|
259
|
+
* (removes `pendingPlanChange` on the old sub while the sub itself stays
|
|
260
|
+
* ACTIVE). No refund, no state transition on the sub itself.
|
|
261
|
+
*/
|
|
262
|
+
interface SettleCancelPendingChangeOk {
|
|
263
|
+
success: true;
|
|
264
|
+
subId: string;
|
|
265
|
+
headers: Record<string, string>;
|
|
266
|
+
}
|
|
267
|
+
type SettleCancelPendingChangeResult = SettleCancelPendingChangeOk | SettleResultFail;
|
|
268
|
+
interface ChargeResult {
|
|
269
|
+
success: true;
|
|
270
|
+
period: number;
|
|
271
|
+
amount: string;
|
|
272
|
+
txHash?: string;
|
|
273
|
+
planChangeTriggered?: boolean;
|
|
274
|
+
newSubId?: string;
|
|
275
|
+
}
|
|
276
|
+
interface SubscriptionCapability {
|
|
277
|
+
readonly settlementMode: "pre";
|
|
278
|
+
verifySubscribe(payload: PaymentPayload, requirements: PaymentRequirements): Promise<VerifyResult>;
|
|
279
|
+
settleSubscribe(payload: PaymentPayload, requirements: PaymentRequirements): Promise<SettleSubscribeResult>;
|
|
280
|
+
/**
|
|
281
|
+
* Inject `extra.changeFrom = { fromSubId, fromPlanId, fromPlanTier,
|
|
282
|
+
* direction, effectiveAt }` into each accept of a change route's 402
|
|
283
|
+
* accepts. Direction / effectiveAt are derived per-accept by comparing
|
|
284
|
+
* `accept.extra.plan.tier` against the stored `oldSub.planTier`. Same-tier
|
|
285
|
+
* accepts are dropped (a change to the same tier is illegal —
|
|
286
|
+
* `tier_same`).
|
|
287
|
+
*
|
|
288
|
+
* Returns `null` when the seller's local store has no record of
|
|
289
|
+
* `currentSubId` — middleware then 404s the GET so buyers see the misuse.
|
|
290
|
+
*/
|
|
291
|
+
enrichAcceptsForChange(accepts: PaymentRequirements[], currentSubId: string): Promise<PaymentRequirements[] | null>;
|
|
292
|
+
verifyChange(payload: PaymentPayload, requirements: PaymentRequirements): Promise<VerifyChangeResult>;
|
|
293
|
+
settleChange(payload: PaymentPayload, requirements: PaymentRequirements): Promise<SettleChangeResult>;
|
|
294
|
+
verifyCancel(auth: CancelAuth, subId: string): Promise<VerifyResult>;
|
|
295
|
+
settleCancel(auth: CancelAuth, subId: string): Promise<SettleCancelResult>;
|
|
296
|
+
/**
|
|
297
|
+
* Verify a `PendingChangeCancelAuth` before facilitator submission.
|
|
298
|
+
* Requires `auth.subId == body.subId` and `auth.newSubId` equal to the
|
|
299
|
+
* currently PENDING `pendingPlanChange.newSubId` — the SDK checks the
|
|
300
|
+
* former; facilitator enforces the latter as
|
|
301
|
+
* `pending_cancel_target_mismatch`.
|
|
302
|
+
*/
|
|
303
|
+
verifyCancelPendingChange(auth: PendingChangeCancelAuth, subId: string): Promise<VerifyResult>;
|
|
304
|
+
/**
|
|
305
|
+
* Cancel a scheduled downgrade (`pendingPlanChange`) — the current sub
|
|
306
|
+
* stays ACTIVE, only the pending row is retired. Facilitator returns the
|
|
307
|
+
* new state; SDK re-pulls GET /detail to refresh the store entry.
|
|
308
|
+
*/
|
|
309
|
+
settleCancelPendingChange(auth: PendingChangeCancelAuth, subId: string): Promise<SettleCancelPendingChangeResult>;
|
|
310
|
+
verifyAccess(proof: AccessProof, route: AccessRouteRequirements): Promise<VerifyAccessResult>;
|
|
311
|
+
/**
|
|
312
|
+
* Lightweight ownership check for the change-route sniff path. Verifies
|
|
313
|
+
* the AccessProof signature, looks up the sub in the store, and confirms
|
|
314
|
+
* `sub.payer == proof.payer`. Deliberately does NOT enforce plan
|
|
315
|
+
* allowlist or period math — the caller is identifying themselves to
|
|
316
|
+
* receive change offers, not consuming a protected resource.
|
|
317
|
+
*/
|
|
318
|
+
verifyOwnership(proof: AccessProof): Promise<VerifyOwnershipResult>;
|
|
319
|
+
charge(subId: string): Promise<ChargeResult>;
|
|
320
|
+
getSubscription(subId: string): Promise<Subscription | null>;
|
|
321
|
+
}
|
|
322
|
+
declare function hasSubscriptionCapability(scheme: unknown): scheme is SubscriptionCapability;
|
|
323
|
+
|
|
324
|
+
/**
|
|
325
|
+
* Standard OKX facilitator response envelope. `code === 0` means success
|
|
326
|
+
* (NUMBER, not string).
|
|
327
|
+
*/
|
|
328
|
+
interface FacilitatorEnvelope<T> {
|
|
329
|
+
code: number;
|
|
330
|
+
msg?: string | null;
|
|
331
|
+
data?: T;
|
|
332
|
+
}
|
|
333
|
+
/** POST /api/v6/pay/x402/subscriptions response data. */
|
|
334
|
+
interface FacilitatorSubscribeData {
|
|
335
|
+
subId: string;
|
|
336
|
+
txHash?: string;
|
|
337
|
+
state: number;
|
|
338
|
+
}
|
|
339
|
+
/** POST /api/v6/pay/x402/subscriptions/change response data. */
|
|
340
|
+
interface FacilitatorChangeData {
|
|
341
|
+
newSubId: string;
|
|
342
|
+
txHash?: string;
|
|
343
|
+
state: number;
|
|
344
|
+
}
|
|
345
|
+
/** POST /api/v6/pay/x402/subscriptions/{id}/cancel response data. */
|
|
346
|
+
interface FacilitatorCancelData {
|
|
347
|
+
subId: string;
|
|
348
|
+
txHash?: string;
|
|
349
|
+
state: number;
|
|
350
|
+
}
|
|
351
|
+
/** POST /api/v6/pay/x402/subscriptions/{id}/cancel-pending-change response data. */
|
|
352
|
+
interface FacilitatorCancelPendingData {
|
|
353
|
+
subId: string;
|
|
354
|
+
txHash?: string;
|
|
355
|
+
state: number;
|
|
356
|
+
}
|
|
357
|
+
/** POST /api/v6/pay/x402/subscriptions/{id}/charge response data. */
|
|
358
|
+
interface FacilitatorChargeData {
|
|
359
|
+
subId: string;
|
|
360
|
+
period: number;
|
|
361
|
+
txHash?: string;
|
|
362
|
+
/** SubscriptionChargeState — 0 pending / 1 success / 2 failed. */
|
|
363
|
+
state: number;
|
|
364
|
+
planChangeTriggered?: boolean;
|
|
365
|
+
newSubId?: string | null;
|
|
366
|
+
}
|
|
367
|
+
/** POST /api/v6/pay/x402/subscriptions/{id}/finalize-expired response data. */
|
|
368
|
+
interface FacilitatorFinalizeExpiredData {
|
|
369
|
+
subId: string;
|
|
370
|
+
txHash?: string;
|
|
371
|
+
state: number;
|
|
372
|
+
}
|
|
373
|
+
/** One row of the charges feed (GET /api/v6/pay/x402/subscriptions/charges). */
|
|
374
|
+
interface FacilitatorChargeRow {
|
|
375
|
+
subId: string;
|
|
376
|
+
period: number;
|
|
377
|
+
/** 1 initial / 2 periodic / 3 downgrade_first_period / 4 finalize_expired_marker. */
|
|
378
|
+
chargeType: number;
|
|
379
|
+
amount: string;
|
|
380
|
+
/** 0 pending / 1 success / 2 failed. */
|
|
381
|
+
state: number;
|
|
382
|
+
txHash?: string;
|
|
383
|
+
planChangeTriggered?: boolean;
|
|
384
|
+
newSubId?: string | null;
|
|
385
|
+
}
|
|
386
|
+
/** GET /api/v6/pay/x402/subscriptions/charges response data. */
|
|
387
|
+
interface FacilitatorGetChargesData {
|
|
388
|
+
charges: FacilitatorChargeRow[];
|
|
389
|
+
}
|
|
390
|
+
/** GET /api/v6/pay/x402/subscriptions/pending response data (most recent row). */
|
|
391
|
+
interface FacilitatorPendingChangeRow {
|
|
392
|
+
subId: string;
|
|
393
|
+
newSubId: string;
|
|
394
|
+
effectiveFromPeriod: number;
|
|
395
|
+
/** 0 pending / 1 activated / 2 canceled / 3 expired. */
|
|
396
|
+
state: number;
|
|
397
|
+
}
|
|
398
|
+
/** GET /api/v6/pay/x402/subscriptions/{id} response data. */
|
|
399
|
+
interface FacilitatorGetSubscriptionData {
|
|
400
|
+
subId: string;
|
|
401
|
+
state: number;
|
|
402
|
+
payer: string;
|
|
403
|
+
merchant: string;
|
|
404
|
+
token: string;
|
|
405
|
+
amountPerPeriod: string;
|
|
406
|
+
periodSec: number;
|
|
407
|
+
/** 0 fixed_seconds / 1 calendar_month. */
|
|
408
|
+
periodMode: number;
|
|
409
|
+
maxPeriods: number;
|
|
410
|
+
startAt: number;
|
|
411
|
+
/** Calendar-month billing anchor (Unix s); 0/undefined in fixed_seconds mode. */
|
|
412
|
+
billingAnchorAt?: number;
|
|
413
|
+
/** Seller-side business identifier (NOT on-chain); facilitator echoes from its DB. */
|
|
414
|
+
planId?: string;
|
|
415
|
+
/** Plan tier from on-chain terms.planTier. */
|
|
416
|
+
planTier?: number;
|
|
417
|
+
lastChargedPeriod: number;
|
|
418
|
+
totalPulled: string;
|
|
419
|
+
changedToSubId?: string | null;
|
|
420
|
+
isActive?: boolean;
|
|
421
|
+
serviceEnded?: boolean;
|
|
422
|
+
/** Mode-aware current period, clamped to maxPeriods (boundary = next period). */
|
|
423
|
+
currentPeriod?: number;
|
|
424
|
+
/**
|
|
425
|
+
* Real elapsed period number, NOT clamped — `elapsedPeriods > maxPeriods`
|
|
426
|
+
* means the service window already ended. SDK polls until
|
|
427
|
+
* `lastChargedPeriod >= elapsedPeriods` to confirm a write settled.
|
|
428
|
+
*/
|
|
429
|
+
elapsedPeriods?: number;
|
|
430
|
+
nextChargeableAt?: number;
|
|
431
|
+
pendingPlanChange?: {
|
|
432
|
+
subId: string;
|
|
433
|
+
newSubId: string;
|
|
434
|
+
effectiveFromPeriod: number;
|
|
435
|
+
state: number;
|
|
436
|
+
} | null;
|
|
437
|
+
}
|
|
438
|
+
/** Subscription-aware facilitator client. Extends the base FacilitatorClient. */
|
|
439
|
+
interface SubscriptionFacilitatorClient extends FacilitatorClient {
|
|
440
|
+
/** POST /api/v6/pay/x402/subscriptions */
|
|
441
|
+
subscribe(payload: PaymentPayload, requirements: PaymentRequirements, syncSettle?: boolean): Promise<FacilitatorEnvelope<FacilitatorSubscribeData>>;
|
|
442
|
+
/** POST /api/v6/pay/x402/subscriptions/change */
|
|
443
|
+
changeSubscription(payload: PaymentPayload, requirements: PaymentRequirements, oldSubId: string, syncSettle?: boolean): Promise<FacilitatorEnvelope<FacilitatorChangeData>>;
|
|
444
|
+
/** POST /api/v6/pay/x402/subscriptions/{subId}/cancel */
|
|
445
|
+
cancelSubscription(subId: string, cancelAuth: CancelAuth, syncSettle?: boolean): Promise<FacilitatorEnvelope<FacilitatorCancelData>>;
|
|
446
|
+
/** POST /api/v6/pay/x402/subscriptions/{subId}/cancel-pending-change */
|
|
447
|
+
cancelPendingChange(subId: string, cancelAuth: PendingChangeCancelAuth, syncSettle?: boolean): Promise<FacilitatorEnvelope<FacilitatorCancelPendingData>>;
|
|
448
|
+
/** POST /api/v6/pay/x402/subscriptions/{subId}/charge */
|
|
449
|
+
chargeSubscription(subId: string, syncSettle?: boolean): Promise<FacilitatorEnvelope<FacilitatorChargeData>>;
|
|
450
|
+
/** POST /api/v6/pay/x402/subscriptions/finalize-expired — cleans up an ACTIVE sub whose service window has ended. */
|
|
451
|
+
finalizeExpired(subId: string, syncSettle?: boolean): Promise<FacilitatorEnvelope<FacilitatorFinalizeExpiredData>>;
|
|
452
|
+
/** GET /api/v6/pay/x402/subscriptions/charges — paginated charge feed. */
|
|
453
|
+
getCharges(subId: string, limit?: number, offset?: number): Promise<FacilitatorEnvelope<FacilitatorGetChargesData>>;
|
|
454
|
+
/** GET /api/v6/pay/x402/subscriptions/pending — most recent pendingPlanChange row (any state). */
|
|
455
|
+
getPendingChange(subId: string): Promise<FacilitatorEnvelope<FacilitatorPendingChangeRow | null>>;
|
|
456
|
+
/** GET /api/v6/pay/x402/subscriptions/{subId} */
|
|
457
|
+
getSubscription(subId: string): Promise<FacilitatorEnvelope<FacilitatorGetSubscriptionData>>;
|
|
458
|
+
}
|
|
459
|
+
/**
|
|
460
|
+
* Type guard: does this FacilitatorClient implement the subscription
|
|
461
|
+
* endpoints?
|
|
462
|
+
*/
|
|
463
|
+
declare function supportsSubscription(client: FacilitatorClient): client is SubscriptionFacilitatorClient;
|
|
464
|
+
|
|
1
465
|
interface FacilitatorConfig {
|
|
2
466
|
url?: string;
|
|
3
467
|
createAuthHeaders?: () => Promise<{
|
|
@@ -5,6 +469,18 @@ interface FacilitatorConfig {
|
|
|
5
469
|
settle: Record<string, string>;
|
|
6
470
|
supported: Record<string, string>;
|
|
7
471
|
}>;
|
|
472
|
+
/**
|
|
473
|
+
* Optional per-operation auth header generator for subscription endpoints.
|
|
474
|
+
* Called with `subscribe` | `change` | `cancel` | `charge` | `getSubscription`.
|
|
475
|
+
* If omitted, subscription requests go out without auth headers (suitable
|
|
476
|
+
* for self-hosted facilitators or tests; for OKX use `OKXFacilitatorClient`).
|
|
477
|
+
*/
|
|
478
|
+
createSubscriptionAuthHeaders?: (op: string) => Promise<Record<string, string>>;
|
|
479
|
+
/**
|
|
480
|
+
* Inject a fetch implementation (test mock / custom transport). Defaults
|
|
481
|
+
* to the global `fetch`.
|
|
482
|
+
*/
|
|
483
|
+
fetchFn?: typeof fetch;
|
|
8
484
|
}
|
|
9
485
|
/**
|
|
10
486
|
* Interface for facilitator clients
|
|
@@ -49,6 +525,8 @@ interface FacilitatorClient {
|
|
|
49
525
|
declare class HTTPFacilitatorClient implements FacilitatorClient {
|
|
50
526
|
readonly url: string;
|
|
51
527
|
private readonly _createAuthHeaders?;
|
|
528
|
+
private readonly _createSubscriptionAuthHeaders?;
|
|
529
|
+
private readonly _fetchFn;
|
|
52
530
|
/**
|
|
53
531
|
* Creates a new HTTPFacilitatorClient instance.
|
|
54
532
|
*
|
|
@@ -102,6 +580,23 @@ declare class HTTPFacilitatorClient implements FacilitatorClient {
|
|
|
102
580
|
* @returns The JSON-safe representation of the object
|
|
103
581
|
*/
|
|
104
582
|
private toJsonSafe;
|
|
583
|
+
private subscriptionAuthHeaders;
|
|
584
|
+
private subscriptionPost;
|
|
585
|
+
private subscriptionGet;
|
|
586
|
+
/**
|
|
587
|
+
* Build the {chainIndex, terms, permit, termsSig, permitSig, syncSettle}
|
|
588
|
+
* request body shared by subscribe / change endpoints.
|
|
589
|
+
*/
|
|
590
|
+
private buildWriteBody;
|
|
591
|
+
subscribe(paymentPayload: PaymentPayload, paymentRequirements: PaymentRequirements, syncSettle?: boolean): Promise<FacilitatorEnvelope<FacilitatorSubscribeData>>;
|
|
592
|
+
changeSubscription(paymentPayload: PaymentPayload, paymentRequirements: PaymentRequirements, oldSubId: string, syncSettle?: boolean): Promise<FacilitatorEnvelope<FacilitatorChangeData>>;
|
|
593
|
+
cancelSubscription(subId: string, cancelAuth: CancelAuth, syncSettle?: boolean): Promise<FacilitatorEnvelope<FacilitatorCancelData>>;
|
|
594
|
+
cancelPendingChange(subId: string, cancelAuth: PendingChangeCancelAuth, syncSettle?: boolean): Promise<FacilitatorEnvelope<FacilitatorCancelPendingData>>;
|
|
595
|
+
chargeSubscription(subId: string, syncSettle?: boolean): Promise<FacilitatorEnvelope<FacilitatorChargeData>>;
|
|
596
|
+
finalizeExpired(subId: string, syncSettle?: boolean): Promise<FacilitatorEnvelope<FacilitatorFinalizeExpiredData>>;
|
|
597
|
+
getCharges(subId: string, limit?: number, offset?: number): Promise<FacilitatorEnvelope<FacilitatorGetChargesData>>;
|
|
598
|
+
getPendingChange(subId: string): Promise<FacilitatorEnvelope<FacilitatorPendingChangeRow | null>>;
|
|
599
|
+
getSubscription(subId: string): Promise<FacilitatorEnvelope<FacilitatorGetSubscriptionData>>;
|
|
105
600
|
}
|
|
106
601
|
|
|
107
602
|
/** Default poll interval for settle/status queries (1 second). */
|
|
@@ -243,6 +738,19 @@ declare class x402ResourceServer {
|
|
|
243
738
|
* @returns True if the scheme is registered for the network, false otherwise
|
|
244
739
|
*/
|
|
245
740
|
hasRegisteredScheme(network: Network, scheme: string): boolean;
|
|
741
|
+
/**
|
|
742
|
+
* Look up the registered SchemeNetworkServer for a given network + scheme.
|
|
743
|
+
* Exposed so the HTTP dispatch layer can perform capability detection
|
|
744
|
+
* (e.g. `hasSubscriptionCapability(scheme)`) on the actual instance.
|
|
745
|
+
*
|
|
746
|
+
* Pattern matching follows the same CAIP-style rules as `verifyPayment`:
|
|
747
|
+
* registered keys may use wildcards like `eip155:*`.
|
|
748
|
+
*
|
|
749
|
+
* @param network - The network identifier
|
|
750
|
+
* @param scheme - The payment scheme name
|
|
751
|
+
* @returns The registered scheme server, or undefined if none matches.
|
|
752
|
+
*/
|
|
753
|
+
findScheme(network: Network, scheme: string): SchemeNetworkServer | undefined;
|
|
246
754
|
/**
|
|
247
755
|
* Registers a resource service extension that can enrich extension declarations.
|
|
248
756
|
*
|
|
@@ -760,4 +1268,4 @@ interface SchemeNetworkServer {
|
|
|
760
1268
|
}, facilitatorExtensions: string[]): Promise<PaymentRequirements>;
|
|
761
1269
|
}
|
|
762
1270
|
|
|
763
|
-
export { type
|
|
1271
|
+
export { type VerifyAccessResult as $, type AccessProof as A, type FacilitatorChargeRow as B, type CancelAuth as C, type OnBeforeAccessHook as D, type OnBeforeAccessResult as E, type FacilitatorExtension as F, type PendingPlanChange as G, HTTPFacilitatorClient as H, type PlanCatalog as I, type PlanCatalogEntry as J, type SettleCancelOk as K, type SettleCancelPendingChangeOk as L, type SettleCancelPendingChangeResult as M, type Network as N, type OnBeforeAccessContext as O, type PaymentPayload as P, type SettleCancelResult as Q, type SettleChangeOk as R, type SettleResponse as S, type SettleChangeResult as T, type SettleResultFail as U, type VerifyResponse as V, type SettleSubscribeOk as W, type SettleSubscribeResult as X, type SubscriptionFacilitatorClient as Y, type SubscriptionState as Z, type VerifyAccessOk as _, type PaymentRequirements as a, type VerifyChangeOk as a0, type VerifyChangeResult as a1, type VerifyOwnershipOk as a2, type VerifyOwnershipResult as a3, type VerifyResult as a4, type VerifyResultFail as a5, type VerifyResultOk as a6, hasSubscriptionCapability as a7, supportsSubscription as a8, type SchemeNetworkClient as a9, DEFAULT_POLL_DEADLINE_MS as aa, DEFAULT_POLL_INTERVAL_MS as ab, type PollResult as ac, type ResourceConfig as ad, type SettleResultContext as ae, type SettlementOverrides as af, x402ResourceServer as ag, type Price as ah, type AssetAmount as ai, type FacilitatorContext as aj, type Money as ak, type MoneyParser as al, type PaymentPayloadContext as am, type PaymentPayloadResult as an, type PaymentRequiredContext as ao, type ResourceInfo as ap, type ResourceServerExtension as aq, type SchemeNetworkServer as ar, SettleError as as, type SettleRequest as at, VerifyError as au, type VerifyRequest as av, type SchemeNetworkFacilitator as b, type PaymentRequired as c, type FacilitatorClient as d, type FacilitatorConfig as e, FacilitatorResponseError as f, getFacilitatorResponseError as g, type SupportedResponse as h, type SettleStatusResponse as i, type FacilitatorEnvelope as j, type FacilitatorSubscribeData as k, type FacilitatorChangeData as l, type FacilitatorCancelData as m, type PendingChangeCancelAuth as n, type FacilitatorCancelPendingData as o, type FacilitatorChargeData as p, type FacilitatorFinalizeExpiredData as q, type FacilitatorGetChargesData as r, type FacilitatorPendingChangeRow as s, type FacilitatorGetSubscriptionData as t, type Subscription as u, type SubscriptionCapability as v, type ChargeResult as w, type CancelInitiator as x, type PlanInitialCharge as y, type AccessRouteRequirements as z };
|
|
@@ -1,2 +1,4 @@
|
|
|
1
|
-
export {
|
|
2
|
-
export { C as CompiledRoute, H as HTTPAdapter, b as HTTPProcessResult, c as HTTPRequestContext, d as HTTPResponseBody, e as HTTPResponseInstructions, f as HTTPTransportContext, g as PaywallConfig, h as PaywallProvider, i as ProcessSettleFailureResponse, j as ProcessSettleResultResponse, k as ProcessSettleSuccessResponse, R as RouteConfig, m as RouteConfigurationError, n as RouteValidationError, o as RoutesConfig, p as SETTLEMENT_OVERRIDES_HEADER, S as SettlementFailedResponseBody, U as UnpaidResponseBody, x as x402HTTPResourceServer } from '../x402HTTPResourceServer-
|
|
1
|
+
export { aa as DEFAULT_POLL_DEADLINE_MS, ab as DEFAULT_POLL_INTERVAL_MS, d as FacilitatorClient, e as FacilitatorConfig, f as FacilitatorResponseError, H as HTTPFacilitatorClient, ac as PollResult, ad as ResourceConfig, ae as SettleResultContext, af as SettlementOverrides, g as getFacilitatorResponseError, ag as x402ResourceServer } from '../mechanisms-LhI9qkRo.js';
|
|
2
|
+
export { C as CompiledRoute, H as HTTPAdapter, b as HTTPProcessResult, c as HTTPRequestContext, d as HTTPResponseBody, e as HTTPResponseInstructions, f as HTTPTransportContext, g as PaywallConfig, h as PaywallProvider, i as ProcessSettleFailureResponse, j as ProcessSettleResultResponse, k as ProcessSettleSuccessResponse, R as RouteConfig, m as RouteConfigurationError, n as RouteValidationError, o as RoutesConfig, p as SETTLEMENT_OVERRIDES_HEADER, S as SettlementFailedResponseBody, U as UnpaidResponseBody, x as x402HTTPResourceServer } from '../x402HTTPResourceServer-B0mXzV8r.js';
|
|
3
|
+
import '../index-2gWfiUbK.js';
|
|
4
|
+
import 'viem';
|