openpay-ng 0.1.0

package/dist/db/schema.js

@@ -0,0 +1,62 @@
+import { jsonb, pgTable, text, timestamp, uniqueIndex, uuid } from "drizzle-orm/pg-core";
+/**
+ * Minimal V1 persistence. Only what reliability rules need:
+ * payments / transfers / refunds ledger rows + idempotency keys + webhook events.
+ * No business logic in SQL — constraints only.
+ */
+export const payments = pgTable("payments", {
+    id: uuid("id").primaryKey(),
+    provider: text("provider").notNull(),
+    reference: text("reference").notNull().unique(),
+    providerRef: text("provider_ref").notNull(),
+    amount: text("amount").notNull(),
+    currency: text("currency").notNull(),
+    status: text("status").notNull(),
+    customerEmail: text("customer_email"),
+    checkoutUrl: text("checkout_url"),
+    raw: jsonb("raw"),
+    createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).defaultNow().notNull(),
+});
+export const transfers = pgTable("transfers", {
+    id: uuid("id").primaryKey(),
+    provider: text("provider").notNull(),
+    reference: text("reference").notNull().unique(),
+    providerRef: text("provider_ref").notNull(),
+    amount: text("amount").notNull(),
+    currency: text("currency").notNull(),
+    status: text("status").notNull(),
+    raw: jsonb("raw"),
+    createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+});
+export const refunds = pgTable("refunds", {
+    id: uuid("id").primaryKey(),
+    provider: text("provider").notNull(),
+    paymentReference: text("payment_reference").notNull(),
+    providerRef: text("provider_ref").notNull(),
+    amount: text("amount").notNull(),
+    currency: text("currency").notNull(),
+    status: text("status").notNull(),
+    raw: jsonb("raw"),
+    createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+});
+export const idempotencyKeys = pgTable("idempotency_keys", {
+    key: text("key").primaryKey(),
+    operation: text("operation").notNull(),
+    provider: text("provider").notNull(),
+    response: jsonb("response").notNull(),
+    createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+});
+export const webhookEvents = pgTable("webhook_events", {
+    id: uuid("id").primaryKey(),
+    provider: text("provider").notNull(),
+    eventId: text("event_id"),
+    type: text("type").notNull(),
+    reference: text("reference"),
+    payload: jsonb("payload").notNull(),
+    createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+}, (t) => [
+    // Retried deliveries of the same provider event collapse into one row.
+    // eventId is always populated at insert time (real id or content hash).
+    uniqueIndex("webhook_events_provider_type_event_uidx").on(t.provider, t.type, t.eventId),
+]);

package/dist/db/store.d.ts

@@ -0,0 +1,60 @@
+import type { OpenPayEvent, Payment, PaymentStatus, ProviderName, Refund, Transfer } from "../core/types.js";
+import type { Db } from "./client.js";
+/**
+ * Resolve a non-null dedupe id for a webhook event.
+ * Real provider event id when available, otherwise a stable content hash
+ * (identical retried deliveries produce identical hashes).
+ */
+export declare function resolveWebhookEventId(event: OpenPayEvent, raw: unknown): string;
+/**
+ * Persistence port. Services depend on this interface, not on Drizzle directly.
+ * Production: DrizzlePersistence. Tests / stateless mode: MemoryPersistence.
+ */
+export interface Persistence {
+    findIdempotency<T>(key: string): Promise<T | null>;
+    saveIdempotency(key: string, operation: string, provider: string, response: unknown): Promise<void>;
+    savePayment(payment: Payment): Promise<void>;
+    saveTransfer(transfer: Transfer): Promise<void>;
+    saveRefund(refund: Refund): Promise<void>;
+    /**
+     * Persist a webhook event. Returns true when newly inserted, false when
+     * this exact event was already recorded (duplicate delivery).
+     * Existing callers may ignore the return value.
+     */
+    saveWebhookEvent(event: OpenPayEvent, raw: unknown): Promise<boolean>;
+    /**
+     * Set a payment's status, matching provider + (reference OR providerRef).
+     * Returns true when a row was updated, false when no payment matched.
+     * Status-only write: never touches amount/currency/refs. Idempotent.
+     */
+    updatePaymentStatus(provider: ProviderName, reference: string, status: PaymentStatus): Promise<boolean>;
+}
+export declare class MemoryPersistence implements Persistence {
+    private idem;
+    private seenWebhooks;
+    readonly paymentRows: Payment[];
+    readonly transferRows: Transfer[];
+    readonly refundRows: Refund[];
+    readonly webhookRows: {
+        event: OpenPayEvent;
+        raw: unknown;
+    }[];
+    findIdempotency<T>(key: string): Promise<T | null>;
+    saveIdempotency(key: string, _op: string, _provider: string, response: unknown): Promise<void>;
+    savePayment(payment: Payment): Promise<void>;
+    saveTransfer(transfer: Transfer): Promise<void>;
+    saveRefund(refund: Refund): Promise<void>;
+    saveWebhookEvent(event: OpenPayEvent, raw: unknown): Promise<boolean>;
+    updatePaymentStatus(provider: ProviderName, reference: string, status: PaymentStatus): Promise<boolean>;
+}
+export declare class DrizzlePersistence implements Persistence {
+    private db;
+    constructor(db: Db);
+    findIdempotency<T>(key: string): Promise<T | null>;
+    saveIdempotency(key: string, operation: string, provider: string, response: unknown): Promise<void>;
+    savePayment(payment: Payment): Promise<void>;
+    saveTransfer(transfer: Transfer): Promise<void>;
+    saveRefund(refund: Refund): Promise<void>;
+    updatePaymentStatus(provider: ProviderName, reference: string, status: PaymentStatus): Promise<boolean>;
+    saveWebhookEvent(event: OpenPayEvent, raw: unknown): Promise<boolean>;
+}

