@mohasinac/appkit 4.45.0 → 4.47.0

package/dist/features/categories/repository/category-counts.js

@@ -0,0 +1,224 @@
+/**
+ * G3b — the incremental leaf→root counter.
+ *
+ * 🛑 MAINTAINED FROM THE REPOSITORY, NOT A FIRESTORE TRIGGER, and this is the
+ * decisive constraint rather than a preference. `FieldValue.increment` is
+ * atomic but **not idempotent**, and a Firestore trigger is delivered
+ * at-least-once — so a redelivered trigger double-counts permanently and
+ * invisibly, which is the worst failure available here (a wrong number is just
+ * a number; nothing errors). From `ProductRepository` a retry is the caller's
+ * and the increments are one batch.
+ *
+ * It walks the STORED chain, which is what makes it duplicate-free and acyclic
+ * by construction rather than by care:
+ *
+ *   - `product.categorySlugs` is already `[leaf, …ancestors, root]`, derived by
+ *     `deriveTaxonomy` on create and update. Each ancestor appears exactly
+ *     once, so incrementing every element once cannot double-count.
+ *   - It comes from `buildCategoryTree`'s DFS over a forest, so it is acyclic
+ *     by construction and bounded at 5 (tiers 0–4).
+ *
+ * 🛑 Do NOT walk parent-by-parent at write time. That is N reads per mutation
+ * and it reintroduces the cycle question the stored chain already answers.
+ */
+import { increment, serverTimestamp } from "../../../contracts/field-ops.js";
+import { normalizeError } from "../../../errors/normalize.js";
+import { CATEGORY_COUNTS_COLLECTION } from "../schemas/category-counts.js";
+const DEFAULT_LISTING_TYPE = "standard";
+/**
+ * Read a product's countable identity.
+ *
+ * Mirrors `countersReconcile.tallyProduct`'s own field selection exactly —
+ * `categorySlugs[0]` first, then the `@deprecated` scalar `category` — so the
+ * incremental and the nightly values can agree. Two different leaf selections
+ * would drift silently and the reconciler would "correct" a count that was
+ * right.
+ */
+export function describeCountable(row) {
+    const chainRaw = Array.isArray(row.categorySlugs) ? row.categorySlugs : [];
+    /*
+     * I3 — the ASSIGNED list is what `own` keys on, and it is read from
+     * `categoryIds` with the old single-leaf selection as the fallback.
+     *
+     * 🛑 The fallback is not legacy tidiness, it is required: `categoryIds` was
+     * added in I1, so every product written before it has only `categorySlugs`,
+     * and the nightly reconciler reads the same two fields in the same order. Two
+     * different selections would drift silently and the reconciler would
+     * "correct" a count that was right.
+     */
+    const ownsRaw = Array.isArray(row.categoryIds) && row.categoryIds.length > 0
+        ? row.categoryIds
+        : [chainRaw[0] || row.category || ""];
+    const ownSeen = new Set();
+    const owns = [];
+    for (const id of ownsRaw) {
+        if (!id || ownSeen.has(id))
+            continue;
+        ownSeen.add(id);
+        owns.push(id);
+    }
+    if (owns.length === 0)
+        return null;
+    /*
+     * Dedupe the chain. The one real duplicate risk the stored closure does NOT
+     * remove is a product filed under two leaves that share an ancestor — the
+     * shared ancestor would otherwise be incremented twice for one listing.
+     *
+     * 🛑 Under the one-per-root rule that cannot happen, and the dedupe stays
+     * anyway: the rule is enforced at ONE write path, while this runs on every
+     * row that reaches Firestore — including a seeded row and an admin
+     * `.passthrough()` write, neither of which passes through it. A belt, and the
+     * cheaper of the two places to be wrong.
+     */
+    const seen = new Set();
+    const chain = [];
+    for (const id of [...owns, ...chainRaw]) {
+        if (!id || seen.has(id))
+            continue;
+        seen.add(id);
+        chain.push(id);
+    }
+    /*
+     * 🛑 Never count the brand twice. If a row's leaf id were also its brand id,
+     * the brand bump below would land on a category already bumped by the chain.
+     * It cannot happen with today's `category-` / `brand-` prefixes, which is
+     * exactly why it is worth guarding rather than trusting: the prefixes are a
+     * convention and this is an arithmetic invariant.
+     */
+    const brandSlug = row.brandSlug || null;
+    const brand = brandSlug && !seen.has(brandSlug) ? brandSlug : null;
+    return {
+        owns,
+        chain,
+        brand,
+        listingType: row.listingType || DEFAULT_LISTING_TYPE,
+        isLot: row.isLot === true,
+    };
+}
+/**
+ * Whether a mutation can possibly have changed the counters.
+ *
+ * 🛑 THE BUG THIS EXISTS TO PREVENT, and the plan called it in advance: a guard
+ * that asks only "did the taxonomy change?" MISSES EVERY STATUS TRANSITION.
+ * `draft → published` changes no `categorySlugs` at all, so the count would
+ * never move — silently, on a page that looks correct. Same for
+ * `published → archived`, a sell-out, and a soft delete.
+ *
+ * So the comparison is over (chain, leaf, listingType, isLot, countsNow), and
+ * the availability verdict is a first-class input rather than an afterthought.
+ */
+export function countsChanged(before, after) {
+    const b = before.countsNow ? before.delta : null;
+    const a = after.countsNow ? after.delta : null;
+    if (!b && !a)
+        return false;
+    if (!b || !a)
+        return true;
+    return (b.owns.length !== a.owns.length ||
+        b.owns.some((id, i) => id !== a.owns[i]) ||
+        b.brand !== a.brand ||
+        b.listingType !== a.listingType ||
+        b.isLot !== a.isLot ||
+        b.chain.length !== a.chain.length ||
+        b.chain.some((id, i) => id !== a.chain[i]));
+}
+function bump(patch, categoryId, field, by) {
+    let doc = patch.get(categoryId);
+    if (!doc) {
+        doc = new Map();
+        patch.set(categoryId, doc);
+    }
+    doc.set(field, (doc.get(field) ?? 0) + by);
+}
+/**
+ * Build the field-path increments for one product transition.
+ *
+ * `sign` is +1 for an addition and −1 for a removal; an update is expressed as
+ * a removal of the old shape followed by an addition of the new, which is why
+ * a move between leaves nets to −1 on the old chain and +1 on the new with no
+ * node double-counted.
+ */
+export function buildCountPatch(deltas) {
+    const patch = new Map();
+    for (const { delta, sign } of deltas) {
+        if (!delta)
+            continue;
+        const ownField = delta.isLot ? "lots.own" : `own.${delta.listingType}`;
+        const totalField = delta.isLot ? "lots.total" : `total.${delta.listingType}`;
+        /*
+         * Every ASSIGNMENT gets `own`; the whole deduped closure gets `total`.
+         *
+         * 🛑 `own` at each one is the point of I3: a product assigned to both
+         * category-dragoon-g and category-beyblade is genuinely filed in both, and
+         * each page's "N here" must say so. `total` is still one bump per closure
+         * entry, so a shared ancestor moves by 1 for the listing rather than by the
+         * number of assignments that reach it.
+         */
+        for (const id of delta.owns)
+            bump(patch, id, ownField, sign);
+        for (const id of delta.chain)
+            bump(patch, id, totalField, sign);
+        // A brand is flat: own and total move together, so its descendant count
+        // derives to 0 rather than to a negative number.
+        if (delta.brand) {
+            bump(patch, delta.brand, ownField, sign);
+            bump(patch, delta.brand, totalField, sign);
+        }
+    }
+    /*
+     * Drop net-zero fields. A move WITHIN one leaf (a title edit on a row whose
+     * chain did not change) cancels to nothing, and writing `increment(0)` would
+     * still be a write — one per ancestor, on the hottest path in the app.
+     */
+    for (const [catId, fields] of patch) {
+        for (const [field, by] of fields)
+            if (by === 0)
+                fields.delete(field);
+        if (fields.size === 0)
+            patch.delete(catId);
+    }
+    return patch;
+}
+/**
+ * Apply a patch.
+ *
+ * `set(..., { merge: true })` rather than `update`, because the counts document
+ * may not exist yet: `update` on a missing document throws, and a counter that
+ * refuses to start is worse than one that starts at the first mutation. Merge
+ * also leaves the OTHER listing types' keys untouched, which is what keeps the
+ * map `Partial`.
+ *
+ * 🛑 Failure is swallowed deliberately, and this is the one place in this
+ * codebase where that is right: a count is a display number, and failing a
+ * seller's publish because an ancestor counter could not be bumped would trade
+ * a cosmetic staleness for a lost listing. The nightly reconciler is the
+ * backstop — its `drifted` count is how a missed increment becomes visible.
+ */
+export async function applyCountPatch(db, patch, onError) {
+    if (patch.size === 0)
+        return;
+    try {
+        const col = db.collection(CATEGORY_COUNTS_COLLECTION);
+        await Promise.all(Array.from(patch, ([categoryId, fields]) => {
+            /*
+             * `FieldSentinel` rather than `unknown`: every value here is either
+             * the id string or a Firestore sentinel (`increment` / `serverTimestamp`),
+             * and `Record<string, unknown>` would be a dodge that `audit-unknown-leakage`
+             * correctly refuses — it says nothing about what may be written.
+             */
+            const payload = {
+                id: categoryId,
+                updatedAt: serverTimestamp(),
+            };
+            for (const [field, by] of fields)
+                payload[field] = increment(by);
+            return col.doc(categoryId).set(payload, { merge: true });
+        }));
+    }
+    catch (err) {
+        // Typed before anything downstream touches it (Root Cause #31) — the
+        // caller logs `.message`, and an `unknown` escaping a catch is how a
+        // non-Error throw becomes "[object Object]" in a log line.
+        onError?.(normalizeError(err));
+    }
+}

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

