@waffo/pancake-ts 0.3.0 → 0.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (12) hide show
  1. package/CHANGELOG.md +16 -4
  2. package/README.md +66 -69
  3. package/dist/index.cjs +58 -72
  4. package/dist/index.cjs.map +1 -1
  5. package/dist/index.d.cts +23 -9
  6. package/dist/index.d.ts +23 -9
  7. package/dist/index.js +58 -72
  8. package/dist/index.js.map +1 -1
  9. package/docs/api-reference.md +311 -283
  10. package/docs/graphql-guide.md +12 -12
  11. package/docs/webhook-guide.md +79 -82
  12. package/package.json +15 -2
package/docs/api-reference.md CHANGED
@@ -3,9 +3,10 @@
3
3
  Complete reference for all `@waffo/pancake-ts` resources, parameters, and return types.
4
4
 
5
5
  > **Conventions**:
6
+ >
6
7
  > - All amounts are in the **smallest currency unit** (e.g. 999 = $9.99 USD, 4500 = ¥4500 JPY)
7
8
  > - All timestamps are **ISO 8601 UTC** strings
8
- > - Product updates follow **immutable versioning** — each update creates a new version, skipped if content is unchanged
9
+ > - Product updates follow **immutable versioning** — only provided fields are updated (omitted fields are preserved), each update creates a new version, skipped if content is unchanged
9
10
  > - The **publish** flow promotes a test version to production
10
11
 
11
12
  ---
