@waffo/pancake-ts 0.18.0 → 0.19.1

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.19.0] - 2026-08-18
+
+Subscription products can now charge for the trial period.
+
+### Added
+
+- **`PriceInfo.trialAmount`** — trial period price as a display string, subscription products only. Omit it for a free trial. It requires `metadata.trialDays` on the product and must be lower than `amount`; the API rejects either violation with a 400.
+- **`PriceSnapshot`** — the type `CreateCheckoutSessionParams.priceSnapshot` accepts. Same shape as `PriceInfo` without `trialAmount`.
+
+### Changed
+
+- **`CreateCheckoutSessionParams.priceSnapshot` is typed `PriceSnapshot` rather than `PriceInfo`.** A session-level override replaces the regular period price; the trial price comes from the product version locked into the session, so a `trialAmount` passed here would be dropped server-side. Existing calls compile unchanged — the fields `PriceSnapshot` declares are exactly the two `PriceInfo` had before `trialAmount` was added.
+
 ## [0.18.0] - 2026-08-08
 
 Customer sessions never reached the API, and webhook retries were rejected as replays.
@@ -25,6 +38,7 @@ Customer sessions never reached the API, and webhook retries were rejected as re
 - `client.buyer(token, options)` (deprecated) accepts and forwards the same options.
 - **`VerifyWebhookOptions.toleranceMs` default raised from `300000` to `2700000`, and the window is now asymmetric** — matching the gateway's API Key check, which pairs a wide past-facing window with a tight future-facing one. `toleranceMs` now means "how far in the past"; the future direction is `futureToleranceMs`. `toleranceMs: 0` still disables the check entirely. A captured request stays replayable for longer under the wider window, so keep your handler idempotent on the event `id` — that, not the window, is the real defense.
 
+
 ## [0.17.0] - 2026-08-03
 
 `supportEmail` and `website` were never applied by the update-store endpoint — passing them was silently ignored.

package/README.md

@@ -74,7 +74,7 @@ Waffo supports two checkout modes based on whether the merchant knows the custom
 
 Both modes support **dynamic pricing** and **trial control** at checkout time:
 
-- `priceSnapshot` — override the product's stored price with a custom amount (e.g., coupon, volume discount)
+- `priceSnapshot` — override the product's stored price with a custom amount (e.g., coupon, volume discount); for subscription products this replaces the regular period price only
 - `withTrial` — explicitly enable or disable the trial period for subscriptions (`true` = force trial, `false` = skip trial, omit = use default rules)
 
 ### Authenticated Checkout (Recommended)

package/dist/index.cjs

@@ -588,7 +588,9 @@ var CustomerSession = class {
    *
    * @example
    * const { orderId, status } = await customer.cancelSubscription({ orderId: "ORD_xxx" });
-   * // status: "canceled" (was pending) or "canceling" (was active)
+   * // status: "canceled" (was pending)
+   * //      or "canceling" (was active — stops at the end of the current period)
+   * //      or "canceling" (was past_due — stops immediately)
    */
   async cancelSubscription(params) {
     validateShortId("orderId", params.orderId, "ORD");
@@ -610,6 +612,12 @@ var CustomerSession = class {
   /**
    * Reactivate a subscription that is in `canceling` status.
    *
+   * A subscription that had an unpaid charge at the moment cancellation was
+   * requested is refused with 400 (`Subscription with an unpaid balance cannot
+   * be reactivated`), which is worded differently from the 400 returned when
+   * the order is not in `canceling` status. Cancelling a `past_due`
+   * subscription always falls into the former category.
+   *
    * @param params - Order to reactivate
    * @returns Order ID and resulting status
    *
@@ -808,8 +816,14 @@ var OrdersResource = class {
   /**
    * Cancel a subscription order.
    *
-   * - pending -> canceled (immediate)
-   * - active/trialing -> canceling (PSP cancel, webhook updates later)
+   * - pending -> canceled (immediate, no PSP call)
+   * - active/trialing -> canceling (PSP cancel scheduled for the end of the
+   *   current billing period; the subscription stays usable until then)
+   * - past_due -> canceling (PSP cancel dispatched immediately; the billing
+   *   period has already lapsed, so nothing is left to use)
+   *
+   * In both canceling cases the terminal `canceled` status is written when the
+   * PSP cancellation webhook arrives, not by this call.
    *
    * @param params - Order to cancel
    * @returns Order ID and resulting status