@@ -0,0 +1,155 @@
+/**
+ * G3b — LISTING COUNTS, maintained incrementally leaf→root.
+ *
+ * 🛑 WHY THIS IS A SIBLING COLLECTION AND NOT A FIELD ON `categories`.
+ *
+ * `handleCategoryWrite` calls `notifyRevalidate({ collection: "categories" })`
+ * as its FIRST statement, unconditionally, before any branch — so ANY write to
+ * a category document drops that category page's ISR entry. Under leaf→root,
+ * publishing one listing touches up to five ancestors, so it would drop five
+ * ISR entries per publish. This project was paused with **ISR writes at 3.1M
+ * against a 200K cap (15.5×)**, which settles the question.
+ *
+ * It also removes the Root Cause #92 hazard outright: a trigger that writes
+ * back to the collection it watches produced 1,017,548 invocations in 24 hours
+ * and a billing denial that blocked `firebase deploy`.
+ *
+ * 🛑 AND `metrics.*` ON `categories` STAYS — a constraint the plan did not
+ * record. Two Sieve SORTS order by `metrics.productCount` through Firestore
+ * (`CategoriesIndexListing`'s "Most Products" and
+ * `AdminSublistingCategoriesView`'s "Most listings"), and a sibling collection
+ * cannot serve an `orderBy` on the categories query. So:
+ *
+ *   - `metrics.*`      — written ONLY by the nightly `countersReconcile`, as
+ *                        today. The two sorts keep working at exactly today's
+ *                        accuracy, so there is no regression, and the ISR cost
+ *                        is unchanged from the status quo (one drop per
+ *                        category per night, already happening).
+ *   - `categoryCounts` — the LIVE value, written per product mutation. Fires no
+ *                        revalidation, because nothing triggers on it.
+ *
+ * Readers prefer `categoryCounts` and fall back to `metrics`. That ordering is
+ * what makes the feature additive: a category with no counts document yet
+ * renders exactly as it does today rather than as zero.
+ *
+ * 🛑 HOW FRESH IT ACTUALLY IS, stated precisely rather than as "live".
+ *
+ * The count is of AVAILABLE rows — `isListingRowAvailable`, the same predicate
+ * `countersReconcile` and the listing query use. That predicate is partly
+ * TIME-dependent: `auction` is the one type with an inequality clause
+ * (`auctionEndDate`), so an auction becomes unavailable by the clock with no
+ * product write, and no incremental counter can observe that.
+ *
+ * In practice the window is minutes, not a day: `auctionSettlement` writes
+ * `isSold: true` when it settles, and that write re-evaluates the counter.
+ * Every other type's unavailability is write-driven (stock, `isSold`,
+ * `digitalCode.codesAvailable`, the prize-draw reveal status).
+ *
+ * So: instant for every write-driven change, and bounded by the settlement
+ * cadence for a just-ended auction. That is strictly better than today, where
+ * every change is up to 24h stale. The nightly reconciler stays as the
+ * authority and the audit — its `drifted` counter becomes a real signal that
+ * an increment was missed.
+ */
+import type { ListingType } from "../../products/types";
+export declare const CATEGORY_COUNTS_COLLECTION = "categoryCounts";
+/**
+ * Per-listing-type counters.
+ *
+ * 🛑 `Partial` on purpose: an absent key means "zero observed". Writing nine
+ * explicit zeros on every row is noise, and it would also make an untouched
+ * category indistinguishable from one measured as empty.
+ *
+ * A MAP rather than scalar fields, because own+total across nine listing types
+ * is 18 fields that grow with the union — and the union has grown twice
+ * already. A map needs no schema change for a tenth type.
+ */
+export type ListingTypeCounts = Partial<Record<ListingType, number>>;
+/**
+ * 🛑 THE INVARIANT, and the one way to get this wrong:
+ *
+ *     total  =  own  +  (every descendant's own)
+ *
+ * **`total` ALREADY INCLUDES `own`. Never add them.** `own + total` double-counts
+ * every item filed directly under the row, and on a leaf — where `total === own`
+ * — it doubles the whole number.
+ *
+ * So there are three questions and only two stored fields, because the third is
+ * a subtraction and a stored mirror of it would drift the first time one half
+ * was written without the other (Root Cause #42):
+ *
+ * | Question | Read |
+ * |---|---|
+ * | "how many are filed right here?" | `own` |
+ * | "how many are under my subcategories?" | **`descendantCountsFor()`** — `total − own`, derived |
+ * | "how many will clicking this show me?" | `total` |
+ *
+ * The third is the one a buyer means, which is why `liveTotalFor` returns it
+ * and why the category chips and grid read it. The second exists because the
+ * distinction is genuinely useful to an admin — `CategoryTableColumns` already
+ * renders "own (total)" explicitly — and because deriving it is the only way to
+ * show it without a third counter to keep in step.
+ */
+export interface CategoryCountsDocument {
+    /** === the category's document id. */
+    id: string;
+    /** Listings filed DIRECTLY under this category, by type. */
+    own: ListingTypeCounts;
+    /**
+     * Own + every descendant's, by type. Equals `own` on a leaf.
+     *
+     * 🛑 INCLUDES `own` — see the invariant above. Never `own + total`.
+     */
+    total: ListingTypeCounts;
+    /**
+     * Multi-item LOTS, counted separately from singles.
+     *
+     * 🛑 This separation is what makes a count mean one thing, and it is why the
+     * filing rule in `deriveTaxonomy` only has to refuse a lot at a LEAF rather
+     * than also refusing a single at a non-leaf. A lot and a single are never
+     * summed into one number, so "12 listings here" is unambiguous wherever they
+     * are filed. (Measured: 58 of 70 live products file at a non-leaf, so the
+     * symmetric rule the plan first specified would have rejected most of the
+     * catalogue — see the `isLot` docstring on `ProductDocument`.)
+     *
+     * Scalars rather than a per-type map: a lot is not type-specific in any way
+     * a buyer or a seller filters on, and there is no reader for "lots of
+     * auctions".
+     */
+    lots: {
+        own: number;
+        total: number;
+    };
+    updatedAt: Date;
+}
+/** Sum a counts map — what a category page renders as "N listings". */
+export declare function sumCounts(counts: ListingTypeCounts | undefined): number;
+/**
+ * The display count for a category, preferring the live document.
+ *
+ * 🛑 `undefined` means "no counts document yet", NOT zero — so the caller falls
+ * back to `metrics`. Returning 0 here would render a confident zero on every
+ * category until the first mutation, which is Root Cause #72's lesson (a count
+ * that failed must never be indistinguishable from a count of nothing).
+ */
+export declare function liveTotalFor(doc: Pick<CategoryCountsDocument, "total" | "lots"> | null | undefined): number | undefined;
+/** Filed directly here, lots included. The "N here" half of "N here, M below". */
+export declare function ownTotalFor(doc: Pick<CategoryCountsDocument, "own" | "lots"> | null | undefined): number | undefined;
+/**
+ * How many sit under this row's DESCENDANTS and not directly on it — `total − own`.
+ *
+ * 🛑 DERIVED, never stored, and that is the point: a third stored counter would
+ * be a mirror of a subtraction, and a mirror drifts the moment one half is
+ * written without the other (Root Cause #42). It is also the function that
+ * makes the invariant un-missable — anyone reaching for "own plus children"
+ * finds this instead of writing `own + total`, which double-counts every item
+ * filed directly on the row.
+ *
+ * Clamped at 0. A negative value is real and means the counters drifted (an
+ * increment lost between the leaf write and an ancestor's), and surfacing
+ * "−3 in subcategories" to a visitor is worse than showing none — the nightly
+ * reconciler's `countsWritten` is where that drift is meant to be seen.
+ */
+export declare function descendantTotalFor(doc: Pick<CategoryCountsDocument, "own" | "total" | "lots"> | null | undefined): number | undefined;
+/** The per-type descendant split, same derivation and the same clamp. */
+export declare function descendantCountsFor(doc: Pick<CategoryCountsDocument, "own" | "total"> | null | undefined): ListingTypeCounts | undefined;

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

