@waffo/pancake-ts 0.11.0 → 0.12.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 +12 -0
  2. package/README.md +41 -41
  3. package/dist/index.cjs +147 -131
  4. package/dist/index.cjs.map +1 -1
  5. package/dist/index.d.cts +187 -173
  6. package/dist/index.d.ts +187 -173
  7. package/dist/index.js +147 -131
  8. package/dist/index.js.map +1 -1
  9. package/docs/api-reference.md +28 -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) |
@@ -693,7 +693,7 @@ const subResult = await client.checkout.authenticated.create({
693
693
 
694
694
  ### `client.checkout.anonymous.create(params)`
695
695
 
696
- Anonymous checkout — visitor enters without a session token. The buyer fills in billing details manually on the checkout page.
696
+ Anonymous checkout — visitor enters without a session token. The customer fills in billing details manually on the checkout page.
697
697
 
698
698
  Internally calls `POST /v1/actions/checkout/create-session`.
699
699
 
@@ -702,7 +702,7 @@ const result = await client.checkout.anonymous.create({
702
702
  productId: "PROD_xxx",
703
703
  currency: "USD",
704
704
  });
705
- // => redirect buyer to result.checkoutUrl (buyer fills form manually)
705
+ // => redirect customer to result.checkoutUrl (customer fills form manually)
706
706
 
707
707
  // With price snapshot override
708
708
  const snapshotResult = await client.checkout.anonymous.create({
@@ -754,7 +754,7 @@ const session = await client.checkout.createSession({
754
754
  | `currency` | `string` | Yes | Currency code (ISO 4217) |
755
755
  | `priceSnapshot` | `PriceInfo` | No | Price snapshot override (reads from DB if omitted) |
756
756
  | `withTrial` | `boolean` | No | Enable trial period (subscription only) |
757
- | `buyerEmail` | `string` | No | Pre-filled buyer email |
757
+ | `buyerEmail` | `string` | No | Pre-filled customer email |
758
758
  | `billingDetail` | `BillingDetail` | No | Pre-filled billing details (country, tax ID, etc.) |
759
759
  | `successUrl` | `string` | No | Redirect URL after successful payment |
760
760
  | `expiresInSeconds` | `number` | No | Session expiry in seconds (default: 45 minutes) |
@@ -881,8 +881,8 @@ All exported type interfaces:
881
881
  | **Order** | |
882
882
  | `CancelSubscriptionParams` | Cancel subscription request |
883
883
  | `CancelSubscriptionResult` | Cancel subscription response |
884
- | `BillingDetail` | Buyer billing details (country, tax ID, etc.) |
885
- | **Buyer Self-Service** | |
884
+ | `BillingDetail` | Customer billing details (country, tax ID, etc.) |
885
+ | **Customer Self-Service** | |
886
886
  | `CancelOnetimeOrderParams` | Cancel one-time order request |
887
887
  | `CancelOnetimeOrderResult` | Cancel one-time order response |
888
888
  | `ReactivateSubscriptionParams` | Reactivate subscription request |
@@ -892,7 +892,7 @@ All exported type interfaces:
892
892
  | `RefundTicket` | Refund ticket entity |
893
893
  | `RequestedAmount` | Refund amount (`{ amount, currency }`) |
894
894
  | **Checkout** | |
895
- | `AuthenticatedCheckoutParams` | Authenticated checkout request (with buyer identity) |
895
+ | `AuthenticatedCheckoutParams` | Authenticated checkout request (with customer identity) |
896
896
  | `AuthenticatedCheckoutResult` | Authenticated checkout response (URL with token + expiry) |
897
897
  | `AnonymousCheckoutParams` | Anonymous checkout request (no identity) |
898
898
  | `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.12.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",