@waffo/pancake-ts 0.11.0 → 0.13.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.
Files changed (11) hide show
  1. package/CHANGELOG.md +21 -0
  2. package/README.md +43 -42
  3. package/dist/index.cjs +147 -131
  4. package/dist/index.cjs.map +1 -1
  5. package/dist/index.d.cts +201 -174
  6. package/dist/index.d.ts +201 -174
  7. package/dist/index.js +147 -131
  8. package/dist/index.js.map +1 -1
  9. package/docs/api-reference.md +31 -28
  10. package/docs/webhook-guide.md +14 -14
  11. package/package.json +1 -1
package/docs/api-reference.md CHANGED
@@ -15,7 +15,7 @@ Complete reference for all `@waffo/pancake-ts` resources, parameters, and return
15
15
 
16
16
  ### `client.auth.issueSessionToken(params)`
17
17
 
18
- Issue a buyer session token (JWT) for storefront authentication.
18
+ Issue a customer session token (JWT) for storefront authentication.
19
19
 
20
20
  ```typescript
21
21
  // With storeId
@@ -37,7 +37,7 @@ const { token, expiresAt } = await client.auth.issueSessionToken({
37
37
  | --------------- | -------- | -------- | ------------------------------------------------------------------------------------------------ |
38
38
  | `storeId` | `string` | No | Store ID (at least one of `storeId` / `productId` required) |
39
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
+ | `buyerIdentity` | `string` | Yes | Customer identity (email or merchant-defined identifier) |
41
41
 
42
42
  **Returns `SessionToken`**:
43
43
 
@@ -541,23 +541,23 @@ const { orderId, status } = await client.orders.cancelSubscription({
541
541
 
542
542
  ---
543
543
 
544
- ## Buyer Self-Service
544
+ ## Customer Self-Service
545
545
 
546
- Issue a session token and create a buyer session to let buyers manage their own orders.
546
+ Issue a session token and create a customer session to let customers manage their own orders.
547
547
 
548
- ### `client.buyer(token)`
548
+ ### `client.customer(token)`
549
549
 
550
- Create a buyer session from a session token issued by `client.auth.issueSessionToken()`.
550
+ Create a customer session from a session token issued by `client.auth.issueSessionToken()`.
551
551
 
552
552
  ```typescript
553
553
  const { token } = await client.auth.issueSessionToken({
554
554
  storeId: "STO_xxx",
555
555
  buyerIdentity: "customer@example.com",
556
556
  });
