@adonis-agora/payments 0.2.0 → 0.3.0

package/dist/providers/payments_client_provider.js

@@ -0,0 +1,95 @@
+import { resolveConfig, } from '../src/client/define_config.js';
+import { paymentStatus } from '../src/client/handlers.js';
+import { getBillingStore } from '../src/services/main.js';
+/**
+ * Mounts the browser-facing status endpoint from `config/payments_client.ts`.
+ *
+ * One route, and only one:
+ *
+ * - `GET <path>/status?reference=<reference>` -> `{ status, amount, currency, paidAt }`
+ *
+ * It exists because a Pix QR (or a boleto) is not paid until the gateway's webhook says so,
+ * seconds to days later, and every app that takes Pix otherwise hand-writes the same
+ * polling loop in its checkout page. It does NOT wrap any gateway's card SDK — Stripe,
+ * Mercado Pago and Adyen ship their own, and eighteen of those is a surface this package
+ * could not keep honest.
+ *
+ * Disabled by default. With `enabled: false` (the default) this provider registers NOTHING:
+ * unlike the dashboard, which is an operator console behind an admin gate, this endpoint is
+ * reachable by every logged-in browser, so an app takes it on deliberately.
+ *
+ * Registered separately from `payments_provider` for the same reason the dashboard is: the
+ * webhook route lives at `/payments/webhook/:provider`, and a guard mounted over that prefix
+ * is how a gateway delivery ends up answering `403`. This one mounts under
+ * `/payments/client` and touches nothing above it.
+ */
+export default class PaymentsClientProvider {
+    app;
+    constructor(app) {
+        this.app = app;
+    }
+    /** Warn once, not once per poll — a denied checkout page can retry for a while. */
+    warnedOnDeny = false;
+    async boot() {
+        const config = resolveConfig(this.app.config.get('payments_client', {}));
+        if (!config.enabled)
+            return;
+        // Registration can't happen synchronously in `boot()`: the router singleton isn't
+        // committed until the app's "booted" hooks run, which fire after every provider's `boot()`.
+        await this.app.booted(async () => {
+            const router = await this.app.container.make('router');
+            this.registerRoutes(router, config);
+        });
+    }
+    registerRoutes(router, config) {
+        router
+            .get(`${config.path}/status`, async (ctx) => {
+            // A payment status is per-caller and changes under you. Nothing between the browser
+            // and here may keep a copy — least of all a shared proxy, which would hand one
+            // customer's settled charge to the next caller with the same URL.
+            ctx.response.header('cache-control', 'no-store');
+            let store;
+            try {
+                store = getBillingStore();
+            }
+            catch (error) {
+                // The billing layer is off, or the app has not booted it. A deployment state, not
+                // a bad request — say so rather than emit a stack-trace-shaped 500.
+                return ctx.response.status(503).json({
+                    error: error instanceof Error ? error.message : 'billing store unavailable',
+                });
+            }
+            const reference = ctx.request.qs().reference;
+            const result = await paymentStatus({
+                store,
+                config,
+                onDeny: (reason) => {
+                    void this.warnOnDeny(reason);
+                },
+            }, ctx, typeof reference === 'string' ? reference : undefined);
+            return ctx.response.status(result.status).json(result.body);
+        })
+            .as('payments_client.status');
+    }
+    /**
+     * Surface the developer-facing denial reason once.
+     *
+     * The browser only ever sees `403`. The single most likely cause — the app never called
+     * `ensureCustomer({ store, owner })`, so `billing_customers` is empty and the default
+     * guard can prove nothing — is otherwise indistinguishable from a real denial, and an
+     * install would sit there refusing every poll with no clue why.
+     */
+    async warnOnDeny(reason) {
+        if (this.warnedOnDeny)
+            return;
+        this.warnedOnDeny = true;
+        try {
+            const logger = await this.app.container.make('logger');
+            logger.warn(reason);
+        }
+        catch {
+            // No logger (a container this bare is a test harness, not a running app).
+        }
+    }
+}
+//# sourceMappingURL=payments_client_provider.js.map

package/dist/providers/payments_client_provider.js.map

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

package/dist/providers/payments_provider.d.ts

@@ -1,4 +1,8 @@
+import type { HttpContext } from '@adonisjs/core/http';
 import type { ApplicationService } from '@adonisjs/core/types';
+import type { BillingStore } from '../src/billing/billing_store.js';
+import { WebhookDispatcher } from '../src/billing/webhook_dispatcher.js';
+import { PaymentsManager } from '../src/payments_manager.js';
 /**
  * Wires `@adonis-agora/payments` into the AdonisJS application: binds a singleton
  * {@link PaymentsManager} built from `config/payments.ts`, wires the optional Lucid
@@ -11,5 +15,36 @@ export default class PaymentsProvider {
     constructor(app: ApplicationService);
     register(): void;
     boot(): Promise<void>;
+    /**
+     * Wire the typed `payments` Telescope watcher, if telescope is in this app and nobody has
+     * already wired one.
+     *
+     * In `ready()`, not `boot()`, and that is the load-bearing part: `start/` files run before
+     * `ready`, so an app that registers its own `PaymentsWatcher` — the way the docs used to
+     * say to — has already claimed the payments channels by the time this looks, and this
+     * stands down. Doing it in `boot()` would race that and record every payment event twice
+     * for exactly the apps that followed the instructions.
+     *
+     * There is no config option. Every one that was drafted described something the code can
+     * detect: the claims registry answers "I wire my own", and a failed import answers "I do
+     * not use telescope".
+     */
+    ready(): Promise<void>;
+    /** Release the watcher's channel claims and subscriptions on shutdown. */
+    shutdown(): Promise<void>;
 }
