@mohasinac/appkit 4.42.18 → 4.44.0

package/dist/features/categories/schemas/category-content.d.ts

@@ -0,0 +1,206 @@
+/**
+ * Category-owned content — description templates and product defaults.
+ *
+ * ## Why this lives on the CATEGORY and not on a listing template
+ *
+ * `ListingTemplateDocument` is store-scoped. The ask is that the description
+ * lives with the *category*, and the crawl proves the model: worldhobbyshop
+ * reuses TWO bodies across 1,195 listings, and tcgindia generates five
+ * templated FAQs per product. Nobody writes 1,195 descriptions by hand — our
+ * sellers do, because no category→description mechanism exists anywhere in
+ * this codebase.
+ *
+ * ## Why it costs ZERO extra reads
+ *
+ * Both hot paths already hold the category document: `deriveTaxonomy` does
+ * `cats.doc(leaf).get()`, and `CategoryDetailPageView` does `getCategoryBySlug`
+ * plus seven parallel reads — already at Rule #6's ~3-round-trip ceiling. A
+ * sidecar collection would add an eighth read to the second-most-crawled page
+ * on the site.
+ *
+ * ## Why three fields rather than one blob
+ *
+ * Each has exactly one reader: `contentBody` → the category page;
+ * `descriptionTemplates` → the seller form plus the narrow template endpoint;
+ * `productDefaults` → `deriveTaxonomy`. A single `content` object would make
+ * every one of those read the other two.
+ */
+import type { ProductAuthenticity } from "../../products/schemas/firestore";
+/**
+ * Which condition a template is written for.
+ *
+ * 🛑 A KEYED SET, not one body, because worldhobbyshop demonstrably reuses
+ * **two** per category — a pre-owned body and a new-in-box body — and a single
+ * string field cannot express that. The variants are the conditions that
+ * change what the copy must SAY, not every `CONDITION_OPTIONS` value: a
+ * "pre-owned" and a "used" listing want the same disclosure paragraph.
+ */
+export type CategoryTemplateVariant = "default" | "new_in_box" | "new_in_packet" | "pre_owned" | "replica";
+export interface CategoryDescriptionTemplate {
+    id: string;
+    /** What the picker shows, e.g. "Pre-owned — condition as pictured". */
+    label: string;
+    variant: CategoryTemplateVariant;
+    /** `{{placeholder}}` slots; HTML permitted, rendered via RichTextRenderer. */
+    body: string;
+    /**
+     * Slot names found in `body`, derived at write time as a convenience.
+     *
+     * 🛑 ABSENT means "re-parse", never "this body has no slots". A reader that
+     * treats `undefined` as an empty list will skip interpolation entirely on
+     * every template written before this field existed — and the failure is a
+     * published description containing a literal `{{series}}`, which is the most
+     * visible way this feature can break. Use `extractPlaceholders(body)` when
+     * it is absent.
+     */
+    placeholders?: string[];
+    /**
+     * An admin has published a real listing from this template.
+     *
+     * Exists because of raikages, the crawl's counter-example: 114-char bodies
+     * lifted from the Beyblade Wiki, one of which ships with the literal UI
+     * string "Add to Wishlist Add to Wishlist" welded into the product body. An
+     * unreviewed template is how that happens, so the flag records review rather
+     * than assuming it.
+     */
+    isTested?: boolean;
+    version?: number;
+}
+/** A spec row as the product page renders it. */
+export interface CategorySpecification {
+    name: string;
+    value: string;
+    unit?: string;
+}
+/**
+ * What a category hands down to a product filed under it.
+ *
+ * Three behaviours, and the distinction matters more than the field list:
+ *
+ *   WRITTEN      tax, specifications, inTheBox, features — written server-side
+ *                by `deriveTaxonomy` when the product omits them.
+ *   FILL-BLANK   seo* — fills only an empty field, never overwrites.
+ *   ADVISORY     priceGuidance — NEVER written to `price`. It renders as a hint
+ *                beside the price input and nothing else.
+ */
+export interface CategoryProductDefaults {
+    /**
+     * Points at a `taxCodes` row. `deriveTaxonomy` resolves it and writes
+     * `gstRate`/`hsnCode` onto the product; the order item then snapshots from
+     * the product. That layering is what stops a tax-code edit retroactively
+     * re-rating an invoice already issued.
+     */
+    taxCodeId?: string;
+    specifications?: CategorySpecification[];
+    /**
+     * Feature ids merged onto the product, never replacing what it already has.
+     * (The old `defaultTags` name went with `ProductDocument.tags`.)
+     */
+    defaultFeatures?: string[];
+    defaultCondition?: string;
+    defaultAuthenticity?: ProductAuthenticity;
+    /** "What's in the box?" — becomes `ProductDocument.features[]` prose. */
+    inTheBox?: string[];
+    priceGuidance?: CategoryPriceGuidance;
+    seoTitleTemplate?: string;
+    seoDescriptionTemplate?: string;
+    /** Merged with whatever the product already has. */
+    seoKeywords?: string[];
+    weightG?: number;
+    dimensionsCm?: {
+        l: number;
+        w: number;
+        h: number;
+    };
+    shippingPaidBy?: string;
+    fragile?: boolean;
+    /**
+     * Rendered at READ time, so fixing a wrong answer fixes every listing at
+     * once. The tcgindia model — five per product, three interpolating the
+     * name — and nobody else in the crawl of fifteen does it.
+     */
+    faqTemplates?: {
+        question: string;
+        answer: string;
+    }[];
+}
+/**
+ * Two price views, never blended.
+ *
+ * 🛑 `market` and `sold` are rendered SIDE BY SIDE — "Market ₹799–₹1,499 ·
+ * Sold here ₹850–₹1,200 (7 sales)" — and the gap between them is the most
+ * useful thing we can tell a seller, given 76–93% of competitor listings never
+ * sell at their ask. Averaging the two would launder an inference into a
+ * measurement.
+ */
+export interface CategoryPriceGuidance {
+    currency: "INR";
+    /**
+     * Day-1 baseline from the competitor crawl: a TYPICAL MARKET LISTING PRICE.
+     *
+     * 🛑 NOT evidence of a transaction. A competitor's sold-out row proves the
+     * item is GONE, not that it sold at that price. Seed-owned — the rollup job
+     * must never write here, or a quiet night would erase the baseline.
+     */
+    market?: {
+        /**
+         * The one figure every measured band has. Required for exactly that
+         * reason — a band with no central value is not a band.
+         */
+        median: number;
+        /**
+         * 🛑 OPTIONAL, and that is load-bearing. The crawl recorded quartiles for
+         * parts, launchers, TCG and figures and only a MEDIAN AND A RANGE for Hot
+         * Wheels (n=7,418, ₹99–36,500). Requiring p25/p75 would have forced a
+         * range to be retyped as quartiles, which is a different statistic
+         * presented as the one the field is named after. Absent means "not
+         * measured", and the hint renders as "around ₹850" rather than a span.
+         */
+        p25?: number;
+        p75?: number;
+        /**
+         * 🛑 Also optional, for the same reason: the crawl's Beyblade-top table
+         * carries no per-leaf sample size at all, and the one place two sources
+         * disagreed (HMS: beybladeshopindia n=39 against worldhobbyshop n=2) is
+         * recorded precisely because an n=2 median is a coin flip presented as
+         * data. Absent must render as absent — never as a confident figure, and
+         * never as a number somebody filled in to satisfy the type.
+         */
+        sampleSize?: number;
+        asOf: Date;
+        soldOutShare?: number;
+        /**
+         * Which crawl this came from, and any caveat about it — "worldhobbyshop",
+         * "raikages n=68 (the only component-level pricing anywhere)",
+         * "toycollectorsindia 1:64 POOLED across mainline and premium".
+         *
+         * Carried so the question "where did this number come from" is answerable
+         * from the data rather than from a markdown file nobody has open, and so a
+         * source-priority decision can be applied without re-deriving the bands.
+         */
+        source?: string;
+    };
+    /**
+     * OUR completed sales only, including won auctions and accepted offers.
+     *
+     * Absent until there are some — **never zeroed**. A zero would render as a
+     * real figure meaning "things sell here for ₹0", which is worse than silence.
+     */
+    sold?: {
+        min: number;
+        median: number;
+        max: number;
+        sampleSize: number;
+        windowDays: number;
+        byPath?: {
+            standard?: number;
+            auction?: number;
+            offer?: number;
+        };
+    };
+    lastSold?: {
+        amount: number;
+        at: Date;
+        via?: "standard" | "auction" | "offer";
+    };
+}

