@waffo/waffo-node 2.0.4 → 2.1.0

package/README.md

@@ -1,6 +1,6 @@
 # Waffo Node.js SDK
 
-<!-- Synced with waffo-sdk/README.md @ commit 9971ef7 -->
+<!-- Synced with waffo-sdk/README.md @ commit 48b44fc -->
 
 **English** | [中文](README_CN.md)
 
@@ -46,11 +46,11 @@ Official Node.js/TypeScript SDK for [Waffo Payment Platform](https://www.waffo.c
   - [Custom HTTP Transport](#custom-http-transport-axios)
   - [TLS Security Configuration](#tls-security-configuration)
   - [Debug Logging](#debug-logging)
+- [Handling New API Fields (ExtraParams)](#handling-new-api-fields-extraparams)
 - [Error Handling](#error-handling)
-- [TypeScript Support](#typescript-support)
-- [Development & Testing](#development--testing)
 - [Support](#support)
 - [License](#license)
+- [Development & Testing](#development-testing)
 
 ## Requirements
 
@@ -1012,6 +1012,62 @@ const signature = RsaUtils.sign(data, privateKey);
 const isValid = RsaUtils.verify(data, signature, publicKey);
 ```
 
+## 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.
+
+### Reading Unknown Fields from Responses
+
+```typescript
+// Get extra field from response
+const response = await waffo.order().inquiry({ paymentRequestId: 'REQ001' });
+if (response.isSuccess()) {
+  const data = response.getData();
+
+  // Access field not yet defined in SDK
+  const newField = data.extraParams?.['newField'];
+
+  // Or use type assertion if you know the type
+  const typedValue = data.extraParams?.['newField'] as string;
+}
+
+// Get extra field from webhook notification
+webhookHandler.onPaymentNotification((notification) => {
+  const result = notification.result;
+  const newField = result.extraParams?.['newField'];
+});
+```
+
+### Sending Extra Fields in Requests
+
+```typescript
+// TypeScript types include index signature [key: string]: unknown
+// You can directly add extra fields to any request
+const response = await waffo.order().create({
+  paymentRequestId: 'REQ001',
+  merchantOrderId: 'ORDER001',
+  // ... other required fields
+  newField: 'value',           // Extra field - no type error
+  nested: { key: 123 }         // Nested object - works too
+});
+```
+
+### Important Notes
+
+> **Upgrade SDK Promptly**
+>
+> ExtraParams is designed as a **temporary solution** for accessing new API fields before SDK updates.
+>
+> **Best Practices:**
+> 1. Check SDK release notes regularly for new field support
+> 2. Once SDK officially supports the field, migrate from `getExtraParam("field")` to the official getter (e.g., `getField()`)
+> 3. The SDK logs a warning when you use `getExtraParam()` on officially supported fields
+>
+> **Why migrate?**
+> - Official getters provide type safety
+> - Better IDE auto-completion and documentation
+> - Reduced risk of typos in field names
+
 ## Error Handling
 
 ### Error Handling Pattern

package/dist/index.d.mts

@@ -525,6 +525,7 @@ interface CreateOrderData {
 interface InquiryOrderParams {
     paymentRequestId?: string;
     acquiringOrderId?: string;
+    merchantInfo?: MerchantInfo;
     [key: string]: unknown;
 }
 /**
@@ -550,8 +551,8 @@ interface InquiryOrderData {
 interface CancelOrderParams {
     paymentRequestId?: string;
     acquiringOrderId?: string;
-    merchantId: string;
-    orderRequestedAt: string;
+    merchantInfo?: MerchantInfo;
+    orderRequestedAt?: string;
     [key: string]: unknown;
 }
 /**
@@ -569,13 +570,14 @@ interface CancelOrderData {
  */
 interface RefundOrderParams {
     refundRequestId: string;
-    acquiringOrderId: string;
+    paymentRequestId?: string;
+    acquiringOrderId?: string;
     merchantRefundOrderId?: string;
-    merchantId: string;
+    merchantInfo?: MerchantInfo;
     refundAmount: string;
-    refundReason: string;
-    requestedAt: string;
-    refundNotifyUrl?: string;
+    refundReason?: string;
+    requestedAt?: string;
+    notifyUrl?: string;
     userInfo?: RefundUserInfo;
     extendInfo?: string;
     [key: string]: unknown;
@@ -812,22 +814,33 @@ declare class OrderResource extends BaseResource {
  * Create subscription request parameters.
  */
 interface CreateSubscriptionParams {
-    subscriptionRequestId: string;
+    /**
+     * Subscription request ID sent from Merchant (max 32 characters).
+     * Used for idempotent check.
+     */
+    subscriptionRequest: string;
     merchantSubscriptionId: string;
-    orderCurrency: string;
-    orderAmount: string;
-    orderDescription: string;
+    currency: string;
+    amount: string;
     notifyUrl: string;
     productInfo: ProductInfo;
     userInfo: SubscriptionUserInfo;
     paymentInfo: SubscriptionPaymentInfo;
     merchantInfo?: SubscriptionMerchantInfo;
+    goodsInfo?: {
+        goodsId: string;
+        goodsName: string;
+        goodsCategory?: string;
+        goodsUrl?: string;
+        goodsQuantity?: number;
+        [key: string]: unknown;
+    };
     successRedirectUrl?: string;
     failedRedirectUrl?: string;
     cancelRedirectUrl?: string;
+    subscriptionManagementUrl?: string;
     requestedAt?: string;
     extendInfo?: string;
-    metadata?: string;
     /**
      * Order expiry time (ISO 8601 format, max 24 characters).
      */
@@ -838,7 +851,7 @@ interface CreateSubscriptionParams {
  * Create subscription response data.
  */
 interface CreateSubscriptionData {
-    subscriptionRequestId?: string;
+    subscriptionRequest?: string;
     merchantSubscriptionId?: string;
     subscriptionId?: string;
     subscriptionStatus?: SubscriptionStatus;
@@ -849,41 +862,43 @@ interface CreateSubscriptionData {
  * Inquiry subscription request parameters.
  */
 interface InquirySubscriptionParams {
-    subscriptionRequestId?: string;
+    subscriptionRequest?: string;
     subscriptionId?: string;
+    merchantInfo?: SubscriptionMerchantInfo;
     [key: string]: unknown;
 }
 /**
  * Inquiry subscription response data.
  */
 interface InquirySubscriptionData {
-    subscriptionRequestId?: string;
+    subscriptionRequest?: string;
     merchantSubscriptionId?: string;
     subscriptionId?: string;
+    payMethodSubscriptionId?: string;
     subscriptionStatus?: SubscriptionStatus;
-    orderCurrency?: string;
-    orderAmount?: string;
-    currentPeriodStartAt?: string;
-    currentPeriodEndAt?: string;
-    nextBillingAt?: string;
+    subscriptionAction?: string;
+    currency?: string;
+    userCurrency?: string;
+    amount?: string;
+    productInfo?: ProductInfo;
     [key: string]: unknown;
 }
 /**
  * Cancel subscription request parameters.
  */
 interface CancelSubscriptionParams {
-    subscriptionRequestId?: string;
+    subscriptionRequest?: string;
     subscriptionId?: string;
-    merchantId: string;
+    merchantInfo?: SubscriptionMerchantInfo;
     cancelReason?: string;
-    requestedAt: string;
+    requestedAt?: string;
     [key: string]: unknown;
 }
 /**
  * Cancel subscription response data.
  */
 interface CancelSubscriptionData {
-    subscriptionRequestId?: string;
+    subscriptionRequest?: string;
     merchantSubscriptionId?: string;
     subscriptionId?: string;
     subscriptionStatus?: SubscriptionStatus;
@@ -912,28 +927,78 @@ interface ManageSubscriptionData {
 }
 /**
  * Subscription status enum.
+ * Based on openapi.json SubscriptionInquiryResponse.subscriptionStatus.
  */
-type SubscriptionStatus = 'SUBSCRIPTION_IN_PROGRESS' | 'SUBSCRIPTION_ACTIVE' | 'SUBSCRIPTION_PAUSED' | 'SUBSCRIPTION_CANCELLED' | 'SUBSCRIPTION_EXPIRED';
+type SubscriptionStatus = 'AUTHORIZATION_REQUIRED' | 'IN_PROGRESS' | 'ACTIVE' | 'CLOSE' | 'MERCHANT_CANCELLED' | 'USER_CANCELLED' | 'CHANNEL_CANCELLED' | 'EXPIRED';
 /**
  * Subscription manage action enum.
  */
 type SubscriptionManageAction = 'PAUSE' | 'RESUME' | 'UPDATE_AMOUNT' | 'UPDATE_PERIOD';
 /**
  * Period type enum.
+ * Values: DAILY, WEEKLY, MONTHLY
  */
-type PeriodType = 'DAY' | 'WEEK' | 'MONTH' | 'YEAR';
+type PeriodType = 'DAILY' | 'WEEKLY' | 'MONTHLY';
 /**
  * Product information for subscription.
+ * Based on openapi.json ProductInfo schema.
  */
 interface ProductInfo {
-    productId: string;
-    productName: string;
-    productDescription?: string;
+    /**
+     * Subscription product description (max 128 characters).
+     * Often appearing to user when asking user's confirmation.
+     */
+    description: string;
+    /**
+     * Subscription product period type: DAILY, WEEKLY, MONTHLY.
+     */
     periodType: PeriodType;
-    periodValue: number;
+    /**
+     * Period interval (max 12 characters).
+     * - DAILY: 1-365
+     * - WEEKLY: 1-4
+     * - MONTHLY: 1-12
+     */
+    periodInterval: string;
+    /**
+     * Number of billing periods until subscription ends (max 24 characters).
+     * Empty means no defined end period.
+     */
+    numberOfPeriod?: string;
+    /**
+     * Trial period amount (max 24 characters).
+     */
+    trialPeriodAmount?: string;
+    /**
+     * Number of trial periods (max 12 characters).
+     */
+    numberOfTrialPeriod?: string;
+    /**
+     * Trial period type: DAILY, WEEKLY, MONTHLY.
+     * If omitted, uses periodType value by default.
+     */
     trialPeriodType?: PeriodType;
-    trialPeriodValue?: number;
-    trialAmount?: string;
+    /**
+     * Trial period interval (max 12 characters).
+     * If omitted, uses periodInterval value by default.
+     */
+    trialPeriodInterval?: string;
+    /**
+     * When the subscription starts (ISO 8601 format).
+     */
+    startDateTime?: string;
+    /**
+     * When the subscription ends (ISO 8601 format).
+     */
+    endDateTime?: string;
+    /**
+     * When the next payment is due (ISO 8601 format).
+     */
+    nextPaymentDateTime?: string;
+    /**
+     * Current billing period number.
+     */
+    currentPeriod?: string;
     [key: string]: unknown;
 }
 /**
@@ -1426,35 +1491,40 @@ declare class SubscriptionResource extends BaseResource {
  * Note: Full type definitions should be generated from openapi.json.
  * These are placeholder interfaces for the SDK structure.
  */
+
 /**
  * Inquiry refund request parameters.
  */
 interface InquiryRefundParams {
     refundRequestId?: string;
     acquiringRefundOrderId?: string;
+    merchantInfo?: MerchantInfo;
     [key: string]: unknown;
 }
 /**
  * Inquiry refund response data.
+ * Based on openapi.json AcqOrderRefundInquiry schema.
  */
 interface InquiryRefundData {
     refundRequestId?: string;
     merchantRefundOrderId?: string;
     acquiringOrderId?: string;
     acquiringRefundOrderId?: string;
+    origPaymentRequestId?: string;
     refundAmount?: string;
+    refundCurrency?: string;
     refundStatus?: RefundStatus;
-    refundFailedReason?: RefundFailedReason;
+    refundReason?: string;
+    refundRequestedAt?: string;
+    refundUpdatedAt?: string;
+    refundFailedReason?: string;
+    extendInfo?: string;
     [key: string]: unknown;
 }
 /**
  * Refund status enum.
  */
 type RefundStatus = 'REFUND_IN_PROGRESS' | 'ORDER_PARTIALLY_REFUNDED' | 'ORDER_FULLY_REFUNDED' | 'ORDER_REFUND_FAILED';
-/**
- * Refund failed reason enum.
- */
-type RefundFailedReason = 'INSUFFICIENT_BALANCE' | 'ORIGINAL_ORDER_NOT_FOUND' | 'REFUND_AMOUNT_EXCEEDED' | 'SYSTEM_ERROR' | 'OTHER';
 
 /**
  * Refund resource for querying refund status.
@@ -1841,108 +1911,100 @@ declare class WaffoUnknownStatusError extends Error {
 }
 
 /**
- * RSA cryptographic utilities for signing and verification.
+ * Result of key pair generation.
+ */
+interface KeyPairResult {
+    /** Base64 encoded PKCS8 private key */
+    privateKey: string;
+    /** Base64 encoded X509 public key */
+    publicKey: string;
+}
+/**
+ * Signs data using RSA-SHA256.
  *
- * Uses SHA256withRSA algorithm with 2048-bit key size.
+ * @param data - The data to sign (UTF-8 string)
+ * @param base64PrivateKey - Base64 encoded PKCS8 private key
+ * @returns Base64 encoded signature
+ * @throws WaffoError if signing fails (S0003)
  *
- * **Key Formats:**
- * - Private Key: PKCS#8 DER encoded, Base64 string
- * - Public Key: X.509 SubjectPublicKeyInfo DER encoded, Base64 string
+ * @example
+ * ```typescript
+ * const signature = sign('{"amount":"100.00"}', privateKey);
+ * ```
+ */
+declare function sign(data: string, base64PrivateKey: string): string;
+/**
+ * Verifies a signature using RSA-SHA256.
  *
- * **Security Best Practices:**
+ * @param data - The original data (UTF-8 string)
+ * @param base64Signature - Base64 encoded signature
+ * @param base64PublicKey - Base64 encoded X509 public key
+ * @returns true if signature is valid, false otherwise
  *
- * When verifying Waffo's response signature fails:
- * 1. Stop sending new transactions to Waffo until the issue is resolved
- * 2. Investigate the cause and contact Waffo support
- * 3. Note: Waffo may have already processed your request, but you failed to
- *    process the response due to signature verification failure
+ * @example
+ * ```typescript
+ * const isValid = verify(responseBody, signature, waffoPublicKey);
+ * if (!isValid) {
+ *   // Handle signature verification failure
+ * }
+ * ```
  */
-declare namespace RsaUtils {
-    /**
-     * Result of key pair generation.
-     */
-    interface KeyPairResult {
-        /** Base64 encoded PKCS8 private key */
-        privateKey: string;
-        /** Base64 encoded X509 public key */
-        publicKey: string;
-    }
-    /**
-     * Signs data using RSA-SHA256.
-     *
-     * @param data - The data to sign (UTF-8 string)
-     * @param base64PrivateKey - Base64 encoded PKCS8 private key
-     * @returns Base64 encoded signature
-     * @throws WaffoError if signing fails (S0003)
-     *
-     * @example
-     * ```typescript
-     * const signature = RsaUtils.sign('{"amount":"100.00"}', privateKey);
-     * ```
-     */
-    function sign(data: string, base64PrivateKey: string): string;
-    /**
-     * Verifies a signature using RSA-SHA256.
-     *
-     * @param data - The original data (UTF-8 string)
-     * @param base64Signature - Base64 encoded signature
-     * @param base64PublicKey - Base64 encoded X509 public key
-     * @returns true if signature is valid, false otherwise
-     *
-     * @example
-     * ```typescript
-     * const isValid = RsaUtils.verify(responseBody, signature, waffoPublicKey);
-     * if (!isValid) {
-     *   // Handle signature verification failure
-     * }
-     * ```
-     */
-    function verify(data: string, base64Signature: string, base64PublicKey: string): boolean;
-    /**
-     * Validates a Base64 encoded PKCS8 private key.
-     *
-     * This method attempts to parse the key to ensure it's a valid RSA private key.
-     * Use this at startup to fail fast if the private key is invalid.
-     *
-     * @param base64PrivateKey - Base64 encoded PKCS8 private key
-     * @throws WaffoError if the key is invalid (S0007)
-     *
-     * @example
-     * ```typescript
-     * // Validate at initialization
-     * RsaUtils.validatePrivateKey(config.privateKey);
-     * ```
-     */
-    function validatePrivateKey(base64PrivateKey: string): void;
-    /**
-     * Validates a Base64 encoded X509 public key.
-     *
-     * This method attempts to parse the key to ensure it's a valid RSA public key.
-     * Use this at startup to fail fast if the public key is invalid.
-     *
-     * @param base64PublicKey - Base64 encoded X509 public key
-     * @throws WaffoError if the key is invalid (S0002)
-     *
-     * @example
-     * ```typescript
-     * // Validate at initialization
-     * RsaUtils.validatePublicKey(config.waffoPublicKey);
-     * ```
-     */
-    function validatePublicKey(base64PublicKey: string): void;
-    /**
-     * Generates a new RSA key pair for testing or merchant key generation.
-     *
-     * @returns A new KeyPairResult containing Base64 encoded keys
-     *
-     * @example
-     * ```typescript
-     * const keyPair = RsaUtils.generateKeyPair();
-     * console.log('Private Key:', keyPair.privateKey);
-     * console.log('Public Key:', keyPair.publicKey);
-     * ```
-     */
-    function generateKeyPair(): KeyPairResult;
-}
+declare function verify(data: string, base64Signature: string, base64PublicKey: string): boolean;
+/**
+ * Validates a Base64 encoded PKCS8 private key.
+ *
+ * This method attempts to parse the key to ensure it's a valid RSA private key.
+ * Use this at startup to fail fast if the private key is invalid.
+ *
+ * @param base64PrivateKey - Base64 encoded PKCS8 private key
+ * @throws WaffoError if the key is invalid (S0007)
+ *
+ * @example
+ * ```typescript
+ * // Validate at initialization
+ * validatePrivateKey(config.privateKey);
+ * ```
+ */
+declare function validatePrivateKey(base64PrivateKey: string): void;
+/**
+ * Validates a Base64 encoded X509 public key.
+ *
+ * This method attempts to parse the key to ensure it's a valid RSA public key.
+ * Use this at startup to fail fast if the public key is invalid.
+ *
+ * @param base64PublicKey - Base64 encoded X509 public key
+ * @throws WaffoError if the key is invalid (S0002)
+ *
+ * @example
+ * ```typescript
+ * // Validate at initialization
+ * validatePublicKey(config.waffoPublicKey);
+ * ```
+ */
+declare function validatePublicKey(base64PublicKey: string): void;
+/**
+ * Generates a new RSA key pair for testing or merchant key generation.
+ *
+ * @returns A new KeyPairResult containing Base64 encoded keys
+ *
+ * @example
+ * ```typescript
+ * const keyPair = generateKeyPair();
+ * console.log('Private Key:', keyPair.privateKey);
+ * console.log('Public Key:', keyPair.publicKey);
+ * ```
+ */
+declare function generateKeyPair(): KeyPairResult;
+/**
+ * RsaUtils namespace for backward compatibility.
+ * @deprecated Use direct function imports instead.
+ */
+declare const RsaUtils: {
+    sign: typeof sign;
+    verify: typeof verify;
+    validatePrivateKey: typeof validatePrivateKey;
+    validatePublicKey: typeof validatePublicKey;
+    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 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 PayMethodInfo, type PaymentInfo, type PaymentNotification, type PeriodType, type ProductInfo, type RefundFailedReason, type RefundNotification, type RefundOrderData, type RefundOrderParams, RefundResource, type RefundStatus$1 as RefundStatus, type RefundUserInfo, type RequestOptions, type RiskData, RsaUtils, type SubscriptionManageAction, type SubscriptionMerchantInfo, type SubscriptionPaymentInfo, type SubscriptionPaymentNotification, type SubscriptionPeriodChangedNotification, SubscriptionResource, type SubscriptionStatus, type SubscriptionStatusNotification, type SubscriptionUserInfo, type UserInfo, Waffo, type WaffoConfig, WaffoConfigDefaults, WaffoError, WaffoErrorCode, WaffoHttpClient, type WaffoLogger, WaffoUnknownStatusError, WebhookEventType, WebhookHandler, type WebhookResult };
+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 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 PayMethodInfo, type PaymentInfo, type PaymentNotification, type PeriodType, type ProductInfo, type RefundNotification, type RefundOrderData, type RefundOrderParams, RefundResource, type RefundStatus$1 as RefundStatus, type RefundUserInfo, type RequestOptions, type RiskData, RsaUtils, type SubscriptionManageAction, type SubscriptionMerchantInfo, type SubscriptionPaymentInfo, type SubscriptionPaymentNotification, type SubscriptionPeriodChangedNotification, SubscriptionResource, type SubscriptionStatus, type SubscriptionStatusNotification, type SubscriptionUserInfo, type UserInfo, Waffo, type WaffoConfig, WaffoConfigDefaults, WaffoError, WaffoErrorCode, WaffoHttpClient, type WaffoLogger, WaffoUnknownStatusError, WebhookEventType, WebhookHandler, type WebhookResult };