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

package/dist/esm/billing/services/webhooks/billing-webhook-event-router.backend.service.js

@@ -19,10 +19,41 @@
  *
  * @see billing-polymorphic-full-implementation.md §4.5
  */
-import { CoreResourceType, CoreWebSocketEvent, ResourcePrimaryScope, SubscriptionStatus, ProductType, CreditPool_Operations, CoreResourceOperation, deriveTrustedSystemWritePreservedFields, } from '@wildo-ai/saas-models';
+import { CoreResourceType, CoreWebSocketEvent, ResourcePrimaryScope, SubscriptionStatus, ProductType, CreditPool_Operations, CoreResourceOperation, ErrorType, deriveTrustedSystemWritePreservedFields, isWildoBackendError, } from '@wildo-ai/saas-models';
+import { currencyMinorUnitDecimals } from '@wildo-ai/zod-decorators';
 import { getBillingProvider, getFeatureSyncService } from '../../../billing/services/custom-impl/billing-custom-implementations.backend.js';
 import { resolveBillingVariants } from '../../../billing/services/custom-impl/billing-custom-impl-utils.backend.js';
 import { BillingAccountEchoVerdict, BillingCheckoutMetadataOutcomeKind, compareEchoedBillingAccount, resolveCheckoutSessionMetadata, } from '../../../billing/services/billing-checkout-metadata.backend.utils.js';
