@zed-io/wam-payment-sdk/README.md

Official WAM Payment SDK for creating and signing payment links

# WAM Payment SDK

Official Node.js SDK for integrating WAM payment links into your applications. This SDK provides a simple and secure way to generate signed payment links for the WAM payment platform.

## Features

- ✅ Generate signed payment links
- ✅ HMAC-SHA256 signature generation
- ✅ Input validation and error handling
- ✅ TypeScript support with full type definitions
- ✅ Works in Node.js environments
- ✅ Lightweight with no external dependencies

## Installation

```bash
npm install wam-payment-sdk
```

Or with yarn:

```bash
yarn add wam-payment-sdk
```

## Quick Start

```javascript
const { WamPaymentSDK } = require('wam-payment-sdk');

// Initialize the SDK
const wamPayment = new WamPaymentSDK({
  businessId: 'your-business-id',
  privateKey: 'your-private-key'
});

// Generate a payment link
const paymentLink = wamPayment.generatePaymentLink({
  amount: 5000, // Amount in cents (50.00)
  currency: 'TTD',
  reference: 'ORDER-123',
  returnUrl: 'https://your-site.com/success'
});

console.log('Payment URL:', paymentLink.url);
```

## TypeScript Usage

```typescript
import { WamPaymentSDK, PaymentLinkParams } from 'wam-payment-sdk';

const wamPayment = new WamPaymentSDK({
  businessId: process.env.WAM_BUSINESS_ID!,
  privateKey: process.env.WAM_PRIVATE_KEY!
});

const params: PaymentLinkParams = {
  amount: 5000,
  currency: 'TTD',
  reference: 'ORDER-123',
  returnUrl: 'https://your-site.com/success'
};

const paymentLink = wamPayment.generatePaymentLink(params);
```

## Configuration

### WamPaymentConfig

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `businessId` | string | Yes | Your WAM business ID |
| `privateKey` | string | Yes | Your WAM private key for signing |

**Note**: The payment gateway URL is automatically configured based on environment variables or defaults to production.

### PaymentLinkParams

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `amount` | number | Yes | Payment amount in cents |
| `currency` | 'TTD' \| 'USD' | Yes | Currency code (TTD or USD only) |
| `reference` | string | Yes | Unique reference for the payment |
| `returnUrl` | string | No | URL to redirect after payment |

## API Reference

### `generatePaymentLink(params: PaymentLinkParams): PaymentLinkResponse`

Generates a signed payment link for WAM payment processing.

**Parameters:**
- `params`: Payment parameters object

**Returns:**
- `PaymentLinkResponse` object with:
  - `url`: Complete payment URL
  - `signature`: HMAC-SHA256 signature
  - `timestamp`: Generation timestamp
  - `payload`: Signed payload string

**Throws:**
- `WamPaymentError`: If validation fails or signing error occurs

### `getConfig(): Omit<WamPaymentConfig, 'privateKey'>`

Returns the current configuration without the private key.

## Error Handling

The SDK provides comprehensive error handling with detailed validation messages:

```javascript
try {
  const paymentLink = wamPayment.generatePaymentLink({
    amount: -100, // Invalid amount
    currency: 'INVALID', // Invalid currency
    reference: '', // Empty reference
  });
} catch (error) {
  if (error instanceof WamPaymentError) {
    console.error('Error code:', error.code);
    console.error('Error message:', error.message);
    
    if (error.validationErrors) {
      error.validationErrors.forEach(validationError => {
        console.error(`${validationError.field}: ${validationError.message}`);
      });
    }
  }
}
```

### Error Codes

- `INVALID_CONFIG`: Invalid SDK configuration
- `INVALID_AMOUNT`: Invalid payment amount
- `INVALID_CURRENCY`: Invalid currency code
- `INVALID_REFERENCE`: Invalid reference
- `INVALID_RETURN_URL`: Invalid return URL
- `SIGNING_ERROR`: Error during signature generation
- `VALIDATION_ERROR`: General validation error

## Environment Variables

For security, it's recommended to use environment variables:

```bash
WAM_BUSINESS_ID=your-business-id
WAM_PRIVATE_KEY=your-private-key
```

### Payment Gateway URL Configuration

The SDK automatically selects the payment gateway URL based on:

1. **WAM_PAY_URL** environment variable (highest priority)
2. **NODE_ENV** or **WAM_ENVIRONMENT** environment variables:
   - `development` → `https://wam-payments-v2-git-development-zed-io.vercel.app`
   - `staging` → `https://pay-staging.wam.money`
   - `production` (default) → `https://pay.wam.money`

```bash
# Override URL directly
WAM_PAY_URL=https://custom-pay.wam.money

# Or use environment-based selection
NODE_ENV=staging
# or
WAM_ENVIRONMENT=staging
```

## Examples

Check out the `examples/` directory for complete implementation examples:

- [Basic Usage](examples/basic-usage.js) - Simple JavaScript example
- [TypeScript Usage](examples/typescript-usage.ts) - TypeScript with Next.js
- [Express Server](examples/express-server.js) - Complete Express.js integration

## Security Best Practices

1. **Never expose your private key** in client-side code
2. **Use environment variables** for sensitive configuration
3. **Validate all inputs** before generating payment links
4. **Use HTTPS** for all payment-related communications
5. **Store private keys securely** using secrets management

## Testing

Run the test suite:

```bash
npm test
```

Run with coverage:

```bash
npm run test:coverage
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for your changes
5. Run the test suite
6. Submit a pull request

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Support

For support and questions:
- Create an issue on GitHub
- Contact the WAM development team
- Check the WAM documentation

## Changelog

### 1.0.0
- Initial release
- Basic payment link generation
- TypeScript support
- Comprehensive validation
- Error handling