package/dist/features/categories/schemas/category-content.js

@@ -0,0 +1,28 @@
+/**
+ * Category-owned content — description templates and product defaults.
+ *
+ * ## Why this lives on the CATEGORY and not on a listing template
+ *
+ * `ListingTemplateDocument` is store-scoped. The ask is that the description
+ * lives with the *category*, and the crawl proves the model: worldhobbyshop
+ * reuses TWO bodies across 1,195 listings, and tcgindia generates five
+ * templated FAQs per product. Nobody writes 1,195 descriptions by hand — our
+ * sellers do, because no category→description mechanism exists anywhere in
+ * this codebase.
+ *
+ * ## Why it costs ZERO extra reads
+ *
+ * Both hot paths already hold the category document: `deriveTaxonomy` does
+ * `cats.doc(leaf).get()`, and `CategoryDetailPageView` does `getCategoryBySlug`
+ * plus seven parallel reads — already at Rule #6's ~3-round-trip ceiling. A
+ * sidecar collection would add an eighth read to the second-most-crawled page
+ * on the site.
+ *
+ * ## Why three fields rather than one blob
+ *
+ * Each has exactly one reader: `contentBody` → the category page;
+ * `descriptionTemplates` → the seller form plus the narrow template endpoint;
+ * `productDefaults` → `deriveTaxonomy`. A single `content` object would make
+ * every one of those read the other two.
+ */
+export {};

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

