@adonis-agora/payments 0.2.0

package/dist/providers/payments_provider.js

@@ -0,0 +1,155 @@
+import { pathToFileURL } from 'node:url';
+import { LucidBillingStore } from '../src/billing/lucid_billing_store.js';
+import { WebhookDispatcher } from '../src/billing/webhook_dispatcher.js';
+import { WebhookProcessor } from '../src/billing/webhook_processor.js';
+import { InvoiceManager, resolveInvoiceProviders } from '../src/invoice/invoice_manager.js';
+import { PaymentsManager, resolveDrivers } from '../src/payments_manager.js';
+import { setPayments } from '../src/services/main.js';
+import { discoverWebhookHandlers, loadWebhookHandlersFromBarrel, resolveWebhookHandler, } from '../src/webhook_handlers.js';
+/**
+ * Wires `@adonis-agora/payments` into the AdonisJS application: binds a singleton
+ * {@link PaymentsManager} built from `config/payments.ts`, wires the optional Lucid
+ * billing layer (store + webhook processor + dispatcher), and mounts the webhook route
+ * under `/payments/webhook/:provider`.
+ */
+export default class PaymentsProvider {
+    app;
+    #webhook;
+    constructor(app) {
+        this.app = app;
+    }
+    register() {
+        const config = this.app.config.get('payments', {});
+        this.app.container.singleton(PaymentsManager, async () => {
+            // Build invoice providers first so drivers can resolve them from their ctx (a
+            // charge with `invoice: true|'name'` emits through the invoice provider).
+            let invoices;
+            if (config.invoice) {
+                const providers = await resolveInvoiceProviders(config.invoice);
+                invoices = new InvoiceManager(providers);
+            }
+            const drivers = await resolveDrivers(config, invoices);
+            const manager = new PaymentsManager({
+                drivers,
+                ...(invoices !== undefined ? { invoices } : {}),
+                ...(config.methods !== undefined ? { methods: config.methods } : {}),
+                ...(config.default !== undefined ? { defaultName: config.default } : {}),
+            });
+            // Hand the manager to the lazy `services/main` singleton so `getPayments()` works.
+            setPayments(manager);
+            return manager;
+        });
+    }
+    async boot() {
+        await this.app.booted(async () => {
+            const config = this.app.config.get('payments', {});
+            // Build the billing layer here (async — resolves the app emitter + handler
+            // factories), so the mounted route can emit `billing:*` and run app handlers.
+            if (config.billing?.enabled !== false) {
+                await this.#buildBillingLayer(config);
+            }
+            // Resolve the manager here so `setPayments` runs and `getPayments()` works for
+            // services that read it during boot — after every provider has registered.
+            await this.app.container.make(PaymentsManager);
+            const router = await this.app.container.make('router');
+            this.#registerWebhookRoute(router);
+        });
+    }
+    async #buildBillingLayer(config) {
+        const store = new LucidBillingStore();
+        const handlers = await this.#resolveAllHandlers(config.billing?.handlers);
+        const processor = new WebhookProcessor({
+            store,
+            ...(handlers !== undefined ? { handlers } : {}),
+        });
+        this.#webhook = new WebhookDispatcher({
+            processor,
+            mode: this.#resolveMode(config),
+            // In 'auto', durable is used only when its engine is resolvable in the app
+            // (i.e. the durable provider is registered) — not merely installed.
+            durableAvailable: () => this.#isDurableAvailable(),
+        });
+    }
+    /**
+     * Merge webhook handlers from the two sources:
+     * 1. `config.billing.handlers` (functions or service classes),
+     * 2. the conventions folder `app/payment_handlers/` (build-time barrel, runtime scan
+     *    as fallback) — the durable-style discovery.
+     */
+    async #resolveAllHandlers(configHandlers) {
+        const handlers = {};
+        if (configHandlers) {
+            for (const [type, entry] of Object.entries(configHandlers)) {
+                handlers[type] = await resolveWebhookHandler(entry, this.app.container);
+            }
+        }
+        for (const discovered of await this.#discoverFolderHandlers()) {
+            handlers[discovered.type] = await resolveWebhookHandler(discovered.entry, this.app.container);
+        }
+        return Object.keys(handlers).length > 0 ? handlers : undefined;
+    }
+    /** Discover handlers in `app/payment_handlers/`: build-time barrel, else runtime scan. */
+    async #discoverFolderHandlers() {
+        const barrel = await this.#loadGeneratedBarrel();
+        if (barrel)
+            return loadWebhookHandlersFromBarrel(barrel);
+        const dir = this.app.makePath('app/payment_handlers');
+        return discoverWebhookHandlers(dir);
+    }
+    /** Import the Assembler `init`-hook barrel (`.adonisjs/payments/webhook_handlers.js`). */
+    async #loadGeneratedBarrel() {
+        const path = this.app.makePath('.adonisjs/payments/webhook_handlers.js');
+        try {
+            const mod = (await import(pathToFileURL(path).href));
+            return mod.webhookHandlers ?? null;
+        }
+        catch (err) {
+            const code = err.code;
+            if (code === 'ERR_MODULE_NOT_FOUND' || code === 'ENOENT')
+                return null;
+            throw err;
+        }
+    }
+    /** Whether the app has a resolvable durable workflow engine. */
+    async #isDurableAvailable() {
+        try {
+            const { WorkflowEngine } = await import('@adonis-agora/durable');
+            await this.app.container.make(WorkflowEngine);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Map `billing.durable` (`'auto' | boolean`) onto the dispatcher's mode. */
+    #resolveMode(config) {
+        const setting = config.billing?.durable ?? 'auto';
+        if (setting === true)
+            return 'durable';
+        if (setting === false)
+            return 'in-process';
+        return 'auto';
+    }
+    #registerWebhookRoute(router) {
+        router
+            .post('/payments/webhook/:provider', async (ctx) => {
+            const manager = await this.app.container.make(PaymentsManager);
+            const provider = String(ctx.params.provider);
+            try {
+                const driver = manager.driver(provider);
+                const rawBody = ctx.request.raw() ?? '';
+                const event = driver.parseWebhook(rawBody, ctx.request.headers());
+                if (this.#webhook) {
+                    await this.#webhook.dispatch(event);
+                }
+                return ctx.response.status(200).json({ received: true });
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : 'invalid webhook';
+                return ctx.response.status(400).json({ error: message });
+            }
+        })
+            .as('payments.webhook');
+    }
+}
+//# sourceMappingURL=payments_provider.js.map

