@waffo/waffo-node 3.1.0 → 3.2.0

package/README.md

@@ -1,6 +1,6 @@
 # Waffo Node.js SDK
 
-<!-- Synced with waffo-sdk/README.md @ commit 53f0d42 -->
+<!-- Synced with waffo-sdk/README.md @ commit 9405bd4 -->
 
 **English** | [中文](README_CN.md)
 
@@ -58,6 +58,7 @@ Official Node.js/TypeScript SDK for [Waffo Payment Platform](https://www.waffo.c
 - [Support](#support)
 - [License](#license)
 - [Development & Testing](#development-testing)
+- [Open Business Values and Custom Events](#open-business-values-and-custom-events)
 
 ## Requirements
 
@@ -1208,6 +1209,60 @@ const signature = RsaUtils.sign(data, privateKey);
 const isValid = RsaUtils.verify(data, signature, publicKey);
 ```
 
+<!-- sdk-sync:start:Open%20Business%20Values%20and%20Custom%20Events -->
+## Open Business Values and Custom Events
+
+Business fields accept arbitrary strings and preserve their original value, including new statuses, currencies, products, periods and actions. The known constants are convenience values. A parsed response or a successful API code does not establish payment success; compare the relevant business status explicitly.
+
+### Read protocol values without changing existing calls
+
+These offline examples show the real SDK model/accessor APIs. `FUTURE_STATUS` is synthetic and does not declare server support. Parsing or API code success does not establish business success.
+
+```typescript
+// Existing aliases/getData stay compatible; getData can contain future strings.
+// getOpenData/OpenBusinessValues opt into open strings: handle a default branch.
+// create/change preserve required fields; concrete eventType types stay fixed.
+import { ApiResponse, type InquirySubscriptionData } from '@waffo/waffo-node';
+
+const source = JSON.parse('{"subscriptionStatus":"ACTIVE","paymentDetails":[{"orderStatus":"INIT"}]}');
+const response = ApiResponse.success<InquirySubscriptionData>(source);
+const data = response.getOpenData();
+console.log(data?.subscriptionStatus, data?.paymentDetails?.[0]?.orderStatus);
+if (data?.subscriptionStatus === 'FUTURE_STATUS') {
+  console.warn('Unsupported business status:', data.subscriptionStatus);
+}
+```
+
+`WebhookEventType` and concrete built-in notification types remain the known event catalogue. Unknown events return a signed failure unless your application registers that exact name. Register before serving callbacks; custom registrations are per instance, case-sensitive, and a later registration replaces the same name. Built-in names use their dedicated methods. Blank names and invalid callbacks/configuration fail at registration with `S0006`; PHP rejects non-callable arguments with its native `TypeError`.
+
+Java, Python and PHP custom callbacks must complete synchronously; PHP Promise/generator callbacks are unsupported. Python rejects async functions at registration and returns failure for an unexpected awaitable result. Node.js explicitly supports Promise callbacks.
+
+The examples below take the **raw, unmodified UTF-8 body file** as their first argument and `WAFFO_WEBHOOK_SIGNATURE` as the request signature. Set `WAFFO_API_KEY`, `WAFFO_PRIVATE_KEY`, `WAFFO_PUBLIC_KEY` and Java/Python's `WAFFO_MERCHANT_ID` using your authorized configuration. They print the signed response header/body; in your HTTP adapter send those bytes with HTTP 200 and the `X-SIGNATURE` header. `EXAMPLE_CUSTOM_NOTIFICATION` is an offline example name: replace it and implement your business action against the event's real contract. Reject/throw/return an error if processing fails; Node.js awaits the callback, and Go converts callback errors or panics into failure responses.
+
+```typescript
+import { readFileSync } from 'node:fs';
+import { WebhookHandler, Environment } from '@waffo/waffo-node';
+
+async function main() {
+  const handler = new WebhookHandler({
+    apiKey: process.env.WAFFO_API_KEY!,
+    privateKey: process.env.WAFFO_PRIVATE_KEY!,
+    waffoPublicKey: process.env.WAFFO_PUBLIC_KEY!,
+    environment: Environment.SANDBOX,
+  }).onEvent('EXAMPLE_CUSTOM_NOTIFICATION', async notification => {
+    // Validate the event's documented fields and perform your business action here.
+    console.error('Handled custom event:', notification.eventType);
+  });
+  const body = readFileSync(process.argv[2], 'utf8');
+  const result = await handler.handleWebhook(body, process.env.WAFFO_WEBHOOK_SIGNATURE ?? '');
+  if (!result.success) console.error(result.error);
+  console.log('X-SIGNATURE: ' + result.responseSignature);
+  console.log(result.responseBody);
+}
+main().catch(error => { console.error(error); process.exitCode = 1; });
+```
+<!-- sdk-sync:end:Open%20Business%20Values%20and%20Custom%20Events -->
+
 ## Handling New API Fields (ExtraParams)
 
 When Waffo API adds new fields that are not yet defined in the SDK, you can use the ExtraParams feature to access these fields without waiting for an SDK update.

package/dist/index.d.mts

@@ -1607,6 +1607,7 @@ declare class WebhookHandler {
     private subscriptionPaymentHandler?;
     private subscriptionPeriodChangedHandler?;
     private subscriptionChangeHandler?;
+    private readonly customEventHandlers;
     constructor(config: WaffoConfig);
     /**
      * Registers a handler for payment notifications.
@@ -1633,6 +1634,8 @@ declare class WebhookHandler {
      * Registers a handler for subscription change notifications.
      */
     onSubscriptionChange(handler: SubscriptionChangeHandler): this;
+    /** Registers an exact custom event name before receiving webhooks. Later registration replaces the same name. */
+    onEvent(eventType: string, handler: (notification: BaseNotification & Record<string, unknown>) => void | Promise<void>): this;
     /**
      * Processes a webhook notification.
      *
@@ -1667,6 +1670,11 @@ declare class WebhookHandler {
     private createFailedResult;
 }
 
+/** Optional view for JSON business data that preserves future protocol strings. */
+type OpenBusinessValues<T> = T extends string ? string : T extends object ? {
+    [K in keyof T]: K extends 'eventType' ? T[K] : OpenBusinessValues<T[K]>;
+} : T;
+
 /**
  * Generic API response wrapper.
  *
@@ -1717,6 +1725,8 @@ declare class ApiResponse<T> {
      * @returns The response data, or undefined if the response is an error
      */
     getData(): T | undefined;
+    /** Returns the same JSON data with business string literals opened to future values. */
+    getOpenData(): OpenBusinessValues<T> | undefined;
     /**
      * Gets the error message.
      *
@@ -1929,6 +1939,7 @@ declare class SubscriptionResource extends BaseResource {
      * @returns API response with subscription data
      * @throws WaffoUnknownStatusError for network errors
      */
+    create(params: OpenBusinessValues<CreateSubscriptionParams>, options?: RequestOptions): Promise<ApiResponse<CreateSubscriptionData>>;
     create(params: CreateSubscriptionParams, options?: RequestOptions): Promise<ApiResponse<CreateSubscriptionData>>;
     /**
      * Queries an existing subscription.
@@ -2010,6 +2021,7 @@ declare class SubscriptionResource extends BaseResource {
      * }
      * ```
      */
+    change(params: OpenBusinessValues<SubscriptionChangeParams>, options?: RequestOptions): Promise<ApiResponse<SubscriptionChangeData>>;
     change(params: SubscriptionChangeParams, options?: RequestOptions): Promise<ApiResponse<SubscriptionChangeData>>;
     /**
      * Queries the status of a subscription change.
@@ -2658,4 +2670,4 @@ declare const RsaUtils: {
     generateKeyPair: typeof generateKeyPair;
 };
 
-export { type AddressInfo, ApiResponse, type BaseNotification, type CancelOrderData, type CancelOrderParams, type CancelSubscriptionData, type CancelSubscriptionParams, type CaptureOrderData, type CaptureOrderParams, type CardInfo, type CreateOrderData, type CreateOrderParams, type CreateSubscriptionData, type CreateSubscriptionParams, Environment, EnvironmentBaseUrl, type FixedMaintenanceRule, type GoodsInfo, type HttpRequest, type HttpResponse, type HttpTransport, type InquiryMerchantConfigData, type InquiryMerchantConfigParams, type InquiryOrderData, type InquiryOrderParams, type InquiryPayMethodConfigData, type InquiryPayMethodConfigParams, type InquiryRefundData, type InquiryRefundParams, type InquirySubscriptionData, type InquirySubscriptionParams, type ManageSubscriptionData, type ManageSubscriptionParams, MerchantConfigResource, type MerchantInfo, OrderResource, type OrderStatus, PayMethodConfigResource, type PayMethodDetail, type PayMethodInfo, type PaymentInfo, type PaymentNotification, type PaymentNotificationResult, type PeriodType, type ProductInfo, type PromotionInfo, type RefundNotification, type RefundNotificationResult, type RefundOrderData, type RefundOrderParams, RefundResource, type RefundStatus$1 as RefundStatus, type RefundUserInfo, type RequestOptions, type RiskData, RsaUtils, type SubscriptionChangeData, type SubscriptionChangeInquiryData, type SubscriptionChangeInquiryParams, type SubscriptionChangeParams, type SubscriptionChangeProductInfo, type SubscriptionChangeStatus, type SubscriptionInfo, type SubscriptionManageAction, type SubscriptionMerchantInfo, type SubscriptionNotificationResult, type SubscriptionPaymentDetail, type SubscriptionPaymentInfo, type SubscriptionPeriodChangedNotification, type SubscriptionPromotionInfo, SubscriptionResource, type SubscriptionScheduledAmount, type SubscriptionStatus, type SubscriptionStatusNotification, type SubscriptionUpdateProductInfo, type SubscriptionUpdateTopupData, type SubscriptionUpdateTopupInfo, type SubscriptionUserInfo, type UpdateSubscriptionData, type UpdateSubscriptionParams, type UserInfo, Waffo, type WaffoConfig, WaffoConfigDefaults, WaffoError, WaffoErrorCode, WaffoHttpClient, type WaffoLogger, WaffoUnknownStatusError, type WalletInquiryData, type WalletInquiryParams, WalletResource, WebhookEventType, WebhookHandler, type WebhookResult, type X402Info };
+export { type AddressInfo, ApiResponse, type BaseNotification, type CancelOrderData, type CancelOrderParams, type CancelSubscriptionData, type CancelSubscriptionParams, type CaptureOrderData, type CaptureOrderParams, type CardInfo, type CreateOrderData, type CreateOrderParams, type CreateSubscriptionData, type CreateSubscriptionParams, Environment, EnvironmentBaseUrl, type FixedMaintenanceRule, type GoodsInfo, type HttpRequest, type HttpResponse, type HttpTransport, type InquiryMerchantConfigData, type InquiryMerchantConfigParams, type InquiryOrderData, type InquiryOrderParams, type InquiryPayMethodConfigData, type InquiryPayMethodConfigParams, type InquiryRefundData, type InquiryRefundParams, type InquirySubscriptionData, type InquirySubscriptionParams, type ManageSubscriptionData, type ManageSubscriptionParams, MerchantConfigResource, type MerchantInfo, type OpenBusinessValues, OrderResource, type OrderStatus, PayMethodConfigResource, type PayMethodDetail, type PayMethodInfo, type PaymentInfo, type PaymentNotification, type PaymentNotificationResult, type PeriodType, type ProductInfo, type PromotionInfo, type RefundNotification, type RefundNotificationResult, type RefundOrderData, type RefundOrderParams, RefundResource, type RefundStatus$1 as RefundStatus, type RefundUserInfo, type RequestOptions, type RiskData, RsaUtils, type SubscriptionChangeData, type SubscriptionChangeInquiryData, type SubscriptionChangeInquiryParams, type SubscriptionChangeParams, type SubscriptionChangeProductInfo, type SubscriptionChangeStatus, type SubscriptionInfo, type SubscriptionManageAction, type SubscriptionMerchantInfo, type SubscriptionNotificationResult, type SubscriptionPaymentDetail, type SubscriptionPaymentInfo, type SubscriptionPeriodChangedNotification, type SubscriptionPromotionInfo, SubscriptionResource, type SubscriptionScheduledAmount, type SubscriptionStatus, type SubscriptionStatusNotification, type SubscriptionUpdateProductInfo, type SubscriptionUpdateTopupData, type SubscriptionUpdateTopupInfo, type SubscriptionUserInfo, type UpdateSubscriptionData, type UpdateSubscriptionParams, type UserInfo, Waffo, type WaffoConfig, WaffoConfigDefaults, WaffoError, WaffoErrorCode, WaffoHttpClient, type WaffoLogger, WaffoUnknownStatusError, type WalletInquiryData, type WalletInquiryParams, WalletResource, WebhookEventType, WebhookHandler, type WebhookResult, type X402Info };

package/dist/index.d.ts

@@ -1607,6 +1607,7 @@ declare class WebhookHandler {
     private subscriptionPaymentHandler?;
     private subscriptionPeriodChangedHandler?;
     private subscriptionChangeHandler?;
+    private readonly customEventHandlers;
     constructor(config: WaffoConfig);
     /**
      * Registers a handler for payment notifications.
@@ -1633,6 +1634,8 @@ declare class WebhookHandler {
      * Registers a handler for subscription change notifications.
      */
     onSubscriptionChange(handler: SubscriptionChangeHandler): this;
+    /** Registers an exact custom event name before receiving webhooks. Later registration replaces the same name. */
+    onEvent(eventType: string, handler: (notification: BaseNotification & Record<string, unknown>) => void | Promise<void>): this;
     /**
      * Processes a webhook notification.
      *
@@ -1667,6 +1670,11 @@ declare class WebhookHandler {
     private createFailedResult;
 }
 
+/** Optional view for JSON business data that preserves future protocol strings. */
+type OpenBusinessValues<T> = T extends string ? string : T extends object ? {
+    [K in keyof T]: K extends 'eventType' ? T[K] : OpenBusinessValues<T[K]>;
+} : T;
+
 /**
  * Generic API response wrapper.
  *
@@ -1717,6 +1725,8 @@ declare class ApiResponse<T> {
      * @returns The response data, or undefined if the response is an error
      */
     getData(): T | undefined;
+    /** Returns the same JSON data with business string literals opened to future values. */
+    getOpenData(): OpenBusinessValues<T> | undefined;
     /**
      * Gets the error message.
      *
@@ -1929,6 +1939,7 @@ declare class SubscriptionResource extends BaseResource {
      * @returns API response with subscription data
      * @throws WaffoUnknownStatusError for network errors
      */
+    create(params: OpenBusinessValues<CreateSubscriptionParams>, options?: RequestOptions): Promise<ApiResponse<CreateSubscriptionData>>;
     create(params: CreateSubscriptionParams, options?: RequestOptions): Promise<ApiResponse<CreateSubscriptionData>>;
     /**
      * Queries an existing subscription.
@@ -2010,6 +2021,7 @@ declare class SubscriptionResource extends BaseResource {
      * }
      * ```
      */
+    change(params: OpenBusinessValues<SubscriptionChangeParams>, options?: RequestOptions): Promise<ApiResponse<SubscriptionChangeData>>;
     change(params: SubscriptionChangeParams, options?: RequestOptions): Promise<ApiResponse<SubscriptionChangeData>>;
     /**
      * Queries the status of a subscription change.
@@ -2658,4 +2670,4 @@ declare const RsaUtils: {
     generateKeyPair: typeof generateKeyPair;
 };
 
-export { type AddressInfo, ApiResponse, type BaseNotification, type CancelOrderData, type CancelOrderParams, type CancelSubscriptionData, type CancelSubscriptionParams, type CaptureOrderData, type CaptureOrderParams, type CardInfo, type CreateOrderData, type CreateOrderParams, type CreateSubscriptionData, type CreateSubscriptionParams, Environment, EnvironmentBaseUrl, type FixedMaintenanceRule, type GoodsInfo, type HttpRequest, type HttpResponse, type HttpTransport, type InquiryMerchantConfigData, type InquiryMerchantConfigParams, type InquiryOrderData, type InquiryOrderParams, type InquiryPayMethodConfigData, type InquiryPayMethodConfigParams, type InquiryRefundData, type InquiryRefundParams, type InquirySubscriptionData, type InquirySubscriptionParams, type ManageSubscriptionData, type ManageSubscriptionParams, MerchantConfigResource, type MerchantInfo, OrderResource, type OrderStatus, PayMethodConfigResource, type PayMethodDetail, type PayMethodInfo, type PaymentInfo, type PaymentNotification, type PaymentNotificationResult, type PeriodType, type ProductInfo, type PromotionInfo, type RefundNotification, type RefundNotificationResult, type RefundOrderData, type RefundOrderParams, RefundResource, type RefundStatus$1 as RefundStatus, type RefundUserInfo, type RequestOptions, type RiskData, RsaUtils, type SubscriptionChangeData, type SubscriptionChangeInquiryData, type SubscriptionChangeInquiryParams, type SubscriptionChangeParams, type SubscriptionChangeProductInfo, type SubscriptionChangeStatus, type SubscriptionInfo, type SubscriptionManageAction, type SubscriptionMerchantInfo, type SubscriptionNotificationResult, type SubscriptionPaymentDetail, type SubscriptionPaymentInfo, type SubscriptionPeriodChangedNotification, type SubscriptionPromotionInfo, SubscriptionResource, type SubscriptionScheduledAmount, type SubscriptionStatus, type SubscriptionStatusNotification, type SubscriptionUpdateProductInfo, type SubscriptionUpdateTopupData, type SubscriptionUpdateTopupInfo, type SubscriptionUserInfo, type UpdateSubscriptionData, type UpdateSubscriptionParams, type UserInfo, Waffo, type WaffoConfig, WaffoConfigDefaults, WaffoError, WaffoErrorCode, WaffoHttpClient, type WaffoLogger, WaffoUnknownStatusError, type WalletInquiryData, type WalletInquiryParams, WalletResource, WebhookEventType, WebhookHandler, type WebhookResult, type X402Info };
+export { type AddressInfo, ApiResponse, type BaseNotification, type CancelOrderData, type CancelOrderParams, type CancelSubscriptionData, type CancelSubscriptionParams, type CaptureOrderData, type CaptureOrderParams, type CardInfo, type CreateOrderData, type CreateOrderParams, type CreateSubscriptionData, type CreateSubscriptionParams, Environment, EnvironmentBaseUrl, type FixedMaintenanceRule, type GoodsInfo, type HttpRequest, type HttpResponse, type HttpTransport, type InquiryMerchantConfigData, type InquiryMerchantConfigParams, type InquiryOrderData, type InquiryOrderParams, type InquiryPayMethodConfigData, type InquiryPayMethodConfigParams, type InquiryRefundData, type InquiryRefundParams, type InquirySubscriptionData, type InquirySubscriptionParams, type ManageSubscriptionData, type ManageSubscriptionParams, MerchantConfigResource, type MerchantInfo, type OpenBusinessValues, OrderResource, type OrderStatus, PayMethodConfigResource, type PayMethodDetail, type PayMethodInfo, type PaymentInfo, type PaymentNotification, type PaymentNotificationResult, type PeriodType, type ProductInfo, type PromotionInfo, type RefundNotification, type RefundNotificationResult, type RefundOrderData, type RefundOrderParams, RefundResource, type RefundStatus$1 as RefundStatus, type RefundUserInfo, type RequestOptions, type RiskData, RsaUtils, type SubscriptionChangeData, type SubscriptionChangeInquiryData, type SubscriptionChangeInquiryParams, type SubscriptionChangeParams, type SubscriptionChangeProductInfo, type SubscriptionChangeStatus, type SubscriptionInfo, type SubscriptionManageAction, type SubscriptionMerchantInfo, type SubscriptionNotificationResult, type SubscriptionPaymentDetail, type SubscriptionPaymentInfo, type SubscriptionPeriodChangedNotification, type SubscriptionPromotionInfo, SubscriptionResource, type SubscriptionScheduledAmount, type SubscriptionStatus, type SubscriptionStatusNotification, type SubscriptionUpdateProductInfo, type SubscriptionUpdateTopupData, type SubscriptionUpdateTopupInfo, type SubscriptionUserInfo, type UpdateSubscriptionData, type UpdateSubscriptionParams, type UserInfo, Waffo, type WaffoConfig, WaffoConfigDefaults, WaffoError, WaffoErrorCode, WaffoHttpClient, type WaffoLogger, WaffoUnknownStatusError, type WalletInquiryData, type WalletInquiryParams, WalletResource, WebhookEventType, WebhookHandler, type WebhookResult, type X402Info };

package/dist/index.js

@@ -370,6 +370,10 @@ var ApiResponse = class _ApiResponse {
   getData() {
     return this.data;
   }
+  /** Returns the same JSON data with business string literals opened to future values. */
+  getOpenData() {
+    return this.data;
+  }
   /**
    * Gets the error message.
    *
@@ -477,7 +481,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/3.1.0";
+var SDK_VERSION = "waffo-node/3.2.0";
 var WaffoHttpClient = class {
   baseUrl;
   apiKey;
@@ -668,6 +672,7 @@ var WebhookHandler = class {
   subscriptionPaymentHandler;
   subscriptionPeriodChangedHandler;
   subscriptionChangeHandler;
+  customEventHandlers = /* @__PURE__ */ new Map();
   constructor(config) {
     this.waffoPublicKey = config.waffoPublicKey;
     this.privateKey = config.privateKey;
@@ -716,6 +721,20 @@ var WebhookHandler = class {
     this.subscriptionChangeHandler = handler;
     return this;
   }
+  /** Registers an exact custom event name before receiving webhooks. Later registration replaces the same name. */
+  onEvent(eventType, handler) {
+    if (typeof eventType !== "string" || !eventType.trim()) {
+      throw new WaffoError(WaffoErrorCode.UNEXPECTED, "Custom event name must not be blank");
+    }
+    if (typeof handler !== "function") {
+      throw new WaffoError(WaffoErrorCode.UNEXPECTED, "Custom event handler must be a function");
+    }
+    if (Object.values(WebhookEventType).some((known) => known === eventType)) {
+      throw new WaffoError(WaffoErrorCode.UNEXPECTED, `Use the dedicated handler for built-in event: ${eventType}`);
+    }
+    this.customEventHandlers.set(eventType, handler);
+    return this;
+  }
   /**
    * Processes a webhook notification.
    *
@@ -735,6 +754,9 @@ var WebhookHandler = class {
         return this.createFailedResult("Invalid signature");
       }
       const parsed = JSON.parse(body);
+      if (!parsed || typeof parsed.eventType !== "string") {
+        return this.createFailedResult("Unknown event type");
+      }
       const eventType = parsed.eventType;
       switch (eventType) {
         case "PAYMENT_NOTIFICATION" /* PAYMENT_NOTIFICATION */:
@@ -764,9 +786,15 @@ var WebhookHandler = class {
             await this.subscriptionChangeHandler(parsed);
           }
           break;
-        default:
-          this.logger?.warn(`Unknown webhook event type: ${eventType}`);
-          return this.createFailedResult(`Unknown event type: ${eventType}`);
+        default: {
+          const handler = this.customEventHandlers.get(eventType);
+          if (!handler) {
+            this.logger?.warn(`Unknown webhook event type: ${eventType}`);
+            return this.createFailedResult(`Unknown event type: ${eventType}`);
+          }
+          await handler(parsed);
+          break;
+        }
       }
       return this.createSuccessResult();
     } catch (error) {
@@ -959,14 +987,6 @@ var SubscriptionResource = class _SubscriptionResource extends BaseResource {
   static PATH_UPDATE = "/update";
   static PATH_CHANGE = "/change";
   static PATH_CHANGE_INQUIRY = "/change/inquiry";
-  /**
-   * Creates a new subscription.
-   *
-   * @param params - Subscription creation parameters
-   * @param options - Optional request options
-   * @returns API response with subscription data
-   * @throws WaffoUnknownStatusError for network errors
-   */
   async create(params, options) {
     if (!params.requestedAt) {
       params.requestedAt = getCurrentTimestamp();
@@ -1048,47 +1068,6 @@ var SubscriptionResource = class _SubscriptionResource extends BaseResource {
       null
     );
   }
-  /**
-   * Changes (upgrades/downgrades) an existing subscription.
-   *
-   * This method allows changing an active subscription to a new plan with different
-   * pricing, billing period, or other terms. The remaining amount from the original
-   * subscription can be applied to the new subscription.
-   *
-   * @param params - Subscription change parameters
-   * @param options - Optional request options
-   * @returns API response with change result
-   * @throws WaffoUnknownStatusError for network errors
-   *
-   * @example
-   * ```typescript
-   * const response = await waffo.subscription().change({
-   *   subscriptionRequest: 'new-request-id',
-   *   originSubscriptionRequest: 'original-request-id',
-   *   remainingAmount: '50.00',
-   *   currency: 'HKD',
-   *   requestedAt: new Date().toISOString(),
-   *   notifyUrl: 'https://example.com/webhook',
-   *   productInfoList: [{
-   *     description: 'Premium Monthly',
-   *     periodType: 'MONTH',
-   *     periodInterval: '1',
-   *     amount: '199.00',
-   *   }],
-   *   userInfo: { userId: 'user-123', userEmail: 'user@example.com' },
-   *   goodsInfo: { goodsId: 'premium', goodsName: 'Premium Plan' },
-   *   paymentInfo: { productName: 'SUBSCRIPTION' },
-   * });
-   *
-   * if (response.isSuccess()) {
-   *   const data = response.getData();
-   *   if (data?.subscriptionChangeStatus === 'AUTHORIZATION_REQUIRED') {
-   *     // Redirect user to authorization URL
-   *     const webUrl = JSON.parse(data.subscriptionAction || '{}').webUrl;
-   *   }
-   * }
-   * ```
-   */
   async change(params, options) {
     if (!params.requestedAt) {
       params.requestedAt = getCurrentTimestamp();