tsapay-sdk 1.0.0 → 1.0.2

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 { TsaPayClient } from 'tsapay-sdk';
+
+const tsapay = new TsaPayClient({
+  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/dist/index.d.ts

@@ -1,4 +1,4 @@
-export interface TinguilinConfig {
+export interface TsaPayConfig {
     apiKey: string;
     baseUrl?: string;
 }
@@ -36,15 +36,15 @@ export interface ListPaymentsResponse {
     payments: PaymentResponse["payment"][];
     total: number;
 }
-export declare class TinguilinError extends Error {
+export declare class TsaPayError extends Error {
     status: number;
     data: any;
     constructor(status: number, message: string, data?: any);
 }
-export declare class TinguilinClient {
+export declare class TsaPayClient {
     private apiKey;
     private baseUrl;
-    constructor(config: TinguilinConfig);
+    constructor(config: TsaPayConfig);
     private request;
     /**
      * Create a new Mobile Money payment.

package/dist/index.js

@@ -3,20 +3,20 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TinguilinClient = exports.TinguilinError = void 0;
+exports.TsaPayClient = exports.TsaPayError = void 0;
 const crypto_1 = __importDefault(require("crypto"));
-class TinguilinError extends Error {
+class TsaPayError extends Error {
     status;
     data;
     constructor(status, message, data) {
         super(message);
-        this.name = "TinguilinError";
+        this.name = "TsaPayError";
         this.status = status;
         this.data = data;
     }
 }
-exports.TinguilinError = TinguilinError;
-class TinguilinClient {
+exports.TsaPayError = TsaPayError;
+class TsaPayClient {
     apiKey;
     baseUrl;
     constructor(config) {
@@ -41,7 +41,7 @@ class TinguilinClient {
             catch (e) {
                 errorData = { message: response.statusText };
             }
-            throw new TinguilinError(response.status, errorData.message || `API error ${response.status}`, errorData);
+            throw new TsaPayError(response.status, errorData.message || `API error ${response.status}`, errorData);
         }
         return response.json();
     }
@@ -102,4 +102,4 @@ class TinguilinClient {
         return expectedSignature === signatureHeader;
     }
 }
-exports.TinguilinClient = TinguilinClient;
+exports.TsaPayClient = TsaPayClient;

package/examples/create_payment.ts

@@ -1,7 +1,7 @@
-import { TinguilinClient } from "../src/index";
+import { TsaPayClient } from "../src/index";
 
 async function run() {
-  const client = new TinguilinClient({
+  const client = new TsaPayClient({
     apiKey: "sk_test_1234567890", // Replace with your real test key
     baseUrl: "http://localhost:8080/v1" // Use production URL when going live
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tsapay-sdk",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "The official Node.js / TypeScript SDK for TsaPay Mobile Money Aggregator",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -8,7 +8,16 @@
     "build": "tsc",
     "prepublishOnly": "npm run build"
   },
-  "keywords": ["tsapay", "mobile-money", "payments", "mtn", "orange-money", "cemac", "cameroon", "fintech"],
+  "keywords": [
+    "tsapay",
+    "mobile-money",
+    "payments",
+    "mtn",
+    "orange-money",
+    "cemac",
+    "cameroon",
+    "fintech"
+  ],
   "author": "TsaPay",
   "license": "MIT",
   "type": "commonjs",

package/src/index.ts

@@ -1,6 +1,6 @@
-import crypto from "crypto";
+import crypto from "crypto";
 
-export interface TinguilinConfig {
+export interface TsaPayConfig {
   apiKey: string;
   baseUrl?: string;
 }
@@ -43,23 +43,23 @@ export interface ListPaymentsResponse {
   total: number;
 }
 
-export class TinguilinError extends Error {
+export class TsaPayError extends Error {
   public status: number;
   public data: any;
 
   constructor(status: number, message: string, data?: any) {
     super(message);
-    this.name = "TinguilinError";
+    this.name = "TsaPayError";
     this.status = status;
     this.data = data;
   }
 }
 
-export class TinguilinClient {
+export class TsaPayClient {
   private apiKey: string;
   private baseUrl: string;
 
-  constructor(config: TinguilinConfig) {
+  constructor(config: TsaPayConfig) {
     if (!config.apiKey) {
       throw new Error("TsaPay API key is required");
     }
@@ -84,7 +84,7 @@ export class TinguilinClient {
       } catch (e) {
         errorData = { message: response.statusText };
       }
-      throw new TinguilinError(
+      throw new TsaPayError(
         response.status,
         errorData.message || `API error ${response.status}`,
         errorData