package/dist/providers/payments_provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"payments_provider.js","sourceRoot":"","sources":["../../providers/payments_provider.ts"],"names":[],"mappings":"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"}

package/dist/src/billing/billing_overview.d.ts

@@ -0,0 +1,26 @@
+import type { BillingStore } from './billing_store.js';
+/** One aggregate line of the billing overview. */
+export interface BillingOverviewMetric {
+    key: string;
+    label: string;
+    value: number;
+}
+/** The dashboard's data contract: aggregate KPIs over a window. */
+export interface BillingOverview {
+    period: {
+        from: Date;
+        to: Date;
+    };
+    metrics: BillingOverviewMetric[];
+}
+/**
+ * Compute a billing overview from the store — the data foundation a billing dashboard
+ * (Agora dashboard pattern) renders. Aggregates KPIs over a `from`/`to` window: revenue
+ * (sum of paid payments), active subscriptions, and usage per meter. Pure store queries
+ * (no gateway calls), so it works headless and is trivially testable.
+ */
+export declare function billingOverview(store: BillingStore, options: {
+    from: Date;
+    to: Date;
+}): Promise<BillingOverview>;
+//# sourceMappingURL=billing_overview.d.ts.map

package/dist/src/billing/billing_overview.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"billing_overview.d.ts","sourceRoot":"","sources":["../../../src/billing/billing_overview.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,kDAAkD;AAClD,MAAM,WAAW,qBAAqB;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED,mEAAmE;AACnE,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE;QAAE,IAAI,EAAE,IAAI,CAAC;QAAC,EAAE,EAAE,IAAI,CAAA;KAAE,CAAC;IACjC,OAAO,EAAE,qBAAqB,EAAE,CAAC;CAClC;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,EAAE,EAAE,IAAI,CAAA;CAAE,GAChC,OAAO,CAAC,eAAe,CAAC,CAqB1B"}

package/dist/src/billing/billing_overview.js

@@ -0,0 +1,27 @@
+/**
+ * Compute a billing overview from the store — the data foundation a billing dashboard
+ * (Agora dashboard pattern) renders. Aggregates KPIs over a `from`/`to` window: revenue
+ * (sum of paid payments), active subscriptions, and usage per meter. Pure store queries
+ * (no gateway calls), so it works headless and is trivially testable.
+ */
+export async function billingOverview(store, options) {
+    const { from, to } = options;
+    const [revenue, activeSubscriptions, usage] = await Promise.all([
+        store.revenue({ from, to }),
+        store.countActiveSubscriptions(),
+        store.usageReport({ from, to }),
+    ]);
+    const metrics = [
+        { key: 'revenue', label: 'Revenue (cents)', value: revenue },
+        { key: 'active_subscriptions', label: 'Active subscriptions', value: activeSubscriptions },
+    ];
+    for (const line of usage) {
+        metrics.push({
+            key: `meter:${line.meter}`,
+            label: `Usage · ${line.meter}`,
+            value: line.quantity,
+        });
+    }
+    return { period: { from, to }, metrics };
+}
+//# sourceMappingURL=billing_overview.js.map

