mockpay 0.1.0

package/README.md

@@ -0,0 +1,207 @@
+# mockpay
+
+Local mock Paystack and Flutterwave servers for offline/local testing. Use this in development to replace live gateway URLs and to simulate payment outcomes, errors, and webhooks.
+
+Default base URLs:
+- Paystack-like: `http://localhost:4010`
+- Flutterwave-like: `http://localhost:4020`
+
+Hosted checkout (served by mockpay):
+- http://localhost:4010/checkout
+- http://localhost:4020/checkout
+
+## Quick Start
+
+```bash
+npm i -g mockpay
+mockpay start
+```
+
+Servers:
+- Paystack: http://localhost:4010
+- Flutterwave: http://localhost:4020
+
+## Integration Goal
+
+Replace live gateway URLs in development:
+- Instead of `https://api.paystack.co`, use `http://localhost:4010`
+- Instead of `https://api.flutterwave.com/v3`, use `http://localhost:4020`
+
+Typical flow:
+1. Initialize payment from your backend.
+2. Open the hosted checkout link in the browser.
+3. Complete payment in the mock checkout UI.
+4. Verify from your backend.
+
+## CLI Commands
+
+```bash
+mockpay start
+mockpay stop
+mockpay status
+mockpay pay success|fail|cancel
+mockpay error 500|timeout|network
+mockpay webhook resend
+mockpay webhook config --delay 1000 --retry 2 --retry-delay 2000 --duplicate --drop
+mockpay reset
+mockpay logs
+```
+
+Notes:
+- `mockpay pay ...` applies to the next payment only, then resets to `success`.
+- `mockpay error ...` applies to the next API request only, then resets to `none`.
+- `mockpay logs` streams live logs over SSE from the Paystack server.
+
+## Environment
+
+Copy `.env.example` to `.env` and adjust if needed.
+
+Key settings:
+- `MOCKPAY_PAYSTACK_PORT`
+- `MOCKPAY_FLUTTERWAVE_PORT`
+- `MOCKPAY_FRONTEND_URL`
+- `MOCKPAY_DATA_DIR`
+- `MOCKPAY_DEFAULT_WEBHOOK_URL`
+
+Webhook controls:
+- `MOCKPAY_WEBHOOK_DELAY_MS`
+- `MOCKPAY_WEBHOOK_RETRY_COUNT`
+- `MOCKPAY_WEBHOOK_RETRY_DELAY_MS`
+- `MOCKPAY_WEBHOOK_DUPLICATE`
+- `MOCKPAY_WEBHOOK_DROP`
+
+## API Coverage
+
+### Paystack
+- `POST /transaction/initialize`
+- `GET /transaction/verify/:reference`
+- `POST /transaction/verify/:reference`
+- `POST /transfer`
+- `GET /banks`
+
+### Flutterwave
+- `POST /payments`
+- `GET /transactions/verify_by_reference?tx_ref=...`
+- `GET /transactions/:id/verify`
+- `POST /transfers`
+
+## Payment Flow
+
+### Paystack-style flow
+1. `POST /transaction/initialize`
+2. Open `data.authorization_url`
+3. Complete payment on checkout (`success` / `failed` / `cancelled`)
+4. Verify on your backend with `/transaction/verify/:reference`
+
+### Flutterwave-style flow
+1. `POST /payments`
+2. Open `data.link`
+3. Complete payment on checkout (`success` / `failed` / `cancelled`)
+4. Verify on your backend using:
+   - `/transactions/verify_by_reference?tx_ref=...` or
+   - `/transactions/:id/verify`
+
+## Example Requests
+
+### Paystack initialize
+
+```bash
+curl -X POST http://localhost:4010/transaction/initialize \
+  -H "Content-Type: application/json" \
+  -d '{
+    "amount": 5000,
+    "currency": "NGN",
+    "email": "test@example.com",
+    "name": "Ada Lovelace",
+    "callback_url": "http://localhost:3000/paystack/callback"
+  }'
+```
+
+### Paystack verify
+
+```bash
+curl http://localhost:4010/transaction/verify/PSK_1234567890_abcdef
+```
+
+### Flutterwave payments
+
+```bash
+curl -X POST http://localhost:4020/payments \
+  -H "Content-Type: application/json" \
+  -d '{
+    "amount": 5000,
+    "currency": "NGN",
+    "customer": {
+      "email": "test@example.com",
+      "name": "Ada Lovelace"
+    },
+    "redirect_url": "http://localhost:3000/flutterwave/callback"
+  }'
+```
+
+### Flutterwave verify by reference
+
+```bash
+curl "http://localhost:4020/transactions/verify_by_reference?tx_ref=FLW_1234567890_abcdef"
+```
+
+### Flutterwave verify by id
+
+```bash
+curl "http://localhost:4020/transactions/<transaction_id>/verify"
+```
+
+## Error Simulation
+
+Simulate one request failure:
+
+```bash
+mockpay error 500
+mockpay error timeout
+mockpay error network
+```
+
+Notes:
+- `network` will drop the socket without a response.
+- `timeout` waits 15 seconds before responding with `504`.
+
+## Webhooks
+
+Set a default webhook URL:
+
+```
+MOCKPAY_DEFAULT_WEBHOOK_URL=http://localhost:3000/webhooks/mockpay
+```
+
+Configure behavior at runtime:
+
+```bash
+mockpay webhook config --delay 1000 --retry 2 --retry-delay 2000 --duplicate --drop
+```
+
+Resend last webhook:
+
+```bash
+mockpay webhook resend
+```
+
+## Development
+
+```bash
+npm install
+npm run dev
+```
+
+## Building the Hosted Checkout
+
+The checkout UI is in `template/` and should be built before publishing:
+
+```bash
+npm --prefix template install
+npm --prefix template run build
+```
+
+## Notes
+
+- ChronoDB is used for file-based persistence. Data is stored under `MOCKPAY_DATA_DIR` (default `.mockpay/data`).
+- Hosted checkout URLs include transaction details (`ref`, `amount`, `currency`, `email`, `name`, provider).

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/index.js

