@wildo-ai/saas-backend-lib 1.1.1 → 1.1.3

package/dist/esm/billing/services/back-office/billing-reconciliation.backend.service.d.ts

@@ -0,0 +1,186 @@
+/**
+ * Billing Reconciliation — asks the provider what it actually holds, and repairs what drifted.
+ *
+ * ## What this service is for
+ *
+ * Every local billing fact arrives by WEBHOOK. `StandardBilling_Interface.retrieveSubscription`
+ * exists, its own doc comment says "on-demand retrieval for reconciliation (if webhook missed)",
+ * and until 2026-09-09 the only two callers were inside the webhook router itself — i.e. the
+ * recovery read only ever ran when a webhook DID arrive. A delivery that is lost, or that arrives
+ * while the application is down and exhausts the provider's retries, left a stale subscription and
+ * a missing invoice with nothing anywhere that could notice. That is the whole finding.
+ *
+ * ## The conflict rule, because a scheduled write to billing state can CORRUPT rather than merely
+ * lag
+ *
+ * Five rules, and each one is a refusal rather than a capability:
+ *
+ * 1. **Only what the provider is authoritative FOR.** `status`, `currentPeriodStart`,
+ *    `currentPeriodEnd`, `cancelAtPeriodEnd` and `discount` — exactly the set the webhook path
+ *    already syncs in `syncSubscriptionFromProvider`, no more. Two writers of one field must agree
+ *    on which fields they own, or a sweep and a webhook take turns undoing each other.
+ *
+ * 2. **`items` is NEVER reconciled.** REJECTED ALTERNATIVE: sync items too, since the provider
+ *    knows them. It races `CHANGE_PLAN` / `ADD_ADDON` / `REMOVE_ADDON`, every one of which calls
+ *    the provider FIRST and writes local items afterwards — so a sweep reading the provider inside
+ *    that window and writing items would revert a plan change the customer has already been
+ *    charged for. The webhook router refuses items for the same reason and says so; a sweep, which
+ *    runs unprompted and concurrently, has strictly more exposure than it does.
+ *
+ * 3. **A row a local mutation currently owns is SKIPPED.** Any subscription whose `updatedAt` is
+ *    inside {@link RECENT_MUTATION_QUIET_PERIOD_MS} is left alone and counted, not written.
+ *    REJECTED ALTERNATIVE: a compare-and-swap on `updatedAt` at write time. It does not close the
+ *    window that matters — the read-modify-write starts at the PROVIDER READ, not at the local
+ *    read, so a snapshot taken before a webhook that has since landed would still satisfy a CAS
+ *    taken after it. The quiet period addresses the real window, needs no schema change, and costs
+ *    one skipped row that the next tick picks up.
+ *
+ * 4. **Nothing is ever DELETED, CANCELLED or CREATED here.** A provider read that fails — including
+ *    a provider saying the subscription does not exist — is REPORTED and acted on by nobody.
+ *    REJECTED ALTERNATIVE: mark a subscription `CANCELLED` when the provider cannot find it. A
+ *    rotated key pointed at the wrong account, a test-vs-live key mix-up, or a provider outage
+ *    would then cancel every subscription in the application, revoking every entitlement, from a
+ *    read that told us nothing. Stale entitlements are recoverable by the next successful tick;
+ *    revoked ones are not.
+ *
+ * 5. **A row that AGREES is not written.** Comparison happens before any update, because a
+ *    subscription UPDATE fires the post-operation feature-sync hook — an unconditional write would
+ *    recompute entitlements for every account on every tick, bump every `updatedAt`, and file an
+ *    audit row per subscription per tick for a change that did not happen.
+ *
+ * ## Invoices are INSERT-mostly, which is why they are safe
+ *
+ * Wildo never authors an invoice: every `invoiceRefs` row exists because a webhook arrived. So the
+ * missing-invoice repair is a pure insert, and the only field the sweep will UPDATE on an existing
+ * row is `status`, which has exactly one writer and one authority. It never touches `total` — see
+ * `listInvoices` in the Stripe adapter for the disagreement that avoids.
+ *
+ * assurance-control: WILDO.BILLING.PROVIDER_RECONCILIATION — local billing state is compared
+ * against the provider on a schedule, and every divergence is either repaired within the
+ * provider-authoritative field set or reported.
+ */
+import { SubscriptionStatus } from '@wildo-ai/saas-models';
+import type { StandardBilling_Interface } from '@wildo-ai/external-connectors-models';
+import { AbstractBillingBackendService } from '../../../billing/services/back-office/abstract-billing.backend.service';
+import type { LoggerService } from '../../../monitoring/logger/services/logger.service';
+import type { ServicesRegistryHandlerBackendService } from '../../../base-classes/services/services/services-registry-handler.backend.service';
+import type { ExecutionContextCreatorBackendService } from '../../../runtime/services/execution-context-creator.backend.service';
+import type { ResourcesRegistryBackendService } from '../../../resources/services/resources-registry.backend.service';
+import type { ErrorBuilderBackendService } from '../../../errors/services/error-builder.backend.service';
+/**
+ * How recently a local write must have happened for the sweep to leave a row alone.
+ *
+ * Ten minutes, and the number is chosen to dominate the widest window a local mutation can hold:
+ * a plan change is one provider round-trip plus one local write, so seconds in the ordinary case
+ * and at most a request timeout in the worst. Ten minutes buys a wide margin at the cost of one
+ * postponed repair — the next tick reconciles the row, and a subscription that has just been
+ * written is the least likely one in the application to be stale.
+ */
+export declare const RECENT_MUTATION_QUIET_PERIOD_MS: number;
+/**
+ * The provider-AUTHORITATIVE field set — the only fields a sweep may write on a subscription.
+ *
+ * Named, exported and iterated rather than spelled out at the comparison site, so the set that
+ * gets compared and the set that gets written cannot drift apart. It mirrors
+ * `syncSubscriptionFromProvider` in the webhook router exactly; if that grows a field, this list
+ * is the other end of the pair and the pin below is what fails.
+ */
+export declare const PROVIDER_AUTHORITATIVE_SUBSCRIPTION_FIELDS: readonly ["status", "currentPeriodStart", "currentPeriodEnd", "cancelAtPeriodEnd", "discount"];
+/**
+ * What one run did — stated as separate counts rather than a single "reconciled" number, because
+ * the interesting quantity is not how many rows were examined but how many DISAGREED. A healthy
+ * application drifts on zero rows; a steady non-zero `subscriptionsRepaired` means webhooks are
+ * being lost and the sweep is papering over it.
+ */
+export interface BillingReconciliationResult {
+    subscriptionsExamined: number;
+    /** Rows left alone because a local mutation had just touched them (rule 3). */
+    subscriptionsSkippedRecentlyMutated: number;
+    /** Rows where at least one provider-authoritative field disagreed. */
+    subscriptionsDrifted: number;
+    /** Rows actually written. Equals `subscriptionsDrifted` unless a write failed. */
+    subscriptionsRepaired: number;
+    /** Rows whose provider state could not be read. Reported, never acted on (rule 4). */
+    subscriptionsUnreadable: number;
+    billingAccountsExamined: number;
+    invoicesExamined: number;
+    /** Invoices that existed at the provider and nowhere locally, now recorded. */
+    invoicesRecovered: number;
+    invoiceStatusesRepaired: number;
+    /**
+     * One line per drift and per failure, naming the row and the field. A count tells an operator
+     * something is wrong; only the line says whose subscription it was.
+     */
+    errors: string[];
+}
+export declare class BillingReconciliationBackendService extends AbstractBillingBackendService {
+    constructor(logger: LoggerService, servicesRegistry: ServicesRegistryHandlerBackendService, executionContextCreator: ExecutionContextCreatorBackendService, resourcesRegistry: ResourcesRegistryBackendService, errorBuilder: ErrorBuilderBackendService);
+    initialize(provider: StandardBilling_Interface): Promise<void>;
+    /**
+     * Reconcile every billing scope against the provider.
+     *
+     * Returns rather than throws on a provider fault, for the same reason the usage flush does: one
+     * account's unreachable subscription must not stop every other account's drift from being
+     * repaired, and every row left unreconciled is selectable by the next tick at no cost.
+     */
+    reconcile(): Promise<BillingReconciliationResult>;
+    private reconcileSubscriptionsForScope;
+    private reconcileOneSubscription;
+    /**
+     * The comparison, over {@link PROVIDER_AUTHORITATIVE_SUBSCRIPTION_FIELDS} and nothing else.
+     *
+     * Returns only the fields that actually differ, so the update payload is minimal and the
+     * `preserveServerInjectedFields` allowlist derived from it stays minimal with it.
+     */
+    private computeSubscriptionDrift;
+    /**
+     * Equality that survives the three shapes these fields actually take.
+     *
+     * A naive `===` reports drift on EVERY row, forever: `currentPeriodEnd` comes back from the
+     * repository as a `Date` instance (or, depending on the adapter and whether the row came through
+     * a JSON column or a cache, as an ISO STRING) while the provider hands back a fresh `Date`, and
+     * `discount` is an object. A sweep that always sees drift is worse than no sweep — it writes every
+     * subscription every tick, recomputes every account's entitlements, and buries a real divergence
+     * in a report where every row is listed.
+     *
+     * Absent and `null` are treated as agreeing: a local row that has never carried a discount and a
+     * provider with no discount are the same state, and distinguishing them would write `null` over
+     * `undefined` on every discount-free subscription in the application.
+     */
+    private valuesAgree;
+    /**
+     * Key-order-independent structural comparison for the `discount` object.
+     *
+     * Key order is not a difference: the local row comes back from a document store or a JSONB column
+     * and the provider view is built by an object literal here, so a plain `JSON.stringify` compare
+     * would report drift on ordering alone. `undefined` members are dropped so an absent optional and
+     * an explicitly-undefined one compare equal, which is the same reading `valuesAgree` takes above.
+     */
+    private stableStringify;
+    private reconcileInvoicesForScope;
+    private reconcileInvoicesForAccount;
+    private recoverMissingInvoice;
+    /**
+     * `ServiceOptions` that re-attach the fields a client-shaped request DTO would strip.
+     *
+     * The same seam the webhook router and the catalog sync use, and it is not optional here: every
+     * period field on a subscription is `.isNotEditable()` and `providerInvoiceId` is
+     * `.isBackendOnly()`, so without the allowlist the write "succeeds" and persists nothing — a
+     * repair that silently repairs nothing, which is the worst possible outcome for a sweep whose
+     * whole job is to make local state true.
+     */
+    private trustedWriteOptions;
+}
+/**
+ * Statuses a reconciliation sweep considers LIVE — everything `TERMINAL_SUBSCRIPTION_STATUSES` does
+ * not claim.
+ *
+ * DERIVED, so the partition is exhaustive by construction and no pin could ever prove it: a member
+ * added to the enum lands in the swept half automatically. That default is the right one (a new
+ * status is presumed live until someone says otherwise), but it is a default rather than a decision,
+ * so the pin beside this asserts the RESULTING MEMBERSHIP literally. Adding an enum member, or
+ * moving one across the boundary, reddens it and puts the decision in front of a person — which is
+ * the only thing a test can actually contribute here.
+ */
+export declare const RECONCILED_SUBSCRIPTION_STATUSES: readonly SubscriptionStatus[];
+//# sourceMappingURL=billing-reconciliation.backend.service.d.ts.map

