@adonis-agora/payments 0.2.0 → 0.3.0

package/dist/src/dashboard/handlers.d.ts

@@ -0,0 +1,281 @@
+import { type BillingStore } from '../billing/billing_store.js';
+import { BILLING_LIST_DEFAULT_LIMIT } from '../billing/list_query.js';
+import type { RefundAction, ReplayAction } from './actions.js';
+/**
+ * Framework-light JSON handlers over a {@link BillingStore}.
+ *
+ * Each handler takes a {@link Deps} bundle (the store the app already resolved, the display
+ * currency, and — for the two write actions — the ports in `actions.ts`) and a plain
+ * {@link ApiRequest} (a thin view of the parts of an HTTP request it needs), and returns a plain
+ * {@link ApiResponse} (status + JSON body). No AdonisJS types leak in, so the handlers are
+ * unit-testable against the real `InMemoryBillingStore` with no HTTP server. The provider adapts
+ * an AdonisJS `HttpContext` to these shapes.
+ *
+ * Mirrors `@adonis-agora/durable`'s `src/dashboard/handlers.ts` convention exactly (`Deps` /
+ * `ApiRequest` / `ApiResponse` / `ok` / `notFound` / `badRequest`, reads as `GET`, actions as
+ * `POST`), so the two consoles' server halves read the same.
+ *
+ * This is a MANAGEMENT console, not a debugger: it answers "what needs my attention, which
+ * customer is stuck, can I fix it from here". Raw payloads, verification traces and timings are
+ * `@adonis-agora/telescope`'s job and are deliberately absent — nothing here returns a stored
+ * gateway payload.
+ *
+ * MONEY: `amount` and `revenue` cross this boundary as integer MINOR UNITS, exactly as they are
+ * stored. Nothing here divides — and the divisor is not always 100 (`src/money.ts`'s
+ * `currencyExponent`). The SPA formats at render (`src/app/money.ts`).
+ */
+/** What the handlers need to answer a request. */
+export interface Deps {
+    store: BillingStore;
+    /** ISO 4217 code echoed to the client so it knows how to format the minor units it receives. */
+    currency: string;
+    /** Injectable clock (for the period presets) — defaults to the wall clock. */
+    now?: () => Date;
+    /**
+     * The write actions. Absent (or partially absent) when the app has no reachable
+     * `PaymentsManager` — the read endpoints keep working and the action endpoints answer `503`
+     * with a sentence saying so, rather than a button that silently does nothing.
+     */
+    actions?: Partial<DashboardActions>;
+    /**
+     * WHO is making this request, as the provider's `enforce()` guard already knew them.
+     *
+     * Per-request, unlike everything else on `Deps`. The guard has verified a signed session
+     * carrying a user before any handler runs, and until now it threw that away — so the only
+     * record of a refund issued from this console was a diagnostic naming a gateway id, an amount
+     * and no person at all. `undefined` on a console with no `dashboardAuth` configured, which is
+     * recorded honestly as "unattributed" rather than invented.
+     */
+    actor?: string;
+}
+/** The two things this console can CHANGE. See `actions.ts`. */
+export interface DashboardActions {
+    refund: RefundAction;
+    replayWebhook: ReplayAction;
+}
+/** The subset of an HTTP request the handlers read. */
+export interface ApiRequest {
+    /** Route params, e.g. `{ gatewayId: 'pi_123' }`. */
+    params: Record<string, string | undefined>;
+    /** Parsed query string, e.g. `{ status: 'failed', limit: '20' }`. */
+    query: Record<string, string | string[] | undefined>;
+    /** Parsed JSON body (for the POST actions). */
+    body?: unknown;
+}
+/** A plain JSON response: an HTTP status and a serializable body. */
+export interface ApiResponse {
+    status: number;
+    body: unknown;
+}
+/** A `200 OK` JSON response. Exported so sibling handlers share one convention. */
+export declare const ok: (body: unknown) => ApiResponse;
+/** The statuses the payments filter offers. `status` is a free string in the store (a gateway may
+ *  send its own), so this is a UI convenience list, not a validation whitelist. Every member of
+ *  `BillingStatus` is here: `authorized` money can still evaporate and `disputed` money has already
+ *  been pulled back, and an operator who cannot filter for either cannot see either. */
+export declare const PAYMENT_STATUSES: readonly ["paid", "authorized", "pending", "failed", "refunded", "disputed", "canceled"];
+/** The statuses the disputes filter offers — `DisputeStatus`, ordered the way an operator reads
+ *  them: what still needs an answer first. `warning` leads because it is the only one where a
+ *  refund still stops the chargeback from ever being filed. */
+export declare const DISPUTE_STATUSES: readonly ["warning", "open", "under_review", "lost", "expired", "canceled", "won"];
+/** How far ahead `?dueWithin=` looks when the caller asks for closing windows but names no
+ *  horizon. Matches `billingHealth`'s default, so the panel and the cron agree about "soon". */
+export declare const DISPUTE_DEFAULT_DUE_WITHIN_HOURS = 72;
+/** The ledger's three statuses. `failed` is the one that means "a handler threw and the dispatcher
+ *  gave up" — i.e. the event's effect never happened. */
+export declare const WEBHOOK_EVENT_STATUSES: readonly ["received", "processed", "failed"];
+/** `SubscriptionStatus`, ordered the way an operator reads them: what needs attention first.
+ *  `paused` sits apart from `active` deliberately — a paused subscriber is not paying. */
+export declare const SUBSCRIPTION_STATUSES: readonly ["past_due", "paused", "incomplete", "trialing", "active", "canceled", "ended"];
+/** The one status the subscriptions screen opens on: someone's payment failed and the subscription
+ *  is about to lapse. Everything else can wait until tomorrow. */
+export declare const SUBSCRIPTION_DEFAULT_STATUS = "past_due";
+/**
+ * How many rows a provider-filtered page may scan before it gives up and says so.
+ *
+ * `BillingListQuery` filters on `status` only, so `?provider=` is applied here, over pages read
+ * from the store. That is bounded work by construction — but it has to be bounded VISIBLY: a
+ * silent "no Asaas payments" that really means "none in the last thousand rows" is the kind of
+ * wrong answer an operator acts on. `page.truncated` says which one they are looking at.
+ */
+export declare const PROVIDER_SCAN_CAP = 1000;
+/**
+ * `GET <api>/overview` — the `billingOverview()` aggregates for a selectable window.
+ *
+ * Straight passthrough of the headless function this package already ships: revenue (integer
+ * minor units), active subscriptions (which INCLUDES `trialing` — see `countActiveSubscriptions`),
+ * and one line per metered meter.
+ */
+export declare function overview(deps: Deps, req: ApiRequest): Promise<ApiResponse>;
+/**
+ * `GET <api>/health` — the three silent failures of a billing install, from `billingHealth()`.
+ *
+ * This is the endpoint the console opens on. Every other screen answers a question the operator
+ * had to think of; this one answers the question they did not: an install where the worker died,
+ * or the webhook endpoint stopped being reachable, keeps returning `200` everywhere while revenue
+ * quietly stops landing. `failures` names WHICH provider and event type is failing, so the answer
+ * is a place to look rather than a number.
+ *
+ * Nothing here is windowed by the period selector: `billingHealth` has its own thresholds
+ * (15 min stuck, 2 h unconfirmed, 24 h of failures) and they are the thresholds `payments:health`
+ * alerts on, so the console and the cron agree.
+ */
+export declare function health(deps: Deps): Promise<ApiResponse>;
+/**
+ * `GET <api>/disputes` — a page of `billing_disputes`.
+ *
+ * Two modes, because a dispute list has two questions:
+ *
+ * - default: newest first, `status`/`provider` filters — the log.
+ * - `?dueWithin=<hours>`: only OPEN disputes carrying a deadline, soonest window first — the
+ *   work. Rows already past their deadline stay in it: they are still open and still
+ *   unanswered, and dropping them the moment they expire would make the panel go quiet at
+ *   exactly the moment it became urgent.
+ *
+ * There is still no "accept" and no "fight" button: whether to submit evidence or refund is a
+ * business rule (it turns on the fee, the evidence you actually have, and the chargeback ratio
+ * that puts a merchant into a card network's monitoring programme), and it stays in the app's
+ * code. The one write this screen does have is {@link resolveDispute}, which records an outcome
+ * that has ALREADY happened at the gateway — see the note there for why that is not the same
+ * thing.
+ */
+export declare function disputes(deps: Deps, req: ApiRequest): Promise<ApiResponse>;
+/**
+ * `GET <api>/payments` — a page of `billing_payments`, newest first.
+ *
+ * Filters: `status`, `provider`, and the three that answer "did this one land?" —
+ * `reference` (the app's own `externalReference`), `gatewayId`, and `customerId`. All three are
+ * EXACT: they are join keys, and a prefix match on `order-4` returning `order-42` is a wrong
+ * answer to a question about money.
+ */
+export declare function payments(deps: Deps, req: ApiRequest): Promise<ApiResponse>;
+/**
+ * `GET <api>/payments/:gatewayId` — everything this system knows about ONE payment.
+ *
+ * The screen that did not exist, and the honest name for it is "what IS knowable", not "history".
+ * `billing_payments` is a single mutable row upserted in place: it has a current state and no
+ * past, so "what changed on this payment, and when?" cannot be answered from it and this endpoint
+ * does not pretend otherwise. What it assembles instead:
+ *
+ * - the row's CURRENT state, including `refundedAmount` and the app's own reference;
+ * - the app-side OWNER, through `billing_customers`;
+ * - every DISPUTE filed against it — that table does carry a real link (`payment_gateway_id`);
+ * - the LEDGER rows whose stored delivery names it, newest first. That is a payload substring
+ *   scan, with everything that implies: it is unindexed, and it can match a delivery that merely
+ *   mentions the id. `events.matchedBy` says so on the wire rather than in a comment nobody sees.
+ * - the AUDIT rows naming it — who refunded it, from this console, and when.
+ *
+ * The stored payload is still never returned. The timeline says an event ARRIVED and what type it
+ * was; what was inside it is telescope's job.
+ */
+export declare function paymentDetail(deps: Deps, req: ApiRequest): Promise<ApiResponse>;
+/**
+ * `GET <api>/subscriptions` — a page of `billing_subscriptions`, newest first,
+ * `status`/`provider` filters.
+ *
+ * For a subscription business this is the daily surface: `countActiveSubscriptions()` answers "how
+ * many", which is the wrong question on any day something is wrong. The operational questions are
+ * WHICH subscriptions are `past_due` (someone's card failed and they are about to lose access) and
+ * which are `paused` (a subscriber who is not paying and must not be read as active) — and a count
+ * cannot name a customer to email.
+ */
+export declare function subscriptions(deps: Deps, req: ApiRequest): Promise<ApiResponse>;
+/**
+ * `GET <api>/webhook-events` — a page of the idempotency ledger, newest first,
+ * `status`/`provider` filters.
+ *
+ * The `error` column is carried through verbatim: a `failed` row is the only record that a handler
+ * threw, and its message is the only place the reason survives. The stored gateway payload is NOT
+ * returned — that is a debugging question, and telescope is where it belongs.
+ */
+export declare function webhookEvents(deps: Deps, req: ApiRequest): Promise<ApiResponse>;
+/**
+ * `GET <api>/customers` — a page of `billing_customers`, newest first.
+ *
+ * The endpoint that did not exist. `billing_customers` holds `owner_type`/`owner_id`, written by
+ * the app itself through `ensureCustomer`, and that mapping is the ONLY thing tying a payment to
+ * a person: a payment row carries `cus_…` and nothing else. Without this the console could show
+ * every charge in the system and never answer "which of these is user 4102's".
+ *
+ * Filters: `provider`, `ownerType`, `ownerId`, `gatewayId` — all exact. Pair `ownerType` with
+ * `ownerId`: one owner may legitimately hold a customer at every configured gateway, so an id
+ * alone is not a key.
+ */
+export declare function customers(deps: Deps, req: ApiRequest): Promise<ApiResponse>;
+/** The audit actions the filter offers. A free string in the column, so this is a UI convenience
+ *  list, not a validation whitelist — an app that records its own actions still sees them. */
+export declare const AUDIT_ACTION_FILTERS: readonly ["webhook.rejected", "payment.refunded", "dispute.resolved"];
+/**
+ * `GET <api>/audit` — the trail of things that happened which no other table records.
+ *
+ * Three kinds of row, and each of them used to be a diagnostic and nothing else:
+ *
+ * - `webhook.rejected` — a delivery the endpoint REFUSED. This is the one that matters most,
+ *   because it is otherwise invisible: a rejected delivery never becomes a ledger row, so a
+ *   rotated webhook secret looks exactly like a quiet week — zero events, zero failures, every
+ *   check green — while every refund, chargeback and dispute closure is dropped on the floor.
+ * - `payment.refunded` — WHO refunded what, from this console. The payment row moves only when
+ *   the gateway's webhook lands, and that row names no person.
+ * - `dispute.resolved` — who closed a dispute the gateway will never close itself.
+ *
+ * Filters: `action`, `actor`, `provider`, `subjectType`, `subjectId` — all exact.
+ */
+export declare function auditEvents(deps: Deps, req: ApiRequest): Promise<ApiResponse>;
+/**
+ * `GET <api>/providers` — the gateways this install actually uses, for the provider filter.
+ *
+ * Driven by the DATA, never by a hardcoded list: this package ships eighteen drivers and an
+ * install runs two or three of them, so a static list would offer fifteen filters that return
+ * nothing and hide the one that matters behind them. The ledger side is exact
+ * (`webhookEventBreakdown` groups the whole table); the payment/subscription side reads the most
+ * recent {@link PROVIDER_DISCOVERY_SCAN} rows, which is enough to notice a gateway that is in use.
+ */
+export declare function providers(deps: Deps): Promise<ApiResponse>;
+/** The dispute statuses that mean the matter is FINISHED — `DISPUTE_STATUSES` minus the open
+ *  ones. Only these can be recorded through {@link resolveDispute}: "resolve" that could put a
+ *  row back into `open` is not a resolution, it is an edit box over a money table. */
+export declare const DISPUTE_RESOLUTION_STATUSES: ("warning" | "open" | "under_review" | "canceled" | "won" | "lost" | "expired")[];
+/**
+ * `POST <api>/disputes/:gatewayId/resolve` — record how a dispute ENDED.
+ *
+ * The one thing this console could not do, and the reason the dispute alarm was permanently red
+ * on a real install: Asaas publishes no lost-dispute event at all, and the driver hardcodes
+ * `outcome: 'won'` when it closes one — so a dispute that was LOST stays `open` in
+ * `billing_disputes` forever. `listDisputesDueWithin` counts past-deadline rows on purpose, so
+ * the check stays red, and a fifteen-minute cron logs the same failure until nobody reads it.
+ * A gateway that never closes the loop is the NORMAL case here, not the exception.
+ *
+ * This does not fight, accept or refund anything — nothing here talks to a gateway. It records
+ * an outcome that has already happened somewhere else, with the status, the outcome and WHO said
+ * so, which is the difference between a resolution and an edit box.
+ *
+ * Body: `{ status, outcome?, note? }`. `status` must be a finished one
+ * ({@link DISPUTE_RESOLUTION_STATUSES}); `outcome` defaults to it.
+ */
+export declare function resolveDispute(deps: Deps, req: ApiRequest): Promise<ApiResponse>;
+/**
+ * `POST <api>/payments/:gatewayId/refund` — refund a payment through its own gateway.
+ *
+ * `POST`, never `GET`: a refund reachable by URL is a refund a crawler can trigger. Body is
+ * `{ amount?: number }` in integer minor units; omit it for the full amount.
+ *
+ * The local row is deliberately NOT rewritten here. The gateway confirms a refund with a
+ * `payment.refunded` webhook, and that is what moves the row to `refunded` — writing it optimistically
+ * would show the operator a refund that may never have settled.
+ */
+export declare function refundPayment(deps: Deps, req: ApiRequest): Promise<ApiResponse>;
+/**
+ * `POST <api>/webhook-events/:gatewayEventId/retry` — re-run a failed event's handlers.
+ *
+ * The single most useful thing an operator can do after fixing a handler bug: a `failed` row means
+ * the dispatcher gave up, so whatever that event described — a subscription activated, a payment
+ * recorded — never happened, and nothing will retry it. Replaying is safe because the ledger
+ * re-claims a `failed` event (`recordWebhookEvent` returns it again) while refusing an in-flight or
+ * already-processed one, so this can never double-apply a redelivery.
+ *
+ * `POST`, never `GET`, for the same reason the refund is.
+ */
+export declare function retryWebhookEvent(deps: Deps, req: ApiRequest): Promise<ApiResponse>;
+/** Re-exported so the provider and the SPA agree on the default page size without duplicating it. */
+export { BILLING_LIST_DEFAULT_LIMIT };
+//# sourceMappingURL=handlers.d.ts.map

package/dist/src/dashboard/handlers.d.ts.map

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