@@ -0,0 +1,270 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import chalk from "chalk";
+import path from "path";
+import { fileURLToPath } from "url";
+import { spawn } from "child_process";
+import fs from "fs";
+import { setNextPaymentResult, setNextError, getWebhookConfig, setWebhookConfig } from "../core/state.js";
+import { readRuntime, writeRuntime, clearRuntime, isPidRunning } from "../core/runtime.js";
+import { resendLastWebhook } from "../webhooks/sender.js";
+import { getCollections, getDb } from "../core/db.js";
+import { getConfig } from "../core/config.js";
+const program = new Command();
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+program
+    .name("mockpay")
+    .description("Local Paystack + Flutterwave mock servers")
+    .version("0.1.0");
+program
+    .command("start")
+    .description("Start mock servers")
+    .action(async () => {
+    const runtime = await readRuntime();
+    if (runtime && isPidRunning(runtime.pid)) {
+        console.log(chalk.yellow(`Mockpay already running (pid ${runtime.pid})`));
+        return;
+    }
+    const config = getConfig();
+    const isHealthy = async () => {
+        const targets = [
+            `http://localhost:${config.paystackPort}/__health`,
+            `http://localhost:${config.flutterwavePort}/__health`
+        ];
+        for (const url of targets) {
+            try {
+                const controller = new AbortController();
+                const timeout = setTimeout(() => controller.abort(), 1000);
+                const res = await fetch(url, { signal: controller.signal });
+                clearTimeout(timeout);
+                if (res.ok)
+                    return true;
+            }
+            catch {
+                // ignore
+            }
+        }
+        return false;
+    };
+    if (await isHealthy()) {
+        console.log(chalk.yellow("Mockpay already running"));
+        return;
+    }
+    const jsServerPath = path.resolve(__dirname, "..", "server", "index.js");
+    const tsServerPath = path.resolve(__dirname, "..", "server", "index.ts");
+    const serverPath = fs.existsSync(jsServerPath) ? jsServerPath : tsServerPath;
+    const child = spawn(process.execPath, [...process.execArgv, serverPath], {
+        detached: true,
+        stdio: "ignore",
+        env: {
+            ...process.env,
+            MOCKPAY_DATA_DIR: config.dataDir
+        }
+    });
+    child.unref();
+    if (!child.pid) {
+        console.log(chalk.red("Failed to start mock servers"));
+        return;
+    }
+    await writeRuntime(child.pid, config.dataDir);
+    console.log(chalk.green(`Mockpay started (pid ${child.pid})`));
+    console.log(chalk.gray(`Paystack: http://localhost:${config.paystackPort}`));
+    console.log(chalk.gray(`Flutterwave: http://localhost:${config.flutterwavePort}`));
+});
+program
+    .command("stop")
+    .description("Stop mock servers")
+    .action(async () => {
+    const runtime = await readRuntime();
+    if (!runtime || !isPidRunning(runtime.pid)) {
+        console.log(chalk.yellow("Mockpay is not running"));
+        await clearRuntime();
+        return;
+    }
+    try {
+        process.kill(runtime.pid);
+        await clearRuntime();
+        console.log(chalk.green("Mockpay stopped"));
+    }
+    catch {
+        console.log(chalk.red(`Failed to stop process ${runtime.pid}`));
+    }
+});
+program
+    .command("status")
+    .description("Show running services")
+    .action(async () => {
+    const config = getConfig();
+    const targets = [
+        { name: "Paystack", url: `http://localhost:${config.paystackPort}/__health` },
+        { name: "Flutterwave", url: `http://localhost:${config.flutterwavePort}/__health` }
+    ];
+    const results = await Promise.all(targets.map(async (target) => {
+        try {
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), 1500);
+            const res = await fetch(target.url, { signal: controller.signal });
+            clearTimeout(timeout);
+            return { name: target.name, ok: res.ok };
+        }
+        catch {
+            return { name: target.name, ok: false };
+        }
+    }));
+    const running = results.filter((r) => r.ok);
+    if (running.length === 0) {
+        console.log(chalk.yellow("Not running"));
+        return;
+    }
+    running.forEach((r) => console.log(chalk.green(`${r.name} running`)));
+});
+program
+    .command("pay")
+    .description("Set next payment result")
+    .argument("<result>", "success|fail|cancel")
+    .action(async (result) => {
+    const runtime = await readRuntime();
+    if (runtime?.dataDir)
+        process.env.MOCKPAY_DATA_DIR = runtime.dataDir;
+    const map = {
+        success: "success",
+        fail: "failed",
+        cancel: "cancelled"
+    };
+    const mapped = map[result];
+    if (!mapped) {
+        console.log(chalk.red("Expected success|fail|cancel"));
+        return;
+    }
+    await setNextPaymentResult(mapped);
+    console.log(chalk.green(`Next payment result set to ${mapped}`));
+});
+program
+    .command("error")
+    .description("Simulate next request failure")
+    .argument("<type>", "500|timeout|network")
+    .action(async (type) => {
+    const runtime = await readRuntime();
+    if (runtime?.dataDir)
+        process.env.MOCKPAY_DATA_DIR = runtime.dataDir;
+    const allowed = ["500", "timeout", "network"];
+    if (!allowed.includes(type)) {
+        console.log(chalk.red("Expected 500|timeout|network"));
+        return;
+    }
+    await setNextError(type);
+    console.log(chalk.green(`Next error set to ${type}`));
+});
+const webhook = program.command("webhook").description("Webhook actions");
+webhook
+    .command("resend")
+    .description("Resend last webhook")
+    .action(async () => {
+    const runtime = await readRuntime();
+    if (runtime?.dataDir)
+        process.env.MOCKPAY_DATA_DIR = runtime.dataDir;
+    const ok = await resendLastWebhook();
+    if (ok) {
+        console.log(chalk.green("Webhook resent"));
+    }
+    else {
+        console.log(chalk.yellow("No webhook to resend"));
+    }
+});
+webhook
+    .command("config")
+    .description("View or update webhook behavior")
+    .option("--delay <ms>", "Delay before sending")
+    .option("--retry <count>", "Retry count")
+    .option("--retry-delay <ms>", "Retry delay")
+    .option("--duplicate", "Send duplicate webhook")
+    .option("--no-duplicate", "Disable duplicate webhook")
+    .option("--drop", "Drop webhook")
+    .option("--no-drop", "Disable drop")
+    .action(async (options) => {
+    const runtime = await readRuntime();
+    if (runtime?.dataDir)
+        process.env.MOCKPAY_DATA_DIR = runtime.dataDir;
+    const current = await getWebhookConfig();
+    const updated = {
+        delayMs: options.delay ? Number(options.delay) : current.delayMs,
+        retryCount: options.retry ? Number(options.retry) : current.retryCount,
+        retryDelayMs: options.retryDelay ? Number(options.retryDelay) : current.retryDelayMs,
+        duplicate: typeof options.duplicate === "boolean" ? options.duplicate : current.duplicate,
+        drop: typeof options.drop === "boolean" ? options.drop : current.drop
+    };
+    await setWebhookConfig(updated);
+    console.log(chalk.green("Webhook config updated"));
+    console.log(updated);
+});
+program
+    .command("reset")
+    .description("Clear ChronoDB data")
+    .action(async () => {
+    const runtime = await readRuntime();
+    if (runtime?.dataDir)
+        process.env.MOCKPAY_DATA_DIR = runtime.dataDir;
+    const { transactions, transfers, webhooks, settings, logs } = await getCollections();
+    await transactions.deleteAll();
+    await transfers.deleteAll();
+    await webhooks.deleteAll();
+    await settings.deleteAll();
+    await logs.deleteAll();
+    const db = await getDb();
+    if (db?.snapshots?.deleteAll) {
+        await db.snapshots.deleteAll();
+    }
+    console.log(chalk.green("Database cleared"));
+});
+program
+    .command("logs")
+    .description("Stream live logs")
+    .action(async () => {
+    const runtime = await readRuntime();
+    if (runtime?.dataDir)
+        process.env.MOCKPAY_DATA_DIR = runtime.dataDir;
+    const config = getConfig();
+    const url = `http://localhost:${config.paystackPort}/__logs`;
+    console.log(chalk.gray(`Streaming logs from ${url}`));
+    try {
+        const res = await fetch(url, {
+            headers: {
+                Accept: "text/event-stream"
+            }
+        });
+        if (!res.body) {
+            console.log(chalk.red("No log stream available"));
+            return;
+        }
+        const reader = res.body.getReader();
+        let buffer = "";
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buffer += new TextDecoder().decode(value);
+            const parts = buffer.split("\n\n");
+            buffer = parts.pop() ?? "";
+            for (const part of parts) {
+                const line = part.trim();
+                if (!line.startsWith("data:"))
+                    continue;
+                const payload = line.replace(/^data:\s*/, "");
+                try {
+                    const entry = JSON.parse(payload);
+                    const time = new Date(entry.timestamp).toLocaleTimeString();
+                    const prefix = entry.source ? `[${entry.source}] ` : "";
+                    console.log(`${chalk.gray(time)} ${prefix}${entry.message}`);
+                }
+                catch {
+                    // ignore parse issues
+                }
+            }
+        }
+    }
+    catch {
+        console.log(chalk.red("Unable to connect to log stream. Is mockpay running?"));
+    }
+});
+program.parseAsync(process.argv);

