@waffo/pancake-ts 0.3.1 → 0.3.3

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 (10) hide show
  1. package/CHANGELOG.md +6 -0
  2. package/README.md +66 -69
  3. package/dist/index.cjs +36 -64
  4. package/dist/index.cjs.map +1 -1
  5. package/dist/index.js +36 -64
  6. package/dist/index.js.map +1 -1
  7. package/docs/api-reference.md +290 -289
  8. package/docs/graphql-guide.md +12 -12
  9. package/docs/webhook-guide.md +79 -82
  10. package/package.json +28 -7
package/docs/api-reference.md CHANGED
@@ -3,6 +3,7 @@
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
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
@@ -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
 
@@ -296,15 +297,15 @@ const { product: p2 } = await client.onetimeProducts.update({
296
297
 
297
298
  **Parameters `UpdateOnetimeProductParams`**:
298
299
 
299
- | Field | Type | Required | Description |
300
- |-------|------|----------|-------------|
301
- | `id` | `string` | Yes | Product ID |
302
- | `name` | `string` | No | Product name |
303
- | `prices` | `Prices` | No | Multi-currency prices |
304
- | `description` | `string` | No | Product description |
305
- | `media` | `MediaItem[]` | No | Media assets |
306
- | `successUrl` | `string` | No | Redirect URL after successful payment |
307
- | `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 |
308
309
 
309
310
  **Returns `{ product: OnetimeProductDetail }`**
310
311
 
@@ -318,9 +319,9 @@ const { product } = await client.onetimeProducts.publish({ id: "PROD_xxx" });
318
319
 
319
320
  **Parameters `PublishOnetimeProductParams`**:
320
321
 
321
- | Field | Type | Required | Description |
322
- |-------|------|----------|-------------|
323
- | `id` | `string` | Yes | Product ID |
322
+ | Field | Type | Required | Description |
323
+ | ----- | -------- | -------- | ----------- |
324
+ | `id` | `string` | Yes | Product ID |
324
325
 
325
326
  **Returns `{ product: OnetimeProductDetail }`**
326
327
 
@@ -339,10 +340,10 @@ const { product } = await client.onetimeProducts.updateStatus({
339
340
 
340
341
  **Parameters `UpdateOnetimeStatusParams`**:
341
342
 
342
- | Field | Type | Required | Description |
343
- |-------|------|----------|-------------|
344
- | `id` | `string` | Yes | Product ID |
345
- | `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` |
346
347
 
347
348
  **Returns `{ product: OnetimeProductDetail }`**
348
349
 
@@ -368,16 +369,16 @@ const { product } = await client.subscriptionProducts.create({
368
369
 
369
370
  **Parameters `CreateSubscriptionProductParams`**:
370
371
 
371
- | Field | Type | Required | Description |
372
- |-------|------|----------|-------------|
373
- | `storeId` | `string` | Yes | Store ID |
374
- | `name` | `string` | Yes | Product name |
375
- | `billingPeriod` | `BillingPeriod` | Yes | Billing period (`Weekly` / `Monthly` / `Quarterly` / `Yearly`) |
376
- | `prices` | `Prices` | Yes | Multi-currency prices |
377
- | `description` | `string` | No | Product description |
378
- | `media` | `MediaItem[]` | No | Media assets |
379
- | `successUrl` | `string` | No | Redirect URL after successful payment |
380
- | `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 |
381
382
 
382
383
  **Returns `{ product: SubscriptionProductDetail }`**
383
384
 
@@ -404,16 +405,16 @@ const { product: p2 } = await client.subscriptionProducts.update({
404
405
 
405
406
  **Parameters `UpdateSubscriptionProductParams`**:
406
407
 
407
- | Field | Type | Required | Description |
408
- |-------|------|----------|-------------|
409
- | `id` | `string` | Yes | Product ID |
410
- | `name` | `string` | No | Product name |
411
- | `billingPeriod` | `BillingPeriod` | No | Billing period |
412
- | `prices` | `Prices` | No | Multi-currency prices |
413
- | `description` | `string` | No | Product description |
414
- | `media` | `MediaItem[]` | No | Media assets |
415
- | `successUrl` | `string` | No | Redirect URL after successful payment |
416
- | `metadata` | `Record<string, unknown>` | No | Custom metadata |
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 |
417
418
 
418
419
  **Returns `{ product: SubscriptionProductDetail }`**
419
420
 
@@ -462,13 +463,13 @@ const { group } = await client.subscriptionProductGroups.create({
462
463
 
463
464
  **Parameters `CreateSubscriptionProductGroupParams`**:
464
465
 
465
- | Field | Type | Required | Description |
466
- |-------|------|----------|-------------|
467
- | `storeId` | `string` | Yes | Store ID |
468
- | `name` | `string` | Yes | Group name |
469
- | `description` | `string` | No | Group description |
470
- | `rules` | `GroupRules` | No | Group rules (e.g. `{ sharedTrial: true }`) |
471
- | `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 |
472
473
 
473
474
  **Returns `{ group: SubscriptionProductGroup }`**
474
475
 
@@ -513,9 +514,9 @@ const { group } = await client.subscriptionProductGroups.publish({ id: "spg_xxx"
513
514
 
514
515
  Cancel a subscription order. The resulting status depends on the current order state:
515
516
 
516
- | Current Status | Result | Behavior |
517
- |---------------|--------|----------|
518
- | `pending` | `canceled` | Immediate cancellation |
517
+ | Current Status | Result | Behavior |
518
+ | --------------------- | ----------- | -------------------------------------------------------- |
519
+ | `pending` | `canceled` | Immediate cancellation |
519
520
  | `active` / `trialing` | `canceling` | PSP cancellation initiated; webhook updates status later |
520
521
 
521
522
  ```typescript
@@ -527,16 +528,16 @@ const { orderId, status } = await client.orders.cancelSubscription({
527
528
 
528
529
  **Parameters `CancelSubscriptionParams`**:
529
530
 
530
- | Field | Type | Required | Description |
531
- |-------|------|----------|-------------|
532
- | `orderId` | `string` | Yes | Order ID |
531
+ | Field | Type | Required | Description |
532
+ | --------- | -------- | -------- | ----------- |
533
+ | `orderId` | `string` | Yes | Order ID |
533
534
 
534
535
  **Returns `CancelSubscriptionResult`**:
535
536
 
536
- | Field | Type | Description |
537
- |-------|------|-------------|
538
- | `orderId` | `string` | Order ID |
539
- | `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"`) |
540
541
 
541
542
  ---
542
543
 
@@ -558,54 +559,54 @@ const buyer = client.buyer(token);
558
559
 
559
560
  ### `buyer.cancelSubscription(params)`
560
561
 
561
- | Field | Type | Required | Description |
562
- |-------|------|----------|-------------|
563
- | `orderId` | `string` | Yes | Subscription order ID |
562
+ | Field | Type | Required | Description |
563
+ | --------- | -------- | -------- | --------------------- |
564
+ | `orderId` | `string` | Yes | Subscription order ID |
564
565
 
565
566
  **Returns `CancelSubscriptionResult`**: `{ orderId, status }` — status is `"canceling"` (active) or `"canceled"` (pending)
566
567
 
567
568
  ### `buyer.cancelOnetimeOrder(params)`
568
569
 
569
- | Field | Type | Required | Description |
570
- |-------|------|----------|-------------|
571
- | `orderId` | `string` | Yes | One-time order ID |
570
+ | Field | Type | Required | Description |
571
+ | --------- | -------- | -------- | ----------------- |
572
+ | `orderId` | `string` | Yes | One-time order ID |
572
573
 
573
574
  **Returns `CancelOnetimeOrderResult`**: `{ orderId, status }` — status is `"canceled"`
574
575
 
575
576
  ### `buyer.reactivateSubscription(params)`
576
577
 
577
- | Field | Type | Required | Description |
578
- |-------|------|----------|-------------|
579
- | `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) |
580
581
 
581
582
  **Returns `ReactivateSubscriptionResult`**: `{ orderId, status }` — status is `"active"`
582
583
 
583
584
  ### `buyer.createRefundTicket(params)`
584
585
 
585
- | Field | Type | Required | Description |
586
- |-------|------|----------|-------------|
587
- | `paymentId` | `string` | Yes | Payment ID to refund |
588
- | `reason` | `string` | Yes | Reason for the refund request |
589
- | `requestedAmount` | `RequestedAmount` | Yes | Refund amount (`{ amount, currency }`) |
590
- | `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 |
591
592
 
592
593
  **`RequestedAmount`**:
593
594
 
594
- | Field | Type | Description |
595
- |-------|------|-------------|
596
- | `amount` | `string` | Amount in display format (e.g., `"29.00"`) |
597
- | `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) |
598
599
 
599
600
  **Returns `{ ticket: RefundTicket }`**
600
601
 
601
602
  ### `buyer.resubmitRefundTicket(params)`
602
603
 
603
- | Field | Type | Required | Description |
604
- |-------|------|----------|-------------|
605
- | `ticketId` | `string` | Yes | Existing ticket ID |
606
- | `paymentId` | `string` | Yes | Payment ID |
607
- | `reason` | `string` | Yes | Updated reason |
608
- | `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 |
609
610
 
610
611
  **Returns `{ ticket: RefundTicket }`**
611
612
 
@@ -613,10 +614,10 @@ const buyer = client.buyer(token);
613
614
 
614
615
  Same parameters as `client.graphql.query<T>()` but scoped to the buyer's own data via session token.
615
616
 
616
- | Field | Type | Required | Description |
617
- |-------|------|----------|-------------|
618
- | `query` | `string` | Yes | GraphQL query string |
619
- | `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 |
620
621
 
621
622
  **Returns `GraphQLResponse<T>`**: `{ data, errors? }`
622
623
 
@@ -661,29 +662,29 @@ const subResult = await client.checkout.authenticated.create({
661
662
 
662
663
  **Parameters `AuthenticatedCheckoutParams`**:
663
664
 
664
- | Field | Type | Required | Description |
665
- |-------|------|----------|-------------|
666
- | `productId` | `string` | Yes | Product ID (product type is auto-detected server-side) |
667
- | `currency` | `string` | Yes | Currency code (ISO 4217) |
668
- | `buyerIdentity` | `string` | Yes | Buyer identity (email or merchant-defined identifier) |
669
- | `buyerEmail` | `string` | No | Pre-filled buyer email (defaults to `buyerIdentity`) |
670
- | `billingDetail` | `BillingDetail` | No | Pre-filled billing details (country, tax ID, etc.) |
671
- | `priceSnapshot` | `PriceInfo` | No | Price snapshot override (reads from DB if omitted) |
672
- | `withTrial` | `boolean` | No | Enable trial period (subscription only) |
673
- | `successUrl` | `string` | No | Redirect URL after successful payment |
674
- | `expiresInSeconds` | `number` | No | Session expiry in seconds (default: 45 minutes) |
675
- | `darkMode` | `boolean` | No | Dark mode override (true=dark, false=light, omit=store default) |
676
- | `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 |
677
678
 
678
679
  **Returns `AuthenticatedCheckoutResult`**:
679
680
 
680
- | Field | Type | Description |
681
- |-------|------|-------------|
682
- | `sessionId` | `string` | Session ID |
683
- | `checkoutUrl` | `string` | Checkout URL with `#token=...` appended |
684
- | `expiresAt` | `string` | Session expiration time |
685
- | `token` | `string` | Issued JWT token |
686
- | `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 |
687
688
 
688
689
  ### `client.checkout.anonymous.create(params)`
689
690
 
@@ -708,24 +709,24 @@ const snapshotResult = await client.checkout.anonymous.create({
708
709
 
709
710
  **Parameters `AnonymousCheckoutParams`**:
710
711
 
711
- | Field | Type | Required | Description |
712
- |-------|------|----------|-------------|
713
- | `productId` | `string` | Yes | Product ID (product type is auto-detected server-side) |
714
- | `currency` | `string` | Yes | Currency code (ISO 4217) |
715
- | `priceSnapshot` | `PriceInfo` | No | Price snapshot override (reads from DB if omitted) |
716
- | `withTrial` | `boolean` | No | Enable trial period (subscription only) |
717
- | `successUrl` | `string` | No | Redirect URL after successful payment |
718
- | `expiresInSeconds` | `number` | No | Session expiry in seconds (default: 45 minutes) |
719
- | `darkMode` | `boolean` | No | Dark mode override (true=dark, false=light, omit=store default) |
720
- | `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 |
721
722
 
722
723
  **Returns `CheckoutSessionResult`**:
723
724
 
724
- | Field | Type | Description |
725
- |-------|------|-------------|
726
- | `sessionId` | `string` | Session ID |
725
+ | Field | Type | Description |
726
+ | ------------- | -------- | ------------------------ |
727
+ | `sessionId` | `string` | Session ID |
727
728
  | `checkoutUrl` | `string` | Hosted checkout page URL |
728
- | `expiresAt` | `string` | Session expiration time |
729
+ | `expiresAt` | `string` | Session expiration time |
729
730
 
730
731
  ### `client.checkout.createSession(params)` (low-level)
731
732
 
@@ -741,37 +742,37 @@ const session = await client.checkout.createSession({
741
742
 
742
743
  **Parameters `CreateCheckoutSessionParams`**:
743
744
 
744
- | Field | Type | Required | Description |
745
- |-------|------|----------|-------------|
746
- | `productId` | `string` | Yes | Product ID (product type is auto-detected server-side) |
747
- | `currency` | `string` | Yes | Currency code (ISO 4217) |
748
- | `priceSnapshot` | `PriceInfo` | No | Price snapshot override (reads from DB if omitted) |
749
- | `withTrial` | `boolean` | No | Enable trial period (subscription only) |
750
- | `buyerEmail` | `string` | No | Pre-filled buyer email |
751
- | `billingDetail` | `BillingDetail` | No | Pre-filled billing details (country, tax ID, etc.) |
752
- | `successUrl` | `string` | No | Redirect URL after successful payment |
753
- | `expiresInSeconds` | `number` | No | Session expiry in seconds (default: 45 minutes) |
754
- | `darkMode` | `boolean` | No | Dark mode override |
755
- | `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 |
756
757
 
757
758
  **`BillingDetail` fields**:
758
759
 
759
- | Field | Type | Required | Description |
760
- |-------|------|----------|-------------|
761
- | `country` | `string` | Yes | Country code (ISO 3166-1 alpha-2) |
762
- | `isBusiness` | `boolean` | Yes | Whether this is a business purchase |
763
- | `postcode` | `string` | No | Postal / ZIP code |
764
- | `state` | `string` | Conditional | State / province code (required when `country` is `US` or `CA`) |
765
- | `businessName` | `string` | Conditional | Business name (required when `isBusiness` is `true`) |
766
- | `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%) |
767
768
 
768
769
  **Returns `CheckoutSessionResult`**:
769
770
 
770
- | Field | Type | Description |
771
- |-------|------|-------------|
772
- | `sessionId` | `string` | Session ID |
771
+ | Field | Type | Description |
772
+ | ------------- | -------- | ------------------------ |
773
+ | `sessionId` | `string` | Session ID |
773
774
  | `checkoutUrl` | `string` | Hosted checkout page URL |
774
- | `expiresAt` | `string` | Session expiration time |
775
+ | `expiresAt` | `string` | Session expiration time |
775
776
 
776
777
  ---
777
778
 
@@ -799,16 +800,16 @@ const productResult = await client.graphql.query({
799
800
 
800
801
  **Parameters `GraphQLParams`**:
801
802
 
802
- | Field | Type | Required | Description |
803
- |-------|------|----------|-------------|
804
- | `query` | `string` | Yes | GraphQL query string |
805
- | `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 |
806
807
 
807
808
  **Returns `GraphQLResponse<T>`**:
808
809
 
809
- | Field | Type | Description |
810
- |-------|------|-------------|
811
- | `data` | `T \| null` | Query result |
810
+ | Field | Type | Description |
811
+ | -------- | --------------------------------------- | ----------------------- |
812
+ | `data` | `T \| null` | Query result |
812
813
  | `errors` | `Array<{ message, locations?, path? }>` | GraphQL errors (if any) |
813
814
 
814
815
  See [GraphQL Guide](graphql-guide.md) for introspection, filters, pagination, and practical examples.
@@ -819,80 +820,80 @@ See [GraphQL Guide](graphql-guide.md) for introspection, filters, pagination, an
819
820
 
820
821
  All exported type interfaces:
821
822
 
822
- | Export | Description |
823
- |--------|-------------|
824
- | **Config** | |
825
- | `WaffoPancakeConfig` | Client configuration |
826
- | **Response Envelope** | |
827
- | `ApiError` | Error object (`{ message, layer }`) |
828
- | `ApiErrorResponse` | Error response (`{ data: null, errors }`) |
829
- | `ApiResponse<T>` | Union of success and error responses |
830
- | `ApiSuccessResponse<T>` | Success response (`{ data: T }`) |
831
- | **Auth** | |
832
- | `IssueSessionTokenParams` | Issue token request |
833
- | `SessionToken` | Token response |
834
- | **Store** | |
835
- | `Store` | Store entity |
836
- | `CreateStoreParams` | Create store request |
837
- | `UpdateStoreParams` | Update store request |
838
- | `DeleteStoreParams` | Delete store request |
839
- | `WebhookSettings` | Webhook endpoint configuration (test/prod) |
840
- | `NotificationSettings` | Email notification preferences |
841
- | `CheckoutSettings` | Checkout page theme (light/dark) |
842
- | `CheckoutThemeSettings` | Single-theme checkout styling |
843
- | **Store Merchant** | |
844
- | `AddMerchantParams` | Add merchant request |
845
- | `AddMerchantResult` | Add merchant response |
846
- | `RemoveMerchantParams` | Remove merchant request |
847
- | `RemoveMerchantResult` | Remove merchant response |
848
- | `UpdateRoleParams` | Update role request |
849
- | `UpdateRoleResult` | Update role response |
850
- | **Product (shared)** | |
851
- | `PriceInfo` | Single-currency price (amount in smallest unit) |
852
- | `Prices` | Multi-currency prices (`Record<currencyCode, PriceInfo>`) |
853
- | `MediaItem` | Media asset (image or video) |
854
- | **Onetime Product** | |
855
- | `OnetimeProductDetail` | One-time product entity |
856
- | `CreateOnetimeProductParams` | Create request |
857
- | `UpdateOnetimeProductParams` | Update request (creates new version) |
858
- | `PublishOnetimeProductParams` | Publish test → prod |
859
- | `UpdateOnetimeStatusParams` | Activate / deactivate |
860
- | **Subscription Product** | |
861
- | `SubscriptionProductDetail` | Subscription product entity |
862
- | `CreateSubscriptionProductParams` | Create request |
863
- | `UpdateSubscriptionProductParams` | Update request (creates new version) |
864
- | `PublishSubscriptionProductParams` | Publish test → prod |
865
- | `UpdateSubscriptionStatusParams` | Activate / deactivate |
866
- | **Subscription Product Group** | |
867
- | `SubscriptionProductGroup` | Product group entity |
868
- | `GroupRules` | Group rules (shared trial, etc.) |
869
- | `CreateSubscriptionProductGroupParams` | Create request |
870
- | `UpdateSubscriptionProductGroupParams` | Update request (`productIds` = full replacement) |
871
- | `DeleteSubscriptionProductGroupParams` | Delete request |
872
- | `PublishSubscriptionProductGroupParams` | Publish test → prod |
873
- | **Order** | |
874
- | `CancelSubscriptionParams` | Cancel subscription request |
875
- | `CancelSubscriptionResult` | Cancel subscription response |
876
- | `BillingDetail` | Buyer billing details (country, tax ID, etc.) |
877
- | **Buyer Self-Service** | |
878
- | `CancelOnetimeOrderParams` | Cancel one-time order request |
879
- | `CancelOnetimeOrderResult` | Cancel one-time order response |
880
- | `ReactivateSubscriptionParams` | Reactivate subscription request |
881
- | `ReactivateSubscriptionResult` | Reactivate subscription response |
882
- | `CreateRefundTicketParams` | Create refund ticket request |
883
- | `ResubmitRefundTicketParams` | Resubmit refund ticket request |
884
- | `RefundTicket` | Refund ticket entity |
885
- | `RequestedAmount` | Refund amount (`{ amount, currency }`) |
886
- | **Checkout** | |
887
- | `AuthenticatedCheckoutParams` | Authenticated checkout request (with buyer identity) |
888
- | `AuthenticatedCheckoutResult` | Authenticated checkout response (URL with token + expiry) |
889
- | `AnonymousCheckoutParams` | Anonymous checkout request (no identity) |
890
- | `CreateCheckoutSessionParams` | Low-level checkout session request |
891
- | `CheckoutSessionResult` | Checkout session response (URL + expiry) |
892
- | **GraphQL** | |
893
- | `GraphQLParams` | GraphQL query parameters |
894
- | `GraphQLResponse<T>` | GraphQL response envelope |
895
- | **Webhook** | |
896
- | `WebhookEvent<T>` | Webhook event payload |
897
- | `WebhookEventData` | Common event data fields |
898
- | `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) |