@waffo/pancake-ts 0.19.0 → 0.20.0

package/dist/index.d.cts

@@ -177,7 +177,7 @@ declare enum OnetimeOrderStatus {
  * - pending -> active, canceled, closed (PSP CLOSE from never-activated)
  * - active -> canceling, past_due, canceled, expired
  * - canceling -> active, canceled
- * - past_due -> active, canceled
+ * - past_due -> active, canceling, canceled
  * - closed -> terminal (never-activated subscription closed by PSP)
  * - canceled -> terminal
  * - expired -> terminal
@@ -353,6 +353,8 @@ interface NotificationSettings {
     emailTrialStarted: boolean;
     emailTrialEnding: boolean;
     emailUpcomingCharge: boolean;
+    /** One toggle for all three plan-change customer emails (scheduled / failed / applied) */
+    emailSubscriptionPlanChanged: boolean;
     notifyNewOrders: boolean;
     notifyNewSubscriptions: boolean;
     notifySubscriptionCanceled: boolean;
@@ -360,7 +362,7 @@ interface NotificationSettings {
     notifySubscriptionPastDue: boolean;
     notifySubscriptionRenewed: boolean;
     notifySubscriptionUncanceled: boolean;
-    notifySubscriptionUpdated: boolean;
+    notifySubscriptionPlanChanged: boolean;
     notifyChargeback: boolean;
 }
 /**
@@ -371,7 +373,7 @@ interface NotificationSettings {
  * endpoint if included. Payout result notifications are platform-managed and always
  * delivered — they have no toggle key. Use this type for any merchant-side update.
  */
-type MerchantWritableNotificationSettings = Pick<NotificationSettings, "notifyNewOrders" | "notifyNewSubscriptions" | "notifySubscriptionCanceled" | "notifySubscriptionEnded" | "notifySubscriptionPastDue" | "notifySubscriptionRenewed" | "notifySubscriptionUncanceled" | "notifySubscriptionUpdated" | "notifyChargeback">;
+type MerchantWritableNotificationSettings = Pick<NotificationSettings, "notifyNewOrders" | "notifyNewSubscriptions" | "notifySubscriptionCanceled" | "notifySubscriptionEnded" | "notifySubscriptionPastDue" | "notifySubscriptionRenewed" | "notifySubscriptionUncanceled" | "notifySubscriptionPlanChanged" | "notifyChargeback">;
 /**
  * Single-theme checkout page styling.
  * @see docs/api-reference/endpoints/stores/overview.mdx
@@ -1034,14 +1036,22 @@ declare enum WebhookEventType {
     OrderCompleted = "order.completed",
     /** Subscription first payment succeeded (newly activated) */
     SubscriptionActivated = "subscription.activated",
-    /** Subscription renewal payment succeeded */
+    /** Subscription payment succeeded — a pure payment event, carries no subscription period or status */
     SubscriptionPaymentSucceeded = "subscription.payment_succeeded",
+    /** Current billing period rolled forward (renewal) */
+    SubscriptionRenewed = "subscription.renewed",
+    /** Subscription recovered from past due (a retried charge succeeded) */
+    SubscriptionRecovered = "subscription.recovered",
+    /** Plan change took effect (upgrade/downgrade) */
+    SubscriptionPlanChanged = "subscription.plan_changed",
+    /** Plan change confirmed, takes effect next billing period */
+    SubscriptionPlanChangeScheduled = "subscription.plan_change_scheduled",
+    /** Plan change did not complete, the current plan stays in effect */
+    SubscriptionPlanChangeFailed = "subscription.plan_change_failed",
     /** Customer initiated cancellation (expires at end of current period) */
     SubscriptionCanceling = "subscription.canceling",
     /** Customer withdrew cancellation (subscription restored) */
     SubscriptionUncanceled = "subscription.uncanceled",
-    /** Subscription product changed (upgrade/downgrade) */
-    SubscriptionUpdated = "subscription.updated",
     /** Subscription fully terminated */
     SubscriptionCanceled = "subscription.canceled",
     /** Renewal payment failed (past due) */
@@ -1057,7 +1067,12 @@ declare enum WebhookEventType {
  */
 interface WebhookEventData {
     orderId: string;
-    /** Order status (e.g., "completed", "active", "canceling") */
+    /**
+     * Order status (e.g., "completed", "active", "canceling").
+     *
+     * Absent on `subscription.payment_succeeded` — that event describes one charge only.
+     * Read the subscription's status from the subscription events instead.
+     */
     orderStatus?: string;
     buyerEmail: string;
     /** Merchant-provided customer identity from checkout session */
@@ -1571,7 +1586,9 @@ declare class CustomerSession {
      *
      * @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)
      */
     cancelSubscription(params: CancelSubscriptionParams): Promise<CancelSubscriptionResult & {
         warnings?: Notice[];
@@ -1591,6 +1608,12 @@ declare class CustomerSession {
     /**
      * 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
      *
@@ -1766,8 +1789,14 @@ declare class OrdersResource {
     /**
      * 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

package/dist/index.d.ts

@@ -177,7 +177,7 @@ declare enum OnetimeOrderStatus {
  * - pending -> active, canceled, closed (PSP CLOSE from never-activated)
  * - active -> canceling, past_due, canceled, expired
  * - canceling -> active, canceled
- * - past_due -> active, canceled
+ * - past_due -> active, canceling, canceled
  * - closed -> terminal (never-activated subscription closed by PSP)
  * - canceled -> terminal
  * - expired -> terminal
@@ -353,6 +353,8 @@ interface NotificationSettings {
     emailTrialStarted: boolean;
     emailTrialEnding: boolean;
     emailUpcomingCharge: boolean;
+    /** One toggle for all three plan-change customer emails (scheduled / failed / applied) */
+    emailSubscriptionPlanChanged: boolean;
     notifyNewOrders: boolean;
     notifyNewSubscriptions: boolean;
     notifySubscriptionCanceled: boolean;
@@ -360,7 +362,7 @@ interface NotificationSettings {
     notifySubscriptionPastDue: boolean;
     notifySubscriptionRenewed: boolean;
     notifySubscriptionUncanceled: boolean;
-    notifySubscriptionUpdated: boolean;
+    notifySubscriptionPlanChanged: boolean;
     notifyChargeback: boolean;
 }
 /**
@@ -371,7 +373,7 @@ interface NotificationSettings {
  * endpoint if included. Payout result notifications are platform-managed and always
  * delivered — they have no toggle key. Use this type for any merchant-side update.
  */
-type MerchantWritableNotificationSettings = Pick<NotificationSettings, "notifyNewOrders" | "notifyNewSubscriptions" | "notifySubscriptionCanceled" | "notifySubscriptionEnded" | "notifySubscriptionPastDue" | "notifySubscriptionRenewed" | "notifySubscriptionUncanceled" | "notifySubscriptionUpdated" | "notifyChargeback">;
+type MerchantWritableNotificationSettings = Pick<NotificationSettings, "notifyNewOrders" | "notifyNewSubscriptions" | "notifySubscriptionCanceled" | "notifySubscriptionEnded" | "notifySubscriptionPastDue" | "notifySubscriptionRenewed" | "notifySubscriptionUncanceled" | "notifySubscriptionPlanChanged" | "notifyChargeback">;
 /**
  * Single-theme checkout page styling.
  * @see docs/api-reference/endpoints/stores/overview.mdx
@@ -1034,14 +1036,22 @@ declare enum WebhookEventType {
     OrderCompleted = "order.completed",
     /** Subscription first payment succeeded (newly activated) */
     SubscriptionActivated = "subscription.activated",
-    /** Subscription renewal payment succeeded */
+    /** Subscription payment succeeded — a pure payment event, carries no subscription period or status */
     SubscriptionPaymentSucceeded = "subscription.payment_succeeded",
+    /** Current billing period rolled forward (renewal) */
+    SubscriptionRenewed = "subscription.renewed",
+    /** Subscription recovered from past due (a retried charge succeeded) */
+    SubscriptionRecovered = "subscription.recovered",
+    /** Plan change took effect (upgrade/downgrade) */
+    SubscriptionPlanChanged = "subscription.plan_changed",
+    /** Plan change confirmed, takes effect next billing period */
+    SubscriptionPlanChangeScheduled = "subscription.plan_change_scheduled",
+    /** Plan change did not complete, the current plan stays in effect */
+    SubscriptionPlanChangeFailed = "subscription.plan_change_failed",
     /** Customer initiated cancellation (expires at end of current period) */
     SubscriptionCanceling = "subscription.canceling",
     /** Customer withdrew cancellation (subscription restored) */
     SubscriptionUncanceled = "subscription.uncanceled",
-    /** Subscription product changed (upgrade/downgrade) */
-    SubscriptionUpdated = "subscription.updated",
     /** Subscription fully terminated */
     SubscriptionCanceled = "subscription.canceled",
     /** Renewal payment failed (past due) */
@@ -1057,7 +1067,12 @@ declare enum WebhookEventType {
  */
 interface WebhookEventData {
     orderId: string;
-    /** Order status (e.g., "completed", "active", "canceling") */
+    /**
+     * Order status (e.g., "completed", "active", "canceling").
+     *
+     * Absent on `subscription.payment_succeeded` — that event describes one charge only.
+     * Read the subscription's status from the subscription events instead.
+     */
     orderStatus?: string;
     buyerEmail: string;
     /** Merchant-provided customer identity from checkout session */
@@ -1571,7 +1586,9 @@ declare class CustomerSession {
      *
      * @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)
      */
     cancelSubscription(params: CancelSubscriptionParams): Promise<CancelSubscriptionResult & {
         warnings?: Notice[];
@@ -1591,6 +1608,12 @@ declare class CustomerSession {
     /**
      * 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
      *
@@ -1766,8 +1789,14 @@ declare class OrdersResource {
     /**
      * 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

package/dist/index.js

@@ -541,7 +541,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");
@@ -563,6 +565,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
    *
@@ -761,8 +769,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
@@ -1503,9 +1517,13 @@ var WebhookEventType = /* @__PURE__ */ ((WebhookEventType2) => {
   WebhookEventType2["OrderCompleted"] = "order.completed";
   WebhookEventType2["SubscriptionActivated"] = "subscription.activated";
   WebhookEventType2["SubscriptionPaymentSucceeded"] = "subscription.payment_succeeded";
+  WebhookEventType2["SubscriptionRenewed"] = "subscription.renewed";
+  WebhookEventType2["SubscriptionRecovered"] = "subscription.recovered";
+  WebhookEventType2["SubscriptionPlanChanged"] = "subscription.plan_changed";
+  WebhookEventType2["SubscriptionPlanChangeScheduled"] = "subscription.plan_change_scheduled";
+  WebhookEventType2["SubscriptionPlanChangeFailed"] = "subscription.plan_change_failed";
   WebhookEventType2["SubscriptionCanceling"] = "subscription.canceling";
   WebhookEventType2["SubscriptionUncanceled"] = "subscription.uncanceled";
-  WebhookEventType2["SubscriptionUpdated"] = "subscription.updated";
   WebhookEventType2["SubscriptionCanceled"] = "subscription.canceled";
   WebhookEventType2["SubscriptionPastDue"] = "subscription.past_due";
   WebhookEventType2["RefundSucceeded"] = "refund.succeeded";