@mohasinac/appkit 4.59.0 → 4.60.1

package/dist/_internal/server/features/checkout/supplier-identity.js

@@ -53,7 +53,24 @@ export function resolveSupplierIdentity(store, settings) {
      * A seller with a GSTIN and no legal name is a data gap worth seeing as a
      * blank on the invoice, not one worth papering over with the wrong name.
      */
-    if (sellerGstin) {
+    /*
+     * 🛑 G8 — `&& settings?.gst?.enabled`, added 2026-10-21.
+     *
+     * This branch returned on the GSTIN ALONE while the platform branch below
+     * was correctly gated on `gst.enabled`. So with GST disabled, a seller who
+     * happens to have a GSTIN still got it stamped onto the order — producing a
+     * document that LOOKS like a tax invoice, names a registration, and carries
+     * **no tax at all**, because the whole GST computation is skipped when the
+     * flag is off (`previewCheckoutPricing` and `createOrderForGroup` both gate
+     * their `sumGroupGst` call on it).
+     *
+     * An invoice asserting a GSTIN with zero tax on it is worse than a plain
+     * invoice: it implies a taxable supply was made and nil tax was due. The two
+     * branches now agree that `gst.enabled` is the switch for whether this is a
+     * tax document at all — which is what that flag already means everywhere
+     * else, and what the platform branch's own comment below says.
+     */
+    if (sellerGstin && settings?.gst?.enabled) {
         return {
             gstin: sellerGstin,
             legalName: trimmed(store?.legalName),

package/dist/_internal/server/features/gateway-events/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * gateway-events — server surface.
+ *
+ * 🛑 A barrel for ONE feature's public surface, not a convenience re-export
+ * hub (Root Cause #18). Three symbols, all consumed by the webhook route; the
+ * repository is imported directly by anything that queries, because a
+ * reconciler has no business pulling the redactor into its graph.
+ */
+export { ingestGatewayEvent, settleGatewayEvent, statusForDispatch, resolveDuplicateDelivery, type IngestGatewayEventInput, type SettleGatewayEventInput, type DuplicateAction, type DuplicateResolution, } from "./ingest";
+export { redactGatewayPayload, type RedactResult } from "./redact";

package/dist/_internal/server/features/gateway-events/index.js

@@ -0,0 +1,10 @@
+/**
+ * gateway-events — server surface.
+ *
+ * 🛑 A barrel for ONE feature's public surface, not a convenience re-export
+ * hub (Root Cause #18). Three symbols, all consumed by the webhook route; the
+ * repository is imported directly by anything that queries, because a
+ * reconciler has no business pulling the redactor into its graph.
+ */
+export { ingestGatewayEvent, settleGatewayEvent, statusForDispatch, resolveDuplicateDelivery, } from "./ingest.js";
+export { redactGatewayPayload } from "./redact.js";

package/dist/_internal/server/features/gateway-events/ingest.d.ts

@@ -0,0 +1,127 @@
+/**
+ * The gateway-event inbox: persist, then act, then ack.
+ *
+ * ## The ordering, and why it is this way round
+ *
+ * ```
+ *   verify signature          ← already done by the route, see below
+ *   parse + normalise
+ *   ingestGatewayEvent()      ← 1 write: persist AND claim, atomically
+ *   dispatch                  ← place the order / signal RTDB / nothing
+ *   settleGatewayEvent()      ← 1 write: the outcome
+ *   ack
+ * ```
+ *
+ * Total cost: 2 writes, 0 reads for a new event; 1 failed create for a
+ * duplicate. ~80 ms against the route's 60,000 ms budget.
+ *
+ * 🛑 **Ingest MUST sit below the signature check**, and the webhook route
+ * carries a comment saying so at the rejection branch. An unauthenticated
+ * caller who can create Firestore documents by POSTing garbage is a write-quota
+ * denial-of-service with no authentication at all — on the one route in the
+ * application that accepts requests with no session. Persist after
+ * authentication, never before.
+ *
+ * ## What a crash leaves behind
+ *
+ * A row with `status: "received"` and a lease that expires in 120 s. That is
+ * the entire point: the 2026-10-21 incident left *nothing*, so there was no
+ * artefact to reconcile against and the first signal was a customer asking
+ * where their order was. Phase 4's R1 sweep queries exactly that shape every
+ * 5 minutes.
+ */
+import { type GatewayEventClaimResult } from "../../../../features/gateway-events/repository/gateway-events.repository";
+import { type GatewayEventKind, type GatewayEventStatus } from "../../../../features/gateway-events/schemas/firestore";
+export interface IngestGatewayEventInput {
+    /** `payment.name` — the provider that signed this delivery. */
+    gateway: string;
+    /** The raw request body, verbatim — the same string the signature covered. */
+    rawBody: string;
+    /** The parsed body. Passed in rather than re-parsed, so there is one parse. */
+    body: unknown;
+    /** The gateway's own event string, e.g. `order.paid`. */
+    rawEvent: string;
+    kind: GatewayEventKind;
+    providerEventId?: string;
+    gatewayOrderId?: string;
+    gatewayPaymentId?: string;
+    /** Decimal rupees. Convert at the provider boundary, never here. */
+    amount?: number;
+    now?: Date;
+}
+/**
+ * Persist and claim.
+ *
+ * 🛑 **Throws** when the write fails for any reason other than "already
+ * exists". The caller must answer **503** in that case — per the route's ack
+ * contract, we hold no record, so the only honest response is "send it again".
+ * Catching this and acking 200 loses the event, which is the failure this
+ * module exists to prevent.
+ */
+export declare function ingestGatewayEvent(input: IngestGatewayEventInput): Promise<GatewayEventClaimResult>;
+/**
+ * What to do about a delivery we have seen before.
+ *
+ * 🛑 THIS BRANCH EXISTS BECAUSE NAIVE DEDUPE WOULD HAVE BROKEN THE D4 FIX, and
+ * the interaction is not obvious until you trace the two mechanisms together.
+ *
+ * Phase 0 made a transient placement failure answer **500**, specifically so
+ * the gateway's own retry schedule becomes the safety net for a
+ * captured-but-unplaced payment. Razorpay then redelivers **the same event
+ * id**. So if "we already have a row for this id" meant "ack 200 and do
+ * nothing", the retry we deliberately asked for would be swallowed by the
+ * inbox — and a captured payment with no order would go back to being
+ * unrecoverable. The inbox would have made things *worse* than no inbox.
+ *
+ * So a duplicate is resolved by reading its row — the one read the write-
+ * amplification budget allows for this path — and the answer depends on where
+ * that row got to:
+ *
+ * | existing row | action | why |
+ * |---|---|---|
+ * | `processed` / `ignored` / `conflict` | **ack** | done; nothing a retry can add |
+ * | `failed` + `terminal: true` | **ack** | a retry cannot help; a human must look |
+ * | `failed` without `terminal` | **redispatch** | transient — this IS the retry we asked for |
+ * | `received`/`processing`, lease LIVE | **ack** | another worker has it; a 5xx would thundering-herd one order |
+ * | `received`/`processing`, lease LAPSED | **redispatch** | the previous worker died mid-flight |
+ * | row missing (raced its own deletion) | **redispatch** | treat as new rather than lose it |
+ */
+export type DuplicateAction = "ack" | "redispatch";
+export interface DuplicateResolution {
+    action: DuplicateAction;
+    /** Attempts recorded so far — the caller renews the lease with this. */
+    attempts: number;
+    status?: GatewayEventStatus;
+}
+export declare function resolveDuplicateDelivery(id: string, now?: Date): Promise<DuplicateResolution>;
+export interface SettleGatewayEventInput {
+    status: GatewayEventStatus;
+    orderIds?: string[];
+    lastError?: string;
+    terminal?: boolean;
+    now?: Date;
+}
+/**
+ * Record the outcome. Never throws — by this point the event is durable and the
+ * work is done, so a bookkeeping failure must not become a 5xx that makes the
+ * gateway redeliver an event we processed successfully. The row is left
+ * `received` with a lapsing lease, which the stuck-event sweep handles.
+ */
+export declare function settleGatewayEvent(id: string, input: SettleGatewayEventInput): Promise<void>;
+/**
+ * Translate a dispatch outcome into an inbox status.
+ *
+ * Kept here rather than inlined at the route so the mapping is stated once and
+ * both halves of the ack contract — the HTTP status the gateway sees and the
+ * row an operator reads — are derived from the same decision. Two hand-rolled
+ * copies of this would be Root Cause #75's shape on the observability axis:
+ * the row would say `processed` while the route answered 500.
+ */
+export declare function statusForDispatch(outcome: {
+    handled: boolean;
+    succeeded: boolean;
+    retryable: boolean;
+}): {
+    status: GatewayEventStatus;
+    terminal?: boolean;
+};

package/dist/_internal/server/features/gateway-events/ingest.js

@@ -0,0 +1,188 @@
+/**
+ * The gateway-event inbox: persist, then act, then ack.
+ *
+ * ## The ordering, and why it is this way round
+ *
+ * ```
+ *   verify signature          ← already done by the route, see below
+ *   parse + normalise
+ *   ingestGatewayEvent()      ← 1 write: persist AND claim, atomically
+ *   dispatch                  ← place the order / signal RTDB / nothing
+ *   settleGatewayEvent()      ← 1 write: the outcome
+ *   ack
+ * ```
+ *
+ * Total cost: 2 writes, 0 reads for a new event; 1 failed create for a
+ * duplicate. ~80 ms against the route's 60,000 ms budget.
+ *
+ * 🛑 **Ingest MUST sit below the signature check**, and the webhook route
+ * carries a comment saying so at the rejection branch. An unauthenticated
+ * caller who can create Firestore documents by POSTing garbage is a write-quota
+ * denial-of-service with no authentication at all — on the one route in the
+ * application that accepts requests with no session. Persist after
+ * authentication, never before.
+ *
+ * ## What a crash leaves behind
+ *
+ * A row with `status: "received"` and a lease that expires in 120 s. That is
+ * the entire point: the 2026-10-21 incident left *nothing*, so there was no
+ * artefact to reconcile against and the first signal was a customer asking
+ * where their order was. Phase 4's R1 sweep queries exactly that shape every
+ * 5 minutes.
+ */
+/*
+ * 🛑 `"crypto"`, NOT `"node:crypto"` — Root Cause #24. A top-level
+ * `node:`-prefixed import in any file reachable from `index.ts` or `client.ts`
+ * through ANY re-export chain hard-fails the Turbopack production build with
+ * `the chunking context (unknown) does not support external modules`, on every
+ * page, in production only. `next dev` tolerates it, so the mistake ships.
+ *
+ * This file is server-only today and so would probably survive the prefixed
+ * form — but "probably, today" is how that bug arrived the first time, and the
+ * bare specifier costs nothing. `refunds/actions.ts` uses the same spelling for
+ * the same reason.
+ */
+import { createHash } from "crypto";
+import { normalizeError } from "../../../../errors/normalize.js";
+import { serverLogger } from "../../../../monitoring/index.js";
+import { gatewayEventsRepository, } from "../../../../features/gateway-events/repository/gateway-events.repository.js";
+import { GATEWAY_EVENT_MAX_ATTEMPTS, } from "../../../../features/gateway-events/schemas/firestore.js";
+import { redactGatewayPayload } from "./redact.js";
+/**
+ * Persist and claim.
+ *
+ * 🛑 **Throws** when the write fails for any reason other than "already
+ * exists". The caller must answer **503** in that case — per the route's ack
+ * contract, we hold no record, so the only honest response is "send it again".
+ * Catching this and acking 200 loses the event, which is the failure this
+ * module exists to prevent.
+ */
+export async function ingestGatewayEvent(input) {
+    const bodySha256 = createHash("sha256").update(input.rawBody).digest("hex");
+    const { payload, truncated } = redactGatewayPayload(input.body);
+    const result = await gatewayEventsRepository().claim({
+        gateway: input.gateway,
+        rawEvent: input.rawEvent,
+        kind: input.kind,
+        bodySha256,
+        ...(input.providerEventId ? { providerEventId: input.providerEventId } : {}),
+        ...(input.gatewayOrderId ? { gatewayOrderId: input.gatewayOrderId } : {}),
+        ...(input.gatewayPaymentId ? { gatewayPaymentId: input.gatewayPaymentId } : {}),
+        ...(typeof input.amount === "number" ? { amount: input.amount } : {}),
+        payload,
+        ...(truncated ? { payloadTruncated: true } : {}),
+        ...(input.now ? { now: input.now } : {}),
+    });
+    if (!result.claimed) {
+        /*
+         * A redelivery, or a second event carrying an identical body. Logged at
+         * `info` because it is NORMAL traffic and not a fault — Razorpay's own
+         * Resend button produces it, and so does any at-least-once delivery
+         * schedule. The absence of a second row IS the feature working.
+         */
+        serverLogger.info("gatewayEvents: duplicate delivery — already have it", {
+            id: result.id,
+            rawEvent: input.rawEvent,
+        });
+    }
+    return result;
+}
+export async function resolveDuplicateDelivery(id, now = new Date()) {
+    const existing = await gatewayEventsRepository().findById(id);
+    if (!existing) {
+        /*
+         * The id exists (the create failed) but the row does not — a race with the
+         * retention sweep, or a delete between the two calls. Fail toward DOING THE
+         * WORK: re-dispatching an already-processed event is idempotent downstream
+         * (the placement claim makes it a no-op), whereas acking an event we have
+         * no record of is the loss this collection exists to prevent.
+         */
+        return { action: "redispatch", attempts: 1 };
+    }
+    if (existing.status === "processed" ||
+        existing.status === "ignored" ||
+        existing.status === "conflict") {
+        return { action: "ack", attempts: existing.attempts, status: existing.status };
+    }
+    if (existing.status === "failed") {
+        return {
+            action: existing.terminal === true ? "ack" : "redispatch",
+            attempts: existing.attempts,
+            status: existing.status,
+        };
+    }
+    // received | processing — decided by the lease, not by the status.
+    const leaseLive = existing.leaseExpiresAt.getTime() > now.getTime();
+    if (leaseLive) {
+        return { action: "ack", attempts: existing.attempts, status: existing.status };
+    }
+    if (existing.attempts >= GATEWAY_EVENT_MAX_ATTEMPTS) {
+        /*
+         * Budget exhausted. Ack rather than loop forever — the row is `received`
+         * with a lapsed lease and a maxed attempt count, which is exactly the shape
+         * Phase 4's R1 sweep escalates into a case.
+         */
+        return { action: "ack", attempts: existing.attempts, status: existing.status };
+    }
+    /*
+     * Taking over a dead worker's claim, so renew the lease HERE rather than
+     * leaving it to the caller.
+     *
+     * 🛑 This is not a lock and does not pretend to be: `renewLease` is a plain
+     * update, so two redeliveries arriving in the same instant can both read a
+     * lapsed lease and both decide to dispatch. Narrowing that window is worth
+     * one write; closing it would need a transaction, and a transaction here
+     * would buy nothing — the thing that actually makes a double dispatch safe is
+     * the placement claim in `verifyAndPlaceGatewayOrderAction`, which is
+     * at-most-once on the gateway order id and turns the second attempt into a
+     * no-op. Two guards for one hazard, and the downstream one is the real one.
+     */
+    try {
+        await gatewayEventsRepository().renewLease(id, existing.attempts, now);
+    }
+    catch (err) {
+        /*
+         * Could not renew. Dispatch anyway: the alternative is dropping a retry we
+         * explicitly asked the gateway for, and the row is already durable so the
+         * sweep can still find it. The lease is an optimisation, not a correctness
+         * boundary.
+         */
+        void normalizeError(err);
+        serverLogger.warn("gatewayEvents: lease renewal failed — dispatching regardless", { id });
+    }
+    return { action: "redispatch", attempts: existing.attempts, status: existing.status };
+}
+/**
+ * Record the outcome. Never throws — by this point the event is durable and the
+ * work is done, so a bookkeeping failure must not become a 5xx that makes the
+ * gateway redeliver an event we processed successfully. The row is left
+ * `received` with a lapsing lease, which the stuck-event sweep handles.
+ */
+export async function settleGatewayEvent(id, input) {
+    try {
+        await gatewayEventsRepository().settle(id, input);
+    }
+    catch (err) {
+        void normalizeError(err);
+        serverLogger.warn("gatewayEvents: settle failed — the stuck-event sweep will retry", {
+            id,
+            err,
+        });
+    }
+}
+/**
+ * Translate a dispatch outcome into an inbox status.
+ *
+ * Kept here rather than inlined at the route so the mapping is stated once and
+ * both halves of the ack contract — the HTTP status the gateway sees and the
+ * row an operator reads — are derived from the same decision. Two hand-rolled
+ * copies of this would be Root Cause #75's shape on the observability axis:
+ * the row would say `processed` while the route answered 500.
+ */
+export function statusForDispatch(outcome) {
+    if (!outcome.handled)
+        return { status: "ignored" };
+    if (outcome.succeeded)
+        return { status: "processed" };
+    return { status: "failed", terminal: !outcome.retryable };
+}

package/dist/_internal/server/features/gateway-events/redact.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Redact a gateway webhook body down to something safe to keep for 90 days.
+ *
+ * ## Why the raw body is never stored
+ *
+ * A Razorpay payment entity carries the buyer's `email`, `contact`,
+ * `card.last4`, `vpa` and `bank` — so persisting the body verbatim would make
+ * `gatewayEvents` a **new PII store**, with a 90-day retention, no encryption,
+ * and an admin table rendering it. That is a worse outcome than the problem the
+ * inbox solves.
+ *
+ * The integrity guarantee does not depend on keeping the body: `bodySha256` is
+ * computed over the verbatim bytes before redaction, so "is this the same event
+ * the gateway signed" stays answerable regardless of what the projection drops.
+ *
+ * ## Deny-list, and why that is defensible HERE specifically
+ *
+ * 🛑 Root Cause #70 is the incident where a deny-list projection published
+ * every field nobody thought to delete, and § "Public Data Projections" draws
+ * the rule: **a document field is private until someone names it public.** This
+ * redactor is a deny-list, which looks like the same mistake. It is not, for
+ * two reasons worth stating rather than assuming:
+ *
+ *   1. **The shape is THEIRS, not ours.** An allow-list requires enumerating
+ *      every field a gateway might send, across providers and across their
+ *      future API versions. A field we failed to anticipate would be *dropped*,
+ *      and the whole value of this row is being able to read a payload we did
+ *      not expect — that is what makes an unhandled event diagnosable. An
+ *      allow-list here optimises for the case that never needs diagnosing.
+ *   2. **The output is never published.** It reaches one admin maintenance
+ *      table behind `admin:maintenance:view-server-errors`. The field that got
+ *      away in #70 went to an *unauthenticated, edge-cached* public endpoint.
+ *
+ * The deny-list is therefore keyed on *categories of sensitive data* rather
+ * than on one provider's field names, and it matches **recursively on the key
+ * at every depth** — so `payload.payment.entity.card.last4` is caught by the
+ * `card` key without anyone having written that path down.
+ */
+import type { FirestoreDocument } from "../../../../schemas/types";
+/**
+ * `vpa` appears as a bare key AND embedded in strings like
+ * `"someone@okhdfcbank"`. The key test catches the former; nothing here tries
+ * to catch the latter, and that is a deliberate limit rather than an oversight:
+ * a value-scanning redactor over arbitrary provider JSON produces false
+ * positives on ids that merely contain "@", and a redactor that mangles the
+ * diagnostic data is worse than one with a documented edge.
+ *
+ * What covers the gap is that the *keys* carrying an address — `email`,
+ * `contact`, `vpa` — are all denied, so a value only survives if the gateway
+ * put a contact detail under a key none of us anticipated.
+ */
+export interface RedactResult {
+    payload: FirestoreDocument;
+    truncated: boolean;
+}
+/**
+ * Redact, then cap.
+ *
+ * 🛑 The cap is applied by MEASURING the serialised result and, if it is over
+ * budget, replacing it with a marker rather than by slicing the JSON string.
+ * A sliced JSON string is not JSON — it would be stored as a truncated blob
+ * that no reader can parse, which is a field that looks present and is
+ * unusable. A marker plus `payloadTruncated: true` tells the reader exactly
+ * what happened, and `bodySha256` still proves what arrived.
+ */
+export declare function redactGatewayPayload(body: unknown): RedactResult;

package/dist/_internal/server/features/gateway-events/redact.js

@@ -0,0 +1,151 @@
+/**
+ * Redact a gateway webhook body down to something safe to keep for 90 days.
+ *
+ * ## Why the raw body is never stored
+ *
+ * A Razorpay payment entity carries the buyer's `email`, `contact`,
+ * `card.last4`, `vpa` and `bank` — so persisting the body verbatim would make
+ * `gatewayEvents` a **new PII store**, with a 90-day retention, no encryption,
+ * and an admin table rendering it. That is a worse outcome than the problem the
+ * inbox solves.
+ *
+ * The integrity guarantee does not depend on keeping the body: `bodySha256` is
+ * computed over the verbatim bytes before redaction, so "is this the same event
+ * the gateway signed" stays answerable regardless of what the projection drops.
+ *
+ * ## Deny-list, and why that is defensible HERE specifically
+ *
+ * 🛑 Root Cause #70 is the incident where a deny-list projection published
+ * every field nobody thought to delete, and § "Public Data Projections" draws
+ * the rule: **a document field is private until someone names it public.** This
+ * redactor is a deny-list, which looks like the same mistake. It is not, for
+ * two reasons worth stating rather than assuming:
+ *
+ *   1. **The shape is THEIRS, not ours.** An allow-list requires enumerating
+ *      every field a gateway might send, across providers and across their
+ *      future API versions. A field we failed to anticipate would be *dropped*,
+ *      and the whole value of this row is being able to read a payload we did
+ *      not expect — that is what makes an unhandled event diagnosable. An
+ *      allow-list here optimises for the case that never needs diagnosing.
+ *   2. **The output is never published.** It reaches one admin maintenance
+ *      table behind `admin:maintenance:view-server-errors`. The field that got
+ *      away in #70 went to an *unauthenticated, edge-cached* public endpoint.
+ *
+ * The deny-list is therefore keyed on *categories of sensitive data* rather
+ * than on one provider's field names, and it matches **recursively on the key
+ * at every depth** — so `payload.payment.entity.card.last4` is caught by the
+ * `card` key without anyone having written that path down.
+ */
+import { GATEWAY_EVENT_PAYLOAD_MAX_BYTES } from "../../../../features/gateway-events/schemas/firestore.js";
+/**
+ * Keys dropped wherever they appear, at any depth.
+ *
+ * Grouped by why, because "it looked sensitive" is not a maintainable reason
+ * and the next person needs to know whether to extend the list:
+ *
+ * - **direct identifiers** — reach a person without any other data
+ * - **instrument data** — card/UPI/bank details; `last4` is nested under `card`
+ *   and so is covered by the parent key
+ * - **our own passthrough** — `notes` and `metaInfo` are where WE pack
+ *   `uid`/`addressId`/`outOfStockPolicy` at create-order time, so they are the
+ *   one category that is sensitive *because of what we put there*
+ * - **credentials** — anything token-shaped, which should never be in a webhook
+ *   body but costs nothing to exclude
+ */
+const DENY_KEYS = new Set([
+    // direct identifiers
+    "email",
+    "contact",
+    "phone",
+    "phone_number",
+    "phoneNumber",
+    "mobile",
+    "name",
+    "customer_id",
+    "customerId",
+    "address",
+    "billing_address",
+    "shipping_address",
+    // instrument data
+    "card",
+    "card_id",
+    "vpa",
+    "bank_account",
+    "bankAccount",
+    "account_number",
+    "accountNumber",
+    "ifsc",
+    "upi",
+    "wallet",
+    // our own passthrough channel
+    "notes",
+    "metaInfo",
+    "udf1",
+    "udf2",
+    "udf3",
+    "udf4",
+    "udf5",
+    // credentials
+    "token",
+    "access_token",
+    "accessToken",
+    "refresh_token",
+    "secret",
+    "signature",
+    "password",
+]);
+function redactValue(value) {
+    if (value === null || value === undefined)
+        return value;
+    if (value instanceof Date)
+        return value;
+    if (typeof value !== "object")
+        return value;
+    if (Array.isArray(value))
+        return value.map(redactValue);
+    const out = {};
+    for (const [key, child] of Object.entries(value)) {
+        if (DENY_KEYS.has(key))
+            continue;
+        out[key] = redactValue(child);
+    }
+    return out;
+}
+/**
+ * Redact, then cap.
+ *
+ * 🛑 The cap is applied by MEASURING the serialised result and, if it is over
+ * budget, replacing it with a marker rather than by slicing the JSON string.
+ * A sliced JSON string is not JSON — it would be stored as a truncated blob
+ * that no reader can parse, which is a field that looks present and is
+ * unusable. A marker plus `payloadTruncated: true` tells the reader exactly
+ * what happened, and `bodySha256` still proves what arrived.
+ */
+export function redactGatewayPayload(body) {
+    if (typeof body !== "object" || body === null || Array.isArray(body)) {
+        return { payload: {}, truncated: false };
+    }
+    const redacted = redactValue(body);
+    let serialisedLength;
+    try {
+        serialisedLength = JSON.stringify(redacted)?.length ?? 0;
+    }
+    catch {
+        /*
+         * A circular structure cannot come from `JSON.parse`, which is the only
+         * producer here — but this function is exported and a future caller could
+         * hand it something else. Failing to a marker keeps the row writable.
+         */
+        return { payload: { redactionFailed: true }, truncated: true };
+    }
+    if (serialisedLength > GATEWAY_EVENT_PAYLOAD_MAX_BYTES) {
+        return {
+            payload: {
+                omitted: "payload exceeded the size budget after redaction",
+                approximateBytes: serialisedLength,
+            },
+            truncated: true,
+        };
+    }
+    return { payload: redacted, truncated: false };
+}

package/dist/_internal/server/features/grievance/actions.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Grievance intake — a record, a clock, and a place in the queue.
+ *
+ * ## What was wrong (D18)
+ *
+ * There was **no intake at all**: no form, no route, no API endpoint. The
+ * public `/grievance` page's only instruction was a `mailto:` to the generic
+ * support address, so nothing recorded a grievance, timestamped it, or tracked
+ * any statutory clock. `/report` is for scam and entity reports, not money.
+ *
+ * ## What this builds, and what it deliberately does NOT
+ *
+ * Built: the record, the acknowledgement timestamp, the resolution deadline,
+ * the structured disputed amount, and a `paymentCases` row so the deadline sits
+ * in the one queue an operator already reads.
+ *
+ * 🛑 **NOT built: anything published.** The Consumer Protection (E-Commerce)
+ * Rules 2020 require a NAMED individual as grievance officer, and this project
+ * publishes the business name with designation "Support" and the same generic
+ * support email — so there is no escalation tier (D17). It also publishes no
+ * timeline anywhere.
+ *
+ * I am not asserting the statutory periods from memory, and the reason is
+ * asymmetric: **a published timeline we then miss is worse than the present
+ * silence.** So the clock runs against `GRIEVANCE_PERIODS`, whose defaults are
+ * deliberately shorter than any plausible statutory period — firing early is
+ * harmless, firing late is the thing the regime punishes — and the public page
+ * stays untouched until the owner supplies the officer and the real numbers.
+ */
+import { type ActionResult } from "../../../shared/types/action-result";
+export interface FileGrievanceInput {
+    subject: string;
+    detail: string;
+    /** The order it concerns, when it concerns one. */
+    orderId?: string;
+    /** Decimal rupees in dispute. Structured so the queue can sort by it. */
+    disputedAmount?: number;
+}
+/**
+ * File a grievance.
+ *
+ * 🛑 The acknowledgement is stamped at intake, SYNCHRONOUSLY, and that is the
+ * one thing here that must not be best-effort. An acknowledgement timestamp is
+ * the evidence that we received the complaint on the day we say we did; writing
+ * it fire-and-forget would mean the clock's start could silently fail to
+ * record, and a clock whose start is unknown cannot be shown to have been met.
+ *
+ * The `paymentCases` row IS best-effort, because it is a convenience surface —
+ * losing it costs visibility, not evidence.
+ */
+export declare function fileGrievanceAction(input: FileGrievanceInput): Promise<ActionResult<{
+    ticketId: string;
+    dueAt: string;
+}>>;
+/**
+ * Stamp the first human response.
+ *
+ * 🛑 Separate from the ticket's ordinary reply path on purpose: it is
+ * write-once (`!existing.firstResponseAt`), so a second reply cannot move the
+ * metric forward and make a slow first response look fast. The same
+ * write-once discipline `resolvedAt` already uses.
+ */
+export declare function recordGrievanceFirstResponseAction(ticketId: string): Promise<ActionResult<void>>;