@mohasinac/appkit 4.59.0 → 4.60.0

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

@@ -303,6 +303,44 @@ export interface OrderRefundEvent {
     reasonCode?: ReturnReason;
     refundedAt: Date;
     refundedBy: string;
+    /**
+     * Lifecycle of this refund entry. **Optional on purpose** — every row
+     * written before the two-phase scheme (2026-10-21) has none, and those are
+     * all committed refunds, so a missing status must COUNT as committed.
+     *
+     * · `reserved`  a slot was claimed and the provider call is in flight. The
+     *               amount is already spoken for, so it counts toward the
+     *               cumulative cap — that is what closes the TOCTOU.
+     * · `processed` the provider confirmed. Money moved.
+     * · `failed`    the provider refused. The reservation is RELEASED simply by
+     *               being skipped in the cumulative sum, which is why there is
+     *               no explicit release step to forget.
+     *
+     * A `reserved` entry that never settles is a crash between the provider call
+     * and our write — detectable, and exactly what the reconciler looks for.
+     */
+    status?: "reserved" | "processed" | "failed";
+    /** Why the provider refused, when `status === "failed"`. */
+    failureReason?: string;
+    /**
+     * The gateway's own refund reference, whichever gateway ran.
+     *
+     * 🛑 ADDED 2026-10-21 because reconciliation was impossible (D7). Razorpay's
+     * refund id was written to **`phonepeRefundId`** unconditionally — the
+     * action did `phonepeRefundId = result.id` with no branch on provider — while
+     * the declared `razorpayRefundId` was written by NOTHING, and
+     * `RefundHistoryTable` rendered no reference at all for a Razorpay refund.
+     * So a refund existed in Razorpay's dashboard with no way to tie it to ours.
+     *
+     * This is the field a reconciler reads, and it is gateway-BLIND on purpose:
+     * a reconciler that has to know which provider ran before it can find the id
+     * is a reconciler that breaks on the next provider. The two
+     * provider-specific fields below stay, populated only by the provider that
+     * actually produced the id, for operators who search a specific dashboard.
+     */
+    gatewayRefundId?: string;
+    /** Which gateway produced `gatewayRefundId` (`payment.name`). */
+    gateway?: string;
     /** Set when PhonePe processed the refund. */
     phonepeRefundId?: string;
     /** Set when Razorpay processed the refund (`rfnd_…`). Mutually exclusive with `phonepeRefundId` — one online gateway runs at a time. */
@@ -371,8 +409,78 @@ export interface OrderDocument extends BaseDocument {
     trackingNumber?: string;
     notes?: string;
     orderDate: Date;
+    /**
+     * When the SELLER accepted the order — the first fact in the fulfilment
+     * lifecycle, and it did not exist before Phase 5b.
+     *
+     * 🛑 D30: there was no seller-acceptance step at all. `customShipOrder`
+     * requires `status === "confirmed"` and **nothing ever set `confirmed` on a
+     * paid order** except an admin PATCH, while `onOrderCreate` wrote one admin
+     * notification and stopped. So a seller could silently ignore a paid order
+     * forever and no clock anywhere noticed.
+     *
+     * Its presence is what distinguishes "the seller has not looked at this yet"
+     * from "the seller accepted it and has not packed it" — two different
+     * obligations with two different deadlines (`seller-accept` then
+     * `seller-dispatch`), which is unexpressible with a single status field.
+     */
+    acceptedAt?: Date;
     shippingDate?: Date;
     deliveryDate?: Date;
+    /**
+     * When the order was marked COMPLETE — the fact that awards points and
+     * closes the dispute window.
+     *
+     * 🛑 Owner's rule, 2026-10-21: *"auto assigned after 7 days of delivery, when
+     * order is marked complete; if review is given and order marked complete by
+     * the buyer before — immediate disburse."*
+     *
+     * So there are two writers and they are not equivalent:
+     *
+     * | writer | when | `completedBy` |
+     * |---|---|---|
+     * | `obligationSweep` | 7 days after delivery, nothing contested | `"system"` |
+     * | `markOrderCompleteAction` | the buyer, having left a review | their uid |
+     *
+     * The buyer's path is the FAST one — it skips the remaining wait, which is
+     * what "immediate disburse" asks for. And because `payout-release` is
+     * `blockedBy: ["order-complete", …]`, an early completion opens the seller's
+     * payout gate early **with no extra mechanism**: the buyer confirming
+     * satisfaction is exactly the signal a quiet period exists to wait for.
+     *
+     * A FACT, never a deadline — the 7-day deadline itself stays derived
+     * (`deadlinesFor`), so changing the period does not need a backfill.
+     */
+    completedAt?: Date;
+    /** `"system"` for the timer, or the buyer's uid for the fast path. */
+    completedBy?: string;
+    /**
+     * When purchase points were credited for this order.
+     *
+     * ## 🛑 THE IDEMPOTENCY KEY, and it is the whole reason the award exists
+     *
+     * `pointsLedger` is append-only and `pointsRepository.append` takes no key,
+     * so an append does not deduplicate itself. Completion has TWO triggers —
+     * the buyer's fast path and the 7-day `order-complete` sweep — and a double
+     * fire would credit twice **permanently, with no way to net it off.**
+     *
+     * Both triggers check this field before awarding and write it after, which
+     * is the same mechanism `order.shippingReconciliation` already provides for
+     * the points credit on shipping savings: the marker is written in the same
+     * step as the credit precisely so it can be the key.
+     *
+     * It is also set on an order that earned ZERO (fully cancelled, zero value),
+     * so the sweep stops revisiting it — "we looked and there was nothing to
+     * give" is a decision, and leaving it unmarked re-reads that order on every
+     * tick forever.
+     */
+    pointsAwardedAt?: Date;
+    /**
+     * How many points were credited. Recorded for the seller's payout deduction
+     * and for explaining a balance, so neither has to re-derive a percentage of a
+     * figure the order may since have changed.
+     */
+    pointsAwarded?: number;
     cancellationDate?: Date;
     cancellationReason?: string;
     /**
@@ -414,6 +522,21 @@ export interface OrderDocument extends BaseDocument {
     returnDestination?: "warehouse" | "seller";
     /** The address the buyer was given, resolved once and recorded verbatim. */
     returnAddress?: string;
+    /**
+     * When the seller APPROVED the return — the anchor the buyer's posting
+     * deadline is measured from.
+     *
+     * 🛑 Added for Phase 5b, and its absence was load-bearing: without it, "the
+     * buyer has 7 days to post an approved return" had nothing to count from, so
+     * the only available anchor was `returnRequestedAt` — which starts the
+     * buyer's clock while the seller is still deciding, i.e. a seller who takes
+     * 48 hours to approve silently eats two days of the buyer's window.
+     *
+     * A FACT, never a deadline. Deadlines are derived (`deadlinesFor`), never
+     * stored — a stored deadline needs a backfill and drifts from the policy the
+     * day somebody edits one (Root Cause #42).
+     */
+    returnApprovedAt?: Date;
     /** Set when the buyer marks it posted; `in_transit` without one is a bug. */
     returnPostedAt?: Date;
     returnReceivedAt?: Date;
@@ -448,6 +571,37 @@ export interface OrderDocument extends BaseDocument {
     /** Full list of all applied coupons/discounts for this order group */
     appliedDiscounts?: AppliedOrderDiscount[];
     platformFee?: number;
+    /**
+     * GST charged on the platform fee, in decimal rupees.
+     *
+     * 🛑 ADDED 2026-10-21 because its ABSENCE made a refund over-deduct by ~10x.
+     *
+     * This was computed at checkout (`gstOnFee`), charged to the buyer as its own
+     * term in `orderTotal`, and then folded into `gstAmount` — so the order
+     * recorded the combined figure and no field held the fee's own tax. The
+     * platform fee is non-refundable by policy, so a refund has to withhold
+     * `platformFee + its GST`, and with the second half unavailable
+     * `previewCancellationRefund` re-derived BOTH from live percentages:
+     *
+     *     effectiveRate = platformFeePercent × (1 + gstPercent / 100)
+     *     feeDeducted   = grossRefund × effectiveRate / 100
+     *
+     * That ignores `commissions.platformFeeMax` (default **₹10**) entirely, so on
+     * a ₹5,000 order it withheld **₹118** from a buyer who had paid **₹11.80** —
+     * keeping ~₹106 of their goods money and calling it a platform fee. The
+     * error grows with order value.
+     *
+     * Stored rather than re-derived for the same reason every other agreed term
+     * is: the rate in force when the order was placed is the rate that governs
+     * it. `platformFeeWithheld()` reads this field and falls back to deriving it
+     * only for orders written before it existed.
+     *
+     * 🛑 Note the ASYMMETRY with product GST, which is deliberate: product
+     * prices are tax-INCLUSIVE so their tax is backed out for reporting, while
+     * this is GST on OUR service fee charged to the buyer ON TOP of the fee. See
+     * the note above `orderTotal` in `createOrderForGroup`.
+     */
+    platformFeeGst?: number;
     depositAmount?: number;
     codRemainingAmount?: number;
     /** COD handling fee charged to the buyer: min(subtotal × codHandlingFeePercent / 100, codHandlingFeeCap). Only set when paymentMethod === "cod". */
@@ -542,6 +696,26 @@ export interface OrderDocument extends BaseDocument {
     emiTokenAmount?: number;
     /** Extra cost of choosing EMI over full payment, in decimal rupees — split between platform and seller. */
     emiSurchargeAmount?: number;
+    /**
+     * The SELLER's share of the EMI surcharge, in decimal rupees.
+     *
+     * 🛑 D45, the half that is a data gap rather than a commercial decision.
+     * `computeEmiSchedule` computes `surchargeSellerShare` (from
+     * `emi.surchargeSellerSharePercent`, seeded at 50) and it was **persisted
+     * nowhere** — so the split existed as a setting, a form field and a returned
+     * value with no field to land in and therefore no reader in the payout path.
+     * The platform kept 100% of a surcharge it had already decided to split.
+     *
+     * 🛑 Persisting it moves NO money on its own, and that is deliberate.
+     * Whether the seller is actually PAID this — along with shipping and the COD
+     * handling fee, the other two D45 terms — is a commercial decision about who
+     * keeps which revenue, and it is the owner's to make, not a defect to quietly
+     * fix. What was broken is that the decision had already been made (the
+     * setting exists, defaulted to 50%) and the number was then thrown away. Now
+     * it is recorded, so honouring it is a payout change rather than an
+     * archaeology exercise.
+     */
+    emiSurchargeSellerShare?: number;
     emiInstallments?: EmiInstallment[];
     /** Sum of unpaid installment amounts, in decimal rupees. 0 once all installments are paid. */
     emiRemainingBalance?: number;
@@ -588,6 +762,56 @@ export interface OrderDocument extends BaseDocument {
     shippingReconciliation?: ShippingReconciliation & {
         reconciledAt: Date;
     };
+    /**
+     * Did WE book this shipment through the Shiprocket integration?
+     *
+     * 🛑 The discriminator for whether postage may be reimbursed at all, and it
+     * must be a fact about the BOOKING rather than about the evidence — see
+     * `isReimbursableShipment`. If reimbursement were gated on "a receipt
+     * exists", a seller could upload a receipt for a parcel the platform paid
+     * for and be reimbursed for our spend.
+     *
+     * Written by the integration at booking time. Absent means nobody recorded a
+     * platform booking, which for a self-shipped parcel is correct and still
+     * requires evidence and approval before anything is paid.
+     */
+    platformBookedShipment?: boolean;
+    /**
+     * The self-shipped reimbursement workflow: evidence in, approved amount out.
+     *
+     * ## 🛑 `declaredAmount` is an ESTIMATE; `approvedAmount` is the entitlement
+     *
+     * Owner, 2026-10-21: *"The seller may set an initial value of shipping but
+     * the only approved amount will be given to them."* So a seller who quotes
+     * ₹120 and posts for ₹80 is reimbursed ₹80 — the two numbers are different
+     * things and must never be conflated, which is why they are separate fields
+     * rather than one that gets overwritten.
+     *
+     * `approvedAmount` is absent until an admin approves. A missing value means
+     * "not yet decided", never zero: defaulting it to 0 would make an
+     * un-reviewed claim indistinguishable from a rejected one, and the payout
+     * base reads this field.
+     *
+     * 🛑 **`approvedBy` must never be `"system"`.** Approving a reimbursement
+     * moves money to a seller on the strength of a document a human has to look
+     * at. Same rule, and the same reason, as `paymentCases.resolve()` refusing a
+     * system resolver.
+     */
+    shippingReimbursement?: {
+        /** What the seller says it cost. An estimate, not an entitlement. */
+        declaredAmount: number;
+        /** Receipt / postage slip. Uploaded by the seller. */
+        evidenceUrl?: string;
+        /** The tracking number on that receipt — ties the evidence to the parcel. */
+        trackingNumber?: string;
+        submittedAt: Date;
+        /** Present only once an admin has decided. Absent ≠ zero. */
+        approvedAmount?: number;
+        approvedBy?: string;
+        approvedAt?: Date;
+        /** Required when the approved amount differs from the declared one. */
+        approvalNote?: string;
+    };
     /**
      * The carrier's label PDF, once a shipment has been booked.
      *
@@ -778,6 +1002,28 @@ export interface OrderDocument extends BaseDocument {
     }[];
     /** Set true only when an automatic partial refund (for dropped Razorpay items) failed and needs manual follow-up. */
     refundPending?: boolean;
+    /**
+     * Marks an order created by the tester harness.
+     *
+     * 🛑 DECLARED LATE: three readers already depended on it —
+     * `deadlinesFor()`, `protection-claims/actions.ts` and
+     * `orders.repository.ts` — while `OrderDocument` never carried the field,
+     * so all three were type errors. The intent is documented in
+     * `obligations/deadlines.ts`: a test order COMPRESSES its obligation
+     * windows, so a tester can watch a deadline lapse inside one run instead of
+     * waiting the real number of days.
+     *
+     * 🛑 This does NOT enrol orders in the test-data purge. `runTestDataCleanup`
+     * deliberately leaves `orders`/`reviews`/`wishlists`/`history` alone — they
+     * denormalise what they display, so a swept order would leave a
+     * half-rendered row rather than disappear. The flag is read for timing, not
+     * for deletion, and adding it to `TEST_DATA_COLLECTIONS` would be a
+     * different and much larger decision.
+     *
+     * Optional, so no migration: every existing order reads `undefined`, which
+     * `deadlinesFor` tests with `=== true`.
+     */
+    isTestData?: boolean;
 }
 export type OrderPaymentRecordMethod = "manual" | "phonepe" | "razorpay" | "cod";
 export type OrderPaymentVerificationMethod = "manual_review" | "webhook" | "cod_collection" | "order_status";
@@ -810,6 +1056,30 @@ export interface OrderPaymentRecord {
     };
 }
 export declare const ORDER_COLLECTION: "orders";
+/**
+ * At-most-once gate for refunds. Document id = `sha256(idempotencyKey)`,
+ * claimed with `.create()` BEFORE any provider call.
+ *
+ * 🛑 A claim is deliberately NOT released on failure. Surviving a crash is the
+ * whole point: it stops a retry from issuing a second provider call for a
+ * refund that may already have succeeded at the gateway. An unsettled claim
+ * older than an hour is a crash between "provider called" and "entry settled",
+ * and resolving it means READING the gateway, never guessing — that is Phase
+ * 4's R3 reconciler.
+ *
+ * Classified **PRESERVE** in the tester tier (`tester/scripts/lib/collections.mjs`)
+ * because it is the only record that a refund was attempted and wiping it
+ * would let a replay re-refund.
+ *
+ * 🛑 It deliberately gets NO `SEED_COLLECTION_PURPOSE` entry, and that is not
+ * an oversight. `audit-seed-purpose`'s R1 requires that registry to match
+ * `COLLECTION_MAP` EXACTLY in both directions — a key for a collection the
+ * seeder never writes is a DEAD entry, the same shape as the `offers` entry in
+ * `TEST_DATA_COLLECTIONS` that could only ever match zero rows while reading
+ * as coverage. This collection has no seed data, so the tester tier is the
+ * only list it belongs in. (I added it to both first; R1 would have failed.)
+ */
+export declare const REFUND_CLAIMS_COLLECTION: "refundClaims";
 export declare const ORDER_INDEXED_FIELDS: readonly ["searchTxt", "userId", "productId", "storeId", "status", "paymentStatus", "payoutStatus", "shippingMethod", "orderDate", "createdAt", "assignedWorkerId", "pickedAt", "packedAt"];
 export declare const DEFAULT_ORDER_DATA: Partial<OrderDocument>;
 export declare const ORDER_PUBLIC_FIELDS: readonly ["id", "productId", "productTitle", "quantity", "unitPrice", "totalPrice", "currency", "status", "paymentStatus", "shippingAddress", "trackingNumber", "notes", "orderDate", "shippingDate", "deliveryDate", "createdAt"];

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

@@ -49,6 +49,30 @@ export const RefundStatusValues = {
     REJECTED: "rejected",
 };
 export const ORDER_COLLECTION = "orders";
+/**
+ * At-most-once gate for refunds. Document id = `sha256(idempotencyKey)`,
+ * claimed with `.create()` BEFORE any provider call.
+ *
+ * 🛑 A claim is deliberately NOT released on failure. Surviving a crash is the
+ * whole point: it stops a retry from issuing a second provider call for a
+ * refund that may already have succeeded at the gateway. An unsettled claim
+ * older than an hour is a crash between "provider called" and "entry settled",
+ * and resolving it means READING the gateway, never guessing — that is Phase
+ * 4's R3 reconciler.
+ *
+ * Classified **PRESERVE** in the tester tier (`tester/scripts/lib/collections.mjs`)
+ * because it is the only record that a refund was attempted and wiping it
+ * would let a replay re-refund.
+ *
+ * 🛑 It deliberately gets NO `SEED_COLLECTION_PURPOSE` entry, and that is not
+ * an oversight. `audit-seed-purpose`'s R1 requires that registry to match
+ * `COLLECTION_MAP` EXACTLY in both directions — a key for a collection the
+ * seeder never writes is a DEAD entry, the same shape as the `offers` entry in
+ * `TEST_DATA_COLLECTIONS` that could only ever match zero rows while reading
+ * as coverage. This collection has no seed data, so the tester tier is the
+ * only list it belongs in. (I added it to both first; R1 would have failed.)
+ */
+export const REFUND_CLAIMS_COLLECTION = "refundClaims";
 export const ORDER_INDEXED_FIELDS = [
     "searchTxt",
     "userId",

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

@@ -107,12 +107,26 @@ export declare const orderDocumentItemSchema: z.ZodObject<{
     listingType?: "classified" | "standard" | "auction" | "pre-order" | "prize-draw" | "digital-code" | "live" | undefined;
     prizeRevealStatus?: "closed" | "open" | "pending" | "revealed" | undefined;
 }>;
+/**
+ * Mirror of `OrderRefundEvent`.
+ *
+ * 🛑 THIS HAD ALREADY DRIFTED, and silently in the dangerous direction.
+ * `z.object()` STRIPS unknown keys, so a field present on the interface and
+ * absent here is **removed on parse** — it does not error, it vanishes. Before
+ * 2026-10-21 it was missing `reasonCode` AND `razorpayRefundId`, which means a
+ * Razorpay refund reference would have been discarded by the very schema meant
+ * to validate it.
+ *
+ * Keep this in lockstep with the interface. When adding a field there, add it
+ * here in the same change.
+ */
 export declare const orderRefundEventSchema: z.ZodObject<{
     refundId: z.ZodString;
     type: z.ZodEnum<["full", "partial"]>;
     amount: z.ZodEffects<z.ZodNumber, number, number>;
     itemIds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     reason: z.ZodString;
+    reasonCode: z.ZodOptional<z.ZodString>;
     refundedAt: z.ZodUnion<[z.ZodDate, z.ZodString, z.ZodObject<{
         toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
     }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
@@ -121,7 +135,12 @@ export declare const orderRefundEventSchema: z.ZodObject<{
         toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
     }, z.ZodTypeAny, "passthrough">>]>;
     refundedBy: z.ZodString;
+    status: z.ZodOptional<z.ZodEnum<["reserved", "processed", "failed"]>>;
+    failureReason: z.ZodOptional<z.ZodString>;
+    gatewayRefundId: z.ZodOptional<z.ZodString>;
+    gateway: z.ZodOptional<z.ZodString>;
     phonepeRefundId: z.ZodOptional<z.ZodString>;
+    razorpayRefundId: z.ZodOptional<z.ZodString>;
     manualTransactionId: z.ZodOptional<z.ZodString>;
     proofDocumentUrl: z.ZodOptional<z.ZodString>;
     proofDocumentMimeType: z.ZodOptional<z.ZodString>;
@@ -135,8 +154,14 @@ export declare const orderRefundEventSchema: z.ZodObject<{
         toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
     }, z.ZodTypeAny, "passthrough">;
     refundedBy: string;
+    status?: "failed" | "processed" | "reserved" | undefined;
+    failureReason?: string | undefined;
+    gateway?: string | undefined;
     itemIds?: string[] | undefined;
+    reasonCode?: string | undefined;
+    gatewayRefundId?: string | undefined;
     phonepeRefundId?: string | undefined;
+    razorpayRefundId?: string | undefined;
     manualTransactionId?: string | undefined;
     proofDocumentUrl?: string | undefined;
     proofDocumentMimeType?: string | undefined;
@@ -150,8 +175,14 @@ export declare const orderRefundEventSchema: z.ZodObject<{
         toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
     }, z.ZodTypeAny, "passthrough">;
     refundedBy: string;
+    status?: "failed" | "processed" | "reserved" | undefined;
+    failureReason?: string | undefined;
+    gateway?: string | undefined;
     itemIds?: string[] | undefined;
+    reasonCode?: string | undefined;
+    gatewayRefundId?: string | undefined;
     phonepeRefundId?: string | undefined;
+    razorpayRefundId?: string | undefined;
     manualTransactionId?: string | undefined;
     proofDocumentUrl?: string | undefined;
     proofDocumentMimeType?: string | undefined;
@@ -449,6 +480,7 @@ export declare const orderFirestoreSchema: z.ZodObject<{
         amount: z.ZodEffects<z.ZodNumber, number, number>;
         itemIds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
         reason: z.ZodString;
+        reasonCode: z.ZodOptional<z.ZodString>;
         refundedAt: z.ZodUnion<[z.ZodDate, z.ZodString, z.ZodObject<{
             toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
         }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
@@ -457,7 +489,12 @@ export declare const orderFirestoreSchema: z.ZodObject<{
             toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
         }, z.ZodTypeAny, "passthrough">>]>;
         refundedBy: z.ZodString;
+        status: z.ZodOptional<z.ZodEnum<["reserved", "processed", "failed"]>>;
+        failureReason: z.ZodOptional<z.ZodString>;
+        gatewayRefundId: z.ZodOptional<z.ZodString>;
+        gateway: z.ZodOptional<z.ZodString>;
         phonepeRefundId: z.ZodOptional<z.ZodString>;
+        razorpayRefundId: z.ZodOptional<z.ZodString>;
         manualTransactionId: z.ZodOptional<z.ZodString>;
         proofDocumentUrl: z.ZodOptional<z.ZodString>;
         proofDocumentMimeType: z.ZodOptional<z.ZodString>;
@@ -471,8 +508,14 @@ export declare const orderFirestoreSchema: z.ZodObject<{
             toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
         }, z.ZodTypeAny, "passthrough">;
         refundedBy: string;
+        status?: "failed" | "processed" | "reserved" | undefined;
+        failureReason?: string | undefined;
+        gateway?: string | undefined;
         itemIds?: string[] | undefined;
+        reasonCode?: string | undefined;
+        gatewayRefundId?: string | undefined;
         phonepeRefundId?: string | undefined;
+        razorpayRefundId?: string | undefined;
         manualTransactionId?: string | undefined;
         proofDocumentUrl?: string | undefined;
         proofDocumentMimeType?: string | undefined;
@@ -486,8 +529,14 @@ export declare const orderFirestoreSchema: z.ZodObject<{
             toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
         }, z.ZodTypeAny, "passthrough">;
         refundedBy: string;
+        status?: "failed" | "processed" | "reserved" | undefined;
+        failureReason?: string | undefined;
+        gateway?: string | undefined;
         itemIds?: string[] | undefined;
+        reasonCode?: string | undefined;
+        gatewayRefundId?: string | undefined;
         phonepeRefundId?: string | undefined;
+        razorpayRefundId?: string | undefined;
         manualTransactionId?: string | undefined;
         proofDocumentUrl?: string | undefined;
         proofDocumentMimeType?: string | undefined;
@@ -661,8 +710,14 @@ export declare const orderFirestoreSchema: z.ZodObject<{
             toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
         }, z.ZodTypeAny, "passthrough">;
         refundedBy: string;
+        status?: "failed" | "processed" | "reserved" | undefined;
+        failureReason?: string | undefined;
+        gateway?: string | undefined;
         itemIds?: string[] | undefined;
+        reasonCode?: string | undefined;
+        gatewayRefundId?: string | undefined;
         phonepeRefundId?: string | undefined;
+        razorpayRefundId?: string | undefined;
         manualTransactionId?: string | undefined;
         proofDocumentUrl?: string | undefined;
         proofDocumentMimeType?: string | undefined;
@@ -809,8 +864,14 @@ export declare const orderFirestoreSchema: z.ZodObject<{
             toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
         }, z.ZodTypeAny, "passthrough">;
         refundedBy: string;
+        status?: "failed" | "processed" | "reserved" | undefined;
+        failureReason?: string | undefined;
+        gateway?: string | undefined;
         itemIds?: string[] | undefined;
+        reasonCode?: string | undefined;
+        gatewayRefundId?: string | undefined;
         phonepeRefundId?: string | undefined;
+        razorpayRefundId?: string | undefined;
         manualTransactionId?: string | undefined;
         proofDocumentUrl?: string | undefined;
         proofDocumentMimeType?: string | undefined;

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

@@ -52,15 +52,37 @@ export const orderDocumentItemSchema = z.object({
     listingType: orderListingTypeSchema.optional(),
     prizeRevealStatus: z.enum(["pending", "open", "closed", "revealed"]).optional(),
 });
+/**
+ * Mirror of `OrderRefundEvent`.
+ *
+ * 🛑 THIS HAD ALREADY DRIFTED, and silently in the dangerous direction.
+ * `z.object()` STRIPS unknown keys, so a field present on the interface and
+ * absent here is **removed on parse** — it does not error, it vanishes. Before
+ * 2026-10-21 it was missing `reasonCode` AND `razorpayRefundId`, which means a
+ * Razorpay refund reference would have been discarded by the very schema meant
+ * to validate it.
+ *
+ * Keep this in lockstep with the interface. When adding a field there, add it
+ * here in the same change.
+ */
 export const orderRefundEventSchema = z.object({
     refundId: z.string(),
     type: orderRefundTypeSchema,
     amount: rupeesSchema,
     itemIds: z.array(z.string()).optional(),
     reason: z.string(),
+    reasonCode: z.string().optional(),
     refundedAt: firestoreDateSchema,
     refundedBy: z.string(),
+    // Two-phase lifecycle. Optional because pre-2026-10-21 rows carry none, and
+    // a missing status means "committed" to every reader.
+    status: z.enum(["reserved", "processed", "failed"]).optional(),
+    failureReason: z.string().optional(),
+    // Gateway-blind reference, the one a reconciler reads.
+    gatewayRefundId: z.string().optional(),
+    gateway: z.string().optional(),
     phonepeRefundId: z.string().optional(),
+    razorpayRefundId: z.string().optional(),
     manualTransactionId: z.string().optional(),
     proofDocumentUrl: z.string().optional(),
     proofDocumentMimeType: z.string().optional(),

package/dist/features/orders/types/index.d.ts

@@ -277,6 +277,44 @@ export interface Order {
     autoApproved?: boolean;
     disputeRaised?: boolean;
     disputeStatus?: "open" | "resolved";
+    /**
+     * Completion — the owner's rule, and both writers of one fact.
+     *
+     * 🛑 Added to the CLIENT type and the adapter together, because adding it to
+     * one alone is Root Cause #57 and the symptom is invisible: with
+     * `completedAt` undefined, `OrderCompletionPanel` renders its rating UI
+     * forever and never shows the "this order is complete" confirmation — which
+     * reads as correct behaviour rather than as a dropped field. That is exactly
+     * how the whole manual-payment flow sat dead for every buyer: the page gated
+     * its render on `paymentMethod`, the adapter mapped only `paymentStatus`, and
+     * the result was a polite "this order does not require manual payment".
+     *
+     * `completedBy` distinguishes the two paths, and they are not the same
+     * signal: `"system"` means nobody complained for seven days, a buyer's uid
+     * means they said they were happy. Same effect, different fact — so the
+     * confirmation copy says which one happened.
+     */
+    completedAt?: string;
+    completedBy?: string;
+    /**
+     * Anchors the panel needs to decide whether anything is contested.
+     *
+     * `returnRequestedAt` is load-bearing beyond the status check: a return can
+     * be requested and then the status moved on, so the status alone is not a
+     * complete answer to "is there a live return".
+     */
+    returnRequestedAt?: string;
+    /**
+     * Refund COUNT only, never the events.
+     *
+     * 🛑 Deliberately not `refunds[]`. The panel needs one bit — "has any money
+     * already moved on this order" — and the events carry `refundedBy` (a staff
+     * uid), `gatewayRefundId` and a `reason` string assembled for operators.
+     * Publishing all that to a buyer's page to answer a yes/no question is the
+     * spread-and-publish shape (Root Cause #70); a count answers it and leaks
+     * nothing.
+     */
+    refundCount?: number;
     /**
      * Manual-payment (cash / UPI / EMI) fields. Every one of these already
      * existed on `OrderDocument` but was dropped by `orderDocumentToOrder`,
@@ -320,6 +358,47 @@ export interface Order {
     /** Denormalized from the product at order-creation time — drives PrizeRevealModal copy. */
     prizeRevealMode?: "instant" | "scheduled";
 }
+/**
+ * What happened to the buyer's money when their order was cancelled.
+ *
+ * 🛑 Lives HERE, not beside the function that produces it
+ * (`_internal/server/features/orders/cancellation-refund.ts`), for one concrete
+ * reason: appkit publishes no `./_internal/*` subpath, so a type declared there
+ * is unreachable from the consumer — and the consumer is exactly who needs to
+ * name it, because the API route and the buyer's cancel page both return and
+ * render this value.
+ *
+ * It is returned rather than swallowed because *"₹2,499 is on its way back"* and
+ * *"we owe you ₹2,499 and someone will send it"* are different sentences, and
+ * a buyer who has just cancelled a paid order is entitled to the right one.
+ * Before D14 the answer was always a bare 200 and `"Order cancelled"` — true,
+ * and silent about the money, which is the defect.
+ */
+export type CancellationRefundOutcome = 
+/** Nothing to refund: never captured, or already returned in full. */
+{
+    moved: "none";
+    why: "not-paid" | "nothing-refundable";
+    amount: 0;
+}
+/** Refunded through the gateway, once, keyed on the order. */
+ | {
+    moved: "gateway";
+    amount: number;
+    refundId: string;
+}
+/**
+ * Owed and recorded, but no automatic rail could move it — a manual payment
+ * method, a post-dispatch cancellation, or a gateway refusal. A
+ * `manual_refund_due` case carries it to an operator; `caseId` is absent only
+ * if that write itself failed, which never blocks the cancellation.
+ */
+ | {
+    moved: "owed";
+    amount: number;
+    why: "post-dispatch" | "manual-payment" | "gateway-failed" | "no-gateway-reference";
+    caseId?: string;
+};
 export interface OrderListResponse {
     items: Order[];
     total: number;

package/dist/features/parts/components/PartsIndexPageView.js

@@ -1,6 +1,13 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Section, Container, Stack, Row, Div, Grid, Heading, Text, Span, TextLink, Badge, } from "../../../ui/index.js";
 import { ALL_PART_SLOTS, PART_SLOT_LABEL, } from "../schemas/firestore.js";
+/*
+ * 🛑 Rendered as JSX from a Server Component, which is the normal RSC
+ * boundary and is fine — the trap Root Cause #76 describes is CALLING a
+ * `/client` runtime value or reading a property off it, not rendering a
+ * client component. The toolbar needs the session, so it owns that itself.
+ */
+import { RecordOwnerQuickActions } from "../../admin/components/RecordOwnerQuickActions.js";
 export function PartsIndexPageView({ hrefForClassification, renderSearch, }) {
     return (_jsx(Section, { padding: "y-lg", children: _jsx(Container, { size: "lg", children: _jsxs(Stack, { gap: "lg", className: "min-w-0", children: [_jsxs(Stack, { gap: "xs", children: [_jsx(Heading, { level: 1, children: "Beyblade parts gallery" }), _jsxs(Text, { color: "muted", children: ["Every component we have a record of, by what it is. A code like", " ", _jsx(Span, { weight: "semibold", children: "RF" }), " or ", _jsx(Span, { weight: "semibold", children: "105" }), " means different things in different generations, so parts are grouped by their classification rather than by code."] })] }), renderSearch?.(), _jsx(Grid, { cols: "navTiles", gap: "sm", className: "min-w-0", children: ALL_PART_SLOTS.map((slot) => (_jsx(Div, { surface: "card", padding: "sm", rounded: "md", border: "subtle", className: "min-w-0", children: _jsx(TextLink, { href: hrefForClassification(slot), children: PART_SLOT_LABEL[slot] }) }, slot))) })] }) }) }));
 }
@@ -13,5 +20,5 @@ export function PartClassificationPageView({ slot, parts, truncated, hrefForPart
     const label = PART_SLOT_LABEL[slot] ?? slot;
     return (_jsx(Section, { padding: "y-lg", children: _jsx(Container, { size: "lg", children: _jsxs(Stack, { gap: "lg", className: "min-w-0", children: [_jsxs(Stack, { gap: "xs", children: [_jsx(Text, { size: "sm", color: "muted", children: _jsx(TextLink, { href: partsIndexHref, children: "Parts" }) }), _jsx(Heading, { level: 1, children: label }), _jsx(Text, { color: "muted", size: "sm", children: parts.length === 0
                                     ? "No parts recorded in this classification yet."
-                                    : `${parts.length}${truncated ? "+" : ""} recorded.` })] }), parts.length > 0 && (_jsx(Stack, { gap: "xs", className: "min-w-0", children: parts.map((p) => (_jsxs(Row, { gap: "sm", align: "center", padding: "inline", surface: "card", rounded: "md", border: "subtle", className: "min-w-0", children: [_jsxs(Div, { className: "flex-1 min-w-0", children: [_jsx(TextLink, { href: hrefForPart(p.slot, tailOf(p.id)), children: p.name }), typeof p.weightG === "number" && (_jsxs(Span, { size: "xs", color: "muted", children: [" ", "\u00B7 ", p.weightG, " g"] }))] }), p.code && (_jsx(Badge, { variant: "info", className: "flex-shrink-0", children: p.code }))] }, p.id))) }))] }) }) }));
+                                    : `${parts.length}${truncated ? "+" : ""} recorded.` })] }), parts.length > 0 && (_jsx(Stack, { gap: "xs", className: "min-w-0", children: parts.map((p) => (_jsxs(Row, { gap: "sm", align: "center", padding: "inline", surface: "card", rounded: "md", border: "subtle", className: "min-w-0", children: [_jsxs(Div, { className: "flex-1 min-w-0", children: [_jsx(TextLink, { href: hrefForPart(p.slot, tailOf(p.id)), children: p.name }), typeof p.weightG === "number" && (_jsxs(Span, { size: "xs", color: "muted", children: [" ", "\u00B7 ", p.weightG, " g"] }))] }), p.code && (_jsx(Badge, { variant: "info", className: "flex-shrink-0", children: p.code })), _jsx(RecordOwnerQuickActions, { resource: "PART", recordId: p.id, placement: "detail", recordLabel: p.name })] }, p.id))) }))] }) }) }));
 }