package/dist/src/billing/billing_overview.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"billing_overview.js","sourceRoot":"","sources":["../../../src/billing/billing_overview.ts"],"names":[],"mappings":"AAeA;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,KAAmB,EACnB,OAAiC;IAEjC,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE,GAAG,OAAO,CAAC;IAC7B,MAAM,CAAC,OAAO,EAAE,mBAAmB,EAAE,KAAK,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QAC9D,KAAK,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;QAC3B,KAAK,CAAC,wBAAwB,EAAE;QAChC,KAAK,CAAC,WAAW,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;KAChC,CAAC,CAAC;IAEH,MAAM,OAAO,GAA4B;QACvC,EAAE,GAAG,EAAE,SAAS,EAAE,KAAK,EAAE,iBAAiB,EAAE,KAAK,EAAE,OAAO,EAAE;QAC5D,EAAE,GAAG,EAAE,sBAAsB,EAAE,KAAK,EAAE,sBAAsB,EAAE,KAAK,EAAE,mBAAmB,EAAE;KAC3F,CAAC;IACF,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,OAAO,CAAC,IAAI,CAAC;YACX,GAAG,EAAE,SAAS,IAAI,CAAC,KAAK,EAAE;YAC1B,KAAK,EAAE,WAAW,IAAI,CAAC,KAAK,EAAE;YAC9B,KAAK,EAAE,IAAI,CAAC,QAAQ;SACrB,CAAC,CAAC;IACL,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC;AAC3C,CAAC"}

package/dist/src/billing/billing_store.d.ts

@@ -0,0 +1,73 @@
+import type { BillingPayment, BillingSubscription, BillingUsageEvent, BillingWebhookEvent } from './mixins/index.js';
+/**
+ * The persistence SPI for the billing layer. The Lucid implementation writes through the
+ * configured models; an in-memory implementation exists in `src/testing` so the billing
+ * layer is unit-testable without a database.
+ *
+ * Generic over the row types so the in-memory store can use plain objects while the
+ * Lucid store returns model instances.
+ */
+export interface BillingStore<SubscriptionRow = BillingSubscription, PaymentRow = BillingPayment, WebhookEventRow = BillingWebhookEvent, UsageEventRow = BillingUsageEvent> {
+    /** Upsert a subscription keyed by gateway id. Returns the stored row. */
+    saveSubscription(sub: {
+        gatewayId: string;
+        provider: string;
+        customerId: string;
+        status: string;
+        planId: string;
+        trialEndsAt?: Date | null;
+        endsAt?: Date | null;
+        payload?: Record<string, unknown>;
+    }): Promise<SubscriptionRow>;
+    findSubscriptionByGatewayId(gatewayId: string): Promise<SubscriptionRow | null>;
+    /** Upsert a payment keyed by gateway id. Returns the stored row. */
+    savePayment(payment: {
+        gatewayId: string;
+        provider: string;
+        status: string;
+        amount: number;
+        currency: string;
+        customerId?: string | null;
+        subscriptionId?: string | null;
+        paidAt?: Date | null;
+        payload?: Record<string, unknown>;
+    }): Promise<PaymentRow>;
+    findPaymentByGatewayId(gatewayId: string): Promise<PaymentRow | null>;
+    /** Record a webhook event for idempotency. Returns null when the event was already recorded. */
+    recordWebhookEvent(event: {
+        gatewayEventId: string;
+        provider: string;
+        type: string;
+        payload: Record<string, unknown>;
+    }): Promise<WebhookEventRow | null>;
+    markWebhookProcessed(id: string): Promise<void>;
+    markWebhookFailed(id: string, error: string): Promise<void>;
+    /** Record one metered-usage event (a metered subscription's consumption). */
+    recordUsage(event: {
+        subscriptionId?: string | null;
+        customerId?: string;
+        meter: string;
+        quantity: number;
+        metadata?: Record<string, unknown>;
+        recordedAt?: Date;
+    }): Promise<UsageEventRow>;
+    /** Aggregate metered usage by meter, filtered by subscription/customer/meter/window. */
+    usageReport(query: {
+        subscriptionId?: string;
+        customerId?: string;
+        meter?: string;
+        from?: Date;
+        to?: Date;
+    }): Promise<Array<{
+        meter: string;
+        quantity: number;
+    }>>;
+    /** Sum of paid payments within a window (revenue, in cents). */
+    revenue(query: {
+        from?: Date;
+        to?: Date;
+    }): Promise<number>;
+    /** Count of active subscriptions (status `'active'`/`'trialing'`). */
+    countActiveSubscriptions(): Promise<number>;
+}
+//# sourceMappingURL=billing_store.d.ts.map