package/dist/core/config.d.ts

@@ -0,0 +1,13 @@
+export interface Config {
+    paystackPort: number;
+    flutterwavePort: number;
+    dataDir: string;
+    frontendUrl?: string;
+    defaultWebhookUrl?: string;
+    webhookDelayMs: number;
+    webhookRetryCount: number;
+    webhookRetryDelayMs: number;
+    webhookDuplicate: boolean;
+    webhookDrop: boolean;
+}
+export declare function getConfig(): Config;

package/dist/core/config.js

@@ -0,0 +1,30 @@
+import dotenv from "dotenv";
+import path from "path";
+dotenv.config();
+function toBool(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    return value.toLowerCase() === "true";
+}
+function toNum(value, fallback) {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : fallback;
+}
+export function getConfig() {
+    const baseDir = process.cwd();
+    const dataDir = process.env.MOCKPAY_DATA_DIR
+        ? path.resolve(baseDir, process.env.MOCKPAY_DATA_DIR)
+        : path.resolve(baseDir, ".mockpay", "data");
+    return {
+        paystackPort: toNum(process.env.MOCKPAY_PAYSTACK_PORT, 4010),
+        flutterwavePort: toNum(process.env.MOCKPAY_FLUTTERWAVE_PORT, 4020),
+        dataDir,
+        frontendUrl: process.env.MOCKPAY_FRONTEND_URL || undefined,
+        defaultWebhookUrl: process.env.MOCKPAY_DEFAULT_WEBHOOK_URL || undefined,
+        webhookDelayMs: toNum(process.env.MOCKPAY_WEBHOOK_DELAY_MS, 1500),
+        webhookRetryCount: toNum(process.env.MOCKPAY_WEBHOOK_RETRY_COUNT, 0),
+        webhookRetryDelayMs: toNum(process.env.MOCKPAY_WEBHOOK_RETRY_DELAY_MS, 2000),
+        webhookDuplicate: toBool(process.env.MOCKPAY_WEBHOOK_DUPLICATE, false),
+        webhookDrop: toBool(process.env.MOCKPAY_WEBHOOK_DROP, false)
+    };
+}

