@waffo/waffo-node 3.0.1 → 3.2.0

package/dist/index.mjs

@@ -348,6 +348,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.
    *
@@ -455,7 +459,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.0.1";
+var SDK_VERSION = "waffo-node/3.2.0";
 var WaffoHttpClient = class {
   baseUrl;
   apiKey;
@@ -485,15 +489,16 @@ var WaffoHttpClient = class {
    * @param path - API endpoint path (e.g., "/order/create")
    * @param request - Request body
    * @param options - Per-request options
+   * @param merchantIdPath - Contract path for merchantId, null for no injection, or omitted for legacy inference
    * @returns API response
    * @throws WaffoUnknownStatusError for network errors or unknown status
    */
-  async post(path, request, options) {
+  async post(path, request, options, merchantIdPath) {
     const url = this.baseUrl + path;
     const effectiveConnectTimeout = options?.connectTimeout ?? this.connectTimeout;
     const effectiveReadTimeout = options?.readTimeout ?? this.readTimeout;
     try {
-      this.injectMerchantIdIfNeeded(request);
+      this.injectMerchantIdIfNeeded(request, merchantIdPath);
       const requestBody = JSON.stringify(request);
       const signature = RsaUtils.sign(requestBody, this.privateKey);
       this.logger?.debug(`Request URL: ${url}`);
@@ -586,9 +591,24 @@ var WaffoHttpClient = class {
   /**
    * Auto-injects merchantId into the request if configured.
    */
-  injectMerchantIdIfNeeded(request) {
+  injectMerchantIdIfNeeded(request, merchantIdPath) {
     if (!this.merchantId) return;
     const req = request;
+    if (merchantIdPath === null) return;
+    if (merchantIdPath === "merchantInfo.merchantId") {
+      const merchantInfo = typeof req.merchantInfo === "object" && req.merchantInfo !== null ? req.merchantInfo : {};
+      if (!merchantInfo.merchantId) {
+        merchantInfo.merchantId = this.merchantId;
+      }
+      req.merchantInfo = merchantInfo;
+      return;
+    }
+    if (merchantIdPath === "merchantId") {
+      if (!req.merchantId) {
+        req.merchantId = this.merchantId;
+      }
+      return;
+    }
     if (typeof req.merchantInfo === "object" && req.merchantInfo !== null) {
       const info = req.merchantInfo;
       if (!info.merchantId) {
@@ -630,6 +650,7 @@ var WebhookHandler = class {
   subscriptionPaymentHandler;
   subscriptionPeriodChangedHandler;
   subscriptionChangeHandler;
+  customEventHandlers = /* @__PURE__ */ new Map();
   constructor(config) {
     this.waffoPublicKey = config.waffoPublicKey;
     this.privateKey = config.privateKey;
@@ -678,6 +699,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.
    *
@@ -697,6 +732,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 */:
@@ -726,9 +764,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) {
@@ -833,7 +877,8 @@ var OrderResource = class _OrderResource extends BaseResource {
     return this.httpClient.post(
       this.getPath(_OrderResource.PATH_CREATE),
       params,
-      options
+      options,
+      "merchantInfo.merchantId"
     );
   }
   /**
@@ -848,7 +893,8 @@ var OrderResource = class _OrderResource extends BaseResource {
     return this.httpClient.post(
       this.getPath(_OrderResource.PATH_INQUIRY),
       params,
-      options
+      options,
+      null
     );
   }
   /**
@@ -866,7 +912,8 @@ var OrderResource = class _OrderResource extends BaseResource {
     return this.httpClient.post(
       this.getPath(_OrderResource.PATH_CANCEL),
       params,
-      options
+      options,
+      "merchantId"
     );
   }
   /**
@@ -884,7 +931,8 @@ var OrderResource = class _OrderResource extends BaseResource {
     return this.httpClient.post(
       this.getPath(_OrderResource.PATH_REFUND),
       params,
-      options
+      options,
+      "merchantId"
     );
   }
   /**
@@ -902,7 +950,8 @@ var OrderResource = class _OrderResource extends BaseResource {
     return this.httpClient.post(
       this.getPath(_OrderResource.PATH_CAPTURE),
       params,
-      options
+      options,
+      "merchantId"
     );
   }
 };
@@ -916,14 +965,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();
@@ -931,7 +972,8 @@ var SubscriptionResource = class _SubscriptionResource extends BaseResource {
     return this.httpClient.post(
       this.getPath(_SubscriptionResource.PATH_CREATE),
       params,
-      options
+      options,
+      "merchantInfo.merchantId"
     );
   }
   /**
@@ -946,7 +988,8 @@ var SubscriptionResource = class _SubscriptionResource extends BaseResource {
     return this.httpClient.post(
       this.getPath(_SubscriptionResource.PATH_INQUIRY),
       params,
-      options
+      options,
+      null
     );
   }
   /**
@@ -964,7 +1007,8 @@ var SubscriptionResource = class _SubscriptionResource extends BaseResource {
     return this.httpClient.post(
       this.getPath(_SubscriptionResource.PATH_CANCEL),
       params,
-      options
+      options,
+      "merchantId"
     );
   }
   /**
@@ -979,7 +1023,8 @@ var SubscriptionResource = class _SubscriptionResource extends BaseResource {
     return this.httpClient.post(
       this.getPath(_SubscriptionResource.PATH_MANAGE),
       params,
-      options
+      options,
+      null
     );
   }
   /**
@@ -997,50 +1042,10 @@ var SubscriptionResource = class _SubscriptionResource extends BaseResource {
     return this.httpClient.post(
       this.getPath(_SubscriptionResource.PATH_UPDATE),
       params,
-      options
+      options,
+      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();
@@ -1048,7 +1053,8 @@ var SubscriptionResource = class _SubscriptionResource extends BaseResource {
     return this.httpClient.post(
       this.getPath(_SubscriptionResource.PATH_CHANGE),
       params,
-      options
+      options,
+      "merchantInfo.merchantId"
     );
   }
   /**
@@ -1079,11 +1085,16 @@ var SubscriptionResource = class _SubscriptionResource extends BaseResource {
       return await this.httpClient.post(
         this.getPath(_SubscriptionResource.PATH_CHANGE_INQUIRY),
         params,
-        options
+        options,
+        null
       );
     } catch (error) {
       if (error && typeof error === "object" && "errorCode" in error) {
-        return ApiResponse.error("E0001", String(error.message || "Unknown error"));
+        const unknownStatus = error;
+        return ApiResponse.error(
+          String(unknownStatus.errorCode),
+          String(unknownStatus.message || "Unknown error")
+        );
       }
       throw error;
     }
@@ -1105,7 +1116,8 @@ var RefundResource = class _RefundResource extends BaseResource {
     return this.httpClient.post(
       this.getPath(_RefundResource.PATH_INQUIRY),
       params,
-      options
+      options,
+      null
     );
   }
 };
@@ -1125,7 +1137,8 @@ var MerchantConfigResource = class _MerchantConfigResource extends BaseResource
     return this.httpClient.post(
       this.getPath(_MerchantConfigResource.PATH_INQUIRY),
       params,
-      options
+      options,
+      "merchantId"
     );
   }
 };
@@ -1145,7 +1158,8 @@ var PayMethodConfigResource = class _PayMethodConfigResource extends BaseResourc
     return this.httpClient.post(
       this.getPath(_PayMethodConfigResource.PATH_INQUIRY),
       params,
-      options
+      options,
+      "merchantId"
     );
   }
 };
@@ -1165,7 +1179,8 @@ var WalletResource = class _WalletResource extends BaseResource {
     return this.httpClient.post(
       this.getPath(_WalletResource.PATH_INQUIRY),
       params,
-      options
+      options,
+      "merchantInfo.merchantId"
     );
   }
 };