@adonis-agora/payments 0.2.0 → 0.3.0

package/dist/providers/dashboard_provider.d.ts

@@ -0,0 +1,97 @@
+import type { ApplicationService } from '@adonisjs/core/types';
+/**
+ * Mounts the payments dashboard into an AdonisJS app: the `@adonis-agora/payments-dashboard` React
+ * SPA plus a JSON API over the resolved {@link BillingStore}, served under a configurable path.
+ *
+ * Reads never touch a gateway. The two ACTIONS do — a refund calls the driver that took the
+ * payment, and a retry re-runs a failed webhook event through the app's own handlers — so both are
+ * `POST` (a refund reachable by URL is a refund a crawler can trigger) and both go through the same
+ * {@link enforce} guard as every read.
+ *
+ * Routes (relative to the configured `path`, default `/payments`):
+ * - `GET  /`                     -> the dashboard SPA's `index.html`
+ * - `GET  /assets/:file`         -> the SPA's hashed JS/CSS bundle
+ * - `GET  /api/health`           -> `billingHealth()` — what needs attention today
+ * - `GET  /api/overview`         -> `billingOverview()` metrics for a period
+ * - `GET  /api/payments`         -> a page of `billing_payments` (status/provider filters, plus
+ *                                   `?reference=` / `?gatewayId=` / `?customerId=` lookups)
+ * - `GET  /api/payments/:gatewayId` -> one payment: current state, owner, disputes, the ledger
+ *                                   rows naming it, and who refunded it
+ * - `GET  /api/customers`        -> a page of `billing_customers` — the owner mapping that ties
+ *                                   a `cus_…` back to an app user
+ * - `GET  /api/audit`            -> the trail: refunds issued here, disputes resolved here, and
+ *                                   the gateway deliveries this endpoint REFUSED
+ * - `GET  /api/disputes`         -> a page of `billing_disputes`; `?dueWithin=<hours>` for the
+ *                                   open windows closing soonest
+ * - `GET  /api/subscriptions`    -> a page of `billing_subscriptions` (status/provider filters)
+ * - `GET  /api/webhook-events`   -> a page of `billing_webhook_events` (status/provider/type)
+ * - `GET  /api/providers`        -> the gateways and event types this install has data for
+ * - `POST /api/payments/:gatewayId/refund`           -> refund through the payment's own gateway
+ * - `POST /api/disputes/:gatewayId/resolve`          -> record how a dispute ended, and who said so
+ * - `POST /api/webhook-events/:gatewayEventId/retry` -> re-run a failed event's handlers
+ *
+ * Plus, when `dashboardAuth` is configured, `GET|POST <path>/login`, `POST <path>/session` and
+ * `GET <path>/logout`.
+ *
+ * With `enabled: false` this provider registers NOTHING — not the SPA, not the API, not the auth
+ * routes. The dashboard is then completely absent from the app's route table.
+ */
+export default class PaymentsDashboardProvider {
+    protected app: ApplicationService;
+    constructor(app: ApplicationService);
+    /** Warn once so a throwing `login`/`session` hook doesn't spam the logs on every failed attempt. */
+    private warnedOnHookThrow;
+    boot(): Promise<void>;
+    private registerRoutes;
+    /**
+     * The two write actions, built once and reused.
+     *
+     * Both need the app's `PaymentsManager` — the refund needs the driver that took the payment, and
+     * the retry needs that driver to rebuild the normalized event from the stored payload. Neither is
+     * fatal when it is missing: the ports are simply absent and the handlers answer `503` with a
+     * sentence saying so.
+     *
+     * Only a successful build is cached. A failure here usually means "the app has not finished
+     * booting", and caching THAT would disable both buttons for the life of the process.
+     */
+    private actionsCache;
+    private actions;
+    /** Webhook handlers from `config.billing.handlers` plus `app/payment_handlers/` (build-time
+     *  barrel, runtime scan as fallback) — the same two sources the payments provider merges. */
+    private resolveHandlers;
+    private discoverHandlers;
+    /** Mount the React SPA at `config.path` plus its hashed asset bundle. */
+    private registerSpaRoutes;
+    /**
+     * Mount the built-in `dashboardAuth` endpoints under `basePath`. All are public (no guard): they
+     * create/destroy the session the {@link enforce} guard checks for.
+     *
+     * - `GET  <base>/login`   -> the server-rendered login page (Mode B only).
+     * - `POST <base>/login`   -> verifies credentials via the host `login` hook and mints the cookie.
+     * - `POST <base>/session` -> Mode A: verifies the HOST APP's own auth (off the raw request) via
+     *    the `session` hook and mints the cookie. `204` on success, uniform `401` on denial.
+     * - `GET  <base>/logout`  -> clears the cookie and redirects to the login page (Mode B) or the
+     *    dashboard root (Mode A only).
+     */
+    private registerAuthRoutes;
+    private warnHookThrow;
+    /**
+     * Run the guards for a dashboard resource. Composes the `authorize` hook (bearer token/custom)
+     * with the optional `dashboardAuth` session guard — BOTH must pass:
+     *
+     * 1. `authorize` fails -> `403`.
+     * 2. `dashboardAuth` configured AND no valid session -> for a `page` request, redirect `302` to
+     *    the login page (Mode B) carrying a sanitized `returnTo`, or a `401` notice (Mode A only);
+     *    for an `api` request, `401 { error: 'unauthorized', auth: { modes } }`.
+     *
+     * Returns `allowed: false` (and has already written the response) when the request must
+     * short-circuit. On success it also carries WHO passed the gate: the session's user, which
+     * the write handlers record against a refund or a dispute resolution. `undefined` when this
+     * deployment configures no `dashboardAuth` — there is genuinely nobody to name, and inventing
+     * one would be worse than an honest "unattributed".
+     */
+    private enforce;
+    private readSessionCookie;
+    private writeSessionCookie;
+}
+//# sourceMappingURL=dashboard_provider.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dashboard_provider.d.ts","sourceRoot":"","sources":["../../providers/dashboard_provider.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,kBAAkB,EAAqB,MAAM,sBAAsB,CAAC;AAiElF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,CAAC,OAAO,OAAO,yBAAyB;IAChC,SAAS,CAAC,GAAG,EAAE,kBAAkB;gBAAvB,GAAG,EAAE,kBAAkB;IAE7C,oGAAoG;IACpG,OAAO,CAAC,iBAAiB,CAAS;IAE5B,IAAI;IAeV,OAAO,CAAC,cAAc;IA2FtB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,YAAY,CAAwC;YAE9C,OAAO;IAqCrB;iGAC6F;YAC/E,eAAe;YAef,gBAAgB;IAa9B,yEAAyE;IACzE,OAAO,CAAC,iBAAiB;IAgDzB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,kBAAkB;YAwDZ,aAAa;IAQ3B;;;;;;;;;;;;;;OAcG;YACW,OAAO;IA+CrB,OAAO,CAAC,iBAAiB;IAKzB,OAAO,CAAC,kBAAkB;CAU3B"}

