@waffo/waffo-node 2.4.0 → 2.5.1

package/README.md

@@ -1,6 +1,6 @@
 # Waffo Node.js SDK
 
-<!-- Synced with waffo-sdk/README.md @ commit ee83ead -->
+<!-- Synced with waffo-sdk/README.md @ commit c23c86f -->
 
 **English** | [中文](README_CN.md)
 
@@ -10,6 +10,12 @@
 
 Official Node.js/TypeScript SDK for [Waffo Payment Platform](https://www.waffo.com), providing one-stop global payment solutions for AI products, SaaS services, and more.
 
+## Latest Release Highlights
+
+- **Subscription update API**: Added `subscription().update()` with `amount`, `trialPeriodAmount`, and `scheduledAmounts` support.
+- **Scheduled amount coverage**: Added `scheduledAmounts` fields across subscription create, change, update, and inquiry product info types.
+- **E2E and contract hardening**: Added subscription update E2E coverage, auto-injected `captureRequestedAt` for `order.capture()`, and expanded nested schema field validation.
+
 ## Introduction
 
 ### Core Features
@@ -30,6 +36,7 @@ Official Node.js/TypeScript SDK for [Waffo Payment Platform](https://www.waffo.c
 
 ## Table of Contents
 
+- [Latest Release Highlights](#latest-release-highlights)
 - [Requirements](#requirements)
 - [Installation](#installation)
 - [Quick Start](#quick-start)
@@ -544,9 +551,9 @@ try {
     notifyUrl: 'https://your-site.com/webhook/subscription',
     productInfoList: [
       {
-        description: 'Yearly Premium Subscription',
-        periodType: 'YEAR',
-        periodInterval: '1',
+        description: 'Annual Premium Subscription (12 months)',
+        periodType: 'MONTHLY',
+        periodInterval: '12',
         amount: '999.00',
       },
     ],
@@ -1287,7 +1294,7 @@ Error codes are classified by first letter:
 | `S0004` | Response Signature Verification Failed | `ApiResponse.error()` | Check Waffo public key config, contact Waffo |
 | `S0005` | Request Serialization Failed | `ApiResponse.error()` | Check request parameter format |
 | `S0006` | SDK Unknown Error | `ApiResponse.error()` | Check logs, contact technical support |
-| `S0007` | Invalid Private Key | `WaffoError` | Check if private key is valid Base64 encoded PKCS8 format |
+| `S0007` | Invalid Private Key | `WaffoError` | Check if private key is valid Base64 PKCS8 DER or unencrypted PKCS8 PEM format |
 
 > **Important**: `S0001` and `E0001` (returned by server) indicate **unknown status**. Do not close order directly! Should call query API or wait for webhook to confirm actual status.
 
@@ -1421,4 +1428,3 @@ npm run test:vectors
 ## License
 
 MIT License - See [LICENSE](LICENSE) file for details.
-

package/dist/index.d.mts

@@ -119,7 +119,7 @@ interface WaffoLogger {
 interface WaffoConfig {
     /** API key provided by Waffo */
     apiKey: string;
-    /** Merchant's private key for signing requests (Base64 encoded PKCS8) */
+    /** Merchant's private key for signing requests (Base64 PKCS8 DER or unencrypted PKCS8 PEM) */
     privateKey: string;
     /** Waffo's public key for verifying responses (Base64 encoded X509) */
     waffoPublicKey: string;
@@ -213,6 +213,11 @@ interface CreateSubscriptionParams {
     orderExpiredAt?: string;
     addressInfo?: SubscriptionAddressInfo;
     riskData?: SubscriptionRiskData;
+    brandInfo?: SubscriptionBrandInfo;
+    subscriptionMode?: string;
+    acqMerchant?: Record<string, unknown>;
+    acqProduct?: Record<string, unknown>;
+    acqAgreements?: Record<string, unknown>[];
     [key: string]: unknown;
 }
 /**
@@ -233,7 +238,19 @@ interface CreateSubscriptionData {
 interface InquirySubscriptionParams {
     subscriptionRequest?: string;
     subscriptionId?: string;
-    paymentDetails?: boolean;
+    paymentDetails?: 0 | 1 | number;
+    [key: string]: unknown;
+}
+/**
+ * Subscription payment detail returned when inquiry paymentDetails=1.
+ */
+interface SubscriptionPaymentDetail {
+    acquiringOrderId?: string;
+    orderCurrency?: string;
+    orderAmount?: string;
+    orderStatus?: string;
+    orderUpdatedAt?: string;
+    period?: string;
     [key: string]: unknown;
 }
 /**
@@ -258,7 +275,7 @@ interface InquirySubscriptionData {
     failedReason?: string;
     subscriptionManagementUrl?: string;
     extendInfo?: string;
-    paymentDetails?: unknown;
+    paymentDetails?: SubscriptionPaymentDetail[];
     goodsInfo?: {
         goodsId?: string;
         goodsName?: string;
@@ -273,7 +290,7 @@ interface InquirySubscriptionData {
  * Cancel subscription request parameters.
  */
 interface CancelSubscriptionParams {
-    subscriptionId?: string;
+    subscriptionId: string;
     merchantId?: string;
     requestedAt?: string;
     [key: string]: unknown;
@@ -308,6 +325,99 @@ interface ManageSubscriptionData {
     subscriptionStatus?: SubscriptionStatus;
     [key: string]: unknown;
 }
+/**
+ * Scheduled amount item for a specific subscription period.
+ */
+interface SubscriptionScheduledAmount {
+    /**
+     * Period number, for example "1".
+     */
+    period?: string;
+    /**
+     * Merchant subscription amount for this period.
+     */
+    amount?: string;
+    [key: string]: unknown;
+}
+/**
+ * Product information for subscription update operations.
+ */
+interface SubscriptionUpdateProductInfo {
+    /**
+     * Updated trial period amount. Empty means no trial period.
+     */
+    trialPeriodAmount?: string;
+    /**
+     * Scheduled amount list for each period.
+     */
+    scheduledAmounts?: SubscriptionScheduledAmount[];
+    [key: string]: unknown;
+}
+/**
+ * Update subscription request parameters.
+ */
+interface UpdateSubscriptionParams {
+    /**
+     * Merchant subscription request ID. Provide subscriptionRequest or subscriptionId.
+     */
+    subscriptionRequest?: string;
+    /**
+     * Waffo subscription ID. Provide subscriptionRequest or subscriptionId.
+     */
+    subscriptionId?: string;
+    /**
+     * New merchant subscription amount. At least one of amount and
+     * productInfo.scheduledAmounts must be provided.
+     */
+    amount?: string;
+    /**
+     * Product information containing trial or scheduled amount updates.
+     */
+    productInfo?: SubscriptionUpdateProductInfo;
+    [key: string]: unknown;
+}
+/**
+ * Update subscription response data.
+ */
+interface UpdateSubscriptionData {
+    /**
+     * Waffo subscription ID.
+     */
+    subscriptionId?: string;
+    /**
+     * Subscription request ID sent from Merchant.
+     */
+    subscriptionRequest?: string;
+    /**
+     * Previous trial period amount.
+     */
+    previousTrialPeriodAmount?: string;
+    /**
+     * New trial period amount.
+     */
+    newTrialPeriodAmount?: string;
+    /**
+     * Previous merchant subscription amount.
+     */
+    previousAmount?: string;
+    /**
+     * New merchant subscription amount.
+     */
+    newAmount?: string;
+    /**
+     * Previous scheduled amount list for each period.
+     */
+    previousScheduledAmounts?: SubscriptionScheduledAmount[];
+    /**
+     * New scheduled amount list for each period.
+     */
+    newScheduledAmounts?: SubscriptionScheduledAmount[];
+    /**
+     * The next period number when the new amount takes effect.
+     */
+    nextEffectivePeriod?: string;
+    [key: string]: unknown;
+}
 /**
  * Subscription status enum.
  * Based on openapi.json SubscriptionInquiryResponse.subscriptionStatus.
@@ -382,6 +492,10 @@ interface ProductInfo {
      * Current billing period number.
      */
     currentPeriod?: string;
+    /**
+     * Scheduled amount list for each period.
+     */
+    scheduledAmounts?: SubscriptionScheduledAmount[];
     [key: string]: unknown;
 }
 /**
@@ -390,9 +504,11 @@ interface ProductInfo {
 interface SubscriptionUserInfo {
     userId: string;
     userEmail: string;
+    userTerminal?: string;
     userPhone?: string;
     userFirstName?: string;
     userLastName?: string;
+    userCreatedAt?: string;
     userCountryCode?: string;
     userBrowserIp?: string;
     userAgent?: string;
@@ -405,12 +521,23 @@ interface SubscriptionPaymentInfo {
     productName: string;
     payMethodType?: string;
     payMethodName?: string;
+    payMethodProperties?: string;
+    payMethodUserAccountType?: string;
+    payMethodUserAccountNo?: string;
+    payMethodUserAccessToken?: string;
+    cashierLanguage?: string;
+    cashierAppearance?: string;
     [key: string]: unknown;
 }
 /**
  * Address information for subscription.
  */
 interface SubscriptionAddressInfo {
+    address?: string;
+    city?: string;
+    region?: string;
+    postcode?: string;
+    addressCountryCode?: string;
     shippingAddress?: {
         country?: string;
         state?: string;
@@ -435,11 +562,28 @@ interface SubscriptionAddressInfo {
  * Risk data for subscription.
  */
 interface SubscriptionRiskData {
+    userType?: string;
+    userCategory?: string;
+    userLegalName?: string;
+    userDisplayName?: string;
+    userRegistrationIp?: string;
+    userLastSeenIp?: string;
+    userIsNew?: string;
+    userIsFirstPurchase?: string;
     deviceType?: string;
     deviceId?: string;
     deviceTokenId?: string;
     [key: string]: unknown;
 }
+/**
+ * Brand display information for cashier.
+ */
+interface SubscriptionBrandInfo {
+    cashierLogoUrl?: string;
+    cashierDisplayName?: string;
+    cashierProductImageUrl?: string;
+    [key: string]: unknown;
+}
 /**
  * Merchant information for subscription.
  */
@@ -517,6 +661,10 @@ interface SubscriptionChangeProductInfo {
      * Trial period interval (max 12 characters).
      */
     trialPeriodInterval?: string;
+    /**
+     * Scheduled amount list for each period.
+     */
+    scheduledAmounts?: SubscriptionScheduledAmount[];
     [key: string]: unknown;
 }
 /**
@@ -634,6 +782,10 @@ interface SubscriptionChangeParams {
         userIsFirstPurchase?: string;
         [key: string]: unknown;
     };
+    /**
+     * Brand display information for cashier.
+     */
+    brandInfo?: SubscriptionBrandInfo;
     [key: string]: unknown;
 }
 /**
@@ -1231,6 +1383,11 @@ interface CreateOrderParams {
     cardInfo?: CardInfo;
     riskData?: RiskData;
     paymentTokenData?: PaymentTokenData;
+    brandInfo?: BrandInfo;
+    productDetail?: ProductDetail;
+    acqOrderExtSubscriptionInfo?: AcqOrderExtSubscriptionInfo;
+    channelId?: string;
+    innerCardData?: WaffoTokenCardData;
     userCurrency?: string;
     successRedirectUrl?: string;
     failedRedirectUrl?: string;
@@ -1356,9 +1513,9 @@ interface RefundOrderData {
 interface CaptureOrderParams {
     paymentRequestId?: string;
     acquiringOrderId?: string;
-    merchantId: string;
+    merchantId?: string;
     captureRequestedAt?: string;
-    captureAmount?: string;
+    captureAmount: string;
     [key: string]: unknown;
 }
 /**
@@ -1407,7 +1564,16 @@ interface PaymentInfo {
     payMethodType?: string;
     payMethodName?: string;
     payMethodProperties?: string;
+    payMethodResponse?: string;
+    userPaymentAccessToken?: string;
+    payMethodUserAccountNo?: string;
+    payMethodUserAccountType?: string;
+    payOption?: string;
+    cashierLanguage?: string;
+    cashierAppearance?: string;
+    payMethodCountry?: string;
     captureMode?: string;
+    merchantInitiatedMode?: string;
     [key: string]: unknown;
 }
 /**
@@ -1476,6 +1642,42 @@ interface PaymentTokenData {
     tokenId?: string;
     [key: string]: unknown;
 }
+/**
+ * Brand display information for cashier.
+ */
+interface BrandInfo {
+    cashierLogoUrl?: string;
+    cashierDisplayName?: string;
+    cashierProductImageUrl?: string;
+    [key: string]: unknown;
+}
+/**
+ * Product detail extension payload.
+ */
+interface ProductDetail {
+    subscriptionInfo?: SubscriptionInfo;
+    [key: string]: unknown;
+}
+/**
+ * Subscription extension information for an acquiring order.
+ */
+interface AcqOrderExtSubscriptionInfo {
+    subscriptionId?: string;
+    periodNo?: number;
+    merchantRequest?: string;
+    subscriptionEvent?: string;
+    [key: string]: unknown;
+}
+/**
+ * Tokenized card data used for direct card payment flows.
+ */
+interface WaffoTokenCardData {
+    cardBinDataList?: Record<string, unknown>[];
+    maskedCardInfo?: string;
+    cardBin?: string;
+    cardExpiry?: string;
+    [key: string]: unknown;
+}
 /**
  * Refund user information.
  */
@@ -1622,6 +1824,7 @@ declare class SubscriptionResource extends BaseResource {
     private static readonly PATH_INQUIRY;
     private static readonly PATH_CANCEL;
     private static readonly PATH_MANAGE;
+    private static readonly PATH_UPDATE;
     private static readonly PATH_CHANGE;
     private static readonly PATH_CHANGE_INQUIRY;
     /**
@@ -1660,6 +1863,18 @@ declare class SubscriptionResource extends BaseResource {
      * @throws WaffoUnknownStatusError for network errors
      */
     manage(params: ManageSubscriptionParams, options?: RequestOptions): Promise<ApiResponse<ManageSubscriptionData>>;
+    /**
+     * Updates an existing subscription amount or scheduled period amounts.
+     *
+     * Provide either subscriptionRequest or subscriptionId. At least one of amount
+     * or productInfo.scheduledAmounts must be provided.
+     *
+     * @param params - Subscription update parameters
+     * @param options - Optional request options
+     * @returns API response with update result
+     * @throws WaffoUnknownStatusError for network errors
+     */
+    update(params: UpdateSubscriptionParams, options?: RequestOptions): Promise<ApiResponse<UpdateSubscriptionData>>;
     /**
      * Changes (upgrades/downgrades) an existing subscription.
      *
@@ -1763,6 +1978,8 @@ interface InquiryRefundData {
     userCurrency?: string;
     finalDealAmount?: string;
     remainingRefundAmount?: string;
+    merchantUserId?: string;
+    subscriptionInfo?: SubscriptionInfo;
     userInfo?: RefundUserInfo;
     refundCompletedAt?: string;
     refundSource?: string;
@@ -1832,7 +2049,6 @@ interface InquiryMerchantConfigData {
  */
 interface InquiryPayMethodConfigParams {
     merchantId: string;
-    payMethodType?: string;
     [key: string]: unknown;
 }
 /**
@@ -1840,21 +2056,33 @@ interface InquiryPayMethodConfigParams {
  */
 interface InquiryPayMethodConfigData {
     merchantId?: string;
-    payMethods?: PayMethodInfo[];
+    payMethodDetails?: PayMethodDetail[];
     [key: string]: unknown;
 }
 /**
- * Pay method information.
+ * Pay method detail.
  */
-interface PayMethodInfo {
-    payMethodType?: string;
+interface PayMethodDetail {
+    productName?: string;
     payMethodName?: string;
-    payMethodStatus?: string;
-    supportedCurrencies?: string[];
-    minAmount?: string;
-    maxAmount?: string;
+    country?: string;
+    currentStatus?: string;
+    fixedMaintenanceRules?: FixedMaintenanceRule[];
+    fixedMaintenanceTimezone?: string;
+    [key: string]: unknown;
+}
+/**
+ * Fixed maintenance rule for a payment method.
+ */
+interface FixedMaintenanceRule {
+    startRule?: string;
+    endRule?: string;
     [key: string]: unknown;
 }
+/**
+ * @deprecated Use PayMethodDetail.
+ */
+type PayMethodInfo = PayMethodDetail;
 
 /**
  * Merchant config resource for querying merchant configuration.
@@ -1898,8 +2126,8 @@ declare class MerchantConfigResource extends BaseResource {
  *
  * if (response.isSuccess()) {
  *   const data = response.getData();
- *   data?.payMethods?.forEach(method => {
- *     console.log(`${method.payMethodName}: ${method.payMethodStatus}`);
+ *   data?.payMethodDetails?.forEach(method => {
+ *     console.log(`${method.payMethodName}: ${method.currentStatus}`);
  *   });
  * }
  * ```
@@ -2160,7 +2388,7 @@ declare class WaffoUnknownStatusError extends Error {
  * Result of key pair generation.
  */
 interface KeyPairResult {
-    /** Base64 encoded PKCS8 private key */
+    /** Base64 encoded PKCS8 DER private key */
     privateKey: string;
     /** Base64 encoded X509 public key */
     publicKey: string;
@@ -2169,16 +2397,16 @@ interface KeyPairResult {
  * Signs data using RSA-SHA256.
  *
  * @param data - The data to sign (UTF-8 string)
- * @param base64PrivateKey - Base64 encoded PKCS8 private key
+ * @param privateKeyInput - Base64 encoded PKCS8 DER private key or unencrypted PKCS8 PEM private key
  * @returns Base64 encoded signature
- * @throws WaffoError if signing fails (S0003)
+ * @throws WaffoError if the private key is invalid (S0007) or signing fails (S0003)
  *
  * @example
  * ```typescript
  * const signature = sign('{"amount":"100.00"}', privateKey);
  * ```
  */
-declare function sign(data: string, base64PrivateKey: string): string;
+declare function sign(data: string, privateKeyInput: string): string;
 /**
  * Verifies a signature using RSA-SHA256.
  *
@@ -2197,12 +2425,12 @@ declare function sign(data: string, base64PrivateKey: string): string;
  */
 declare function verify(data: string, base64Signature: string, base64PublicKey: string): boolean;
 /**
- * Validates a Base64 encoded PKCS8 private key.
+ * Validates a Base64 encoded PKCS8 DER private key or unencrypted PKCS8 PEM 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
+ * @param base64PrivateKey - Base64 encoded PKCS8 DER private key or unencrypted PKCS8 PEM private key
  * @throws WaffoError if the key is invalid (S0007)
  *
  * @example
@@ -2253,4 +2481,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 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 PaymentNotificationResult, type PeriodType, type ProductInfo, type RefundNotification, type RefundNotificationResult, type RefundOrderData, type RefundOrderParams, RefundResource, type RefundStatus$1 as RefundStatus, type RefundUserInfo, type RequestOptions, type RiskData, RsaUtils, type SubscriptionInfo, type SubscriptionManageAction, type SubscriptionMerchantInfo, type SubscriptionNotificationResult, type SubscriptionPaymentInfo, 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 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 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, SubscriptionResource, type SubscriptionScheduledAmount, type SubscriptionStatus, type SubscriptionStatusNotification, type SubscriptionUpdateProductInfo, type SubscriptionUserInfo, type UpdateSubscriptionData, type UpdateSubscriptionParams, type UserInfo, Waffo, type WaffoConfig, WaffoConfigDefaults, WaffoError, WaffoErrorCode, WaffoHttpClient, type WaffoLogger, WaffoUnknownStatusError, WebhookEventType, WebhookHandler, type WebhookResult };