@mohasinac/appkit 4.61.0 → 4.62.1

package/dist/features/orders/repository/orders.repository.js

@@ -783,6 +783,52 @@ class OrderRepository extends BaseRepository {
             reason: ctx?.reason ?? target.reason,
         }, "orderRepository.settleRefund", order);
     }
+    /**
+     * Stamp a credit-note number onto one settled refund event (Phase 7, 7c).
+     *
+     * ## 🛑 Why this is a repository method and not an inline update
+     *
+     * `refunds[]` is written by re-mapping the whole array, exactly as
+     * `settleRefund` directly above does — because a read-modify-write of
+     * `[...existing, event]` LOSES a concurrent event (D6), and that defect is
+     * just as reachable from a credit-note stamp as from a refund append.
+     * Letting the invoicing feature touch the array directly would reintroduce
+     * it one caller away from the fix.
+     *
+     * It goes through `updateWithHistory` for the same reason every other
+     * mutator here does: the transition guard and the status-history entry live
+     * there, and this is a real recorded event on the order.
+     *
+     * 🛑 A missing refund event is a NO-OP, not a throw. The caller is the
+     * refund settle path, where money has already moved; raising here would turn
+     * a successful refund into a reported failure. See
+     * `issueCreditNoteForRefund`'s own 🛑.
+     */
+    async setRefundCreditNote(orderId, refundId, note, ctx) {
+        const order = await this.findById(orderId);
+        if (!order)
+            return null;
+        const existing = order.refunds ?? [];
+        const target = existing.find((r) => r.refundId === refundId);
+        if (!target)
+            return null;
+        // Already numbered — never overwrite. A credit-note number is issued once,
+        // and a second number for one reversal is a permanent gap in the series.
+        if (target.creditNoteNumber)
+            return order;
+        const stamped = existing.map((r) => r.refundId === refundId ? { ...r, ...note } : r);
+        return this.updateWithHistory(orderId, { refunds: stamped, updatedAt: new Date() }, {
+            ...ctx,
+            extraChanges: {
+                creditNote: {
+                    from: null,
+                    to: { refundId, creditNoteNumber: note.creditNoteNumber },
+                },
+            },
+            actor: ctx?.actor ?? { uid: "system:invoicing", role: "system" },
+            reason: ctx?.reason ?? `Credit note ${note.creditNoteNumber} issued`,
+        }, "orderRepository.setRefundCreditNote", order);
+    }
     /**
      * 🛑 LEGACY — prefer `reserveRefund` + `settleRefund`.
      *
@@ -878,6 +924,68 @@ class OrderRepository extends BaseRepository {
      * `paymentProofUrl != null` filter would silently exclude every doc where
      * the field isn't set at all — the opposite of what's needed here.
      */
