@mohasinac/appkit 4.62.0 → 4.63.0

package/dist/features/orders/repository/orders.repository.d.ts

@@ -5,6 +5,7 @@ import { BaseRepository, parseSieveDateValue } from "../../../providers/db-fireb
 import { type OrderCreateInput, type OrderDocument, type OrderPlain, type OrderRefundEvent } from "../schemas";
 import { type HistoryActor, type FieldChange } from "../../../_internal/shared/history/index";
 import type { OrderStatus, PaymentStatus } from "../types";
+import type { OrderType } from "../utils/order-splitter";
 import { type PaymentReviewQueueMode } from "../constants/payment-window";
 /**
  * Who/why for a write that lands in `statusHistory`.
@@ -64,7 +65,7 @@ declare class OrderRepository extends BaseRepository<OrderDocument> {
      * encryption lived in a private method only three call sites remembered to
      * call.
      */
-    protected piiFields: readonly ["userName", "userEmail", "sellerEmail"];
+    protected piiFields: readonly ["userName", "userEmail", "sellerEmail", "deliveryFullName", "deliveryPhone", "deliveryAddressLine1", "deliveryAddressLine2", "deliveryLandmark", "deliveryAmendments[].fullName", "deliveryAmendments[].phone", "deliveryAmendments[].addressLine1", "deliveryAmendments[].addressLine2", "deliveryAmendments[].landmark"];
     /** Plaintext PII. **Opt-in and named** — shows up in review and in a grep. */
     revealOrder(doc: OrderDocument): OrderPlain;
     /** As `revealOrder`, for a list read. */