package/dist/src/billing/billing_store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"billing_store.d.ts","sourceRoot":"","sources":["../../../src/billing/billing_store.ts"],"names":[],"mappings":"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"}

package/dist/src/billing/billing_store.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=billing_store.js.map

package/dist/src/billing/billing_store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"billing_store.js","sourceRoot":"","sources":["../../../src/billing/billing_store.ts"],"names":[],"mappings":""}

package/dist/src/billing/index.d.ts

@@ -0,0 +1,8 @@
+export type { BillingStore } from './billing_store.js';
+export { LucidBillingStore, lucidBillingStore } from './lucid_billing_store.js';
+export type { BillingModels } from './lucid_billing_store.js';
+export { withBillable } from './mixins/with_billable.js';
+export { BillingSubscription, withSubscription } from './mixins/with_subscription.js';
+export { BillingPayment, withPayment } from './mixins/with_payment.js';
+export { BillingWebhookEvent } from './mixins/with_webhook_event.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/billing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/billing/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAChF,YAAY,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACtF,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvE,OAAO,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC"}

package/dist/src/billing/index.js

@@ -0,0 +1,6 @@
+export { LucidBillingStore, lucidBillingStore } from './lucid_billing_store.js';
+export { withBillable } from './mixins/with_billable.js';
+export { BillingSubscription, withSubscription } from './mixins/with_subscription.js';
+export { BillingPayment, withPayment } from './mixins/with_payment.js';
+export { BillingWebhookEvent } from './mixins/with_webhook_event.js';
+//# sourceMappingURL=index.js.map

package/dist/src/billing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/billing/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAEhF,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACtF,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvE,OAAO,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC"}

package/dist/src/billing/lucid_billing_store.d.ts

@@ -0,0 +1,84 @@
+import type { NormalizeConstructor } from '@adonisjs/core/types/helpers';
+import type { BillingStore } from './billing_store.js';
+import { BillingPayment as DefaultPayment, BillingSubscription as DefaultSubscription, BillingUsageEvent as DefaultUsageEvent, BillingWebhookEvent as DefaultWebhookEvent } from './mixins/index.js';
+/**
+ * Models the billing layer persists through. Apps may override any of them with their own
+ * model composed from the corresponding mixin (authkit `lucidStores` pattern).
+ */
+export interface BillingModels {
+    subscriptionModel?: NormalizeConstructor<typeof DefaultSubscription>;
+    paymentModel?: NormalizeConstructor<typeof DefaultPayment>;
+    webhookEventModel?: NormalizeConstructor<typeof DefaultWebhookEvent>;
+    usageEventModel?: NormalizeConstructor<typeof DefaultUsageEvent>;
+}
+type SubscriptionInstance = InstanceType<typeof DefaultSubscription>;
+type PaymentInstance = InstanceType<typeof DefaultPayment>;
+type WebhookEventInstance = InstanceType<typeof DefaultWebhookEvent>;
+type UsageEventInstance = InstanceType<typeof DefaultUsageEvent>;
+/**
+ * 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 declare class LucidBillingStore implements BillingStore<SubscriptionInstance, PaymentInstance, WebhookEventInstance, UsageEventInstance> {
+    #private;
+    constructor(models?: BillingModels);
+    saveSubscription(sub: {
+        gatewayId: string;
+        provider: string;
+        customerId: string;
+        status: string;
+        planId: string;
+        trialEndsAt?: Date | null;
+        endsAt?: Date | null;
+        payload?: Record<string, unknown>;
+    }): Promise<SubscriptionInstance>;
+    findSubscriptionByGatewayId(gatewayId: string): Promise<SubscriptionInstance | null>;
+    savePayment(payment: {
+        gatewayId: string;
+        provider: string;
+        status: string;
+        amount: number;
+        currency: string;
+        customerId?: string | null;
+        subscriptionId?: string | null;
+        paidAt?: Date | null;
+        payload?: Record<string, unknown>;
+    }): Promise<PaymentInstance>;
+    findPaymentByGatewayId(gatewayId: string): Promise<PaymentInstance | null>;
+    recordWebhookEvent(event: {
+        gatewayEventId: string;
+        provider: string;
+        type: string;
+        payload: Record<string, unknown>;
+    }): Promise<WebhookEventInstance | null>;
+    markWebhookProcessed(id: string): Promise<void>;
+    markWebhookFailed(id: string, error: string): Promise<void>;
+    recordUsage(event: {
+        subscriptionId?: string | null;
+        customerId?: string;
+        meter: string;
+        quantity: number;
+        metadata?: Record<string, unknown>;
+        recordedAt?: Date;
+    }): Promise<UsageEventInstance>;
+    usageReport(query: {
+        subscriptionId?: string;
+        customerId?: string;
+        meter?: string;
+        from?: Date;
+        to?: Date;
+    }): Promise<Array<{
+        meter: string;
+        quantity: number;
+    }>>;
+    revenue(query: {
+        from?: Date;
+        to?: Date;
+    }): Promise<number>;
+    countActiveSubscriptions(): Promise<number>;
+}
+/** Builder matching the authkit `lucidStores(...)` convention. */
+export declare function lucidBillingStore(models?: BillingModels): BillingStore;
+export {};
+//# sourceMappingURL=lucid_billing_store.d.ts.map