package/dist/db/store.js

@@ -0,0 +1,159 @@
+import { createHash } from "node:crypto";
+import { newId } from "../core/idempotency.js";
+import { idempotencyKeys, payments, refunds, transfers, webhookEvents } from "./schema.js";
+/**
+ * Resolve a non-null dedupe id for a webhook event.
+ * Real provider event id when available, otherwise a stable content hash
+ * (identical retried deliveries produce identical hashes).
+ */
+export function resolveWebhookEventId(event, raw) {
+    if (event.providerEventId)
+        return event.providerEventId;
+    return createHash("sha256")
+        .update(typeof raw === "string" ? raw : JSON.stringify(raw))
+        .digest("hex");
+}
+export class MemoryPersistence {
+    idem = new Map();
+    seenWebhooks = new Set();
+    paymentRows = [];
+    transferRows = [];
+    refundRows = [];
+    webhookRows = [];
+    async findIdempotency(key) {
+        return this.idem.get(key) ?? null;
+    }
+    async saveIdempotency(key, _op, _provider, response) {
+        // First write wins — repeated requests must not create duplicates.
+        if (!this.idem.has(key))
+            this.idem.set(key, response);
+    }
+    async savePayment(payment) {
+        const i = this.paymentRows.findIndex((p) => p.reference === payment.reference);
+        if (i >= 0)
+            this.paymentRows[i] = payment;
+        else
+            this.paymentRows.push(payment);
+    }
+    async saveTransfer(transfer) {
+        this.transferRows.push(transfer);
+    }
+    async saveRefund(refund) {
+        this.refundRows.push(refund);
+    }
+    async saveWebhookEvent(event, raw) {
+        const key = `${event.provider}\n${event.type}\n${resolveWebhookEventId(event, raw)}`;
+        if (this.seenWebhooks.has(key))
+            return false;
+        this.seenWebhooks.add(key);
+        this.webhookRows.push({ event, raw });
+        return true;
+    }
+    async updatePaymentStatus(provider, reference, status) {
+        const row = this.paymentRows.find((p) => p.provider === provider && (p.reference === reference || p.providerRef === reference));
+        if (!row)
+            return false;
+        row.status = status;
+        return true;
+    }
+}
+export class DrizzlePersistence {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async findIdempotency(key) {
+        const { eq } = await import("drizzle-orm");
+        const rows = await this.db
+            .select()
+            .from(idempotencyKeys)
+            .where(eq(idempotencyKeys.key, key))
+            .limit(1);
+        const row = rows[0];
+        return row ? row.response : null;
+    }
+    async saveIdempotency(key, operation, provider, response) {
+        await this.db
+            .insert(idempotencyKeys)
+            .values({ key, operation, provider, response: response })
+            .onConflictDoNothing({ target: idempotencyKeys.key });
+    }
+    async savePayment(payment) {
+        await this.db
+            .insert(payments)
+            .values({
+            id: payment.id,
+            provider: payment.provider,
+            reference: payment.reference,
+            providerRef: payment.providerRef,
+            amount: payment.amount,
+            currency: payment.currency,
+            status: payment.status,
+            customerEmail: payment.customerEmail,
+            checkoutUrl: payment.checkoutUrl,
+            raw: payment.raw,
+        })
+            .onConflictDoUpdate({
+            target: payments.reference,
+            set: {
+                providerRef: payment.providerRef,
+                status: payment.status,
+                checkoutUrl: payment.checkoutUrl,
+                raw: payment.raw,
+                updatedAt: new Date(),
+            },
+        });
+    }
+    async saveTransfer(transfer) {
+        await this.db.insert(transfers).values({
+            id: transfer.id,
+            provider: transfer.provider,
+            reference: transfer.reference,
+            providerRef: transfer.providerRef,
+            amount: transfer.amount,
+            currency: transfer.currency,
+            status: transfer.status,
+            raw: transfer.raw,
+        });
+    }
+    async saveRefund(refund) {
+        await this.db.insert(refunds).values({
+            id: refund.id,
+            provider: refund.provider,
+            paymentReference: refund.paymentReference,
+            providerRef: refund.providerRef,
+            amount: refund.amount,
+            currency: refund.currency,
+            status: refund.status,
+            raw: refund.raw,
+        });
+    }
+    async updatePaymentStatus(provider, reference, status) {
+        const { and, eq, or } = await import("drizzle-orm");
+        const rows = await this.db
+            .update(payments)
+            .set({ status, updatedAt: new Date() })
+            .where(and(eq(payments.provider, provider), or(eq(payments.reference, reference), eq(payments.providerRef, reference))))
+            .returning({ id: payments.id });
+        return rows.length > 0;
+    }
+    async saveWebhookEvent(event, raw) {
+        // The unique index is the concurrency arbiter: simultaneous duplicate
+        // deliveries collapse into one row, and RETURNING tells us if we won.
+        const rows = await this.db
+            .insert(webhookEvents)
+            .values({
+            id: newId(),
+            provider: event.provider,
+            eventId: resolveWebhookEventId(event, raw),
+            type: event.type,
+            reference: event.reference,
+            payload: raw,
+        })
+            .onConflictDoNothing({
+            target: [webhookEvents.provider, webhookEvents.type, webhookEvents.eventId],
+        })
+            .returning({ id: webhookEvents.id });
+        return rows.length > 0;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { OpenPay, default } from "./sdk.js";
+export type { OpenPayConfig, ProviderConf } from "./config.js";
+export * from "./core/types.js";
+export * from "./core/errors.js";
+export { normalizeAmount, toMinorUnits } from "./core/validation.js";
+export type { WebhookResult } from "./webhooks/service.js";

package/dist/index.js

@@ -0,0 +1,8 @@
+// Public API surface (V1). Intentionally small: the OpenPay class, config and
+// domain types, catchable errors, and amount helpers. Connector classes,
+// context resolution, and persistence implementations are internal — import
+// them from their modules directly if you really need them.
+export { OpenPay, default } from "./sdk.js";
+export * from "./core/types.js";
+export * from "./core/errors.js";
+export { normalizeAmount, toMinorUnits } from "./core/validation.js";

package/dist/sdk.d.ts

@@ -0,0 +1,28 @@
+import { type OpenPayConfig } from "./config.js";
+import type { CreatePaymentInput, CreateRefundInput, CreateTransferInput, OpenPayEvent, Payment, ProviderName, Refund, Transfer, VerifyPaymentInput, WebhookHeaders } from "./core/types.js";
+import { type WebhookResult } from "./webhooks/service.js";
+export declare class OpenPay {
+    private ctx;
+    constructor(config?: OpenPayConfig);
+    readonly payments: {
+        create: (input: CreatePaymentInput) => Promise<Payment>;
+        verify: (input: VerifyPaymentInput) => Promise<Payment>;
+        retrieve: (input: VerifyPaymentInput) => Promise<Payment>;
+    };
+    readonly transfers: {
+        create: (input: CreateTransferInput) => Promise<Transfer>;
+        verify: (reference: string, provider?: ProviderName) => Promise<Transfer>;
+    };
+    readonly refunds: {
+        create: (input: CreateRefundInput) => Promise<Refund>;
+    };
+    readonly webhooks: {
+        /** Verify + normalize a raw webhook body. Persists the event when persistence is enabled. */
+        normalize: (provider: ProviderName, rawBody: string | Buffer, headers: WebhookHeaders) => Promise<OpenPayEvent | null>;
+        /** Same as normalize, but also reports retried (duplicate) deliveries. */
+        normalizeDetailed: (provider: ProviderName, rawBody: string | Buffer, headers: WebhookHeaders) => Promise<WebhookResult>;
+    };
+    /** Which providers are configured in this instance. */
+    configuredProviders(): ProviderName[];
+}
+export default OpenPay;

package/dist/sdk.js

@@ -0,0 +1,59 @@
+/**
+ * OpenPay NG — public SDK entry.
+ *
+ * ```ts
+ * const openpay = new OpenPay({ provider: "paystack", secretKey: "sk_test_..." });
+ * const payment = await openpay.payments.create({
+ *   amount: "5000.00",
+ *   currency: "NGN",
+ *   customer: { email: "customer@example.com" },
+ * });
+ * ```
+ */
+import { createPayment, createRefund, createTransfer, verifyPayment } from "./connectors/service.js";
+import { resolveContext } from "./config.js";
+import { CapabilityError } from "./core/errors.js";
+import { handleWebhook, handleWebhookDetailed } from "./webhooks/service.js";
+export class OpenPay {
+    ctx;
+    constructor(config = {}) {
+        this.ctx = resolveContext(config);
+    }
+    payments = {
+        create: (input) => createPayment(this.ctx, input),
+        verify: (input) => verifyPayment(this.ctx, input),
+        retrieve: (input) => verifyPayment(this.ctx, input),
+    };
+    transfers = {
+        create: (input) => createTransfer(this.ctx, input),
+        verify: (reference, provider) => {
+            const name = provider ?? this.ctx.defaultProvider;
+            const c = this.ctx.connectors[name];
+            if (!c.capabilities.transfers)
+                throw new CapabilityError(name, "transfers");
+            return c.verifyTransfer(reference);
+        },
+    };
+    refunds = {
+        create: (input) => createRefund(this.ctx, input),
+    };
+    webhooks = {
+        /** Verify + normalize a raw webhook body. Persists the event when persistence is enabled. */
+        normalize: (provider, rawBody, headers) => handleWebhook(this.ctx, provider, rawBody, headers),
+        /** Same as normalize, but also reports retried (duplicate) deliveries. */
+        normalizeDetailed: (provider, rawBody, headers) => handleWebhookDetailed(this.ctx, provider, rawBody, headers),
+    };
+    /** Which providers are configured in this instance. */
+    configuredProviders() {
+        return Object.keys(this.ctx.connectors).filter((k) => {
+            try {
+                void this.ctx.connectors[k];
+                return true;
+            }
+            catch {
+                return false;
+            }
+        });
+    }
+}
+export default OpenPay;

package/dist/server.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Thin local webhook receiver for OpenPay NG (V1).
+ *
+ * This is intentionally dependency-free (Node built-in `http` only).
+ * All verification / normalization / persistence logic lives in the SDK —
+ * this server only transports the RAW body + headers into:
+ *   openpay.webhooks.normalizeDetailed(provider, rawBody, headers)
+ *
+ * Raw body preservation is critical: Paystack's HMAC-SHA512 signature is
+ * computed over the exact request bytes, so no JSON parsing happens first.
+ * (Flutterwave compares the `verif-hash` header instead, but the transport
+ * stays identical.)
+ */
+import 'dotenv/config';
+import { type Server } from 'node:http';
+import { OpenPay } from './sdk.js';
+export declare function createWebhookServer(openpay: OpenPay): Server;

package/dist/server.js

@@ -0,0 +1,137 @@
+/**
+ * Thin local webhook receiver for OpenPay NG (V1).
+ *
+ * This is intentionally dependency-free (Node built-in `http` only).
+ * All verification / normalization / persistence logic lives in the SDK —
+ * this server only transports the RAW body + headers into:
+ *   openpay.webhooks.normalizeDetailed(provider, rawBody, headers)
+ *
+ * Raw body preservation is critical: Paystack's HMAC-SHA512 signature is
+ * computed over the exact request bytes, so no JSON parsing happens first.
+ * (Flutterwave compares the `verif-hash` header instead, but the transport
+ * stays identical.)
+ */
+import 'dotenv/config';
+import { createServer } from 'node:http';
+import { pathToFileURL } from 'node:url';
+import { WebhookVerificationError } from './core/errors.js';
+import { OpenPay } from './sdk.js';
+const MAX_BODY_BYTES = 1_000_000; // 1 MB — Paystack events are a few KB
+function sendJson(res, status, body) {
+    const text = JSON.stringify(body);
+    res.writeHead(status, {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(text),
+    });
+    res.end(text);
+}
+async function readRawBody(req) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        size += buf.length;
+        if (size > MAX_BODY_BYTES)
+            throw new Error('body_too_large');
+        chunks.push(buf);
+    }
+    return Buffer.concat(chunks);
+}
+/** First value wins; Node lowercases header names. */
+function header(req, name) {
+    const v = req.headers[name];
+    return Array.isArray(v) ? v[0] : v;
+}
+/**
+ * Shared raw-body -> normalizeDetailed -> status mapping used by every
+ * provider route. Behavior is identical for all providers; only the
+ * provider name and signature header differ per route.
+ */
+async function handleProviderWebhook(openpay, provider, raw, headers, res) {
+    try {
+        const { event, duplicate } = await openpay.webhooks.normalizeDetailed(provider, raw, headers);
+        if (!event) {
+            sendJson(res, 400, { ok: false, error: 'malformed_payload' });
+            return;
+        }
+        if (duplicate) {
+            sendJson(res, 200, { ok: true, deduped: true, type: event.type, reference: event.reference });
+            return;
+        }
+        if (event.type === 'unknown') {
+            // Valid signature, unrecognized event: acknowledge so the provider doesn't retry forever.
+            sendJson(res, 200, { ok: true, ignored: true, reference: event.reference });
+            return;
+        }
+        sendJson(res, 200, { ok: true, type: event.type, reference: event.reference });
+    }
+    catch (err) {
+        if (err instanceof WebhookVerificationError) {
+            sendJson(res, 401, { ok: false, error: 'invalid_signature' });
+            return;
+        }
+        throw err; // -> 500 via outer catch
+    }
+}
+const PROVIDER_ROUTES = {
+    '/webhooks/paystack': 'paystack',
+    '/webhooks/flutterwave': 'flutterwave',
+};
+/** Signature headers per provider (values extracted from the raw request). */
+function signatureHeaders(provider, req) {
+    if (provider === 'flutterwave')
+        return { 'verif-hash': header(req, 'verif-hash') };
+    return { 'x-paystack-signature': header(req, 'x-paystack-signature') };
+}
+export function createWebhookServer(openpay) {
+    const server = createServer((req, res) => {
+        void handle(req, res).catch((err) => {
+            // Genuine processing failure (e.g. DB down) -> 500 so the provider retries.
+            console.error(`webhook error: ${err instanceof Error ? err.message : String(err)}`);
+            if (!res.headersSent)
+                sendJson(res, 500, { ok: false, error: 'processing_failed' });
+        });
+    });
+    async function handle(req, res) {
+        const url = new URL(req.url ?? '/', 'http://localhost');
+        console.log(`${req.method} ${url.pathname}`);
+        if (req.method === 'GET' && url.pathname === '/healthz') {
+            sendJson(res, 200, { ok: true });
+            return;
+        }
+        const provider = PROVIDER_ROUTES[url.pathname];
+        if (!provider) {
+            sendJson(res, 404, { ok: false, error: 'not_found' });
+            return;
+        }
+        if (req.method !== 'POST') {
+            sendJson(res, 405, { ok: false, error: 'method_not_allowed' });
+            return;
+        }
+        let raw;
+        try {
+            raw = await readRawBody(req);
+        }
+        catch {
+            sendJson(res, 413, { ok: false, error: 'body_too_large' });
+            return;
+        }
+        await handleProviderWebhook(openpay, provider, raw, signatureHeaders(provider, req), res);
+    }
+    return server;
+}
+// Runnable CLI: `npm run receiver`. Import-safe (tests import the factory only).
+const argv1 = process.argv[1];
+if (argv1 && import.meta.url === pathToFileURL(argv1).href) {
+    const port = Number(process.env.PORT ?? 3000);
+    const defaultProvider = process.env.OPENPAY_DEFAULT_PROVIDER ?? 'paystack';
+    // Keys + DATABASE_URL resolve from env inside OpenPay; missing keys throw ConfigurationError.
+    const openpay = new OpenPay({ defaultProvider });
+    if (!process.env.DATABASE_URL) {
+        console.warn('WARNING: DATABASE_URL not set — webhooks will verify/normalize but NOT persist.');
+    }
+    createWebhookServer(openpay).listen(port, () => {
+        console.log(`OpenPay webhook receiver listening on http://localhost:${port}`);
+        console.log('Paths: POST /webhooks/paystack, POST /webhooks/flutterwave');
+    });
+}

