@mohasinac/appkit 4.42.18 → 4.44.0

package/dist/features/categories/repository/categories.repository.js

@@ -1,15 +1,45 @@
 import { normalizeError } from "../../../errors/normalize";
 import { increment, arrayUnion, arrayRemove, } from "../../../contracts/field-ops";
 import { DatabaseError } from "../../../errors";
-import { BaseRepository, prepareForFirestore, parseSieveDateValue, } from "../../../providers/db-firebase";
+import { BaseRepository, prepareForFirestore, parseSieveDateValue, applySieveToFirestore, } from "../../../providers/db-firebase";
+import { buildCategorySearchTxt } from "../../../utils/search-txt-builders";
+import { planSearchTxt, refineSearchTxt, emptySearchResult, } from "../../../utils/search-txt-query";
 import { PRODUCT_FIELDS } from "../../../constants/field-names";
 import { CATEGORY_FIELDS, CATEGORIES_COLLECTION, MIN_ITEMS_FOR_FEATURED, buildCategoryTree, calculateCategoryFields, canBeFeatured, createCategoryId, isValidCategoryMove, } from "../schemas";
 export class CategoriesRepository extends BaseRepository {
     constructor() {
         super(CATEGORIES_COLLECTION);
     }
-    async list(model) {
-        return this.sieveQuery(model, CategoriesRepository.SIEVE_FIELDS);
+    /** Derived on every write path via `applyWriteHooks`. */
+    buildSearchTxtFor(data) {
+        return buildCategorySearchTxt(data);
+    }
+    async list(model, opts) {
+        /*
+         * `q` is a searchTxt pushdown, NOT a Sieve filter.
+         *
+         * `plan.head` becomes one `array-contains` on the longest term and
+         * `plan.rest` is AND-refined in memory — the same two-part shape the other
+         * ten migrated collections use. Going through `planSearchTxt` rather than
+         * hand-rolling it is what buys the `empty` guard: a query that normalises
+         * to no usable token (`"!!!"`, `"—"`) must return NOTHING, because
+         * emitting no clause at all returns the whole collection and calls it a
+         * search result. That is the live bug `products` still has (A2).
+         */
+        const plan = planSearchTxt(opts?.search);
+        if (plan.empty)
+            return emptySearchResult();
+        if (!plan.head) {
+            return this.sieveQuery(model, CategoriesRepository.SIEVE_FIELDS);
+        }
+        const baseQuery = this.getCollection().where(CATEGORY_FIELDS.SEARCH_TXT, "array-contains", plan.head);
+        const result = await applySieveToFirestore({
+            baseQuery,
+            model,
+            fields: CategoriesRepository.SIEVE_FIELDS,
+            mapDoc: (snap) => this.mapDoc(snap),
+        });
+        return refineSearchTxt(result, plan.rest);
     }
     async createWithHierarchy(input) {
         try {
@@ -112,14 +142,26 @@ export class CategoriesRepository extends BaseRepository {
             throw new DatabaseError(`Failed to retrieve leaf categories: ${error instanceof Error ? error.message : "Unknown error"}`);
         }
     }
-    async getCategoriesByTier(tier) {
+    /**
+     * @param limit 0 = unbounded (the historical behaviour). When > 0 the bound is
+     *   pushed into Firestore instead of slicing after the read.
+     *
+     * 🛑 The limit is applied with HEADROOM, not exactly, because `!isBrand` is a
+     * post-fetch filter: brand rows live in this same collection (they are
+     * `CategoryDocument`s discriminated by `isBrand`), so a bare `.limit(n)` could
+     * return n brand rows, filter all of them out, and yield an empty tier. The
+     * caller still slices to its own limit.
+     */
+    async getCategoriesByTier(tier, limit = 0) {
         try {
-            const snapshot = await this.db
+            let query = this.db
                 .collection(this.collection)
                 .where(CATEGORY_FIELDS.TIER, "==", tier)
                 .where(CATEGORY_FIELDS.IS_ACTIVE, "==", true)
-                .orderBy(CATEGORY_FIELDS.ORDER, "asc")
-                .get();
+                .orderBy(CATEGORY_FIELDS.ORDER, "asc");
+            if (limit > 0)
+                query = query.limit(limit * 4);
+            const snapshot = await query.get();
             return snapshot.docs
                 .map((doc) => this.mapDoc(doc))
                 .filter((category) => !category.isBrand);
@@ -129,21 +171,139 @@ export class CategoriesRepository extends BaseRepository {
             throw new DatabaseError(`Failed to retrieve categories by tier: ${error instanceof Error ? error.message : "Unknown error"}`);
         }
     }
-    async getCategoriesByRootId(rootId) {
+    /**
+     * Every category sharing a root, tier-then-order.
+     *
+     * 🛑 `limit` is for DISPLAY callers only, and it is a real truncation.
+     * `buildTree(rootId)` must pass nothing: a tree built from a truncated node
+     * list silently drops whole branches, which is the exact failure
+     * `getDescendants`'s docstring was rewritten to avoid. A display grid of
+     * sibling categories, by contrast, renders ~20 tiles and has no reason to
+     * read 1,500 documents to do it.
+     *
+     * Paginated rather than one unbounded `.get()`: the previous form read the
+     * whole root subtree into memory on every category page render, which at the
+     * ~330-node forest this plan seeds is ~9% of a 50K/day Firestore budget for
+     * ONE page view.
+     */
+    /**
+     * Several categories by id, in ONE round trip, in the order asked for.
+     *
+     * The ancestor-walk primitive. A five-tier tree means a leaf has up to four
+     * ancestors, and resolving an inherited description template or an inherited
+     * `productDefaults` means reading them nearest-first until the answer is
+     * found — which as four sequential `findById` calls is four round trips, on
+     * a route the seller form hits on every category change. Rule #6 budgets
+     * about three for a whole request.
+     *
+     * 🛑 Order is PRESERVED and missing ids are DROPPED, not nulled. Callers
+     * walk the result looking for the first document that declares a thing, so
+     * "nearest first" has to survive the round trip — Firestore's `getAll`
+     * already answers in argument order, and this keeps that guarantee explicit
+     * rather than incidental. A caller needing to know WHICH id was missing
+     * should compare lengths; none does, because an ancestor that no longer
+     * exists is a data problem for the reconcile job, not a reason to fail a
+     * form.
+     *
+     * Bounded at 30 to match `array-contains-any`'s cap, so this cannot become
+     * the unbounded read that `getCategoriesByRootId` had to be rewritten to
+     * avoid being.
+     */
+    async findByIds(ids) {
+        const unique = Array.from(new Set(ids.filter(Boolean))).slice(0, 30);
+        if (unique.length === 0)
+            return [];
         try {
-            const snapshot = await this.db
-                .collection(this.collection)
-                .where(CATEGORY_FIELDS.ROOT_ID, "==", rootId)
-                .orderBy(CATEGORY_FIELDS.TIER, "asc")
-                .orderBy(CATEGORY_FIELDS.ORDER, "asc")
-                .get();
-            return snapshot.docs.map((doc) => this.mapDoc(doc));
+            const refs = unique.map((id) => this.db.collection(this.collection).doc(id));
+            const snaps = await this.db.getAll(...refs);
+            return snaps
+                .filter((s) => s.exists)
+                .map((s) => this.mapDoc(s));
+        }
+        catch (err) {
+            const e = normalizeError(err);
+            /*
+             * 🛑 The raw `.message` is NOT interpolated into the thrown error — only
+             * the normalised `kind` and a count.
+             *
+             * Several older methods in this file do interpolate it, and
+             * `audit-raw-error-text` flagged this one for trying. The reasoning is
+             * Root Cause #86's: a thrown value's message is written for a developer,
+             * and this one reaches a user through the route's 500 branch — which is
+             * how a Node `MODULE_NOT_FOUND` with a full require stack ended up
+             * rendered inside the "Place your bid" modal.
+             *
+             * The ids are counted rather than listed. A category id is not
+             * sensitive, but 30 of them in one line is noise against Hobby's ~4 KB/s
+             * log budget.
+             *
+             * (`normalizeError` has to be the FIRST statement, not merely nearby:
+             * `audit-catch-normalize` looks within a few lines of the catch, and the
+             * first draft put this comment above the call and tripped it.)
+             */
+            throw new DatabaseError(`Failed to read categories by id (${unique.length} requested): ${e.kind}`);
+        }
+    }
+    async getCategoriesByRootId(rootId, opts) {
+        try {
+            const cap = opts?.limit;
+            const pageSize = cap ? Math.min(cap, 300) : 300;
+            const out = [];
+            let cursor = null;
+            for (;;) {
+                let q = this.db
+                    .collection(this.collection)
+                    .where(CATEGORY_FIELDS.ROOT_ID, "==", rootId)
+                    .orderBy(CATEGORY_FIELDS.TIER, "asc")
+                    .orderBy(CATEGORY_FIELDS.ORDER, "asc")
+                    .limit(pageSize);
+                if (cursor)
+                    q = q.startAfter(cursor);
+                const page = await q.get();
+                if (page.empty)
+                    break;
+                for (const doc of page.docs)
+                    out.push(this.mapDoc(doc));
+                if (cap && out.length >= cap)
+                    return out.slice(0, cap);
+                if (page.size < pageSize)
+                    break;
+                cursor = page.docs[page.docs.length - 1];
+            }
+            return out;
         }
         catch (error) {
             void normalizeError(error);
             throw new DatabaseError(`Failed to retrieve categories by rootId: ${error instanceof Error ? error.message : "Unknown error"}`);
         }
     }
+    /**
+     * Categories whose `productDefaults.taxCodeId` points at `taxCodeId`.
+     *
+     * 🛑 Exists so DELETE on a tax code can REFUSE while it is referenced.
+     * `taxCodeId` is a plain string with no referential integrity, and a
+     * dangling reference does not error — `findResolvable` answers `null`,
+     * whose correct handling is "leave the product's gstRate alone", so every
+     * subsequent listing under that category silently derives NO TAX. It does
+     * not fail; it under-charges, until someone reads an invoice.
+     *
+     * One equality on a dot-path — served by the automatic index, no composite
+     * to declare. Bounded at 200: the answer is used to NAME referrers in a 409
+     * message, and the first five are what the admin reads.
+     */
+    async findByTaxCodeId(taxCodeId) {
+        try {
+            const snap = await this.getCollection()
+                .where(CATEGORY_FIELDS.PRODUCT_DEFAULTS_TAX_CODE_ID, "==", taxCodeId)
+                .limit(200)
+                .get();
+            return snap.docs.map((d) => this.mapDoc(d));
+        }
+        catch (error) {
+            void normalizeError(error);
+            throw new DatabaseError(`Failed to find categories by tax code: ${error instanceof Error ? error.message : "Unknown error"}`);
+        }
+    }
     async getChildren(parentId) {
         try {
             const snapshot = await this.db
@@ -161,17 +321,16 @@ export class CategoriesRepository extends BaseRepository {
             throw new DatabaseError(`Failed to retrieve children categories: ${error instanceof Error ? error.message : "Unknown error"}`);
         }
     }
-    /**
-     * IDs of every descendant category at any depth (not just direct
-     * children) — `parentIds` stores the full ancestor chain, so a single
-     * array-contains query on that field already returns the whole subtree
-     * with no recursion needed. Used to expand a parent category's product
-     * listing/count to include products filed under any of its children.
+    /*
+     * 🛑 `getDescendantIds` was DELETED (2026-10-10). It was
+     * `getDescendants(id).then(d => d.map(x => x.id))`, and its only caller —
+     * CategoryDetailPageView — already held the documents from its own
+     * `getDescendants` call in the same render. So it re-ran the identical
+     * paginated subtree query and discarded everything but the ids: ~330 wasted
+     * reads per page view at the forest size this plan seeds, and two answers
+     * that could disagree whenever one read failed and the other did not.
+     * Call `getDescendants` and `.map(d => d.id)` at the one site that needs it.
      */
-    async getDescendantIds(categoryId) {
-        const docs = await this.getDescendants(categoryId);
-        return docs.map((d) => d.id);
-    }
     /**
      * Every descendant DOCUMENT at any depth.
      *
@@ -230,12 +389,18 @@ export class CategoriesRepository extends BaseRepository {
     }
     async getBrandCategories(limit = 0) {
         try {
-            const snapshot = await this.db
+            // The limit is pushed into Firestore rather than sliced after the read.
+            // It used to fetch EVERY brand and `.slice()` — so `limit` reduced what
+            // the caller saw but not what was billed. Exact here (no post-filter to
+            // under-fill), unlike `getCategoriesByTier` above.
+            let query = this.db
                 .collection(this.collection)
                 .where("isBrand", "==", true)
                 .where(CATEGORY_FIELDS.IS_ACTIVE, "==", true)
-                .orderBy(CATEGORY_FIELDS.ORDER, "asc")
-                .get();
+                .orderBy(CATEGORY_FIELDS.ORDER, "asc");
+            if (limit > 0)
+                query = query.limit(limit);
+            const snapshot = await query.get();
             const brands = snapshot.docs.map((doc) => this.mapDoc(doc));
             return limit > 0 ? brands.slice(0, limit) : brands;
         }
@@ -678,24 +843,19 @@ export class CategoriesRepository extends BaseRepository {
             .get();
         return snap.docs.map((d) => this.mapDoc(d));
     }
+    /*
+     * 🛑 `incrementViewCount` DELETED 2026-10-10 — zero callers since
+     * 2026-08-31, when it was removed from the category-detail render path (a
+     * Firestore write per render, and a second counter racing `pageViews`).
+     *
+     * Measured: `viewCount` is absent from all 58 category documents. Deleting
+     * the writer nobody calls is what stops the dead field reading as live. See
+     * the products repository for the same removal.
+     */
     /**
      * SB-UNI-B — derive the canonical `sublisting-{slug}` ID from a
      * human-entered category name.
      */
-    async incrementViewCount(categoryId) {
-        try {
-            await this.db
-                .collection(this.collection)
-                .doc(categoryId)
-                .update({ [CATEGORY_FIELDS.VIEW_COUNT]: increment(1) });
-            // Fire-and-forget analytics: a lost view increment changes nothing that
-            // renders, so it must never break the category read path it rides along
-            // with — the count is approximate by design.
-        }
-        catch (_err) {
-            void normalizeError(_err);
-        }
-    }
     generateSublistingId(name) {
         const base = name
             .toLowerCase()
@@ -712,6 +872,7 @@ CategoriesRepository.SIEVE_FIELDS = {
     isActive: { canFilter: true, canSort: false },
     isFeatured: { canFilter: true, canSort: false },
     isBrand: { canFilter: true, canSort: false },
+    searchTxt: { canFilter: true, canSort: false },
     categoryType: { canFilter: true, canSort: false },
     isSearchable: { canFilter: true, canSort: false },
     parentId: { canFilter: true, canSort: false, path: "parentIds" },

package/dist/features/categories/repository/price-index.repository.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Price Index Repository — what things actually SOLD for here, per leaf.
+ *
+ * ## 🛑 Why this is its own collection and not a field on `categories`
+ *
+ * The obvious design is `categories/{leafId}.productDefaults.priceGuidance.sold`,
+ * beside the seed-owned `market` band it is shown next to. That design is a
+ * runaway-trigger hazard and it is not a theoretical one.
+ *
+ * `onCategoryWrite` is a `documentWritten` trigger on `categories`, so a job
+ * writing a price band there re-triggers it once per document. That is exactly
+ * the shape of Root Cause #92, where `onShipmentHeaderWrite` wrote back to the
+ * collection it watched and produced **1,017,548 invocations in 24 hours**
+ * against a 2M/month allowance, blocked `firebase deploy` with a billing
+ * denial, and degraded production.
+ *
+ * It is also worse than that here, because `notifyRevalidate` fires on every
+ * category write — so each nightly price write would drop that category page's
+ * ISR entry, on a project that was paused for exceeding ISR writes by 15.5×.
+ *
+ * A sibling collection removes the self-write entirely. It costs one extra
+ * read on the surface that shows the band, and buys immunity.
+ *
+ * ## Shape
+ *
+ *   priceIndex/{leafId}                 the current band
+ *   priceIndex/{leafId}/daily/{YYYYMMDD}  one point per day, for a series
+ *
+ * 🛑 NO `soldPrices: number[]` on the document. `CategoryDocument.metrics`
+ * already carries two unbounded arrays and a third is the 1 MiB trap. The
+ * samples stay in job memory and only the summary is written.
+ */
+import { BaseRepository } from "../../../providers/db-firebase";
+/** Which acquisition path a sale came through. Counts, not amounts. */
+export interface PriceIndexByPath {
+    standard?: number;
+    auction?: number;
+    offer?: number;
+}
+export interface PriceIndexDocument {
+    /** The LEAF category id. A sale rolls up to exactly one leaf. */
+    id: string;
+    currency: "INR";
+    /**
+     * Scoped by listing type WITHIN the leaf.
+     *
+     * 🛑 Load-bearing. A named-model leaf holds every listing type for that
+     * model — the bey, its stickers, its spare parts, a used one as a classified
+     * — because `listingType` and `categorySlugs` are independent axes. A ₹399
+     * sticker sheet and a ₹1,299 bey under one leaf would blend into a
+     * meaningless band, so the band is per type and the UI shows the one the
+     * seller is listing.
+     */
+    byListingType: Record<string, PriceIndexBand>;
+    /** How many days of completed sales the bands cover. */
+    windowDays: number;
+    computedAt: Date;
+}
+export interface PriceIndexBand {
+    min: number;
+    median: number;
+    max: number;
+    /**
+     * 🛑 The confidence signal, and the UI must render a small one as a sample
+     * size with NO headline number — the same discipline as `truncated`
+     * rendering "50+" rather than a false total. A median of two sales is a coin
+     * flip presented as data.
+     */
+    sampleSize: number;
+    byPath?: PriceIndexByPath;
+    lastSold?: {
+        amount: number;
+        at: Date;
+        via?: "standard" | "auction" | "offer";
+    };
+}
+/** One day's point, for a series. */
+export interface PriceIndexDailyPoint {
+    id: string;
+    /** `YYYYMMDD`, so the document id sorts chronologically on its own. */
+    date: string;
+    byListingType: Record<string, Pick<PriceIndexBand, "median" | "sampleSize">>;
+    computedAt: Date;
+}
+export declare const PRICE_INDEX_COLLECTION = "priceIndex";
+/**
+ * Below this, a band renders as a sample size and no headline figure.
+ *
+ * Exported because the renderer and the job must agree: a threshold the job
+ * applied and the UI did not would hide bands that exist, and the reverse
+ * would publish a median of one sale as a market rate.
+ */
+export declare const PRICE_INDEX_MIN_CONFIDENT_SAMPLES = 3;
+export declare class PriceIndexRepository extends BaseRepository<PriceIndexDocument> {
+    constructor();
+    getForLeaf(leafId: string): Promise<PriceIndexDocument | null>;
+    /**
+     * Write the current band for one leaf.
+     *
+     * `createWithId`/`update` rather than a blind `set`, matching every other
+     * rollup repository here — and `update` merges, so a leaf whose band for one
+     * listing type disappeared this run would keep the stale entry. Hence
+     * `byListingType` is replaced wholesale by passing the full map.
+     */
+    setForLeaf(leafId: string, data: Pick<PriceIndexDocument, "byListingType" | "windowDays">): Promise<void>;
+    /**
+     * Append today's point.
+     *
+     * Keyed on the date, so a re-run on the same day OVERWRITES rather than
+     * double-counting — the same idempotency `pageViewRollup`'s `throughDate`
+     * buys, achieved here by the document id instead of a cursor.
+     */
+    setDailyPoint(leafId: string, date: string, byListingType: PriceIndexDailyPoint["byListingType"]): Promise<void>;
+}
+export declare const priceIndexRepository: PriceIndexRepository;

package/dist/features/categories/repository/price-index.repository.js

@@ -0,0 +1,85 @@
+/**
+ * Price Index Repository — what things actually SOLD for here, per leaf.
+ *
+ * ## 🛑 Why this is its own collection and not a field on `categories`
+ *
+ * The obvious design is `categories/{leafId}.productDefaults.priceGuidance.sold`,
+ * beside the seed-owned `market` band it is shown next to. That design is a
+ * runaway-trigger hazard and it is not a theoretical one.
+ *
+ * `onCategoryWrite` is a `documentWritten` trigger on `categories`, so a job
+ * writing a price band there re-triggers it once per document. That is exactly
+ * the shape of Root Cause #92, where `onShipmentHeaderWrite` wrote back to the
+ * collection it watched and produced **1,017,548 invocations in 24 hours**
+ * against a 2M/month allowance, blocked `firebase deploy` with a billing
+ * denial, and degraded production.
+ *
+ * It is also worse than that here, because `notifyRevalidate` fires on every
+ * category write — so each nightly price write would drop that category page's
+ * ISR entry, on a project that was paused for exceeding ISR writes by 15.5×.
+ *
+ * A sibling collection removes the self-write entirely. It costs one extra
+ * read on the surface that shows the band, and buys immunity.
+ *
+ * ## Shape
+ *
+ *   priceIndex/{leafId}                 the current band
+ *   priceIndex/{leafId}/daily/{YYYYMMDD}  one point per day, for a series
+ *
+ * 🛑 NO `soldPrices: number[]` on the document. `CategoryDocument.metrics`
+ * already carries two unbounded arrays and a third is the 1 MiB trap. The
+ * samples stay in job memory and only the summary is written.
+ */
+import { BaseRepository } from "../../../providers/db-firebase";
+export const PRICE_INDEX_COLLECTION = "priceIndex";
+const DAILY_SUBCOLLECTION = "daily";
+/**
+ * Below this, a band renders as a sample size and no headline figure.
+ *
+ * Exported because the renderer and the job must agree: a threshold the job
+ * applied and the UI did not would hide bands that exist, and the reverse
+ * would publish a median of one sale as a market rate.
+ */
+export const PRICE_INDEX_MIN_CONFIDENT_SAMPLES = 3;
+export class PriceIndexRepository extends BaseRepository {
+    constructor() {
+        super(PRICE_INDEX_COLLECTION);
+    }
+    async getForLeaf(leafId) {
+        return this.findById(leafId);
+    }
+    /**
+     * Write the current band for one leaf.
+     *
+     * `createWithId`/`update` rather than a blind `set`, matching every other
+     * rollup repository here — and `update` merges, so a leaf whose band for one
+     * listing type disappeared this run would keep the stale entry. Hence
+     * `byListingType` is replaced wholesale by passing the full map.
+     */
+    async setForLeaf(leafId, data) {
+        const payload = { currency: "INR", ...data, computedAt: new Date() };
+        const existing = await this.findById(leafId);
+        if (existing) {
+            await this.update(leafId, payload);
+        }
+        else {
+            await this.createWithId(leafId, payload);
+        }
+    }
+    /**
+     * Append today's point.
+     *
+     * Keyed on the date, so a re-run on the same day OVERWRITES rather than
+     * double-counting — the same idempotency `pageViewRollup`'s `throughDate`
+     * buys, achieved here by the document id instead of a cursor.
+     */
+    async setDailyPoint(leafId, date, byListingType) {
+        await this.db
+            .collection(PRICE_INDEX_COLLECTION)
+            .doc(leafId)
+            .collection(DAILY_SUBCOLLECTION)
+            .doc(date)
+            .set({ date, byListingType, computedAt: new Date() }, { merge: true });
+    }
+}
+export const priceIndexRepository = new PriceIndexRepository();