@waffo/waffo-node 2.0.2

package/README.md

@@ -0,0 +1,580 @@
+# Waffo PSP SDK for Node.js
+
+Official Node.js SDK for Waffo PSP (Payment Service Provider) acquiring services. This SDK provides secure API communication with RSA signing and comprehensive type definitions for payment acquiring operations.
+
+**Language**: [English](./README.md) | [中文](./README.zh-CN.md) | [日本語](./README.ja.md)
+
+## Quick Start
+
+```typescript
+import {
+  Waffo,
+  Environment,
+  CurrencyCode,
+  ProductName,
+} from '@waffo/waffo-node';
+
+// 1. Initialize SDK
+const waffo = new Waffo({
+  apiKey: 'your-api-key',
+  privateKey: 'your-base64-encoded-private-key',
+  environment: Environment.SANDBOX,
+});
+
+// 2. Create an order
+const result = await waffo.order.create({
+  paymentRequestId: 'REQ_001',
+  merchantOrderId: 'ORDER_001',
+  orderCurrency: CurrencyCode.IDR,
+  orderAmount: '100000',
+  orderDescription: 'Product purchase',
+  notifyUrl: 'https://merchant.com/notify',
+  merchantInfo: { merchantId: 'your-merchant-id' },
+  userInfo: {
+    userId: 'user_001',
+    userEmail: 'user@example.com',
+  },
+  paymentInfo: {
+    productName: ProductName.ONE_TIME_PAYMENT,
+    payMethodType: 'EWALLET',
+    payMethodName: 'DANA',
+  },
+});
+
+// 3. Handle response
+if (result.success) {
+  console.log('Order created:', result.data);
+  // Redirect user to payment page
+  if (result.data?.orderAction) {
+    const action = JSON.parse(result.data.orderAction);
+    window.location.href = action.webUrl;
+  }
+}
+```
+
+> **Tip**: Need to generate a new RSA key pair? Use `Waffo.generateKeyPair()` to create one:
+> ```typescript
+> const keyPair = Waffo.generateKeyPair();
+> console.log(keyPair.privateKey); // Keep this secure, use for SDK initialization
+> console.log(keyPair.publicKey);  // Share this with Waffo
+> ```
+
+## Features
+
+- RSA-2048 request signing and response verification
+- Full TypeScript support with comprehensive type definitions
+- Zero production dependencies (uses only Node.js built-in `crypto` module)
+- Support for Sandbox and Production environments
+- Dual ESM/CommonJS module support
+- Order management (create, query, cancel, refund, capture)
+- Subscription management (create, query, cancel, manage)
+- Refund status inquiry
+- Merchant configuration inquiry (transaction limits, daily limits)
+- Payment method configuration inquiry (availability, maintenance schedules)
+- Webhook handler with automatic signature verification and event routing
+- Webhook signature verification utilities
+- Direct HTTP client access for custom API requests
+- Automatic timestamp defaults for request parameters
+
+## Automatic Timestamp Defaults
+
+All timestamp parameters (`orderRequestedAt`, `requestedAt`, `captureRequestedAt`) are **optional** and will automatically default to the current time (`new Date().toISOString()`) if not provided:
+
+```typescript
+// Timestamp is automatically set to current time
+await waffo.order.create({
+  paymentRequestId: 'REQ_001',
+  merchantOrderId: 'ORDER_001',
+  // ... other required fields
+  // orderRequestedAt is automatically set
+});
+
+// Or explicitly provide a custom timestamp
+await waffo.order.create({
+  paymentRequestId: 'REQ_001',
+  merchantOrderId: 'ORDER_001',
+  orderRequestedAt: '2025-01-01T00:00:00.000Z', // Custom timestamp
+  // ... other required fields
+});
+```
+
+This applies to:
+- `CreateOrderParams.orderRequestedAt`
+- `CancelOrderParams.orderRequestedAt`
+- `RefundOrderParams.requestedAt`
+- `CaptureOrderParams.captureRequestedAt`
+- `CreateSubscriptionParams.requestedAt`
+- `CancelSubscriptionParams.requestedAt`
+
+## Installation
+
+```bash
+npm install @waffo/waffo-node
+```
+
+## Usage
+
+### Initialize the SDK
+
+```typescript
+import { Waffo, Environment } from '@waffo/waffo-node';
+
+const waffo = new Waffo({
+  apiKey: 'your-api-key',
+  privateKey: 'your-base64-encoded-private-key',
+  environment: Environment.SANDBOX, // or Environment.PRODUCTION
+});
+```
+
+### Generate RSA Key Pair
+
+```typescript
+import { Waffo } from '@waffo/waffo-node';
+
+const keyPair = Waffo.generateKeyPair();
+console.log(keyPair.privateKey); // Base64 encoded PKCS8 private key
+console.log(keyPair.publicKey);  // Base64 encoded X509 public key
+```
+
+### Create an Order
+
+```typescript
+const result = await waffo.order.create({
+  paymentRequestId: 'REQ_001',
+  merchantOrderId: 'ORDER_001',
+  orderCurrency: CurrencyCode.IDR,
+  orderAmount: '100000',
+  orderDescription: 'Product purchase',
+  notifyUrl: 'https://merchant.com/notify',
+  merchantInfo: {
+    merchantId: 'your-merchant-id',
+  },
+  userInfo: {
+    userId: 'user_001',
+    userEmail: 'user@example.com',
+    userPhone: '+62-81234567890',
+    userTerminal: UserTerminalType.WEB,
+  },
+  paymentInfo: {
+    productName: ProductName.ONE_TIME_PAYMENT,
+    payMethodType: 'EWALLET',
+    payMethodName: 'DANA',
+  },
+});
+
+if (result.success) {
+  console.log('Order created:', result.data);
+} else {
+  console.error('Error:', result.error);
+}
+```
+
+### Query Order Status
+
+```typescript
+const result = await waffo.order.inquiry({
+  acquiringOrderId: 'A202512230000001',
+  // or use paymentRequestId: 'REQ_001'
+});
+
+if (result.success) {
+  console.log('Order status:', result.data?.orderStatus);
+}
+```
+
+### Cancel an Order
+
+```typescript
+const result = await waffo.order.cancel({
+  acquiringOrderId: 'A202512230000001',
+  merchantId: 'your-merchant-id',
+  // orderRequestedAt is optional, defaults to current time
+});
+```
+
+### Refund an Order
+
+```typescript
+const result = await waffo.order.refund({
+  refundRequestId: 'REFUND_001',
+  acquiringOrderId: 'A202512230000001',
+  merchantId: 'your-merchant-id',
+  refundAmount: '50000',
+  refundReason: 'Customer requested refund',
+  refundNotifyUrl: 'https://merchant.com/refund-notify',
+  // requestedAt is optional, defaults to current time
+});
+```
+
+### Query Refund Status
+
+```typescript
+const result = await waffo.refund.inquiry({
+  refundRequestId: 'REFUND_001',
+  // or use acquiringRefundOrderId: 'R202512230000001'
+});
+
+if (result.success) {
+  console.log('Refund status:', result.data?.refundStatus);
+}
+```
+
+### Capture a Pre-authorized Payment
+
+```typescript
+const result = await waffo.order.capture({
+  acquiringOrderId: 'A202512230000001',
+  merchantId: 'your-merchant-id',
+  captureAmount: '100000',
+  // captureRequestedAt is optional, defaults to current time
+});
+```
+
+### Create a Subscription
+
+```typescript
+const result = await waffo.subscription.create({
+  subscriptionRequest: 'SUB_REQ_001',
+  merchantSubscriptionId: 'MERCHANT_SUB_001',
+  currency: CurrencyCode.PHP,
+  amount: '100',
+  productInfo: {
+    periodType: PeriodType.MONTHLY,
+    periodInterval: '1',
+    numberOfPeriod: '12',
+    description: 'Monthly subscription',
+  },
+  paymentInfo: {
+    productName: ProductName.SUBSCRIPTION,
+    payMethodType: 'EWALLET',
+    payMethodName: 'GCASH',
+  },
+  merchantInfo: { merchantId: 'your-merchant-id' },
+  userInfo: {
+    userId: 'user_001',
+    userEmail: 'user@example.com',
+  },
+  goodsInfo: {
+    goodsId: 'GOODS_001',
+    goodsName: 'Premium Plan',
+  },
+  notifyUrl: 'https://merchant.com/subscription/notify',
+  // requestedAt is optional, defaults to current time
+});
+
+if (result.success) {
+  console.log('Subscription created:', result.data);
+  // Redirect user to complete subscription signing
+  if (result.data?.subscriptionAction?.webUrl) {
+    window.location.href = result.data.subscriptionAction.webUrl;
+  }
+}
+```
+
+### Query Subscription Status
+
+```typescript
+const result = await waffo.subscription.inquiry({
+  merchantId: 'your-merchant-id',
+  subscriptionId: 'SUB_202512230000001',
+  paymentDetails: '1', // Include payment history
+});
+
+if (result.success) {
+  console.log('Subscription status:', result.data?.subscriptionStatus);
+}
+```
+
+### Cancel a Subscription
+
+```typescript
+const result = await waffo.subscription.cancel({
+  merchantId: 'your-merchant-id',
+  subscriptionId: 'SUB_202512230000001',
+  // requestedAt is optional, defaults to current time
+});
+```
+
+### Get Subscription Management URL
+
+```typescript
+const result = await waffo.subscription.manage({
+  subscriptionId: 'SUB_202512230000001',
+  // or use subscriptionRequest: 'SUB_REQ_001'
+});
+
+if (result.success) {
+  console.log('Management URL:', result.data?.managementUrl);
+  console.log('Expires at:', result.data?.expiresAt);
+  // Redirect user to manage their subscription
+  window.location.href = result.data?.managementUrl;
+}
+```
+
+### Query Merchant Configuration
+
+```typescript
+const result = await waffo.merchantConfig.inquiry({
+  merchantId: 'your-merchant-id',
+});
+
+if (result.success) {
+  console.log('Daily Limit:', result.data?.totalDailyLimit);
+  console.log('Remaining Daily Limit:', result.data?.remainingDailyLimit);
+  console.log('Transaction Limit:', result.data?.transactionLimit);
+}
+```
+
+### Query Payment Method Configuration
+
+```typescript
+const result = await waffo.payMethodConfig.inquiry({
+  merchantId: 'your-merchant-id',
+});
+
+if (result.success) {
+  result.data?.payMethodDetails.forEach(method => {
+    console.log(`${method.payMethodName}: ${method.currentStatus === '1' ? 'Available' : 'Unavailable'}`);
+    if (method.fixedMaintenanceRules) {
+      console.log('Maintenance periods:', method.fixedMaintenanceRules);
+    }
+  });
+}
+```
+
+### Webhook Handler
+
+The SDK provides a built-in webhook handler that automatically handles signature verification, event routing, and response signing:
+
+```typescript
+// In your webhook handler
+app.post('/webhook', async (req, res) => {
+  const signature = req.headers['x-signature'] as string;
+  const body = JSON.stringify(req.body);
+
+  const result = await waffo.webhook.handle(body, signature, {
+    onPayment: async ({ notification }) => {
+      console.log('Payment status:', notification.result.orderStatus);
+      // Process payment notification
+    },
+    onRefund: async ({ notification }) => {
+      console.log('Refund status:', notification.result.refundStatus);
+      // Process refund notification
+    },
+    onSubscriptionStatus: async ({ notification }) => {
+      console.log('Subscription status:', notification.result.subscriptionStatus);
+      // Process subscription status change
+    },
+    onSubscriptionPayment: async ({ notification }) => {
+      console.log('Subscription payment:', notification.result.orderStatus);
+      // Process subscription recurring payment
+    },
+    onError: async (error) => {
+      console.error('Webhook error:', error.message);
+    },
+  });
+
+  return res.json(result.response);
+});
+```
+
+### Manual Webhook Signature Verification
+
+For more control, you can use the low-level webhook utilities:
+
+```typescript
+import {
+  verifyWebhookSignature,
+  buildSuccessResponse,
+  buildFailedResponse,
+  isPaymentNotification,
+  isRefundNotification,
+} from '@waffo/waffo-node';
+
+// In your webhook handler
+app.post('/webhook', (req, res) => {
+  const signature = req.headers['x-signature'];
+  const body = JSON.stringify(req.body);
+
+  // Verify signature
+  const verifyResult = verifyWebhookSignature(body, signature, waffoPublicKey);
+
+  if (!verifyResult.valid) {
+    return res.json(buildFailedResponse('Signature verification failed', merchantPrivateKey));
+  }
+
+  // Handle notification based on type
+  const notification = verifyResult.notification;
+
+  if (isPaymentNotification(notification)) {
+    // Handle payment notification
+    console.log('Payment status:', notification.result.orderStatus);
+  } else if (isRefundNotification(notification)) {
+    // Handle refund notification
+    console.log('Refund status:', notification.result.refundStatus);
+  }
+
+  // Return success response
+  return res.json(buildSuccessResponse(merchantPrivateKey));
+});
+```
+
+### Direct HTTP Client Access
+
+For custom API requests not covered by the SDK methods:
+
+```typescript
+const response = await waffo.httpClient.post<CustomResponseType>('/custom/endpoint', {
+  body: { key: 'value' }
+});
+
+if (response.success) {
+  console.log(response.data);
+}
+```
+
+## Configuration Options
+
+| Option | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `apiKey` | string | Yes | - | API key provided by Waffo |
+| `privateKey` | string | Yes | - | Base64 encoded PKCS8 private key |
+| `waffoPublicKey` | string | No | Built-in | Custom Waffo public key for response verification |
+| `environment` | Environment | No | PRODUCTION | API environment (SANDBOX or PRODUCTION) |
+| `timeout` | number | No | 30000 | Request timeout in milliseconds |
+| `logger` | Logger | No | - | Logger instance for debugging (can use `console`) |
+
+## API Response Format
+
+All API methods return an `ApiResponse<T>` object:
+
+```typescript
+interface ApiResponse<T> {
+  success: boolean;      // Whether the request was successful
+  statusCode: number;    // HTTP status code
+  data?: T;              // Response data (on success)
+  error?: string;        // Error message (on failure)
+}
+```
+
+## Type Definitions
+
+The SDK exports comprehensive TypeScript types including:
+
+- `Environment` - SDK environment enum
+- `CountryCode` - ISO 3166-1 alpha-3 country codes
+- `CurrencyCode` - ISO 4217 currency codes
+- `ProductName` - Payment product type enum (ONE_TIME_PAYMENT, SUBSCRIPTION)
+- `payMethodType` - Payment method category (string: "EWALLET", "CREDITCARD", "BANKTRANSFER", "ONLINE_BANKING", "DIGITAL_BANKING", "OTC", "DEBITCARD")
+- `payMethodName` - Specific payment method (string: "OVO", "DANA", "GOPAY", "GCASH", "CC_VISA", "CC_MASTERCARD", "VA_BCA", "VA_BNI", etc.)
+- `OrderStatus` - Order status enum (PAY_IN_PROGRESS, AUTHORIZATION_REQUIRED, PAY_SUCCESS, ORDER_CLOSE, etc.)
+- `RefundStatus` - Refund status enum (REFUND_IN_PROGRESS, ORDER_PARTIALLY_REFUNDED, ORDER_FULLY_REFUNDED, ORDER_REFUND_FAILED)
+- `SubscriptionStatus` - Subscription status enum (AUTHORIZATION_REQUIRED, ACTIVE, PAUSED, MERCHANT_CANCELLED, etc.)
+- `PeriodType` - Subscription period type enum (DAILY, WEEKLY, MONTHLY, YEARLY)
+- `UserTerminalType` - User terminal type enum (WEB, APP, IN_WALLET_APP, IN_MINI_PROGRAM)
+- Request/Response interfaces for all API operations
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build (generates both ESM and CJS)
+npm run build
+
+# Run tests
+npm test
+
+# Run tests with coverage
+npm run test:coverage
+
+# Run tests in watch mode
+npm run test:watch
+
+# Lint code
+npm run lint
+
+# Lint and auto-fix
+npm run lint:fix
+
+# Format code
+npm run format
+
+# Check formatting
+npm run format:check
+```
+
+### Code Quality
+
+This project uses:
+- **ESLint** - Code linting with TypeScript support
+- **Prettier** - Code formatting
+- **Husky** - Git hooks
+- **lint-staged** - Run linters on staged files
+
+Pre-commit hooks automatically run ESLint and Prettier on staged `.ts` files.
+
+### Running E2E Tests
+
+E2E tests require Waffo sandbox credentials. The SDK supports multiple merchant configurations for different test scenarios and provides comprehensive test coverage based on the official Waffo test cases document.
+
+```bash
+# Copy the template and fill in your credentials
+cp .env.template .env
+# Edit .env with your credentials
+```
+
+Environment variables:
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `WAFFO_PUBLIC_KEY` | No | Waffo public key for signature verification (shared) |
+| `ACQUIRING_MERCHANT_ID` | Yes* | Merchant ID for payment/order tests |
+| `ACQUIRING_API_KEY` | Yes* | API key for payment/order tests |
+| `ACQUIRING_MERCHANT_PRIVATE_KEY` | Yes* | Private key for payment/order tests |
+| `SUBSCRIPTION_MERCHANT_ID` | Yes** | Merchant ID for subscription tests |
+| `SUBSCRIPTION_API_KEY` | Yes** | API key for subscription tests |
+| `SUBSCRIPTION_MERCHANT_PRIVATE_KEY` | Yes** | Private key for subscription tests |
+
+\* Required for running acquiring/payment E2E tests
+\** Required for running subscription E2E tests
+
+**E2E Test Coverage:**
+
+| Module | Test Cases |
+|--------|------------|
+| Create Order | Payment success/failure, channel rejection (C0005), idempotency error (A0011), system error (C0001), unknown status (E0001) |
+| Inquiry Order | Query before/after payment |
+| Cancel Order | Cancel before payment, channel not supported (A0015), already paid (A0013) |
+| Refund Order | Full/partial refund, parameter validation (A0003), refund rules (A0014) |
+| Create Subscription | Subscription success/failure, next period payment simulation |
+| Cancel Subscription | Merchant-initiated cancellation |
+| Webhook Notifications | Signature verification for payment, refund, and subscription notifications |
+
+**Sandbox Amount Triggers:**
+
+| Amount Pattern | Error Code | Description |
+|----------------|------------|-------------|
+| 9, 90, 990, 1990, 19990 | C0005 | Channel rejection |
+| 9.1, 91, 991, 1991, 19991 | C0001 | System error |
+| 9.2, 92, 992, 1992, 19992 | E0001 | Unknown status |
+| 9.3, 93, 993, 1993, 19993 | C0001 | Cancel system error |
+| 9.4, 94, 994, 1994, 19994 | E0001 | Cancel unknown status |
+| 9.5, 95, 995, 1995, 19995 | C0001 | Refund system error |
+| 9.6, 96, 996, 1996, 199996 | E0001 | Refund unknown status |
+
+```bash
+# Run all tests
+npm test
+```
+
+## Build Output
+
+The SDK is built using [tsup](https://tsup.egoist.dev/) and outputs:
+
+| File | Format | Description |
+|------|--------|-------------|
+| `dist/index.js` | CommonJS | For `require()` imports |
+| `dist/index.mjs` | ESM | For `import` statements |
+| `dist/index.d.ts` | TypeScript | Type declarations |