package/dist/src/billing/lucid_billing_store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lucid_billing_store.d.ts","sourceRoot":"","sources":["../../../src/billing/lucid_billing_store.ts"],"names":[],"mappings":"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"}

package/dist/src/billing/lucid_billing_store.js

@@ -0,0 +1,143 @@
+import { DateTime } from 'luxon';
+import { BillingPayment as DefaultPayment, BillingSubscription as DefaultSubscription, BillingUsageEvent as DefaultUsageEvent, BillingWebhookEvent as DefaultWebhookEvent, } from './mixins/index.js';
+/**
+ * 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 {
+    #subscriptionModel;
+    #paymentModel;
+    #webhookEventModel;
+    #usageEventModel;
+    constructor(models = {}) {
+        this.#subscriptionModel = (models.subscriptionModel ??
+            DefaultSubscription);
+        this.#paymentModel = (models.paymentModel ?? DefaultPayment);
+        this.#webhookEventModel = (models.webhookEventModel ??
+            DefaultWebhookEvent);
+        this.#usageEventModel = (models.usageEventModel ??
+            DefaultUsageEvent);
+    }
+    async saveSubscription(sub) {
+        const existing = await this.findSubscriptionByGatewayId(sub.gatewayId);
+        const row = (existing ?? new this.#subscriptionModel());
+        row.gatewayId = sub.gatewayId;
+        row.provider = sub.provider;
+        row.customerId = sub.customerId;
+        row.status = sub.status;
+        row.planId = sub.planId;
+        row.trialEndsAt = sub.trialEndsAt ? DateTime.fromJSDate(sub.trialEndsAt) : null;
+        row.endsAt = sub.endsAt ? DateTime.fromJSDate(sub.endsAt) : null;
+        row.payload = sub.payload ?? {};
+        await row.save();
+        return row;
+    }
+    async findSubscriptionByGatewayId(gatewayId) {
+        const row = await this.#subscriptionModel.findBy('gateway_id', gatewayId);
+        return row;
+    }
+    async savePayment(payment) {
+        const existing = await this.findPaymentByGatewayId(payment.gatewayId);
+        const row = (existing ?? new this.#paymentModel());
+        row.gatewayId = payment.gatewayId;
+        row.provider = payment.provider;
+        row.status = payment.status;
+        row.amount = payment.amount;
+        row.currency = payment.currency;
+        row.customerId = payment.customerId ?? null;
+        row.subscriptionId = payment.subscriptionId ?? null;
+        row.paidAt = payment.paidAt ? DateTime.fromJSDate(payment.paidAt) : null;
+        row.payload = payment.payload ?? {};
+        await row.save();
+        return row;
+    }
+    async findPaymentByGatewayId(gatewayId) {
+        const row = await this.#paymentModel.findBy('gateway_id', gatewayId);
+        return row;
+    }
+    async recordWebhookEvent(event) {
+        const existing = await this.#webhookEventModel.findBy('gateway_event_id', event.gatewayEventId);
+        if (existing)
+            return null;
+        const row = new this.#webhookEventModel();
+        row.gatewayEventId = event.gatewayEventId;
+        row.provider = event.provider;
+        row.type = event.type;
+        row.status = 'received';
+        row.payload = event.payload;
+        row.error = null;
+        await row.save();
+        return row;
+    }
+    async markWebhookProcessed(id) {
+        const row = await this.#webhookEventModel.find(id);
+        if (row) {
+            row.status = 'processed';
+            await row.save();
+        }
+    }
+    async markWebhookFailed(id, error) {
+        const row = await this.#webhookEventModel.find(id);
+        if (row) {
+            row.status = 'failed';
+            row.error = error;
+            await row.save();
+        }
+    }
+    async recordUsage(event) {
+        const row = new this.#usageEventModel();
+        row.subscriptionId = event.subscriptionId ?? null;
+        row.customerId = event.customerId ?? null;
+        row.meter = event.meter;
+        row.quantity = event.quantity;
+        row.metadata = event.metadata ?? {};
+        row.recordedAt = event.recordedAt ? DateTime.fromJSDate(event.recordedAt) : DateTime.now();
+        await row.save();
+        return row;
+    }
+    async usageReport(query) {
+        const builder = this.#usageEventModel
+            .query()
+            .select('meter')
+            .sum('quantity as quantity')
+            .groupBy('meter');
+        if (query.subscriptionId !== undefined)
+            builder.where('subscription_id', query.subscriptionId);
+        else if (query.customerId !== undefined)
+            builder.where('customer_id', query.customerId);
+        if (query.meter !== undefined)
+            builder.where('meter', query.meter);
+        if (query.from !== undefined)
+            builder.where('recorded_at', '>=', query.from);
+        if (query.to !== undefined)
+            builder.where('recorded_at', '<', query.to);
+        const rows = await builder;
+        return rows.map((row) => ({
+            meter: row.meter,
+            quantity: Number(row.quantity),
+        }));
+    }
+    async revenue(query) {
+        const builder = this.#paymentModel.query().where('status', 'paid').sum('amount as total');
+        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);
+    }
+    async countActiveSubscriptions() {
+        const count = await this.#subscriptionModel
+            .query()
+            .whereIn('status', ['active', 'trialing'])
+            .count('* as total');
+        return Number(count[0]?.total ?? 0);
+    }
+}
+/** Builder matching the authkit `lucidStores(...)` convention. */
+export function lucidBillingStore(models = {}) {
+    return new LucidBillingStore(models);
+}
+//# sourceMappingURL=lucid_billing_store.js.map