@@ -0,0 +1,116 @@
+/**
+ * G3b — LISTING COUNTS, maintained incrementally leaf→root.
+ *
+ * 🛑 WHY THIS IS A SIBLING COLLECTION AND NOT A FIELD ON `categories`.
+ *
+ * `handleCategoryWrite` calls `notifyRevalidate({ collection: "categories" })`
+ * as its FIRST statement, unconditionally, before any branch — so ANY write to
+ * a category document drops that category page's ISR entry. Under leaf→root,
+ * publishing one listing touches up to five ancestors, so it would drop five
+ * ISR entries per publish. This project was paused with **ISR writes at 3.1M
+ * against a 200K cap (15.5×)**, which settles the question.
+ *
+ * It also removes the Root Cause #92 hazard outright: a trigger that writes
+ * back to the collection it watches produced 1,017,548 invocations in 24 hours
+ * and a billing denial that blocked `firebase deploy`.
+ *
+ * 🛑 AND `metrics.*` ON `categories` STAYS — a constraint the plan did not
+ * record. Two Sieve SORTS order by `metrics.productCount` through Firestore
+ * (`CategoriesIndexListing`'s "Most Products" and
+ * `AdminSublistingCategoriesView`'s "Most listings"), and a sibling collection
+ * cannot serve an `orderBy` on the categories query. So:
+ *
+ *   - `metrics.*`      — written ONLY by the nightly `countersReconcile`, as
+ *                        today. The two sorts keep working at exactly today's
+ *                        accuracy, so there is no regression, and the ISR cost
+ *                        is unchanged from the status quo (one drop per
+ *                        category per night, already happening).
+ *   - `categoryCounts` — the LIVE value, written per product mutation. Fires no
+ *                        revalidation, because nothing triggers on it.
+ *
+ * Readers prefer `categoryCounts` and fall back to `metrics`. That ordering is
+ * what makes the feature additive: a category with no counts document yet
+ * renders exactly as it does today rather than as zero.
+ *
+ * 🛑 HOW FRESH IT ACTUALLY IS, stated precisely rather than as "live".
+ *
+ * The count is of AVAILABLE rows — `isListingRowAvailable`, the same predicate
+ * `countersReconcile` and the listing query use. That predicate is partly
+ * TIME-dependent: `auction` is the one type with an inequality clause
+ * (`auctionEndDate`), so an auction becomes unavailable by the clock with no
+ * product write, and no incremental counter can observe that.
+ *
+ * In practice the window is minutes, not a day: `auctionSettlement` writes
+ * `isSold: true` when it settles, and that write re-evaluates the counter.
+ * Every other type's unavailability is write-driven (stock, `isSold`,
+ * `digitalCode.codesAvailable`, the prize-draw reveal status).
+ *
+ * So: instant for every write-driven change, and bounded by the settlement
+ * cadence for a just-ended auction. That is strictly better than today, where
+ * every change is up to 24h stale. The nightly reconciler stays as the
+ * authority and the audit — its `drifted` counter becomes a real signal that
+ * an increment was missed.
+ */
+export const CATEGORY_COUNTS_COLLECTION = "categoryCounts";
+/** Sum a counts map — what a category page renders as "N listings". */
+export function sumCounts(counts) {
+    if (!counts)
+        return 0;
+    let n = 0;
+    for (const v of Object.values(counts))
+        n += v ?? 0;
+    return n;
+}
+/**
+ * The display count for a category, preferring the live document.
+ *
+ * 🛑 `undefined` means "no counts document yet", NOT zero — so the caller falls
+ * back to `metrics`. Returning 0 here would render a confident zero on every
+ * category until the first mutation, which is Root Cause #72's lesson (a count
+ * that failed must never be indistinguishable from a count of nothing).
+ */
+export function liveTotalFor(doc) {
+    if (!doc)
+        return undefined;
+    return sumCounts(doc.total) + (doc.lots?.total ?? 0);
+}
+/** Filed directly here, lots included. The "N here" half of "N here, M below". */
+export function ownTotalFor(doc) {
+    if (!doc)
+        return undefined;
+    return sumCounts(doc.own) + (doc.lots?.own ?? 0);
+}
+/**
+ * How many sit under this row's DESCENDANTS and not directly on it — `total − own`.
+ *
+ * 🛑 DERIVED, never stored, and that is the point: a third stored counter would
+ * be a mirror of a subtraction, and a mirror drifts the moment one half is
+ * written without the other (Root Cause #42). It is also the function that
+ * makes the invariant un-missable — anyone reaching for "own plus children"
+ * finds this instead of writing `own + total`, which double-counts every item
+ * filed directly on the row.
+ *
+ * Clamped at 0. A negative value is real and means the counters drifted (an
+ * increment lost between the leaf write and an ancestor's), and surfacing
+ * "−3 in subcategories" to a visitor is worse than showing none — the nightly
+ * reconciler's `countsWritten` is where that drift is meant to be seen.
+ */
+export function descendantTotalFor(doc) {
+    if (!doc)
+        return undefined;
+    const total = liveTotalFor(doc) ?? 0;
+    const own = ownTotalFor(doc) ?? 0;
+    return Math.max(0, total - own);
+}
+/** The per-type descendant split, same derivation and the same clamp. */
+export function descendantCountsFor(doc) {
+    if (!doc)
+        return undefined;
+    const out = {};
+    for (const k of Object.keys(doc.total ?? {})) {
+        const d = (doc.total[k] ?? 0) - (doc.own?.[k] ?? 0);
+        if (d > 0)
+            out[k] = d;
+    }
+    return out;
+}

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

@@ -108,7 +108,6 @@ export interface CategoryDocument extends BaseDocument {
      */
     subtreeSize: number;
     metrics: CategoryDocumentMetrics;
-    viewCount?: number;
     isFeatured: boolean;
     featuredPriority?: number;
     /** @deprecated Use categoryType === "brand". Will be removed once seed + admin form fully migrate. */
@@ -329,7 +328,6 @@ export declare const CATEGORY_FIELDS: {
     readonly FEATURED_PRIORITY: "featuredPriority";
     readonly SEO: "seo";
     readonly DISPLAY: "display";
-    readonly VIEW_COUNT: "viewCount";
     readonly IS_ACTIVE: "isActive";
     readonly IS_SEARCHABLE: "isSearchable";
     readonly SEARCH_TXT: "searchTxt";

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

@@ -210,7 +210,6 @@ export const CATEGORY_FIELDS = {
     FEATURED_PRIORITY: "featuredPriority",
     SEO: "seo",
     DISPLAY: "display",
-    VIEW_COUNT: "viewCount",
     IS_ACTIVE: "isActive",
     IS_SEARCHABLE: "isSearchable",
     SEARCH_TXT: "searchTxt",