package/dist/esm/billing/services/back-office/billing-reconciliation.backend.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"billing-reconciliation.backend.service.d.ts","sourceRoot":"","sources":["../../../../../../src/billing/services/back-office/billing-reconciliation.backend.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AAGH,OAAO,EAML,kBAAkB,EAEnB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,KAAK,EACV,yBAAyB,EAG1B,MAAM,sCAAsC,CAAC;AAE9C,OAAO,EAAE,6BAA6B,EAAE,MAAM,kFAAkF,CAAC;AAOjI,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8DAA8D,CAAC;AAClG,OAAO,KAAK,EAAE,qCAAqC,EAAE,MAAM,6FAA6F,CAAC;AACzJ,OAAO,KAAK,EAAE,qCAAqC,EAAE,MAAM,+EAA+E,CAAC;AAC3I,OAAO,KAAK,EAAE,+BAA+B,EAAE,MAAM,0EAA0E,CAAC;AAChI,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,kEAAkE,CAAC;AAMnH;;;;;;;;GAQG;AACH,eAAO,MAAM,+BAA+B,QAAiB,CAAC;AAE9D;;;;;;;GAOG;AACH,eAAO,MAAM,0CAA0C,gGAM7C,CAAC;AAoBX;;;;;GAKG;AACH,MAAM,WAAW,2BAA2B;IAC1C,qBAAqB,EAAE,MAAM,CAAC;IAC9B,+EAA+E;IAC/E,mCAAmC,EAAE,MAAM,CAAC;IAC5C,sEAAsE;IACtE,oBAAoB,EAAE,MAAM,CAAC;IAC7B,kFAAkF;IAClF,qBAAqB,EAAE,MAAM,CAAC;IAC9B,sFAAsF;IACtF,uBAAuB,EAAE,MAAM,CAAC;IAChC,uBAAuB,EAAE,MAAM,CAAC;IAChC,gBAAgB,EAAE,MAAM,CAAC;IACzB,+EAA+E;IAC/E,iBAAiB,EAAE,MAAM,CAAC;IAC1B,uBAAuB,EAAE,MAAM,CAAC;IAChC;;;OAGG;IACH,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAMD,qBACa,mCAAoC,SAAQ,6BAA6B;gBAE/C,MAAM,EAAE,aAAa,EACG,gBAAgB,EAAE,qCAAqC,EAChD,uBAAuB,EAAE,qCAAqC,EAC5E,iBAAiB,EAAE,+BAA+B,EACtD,YAAY,EAAE,0BAA0B;IAK7E,UAAU,CAAC,QAAQ,EAAE,yBAAyB,GAAG,OAAO,CAAC,IAAI,CAAC;IAU3E;;;;;;OAMG;IACU,SAAS,IAAI,OAAO,CAAC,2BAA2B,CAAC;YAyChD,8BAA8B;YAiC9B,wBAAwB;IAgEtC;;;;;OAKG;IACH,OAAO,CAAC,wBAAwB;IAuChC;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,WAAW;IAoBnB;;;;;;;OAOG;IACH,OAAO,CAAC,eAAe;YAeT,yBAAyB;YAoCzB,2BAA2B;YAyD3B,qBAAqB;IAyDnC;;;;;;;;OAQG;IACH,OAAO,CAAC,mBAAmB;CAc5B;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gCAAgC,EAAE,SAAS,kBAAkB,EAC4B,CAAC"}