@waffo/waffo-node 2.0.4 → 2.2.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
 
@@ -229,7 +229,7 @@ app.post('/webhook', express.raw({ type: 'application/json' }), async (req, res)
 
   const webhookHandler = waffo.webhook()
     .onPayment((notification) => {
-      console.log('Payment received:', notification.acquiringOrderId);
+      console.log('Payment received:', notification.result?.acquiringOrderId);
     });
 
   const result = await webhookHandler.handleWebhook(body, signature);
@@ -283,7 +283,7 @@ export class PaymentController {
   ) {
     const webhookHandler = this.waffo.webhook()
       .onPayment((notification) => {
-        console.log('Payment received:', notification.acquiringOrderId);
+        console.log('Payment received:', notification.result?.acquiringOrderId);
       });
 
     const result = await webhookHandler.handleWebhook(body, signature);
@@ -318,7 +318,7 @@ fastify.post('/webhook', async (request, reply) => {
 
   const webhookHandler = waffo.webhook()
     .onPayment((notification) => {
-      console.log('Payment received:', notification.acquiringOrderId);
+      console.log('Payment received:', notification.result?.acquiringOrderId);
     });
 
   const result = await webhookHandler.handleWebhook(body, signature);
@@ -688,28 +688,28 @@ const waffo = new Waffo({ /* config */ });
 const webhookHandler = waffo.webhook()
   .onPayment((notification) => {
     console.log('Payment notification received:');
-    console.log('  Acquiring Order ID:', notification.acquiringOrderId);
-    console.log('  Order Status:', notification.orderStatus);
-    console.log('  Payment Amount:', notification.orderAmount);
-    console.log('  Payment Currency:', notification.orderCurrency);
+    console.log('  Acquiring Order ID:', notification.result?.acquiringOrderId);
+    console.log('  Order Status:', notification.result?.orderStatus);
+    console.log('  Payment Amount:', notification.result?.orderAmount);
+    console.log('  Payment Currency:', notification.result?.orderCurrency);
 
     // Tip: First verify amount and currency match your records
     // Then handle based on orderStatus
 
-    if (notification.orderStatus === 'PAY_SUCCESS') {
+    if (notification.result?.orderStatus === 'PAY_SUCCESS') {
       // Payment successful - update order status, deliver goods, etc.
     }
   })
   .onRefund((notification) => {
-    console.log('Refund notification:', notification.acquiringRefundOrderId);
+    console.log('Refund notification:', notification.result?.acquiringRefundOrderId);
     // Handle refund notification
   })
   .onSubscriptionStatus((notification) => {
     console.log('Subscription status notification:');
-    console.log('  Subscription ID:', notification.subscriptionId);
-    console.log('  Subscription Status:', notification.subscriptionStatus);
+    console.log('  Subscription ID:', notification.result?.subscriptionId);
+    console.log('  Subscription Status:', notification.result?.subscriptionStatus);
 
-    switch (notification.subscriptionStatus) {
+    switch (notification.result?.subscriptionStatus) {
       case 'ACTIVE':
         // Subscription activated - grant membership privileges
         break;
@@ -731,28 +731,28 @@ const webhookHandler = waffo.webhook()
     }
   })
   .onSubscriptionPeriodChanged((notification) => {
-    console.log('Subscription period changed:', notification.subscriptionId);
+    console.log('Subscription period changed:', notification.result?.subscriptionId);
     // Key fields to track:
-    // - notification.period: Current period number
-    // - notification.nextChargeAt: Next billing time
-    // - notification.subscriptionStatus: Subscription status
-    // - notification.orderStatus: Current billing order status (SUCCESS/FAILED)
-    // - notification.orderAmount: Billing amount
-    // - notification.orderCurrency: Billing currency
+    // - notification.result?.period: Current period number
+    // - notification.result?.nextChargeAt: Next billing time
+    // - notification.result?.subscriptionStatus: Subscription status
+    // - notification.result?.orderStatus: Current billing order status (SUCCESS/FAILED)
+    // - notification.result?.orderAmount: Billing amount
+    // - notification.result?.orderCurrency: Billing currency
   })
   .onSubscriptionChange((notification) => {
     console.log('Subscription change notification:');
-    console.log('  Change Request ID:', notification.subscriptionRequest);
-    console.log('  Change Status:', notification.subscriptionChangeStatus);
-    console.log('  Origin Subscription:', notification.originSubscriptionId);
-    console.log('  New Subscription:', notification.subscriptionId);
+    console.log('  Change Request ID:', notification.result?.subscriptionRequest);
+    console.log('  Change Status:', notification.result?.subscriptionChangeStatus);
+    console.log('  Origin Subscription:', notification.result?.originSubscriptionId);
+    console.log('  New Subscription:', notification.result?.subscriptionId);
 
-    if (notification.subscriptionChangeStatus === 'SUCCESS') {
+    if (notification.result?.subscriptionChangeStatus === 'SUCCESS') {
       // Subscription change successful
       // - Original subscription is now MERCHANT_CANCELLED
       // - New subscription is now ACTIVE
       // Update user's subscription level accordingly
-    } else if (notification.subscriptionChangeStatus === 'CLOSED') {
+    } else if (notification.result?.subscriptionChangeStatus === 'CLOSED') {
       // Subscription change failed/closed
       // Original subscription remains unchanged
     }
@@ -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