package/dist/core/db.d.ts

@@ -0,0 +1,9 @@
+export interface Collections {
+    transactions: any;
+    transfers: any;
+    webhooks: any;
+    settings: any;
+    logs: any;
+}
+export declare function getDb(): Promise<any>;
+export declare function getCollections(): Promise<Collections>;

package/dist/core/db.js

@@ -0,0 +1,104 @@
+import ChronoDB from "chronodb";
+import fs from "fs/promises";
+import { getConfig } from "./config.js";
+let dbPromise = null;
+let collectionsPromise = null;
+export async function getDb() {
+    if (!dbPromise) {
+        dbPromise = openDb();
+    }
+    return dbPromise;
+}
+export async function getCollections() {
+    if (!collectionsPromise) {
+        collectionsPromise = initCollections();
+    }
+    return collectionsPromise;
+}
+async function openDb() {
+    const { dataDir } = getConfig();
+    await fs.mkdir(dataDir, { recursive: true });
+    try {
+        return await ChronoDB.open({ path: dataDir, cloudSync: false });
+    }
+    catch {
+        const previous = process.cwd();
+        process.chdir(dataDir);
+        try {
+            return await ChronoDB.open({ cloudSync: false });
+        }
+        finally {
+            process.chdir(previous);
+        }
+    }
+}
+async function initCollections() {
+    const db = await getDb();
+    const transactions = db.col("transactions", {
+        schema: {
+            createdAt: { type: "string" },
+            updatedAt: { type: "string" },
+            provider: { type: "string", important: true },
+            reference: { type: "string", important: true, distinct: true },
+            status: { type: "string", important: true },
+            amount: { type: "number", important: true },
+            currency: { type: "string", default: "NGN" },
+            customerEmail: { type: "string", important: true },
+            customerName: { type: "string", nullable: true },
+            callbackUrl: { type: "string", nullable: true },
+            metadata: { type: "string", nullable: true }
+        },
+        indexes: ["provider", "reference", "status"]
+    });
+    const transfers = db.col("transfers", {
+        schema: {
+            createdAt: { type: "string" },
+            updatedAt: { type: "string" },
+            provider: { type: "string", important: true },
+            reference: { type: "string", important: true, distinct: true },
+            status: { type: "string", important: true },
+            amount: { type: "number", important: true },
+            currency: { type: "string", default: "NGN" },
+            bankCode: { type: "string", nullable: true },
+            accountNumber: { type: "string", nullable: true },
+            narration: { type: "string", nullable: true },
+            metadata: { type: "string", nullable: true }
+        },
+        indexes: ["provider", "reference", "status"]
+    });
+    const webhooks = db.col("webhooks", {
+        schema: {
+            createdAt: { type: "string" },
+            updatedAt: { type: "string" },
+            provider: { type: "string", important: true },
+            event: { type: "string", important: true },
+            url: { type: "string", important: true },
+            status: { type: "string", important: true },
+            attempts: { type: "number", default: 0 },
+            payload: { type: "string", important: true },
+            lastAttemptAt: { type: "number", nullable: true }
+        },
+        indexes: ["provider", "event", "status"]
+    });
+    const settings = db.col("settings", {
+        schema: {
+            createdAt: { type: "string" },
+            updatedAt: { type: "string" },
+            key: { type: "string", important: true, distinct: true },
+            value: { type: "string", important: true }
+        },
+        indexes: ["key"]
+    });
+    const logs = db.col("logs", {
+        schema: {
+            createdAt: { type: "string" },
+            updatedAt: { type: "string" },
+            level: { type: "string", important: true },
+            message: { type: "string", important: true },
+            source: { type: "string", nullable: true },
+            timestamp: { type: "number", important: true }
+        },
+        indexes: ["level", "timestamp"]
+    });
+    return { transactions, transfers, webhooks, settings, logs };
+}

