warimcp 0.0.1

package/.env.example

@@ -0,0 +1,19 @@
+# WariMCP — Environment Variables
+# Copy this file to .env and fill in your credentials
+
+# CinetPay (Phase 1)
+CINETPAY_API_KEY=
+CINETPAY_SITE_ID=
+
+# Wave (Phase 1)
+WAVE_API_KEY=
+
+# Hub2 / Ecobank unified gateway (Phase 2)
+HUB2_API_KEY=
+
+# PAPSS Pan-African (Phase 3)
+PAPSS_API_KEY=
+
+# Server config
+WARIMCP_PORT=3000
+WARIMCP_ENV=development

package/Dockerfile

@@ -0,0 +1,14 @@
+FROM node:20-alpine
+
+WORKDIR /app
+
+COPY package*.json ./
+RUN npm install --production
+
+COPY . .
+
+USER node
+
+EXPOSE 3000
+
+CMD ["node", "src/index.js"]

package/NPM_SETUP.md

@@ -0,0 +1,76 @@
+# WariMCP — npm Publish Setup
+
+## One-Time Setup
+
+### Step 1 — Create an npm Account
+1. Go to https://www.npmjs.com/signup
+2. Create an account with:
+   - Username: (your preferred handle, e.g. `bigabou`)
+   - Email: your main email
+   - Password: strong, unique
+3. Verify your email from the confirmation message
+
+### Step 2 — Enable 2FA (Required for Publishing)
+1. Log into npmjs.com
+2. Click your avatar → **Account** → **Two-Factor Authentication**
+3. Choose **Auth and Writes** (required for publish)
+4. Scan the QR code with Google Authenticator or Authy
+5. Save your backup codes securely
+
+### Step 3 — Log In from Terminal
+
+```bash
+cd ~/automation/projects/warimcp
+npm login
+```
+
+You'll be prompted for:
+- Username
+- Password
+- Email
+- OTP (from your authenticator app)
+
+Verify login:
+```bash
+npm whoami
+# should return your npm username
+```
+
+### Step 4 — Publish the Package
+
+```bash
+npm publish --access=public
+```
+
+> **Note:** The package name `warimcp` was confirmed available as of March 1, 2026.
+
+### Step 5 — Verify on npm
+
+Visit: https://www.npmjs.com/package/warimcp
+
+You should see the package live within ~2 minutes.
+
+---
+
+## Future Publishes
+
+Once logged in, Claude Code can handle all future publishes automatically:
+
+```bash
+# Bump version (patch / minor / major)
+npm version patch   # 0.0.1 → 0.0.2
+npm version minor   # 0.0.1 → 0.1.0
+
+# Publish
+npm publish --access=public
+```
+
+Or just tell Claude: "Publish warimcp version X.Y.Z" and it will handle the version bump and publish.
+
+---
+
+## Important Notes
+
+- Do NOT run `npm publish` without bumping the version first — npm will reject duplicate versions
+- The `--access=public` flag is required for the first publish of a scoped or new package
+- npm sessions expire — re-run `npm login` if you get auth errors

package/README.md

