@mohasinac/appkit 4.62.0 → 4.63.0

package/dist/features/orders/schemas/firestore.d.ts

@@ -7,6 +7,7 @@ import type { BaseDocument } from "../../../_internal/shared/types/base-document
 import type { ListingType } from "../../products/types";
 import type { StatusChangeEntry } from "../../../_internal/shared/history/index";
 import type { ReturnReason } from "../../../_internal/shared/features/orders/return-reasons";
+import type { DisputeKind } from "../../../_internal/shared/features/orders/dispute-reasons";
 import type { ReturnCustodyState } from "../../../_internal/shared/features/returns/custody";
 import type { ActualShipmentCost, SelectedShippingQuote, ShippingReconciliation } from "../../../_internal/shared/shipping/quote";
 import type { Encrypted, Plaintext } from "../../../security/encrypted";
@@ -173,6 +174,68 @@ export declare const RefundStatusValues: {
     readonly REJECTED: "rejected";
 };
 /** Firestore storage shape for an order line item â€" distinct from the API display model OrderItem */
+/**
+ * The PII inside one amendment.
+ *
+ * 🛑 BARE keys, and `ORDER_PII_FIELDS` uses the `deliveryAmendments[].…`
+ * form for the same five fields. Two notations, two scopes, both correct:
+ * the `[]` form is for the whole ORDER document, where the hook has to walk
+ * into the array; these bare names are for ONE amendment object, where they
+ * are genuinely top-level.
+ *
+ * 🛑 This list was first justified as "`encryptPiiFields` CANNOT cover an
+ * array" — CLAUDE.md's wording, and FALSE. `encryptInArray` has always
+ * handled `a[].b`, in both directions. The real rule is that the encryptor
+ * does not infer: a field is covered only where it is NAMED, in the notation
+ * matching the object the list is applied to.
+ */
+export declare const AMENDMENT_PII_FIELDS: readonly ["fullName", "phone", "addressLine1", "addressLine2", "landmark"];
+/**
+ * A correction to the delivery address after the order was placed.
+ *
+ * 🛑 Carries the FULL new address, not a diff. A diff would make the current
+ * address reconstructable only by replaying every entry in order, so one
+ * malformed entry in the middle makes everything after it unreadable — and
+ * the parcel label is produced from the current address.
+ *
+ * PII in here is the same problem as everywhere else: `encryptPiiFields` does
+ * not descend into arrays, so these values are NOT encrypted by that
+ * mechanism. `scrubAmendmentPii` is what handles them; see its header.
+ */
+export interface DeliveryAmendment {
+    at: Date;
+    /** Who asked. `actorRole` distinguishes a buyer correction from a support fix. */
+    actorUid?: string;
+    actorRole: "buyer" | "seller" | "admin" | "system";
+    reason?: string;
+    fullName: string;
+    phone: string;
+    addressLine1: string;
+    addressLine2?: string;
+    landmark?: string;
+    city: string;
+    state: string;
+    pincode: string;
+    country: string;
+}
+/**
+ * How much seller prose a single order line carries.
+ *
+ * 🛑 A Firestore document caps at 1 MiB and `items[]` is inline on the order.
+ * 2,000 characters × 20 lines is ~40 KB of description — comfortable. The
+ * same field unbounded is a rejected write at checkout, and the checkout is
+ * the one operation in the system that must never fail for a reason the buyer
+ * cannot act on.
+ */
+export declare const ORDER_ITEM_DESCRIPTION_MAX = 2000;
+/**
+ * How many spec rows one order line keeps.
+ *
+ * Capped by COUNT rather than characters: a spec table is rows, and half a
+ * row is worse than a missing one — "Weight: 4" with the unit cut off reads
+ * as a fact rather than as truncation.
+ */
+export declare const ORDER_ITEM_SPECIFICATIONS_MAX = 30;
 export interface OrderDocumentItem {
     productId: string;
     productTitle: string;
@@ -260,6 +323,37 @@ export interface OrderDocumentItem {
     /** Which kind of multi-member line produced these rows. */
     groupSource?: "bundle" | "product-group" | "grouped-listing";
     /** P-8 GST — snapshotted from the product at order time so the invoice stays accurate even if the product's HSN/rate later changes. */
+    /**
+     * The listing description as it read at purchase.
+     *
+     * 🛑 BOUNDED at `ORDER_ITEM_DESCRIPTION_MAX`, with `descriptionTruncated`
+     * recording that it was cut. A Firestore document caps at 1 MiB and this is
+     * free-form seller prose on every line of every order — an unbounded copy
+     * on a 20-line order is a rejected write AT CHECKOUT, which fails the one
+     * operation that must not fail. Truncation is recorded rather than silent
+     * for the same reason `statusHistoryTruncated` exists: a short description
+     * and a cut one must not read alike.
+     */
+    description?: string;
+    descriptionTruncated?: boolean;
+    /** The spec table as it read at purchase. */
+    specifications?: Array<{
+        name: string;
+        value: string;
+        unit?: string;
+    }>;
+    /**
+     * For a composed listing, the parts it was sold as containing.
+     *
+     * Ids and names only — the part CATALOGUE is a live reference work and
+     * copying its entries onto every order line would duplicate a research
+     * corpus per purchase. What matters for a dispute is which parts were
+     * claimed, not their current catalogue entry.
+     */
+    parts?: Array<{
+        code: string;
+        name: string;
+    }>;
     hsnCode?: string;
     gstRate?: 0 | 5 | 12 | 18 | 28;
     /**
@@ -352,6 +446,25 @@ export interface OrderRefundEvent {
     proofDocumentMimeType?: string;
     /** Required for Razorpay-override path ("failed auto-refund, settled manually"). */
     overrideReason?: string;
+    /**
+     * The credit note that documents this refund, e.g. `LIRCN/26-27/0001`
+     * (Phase 7, D12).
+     *
+     * 🛑 Per REFUND EVENT, not per order — an order can legitimately be refunded
+     * several times, and each reversal of tax needs its own numbered document
+     * referencing the original invoice. That is why the allocation claim for a
+     * credit note is keyed `${orderId}_${refundId}` while an invoice's is keyed
+     * on the order alone: keying a credit note on the order would refuse the
+     * second one.
+     *
+     * Only ever set on a refund that actually SETTLED. A `reserved` entry that
+     * failed is not a reversal of anything, and numbering it would leave a
+     * credit note in the series for money that never moved.
+     */
+    creditNoteNumber?: string;
+    creditNoteIssuedAt?: Date;
+    /** Private storage path — same no-public-URL rule as `invoiceStoragePath`. */
+    creditNoteStoragePath?: string;
 }
 /** One applied discount/coupon saved on the order for accounting and display */
 export interface AppliedOrderDiscount {
@@ -405,7 +518,64 @@ export interface OrderDocument extends BaseDocument {
     paymentStatus: PaymentStatus;
     paymentId?: string;
     paymentMethod?: string;
+    /**
+     * 🛑 LEGACY. Never written for an order created after Part 14.
+     *
+     * Flat free text with no pincode, no phone and no address id — which is why
+     * `placeOfSupply` had to be written separately rather than derived, and why
+     * parcel booking could not be built at all (`CreateShipmentInput` needs a
+     * structured `{name, phone, addressLine1, city, state, pincode, country}`).
+     *
+     * It is ALSO in `ORDER_UPDATABLE_FIELDS`, so it is editable after the order
+     * — meaning it never recorded what the buyer actually chose. And it was
+     * never encrypted: `ORDER_PII_FIELDS` is `userName` / `userEmail` /
+     * `sellerEmail`, so every delivery address on every order up to now sits in
+     * Firestore in plaintext, despite the docs saying otherwise.
+     *
+     * Read it only as a fallback for orders that predate `deliveryAddress*`,
+     * and render it labelled as legacy. Forward-only; no backfill — parsing a
+     * state out of free text to file a tax return is the thing the
+     * `placeOfSupply` comment below already refuses.
+     */
     shippingAddress?: string;
+    /** PII — encrypted. See `ORDER_PII_FIELDS`. */
+    deliveryFullName?: Encrypted<string>;
+    /** PII — encrypted. */
+    deliveryPhone?: Encrypted<string>;
+    /** PII — encrypted. */
+    deliveryAddressLine1?: Encrypted<string>;
+    /** PII — encrypted. Optional second line / apartment. */
+    deliveryAddressLine2?: Encrypted<string>;
+    /** PII — encrypted. */
+    deliveryLandmark?: Encrypted<string>;
+    deliveryCity?: string;
+    deliveryState?: string;
+    deliveryPincode?: string;
+    deliveryCountry?: string;
+    /**
+     * The `addresses` row this was taken from, for provenance only.
+     *
+     * 🛑 Never resolved at read time. The row can be edited or deleted after the
+     * order, and following it would make the invoice disagree with what the
+     * buyer chose — which is the entire failure a snapshot exists to prevent.
+     */
+    deliveryAddressId?: string;
+    /**
+     * Corrections after the fact, newest LAST. Append-only.
+     *
+     * 🛑 Its OWN array, not a passenger on `statusHistory`.
+     *
+     * `statusHistory` caps at 50 with FIFO eviction. Address edits riding that
+     * log would compete with status transitions for the same slots and evict
+     * the thing the timeline exists to show — and on a chatty order the
+     * creation entry goes first, which is precisely the value reconstruction
+     * depends on. The creation snapshot is a FIELD above for the same reason: a
+     * field cannot be truncated.
+     *
+     * Dispatch reads the latest amendment (or the snapshot when there is none).
+     * The invoice always reads the snapshot.
+     */
+    deliveryAmendments?: DeliveryAmendment[];
     trackingNumber?: string;
     notes?: string;
     orderDate: Date;
@@ -426,6 +596,21 @@ export interface OrderDocument extends BaseDocument {
      */
     acceptedAt?: Date;
     shippingDate?: Date;
+    /**
+     * The COURIER's estimated delivery date, captured at dispatch.
+     *
+     * 🛑 Not to be confused with `OrderSourcePreOrder.expectedDeliveryDate`,
+     * which is when a pre-ordered product RELEASES — a different concept that
+     * this field was mistaken for while planning the dispute gates.
+     *
+     * Optional, and will stay mostly empty for now: nothing platform-books yet
+     * (`createShipment` has zero callers), and a self-shipping seller types a
+     * tracking number with no estimate attached. `resolveDisputeEtd` therefore
+     * falls back to `shippingDate + DISPUTE_TRANSIT_WINDOW_DAYS` — without that
+     * fallback the `not_reached` dispute gate would be unreachable for every
+     * parcel currently shipped.
+     */
+    estimatedDeliveryDate?: Date;
     deliveryDate?: Date;
     /**
      * When the order was marked COMPLETE — the fact that awards points and
@@ -481,6 +666,37 @@ export interface OrderDocument extends BaseDocument {
      * figure the order may since have changed.
      */
     pointsAwarded?: number;
+    /**
+     * Points SPENT on this order as part-payment, in points (1 point = ₹1).
+     *
+     * 🛑 Distinct from `pointsAwarded` directly above, which is what the buyer
+     * EARNED. Both can be non-zero on one order — a buyer can pay partly with
+     * points and still earn on the goods value — and conflating them would make
+     * the ledger unexplainable in exactly the place it matters most.
+     *
+     * Written at order creation from `resolvePointsTender`, never from a request
+     * body. The ledger's `redemption` entry is keyed on this order, so this field
+     * and that entry must agree; the order carries it so a payout deduction and a
+     * refund can both answer "how much of this was points" without re-deriving a
+     * percentage of a total that may since have changed.
+     */
+    pointsApplied?: number;
+    /**
+     * What the buyer actually pays: `totalPrice − pointsApplied`.
+     *
+     * ## 🛑 THE FIGURE THE GATEWAY CAPTURES, and the one the guard compares
+     *
+     * `totalPrice` stays the full value of the order — that is what the invoice
+     * declares and what GST is computed against, because points are a DISCOUNT
+     * and not a reduction in the value of the supply (decision 5). `amountDue` is
+     * the cash leg.
+     *
+     * Absent means "nothing was tendered", so every order written before this
+     * existed reads correctly as `amountDue === totalPrice`. 🛑 Readers must use
+     * `amountDue ?? totalPrice` rather than defaulting to 0 — treating absence as
+     * zero would say every historical order was fully paid in points.
+     */
+    amountDue?: number;
     cancellationDate?: Date;
     cancellationReason?: string;
     /**
@@ -668,6 +884,25 @@ export interface OrderDocument extends BaseDocument {
         igst: number;
         gstAmount: number;
     }>;
+    /**
+     * The buyer's state — the PLACE OF SUPPLY (Phase 7).
+     *
+     * 🛑 This is the input the CGST/SGST-vs-IGST decision was made FROM, and it
+     * was not recorded anywhere. `isIntraStateSupply(buyerState, storeState)`
+     * runs at checkout and only its *result* survived, in the shape of which tax
+     * fields got populated — so an order could not state why it split the way it
+     * did, and GSTR-1 has a mandatory place-of-supply column that nothing could
+     * fill.
+     *
+     * `shippingAddress` is a flat STRING on this document and contains the state
+     * somewhere inside it; parsing a state back out of free text to file a tax
+     * return is not a thing to do. The value is in scope at order creation, so
+     * it is written there.
+     *
+     * Absent on orders placed before this, which the export reports rather than
+     * silently blanks.
+     */
+    placeOfSupply?: string;
     /**
      * OUR GST registration as it stood at the moment of supply — LetItRip is the
      * seller of record and invoices under its own GSTIN.
@@ -689,6 +924,58 @@ export interface OrderDocument extends BaseDocument {
     supplierGstin?: string;
     supplierLegalName?: string;
     supplierAddress?: string;
+    /**
+     * The invoice number from the gapless FY series, e.g. `LIR/26-27/0001`.
+     *
+     * 🛑 Allocated on `paymentStatus → paid`, never at order creation — a number
+     * burned on an abandoned COD order is a gap nobody can explain. Written once
+     * and never rewritten: a GST invoice is issued once, and an adjustment is a
+     * CREDIT NOTE, not a re-issue.
+     *
+     * Absence means "not yet invoiced", which is the correct state for a pending
+     * order and for every order placed before this phase.
+     */
+    invoiceNumber?: string;
+    /** When the number was allocated — the invoice's own date. */
+    invoiceIssuedAt?: Date;
+    /**
+     * Where the rendered PDF lives.
+     *
+     * 🛑 **`private/invoices/{orderId}/{uuid}.pdf`, with NO `mediaAssets` row and
+     * a RANDOM object name.** An invoice carries the buyer's full name, address
+     * and phone. `/api/media/[...slug]` applies **no authentication** over a
+     * bucket whose storage rule is `allow read: if true`, and the slug resolves
+     * through `mediaAssets` — so no row means no public URL exists at all.
+     *
+     * The random name is deliberately AGAINST the content-derived SEO-slug
+     * convention used everywhere else in this codebase, because guessable is the
+     * one property this must not have. `generateInvoiceFilename` is
+     * content-derived and is therefore the wrong tool here. Same reasoning as the
+     * digital-content decision (D103).
+     */
+    invoiceStoragePath?: string;
+    /**
+     * The arrangement's fees, SNAPSHOTTED at checkout.
+     *
+     * 🛑 Snapshotted, not re-read. A coordinator commits against a quoted total;
+     * if the rates were read again at settle a seller could raise them
+     * afterwards and the coordinator would absorb it. The precedent is exact —
+     * the refund path reads `finalSale` from this document rather than the live
+     * product, "because re-reading the live product would let a seller flip the
+     * switch afterwards" — and D61 generalises it to every agreement with a gap
+     * between terms-agreed and money-taken.
+     *
+     * Absent on every ordinary single-destination order, which is almost all of
+     * them.
+     */
+    sharedPurchase?: {
+        /** Distinct destinations, including the first. Always ≥ 2 when present. */
+        destinationCount: number;
+        /** Flat per-arrangement fee, as charged. */
+        handlingFee: number;
+        /** Extra shipping for destinations beyond the first, as charged. */
+        extraShippingFee: number;
+    };
     emiEnabled?: boolean;
     /** Number of monthly installments the buyer chose (2–6). */
     emiTenureMonths?: number;
@@ -776,6 +1063,38 @@ export interface OrderDocument extends BaseDocument {
      * requires evidence and approval before anything is paid.
      */
     platformBookedShipment?: boolean;
+    /**
+     * We tried to book a courier for this order and could not.
+     *
+     * ## 🛑 ITS WHOLE PURPOSE IS TO STOP AN AUTO-CANCELLATION
+     *
+     * `seller-dispatch` is an `onDue: "act"` obligation on a 2-business-day
+     * clock. Without this field, an order sitting on OUR empty courier wallet is
+     * auto-cancelled and the buyer refunded — with the seller recorded as having
+     * failed to dispatch. The buyer paid, the seller did nothing wrong, and the
+     * platform's own funding state caused the cancellation.
+     *
+     * So every `onDue: "act"` policy anchored at or after dispatch gates its
+     * `precondition` on `!hasOpenCourierBlock(order)`. The obligation engine
+     * re-evaluates `precondition` at fire time and closes `superseded` when it
+     * returns false, so the clock pauses and resumes with no new mechanism.
+     *
+     * Absent means no block — which is every order ever written, so this needs
+     * no migration and changes nothing until something sets it.
+     *
+     * `reason` is the operator's word, not the seller's: the seller is told only
+     * that we could not book a courier right now, because our balance is our
+     * problem and not theirs.
+     */
+    courierBlock?: {
+        reason: "insufficient_funds" | "provider_error" | "unserviceable";
+        at: Date;
+        lastAttemptAt?: Date;
+        /** Attempts so far, so the digest can distinguish stuck from transient. */
+        attempts: number;
+        /** Upstream detail, for the admin surface only. Never shown to a seller. */
+        detail?: string;
+    };
     /**
      * The self-shipped reimbursement workflow: evidence in, approved amount out.
      *
@@ -961,6 +1280,58 @@ export interface OrderDocument extends BaseDocument {
     /** Buyer's required "this payment is genuine, no fraudulent tricks/chargebacks" agreement — server-validated, not just a client-side disable. */
     buyerFraudAgreementAccepted?: boolean;
     buyerFraudAgreementAcceptedAt?: Date;
+    /**
+     * ── D55: the pre-order BALANCE, which is a second payment ──────────────
+     *
+     * 🛑 Its own block rather than reusing the fields above, and that is the
+     * decision this whole feature turns on. Every field above describes ONE
+     * payment; a pre-order has two, months apart. Reusing `paymentProofUrl`
+     * for the balance overwrites the deposit's proof — the evidence for the
+     * payment that created the order — and `paymentReviewOutcome` then means
+     * two different things depending on when you read it.
+     *
+     * Worse, `paymentWindowTimeout` sweeps orders that are `pending`/`pending`
+     * with no `paymentProofUrl`, so clearing that field to collect a balance
+     * would make the sweep cancel and restock a PAID order.
+     *
+     * The balance is therefore its own small state machine beside the
+     * deposit's, sharing the review vocabulary but none of the storage.
+     */
+    balance?: {
+        /**
+         * 🛑 SNAPSHOTTED, not recomputed — D61, and the worst case in the
+         * codebase for it: a deposit-to-balance gap is months. It is copied from
+         * `sourceContext.balanceDue` at the moment the collection is opened, so
+         * a price change, a tax-rate change or a re-quote in between cannot move
+         * what the buyer was told they owe. Recomputing at payment time is how a
+         * buyer who agreed to ₹4,000 is charged ₹4,400.
+         */
+        amount: number;
+        /**
+         * `manual` only, today, and the field exists so the absence is explicit.
+         *
+         * 🛑 The AUTO path is not merely unbuilt — it is blocked on things
+         * outside this repo. A months-long gap cannot use authorise-then-capture
+         * (capture windows are days), so it needs a real RBI-compliant mandate:
+         * AFA at creation, a pre-debit notice at least 24 HOURS before every
+         * debit, and a max amount fixed at registration. Razorpay must also have
+         * recurring enabled, and production runs TEST keys with
+         * `razorpayEnabled` defaulting false. Declaring the union now means
+         * adding `auto` later is a compile-checked change rather than a new
+         * field nobody wires.
+         */
+        method: "manual";
+        status: "awaiting" | "submitted" | "paid" | "rejected";
+        /** Set when the collection is opened, so the buyer has a stated window. */
+        dueBy?: Date;
+        proofUrl?: string;
+        transactionId?: string;
+        submittedAt?: Date;
+        reviewedBy?: string;
+        reviewedAt?: Date;
+        /** Required on `rejected`, for the same reason a refund reason is. */
+        reviewNote?: string;
+    };
     /** Which of the three admin review actions was taken on this order's payment proof. */
     paymentReviewOutcome?: "approved" | "reupload_requested" | "rejected_fraud";
     /** Admin's reason text — required for both `reupload_requested` and `rejected_fraud`. */
@@ -970,11 +1341,37 @@ export interface OrderDocument extends BaseDocument {
     /** True when `paymentReviewAutoApprove` approved this order after 2 hours of no manual admin review. */
     autoApproved?: boolean;
     autoApprovedAt?: Date;
-    /** Buyer/seller/admin dispute raised against an auto-approved order — surfaces to the admin queue, does not itself reverse payment/order status. */
+    /**
+     * A buyer/seller/admin dispute. Surfaces to the admin queue; does not itself
+     * reverse payment or order status.
+     *
+     * 🛑 This used to say "against an auto-approved order", and that was the
+     * whole scope: `raiseOrderDisputeAction` refused anything else, telling the
+     * caller to use the return/refund flow. Disputes are now GENERAL — any
+     * delivered-or-late order can be disputed, gated by `disputeKind`.
+     */
     disputeRaised?: boolean;
     disputeRaisedBy?: string;
     disputeRaisedAt?: Date;
+    /**
+     * The reason's LABEL, snapshotted at the moment the dispute was raised.
+     *
+     * 🛑 A snapshot, not a lookup, and that is the point: `disputeReasons` rows
+     * can be retired or reworded by staff, and neither may rewrite what a buyer
+     * said months ago. `disputeReasonId` below is the join key for analytics;
+     * THIS is the record.
+     *
+     * Still a plain `string` and still the field every existing surface renders,
+     * so pre-2026-10-22 disputes (free text typed by the buyer) keep displaying
+     * unchanged rather than being orphaned beside a new field.
+     */
     disputeReason?: string;
+    /** Which gate this dispute passed. Absent on pre-2026-10-22 disputes. */
+    disputeKind?: DisputeKind;
+    /** `disputeReasons/{id}`. The join key for "what are buyers reporting". */
+    disputeReasonId?: string;
+    /** The buyer's own words. Free text, never parsed, never gated on. */
+    disputeDetail?: string;
     disputeStatus?: "open" | "resolved";
     /**
      * Same-shape payment record regardless of how the buyer paid — manual

package/dist/features/orders/schemas/firestore.js

@@ -48,6 +48,49 @@ export const RefundStatusValues = {
     COMPLETED: "completed",
     REJECTED: "rejected",
 };
+/** Firestore storage shape for an order line item â€" distinct from the API display model OrderItem */
+/**
+ * The PII inside one amendment.
+ *
+ * 🛑 BARE keys, and `ORDER_PII_FIELDS` uses the `deliveryAmendments[].…`
+ * form for the same five fields. Two notations, two scopes, both correct:
+ * the `[]` form is for the whole ORDER document, where the hook has to walk
+ * into the array; these bare names are for ONE amendment object, where they
+ * are genuinely top-level.
+ *
+ * 🛑 This list was first justified as "`encryptPiiFields` CANNOT cover an
+ * array" — CLAUDE.md's wording, and FALSE. `encryptInArray` has always
+ * handled `a[].b`, in both directions. The real rule is that the encryptor
+ * does not infer: a field is covered only where it is NAMED, in the notation
+ * matching the object the list is applied to.
+ */
+export const AMENDMENT_PII_FIELDS = [
+    "fullName",
+    "phone",
+    "addressLine1",
+    "addressLine2",
+    /* Encrypted on the snapshot as `deliveryLandmark`; the two must agree or the
+     * same datum is protected before a correction and exposed after it. */
+    "landmark",
+];
+/**
+ * How much seller prose a single order line carries.
+ *
+ * 🛑 A Firestore document caps at 1 MiB and `items[]` is inline on the order.
+ * 2,000 characters × 20 lines is ~40 KB of description — comfortable. The
+ * same field unbounded is a rejected write at checkout, and the checkout is
+ * the one operation in the system that must never fail for a reason the buyer
+ * cannot act on.
+ */
+export const ORDER_ITEM_DESCRIPTION_MAX = 2000;
+/**
+ * How many spec rows one order line keeps.
+ *
+ * Capped by COUNT rather than characters: a spec table is rows, and half a
+ * row is worse than a missing one — "Weight: 4" with the unit cut off reads
+ * as a fact rather than as truncation.
+ */
+export const ORDER_ITEM_SPECIFICATIONS_MAX = 30;
 export const ORDER_COLLECTION = "orders";
 /**
  * At-most-once gate for refunds. Document id = `sha256(idempotencyKey)`,