+/**
+ * One webhook delivery, from raw body to HTTP status — the body of the mounted
+ * `POST /payments/webhook/:provider` route.
+ *
+ * Exported so the delivery can be tested for what it actually promises the gateway (the
+ * status code IS the retry instruction) without standing up an application, a router and a
+ * container around it.
+ */
+export declare function handleWebhookDelivery(ctx: HttpContext, deps: {
+    manager: PaymentsManager;
+    dispatcher?: WebhookDispatcher | undefined;
+    /** Where a REFUSED delivery is recorded. Absent when the billing layer is off. */
+    store?: Pick<BillingStore, 'recordAuditEvent'> | undefined;
+}): Promise<unknown>;
 //# sourceMappingURL=payments_provider.d.ts.map

package/dist/providers/payments_provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"payments_provider.d.ts","sourceRoot":"","sources":["../../providers/payments_provider.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAqB,MAAM,sBAAsB,CAAC;AAkBlF;;;;;GAKG;AACH,MAAM,CAAC,OAAO,OAAO,gBAAgB;;IAGvB,SAAS,CAAC,GAAG,EAAE,kBAAkB;gBAAvB,GAAG,EAAE,kBAAkB;IAE7C,QAAQ;IAwBF,IAAI;CAmHX"}
+{"version":3,"file":"payments_provider.d.ts","sourceRoot":"","sources":["../../providers/payments_provider.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAE,kBAAkB,EAAqB,MAAM,sBAAsB,CAAC;AAElF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAQpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,sCAAsC,CAAC;AAczE,OAAO,EAAE,eAAe,EAAkB,MAAM,4BAA4B,CAAC;AAa7E;;;;;GAKG;AACH,MAAM,CAAC,OAAO,OAAO,gBAAgB;;IAKvB,SAAS,CAAC,GAAG,EAAE,kBAAkB;gBAAvB,GAAG,EAAE,kBAAkB;IAE7C,QAAQ;IA2BF,IAAI;IA6BV;;;;;;;;;;;;;OAaG;IACG,KAAK;IAKX,0EAA0E;IACpE,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAgLhC;AAED;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CACzC,GAAG,EAAE,WAAW,EAChB,IAAI,EAAE;IACJ,OAAO,EAAE,eAAe,CAAC;IACzB,UAAU,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAC;IAC3C,kFAAkF;IAClF,KAAK,CAAC,EAAE,IAAI,CAAC,YAAY,EAAE,kBAAkB,CAAC,GAAG,SAAS,CAAC;CAC5D,GACA,OAAO,CAAC,OAAO,CAAC,CAqGlB"}

package/dist/providers/payments_provider.js

@@ -1,11 +1,16 @@
 import { pathToFileURL } from 'node:url';
+import { AUDIT_ACTIONS } from '../src/billing/billing_store.js';
 import { LucidBillingStore } from '../src/billing/lucid_billing_store.js';
+import { assertRoleIsDispatchable, resolveDispatchMode, resolveRole, } from '../src/billing/resolve_dispatch.js';
+import { isInjectableAsLucid, resolveBillingStore } from '../src/billing/resolve_store.js';
 import { WebhookDispatcher } from '../src/billing/webhook_dispatcher.js';
 import { WebhookProcessor } from '../src/billing/webhook_processor.js';
+import { newPaymentsTraceId, publishWebhookVerification, runWithPaymentsTrace, webhookVerificationOutcome, } from '../src/diagnostics.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';
+import { setBillingStore, setPayments, setWebhookDispatcher } from '../src/services/main.js';
+import { assertWebhookHandlerTypes, discoverWebhookHandlers, loadWebhookHandlersFromBarrel, resolveWebhookHandler, } from '../src/webhook_handlers.js';
+import { assertWebhookVerification } from '../src/webhook_security.js';
 /**
  * Wires `@adonis-agora/payments` into the AdonisJS application: binds a singleton
  * {@link PaymentsManager} built from `config/payments.ts`, wires the optional Lucid
@@ -15,6 +20,8 @@ import { discoverWebhookHandlers, loadWebhookHandlersFromBarrel, resolveWebhookH
 export default class PaymentsProvider {
     app;
     #webhook;
+    /** Held for the webhook route: a REFUSED delivery is filed here, having no ledger row. */
+    #store;
     constructor(app) {
         this.app = app;
     }
@@ -40,6 +47,8 @@ export default class PaymentsProvider {
             return manager;
         });
     }
+    /** Kept so `shutdown()` can release the channel claims it took. */
+    #telescopeWatcher;
     async boot() {
         await this.app.booted(async () => {
             const config = this.app.config.get('payments', {});
@@ -50,25 +59,108 @@ export default class PaymentsProvider {
             }
             // 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);
+            const manager = await this.app.container.make(PaymentsManager);
+            // Before the route goes up, not after: a driver with an empty webhook-credential slot
+            // verifies nothing, and the route it would be mounted behind is reachable from the
+            // public internet. Fail closed at boot, the way the dashboard does on a missing session
+            // secret.
+            assertWebhookVerification(manager.drivers, {
+                ...(config.allowUnverifiedWebhooks !== undefined
+                    ? { allowUnverifiedWebhooks: config.allowUnverifiedWebhooks }
+                    : {}),
+            });
+            // A 'worker' process consumes what the api half enqueued; it must not also
+            // advertise an endpoint gateways could deliver to.
+            if (resolveRole(config) !== 'worker') {
+                const router = await this.app.container.make('router');
+                this.#registerWebhookRoute(router);
+            }
         });
     }
