@mohasinac/appkit 4.58.0 → 4.60.0

package/dist/features/gateway-events/repository/gateway-events.repository.js

@@ -0,0 +1,274 @@
+import { BaseRepository, applySieveToFirestore, parseSieveDateValue, prepareForFirestore, } from "../../../providers/db-firebase/index.js";
+import { normalizeError } from "../../../errors/normalize.js";
+import { GATEWAY_EVENTS_COLLECTION, GATEWAY_EVENT_ERROR_MAX_BYTES, GATEWAY_EVENT_FIELDS, GATEWAY_EVENT_LEASE_SECONDS, GATEWAY_EVENT_RETENTION_DAYS, createGatewayEventId, } from "../schemas/firestore.js";
+/** gRPC `ALREADY_EXISTS`. The one failure of `.create()` that means "duplicate". */
+const GRPC_ALREADY_EXISTS = 6;
+/**
+ * Is this the specific "a document with that id already exists" failure, as
+ * opposed to any other write failure?
+ *
+ * 🛑 THIS DISTINCTION IS THE WHOLE POINT, and it is where the inbox differs
+ * from every other `.create()` claim in the codebase.
+ *
+ * `refunds/actions.ts` catches *every* error from its claim and treats it as a
+ * duplicate — and that is correct THERE, because the cost of being wrong is
+ * issuing a second real refund, so it must fail CLOSED.
+ *
+ * Here the cost of being wrong is inverted: treating a permissions error or a
+ * Firestore outage as "already have it" would make the route ack 200 and the
+ * event would be **silently lost** — which is the exact failure this collection
+ * exists to prevent. So the inbox fails OPEN: anything that is not
+ * ALREADY_EXISTS propagates, the route answers 503, and the gateway sends it
+ * again.
+ *
+ * Same primitive, opposite failure direction, because the asymmetry of harm is
+ * opposite. Do not "unify" these two call sites.
+ */
+function isAlreadyExists(err) {
+    if (typeof err !== "object" || err === null)
+        return false;
+    const code = err.code;
+    if (code === GRPC_ALREADY_EXISTS)
+        return true;
+    /*
+     * The Admin SDK has also surfaced this as a string code and as a plain
+     * message depending on version and transport. Checked in addition to, never
+     * instead of, the numeric code — a message test alone is the kind of
+     * stringly-typed guard that breaks silently on an SDK bump.
+     */
+    if (code === "already-exists" || code === "ALREADY_EXISTS")
+        return true;
+    const message = err.message;
+    return typeof message === "string" && message.includes("ALREADY_EXISTS");
+}
+function truncate(value, maxBytes) {
+    if (!value)
+        return undefined;
+    return value.length <= maxBytes ? value : value.slice(0, maxBytes);
+}
+export class GatewayEventsRepository extends BaseRepository {
+    constructor() {
+        super(GATEWAY_EVENTS_COLLECTION);
+    }
+    /**
+     * Persist-and-claim in one write. Returns `claimed: false` for a duplicate.
+     *
+     * 🛑 THROWS on any write failure that is not a duplicate — see
+     * `isAlreadyExists`. The caller must translate that into a 503 so the gateway
+     * redelivers; swallowing it is how an event is lost.
+     */
+    async claim(input) {
+        const now = input.now ?? new Date();
+        const id = createGatewayEventId(input.gateway, input.providerEventId, input.bodySha256);
+        const doc = {
+            id,
+            gateway: input.gateway,
+            rawEvent: input.rawEvent,
+            kind: input.kind,
+            status: "received",
+            bodySha256: input.bodySha256,
+            ...(input.providerEventId ? { providerEventId: input.providerEventId } : {}),
+            ...(input.gatewayOrderId ? { gatewayOrderId: input.gatewayOrderId } : {}),
+            ...(input.gatewayPaymentId ? { gatewayPaymentId: input.gatewayPaymentId } : {}),
+            ...(typeof input.amount === "number" ? { amount: input.amount } : {}),
+            ...(input.payload ? { payload: input.payload } : {}),
+            ...(input.payloadTruncated ? { payloadTruncated: true } : {}),
+            receivedAt: now,
+            claimedAt: now,
+            leaseExpiresAt: new Date(now.getTime() + GATEWAY_EVENT_LEASE_SECONDS * 1000),
+            attempts: 1,
+            expiresAt: new Date(now.getTime() + GATEWAY_EVENT_RETENTION_DAYS * 86400000),
+            createdAt: now,
+            updatedAt: now,
+        };
+        try {
+            await this.getCollection().doc(id).create(prepareForFirestore(doc));
+            return { claimed: true, id, doc };
+        }
+        catch (err) {
+            if (isAlreadyExists(err)) {
+                void normalizeError(err);
+                return { claimed: false, id };
+            }
+            /*
+             * Not a duplicate — a real write failure. Normalised for the log trail
+             * and then RETHROWN, deliberately: the inbox holds no record, so the only
+             * honest answer to the gateway is "send it again".
+             */
+            void normalizeError(err);
+            throw err;
+        }
+    }
+    /** Flip a claimed row to its outcome. Never throws — see the docstring. */
+    async settle(id, input) {
+        const now = input.now ?? new Date();
+        try {
+            await this.getCollection()
+                .doc(id)
+                .update({
+                status: input.status,
+                processedAt: now,
+                updatedAt: now,
+                ...(input.orderIds?.length ? { orderIds: input.orderIds } : {}),
+                ...(input.lastError
+                    ? { lastError: truncate(input.lastError, GATEWAY_EVENT_ERROR_MAX_BYTES) }
+                    : {}),
+                ...(typeof input.terminal === "boolean" ? { terminal: input.terminal } : {}),
+            });
+        }
+        catch (err) {
+            /*
+             * Swallowed on purpose, and the asymmetry with `claim` is the reason: by
+             * the time we settle, the EVENT IS ALREADY DURABLE and the work is
+             * already done. Rethrowing would turn a bookkeeping failure into a 5xx
+             * and have the gateway redeliver an event we successfully processed. The
+             * row is left `received` with a lease that expires, which the stuck-event
+             * sweep then picks up — the right failure mode.
+             */
+            void normalizeError(err);
+            console.error("[gatewayEvents.settle] failed to persist outcome", { id, err });
+        }
+    }
+    /**
+     * R1's query: rows claimed but never settled, whose lease has lapsed.
+     *
+     * 🛑 `status` is an `in` equality and `leaseExpiresAt` the single inequality,
+     * which is the only shape Firestore will serve without demanding the
+     * inequality field lead the `orderBy` (Root Cause #59). Ordered by
+     * `leaseExpiresAt` for exactly that reason — not by `receivedAt`, which would
+     * need an index in an order nobody declares.
+     */
+    async listStuck(now, limit = 20) {
+        const snap = await this.getCollection()
+            .where(GATEWAY_EVENT_FIELDS.STATUS, "in", ["received", "processing"])
+            .where(GATEWAY_EVENT_FIELDS.LEASE_EXPIRES_AT, "<", now)
+            .orderBy(GATEWAY_EVENT_FIELDS.LEASE_EXPIRES_AT, "asc")
+            .limit(limit)
+            .get();
+        return snap.docs.map((d) => this.mapDoc(d));
+    }
+    /**
+     * Make the NEXT delivery of this event be accepted instead of acked.
+     *
+     * ## 🛑 IT DOES NOT REPROCESS ANYTHING, AND THE NAME SAYS SO
+     *
+     * There is no way to replay a gateway event from here, deliberately. R1's own
+     * header gives the reason: re-dispatching from a job or an admin button would
+     * mean duplicating the webhook route's entire switch — and its RTDB
+     * signalling — in a second place, which is Root Cause #75 on the dispatch
+     * axis. The webhook route is the only thing that knows how to handle an event.
+     *
+     * So this reopens the DOOR and nothing more. The operator still has to press
+     * Resend in the gateway dashboard (or wait for the gateway's own retry); this
+     * is what stops the inbox from refusing that redelivery as a duplicate.
+     *
+     * Anything calling this must tell the operator that second step is theirs. A
+     * button labelled "Reprocess" that only did this would be the worst kind of
+     * half-truth — it would look like the work had been done.
+     *
+     * ## Why these four fields, read off `resolveDuplicateDelivery`'s table
+     *
+     * That function decides ack-vs-redispatch, and three of its branches would
+     * otherwise swallow the redelivery:
+     *
+     *   · `processed` / `ignored` / `conflict` → always ack. Hence `status` is
+     *     reset to `failed`, the one non-terminal state that redispatches.
+     *   · `failed` + `terminal: true` → ack. Hence `terminal: false`.
+     *   · lapsed lease but `attempts >= GATEWAY_EVENT_MAX_ATTEMPTS` → ack. Hence
+     *     `attempts: 0`.
+     *
+     * And the lease is set to `now`, i.e. already expired, because the
+     * received/processing branch is decided by the LEASE rather than the status —
+     * a live lease means "another worker has this" and must keep acking.
+     *
+     * `lastError` records that a human did this, so the row does not read as a
+     * fresh transient failure to whoever looks next.
+     */
+    async reopenForRedelivery(id, actorUid, now = new Date()) {
+        await this.getCollection()
+            .doc(id)
+            .update({
+            status: "failed",
+            terminal: false,
+            attempts: 0,
+            claimedAt: now,
+            // Already lapsed — see the docstring: the lease, not the status, is what
+            // decides the received/processing branch.
+            leaseExpiresAt: now,
+            lastError: `Reopened for redelivery by ${actorUid}`,
+            updatedAt: now,
+        });
+    }
+    /** Take over a lapsed lease and count the attempt. */
+    async renewLease(id, attempts, now) {
+        await this.getCollection()
+            .doc(id)
+            .update({
+            status: "processing",
+            attempts: attempts + 1,
+            claimedAt: now,
+            leaseExpiresAt: new Date(now.getTime() + GATEWAY_EVENT_LEASE_SECONDS * 1000),
+            updatedAt: now,
+        });
+    }
+    /** Every event for one gateway order — the reconciliation join. */
+    async findByGatewayOrderId(gatewayOrderId) {
+        const snap = await this.getCollection()
+            .where(GATEWAY_EVENT_FIELDS.GATEWAY_ORDER_ID, "==", gatewayOrderId)
+            .orderBy(GATEWAY_EVENT_FIELDS.RECEIVED_AT, "desc")
+            .limit(50)
+            .get();
+        return snap.docs.map((d) => this.mapDoc(d));
+    }
+    /**
+     * Retention: refs for rows past `expiresAt`, for the caller's batch delete.
+     * Mirrors `sessionRepository.getExpiredRefs` so `dailyDataCleanup` composes
+     * it the same way it composes sessions and tokens.
+     */
+    async getExpiredRefs(now, limit = 500) {
+        const snap = await this.getCollection()
+            .where(GATEWAY_EVENT_FIELDS.EXPIRES_AT, "<", now)
+            .limit(limit)
+            .get();
+        return snap.docs.map((d) => d.ref);
+    }
+    async list(model) {
+        return applySieveToFirestore({
+            baseQuery: this.getCollection(),
+            model,
+            fields: GatewayEventsRepository.SIEVE_FIELDS,
+        });
+    }
+}
+/**
+ * 🛑 Every date field carries `parseValue: parseSieveDateValue`, and it is not
+ * optional: these are stored Firestore Timestamps, and sievejs' default
+ * `convertValue()` only coerces `"true"`/`"false"`/numeric strings. An ISO
+ * string therefore reaches the adapter unchanged and becomes
+ * `.where("receivedAt", ">=", "<iso-string>")` — a type mismatch against a
+ * Timestamp, which matches **zero documents with no error at all**
+ * (Root Cause #47). `audit-sieve-date-fields` blocks the omission.
+ */
+GatewayEventsRepository.SIEVE_FIELDS = {
+    gateway: { canFilter: true, canSort: false },
+    rawEvent: { canFilter: true, canSort: false },
+    kind: { canFilter: true, canSort: false },
+    status: { canFilter: true, canSort: false },
+    terminal: { canFilter: true, canSort: false },
+    providerEventId: { canFilter: true, canSort: false },
+    gatewayOrderId: { canFilter: true, canSort: false },
+    gatewayPaymentId: { canFilter: true, canSort: false },
+    attempts: { canFilter: true, canSort: true },
+    receivedAt: { canFilter: true, canSort: true, parseValue: parseSieveDateValue },
+    claimedAt: { canFilter: true, canSort: true, parseValue: parseSieveDateValue },
+    leaseExpiresAt: { canFilter: true, canSort: true, parseValue: parseSieveDateValue },
+    processedAt: { canFilter: true, canSort: true, parseValue: parseSieveDateValue },
+    expiresAt: { canFilter: true, canSort: true, parseValue: parseSieveDateValue },
+};
+let cached = null;
+/** Lazy singleton — avoids cold-start admin SDK init when nothing is ingesting. */
+export function gatewayEventsRepository() {
+    if (!cached)
+        cached = new GatewayEventsRepository();
+    return cached;
+}

