mockpay 0.1.0

package/src/core/db.ts

@@ -0,0 +1,123 @@
+import ChronoDB from "chronodb";
+import fs from "fs/promises";
+
+import { getConfig } from "./config.js";
+
+let dbPromise: Promise<any> | null = null;
+let collectionsPromise: Promise<Collections> | null = null;
+
+export interface Collections {
+  transactions: any;
+  transfers: any;
+  webhooks: any;
+  settings: any;
+  logs: any;
+}
+
+export async function getDb(): Promise<any> {
+  if (!dbPromise) {
+    dbPromise = openDb();
+  }
+  return dbPromise;
+}
+
+export async function getCollections(): Promise<Collections> {
+  if (!collectionsPromise) {
+    collectionsPromise = initCollections();
+  }
+  return collectionsPromise;
+}
+
+async function openDb(): Promise<any> {
+  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(): Promise<Collections> {
+  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 } as Collections;
+}

package/src/core/logger.ts

@@ -0,0 +1,57 @@
+import chalk from "chalk";
+import { EventEmitter } from "events";
+
+import { getCollections } from "./db.js";
+import type { LogEntry } from "../types/index.js";
+
+export type LogLevel = "info" | "warn" | "error" | "http";
+
+const emitter = new EventEmitter();
+
+function colorize(level: LogLevel, message: string): string {
+  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: LogEntry): Promise<void> {
+  try {
+    const { logs } = await getCollections();
+    await logs.add(entry);
+  } catch {
+    // Best-effort logging only.
+  }
+}
+
+function log(level: LogLevel, message: string, source?: string): void {
+  const entry: LogEntry = {
+    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: string, source?: string) => log("info", message, source),
+  warn: (message: string, source?: string) => log("warn", message, source),
+  error: (message: string, source?: string) => log("error", message, source),
+  http: (message: string, source?: string) => log("http", message, source),
+  on: (handler: (entry: LogEntry) => void) => emitter.on("log", handler),
+  off: (handler: (entry: LogEntry) => void) => emitter.off("log", handler)
+};
+

package/src/core/runtime.ts