+    /**
+     * Wire the typed `payments` Telescope watcher, if telescope is in this app and nobody has
+     * already wired one.
+     *
+     * In `ready()`, not `boot()`, and that is the load-bearing part: `start/` files run before
+     * `ready`, so an app that registers its own `PaymentsWatcher` — the way the docs used to
+     * say to — has already claimed the payments channels by the time this looks, and this
+     * stands down. Doing it in `boot()` would race that and record every payment event twice
+     * for exactly the apps that followed the instructions.
+     *
+     * There is no config option. Every one that was drafted described something the code can
+     * detect: the claims registry answers "I wire my own", and a failed import answers "I do
+     * not use telescope".
+     */
+    async ready() {
+        const { registerPaymentsWatcher } = await import('../src/telescope/register.js');
+        this.#telescopeWatcher = await registerPaymentsWatcher(this.app);
+    }
+    /** Release the watcher's channel claims and subscriptions on shutdown. */
+    async shutdown() {
+        this.#telescopeWatcher?.dispose();
+        this.#telescopeWatcher = undefined;
+    }
     async #buildBillingLayer(config) {
-        const store = new LucidBillingStore();
-        const handlers = await this.#resolveAllHandlers(config.billing?.handlers);
+        const mode = resolveDispatchMode(config);
+        const role = resolveRole(config);
+        assertRoleIsDispatchable(role, mode);
+        const store = await this.#resolveBillingStore(config);
+        this.#store = store;
+        let handlers;
+        if (role === 'api') {
+            // The handlers run on the worker, so resolving them here would scan the folder and
+            // build services this process never calls. The TYPES are still checked, from config
+            // alone: a misspelled key is a config error on both halves of the deployment, and the
+            // api process is usually the one a developer boots first.
+            assertWebhookHandlerTypes(Object.keys(config.billing?.handlers ?? {}).map((type) => ({
+                type,
+                source: 'billing.handlers',
+            })), {
+                ...(config.billing?.passthroughEvents !== undefined
+                    ? { passthroughEvents: config.billing.passthroughEvents }
+                    : {}),
+            });
+        }
+        else {
+            handlers = await this.#resolveAllHandlers(config.billing?.handlers, config.billing?.passthroughEvents);
+        }
         const processor = new WebhookProcessor({
             store,
             ...(handlers !== undefined ? { handlers } : {}),
         });
-        this.#webhook = new WebhookDispatcher({
+        const dispatcher = new WebhookDispatcher({
             processor,
-            mode: this.#resolveMode(config),
+            mode,
             // 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(),
+            // The engine itself, not just "is it there": the dispatcher has to REGISTER the
+            // webhook workflow on the app's engine before it can start a run on it.
+            durableEngine: () => this.#resolveDurableEngine(),
         });
+        this.#webhook = dispatcher;
+        // Published so tests can reach it: `flushWebhooks()` from
+        // `@adonis-agora/payments/testing` awaits the in-flight processing that durable mode
+        // deliberately does not await. Bound in the container too, for an app that prefers
+        // `@inject()` over the service accessor.
+        setWebhookDispatcher(dispatcher);
+        this.app.container.singleton(WebhookDispatcher, () => dispatcher);
+    }
+    /**
+     * The billing store from `config.billing.store`, defaulting to Lucid over the
+     * published tables.
+     *
+     * The resolved store is published on `services/main` (which reaches any store) and,
+     * when it is the Lucid one, bound in the container so a service can `@inject()` it
+     * like any other dependency.
+     */
+    async #resolveBillingStore(config) {
+        const store = await resolveBillingStore(config);
+        setBillingStore(store);
+        if (isInjectableAsLucid(store)) {
+            this.app.container.singleton(LucidBillingStore, () => store);
+        }
+        return store;
     }
     /**
      * Merge webhook handlers from the two sources:
@@ -76,15 +168,33 @@ export default class PaymentsProvider {
      * 2. the conventions folder `app/payment_handlers/` (build-time barrel, runtime scan
      *    as fallback) — the durable-style discovery.
      */
-    async #resolveAllHandlers(configHandlers) {
+    async #resolveAllHandlers(configHandlers, passthroughEvents) {
+        const discovered = await this.#discoverFolderHandlers();
+        // Validated BEFORE anything is wired, so the app never boots half-registered. A handler
+        // for an event type that will never be delivered is a silent no-op — the ledger records
+        // the delivery as processed and the grant simply never happens — and two handlers for
+        // one type mean the second overwrote the first in the map below.
+        const registrations = [
+            ...Object.keys(configHandlers ?? {}).map((type) => ({
+                type,
+                source: 'billing.handlers',
+            })),
+            ...discovered.map((entry) => ({
+                type: entry.type,
+                source: entry.source ?? 'app/payment_handlers',
+            })),
+        ];
+        assertWebhookHandlerTypes(registrations, {
+            ...(passthroughEvents !== undefined ? { passthroughEvents } : {}),
+        });
         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);
+        for (const entry of discovered) {
+            handlers[entry.type] = await resolveWebhookHandler(entry.entry, this.app.container);
         }
         return Object.keys(handlers).length > 0 ? handlers : undefined;
     }