package/dist/features/gateway-events/schemas/firestore.d.ts

@@ -0,0 +1,217 @@
+/**
+ * `gatewayEvents` — the durable inbox for every payment-gateway webhook.
+ *
+ * ## Why this collection exists
+ *
+ * Before it, a webhook was a request and nothing else. If the handler threw, or
+ * the Lambda died mid-dispatch, or the event type was one we had not written a
+ * `case` for, **the event was gone** — there was no record it had ever arrived.
+ * That is what made the 2026-10-21 incident undiagnosable (₹2,511.80 captured,
+ * no order, a manual refund): the only trace was a `serverLogger.warn` in a log
+ * buffer that drops at ~4 KB/s, and a Server Action's throw never reaches
+ * `onRequestError` because `wrapAction` returns rather than throws
+ * (Root Cause #87).
+ *
+ * The inbox inverts that. Persist, then act, then ack — so a crash leaves a row
+ * with an expired lease that a reconciler finds within 5 minutes, instead of
+ * leaving nothing at all.
+ *
+ * ## The name
+ *
+ * 🛑 Not `paymentEvents` — that collides with `RTDB_PATHS.PAYMENT_EVENTS`, a
+ * short-lived Realtime Database signal channel that is a completely different
+ * thing (a browser-facing ping, pruned every 15 minutes). Not `disputes` or
+ * `incidents` either: both names are taken, by a buyer-contests-auto-approval
+ * flow and a `scammerProfiles` subcollection respectively.
+ *
+ * ## Dedupe: the document id IS the key
+ *
+ * `${gateway}_${providerEventId ?? bodySha256.slice(0,32)}`, written with
+ * Firestore's `.create()`, which **fails if the document exists**. That is the
+ * same at-most-once primitive `gatewayOrderClaims` and `refundClaims` already
+ * use, and it needs no transaction and no read.
+ *
+ * 🛑 **The `bodySha256` fallback is load-bearing, not a nicety.** Razorpay
+ * sends `x-razorpay-event-id` and it is believed stable across redeliveries —
+ * but that has NOT been verified against a live delivery, and verifying it
+ * needs a real webhook. So the fallback means a missing or unstable header
+ * degrades to body-identity dedupe rather than to *no* dedupe. PhonePe needs
+ * that branch regardless: it documents no event id, and its bodies carry
+ * `merchantOrderId` + `state`, so two identical bodies genuinely are the same
+ * logical transition.
+ *
+ * ## Write amplification
+ *
+ * 2 writes + 0 reads for a new event; 1 failed create for a duplicate. At 100
+ * events/day that is ~1% of the free daily write budget.
+ *
+ * 🛑 **Do not "optimise" this with an allowlist of event types that get a
+ * durable row.** That reintroduces the exact gap this collection closes — the
+ * unhandled event is the one you most want a record of, because it is the one
+ * no code path is watching. The correct lever for volume is unsubscribing
+ * unwanted types in the gateway's own dashboard.
+ */
+import type { BaseDocument } from "../../../_internal/shared/types/base-document";
+import type { FirestoreDocument } from "../../../schemas/types";
+export declare const GATEWAY_EVENTS_COLLECTION = "gatewayEvents";
+/**
+ * What the event is about, with the gateway's vocabulary already resolved.
+ *
+ * Deliberately the same five values the webhook route's own `NormalisedEvent`
+ * uses, so the route classifies once and both the inbox and the dispatcher read
+ * the same answer. `"dispute"` and `"refund"` have no producer until Phase 3
+ * widens `normaliseRazorpayEvent` — they are declared here first **on purpose**:
+ * a `payment.dispute.created` arriving today lands as `kind: "other"` with its
+ * `rawEvent` intact and is therefore recoverable, rather than vanishing.
+ */
+export type GatewayEventKind = "paid" | "failed" | "dispute" | "refund" | "other";
+/**
+ * Lifecycle. Every value is reachable and each means something distinct:
+ *
+ * | value        | meaning |
+ * |---|---|
+ * | `received`   | persisted and claimed; dispatch has not returned yet |
+ * | `processing` | re-dispatched by the stuck-event sweep (attempt ≥ 2) |
+ * | `processed`  | the handler succeeded |
+ * | `ignored`    | an event type we do not handle — recorded verbatim, not dropped |
+ * | `conflict`   | a LATE event whose transition would regress the order |
+ * | `failed`     | the handler threw; `terminal` says whether a retry can help |
+ *
+ * 🛑 `conflict` is not an error state. A late `order.paid` arriving after the
+ * order shipped is not *wrong*, it is *out of date* — and asking the gateway to
+ * retry a regression it can never win is the pathology the webhook route's own
+ * header warns about. It acks 200 and records the conflict for a human.
+ */
+export type GatewayEventStatus = "received" | "processing" | "processed" | "ignored" | "conflict" | "failed";
+export interface GatewayEventDocument extends BaseDocument {
+    /** `payment.name` — "razorpay" | "phonepe" | "manual". */
+    gateway: string;
+    /** The gateway's own event string, verbatim, e.g. `payment.dispute.created`. */
+    rawEvent: string;
+    kind: GatewayEventKind;
+    status: GatewayEventStatus;
+    /**
+     * Set with `status: "failed"` to mean "a retry cannot help" — a 4xx-class
+     * fault, a validation refusal, an exhausted attempt budget. Absent means
+     * unknown, which the sweep treats as retryable.
+     */
+    terminal?: boolean;
+    /** `x-razorpay-event-id` when the gateway sent one. Absent for PhonePe. */
+    providerEventId?: string;
+    /**
+     * sha256 of the raw body. Always present, even when `providerEventId` is —
+     * it is the dedupe fallback AND the integrity check that survives payload
+     * redaction, so the row can prove what arrived without storing it.
+     */
+    bodySha256: string;
+    gatewayOrderId?: string;
+    gatewayPaymentId?: string;
+    /**
+     * Decimal RUPEES, never subunits. Converted at the provider boundary with
+     * `paiseToRupees` — `audit-money-units` blocks both the raw arithmetic and
+     * the word for the subunit appearing in a comment or a label.
+     */
+    amount?: number;
+    /**
+     * The reconciliation join key: which of OUR orders this event produced or
+     * concerns. Empty on an `ignored` row and on a `failed` one that never got
+     * far enough to place anything.
+     */
+    orderIds?: string[];
+    receivedAt: Date;
+    /**
+     * 🛑 `claimedAt`, `leaseExpiresAt` and `expiresAt` are all REQUIRED, and that
+     * is a correctness requirement rather than tidiness — Root Cause #100.
+     *
+     * The stuck-event sweep queries `leaseExpiresAt < now`, and the retention
+     * sweep queries `expiresAt < now`. **A Firestore inequality excludes every
+     * document that LACKS the field**, so an optional lease would make the
+     * detector structurally unable to see exactly the rows it exists to find:
+     * an event that crashed before claiming would be invisible to the thing
+     * watching for events that crashed. Same for retention — an optional
+     * `expiresAt` means rows that accumulate forever while the sweep reports
+     * success.
+     *
+     * The create therefore always sets all three. There is no "unclaimed" state.
+     */
+    claimedAt: Date;
+    leaseExpiresAt: Date;
+    processedAt?: Date;
+    /** 1 on create; incremented by each re-dispatch. */
+    attempts: number;
+    /** Truncated. Never the raw body — that is what `bodySha256` is for. */
+    lastError?: string;
+    /** Retention anchor. 90 days — see `GATEWAY_EVENT_RETENTION_DAYS`. */
+    expiresAt: Date;
+    /**
+     * A REDACTED projection of the body, never the body itself.
+     *
+     * Razorpay payment entities carry `email`, `contact`, `card.last4`, `vpa` and
+     * `bank`. `redactGatewayPayload` strips those recursively and caps the
+     * result; `bodySha256` preserves integrity regardless, so nothing is lost
+     * that a diagnosis actually needs.
+     */
+    payload?: FirestoreDocument;
+    /** True when redaction hit the size cap, so a reader knows it is partial. */
+    payloadTruncated?: boolean;
+}
+export declare const GATEWAY_EVENT_FIELDS: {
+    readonly ID: "id";
+    readonly GATEWAY: "gateway";
+    readonly RAW_EVENT: "rawEvent";
+    readonly KIND: "kind";
+    readonly STATUS: "status";
+    readonly TERMINAL: "terminal";
+    readonly PROVIDER_EVENT_ID: "providerEventId";
+    readonly BODY_SHA256: "bodySha256";
+    readonly GATEWAY_ORDER_ID: "gatewayOrderId";
+    readonly GATEWAY_PAYMENT_ID: "gatewayPaymentId";
+    readonly AMOUNT: "amount";
+    readonly ORDER_IDS: "orderIds";
+    readonly RECEIVED_AT: "receivedAt";
+    readonly CLAIMED_AT: "claimedAt";
+    readonly LEASE_EXPIRES_AT: "leaseExpiresAt";
+    readonly PROCESSED_AT: "processedAt";
+    readonly ATTEMPTS: "attempts";
+    readonly LAST_ERROR: "lastError";
+    readonly EXPIRES_AT: "expiresAt";
+};
+/**
+ * 90 days, deliberately longer than `serverErrors`' 30.
+ *
+ * A chargeback can arrive 120+ days after the payment it concerns, and the
+ * first thing anyone wants then is the original `order.paid` event. 90 days
+ * does not cover the full chargeback horizon — nothing short of indefinite
+ * would — but it covers the window in which an event is still the cheapest way
+ * to answer "what did the gateway actually tell us", and a row referenced by an
+ * open case is excluded from the sweep regardless.
+ */
+export declare const GATEWAY_EVENT_RETENTION_DAYS = 90;
+/**
+ * How long a dispatch may hold its claim before the stuck-event sweep assumes
+ * the worker died.
+ *
+ * 🛑 Must exceed the route's own `maxDuration` (60s), or the sweep re-dispatches
+ * an event that is still legitimately in flight — which, for a `paid` event,
+ * means two concurrent order placements. The placement claim makes that a no-op
+ * rather than a double order, but relying on a downstream guard to cover a
+ * timing bug we chose is the wrong order of defences.
+ */
+export declare const GATEWAY_EVENT_LEASE_SECONDS = 120;
+/** Attempts after which the sweep stops re-dispatching and opens a case. */
+export declare const GATEWAY_EVENT_MAX_ATTEMPTS = 5;
+/** Byte budget for the redacted payload. */
+export declare const GATEWAY_EVENT_PAYLOAD_MAX_BYTES = 32768;
+/** Byte budget for `lastError`. */
+export declare const GATEWAY_EVENT_ERROR_MAX_BYTES = 2048;
+/**
+ * Build the dedupe id. Exported so the route, the ingest helper and any future
+ * reconciler all derive it the same way — two spellings of a dedupe key is a
+ * dedupe that silently does not work.
+ *
+ * `providerEventId` is preferred because it is stable across redeliveries of
+ * the SAME event even when the body is re-serialised; the digest is the
+ * fallback. Both are prefixed with the gateway so two providers cannot collide
+ * on a shared id format.
+ */
+export declare function createGatewayEventId(gateway: string, providerEventId: string | undefined, bodySha256: string): string;

