@waffo/pancake-ts 0.19.0 → 0.20.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 (10) hide show
  1. package/CHANGELOG.md +20 -0
  2. package/README.md +17 -17
  3. package/dist/index.cjs +22 -4
  4. package/dist/index.cjs.map +1 -1
  5. package/dist/index.d.cts +39 -10
  6. package/dist/index.d.ts +39 -10
  7. package/dist/index.js +22 -4
  8. package/dist/index.js.map +1 -1
  9. package/docs/webhook-guide.md +45 -13
  10. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -4,6 +4,26 @@ All notable changes to `@waffo/pancake-ts` will be documented in this file.
4
4
 
5
5
  Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
6
6
 
7
+ ## [0.20.0] - 2026-09-02
8
+
9
+ Subscription period and status now travel on the subscription events only; `subscription.payment_succeeded` is a pure payment event.
10
+
11
+ ### Removed
12
+
13
+ - **`WebhookEventType.SubscriptionUpdated` (`subscription.updated`)** — the platform has no publisher for it. Plan changes are published as `subscription.plan_changed`.
14
+ - **`subscription.payment_succeeded` no longer carries `billingPeriod`, `currentPeriodStart`, `currentPeriodEnd`, `canceledAt` or `orderStatus`.** Those five fields described the subscription, not the charge, and were populated from whichever channel notification happened to land first — 10.3% of first payments arrived without a period. They now travel on the subscription domain events, which write and publish inside the same request. `docs/webhook-guide.md` has the field-by-event table and a per-use-case migration path; the payment fields on this event are unchanged.
15
+
16
+ ### Added
17
+
18
+ - **`WebhookEventType.SubscriptionRenewed` (`subscription.renewed`)** — emitted when the current billing period actually rolls forward. Carries the new period. The first period is not a renewal and does not emit it; a redelivered channel notification does not emit a second one.
19
+ - **`WebhookEventType.SubscriptionRecovered` (`subscription.recovered`)** — emitted when a retried charge brings a past-due subscription back to active, closing the loop with `subscription.past_due`. Ordinary renewals and first payments do not emit it.
20
+ - **`WebhookEventType.SubscriptionPlanChanged` / `SubscriptionPlanChangeScheduled` / `SubscriptionPlanChangeFailed`** — the three plan-change events, subscribable from the dashboard.
21
+ - **`NotificationSettings.emailSubscriptionPlanChanged`** — the platform-managed toggle shared by the three plan-change customer emails. Read-only from this SDK, like the other `email*` keys.
22
+
23
+ ### Changed
24
+
25
+ - **`NotificationSettings.notifySubscriptionUpdated` renamed to `notifySubscriptionPlanChanged`** — the old key was never accepted by `update-store`, so a settings object built from the previous type was rejected by server-side validation. `MerchantWritableNotificationSettings` picks the new key.
26
+
7
27
  ## [0.19.0] - 2026-08-18
8
28
 
9
29
  Subscription products can now charge for the trial period.