package/dist/src/billing/lucid_billing_store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lucid_billing_store.js","sourceRoot":"","sources":["../../../src/billing/lucid_billing_store.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAEjC,OAAO,EACL,cAAc,IAAI,cAAc,EAChC,mBAAmB,IAAI,mBAAmB,EAC1C,iBAAiB,IAAI,iBAAiB,EACtC,mBAAmB,IAAI,mBAAmB,GAC3C,MAAM,mBAAmB,CAAC;AAkB3B;;;;GAIG;AACH,MAAM,OAAO,iBAAiB;IAI5B,kBAAkB,CAA6B;IAC/C,aAAa,CAAwB;IACrC,kBAAkB,CAA6B;IAC/C,gBAAgB,CAA2B;IAE3C,YAAY,SAAwB,EAAE;QACpC,IAAI,CAAC,kBAAkB,GAAG,CAAC,MAAM,CAAC,iBAAiB;YACjD,mBAAmB,CAA+B,CAAC;QACrD,IAAI,CAAC,aAAa,GAAG,CAAC,MAAM,CAAC,YAAY,IAAI,cAAc,CAA0B,CAAC;QACtF,IAAI,CAAC,kBAAkB,GAAG,CAAC,MAAM,CAAC,iBAAiB;YACjD,mBAAmB,CAA+B,CAAC;QACrD,IAAI,CAAC,gBAAgB,GAAG,CAAC,MAAM,CAAC,eAAe;YAC7C,iBAAiB,CAA6B,CAAC;IACnD,CAAC;IAED,KAAK,CAAC,gBAAgB,CAAC,GAStB;QACC,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,2BAA2B,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACvE,MAAM,GAAG,GAAG,CAAC,QAAQ,IAAI,IAAI,IAAI,CAAC,kBAAkB,EAAE,CAAyB,CAAC;QAChF,GAAG,CAAC,SAAS,GAAG,GAAG,CAAC,SAAS,CAAC;QAC9B,GAAG,CAAC,QAAQ,GAAG,GAAG,CAAC,QAAQ,CAAC;QAC5B,GAAG,CAAC,UAAU,GAAG,GAAG,CAAC,UAAU,CAAC;QAChC,GAAG,CAAC,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC;QACxB,GAAG,CAAC,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC;QACxB,GAAG,CAAC,WAAW,GAAG,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QAChF,GAAG,CAAC,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QACjE,GAAG,CAAC,OAAO,GAAG,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC;QAChC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;QACjB,OAAO,GAAG,CAAC;IACb,CAAC;IAED,KAAK,CAAC,2BAA2B,CAAC,SAAiB;QACjD,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,kBAAkB,CAAC,MAAM,CAAC,YAAY,EAAE,SAAS,CAAC,CAAC;QAC1E,OAAO,GAAkC,CAAC;IAC5C,CAAC;IAED,KAAK,CAAC,WAAW,CAAC,OAUjB;QACC,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,sBAAsB,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QACtE,MAAM,GAAG,GAAG,CAAC,QAAQ,IAAI,IAAI,IAAI,CAAC,aAAa,EAAE,CAAoB,CAAC;QACtE,GAAG,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;QAClC,GAAG,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QAChC,GAAG,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC5B,GAAG,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC5B,GAAG,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QAChC,GAAG,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,IAAI,CAAC;QAC5C,GAAG,CAAC,cAAc,GAAG,OAAO,CAAC,cAAc,IAAI,IAAI,CAAC;QACpD,GAAG,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QACzE,GAAG,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC;QACpC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;QACjB,OAAO,GAAG,CAAC;IACb,CAAC;IAED,KAAK,CAAC,sBAAsB,CAAC,SAAiB;QAC5C,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,YAAY,EAAE,SAAS,CAAC,CAAC;QACrE,OAAO,GAA6B,CAAC;IACvC,CAAC;IAED,KAAK,CAAC,kBAAkB,CAAC,KAKxB;QACC,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,kBAAkB,CAAC,MAAM,CAAC,kBAAkB,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC;QAChG,IAAI,QAAQ;YAAE,OAAO,IAAI,CAAC;QAC1B,MAAM,GAAG,GAAG,IAAI,IAAI,CAAC,kBAAkB,EAA0B,CAAC;QAClE,GAAG,CAAC,cAAc,GAAG,KAAK,CAAC,cAAc,CAAC;QAC1C,GAAG,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC;QAC9B,GAAG,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;QACtB,GAAG,CAAC,MAAM,GAAG,UAAU,CAAC;QACxB,GAAG,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;QAC5B,GAAG,CAAC,KAAK,GAAG,IAAI,CAAC;QACjB,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;QACjB,OAAO,GAAG,CAAC;IACb,CAAC;IAED,KAAK,CAAC,oBAAoB,CAAC,EAAU;QACnC,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACnD,IAAI,GAAG,EAAE,CAAC;YACR,GAAG,CAAC,MAAM,GAAG,WAAW,CAAC;YACzB,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;QACnB,CAAC;IACH,CAAC;IAED,KAAK,CAAC,iBAAiB,CAAC,EAAU,EAAE,KAAa;QAC/C,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACnD,IAAI,GAAG,EAAE,CAAC;YACR,GAAG,CAAC,MAAM,GAAG,QAAQ,CAAC;YACtB,GAAG,CAAC,KAAK,GAAG,KAAK,CAAC;YAClB,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;QACnB,CAAC;IACH,CAAC;IAED,KAAK,CAAC,WAAW,CAAC,KAOjB;QACC,MAAM,GAAG,GAAG,IAAI,IAAI,CAAC,gBAAgB,EAAwB,CAAC;QAC9D,GAAG,CAAC,cAAc,GAAG,KAAK,CAAC,cAAc,IAAI,IAAI,CAAC;QAClD,GAAG,CAAC,UAAU,GAAG,KAAK,CAAC,UAAU,IAAI,IAAI,CAAC;QAC1C,GAAG,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;QACxB,GAAG,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC;QAC9B,GAAG,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,IAAI,EAAE,CAAC;QACpC,GAAG,CAAC,UAAU,GAAG,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC;QAC3F,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;QACjB,OAAO,GAAG,CAAC;IACb,CAAC;IAED,KAAK,CAAC,WAAW,CAAC,KAMjB;QACC,MAAM,OAAO,GAAG,IAAI,CAAC,gBAAgB;aAClC,KAAK,EAAE;aACP,MAAM,CAAC,OAAO,CAAC;aACf,GAAG,CAAC,sBAAsB,CAAC;aAC3B,OAAO,CAAC,OAAO,CAAC,CAAC;QACpB,IAAI,KAAK,CAAC,cAAc,KAAK,SAAS;YAAE,OAAO,CAAC,KAAK,CAAC,iBAAiB,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC;aAC1F,IAAI,KAAK,CAAC,UAAU,KAAK,SAAS;YAAE,OAAO,CAAC,KAAK,CAAC,aAAa,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;QACxF,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS;YAAE,OAAO,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;QACnE,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS;YAAE,OAAO,CAAC,KAAK,CAAC,aAAa,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QAC7E,IAAI,KAAK,CAAC,EAAE,KAAK,SAAS;YAAE,OAAO,CAAC,KAAK,CAAC,aAAa,EAAE,GAAG,EAAE,KAAK,CAAC,EAAE,CAAC,CAAC;QACxE,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC;QAC3B,OAAQ,IAA4D,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;YACjF,KAAK,EAAE,GAAG,CAAC,KAAK;YAChB,QAAQ,EAAE,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;SAC/B,CAAC,CAAC,CAAC;IACN,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,KAAiC;QAC7C,MAAM,OAAO,GAAG,IAAI,CAAC,aAAa,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;QAC1F,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS;YAAE,OAAO,CAAC,KAAK,CAAC,SAAS,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QACzE,IAAI,KAAK,CAAC,EAAE,KAAK,SAAS;YAAE,OAAO,CAAC,KAAK,CAAC,SAAS,EAAE,GAAG,EAAE,KAAK,CAAC,EAAE,CAAC,CAAC;QACpE,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC;QAC3B,MAAM,KAAK,GAAI,IAAI,CAAC,CAAC,CAA6C,EAAE,KAAK,CAAC;QAC1E,OAAO,MAAM,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC;IAC5B,CAAC;IAED,KAAK,CAAC,wBAAwB;QAC5B,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,kBAAkB;aACxC,KAAK,EAAE;aACP,OAAO,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;aACzC,KAAK,CAAC,YAAY,CAAC,CAAC;QACvB,OAAO,MAAM,CAAE,KAAK,CAAC,CAAC,CAA6C,EAAE,KAAK,IAAI,CAAC,CAAC,CAAC;IACnF,CAAC;CACF;AAED,kEAAkE;AAClE,MAAM,UAAU,iBAAiB,CAAC,SAAwB,EAAE;IAC1D,OAAO,IAAI,iBAAiB,CAAC,MAAM,CAAC,CAAC;AACvC,CAAC"}

