@patalink/node-api-client 1.0.1 → 1.0.3

package/README.md

@@ -1 +1,623 @@
-# patalink_node_api_client
+Here's a professional, detailed documentation for your `@patlink/node-api-client` package:
+
+```markdown
+# @patlink/node-api-client - Official PataLink API Client
+
+**Server-side API client for Node.js. Accept payments programmatically with automatic encryption.**
+
+[![npm version](https://badge.fury.io/js/@patlink%2Fapi-client.svg)](https://badge.fury.io/js/@patlink%2Fapi-client)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node Version](https://img.shields.io/node/v/@patlink/node-api-client)](https://nodejs.org/)
+
+---
+
+## 📖 Table of Contents
+
+- [Quick Start](#rocket-quick-start)
+- [Installation](#package-installation)
+- [Configuration](#gear-configuration)
+- [API Reference](#api-reference)
+- [Usage Examples](#usage-examples)
+- [Error Handling](#error-handling)
+- [TypeScript Support](#typescript-support)
+- [Browser Support](#browser-support)
+- [FAQ](#faq)
+
+---
+
+## 🚀 Quick Start
+
+Add payment processing to your Node.js backend in 3 simple steps:
+
+### Step 1: Install the package
+
+```bash
+npm install @patlink/node-api-client
+```
+
+### Step 2: Initialize the client
+
+```javascript
+import { createClient } from '@patlink/node-api-client';
+
+const client = createClient({
+    apiKey: 'pk_live_abc123...',
+    encryptionKey: 'xK8j3Hd9Fq2Wm5R...',
+    baseUrl: 'https://api.patalink.me'
+});
+```
+
+### Step 3: Create a payment
+
+```javascript
+const payment = await client.createPayment({
+    amount: 25000,
+    paymentMethod: 'MTN',
+    phoneNumber: '0788888888',
+    customerName: 'John Doe',
+    customerEmail: 'john@example.com'
+});
+
+console.log('Transaction ID:', payment.transactionId);
+```
+
+---
+
+## 📦 Installation
+
+### Node.js (Recommended)
+
+```bash
+npm install @patlink/node-api-client
+```
+
+### With yarn
+
+```bash
+yarn add @patlink/node-api-client
+```
+
+### With pnpm
+
+```bash
+pnpm add @patlink/node-api-client
+```
+
+### Requirements
+
+- Node.js 16.x or higher
+- TypeScript 4.x or higher (optional)
+
+---
+
+## ⚙️ Configuration
+
+### Client Configuration Options
+
+```typescript
+interface ClientConfig {
+    apiKey: string;        // Required: Your API key from dashboard
+    encryptionKey: string; // Required: Your encryption key from dashboard  
+    baseUrl: string;       // Required: API endpoint URL
+    timeout?: number;      // Optional: Request timeout in ms (default: 30000)
+}
+```
+
+### Getting Your Keys
+
+1. Sign up at [dashboard.patalink.me](https://dashboard.patalink.me)
+2. Navigate to **Settings** → **API Keys**
+3. Click **Generate API Key** and **Generate Encryption Key**
+4. Copy both keys to your environment variables
+
+### Environment Setup (.env)
+
+```env
+PATALINK_API_KEY=pk_live_abc123def456...
+PATALINK_ENCRYPTION_KEY=xK8j3Hd9Fq2Wm5R...
+PATALINK_BASE_URL=https://api.patalink.me
+```
+
+```javascript
+import { createClient } from '@patlink/node-api-client';
+
+const client = createClient({
+    apiKey: process.env.PATALINK_API_KEY,
+    encryptionKey: process.env.PATALINK_ENCRYPTION_KEY,
+    baseUrl: process.env.PATALINK_BASE_URL,
+    timeout: 30000  // optional
+});
+```
+
+---
+
+## 📚 API Reference
+
+### `createPayment(request)`
+
+Create a new payment transaction.
+
+**Parameters:**
+
+```typescript
+interface PaymentRequest {
+    amount: number;                    // Required: Amount in RWF (min 100, max 2,000,000 for mobile money)
+    currency?: string;                 // Optional: Currency code (default: 'RWF')
+    paymentMethod: 'MTN' | 'Airtel' | 'PesaPal';  // Required: Payment method
+    phoneNumber?: string;              // Required for MTN/Airtel
+    customerName?: string;             // Optional: Customer's full name
+    customerEmail?: string;            // Optional: Customer's email address
+}
+```
+
+**Returns:**
+
+```typescript
+interface PaymentResponse {
+    transactionId: string;             // Unique transaction identifier
+    status: 'pending' | 'success' | 'failed';  // Current payment status
+    providerRef?: string;              // Payment provider reference
+    redirectUrl?: string;              // For PesaPal card payments
+    message?: string;                  // Additional response message
+}
+```
+
+**Example:**
+
+```javascript
+// MTN Mobile Money
+const payment = await client.createPayment({
+    amount: 25000,
+    paymentMethod: 'MTN',
+    phoneNumber: '0788888888',
+    customerName: 'John Doe',
+    customerEmail: 'john@example.com'
+});
+
+// Card Payment (PesaPal)
+const cardPayment = await client.createPayment({
+    amount: 50000,
+    paymentMethod: 'PesaPal',
+    customerName: 'Jane Smith',
+    customerEmail: 'jane@example.com'
+});
+
+// Handle redirect for card payments
+if (cardPayment.redirectUrl) {
+    // Redirect user to payment page
+    res.redirect(cardPayment.redirectUrl);
+}
+```
+
+---
+
+### `getTransactionStatus(transactionId)`
+
+Get the current status of a transaction.
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `transactionId` | `string` | Transaction ID from `createPayment` response |
+
+**Returns:**
+
+```typescript
+interface TransactionStatus {
+    id: string;                        // Transaction ID
+    status: 'pending' | 'success' | 'failed';  // Current status
+    amount: number;                    // Transaction amount
+    currency: string;                  // Currency code
+    paymentMethod: string;             // Payment method used
+    createdAt: string;                 // ISO timestamp of creation
+    completedAt?: string;              // ISO timestamp of completion
+    providerRef?: string;              // Provider reference
+}
+```
+
+**Example:**
+
+```javascript
+const status = await client.getTransactionStatus('txn_abc123');
+
+if (status.status === 'success') {
+    console.log('Payment completed at:', status.completedAt);
+} else if (status.status === 'pending') {
+    console.log('Still waiting for confirmation...');
+} else {
+    console.log('Payment failed');
+}
+```
+
+---
+
+## 💡 Usage Examples
+
+### Webhook Endpoint (Express.js)
+
+```javascript
+import express from 'express';
+import { createClient } from '@patlink/node-api-client';
+
+const app = express();
+const client = createClient({
+    apiKey: process.env.PATALINK_API_KEY,
+    encryptionKey: process.env.PATALINK_ENCRYPTION_KEY,
+    baseUrl: process.env.PATALINK_BASE_URL
+});
+
+app.post('/api/create-payment', async (req, res) => {
+    try {
+        const { amount, phoneNumber, customerName, customerEmail } = req.body;
+        
+        const payment = await client.createPayment({
+            amount,
+            paymentMethod: 'MTN',
+            phoneNumber,
+            customerName,
+            customerEmail
+        });
+        
+        res.json({
+            success: true,
+            transactionId: payment.transactionId,
+            status: payment.status
+        });
+    } catch (error) {
+        res.status(400).json({
+            success: false,
+            error: error.message
+        });
+    }
+});
+
+app.get('/api/payment-status/:transactionId', async (req, res) => {
+    try {
+        const status = await client.getTransactionStatus(req.params.transactionId);
+        res.json(status);
+    } catch (error) {
+        res.status(404).json({ error: error.message });
+    }
+});
+
+app.listen(3000, () => {
+    console.log('Server running on port 3000');
+});
+```
+
+### Polling Implementation
+
+```javascript
+async function pollPaymentStatus(transactionId, maxAttempts = 30, interval = 2000) {
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        console.log(`Checking status (attempt ${attempt}/${maxAttempts})...`);
+        
+        const status = await client.getTransactionStatus(transactionId);
+        
+        if (status.status === 'success') {
+            console.log('✅ Payment successful!');
+            return status;
+        }
+        
+        if (status.status === 'failed') {
+            console.log('❌ Payment failed!');
+            return status;
+        }
+        
+        // Wait before next attempt
+        await new Promise(resolve => setTimeout(resolve, interval));
+    }
+    
+    throw new Error('Payment timeout - still pending after maximum attempts');
+}
+
+// Usage
+const transaction = await client.createPayment({
+    amount: 25000,
+    paymentMethod: 'MTN',
+    phoneNumber: '0788888888'
+});
+
+const result = await pollPaymentStatus(transaction.transactionId);
+console.log('Final status:', result.status);
+```
+
+### Next.js API Route
+
+```typescript
+// app/api/payments/route.ts
+import { NextResponse } from 'next/server';
+import { createClient } from '@patlink/node-api-client';
+
+const client = createClient({
+    apiKey: process.env.PATALINK_API_KEY!,
+    encryptionKey: process.env.PATALINK_ENCRYPTION_KEY!,
+    baseUrl: process.env.PATALINK_BASE_URL!
+});
+
+export async function POST(request: Request) {
+    try {
+        const body = await request.json();
+        
+        const payment = await client.createPayment({
+            amount: body.amount,
+            paymentMethod: body.paymentMethod,
+            phoneNumber: body.phoneNumber,
+            customerName: body.customerName,
+            customerEmail: body.customerEmail
+        });
+        
+        return NextResponse.json(payment);
+    } catch (error: any) {
+        return NextResponse.json(
+            { error: error.message },
+            { status: 400 }
+        );
+    }
+}
+
+export async function GET(request: Request) {
+    const { searchParams } = new URL(request.url);
+    const transactionId = searchParams.get('transactionId');
+    
+    if (!transactionId) {
+        return NextResponse.json(
+            { error: 'transactionId is required' },
+            { status: 400 }
+        );
+    }
+    
+    try {
+        const status = await client.getTransactionStatus(transactionId);
+        return NextResponse.json(status);
+    } catch (error: any) {
+        return NextResponse.json(
+            { error: error.message },
+            { status: 404 }
+        );
+    }
+}
+```
+
+### Bulk Payment Processing
+
+```javascript
+async function processBulkPayments(payments) {
+    const results = [];
+    
+    for (const payment of payments) {
+        try {
+            const result = await client.createPayment(payment);
+            results.push({
+                success: true,
+                transactionId: result.transactionId,
+                amount: payment.amount,
+                phoneNumber: payment.phoneNumber
+            });
+        } catch (error) {
+            results.push({
+                success: false,
+                error: error.message,
+                amount: payment.amount,
+                phoneNumber: payment.phoneNumber
+            });
+        }
+        
+        // Rate limiting - avoid overwhelming the API
+        await new Promise(resolve => setTimeout(resolve, 500));
+    }
+    
+    return results;
+}
+
+// Usage
+const payments = [
+    { amount: 10000, paymentMethod: 'MTN', phoneNumber: '0788888888' },
+    { amount: 25000, paymentMethod: 'Airtel', phoneNumber: '0789999999' },
+    { amount: 5000, paymentMethod: 'MTN', phoneNumber: '0787777777' }
+];
+
+const results = await processBulkPayments(payments);
+console.log(results);
+```
+
+---
+
+## 🚨 Error Handling
+
+### Common Errors
+
+```javascript
+try {
+    const payment = await client.createPayment({
+        amount: 500,
+        paymentMethod: 'MTN',
+        phoneNumber: '0788888888'
+    });
+} catch (error) {
+    switch (error.message) {
+        case 'Amount must be at least 100 RWF':
+            // Handle minimum amount error
+            break;
+        case 'Mobile Money limit is 2,000,000 RWF':
+            // Handle maximum amount error
+            break;
+        case 'phoneNumber is required for mobile money payments':
+            // Handle missing phone number
+            break;
+        case 'Request timeout':
+            // Handle timeout - implement retry logic
+            break;
+        default:
+            // Handle other errors
+            console.error('Payment failed:', error.message);
+    }
+}
+```
+
+### Retry Logic with Exponential Backoff
+
+```javascript
+async function createPaymentWithRetry(request, maxRetries = 3) {
+    let lastError;
+    
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+        try {
+            return await client.createPayment(request);
+        } catch (error) {
+            lastError = error;
+            
+            if (attempt === maxRetries) break;
+            
+            // Exponential backoff: 1s, 2s, 4s
+            const delay = Math.pow(2, attempt - 1) * 1000;
+            console.log(`Retry ${attempt}/${maxRetries} after ${delay}ms...`);
+            await new Promise(resolve => setTimeout(resolve, delay));
+        }
+    }
+    
+    throw lastError;
+}
+
+// Usage
+const payment = await createPaymentWithRetry({
+    amount: 25000,
+    paymentMethod: 'MTN',
+    phoneNumber: '0788888888'
+});
+```
+
+---
+
+## 🔷 TypeScript Support
+
+Full TypeScript support with complete type definitions.
+
+### Type Definitions
+
+```typescript
+import { createClient, PaymentRequest, PaymentResponse, TransactionStatus } from '@patlink/node-api-client';
+
+const client = createClient({
+    apiKey: process.env.PATALINK_API_KEY!,
+    encryptionKey: process.env.PATALINK_ENCRYPTION_KEY!,
+    baseUrl: process.env.PATALINK_BASE_URL!
+});
+
+async function processPayment(request: PaymentRequest): Promise<PaymentResponse> {
+    const payment = await client.createPayment(request);
+    return payment;
+}
+
+async function checkStatus(transactionId: string): Promise<TransactionStatus> {
+    const status = await client.getTransactionStatus(transactionId);
+    return status;
+}
+```
+
+---
+
+## 🌐 Browser Support
+
+This package is designed for **Node.js server-side** use only. For browser/client-side integration, use our HTML web component:
+
+```html
+<script type="module">
+    import 'https://esm.sh/@patlink/html-payment-modal';
+</script>
+
+<payment-modal
+    base-url="https://api.patalink.me"
+    api-key="your_api_key"
+    encryption-key="your_encryption_key"
+></payment-modal>
+```
+
+---
+
+## ❓ FAQ
+
+### Can I use this in the browser?
+
+**No.** This package uses server-side encryption and should only be used in Node.js environments. For browser payments, use our HTML web component instead.
+
+### How do I get my API and encryption keys?
+
+1. Sign up at [dashboard.patalink.me](https://dashboard.patalink.me)
+2. Go to **Settings** → **API Keys**
+3. Click **Generate API Key** and **Generate Encryption Key**
+4. Store both keys securely in environment variables
+
+### What's the difference between API key and encryption key?
+
+- **API Key**: Identifies your account (authentication)
+- **Encryption Key**: Encrypts payment data (security)
+
+Both are required and should be kept secret.
+
+### What payment methods are supported?
+
+- MTN Mobile Money
+- Airtel Money  
+- Credit/Debit Cards (via PesaPal)
+
+### What's the minimum and maximum payment amount?
+
+- **Minimum**: 100 RWF
+- **Maximum for Mobile Money**: 2,000,000 RWF
+- **Maximum for Cards**: No limit (subject to card issuer)
+
+### How do I handle card payment redirects?
+
+For PesaPal card payments, the response includes a `redirectUrl`. You need to redirect your user to this URL to complete the payment.
+
+```javascript
+const payment = await client.createPayment({
+    amount: 50000,
+    paymentMethod: 'PesaPal',
+    customerEmail: 'customer@example.com'
+});
+
+if (payment.redirectUrl) {
+    res.redirect(payment.redirectUrl);
+}
+```
+
+### Is the encryption automatic?
+
+**Yes.** The client automatically encrypts all payment data before sending to our API. You don't need to implement any encryption logic.
+
+### Can I test without real money?
+
+**Yes.** Use your test keys from the dashboard (they start with `pk_test_`). Test transactions are processed in sandbox mode.
+
+### What happens if a request times out?
+
+The client will throw a timeout error after the configured timeout period (default 30 seconds). You should implement retry logic with exponential backoff.
+
+### How do I know if a payment is complete?
+
+1. Check the `status` field in the `createPayment` response
+2. For pending payments, use `getTransactionStatus` to poll
+3. Or set up webhooks to receive real-time updates
+
+---
+
+## 📞 Support
+
+- 📖 [Full API Documentation](https://docs.patalink.me)
+- 💬 [Discord Community](https://discord.gg/patlink)
+- 🐛 [GitHub Issues](https://github.com/patlink/api-client/issues)
+- ✉️ [support@patalink.me](mailto:support@patalink.me)
+
+---
+
+## 📄 License
+
+MIT © [PataLink](https://patalink.me)
+
+---
+
+**Secure, encrypted payments for your Node.js backend.** 🚀
+```

package/dist/index.js

@@ -39,6 +39,7 @@ var PataLinkClient = class {
   constructor(config) {
     if (!config.apiKey) throw new Error("API key is required");
     if (!config.encryptionKey) throw new Error("Encryption key is required");
+    if (!config.baseUrl) throw new Error("Base url is required");
     this.apiKey = config.apiKey;
     this.baseUrl = config.baseUrl;
     this.encryptionKey = config.encryptionKey;

package/dist/index.mjs

@@ -4,6 +4,7 @@ var PataLinkClient = class {
   constructor(config) {
     if (!config.apiKey) throw new Error("API key is required");
     if (!config.encryptionKey) throw new Error("Encryption key is required");
+    if (!config.baseUrl) throw new Error("Base url is required");
     this.apiKey = config.apiKey;
     this.baseUrl = config.baseUrl;
     this.encryptionKey = config.encryptionKey;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patalink/node-api-client",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Official PataLink API client - Simple, secure payment integration",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",