tsapay-sdk 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,106 @@
+# TsaPay Node.js SDK
+
+![NPM Version](https://img.shields.io/npm/v/tsapay-sdk)
+![License](https://img.shields.io/npm/l/tsapay-sdk)
+
+The official Node.js / TypeScript SDK for **TsaPay**, the universal Mobile Money aggregator for the CEMAC zone (MTN MoMo, Orange Money).
+
+Integrate Mobile Money payments into your e-commerce platform, mobile app backend, or SaaS in just a few lines of code.
+
+## 📦 Installation
+
+```bash
+npm install tsapay-sdk
+# or
+yarn add tsapay-sdk
+# or
+pnpm add tsapay-sdk
+```
+
+## 🚀 Quick Start
+
+### 1. Initialization
+
+First, get your API Key from your TsaPay Merchant Dashboard.
+
+```typescript
+import { TinguilinClient } from 'tsapay-sdk';
+
+const tsapay = new TinguilinClient({
+  apiKey: 'sk_test_YOUR_API_KEY_HERE',
+  // baseUrl is optional, defaults to the production gateway
+});
+```
+
+### 2. Create a Payment
+
+Initiate a USSD push directly to the customer's phone.
+
+```typescript
+try {
+  const response = await tsapay.createPayment({
+    amount: 1500,
+    currency: 'XAF', // Optional, defaults to XAF
+    provider: 'mtn_momo', // or 'orange_money'
+    phoneNumber: '+237670000000', // Customer's phone number
+    description: 'Order #12345',
+    reference: 'REF-12345', // Your internal order reference
+    callbackUrl: 'https://your-site.com/api/webhooks/tsapay', // Where we should send the webhook
+  });
+
+  console.log('Payment initiated successfully:', response.payment.id);
+  console.log('Status:', response.payment.status); // 'pending'
+} catch (error) {
+  console.error('Payment failed:', error.message);
+}
+```
+
+### 3. Check Payment Status
+
+```typescript
+const response = await tsapay.getPayment('pay_123456789');
+console.log('Current status:', response.payment.status);
+```
+
+### 4. Verify Webhooks
+
+When a payment succeeds or fails, TsaPay will send a POST request to your `callbackUrl`. To ensure this request actually came from TsaPay, you must verify the signature using your Webhook Secret.
+
+```typescript
+import express from 'express';
+
+const app = express();
+const WEBHOOK_SECRET = 'whsec_YOUR_WEBHOOK_SECRET';
+
+app.post('/api/webhooks/tsapay', express.raw({ type: 'application/json' }), (req, res) => {
+  const signature = req.headers['x-tsapay-signature'] as string;
+  const payload = req.body.toString();
+
+  // Verify the signature
+  const isValid = tsapay.verifyWebhookSignature(payload, signature, WEBHOOK_SECRET);
+
+  if (!isValid) {
+    return res.status(400).send('Invalid signature');
+  }
+
+  const event = JSON.parse(payload);
+  
+  if (event.event_type === 'payment.success') {
+    console.log('Payment successful for:', event.data.reference);
+    // TODO: Fulfill the order in your database
+  }
+
+  res.send('Webhook received');
+});
+```
+
+## 📚 Features
+
+- **Zero dependencies** (uses native `fetch`)
+- **Full TypeScript support** with strict types
+- **Built-in idempotency** to prevent duplicate charges
+- **Secure webhook verification** helper included
+
+## 📄 License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tsapay-sdk",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "The official Node.js / TypeScript SDK for TsaPay Mobile Money Aggregator",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",