@mohasinac/appkit 4.43.0 → 4.44.0

package/dist/_internal/server/features/seo/sitemap.js

@@ -1,10 +1,12 @@
 import { normalizeError } from "../../../../errors/normalize";
 import { getAdminDb } from "../../../../providers/db-firebase";
 import { ROUTES } from "../../../../next/routing/route-map";
-import { PRODUCT_COLLECTION } from "../../../..";
+import { PRODUCT_COLLECTION } from "../../../../features/products/schemas/firestore";
 import { EVENTS_COLLECTION, EVENT_FIELDS } from "../../../../features/events";
 import { BLOG_POSTS_COLLECTION, BLOG_POST_FIELDS } from "../../../../features/blog";
 import { CATEGORIES_COLLECTION, CATEGORY_FIELDS } from "../../../../features/categories";
+// Imported from the DEFINING module, not the feature barrel (Root Cause #18).
+import { isListingCategory } from "../../../../features/categories/constants/listing-categories";
 import { STORE_COLLECTION, STORE_FIELDS } from "../../../../features/stores";
 import { SCAMMER_COLLECTION } from "../../../../features/scams/schemas/firestore";
 import { serverLogger } from "../../../../monitoring/server-logger";
@@ -16,7 +18,7 @@ const PRODUCT_SLUG = "slug";
 const PRODUCT_UPDATED_AT = "updatedAt";
 /**
  * Tester-sandbox fixtures must never reach the public sitemap. They are created
- * and destroyed on a cycle by `testerSandboxCleanup` and by each tester run's
+ * and destroyed on a cycle by `testDataCleanup` and by each tester run's
  * wipe/seed, so anything Google indexes from them 404s shortly after. 34 of 182 sitemap
  * URLs were disposable test fixtures before this filter existed.
  *
@@ -58,6 +60,47 @@ function sitemapSectionFailed(label, err) {
     serverLogger.error(`sitemap: section "${label}" failed and returned 0 URLs`, { section: label, error: err });
     return [];
 }
+/**
+ * Read every document a query matches, in pages.
+ *
+ * 🛑 WHY: three category fetchers below carried a bare `.limit(500)` and then
+ * filtered in memory, so past 500 active rows the sitemap emitted an
+ * **unpredictable subset** — and `scripts/deploy.mjs` only asserts a section is
+ * non-ZERO, so truncation passes the deploy gate silently. The taxonomy this
+ * plan seeds takes `categories` from 58 to ~330 rows, which is still under 500
+ * today; the point is that crossing it would be invisible.
+ *
+ * `MAX_SITEMAP_DOCS` is a real ceiling, kept well under the 50,000-URL
+ * sitemap-file limit, and crossing it is LOGGED rather than swallowed — the
+ * opposite of a bare `.limit()`, which cannot tell you it truncated.
+ *
+ * An explicit `orderBy("__name__")` is required: `startAfter(docSnapshot)`
+ * needs a defined sort to page against, and a `where`-only query's implicit
+ * document order is not something to rely on across pages.
+ */
+const SITEMAP_PAGE_SIZE = 500;
+const MAX_SITEMAP_DOCS = 10000;
+async function readAllDocs(query, label) {
+    const out = [];
+    let cursor = null;
+    for (;;) {
+        let page = query.orderBy("__name__").limit(SITEMAP_PAGE_SIZE);
+        if (cursor)
+            page = page.startAfter(cursor);
+        const snap = await page.get();
+        if (snap.empty)
+            break;
+        out.push(...snap.docs);
+        if (out.length >= MAX_SITEMAP_DOCS) {
+            serverLogger.error(`sitemap: section "${label}" hit the ${MAX_SITEMAP_DOCS}-document ceiling and is TRUNCATED`, { section: label, scanned: out.length });
+            return out.slice(0, MAX_SITEMAP_DOCS);
+        }
+        if (snap.size < SITEMAP_PAGE_SIZE)
+            break;
+        cursor = snap.docs[snap.docs.length - 1];
+    }
+    return out;
+}
 function staticPages(baseUrl) {
     const page = (path, changeFreq, priority) => ({ url: `${baseUrl}${path}`, lastModified: new Date(), changeFrequency: changeFreq, priority });
     return [
@@ -250,14 +293,12 @@ async function fetchEventUrls(baseUrl) {
 async function fetchCategoryTypeUrls(baseUrl, categoryType, buildUrl, label) {
     try {
         const db = getAdminDb();
-        const snap = await db
+        const docs = await readAllDocs(db
             .collection(CATEGORIES_COLLECTION)
             .where(CATEGORY_FIELDS.CATEGORY_TYPE, "==", categoryType)
             .where(CATEGORY_FIELDS.IS_ACTIVE, "==", true)
-            .select(CATEGORY_FIELDS.SLUG, CATEGORY_FIELDS.UPDATED_AT, TEST_DATA_FIELD)
-            .limit(500)
-            .get();
-        return snap.docs
+            .select(CATEGORY_FIELDS.SLUG, CATEGORY_FIELDS.UPDATED_AT, TEST_DATA_FIELD), label);
+        return docs
             .filter((doc) => !isTestDoc(doc.data()))
             .map((doc) => {
             const data = doc.data();
@@ -289,23 +330,21 @@ async function fetchCategoryTypeUrls(baseUrl, categoryType, buildUrl, label) {
  * stay in the `.select()` list or it comes back undefined and nothing is
  * rejected.
  */
-const NON_LISTING_CATEGORY_TYPES = new Set(["brand", "bundle", "sublisting"]);
 async function fetchCategoryUrls(baseUrl) {
     try {
         const db = getAdminDb();
-        const snap = await db
+        const docs = await readAllDocs(db
             .collection(CATEGORIES_COLLECTION)
             .where(CATEGORY_FIELDS.IS_ACTIVE, "==", true)
-            .select(CATEGORY_FIELDS.SLUG, CATEGORY_FIELDS.UPDATED_AT, CATEGORY_FIELDS.CATEGORY_TYPE, TEST_DATA_FIELD)
-            .limit(500)
-            .get();
-        return snap.docs
+            .select(CATEGORY_FIELDS.SLUG, CATEGORY_FIELDS.UPDATED_AT, CATEGORY_FIELDS.CATEGORY_TYPE, TEST_DATA_FIELD), "category");
+        return docs
             .filter((doc) => {
             const data = doc.data();
             if (isTestDoc(data))
                 return false;
-            const kind = data[CATEGORY_FIELDS.CATEGORY_TYPE];
-            return typeof kind !== "string" || !NON_LISTING_CATEGORY_TYPES.has(kind);
+            return isListingCategory({
+                categoryType: data[CATEGORY_FIELDS.CATEGORY_TYPE],
+            });
         })
             .map((doc) => {
             const data = doc.data();

package/dist/_internal/server/features/stores/adapters.d.ts

@@ -27,7 +27,7 @@ import type { StoreDetail, StoreListItem } from "../../../../features/stores/typ
  */
 export declare const PUBLIC_STORE_FIELDS: readonly ["id", "storeSlug", "ownerId", "storeName", "storeDescription", "storeCategory", "storeLogoURL", "storeBannerURL", "status", "isPublic", "stats", "bio", "location", "website", "socialLinks", "returnPolicy", "shippingPolicy", "isVacationMode", "vacationMessage", "createdAt"];
 /** Everything else, with the reason it stays server-side. */
-export declare const PRIVATE_STORE_FIELDS: readonly ["searchTxt", "updatedAt", "whatsappConfig", "adminNotes", "statusHistory", "statusHistoryTruncated", "isVerified", "suspensionReason", "capabilities", "customCommissionRate", "googleReviews", "shippingConfig", "emiEnabled", "isFeatured", "vacationReturnDate", "isTestData", "testDataExpiresAt"];
+export declare const PRIVATE_STORE_FIELDS: readonly ["searchTxt", "updatedAt", "whatsappConfig", "adminNotes", "statusHistory", "statusHistoryTruncated", "isVerified", "suspensionReason", "capabilities", "customCommissionRate", "googleReviews", "shippingConfig", "emiEnabled", "pricesIncludeGst", "isFeatured", "vacationReturnDate", "isTestData", "testDataExpiresAt"];
 /**
  * Accepted input: a `StoreDocument` (the common case) or a loosely-typed
  * Firestore row. The legacy top-level counters below predate `stats` and are

package/dist/_internal/server/features/stores/adapters.js

@@ -46,6 +46,12 @@ export const PRIVATE_STORE_FIELDS = [
     "googleReviews", // placeId is billed-API config; the RSC reads it server-side
     "shippingConfig", // resolved server-side into per-item shipping at cart time
     "emiEnabled", // read server-side by the checkout/product RSCs, never from a public payload
+    // A seller AUTHORING preference with no public reader by construction: the
+    // stored `price` is always tax-inclusive, so a buyer never needs to know how
+    // the seller typed it. Read only by `ProductRepository` at write time, and
+    // publishing it would invite a client to "correct" a price that is already
+    // correct.
+    "pricesIncludeGst",
     "isFeatured", // ranking input; not part of the public store profile
     "vacationReturnDate", // not rendered by StoreAboutView; add to PUBLIC when a reader exists
     "isTestData", // tester-sandbox tagging; filtered by filterTestDataForViewer

package/dist/_internal/server/functions/scheduled.d.ts

@@ -7,6 +7,8 @@ export declare const couponExpiry: import("./types").ScheduledFunctionDefinition
 export declare const offerExpiry: import("./types").ScheduledFunctionDefinition;
 export declare const productStatsSync: import("./types").ScheduledFunctionDefinition;
 export declare const revenueRollup: import("./types").ScheduledFunctionDefinition;
+export declare const priceIndexRollup: import("./types").ScheduledFunctionDefinition;
+export declare const analyticsAlertEvaluate: import("./types").ScheduledFunctionDefinition;
 export declare const pageViewRollup: import("./types").ScheduledFunctionDefinition;
 export declare const pageViewPrune: import("./types").ScheduledFunctionDefinition;
 export declare const dailyStatusDigest: import("./types").ScheduledFunctionDefinition;
@@ -20,9 +22,9 @@ export declare const autoPayoutEligibility: import("./types").ScheduledFunctionD
 export declare const cleanupRtdbEvents: import("./types").ScheduledFunctionDefinition;
 export declare const mediaTmpCleanup: import("./types").ScheduledFunctionDefinition;
 export declare const draftPrune: import("./types").ScheduledFunctionDefinition;
-export declare const testerSandboxCleanup: import("./types").ScheduledFunctionDefinition;
+export declare const testDataCleanup: import("./types").ScheduledFunctionDefinition;
 export declare const prizeDrawExpiryReveal: import("./types").ScheduledFunctionDefinition;
 export declare const bundleStockSync: import("./types").ScheduledFunctionDefinition;
 export declare const emiInstallmentReminder: import("./types").ScheduledFunctionDefinition;
 export declare const catalogueImageStalenessReminder: import("./types").ScheduledFunctionDefinition;
-export declare const SCHEDULED_FUNCTIONS: readonly [import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition];
+export declare const SCHEDULED_FUNCTIONS: readonly [import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition];

package/dist/_internal/server/functions/scheduled.js

@@ -1,6 +1,6 @@
 // Scheduled function definitions (Cloud Scheduler triggers).
 // Cron syntax accepts both Firebase shorthand and standard cron expressions.
-import { auctionSettlementHandler, autoPayoutEligibilityHandler, bundleStockSyncHandler, cartPruneHandler, cleanupRtdbEventsHandler, countersReconcileHandler, couponExpiryHandler, dailyDataCleanupHandler, draftPruneHandler, emiInstallmentReminderHandler, catalogueImageStalenessReminderHandler, mediaTmpCleanupHandler, notificationPruneHandler, offerExpiryHandler, paymentWindowTimeoutHandler, hardBanReinstatementHandler, paymentReviewAutoApproveHandler, pendingOrderTimeoutHandler, positionsReconcileHandler, prizeDrawExpiryRevealHandler, productStatsSyncHandler, revenueRollupHandler, pageViewRollupHandler, pageViewPruneHandler, dailyStatusDigestHandler, weeklyPayoutEligibilityHandler, testerSandboxCleanupHandler, } from "../jobs/handlers";
+import { auctionSettlementHandler, autoPayoutEligibilityHandler, bundleStockSyncHandler, cartPruneHandler, cleanupRtdbEventsHandler, countersReconcileHandler, couponExpiryHandler, dailyDataCleanupHandler, draftPruneHandler, emiInstallmentReminderHandler, catalogueImageStalenessReminderHandler, mediaTmpCleanupHandler, notificationPruneHandler, offerExpiryHandler, paymentWindowTimeoutHandler, hardBanReinstatementHandler, paymentReviewAutoApproveHandler, pendingOrderTimeoutHandler, positionsReconcileHandler, prizeDrawExpiryRevealHandler, productStatsSyncHandler, revenueRollupHandler, priceIndexRollupHandler, analyticsAlertEvaluateHandler, pageViewRollupHandler, pageViewPruneHandler, dailyStatusDigestHandler, weeklyPayoutEligibilityHandler, testDataCleanupHandler, } from "../jobs/handlers";
 import { defineFunction } from "./define";
 const REGION = "asia-south1";
 const EVERY_5_MIN = "every 5 minutes";
@@ -67,6 +67,49 @@ export const revenueRollup = defineFunction({
     handler: revenueRollupHandler,
     options: { region: REGION, timeoutSeconds: 300, memory: "256MiB", maxInstances: 1 },
 });
+/*
+ * The realised-price index — 04:30 UTC, i.e. **10:00 IST**, the cadence the
+ * page states as "prices as of".
+ *
+ * 🛑 Its OWN function rather than a pass inside `countersReconcile`, which
+ * already runs at its 540s ceiling. A separate job can fail without taking
+ * category metrics down with it, and the two share nothing beyond reading
+ * products.
+ *
+ * It writes `priceIndex/{leafId}` and never `categories` — see the
+ * repository's header for why that is not a preference. A job writing a price
+ * band onto the collection `onCategoryWrite` watches is Root Cause #92's exact
+ * shape (1,017,548 invocations in 24h), and `notifyRevalidate` would
+ * additionally drop each category page's ISR entry nightly on a project that
+ * was paused for exceeding ISR writes by 15.5×.
+ */
+export const priceIndexRollup = defineFunction({
+    name: "priceIndexRollup",
+    description: "Roll up realised sale prices per leaf category into priceIndex/{leafId} (daily 04:30 UTC = 10:00 IST).",
+    trigger: { kind: "schedule", cron: "30 4 * * *", timeZone: "UTC" },
+    handler: priceIndexRollupHandler,
+    options: { region: REGION, timeoutSeconds: 540, memory: "512MiB", maxInstances: 1 },
+});
+/*
+ * Evaluate the alert rules sellers and admins configured — hourly, 20 past.
+ *
+ * 🛑 This feature had a schema, a CRUD UI, two API routes, four seeded
+ * fixtures and **no evaluator anywhere**: zero references across all 59 job
+ * files, with `lastTriggeredAt` declared and written nowhere. So every alert a
+ * seller configured could never fire.
+ *
+ * Hourly rather than daily, because an alert whose point is "tell me when
+ * nothing is selling" is useless a day late — and the job's own 24h
+ * re-notify cooldown is what stops hourly evaluation becoming hourly mail.
+ * 20 past the hour keeps it clear of the dense :00/:15 band.
+ */
+export const analyticsAlertEvaluate = defineFunction({
+    name: "analyticsAlertEvaluate",
+    description: "Evaluate seller and admin analytics alerts against live metrics and notify on a crossing (hourly at :20).",
+    trigger: { kind: "schedule", cron: "20 * * * *", timeZone: "UTC" },
+    handler: analyticsAlertEvaluateHandler,
+    options: { region: REGION, timeoutSeconds: 300, memory: "256MiB", maxInstances: 1 },
+});
 /*
  * The rollup runs BEFORE the prune, and both before the retention boundary
  * moves. `pageViews` had neither until 2026-08-31: it wrote one document per
@@ -168,11 +211,24 @@ export const draftPrune = defineFunction({
     handler: draftPruneHandler,
     options: { region: REGION, timeoutSeconds: 300, memory: "256MiB", maxInstances: 1 },
 });
-export const testerSandboxCleanup = defineFunction({
-    name: "testerSandboxCleanup",
-    description: "Delete expired tester QA sandbox test data (daily 05:00 UTC).",
+/*
+ * 🛑 RENAMED from `testerSandboxCleanup` (2026-10-10, plan §7). The job never
+ * had anything to do with the tester HARNESS — it sweeps any document carrying
+ * `isTestData: true` past its `testDataExpiresAt`, which is a seed-data concern
+ * and outlives the human tester programme being retired in B2.
+ *
+ * 🛑 A Scheduler job rename is DELETE-AND-RECREATE on deploy, not a rename:
+ * `firebase deploy --only functions` creates `testDataCleanup` and leaves
+ * `testerSandboxCleanup` running until it is explicitly deleted. Two jobs
+ * sweeping the same documents is not redundancy — it is the two-owners race
+ * that got `testerSandboxRefresh` removed (see the note below). Delete the old
+ * function in the same deploy.
+ */
+export const testDataCleanup = defineFunction({
+    name: "testDataCleanup",
+    description: "Delete expired isTestData documents past their TTL (daily 05:00 UTC).",
     trigger: { kind: "schedule", cron: "0 5 * * *", timeZone: "UTC" },
-    handler: testerSandboxCleanupHandler,
+    handler: testDataCleanupHandler,
     options: { region: REGION, timeoutSeconds: 300, memory: "256MiB", maxInstances: 1 },
 });
 // testerSandboxRefresh (every 4h: revert fixtures to seed shape, prune extras) was
@@ -220,6 +276,8 @@ export const SCHEDULED_FUNCTIONS = [
     offerExpiry,
     productStatsSync,
     revenueRollup,
+    priceIndexRollup,
+    analyticsAlertEvaluate,
     pageViewRollup,
     pageViewPrune,
     dailyStatusDigest,
@@ -233,7 +291,7 @@ export const SCHEDULED_FUNCTIONS = [
     cleanupRtdbEvents,
     mediaTmpCleanup,
     draftPrune,
-    testerSandboxCleanup,
+    testDataCleanup,
     prizeDrawExpiryReveal,
     bundleStockSync,
     emiInstallmentReminder,

package/dist/_internal/server/jobs/core/adminAnalytics.d.ts

@@ -23,7 +23,6 @@ export interface AdminAnalyticsResult {
         revenue: number;
         orders: number;
         mainImage: string;
-        viewCount: number;
     }>;
 }
 export declare function runAdminAnalytics(_input: void, ctx: JobContext): Promise<AdminAnalyticsResult>;

package/dist/_internal/server/jobs/core/adminAnalytics.js

@@ -82,7 +82,15 @@ export async function runAdminAnalytics(_input, ctx) {
     const topProductsWithImages = topProducts.map((p, i) => ({
         ...p,
         mainImage: topProductDocs[i]?.mainImage ?? "",
-        viewCount: topProductDocs[i]?.viewCount ?? 0,
+        /*
+         * 🛑 `viewCount: … ?? 0` removed 2026-10-10. The `?? 0` was the active
+         * ingredient: `viewCount` is absent from every product document, and
+         * coercing that absence to `0` made it pass `AdminTopProductsTable`'s
+         * `!= null` guard, so the table rendered a permanent "0 views".
+         *
+         * Dropping the key leaves it `undefined`, which is the truth. Real counts
+         * come from the `pageViews` collection once it is rolled up.
+         */
     }));
     return {
         summary: {

package/dist/_internal/server/jobs/core/analyticsAlertEvaluate.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Core: evaluate the alert rules sellers and admins have configured — C3b.
+ *
+ * ## 🛑 The defect this closes: there was no evaluator at all
+ *
+ * `analyticsAlerts` had a schema, a seller CRUD UI, two API routes and four
+ * seeded fixtures — and **zero references across all 59 job files and
+ * `functions/`**. `lastTriggeredAt` was declared and written nowhere. So every
+ * alert a seller configured, and every one the seed created, could never fire.
+ *
+ * CLAUDE.md overstates this feature for exactly that reason: the parts that
+ * exist look complete, and the one that was missing is the one nothing points
+ * at. It also hid the metric-vocabulary split that C3a closed — two disjoint
+ * lists of metric names cannot be noticed while nothing reads the field.
+ *
+ * ## The switch is EXHAUSTIVE over `AlertMetric`
+ *
+ * `satisfies never` on the default branch, so adding a vocabulary member
+ * without an implementation does not compile. That is the mechanism behind the
+ * vocabulary's rule — *a metric is offerable only if the evaluator computes
+ * it* — rather than a convention someone has to remember.
+ *
+ * ## Read cost, and why it is bounded
+ *
+ * Metrics are computed ONCE PER OWNER, not once per alert: a seller with four
+ * alerts on orders pays for one orders query. Each query is bounded by
+ * `QUERY_LIMIT` and every count is reported as saturated when it hits the cap,
+ * because a count that silently stopped at 500 is a threshold comparison
+ * against a number that is not the number.
+ *
+ * 🛑 It does NOT scan per-product for `low_stock`. `availableQuantity <= N` is
+ * an inequality, and pairing one with an arbitrary sort is what demands an
+ * index nobody declares (Root Cause #59) — so the window is bounded and the
+ * predicate runs in memory, the same asymmetry § Availability describes.
+ */
+import type { AlertOperator, AnalyticsAlertDocument } from "../../../../features/store-extensions/schemas/firestore";
+import type { JobContext } from "../runtime/types";
+/** Compare, with the operator the alert carries. */
+export declare function alertFires(value: number, operator: AlertOperator, threshold: number): boolean;
+/**
+ * Whether enough time has passed to notify again.
+ *
+ * An alert that has NEVER fired always notifies — absence of
+ * `lastTriggeredAt` means "not yet", never "recently".
+ */
+export declare function mayRenotify(alert: AnalyticsAlertDocument, now: Date): boolean;
+export declare function runAnalyticsAlertEvaluate(ctx: JobContext): Promise<void>;