@@ -6,6 +6,8 @@
  */
 import type { CategoryAncestor, CategoryMetrics, CategoryDisplay } from "../types";
 import type { BaseDocument } from "../../../_internal/shared/types/base-document";
+import type { CategoryDescriptionTemplate, CategoryProductDefaults } from "./category-content";
+export type { CategoryDescriptionTemplate, CategoryProductDefaults, CategoryPriceGuidance, CategorySpecification, CategoryTemplateVariant, } from "./category-content";
 export type { CategoryAncestor, CategoryMetrics };
 /**
  * How a bundle resolves its member products.
@@ -82,9 +84,9 @@ export interface CategoryDocument extends BaseDocument {
     name: string;
     slug: string;
     description?: string;
-    /** Tester sandbox flag — set on shared admin-seeded test categories/brands/bundles; swept by testerSandboxCleanup. */
+    /** Test-data flag — set on shared admin-seeded test categories/brands/bundles; swept by testDataCleanup. */
     isTestData?: boolean;
-    /** When isTestData, the cutoff after which testerSandboxCleanup deletes this doc. */
+    /** When isTestData, the cutoff after which testDataCleanup deletes this doc. */
     testDataExpiresAt?: Date;
     rootId: string;
     parentIds: string[];
@@ -135,6 +137,38 @@ export interface CategoryDocument extends BaseDocument {
         question: string;
         answer: string;
     }[];
