tsapay-sdk 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,67 @@
+export interface TinguilinConfig {
+    apiKey: string;
+    baseUrl?: string;
+}
+export interface CreatePaymentParams {
+    amount: number;
+    currency?: string;
+    provider: "mtn_momo" | "orange_money";
+    phoneNumber: string;
+    description?: string;
+    reference?: string;
+    callbackUrl?: string;
+    metadata?: Record<string, string>;
+}
+export interface PaymentResponse {
+    payment: {
+        id: string;
+        merchant_id: string;
+        amount: number;
+        currency: string;
+        provider: string;
+        phone_number: string;
+        status: "created" | "pending" | "success" | "failed" | "expired";
+        description?: string;
+        reference?: string;
+        created_at: string;
+        updated_at: string;
+    };
+}
+export interface ListPaymentsParams {
+    status?: string;
+    limit?: number;
+    offset?: number;
+}
+export interface ListPaymentsResponse {
+    payments: PaymentResponse["payment"][];
+    total: number;
+}
+export declare class TinguilinError extends Error {
+    status: number;
+    data: any;
+    constructor(status: number, message: string, data?: any);
+}
+export declare class TinguilinClient {
+    private apiKey;
+    private baseUrl;
+    constructor(config: TinguilinConfig);
+    private request;
+    /**
+     * Create a new Mobile Money payment.
+     * This sends a USSD push to the user's phone.
+     */
+    createPayment(params: CreatePaymentParams, idempotencyKey?: string): Promise<PaymentResponse>;
+    /**
+     * Retrieve a payment by its ID.
+     */
+    getPayment(paymentId: string): Promise<PaymentResponse>;
+    /**
+     * List payments with optional filtering.
+     */
+    listPayments(params?: ListPaymentsParams): Promise<ListPaymentsResponse>;
+    /**
+     * Verify an incoming webhook signature using your webhook secret.
+     * Helps ensure the webhook actually came from TsaPay.
+     */
+    verifyWebhookSignature(payload: string, signatureHeader: string, webhookSecret: string): boolean;
+}

package/dist/index.js

@@ -0,0 +1,105 @@
+"use strict";
+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;
+const crypto_1 = __importDefault(require("crypto"));
+class TinguilinError extends Error {
+    status;
+    data;
+    constructor(status, message, data) {
+        super(message);
+        this.name = "TinguilinError";
+        this.status = status;
+        this.data = data;
+    }
+}
+exports.TinguilinError = TinguilinError;
+class TinguilinClient {
+    apiKey;
+    baseUrl;
+    constructor(config) {
+        if (!config.apiKey) {
+            throw new Error("TsaPay API key is required");
+        }
+        this.apiKey = config.apiKey;
+        // Default to the local gateway if not provided
+        this.baseUrl = config.baseUrl || "http://localhost:8080/v1";
+    }
+    async request(endpoint, options = {}) {
+        const url = `${this.baseUrl}${endpoint}`;
+        const headers = new Headers(options.headers || {});
+        headers.set("Authorization", `Bearer ${this.apiKey}`);
+        headers.set("Content-Type", "application/json");
+        const response = await fetch(url, { ...options, headers });
+        if (!response.ok) {
+            let errorData;
+            try {
+                errorData = await response.json();
+            }
+            catch (e) {
+                errorData = { message: response.statusText };
+            }
+            throw new TinguilinError(response.status, errorData.message || `API error ${response.status}`, errorData);
+        }
+        return response.json();
+    }
+    /**
+     * Create a new Mobile Money payment.
+     * This sends a USSD push to the user's phone.
+     */
+    async createPayment(params, idempotencyKey) {
+        const key = idempotencyKey || crypto_1.default.randomUUID();
+        const body = {
+            amount: params.amount,
+            currency: params.currency || "XAF",
+            provider: params.provider,
+            phone_number: params.phoneNumber,
+            description: params.description,
+            reference: params.reference,
+            callback_url: params.callbackUrl,
+            metadata: params.metadata,
+        };
+        return this.request("/payments", {
+            method: "POST",
+            headers: {
+                "Idempotency-Key": key,
+            },
+            body: JSON.stringify(body),
+        });
+    }
+    /**
+     * Retrieve a payment by its ID.
+     */
+    async getPayment(paymentId) {
+        return this.request(`/payments/${paymentId}`);
+    }
+    /**
+     * List payments with optional filtering.
+     */
+    async listPayments(params) {
+        const urlParams = new URLSearchParams();
+        if (params?.status)
+            urlParams.set("status", params.status);
+        if (params?.limit)
+            urlParams.set("limit", params.limit.toString());
+        if (params?.offset)
+            urlParams.set("offset", params.offset.toString());
+        const queryString = urlParams.toString();
+        const endpoint = queryString ? `/payments?${queryString}` : "/payments";
+        return this.request(endpoint);
+    }
+    /**
+     * Verify an incoming webhook signature using your webhook secret.
+     * Helps ensure the webhook actually came from TsaPay.
+     */
+    verifyWebhookSignature(payload, signatureHeader, webhookSecret) {
+        const expectedSignature = crypto_1.default
+            .createHmac("sha256", webhookSecret)
+            .update(payload)
+            .digest("hex");
+        return expectedSignature === signatureHeader;
+    }
+}
+exports.TinguilinClient = TinguilinClient;

package/examples/create_payment.ts