package/dist/providers/dashboard_provider.js

@@ -0,0 +1,430 @@
+import { readFile } from 'node:fs/promises';
+import { basename, resolve as resolvePath } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { WebhookProcessor } from '../src/billing/webhook_processor.js';
+import { createRefundAction, createReplayAction } from '../src/dashboard/actions.js';
+import { SESSION_COOKIE_NAME, performLogin, performSession, readSession, } from '../src/dashboard/auth.js';
+import { resolveConfig, } from '../src/dashboard/define_config.js';
+import { auditEvents, customers, disputes, health, overview, paymentDetail, payments, providers, refundPayment, resolveDispute, retryWebhookEvent, subscriptions, webhookEvents, } from '../src/dashboard/handlers.js';
+import { renderLoginPage } from '../src/dashboard/login_page.js';
+import { contentTypeFor, renderIndexHtml } from '../src/dashboard/spa.js';
+import { PaymentsManager } from '../src/payments_manager.js';
+import { getBillingStore } from '../src/services/main.js';
+import { discoverWebhookHandlers, loadWebhookHandlersFromBarrel, resolveWebhookHandler, } from '../src/webhook_handlers.js';
+/**
+ * Directory of the built SPA (`dist/assets/spa`, copied in by `copy:spa` — see `package.json`),
+ * relative to this compiled provider (`dist/providers`). Resolved lazily (not at module scope) for
+ * the same reason `@adonis-agora/durable`'s dashboard provider resolves its SPA directory lazily:
+ * `fileURLToPath` throws on any non-`file:` `import.meta.url`, which would make this provider
+ * unimportable under a test runner that doesn't use real file URLs.
+ *
+ * NOTE this reads BUILT ASSETS FROM DISK. The provider never imports `@adonis-agora/payments-dashboard`
+ * — that package is a devDependency of this one purely so the workspace build orders them.
+ */
+let spaDir;
+function spaDirectory() {
+    spaDir ??= fileURLToPath(new URL('../assets/spa/', import.meta.url));
+    return spaDir;
+}
+/**
+ * Mounts the payments dashboard into an AdonisJS app: the `@adonis-agora/payments-dashboard` React
+ * SPA plus a JSON API over the resolved {@link BillingStore}, served under a configurable path.
+ *
+ * Reads never touch a gateway. The two ACTIONS do — a refund calls the driver that took the
+ * payment, and a retry re-runs a failed webhook event through the app's own handlers — so both are
+ * `POST` (a refund reachable by URL is a refund a crawler can trigger) and both go through the same
+ * {@link enforce} guard as every read.
+ *
+ * Routes (relative to the configured `path`, default `/payments`):
+ * - `GET  /`                     -> the dashboard SPA's `index.html`
+ * - `GET  /assets/:file`         -> the SPA's hashed JS/CSS bundle
+ * - `GET  /api/health`           -> `billingHealth()` — what needs attention today
+ * - `GET  /api/overview`         -> `billingOverview()` metrics for a period
+ * - `GET  /api/payments`         -> a page of `billing_payments` (status/provider filters, plus
+ *                                   `?reference=` / `?gatewayId=` / `?customerId=` lookups)
+ * - `GET  /api/payments/:gatewayId` -> one payment: current state, owner, disputes, the ledger
+ *                                   rows naming it, and who refunded it
+ * - `GET  /api/customers`        -> a page of `billing_customers` — the owner mapping that ties
+ *                                   a `cus_…` back to an app user
+ * - `GET  /api/audit`            -> the trail: refunds issued here, disputes resolved here, and
+ *                                   the gateway deliveries this endpoint REFUSED
+ * - `GET  /api/disputes`         -> a page of `billing_disputes`; `?dueWithin=<hours>` for the
+ *                                   open windows closing soonest
+ * - `GET  /api/subscriptions`    -> a page of `billing_subscriptions` (status/provider filters)
+ * - `GET  /api/webhook-events`   -> a page of `billing_webhook_events` (status/provider/type)
+ * - `GET  /api/providers`        -> the gateways and event types this install has data for
+ * - `POST /api/payments/:gatewayId/refund`           -> refund through the payment's own gateway
+ * - `POST /api/disputes/:gatewayId/resolve`          -> record how a dispute ended, and who said so
+ * - `POST /api/webhook-events/:gatewayEventId/retry` -> re-run a failed event's handlers
+ *
+ * Plus, when `dashboardAuth` is configured, `GET|POST <path>/login`, `POST <path>/session` and
+ * `GET <path>/logout`.
+ *
+ * With `enabled: false` this provider registers NOTHING — not the SPA, not the API, not the auth
+ * routes. The dashboard is then completely absent from the app's route table.
+ */
+export default class PaymentsDashboardProvider {
+    app;
+    constructor(app) {
+        this.app = app;
+    }
+    /** Warn once so a throwing `login`/`session` hook doesn't spam the logs on every failed attempt. */
+    warnedOnHookThrow = false;
+    async boot() {
+        const config = resolveConfig(this.app.config.get('payments_dashboard', {}));
+        if (!config.enabled)
+            return;
+        // Route registration can't happen synchronously in `boot()`: the router singleton isn't
+        // committed until the app's "booted" hooks run, which fire strictly AFTER every provider's
+        // own `boot()`. Same note `@adonis-agora/durable`'s dashboard provider carries.
+        await this.app.booted(async () => {
+            const router = await this.app.container.make('router');
+            this.registerRoutes(router, config);
+        });
+    }
+    registerRoutes(router, config) {
+        const apiBase = `${config.path}/api`;
+        // Built-in `dashboardAuth` (Mode A `session` and/or Mode B `login`, opt-in). Registered ONLY
+        // when configured. These endpoints are public (behind NEITHER guard): they MINT the session
+        // the guard checks for.
+        if (config.dashboardAuth) {
+            this.registerAuthRoutes(router, config, config.dashboardAuth);
+        }
+        this.registerSpaRoutes(router, config, apiBase);
+        const json = (handler, needsActions = false) => {
+            return async (ctx) => {
+                const guard = await this.enforce(config, ctx, 'api');
+                if (!guard.allowed)
+                    return;
+                let store;
+                try {
+                    store = getBillingStore();
+                }
+                catch (error) {
+                    // The billing layer is off (or the app hasn't booted it). That is a deployment state,
+                    // not a bug in the request — say so with a 503 rather than a stack-trace-shaped 500.
+                    return ctx.response.status(503).json({
+                        error: error instanceof Error ? error.message : 'billing store unavailable',
+                    });
+                }
+                try {
+                    const deps = {
+                        store,
+                        currency: config.currency,
+                        // WHO is asking. The guard has already verified a signed session carrying a user;
+                        // passing it through is what lets a refund and a dispute resolution be recorded
+                        // against a person instead of against nobody. Absent when this deployment
+                        // configures no `dashboardAuth` — recorded as "unattributed", never invented.
+                        ...(guard.actor !== undefined ? { actor: guard.actor } : {}),
+                        // Resolved lazily and only for the routes that need it: a console whose payments
+                        // manager is unreachable must still serve every read.
+                        ...(needsActions ? { actions: await this.actions(store) } : {}),
+                    };
+                    const result = await handler(deps, toApiRequest(ctx));
+                    return ctx.response.status(result.status).json(result.body);
+                }
+                catch (error) {
+                    return ctx.response
+                        .status(500)
+                        .json({ error: error instanceof Error ? error.message : 'internal error' });
+                }
+            };
+        };
+        router.get(`${apiBase}/health`, json(health)).as('payments_dashboard.health');
+        router.get(`${apiBase}/overview`, json(overview)).as('payments_dashboard.overview');
+        router.get(`${apiBase}/payments`, json(payments)).as('payments_dashboard.payments');
+        // Registered AFTER the collection route and before the refund `POST`, and the ordering is
+        // only cosmetic here — `/payments` and `/payments/:gatewayId` cannot shadow each other — but
+        // it keeps the read routes reading top-down.
+        router
+            .get(`${apiBase}/payments/:gatewayId`, json(paymentDetail))
+            .as('payments_dashboard.payments.show');
+        router.get(`${apiBase}/customers`, json(customers)).as('payments_dashboard.customers');
+        router.get(`${apiBase}/audit`, json(auditEvents)).as('payments_dashboard.audit');
+        // There is still no "fight" or "accept" route, on purpose: whether to submit evidence or
+        // refund is a business rule that stays in the app's code. The `resolve` POST below is a
+        // different thing — it records an outcome that already happened at the gateway.
+        router.get(`${apiBase}/disputes`, json(disputes)).as('payments_dashboard.disputes');
+        router
+            .get(`${apiBase}/subscriptions`, json(subscriptions))
+            .as('payments_dashboard.subscriptions');
+        router
+            .get(`${apiBase}/webhook-events`, json(webhookEvents))
+            .as('payments_dashboard.webhook_events');
+        router.get(`${apiBase}/providers`, json(providers)).as('payments_dashboard.providers');
+        // The console's only WRITE routes. `POST` is load-bearing, not stylistic: registering either of
+        // these as a `GET` would put "refund this customer" behind a link a prefetcher can follow.
+        router
+            .post(`${apiBase}/payments/:gatewayId/refund`, json(refundPayment, true))
+            .as('payments_dashboard.payments.refund');
+        router
+            .post(`${apiBase}/webhook-events/:gatewayEventId/retry`, json(retryWebhookEvent, true))
+            .as('payments_dashboard.webhook_events.retry');
+        // No `needsActions`: this one calls no gateway. It records how a dispute ENDED — the loop a
+        // gateway that publishes no lost-dispute event never closes on its own — so it stays
+        // available on a deployment whose payments manager is unreachable.
+        router
+            .post(`${apiBase}/disputes/:gatewayId/resolve`, json(resolveDispute))
+            .as('payments_dashboard.disputes.resolve');
+    }
+    /**
+     * The two write actions, built once and reused.
+     *
+     * Both need the app's `PaymentsManager` — the refund needs the driver that took the payment, and
+     * the retry needs that driver to rebuild the normalized event from the stored payload. Neither is
+     * fatal when it is missing: the ports are simply absent and the handlers answer `503` with a
+     * sentence saying so.
+     *
+     * Only a successful build is cached. A failure here usually means "the app has not finished
+     * booting", and caching THAT would disable both buttons for the life of the process.
+     */
+    actionsCache;
+    async actions(store) {
+        if (this.actionsCache)
+            return this.actionsCache;
+        let manager;
+        try {
+            manager = await this.app.container.make(PaymentsManager);
+        }
+        catch {
+            return {};
+        }
+        // The retry re-runs the app's OWN handlers, not just the built-in store sync — a retry that
+        // skipped them would silently do half the job, which is worse than no button. They are
+        // resolved the same way `payments_provider.ts` resolves them (config entries plus the
+        // `app/payment_handlers/` convention).
+        const config = this.app.config.get('payments', {});
+        const handlers = await this.resolveHandlers(config.billing?.handlers);
+        const processor = new WebhookProcessor({
+            store,
+            ...(handlers !== undefined ? { handlers } : {}),
+        });
+        const actions = {
+            refund: createRefundAction((provider) => manager.driver(provider)),
+            replayWebhook: createReplayAction({
+                store,
+                // The event is rebuilt from the ledger's own `payload` + `normalized` columns and run
+                // straight through the processor — no driver, no `parseWebhook`, so no signature to
+                // re-verify from headers nobody kept. That is what makes a Stripe or Adyen row
+                // replayable at all. A row recorded before the `normalized` column existed is reported
+                // to the operator as `422`, ledger row untouched.
+                process: (event) => processor.process(event),
+            }),
+        };
+        this.actionsCache = actions;
+        return actions;
+    }
+    /** Webhook handlers from `config.billing.handlers` plus `app/payment_handlers/` (build-time
+     *  barrel, runtime scan as fallback) — the same two sources the payments provider merges. */
+    async resolveHandlers(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.discoverHandlers()) {
+            handlers[discovered.type] = await resolveWebhookHandler(discovered.entry, this.app.container);
+        }
+        return Object.keys(handlers).length > 0 ? handlers : undefined;
+    }
+    async discoverHandlers() {
+        try {
+            const path = this.app.makePath('.adonisjs/payments/webhook_handlers.js');
+            const mod = (await import(pathToFileURL(path).href));
+            if (mod.webhookHandlers)
+                return loadWebhookHandlersFromBarrel(mod.webhookHandlers);
+        }
+        catch {
+            // No generated barrel — fall through to the runtime scan.
+        }
+        return discoverWebhookHandlers(this.app.makePath('app/payment_handlers'));
+    }
+    /** Mount the React SPA at `config.path` plus its hashed asset bundle. */
+    registerSpaRoutes(router, config, apiBase) {
+        const indexPath = config.path === '' ? '/' : config.path;
+        router
+            .get(indexPath, async (ctx) => {
+            if (!(await this.enforce(config, ctx, 'page')).allowed)
+                return;
+            let html;
+            try {
+                html = await readFile(resolvePath(spaDirectory(), 'index.html'), 'utf8');
+            }
+            catch {
+                return ctx.response
+                    .status(404)
+                    .send('The payments dashboard SPA is not built. Run `pnpm --filter @adonis-agora/payments-dashboard build` (or the package build) to emit dist/spa.');
+            }
+            return ctx.response
+                .header('content-type', 'text/html; charset=utf-8')
+                .header('cache-control', 'no-store, must-revalidate')
+                .send(renderIndexHtml(html, config.path, apiBase, config.currency));
+        })
+            .as('payments_dashboard.index');
+        router
+            .get(`${config.path}/assets/:file`, async (ctx) => {
+            if (!(await this.enforce(config, ctx, 'page')).allowed)
+                return;
+            const file = basename(String(ctx.params.file));
+            const root = resolvePath(spaDirectory(), 'assets');
+            const assetPath = resolvePath(root, file);
+            if (!assetPath.startsWith(root))
+                return ctx.response.status(404).send('');
+            let bytes;
+            try {
+                bytes = await readFile(assetPath);
+            }
+            catch {
+                return ctx.response.status(404).send('');
+            }
+            return ctx.response
+                .header('content-type', contentTypeFor(file))
+                .header('cache-control', 'public, max-age=31536000, immutable')
+                .send(bytes);
+        })
+            .as('payments_dashboard.assets');
+    }
+    /**
+     * Mount the built-in `dashboardAuth` endpoints under `basePath`. All are public (no guard): they
+     * create/destroy the session the {@link enforce} guard checks for.
+     *
+     * - `GET  <base>/login`   -> the server-rendered login page (Mode B only).
+     * - `POST <base>/login`   -> verifies credentials via the host `login` hook and mints the cookie.
+     * - `POST <base>/session` -> Mode A: verifies the HOST APP's own auth (off the raw request) via
+     *    the `session` hook and mints the cookie. `204` on success, uniform `401` on denial.
+     * - `GET  <base>/logout`  -> clears the cookie and redirects to the login page (Mode B) or the
+     *    dashboard root (Mode A only).
+     */
+    registerAuthRoutes(router, config, auth) {
+        const loginPath = `${config.path}/login`;
+        const sessionPath = `${config.path}/session`;
+        const logoutPath = `${config.path}/logout`;
+        if (auth.login) {
+            router
+                .get(loginPath, async (ctx) => {
+                ctx.response.header('content-type', 'text/html; charset=utf-8');
+                ctx.response.header('cache-control', 'no-store, must-revalidate');
+                return ctx.response.send(renderLoginPage(config.path));
+            })
+                .as('payments_dashboard.login.page');
+            router
+                .post(loginPath, async (ctx) => {
+                const outcome = await performLogin(auth, ctx.request.body(), config.path);
+                if (outcome.kind === 'bad-request') {
+                    return ctx.response.status(400).json({ error: outcome.message });
+                }
+                if (outcome.kind === 'unauthorized') {
+                    await this.warnHookThrow(outcome.hookError);
+                    return ctx.response.status(401).json({ error: outcome.message });
+                }
+                this.writeSessionCookie(ctx, auth, outcome.cookieValue);
+                return ctx.response.status(200).json({ redirectTo: outcome.redirectTo });
+            })
+                .as('payments_dashboard.login.submit');
+        }
+        if (auth.session) {
+            router
+                .post(sessionPath, async (ctx) => {
+                const outcome = await performSession(auth, ctx.request.request);
+                if (outcome.kind === 'unauthorized') {
+                    await this.warnHookThrow(outcome.hookError);
+                    return ctx.response.status(401).json({ error: 'unauthorized' });
+                }
+                this.writeSessionCookie(ctx, auth, outcome.cookieValue);
+                return ctx.response.status(204).send('');
+            })
+                .as('payments_dashboard.session.mint');
+        }
+        router
+            .get(logoutPath, async (ctx) => {
+            ctx.response.clearCookie(SESSION_COOKIE_NAME, { path: '/' });
+            return ctx.response.redirect().toPath(auth.login ? loginPath : config.path || '/');
+        })
+            .as('payments_dashboard.logout');
+    }
+    async warnHookThrow(hookError) {
+        if (hookError === undefined || this.warnedOnHookThrow)
+            return;
+        this.warnedOnHookThrow = true;
+        const message = hookError instanceof Error ? hookError.message : String(hookError);
+        const logger = await this.app.container.make('logger');
+        logger.warn(`dashboardAuth login/session hook threw; treating as denial. ${message}`);
+    }
+    /**
+     * Run the guards for a dashboard resource. Composes the `authorize` hook (bearer token/custom)
+     * with the optional `dashboardAuth` session guard — BOTH must pass:
+     *
+     * 1. `authorize` fails -> `403`.
+     * 2. `dashboardAuth` configured AND no valid session -> for a `page` request, redirect `302` to
+     *    the login page (Mode B) carrying a sanitized `returnTo`, or a `401` notice (Mode A only);
+     *    for an `api` request, `401 { error: 'unauthorized', auth: { modes } }`.
+     *
+     * Returns `allowed: false` (and has already written the response) when the request must
+     * short-circuit. On success it also carries WHO passed the gate: the session's user, which
+     * the write handlers record against a refund or a dispute resolution. `undefined` when this
+     * deployment configures no `dashboardAuth` — there is genuinely nobody to name, and inventing
+     * one would be worse than an honest "unattributed".
+     */
+    async enforce(config, ctx, mode) {
+        const allowed = await config.authorize(ctx);
+        if (!allowed) {
+            if (!ctx.response.getHeader('location')) {
+                ctx.response.status(403).json({ error: 'forbidden' });
+            }
+            return { allowed: false };
+        }
+        const auth = config.dashboardAuth;
+        if (!auth)
+            return { allowed: true };
+        const session = readSession(auth, this.readSessionCookie(ctx));
+        // The display name when the host supplied one, the stable id otherwise. `sub` alone is
+        // unambiguous but often unreadable; a name alone is readable and not unique.
+        if (session) {
+            return {
+                allowed: true,
+                actor: session.name !== undefined ? `${session.name} <${session.sub}>` : session.sub,
+            };
+        }
+        if (mode === 'page') {
+            if (auth.login) {
+                const returnTo = ctx.request.url(true);
+                ctx.response.redirect().withQs('returnTo', returnTo).toPath(`${config.path}/login`);
+                return { allowed: false };
+            }
+            // Mode A only: there's no login page to send the browser to — this deployment expects the
+            // host app to mint a session via `POST <path>/session` before ever navigating here.
+            ctx.response
+                .status(401)
+                .header('content-type', 'text/html; charset=utf-8')
+                .header('cache-control', 'no-store, must-revalidate')
+                .send('<!doctype html><html><body style="font-family:ui-monospace,monospace;background:#09090b;color:#e7e7ea;display:flex;align-items:center;justify-content:center;height:100vh;margin:0"><p>Open this console from your application.</p></body></html>');
+            return { allowed: false };
+        }
+        ctx.response.status(401).json({ error: 'unauthorized', auth: { modes: auth.modes } });
+        return { allowed: false };
+    }
+    readSessionCookie(ctx) {
+        const value = ctx.request.plainCookie(SESSION_COOKIE_NAME, undefined, false);
+        return typeof value === 'string' && value !== '' ? value : undefined;
+    }
+    writeSessionCookie(ctx, auth, value) {
+        ctx.response.plainCookie(SESSION_COOKIE_NAME, value, {
+            httpOnly: true,
+            sameSite: 'lax',
+            secure: ctx.request.secure(),
+            path: '/',
+            maxAge: Math.floor(auth.ttlMs / 1000),
+            encode: false,
+        });
+    }
+}
+/** Adapt an AdonisJS `HttpContext` to the framework-light {@link ApiRequest}. */
+function toApiRequest(ctx) {
+    return {
+        params: ctx.params,
+        query: ctx.request.qs(),
+        body: ctx.request.body(),
+    };
+}
+//# sourceMappingURL=dashboard_provider.js.map

package/dist/providers/dashboard_provider.js.map

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

package/dist/providers/payments_client_provider.d.ts

@@ -0,0 +1,41 @@
+import type { ApplicationService } from '@adonisjs/core/types';
+/**
+ * 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 {
+    protected app: ApplicationService;
+    constructor(app: ApplicationService);
+    /** Warn once, not once per poll — a denied checkout page can retry for a while. */
+    private warnedOnDeny;
+    boot(): Promise<void>;
+    private registerRoutes;
+    /**
+     * 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.
+     */
+    private warnOnDeny;
+}
+//# sourceMappingURL=payments_client_provider.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"payments_client_provider.d.ts","sourceRoot":"","sources":["../../providers/payments_client_provider.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAqB,MAAM,sBAAsB,CAAC;AAUlF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,OAAO,OAAO,sBAAsB;IAC7B,SAAS,CAAC,GAAG,EAAE,kBAAkB;gBAAvB,GAAG,EAAE,kBAAkB;IAE7C,mFAAmF;IACnF,OAAO,CAAC,YAAY,CAAS;IAEvB,IAAI;IAYV,OAAO,CAAC,cAAc;IAoCtB;;;;;;;OAOG;YACW,UAAU;CAUzB"}