openpay-ng 0.1.0

package/dist/connectors/flutterwave.js

@@ -0,0 +1,234 @@
+import { ConfigurationError, ValidationError } from "../core/errors.js";
+import { newId } from "../core/idempotency.js";
+import { normalizeAmount } from "../core/validation.js";
+import { firstHeader, providerJson } from "./http.js";
+const DEFAULT_BASE = "https://api.flutterwave.com/v3";
+export function mapFlutterwaveStatus(s) {
+    switch (s.toLowerCase()) {
+        case "successful":
+        case "success":
+        case "completed":
+            return "successful";
+        case "failed":
+        case "cancelled":
+            return "failed";
+        case "pending":
+        case "processing":
+        case "new":
+            return "pending";
+        default:
+            return "unknown";
+    }
+}
+export class FlutterwaveConnector {
+    name = "flutterwave";
+    capabilities = {
+        paymentsCreate: true,
+        paymentsVerify: true,
+        refunds: true,
+        transfers: true,
+        webhooks: true,
+    };
+    secretKey;
+    baseUrl;
+    timeoutMs;
+    http;
+    webhookSecret;
+    constructor(cfg) {
+        if (!cfg.secretKey)
+            throw new ConfigurationError("Flutterwave secret key is required");
+        this.secretKey = cfg.secretKey;
+        this.baseUrl = (cfg.baseUrl ?? DEFAULT_BASE).replace(/\/$/, "");
+        this.timeoutMs = cfg.timeoutMs ?? 15_000;
+        this.http = cfg.http;
+        this.webhookSecret = cfg.webhookSecretHash ?? cfg.secretKey;
+    }
+    headers() {
+        return { Authorization: `Bearer ${this.secretKey}` };
+    }
+    async createPayment(input) {
+        // Provider evidence (sandbox 400: "Redirect URL is required"): Flutterwave
+        // mandates redirect_url on POST /v3/payments. Fail fast with a clear SDK
+        // error instead of an opaque provider rejection.
+        if (!input.redirectUrl) {
+            throw new ValidationError("Flutterwave requires redirectUrl for payments.create()");
+        }
+        const amount = normalizeAmount(input.amount);
+        const data = await providerJson(`${this.baseUrl}/payments`, {
+            method: "POST",
+            headers: this.headers(),
+            body: {
+                tx_ref: input.reference,
+                amount,
+                currency: input.currency,
+                customer: { email: input.customer.email, name: input.customer.name, phonenumber: input.customer.phone },
+                redirect_url: input.redirectUrl,
+                meta: input.metadata,
+            },
+            timeoutMs: this.timeoutMs,
+            provider: "flutterwave",
+            reference: input.reference,
+            http: this.http,
+        });
+        return {
+            id: newId(),
+            provider: "flutterwave",
+            reference: input.reference,
+            providerRef: data.data.flw_ref ?? input.reference,
+            amount,
+            currency: input.currency,
+            status: "pending",
+            checkoutUrl: data.data.link,
+            customerEmail: input.customer.email,
+            raw: data,
+        };
+    }
+    async verifyPayment(input) {
+        // Prefer verify-by-reference so callers can use the merchant tx_ref.
+        const data = await providerJson(`${this.baseUrl}/transactions/verify_by_reference?tx_ref=${encodeURIComponent(input.reference)}`, {
+            headers: this.headers(),
+            timeoutMs: this.timeoutMs,
+            provider: "flutterwave",
+            reference: input.reference,
+            http: this.http,
+        });
+        const d = data.data;
+        return {
+            id: newId(),
+            provider: "flutterwave",
+            reference: d.tx_ref,
+            providerRef: String(d.id),
+            amount: Number(d.amount).toFixed(2),
+            currency: d.currency,
+            status: mapFlutterwaveStatus(d.status),
+            customerEmail: d.customer?.email,
+            raw: data,
+        };
+    }
+    async createRefund(input) {
+        // Flutterwave refunds address the numeric transaction id.
+        // verifyPayment() stores it in providerRef; callers may also pass it directly.
+        const data = await providerJson(`${this.baseUrl}/transactions/${encodeURIComponent(input.paymentReference)}/refund`, {
+            method: "POST",
+            headers: this.headers(),
+            body: {
+                amount: input.amount ? normalizeAmount(input.amount) : undefined,
+                comments: input.reason,
+            },
+            timeoutMs: this.timeoutMs,
+            provider: "flutterwave",
+            reference: input.paymentReference,
+            http: this.http,
+        });
+        const s = String(data.data.status).toLowerCase();
+        return {
+            id: newId(),
+            provider: "flutterwave",
+            paymentReference: input.paymentReference,
+            providerRef: String(data.data.id),
+            amount: normalizeAmount(input.amount ?? "0.00"),
+            currency: input.currency ?? "NGN",
+            status: s.startsWith("completed") ? "successful" : s === "failed" ? "failed" : "pending",
+            raw: data,
+        };
+    }
+    async createTransfer(input) {
+        const data = await providerJson(`${this.baseUrl}/transfers`, {
+            method: "POST",
+            headers: this.headers(),
+            body: {
+                account_bank: input.bankCode,
+                account_number: input.accountNumber,
+                amount: normalizeAmount(input.amount),
+                currency: input.currency,
+                narration: input.narration,
+                reference: input.reference,
+                meta: input.metadata,
+            },
+            timeoutMs: this.timeoutMs,
+            provider: "flutterwave",
+            reference: input.reference,
+            http: this.http,
+        });
+        return {
+            id: newId(),
+            provider: "flutterwave",
+            reference: input.reference,
+            providerRef: String(data.data.id),
+            amount: normalizeAmount(input.amount),
+            currency: input.currency,
+            status: mapFlutterwaveStatus(data.data.status),
+            raw: data,
+        };
+    }
+    async verifyTransfer(reference) {
+        const data = await providerJson(`${this.baseUrl}/transfers/${encodeURIComponent(reference)}`, {
+            headers: this.headers(),
+            timeoutMs: this.timeoutMs,
+            provider: "flutterwave",
+            reference,
+            http: this.http,
+        });
+        return {
+            id: newId(),
+            provider: "flutterwave",
+            reference: data.data.reference,
+            providerRef: String(data.data.id),
+            amount: Number(data.data.amount).toFixed(2),
+            currency: data.data.currency,
+            status: mapFlutterwaveStatus(data.data.status),
+            raw: data,
+        };
+    }
+    verifyWebhookSignature(_rawBody, headers) {
+        // Flutterwave sends `verif-hash` == your webhook secret hash (dashboard setting).
+        const h = firstHeader(headers, "verif-hash", "Verif-Hash");
+        if (!h)
+            return false;
+        return h === this.webhookSecret;
+    }
+    normalizeWebhook(payload) {
+        if (typeof payload !== "object" || payload === null)
+            return null;
+        const p = payload;
+        if (p.event)
+            return this.normalizeDocumentedShape(p, payload);
+        // Flat sandbox charge shape: top-level txRef identifies the payment.
+        const txRef = p.txRef ?? p.tx_ref;
+        if (txRef) {
+            const ok = (p.status ?? "").toLowerCase() === "successful";
+            return {
+                type: ok ? "payment.succeeded" : "payment.failed",
+                provider: "flutterwave",
+                providerEventId: p.flwRef ?? (p.id !== undefined ? String(p.id) : undefined),
+                reference: txRef,
+                raw: payload,
+            };
+        }
+        return null;
+    }
+    /** Documented `{event, data}` envelope shape. Unchanged behavior. */
+    normalizeDocumentedShape(p, payload) {
+        if (p.event === "charge.completed") {
+            const ok = (p.data?.status ?? "").toLowerCase() === "successful";
+            return {
+                type: ok ? "payment.succeeded" : "payment.failed",
+                provider: "flutterwave",
+                providerEventId: p.data?.id ? String(p.data.id) : undefined,
+                reference: p.data?.tx_ref ?? p.data?.reference,
+                raw: payload,
+            };
+        }
+        if (p.event === "transfer.completed") {
+            const ok = ["successful", "success"].includes((p.data?.status ?? "").toLowerCase());
+            return {
+                type: ok ? "transfer.succeeded" : "transfer.failed",
+                provider: "flutterwave",
+                providerEventId: p.data?.id ? String(p.data.id) : undefined,
+                reference: p.data?.reference ?? p.data?.tx_ref,
+                raw: payload,
+            };
+        }
+        return { type: "unknown", provider: "flutterwave", raw: payload };
+    }
+}