@@ -0,0 +1,30 @@
+import { TinguilinClient } from "../src/index";
+
+async function run() {
+  const client = new TinguilinClient({
+    apiKey: "sk_test_1234567890", // Replace with your real test key
+    baseUrl: "http://localhost:8080/v1" // Use production URL when going live
+  });
+
+  try {
+    console.log("Initiating payment...");
+    
+    // Create a payment using a Sandbox test number
+    const result = await client.createPayment({
+      amount: 15000,
+      currency: "XAF",
+      provider: "mtn_momo",
+      phoneNumber: "+237600000001", // Instant success number in sandbox
+      description: "Order #999"
+    });
+
+    console.log("Payment created successfully:", result.payment.id);
+    console.log("Status:", result.payment.status);
+
+  } catch (error: any) {
+    console.error("Payment failed:");
+    console.error(error.message);
+  }
+}
+
+run();

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "tsapay-sdk",
+  "version": "1.0.0",
+  "description": "The official Node.js / TypeScript SDK for TsaPay Mobile Money Aggregator",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["tsapay", "mobile-money", "payments", "mtn", "orange-money", "cemac", "cameroon", "fintech"],
+  "author": "TsaPay",
+  "license": "MIT",
+  "type": "commonjs",
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "typescript": "^6.0.3"
+  }
+}

package/src/index.ts

@@ -0,0 +1,158 @@
+import crypto from "crypto";
+
+export interface TinguilinConfig {
+  apiKey: string;
+  baseUrl?: string;
+}
+
+export interface CreatePaymentParams {
+  amount: number;
+  currency?: string;
+  provider: "mtn_momo" | "orange_money";
+  phoneNumber: string;
+  description?: string;
+  reference?: string;
+  callbackUrl?: string;
+  metadata?: Record<string, string>;
+}
+
+export interface PaymentResponse {
+  payment: {
+    id: string;
+    merchant_id: string;
+    amount: number;
+    currency: string;
+    provider: string;
+    phone_number: string;
+    status: "created" | "pending" | "success" | "failed" | "expired";
+    description?: string;
+    reference?: string;
+    created_at: string;
+    updated_at: string;
+  };
+}
+
+export interface ListPaymentsParams {
+  status?: string;
+  limit?: number;
+  offset?: number;
+}
+
+export interface ListPaymentsResponse {
+  payments: PaymentResponse["payment"][];
+  total: number;
+}
+
+export class TinguilinError extends Error {
+  public status: number;
+  public data: any;
+
+  constructor(status: number, message: string, data?: any) {
+    super(message);
+    this.name = "TinguilinError";
+    this.status = status;
+    this.data = data;
+  }
+}
+
+export class TinguilinClient {
+  private apiKey: string;
+  private baseUrl: string;
+
+  constructor(config: TinguilinConfig) {
+    if (!config.apiKey) {
+      throw new Error("TsaPay API key is required");
+    }
+    this.apiKey = config.apiKey;
+    // Default to the local gateway if not provided
+    this.baseUrl = config.baseUrl || "http://localhost:8080/v1";
+  }
+
+  private async request<T>(endpoint: string, options: RequestInit = {}): Promise<T> {
+    const url = `${this.baseUrl}${endpoint}`;
+    
+    const headers = new Headers(options.headers || {});
+    headers.set("Authorization", `Bearer ${this.apiKey}`);
+    headers.set("Content-Type", "application/json");
+
+    const response = await fetch(url, { ...options, headers });
+
+    if (!response.ok) {
+      let errorData;
+      try {
+        errorData = await response.json();
+      } catch (e) {
+        errorData = { message: response.statusText };
+      }
+      throw new TinguilinError(
+        response.status,
+        errorData.message || `API error ${response.status}`,
+        errorData
+      );
+    }
+
+    return response.json() as Promise<T>;
+  }
+
+  /**
+   * Create a new Mobile Money payment.
+   * This sends a USSD push to the user's phone.
+   */
+  public async createPayment(params: CreatePaymentParams, idempotencyKey?: string): Promise<PaymentResponse> {
+    const key = idempotencyKey || crypto.randomUUID();
+
+    const body = {
+      amount: params.amount,
+      currency: params.currency || "XAF",
+      provider: params.provider,
+      phone_number: params.phoneNumber,
+      description: params.description,
+      reference: params.reference,
+      callback_url: params.callbackUrl,
+      metadata: params.metadata,
+    };
+
+    return this.request<PaymentResponse>("/payments", {
+      method: "POST",
+      headers: {
+        "Idempotency-Key": key,
+      },
+      body: JSON.stringify(body),
+    });
+  }
+
+  /**
+   * Retrieve a payment by its ID.
+   */
+  public async getPayment(paymentId: string): Promise<PaymentResponse> {
+    return this.request<PaymentResponse>(`/payments/${paymentId}`);
+  }
+
+  /**
+   * List payments with optional filtering.
+   */
+  public async listPayments(params?: ListPaymentsParams): Promise<ListPaymentsResponse> {
+    const urlParams = new URLSearchParams();
+    if (params?.status) urlParams.set("status", params.status);
+    if (params?.limit) urlParams.set("limit", params.limit.toString());
+    if (params?.offset) urlParams.set("offset", params.offset.toString());
+
+    const queryString = urlParams.toString();
+    const endpoint = queryString ? `/payments?${queryString}` : "/payments";
+
+    return this.request<ListPaymentsResponse>(endpoint);
+  }
+
+  /**
+   * Verify an incoming webhook signature using your webhook secret.
+   * Helps ensure the webhook actually came from TsaPay.
+   */
+  public verifyWebhookSignature(payload: string, signatureHeader: string, webhookSecret: string): boolean {
+    const expectedSignature = crypto
+      .createHmac("sha256", webhookSecret)
+      .update(payload)
+      .digest("hex");
+    
+    return expectedSignature === signatureHeader;
+  }
+}

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "CommonJS",
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "types": ["node"],
+    "lib": ["ES2022", "DOM"]
+  },
+  "include": ["src/**/*"]
+}