557
- const buyer = client.buyer(token);
557
+ const customer = client.customer(token);
558
558
  ```
559
559
 
560
- ### `buyer.cancelSubscription(params)`
560
+ ### `customer.cancelSubscription(params)`
561
561
 
562
562
  | Field | Type | Required | Description |
563
563
  | --------- | -------- | -------- | --------------------- |
@@ -565,7 +565,7 @@ const buyer = client.buyer(token);
565
565
 
566
566
  **Returns `CancelSubscriptionResult`**: `{ orderId, status }` — status is `"canceling"` (active) or `"canceled"` (pending)
567
567
 
568
- ### `buyer.cancelOnetimeOrder(params)`
568
+ ### `customer.cancelOnetimeOrder(params)`
569
569
 
570
570
  | Field | Type | Required | Description |
571
571
  | --------- | -------- | -------- | ----------------- |
@@ -573,7 +573,7 @@ const buyer = client.buyer(token);
573
573
 
574
574
  **Returns `CancelOnetimeOrderResult`**: `{ orderId, status }` — status is `"canceled"`
575
575
 
576
- ### `buyer.reactivateSubscription(params)`
576
+ ### `customer.reactivateSubscription(params)`
577
577
 
578
578
  | Field | Type | Required | Description |
579
579
  | --------- | -------- | -------- | ----------------------------------------------------- |
@@ -581,7 +581,7 @@ const buyer = client.buyer(token);
581
581
 
582
582
  **Returns `ReactivateSubscriptionResult`**: `{ orderId, status }` — status is `"active"`
583
583
 
584
- ### `buyer.createRefundTicket(params)`
584
+ ### `customer.createRefundTicket(params)`
585
585
 
586
586
  | Field | Type | Required | Description |
587
587
  | -------------------------------- | ------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -600,7 +600,7 @@ const buyer = client.buyer(token);
600
600
 
601
601
  **Returns `{ ticket: RefundTicket }`**
602
602
 
603
- ### `buyer.resubmitRefundTicket(params)`
603
+ ### `customer.resubmitRefundTicket(params)`
604
604
 
605
605
  | Field | Type | Required | Description |
606
606
  | ----------------- | ----------------- | -------- | --------------------- |
@@ -611,9 +611,9 @@ const buyer = client.buyer(token);
611
611
 
612
612
  **Returns `{ ticket: RefundTicket }`**
613
613
 
614
- ### `buyer.graphql.query<T>(params)`
614
+ ### `customer.graphql.query<T>(params)`
615
615
 
616
- Same parameters as `client.graphql.query<T>()` but scoped to the buyer's own data via session token.
616
+ Same parameters as `client.graphql.query<T>()` but scoped to the customer's own data via session token.
617
617
 
618
618
  | Field | Type | Required | Description |
619
619
  | ----------- | ------------------------- | -------- | -------------------- |
@@ -626,32 +626,32 @@ Same parameters as `client.graphql.query<T>()` but scoped to the buyer's own dat
626
626
 
627
627
  ## Checkout
628
628
 
629
- Waffo supports two checkout modes based on whether the merchant knows the buyer's identity at checkout time:
629
+ Waffo supports two checkout modes based on whether the merchant knows the customer's identity at checkout time:
630
630
 
631
- - **Authenticated** — the merchant has a user system or collects buyer info before checkout. The buyer's identity is provided upfront, the checkout form is pre-filled, and a session token is automatically issued.
632
- - **Anonymous** — the buyer arrives via a template store or shared link with no prior context. They fill in billing details manually on the checkout page.
631
+ - **Authenticated** — the merchant has a user system or collects customer info before checkout. The customer's identity is provided upfront, the checkout form is pre-filled, and a session token is automatically issued.
632
+ - **Anonymous** — the customer arrives via a template store or shared link with no prior context. They fill in billing details manually on the checkout page.
633
633
 
634
- > **Authenticated checkout is recommended.** The key advantage: the order is bound to the `buyerIdentity` you provide — a **merchant-controlled stable identifier**. Even if the buyer changes the email on the checkout form, the order stays tied to your identifier. In anonymous mode, the buyer self-reports their email, and a different address means a different user — **previous orders become unlinked** and **subscription trial periods can be exploited** (new email = new user = fresh trial). Additionally, anonymous checkout only supports creating orders — buyers cannot cancel orders, manage subscriptions, or submit refund tickets afterward.
634
+ > **Authenticated checkout is recommended.** The key advantage: the order is bound to the `buyerIdentity` you provide — a **merchant-controlled stable identifier**. Even if the customer changes the email on the checkout form, the order stays tied to your identifier. In anonymous mode, the customer self-reports their email, and a different address means a different user — **previous orders become unlinked** and **subscription trial periods can be exploited** (new email = new user = fresh trial). Additionally, anonymous checkout only supports creating orders — customers cannot cancel orders, manage subscriptions, or submit refund tickets afterward.
635
635
 
636
636
  For advanced use cases, the low-level `createSession()` is also available.
637
637
 
638
638
  ### `client.checkout.authenticated.create(params)`
639
639
 
640
- Authenticated checkout — the merchant provides buyer identity. The SDK issues a session token, creates a checkout session, and returns a checkout URL with the token appended as a URL fragment (`#token=...`). The checkout page pre-fills buyer information from the token.
640
+ Authenticated checkout — the merchant provides customer identity. The SDK issues a session token, creates a checkout session, and returns a checkout URL with the token appended as a URL fragment (`#token=...`). The checkout page pre-fills customer information from the token.
641
641
 
