@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 @zed-io/wam-payment-sdk
```

Or with yarn:

```bash
yarn add @zed-io/wam-payment-sdk
```

## Quick Start

```javascript
const { WamPaymentSDK } = require('@zed-io/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 TTD)
  reference: 'ORDER-123',
  returnUrl: 'https://your-site.com/success'
});

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

### Using Staging Environment

For testing and development, use the staging environment:

```javascript
const wamPayment = new WamPaymentSDK({
  businessId: 'your-business-id',
  privateKey: 'your-private-key',
  environment: 'staging'
});

const paymentLink = wamPayment.generatePaymentLink({
  amount: 5000,
  reference: 'ORDER-123',
  returnUrl: 'https://your-site.com/success'
});

console.log(paymentLink.url);
// https://staging.billing.wam.money/pay/external/generic/your-business-id?amount=5000&currency=TTD&reference=ORDER-123&signature=...
```

## TypeScript Usage

```typescript
import { WamPaymentSDK, PaymentLinkParams } from '@zed-io/wam-payment-sdk';

const wamPayment = new WamPaymentSDK({
  businessId: process.env.WAM_BUSINESS_ID!,
  privateKey: process.env.WAM_PRIVATE_KEY!,
  environment: 'staging'  // Optional: 'production' | 'staging' | 'development'
});

const params: PaymentLinkParams = {
  amount: 5000,
  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 |
| `environment` | string | No | Environment: `'production'` \| `'staging'` \| `'development'`. Defaults to `'production'` |

### Environment URLs

| Environment | Base URL |
|-------------|----------|
| `production` (default) | `https://billing.wam.money` |
| `staging` | `https://staging.billing.wam.money` |
| `development` | `https://staging.billing.wam.money` |

**Note**: If no `environment` is specified, the SDK defaults to `production`.

### PaymentLinkParams

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `amount` | number | Yes | Payment amount in cents (TTD) |
| `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
  - `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_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 for your credentials:

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

## 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.10
- Removed currency option (TTD is now hardcoded)

### 1.0.9
- Removed USD currency support (TTD only)

### 1.0.8
- Simplified environment configuration (pass `environment` directly in SDK init)
- Updated documentation with complete staging example

### 1.0.7
- Added explicit `environment` config option (`'production'` | `'staging'` | `'development'`)
- Staging environment uses `staging.billing.wam.money`

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