package/dist/connectors/http.d.ts

@@ -0,0 +1,18 @@
+import type { WebhookHeaders } from "../core/types.js";
+import type { HttpClient } from "./types.js";
+/**
+ * First value wins for repeated headers. String inputs behave exactly as
+ * before; this only additionally accepts Node/Express-style string arrays.
+ */
+export declare function firstHeader(headers: WebhookHeaders, ...names: string[]): string | undefined;
+export interface RequestOptions {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: unknown;
+    timeoutMs?: number;
+    provider: string;
+    reference?: string;
+    http?: HttpClient;
+}
+/** JSON request with timeout. Timeouts/network errors -> UnknownResultError (never auto-fail). */
+export declare function providerJson<T>(url: string, opts: RequestOptions): Promise<T>;

package/dist/connectors/http.js

@@ -0,0 +1,59 @@
+import { ProviderError, UnknownResultError } from "../core/errors.js";
+/**
+ * First value wins for repeated headers. String inputs behave exactly as
+ * before; this only additionally accepts Node/Express-style string arrays.
+ */
+export function firstHeader(headers, ...names) {
+    for (const name of names) {
+        const v = headers[name];
+        if (Array.isArray(v))
+            return v[0];
+        if (v !== undefined)
+            return v;
+    }
+    return undefined;
+}
+/** JSON request with timeout. Timeouts/network errors -> UnknownResultError (never auto-fail). */
+export async function providerJson(url, opts) {
+    const http = opts.http ?? ((u, init) => fetch(u, init));
+    const timeoutMs = opts.timeoutMs ?? 15_000;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await http(url, {
+            method: opts.method ?? "GET",
+            headers: { "Content-Type": "application/json", ...(opts.headers ?? {}) },
+            body: opts.body === undefined ? undefined : JSON.stringify(opts.body),
+            signal: controller.signal,
+        });
+        const text = await res.text();
+        let json = null;
+        try {
+            json = text ? JSON.parse(text) : null;
+        }
+        catch {
+            json = { _rawText: text };
+        }
+        if (!res.ok) {
+            const message = typeof json === "object" && json !== null && "message" in json
+                ? String(json.message)
+                : `HTTP ${res.status}`;
+            throw new ProviderError(message, {
+                provider: opts.provider,
+                status: res.status,
+                retryable: res.status >= 500 || res.status === 429,
+                raw: json,
+            });
+        }
+        return json;
+    }
+    catch (err) {
+        if (err instanceof ProviderError)
+            throw err;
+        const aborted = err instanceof Error && (err.name === "AbortError" || /abort/i.test(err.message));
+        throw new UnknownResultError(opts.provider, opts.reference ?? url, err);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/connectors/paystack.d.ts

@@ -0,0 +1,28 @@
+import type { CreatePaymentInput, CreateRefundInput, CreateTransferInput, OpenPayEvent, Payment, PaymentStatus, ProviderCapabilities, Refund, Transfer, VerifyPaymentInput, WebhookHeaders } from "../core/types.js";
+import type { ConnectorConfig, ProviderConnector } from "./types.js";
+export declare function mapPaystackPaymentStatus(s: string): PaymentStatus;
+export declare class PaystackConnector implements ProviderConnector {
+    readonly name: "paystack";
+    readonly capabilities: ProviderCapabilities;
+    private secretKey;
+    private baseUrl;
+    private timeoutMs;
+    private http;
+    private webhookSecret;
+    constructor(cfg: ConnectorConfig & {
+        webhookSecret?: string;
+    });
+    private headers;
+    createPayment(input: CreatePaymentInput & {
+        reference: string;
+    }): Promise<Payment>;
+    verifyPayment(input: VerifyPaymentInput): Promise<Payment>;
+    createRefund(input: CreateRefundInput): Promise<Refund>;
+    createTransfer(input: CreateTransferInput & {
+        reference: string;
+    }): Promise<Transfer>;
+    verifyTransfer(reference: string): Promise<Transfer>;
+    verifyWebhookSignature(rawBody: string | Buffer, headers: WebhookHeaders): boolean;
+    normalizeWebhook(payload: unknown): OpenPayEvent | null;
+    assertSupports(op: "refunds" | "transfers"): void;
+}

package/dist/connectors/paystack.js

@@ -0,0 +1,238 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { CapabilityError, ConfigurationError } from "../core/errors.js";
+import { newId } from "../core/idempotency.js";
+import { normalizeAmount, toMinorUnits } from "../core/validation.js";
+import { firstHeader, providerJson } from "./http.js";
+const DEFAULT_BASE = "https://api.paystack.co";
+export function mapPaystackPaymentStatus(s) {
+    switch (s.toLowerCase()) {
+        case "success":
+            return "successful";
+        case "failed":
+        case "abandoned":
+            return "failed";
+        case "reversed":
+            return "successful"; // money moved; reversal/refund tracked separately
+        case "pending":
+        case "ongoing":
+        case "processing":
+        case "queued":
+            return "pending";
+        default:
+            return "unknown";
+    }
+}
+export class PaystackConnector {
+    name = "paystack";
+    capabilities = {
+        paymentsCreate: true,
+        paymentsVerify: true,
+        refunds: true,
+        transfers: true,
+        webhooks: true,
+    };
+    secretKey;
+    baseUrl;
+    timeoutMs;
+    http;
+    webhookSecret;
+    constructor(cfg) {
+        if (!cfg.secretKey)
+            throw new ConfigurationError("Paystack secret key is required");
+        this.secretKey = cfg.secretKey;
+        this.baseUrl = (cfg.baseUrl ?? DEFAULT_BASE).replace(/\/$/, "");
+        this.timeoutMs = cfg.timeoutMs ?? 15_000;
+        this.http = cfg.http;
+        this.webhookSecret = cfg.webhookSecret ?? cfg.secretKey;
+    }
+    headers() {
+        return { Authorization: `Bearer ${this.secretKey}` };
+    }
+    async createPayment(input) {
+        const amount = normalizeAmount(input.amount);
+        const data = await providerJson(`${this.baseUrl}/transaction/initialize`, {
+            method: "POST",
+            headers: this.headers(),
+            body: {
+                email: input.customer.email,
+                amount: toMinorUnits(amount),
+                reference: input.reference,
+                currency: input.currency,
+                callback_url: input.redirectUrl,
+                metadata: input.metadata,
+            },
+            timeoutMs: this.timeoutMs,
+            provider: "paystack",
+            reference: input.reference,
+            http: this.http,
+        });
+        return {
+            id: newId(),
+            provider: "paystack",
+            reference: input.reference,
+            providerRef: data.data.reference,
+            amount,
+            currency: input.currency,
+            status: "pending",
+            checkoutUrl: data.data.authorization_url,
+            customerEmail: input.customer.email,
+            raw: data,
+        };
+    }
+    async verifyPayment(input) {
+        const data = await providerJson(`${this.baseUrl}/transaction/verify/${encodeURIComponent(input.reference)}`, {
+            headers: this.headers(),
+            timeoutMs: this.timeoutMs,
+            provider: "paystack",
+            reference: input.reference,
+            http: this.http,
+        });
+        const d = data.data;
+        return {
+            id: newId(),
+            provider: "paystack",
+            reference: d.reference,
+            providerRef: d.reference,
+            amount: (d.amount / 100).toFixed(2),
+            currency: d.currency,
+            status: mapPaystackPaymentStatus(d.status),
+            customerEmail: d.customer?.email,
+            raw: data,
+        };
+    }
+    async createRefund(input) {
+        const data = await providerJson(`${this.baseUrl}/refund`, {
+            method: "POST",
+            headers: this.headers(),
+            body: {
+                transaction: input.paymentReference,
+                amount: input.amount ? toMinorUnits(normalizeAmount(input.amount)) : undefined,
+            },
+            timeoutMs: this.timeoutMs,
+            provider: "paystack",
+            reference: input.paymentReference,
+            http: this.http,
+        });
+        const s = String(data.data.status).toLowerCase();
+        const status = s === "processed" ? "successful" : s === "failed" ? "failed" : s === "pending" || s === "processing" ? "pending" : "unknown";
+        return {
+            id: newId(),
+            provider: "paystack",
+            paymentReference: input.paymentReference,
+            providerRef: String(data.data.id),
+            amount: normalizeAmount(input.amount ?? "0.00"),
+            currency: input.currency ?? "NGN",
+            status,
+            raw: data,
+        };
+    }
+    async createTransfer(input) {
+        // Step 1: create recipient, Step 2: initiate transfer
+        const recipient = await providerJson(`${this.baseUrl}/transferrecipient`, {
+            method: "POST",
+            headers: this.headers(),
+            body: {
+                type: "nuban",
+                name: input.accountName ?? input.accountNumber,
+                account_number: input.accountNumber,
+                bank_code: input.bankCode,
+                currency: input.currency,
+            },
+            timeoutMs: this.timeoutMs,
+            provider: "paystack",
+            reference: input.reference,
+            http: this.http,
+        });
+        const transfer = await providerJson(`${this.baseUrl}/transfer`, {
+            method: "POST",
+            headers: this.headers(),
+            body: {
+                source: "balance",
+                amount: toMinorUnits(normalizeAmount(input.amount)),
+                recipient: recipient.data.recipient_code,
+                reference: input.reference,
+                reason: input.narration,
+            },
+            timeoutMs: this.timeoutMs,
+            provider: "paystack",
+            reference: input.reference,
+            http: this.http,
+        });
+        const s = transfer.data.status.toLowerCase();
+        return {
+            id: newId(),
+            provider: "paystack",
+            reference: input.reference,
+            providerRef: transfer.data.reference,
+            amount: normalizeAmount(input.amount),
+            currency: input.currency,
+            status: s === "success" ? "successful" : s === "failed" ? "failed" : "pending",
+            raw: { recipient, transfer },
+        };
+    }
+    async verifyTransfer(reference) {
+        const data = await providerJson(`${this.baseUrl}/transfer/verify/${encodeURIComponent(reference)}`, {
+            headers: this.headers(),
+            timeoutMs: this.timeoutMs,
+            provider: "paystack",
+            reference,
+            http: this.http,
+        });
+        const s = data.data.status.toLowerCase();
+        return {
+            id: newId(),
+            provider: "paystack",
+            reference: data.data.reference,
+            providerRef: data.data.reference,
+            amount: (data.data.amount / 100).toFixed(2),
+            currency: data.data.currency,
+            status: s === "success" ? "successful" : s === "failed" ? "failed" : s === "pending" ? "pending" : "unknown",
+            raw: data,
+        };
+    }
+    verifyWebhookSignature(rawBody, headers) {
+        const sig = firstHeader(headers, "x-paystack-signature", "X-Paystack-Signature");
+        if (!sig)
+            return false;
+        const digest = createHmac("sha512", this.webhookSecret).update(rawBody).digest("hex");
+        const a = Buffer.from(digest);
+        const b = Buffer.from(sig);
+        return a.length === b.length && timingSafeEqual(a, b);
+    }
+    normalizeWebhook(payload) {
+        if (typeof payload !== "object" || payload === null)
+            return null;
+        const p = payload;
+        if (!p.event)
+            return null;
+        const map = {
+            "charge.success": "payment.succeeded",
+            "charge.failed": "payment.failed",
+            "transfer.success": "transfer.succeeded",
+            "transfer.failed": "transfer.failed",
+            "transfer.reversed": "transfer.failed",
+            "refund.processed": "refund.processed",
+            "refund.failed": "refund.failed",
+            "refund.pending": "payment.pending",
+            "refund.processing": "payment.pending",
+        };
+        const type = map[p.event] ?? "unknown";
+        // Stable dedupe id: numeric object id where present, otherwise the
+        // provider's own references (refund retries share refund_reference).
+        const eventId = p.data?.id !== undefined
+            ? String(p.data.id)
+            : (p.data?.refund_reference ?? p.data?.transaction_reference ?? p.data?.reference);
+        return {
+            type,
+            provider: "paystack",
+            providerEventId: eventId,
+            reference: p.data?.reference ?? p.data?.transaction_reference,
+            raw: payload,
+        };
+    }
+    // Narrowing helper so TS keeps `capabilities` honest if extended later.
+    assertSupports(op) {
+        if (!this.capabilities[op])
+            throw new CapabilityError("paystack", op);
+    }
+}

package/dist/connectors/service.d.ts

@@ -0,0 +1,12 @@
+import type { CreatePaymentInput, CreateRefundInput, CreateTransferInput, Payment, ProviderName, Refund, Transfer, VerifyPaymentInput } from "../core/types.js";
+import type { Persistence } from "../db/store.js";
+import type { ProviderConnector } from "./types.js";
+export interface ServiceContext {
+    connectors: Record<ProviderName, ProviderConnector>;
+    defaultProvider: ProviderName;
+    persistence?: Persistence;
+}
+export declare function createPayment(ctx: ServiceContext, input: CreatePaymentInput): Promise<Payment>;
+export declare function verifyPayment(ctx: ServiceContext, input: VerifyPaymentInput): Promise<Payment>;
+export declare function createTransfer(ctx: ServiceContext, input: CreateTransferInput): Promise<Transfer>;
+export declare function createRefund(ctx: ServiceContext, input: CreateRefundInput): Promise<Refund>;