@@ -113,43 +223,147 @@ export default class PaymentsProvider {
     /** 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);
+            await this.#resolveDurableEngine();
             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';
+    /**
+     * The app's durable engine, from the container.
+     *
+     * Deliberately the app's own instance and never a fresh one: the engine is bound to the
+     * store and transport the app configured, and a second engine would persist runs that
+     * nothing picks up.
+     */
+    async #resolveDurableEngine() {
+        const { WorkflowEngine } = await import('@adonis-agora/durable');
+        return (await this.app.container.make(WorkflowEngine));
     }
+    /** Map `billing.durable` (`'auto' | boolean`) onto the dispatcher's mode. */
     #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 });
-            }
+            return handleWebhookDelivery(ctx, {
+                manager,
+                dispatcher: this.#webhook,
+                ...(this.#store !== undefined ? { store: this.#store } : {}),
+            });
         })
             .as('payments.webhook');
     }
 }
+/**
+ * One webhook delivery, from raw body to HTTP status — the body of the mounted
+ * `POST /payments/webhook/:provider` route.
+ *
+ * Exported so the delivery can be tested for what it actually promises the gateway (the
+ * status code IS the retry instruction) without standing up an application, a router and a
+ * container around it.
+ */
+export async function handleWebhookDelivery(ctx, deps) {
+    const provider = String(ctx.params.provider);
+    // ONE trace per delivery ATTEMPT, shared by every event the delivery carries — not one
+    // trace per event.
+    //
+    // The trace answers "what happened to this HTTP request", and the facts it correlates are
+    // request-scoped: the body that arrived, the signature check over it, the response the
+    // gateway got. Minting a trace per event would leave the single `webhook.verification`
+    // report attached to one arbitrary event and orphan the rest, and it would erase the one
+    // thing a batch makes worth knowing — that these four events arrived together, so a
+    // failure that hit all four is one delivery's problem and not four payments' problem.
+    //
+    // Per-event identity is not lost by sharing: `webhook.received`/`processed`/`failed` each
+    // carry the event's own `id` and `type`, and the processor publishes them once per event.
+    // So a delivery of four events is four lifecycle triples under one traceId, which is
+    // exactly what happened — never one event's worth of noise.
+    //
+    // (A redelivery gets its own id, which is what you want when the question is "why did the
+    // retry behave differently".)
+    const frame = { traceId: newPaymentsTraceId(), provider };
+    return runWithPaymentsTrace(frame, async () => {
+        const startedAt = Date.now();
+        // The catch below also sees failures from parsing, which happen before the delivery was
+        // authenticated — one delivery must not report two outcomes.
+        let verificationPublished = false;
+        try {
+            const driver = deps.manager.driver(provider);
+            const rawBody = ctx.request.raw() ?? '';
+            // Awaited: `parseWebhook` may be async. A gateway whose callback carries only an
+            // id (Mollie) has to fetch the payment to know what happened, and that fetch is
+            // also the only thing authenticating the call.
+            //
+            // May be ONE event or SEVERAL: Adyen's `notificationItems` and Efí's `pix` are both
+            // lists. `dispatchAll` takes either, so no driver is forced to wrap its single event
+            // in an array.
+            const parsed = await driver.parseWebhook(rawBody, ctx.request.headers());
+            // Reported by the shared `webhook_security` helpers during parseWebhook. No
+            // report means nothing verified through them: the driver used its own SDK, or
+            // it has no webhook credential configured and skipped the check entirely.
+            publishWebhookVerification({
+                provider,
+                ...webhookVerificationOutcome(frame),
+                durationMs: Date.now() - startedAt,
+            });
+            verificationPublished = true;
+            if (deps.dispatcher) {
+                const result = await deps.dispatcher.dispatchAll(parsed);
+                if (result.failures.length > 0) {
+                    // A 2xx tells the gateway "done, never send this again". Answering it over an
+                    // event that failed is how a payment is lost for good — Adyen queues a failed
+                    // delivery for up to 30 days of retries and Efí makes 9 attempts, and both of
+                    // those only ever start if the response is not a 2xx. So a delivery with ANY
+                    // failed event is a failed delivery.
+                    //
+                    // The events that DID succeed are not re-run by that redelivery: their ledger
+                    // rows are `processed`, so the claim answers `null` and they skip. The gateway
+                    // resending all four costs one redelivery and re-runs exactly the one that failed.
+                    const failed = result.failures.map((failure) => failure.event.id);
+                    return ctx.response.status(500).json({
+                        received: true,
+                        // What the delivery actually did, rather than a bare error — an operator reading
+                        // the gateway's failed-delivery log needs to know the other three landed.
+                        processed: result.dispatched,
+                        failed,
+                        error: result.failures[0]?.error.message ?? 'webhook processing failed',
+                    });
+                }
+            }
+            return ctx.response.status(200).json({ received: true });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'invalid webhook';
+            // A throw out of `parseWebhook` is a REJECTED delivery — a bad signature, an
+            // unparsable body, an unknown provider — and the reason is the single most-wanted
+            // fact when a gateway reports failing callbacks. It stays a 400: unlike a processing
+            // failure, redelivering it would fail identically, and a forged batch must not be
+            // answered with an invitation to send it again.
+            if (!verificationPublished) {
+                publishWebhookVerification({
+                    provider,
+                    ...webhookVerificationOutcome(frame, message),
+                    durationMs: Date.now() - startedAt,
+                });
+            }
+            // A rejected delivery is the ONLY webhook outcome that leaves no ledger row — it is
+            // refused before an event exists to record. That is why a rotated webhook token looks
+            // exactly like a quiet gateway from the inside: zero events, zero failures, every
+            // health check green. The audit row is what the `rejected_deliveries` check counts.
+            //
+            // Best-effort on purpose: the delivery is already being refused, and failing to file
+            // the note must not change the status the gateway sees. The store itself returns
+            // `null` when the install predates the table.
+            await deps.store
+                ?.recordAuditEvent({
+                action: AUDIT_ACTIONS.webhookRejected,
+                provider,
+                message,
+            })
+                .catch(() => { });
+            return ctx.response.status(400).json({ error: message });
+        }
+    });
+}
 //# sourceMappingURL=payments_provider.js.map