package/dist/features/gateway-events/schemas/firestore.js

@@ -0,0 +1,125 @@
+/**
+ * `gatewayEvents` — the durable inbox for every payment-gateway webhook.
+ *
+ * ## Why this collection exists
+ *
+ * Before it, a webhook was a request and nothing else. If the handler threw, or
+ * the Lambda died mid-dispatch, or the event type was one we had not written a
+ * `case` for, **the event was gone** — there was no record it had ever arrived.
+ * That is what made the 2026-10-21 incident undiagnosable (₹2,511.80 captured,
+ * no order, a manual refund): the only trace was a `serverLogger.warn` in a log
+ * buffer that drops at ~4 KB/s, and a Server Action's throw never reaches
+ * `onRequestError` because `wrapAction` returns rather than throws
+ * (Root Cause #87).
+ *
+ * The inbox inverts that. Persist, then act, then ack — so a crash leaves a row
+ * with an expired lease that a reconciler finds within 5 minutes, instead of
+ * leaving nothing at all.
+ *
+ * ## The name
+ *
+ * 🛑 Not `paymentEvents` — that collides with `RTDB_PATHS.PAYMENT_EVENTS`, a
+ * short-lived Realtime Database signal channel that is a completely different
+ * thing (a browser-facing ping, pruned every 15 minutes). Not `disputes` or
+ * `incidents` either: both names are taken, by a buyer-contests-auto-approval
+ * flow and a `scammerProfiles` subcollection respectively.
+ *
+ * ## Dedupe: the document id IS the key
+ *
+ * `${gateway}_${providerEventId ?? bodySha256.slice(0,32)}`, written with
+ * Firestore's `.create()`, which **fails if the document exists**. That is the
+ * same at-most-once primitive `gatewayOrderClaims` and `refundClaims` already
+ * use, and it needs no transaction and no read.
+ *
+ * 🛑 **The `bodySha256` fallback is load-bearing, not a nicety.** Razorpay
+ * sends `x-razorpay-event-id` and it is believed stable across redeliveries —
+ * but that has NOT been verified against a live delivery, and verifying it
+ * needs a real webhook. So the fallback means a missing or unstable header
+ * degrades to body-identity dedupe rather than to *no* dedupe. PhonePe needs
+ * that branch regardless: it documents no event id, and its bodies carry
+ * `merchantOrderId` + `state`, so two identical bodies genuinely are the same
+ * logical transition.
+ *
+ * ## Write amplification
+ *
+ * 2 writes + 0 reads for a new event; 1 failed create for a duplicate. At 100
+ * events/day that is ~1% of the free daily write budget.
+ *
+ * 🛑 **Do not "optimise" this with an allowlist of event types that get a
+ * durable row.** That reintroduces the exact gap this collection closes — the
+ * unhandled event is the one you most want a record of, because it is the one
+ * no code path is watching. The correct lever for volume is unsubscribing
+ * unwanted types in the gateway's own dashboard.
+ */
+export const GATEWAY_EVENTS_COLLECTION = "gatewayEvents";
+export const GATEWAY_EVENT_FIELDS = {
+    ID: "id",
+    GATEWAY: "gateway",
+    RAW_EVENT: "rawEvent",
+    KIND: "kind",
+    STATUS: "status",
+    TERMINAL: "terminal",
+    PROVIDER_EVENT_ID: "providerEventId",
+    BODY_SHA256: "bodySha256",
+    GATEWAY_ORDER_ID: "gatewayOrderId",
+    GATEWAY_PAYMENT_ID: "gatewayPaymentId",
+    AMOUNT: "amount",
+    ORDER_IDS: "orderIds",
+    RECEIVED_AT: "receivedAt",
+    CLAIMED_AT: "claimedAt",
+    LEASE_EXPIRES_AT: "leaseExpiresAt",
+    PROCESSED_AT: "processedAt",
+    ATTEMPTS: "attempts",
+    LAST_ERROR: "lastError",
+    EXPIRES_AT: "expiresAt",
+};
+/**
+ * 90 days, deliberately longer than `serverErrors`' 30.
+ *
+ * A chargeback can arrive 120+ days after the payment it concerns, and the
+ * first thing anyone wants then is the original `order.paid` event. 90 days
+ * does not cover the full chargeback horizon — nothing short of indefinite
+ * would — but it covers the window in which an event is still the cheapest way
+ * to answer "what did the gateway actually tell us", and a row referenced by an
+ * open case is excluded from the sweep regardless.
+ */
+export const GATEWAY_EVENT_RETENTION_DAYS = 90;
+/**
+ * How long a dispatch may hold its claim before the stuck-event sweep assumes
+ * the worker died.
+ *
+ * 🛑 Must exceed the route's own `maxDuration` (60s), or the sweep re-dispatches
+ * an event that is still legitimately in flight — which, for a `paid` event,
+ * means two concurrent order placements. The placement claim makes that a no-op
+ * rather than a double order, but relying on a downstream guard to cover a
+ * timing bug we chose is the wrong order of defences.
+ */
+export const GATEWAY_EVENT_LEASE_SECONDS = 120;
+/** Attempts after which the sweep stops re-dispatching and opens a case. */
+export const GATEWAY_EVENT_MAX_ATTEMPTS = 5;
+/** Byte budget for the redacted payload. */
+export const GATEWAY_EVENT_PAYLOAD_MAX_BYTES = 32768;
+/** Byte budget for `lastError`. */
+export const GATEWAY_EVENT_ERROR_MAX_BYTES = 2048;
+/**
+ * Build the dedupe id. Exported so the route, the ingest helper and any future
+ * reconciler all derive it the same way — two spellings of a dedupe key is a
+ * dedupe that silently does not work.
+ *
+ * `providerEventId` is preferred because it is stable across redeliveries of
+ * the SAME event even when the body is re-serialised; the digest is the
+ * fallback. Both are prefixed with the gateway so two providers cannot collide
+ * on a shared id format.
+ */
+export function createGatewayEventId(gateway, providerEventId, bodySha256) {
+    const key = providerEventId?.trim() || bodySha256.slice(0, 32);
+    /*
+     * Firestore ids may not contain "/" and must not be "." or "..". A gateway
+     * name is ours and safe, but a provider event id is THEIRS — so it is
+     * sanitised rather than trusted. Anything outside the safe set collapses to
+     * "_", which can at worst merge two events that differ only by an unsafe
+     * character; that is strictly better than a write that throws on the one
+     * path whose whole job is to not lose the event.
+     */
+    return `${gateway}_${key}`.replace(/[^A-Za-z0-9_.:-]/g, "_").slice(0, 1500);
+}