+    /**
+     * Orders invoiced within a window — the GSTR-1 export's only query
+     * (Phase 7d).
+     *
+     * ## 🛑 Windowed on `invoiceIssuedAt`, not on the order date
+     *
+     * A COD order placed on 30 March and paid on 2 April is invoiced in the NEW
+     * financial year, and that is the period its tax belongs to. Numbering
+     * happens at the payment transition for exactly this reason, so the invoice
+     * date is the only correct axis — windowing on `orderDate` would file that
+     * order's tax in the year before it was invoiced.
+     *
+     * ## 🛑 It also returns PAID orders with no invoice number, deliberately
+     *
+     * Those are the ones the export must warn about rather than omit — a paid
+     * order silently absent from a tax return is the single error this whole
+     * feature exists to prevent. Firestore cannot OR across two fields, so the
+     * second query is a separate one and the caller merges; the alternative
+     * (one query on `paymentStatus`, filtered in memory) would scan every paid
+     * order ever placed.
+     *
+     * Unbounded `.limit(2000)`: a quarter's orders at this volume is a few
+     * hundred, and an export that silently truncated would understate a tax
+     * return. If this ever saturates, the fix is pagination with an explicit
+     * "more rows exist" signal in the CSV — never a higher cap.
+     */
+    async listInvoicedBetween(from, to) {
+        const [invoiced, paidUnnumbered] = await Promise.all([
+            this.db
+                .collection(this.collection)
+                .where("invoiceIssuedAt", ">=", from)
+                .where("invoiceIssuedAt", "<=", to)
+                .limit(2000)
+                .get(),
+            /*
+             * The exceptions. Bounded on `orderDate` because an un-invoiced order
+             * has no invoice date to window on — which is the whole problem with it
+             * — and because `paymentStatus == paid` alone would match every paid
+             * order in the collection's history.
+             */
+            this.db
+                .collection(this.collection)
+                .where(ORDER_FIELDS.PAYMENT_STATUS, "==", "paid")
+                .where(ORDER_FIELDS.ORDER_DATE, ">=", from)
+                .where(ORDER_FIELDS.ORDER_DATE, "<=", to)
+                .limit(2000)
+                .get(),
+        ]);
+        const byId = new Map();
+        for (const d of invoiced.docs) {
+            byId.set(d.id, { id: d.id, ...d.data() });
+        }
+        for (const d of paidUnnumbered.docs) {
+            const data = { id: d.id, ...d.data() };
+            // Only the genuinely un-numbered ones — a paid, numbered order is
+            // already in the first set, and adding it again would double every one
+            // of its rows in the return.
+            if (!data.invoiceNumber && !byId.has(d.id))
+                byId.set(d.id, data);
+        }
+        return [...byId.values()];
+    }
     async getExpiredPaymentDeadlines() {
         const snap = await this.db
             .collection(this.collection)
@@ -1056,6 +1164,27 @@ class OrderRepository extends BaseRepository {
              * early. Withholding is recoverable — the next sweep picks it up;
              * releasing early is not, because the money has gone.
              */
+            /*
+             * 🛑 A BUYER'S OWN CONFIRMATION RELEASES THE PAYOUT IMMEDIATELY.
+             *
+             * The owner's rule: an order is CONFIRMED when it is delivered and
+             * either the buyer says they received it, or 7 days pass. This filter
+             * only ever implemented the second half — `deliveryDate <= cutoff` —
+             * so a buyer who pressed "Mark complete" on day one still made their
+             * seller wait out the full hold. The fast path existed and bought the
+             * seller nothing.
+             *
+             * Safe in the direction that matters, and not by luck:
+             * `markOrderCompleteAction` is the only writer of `completedAt`, and it
+             * REFUSES while a return in any state, a posted refund or a buyer
+             * dispute is live — the same precondition the `order-complete`
+             * obligation carries. So honouring it here cannot release money while
+             * an issue is open; the hold is skipped only because the one party the
+             * hold protects has said they are satisfied.
+             */
+            const completedAt = toDateOrNull(o.data.completedAt);
+            if (completedAt)
+                return true;
             const anchor = toDateOrNull(o.data.deliveryDate) ?? toDateOrNull(o.data.updatedAt);
             if (!o.data.deliveryDate)
                 missingAnchor++;
@@ -1162,6 +1291,22 @@ OrderRepository.SELLER_SIEVE_FIELDS = {
     orderDate: { canFilter: true, canSort: true, parseValue: parseSieveDateValue },
     createdAt: { canFilter: true, canSort: true, parseValue: parseSieveDateValue },
     contestable: { canFilter: true, canSort: false },
+    /*
+     * Lane segregation on the SELLER's order list — the same provenance axis
+     * `/user/orders` has had.
+     *
+     * 🛑 It was absent, and absence here is SILENT: `sieve.ts` sets
+     * `throwExceptions: false`, so an unallowlisted field does not raise —
+     * `findField` returns undefined and the clause is simply dropped. A lane
+     * chip emitting `orderType==auction` would therefore have returned the
+     * seller's ENTIRE order list while looking exactly like a working filter
+     * (Root Cause #62). Checked before wiring the chip, not after.
+     *
+     * 🛑 Never pushed as `orderType==standard`, for the same reason the admin
+     * set above carries that note: orders written before the field existed have
+     * no value to match. `/api/store/orders` refines that one case in memory.
+     */
+    orderType: { canFilter: true, canSort: false },
     // Fulfilment flags. Filterable so "which of my orders need gift wrap?" is a
     // query against the orders themselves — the whole point of recording the
     // add-on on the order rather than keeping a side list of who asked for what.

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";
@@ -352,6 +353,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 {
@@ -426,6 +446,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 +516,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 +734,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 +774,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 +913,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.
      *
@@ -970,11 +1139,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/index.d.ts

@@ -53,8 +53,8 @@ export declare const emiInstallmentSchema: z.ZodObject<{
     }, z.ZodTypeAny, "passthrough">>]>>;
 }, "strip", z.ZodTypeAny, {
     status: "paid" | "pending" | "overdue";
-    amount: number;
     index: number;
+    amount: number;
     dueDate: string | Date | z.objectOutputType<{
         toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
     }, z.ZodTypeAny, "passthrough">;
@@ -68,8 +68,8 @@ export declare const emiInstallmentSchema: z.ZodObject<{
     }, z.ZodTypeAny, "passthrough"> | undefined;
 }, {
     status: "paid" | "pending" | "overdue";
-    amount: number;
     index: number;
+    amount: number;
     dueDate: string | Date | z.objectInputType<{
         toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
     }, z.ZodTypeAny, "passthrough">;
@@ -145,6 +145,15 @@ export declare const orderRefundEventSchema: z.ZodObject<{
     proofDocumentUrl: z.ZodOptional<z.ZodString>;
     proofDocumentMimeType: z.ZodOptional<z.ZodString>;
     overrideReason: z.ZodOptional<z.ZodString>;
+    creditNoteNumber: z.ZodOptional<z.ZodString>;
+    creditNoteIssuedAt: z.ZodOptional<z.ZodUnion<[z.ZodDate, z.ZodString, z.ZodObject<{
+        toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
+    }, z.ZodTypeAny, "passthrough">>]>>;
+    creditNoteStoragePath: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     type: "full" | "partial";
     amount: number;
@@ -155,8 +164,8 @@ export declare const orderRefundEventSchema: z.ZodObject<{
     }, z.ZodTypeAny, "passthrough">;
     refundedBy: string;
     status?: "failed" | "processed" | "reserved" | undefined;
-    failureReason?: string | undefined;
     gateway?: string | undefined;
+    failureReason?: string | undefined;
     itemIds?: string[] | undefined;
     reasonCode?: string | undefined;
     gatewayRefundId?: string | undefined;
@@ -166,6 +175,11 @@ export declare const orderRefundEventSchema: z.ZodObject<{
     proofDocumentUrl?: string | undefined;
     proofDocumentMimeType?: string | undefined;
     overrideReason?: string | undefined;
+    creditNoteNumber?: string | undefined;
+    creditNoteIssuedAt?: string | Date | z.objectOutputType<{
+        toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
+    }, z.ZodTypeAny, "passthrough"> | undefined;
+    creditNoteStoragePath?: string | undefined;
 }, {
     type: "full" | "partial";
     amount: number;
@@ -176,8 +190,8 @@ export declare const orderRefundEventSchema: z.ZodObject<{
     }, z.ZodTypeAny, "passthrough">;
     refundedBy: string;
     status?: "failed" | "processed" | "reserved" | undefined;
-    failureReason?: string | undefined;
     gateway?: string | undefined;
+    failureReason?: string | undefined;
     itemIds?: string[] | undefined;
     reasonCode?: string | undefined;
     gatewayRefundId?: string | undefined;
@@ -187,6 +201,11 @@ export declare const orderRefundEventSchema: z.ZodObject<{
     proofDocumentUrl?: string | undefined;
     proofDocumentMimeType?: string | undefined;
     overrideReason?: string | undefined;
+    creditNoteNumber?: string | undefined;
+    creditNoteIssuedAt?: string | Date | z.objectInputType<{
+        toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
+    }, z.ZodTypeAny, "passthrough"> | undefined;
+    creditNoteStoragePath?: string | undefined;
 }>;
 export declare const appliedOrderDiscountSchema: z.ZodObject<{
     code: z.ZodString;
@@ -405,8 +424,8 @@ export declare const orderFirestoreSchema: z.ZodObject<{
         }, z.ZodTypeAny, "passthrough">>]>>;
     }, "strip", z.ZodTypeAny, {
         status: "paid" | "pending" | "overdue";
-        amount: number;
         index: number;
+        amount: number;
         dueDate: string | Date | z.objectOutputType<{
             toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
         }, z.ZodTypeAny, "passthrough">;
@@ -420,8 +439,8 @@ export declare const orderFirestoreSchema: z.ZodObject<{
         }, z.ZodTypeAny, "passthrough"> | undefined;
     }, {
         status: "paid" | "pending" | "overdue";
-        amount: number;
         index: number;
+        amount: number;
         dueDate: string | Date | z.objectInputType<{
             toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
         }, z.ZodTypeAny, "passthrough">;
@@ -499,6 +518,15 @@ export declare const orderFirestoreSchema: z.ZodObject<{
         proofDocumentUrl: z.ZodOptional<z.ZodString>;
         proofDocumentMimeType: z.ZodOptional<z.ZodString>;
         overrideReason: z.ZodOptional<z.ZodString>;
+        creditNoteNumber: z.ZodOptional<z.ZodString>;
+        creditNoteIssuedAt: z.ZodOptional<z.ZodUnion<[z.ZodDate, z.ZodString, z.ZodObject<{
+            toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
+        }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+            toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
+        }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+            toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
+        }, z.ZodTypeAny, "passthrough">>]>>;
+        creditNoteStoragePath: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         type: "full" | "partial";
         amount: number;
@@ -509,8 +537,8 @@ export declare const orderFirestoreSchema: z.ZodObject<{
         }, z.ZodTypeAny, "passthrough">;
         refundedBy: string;
         status?: "failed" | "processed" | "reserved" | undefined;
-        failureReason?: string | undefined;
         gateway?: string | undefined;
+        failureReason?: string | undefined;
         itemIds?: string[] | undefined;
         reasonCode?: string | undefined;
         gatewayRefundId?: string | undefined;
@@ -520,6 +548,11 @@ export declare const orderFirestoreSchema: z.ZodObject<{
         proofDocumentUrl?: string | undefined;
         proofDocumentMimeType?: string | undefined;
         overrideReason?: string | undefined;
+        creditNoteNumber?: string | undefined;
+        creditNoteIssuedAt?: string | Date | z.objectOutputType<{
+            toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
+        }, z.ZodTypeAny, "passthrough"> | undefined;
+        creditNoteStoragePath?: string | undefined;
     }, {
         type: "full" | "partial";
         amount: number;
@@ -530,8 +563,8 @@ export declare const orderFirestoreSchema: z.ZodObject<{
         }, z.ZodTypeAny, "passthrough">;
         refundedBy: string;
         status?: "failed" | "processed" | "reserved" | undefined;
-        failureReason?: string | undefined;
         gateway?: string | undefined;
+        failureReason?: string | undefined;
         itemIds?: string[] | undefined;
         reasonCode?: string | undefined;
         gatewayRefundId?: string | undefined;
@@ -541,6 +574,11 @@ export declare const orderFirestoreSchema: z.ZodObject<{
         proofDocumentUrl?: string | undefined;
         proofDocumentMimeType?: string | undefined;
         overrideReason?: string | undefined;
+        creditNoteNumber?: string | undefined;
+        creditNoteIssuedAt?: string | Date | z.objectInputType<{
+            toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
+        }, z.ZodTypeAny, "passthrough"> | undefined;
+        creditNoteStoragePath?: string | undefined;
     }>, "many">>;
     contestable: z.ZodOptional<z.ZodBoolean>;
     adminBypassBy: z.ZodOptional<z.ZodString>;
@@ -684,8 +722,8 @@ export declare const orderFirestoreSchema: z.ZodObject<{
     emiSurchargeAmount?: number | undefined;
     emiInstallments?: {
         status: "paid" | "pending" | "overdue";
-        amount: number;
         index: number;
+        amount: number;
         dueDate: string | Date | z.objectOutputType<{
             toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
         }, z.ZodTypeAny, "passthrough">;
@@ -711,8 +749,8 @@ export declare const orderFirestoreSchema: z.ZodObject<{
         }, z.ZodTypeAny, "passthrough">;
         refundedBy: string;
         status?: "failed" | "processed" | "reserved" | undefined;
-        failureReason?: string | undefined;
         gateway?: string | undefined;
+        failureReason?: string | undefined;
         itemIds?: string[] | undefined;
         reasonCode?: string | undefined;
         gatewayRefundId?: string | undefined;
@@ -722,6 +760,11 @@ export declare const orderFirestoreSchema: z.ZodObject<{
         proofDocumentUrl?: string | undefined;
         proofDocumentMimeType?: string | undefined;
         overrideReason?: string | undefined;
+        creditNoteNumber?: string | undefined;
+        creditNoteIssuedAt?: string | Date | z.objectOutputType<{
+            toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
+        }, z.ZodTypeAny, "passthrough"> | undefined;
+        creditNoteStoragePath?: string | undefined;
     }[] | undefined;
     contestable?: boolean | undefined;
     adminBypassBy?: string | undefined;
@@ -838,8 +881,8 @@ export declare const orderFirestoreSchema: z.ZodObject<{
     emiSurchargeAmount?: number | undefined;
     emiInstallments?: {
         status: "paid" | "pending" | "overdue";
-        amount: number;
         index: number;
+        amount: number;
         dueDate: string | Date | z.objectInputType<{
             toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
         }, z.ZodTypeAny, "passthrough">;
@@ -865,8 +908,8 @@ export declare const orderFirestoreSchema: z.ZodObject<{
         }, z.ZodTypeAny, "passthrough">;
         refundedBy: string;
         status?: "failed" | "processed" | "reserved" | undefined;
-        failureReason?: string | undefined;
         gateway?: string | undefined;
+        failureReason?: string | undefined;
         itemIds?: string[] | undefined;
         reasonCode?: string | undefined;
         gatewayRefundId?: string | undefined;
@@ -876,6 +919,11 @@ export declare const orderFirestoreSchema: z.ZodObject<{
         proofDocumentUrl?: string | undefined;
         proofDocumentMimeType?: string | undefined;
         overrideReason?: string | undefined;
+        creditNoteNumber?: string | undefined;
+        creditNoteIssuedAt?: string | Date | z.objectInputType<{
+            toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
+        }, z.ZodTypeAny, "passthrough"> | undefined;
+        creditNoteStoragePath?: string | undefined;
     }[] | undefined;
     contestable?: boolean | undefined;
     adminBypassBy?: string | undefined;

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

@@ -87,6 +87,18 @@ export const orderRefundEventSchema = z.object({
     proofDocumentUrl: z.string().optional(),
     proofDocumentMimeType: z.string().optional(),
     overrideReason: z.string().optional(),
+    /*
+     * Phase 7 credit note. Added HERE in the same change as the interface, per
+     * the 🛑 above: `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. That is exactly how this schema silently discarded
+     * `razorpayRefundId`, and a credit-note number discarded on parse is a
+     * numbered document with nothing pointing at it: the number is consumed, the
+     * series has no gap, and no refund claims it.
+     */
+    creditNoteNumber: z.string().optional(),
+    creditNoteIssuedAt: firestoreDateSchema.optional(),
+    creditNoteStoragePath: z.string().optional(),
 });
 export const appliedOrderDiscountSchema = z.object({
     code: z.string(),