package/README.md CHANGED
@@ -581,23 +581,23 @@ try {
581
581
 
582
582
  ### Enums
583
583
 
584
- | Export | Values |
585
- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
586
- | `Environment` | `Test`, `Prod` |
587
- | `TaxCategory` | `DigitalGoods`, `SaaS`, `Software`, `Ebook`, `OnlineCourse`, `Consulting`, `ProfessionalService` |
588
- | `BillingPeriod` | `Weekly`, `Monthly`, `Quarterly`, `Yearly` |
589
- | `ProductVersionStatus` | `Active`, `Inactive` |
590
- | `EntityStatus` | `Active`, `Inactive`, `Suspended` |
591
- | `StoreRole` | `Owner`, `Admin`, `Member` |
592
- | `OnetimeOrderStatus` | `Pending`, `Completed`, `Canceled` |
593
- | `SubscriptionOrderStatus` | `Pending`, `Active`, `Canceling`, `PastDue`, `Closed`, `Canceled`, `Expired` |
594
- | `PaymentStatus` | `Pending`, `Succeeded`, `Failed`, `Canceled` |
595
- | `RefundTicketStatus` | `Pending`, `Approved`, `Rejected`, `Processing`, `Succeeded`, `Failed` |
596
- | `RefundStatus` | `Succeeded`, `Failed` |
597
- | `MediaType` | `Image`, `Video` |
598
- | `CheckoutSessionProductType` | `Onetime`, `Subscription` |
599
- | `ErrorLayer` | `Gateway`, `User`, `Store`, `Product`, `Order`, `Ticket`, `GraphQL`, `Resource`, `Email` |
600
- | `WebhookEventType` | `OrderCompleted`, `SubscriptionActivated`, `SubscriptionPaymentSucceeded`, `SubscriptionCanceling`, `SubscriptionUncanceled`, `SubscriptionUpdated`, `SubscriptionCanceled`, `SubscriptionPastDue`, `RefundSucceeded`, `RefundFailed` |
584
+ | Export | Values |
585
+ | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
586
+ | `Environment` | `Test`, `Prod` |
587
+ | `TaxCategory` | `DigitalGoods`, `SaaS`, `Software`, `Ebook`, `OnlineCourse`, `Consulting`, `ProfessionalService` |
588
+ | `BillingPeriod` | `Weekly`, `Monthly`, `Quarterly`, `Yearly` |
589
+ | `ProductVersionStatus` | `Active`, `Inactive` |
590
+ | `EntityStatus` | `Active`, `Inactive`, `Suspended` |
591
+ | `StoreRole` | `Owner`, `Admin`, `Member` |
592
+ | `OnetimeOrderStatus` | `Pending`, `Completed`, `Canceled` |
593
+ | `SubscriptionOrderStatus` | `Pending`, `Active`, `Canceling`, `PastDue`, `Closed`, `Canceled`, `Expired` |
594
+ | `PaymentStatus` | `Pending`, `Succeeded`, `Failed`, `Canceled` |
595
+ | `RefundTicketStatus` | `Pending`, `Approved`, `Rejected`, `Processing`, `Succeeded`, `Failed` |
596
+ | `RefundStatus` | `Succeeded`, `Failed` |
597
+ | `MediaType` | `Image`, `Video` |
598
+ | `CheckoutSessionProductType` | `Onetime`, `Subscription` |
599
+ | `ErrorLayer` | `Gateway`, `User`, `Store`, `Product`, `Order`, `Ticket`, `GraphQL`, `Resource`, `Email` |
600
+ | `WebhookEventType` | `OrderCompleted`, `SubscriptionActivated`, `SubscriptionPaymentSucceeded`, `SubscriptionRenewed`, `SubscriptionRecovered`, `SubscriptionPlanChanged`, `SubscriptionPlanChangeScheduled`, `SubscriptionPlanChangeFailed`, `SubscriptionCanceling`, `SubscriptionUncanceled`, `SubscriptionCanceled`, `SubscriptionPastDue`, `RefundSucceeded`, `RefundFailed` |
601
601
 
602
602
  ### Types
603
603
 
package/dist/index.cjs CHANGED
@@ -588,7 +588,9 @@ var CustomerSession = class {
588
588
  *
589
589
  * @example
590
590
  * const { orderId, status } = await customer.cancelSubscription({ orderId: "ORD_xxx" });
591
- * // status: "canceled" (was pending) or "canceling" (was active)
591
+ * // status: "canceled" (was pending)
592
+ * // or "canceling" (was active — stops at the end of the current period)
593
+ * // or "canceling" (was past_due — stops immediately)
592
594
  */
593
595
  async cancelSubscription(params) {
594
596
  validateShortId("orderId", params.orderId, "ORD");
@@ -610,6 +612,12 @@ var CustomerSession = class {
610
612
  /**
611
613
  * Reactivate a subscription that is in `canceling` status.
612
614
  *
615
+ * A subscription that had an unpaid charge at the moment cancellation was
616
+ * requested is refused with 400 (`Subscription with an unpaid balance cannot
617
+ * be reactivated`), which is worded differently from the 400 returned when
618
+ * the order is not in `canceling` status. Cancelling a `past_due`
619
+ * subscription always falls into the former category.
620
+ *
613
621
  * @param params - Order to reactivate
614
622
  * @returns Order ID and resulting status
615
623
  *
@@ -808,8 +816,14 @@ var OrdersResource = class {
808
816
  /**
809
817
  * Cancel a subscription order.
810
818
  *
811
- * - pending -> canceled (immediate)
812
- * - active/trialing -> canceling (PSP cancel, webhook updates later)
819
+ * - pending -> canceled (immediate, no PSP call)
820
+ * - active/trialing -> canceling (PSP cancel scheduled for the end of the
821
+ * current billing period; the subscription stays usable until then)
822
+ * - past_due -> canceling (PSP cancel dispatched immediately; the billing
823
+ * period has already lapsed, so nothing is left to use)
824
+ *
825
+ * In both canceling cases the terminal `canceled` status is written when the
826
+ * PSP cancellation webhook arrives, not by this call.
813
827
  *
814
828
  * @param params - Order to cancel
815
829
  * @returns Order ID and resulting status
@@ -1550,9 +1564,13 @@ var WebhookEventType = /* @__PURE__ */ ((WebhookEventType2) => {
1550
1564
  WebhookEventType2["OrderCompleted"] = "order.completed";
1551
1565
  WebhookEventType2["SubscriptionActivated"] = "subscription.activated";
1552
1566
  WebhookEventType2["SubscriptionPaymentSucceeded"] = "subscription.payment_succeeded";
1567
+ WebhookEventType2["SubscriptionRenewed"] = "subscription.renewed";
1568
+ WebhookEventType2["SubscriptionRecovered"] = "subscription.recovered";
1569
+ WebhookEventType2["SubscriptionPlanChanged"] = "subscription.plan_changed";
1570
+ WebhookEventType2["SubscriptionPlanChangeScheduled"] = "subscription.plan_change_scheduled";
1571
+ WebhookEventType2["SubscriptionPlanChangeFailed"] = "subscription.plan_change_failed";
1553
1572
  WebhookEventType2["SubscriptionCanceling"] = "subscription.canceling";
1554
1573
  WebhookEventType2["SubscriptionUncanceled"] = "subscription.uncanceled";
1555
- WebhookEventType2["SubscriptionUpdated"] = "subscription.updated";
1556
1574
  WebhookEventType2["SubscriptionCanceled"] = "subscription.canceled";
1557
1575
  WebhookEventType2["SubscriptionPastDue"] = "subscription.past_due";
1558
1576
  WebhookEventType2["RefundSucceeded"] = "refund.succeeded";