@waffo/pancake-ts 0.18.0 → 0.19.1

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
@@ -505,12 +505,18 @@ interface UpdateRoleResult {
  * @example
  * // JPY ¥1000
  * { amount: "1000", taxCategory: "software" }
+ *
+ * @example
+ * // USD $9.99 with a $1.00 trial period (subscription products only)
+ * { amount: "9.99", taxCategory: "saas", trialAmount: "1.00" }
  */
 interface PriceInfo {
     /** Price amount as display string (e.g., "9.99" for USD, "1000" for JPY) */
     amount: string;
     /** Tax category */
     taxCategory: TaxCategory;
+    /** Trial period price as display string; requires `metadata.trialDays` and must be lower than `amount` */
+    trialAmount?: string;
 }
 /**
  * Multi-currency prices (keyed by ISO 4217 currency code).
@@ -757,6 +763,17 @@ type CashierLanguage = "en" | "pt-BR" | "es-MX" | "id-ID" | "vi-VN" | "ru-RU" |
  * Currencies outside this matrix cannot be charged at all — checkout session creation is rejected with a 400.
  */
 type PaymentMethod = "card" | "applepay" | "googlepay" | "wechat";
+/**
+ * Session-level price override, accepted with API Key authentication only.
+ * For subscription products it replaces the regular period price; the trial price comes from the locked product version.
+ * @see docs/api-reference/endpoints/orders/create-checkout-session.mdx
+ */
+interface PriceSnapshot {
+    /** Price amount as display string (e.g., "9.99" for USD, "1000" for JPY) */
+    amount: string;
+    /** Tax category */
+    taxCategory: TaxCategory;
+}
 /**
  * Parameters for creating a checkout session.
  * @see docs/api-reference/endpoints/orders/create-checkout-session.mdx
@@ -767,7 +784,7 @@ interface CreateCheckoutSessionParams {
     /** Currency code (ISO 4217) */
     currency: string;
     /** Optional price snapshot override (reads from DB if omitted) */
-    priceSnapshot?: PriceInfo;
+    priceSnapshot?: PriceSnapshot;
     /** Trial toggle override (subscription only) */
     withTrial?: boolean;
     /** Pre-filled customer email */
@@ -1554,7 +1571,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[];
@@ -1574,6 +1593,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
      *
@@ -1749,8 +1774,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
@@ -2339,4 +2370,4 @@ declare class WaffoPancakeError extends Error {
  */
 declare function verifyWebhook<T = Record<string, unknown>>(payload: string, signatureHeader: string | undefined | null, options?: VerifyWebhookOptions): WebhookEvent<T>;
 
-export { type AddMerchantParams, type AddMerchantResult, type AddWebhookParams, type AnonymousCheckoutParams, type ApiError, type AuthenticatedCheckoutParams, type AuthenticatedCheckoutResult, type BillingDetail, BillingPeriod, type CancelOnetimeOrderParams, type CancelOnetimeOrderResult, type CancelSubscriptionParams, type CancelSubscriptionResult, type CashierLanguage, type CheckoutSessionResult, type CheckoutSettings, type CheckoutThemeSettings, type CreateCheckoutSessionParams, type CreateOnetimeProductParams, type CreateRefundTicketParams, type CreateStoreParams, type CreateSubscriptionProductGroupParams, type CreateSubscriptionProductParams, type CustomerSessionOptions, type DeleteStoreParams, type DeleteSubscriptionProductGroupParams, EntityStatus, type Envelope, Environment, ErrorLayer, type GraphQLParams, type GraphQLResponse, type GroupRules, type IssueSessionTokenParams, type MediaItem, MediaType, type MerchantWritableNotificationSettings, type Notice, type NotificationSettings, OnetimeOrderStatus, type OnetimeProductDetail, type PaymentMethod, PaymentStatus, type PostResult, type PriceInfo, type Prices, ProductVersionStatus, type PublishOnetimeProductParams, type PublishSubscriptionProductGroupParams, type PublishSubscriptionProductParams, type ReactivateSubscriptionParams, type ReactivateSubscriptionResult, RefundStatus, type RefundTicket, RefundTicketStatus, type RefundTicketVersionData, type RemoveMerchantParams, type RemoveMerchantResult, type RemoveWebhookParams, type RequestedAmount, type ResubmitRefundTicketParams, ScanAction, ScanPolicyCategory, type ScanPromptParams, ScanReasonCode, type ScanResult, ScanSemanticMode, ScanSemanticStatus, type SessionToken, type Store, StoreRole, type StoreWebhook, SubscriptionOrderStatus, type SubscriptionProductDetail, type SubscriptionProductGroup, TaxCategory, type UpdateOnetimeProductParams, type UpdateOnetimeStatusParams, type UpdateRoleParams, type UpdateRoleResult, type UpdateStoreParams, type UpdateSubscriptionProductGroupParams, type UpdateSubscriptionProductParams, type UpdateSubscriptionStatusParams, type UpdateWebhookParams, type VerifyWebhookOptions, WaffoPancake, type WaffoPancakeConfig, WaffoPancakeError, type WebhookChannel, type WebhookEvent, type WebhookEventData, WebhookEventType, type WebhookPublicKeys, verifyWebhook };
+export { type AddMerchantParams, type AddMerchantResult, type AddWebhookParams, type AnonymousCheckoutParams, type ApiError, type AuthenticatedCheckoutParams, type AuthenticatedCheckoutResult, type BillingDetail, BillingPeriod, type CancelOnetimeOrderParams, type CancelOnetimeOrderResult, type CancelSubscriptionParams, type CancelSubscriptionResult, type CashierLanguage, type CheckoutSessionResult, type CheckoutSettings, type CheckoutThemeSettings, type CreateCheckoutSessionParams, type CreateOnetimeProductParams, type CreateRefundTicketParams, type CreateStoreParams, type CreateSubscriptionProductGroupParams, type CreateSubscriptionProductParams, type CustomerSessionOptions, type DeleteStoreParams, type DeleteSubscriptionProductGroupParams, EntityStatus, type Envelope, Environment, ErrorLayer, type GraphQLParams, type GraphQLResponse, type GroupRules, type IssueSessionTokenParams, type MediaItem, MediaType, type MerchantWritableNotificationSettings, type Notice, type NotificationSettings, OnetimeOrderStatus, type OnetimeProductDetail, type PaymentMethod, PaymentStatus, type PostResult, type PriceInfo, type PriceSnapshot, type Prices, ProductVersionStatus, type PublishOnetimeProductParams, type PublishSubscriptionProductGroupParams, type PublishSubscriptionProductParams, type ReactivateSubscriptionParams, type ReactivateSubscriptionResult, RefundStatus, type RefundTicket, RefundTicketStatus, type RefundTicketVersionData, type RemoveMerchantParams, type RemoveMerchantResult, type RemoveWebhookParams, type RequestedAmount, type ResubmitRefundTicketParams, ScanAction, ScanPolicyCategory, type ScanPromptParams, ScanReasonCode, type ScanResult, ScanSemanticMode, ScanSemanticStatus, type SessionToken, type Store, StoreRole, type StoreWebhook, SubscriptionOrderStatus, type SubscriptionProductDetail, type SubscriptionProductGroup, TaxCategory, type UpdateOnetimeProductParams, type UpdateOnetimeStatusParams, type UpdateRoleParams, type UpdateRoleResult, type UpdateStoreParams, type UpdateSubscriptionProductGroupParams, type UpdateSubscriptionProductParams, type UpdateSubscriptionStatusParams, type UpdateWebhookParams, type VerifyWebhookOptions, WaffoPancake, type WaffoPancakeConfig, WaffoPancakeError, type WebhookChannel, type WebhookEvent, type WebhookEventData, WebhookEventType, type WebhookPublicKeys, verifyWebhook };

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
@@ -505,12 +505,18 @@ interface UpdateRoleResult {
  * @example
  * // JPY ¥1000
  * { amount: "1000", taxCategory: "software" }
+ *
+ * @example
+ * // USD $9.99 with a $1.00 trial period (subscription products only)
+ * { amount: "9.99", taxCategory: "saas", trialAmount: "1.00" }
  */
 interface PriceInfo {
     /** Price amount as display string (e.g., "9.99" for USD, "1000" for JPY) */
     amount: string;
     /** Tax category */
     taxCategory: TaxCategory;
+    /** Trial period price as display string; requires `metadata.trialDays` and must be lower than `amount` */
+    trialAmount?: string;
 }
 /**
  * Multi-currency prices (keyed by ISO 4217 currency code).
@@ -757,6 +763,17 @@ type CashierLanguage = "en" | "pt-BR" | "es-MX" | "id-ID" | "vi-VN" | "ru-RU" |
  * Currencies outside this matrix cannot be charged at all — checkout session creation is rejected with a 400.
  */
 type PaymentMethod = "card" | "applepay" | "googlepay" | "wechat";
+/**
+ * Session-level price override, accepted with API Key authentication only.
+ * For subscription products it replaces the regular period price; the trial price comes from the locked product version.
+ * @see docs/api-reference/endpoints/orders/create-checkout-session.mdx
+ */
+interface PriceSnapshot {
+    /** Price amount as display string (e.g., "9.99" for USD, "1000" for JPY) */
+    amount: string;
+    /** Tax category */
+    taxCategory: TaxCategory;
+}
 /**
  * Parameters for creating a checkout session.
  * @see docs/api-reference/endpoints/orders/create-checkout-session.mdx
@@ -767,7 +784,7 @@ interface CreateCheckoutSessionParams {
     /** Currency code (ISO 4217) */
     currency: string;
     /** Optional price snapshot override (reads from DB if omitted) */
-    priceSnapshot?: PriceInfo;
+    priceSnapshot?: PriceSnapshot;
     /** Trial toggle override (subscription only) */
     withTrial?: boolean;
     /** Pre-filled customer email */
@@ -1554,7 +1571,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[];
@@ -1574,6 +1593,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
      *
@@ -1749,8 +1774,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
@@ -2339,4 +2370,4 @@ declare class WaffoPancakeError extends Error {
  */
 declare function verifyWebhook<T = Record<string, unknown>>(payload: string, signatureHeader: string | undefined | null, options?: VerifyWebhookOptions): WebhookEvent<T>;
 
-export { type AddMerchantParams, type AddMerchantResult, type AddWebhookParams, type AnonymousCheckoutParams, type ApiError, type AuthenticatedCheckoutParams, type AuthenticatedCheckoutResult, type BillingDetail, BillingPeriod, type CancelOnetimeOrderParams, type CancelOnetimeOrderResult, type CancelSubscriptionParams, type CancelSubscriptionResult, type CashierLanguage, type CheckoutSessionResult, type CheckoutSettings, type CheckoutThemeSettings, type CreateCheckoutSessionParams, type CreateOnetimeProductParams, type CreateRefundTicketParams, type CreateStoreParams, type CreateSubscriptionProductGroupParams, type CreateSubscriptionProductParams, type CustomerSessionOptions, type DeleteStoreParams, type DeleteSubscriptionProductGroupParams, EntityStatus, type Envelope, Environment, ErrorLayer, type GraphQLParams, type GraphQLResponse, type GroupRules, type IssueSessionTokenParams, type MediaItem, MediaType, type MerchantWritableNotificationSettings, type Notice, type NotificationSettings, OnetimeOrderStatus, type OnetimeProductDetail, type PaymentMethod, PaymentStatus, type PostResult, type PriceInfo, type Prices, ProductVersionStatus, type PublishOnetimeProductParams, type PublishSubscriptionProductGroupParams, type PublishSubscriptionProductParams, type ReactivateSubscriptionParams, type ReactivateSubscriptionResult, RefundStatus, type RefundTicket, RefundTicketStatus, type RefundTicketVersionData, type RemoveMerchantParams, type RemoveMerchantResult, type RemoveWebhookParams, type RequestedAmount, type ResubmitRefundTicketParams, ScanAction, ScanPolicyCategory, type ScanPromptParams, ScanReasonCode, type ScanResult, ScanSemanticMode, ScanSemanticStatus, type SessionToken, type Store, StoreRole, type StoreWebhook, SubscriptionOrderStatus, type SubscriptionProductDetail, type SubscriptionProductGroup, TaxCategory, type UpdateOnetimeProductParams, type UpdateOnetimeStatusParams, type UpdateRoleParams, type UpdateRoleResult, type UpdateStoreParams, type UpdateSubscriptionProductGroupParams, type UpdateSubscriptionProductParams, type UpdateSubscriptionStatusParams, type UpdateWebhookParams, type VerifyWebhookOptions, WaffoPancake, type WaffoPancakeConfig, WaffoPancakeError, type WebhookChannel, type WebhookEvent, type WebhookEventData, WebhookEventType, type WebhookPublicKeys, verifyWebhook };
+export { type AddMerchantParams, type AddMerchantResult, type AddWebhookParams, type AnonymousCheckoutParams, type ApiError, type AuthenticatedCheckoutParams, type AuthenticatedCheckoutResult, type BillingDetail, BillingPeriod, type CancelOnetimeOrderParams, type CancelOnetimeOrderResult, type CancelSubscriptionParams, type CancelSubscriptionResult, type CashierLanguage, type CheckoutSessionResult, type CheckoutSettings, type CheckoutThemeSettings, type CreateCheckoutSessionParams, type CreateOnetimeProductParams, type CreateRefundTicketParams, type CreateStoreParams, type CreateSubscriptionProductGroupParams, type CreateSubscriptionProductParams, type CustomerSessionOptions, type DeleteStoreParams, type DeleteSubscriptionProductGroupParams, EntityStatus, type Envelope, Environment, ErrorLayer, type GraphQLParams, type GraphQLResponse, type GroupRules, type IssueSessionTokenParams, type MediaItem, MediaType, type MerchantWritableNotificationSettings, type Notice, type NotificationSettings, OnetimeOrderStatus, type OnetimeProductDetail, type PaymentMethod, PaymentStatus, type PostResult, type PriceInfo, type PriceSnapshot, type Prices, ProductVersionStatus, type PublishOnetimeProductParams, type PublishSubscriptionProductGroupParams, type PublishSubscriptionProductParams, type ReactivateSubscriptionParams, type ReactivateSubscriptionResult, RefundStatus, type RefundTicket, RefundTicketStatus, type RefundTicketVersionData, type RemoveMerchantParams, type RemoveMerchantResult, type RemoveWebhookParams, type RequestedAmount, type ResubmitRefundTicketParams, ScanAction, ScanPolicyCategory, type ScanPromptParams, ScanReasonCode, type ScanResult, ScanSemanticMode, ScanSemanticStatus, type SessionToken, type Store, StoreRole, type StoreWebhook, SubscriptionOrderStatus, type SubscriptionProductDetail, type SubscriptionProductGroup, TaxCategory, type UpdateOnetimeProductParams, type UpdateOnetimeStatusParams, type UpdateRoleParams, type UpdateRoleResult, type UpdateStoreParams, type UpdateSubscriptionProductGroupParams, type UpdateSubscriptionProductParams, type UpdateSubscriptionStatusParams, type UpdateWebhookParams, type VerifyWebhookOptions, WaffoPancake, type WaffoPancakeConfig, WaffoPancakeError, type WebhookChannel, type WebhookEvent, type WebhookEventData, WebhookEventType, type WebhookPublicKeys, verifyWebhook };

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