@waffo/waffo-node 2.3.0 → 2.3.2

package/README.md

@@ -1,6 +1,6 @@
 # Waffo Node.js SDK
 
-<!-- Synced with waffo-sdk/README.md @ commit 48b44fc -->
+<!-- Synced with waffo-sdk/README.md @ commit ee83ead -->
 
 **English** | [中文](README_CN.md)
 
@@ -804,6 +804,113 @@ app.post('/webhook', express.raw({ type: 'application/json' }), async (req, res)
 > - `SUBSCRIPTION_STATUS_NOTIFICATION`: When new subscription status changes to `ACTIVE`
 > - `PAYMENT_NOTIFICATION`: If upgrade requires additional payment (price difference)
 
+### Webhook Notification Payload Examples
+
+The following examples show the actual payload structure for each notification type.
+
+#### PAYMENT_NOTIFICATION
+
+```json
+{
+  "eventType": "PAYMENT_NOTIFICATION",
+  "result": {
+    "acquiringOrderId": "A2026xxxxxxxxxxxxxxxxxxxx",
+    "orderStatus": "PAY_SUCCESS",
+    "orderAmount": "109.00",
+    "orderCurrency": "USD",
+    "finalDealAmount": "109.00",
+    "userCurrency": "USD",
+    "orderDescription": "Sample Product",
+    "orderRequestedAt": "2026-02-28T10:05:58.000Z",
+    "orderCompletedAt": "2026-02-28T10:06:10.000Z",
+    "orderUpdatedAt": "2026-02-28T10:06:10.000Z",
+    "refundExpiryAt": "2026-08-26T23:59:59.999Z",
+    "userInfo": {
+      "userId": "user@example.com",
+      "userEmail": "user@example.com"
+    },
+    "merchantInfo": {
+      "merchantId": "YOUR_MERCHANT_ID"
+    },
+    "goodsInfo": {
+      "goodsId": "goods_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+      "goodsName": "Sample Product"
+    },
+    "addressInfo": {},
+    "paymentInfo": {
+      "productName": "SUBSCRIPTION",
+      "payMethodType": "CREDITCARD",
+      "payMethodName": "CC_VISA",
+      "payMethodProperties": "{\"cardToken\":\"CARD_TOKEN_XXXXXXXXXXXXXXXXXXXX\",\"cardTransactionType\":\"CIT\"}",
+      "payMethodResponse": "{\"maskCardData\":\"XXXX42****XX4242\"}"
+    },
+    "subscriptionInfo": {
+      "subscriptionId": "SC2026xxxxxxxxxxxxxxxxxxxxxxxxxx",
+      "subscriptionRequest": "sub_req_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+      "merchantRequest": "sub_req_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+      "period": "1"
+    },
+    "cancelRedirectUrl": "https://YOUR_DOMAIN/checkout/YOUR_CHECKOUT_ID"
+  }
+}
+```
+
+#### SUBSCRIPTION_STATUS_NOTIFICATION / SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION
+
+These two notification types share the same payload structure:
+
+```json
+{
+  "eventType": "SUBSCRIPTION_STATUS_NOTIFICATION",
+  "result": {
+    "subscriptionId": "SC2026xxxxxxxxxxxxxxxxxxxxxxxxxx",
+    "subscriptionRequest": "sub_req_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+    "merchantSubscriptionId": "sub_req_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+    "subscriptionStatus": "ACTIVE",
+    "currency": "USD",
+    "userCurrency": "USD",
+    "amount": "109.00",
+    "requestedAt": "2026-02-28T10:05:58.000Z",
+    "updatedAt": "2026-02-28T10:06:10.000Z",
+    "userInfo": {
+      "userId": "user@example.com",
+      "userEmail": "user@example.com"
+    },
+    "merchantInfo": {
+      "merchantId": "YOUR_MERCHANT_ID"
+    },
+    "goodsInfo": {
+      "goodsId": "goods_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+      "goodsName": "Sample Product"
+    },
+    "productInfo": {
+      "periodType": "MONTHLY",
+      "periodInterval": "1",
+      "currentPeriod": "1",
+      "startDateTime": "2026-02-28T10:06:10.000Z",
+      "nextPaymentDateTime": "2026-03-28T10:06:10.000Z",
+      "description": "Sample Product"
+    },
+    "paymentInfo": {
+      "productName": "SUBSCRIPTION",
+      "payMethodType": "CREDITCARD",
+      "payMethodName": "CC_VISA",
+      "payMethodProperties": "{}"
+    },
+    "paymentDetails": [
+      {
+        "period": "1",
+        "acquiringOrderId": "A2026xxxxxxxxxxxxxxxxxxxx",
+        "orderAmount": "109.00",
+        "orderCurrency": "USD",
+        "orderStatus": "PAY_SUCCESS",
+        "orderUpdatedAt": "2026-02-28T10:06:10.000Z"
+      }
+    ]
+  }
+}
+```
+
 ## Payment Method Types
 
 ### payMethodType Reference

package/dist/index.d.mts

@@ -735,7 +735,8 @@ declare enum WebhookEventType {
     PAYMENT_NOTIFICATION = "PAYMENT_NOTIFICATION",
     REFUND_NOTIFICATION = "REFUND_NOTIFICATION",
     SUBSCRIPTION_STATUS_NOTIFICATION = "SUBSCRIPTION_STATUS_NOTIFICATION",
-    SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION = "SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION"
+    SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION = "SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION",
+    SUBSCRIPTION_CHANGE_NOTIFICATION = "SUBSCRIPTION_CHANGE_NOTIFICATION"
 }
 /**
  * Result of webhook handling.
@@ -853,6 +854,33 @@ interface SubscriptionNotificationResult {
     paymentDetails?: Record<string, unknown>[];
     [key: string]: unknown;
 }
+/**
+ * Subscription change notification result payload.
+ * Triggered when a subscription change (upgrade/downgrade) reaches final status (SUCCESS or CLOSED).
+ */
+interface SubscriptionChangeNotificationResult {
+    subscriptionRequest?: string;
+    originSubscriptionRequest?: string;
+    merchantSubscriptionId?: string;
+    subscriptionId?: string;
+    /** Final status: SUCCESS or CLOSED */
+    subscriptionChangeStatus?: string;
+    subscriptionAction?: string;
+    remainingAmount?: string;
+    currency?: string;
+    userCurrency?: string;
+    requestedAt?: string;
+    subscriptionManagementUrl?: string;
+    extendInfo?: string;
+    orderExpiredAt?: string;
+    productInfoList?: Record<string, unknown>[];
+    merchantInfo?: Record<string, unknown>;
+    userInfo?: Record<string, unknown>;
+    goodsInfo?: Record<string, unknown>;
+    addressInfo?: Record<string, unknown>;
+    paymentInfo?: Record<string, unknown>;
+    [key: string]: unknown;
+}
 /**
  * Payment notification from Waffo.
  */
@@ -885,11 +913,20 @@ interface SubscriptionPeriodChangedNotification extends BaseNotification {
     result?: SubscriptionNotificationResult;
     [key: string]: unknown;
 }
+/**
+ * Subscription change notification from Waffo.
+ */
+interface SubscriptionChangeNotification extends BaseNotification {
+    eventType: 'SUBSCRIPTION_CHANGE_NOTIFICATION';
+    result?: SubscriptionChangeNotificationResult;
+    [key: string]: unknown;
+}
 type PaymentHandler = (notification: PaymentNotification) => void | Promise<void>;
 type RefundHandler = (notification: RefundNotification) => void | Promise<void>;
 type SubscriptionStatusHandler = (notification: SubscriptionStatusNotification) => void | Promise<void>;
 type SubscriptionPaymentHandler = (notification: SubscriptionStatusNotification) => void | Promise<void>;
 type SubscriptionPeriodChangedHandler = (notification: SubscriptionPeriodChangedNotification) => void | Promise<void>;
+type SubscriptionChangeHandler = (notification: SubscriptionChangeNotification) => void | Promise<void>;
 /**
  * Webhook handler for processing Waffo webhook notifications.
  *
@@ -924,6 +961,7 @@ declare class WebhookHandler {
     private subscriptionStatusHandler?;
     private subscriptionPaymentHandler?;
     private subscriptionPeriodChangedHandler?;
+    private subscriptionChangeHandler?;
     constructor(config: WaffoConfig);
     /**
      * Registers a handler for payment notifications.
@@ -946,6 +984,10 @@ declare class WebhookHandler {
      * Registers a handler for subscription period changed notifications.
      */
     onSubscriptionPeriodChanged(handler: SubscriptionPeriodChangedHandler): this;
+    /**
+     * Registers a handler for subscription change notifications.
+     */
+    onSubscriptionChange(handler: SubscriptionChangeHandler): this;
     /**
      * Processes a webhook notification.
      *
@@ -972,7 +1014,7 @@ declare class WebhookHandler {
     /**
      * Builds a failed response with signature.
      */
-    buildFailedResponse(message: string): {
+    buildFailedResponse(_message: string): {
         body: string;
         signature: string;
     };

package/dist/index.d.ts

@@ -735,7 +735,8 @@ declare enum WebhookEventType {
     PAYMENT_NOTIFICATION = "PAYMENT_NOTIFICATION",
     REFUND_NOTIFICATION = "REFUND_NOTIFICATION",
     SUBSCRIPTION_STATUS_NOTIFICATION = "SUBSCRIPTION_STATUS_NOTIFICATION",
-    SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION = "SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION"
+    SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION = "SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION",
+    SUBSCRIPTION_CHANGE_NOTIFICATION = "SUBSCRIPTION_CHANGE_NOTIFICATION"
 }
 /**
  * Result of webhook handling.
@@ -853,6 +854,33 @@ interface SubscriptionNotificationResult {
     paymentDetails?: Record<string, unknown>[];
     [key: string]: unknown;
 }
+/**
+ * Subscription change notification result payload.
+ * Triggered when a subscription change (upgrade/downgrade) reaches final status (SUCCESS or CLOSED).
+ */
+interface SubscriptionChangeNotificationResult {
+    subscriptionRequest?: string;
+    originSubscriptionRequest?: string;
+    merchantSubscriptionId?: string;
+    subscriptionId?: string;
+    /** Final status: SUCCESS or CLOSED */
+    subscriptionChangeStatus?: string;
+    subscriptionAction?: string;
+    remainingAmount?: string;
+    currency?: string;
+    userCurrency?: string;
+    requestedAt?: string;
+    subscriptionManagementUrl?: string;
+    extendInfo?: string;
+    orderExpiredAt?: string;
+    productInfoList?: Record<string, unknown>[];
+    merchantInfo?: Record<string, unknown>;
+    userInfo?: Record<string, unknown>;
+    goodsInfo?: Record<string, unknown>;
+    addressInfo?: Record<string, unknown>;
+    paymentInfo?: Record<string, unknown>;
+    [key: string]: unknown;
+}
 /**
  * Payment notification from Waffo.
  */
@@ -885,11 +913,20 @@ interface SubscriptionPeriodChangedNotification extends BaseNotification {
     result?: SubscriptionNotificationResult;
     [key: string]: unknown;
 }
+/**
+ * Subscription change notification from Waffo.
+ */
+interface SubscriptionChangeNotification extends BaseNotification {
+    eventType: 'SUBSCRIPTION_CHANGE_NOTIFICATION';
+    result?: SubscriptionChangeNotificationResult;
+    [key: string]: unknown;
+}
 type PaymentHandler = (notification: PaymentNotification) => void | Promise<void>;
 type RefundHandler = (notification: RefundNotification) => void | Promise<void>;
 type SubscriptionStatusHandler = (notification: SubscriptionStatusNotification) => void | Promise<void>;
 type SubscriptionPaymentHandler = (notification: SubscriptionStatusNotification) => void | Promise<void>;
 type SubscriptionPeriodChangedHandler = (notification: SubscriptionPeriodChangedNotification) => void | Promise<void>;
+type SubscriptionChangeHandler = (notification: SubscriptionChangeNotification) => void | Promise<void>;
 /**
  * Webhook handler for processing Waffo webhook notifications.
  *
@@ -924,6 +961,7 @@ declare class WebhookHandler {
     private subscriptionStatusHandler?;
     private subscriptionPaymentHandler?;
     private subscriptionPeriodChangedHandler?;
+    private subscriptionChangeHandler?;
     constructor(config: WaffoConfig);
     /**
      * Registers a handler for payment notifications.
@@ -946,6 +984,10 @@ declare class WebhookHandler {
      * Registers a handler for subscription period changed notifications.
      */
     onSubscriptionPeriodChanged(handler: SubscriptionPeriodChangedHandler): this;
+    /**
+     * Registers a handler for subscription change notifications.
+     */
+    onSubscriptionChange(handler: SubscriptionChangeHandler): this;
     /**
      * Processes a webhook notification.
      *
@@ -972,7 +1014,7 @@ declare class WebhookHandler {
     /**
      * Builds a failed response with signature.
      */
-    buildFailedResponse(message: string): {
+    buildFailedResponse(_message: string): {
         body: string;
         signature: string;
     };

package/dist/index.js

@@ -463,7 +463,7 @@ var HEADER_SDK_VERSION = "x-sdk-version";
 var HEADER_CONTENT_TYPE = "content-type";
 var CONTENT_TYPE_JSON = "application/json";
 var API_VERSION = "1.0.0";
-var SDK_VERSION = "waffo-node/2.3.0";
+var SDK_VERSION = "waffo-node/2.3.2";
 var WaffoHttpClient = class {
   baseUrl;
   apiKey;
@@ -624,6 +624,7 @@ var WebhookEventType = /* @__PURE__ */ ((WebhookEventType2) => {
   WebhookEventType2["REFUND_NOTIFICATION"] = "REFUND_NOTIFICATION";
   WebhookEventType2["SUBSCRIPTION_STATUS_NOTIFICATION"] = "SUBSCRIPTION_STATUS_NOTIFICATION";
   WebhookEventType2["SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION"] = "SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION";
+  WebhookEventType2["SUBSCRIPTION_CHANGE_NOTIFICATION"] = "SUBSCRIPTION_CHANGE_NOTIFICATION";
   return WebhookEventType2;
 })(WebhookEventType || {});
 var WebhookHandler = class {
@@ -635,6 +636,7 @@ var WebhookHandler = class {
   subscriptionStatusHandler;
   subscriptionPaymentHandler;
   subscriptionPeriodChangedHandler;
+  subscriptionChangeHandler;
   constructor(config) {
     this.waffoPublicKey = config.waffoPublicKey;
     this.privateKey = config.privateKey;
@@ -676,6 +678,13 @@ var WebhookHandler = class {
     this.subscriptionPeriodChangedHandler = handler;
     return this;
   }
+  /**
+   * Registers a handler for subscription change notifications.
+   */
+  onSubscriptionChange(handler) {
+    this.subscriptionChangeHandler = handler;
+    return this;
+  }
   /**
    * Processes a webhook notification.
    *
@@ -719,6 +728,11 @@ var WebhookHandler = class {
             await this.subscriptionPeriodChangedHandler(parsed);
           }
           break;
+        case "SUBSCRIPTION_CHANGE_NOTIFICATION" /* SUBSCRIPTION_CHANGE_NOTIFICATION */:
+          if (this.subscriptionChangeHandler) {
+            await this.subscriptionChangeHandler(parsed);
+          }
+          break;
         default:
           this.logger?.warn(`Unknown webhook event type: ${eventType}`);
           return this.createFailedResult(`Unknown event type: ${eventType}`);
@@ -745,15 +759,15 @@ var WebhookHandler = class {
    * Builds a success response with signature.
    */
   buildSuccessResponse() {
-    const body = JSON.stringify({ status: "success" });
+    const body = JSON.stringify({ message: "success" });
     const signature = RsaUtils.sign(body, this.privateKey);
     return { body, signature };
   }
   /**
    * Builds a failed response with signature.
    */
-  buildFailedResponse(message) {
-    const body = JSON.stringify({ status: "failed", message });
+  buildFailedResponse(_message) {
+    const body = JSON.stringify({ message: "failed" });
     const signature = RsaUtils.sign(body, this.privateKey);
     return { body, signature };
   }