+    /**
+     * Alternate names this category is searched by — indexed into `searchTxt`
+     * and rendered nowhere.
+     *
+     * B5. A named-model leaf is the case that needs it: *Lost Longinus* is sold
+     * in the west as *Lost Luinor L2* and its product code is *B-66*, and a
+     * buyer types whichever one they learned first. `name` can only hold one of
+     * the three.
+     *
+     * 🛑 Watch the 600-token ceiling in `buildSearchTxt`, which truncates
+     * SILENTLY. A category's own tokens (name, slug, description, path, every
+     * ancestor name) come first in the array, so an unbounded alias list would
+     * evict the lineage tokens that are the whole reason ancestors are indexed.
+     * The generator caps a model leaf at the Hasbro name plus the product code.
+     */
+    aliases?: string[];
+    /**
+     * 400–900 chars of keyword-rich HTML with sibling/parent cross-links,
+     * rendered via `<RichTextRenderer>`.
+     *
+     * 🛑 DISTINCT from `description`, which is a <=230-char blurb that also
+     * feeds `seo.description` and every card. Conflating them would put a
+     * 900-char body in a card and a 230-char stub on the page.
+     *
+     * 36 of worldhobbyshop's 46 categories carry one and it is their actual
+     * ranking mechanism; no Shopify competitor in the crawl has any.
+     */
+    contentBody?: string;
+    /** Condition-keyed description bodies. A SET, because WHS reuses two per category. */
+    descriptionTemplates?: CategoryDescriptionTemplate[];
+    /** What this category hands down to a product filed under it. */
+    productDefaults?: CategoryProductDefaults;
     /**
      * "special" — admin-curated bundle; writes reverse `partOfBundleIds`
      * pointers on member products and shows the "Bundled" badge on cards.
@@ -194,6 +228,19 @@ export interface CategoryDocument extends BaseDocument {
     isActive: boolean;
     isSearchable: boolean;
     showOnHomepage?: boolean;
+    /**
+     * Prefix-expanded search tokens, derived on every write by
+     * `CategoriesRepository.buildSearchTxtFor` → `buildCategorySearchTxt`.
+     *
+     * 🛑 Distinct from `isSearchable`, which is an admin visibility flag. This is
+     * the index that makes a category findable AT ALL: before it existed,
+     * `CATEGORY_SEARCH_SCAN_LIMIT` was capped at 100 by `SIEVE_DEFAULTS.maxPageSize`
+     * — so raising that number did nothing — and a tier-4 model like
+     * "Lost Longinus" was unfindable in every picker.
+     *
+     * Never fed any PII: no `createdBy` (a raw uid) and no `createdByStoreName`.
+     */
+    searchTxt?: string[];
     createdBy: string;
     /** Whether this category was created by admin or a store owner. */
     createdByType?: "admin" | "store";
@@ -204,12 +251,12 @@ export interface CategoryDocument extends BaseDocument {
     ancestors: CategoryAncestor[];
 }
 export declare const CATEGORIES_COLLECTION: "categories";
-export declare const CATEGORIES_INDEXED_FIELDS: readonly ["slug", "rootId", "tier", "parentIds", "isLeaf", "isFeatured", "featuredPriority", "isBrand", "categoryType", "isActive", "isSearchable", "showOnHomepage", "createdBy", "createdByType", "createdByStoreId", "createdAt"];
+export declare const CATEGORIES_INDEXED_FIELDS: readonly ["slug", "rootId", "tier", "parentIds", "isLeaf", "isFeatured", "featuredPriority", "isBrand", "categoryType", "isActive", "isSearchable", "showOnHomepage", "searchTxt", "createdBy", "createdByType", "createdByStoreId", "createdAt"];
 export declare const MIN_ITEMS_FOR_FEATURED: 8;
 export declare const MAX_FEATURED_CATEGORIES: 4;
 export declare const DEFAULT_CATEGORY_DATA: Partial<CategoryDocument>;