package/dist/providers/payments_provider.js.map

@@ -1 +1 @@
-{"version":3,"file":"payments_provider.js","sourceRoot":"","sources":["../../providers/payments_provider.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"payments_provider.js","sourceRoot":"","sources":["../../providers/payments_provider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAGzC,OAAO,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAEhE,OAAO,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAC;AAC1E,OAAO,EACL,wBAAwB,EACxB,mBAAmB,EACnB,WAAW,GACZ,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AAC3F,OAAO,EAAE,iBAAiB,EAAE,MAAM,sCAAsC,CAAC;AAGzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,qCAAqC,CAAC;AAGvE,OAAO,EAEL,kBAAkB,EAClB,0BAA0B,EAC1B,oBAAoB,EACpB,0BAA0B,GAC3B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,mCAAmC,CAAC;AAC5F,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC7E,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAC7F,OAAO,EAIL,yBAAyB,EACzB,uBAAuB,EACvB,6BAA6B,EAC7B,qBAAqB,GACtB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AAEvE;;;;;GAKG;AACH,MAAM,CAAC,OAAO,OAAO,gBAAgB;IAKb;IAJtB,QAAQ,CAAgC;IACxC,0FAA0F;IAC1F,MAAM,CAA2B;IAEjC,YAAsB,GAAuB;QAAvB,QAAG,GAAH,GAAG,CAAoB;IAAG,CAAC;IAEjD,QAAQ;QACN,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAiB,UAAU,EAAE,EAAE,CAAC,CAAC;QAEnE,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,SAAS,CAAC,eAAe,EAAE,KAAK,IAAI,EAAE;YACvD,8EAA8E;YAC9E,0EAA0E;YAC1E,IAAI,QAAoC,CAAC;YACzC,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;gBACnB,MAAM,SAAS,GAAG,MAAM,uBAAuB,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;gBAChE,QAAQ,GAAG,IAAI,cAAc,CAAC,SAAS,CAAC,CAAC;YAC3C,CAAC;YACD,MAAM,OAAO,GAAG,MAAM,cAAc,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;YACvD,MAAM,OAAO,GAAG,IAAI,eAAe,CAAC;gBAClC,OAAO;gBACP,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC/C,GAAG,CAAC,MAAM,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACpE,GAAG,CAAC,MAAM,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACzE,CAAC,CAAC;YACH,mFAAmF;YACnF,WAAW,CAAC,OAAO,CAAC,CAAC;YACrB,OAAO,OAAO,CAAC;QACjB,CAAC,CAAC,CAAC;IACL,CAAC;IAED,mEAAmE;IACnE,iBAAiB,CAAkC;IAEnD,KAAK,CAAC,IAAI;QACR,MAAM,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE;YAC/B,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAiB,UAAU,EAAE,EAAE,CAAC,CAAC;YACnE,2EAA2E;YAC3E,8EAA8E;YAC9E,IAAI,MAAM,CAAC,OAAO,EAAE,OAAO,KAAK,KAAK,EAAE,CAAC;gBACtC,MAAM,IAAI,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC;YACxC,CAAC;YACD,+EAA+E;YAC/E,2EAA2E;YAC3E,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;YAC/D,sFAAsF;YACtF,mFAAmF;YACnF,wFAAwF;YACxF,UAAU;YACV,yBAAyB,CAAC,OAAO,CAAC,OAAO,EAAE;gBACzC,GAAG,CAAC,MAAM,CAAC,uBAAuB,KAAK,SAAS;oBAC9C,CAAC,CAAC,EAAE,uBAAuB,EAAE,MAAM,CAAC,uBAAuB,EAAE;oBAC7D,CAAC,CAAC,EAAE,CAAC;aACR,CAAC,CAAC;YACH,2EAA2E;YAC3E,mDAAmD;YACnD,IAAI,WAAW,CAAC,MAAM,CAAC,KAAK,QAAQ,EAAE,CAAC;gBACrC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;gBACvD,IAAI,CAAC,qBAAqB,CAAC,MAAM,CAAC,CAAC;YACrC,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,KAAK;QACT,MAAM,EAAE,uBAAuB,EAAE,GAAG,MAAM,MAAM,CAAC,8BAA8B,CAAC,CAAC;QACjF,IAAI,CAAC,iBAAiB,GAAG,MAAM,uBAAuB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACnE,CAAC;IAED,0EAA0E;IAC1E,KAAK,CAAC,QAAQ;QACZ,IAAI,CAAC,iBAAiB,EAAE,OAAO,EAAE,CAAC;QAClC,IAAI,CAAC,iBAAiB,GAAG,SAAS,CAAC;IACrC,CAAC;IAED,KAAK,CAAC,kBAAkB,CAAC,MAAsB;QAC7C,MAAM,IAAI,GAAG,mBAAmB,CAAC,MAAM,CAAC,CAAC;QACzC,MAAM,IAAI,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;QACjC,wBAAwB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAErC,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,oBAAoB,CAAC,MAAM,CAAC,CAAC;QACtD,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;QACpB,IAAI,QAAoD,CAAC;QACzD,IAAI,IAAI,KAAK,KAAK,EAAE,CAAC;YACnB,mFAAmF;YACnF,oFAAoF;YACpF,sFAAsF;YACtF,0DAA0D;YAC1D,yBAAyB,CACvB,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,QAAQ,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;gBACzD,IAAI;gBACJ,MAAM,EAAE,kBAAkB;aAC3B,CAAC,CAAC,EACH;gBACE,GAAG,CAAC,MAAM,CAAC,OAAO,EAAE,iBAAiB,KAAK,SAAS;oBACjD,CAAC,CAAC,EAAE,iBAAiB,EAAE,MAAM,CAAC,OAAO,CAAC,iBAAiB,EAAE;oBACzD,CAAC,CAAC,EAAE,CAAC;aACR,CACF,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,QAAQ,GAAG,MAAM,IAAI,CAAC,mBAAmB,CACvC,MAAM,CAAC,OAAO,EAAE,QAAQ,EACxB,MAAM,CAAC,OAAO,EAAE,iBAAiB,CAClC,CAAC;QACJ,CAAC;QACD,MAAM,SAAS,GAAG,IAAI,gBAAgB,CAAC;YACrC,KAAK;YACL,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAChD,CAAC,CAAC;QACH,MAAM,UAAU,GAAG,IAAI,iBAAiB,CAAC;YACvC,SAAS;YACT,IAAI;YACJ,2EAA2E;YAC3E,oEAAoE;YACpE,gBAAgB,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,mBAAmB,EAAE;YAClD,gFAAgF;YAChF,wEAAwE;YACxE,aAAa,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,qBAAqB,EAAE;SAClD,CAAC,CAAC;QACH,IAAI,CAAC,QAAQ,GAAG,UAAU,CAAC;QAC3B,0DAA0D;QAC1D,qFAAqF;QACrF,mFAAmF;QACnF,yCAAyC;QACzC,oBAAoB,CAAC,UAAU,CAAC,CAAC;QACjC,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,SAAS,CAAC,iBAAiB,EAAE,GAAG,EAAE,CAAC,UAAU,CAAC,CAAC;IACpE,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,oBAAoB,CAAC,MAAsB;QAC/C,MAAM,KAAK,GAAG,MAAM,mBAAmB,CAAC,MAAM,CAAC,CAAC;QAEhD,eAAe,CAAC,KAAK,CAAC,CAAC;QACvB,IAAI,mBAAmB,CAAC,KAAK,CAAC,EAAE,CAAC;YAC/B,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,SAAS,CAAC,iBAAiB,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC;QAC/D,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,mBAAmB,CACvB,cAA2C,EAC3C,iBAAgD;QAEhD,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,uBAAuB,EAAE,CAAC;QACxD,wFAAwF;QACxF,wFAAwF;QACxF,sFAAsF;QACtF,iEAAiE;QACjE,MAAM,aAAa,GAAiC;YAClD,GAAG,MAAM,CAAC,IAAI,CAAC,cAAc,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;gBAClD,IAAI;gBACJ,MAAM,EAAE,kBAAkB;aAC3B,CAAC,CAAC;YACH,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;gBAC5B,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,sBAAsB;aAC/C,CAAC,CAAC;SACJ,CAAC;QACF,yBAAyB,CAAC,aAAa,EAAE;YACvC,GAAG,CAAC,iBAAiB,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,iBAAiB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAClE,CAAC,CAAC;QAEH,MAAM,QAAQ,GAAmC,EAAE,CAAC;QACpD,IAAI,cAAc,EAAE,CAAC;YACnB,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,cAAc,CAAC,EAAE,CAAC;gBAC3D,QAAQ,CAAC,IAAI,CAAC,GAAG,MAAM,qBAAqB,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YAC1E,CAAC;QACH,CAAC;QACD,KAAK,MAAM,KAAK,IAAI,UAAU,EAAE,CAAC;YAC/B,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,MAAM,qBAAqB,CAAC,KAAK,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACtF,CAAC;QACD,OAAO,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;IACjE,CAAC;IAED,0FAA0F;IAC1F,KAAK,CAAC,uBAAuB;QAC3B,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,oBAAoB,EAAE,CAAC;QACjD,IAAI,MAAM;YAAE,OAAO,6BAA6B,CAAC,MAAM,CAAC,CAAC;QACzD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,sBAAsB,CAAC,CAAC;QACtD,OAAO,uBAAuB,CAAC,GAAG,CAAC,CAAC;IACtC,CAAC;IAED,0FAA0F;IAC1F,KAAK,CAAC,oBAAoB;QACxB,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,wCAAwC,CAAC,CAAC;QACzE,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,CAAC,MAAM,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAElD,CAAC;YACF,OAAO,GAAG,CAAC,eAAe,IAAI,IAAI,CAAC;QACrC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,GAAI,GAA6B,CAAC,IAAI,CAAC;YACjD,IAAI,IAAI,KAAK,sBAAsB,IAAI,IAAI,KAAK,QAAQ;gBAAE,OAAO,IAAI,CAAC;YACtE,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC;IAED,gEAAgE;IAChE,KAAK,CAAC,mBAAmB;QACvB,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,qBAAqB,EAAE,CAAC;YACnC,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,qBAAqB;QACzB,MAAM,EAAE,cAAc,EAAE,GAAG,MAAM,MAAM,CAAC,uBAAuB,CAAC,CAAC;QACjE,OAAO,CAAC,MAAM,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,cAAc,CAAC,CAAiC,CAAC;IACzF,CAAC;IAED,6EAA6E;IAE7E,qBAAqB,CAAC,MAAyB;QAC7C,MAAM;aACH,IAAI,CAAC,6BAA6B,EAAE,KAAK,EAAE,GAAgB,EAAE,EAAE;YAC9D,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;YAC/D,OAAO,qBAAqB,CAAC,GAAG,EAAE;gBAChC,OAAO;gBACP,UAAU,EAAE,IAAI,CAAC,QAAQ;gBACzB,GAAG,CAAC,IAAI,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC7D,CAAC,CAAC;QACL,CAAC,CAAC;aACD,EAAE,CAAC,kBAAkB,CAAC,CAAC;IAC5B,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,GAAgB,EAChB,IAKC;IAED,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC7C,uFAAuF;IACvF,mBAAmB;IACnB,EAAE;IACF,0FAA0F;IAC1F,uFAAuF;IACvF,uFAAuF;IACvF,yFAAyF;IACzF,oFAAoF;IACpF,sFAAsF;IACtF,EAAE;IACF,0FAA0F;IAC1F,0FAA0F;IAC1F,qFAAqF;IACrF,4DAA4D;IAC5D,EAAE;IACF,0FAA0F;IAC1F,8BAA8B;IAC9B,MAAM,KAAK,GAAuB,EAAE,OAAO,EAAE,kBAAkB,EAAE,EAAE,QAAQ,EAAE,CAAC;IAC9E,OAAO,oBAAoB,CAAC,KAAK,EAAE,KAAK,IAAI,EAAE;QAC5C,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC7B,wFAAwF;QACxF,6DAA6D;QAC7D,IAAI,qBAAqB,GAAG,KAAK,CAAC;QAClC,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YAC7C,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC;YACxC,iFAAiF;YACjF,gFAAgF;YAChF,+CAA+C;YAC/C,EAAE;YACF,oFAAoF;YACpF,qFAAqF;YACrF,eAAe;YACf,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,YAAY,CAAC,OAAO,EAAE,GAAG,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;YACzE,4EAA4E;YAC5E,8EAA8E;YAC9E,0EAA0E;YAC1E,0BAA0B,CAAC;gBACzB,QAAQ;gBACR,GAAG,0BAA0B,CAAC,KAAK,CAAC;gBACpC,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;aACnC,CAAC,CAAC;YACH,qBAAqB,GAAG,IAAI,CAAC;YAC7B,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;gBACpB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;gBACzD,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBAC/B,8EAA8E;oBAC9E,8EAA8E;oBAC9E,8EAA8E;oBAC9E,6EAA6E;oBAC7E,qCAAqC;oBACrC,EAAE;oBACF,8EAA8E;oBAC9E,+EAA+E;oBAC/E,mFAAmF;oBACnF,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;oBAClE,OAAO,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;wBACnC,QAAQ,EAAE,IAAI;wBACd,iFAAiF;wBACjF,0EAA0E;wBAC1E,SAAS,EAAE,MAAM,CAAC,UAAU;wBAC5B,MAAM;wBACN,KAAK,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,OAAO,IAAI,2BAA2B;qBACxE,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;YACD,OAAO,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;QAC3D,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,iBAAiB,CAAC;YAC3E,6EAA6E;YAC7E,kFAAkF;YAClF,qFAAqF;YACrF,kFAAkF;YAClF,gDAAgD;YAChD,IAAI,CAAC,qBAAqB,EAAE,CAAC;gBAC3B,0BAA0B,CAAC;oBACzB,QAAQ;oBACR,GAAG,0BAA0B,CAAC,KAAK,EAAE,OAAO,CAAC;oBAC7C,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;iBACnC,CAAC,CAAC;YACL,CAAC;YACD,oFAAoF;YACpF,sFAAsF;YACtF,kFAAkF;YAClF,oFAAoF;YACpF,EAAE;YACF,qFAAqF;YACrF,iFAAiF;YACjF,8CAA8C;YAC9C,MAAM,IAAI,CAAC,KAAK;gBACd,EAAE,gBAAgB,CAAC;gBACjB,MAAM,EAAE,aAAa,CAAC,eAAe;gBACrC,QAAQ;gBACR,OAAO;aACR,CAAC;iBACD,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;YACnB,OAAO,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC;QAC3D,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC"}

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

@@ -0,0 +1,85 @@
+import { type BillingStore, type DisputeListItem, type WebhookEventBreakdownLine } from './billing_store.js';
+export interface BillingHealthOptions {
+    /** Milliseconds an event may sit in `received` before it counts as stuck. Default 15 min. */
+    stuckAfter?: number;
+    /** Milliseconds a `pending` payment may age before it counts as unconfirmed. Default 2 h. */
+    unconfirmedAfter?: number;
+    /** The window `failed` events are counted over. Default 24 h. */
+    failedWithin?: number;
+    /**
+     * How far ahead to look for a dispute whose evidence window is about to close. Default 72 h.
+     *
+     * In milliseconds like every other threshold here, though the store's read takes hours —
+     * the conversion happens once, at the call.
+     */
+    disputeDueWithin?: number;
+    /** The window rejected deliveries are counted over. Default 24 h. */
+    rejectedWithin?: number;
+    /** Overridable clock — the tests pass a fixed instant. Defaults to now. */
+    now?: Date;
+}
+export interface BillingHealthCheck {
+    key: 'stuck_webhooks' | 'failed_webhooks' | 'unconfirmed_payments' | 'disputes_due' | 'open_disputes' | 'rejected_deliveries';
+    label: string;
+    count: number;
+    /** `true` when `count` is zero — every check here is a "should be nothing" check. */
+    healthy: boolean;
+    /** What a non-zero count means, and what to do about it. */
+    hint: string;
+}
+export interface BillingHealth {
+    /** `false` when any check is non-zero — the exit code `payments:health` returns. */
+    healthy: boolean;
+    checkedAt: Date;
+    checks: BillingHealthCheck[];
+    /** Which provider/event pairs make up `failed_webhooks`, worst first. */
+    failures: WebhookEventBreakdownLine[];
+    /**
+     * The disputes behind `disputes_due`, soonest deadline first — WHICH windows are closing,
+     * not just how many. Capped at {@link DISPUTE_DEADLINE_SAMPLE}; `disputes_due.count` is the
+     * full number, so a report can name twenty and still say there are fifty.
+     */
+    deadlines: DisputeListItem[];
+    /**
+     * The disputes behind `open_disputes`, OLDEST first — the ones nobody has answered, whether or
+     * not a deadline was ever published for them. Capped at {@link OPEN_DISPUTE_SAMPLE}.
+     *
+     * Overlaps `deadlines` on purpose: a dispute that has both a deadline and no answer belongs in
+     * both lists, and suppressing it from one of them to keep them disjoint would make the
+     * deadline-free check quietly incomplete on exactly the install it exists for.
+     */
+    openDisputes: DisputeListItem[];
+}
+/**
+ * The six operational questions about a billing install that nothing else answers, asked
+ * through the store instead of by hand against the tables.
+ *
+ * Each is a silent failure — the kind where the endpoint keeps returning `200` and revenue
+ * quietly stops landing:
+ *
+ * - **Stuck events**: claimed in the ledger, never finished. Almost always the worker the
+ *   dispatcher depends on (`durable:work` / `queue:listen`) is not running.
+ * - **Failed events**: the handler threw and retries were exhausted, so the effect that
+ *   event described — the grant, the activation — never happened.
+ * - **Unconfirmed charges**: created and never confirmed. This is what a webhook endpoint
+ *   that stopped being reachable looks like from the inside, and nothing errors.
+ * - **Closing dispute windows**: an open chargeback whose evidence deadline is inside the
+ *   next three days. This is the only check here that alerts on a CLOCK rather than on a
+ *   failure — nothing is broken, and the money is lost anyway if the window closes
+ *   unanswered, by default rather than on the merits.
+ * - **Open disputes**: the same money, without the clock. `disputes_due` can only ever see a
+ *   dispute whose gateway PUBLISHED a deadline, and most do not — Asaas' comes from
+ *   `chargeback.deadlineToSendDisputeDocuments`, which no published webhook example contains.
+ *   On such an install the deadline check is zero forever while a chargeback sits open with the
+ *   money already pulled back, and the report says healthy. This one asks the question the
+ *   deadline cannot.
+ * - **Rejected deliveries**: gateway calls the endpoint REFUSED — a bad signature, an unparsable
+ *   body, a provider nobody configured. They never become ledger rows, so a rotated webhook
+ *   token used to look exactly like a quiet week: zero events, zero failures, every check green.
+ *   `unconfirmed_payments` eventually notices, but only for charges the app itself created;
+ *   refunds, chargebacks and dispute closures produce no pending payment and simply vanish.
+ *
+ * Pure store reads, no gateway calls — safe to run on a schedule and to alert on.
+ */
+export declare function billingHealth(store: BillingStore, options?: BillingHealthOptions): Promise<BillingHealth>;
+//# sourceMappingURL=billing_health.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"billing_health.d.ts","sourceRoot":"","sources":["../../../src/billing/billing_health.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,yBAAyB,EAC/B,MAAM,oBAAoB,CAAC;AAkC5B,MAAM,WAAW,oBAAoB;IACnC,6FAA6F;IAC7F,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6FAA6F;IAC7F,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iEAAiE;IACjE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,qEAAqE;IACrE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,2EAA2E;IAC3E,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED,MAAM,WAAW,kBAAkB;IACjC,GAAG,EACC,gBAAgB,GAChB,iBAAiB,GACjB,sBAAsB,GACtB,cAAc,GACd,eAAe,GACf,qBAAqB,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,qFAAqF;IACrF,OAAO,EAAE,OAAO,CAAC;IACjB,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,aAAa;IAC5B,oFAAoF;IACpF,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,IAAI,CAAC;IAChB,MAAM,EAAE,kBAAkB,EAAE,CAAC;IAC7B,yEAAyE;IACzE,QAAQ,EAAE,yBAAyB,EAAE,CAAC;IACtC;;;;OAIG;IACH,SAAS,EAAE,eAAe,EAAE,CAAC;IAC7B;;;;;;;OAOG;IACH,YAAY,EAAE,eAAe,EAAE,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,YAAY,EACnB,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,aAAa,CAAC,CA6FxB"}