642
642
  Internally calls `POST /v1/actions/auth/issue-session-token` and `POST /v1/actions/checkout/create-session` in parallel.
643
643
 
644
644
  `buyerIdentity` is for order attribution and trial tracking only — it is not rendered on the checkout page. To pre-fill the email field on the checkout form, pass `buyerEmail` explicitly.
645
645
 
646
646
  ```typescript
647
- // One-time product with buyer identity (checkout page email field stays empty)
647
+ // One-time product with customer identity (checkout page email field stays empty)
648
648
  const result = await client.checkout.authenticated.create({
649
649
  productId: "PROD_xxx",
650
650
  currency: "USD",
651
651
  buyerIdentity: "userIdInYourSystem",
652
652
  successUrl: "https://example.com/thank-you",
653
653
  });
654
- // => redirect buyer to result.checkoutUrl (includes #token=...)
654
+ // => redirect customer to result.checkoutUrl (includes #token=...)
655
655
 
656
656
  // Subscription with trial and billing detail
657
657
  const subResult = await client.checkout.authenticated.create({
@@ -670,7 +670,7 @@ const subResult = await client.checkout.authenticated.create({
670
670
  | ------------------------- | ------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
671
671
  | `productId` | `string` | Yes | Product ID (product type is auto-detected server-side) |
672
672
  | `currency` | `string` | Yes | Currency code (ISO 4217) |
673
- | `buyerIdentity` | `string` | Yes | Buyer identity (email or merchant-defined identifier) |
673
+ | `buyerIdentity` | `string` | Yes | Customer identity (email or merchant-defined identifier) |
674
674
  | `buyerEmail` | `string` | No | Pre-fill checkout page email field (independent from `buyerIdentity`) |
675
675
  | `billingDetail` | `BillingDetail` | No | Pre-filled billing details (country, tax ID, etc.) |
676
676
  | `priceSnapshot` | `PriceInfo` | No | Price snapshot override (reads from DB if omitted) |
@@ -680,6 +680,7 @@ const subResult = await client.checkout.authenticated.create({
680
680
  | `darkMode` | `boolean` | No | Dark mode override (true=dark, false=light, omit=store default) |
681
681
  | `metadata` | `Record<string, string>` | No | Custom metadata |
682
682
  | `orderMerchantExternalId` | `string` | No | Your business-side order identifier (max 128 chars). Surfaces under the same name on `Order` / `Payment` / `Refund` GraphQL types and in webhook payload (`data.orderMerchantExternalId`). |
683
+ | `language` | `string` | No | Default checkout cashier language (IETF BCP 47), e.g. `pt-BR`, `zh-Hant-TW`. Must be one of the supported cashier languages; the customer can switch on the page. |
683
684
 
684
685
  **Returns `AuthenticatedCheckoutResult`**:
685
686
 
@@ -693,7 +694,7 @@ const subResult = await client.checkout.authenticated.create({
693
694
 
694
695
  ### `client.checkout.anonymous.create(params)`
695
696
 
696
- Anonymous checkout — visitor enters without a session token. The buyer fills in billing details manually on the checkout page.
697
+ Anonymous checkout — visitor enters without a session token. The customer fills in billing details manually on the checkout page.
697
698
 
698
699
  Internally calls `POST /v1/actions/checkout/create-session`.
699
700
 
@@ -702,7 +703,7 @@ const result = await client.checkout.anonymous.create({
702
703
  productId: "PROD_xxx",
703
704
  currency: "USD",
704
705
  });
705
- // => redirect buyer to result.checkoutUrl (buyer fills form manually)
706
+ // => redirect customer to result.checkoutUrl (customer fills form manually)
706
707
 
707
708
  // With price snapshot override
708
709
  const snapshotResult = await client.checkout.anonymous.create({
@@ -725,6 +726,7 @@ const snapshotResult = await client.checkout.anonymous.create({
725
726
  | `darkMode` | `boolean` | No | Dark mode override (true=dark, false=light, omit=store default) |
726
727
  | `metadata` | `Record<string, string>` | No | Custom metadata |
727
728
  | `orderMerchantExternalId` | `string` | No | Your business-side order identifier (max 128 chars). Honored on the API Key path; visitor / store-slug flows silently drop it. Same field name in webhook payload and GraphQL `Order` / `Payment` / `Refund`. |
729
+ | `language` | `string` | No | Default checkout cashier language (IETF BCP 47), e.g. `pt-BR`, `zh-Hant-TW`. Must be one of the supported cashier languages; the customer can switch on the page. |
728
730
 
729
731
  **Returns `CheckoutSessionResult`**:
730
732
 
@@ -754,13 +756,14 @@ const session = await client.checkout.createSession({
754
756
  | `currency` | `string` | Yes | Currency code (ISO 4217) |
755
757
  | `priceSnapshot` | `PriceInfo` | No | Price snapshot override (reads from DB if omitted) |
756
758
  | `withTrial` | `boolean` | No | Enable trial period (subscription only) |
757
- | `buyerEmail` | `string` | No | Pre-filled buyer email |
759
+ | `buyerEmail` | `string` | No | Pre-filled customer email |
758
760
  | `billingDetail` | `BillingDetail` | No | Pre-filled billing details (country, tax ID, etc.) |
759
761
  | `successUrl` | `string` | No | Redirect URL after successful payment |
760
762
  | `expiresInSeconds` | `number` | No | Session expiry in seconds (default: 45 minutes) |
761
763
  | `darkMode` | `boolean` | No | Dark mode override |
762
764
  | `metadata` | `Record<string, string>` | No | Custom metadata |
763
765
  | `orderMerchantExternalId` | `string` | No | Your business-side order identifier (max 128 chars). Honored on the API Key (merchant) path; visitor / store-slug flows silently drop it. Same field name in webhook payload and GraphQL. |
766
+ | `language` | `string` | No | Default checkout cashier language (IETF BCP 47), e.g. `pt-BR`, `zh-Hant-TW`. Must be one of the supported cashier languages; the customer can switch on the page. |
764
767
 
765
768
  **`BillingDetail` fields**:
766
769
 
@@ -881,8 +884,8 @@ All exported type interfaces:
881
884
  | **Order** | |
882
885
  | `CancelSubscriptionParams` | Cancel subscription request |
883
886
  | `CancelSubscriptionResult` | Cancel subscription response |
884
- | `BillingDetail` | Buyer billing details (country, tax ID, etc.) |
885
- | **Buyer Self-Service** | |
887
+ | `BillingDetail` | Customer billing details (country, tax ID, etc.) |
888
+ | **Customer Self-Service** | |
886
889
  | `CancelOnetimeOrderParams` | Cancel one-time order request |
887
890
  | `CancelOnetimeOrderResult` | Cancel one-time order response |
888
891
  | `ReactivateSubscriptionParams` | Reactivate subscription request |
@@ -892,7 +895,7 @@ All exported type interfaces:
892
895
  | `RefundTicket` | Refund ticket entity |
893
896
  | `RequestedAmount` | Refund amount (`{ amount, currency }`) |
894
897
  | **Checkout** | |
895
- | `AuthenticatedCheckoutParams` | Authenticated checkout request (with buyer identity) |
898
+ | `AuthenticatedCheckoutParams` | Authenticated checkout request (with customer identity) |
896
899
  | `AuthenticatedCheckoutResult` | Authenticated checkout response (URL with token + expiry) |
897
900
  | `AnonymousCheckoutParams` | Anonymous checkout request (no identity) |
898
901
  | `CreateCheckoutSessionParams` | Low-level checkout session request |
package/docs/webhook-guide.md CHANGED
@@ -375,8 +375,8 @@ All events include the **Order**, **Amount**, and **Product** sections. Addition
375
375
  | -------------------------------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
376
376
  | `orderId` | `string` | Yes | Associated order ID |
377
377
  | `orderStatus` | `string` | No | Order status (e.g., `"completed"`, `"active"`, `"canceling"`) |
378
- | `buyerEmail` | `string` | Yes | Buyer email address |
379
- | `merchantProvidedBuyerIdentity` | `string` | No | Merchant-provided buyer identity from checkout session |
378
+ | `buyerEmail` | `string` | Yes | Customer email address |
379
+ | `merchantProvidedBuyerIdentity` | `string` | No | Merchant-provided customer identity from checkout session |
380
380
  | `orderMerchantExternalId` | `string` | No | Order business-side identifier set at checkout creation (max 128 chars). Present on order / payment / subscription events and on refund events (inherited from the originating order). |
381
381
  | `refundTicketMerchantExternalId` | `string` | No | Refund-ticket business-side identifier set at refund-ticket creation. **Only present on `refund.*` events**; coexists with `orderMerchantExternalId` on the same refund payload. |
382
382
  | `currency` | `string` | Yes | Currency code (ISO 4217) |
@@ -432,18 +432,18 @@ All events include the **Order**, **Amount**, and **Product** sections. Addition
432
432
 
433
433
  ## Event Types
434
434
 
435
- | Enum Value | String | Trigger |
436
- | ------------------------------ | -------------------------------- | --------------------------------------------------------------- |
437
- | `OrderCompleted` | `order.completed` | One-time order first payment succeeded |
438
- | `SubscriptionActivated` | `subscription.activated` | New subscription activated |
439
- | `SubscriptionPaymentSucceeded` | `subscription.payment_succeeded` | Subscription renewal payment succeeded |
440
- | `SubscriptionCanceling` | `subscription.canceling` | Buyer initiated cancellation (expires at end of billing period) |
441
- | `SubscriptionUncanceled` | `subscription.uncanceled` | Buyer withdrew cancellation request |
442
- | `SubscriptionUpdated` | `subscription.updated` | Subscription product changed (upgrade/downgrade) |
443
- | `SubscriptionCanceled` | `subscription.canceled` | Subscription fully terminated |
444
- | `SubscriptionPastDue` | `subscription.past_due` | Renewal payment failed (past due) |
445
- | `RefundSucceeded` | `refund.succeeded` | Refund completed successfully |
446
- | `RefundFailed` | `refund.failed` | Refund failed |
435
+ | Enum Value | String | Trigger |
436
+ | ------------------------------ | -------------------------------- | ------------------------------------------------------------------ |
437
+ | `OrderCompleted` | `order.completed` | One-time order first payment succeeded |
438
+ | `SubscriptionActivated` | `subscription.activated` | New subscription activated |
439
+ | `SubscriptionPaymentSucceeded` | `subscription.payment_succeeded` | Subscription renewal payment succeeded |
440
+ | `SubscriptionCanceling` | `subscription.canceling` | Customer initiated cancellation (expires at end of billing period) |
441
+ | `SubscriptionUncanceled` | `subscription.uncanceled` | Customer withdrew cancellation request |
442
+ | `SubscriptionUpdated` | `subscription.updated` | Subscription product changed (upgrade/downgrade) |
443
+ | `SubscriptionCanceled` | `subscription.canceled` | Subscription fully terminated |
444
+ | `SubscriptionPastDue` | `subscription.past_due` | Renewal payment failed (past due) |
445
+ | `RefundSucceeded` | `refund.succeeded` | Refund completed successfully |
446
+ | `RefundFailed` | `refund.failed` | Refund failed |
447
447
 
448
448
  ## Key Rotation & Migration
449
449
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@waffo/pancake-ts",
3
- "version": "0.11.0",
3
+ "version": "0.13.0",
4
4
  "description": "TypeScript SDK for Waffo Pancake MoR platform — RSA-SHA256 signing, zero runtime dependencies",
5
5
  "type": "module",
6
6
  "main": "./dist/index.cjs",