package/dist/src/billing/metered_bill.d.ts

@@ -0,0 +1,60 @@
+import type { BillingStore } from './billing_store.js';
+/** The per-meter rate and included allowance for a metered plan. */
+export interface MeterRate {
+    /** The meter name, e.g. `'api_calls'`. */
+    meter: string;
+    /** Price per unit of the meter, in currency smallest unit (e.g. cents). */
+    rate: number;
+    /** Units included free of charge per billing period. Defaults to 0. */
+    included?: number;
+}
+/** One metered bill line — how much of a meter was consumed and what it costs. */
+export interface MeteredBillLine {
+    meter: string;
+    quantity: number;
+    /** Quantity beyond the plan's included allowance. */
+    billable: number;
+    /** `billable × rate`, in cents. */
+    amount: number;
+}
+/** The result of pricing a period's metered usage. */
+export interface MeteredBill {
+    lines: MeteredBillLine[];
+    /** Sum of all line amounts, in cents. */
+    total: number;
+}
+/**
+ * Price a period's metered usage against per-meter rates — the "how much do I bill for
+ * what was consumed" step of a metered subscription. Pure: feed it a
+ * {@link BillingStore.usageReport} result and the plan's {@link MeterRate}s.
+ *
+ * ```ts
+ * const usage = await store.usageReport({ subscriptionId: sub.id, from, to })
+ * const bill = meteredBill(usage, [
+ *   { meter: 'api_calls', rate: 0.5,  included: 1000 },
+ *   { meter: 'storage_gb', rate: 200 },
+ * ])
+ * bill.total // cents to charge for overage
+ * ```
+ */
+export declare function meteredBill(usage: Array<{
+    meter: string;
+    quantity: number;
+}>, rates: MeterRate[]): MeteredBill;
+/**
+ * Convenience: run a subscription's metered usage for a window through
+ * {@link meteredBill}. Fetches the usage from the store, prices it with `rates`, and
+ * returns the bill (plus the raw usage for reference).
+ */
+export declare function meteredBillForSubscription(store: BillingStore, input: {
+    subscriptionId: string;
+    from: Date;
+    to: Date;
+    rates: MeterRate[];
+}): Promise<MeteredBill & {
+    usage: Array<{
+        meter: string;
+        quantity: number;
+    }>;
+}>;
+//# sourceMappingURL=metered_bill.d.ts.map