-export declare const CATEGORIES_PUBLIC_FIELDS: readonly ["id", "name", "slug", "description", "rootId", "parentIds", "childrenIds", "tier", "path", "order", "position", "subtreeSize", "isLeaf", "metrics.totalProductCount", "metrics.totalAuctionCount", "metrics.totalItemCount", "isFeatured", "featuredPriority", "isBrand", "seo", "display", "isActive", "ancestors"];
-export declare const CATEGORIES_UPDATABLE_FIELDS: readonly ["name", "slug", "description", "order", "isFeatured", "featuredPriority", "isBrand", "seo", "display", "isActive", "isSearchable"];
+export declare const CATEGORIES_PUBLIC_FIELDS: readonly ["id", "name", "slug", "description", "rootId", "parentIds", "childrenIds", "tier", "path", "order", "position", "subtreeSize", "isLeaf", "metrics.totalProductCount", "metrics.totalAuctionCount", "metrics.totalItemCount", "isFeatured", "featuredPriority", "isBrand", "seo", "display", "isActive", "ancestors", "highlights", "faqs", "contentBody", "descriptionTemplates", "productDefaults", "aliases"];
+export declare const CATEGORIES_UPDATABLE_FIELDS: readonly ["name", "slug", "description", "order", "isFeatured", "featuredPriority", "isBrand", "seo", "display", "isActive", "isSearchable", "highlights", "faqs", "contentBody", "descriptionTemplates", "productDefaults", "aliases"];
 export type CategoryCreateInput = Omit<CategoryDocument, "id" | "createdAt" | "updatedAt" | "metrics" | "isLeaf" | "ancestors"> & {
     parentIds?: string[];
     parentId?: string | null;
@@ -285,6 +332,11 @@ export declare const CATEGORY_FIELDS: {
     readonly VIEW_COUNT: "viewCount";
     readonly IS_ACTIVE: "isActive";
     readonly IS_SEARCHABLE: "isSearchable";
+    readonly SEARCH_TXT: "searchTxt";
+    readonly CONTENT_BODY: "contentBody";
+    readonly DESCRIPTION_TEMPLATES: "descriptionTemplates";
+    readonly PRODUCT_DEFAULTS: "productDefaults";
+    readonly PRODUCT_DEFAULTS_TAX_CODE_ID: "productDefaults.taxCodeId";
     readonly CATEGORY_TYPE: "categoryType";
     readonly CREATED_BY: "createdBy";
     readonly CREATED_AT: "createdAt";
@@ -293,5 +345,22 @@ export declare const CATEGORY_FIELDS: {
 };
 /**
  * Build a category tree from a flat list of CategoryDocument objects.
+ *
+ * 🛑 ONE INDEXING PASS, then recursion — not a `.filter()` per node.
+ * This used to scan the whole array once per category to find its children,
+ * which is O(n²): 2,209 comparisons at today's 47 nodes, ~109,000 at the ~330
+ * this plan seeds, and **2.25 million** at 1,500. It runs inside
+ * `categoriesRepository.buildTree()`, i.e. on a request path. Grouping by
+ * parent id first makes it O(n log n) (the sorts) and the output is
+ * byte-identical: same roots, same child order, same depths.
+ *
+ * 🛑 The `seen` set is not defensive padding. A root is picked by
+ * `tier === 0`, and nothing stops a corrupt row from being tier 0 *and* a
+ * descendant of its own child (`parentIds` is a denormalised chain that four
+ * different write paths maintain). The old code would recurse forever on that,
+ * and a hung SSR render is worse than a failed one — it holds a function open
+ * for its whole timeout and reports nothing. A revisited node is dropped from
+ * the second position it appears in rather than throwing: a malformed edge
+ * should cost one tile, not the category page.
  */
 export declare function buildCategoryTree(categories: CategoryDocument[], rootId?: string): CategoryTreeNode[];

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

@@ -20,6 +20,7 @@ export const CATEGORIES_INDEXED_FIELDS = [
     "isActive",
     "isSearchable",
     "showOnHomepage",
+    "searchTxt",
     "createdBy",
     "createdByType",
     "createdByStoreId",
@@ -76,6 +77,31 @@ export const CATEGORIES_PUBLIC_FIELDS = [
     "display",
     "isActive",
     "ancestors",
+    /*
+     * B3. `highlights` and `faqs` were MISSING from both this list and the
+     * updatable one, which is the more interesting half: `CategoryUpdateInput`
+     * derives from UPDATABLE_FIELDS, so a field absent from it is not even
+     * TYPE-LEGAL to update — and both had shipped with no editor at all.
+     * Precedent-by-omission gets closed, not copied.
+     *
+     * `productDefaults` is public because its advisory half (priceGuidance,
+     * specifications, inTheBox) is rendered to buyers and sellers. Its
+     * `taxCodeId` is a reference to an admin-only row, not a secret.
+     */
+    "highlights",
+    "faqs",
+    "contentBody",
+    "descriptionTemplates",
+    "productDefaults",
+    /*
+     * B5. `aliases` is public because it is already published in a form nobody
+     * can withhold: every alias is tokenised into `searchTxt`, which is what the
+     * search endpoint matches on, so the facts are inferable from search results
+     * whether or not the array is in the payload. Withholding it would hide a
+     * useful "also known as" line from the page while changing nothing about
+     * what is reachable.
+     */
+    "aliases",
 ];
 export const CATEGORIES_UPDATABLE_FIELDS = [
     "name",
@@ -89,6 +115,14 @@ export const CATEGORIES_UPDATABLE_FIELDS = [
     "display",
     "isActive",
     "isSearchable",
+    // B3 — see the note in CATEGORIES_PUBLIC_FIELDS. Without these five,
+    // CategoryUpdateInput cannot express them and no editor can save them.
+    "highlights",
+    "faqs",
+    "contentBody",
+    "descriptionTemplates",
+    "productDefaults",
+    "aliases",
 ];
 export const categoryQueryHelpers = {
     bySlug: (slug) => ["slug", "==", slug],
@@ -179,6 +213,12 @@ export const CATEGORY_FIELDS = {
     VIEW_COUNT: "viewCount",
     IS_ACTIVE: "isActive",
     IS_SEARCHABLE: "isSearchable",
+    SEARCH_TXT: "searchTxt",
+    CONTENT_BODY: "contentBody",
+    DESCRIPTION_TEMPLATES: "descriptionTemplates",
+    PRODUCT_DEFAULTS: "productDefaults",
+    /* Dot-path, so a referrer query is one equality and needs no index. */
+    PRODUCT_DEFAULTS_TAX_CODE_ID: "productDefaults.taxCodeId",
     CATEGORY_TYPE: "categoryType",
     CREATED_BY: "createdBy",
     CREATED_AT: "createdAt",
@@ -187,12 +227,43 @@ export const CATEGORY_FIELDS = {
 };
 /**
  * Build a category tree from a flat list of CategoryDocument objects.
+ *
+ * 🛑 ONE INDEXING PASS, then recursion — not a `.filter()` per node.
+ * This used to scan the whole array once per category to find its children,
+ * which is O(n²): 2,209 comparisons at today's 47 nodes, ~109,000 at the ~330
+ * this plan seeds, and **2.25 million** at 1,500. It runs inside
+ * `categoriesRepository.buildTree()`, i.e. on a request path. Grouping by
+ * parent id first makes it O(n log n) (the sorts) and the output is
+ * byte-identical: same roots, same child order, same depths.
+ *
+ * 🛑 The `seen` set is not defensive padding. A root is picked by
+ * `tier === 0`, and nothing stops a corrupt row from being tier 0 *and* a
+ * descendant of its own child (`parentIds` is a denormalised chain that four
+ * different write paths maintain). The old code would recurse forever on that,
+ * and a hung SSR render is worse than a failed one — it holds a function open
+ * for its whole timeout and reports nothing. A revisited node is dropped from
+ * the second position it appears in rather than throwing: a malformed edge
+ * should cost one tile, not the category page.
  */
 export function buildCategoryTree(categories, rootId) {
+    const byParent = new Map();
+    for (const cat of categories) {
+        const parentId = cat.parentIds[cat.parentIds.length - 1];
+        if (!parentId)
+            continue;
+        const bucket = byParent.get(parentId);
+        if (bucket)
+            bucket.push(cat);
+        else
+            byParent.set(parentId, [cat]);
+    }
+    for (const bucket of byParent.values())
+        bucket.sort((a, b) => a.order - b.order);
+    const seen = new Set();
     function buildTree(category, depth) {
-        const children = categories
-            .filter((cat) => cat.parentIds[cat.parentIds.length - 1] === category.id)
-            .sort((a, b) => a.order - b.order)
+        seen.add(category.id);
+        const children = (byParent.get(category.id) ?? [])
+            .filter((child) => !seen.has(child.id))
             .map((child) => buildTree(child, depth + 1));
         return { category, children, depth };
     }