package/dist/webhooks/service.d.ts

@@ -0,0 +1,18 @@
+import type { OpenPayEvent, ProviderName, WebhookHeaders } from "../core/types.js";
+import type { Persistence } from "../db/store.js";
+import type { ProviderConnector } from "../connectors/types.js";
+export interface WebhookContext {
+    connectors: Record<ProviderName, ProviderConnector>;
+    persistence?: Persistence;
+}
+/** Verify signature, normalize to OpenPayEvent, persist. Throws WebhookVerificationError on bad signature. */
+export declare function handleWebhook(ctx: WebhookContext, provider: ProviderName, rawBody: string | Buffer, headers: WebhookHeaders): Promise<OpenPayEvent | null>;
+export interface WebhookResult {
+    event: OpenPayEvent | null;
+    /** True when this exact event was already recorded (retried delivery). */
+    duplicate: boolean;
+    /** True when a matching payment row's status was updated by this event. */
+    projected: boolean;
+}
+/** Same as handleWebhook, but also reports duplicate deliveries. */
+export declare function handleWebhookDetailed(ctx: WebhookContext, provider: ProviderName, rawBody: string | Buffer, headers: WebhookHeaders): Promise<WebhookResult>;

package/dist/webhooks/service.js

@@ -0,0 +1,60 @@
+import { ConfigurationError, WebhookVerificationError } from "../core/errors.js";
+function pick(ctx, provider) {
+    const c = ctx.connectors[provider];
+    if (!c)
+        throw new ConfigurationError(`Provider '${provider}' is not configured`);
+    return c;
+}
+/** Verify signature, normalize to OpenPayEvent, persist. Throws WebhookVerificationError on bad signature. */
+export async function handleWebhook(ctx, provider, rawBody, headers) {
+    const { event } = await handleWebhookDetailed(ctx, provider, rawBody, headers);
+    return event;
+}
+/**
+ * Project a normalized event onto its payment row (status-only, idempotent).
+ * Only terminal payment-lifecycle events project:
+ * - payment.succeeded -> successful
+ * - payment.failed    -> failed
+ * payment.pending is intentionally NOT projected: it carries no new information
+ * for genuinely pending payments, and must never regress a successful/failed
+ * row (e.g. Paystack refund.pending normalizes to payment.pending but describes
+ * the refund, not the payment). transfer/refund/unknown events never project.
+ */
+function projectedStatus(event) {
+    if (event.type === "payment.succeeded")
+        return "successful";
+    if (event.type === "payment.failed")
+        return "failed";
+    return null;
+}
+/** Same as handleWebhook, but also reports duplicate deliveries. */
+export async function handleWebhookDetailed(ctx, provider, rawBody, headers) {
+    const connector = pick(ctx, provider);
+    const text = typeof rawBody === "string" ? rawBody : rawBody.toString("utf8");
+    if (!connector.verifyWebhookSignature(rawBody, headers)) {
+        throw new WebhookVerificationError(provider);
+    }
+    let payload;
+    try {
+        payload = JSON.parse(text);
+    }
+    catch {
+        return { event: null, duplicate: false, projected: false };
+    }
+    const event = connector.normalizeWebhook(payload);
+    if (!event)
+        return { event: null, duplicate: false, projected: false };
+    if (ctx.persistence) {
+        const inserted = await ctx.persistence.saveWebhookEvent(event, payload);
+        if (!inserted)
+            return { event, duplicate: true, projected: false };
+        const status = projectedStatus(event);
+        if (status !== null && event.reference !== undefined) {
+            // Unknown references are safe: no row matches, nothing changes.
+            const updated = await ctx.persistence.updatePaymentStatus(event.provider, event.reference, status);
+            return { event, duplicate: false, projected: updated };
+        }
+        return { event, duplicate: false, projected: false };
+    }
+    return { event, duplicate: false, projected: false };
+}