@adonis-agora/payments 0.2.0 → 0.3.0

package/dist/src/billing/lucid_billing_store.js

@@ -1,16 +1,160 @@
 import { DateTime } from 'luxon';
-import { BillingPayment as DefaultPayment, BillingSubscription as DefaultSubscription, BillingUsageEvent as DefaultUsageEvent, BillingWebhookEvent as DefaultWebhookEvent, } from './mixins/index.js';
+import { OPEN_DISPUTE_STATUSES, } from './billing_store.js';
+import { clampLimit, clampOffset } from './list_query.js';
+import { BillingAuditEvent as DefaultAuditEvent, BillingCustomer as DefaultCustomer, BillingDispute as DefaultDispute, BillingPayment as DefaultPayment, BillingSubscription as DefaultSubscription, BillingUsageEvent as DefaultUsageEvent, BillingWebhookEvent as DefaultWebhookEvent, } from './mixins/index.js';
+import { createBillingTables, detectDialect, registerBillingSchemaCache, } from './schema.js';
+/** Lucid hands back Luxon `DateTime`s; the read SPI speaks plain `Date`. */
+function toDate(value) {
+    return value ? value.toJSDate() : null;
+}
+/**
+ * Read a single aggregate row.
+ *
+ * Every aggregate query below must go through `.pojo()`. A model query builder hydrates
+ * its rows into model INSTANCES, and a value with no matching column — `count(*) as total`
+ * — is not assigned to the instance; it is tucked into `$extras`. Reading `row.total` off
+ * the instance therefore yields `undefined`, which `?? 0` then turns into a confident,
+ * silent zero. `.pojo()` opts out of hydration and hands back the raw row.
+ *
+ * Counts also come back as strings on some drivers (Postgres `bigint`), hence the `Number`.
+ */
+function toCount(rows) {
+    const first = rows?.[0];
+    return Number(first?.total ?? 0);
+}
+/**
+ * The instant a deadline query looks up to: `now + withinHours`.
+ *
+ * There is no lower bound on purpose. A deadline that has already PASSED is still open and
+ * still unanswered, and excluding it would make the alert go quiet at exactly the moment it
+ * became true.
+ */
+function deadlineCutoff(query) {
+    const now = query.now ?? new Date();
+    return new Date(now.getTime() + query.withinHours * 3_600_000);
+}
+/** One dispute row, normalized for reading. `amount` stays integer minor units. */
+function disputeItem(row) {
+    return {
+        id: String(row.id),
+        gatewayId: row.gatewayId,
+        paymentGatewayId: row.paymentGatewayId,
+        provider: row.provider,
+        status: row.status,
+        reason: row.reason ?? null,
+        // `bigint` comes back as a STRING on Postgres, like every other amount in this store.
+        amount: row.amount === null || row.amount === undefined ? null : Number(row.amount),
+        currency: row.currency ?? null,
+        evidenceDueBy: toDate(row.evidenceDueBy),
+        outcome: row.outcome ?? null,
+        openedAt: toDate(row.openedAt),
+        closedAt: toDate(row.closedAt),
+        createdAt: toDate(row.createdAt),
+    };
+}
+/**
+ * The normalized event, as a jsonb-storable value.
+ *
+ * Drivers normalize onto object shapes (`PaymentWebhookData`, `SubscriptionWebhookData`), but
+ * `WebhookEvent.data` is `unknown` and a driver may hand back anything. Anything that is not
+ * an object is stored as `null` rather than coerced: the retry checks for `null` and says it
+ * cannot replay, which is a better answer than rebuilding an event around a string.
+ */
+function normalizedColumn(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value !== 'object' || Array.isArray(value))
+        return null;
+    return value;
+}
+/** One ledger row, normalized for reading. The stored payload is NEVER part of it. */
+function webhookEventItem(row) {
+    return {
+        id: String(row.id),
+        gatewayEventId: row.gatewayEventId,
+        provider: row.provider,
+        type: row.type,
+        status: row.status,
+        error: row.error ?? null,
+        createdAt: toDate(row.createdAt),
+        updatedAt: toDate(row.updatedAt),
+    };
+}
+/** One customer-mapping row, normalized for reading. Shared by both customer reads. */
+function customerItem(row) {
+    return {
+        id: String(row.id),
+        gatewayId: row.gatewayId,
+        provider: row.provider,
+        ownerType: row.ownerType ?? null,
+        ownerId: row.ownerId ?? null,
+        email: row.email ?? null,
+        name: row.name ?? null,
+        taxId: row.taxId ?? null,
+        createdAt: toDate(row.createdAt),
+    };
+}
+/** One audit row, normalized for reading. `amount` is BIGINT — a STRING on Postgres. */
+function auditItem(row) {
+    return {
+        id: String(row.id),
+        action: row.action,
+        actor: row.actor ?? null,
+        provider: row.provider ?? null,
+        subjectType: row.subjectType ?? null,
+        subjectId: row.subjectId ?? null,
+        amount: row.amount === null || row.amount === undefined ? null : Number(row.amount),
+        currency: row.currency ?? null,
+        message: row.message ?? null,
+        metadata: row.metadata ?? null,
+        createdAt: toDate(row.createdAt),
+    };
+}
 /**
  * Lucid implementation of {@link BillingStore}. Resolves the models passed in (defaulting
  * to the bundled ones) and writes through them, so custom models/composed mixins keep
  * working with the same store.
  */
 export class LucidBillingStore {
+    /**
+     * Per-column answers to "does this install's table actually have it?", cached per store.
+     *
+     * `external_reference` and `normalized` arrive in a SECOND migration
+     * (an earlier schema), because the first one is already in production
+     * everywhere this package is installed. An app that upgrades the package before running it
+     * must keep taking webhooks — a payment that records no reference, and a ledger row the
+     * dashboard cannot replay, are both survivable; a `column ... does not exist` on every
+     * gateway delivery is not. So the write asks once, per column, and skips what is not there.
+     *
+     * Keyed by `table.column`. One `information_schema` read per column per process, then
+     * nothing. A probe that itself fails answers "present": dropping data quietly is the worse
+     * of the two failures, and the real INSERT will then say exactly what is wrong.
+     */
+    #columnCache = new Map();
+    /**
+     * Whether to create the billing tables on first use. On by default — the ecosystem
+     * convention is that a lib owns its own schema, the same way `@adonis-agora/durable` and
+     * `@adonis-agora/authz` do. An app that wants explicit control sets
+     * `billing.autoCreateSchema: false` and calls {@link createBillingTables} from a migration
+     * instead; both paths run the SAME DDL, so they cannot drift.
+     */
+    #autoCreateSchema;
+    /**
+     * The one-shot schema promise. Cached so the DDL runs once per store, not once per query,
+     * and so concurrent first calls await the same round trip rather than racing six
+     * `CREATE TABLE IF NOT EXISTS` statements against each other.
+     */
+    #schemaReady;
+    #customerModel;
     #subscriptionModel;
     #paymentModel;
     #webhookEventModel;
     #usageEventModel;
-    constructor(models = {}) {
+    #disputeModel;
+    #auditEventModel;
+    constructor(models = {}, options = {}) {
+        this.#autoCreateSchema = options.autoCreateSchema !== false;
+        this.#customerModel = (models.customerModel ?? DefaultCustomer);
         this.#subscriptionModel = (models.subscriptionModel ??
             DefaultSubscription);
         this.#paymentModel = (models.paymentModel ?? DefaultPayment);
@@ -18,8 +162,186 @@ export class LucidBillingStore {
             DefaultWebhookEvent);
         this.#usageEventModel = (models.usageEventModel ??
             DefaultUsageEvent);
+        this.#disputeModel = (models.disputeModel ?? DefaultDispute);
+        this.#auditEventModel = (models.auditEventModel ??
+            DefaultAuditEvent);
+        // So `dropBillingTables()` can invalidate the memo below. Without it a suite that drops
+        // the tables between groups leaves this store certain they still exist, and every
+        // following query fails on a table nothing will re-create.
+        registerBillingSchemaCache(() => {
+            this.#schemaReady = undefined;
+            this.#columnCache.clear();
+        });
+    }
+    /**
+     * Create the billing tables if they are not there. Idempotent, and safe to call from an
+     * app that already ran the published migration — every statement is `IF NOT EXISTS`.
+     *
+     * Public because an app that turns `autoCreateSchema` off may still want it in a seeder or
+     * a test bootstrap without reaching for the standalone function.
+     */
+    /**
+     * Turn the automatic schema creation off after construction.
+     *
+     * One direction only, and deliberately: the flag exists to keep a library from running
+     * DDL against a database somebody else owns, so honouring `false` wherever it appears is
+     * the safe move and there is no way to switch it back on from here.
+     *
+     * It exists because the flag can arrive after the store does. An app that builds its own
+     * store — `billing.store: () => lucidBillingStore({ paymentModel: MyPayment })` — has
+     * already constructed it by the time the provider reads the config, and skipping the flag
+     * there would create tables in exactly the shared database it was set to protect.
+     */
+    disableAutoCreateSchema() {
+        this.#autoCreateSchema = false;
+    }
+    async ensureSchema() {
+        // NOT gated by `#ready()`: that is what calls this, and awaiting it here would have the
+        // promise await itself. A deadlock, not a crash — every query would hang forever.
+        await createBillingTables(this.#paymentModel.query().client);
+    }
+    /**
+     * Awaited at the top of every public method.
+     *
+     * Every one, not just the writes: a read against a table that does not exist is the same
+     * error, and it is the first thing an app hits — a dashboard opened before the first
+     * charge. `test/lucid_store_schema.spec.ts` enumerates this class's public methods and
+     * fails when one of them skips this, because "I added a method and forgot" is exactly how
+     * a lazily-created schema becomes a schema that exists most of the time.
+     */
+    async #ready() {
+        if (!this.#autoCreateSchema)
+            return;
+        if (!this.#schemaReady)
+            this.#schemaReady = this.ensureSchema();
+        return this.#schemaReady;
+    }
+    async #hasColumn(model, column) {
+        const key = `${model.table}.${column}`;
+        let answer = this.#columnCache.get(key);
+        if (answer === undefined) {
+            answer = model
+                .query()
+                .client.columnsInfo(model.table)
+                .then((columns) => Object.hasOwn(columns, column))
+                .catch(() => true);
+            this.#columnCache.set(key, answer);
+        }
+        return answer;
+    }
+    /**
+     * Does this install have the `billing_disputes` table at all?
+     *
+     * Same question as {@link LucidBillingStore.hasColumn}, one level up, and for the same
+     * reason: `billing_disputes` arrives in a THIRD migration (an earlier schema), so an
+     * app that upgrades the package before running it has a processor that wants to write
+     * disputes and no table to write them to. The dispute row is ADDITIONAL — the payment row
+     * still moves, the diagnostics still publish — so a missing table skips the write and
+     * every dispute read answers empty, rather than failing every gateway delivery with
+     * `relation "billing_disputes" does not exist` until someone notices.
+     *
+     * Reuses the column cache and the column probe: `columnsInfo` on a table that does not
+     * exist yields no columns at all. A probe that itself fails answers "present", so the real
+     * query then says exactly what is wrong.
+     */
+    async #hasDisputesTable() {
+        return this.#hasTable(this.#disputeModel);
+    }
+    /**
+     * Does this install have `billing_audit_events`?
+     *
+     * Same question, same tolerance: the table arrives after the package shipped, and every write
+     * to it is ADDITIONAL to an action that already happened. Refusing a refund the gateway
+     * already accepted because the audit note could not be filed would be strictly worse than
+     * filing no note.
+     */
+    async #hasAuditTable() {
+        return this.#hasTable(this.#auditEventModel);
+    }
+    /**
+     * "Does this table exist?", cached beside the column answers and resolved the same way:
+     * `columnsInfo` on a missing table yields no columns at all. A probe that itself fails
+     * answers "present", so the real query then says exactly what is wrong.
+     */
+    async #hasTable(model) {
+        const key = `${model.table}.*`;
+        let answer = this.#columnCache.get(key);
+        if (answer === undefined) {
+            answer = model
+                .query()
+                .client.columnsInfo(model.table)
+                .then((columns) => Object.keys(columns).length > 0)
+                .catch(() => true);
+            this.#columnCache.set(key, answer);
+        }
+        return answer;
+    }
+    async saveCustomer(customer) {
+        await this.#ready();
+        const existing = await this.findCustomerByGatewayId(customer.gatewayId);
+        const row = (existing ?? new this.#customerModel());
+        row.gatewayId = customer.gatewayId;
+        row.provider = customer.provider;
+        // Absent fields do NOT erase what is already recorded: a later call that only knows the
+        // gateway id — a reconcile, a webhook — would otherwise blank the owner mapping that an
+        // earlier, better-informed call wrote, which is the whole reason the row exists.
+        if (customer.ownerType !== undefined)
+            row.ownerType = customer.ownerType;
+        if (customer.ownerId !== undefined)
+            row.ownerId = customer.ownerId;
+        if (customer.email !== undefined)
+            row.email = customer.email;
+        if (customer.name !== undefined)
+            row.name = customer.name;
+        if (customer.taxId !== undefined)
+            row.taxId = customer.taxId;
+        if (customer.metadata !== undefined)
+            row.metadata = customer.metadata;
+        await row.save();
+        return row;
+    }
+    async findCustomerByGatewayId(gatewayId) {
+        await this.#ready();
+        return (await this.#customerModel.findBy('gateway_id', gatewayId));
+    }
+    async findCustomerByOwner(ownerType, ownerId, provider) {
+        await this.#ready();
+        return (await this.#customerModel
+            .query()
+            .where('owner_type', ownerType)
+            .where('owner_id', ownerId)
+            .where('provider', provider)
+            .first());
+    }
+    async listCustomers(query) {
+        await this.#ready();
+        const builder = this.#customerModel.query().orderBy('created_at', 'desc');
+        if (query.provider !== undefined)
+            builder.where('provider', query.provider);
+        if (query.ownerType !== undefined)
+            builder.where('owner_type', query.ownerType);
+        if (query.ownerId !== undefined)
+            builder.where('owner_id', query.ownerId);
+        if (query.gatewayId !== undefined)
+            builder.where('gateway_id', query.gatewayId);
+        const rows = (await builder
+            .limit(clampLimit(query.limit))
+            .offset(clampOffset(query.offset)));
+        return rows.map(customerItem);
+    }
+    async listCustomersByGatewayIds(gatewayIds) {
+        await this.#ready();
+        // No ids means no query. `whereIn('gateway_id', [])` is a guaranteed-empty scan on some
+        // dialects and a syntax error on others; either way it is a round trip for a known answer.
+        if (gatewayIds.length === 0)
+            return [];
+        const rows = (await this.#customerModel
+            .query()
+            .whereIn('gateway_id', [...new Set(gatewayIds)]));
+        return rows.map(customerItem);
     }
     async saveSubscription(sub) {
+        await this.#ready();
         const existing = await this.findSubscriptionByGatewayId(sub.gatewayId);
         const row = (existing ?? new this.#subscriptionModel());
         row.gatewayId = sub.gatewayId;
@@ -33,11 +355,46 @@ export class LucidBillingStore {
         await row.save();
         return row;
     }
+    async listSubscriptions(query) {
+        await this.#ready();
+        const builder = this.#subscriptionModel.query().orderBy('created_at', 'desc');
+        if (query.status !== undefined)
+            builder.where('status', query.status);
+        if (query.provider !== undefined)
+            builder.where('provider', query.provider);
+        const rows = (await builder
+            .limit(clampLimit(query.limit))
+            .offset(clampOffset(query.offset)));
+        return rows.map((row) => ({
+            id: String(row.id),
+            gatewayId: row.gatewayId,
+            provider: row.provider,
+            status: row.status,
+            planId: row.planId,
+            customerId: row.customerId ?? null,
+            trialEndsAt: toDate(row.trialEndsAt),
+            endsAt: toDate(row.endsAt),
+            createdAt: toDate(row.createdAt),
+        }));
+    }
+    async countSubscriptions(query) {
+        await this.#ready();
+        const builder = this.#subscriptionModel.query().count('* as total').pojo();
+        if (query.status !== undefined)
+            builder.where('status', query.status);
+        if (query.createdBefore !== undefined)
+            builder.where('created_at', '<', query.createdBefore);
+        if (query.createdAfter !== undefined)
+            builder.where('created_at', '>=', query.createdAfter);
+        return toCount(await builder);
+    }
     async findSubscriptionByGatewayId(gatewayId) {
+        await this.#ready();
         const row = await this.#subscriptionModel.findBy('gateway_id', gatewayId);
         return row;
     }
     async savePayment(payment) {
+        await this.#ready();
         const existing = await this.findPaymentByGatewayId(payment.gatewayId);
         const row = (existing ?? new this.#paymentModel());
         row.gatewayId = payment.gatewayId;
@@ -47,30 +404,358 @@ export class LucidBillingStore {
         row.currency = payment.currency;
         row.customerId = payment.customerId ?? null;
         row.subscriptionId = payment.subscriptionId ?? null;
-        row.paidAt = payment.paidAt ? DateTime.fromJSDate(payment.paidAt) : null;
+        // An ABSENT reference does not erase the stored one — same rule as `saveCustomer`'s owner
+        // mapping, and for a sharper reason: `payment.succeeded` carries the app's reference,
+        // `payment.refunded` and `payment.disputed` frequently do not, and blanking it there would
+        // destroy the only key `findPaymentByExternalReference` can route on. `null` still clears.
+        if (payment.externalReference !== undefined &&
+            (await this.#hasColumn(this.#paymentModel, 'external_reference'))) {
+            row.externalReference = payment.externalReference;
+        }
+        // An ABSENT `paidAt` does not erase the stored one — the same leave-alone rule as the
+        // reference above, and with a sharper consequence. `payment.refunded`,
+        // `payment.disputed` and `payment.dispute_closed` all call this WITHOUT a `paidAt`
+        // (a refund/dispute payload carries no settlement date), and `revenue()` filters on
+        // `status = 'paid' AND paid_at >= from AND paid_at < to`. Writing `null` through meant a
+        // dispute closed as WON restored `status = 'paid'` with `paid_at = NULL`, so the recovered
+        // money vanished from every windowed revenue figure — permanently, because `paid_at` is
+        // the only record of when the charge landed. `null` still clears it, explicitly.
+        if (payment.paidAt !== undefined) {
+            row.paidAt = payment.paidAt === null ? null : DateTime.fromJSDate(payment.paidAt);
+        }
+        // Same leave-alone rule, same reason: only a partial-refund event knows this figure, and
+        // every other write about the payment would otherwise reset it to zero.
+        if (payment.refundedAmount !== undefined &&
+            (await this.#hasColumn(this.#paymentModel, 'refunded_amount'))) {
+            row.refundedAmount = payment.refundedAmount;
+        }
         row.payload = payment.payload ?? {};
         await row.save();
         return row;
     }
     async findPaymentByGatewayId(gatewayId) {
+        await this.#ready();
         const row = await this.#paymentModel.findBy('gateway_id', gatewayId);
         return row;
     }
+    async findPaymentByExternalReference(reference) {
+        await this.#ready();
+        // An install that has not run an earlier schema has no column to match on,
+        // and every row it holds would answer `null` anyway — so say `null` instead of raising
+        // `column "external_reference" does not exist` at a browser that is merely polling.
+        if (!(await this.#hasColumn(this.#paymentModel, 'external_reference')))
+            return null;
+        // Newest first: nothing stops an app reusing a reference across retries, and the row an
+        // operator (or a polling checkout page) means is the most recent one.
+        const row = await this.#paymentModel
+            .query()
+            .where('external_reference', reference)
+            .orderBy('created_at', 'desc')
+            .first();
+        return row;
+    }
+    async listPayments(query) {
+        await this.#ready();
+        const builder = this.#paymentModel.query().orderBy('created_at', 'desc');
+        if (query.status !== undefined)
+            builder.where('status', query.status);
+        if (query.provider !== undefined)
+            builder.where('provider', query.provider);
+        if (query.gatewayId !== undefined)
+            builder.where('gateway_id', query.gatewayId);
+        if (query.customerId !== undefined)
+            builder.where('customer_id', query.customerId);
+        // Guarded like `findPaymentByExternalReference`: an install that has not run the ALTER has
+        // no column to match on, and every row it holds would answer nothing anyway. Returning an
+        // empty page beats raising `column "external_reference" does not exist` at a filter box.
+        if (query.externalReference !== undefined) {
+            if (!(await this.#hasColumn(this.#paymentModel, 'external_reference')))
+                return [];
+            builder.where('external_reference', query.externalReference);
+        }
+        const rows = (await builder
+            .limit(clampLimit(query.limit))
+            .offset(clampOffset(query.offset)));
+        return rows.map((row) => ({
+            id: String(row.id),
+            gatewayId: row.gatewayId,
+            provider: row.provider,
+            status: row.status,
+            amount: Number(row.amount),
+            currency: row.currency,
+            customerId: row.customerId ?? null,
+            subscriptionId: row.subscriptionId ?? null,
+            externalReference: row.externalReference ?? null,
+            // `bigint` arrives as a STRING on Postgres, and `undefined` on an install whose table
+            // predates the column — both normalize to the same honest answer.
+            refundedAmount: row.refundedAmount === null || row.refundedAmount === undefined
+                ? null
+                : Number(row.refundedAmount),
+            paidAt: toDate(row.paidAt),
+            createdAt: toDate(row.createdAt),
+        }));
+    }
+    async countPayments(query) {
+        await this.#ready();
+        const builder = this.#paymentModel.query().count('* as total').pojo();
+        if (query.status !== undefined)
+            builder.where('status', query.status);
+        if (query.createdBefore !== undefined)
+            builder.where('created_at', '<', query.createdBefore);
+        if (query.createdAfter !== undefined)
+            builder.where('created_at', '>=', query.createdAfter);
+        return toCount(await builder);
+    }
+    async saveDispute(dispute) {
+        await this.#ready();
+        if (!(await this.#hasDisputesTable()))
+            return null;
+        const existing = await this.findDisputeByGatewayId(dispute.gatewayId);
+        const row = (existing ?? new this.#disputeModel());
+        row.gatewayId = dispute.gatewayId;
+        row.paymentGatewayId = dispute.paymentGatewayId;
+        row.provider = dispute.provider;
+        row.status = dispute.status;
+        // A new row starts with every optional column explicitly `null` rather than absent, so a
+        // reader never has to tell "the gateway sent nothing" apart from "the column was omitted".
+        if (existing === null) {
+            row.reason = null;
+            row.amount = null;
+            row.currency = null;
+            row.evidenceDueBy = null;
+            row.outcome = null;
+            row.closedAt = null;
+            row.payload = {};
+        }
+        // Absent does NOT erase: the event that OPENS a dispute carries the deadline and the
+        // reason, and the one that CLOSES it carries neither. Blanking them on the close would
+        // destroy the only record of the window that was answered. `null` still clears.
+        if (dispute.reason !== undefined)
+            row.reason = dispute.reason;
+        if (dispute.amount !== undefined)
+            row.amount = dispute.amount;
+        if (dispute.currency !== undefined)
+            row.currency = dispute.currency;
+        if (dispute.evidenceDueBy !== undefined) {
+            row.evidenceDueBy = dispute.evidenceDueBy ? DateTime.fromJSDate(dispute.evidenceDueBy) : null;
+        }
+        if (dispute.outcome !== undefined)
+            row.outcome = dispute.outcome;
+        if (dispute.closedAt !== undefined) {
+            row.closedAt = dispute.closedAt ? DateTime.fromJSDate(dispute.closedAt) : null;
+        }
+        // `openedAt` is when the dispute FIRST reached us and is never moved afterwards: a later
+        // event re-stamping it would make every dispute look brand new and destroy the only
+        // measure of how long one has been open.
+        if (existing === null || existing.openedAt === null) {
+            row.openedAt = dispute.openedAt ? DateTime.fromJSDate(dispute.openedAt) : DateTime.now();
+        }
+        if (dispute.payload !== undefined)
+            row.payload = dispute.payload;
+        await row.save();
+        return row;
+    }
+    async findDisputeByGatewayId(gatewayId) {
+        await this.#ready();
+        if (!(await this.#hasDisputesTable()))
+            return null;
+        return (await this.#disputeModel.findBy('gateway_id', gatewayId));
+    }
+    async findOpenDisputeByPayment(paymentGatewayId) {
+        await this.#ready();
+        if (!(await this.#hasDisputesTable()))
+            return null;
+        const row = await this.#disputeModel
+            .query()
+            .where('payment_gateway_id', paymentGatewayId)
+            .whereIn('status', [...OPEN_DISPUTE_STATUSES])
+            .orderBy('created_at', 'desc')
+            .first();
+        return row;
+    }
+    async listDisputes(query) {
+        await this.#ready();
+        if (!(await this.#hasDisputesTable()))
+            return [];
+        const builder = this.#disputeModel.query().orderBy('created_at', 'desc');
+        if (query.status !== undefined)
+            builder.where('status', query.status);
+        if (query.provider !== undefined)
+            builder.where('provider', query.provider);
+        const rows = (await builder
+            .limit(clampLimit(query.limit))
+            .offset(clampOffset(query.offset)));
+        return rows.map(disputeItem);
+    }
+    async countDisputes(query) {
+        await this.#ready();
+        if (!(await this.#hasDisputesTable()))
+            return 0;
+        const builder = this.#disputeModel.query().count('* as total').pojo();
+        if (query.status !== undefined)
+            builder.where('status', query.status);
+        if (query.createdBefore !== undefined)
+            builder.where('created_at', '<', query.createdBefore);
+        if (query.createdAfter !== undefined)
+            builder.where('created_at', '>=', query.createdAfter);
+        return toCount(await builder);
+    }
+    async listDisputesDueWithin(query) {
+        await this.#ready();
+        if (!(await this.#hasDisputesTable()))
+            return [];
+        const builder = this.#disputeModel
+            .query()
+            .whereIn('status', [...OPEN_DISPUTE_STATUSES])
+            // Explicit, though `<=` would already exclude NULLs: a gateway that sent no deadline
+            // gives nothing to be late for, and the reader should not have to know SQL's NULL rules
+            // to be sure of that.
+            .whereNotNull('evidence_due_by')
+            .where('evidence_due_by', '<=', deadlineCutoff(query))
+            // Soonest first — the priority order, not the arrival order. The only list in this store
+            // that is not newest-first.
+            .orderBy('evidence_due_by', 'asc');
+        if (query.provider !== undefined)
+            builder.where('provider', query.provider);
+        const rows = (await builder
+            .limit(clampLimit(query.limit))
+            .offset(clampOffset(query.offset)));
+        return rows.map(disputeItem);
+    }
+    async countDisputesDueWithin(query) {
+        await this.#ready();
+        if (!(await this.#hasDisputesTable()))
+            return 0;
+        const builder = this.#disputeModel
+            .query()
+            .whereIn('status', [...OPEN_DISPUTE_STATUSES])
+            .whereNotNull('evidence_due_by')
+            .where('evidence_due_by', '<=', deadlineCutoff(query))
+            .count('* as total')
+            .pojo();
+        if (query.provider !== undefined)
+            builder.where('provider', query.provider);
+        return toCount(await builder);
+    }
+    async listOpenDisputes(query) {
+        await this.#ready();
+        if (!(await this.#hasDisputesTable()))
+            return [];
+        // Oldest FIRST, and it is the opposite of every other list here. With no deadline to sort
+        // on, "nobody has answered this for eleven days" is the only priority signal there is.
+        const builder = this.#disputeModel
+            .query()
+            .whereIn('status', [...OPEN_DISPUTE_STATUSES])
+            .orderBy('created_at', 'asc');
+        if (query.provider !== undefined)
+            builder.where('provider', query.provider);
+        const rows = (await builder
+            .limit(clampLimit(query.limit))
+            .offset(clampOffset(query.offset)));
+        return rows.map(disputeItem);
+    }
+    async countOpenDisputes(query) {
+        await this.#ready();
+        if (!(await this.#hasDisputesTable()))
+            return 0;
+        const builder = this.#disputeModel
+            .query()
+            .whereIn('status', [...OPEN_DISPUTE_STATUSES])
+            .count('* as total')
+            .pojo();
+        if (query.provider !== undefined)
+            builder.where('provider', query.provider);
+        return toCount(await builder);
+    }
+    async recordAuditEvent(event) {
+        await this.#ready();
+        if (!(await this.#hasAuditTable()))
+            return null;
+        const row = new this.#auditEventModel();
+        row.action = event.action;
+        row.actor = event.actor ?? null;
+        row.provider = event.provider ?? null;
+        row.subjectType = event.subjectType ?? null;
+        row.subjectId = event.subjectId ?? null;
+        row.amount = event.amount ?? null;
+        row.currency = event.currency ?? null;
+        row.message = event.message ?? null;
+        row.metadata = event.metadata ?? null;
+        if (event.createdAt !== undefined)
+            row.createdAt = DateTime.fromJSDate(event.createdAt);
+        await row.save();
+        return auditItem(row);
+    }
+    async listAuditEvents(query) {
+        await this.#ready();
+        if (!(await this.#hasAuditTable()))
+            return [];
+        const builder = this.#auditEventModel.query().orderBy('created_at', 'desc');
+        this.#applyAuditFilters(builder, query);
+        const rows = (await builder
+            .limit(clampLimit(query.limit))
+            .offset(clampOffset(query.offset)));
+        return rows.map(auditItem);
+    }
+    async countAuditEvents(query) {
+        await this.#ready();
+        if (!(await this.#hasAuditTable()))
+            return 0;
+        const builder = this.#auditEventModel.query().count('* as total').pojo();
+        this.#applyAuditFilters(builder, query);
+        return toCount(await builder);
+    }
+    /** The audit filter, applied identically by the list and the count — see `#matchesCount`'s
+     *  note in the in-memory store: a bound one of them ignored would report a healthy zero. */
+    #applyAuditFilters(builder, query) {
+        if (query.action !== undefined)
+            builder.where('action', query.action);
+        if (query.actions !== undefined)
+            builder.whereIn('action', [...query.actions]);
+        if (query.actor !== undefined)
+            builder.where('actor', query.actor);
+        if (query.provider !== undefined)
+            builder.where('provider', query.provider);
+        if (query.subjectType !== undefined)
+            builder.where('subject_type', query.subjectType);
+        if (query.subjectId !== undefined)
+            builder.where('subject_id', query.subjectId);
+        if (query.createdBefore !== undefined)
+            builder.where('created_at', '<', query.createdBefore);
+        if (query.createdAfter !== undefined)
+            builder.where('created_at', '>=', query.createdAfter);
+    }
     async recordWebhookEvent(event) {
+        await this.#ready();
         const existing = await this.#webhookEventModel.findBy('gateway_event_id', event.gatewayEventId);
-        if (existing)
-            return null;
+        if (existing) {
+            // A previous attempt failed: claim it again so the retry re-runs. Anything
+            // else (in flight, or already processed) is a redelivery — stop here.
+            if (existing.status !== 'failed')
+                return null;
+            existing.status = 'received';
+            existing.error = null;
+            // `payload` and `normalized` are deliberately NOT touched here: the retry re-claims
+            // this row precisely to read back what the original delivery recorded.
+            await existing.save();
+            return existing;
+        }
         const row = new this.#webhookEventModel();
         row.gatewayEventId = event.gatewayEventId;
         row.provider = event.provider;
         row.type = event.type;
         row.status = 'received';
         row.payload = event.payload;
+        const normalized = normalizedColumn(event.normalized);
+        if (normalized !== null && (await this.#hasColumn(this.#webhookEventModel, 'normalized'))) {
+            row.normalized = normalized;
+        }
         row.error = null;
         await row.save();
         return row;
     }
     async markWebhookProcessed(id) {
+        await this.#ready();
         const row = await this.#webhookEventModel.find(id);
         if (row) {
             row.status = 'processed';
@@ -78,6 +763,7 @@ export class LucidBillingStore {
         }
     }
     async markWebhookFailed(id, error) {
+        await this.#ready();
         const row = await this.#webhookEventModel.find(id);
         if (row) {
             row.status = 'failed';
@@ -85,7 +771,81 @@ export class LucidBillingStore {
             await row.save();
         }
     }
+    async listWebhookEvents(query) {
+        await this.#ready();
+        const builder = this.#webhookEventModel.query().orderBy('created_at', 'desc');
+        if (query.status !== undefined)
+            builder.where('status', query.status);
+        if (query.provider !== undefined)
+            builder.where('provider', query.provider);
+        if (query.type !== undefined)
+            builder.where('type', query.type);
+        const rows = (await builder
+            .limit(clampLimit(query.limit))
+            .offset(clampOffset(query.offset)));
+        return rows.map(webhookEventItem);
+    }
+    async listWebhookEventsForPayment(paymentGatewayId, query = {}) {
+        await this.#ready();
+        // An empty needle would match the whole table — the timeline of "no payment at all".
+        if (paymentGatewayId === '')
+            return [];
+        // The payload column's type differs per dialect (JSONB / JSON / TEXT) and only one of the
+        // three can be compared to a string directly, so it is cast. MySQL spells the text type
+        // `CHAR`; Postgres and SQLite take `TEXT`.
+        const dialect = detectDialect(this.#webhookEventModel.query().client);
+        const textType = /mysql|mariadb/i.test(dialect ?? '') ? 'CHAR' : 'TEXT';
+        const rows = (await this.#webhookEventModel
+            .query()
+            .whereRaw(`CAST(payload AS ${textType}) LIKE ?`, [`%${paymentGatewayId}%`])
+            .orderBy('created_at', 'desc')
+            .limit(clampLimit(query.limit)));
+        return rows.map(webhookEventItem);
+    }
+    async findWebhookEventByGatewayEventId(gatewayEventId) {
+        await this.#ready();
+        const row = (await this.#webhookEventModel.findBy('gateway_event_id', gatewayEventId));
+        if (!row)
+            return null;
+        return webhookEventItem(row);
+    }
+    async countWebhookEvents(query) {
+        await this.#ready();
+        const builder = this.#webhookEventModel.query().count('* as total').pojo();
+        if (query.status !== undefined)
+            builder.where('status', query.status);
+        if (query.createdBefore !== undefined)
+            builder.where('created_at', '<', query.createdBefore);
+        if (query.createdAfter !== undefined)
+            builder.where('created_at', '>=', query.createdAfter);
+        return toCount(await builder);
+    }
+    async webhookEventBreakdown(query) {
+        await this.#ready();
+        const builder = this.#webhookEventModel
+            .query()
+            .select('provider', 'type')
+            .count('* as total')
+            .groupBy('provider', 'type')
+            .orderBy('total', 'desc')
+            .pojo();
+        if (query.status !== undefined)
+            builder.where('status', query.status);
+        if (query.createdBefore !== undefined)
+            builder.where('created_at', '<', query.createdBefore);
+        if (query.createdAfter !== undefined)
+            builder.where('created_at', '>=', query.createdAfter);
+        // Through `unknown`: the query builder is typed as yielding model instances, but a
+        // grouped `select(...).count(...)` yields aggregate rows, which do not overlap with it.
+        const rows = (await builder);
+        return rows.map((row) => ({
+            provider: row.provider,
+            type: row.type,
+            count: Number(row.total),
+        }));
+    }
     async recordUsage(event) {
+        await this.#ready();
         const row = new this.#usageEventModel();
         row.subscriptionId = event.subscriptionId ?? null;
         row.customerId = event.customerId ?? null;
@@ -97,11 +857,13 @@ export class LucidBillingStore {
         return row;
     }
     async usageReport(query) {
+        await this.#ready();
         const builder = this.#usageEventModel
             .query()
             .select('meter')
             .sum('quantity as quantity')
-            .groupBy('meter');
+            .groupBy('meter')
+            .pojo();
         if (query.subscriptionId !== undefined)
             builder.where('subscription_id', query.subscriptionId);
         else if (query.customerId !== undefined)
@@ -119,21 +881,57 @@ export class LucidBillingStore {
         }));
     }
     async revenue(query) {
-        const builder = this.#paymentModel.query().where('status', 'paid').sum('amount as total');
+        await this.#ready();
+        const builder = this.#paymentModel
+            .query()
+            .where('status', 'paid')
+            .sum('amount as total')
+            .pojo();
         if (query.from !== undefined)
             builder.where('paid_at', '>=', query.from);
         if (query.to !== undefined)
             builder.where('paid_at', '<', query.to);
-        const rows = await builder;
-        const total = rows[0]?.total;
-        return Number(total ?? 0);
+        return toCount(await builder);
+    }
+    /**
+     * Gross minus what came back. Same rows, same window, one subtraction.
+     *
+     * Three details this has to get right, each of which has already bitten this package:
+     *
+     * 1. `COALESCE(refunded_amount, 0)`. `refunded_amount` is `NULL` on every row written before
+     *    the column existed, and SQL `amount - NULL` is `NULL`, which propagates through `SUM`
+     *    and turns the whole window into `NULL` — one legacy row would report zero net revenue
+     *    for an install that took a million. `NULL` means "nothing came back".
+     * 2. `SUM` over no rows is `NULL`, not `0`; `toCount` normalizes it, exactly as `revenue()`
+     *    already relies on.
+     * 3. Postgres returns a `BIGINT` sum as a STRING. `toCount` runs it through `Number` for the
+     *    same reason `amount` is read through `Number` everywhere else in this file — without it
+     *    the metric would cross the API as `"9000"` and the SPA would render `"9000" / 100`.
+     *
+     * An install whose table predates the column has no refund recorded anywhere, so net IS
+     * gross — and asking for a column Postgres does not have would raise `column
+     * "refunded_amount" does not exist` at a dashboard that is merely loading its overview.
+     */
+    async netRevenue(query) {
+        await this.#ready();
+        if (!(await this.#hasColumn(this.#paymentModel, 'refunded_amount'))) {
+            return this.revenue(query);
+        }
+        const builder = this.#paymentModel.query().where('status', 'paid').pojo();
+        builder.select(builder.client.raw('SUM(amount - COALESCE(refunded_amount, 0)) as total'));
+        if (query.from !== undefined)
+            builder.where('paid_at', '>=', query.from);
+        if (query.to !== undefined)
+            builder.where('paid_at', '<', query.to);
+        return toCount(await builder);
     }
     async countActiveSubscriptions() {
-        const count = await this.#subscriptionModel
+        await this.#ready();
+        return toCount(await this.#subscriptionModel
             .query()
             .whereIn('status', ['active', 'trialing'])
-            .count('* as total');
-        return Number(count[0]?.total ?? 0);
+            .count('* as total')
+            .pojo());
     }
 }
 /** Builder matching the authkit `lucidStores(...)` convention. */