@@ -0,0 +1,151 @@
+# WariMCP
+
+> **The AI-native payment layer for West Africa**
+
+[![npm version](https://img.shields.io/npm/v/warimcp.svg?style=flat-square)](https://www.npmjs.com/package/warimcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](https://github.com/Bigabou007-dev/warimcp/blob/main/CONTRIBUTING.md)
+
+---
+
+## Overview
+
+WariMCP is an **MCP (Model Context Protocol) server** that gives AI agents and LLMs a unified, production-ready interface to all major West African payment rails.
+
+Instead of integrating CinetPay, Wave, Hub2/Ecobank, and PAPSS one by one — WariMCP exposes them all through a single, consistent API that any Claude, GPT, or custom AI agent can call natively.
+
+**Built for:**
+- AI agents that need to initiate, track, or refund payments in West Africa
+- Developers building fintech products across UEMOA and pan-African corridors
+- Agencies that need a white-label payment middleware layer
+
+---
+
+## Supported Payment Rails
+
+| Provider | Region | Coverage | Phase |
+|---|---|---|---|
+| **CinetPay** | UEMOA | Orange Money, MTN, Wave, Moov, Visa/MC | Phase 1 |
+| **Wave** | Côte d'Ivoire, Sénégal | Wave mobile wallet | Phase 1 |
+| **Hub2 / Ecobank** | UEMOA (unified) | 200M+ mobile wallets, single API | Phase 2 |
+| **PAPSS** | Pan-African | CI ↔ Kenya corridor, 160+ banks, local currency | Phase 3 |
+
+---
+
+## Installation
+
+```bash
+npm install warimcp
+```
+
+### Environment Variables
+
+Copy `.env.example` and fill in your credentials:
+
+```bash
+cp .env.example .env
+```
+
+```env
+CINETPAY_API_KEY=your_cinetpay_api_key
+CINETPAY_SITE_ID=your_cinetpay_site_id
+WAVE_API_KEY=your_wave_api_key
+HUB2_API_KEY=your_hub2_api_key
+PAPSS_API_KEY=your_papss_api_key
+WARIMCP_PORT=3000
+WARIMCP_ENV=development
+```
+
+---
+
+## Usage
+
+### As an MCP Server (Claude / Cursor / Windsurf)
+
+Add to your `.claude.json` or MCP config:
+
+```json
+{
+  "mcpServers": {
+    "warimcp": {
+      "command": "node",
+      "args": ["/path/to/warimcp/src/index.js"],
+      "env": {
+        "CINETPAY_API_KEY": "...",
+        "CINETPAY_SITE_ID": "..."
+      }
+    }
+  }
+}
+```
+
+### As a Node.js Module
+
+```js
+const warimcp = require('warimcp');
+
+const result = await warimcp.initiatePayment({
+  provider: 'cinetpay',
+  amount: 5000,
+  currency: 'XOF',
+  customer: { name: 'Kofi Atta', phone: '+2250700000000' },
+  description: 'Invoice #001',
+  return_url: 'https://yourapp.com/payment/callback'
+});
+```
+
+---
+
+## MCP Tools
+
+WariMCP exposes the following tools to AI agents:
+
+| Tool | Description |
+|---|---|
+| `initiate_payment` | Start a payment via any supported rail |
+| `check_status` | Poll the status of a transaction |
+| `refund` | Issue a full or partial refund |
+| `list_transactions` | List recent transactions with filters |
+| `generate_payment_link` | Create a shareable payment link |
+
+---
+
+## Roadmap
+
+### Phase 1 — CinetPay + Wave (March 2026)
+- [x] Project scaffold + MCP server
+- [ ] CinetPay provider: `initiate_payment`, `check_status`, `refund`
+- [ ] Wave provider: `initiate_payment`, `check_status`
+- [ ] Webhook handler (payment confirmation)
+- [ ] Master log / queue for Always-On reliability
+- [ ] npm publish (`npm install warimcp`)
+
+### Phase 2 — Hub2 / Ecobank Unified Gateway (60 days)
+- [ ] Hub2 provider integration (single API → full UEMOA)
+- [ ] Unified routing layer (auto-select best rail by country/wallet)
+- [ ] `list_transactions` across providers
+- [ ] Hosted dashboard (transaction monitor)
+
+### Phase 3 — PAPSS Pan-African Corridor (Q3 2026)
+- [ ] PAPSS integration (CI ↔ Kenya + 160 banks)
+- [ ] Multi-currency settlement engine
+- [ ] Enterprise middleware API (AI Bookkeeper, Bulk Payment Agent)
+- [ ] Partnership program (Hub2, CinetPay, Orange Ventures)
+
+---
+
+## Contributing
+
+PRs, issues, and discussions are welcome. Please open an issue before submitting major changes.
+
+1. Fork the repo
+2. Create your branch: `git checkout -b feat/your-feature`
+3. Commit your changes: `git commit -m 'feat: add your feature'`
+4. Push: `git push origin feat/your-feature`
+5. Open a Pull Request
+
+---
+
+## License
+
+[MIT](LICENSE) — Built by [Bigabou](https://github.com/Bigabou007-dev) in Abidjan, Côte d'Ivoire.

package/RECOVERY.md

@@ -0,0 +1,62 @@
+# WariMCP — Recovery Protocol
+
+**Target:** Restore WariMCP to a fresh host in under 30 minutes.
+
+## Prerequisites on Fresh Host
+- Ubuntu 22.04+
+- Docker + Docker Compose installed
+- Nginx Proxy Manager running with `npm_proxy` network
+
+## Step-by-Step Restore
+
+### Step 1 — Restore Files (5 min)
+```bash
+# From backup archive (gdrive:vps-backups)
+rclone copy gdrive:vps-backups/warimcp/latest.tar.gz /tmp/
+cd /tmp && tar -xzf latest.tar.gz
+mv warimcp ~/automation/projects/
+```
+
+### Step 2 — Restore Environment (2 min)
+```bash
+cd ~/automation/projects/warimcp
+# .env is NOT in the archive — restore from your password manager or secure vault
+cp /path/to/secure/.env .env
+```
+
+### Step 3 — Restore Database (10 min)
+```bash
+# Start only the DB container first
+docker compose up -d warimcp_db
+
+# Wait for postgres to be ready
+sleep 10
+
+# Restore from backup dump
+docker compose exec -T warimcp_db psql -U warimcp warimcp < /tmp/warimcp_db_backup.sql
+```
+
+### Step 4 — Start Service (3 min)
+```bash
+docker compose up -d
+docker compose logs -f warimcp   # confirm healthy
+```
+
+### Step 5 — Verify NPM Route (2 min)
+- Log into Nginx Proxy Manager dashboard
+- Confirm `warimcp` proxy host points to container:3000 on npm_proxy network
+- Test payment status endpoint
+
+### Step 6 — Queue Reconciliation (5 min)
+```bash
+# Check the master log for any in-flight transactions at time of failure
+cat ~/automation/projects/warimcp/logs/queue.log | tail -50
+# Re-process any PENDING transactions manually if needed
+```
+
+## Total Estimated Time: ~27 minutes
+
+## Contacts
+- CinetPay support: support@cinetpay.com
+- Wave developer support: developers@wave.com
+- Hub2: developers@hub2.io

package/TECHNICAL.md

@@ -0,0 +1,82 @@
+# WariMCP — Technical Documentation
+
+## Architecture
+
+WariMCP is a Node.js MCP (Model Context Protocol) server that exposes West African payment rails to AI agents. It runs as a containerized service behind Nginx Proxy Manager with an embedded PostgreSQL database for transaction logging.
+
+```
+AI Agent / LLM
+      │
+      ▼
+  WariMCP MCP Server (Express + MCP SDK)
+      │
+      ├── router.js        → Selects the correct payment provider
+      ├── tools.js         → MCP tool definitions
+      ├── queue.js         → Master log / Always-On queue
+      │
+      ├── providers/
+      │   ├── cinetpay.js  → CinetPay UEMOA gateway (Phase 1)
+      │   ├── wave.js      → Wave mobile wallet (Phase 1)
+      │   ├── hub2.js      → Hub2/Ecobank unified (Phase 2)
+      │   └── papss.js     → PAPSS pan-African (Phase 3)
+      │
+      └── webhook.js       → Inbound payment confirmations
+```
+
+## Deployment
+
+### Prerequisites
+- Docker + Docker Compose
+- Nginx Proxy Manager (shared `npm_proxy` network)
+- `.env` file with all required keys
+
+### First-Time Setup
+
+```bash
+# 1. Clone the repo
+git clone https://github.com/Bigabou007-dev/warimcp.git
+cd warimcp
+
+# 2. Configure environment
+cp .env.example .env
+nano .env   # fill in API keys
+
+# 3. Add DB password to .env
+echo "DB_PASSWORD=$(openssl rand -hex 16)" >> .env
+
+# 4. Start services
+docker compose up -d
+
+# 5. Verify
+docker compose logs -f warimcp
+```
+
+### NPM Proxy Manager Route
+- Container name: `warimcp`
+- Internal port: `3000`
+- Route via NPM — do NOT expose this port publicly
+
+## Maintenance
+
+### Logs
+```bash
+docker compose logs -f warimcp
+docker compose logs -f warimcp_db
+```
+
+### Updates
+```bash
+git pull
+docker compose up -d --build
+```
+
+### Restart
+```bash
+docker compose restart warimcp
+```
+
+## Security
+- Service runs as non-root (`USER node`)
+- Zero public ports — all traffic via NPM internal network
+- API keys stored in `.env` only, never hardcoded
+- DB credentials auto-generated at setup

package/backup.sh

@@ -0,0 +1,55 @@
+#!/bin/bash
+
+# WariMCP — Backup Script
+# Usage: ./backup.sh [--dry-run]
+
+set -euo pipefail
+
+DRY_RUN=false
+[[ "${1:-}" == "--dry-run" ]] && DRY_RUN=true
+
+TIMESTAMP=$(date +%Y%m%d_%H%M%S)
+BACKUP_DIR="/tmp/warimcp_backup_${TIMESTAMP}"
+ARCHIVE="/tmp/warimcp_${TIMESTAMP}.tar.gz"
+REMOTE="gdrive:vps-backups/warimcp"
+
+log() { echo "[$(date '+%Y-%m-%d %H:%M:%S')] $*"; }
+
+log "WariMCP backup starting — dry-run: $DRY_RUN"
+
+mkdir -p "$BACKUP_DIR"
+
+log "Dumping database..."
+if $DRY_RUN; then
+  log "[DRY-RUN] Would run: docker compose exec warimcp_db pg_dump -U warimcp warimcp"
+else
+  docker compose -f "$(dirname "$0")/docker-compose.yml" exec -T warimcp_db \
+    pg_dump -U warimcp warimcp > "${BACKUP_DIR}/warimcp_db_${TIMESTAMP}.sql"
+fi
+
+log "Archiving code..."
+if $DRY_RUN; then
+  log "[DRY-RUN] Would archive: $(dirname "$0") -> $ARCHIVE"
+else
+  tar -czf "$ARCHIVE" \
+    --exclude=".env" \
+    --exclude="node_modules" \
+    --exclude=".git" \
+    -C "$(dirname "$(realpath "$0")")" . \
+    -C "$BACKUP_DIR" .
+fi
+
+log "Syncing to remote..."
+if $DRY_RUN; then
+  log "[DRY-RUN] Would run: rclone copy $ARCHIVE $REMOTE/"
+else
+  rclone copy "$ARCHIVE" "$REMOTE/" --progress
+  rclone copy "${BACKUP_DIR}/warimcp_db_${TIMESTAMP}.sql" "$REMOTE/" --progress
+fi
+
+log "Cleaning up temp files..."
+if ! $DRY_RUN; then
+  rm -rf "$BACKUP_DIR" "$ARCHIVE"
+fi
+
+log "Backup complete."

package/docker-compose.yml

@@ -0,0 +1,45 @@
+version: "3.9"
+
+services:
+  warimcp:
+    build: .
+    container_name: warimcp
+    restart: unless-stopped
+    env_file: .env
+    networks:
+      - npm_proxy
+    deploy:
+      resources:
+        limits:
+          cpus: "0.25"
+          memory: 256M
+        reservations:
+          cpus: "0.10"
+          memory: 128M
+    depends_on:
+      - warimcp_db
+
+  warimcp_db:
+    image: postgres:16-alpine
+    container_name: warimcp_db
+    restart: unless-stopped
+    environment:
+      POSTGRES_USER: warimcp
+      POSTGRES_PASSWORD: ${DB_PASSWORD}
+      POSTGRES_DB: warimcp
+    volumes:
+      - warimcp_db_data:/var/lib/postgresql/data
+    networks:
+      - npm_proxy
+    deploy:
+      resources:
+        limits:
+          cpus: "0.25"
+          memory: 256M
+
+volumes:
+  warimcp_db_data:
+
+networks:
+  npm_proxy:
+    external: true

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "warimcp",
+  "version": "0.0.1",
+  "description": "WariMCP — AI-native payment MCP server for West Africa. Unified gateway for CinetPay, Wave, Hub2/Ecobank, and PAPSS payment rails.",
+  "main": "src/index.js",
+  "scripts": {
+    "start": "node src/index.js",
+    "dev": "node --watch src/index.js",
+    "test": "echo \"No tests yet\" && exit 0"
+  },
+  "keywords": [
+    "mcp",
+    "payments",
+    "west-africa",
+    "cinetpay",
+    "wave",
+    "fintech",
+    "africa",
+    "nodejs",
+    "uemoa",
+    "papss"
+  ],
+  "author": "Bigabou",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Bigabou007-dev/warimcp.git"
+  },
+  "homepage": "https://github.com/Bigabou007-dev/warimcp#readme",
+  "bugs": {
+    "url": "https://github.com/Bigabou007-dev/warimcp/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "axios": "^1.7.0",
+    "dotenv": "^16.4.0",
+    "express": "^4.18.0"
+  }
+}

package/src/index.js

@@ -0,0 +1,33 @@
+require("dotenv").config();
+const express = require("express");
+const { tools } = require("./tools");
+const { processToolCall } = require("./router");
+const { logQueue } = require("./queue");
+const { handleWebhook } = require("./webhook");
+
+const app = express();
+app.use(express.json());
+
+app.post("/mcp", async (req, res) => {
+  const { tool, input } = req.body;
+  if (!tool || !input) return res.status(400).json({ error: "tool and input required" });
+
+  try {
+    logQueue("RECEIVED", tool, input);
+    const result = await processToolCall(tool, input);
+    logQueue("COMPLETED", tool, result);
+    res.json({ result });
+  } catch (err) {
+    logQueue("FAILED", tool, { error: err.message });
+    res.status(500).json({ error: err.message });
+  }
+});
+
+app.get("/tools", (_req, res) => res.json({ tools }));
+
+app.post("/webhook/:provider", handleWebhook);
+
+app.get("/health", (_req, res) => res.json({ status: "ok", ts: new Date().toISOString() }));
+
+const PORT = process.env.WARIMCP_PORT || 3000;
+app.listen(PORT, () => console.log(`WariMCP listening on port ${PORT}`));

package/src/providers/cinetpay.js

@@ -0,0 +1,73 @@
+const axios = require("axios");
+
+const BASE_URL = "https://api-checkout.cinetpay.com/v2";
+
+function headers() {
+  return { "Content-Type": "application/json" };
+}
+
+function credentials() {
+  return {
+    apikey: process.env.CINETPAY_API_KEY,
+    site_id: process.env.CINETPAY_SITE_ID
+  };
+}
+
+async function initiatePayment({ amount, currency, customer, description, return_url, metadata }) {
+  const transaction_id = `CP_${Date.now()}_${Math.random().toString(36).slice(2,8)}`;
+
+  const payload = {
+    ...credentials(),
+    transaction_id,
+    amount,
+    currency: currency || "XOF",
+    description: description || "WariMCP Payment",
+    customer_name: customer.name,
+    customer_surname: "",
+    customer_email: customer.email || "",
+    customer_phone_number: customer.phone,
+    customer_address: "",
+    customer_city: "",
+    customer_country: "CI",
+    customer_state: "CI",
+    customer_zip_code: "00000",
+    return_url: return_url || "",
+    notify_url: `${process.env.WARIMCP_WEBHOOK_URL || ""}/webhook/cinetpay`,
+    channels: "ALL",
+    metadata: JSON.stringify(metadata || {})
+  };
+
+  const { data } = await axios.post(`${BASE_URL}/payment`, payload, { headers: headers() });
+  return { transaction_id, ...data };
+}
+
+async function checkStatus(transaction_id) {
+  const { data } = await axios.post(`${BASE_URL}/payment/check`, {
+    ...credentials(),
+    transaction_id
+  }, { headers: headers() });
+
+  return data;
+}
+
+async function refund(transaction_id, amount, reason) {
+  throw new Error("CinetPay refunds require manual processing via CinetPay dashboard.");
+}
+
+async function listTransactions({ limit = 20, offset = 0 } = {}) {
+  throw new Error("CinetPay list_transactions not yet implemented.");
+}
+
+async function generatePaymentLink({ amount, currency, description, expires_at, metadata }) {
+  const result = await initiatePayment({
+    amount,
+    currency,
+    customer: { name: "Customer", phone: "" },
+    description,
+    metadata
+  });
+
+  return { payment_url: result?.data?.payment_url, transaction_id: result.transaction_id };
+}
+
+module.exports = { initiatePayment, checkStatus, refund, listTransactions, generatePaymentLink };

package/src/providers/hub2.js

@@ -0,0 +1,21 @@
+async function initiatePayment(input) {
+  throw new Error("Hub2 provider coming in Phase 2.");
+}
+
+async function checkStatus(transaction_id) {
+  throw new Error("Hub2 provider coming in Phase 2.");
+}
+
+async function refund(transaction_id, amount, reason) {
+  throw new Error("Hub2 provider coming in Phase 2.");
+}
+
+async function listTransactions(filters) {
+  throw new Error("Hub2 provider coming in Phase 2.");
+}
+
+async function generatePaymentLink(input) {
+  throw new Error("Hub2 provider coming in Phase 2.");
+}
+
+module.exports = { initiatePayment, checkStatus, refund, listTransactions, generatePaymentLink };

package/src/providers/papss.js

@@ -0,0 +1,21 @@
+async function initiatePayment(input) {
+  throw new Error("PAPSS provider coming in Phase 3.");
+}
+
+async function checkStatus(transaction_id) {
+  throw new Error("PAPSS provider coming in Phase 3.");
+}
+
+async function refund(transaction_id, amount, reason) {
+  throw new Error("PAPSS provider coming in Phase 3.");
+}
+
+async function listTransactions(filters) {
+  throw new Error("PAPSS provider coming in Phase 3.");
+}
+
+async function generatePaymentLink(input) {
+  throw new Error("PAPSS provider coming in Phase 3.");
+}
+
+module.exports = { initiatePayment, checkStatus, refund, listTransactions, generatePaymentLink };

package/src/providers/wave.js

@@ -0,0 +1,42 @@
+const axios = require("axios");
+
+const BASE_URL = "https://api.wave.com/v1";
+
+function headers() {
+  return {
+    "Authorization": `Bearer ${process.env.WAVE_API_KEY}`,
+    "Content-Type": "application/json"
+  };
+}
+
+async function initiatePayment({ amount, currency, customer, description, return_url, metadata }) {
+  const payload = {
+    currency: currency || "XOF",
+    amount: String(amount),
+    error_url: return_url || "",
+    success_url: return_url || "",
+    client_reference: `WAVE_${Date.now()}`
+  };
+
+  const { data } = await axios.post(`${BASE_URL}/checkout/sessions`, payload, { headers: headers() });
+  return { transaction_id: data.id, payment_url: data.wave_launch_url, ...data };
+}
+
+async function checkStatus(transaction_id) {
+  const { data } = await axios.get(`${BASE_URL}/checkout/sessions/${transaction_id}`, { headers: headers() });
+  return data;
+}
+
+async function refund(transaction_id, amount, reason) {
+  throw new Error("Wave refunds not yet implemented.");
+}
+
+async function listTransactions({ limit = 20, offset = 0 } = {}) {
+  throw new Error("Wave list_transactions not yet implemented.");
+}
+
+async function generatePaymentLink({ amount, currency, description, metadata }) {
+  return initiatePayment({ amount, currency, customer: { name: "Customer", phone: "" }, description, metadata });
+}
+
+module.exports = { initiatePayment, checkStatus, refund, listTransactions, generatePaymentLink };

package/src/queue.js

@@ -0,0 +1,42 @@
+const fs = require("fs");
+const path = require("path");
+
+const LOG_FILE = path.join(__dirname, "../logs/queue.log");
+
+function logQueue(status, tool, data) {
+  const entry = JSON.stringify({
+    ts: new Date().toISOString(),
+    status,
+    tool,
+    data
+  });
+
+  fs.appendFileSync(LOG_FILE, entry + "\n");
+}
+
+function readQueue() {
+  if (!fs.existsSync(LOG_FILE)) return [];
+
+  return fs.readFileSync(LOG_FILE, "utf8")
+    .split("\n")
+    .filter(Boolean)
+    .map(line => {
+      try { return JSON.parse(line); }
+      catch { return null; }
+    })
+    .filter(Boolean);
+}
+
+function getPending() {
+  const entries = readQueue();
+  const pending = new Map();
+
+  for (const entry of entries) {
+    if (entry.status === "RECEIVED") pending.set(entry.data?.transaction_id, entry);
+    if (entry.status === "COMPLETED" || entry.status === "FAILED") pending.delete(entry.data?.transaction_id);
+  }
+
+  return [...pending.values()];
+}
+
+module.exports = { logQueue, readQueue, getPending };

package/src/router.js

@@ -0,0 +1,31 @@
+const cinetpay = require("./providers/cinetpay");
+const wave = require("./providers/wave");
+const hub2 = require("./providers/hub2");
+const papss = require("./providers/papss");
+
+const providers = { cinetpay, wave, hub2, papss };
+
+async function processToolCall(tool, input) {
+  const provider = input.provider || "cinetpay";
+
+  if (!providers[provider]) {
+    throw new Error(`Unknown provider: ${provider}`);
+  }
+
+  switch (tool) {
+    case "initiate_payment":
+      return providers[provider].initiatePayment(input);
+    case "check_status":
+      return providers[provider].checkStatus(input.transaction_id);
+    case "refund":
+      return providers[provider].refund(input.transaction_id, input.amount, input.reason);
+    case "list_transactions":
+      return providers[provider].listTransactions(input);
+    case "generate_payment_link":
+      return providers[provider].generatePaymentLink(input);
+    default:
+      throw new Error(`Unknown tool: ${tool}`);
+  }
+}
+
+module.exports = { processToolCall };

package/src/tools.js

@@ -0,0 +1,84 @@
+const tools = [
+  {
+    name: "initiate_payment",
+    description: "Start a payment transaction via a supported West African payment rail.",
+    inputSchema: {
+      type: "object",
+      required: ["provider", "amount", "currency", "customer"],
+      properties: {
+        provider: { type: "string", enum: ["cinetpay", "wave", "hub2", "papss"] },
+        amount: { type: "number", description: "Amount in smallest currency unit" },
+        currency: { type: "string", description: "ISO 4217 currency code, e.g. XOF, CFA" },
+        customer: {
+          type: "object",
+          required: ["name", "phone"],
+          properties: {
+            name: { type: "string" },
+            phone: { type: "string" },
+            email: { type: "string" }
+          }
+        },
+        description: { type: "string" },
+        return_url: { type: "string" },
+        metadata: { type: "object" }
+      }
+    }
+  },
+  {
+    name: "check_status",
+    description: "Check the status of an existing payment transaction.",
+    inputSchema: {
+      type: "object",
+      required: ["transaction_id", "provider"],
+      properties: {
+        transaction_id: { type: "string" },
+        provider: { type: "string", enum: ["cinetpay", "wave", "hub2", "papss"] }
+      }
+    }
+  },
+  {
+    name: "refund",
+    description: "Issue a full or partial refund for a completed transaction.",
+    inputSchema: {
+      type: "object",
+      required: ["transaction_id", "provider"],
+      properties: {
+        transaction_id: { type: "string" },
+        provider: { type: "string", enum: ["cinetpay", "wave", "hub2", "papss"] },
+        amount: { type: "number", description: "Partial refund amount. Omit for full refund." },
+        reason: { type: "string" }
+      }
+    }
+  },
+  {
+    name: "list_transactions",
+    description: "List recent transactions with optional filters.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        provider: { type: "string", enum: ["cinetpay", "wave", "hub2", "papss", "all"] },
+        status: { type: "string", enum: ["pending", "completed", "failed", "refunded"] },
+        limit: { type: "number", default: 20 },
+        offset: { type: "number", default: 0 }
+      }
+    }
+  },
+  {
+    name: "generate_payment_link",
+    description: "Generate a shareable payment link for a customer.",
+    inputSchema: {
+      type: "object",
+      required: ["provider", "amount", "currency"],
+      properties: {
+        provider: { type: "string", enum: ["cinetpay", "wave", "hub2"] },
+        amount: { type: "number" },
+        currency: { type: "string" },
+        description: { type: "string" },
+        expires_at: { type: "string", description: "ISO 8601 expiry datetime" },
+        metadata: { type: "object" }
+      }
+    }
+  }
+];
+
+module.exports = { tools };

package/src/webhook.js

@@ -0,0 +1,12 @@
+const { logQueue } = require("./queue");
+
+async function handleWebhook(req, res) {
+  const { provider } = req.params;
+  const payload = req.body;
+
+  logQueue("WEBHOOK", provider, payload);
+
+  res.json({ received: true });
+}
+
+module.exports = { handleWebhook };