@@ -32,17 +33,17 @@ const { token, expiresAt } = await client.auth.issueSessionToken({
32
33
 
33
34
  **Parameters `IssueSessionTokenParams`**:
34
35
 
35
- | Field | Type | Required | Description |
36
- |-------|------|----------|-------------|
37
- | `storeId` | `string` | No | Store ID (at least one of `storeId` / `productId` required) |
38
- | `productId` | `string` | No | Product ID (at least one of `storeId` / `productId` required; server derives store from product) |
39
- | `buyerIdentity` | `string` | Yes | Buyer identity (email or merchant-defined identifier) |
36
+ | Field | Type | Required | Description |
37
+ | --------------- | -------- | -------- | ------------------------------------------------------------------------------------------------ |
38
+ | `storeId` | `string` | No | Store ID (at least one of `storeId` / `productId` required) |
39
+ | `productId` | `string` | No | Product ID (at least one of `storeId` / `productId` required; server derives store from product) |
40
+ | `buyerIdentity` | `string` | Yes | Buyer identity (email or merchant-defined identifier) |
40
41
 
41
42
  **Returns `SessionToken`**:
42
43
 
43
- | Field | Type | Description |
44
- |-------|------|-------------|
45
- | `token` | `string` | JWT token string |
44
+ | Field | Type | Description |
45
+ | ----------- | -------- | --------------------- |
46
+ | `token` | `string` | JWT token string |
46
47
  | `expiresAt` | `string` | Token expiration time |
47
48
 
48
49
  ---
@@ -59,9 +60,9 @@ const { store } = await client.stores.create({ name: "My Store" });
59
60
 
60
61
  **Parameters `CreateStoreParams`**:
61
62
 
62
- | Field | Type | Required | Description |
63
- |-------|------|----------|-------------|
64
- | `name` | `string` | Yes | Store name (1–48 characters, trimmed automatically) |
63
+ | Field | Type | Required | Description |
64
+ | ------ | -------- | -------- | --------------------------------------------------- |
65
+ | `name` | `string` | Yes | Store name (1–48 characters, trimmed automatically) |
65
66
 
66
67
  **Returns `{ store: Store }`**
67
68
 
@@ -113,17 +114,17 @@ const { store } = await client.stores.update({
113
114
 
114
115
  **Parameters `UpdateStoreParams`**:
115
116
 
116
- | Field | Type | Required | Description |
117
- |-------|------|----------|-------------|
118
- | `id` | `string` | Yes | Store ID |
119
- | `name` | `string` | No | Store name (1–100 characters) |
120
- | `status` | `EntityStatus` | No | Store status |
121
- | `logo` | `string \| null` | No | Logo (Base64 encoded image) |
122
- | `supportEmail` | `string \| null` | No | Support email address |
123
- | `website` | `string \| null` | No | Store website URL |
124
- | `webhookSettings` | `WebhookSettings \| null` | No | Webhook endpoint configuration (test/prod URLs and subscribed event types) |
125
- | `notificationSettings` | `NotificationSettings \| null` | No | Email notification preferences |
126
- | `checkoutSettings` | `CheckoutSettings \| null` | No | Checkout page theme (light/dark) |
117
+ | Field | Type | Required | Description |
118
+ | ---------------------- | ------------------------------ | -------- | -------------------------------------------------------------------------- |
119
+ | `id` | `string` | Yes | Store ID |
120
+ | `name` | `string` | No | Store name (1–100 characters) |
121
+ | `status` | `EntityStatus` | No | Store status |
122
+ | `logo` | `string \| null` | No | Logo (Base64 encoded image) |
123
+ | `supportEmail` | `string \| null` | No | Support email address |
124
+ | `website` | `string \| null` | No | Store website URL |
125
+ | `webhookSettings` | `WebhookSettings \| null` | No | Webhook endpoint configuration (test/prod URLs and subscribed event types) |
126
+ | `notificationSettings` | `NotificationSettings \| null` | No | Email notification preferences |
127
+ | `checkoutSettings` | `CheckoutSettings \| null` | No | Checkout page theme (light/dark) |
127
128
 
128
129
  **Returns `{ store: Store }`**
129
130
 
@@ -137,9 +138,9 @@ const { store } = await client.stores.delete({ id: "STO_xxx" });
137
138
 
138
139
  **Parameters `DeleteStoreParams`**:
139
140
 
140
- | Field | Type | Required | Description |
141
- |-------|------|----------|-------------|
142
- | `id` | `string` | Yes | Store ID |
141
+ | Field | Type | Required | Description |
142
+ | ----- | -------- | -------- | ----------- |
143
+ | `id` | `string` | Yes | Store ID |
143
144
 
144
145
  **Returns `{ store: Store }`**
145
146
 
@@ -163,22 +164,22 @@ const result = await client.storeMerchants.add({
163
164
 
164
165
  **Parameters `AddMerchantParams`**:
165
166
 
166
- | Field | Type | Required | Description |
167
- |-------|------|----------|-------------|
168
- | `storeId` | `string` | Yes | Store ID |
169
- | `email` | `string` | Yes | Merchant email |
170
- | `role` | `"admin" \| "member"` | Yes | Role to assign |
167
+ | Field | Type | Required | Description |
168
+ | --------- | --------------------- | -------- | -------------- |
169
+ | `storeId` | `string` | Yes | Store ID |
170
+ | `email` | `string` | Yes | Merchant email |
171
+ | `role` | `"admin" \| "member"` | Yes | Role to assign |
171
172
 
172
173
  **Returns `AddMerchantResult`**:
173
174
 
174
- | Field | Type | Description |
175
- |-------|------|-------------|
176
- | `storeId` | `string` | Store ID |
177
- | `merchantId` | `string` | Merchant ID |
178
- | `email` | `string` | Merchant email |
179
- | `role` | `string` | Assigned role |
180
- | `status` | `string` | Membership status |
181
- | `addedAt` | `string` | Timestamp when added |
175
+ | Field | Type | Description |
176
+ | ------------ | -------- | -------------------- |
177
+ | `storeId` | `string` | Store ID |
178
+ | `merchantId` | `string` | Merchant ID |
179
+ | `email` | `string` | Merchant email |
180
+ | `role` | `string` | Assigned role |
181
+ | `status` | `string` | Membership status |
182
+ | `addedAt` | `string` | Timestamp when added |
182
183
 
183
184
  ### `client.storeMerchants.remove(params)`
184
185
 
@@ -193,16 +194,16 @@ const result = await client.storeMerchants.remove({
193
194
 
194
195
  **Parameters `RemoveMerchantParams`**:
195
196
 
196
- | Field | Type | Required | Description |
197
- |-------|------|----------|-------------|
198
- | `storeId` | `string` | Yes | Store ID |
199
- | `merchantId` | `string` | Yes | Merchant ID |
197
+ | Field | Type | Required | Description |
198
+ | ------------ | -------- | -------- | ----------- |
199
+ | `storeId` | `string` | Yes | Store ID |
200
+ | `merchantId` | `string` | Yes | Merchant ID |
200
201
 
201
202
  **Returns `RemoveMerchantResult`**:
202
203
 
203
- | Field | Type | Description |
204
- |-------|------|-------------|
205
- | `message` | `string` | Operation message |
204
+ | Field | Type | Description |
205
+ | ----------- | -------- | ---------------------- |
206
+ | `message` | `string` | Operation message |
206
207
  | `removedAt` | `string` | Timestamp when removed |
207
208
 
208
209
  ### `client.storeMerchants.updateRole(params)`
@@ -219,20 +220,20 @@ const result = await client.storeMerchants.updateRole({
219
220
 
220
221
  **Parameters `UpdateRoleParams`**:
221
222
 
222
- | Field | Type | Required | Description |
223
- |-------|------|----------|-------------|
224
- | `storeId` | `string` | Yes | Store ID |
225
- | `merchantId` | `string` | Yes | Merchant ID |
226
- | `role` | `"admin" \| "member"` | Yes | New role |
223
+ | Field | Type | Required | Description |
224
+ | ------------ | --------------------- | -------- | ----------- |
225
+ | `storeId` | `string` | Yes | Store ID |
226
+ | `merchantId` | `string` | Yes | Merchant ID |
227
+ | `role` | `"admin" \| "member"` | Yes | New role |
227
228
 
228
229
  **Returns `UpdateRoleResult`**:
229
230
 
230
- | Field | Type | Description |
231
- |-------|------|-------------|
232
- | `storeId` | `string` | Store ID |
233
- | `merchantId` | `string` | Merchant ID |
234
- | `role` | `string` | Updated role |
235
- | `updatedAt` | `string` | Timestamp when updated |
231
+ | Field | Type | Description |
232
+ | ------------ | -------- | ---------------------- |
233
+ | `storeId` | `string` | Store ID |
234
+ | `merchantId` | `string` | Merchant ID |
235
+ | `role` | `string` | Updated role |
236
+ | `updatedAt` | `string` | Timestamp when updated |
236
237
 
237
238
  ---
238
239
 
@@ -262,15 +263,15 @@ const { product } = await client.onetimeProducts.create({
262
263
 
263
264
  **Parameters `CreateOnetimeProductParams`**:
264
265
 
265
- | Field | Type | Required | Description |
266
- |-------|------|----------|-------------|
267
- | `storeId` | `string` | Yes | Store ID |
268
- | `name` | `string` | Yes | Product name |
269
- | `prices` | `Prices` | Yes | Multi-currency prices (`Record<string, PriceInfo>`) |
270
- | `description` | `string` | No | Product description |
271
- | `media` | `MediaItem[]` | No | Media assets (images, videos) |
272
- | `successUrl` | `string` | No | Redirect URL after successful payment |
273
- | `metadata` | `Record<string, unknown>` | No | Custom metadata |
266
+ | Field | Type | Required | Description |
267
+ | ------------- | ------------------------- | -------- | --------------------------------------------------- |
268
+ | `storeId` | `string` | Yes | Store ID |
269
+ | `name` | `string` | Yes | Product name |
270
+ | `prices` | `Prices` | Yes | Multi-currency prices (`Record<string, PriceInfo>`) |
271
+ | `description` | `string` | No | Product description |
272
+ | `media` | `MediaItem[]` | No | Media assets (images, videos) |
273
+ | `successUrl` | `string` | No | Redirect URL after successful payment |
274
+ | `metadata` | `Record<string, unknown>` | No | Custom metadata |
274
275
 
275
276
  **Returns `{ product: OnetimeProductDetail }`**
276
277
 
@@ -278,25 +279,33 @@ const { product } = await client.onetimeProducts.create({
278
279
 
279
280
  Update a one-time product. Creates a new immutable version; skips if content is unchanged.
280
281
 
282
+ > Only `id` is required. Omitted fields keep their current values.
283
+
281
284
  ```typescript
285
+ // Update only the name
282
286
  const { product } = await client.onetimeProducts.update({
283
287
  id: "PROD_xxx",
284
288
  name: "E-Book: TypeScript Handbook v2",
289
+ });
290
+
291
+ // Update only the prices
292
+ const { product: p2 } = await client.onetimeProducts.update({
293
+ id: "PROD_xxx",
285
294
  prices: { USD: { amount: "39.00", taxCategory: "digital_goods" } },
286
295
  });
287
296
  ```
288
297
 
289
298
  **Parameters `UpdateOnetimeProductParams`**:
290
299
 
291
- | Field | Type | Required | Description |
292
- |-------|------|----------|-------------|
293
- | `id` | `string` | Yes | Product ID |
294
- | `name` | `string` | Yes | Product name |
295
- | `prices` | `Prices` | Yes | Multi-currency prices |
296
- | `description` | `string` | No | Product description |
297
- | `media` | `MediaItem[]` | No | Media assets |
298
- | `successUrl` | `string` | No | Redirect URL after successful payment |
299
- | `metadata` | `Record<string, unknown>` | No | Custom metadata |
300
+ | Field | Type | Required | Description |
301
+ | ------------- | ------------------------- | -------- | ------------------------------------- |
302
+ | `id` | `string` | Yes | Product ID |
303
+ | `name` | `string` | No | Product name |
304
+ | `prices` | `Prices` | No | Multi-currency prices |
305
+ | `description` | `string` | No | Product description |
306
+ | `media` | `MediaItem[]` | No | Media assets |
307
+ | `successUrl` | `string` | No | Redirect URL after successful payment |
308
+ | `metadata` | `Record<string, unknown>` | No | Custom metadata |
300
309
 
301
310
  **Returns `{ product: OnetimeProductDetail }`**
302
311
 
@@ -310,9 +319,9 @@ const { product } = await client.onetimeProducts.publish({ id: "PROD_xxx" });
310
319
 
311
320
  **Parameters `PublishOnetimeProductParams`**:
312
321
 
313
- | Field | Type | Required | Description |
314
- |-------|------|----------|-------------|
315
- | `id` | `string` | Yes | Product ID |
322
+ | Field | Type | Required | Description |
323
+ | ----- | -------- | -------- | ----------- |
324
+ | `id` | `string` | Yes | Product ID |
316
325
 
317
326
  **Returns `{ product: OnetimeProductDetail }`**
318
327
 
@@ -331,10 +340,10 @@ const { product } = await client.onetimeProducts.updateStatus({
331
340
 
332
341
  **Parameters `UpdateOnetimeStatusParams`**:
333
342
 
334
- | Field | Type | Required | Description |
335
- |-------|------|----------|-------------|
336
- | `id` | `string` | Yes | Product ID |
337
- | `status` | `ProductVersionStatus` | Yes | `Active` or `Inactive` |
343
+ | Field | Type | Required | Description |
344
+ | -------- | ---------------------- | -------- | ---------------------- |
345
+ | `id` | `string` | Yes | Product ID |
346
+ | `status` | `ProductVersionStatus` | Yes | `Active` or `Inactive` |
338
347
 
339
348
  **Returns `{ product: OnetimeProductDetail }`**
340
349
 
@@ -360,16 +369,16 @@ const { product } = await client.subscriptionProducts.create({
360
369
 
361
370
  **Parameters `CreateSubscriptionProductParams`**:
362
371
 
363
- | Field | Type | Required | Description |
364
- |-------|------|----------|-------------|
365
- | `storeId` | `string` | Yes | Store ID |
366
- | `name` | `string` | Yes | Product name |
367
- | `billingPeriod` | `BillingPeriod` | Yes | Billing period (`Weekly` / `Monthly` / `Quarterly` / `Yearly`) |
368
- | `prices` | `Prices` | Yes | Multi-currency prices |
369
- | `description` | `string` | No | Product description |
370
- | `media` | `MediaItem[]` | No | Media assets |
371
- | `successUrl` | `string` | No | Redirect URL after successful payment |
372
- | `metadata` | `Record<string, unknown>` | No | Custom metadata |
372
+ | Field | Type | Required | Description |
373
+ | --------------- | ------------------------- | -------- | -------------------------------------------------------------- |
374
+ | `storeId` | `string` | Yes | Store ID |
375
+ | `name` | `string` | Yes | Product name |
376
+ | `billingPeriod` | `BillingPeriod` | Yes | Billing period (`Weekly` / `Monthly` / `Quarterly` / `Yearly`) |
377
+ | `prices` | `Prices` | Yes | Multi-currency prices |
378
+ | `description` | `string` | No | Product description |
379
+ | `media` | `MediaItem[]` | No | Media assets |
380
+ | `successUrl` | `string` | No | Redirect URL after successful payment |
381
+ | `metadata` | `Record<string, unknown>` | No | Custom metadata |
373
382
 
374
383
  **Returns `{ product: SubscriptionProductDetail }`**
375
384
 
@@ -377,16 +386,35 @@ const { product } = await client.subscriptionProducts.create({
377
386
 
378
387
  Update a subscription product. Creates a new immutable version; skips if unchanged.
379
388
 
389
+ > Only `id` is required. Omitted fields keep their current values.
390
+
380
391
  ```typescript
392
+ // Update only the name
381
393
  const { product } = await client.subscriptionProducts.update({
382
394
  id: "PROD_xxx",
383
395
  name: "Pro Plan v2",
384
- billingPeriod: BillingPeriod.Monthly,
385
- prices: { USD: { amount: "14.99", taxCategory: "saas" } },
396
+ });
397
+
398
+ // Update billing period and prices
399
+ const { product: p2 } = await client.subscriptionProducts.update({
400
+ id: "PROD_xxx",
401
+ billingPeriod: BillingPeriod.Yearly,
402
+ prices: { USD: { amount: "99.00", taxCategory: "saas" } },
386
403
  });
387
404
  ```
388
405
 
389
- **Parameters `UpdateSubscriptionProductParams`**: Same as create, but `id` replaces `storeId`.
406
+ **Parameters `UpdateSubscriptionProductParams`**:
407
+
408
+ | Field | Type | Required | Description |
409
+ | --------------- | ------------------------- | -------- | ------------------------------------- |
410
+ | `id` | `string` | Yes | Product ID |
411
+ | `name` | `string` | No | Product name |
412
+ | `billingPeriod` | `BillingPeriod` | No | Billing period |
413
+ | `prices` | `Prices` | No | Multi-currency prices |
414
+ | `description` | `string` | No | Product description |
415
+ | `media` | `MediaItem[]` | No | Media assets |
416
+ | `successUrl` | `string` | No | Redirect URL after successful payment |
417
+ | `metadata` | `Record<string, unknown>` | No | Custom metadata |
390
418
 
391
419
  **Returns `{ product: SubscriptionProductDetail }`**
392
420
 
@@ -435,13 +463,13 @@ const { group } = await client.subscriptionProductGroups.create({
435
463
 
436
464
  **Parameters `CreateSubscriptionProductGroupParams`**:
437
465
 
438
- | Field | Type | Required | Description |
439
- |-------|------|----------|-------------|
440
- | `storeId` | `string` | Yes | Store ID |
441
- | `name` | `string` | Yes | Group name |
442
- | `description` | `string` | No | Group description |
443
- | `rules` | `GroupRules` | No | Group rules (e.g. `{ sharedTrial: true }`) |
444
- | `productIds` | `string[]` | No | Subscription product IDs to include |
466
+ | Field | Type | Required | Description |
467
+ | ------------- | ------------ | -------- | ------------------------------------------ |
468
+ | `storeId` | `string` | Yes | Store ID |
469
+ | `name` | `string` | Yes | Group name |
470
+ | `description` | `string` | No | Group description |
471
+ | `rules` | `GroupRules` | No | Group rules (e.g. `{ sharedTrial: true }`) |
472
+ | `productIds` | `string[]` | No | Subscription product IDs to include |
445
473
 
446
474
  **Returns `{ group: SubscriptionProductGroup }`**
447
475
 
@@ -486,9 +514,9 @@ const { group } = await client.subscriptionProductGroups.publish({ id: "spg_xxx"
486
514
 
487
515
  Cancel a subscription order. The resulting status depends on the current order state:
488
516
 
489
- | Current Status | Result | Behavior |
490
- |---------------|--------|----------|
491
- | `pending` | `canceled` | Immediate cancellation |
517
+ | Current Status | Result | Behavior |
518
+ | --------------------- | ----------- | -------------------------------------------------------- |
519
+ | `pending` | `canceled` | Immediate cancellation |
492
520
  | `active` / `trialing` | `canceling` | PSP cancellation initiated; webhook updates status later |
493
521
 
494
522
  ```typescript
@@ -500,16 +528,16 @@ const { orderId, status } = await client.orders.cancelSubscription({
500
528
 
501
529
  **Parameters `CancelSubscriptionParams`**:
502
530
 
503
- | Field | Type | Required | Description |
504
- |-------|------|----------|-------------|
505
- | `orderId` | `string` | Yes | Order ID |
531
+ | Field | Type | Required | Description |
532
+ | --------- | -------- | -------- | ----------- |
533
+ | `orderId` | `string` | Yes | Order ID |
506
534
 
507
535
  **Returns `CancelSubscriptionResult`**:
508
536
 
509
- | Field | Type | Description |
510
- |-------|------|-------------|
511
- | `orderId` | `string` | Order ID |
512
- | `status` | `string` | Resulting status (`"canceled"` or `"canceling"`) |
537
+ | Field | Type | Description |
538
+ | --------- | -------- | ------------------------------------------------ |
539
+ | `orderId` | `string` | Order ID |
540
+ | `status` | `string` | Resulting status (`"canceled"` or `"canceling"`) |
513
541
 
514
542
  ---
515
543
 
@@ -531,54 +559,54 @@ const buyer = client.buyer(token);
531
559
 
532
560
  ### `buyer.cancelSubscription(params)`
533
561
 
534
- | Field | Type | Required | Description |
535
- |-------|------|----------|-------------|
536
- | `orderId` | `string` | Yes | Subscription order ID |
562
+ | Field | Type | Required | Description |
563
+ | --------- | -------- | -------- | --------------------- |
564
+ | `orderId` | `string` | Yes | Subscription order ID |
537
565
 
538
566
  **Returns `CancelSubscriptionResult`**: `{ orderId, status }` — status is `"canceling"` (active) or `"canceled"` (pending)
539
567
 
540
568
  ### `buyer.cancelOnetimeOrder(params)`
541
569
 
542
- | Field | Type | Required | Description |
543
- |-------|------|----------|-------------|
544
- | `orderId` | `string` | Yes | One-time order ID |
570
+ | Field | Type | Required | Description |
571
+ | --------- | -------- | -------- | ----------------- |
572
+ | `orderId` | `string` | Yes | One-time order ID |
545
573
 
546
574
  **Returns `CancelOnetimeOrderResult`**: `{ orderId, status }` — status is `"canceled"`
547
575
 
548
576
  ### `buyer.reactivateSubscription(params)`
549
577
 
550
- | Field | Type | Required | Description |
551
- |-------|------|----------|-------------|
552
- | `orderId` | `string` | Yes | Subscription order ID (must be in `canceling` status) |
578
+ | Field | Type | Required | Description |
579
+ | --------- | -------- | -------- | ----------------------------------------------------- |
580
+ | `orderId` | `string` | Yes | Subscription order ID (must be in `canceling` status) |
553
581
 
554
582
  **Returns `ReactivateSubscriptionResult`**: `{ orderId, status }` — status is `"active"`
555
583
 
556
584
  ### `buyer.createRefundTicket(params)`
557
585
 
558
- | Field | Type | Required | Description |
559
- |-------|------|----------|-------------|
560
- | `paymentId` | `string` | Yes | Payment ID to refund |
561
- | `reason` | `string` | Yes | Reason for the refund request |
562
- | `requestedAmount` | `RequestedAmount` | Yes | Refund amount (`{ amount, currency }`) |
563
- | `metadata` | `Record<string, unknown>` | No | Custom metadata |
586
+ | Field | Type | Required | Description |
587
+ | ----------------- | ------------------------- | -------- | -------------------------------------- |
588
+ | `paymentId` | `string` | Yes | Payment ID to refund |
589
+ | `reason` | `string` | Yes | Reason for the refund request |
590
+ | `requestedAmount` | `RequestedAmount` | Yes | Refund amount (`{ amount, currency }`) |
591
+ | `metadata` | `Record<string, unknown>` | No | Custom metadata |
564
592
 
565
593
  **`RequestedAmount`**:
566
594
 
567
- | Field | Type | Description |
568
- |-------|------|-------------|
569
- | `amount` | `string` | Amount in display format (e.g., `"29.00"`) |
570
- | `currency` | `string` | Currency code (ISO 4217) |
595
+ | Field | Type | Description |
596
+ | ---------- | -------- | ------------------------------------------ |
597
+ | `amount` | `string` | Amount in display format (e.g., `"29.00"`) |
598
+ | `currency` | `string` | Currency code (ISO 4217) |
571
599
 
572
600
  **Returns `{ ticket: RefundTicket }`**
573
601
 
574
602
  ### `buyer.resubmitRefundTicket(params)`
575
603
 
576
- | Field | Type | Required | Description |
577
- |-------|------|----------|-------------|
578
- | `ticketId` | `string` | Yes | Existing ticket ID |
579
- | `paymentId` | `string` | Yes | Payment ID |
580
- | `reason` | `string` | Yes | Updated reason |
581
- | `requestedAmount` | `RequestedAmount` | Yes | Updated refund amount |
604
+ | Field | Type | Required | Description |
605
+ | ----------------- | ----------------- | -------- | --------------------- |
606
+ | `ticketId` | `string` | Yes | Existing ticket ID |
607
+ | `paymentId` | `string` | Yes | Payment ID |
608
+ | `reason` | `string` | Yes | Updated reason |
609
+ | `requestedAmount` | `RequestedAmount` | Yes | Updated refund amount |
582
610
 
583
611
  **Returns `{ ticket: RefundTicket }`**
584
612
 
@@ -586,10 +614,10 @@ const buyer = client.buyer(token);
586
614
 
587
615
  Same parameters as `client.graphql.query<T>()` but scoped to the buyer's own data via session token.
588
616
 
589
- | Field | Type | Required | Description |
590
- |-------|------|----------|-------------|
591
- | `query` | `string` | Yes | GraphQL query string |
592
- | `variables` | `Record<string, unknown>` | No | Query variables |
617
+ | Field | Type | Required | Description |
618
+ | ----------- | ------------------------- | -------- | -------------------- |
619
+ | `query` | `string` | Yes | GraphQL query string |
620
+ | `variables` | `Record<string, unknown>` | No | Query variables |
593
621
 
594
622
  **Returns `GraphQLResponse<T>`**: `{ data, errors? }`
595
623
 
@@ -634,29 +662,29 @@ const subResult = await client.checkout.authenticated.create({
634
662
 
635
663
  **Parameters `AuthenticatedCheckoutParams`**:
636
664
 
637
- | Field | Type | Required | Description |
638
- |-------|------|----------|-------------|
639
- | `productId` | `string` | Yes | Product ID (product type is auto-detected server-side) |
640
- | `currency` | `string` | Yes | Currency code (ISO 4217) |
641
- | `buyerIdentity` | `string` | Yes | Buyer identity (email or merchant-defined identifier) |
642
- | `buyerEmail` | `string` | No | Pre-filled buyer email (defaults to `buyerIdentity`) |
643
- | `billingDetail` | `BillingDetail` | No | Pre-filled billing details (country, tax ID, etc.) |
644
- | `priceSnapshot` | `PriceInfo` | No | Price snapshot override (reads from DB if omitted) |
645
- | `withTrial` | `boolean` | No | Enable trial period (subscription only) |
646
- | `successUrl` | `string` | No | Redirect URL after successful payment |
647
- | `expiresInSeconds` | `number` | No | Session expiry in seconds (default: 45 minutes) |
648
- | `darkMode` | `boolean` | No | Dark mode override (true=dark, false=light, omit=store default) |
649
- | `metadata` | `Record<string, string>` | No | Custom metadata |
665
+ | Field | Type | Required | Description |
666
+ | ------------------ | ------------------------ | -------- | --------------------------------------------------------------- |
667
+ | `productId` | `string` | Yes | Product ID (product type is auto-detected server-side) |
668
+ | `currency` | `string` | Yes | Currency code (ISO 4217) |
669
+ | `buyerIdentity` | `string` | Yes | Buyer identity (email or merchant-defined identifier) |
670
+ | `buyerEmail` | `string` | No | Pre-filled buyer email (defaults to `buyerIdentity`) |
671
+ | `billingDetail` | `BillingDetail` | No | Pre-filled billing details (country, tax ID, etc.) |
672
+ | `priceSnapshot` | `PriceInfo` | No | Price snapshot override (reads from DB if omitted) |
673
+ | `withTrial` | `boolean` | No | Enable trial period (subscription only) |
674
+ | `successUrl` | `string` | No | Redirect URL after successful payment |
675
+ | `expiresInSeconds` | `number` | No | Session expiry in seconds (default: 45 minutes) |
676
+ | `darkMode` | `boolean` | No | Dark mode override (true=dark, false=light, omit=store default) |
677
+ | `metadata` | `Record<string, string>` | No | Custom metadata |
650
678
 
651
679
  **Returns `AuthenticatedCheckoutResult`**:
652
680
 
653
- | Field | Type | Description |
654
- |-------|------|-------------|
655
- | `sessionId` | `string` | Session ID |
656
- | `checkoutUrl` | `string` | Checkout URL with `#token=...` appended |
657
- | `expiresAt` | `string` | Session expiration time |
658
- | `token` | `string` | Issued JWT token |
659
- | `tokenExpiresAt` | `string` | Token expiration time |
681
+ | Field | Type | Description |
682
+ | ---------------- | -------- | --------------------------------------- |
683
+ | `sessionId` | `string` | Session ID |
684
+ | `checkoutUrl` | `string` | Checkout URL with `#token=...` appended |
685
+ | `expiresAt` | `string` | Session expiration time |
686
+ | `token` | `string` | Issued JWT token |
687
+ | `tokenExpiresAt` | `string` | Token expiration time |
660
688
 
661
689
  ### `client.checkout.anonymous.create(params)`
662
690
 
@@ -681,24 +709,24 @@ const snapshotResult = await client.checkout.anonymous.create({
681
709
 
682
710
  **Parameters `AnonymousCheckoutParams`**:
683
711
 
684
- | Field | Type | Required | Description |
685
- |-------|------|----------|-------------|
686
- | `productId` | `string` | Yes | Product ID (product type is auto-detected server-side) |
687
- | `currency` | `string` | Yes | Currency code (ISO 4217) |
688
- | `priceSnapshot` | `PriceInfo` | No | Price snapshot override (reads from DB if omitted) |
689
- | `withTrial` | `boolean` | No | Enable trial period (subscription only) |
690
- | `successUrl` | `string` | No | Redirect URL after successful payment |
691
- | `expiresInSeconds` | `number` | No | Session expiry in seconds (default: 45 minutes) |
692
- | `darkMode` | `boolean` | No | Dark mode override (true=dark, false=light, omit=store default) |
693
- | `metadata` | `Record<string, string>` | No | Custom metadata |
712
+ | Field | Type | Required | Description |
713
+ | ------------------ | ------------------------ | -------- | --------------------------------------------------------------- |
714
+ | `productId` | `string` | Yes | Product ID (product type is auto-detected server-side) |
715
+ | `currency` | `string` | Yes | Currency code (ISO 4217) |
716
+ | `priceSnapshot` | `PriceInfo` | No | Price snapshot override (reads from DB if omitted) |
717
+ | `withTrial` | `boolean` | No | Enable trial period (subscription only) |
718
+ | `successUrl` | `string` | No | Redirect URL after successful payment |
719
+ | `expiresInSeconds` | `number` | No | Session expiry in seconds (default: 45 minutes) |
720
+ | `darkMode` | `boolean` | No | Dark mode override (true=dark, false=light, omit=store default) |
721
+ | `metadata` | `Record<string, string>` | No | Custom metadata |
694
722
 
695
723
  **Returns `CheckoutSessionResult`**:
696
724
 
697
- | Field | Type | Description |
698
- |-------|------|-------------|
699
- | `sessionId` | `string` | Session ID |
725
+ | Field | Type | Description |
726
+ | ------------- | -------- | ------------------------ |
727
+ | `sessionId` | `string` | Session ID |
700
728
  | `checkoutUrl` | `string` | Hosted checkout page URL |
701
- | `expiresAt` | `string` | Session expiration time |
729
+ | `expiresAt` | `string` | Session expiration time |
702
730
 
703
731
  ### `client.checkout.createSession(params)` (low-level)
704
732
 
@@ -714,37 +742,37 @@ const session = await client.checkout.createSession({
714
742
 
715
743
  **Parameters `CreateCheckoutSessionParams`**:
716
744
 
717
- | Field | Type | Required | Description |
718
- |-------|------|----------|-------------|
719
- | `productId` | `string` | Yes | Product ID (product type is auto-detected server-side) |
720
- | `currency` | `string` | Yes | Currency code (ISO 4217) |
721
- | `priceSnapshot` | `PriceInfo` | No | Price snapshot override (reads from DB if omitted) |
722
- | `withTrial` | `boolean` | No | Enable trial period (subscription only) |
723
- | `buyerEmail` | `string` | No | Pre-filled buyer email |
724
- | `billingDetail` | `BillingDetail` | No | Pre-filled billing details (country, tax ID, etc.) |
725
- | `successUrl` | `string` | No | Redirect URL after successful payment |
726
- | `expiresInSeconds` | `number` | No | Session expiry in seconds (default: 45 minutes) |
727
- | `darkMode` | `boolean` | No | Dark mode override |
728
- | `metadata` | `Record<string, string>` | No | Custom metadata |
745
+ | Field | Type | Required | Description |
746
+ | ------------------ | ------------------------ | -------- | ------------------------------------------------------ |
747
+ | `productId` | `string` | Yes | Product ID (product type is auto-detected server-side) |
748
+ | `currency` | `string` | Yes | Currency code (ISO 4217) |
749
+ | `priceSnapshot` | `PriceInfo` | No | Price snapshot override (reads from DB if omitted) |
750
+ | `withTrial` | `boolean` | No | Enable trial period (subscription only) |
751
+ | `buyerEmail` | `string` | No | Pre-filled buyer email |
752
+ | `billingDetail` | `BillingDetail` | No | Pre-filled billing details (country, tax ID, etc.) |
753
+ | `successUrl` | `string` | No | Redirect URL after successful payment |
754
+ | `expiresInSeconds` | `number` | No | Session expiry in seconds (default: 45 minutes) |
755
+ | `darkMode` | `boolean` | No | Dark mode override |
756
+ | `metadata` | `Record<string, string>` | No | Custom metadata |
729
757
 
730
758
  **`BillingDetail` fields**:
731
759
 
732
- | Field | Type | Required | Description |
733
- |-------|------|----------|-------------|
734
- | `country` | `string` | Yes | Country code (ISO 3166-1 alpha-2) |
735
- | `isBusiness` | `boolean` | Yes | Whether this is a business purchase |
736
- | `postcode` | `string` | No | Postal / ZIP code |
737
- | `state` | `string` | Conditional | State / province code (required when `country` is `US` or `CA`) |
738
- | `businessName` | `string` | Conditional | Business name (required when `isBusiness` is `true`) |
739
- | `taxId` | `string` | Conditional | Tax ID / VAT number (required for EU countries when `isBusiness` is `true`; triggers reverse charge 0%) |
760
+ | Field | Type | Required | Description |
761
+ | -------------- | --------- | ----------- | ------------------------------------------------------------------------------------------------------- |
762
+ | `country` | `string` | Yes | Country code (ISO 3166-1 alpha-2) |
763
+ | `isBusiness` | `boolean` | Yes | Whether this is a business purchase |
764
+ | `postcode` | `string` | No | Postal / ZIP code |
765
+ | `state` | `string` | Conditional | State / province code (required when `country` is `US` or `CA`) |
766
+ | `businessName` | `string` | Conditional | Business name (required when `isBusiness` is `true`) |
767
+ | `taxId` | `string` | Conditional | Tax ID / VAT number (required for EU countries when `isBusiness` is `true`; triggers reverse charge 0%) |
740
768
 
741
769
  **Returns `CheckoutSessionResult`**:
742
770
 
743
- | Field | Type | Description |
744
- |-------|------|-------------|
745
- | `sessionId` | `string` | Session ID |
771
+ | Field | Type | Description |
772
+ | ------------- | -------- | ------------------------ |
773
+ | `sessionId` | `string` | Session ID |
746
774
  | `checkoutUrl` | `string` | Hosted checkout page URL |
747
- | `expiresAt` | `string` | Session expiration time |
775
+ | `expiresAt` | `string` | Session expiration time |
748
776
 
749
777
  ---
750
778
 
@@ -772,16 +800,16 @@ const productResult = await client.graphql.query({
772
800
 
773
801
  **Parameters `GraphQLParams`**:
774
802
 
775
- | Field | Type | Required | Description |
776
- |-------|------|----------|-------------|
777
- | `query` | `string` | Yes | GraphQL query string |
778
- | `variables` | `Record<string, unknown>` | No | Query variables |
803
+ | Field | Type | Required | Description |
804
+ | ----------- | ------------------------- | -------- | -------------------- |
805
+ | `query` | `string` | Yes | GraphQL query string |
806
+ | `variables` | `Record<string, unknown>` | No | Query variables |
779
807
 
780
808
  **Returns `GraphQLResponse<T>`**:
781
809
 
782
- | Field | Type | Description |
783
- |-------|------|-------------|
784
- | `data` | `T \| null` | Query result |
810
+ | Field | Type | Description |
811
+ | -------- | --------------------------------------- | ----------------------- |
812
+ | `data` | `T \| null` | Query result |
785
813
  | `errors` | `Array<{ message, locations?, path? }>` | GraphQL errors (if any) |
786
814
 
787
815
  See [GraphQL Guide](graphql-guide.md) for introspection, filters, pagination, and practical examples.
@@ -792,80 +820,80 @@ See [GraphQL Guide](graphql-guide.md) for introspection, filters, pagination, an
792
820
 
793
821
  All exported type interfaces:
794
822
 
795
- | Export | Description |
796
- |--------|-------------|
797
- | **Config** | |
798
- | `WaffoPancakeConfig` | Client configuration |
799
- | **Response Envelope** | |
800
- | `ApiError` | Error object (`{ message, layer }`) |
801
- | `ApiErrorResponse` | Error response (`{ data: null, errors }`) |
802
- | `ApiResponse<T>` | Union of success and error responses |
803
- | `ApiSuccessResponse<T>` | Success response (`{ data: T }`) |
804
- | **Auth** | |
805
- | `IssueSessionTokenParams` | Issue token request |
806
- | `SessionToken` | Token response |
807
- | **Store** | |
808
- | `Store` | Store entity |
809
- | `CreateStoreParams` | Create store request |
810
- | `UpdateStoreParams` | Update store request |
811
- | `DeleteStoreParams` | Delete store request |
812
- | `WebhookSettings` | Webhook endpoint configuration (test/prod) |
813
- | `NotificationSettings` | Email notification preferences |
814
- | `CheckoutSettings` | Checkout page theme (light/dark) |
815
- | `CheckoutThemeSettings` | Single-theme checkout styling |
816
- | **Store Merchant** | |
817
- | `AddMerchantParams` | Add merchant request |
818
- | `AddMerchantResult` | Add merchant response |
819
- | `RemoveMerchantParams` | Remove merchant request |
820
- | `RemoveMerchantResult` | Remove merchant response |
821
- | `UpdateRoleParams` | Update role request |
822
- | `UpdateRoleResult` | Update role response |
823
- | **Product (shared)** | |
824
- | `PriceInfo` | Single-currency price (amount in smallest unit) |
825
- | `Prices` | Multi-currency prices (`Record<currencyCode, PriceInfo>`) |
826
- | `MediaItem` | Media asset (image or video) |
827
- | **Onetime Product** | |
828
- | `OnetimeProductDetail` | One-time product entity |
829
- | `CreateOnetimeProductParams` | Create request |
830
- | `UpdateOnetimeProductParams` | Update request (creates new version) |
831
- | `PublishOnetimeProductParams` | Publish test → prod |
832
- | `UpdateOnetimeStatusParams` | Activate / deactivate |
833
- | **Subscription Product** | |
834
- | `SubscriptionProductDetail` | Subscription product entity |
835
- | `CreateSubscriptionProductParams` | Create request |
836
- | `UpdateSubscriptionProductParams` | Update request (creates new version) |
837
- | `PublishSubscriptionProductParams` | Publish test → prod |
838
- | `UpdateSubscriptionStatusParams` | Activate / deactivate |
839
- | **Subscription Product Group** | |
840
- | `SubscriptionProductGroup` | Product group entity |
841
- | `GroupRules` | Group rules (shared trial, etc.) |
842
- | `CreateSubscriptionProductGroupParams` | Create request |
843
- | `UpdateSubscriptionProductGroupParams` | Update request (`productIds` = full replacement) |
844
- | `DeleteSubscriptionProductGroupParams` | Delete request |
845
- | `PublishSubscriptionProductGroupParams` | Publish test → prod |
846
- | **Order** | |
847
- | `CancelSubscriptionParams` | Cancel subscription request |
848
- | `CancelSubscriptionResult` | Cancel subscription response |
849
- | `BillingDetail` | Buyer billing details (country, tax ID, etc.) |
850
- | **Buyer Self-Service** | |
851
- | `CancelOnetimeOrderParams` | Cancel one-time order request |
852
- | `CancelOnetimeOrderResult` | Cancel one-time order response |
853
- | `ReactivateSubscriptionParams` | Reactivate subscription request |
854
- | `ReactivateSubscriptionResult` | Reactivate subscription response |
855
- | `CreateRefundTicketParams` | Create refund ticket request |
856
- | `ResubmitRefundTicketParams` | Resubmit refund ticket request |
857
- | `RefundTicket` | Refund ticket entity |
858
- | `RequestedAmount` | Refund amount (`{ amount, currency }`) |
859
- | **Checkout** | |
860
- | `AuthenticatedCheckoutParams` | Authenticated checkout request (with buyer identity) |
861
- | `AuthenticatedCheckoutResult` | Authenticated checkout response (URL with token + expiry) |
862
- | `AnonymousCheckoutParams` | Anonymous checkout request (no identity) |
863
- | `CreateCheckoutSessionParams` | Low-level checkout session request |
864
- | `CheckoutSessionResult` | Checkout session response (URL + expiry) |
865
- | **GraphQL** | |
866
- | `GraphQLParams` | GraphQL query parameters |
867
- | `GraphQLResponse<T>` | GraphQL response envelope |
868
- | **Webhook** | |
869
- | `WebhookEvent<T>` | Webhook event payload |
870
- | `WebhookEventData` | Common event data fields |
871
- | `VerifyWebhookOptions` | Verification options (environment, tolerance) |
823
+ | Export | Description |
824
+ | --------------------------------------- | --------------------------------------------------------- |
825
+ | **Config** | |
826
+ | `WaffoPancakeConfig` | Client configuration |
827
+ | **Response Envelope** | |
828
+ | `ApiError` | Error object (`{ message, layer }`) |
829
+ | `ApiErrorResponse` | Error response (`{ data: null, errors }`) |
830
+ | `ApiResponse<T>` | Union of success and error responses |
831
+ | `ApiSuccessResponse<T>` | Success response (`{ data: T }`) |
832
+ | **Auth** | |
833
+ | `IssueSessionTokenParams` | Issue token request |
834
+ | `SessionToken` | Token response |
835
+ | **Store** | |
836
+ | `Store` | Store entity |
837
+ | `CreateStoreParams` | Create store request |
838
+ | `UpdateStoreParams` | Update store request |
839
+ | `DeleteStoreParams` | Delete store request |
840
+ | `WebhookSettings` | Webhook endpoint configuration (test/prod) |
841
+ | `NotificationSettings` | Email notification preferences |
842
+ | `CheckoutSettings` | Checkout page theme (light/dark) |
843
+ | `CheckoutThemeSettings` | Single-theme checkout styling |
844
+ | **Store Merchant** | |
845
+ | `AddMerchantParams` | Add merchant request |
846
+ | `AddMerchantResult` | Add merchant response |
847
+ | `RemoveMerchantParams` | Remove merchant request |
848
+ | `RemoveMerchantResult` | Remove merchant response |
849
+ | `UpdateRoleParams` | Update role request |
850
+ | `UpdateRoleResult` | Update role response |
851
+ | **Product (shared)** | |
852
+ | `PriceInfo` | Single-currency price (amount in smallest unit) |
853
+ | `Prices` | Multi-currency prices (`Record<currencyCode, PriceInfo>`) |
854
+ | `MediaItem` | Media asset (image or video) |
855
+ | **Onetime Product** | |
856
+ | `OnetimeProductDetail` | One-time product entity |
857
+ | `CreateOnetimeProductParams` | Create request |
858
+ | `UpdateOnetimeProductParams` | Update request (creates new version) |
859
+ | `PublishOnetimeProductParams` | Publish test → prod |
860
+ | `UpdateOnetimeStatusParams` | Activate / deactivate |
861
+ | **Subscription Product** | |
862
+ | `SubscriptionProductDetail` | Subscription product entity |
863
+ | `CreateSubscriptionProductParams` | Create request |
864
+ | `UpdateSubscriptionProductParams` | Update request (creates new version) |
865
+ | `PublishSubscriptionProductParams` | Publish test → prod |
866
+ | `UpdateSubscriptionStatusParams` | Activate / deactivate |
867
+ | **Subscription Product Group** | |
868
+ | `SubscriptionProductGroup` | Product group entity |
869
+ | `GroupRules` | Group rules (shared trial, etc.) |
870
+ | `CreateSubscriptionProductGroupParams` | Create request |
871
+ | `UpdateSubscriptionProductGroupParams` | Update request (`productIds` = full replacement) |
872
+ | `DeleteSubscriptionProductGroupParams` | Delete request |
873
+ | `PublishSubscriptionProductGroupParams` | Publish test → prod |
874
+ | **Order** | |
875
+ | `CancelSubscriptionParams` | Cancel subscription request |
876
+ | `CancelSubscriptionResult` | Cancel subscription response |
877
+ | `BillingDetail` | Buyer billing details (country, tax ID, etc.) |
878
+ | **Buyer Self-Service** | |
879
+ | `CancelOnetimeOrderParams` | Cancel one-time order request |
880
+ | `CancelOnetimeOrderResult` | Cancel one-time order response |
881
+ | `ReactivateSubscriptionParams` | Reactivate subscription request |
882
+ | `ReactivateSubscriptionResult` | Reactivate subscription response |
883
+ | `CreateRefundTicketParams` | Create refund ticket request |
884
+ | `ResubmitRefundTicketParams` | Resubmit refund ticket request |
885
+ | `RefundTicket` | Refund ticket entity |
886
+ | `RequestedAmount` | Refund amount (`{ amount, currency }`) |
887
+ | **Checkout** | |
888
+ | `AuthenticatedCheckoutParams` | Authenticated checkout request (with buyer identity) |
889
+ | `AuthenticatedCheckoutResult` | Authenticated checkout response (URL with token + expiry) |
890
+ | `AnonymousCheckoutParams` | Anonymous checkout request (no identity) |
891
+ | `CreateCheckoutSessionParams` | Low-level checkout session request |
892
+ | `CheckoutSessionResult` | Checkout session response (URL + expiry) |
893
+ | **GraphQL** | |
894
+ | `GraphQLParams` | GraphQL query parameters |
895
+ | `GraphQLResponse<T>` | GraphQL response envelope |
896
+ | **Webhook** | |
897
+ | `WebhookEvent<T>` | Webhook event payload |
898
+ | `WebhookEventData` | Common event data fields |
899
+ | `VerifyWebhookOptions` | Verification options (environment, tolerance) |