@@ -0,0 +1,42 @@
+import fs from "fs/promises";
+import path from "path";
+
+interface RuntimeState {
+  pid: number;
+  startedAt: number;
+  dataDir?: string;
+}
+
+const runtimePath = path.resolve(process.cwd(), ".mockpay", "runtime.json");
+
+export async function writeRuntime(pid: number, dataDir?: string): Promise<void> {
+  await fs.mkdir(path.dirname(runtimePath), { recursive: true });
+  const state: RuntimeState = { pid, startedAt: Date.now(), dataDir };
+  await fs.writeFile(runtimePath, JSON.stringify(state, null, 2), "utf-8");
+}
+
+export async function readRuntime(): Promise<RuntimeState | null> {
+  try {
+    const content = await fs.readFile(runtimePath, "utf-8");
+    return JSON.parse(content) as RuntimeState;
+  } catch {
+    return null;
+  }
+}
+
+export async function clearRuntime(): Promise<void> {
+  try {
+    await fs.unlink(runtimePath);
+  } catch {
+    // ignore
+  }
+}
+
+export function isPidRunning(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/core/state.ts

@@ -0,0 +1,91 @@
+import { getCollections } from "./db.js";
+import { getConfig } from "./config.js";
+
+export type PaymentResult = "success" | "failed" | "cancelled";
+export type NextError = "none" | "500" | "timeout" | "network";
+
+export interface WebhookConfig {
+  delayMs: number;
+  duplicate: boolean;
+  drop: boolean;
+  retryCount: number;
+  retryDelayMs: number;
+}
+
+const NEXT_PAYMENT_KEY = "next_payment_result";
+const NEXT_ERROR_KEY = "next_error";
+const WEBHOOK_CONFIG_KEY = "webhook_config";
+const LAST_WEBHOOK_KEY = "last_webhook";
+
+async function getSetting<T>(key: string, fallback: T): Promise<T> {
+  const { settings } = await getCollections();
+  const existing = await settings.getOne({ key });
+  if (!existing) return fallback;
+  try {
+    return JSON.parse(existing.value) as T;
+  } catch {
+    return fallback;
+  }
+}
+
+async function setSetting<T>(key: string, value: T): Promise<void> {
+  const { settings } = await getCollections();
+  const existing = await settings.getOne({ key });
+  const payload = JSON.stringify(value);
+  if (existing) {
+    await settings.updateById(existing.id, { value: payload });
+  } else {
+    await settings.add({ key, value: payload });
+  }
+}
+
+export async function takeNextPaymentResult(): Promise<PaymentResult> {
+  const current = await getSetting<PaymentResult>(NEXT_PAYMENT_KEY, "success");
+  await setSetting(NEXT_PAYMENT_KEY, "success");
+  return current;
+}
+
+export async function setNextPaymentResult(result: PaymentResult): Promise<void> {
+  await setSetting(NEXT_PAYMENT_KEY, result);
+}
+
+export async function takeNextError(): Promise<NextError> {
+  const current = await getSetting<NextError>(NEXT_ERROR_KEY, "none");
+  await setSetting(NEXT_ERROR_KEY, "none");
+  return current;
+}
+
+export async function setNextError(error: NextError): Promise<void> {
+  await setSetting(NEXT_ERROR_KEY, error);
+}
+
+export async function getWebhookConfig(): Promise<WebhookConfig> {
+  const config = getConfig();
+  const fallback: WebhookConfig = {
+    delayMs: config.webhookDelayMs,
+    duplicate: config.webhookDuplicate,
+    drop: config.webhookDrop,
+    retryCount: config.webhookRetryCount,
+    retryDelayMs: config.webhookRetryDelayMs
+  };
+  return getSetting<WebhookConfig>(WEBHOOK_CONFIG_KEY, fallback);
+}
+
+export async function setWebhookConfig(value: WebhookConfig): Promise<void> {
+  await setSetting(WEBHOOK_CONFIG_KEY, value);
+}
+
+export async function setLastWebhook(value: unknown): Promise<void> {
+  await setSetting(LAST_WEBHOOK_KEY, value);
+}
+
+export async function getLastWebhook<T>(): Promise<T | null> {
+  return getSetting<T | null>(LAST_WEBHOOK_KEY, null);
+}
+
+export async function resetState(): Promise<void> {
+  await setSetting(NEXT_PAYMENT_KEY, "success");
+  await setSetting(NEXT_ERROR_KEY, "none");
+  await setWebhookConfig(await getWebhookConfig());
+}
+

package/src/core/utils.ts

@@ -0,0 +1,10 @@
+import crypto from "crypto";
+
+export function generateReference(prefix: string): string {
+  const random = crypto.randomBytes(6).toString("hex");
+  return `${prefix}_${Date.now()}_${random}`;
+}
+
+export function toKobo(amount: number): number {
+  return Math.round(amount * 100);
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from "./types/index.js";
+export { PaystackProvider } from "./providers/paystack/index.js";
+export { FlutterwaveProvider } from "./providers/flutterwave/index.js";

package/src/providers/flutterwave/index.ts

@@ -0,0 +1,254 @@
+import type { Express, Request, Response } from "express";
+
+import { getCollections } from "../../core/db.js";
+import { getConfig } from "../../core/config.js";
+import { generateReference } from "../../core/utils.js";
+import { takeNextPaymentResult } from "../../core/state.js";
+import { logger } from "../../core/logger.js";
+import { sendWebhook } from "../../webhooks/sender.js";
+import type { PaymentProvider, TransactionRecord } from "../../types/index.js";
+
+type CheckoutStatus = "success" | "failed" | "cancelled";
+
+function mapCheckoutStatusToFlutterwave(status: CheckoutStatus): "successful" | "failed" | "cancelled" {
+  if (status === "success") return "successful";
+  if (status === "failed") return "failed";
+  return "cancelled";
+}
+
+function mapCliStatusToFlutterwave(status: "success" | "failed" | "cancelled"): "successful" | "failed" | "cancelled" {
+  if (status === "success") return "successful";
+  if (status === "failed") return "failed";
+  return "cancelled";
+}
+
+function mapFlutterwaveStatusToCheckout(status: "successful" | "failed" | "cancelled"): CheckoutStatus {
+  if (status === "successful") return "success";
+  if (status === "failed") return "failed";
+  return "cancelled";
+}
+
+function webhookEventFromStatus(status: string): string {
+  if (status === "successful") return "charge.completed";
+  if (status === "cancelled") return "charge.cancelled";
+  return "charge.failed";
+}
+
+function buildVerifyResponse(transaction: any) {
+  return {
+    id: transaction.id,
+    tx_ref: transaction.reference,
+    flw_ref: `FLW-MOCK-${transaction.reference}`,
+    amount: transaction.amount,
+    currency: transaction.currency,
+    status: transaction.status,
+    customer: {
+      email: transaction.customerEmail,
+      name: transaction.customerName
+    }
+  };
+}
+
+export class FlutterwaveProvider implements PaymentProvider {
+  registerRoutes(app: Express): void {
+    app.post("/payments", this.initialize);
+    app.post("/mock/complete", this.completeCheckout);
+    app.get("/transactions/verify_by_reference", this.verifyByReference);
+    app.get("/transactions/:id/verify", this.verifyById);
+    app.post("/transfers", this.createTransfer);
+  }
+
+  private initialize = async (req: Request, res: Response) => {
+    const { transactions } = await getCollections();
+    const { frontendUrl, flutterwavePort } = getConfig();
+    const reference = generateReference("FLW");
+    const amount = Number(req.body?.amount ?? 0);
+    const email = String(req.body?.customer?.email ?? req.body?.email ?? "customer@example.com");
+    const name = req.body?.customer?.name
+      ? String(req.body?.customer?.name)
+      : req.body?.name
+      ? String(req.body?.name)
+      : null;
+    const currency = String(req.body?.currency ?? "NGN").toUpperCase();
+    const callbackUrl = req.body?.redirect_url || null;
+
+    const record: TransactionRecord = {
+      provider: "flutterwave",
+      reference,
+      status: "pending",
+      amount,
+      currency,
+      customerEmail: email,
+      customerName: name,
+      callbackUrl,
+      metadata: JSON.stringify(req.body?.meta ?? null)
+    };
+
+    await transactions.add(record);
+
+    const checkoutBase = frontendUrl ?? `http://localhost:${flutterwavePort}`;
+    const apiBase = `http://localhost:${flutterwavePort}`;
+    const checkoutUrl = new URL("/checkout", checkoutBase);
+    checkoutUrl.searchParams.set("provider", "flutterwave");
+    checkoutUrl.searchParams.set("api_base", apiBase);
+    checkoutUrl.searchParams.set("ref", reference);
+    checkoutUrl.searchParams.set("amount", String(amount));
+    checkoutUrl.searchParams.set("currency", currency);
+    checkoutUrl.searchParams.set("email", email);
+    if (name) checkoutUrl.searchParams.set("name", name);
+    if (callbackUrl) checkoutUrl.searchParams.set("redirect_url", callbackUrl);
+
+    res.json({
+      status: "success",
+      message: "Hosted Link created",
+      data: {
+        link: checkoutUrl.toString(),
+        tx_ref: reference,
+        amount,
+        currency,
+        customer: {
+          email,
+          name
+        },
+        api_base: apiBase
+      }
+    });
+  };
+
+  private completeCheckout = async (req: Request, res: Response) => {
+    const { transactions } = await getCollections();
+    const reference = String(req.body?.reference ?? "");
+    const checkoutStatus = String(req.body?.status ?? "") as CheckoutStatus;
+
+    if (!reference) {
+      res.status(400).json({ status: "error", message: "reference is required" });
+      return;
+    }
+
+    if (!["success", "failed", "cancelled"].includes(checkoutStatus)) {
+      res.status(400).json({ status: "error", message: "status must be success|failed|cancelled" });
+      return;
+    }
+
+    const transaction = await transactions.getOne({ reference, provider: "flutterwave" });
+    if (!transaction) {
+      res.status(404).json({ status: "error", message: "Transaction not found" });
+      return;
+    }
+
+    // CLI-driven result takes precedence over checkout input when configured.
+    const nextCliStatus = await takeNextPaymentResult();
+    const finalStatus =
+      nextCliStatus === "success"
+        ? mapCheckoutStatusToFlutterwave(checkoutStatus)
+        : mapCliStatusToFlutterwave(nextCliStatus);
+    await transactions.updateById(transaction.id, { status: finalStatus });
+    transaction.status = finalStatus;
+
+    const { defaultWebhookUrl } = getConfig();
+    if (defaultWebhookUrl) {
+      const event = webhookEventFromStatus(finalStatus);
+      void sendWebhook({
+        provider: "flutterwave",
+        event,
+        url: defaultWebhookUrl,
+        payload: {
+          event,
+          data: {
+            id: transaction.id,
+            tx_ref: transaction.reference,
+            status: finalStatus,
+            amount: transaction.amount,
+            currency: transaction.currency,
+            customer: {
+              email: transaction.customerEmail,
+              name: transaction.customerName
+            }
+          }
+        }
+      });
+    } else {
+      logger.warn("No default webhook URL provided for Flutterwave webhook", "flutterwave");
+    }
+
+    res.json({
+      status: "success",
+      message: "Checkout status captured",
+      data: {
+        transaction_id: transaction.id,
+        tx_ref: reference,
+        status: finalStatus,
+        checkout_status: mapFlutterwaveStatusToCheckout(finalStatus)
+      }
+    });
+  };
+
+  private verifyByReference = async (req: Request, res: Response) => {
+    const { transactions } = await getCollections();
+    const txRef = String(req.query?.tx_ref ?? "");
+
+    if (!txRef) {
+      res.status(400).json({ status: "error", message: "tx_ref query parameter is required" });
+      return;
+    }
+
+    const transaction = await transactions.getOne({ reference: txRef, provider: "flutterwave" });
+    if (!transaction) {
+      res.status(404).json({ status: "error", message: "Transaction not found" });
+      return;
+    }
+
+    res.json({
+      status: "success",
+      message: "Transaction fetched successfully",
+      data: buildVerifyResponse(transaction)
+    });
+  };
+
+  private verifyById = async (req: Request, res: Response) => {
+    const { transactions } = await getCollections();
+    const id = String(req.params.id ?? "");
+    const transaction = await transactions.getById(id);
+
+    if (!transaction || transaction.provider !== "flutterwave") {
+      res.status(404).json({ status: "error", message: "Transaction not found" });
+      return;
+    }
+
+    res.json({
+      status: "success",
+      message: "Transaction fetched successfully",
+      data: buildVerifyResponse(transaction)
+    });
+  };
+
+  private createTransfer = async (req: Request, res: Response) => {
+    const { transfers } = await getCollections();
+    const reference = generateReference("FLT");
+    const amount = Number(req.body?.amount ?? 0);
+
+    const transfer = await transfers.add({
+      provider: "flutterwave",
+      reference,
+      status: "pending",
+      amount,
+      currency: String(req.body?.currency ?? "NGN"),
+      bankCode: req.body?.bank_code ?? null,
+      accountNumber: req.body?.account_number ?? null,
+      narration: req.body?.narration ?? null,
+      metadata: JSON.stringify(req.body?.meta ?? null)
+    });
+
+    res.json({
+      status: "success",
+      message: "Transfer queued",
+      data: {
+        id: transfer.id,
+        reference: transfer.reference,
+        status: transfer.status,
+        amount: transfer.amount,
+        currency: transfer.currency
+      }
+    });
+  };
+}