package/dist/core/logger.d.ts

@@ -0,0 +1,11 @@
+import { EventEmitter } from "events";
+import type { LogEntry } from "../types/index.js";
+export type LogLevel = "info" | "warn" | "error" | "http";
+export declare const logger: {
+    info: (message: string, source?: string) => void;
+    warn: (message: string, source?: string) => void;
+    error: (message: string, source?: string) => void;
+    http: (message: string, source?: string) => void;
+    on: (handler: (entry: LogEntry) => void) => EventEmitter<[never]>;
+    off: (handler: (entry: LogEntry) => void) => EventEmitter<[never]>;
+};

package/dist/core/logger.js

@@ -0,0 +1,47 @@
+import chalk from "chalk";
+import { EventEmitter } from "events";
+import { getCollections } from "./db.js";
+const emitter = new EventEmitter();
+function colorize(level, message) {
+    switch (level) {
+        case "info":
+            return chalk.cyan(message);
+        case "warn":
+            return chalk.yellow(message);
+        case "error":
+            return chalk.red(message);
+        case "http":
+            return chalk.green(message);
+        default:
+            return message;
+    }
+}
+async function persist(entry) {
+    try {
+        const { logs } = await getCollections();
+        await logs.add(entry);
+    }
+    catch {
+        // Best-effort logging only.
+    }
+}
+function log(level, message, source) {
+    const entry = {
+        level,
+        message,
+        source,
+        timestamp: Date.now()
+    };
+    const prefix = source ? `[${source}] ` : "";
+    console.log(colorize(level, `${prefix}${message}`));
+    emitter.emit("log", entry);
+    void persist(entry);
+}
+export const logger = {
+    info: (message, source) => log("info", message, source),
+    warn: (message, source) => log("warn", message, source),
+    error: (message, source) => log("error", message, source),
+    http: (message, source) => log("http", message, source),
+    on: (handler) => emitter.on("log", handler),
+    off: (handler) => emitter.off("log", handler)
+};