@@ -144,6 +145,20 @@ declare class OrderRepository extends BaseRepository<OrderDocument> {
      * `order.bundleId` at creation time (SB3 / SB6-C).
      */
     countByUserAndBundle(userId: string, bundleId: string): Promise<number>;
+    /**
+     * How many orders this buyer has placed, optionally scoped to one lane.
+     *
+     * A Firestore aggregation — billed at one read per 1000 index entries
+     * matched, not one per order — so it stays flat as an account's history
+     * grows. That matters because the only caller is the session profile
+     * endpoint, which every page load hits.
+     *
+     * 🛑 `orderType` may only name a NON-standard lane. The field was added
+     * after orders already existed, so an equality on `"standard"` would return
+     * zero for every legacy order while looking perfectly correct — see the
+     * constant's own note.
+     */
+    countForUser(userId: string, orderType?: Exclude<OrderType, "standard">): Promise<number>;
     deleteByUser(userId: string): Promise<number>;
     static readonly SELLER_SIEVE_FIELDS: {
         id: {
@@ -196,6 +211,10 @@ declare class OrderRepository extends BaseRepository<OrderDocument> {
             canFilter: boolean;
             canSort: boolean;
         };
+        orderType: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
         giftWrapAddon: {
             canFilter: boolean;
             canSort: boolean;
@@ -404,6 +423,32 @@ declare class OrderRepository extends BaseRepository<OrderDocument> {
         status: "failed";
         failureReason?: string;
     }, becomeRefunded?: boolean, ctx?: OrderWriteContext): Promise<OrderDocument>;
+    /**
+     * 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 🛑.
+     */
+    setRefundCreditNote(orderId: string, refundId: string, note: {
+        creditNoteNumber: string;
+        creditNoteIssuedAt: Date;
+        creditNoteStoragePath?: string;
+    }, ctx?: OrderWriteContext): Promise<OrderDocument | null>;
     /**
      * 🛑 LEGACY — prefer `reserveRefund` + `settleRefund`.
      *
@@ -442,6 +487,33 @@ declare class OrderRepository extends BaseRepository<OrderDocument> {
      * `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.
+     */
+    listInvoicedBetween(from: Date, to: Date): Promise<OrderDocument[]>;
     getExpiredPaymentDeadlines(): Promise<Array<{
         id: string;
         ref: DocumentReference;
@@ -507,6 +579,18 @@ declare class OrderRepository extends BaseRepository<OrderDocument> {
      */
     getEligibleAutomatic(cutoff: Date, opts?: {
         onWarn?: (msg: string, meta?: Record<string, JsonValue>) => void;
+        /**
+         * Stores paid at SHIPPING rather than at delivery.
+         *
+         * 🛑 A faster path through the SAME query, not a second one. A `shipped`
+         * row is admitted only for a store in this set, and then skips the hold
+         * anchor — being paid before delivery is the entire grant, so applying a
+         * post-delivery hold to it would make the flag do nothing.
+         *
+         * Omitted or empty means nobody is trusted, which is the correct default
+         * and reproduces the pre-existing behaviour exactly.
+         */
+        trustedStoreIds?: ReadonlySet<string>;
     }): Promise<Array<{
         id: string;
         ref: DocumentReference;

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

@@ -9,7 +9,7 @@ import { normalizeError } from "../../../errors/normalize.js";
  * that mix-up swallowing ~100 call sites' validation messages.
  */
 import { DatabaseError, NotFoundError, ValidationError } from "../../../errors/index.js";
-import { BaseRepository, prepareForFirestore, parseSieveDateValue, } from "../../../providers/db-firebase/index.js";
+import { BaseRepository, prepareForFirestore, parseSieveDateValue, getFirestoreCount, } from "../../../providers/db-firebase/index.js";
 import { maskPii, revealPii, ORDER_PII_FIELDS, } from "../../../security/index.js";
 import { serverTimestamp, arrayUnion } from "../../../contracts/field-ops.js";
 import { createOrderId, ORDER_COLLECTION, ORDER_TRACKED_FIELDS, OrderStatusValues, } from "../schemas/index.js";
@@ -304,10 +304,11 @@ class OrderRepository extends BaseRepository {
             reason: ctx?.reason,
             note: ctx?.note,
             extraChanges: ctx?.extraChanges,
-            // `encryptPiiFields` is a flat top-level loop and never descends into
-            // arrays, so anything PII-named reaching `changes` would persist in
-            // PLAINTEXT inside statusHistory. None of ORDER_TRACKED_FIELDS is PII
-            // today — this is defence for the next field somebody adds.
+            // `encryptPiiFields` covers a field only where it is NAMED, so a
+            // PII-named value reaching `changes` is plaintext unless somebody
+            // declared `statusHistory[].changes.<that key>` — which nobody will.
+            // The scrub removes the guesswork. None of ORDER_TRACKED_FIELDS is PII
+            // today; this is defence for the next field somebody adds.
             piiFields: ORDER_PII_FIELDS,
             historyField: "statusHistory",
             truncatedField: "statusHistoryTruncated",
@@ -516,6 +517,26 @@ class OrderRepository extends BaseRepository {
             .get();
         return snapshot.size;
     }
+    /**
+     * How many orders this buyer has placed, optionally scoped to one lane.
+     *
+     * A Firestore aggregation — billed at one read per 1000 index entries
+     * matched, not one per order — so it stays flat as an account's history
+     * grows. That matters because the only caller is the session profile
+     * endpoint, which every page load hits.
+     *
+     * 🛑 `orderType` may only name a NON-standard lane. The field was added
+     * after orders already existed, so an equality on `"standard"` would return
+     * zero for every legacy order while looking perfectly correct — see the
+     * constant's own note.
+     */
+    async countForUser(userId, orderType) {
+        let query = this.getCollection().where(ORDER_FIELDS.USER_ID, "==", userId);
+        if (orderType) {
+            query = query.where(ORDER_FIELDS.ORDER_TYPE, "==", orderType);
+        }
+        return getFirestoreCount(query);
+    }
     async deleteByUser(userId) {
         try {
             const snapshot = await this.getCollection()
@@ -783,6 +804,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 +945,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)
@@ -1031,10 +1160,23 @@ class OrderRepository extends BaseRepository {
          * and the anchor test is a per-row predicate below. One query, no new
          * composite index, and no way to silently return nothing.
          */
+        const trusted = opts?.trustedStoreIds ?? new Set();
         const snap = await this.db
             .collection(this.collection)
             .where(ORDER_FIELDS.PAYOUT_STATUS, "==", "eligible")
-            .where(ORDER_FIELDS.STATUS, "==", OrderStatusValues.DELIVERED)
+            /*
+             * 🛑 Widened to an `in` ONLY when some store is trusted.
+             *
+             * Firestore's `in` is an OR of equalities, so the existing
+             * `(payoutStatus, status)` composite serves both forms and no new index
+             * is needed. Keeping the plain equality when the set is empty matters
+             * anyway: a deployment with no trusted sellers then runs byte-identically
+             * to before, so the flag cannot change behaviour for anyone who has not
+             * been granted it.
+             */
+            .where(ORDER_FIELDS.STATUS, ...(trusted.size > 0
+            ? ["in", [OrderStatusValues.DELIVERED, OrderStatusValues.SHIPPED]]
+            : ["==", OrderStatusValues.DELIVERED]))
             .limit(500)
             .get();
         let missingAnchor = 0;
@@ -1045,6 +1187,26 @@ class OrderRepository extends BaseRepository {
             data: { id: d.id, ...d.data() },
         }))
             .filter((o) => !o.data.emiEnabled || o.data.emiComplete)
+            .filter((o) => {
+            /*
+             * 🛑 A SHIPPED row is admitted only for a TRUSTED store, and then
+             * bypasses the hold entirely — paying at shipping is the grant.
+             *
+             * Tested before the anchor rather than inside it, because a shipped
+             * order has no `deliveryDate` and would fall through to the
+             * `updatedAt` fallback — which is always LATER than delivery would
+             * have been. A trusted seller would be paid more SLOWLY than an
+             * untrusted one: the flag would read as working and do the opposite.
+             *
+             * The `in` above cannot express "shipped, but only for these stores",
+             * so the store test has to live here — otherwise one trusted seller
+             * anywhere would widen the sweep for every seller.
+             */
+            if (o.data.status === OrderStatusValues.SHIPPED) {
+                return typeof o.data.storeId === "string" && trusted.has(o.data.storeId);
+            }
+            return true;
+        })
             .filter((o) => {
             /*
              * The anchor, with a conservative fallback. `deliveryDate` is the
@@ -1056,6 +1218,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 +1345,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/balance.d.ts

@@ -0,0 +1,40 @@
+/**
+ * D55 — write shapes for the pre-order balance collector.
+ *
+ * 🛑 Both are `.strict()`, and that is the Root Cause #76 lesson rather than
+ * tidiness: the balance block carries `status`, `reviewedBy`, `reviewedAt`
+ * and `amount`, and a write shape that can NAME a field is a write shape that
+ * can destroy it. A buyer must not be able to send `status: "paid"` or
+ * `amount: 1`, and `z.object()` merely STRIPS unknown keys — which is the
+ * same silent-success failure as the grouped-listings PATCH. `.strict()`
+ * makes it a 400 instead.
+ *
+ * Neither schema is where `amount` comes from. It is snapshotted from
+ * `sourceContext.balanceDue` when the seller opens collection, months before
+ * this, and is never re-read from the live product (D61).
+ */
+import { z } from "zod";
+/** The buyer's proof of payment. */
+export declare const balanceProofSchema: z.ZodObject<{
+    proofUrl: z.ZodString;
+    transactionId: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    transactionId: string;
+    proofUrl: string;
+}, {
+    transactionId: string;
+    proofUrl: string;
+}>;
+export type BalanceProofInput = z.infer<typeof balanceProofSchema>;
+/** The admin's verdict on a submitted proof. */
+export declare const balanceReviewSchema: z.ZodObject<{
+    approve: z.ZodBoolean;
+    note: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    approve: boolean;
+    note?: string | undefined;
+}, {
+    approve: boolean;
+    note?: string | undefined;
+}>;
+export type BalanceReviewInput = z.infer<typeof balanceReviewSchema>;

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

@@ -0,0 +1,47 @@
+/**
+ * D55 — write shapes for the pre-order balance collector.
+ *
+ * 🛑 Both are `.strict()`, and that is the Root Cause #76 lesson rather than
+ * tidiness: the balance block carries `status`, `reviewedBy`, `reviewedAt`
+ * and `amount`, and a write shape that can NAME a field is a write shape that
+ * can destroy it. A buyer must not be able to send `status: "paid"` or
+ * `amount: 1`, and `z.object()` merely STRIPS unknown keys — which is the
+ * same silent-success failure as the grouped-listings PATCH. `.strict()`
+ * makes it a 400 instead.
+ *
+ * Neither schema is where `amount` comes from. It is snapshotted from
+ * `sourceContext.balanceDue` when the seller opens collection, months before
+ * this, and is never re-read from the live product (D61).
+ */
+import { z } from "zod";
+/** The buyer's proof of payment. */
+export const balanceProofSchema = z
+    .object({
+    /*
+     * A `/media/…` slug from the signed-URL upload flow — bytes never reach
+     * this route (Rule #6's 4.5 MB payload cap, and § Media Architecture).
+     */
+    proofUrl: z.string().min(1, "Upload a screenshot of the payment."),
+    /*
+     * The UTR or UPI reference. Required, because it is the only thing an
+     * admin can check the payment against — a screenshot alone is a picture.
+     */
+    transactionId: z
+        .string()
+        .min(4, "Enter the transaction reference from your bank or UPI app.")
+        .max(64),
+})
+    .strict();
+/** The admin's verdict on a submitted proof. */
+export const balanceReviewSchema = z
+    .object({
+    approve: z.boolean(),
+    /*
+     * Optional HERE and required in `reviewBalanceProof` when `approve` is
+     * false. Deliberately not a `.refine()`: the rule belongs with the
+     * transition it guards, and duplicating it would give two places to
+     * disagree. An approval genuinely needs no note.
+     */
+    note: z.string().max(300).optional(),
+})
+    .strict();