+import { BILLING_PROVIDER_EVENT_SETTLEMENT_CLAIM_LEASE_MS, billingProviderEventSettlementId, } from '../../../billing/models/billing-provider-event-settlement.backend.schemas.js';
+import { BackendResourceType } from '../../../resources/models/resources-types.backend.schemas.js';
+/**
+ * What a durable settlement claim answered — a closed vocabulary with one named runtime source,
+ * because each member routes to a different action on a MONEY path and an inline string union
+ * could carry none of the reasoning below.
+ */
+export var BillingSettlementClaim;
+(function (BillingSettlementClaim) {
+    /**
+     * This handler holds the claim and is the one that must apply the event's effects. Either it
+     * inserted the ledger row, or it took over a claim whose holder died more than
+     * {@link BILLING_PROVIDER_EVENT_SETTLEMENT_CLAIM_LEASE_MS} ago.
+     */
+    BillingSettlementClaim["OWNED"] = "OWNED";
+    /** The effects were already applied by an earlier delivery. Grant nothing. */
+    BillingSettlementClaim["ALREADY_APPLIED"] = "ALREADY_APPLIED";
+    /**
+     * Another delivery — very likely on another replica — holds a FRESH claim and is applying the
+     * effects right now. Grant nothing, and say nothing alarming: this is the ordinary shape of a
+     * duplicate delivery arriving while the first is still in flight.
+     */
+    BillingSettlementClaim["HELD_ELSEWHERE"] = "HELD_ELSEWHERE";
+    /**
+     * The claim could not be taken at all — the ledger store refused, or the event carried no
+     * identity to key one on. Grant nothing: a money write nobody can deduplicate is exactly what
+     * this ledger exists to prevent.
+     */
+    BillingSettlementClaim["UNAVAILABLE"] = "UNAVAILABLE";
+})(BillingSettlementClaim || (BillingSettlementClaim = {}));
 // ── Provider Status Mapping ─────────────────────────────────────────
 const PROVIDER_STATUS_MAP = {
     active: SubscriptionStatus.ACTIVE,
@@ -44,22 +75,29 @@ export class BillingWebhookEventRouterBackendService {
     resourcesRegistry;
     logger;
     webSocketService;
+    repositoriesRegistry;
+    constructor(servicesRegistry, resourcesRegistry, logger, webSocketService, 
     /**
-     * In-memory dedup guard for checkout sessions.
-     * Prevents double top-ups on webhook retries within the same process.
-     * Capped to prevent unbounded memory growth; oldest entries evicted on overflow.
+     * REQUIRED, and it was optional until the duplicate-suppression fix.
+     *
+     * It arrived for the promotion-redemption compare-and-swap (#518) and was declared optional on
+     * a defensible argument: everything else this router does goes through the service tier, and a
+     * purchase must not fail because a COUNTER could not be incremented.
      *
-     * Limitation: process-local only — does not protect against retries delivered
-     * to different instances in a multi-instance deployment. For production hardening,
-     * replace with a shared store (Redis SET with TTL or MongoDB dedup collection).
+     * That argument does not survive this registry also carrying the durable settlement ledger.
+     * Without it there is no idempotency for the credit-pool top-up at all, and the two ways of
+     * degrading are both unacceptable rather than merely inconvenient: granting anyway double-grants
+     * money on the next retry, and skipping loses a purchase the customer has already paid for.
+     * Neither is a degradation a deployment should be allowed to reach by omitting a constructor
+     * argument, so the argument is now required and every construction site — production and test —
+     * has to say what backs the ledger.
      */
-    processedCheckoutSessions = new Set();
-    static MAX_DEDUP_ENTRIES = 10_000;
-    constructor(servicesRegistry, resourcesRegistry, logger, webSocketService) {
+    repositoriesRegistry) {
         this.servicesRegistry = servicesRegistry;
         this.resourcesRegistry = resourcesRegistry;
         this.logger = logger;
         this.webSocketService = webSocketService;
+        this.repositoriesRegistry = repositoriesRegistry;
     }
     log(level, message, context) {
         if (!this.logger)
@@ -325,6 +363,29 @@ export class BillingWebhookEventRouterBackendService {
         const rawAmount = data.amount_paid ?? data.total ?? 0;
         const amountInCents = typeof rawAmount === 'string' ? parseInt(rawAmount, 10) || 0 : Number(rawAmount) || 0;
         const currency = data.currency ?? 'usd';
+        /*
+         * The provider's amount is in the CURRENCY's smallest unit, so the scale is the currency's — not 2
+         * (#515).
+         *
+         * `decimals: 2` was written here unconditionally, two lines below the event's own `currency`. For
+         * a zero-decimal currency the provider's amount is already whole units, so recording it at scale 2
+         * stored a JPY invoice at a HUNDREDTH of its value; for a three-decimal dinar it stored ten times
+         * too much.
+         *
+         * An unresolvable currency falls back to 2 with a loud error rather than dropping the invoice: a
+         * webhook is the provider telling us something happened, and refusing to record it loses the fact
+         * as well as the amount. The error names the currency so the row can be corrected — and this is
+         * the one place in the boundary that degrades rather than refuses, because it is the only one
+         * where refusing destroys information we cannot ask for again.
+         */
+        const resolvedDecimals = currencyMinorUnitDecimals(currency.toUpperCase());
+        if (resolvedDecimals === undefined) {
+            this.logger.error('Invoice recorded at an ASSUMED scale: the provider currency has no resolvable minor unit', {
+                providerInvoiceId,
+                currency,
+                assumedDecimals: 2,
+            });
+        }
         const invoiceData = {
             [variants.billingAccountFkField]: billingAccountId,
             providerInvoiceId,
@@ -332,7 +393,7 @@ export class BillingWebhookEventRouterBackendService {
             total: {
                 amount: BigInt(amountInCents),
                 currency,
-                decimals: 2,
+                decimals: resolvedDecimals ?? 2,
             },
             hostedInvoiceUrl: data.hosted_invoice_url,
             invoicePdfUrl: data.invoice_pdf,
@@ -372,13 +433,8 @@ export class BillingWebhookEventRouterBackendService {
      *   (the `?? 1` fallback is dead — `NaN` is not nullish), `-5` for `"-5"`, and 1e9 for `"1e9"`.
      */
     async handleCheckoutCompleted(event, variants, execCtx) {
-        // Idempotency: skip if this checkout session was already processed (webhook retry)
         const checkoutSessionId = event.data.id;
         const dedupKey = checkoutSessionId ?? event.providerEventId;
-        if (dedupKey && this.processedCheckoutSessions.has(dedupKey)) {
-            this.log('debug', 'Skipping duplicate checkout.session.completed', { dedupKey });
-            return;
-        }
         const data = event.data;
         // Provider truth first: whose customer actually paid. Scope resolution already matched this
         // customer to a billing-account row (otherwise the event would have degraded to APPLICATION
@@ -400,14 +456,66 @@ export class BillingWebhookEventRouterBackendService {
         }
         if (outcome.kind === BillingCheckoutMetadataOutcomeKind.REFUSED) {
             // A session that CLAIMS to be ours and is internally inconsistent. Distinct from the case
-            // above on purpose: this is a tamper signal and must be loud, not a debug skip. Not marked as
-            // deduplicated either — a refusal granted nothing, so a retry re-evaluates it.
+            // above on purpose: this is a tamper signal and must be loud, not a debug skip. No settlement
+            // claim is taken either — a refusal granted nothing, so a retry re-evaluates it.
             this.log('error', 'Refusing checkout.session.completed: framework metadata failed validation', {
                 dedupKey, reason: outcome.reason, ...outcome.detail,
             });
             return;
         }
-        const { productKey, quantity } = outcome;
+        const { productKey, quantity, promotionId } = outcome;
+        /*
+         * DURABLE duplicate suppression, taken HERE and not one line earlier.
+         *
+         * Everything above this point either granted nothing (a session the framework did not open, a
+         * session whose metadata failed validation, a customer that resolves to no billing account) or
+         * decided WHAT would be granted. None of it may be suppressed: a refusal must be re-evaluated
+         * on the next delivery — that is what the REFUSED branch above says in so many words — and a
+         * suppression taken before the refusal would freeze a tamper verdict into the ledger.
+         *
+         * Everything BELOW writes money: it counts a promotion redemption against its cap and tops up a
+         * credit pool. Those are the writes the claim exists to make exactly-once.
+         *
+         * The two races answer differently, and both answers are deliberate:
+         *
+         *  - **A retry that arrives AFTER the first finished** finds a row carrying `appliedAt` and is
+         *    ALREADY_APPLIED. Nothing is granted, and it is logged at debug because it is the ordinary,
+         *    expected shape of at-least-once delivery.
+         *  - **A retry that arrives WHILE the first is still in flight** — a genuinely concurrent
+         *    delivery, most often to another replica — loses the INSERT to the primary key and finds a
+         *    row with a fresh `claimedAt` and no `appliedAt`. It is HELD_ELSEWHERE and also grants
+         *    nothing. It does not wait, and it does not retry: the holder is milliseconds from
+         *    finishing, and if it instead DIES the provider's own retry schedule brings the event back
+         *    after the claim lease expires, at which point the takeover branch applies it. So a crashed
+         *    holder costs a delay, never the credits.
+         */
+        const settlement = await this.claimSettlement(dedupKey, event.type, execCtx);
+        if (settlement.claim !== BillingSettlementClaim.OWNED) {
+            this.log(settlement.claim === BillingSettlementClaim.UNAVAILABLE ? 'error' : 'debug', 'Granting nothing for checkout.session.completed — this delivery does not hold the settlement claim', { dedupKey, claim: settlement.claim });
+            return;
+        }
+        /*
+         * COUNT the redemption, now that the purchase is real (#518).
+         *
+         * At checkout OPEN the code was validated — including against `maxRedemptions` — and nothing was
+         * incremented, so a code used only through checkout stayed at zero redemptions forever and the cap
+         * could be exceeded without limit. The separate `apply` verb counted one, at the moment a customer
+         * TYPED a code, which is a different event from redeeming it; it no longer counts, so this is now
+         * the ONE place a redemption is recorded.
+         *
+         * Counted at COMPLETION rather than at open, because a customer who opens a checkout and walks
+         * away has redeemed nothing; incrementing at open would exhaust a limited code on abandoned
+         * sessions and is the more expensive mistake of the two.
+         *
+         * Compare-and-swap against the cap: two sessions completing at once cannot both take the last
+         * redemption. And it sits INSIDE the settlement claim, so a retried delivery cannot count a
+         * second redemption for one purchase. A refusal here does NOT refuse the purchase — the
+         * customer has already paid and the provider has already applied the discount, so the only honest
+         * response is to grant what they bought and record loudly that the cap was passed.
+         */
+        if (promotionId) {
+            await this.countPromotionRedemption(promotionId, execCtx, dedupKey);
+        }
         // Read product to check if it's a CREDIT_PACK
         const products = await this.servicesRegistry.list(CoreResourceType.PRODUCTS, execCtx, { key: productKey });
         const product = products.length > 0 ? products[0] : null;
@@ -440,14 +548,109 @@ export class BillingWebhookEventRouterBackendService {
                 });
             }
         }
-        // Mark as processed for dedup
-        if (dedupKey) {
-            if (this.processedCheckoutSessions.size >= BillingWebhookEventRouterBackendService.MAX_DEDUP_ENTRIES) {
-                const first = this.processedCheckoutSessions.values().next().value;
-                if (first !== undefined)
-                    this.processedCheckoutSessions.delete(first);
+        await this.markSettlementApplied(settlement.settlementId, dedupKey);
+    }
+    /**
+     * Take the DURABLE claim on one money-affecting provider event, or report who already holds it.
+     *
+     * ## Why the collision is an INSERT and not a read-then-write
+     *
+     * Two deliveries arriving together would both read "not settled" before either wrote, so the
+     * suppression cannot be a check. It is a row whose PRIMARY KEY is derived from the event's own
+     * identity: the second INSERT collides at the store, on the one constraint both adapters enforce
+     * natively and identically. `insertDocumentForInfrastructure` translates that collision into a
+     * classified `CONFLICT` on either arm — MongoDB from `E11000`, PostgreSQL from SQLSTATE `23505` —
+     * so this branch is adapter-neutral rather than adapter-aware.
+     *
+     * ## Why anything that is NOT a conflict re-throws
+     *
+     * A store that is unreachable, a table that does not exist, a cast that failed: none of those
+     * mean "already settled", and reading them as suppression would silently swallow a purchase. They
+     * propagate, the webhook delivery fails, and the provider retries — which is the correct outcome
+     * for a transient store failure and a loud one for a permanent misconfiguration.
+     */
+    async claimSettlement(dedupKey, eventType, execCtx) {
+        if (!dedupKey) {
+            /*
+             * An event carrying neither a checkout-session id nor a provider event id. The standard
+             * webhook contract types `providerEventId` as required, so reaching this is a malformed event
+             * or a broken adapter rather than a provider behaviour.
+             *
+             * Refusing is the fail-CLOSED choice and it is taken knowingly: without an identity there is
+             * nothing to key a claim on, so every redelivery of this same event would grant again, without
+             * limit. A missed grant is recoverable by a human reading this error; an unbounded repeat of a
+             * credit grant is not.
+             */
+            this.log('error', 'Checkout completion carries no identity to deduplicate on — refusing to grant', { eventType });
+            return { claim: BillingSettlementClaim.UNAVAILABLE, settlementId: null };
+        }
+        const claimKey = `${eventType}:${dedupKey}`;
+        const settlementId = billingProviderEventSettlementId(claimKey);
+        const now = new Date();
+        try {
+            await this.repositoriesRegistry.insertDocumentForInfrastructure(BackendResourceType.BILLING_PROVIDER_EVENT_SETTLEMENTS, { _id: settlementId, claimKey, eventType, claimedAt: now }, execCtx);
+            return { claim: BillingSettlementClaim.OWNED, settlementId };
+        }
+        catch (error) {
+            if (!isWildoBackendError(error) || error.type !== ErrorType.CONFLICT) {
+                this.log('error', 'Could not take the settlement claim for a completed checkout — refusing to grant', {
+                    claimKey, message: error.message,
+                });
+                return { claim: BillingSettlementClaim.UNAVAILABLE, settlementId: null };
             }
-            this.processedCheckoutSessions.add(dedupKey);
+        }
+        // The row exists. Whether it SETTLED is the next question, and only a row that did not may be
+        // taken over — see the lease constant for why a takeover exists at all.
+        const existing = await this.repositoriesRegistry.readUnscopedByKey(BackendResourceType.BILLING_PROVIDER_EVENT_SETTLEMENTS, { _id: settlementId });
+        if (existing?.appliedAt)
+            return { claim: BillingSettlementClaim.ALREADY_APPLIED, settlementId };
+        /*
+         * Compare-and-swap the lease, never a read-then-write: several retries of an abandoned claim can
+         * arrive together, and exactly one of them may take it. `appliedAt: { $exists: false }` is in
+         * the FILTER rather than checked above for the same reason — the row may settle between the read
+         * and this statement, and a filter that admitted a settled row would double-grant.
+         *
+         * `$exists` is the one presence predicate both adapters answer identically (MongoDB: the path is
+         * absent; PostgreSQL: the column IS NULL) — which is why the ledger expresses "not yet applied"
+         * as an absent value rather than as a status.
+         */
+        const takenOver = await this.repositoriesRegistry.atomicGuardedMutation(BackendResourceType.BILLING_PROVIDER_EVENT_SETTLEMENTS, {
+            _id: settlementId,
+            appliedAt: { $exists: false },
+            claimedAt: { $lt: new Date(now.getTime() - BILLING_PROVIDER_EVENT_SETTLEMENT_CLAIM_LEASE_MS) },
+        }, { set: { claimedAt: now } }, execCtx);
+        if (takenOver) {
+            this.log('warn', 'Took over an ABANDONED settlement claim — a previous delivery claimed this event and never applied it', {
+                claimKey, previousClaimedAt: existing?.claimedAt,
+            });
+            return { claim: BillingSettlementClaim.OWNED, settlementId };
+        }
+        return { claim: BillingSettlementClaim.HELD_ELSEWHERE, settlementId };
+    }
+    /**
+     * Close the claim, so every later delivery of this event is ALREADY_APPLIED rather than a
+     * candidate for takeover.
+     *
+     * Never throws: the grant has already landed, and turning a successful purchase into a failed
+     * webhook delivery would make the provider retry an event whose effects are complete.
+     *
+     * The failure it logs is the residual this design keeps rather than removes, and it is stated
+     * plainly because nothing else records it: if this single write is lost, the ledger row keeps an
+     * open claim, and a redelivery arriving after the lease expires WILL grant a second time. That
+     * window is one statement wide, and the alternative — marking applied BEFORE doing the work —
+     * trades it for a strictly worse one, where a handler that dies mid-grant leaves a purchase
+     * permanently unsettled and no retry can ever repair it.
+     */
+    async markSettlementApplied(settlementId, dedupKey) {
+        if (!settlementId)
+            return;
+        try {
+            await this.repositoriesRegistry.atomicGuardedMutation(BackendResourceType.BILLING_PROVIDER_EVENT_SETTLEMENTS, { _id: settlementId }, { set: { appliedAt: new Date() } });
+        }
+        catch (error) {
+            this.log('error', 'Settlement applied but NOT recorded as applied — a later retry of this event could grant a second time', {
+                dedupKey, message: error.message,
+            });
         }
     }
     // ════════════════════════════════════════════════════════════════════
@@ -508,6 +711,37 @@ export class BillingWebhookEventRouterBackendService {
     /**
      * Find a subscription by providerSubscriptionId in a specific variant collection.
      */
+    /**
+     * Increment a promotion's `timesRedeemed`, guarded against its own cap (#518).
+     *
+     * Never throws. It runs after the customer has paid and the provider has applied the discount, so
+     * every failure mode — a missing row, a store error, a cap already reached — must leave the grant
+     * alone and become a loud record instead. The cap being passed is a real operational event (a
+     * promotion was honoured beyond its limit) and it is logged at ERROR for exactly that reason.
+     */
+    async countPromotionRedemption(promotionId, execCtx, dedupKey) {
+        try {
+            const promotion = await this.servicesRegistry.read(CoreResourceType.PROMOTIONS, execCtx, promotionId);
+            if (!promotion) {
+                this.log('warn', 'Checkout completed carrying a promotion that no longer exists — redemption not counted', {
+                    dedupKey, promotionId,
+                });
+                return;
+            }
+            const capped = promotion.maxRedemptions !== null && promotion.maxRedemptions !== undefined;
+            const counted = await this.repositoriesRegistry.atomicGuardedMutation(CoreResourceType.PROMOTIONS, capped ? { _id: promotionId, timesRedeemed: { $lt: promotion.maxRedemptions } } : { _id: promotionId }, { increment: { timesRedeemed: 1 } }, execCtx);
+            if (!counted && capped) {
+                this.log('error', 'Promotion honoured BEYOND its redemption cap: the purchase completed and the count could not be incremented', {
+                    dedupKey, promotionId, maxRedemptions: promotion.maxRedemptions,
+                });
+            }
+        }
+        catch (error) {
+            this.log('error', 'Failed to count a promotion redemption for a completed checkout', {
+                dedupKey, promotionId, message: error.message,
+            });
+        }
+    }
     async findSubscriptionByProviderId(subscriptionVariant, execCtx, providerSubscriptionId) {
         try {
             const items = await this.servicesRegistry.list(subscriptionVariant, execCtx, { providerSubscriptionId });