@waffo/pancake-ts 0.20.0 → 0.22.0

package/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to `@waffo/pancake-ts` will be documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.22.0] - 2026-09-17
+
+Subscription webhooks carry the payment channel's billing period number, and merchants can switch off the trial-ending reminder their buyers receive.
+
+### Added
+
+- **`WebhookEventData.periodNumber` (optional `number`)** — which billing period the event refers to, exactly as reported by the payment channel: `1` on the first charge, `N` on the Nth renewal. A failed charge still consumes a period, so it is not a count of successful charges; `0` means the channel authorized the subscription but has not charged it yet. On payment events it is the period of that charge, on refund events the period of the **refunded** charge. Present on the subscription domain events and on `subscription.payment_succeeded`; **absent on one-time orders and their refunds**. Several events in one period share the number, so it is not a deduplication key — use `id` or `eventId`.
+
+### Changed
+
+- **`MerchantWritableNotificationSettings` picks `emailTrialEnding`** — the customer email sent before a paid trial ends is now a merchant decision, writable through `client.stores.update({ notificationSettings: { emailTrialEnding: false } })` and readable back from `Store.notificationSettings`. It defaults to on, is decided per store (there is no per-recipient form of it), and joins `emailUpcomingCharge` as the second `email*` key this type accepts. Every other `email*` toggle stays platform-managed: `update-store` drops it and names it in the response's `warnings`.
+- **`notificationSettings: null` clears `emailTrialEnding` too.** The documented clearing semantics apply to every merchant-writable key, so a store that switched the reminder off gets it back on. Send a partial update carrying only the keys you want to change to keep it off.
+
 ## [0.20.0] - 2026-09-02
 
 Subscription period and status now travel on the subscription events only; `subscription.payment_succeeded` is a pure payment event.

package/README.md

@@ -373,10 +373,16 @@ const { store } = await client.stores.create({ name: "My Store" });
 
 // Update settings (notification, checkout theme).
 // NOTE: webhook configuration moved to client.webhooks (see Webhooks section below).
-// NOTE: only merchant-facing `notify*` toggles (notifyNewOrders / notifyNewSubscriptions /
-//       notifySubscription* / notifyChargeback / notifyPayout*) are writable here;
-//       consumer email toggles (emailOrderConfirmation, emailSubscription*, emailTrial*) are
-//       managed by the PANCAKE platform and silently dropped if passed.
+// NOTE: writable here are all the merchant-facing `notify*` toggles (notifyNewOrders /
+//       notifyNewSubscriptions / notifySubscription* / notifyChargeback /
+//       notifyRefundSucceeded) plus the two buyer-facing reminders
+//       emailUpcomingCharge (renewal) and emailTrialEnding (trial ending). Every
+//       other consumer email toggle (emailOrderConfirmation, emailSubscription*,
+//       emailTrialStarted, emailRefundSucceeded) is managed by the PANCAKE
+//       platform and silently dropped if passed. Payout result emails are
+//       always delivered and have no toggle.
+// NOTE: both reminders are decided per store — every buyer of the store is covered
+//       by the same switch, and passing notificationSettings: null puts them back on.
 // NOTE: supportEmail and website are not writable here — they are set by
 //       ownership verification (email code / domain) or KYB approval.
 const { store: updated } = await client.stores.update({
@@ -384,6 +390,10 @@ const { store: updated } = await client.stores.update({
   notificationSettings: {
     notifyNewOrders: true,
     notifyNewSubscriptions: false,
+    // Stop reminding this store's buyers before a renewal is charged.
+    emailUpcomingCharge: false,
+    // Stop reminding this store's buyers that their paid trial is about to end.
+    emailTrialEnding: false,
   },
 });
 

package/dist/index.cjs

@@ -927,6 +927,12 @@ var StoresResource = class {
    * partial updates: omitted sub-fields keep existing values, `null` clears a
    * field. Pass the entire settings object as `null` to clear all fields.
    *
+   * `notificationSettings` accepts the merchant-writable keys only — every
+   * `notify*` toggle plus the two customer reminders `emailUpcomingCharge` and
+   * `emailTrialEnding`. Other `email*` keys are dropped and named in `warnings`.
+   * Passing `notificationSettings: null` clears the writable keys back to their
+   * default of on, so send a partial update to keep a reminder switched off.
+   *
    * **BREAKING (2026-05)**: the legacy `webhookSettings` parameter is removed.
    * Use `client.webhooks.add / update / remove` to manage webhook endpoints,
    * and query the configured webhook list via GraphQL `Store.storeWebhooks`.
@@ -945,7 +951,14 @@ var StoresResource = class {
    * // Toggle a notification preference
    * const { store } = await client.stores.update({
    *   id: "STO_xxx",
-   *   notificationSettings: { emailOrderConfirmation: false },
+   *   notificationSettings: { notifyNewOrders: false },
+   * });
+   *
+   * @example
+   * // Stop reminding this store's buyers that their trial is about to end
+   * const { store } = await client.stores.update({
+   *   id: "STO_xxx",
+   *   notificationSettings: { emailTrialEnding: false },
    * });
    */
   async update(params) {