@mohasinac/appkit 4.42.18 → 4.44.0

package/dist/features/seller/components/SellerProductsView.js

@@ -1,8 +1,10 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { formatPhysicalLocation } from "../../../utils/physical-location";
 import { normalizeError } from "../../../errors/normalize";
 import { toUserMessage } from "../../../errors/error-display-map";
 import { SIEVE_OP, Stack, sieveFilter } from "@mohasinac/appkit/client";
+import { LOW_STOCK_THRESHOLD } from "../../store-extensions/constants/alert-metrics";
 import { sortBy } from "@mohasinac/appkit/client";
 import { useState, useCallback } from "react";
 import { useEntityDelete } from "../../../react/hooks/useEntityDelete";
@@ -39,7 +41,55 @@ const FILTER_KEYS = [
     "tags",
     "badges",
     "listingType",
+    /*
+     * The stock quick-filter. `FILTER_KEYS` had no stock key at all — stock
+     * appeared only inside a row's subtitle string, so there was no way to ask
+     * "what needs restocking" short of reading every row.
+     *
+     * Registered here (not in `buildExtraParams`) because it IS a drawer facet:
+     * it narrows the list the way `condition` does, so it should inflate the
+     * filter badge and be cleared by the drawer's Clear button. That is the
+     * opposite call from the availability SCOPE, which is a tab and deliberately
+     * stays out of `filterKeys` so a tab selection cannot be silently reset by
+     * Clear.
+     */
+    "stockState",
 ];
+/**
+ * 🛑 Applied IN MEMORY, never as a Firestore clause.
+ *
+ * `availableQuantity <= N` is an inequality, and Firestore appends an
+ * inequality's field to the `orderBy` implicitly — so pairing one with the
+ * default `-createdAt` sort demands a composite index nobody declares, and the
+ * `FAILED_PRECONDITION` gets swallowed into an empty page (Root Cause #59).
+ * Same reasoning as the alert evaluator's `low_stock` branch.
+ *
+ * The honest cost is that it filters the PAGE rather than the collection: a
+ * seller on page 1 of 200 listings sees the low-stock rows from those 50. That
+ * is stated in the facet's own label rather than left for them to infer.
+ */
+const STOCK_STATE_OPTIONS = [
+    { value: "", label: "Any stock level" },
+    { value: "low", label: `Low — ${LOW_STOCK_THRESHOLD} or fewer left` },
+    { value: "out", label: "Out of stock" },
+    { value: "in", label: "In stock" },
+];
+function matchesStockState(stockValue, state) {
+    if (!state)
+        return true;
+    // 🛑 An unknown quantity matches NOTHING rather than everything. A listing
+    // whose stock the API did not report is not evidence of being low, and
+    // including it would put rows a seller cannot act on into a worklist.
+    if (stockValue == null)
+        return false;
+    if (state === "out")
+        return stockValue <= 0;
+    if (state === "low")
+        return stockValue > 0 && stockValue <= LOW_STOCK_THRESHOLD;
+    if (state === "in")
+        return stockValue > LOW_STOCK_THRESHOLD;
+    return true;
+}
 const DEFAULT_SORT = "-createdAt";
 const SORT_OPTIONS = [
     { value: sortBy("createdAt", "DESC"), label: "Newest" },
@@ -86,6 +136,43 @@ const PRODUCT_COLUMNS = [
         className: "w-28 text-right",
         render: (row) => (_jsx(Span, { size: "sm", weight: "medium", className: "text-[var(--appkit-color-text)]", children: row.price })),
     },
+    /*
+     * 🛑 `row.stock` was COMPUTED in `mapRows` and no column rendered it.
+     *
+     * Data fetched and discarded — Root Cause #52's shape — and the reason it
+     * stayed invisible is that the figure also appears inside the row's
+     * `secondary` string, so the information was technically on screen while
+     * being unsortable, unfilterable and impossible to scan down a column.
+     *
+     * Both stock fields have been `canFilter`/`canSort` at the repository layer
+     * the whole time; only the view omitted them.
+     */
+    {
+        key: "stock",
+        header: "Stock",
+        className: "w-24 text-right",
+        render: (row) => {
+            if (row.stockValue == null)
+                return _jsx(Span, { size: "xs", color: "faint", children: "\u2014" });
+            /*
+             * Three states, not two, and the middle one is the point of the column.
+             * `LOW_STOCK_THRESHOLD` is imported rather than re-picked here: the
+             * alert, this column and the dashboard tile must agree on what "low"
+             * means, or a seller gets a warning from one and a clean bill from
+             * another.
+             */
+            /*
+             * Three states, and `Span` has no `warning` variant — so "low" is
+             * carried by WEIGHT plus a suffix rather than by colour alone. That is
+             * better anyway: `audit-a11y` records that white-on-warning fails
+             * contrast in this theme set, and a status conveyed only by colour is
+             * invisible to a colour-blind seller.
+             */
+            const isOut = row.stockValue <= 0;
+            const isLow = !isOut && row.stockValue <= LOW_STOCK_THRESHOLD;
+            return (_jsxs(Span, { size: "sm", weight: isOut || isLow ? "semibold" : "normal", color: isOut ? "error" : isLow ? "primary" : "muted", children: [row.stockValue, isOut ? " · out" : isLow ? " · low" : ""] }));
+        },
+    },
     {
         key: "status",
         header: "Status",
@@ -109,7 +196,13 @@ const PRODUCT_COLUMNS = [
         key: "physicalLocation",
         header: "Location",
         className: "w-28",
-        render: (row) => row.physicalLocation ? (_jsxs(Span, { size: "xs", className: "font-mono text-[var(--appkit-color-text-muted)]", children: [row.physicalLocation.zone, "/", row.physicalLocation.shelf, "/", row.physicalLocation.bin] })) : (_jsx(Span, { size: "xs", color: "faint", children: "\u2014" })),
+        render: (row) => {
+            // One formatter, shared with SellerOrdersView and PrintCenterView. It
+            // also returns undefined for an all-blank location, which the bulk
+            // routes genuinely allow — this used to print a bare "//".
+            const loc = formatPhysicalLocation(row.physicalLocation);
+            return loc ? (_jsx(Span, { size: "xs", className: "font-mono text-[var(--appkit-color-text-muted)]", children: loc })) : (_jsx(Span, { size: "xs", color: "faint", children: "\u2014" }));
+        },
     },
 ];
 export function SellerProductsView({ onDeleteProduct, onCreateClick, }) {
@@ -288,7 +381,9 @@ export function SellerProductsView({ onDeleteProduct, onCreateClick, }) {
                  * reserve and the current bid, both already in `auctionSecondary`, and
                  * a "price" beside them would read as a third, competing figure.
                  */
+                const availableRaw = typeof item.availableQuantity === "number" ? item.availableQuantity : null;
                 const stockRaw = typeof item.stockQuantity === "number" ? item.stockQuantity : null;
+                const stockValue = availableRaw ?? stockRaw;
                 const priceLabel = kind !== "auction" && priceRaw ? `₹${priceRaw.toLocaleString("en-IN")}` : "";
                 const stockLabel = stockRaw === null ? "" : `${stockRaw} in stock`;
                 const secondaryBase = auctionSecondary || toStringValue(item.condition, "");
@@ -303,13 +398,23 @@ export function SellerProductsView({ onDeleteProduct, onCreateClick, }) {
                     listingKind: kind,
                     price: priceRaw ? `₹${priceRaw.toLocaleString("en-IN")}` : "—",
                     stock: stockLabel || "—",
+                    stockValue,
                     physicalLocation: item.physicalLocation &&
                         typeof item.physicalLocation.zone === "string"
                         ? item.physicalLocation
                         : undefined,
                 };
             });
-            return rows.filter((r) => !deletedIds.has(r.id)).map((r) => statusOverrides.has(r.id) ? { ...r, status: statusOverrides.get(r.id) } : r);
+            /*
+             * The stock predicate runs HERE, in the same pass that already drops
+             * optimistically-deleted rows and applies status overrides — so there is
+             * one place a row can be removed from the rendered list rather than two
+             * that could disagree about which rows exist.
+             */
+            const stockState = sideTable.get("stockState") ?? "";
+            return rows
+                .filter((r) => !deletedIds.has(r.id) && matchesStockState(r.stockValue, stockState))
+                .map((r) => statusOverrides.has(r.id) ? { ...r, status: statusOverrides.get(r.id) } : r);
         },
         getTotal: (response, mappedRows) => typeof response.meta?.total === "number" ? response.meta.total : mappedRows.length,
         buildFilters: (state) => {
@@ -321,7 +426,7 @@ export function SellerProductsView({ onDeleteProduct, onCreateClick, }) {
             // same rows. The scope param carries the per-type meaning instead.
             return [statusFilter, kindFilter].filter(Boolean).join(",") || undefined;
         },
-        renderFilterPanel: ({ pendingFilters, setPendingFilters }) => (_jsx(SellerProductsFilterFields, { pendingFilters: pendingFilters, statusOptions: STATUS_OPTIONS, onChange: setPendingFilters })),
+        renderFilterPanel: ({ pendingFilters, setPendingFilters }) => (_jsx(SellerProductsFilterFields, { pendingFilters: pendingFilters, statusOptions: STATUS_OPTIONS, stockStateOptions: STOCK_STATE_OPTIONS, onChange: setPendingFilters })),
         buildExtraParams: () => scope.extraParams,
         renderAboveContent: () => (_jsxs(Stack, { gap: "sm", children: [_jsx(TypeDropdown, { active: listingKind, onChange: handleKindChange }), scope.renderAboveContent()] })),
         buildBulkActions: (selection) => {

package/dist/features/seller/types/index.d.ts

@@ -76,6 +76,23 @@ export interface SellerDashboardStats {
     totalRevenue: number;
     pendingPayouts: number;
     activeListings: number;
+    /**
+     * Published listings at or below `LOW_STOCK_THRESHOLD`, and at zero.
+     *
+     * 🛑 Two numbers rather than one "needs attention" count, because the two
+     * call for different actions: low means reorder, out means the listing
+     * cannot be bought right now. A combined figure hides which.
+     *
+     * Both from `availableQuantity`, not `stockQuantity` — purchasability gates
+     * on the first in three places, and reporting the second would tell a seller
+     * they have stock while buyers cannot buy.
+     *
+     * Optional because a store that does not exist yet returns the zeroed
+     * payload, and because an older client reading a newer field is a nicer
+     * failure than a required field a stale route omits.
+     */
+    lowStockListings?: number;
+    outOfStockListings?: number;
     totalOrders: number;
     pendingOrders: number;
     averageRating?: number;

package/dist/features/seller/utils/product-draft-mapping.d.ts

@@ -49,6 +49,19 @@ import type { SellerProductDraft } from "../components/SellerProductShell";
 export interface StoredProductBlocks {
     finalSale?: boolean;
     returnPolicy?: string;
+    authenticity?: "original" | "reproduction" | "unverified";
+    specifications?: {
+        name: string;
+        value: string;
+        unit?: string;
+    }[];
+    features?: string[];
+    weightG?: number;
+    dimensionsCm?: {
+        l: number;
+        w: number;
+        h: number;
+    };
     classified?: {
         meetupArea?: {
             city?: string;

package/dist/features/seller/utils/product-draft-mapping.js

@@ -120,6 +120,23 @@ export function productToDraft(product) {
          */
         finalSale: product.finalSale,
         returnPolicy: product.returnPolicy,
+        /*
+         * The inherited-but-editable fields (C2c). Same category as `finalSale`:
+         * flat, stored, and absent from the ten hand-written `initialValues`
+         * literals — so the Details section would open EMPTY on a listing that
+         * already carries them, and a seller saving anything else would appear to
+         * have cleared their own specifications.
+         *
+         * (The write is partial, so an untouched save does not actually clear
+         * them. But a form that shows a listing's authenticity as unanswered when
+         * it is answered is telling the seller something untrue, which is exactly
+         * the argument `finalSale` above is making.)
+         */
+        authenticity: product.authenticity,
+        specifications: product.specifications,
+        features: product.features,
+        weightG: product.weightG,
+        dimensionsCm: product.dimensionsCm,
         classifiedCity: classified?.meetupArea?.city,
         classifiedLocality: classified?.meetupArea?.locality,
         classifiedPincode: classified?.meetupArea?.pincode,

package/dist/features/store-extensions/constants/alert-metrics.d.ts

@@ -0,0 +1,86 @@
+/**
+ * ONE alert-metric vocabulary — C3a.
+ *
+ * ## The defect this closes
+ *
+ * `AnalyticsAlertDocument.metric` was `z.string()`, and the two places that
+ * produce one shared **ZERO tokens**:
+ *
+ *   the seller UI offered  daily_revenue · daily_orders · low_stock ·
+ *                          cancelled_orders · pending_payouts · avg_rating ·
+ *                          reviews_count          (7, snake_case)
+ *   the seed wrote         min-stock · orders-window · api-error-rate ·
+ *                          reports-1h             (4, kebab-case)
+ *
+ * Not a near-miss — no value in one list appears in the other. And because
+ * nothing validated the field, every seeded alert rendered its raw string in
+ * the seller's list (`METRIC_OPTIONS.find(...)?.label ?? alert.metric`) while
+ * every alert a seller created was equally unrecognised by anything else.
+ *
+ * It stayed invisible for one reason: **nothing read either value**. There was
+ * no evaluator anywhere — zero references across all 59 job files and
+ * `functions/` — so `lastTriggeredAt` was declared and written nowhere, and
+ * sellers configured alerts that could never fire.
+ *
+ * ## 🛑 The rule that keeps it closed
+ *
+ * **A metric is in this map only if the evaluator computes it.** Offering one
+ * it cannot is how the original dead promise was built — a dropdown is a
+ * commitment, and `low_stock` sitting in a picker with no evaluator behind it
+ * is worse than its absence, because the seller stops watching their stock.
+ *
+ * So `ALERT_METRICS` is a `Record<AlertMetric, AlertMetricDef>`: adding a
+ * union member without a definition is a compile error, and the evaluator's
+ * own switch is exhaustive over the same union, so adding a member without an
+ * implementation is a compile error too. Root Cause #61 — a `Record<Union, T>`
+ * is compile-safe where an array literal is not, and this vocabulary existed
+ * as two array literals.
+ */
+/** Who may set an alert on this metric. */
+export type AlertMetricScope = "seller" | "admin";
+/** How to render the threshold the seller types. */
+export type AlertMetricUnit = "count" | "currency" | "rating";
+export interface AlertMetricDef {
+    label: string;
+    /** What the number means, so the form can suffix it honestly. */
+    unit: AlertMetricUnit;
+    /** Which portals may offer it. Seller metrics are evaluated per store. */
+    scopes: readonly AlertMetricScope[];
+    /**
+     * Plain-English statement of what is counted, shown as helper text.
+     *
+     * Carried because "Daily Orders" does not say whether a cancelled order
+     * counts, and an alert whose definition the seller has to guess at is an
+     * alert they will not trust when it fires.
+     */
+    describes: string;
+}
+export declare const ALERT_METRIC_VALUES: readonly ["low_stock", "out_of_stock", "orders_count", "revenue_total", "cancelled_orders", "pending_payout_total", "avg_rating", "reviews_count", "open_reports", "pending_moderation"];
+export type AlertMetric = (typeof ALERT_METRIC_VALUES)[number];
+/**
+ * 🛑 `Record<AlertMetric, …>`, not a partial and not an array. A union member
+ * with no definition does not compile, and the evaluator switches over the
+ * same union exhaustively — so the picker, the evaluator and the stored value
+ * cannot drift the way the two array literals did.
+ */
+export declare const ALERT_METRICS: Record<AlertMetric, AlertMetricDef>;
+/** Narrow an arbitrary stored string. */
+export declare function isAlertMetric(value: unknown): value is AlertMetric;
+/**
+ * The metrics one portal may offer, derived — never a second hand-written list.
+ *
+ * That is the whole defect this file closes: the seller picker WAS a
+ * hand-written list, and it agreed with nothing.
+ */
+export declare function alertMetricsForScope(scope: AlertMetricScope): {
+    value: AlertMetric;
+    def: AlertMetricDef;
+}[];
+/**
+ * The stock level `low_stock` counts at or below.
+ *
+ * Exported so the alert, the products-list filter and the dashboard tile agree
+ * on what "low" means. Three surfaces each picking their own number is how a
+ * seller gets a warning from one and a clean bill from another.
+ */
+export declare const LOW_STOCK_THRESHOLD = 5;

package/dist/features/store-extensions/constants/alert-metrics.js

@@ -0,0 +1,142 @@
+/**
+ * ONE alert-metric vocabulary — C3a.
+ *
+ * ## The defect this closes
+ *
+ * `AnalyticsAlertDocument.metric` was `z.string()`, and the two places that
+ * produce one shared **ZERO tokens**:
+ *
+ *   the seller UI offered  daily_revenue · daily_orders · low_stock ·
+ *                          cancelled_orders · pending_payouts · avg_rating ·
+ *                          reviews_count          (7, snake_case)
+ *   the seed wrote         min-stock · orders-window · api-error-rate ·
+ *                          reports-1h             (4, kebab-case)
+ *
+ * Not a near-miss — no value in one list appears in the other. And because
+ * nothing validated the field, every seeded alert rendered its raw string in
+ * the seller's list (`METRIC_OPTIONS.find(...)?.label ?? alert.metric`) while
+ * every alert a seller created was equally unrecognised by anything else.
+ *
+ * It stayed invisible for one reason: **nothing read either value**. There was
+ * no evaluator anywhere — zero references across all 59 job files and
+ * `functions/` — so `lastTriggeredAt` was declared and written nowhere, and
+ * sellers configured alerts that could never fire.
+ *
+ * ## 🛑 The rule that keeps it closed
+ *
+ * **A metric is in this map only if the evaluator computes it.** Offering one
+ * it cannot is how the original dead promise was built — a dropdown is a
+ * commitment, and `low_stock` sitting in a picker with no evaluator behind it
+ * is worse than its absence, because the seller stops watching their stock.
+ *
+ * So `ALERT_METRICS` is a `Record<AlertMetric, AlertMetricDef>`: adding a
+ * union member without a definition is a compile error, and the evaluator's
+ * own switch is exhaustive over the same union, so adding a member without an
+ * implementation is a compile error too. Root Cause #61 — a `Record<Union, T>`
+ * is compile-safe where an array literal is not, and this vocabulary existed
+ * as two array literals.
+ */
+export const ALERT_METRIC_VALUES = [
+    "low_stock",
+    "out_of_stock",
+    "orders_count",
+    "revenue_total",
+    "cancelled_orders",
+    "pending_payout_total",
+    "avg_rating",
+    "reviews_count",
+    "open_reports",
+    "pending_moderation",
+];
+/**
+ * 🛑 `Record<AlertMetric, …>`, not a partial and not an array. A union member
+ * with no definition does not compile, and the evaluator switches over the
+ * same union exhaustively — so the picker, the evaluator and the stored value
+ * cannot drift the way the two array literals did.
+ */
+export const ALERT_METRICS = {
+    low_stock: {
+        label: "Products low on stock",
+        unit: "count",
+        scopes: ["seller", "admin"],
+        describes: "How many of your published listings have available stock at or below 5. With 76–93% of competitor catalogues sold out, restock is the main lifecycle event.",
+    },
+    out_of_stock: {
+        label: "Products out of stock",
+        unit: "count",
+        scopes: ["seller", "admin"],
+        describes: "How many published listings have zero available stock and cannot be bought.",
+    },
+    orders_count: {
+        label: "Orders in the window",
+        unit: "count",
+        scopes: ["seller", "admin"],
+        describes: "Orders placed in the window, whatever their status. Set this to `== 0` to be told when nothing is selling.",
+    },
+    revenue_total: {
+        label: "Revenue in the window",
+        unit: "currency",
+        scopes: ["seller", "admin"],
+        describes: "Goods value of delivered, paid, unrefunded orders in the window — the same base a payout is computed from, not the grand total.",
+    },
+    cancelled_orders: {
+        label: "Cancelled orders in the window",
+        unit: "count",
+        scopes: ["seller", "admin"],
+        describes: "Orders cancelled in the window.",
+    },
+    pending_payout_total: {
+        label: "Pending payout amount",
+        unit: "currency",
+        scopes: ["seller", "admin"],
+        describes: "Total of payouts not yet marked paid. Not window-scoped — a backlog is a backlog.",
+    },
+    avg_rating: {
+        label: "Average rating",
+        unit: "rating",
+        scopes: ["seller"],
+        describes: "Mean of approved reviews across the whole store. Set this to `< 4` to hear about a slide early.",
+    },
+    reviews_count: {
+        label: "New reviews in the window",
+        unit: "count",
+        scopes: ["seller"],
+        describes: "Approved reviews published in the window.",
+    },
+    open_reports: {
+        label: "Open reports",
+        unit: "count",
+        scopes: ["admin"],
+        describes: "Reports awaiting moderation. Replaces the seeded `reports-1h`, which nothing read.",
+    },
+    pending_moderation: {
+        label: "Listings pending review",
+        unit: "count",
+        scopes: ["admin"],
+        describes: "Listings in `in_review`, waiting on a moderator.",
+    },
+};
+/** Narrow an arbitrary stored string. */
+export function isAlertMetric(value) {
+    return typeof value === "string" && ALERT_METRIC_VALUES.includes(value);
+}
+/**
+ * The metrics one portal may offer, derived — never a second hand-written list.
+ *
+ * That is the whole defect this file closes: the seller picker WAS a
+ * hand-written list, and it agreed with nothing.
+ */
+export function alertMetricsForScope(scope) {
+    return ALERT_METRIC_VALUES.filter((m) => ALERT_METRICS[m].scopes.includes(scope)).map((m) => ({
+        value: m,
+        def: ALERT_METRICS[m],
+    }));
+}
+/**
+ * The stock level `low_stock` counts at or below.
+ *
+ * Exported so the alert, the products-list filter and the dashboard tile agree
+ * on what "low" means. Three surfaces each picking their own number is how a
+ * seller gets a warning from one and a clean bill from another.
+ */
+export const LOW_STOCK_THRESHOLD = 5;

package/dist/features/store-extensions/schemas/firestore.d.ts

@@ -1,3 +1,4 @@
+import type { AlertMetric } from "../constants/alert-metrics";
 import type { FirestoreDocument } from "@mohasinac/appkit";
 import type { BaseDocument } from "../../../_internal/shared/types/base-document";
 /**
@@ -76,13 +77,30 @@ export interface AnalyticsAlertDocument extends BaseDocument {
     scope: AnalyticsScope;
     ownerId: string;
     label: string;
-    metric: string;
+    /**
+     * 🛑 Was `string`, and that is what let the two producers share ZERO tokens:
+     * the seller picker offered seven snake_case values and the seed wrote four
+     * kebab-case ones, with no overlap and nothing to notice. Narrowed to the
+     * one vocabulary in `constants/alert-metrics.ts`, which the picker derives
+     * from and the evaluator switches over exhaustively.
+     */
+    metric: AlertMetric;
     operator: AlertOperator;
     threshold: number;
     windowHours: number;
     isActive: boolean;
     notifyChannels: Array<"in-app" | "email" | "whatsapp">;
+    /**
+     * When this alert last fired.
+     *
+     * Declared from the start and written NOWHERE until C3b, because there was
+     * no evaluator — which is also why nobody noticed the metric vocabulary was
+     * two disjoint lists. It is now the re-notify guard: an alert that is still
+     * true must not mail every run.
+     */
     lastTriggeredAt?: Date;
+    /** The value observed at `lastTriggeredAt`, so the message can quote it. */
+    lastObservedValue?: number;
 }
 export declare const ANALYTICS_ALERTS_COLLECTION: "analyticsAlerts";
 export declare const ANALYTICS_ALERT_INDEXED_FIELDS: readonly ["scope", "ownerId", "isActive", "metric", "createdAt"];

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

@@ -53,9 +53,9 @@ export interface StoreDocument extends BaseDocument {
     searchTxt?: string[];
     storeSlug: string;
     ownerId: string;
-    /** Tester sandbox flag — set on the shared admin-seeded test store; swept by testerSandboxCleanup. */
+    /** Test-data flag — set on the shared admin-seeded test store; 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;
     storeName: string;
     storeDescription?: string;
@@ -120,6 +120,35 @@ export interface StoreDocument extends BaseDocument {
      * true. Default false — sellers must explicitly opt in.
      */
     emiEnabled?: boolean;
+    /**
+     * How this seller THINKS about the prices they type. An authoring
+     * convenience, and nothing more.
+     *
+     * 🛑 **Every stored `price` in this system is tax-INCLUSIVE** — it is what
+     * the buyer pays, with GST inside it, remitted from it. No money path
+     * branches on this flag, and that is deliberate: a mode read in five places
+     * is five places to drift, which is the defect family C0/C0c spent its
+     * whole length removing.
+     *
+     * `true` (the default) — the seller types the buyer-facing price. ₹999 at 5%
+     * means the buyer pays ₹999 and the seller earns from a ₹951.43 taxable
+     * value.
+     *
+     * `false` — the seller types an EX-TAX price, and `ProductRepository`
+     * grosses it up **once, at write time**: ₹999 at 5% is stored as ₹1,048.95,
+     * so the buyer pays ₹1,048.95 and the seller earns from ₹999.00.
+     *
+     * Default `true`, which matters twice. It is the Indian B2C convention
+     * (and what worldhobbyshop asserts in its own JSON-LD via
+     * `valueAddedTaxIncluded: true`); and it means enabling GST changes no
+     * displayed price, where defaulting to `false` would raise every listing in
+     * the catalogue the moment the switch was flipped.
+     *
+     * 🛑 Flipping this does NOT re-price existing listings. The gross-up happens
+     * at write, so a seller who switches must re-save (or have re-derived) the
+     * products they want converted — see `ProductRepository`.
+     */
+    pricesIncludeGst?: boolean;
     whatsappConfig?: {
         /** Seller's WhatsApp Business phone number, digits-only with country code e.g. "919876543210" */
         phoneNumber?: string;

package/dist/features/tax-codes/repository/tax-codes.repository.d.ts

@@ -0,0 +1,55 @@
+import { BaseRepository, type FirebaseSieveResult, type SieveModel } from "../../../providers/db-firebase";
+import { type TaxCodeCreateInput, type TaxCodeDocument, type TaxCodeUpdateInput } from "../schemas/firestore";
+/**
+ * The `taxCodes` collection.
+ *
+ * Small, read-mostly and read on a hot path — `deriveTaxonomy` resolves a
+ * category's `taxCodeId` on every product create and on any update that names
+ * a taxonomy field. So the two reads below are single-document and
+ * single-field-equality shaped on purpose; neither needs a composite index.
+ */
+export declare class TaxCodesRepository extends BaseRepository<TaxCodeDocument> {
+    constructor();
+    list(model: SieveModel): Promise<FirebaseSieveResult<TaxCodeDocument>>;
+    /**
+     * Every active code, chapter-then-rate ordered, for the picker.
+     *
+     * Unpaginated deliberately — this is ~10 rows and will be a few dozen at
+     * most. If it ever needs paging, the picker needs `searchTxt` first, and
+     * that is a different change.
+     */
+    listActive(): Promise<TaxCodeDocument[]>;
+    /**
+     * Every code including inactive ones, for the admin list.
+     *
+     * 🛑 EXPLICITLY bounded, even though the collection is five rows. Two
+     * reasons: `BaseRepository.findAll()` relies on a cap several layers away
+     * (`base.ts` clamps perPage at 500), and a route that reads "all of a
+     * collection" with no visible bound is the shape that has to be re-audited
+     * every time somebody wonders whether it is safe. 200 is far above any
+     * plausible number of HSN codes and far below anything that costs.
+     */
+    listAllBounded(): Promise<TaxCodeDocument[]>;
+    /**
+     * Resolve a code for derivation.
+     *
+     * 🛑 Returns `null` for an INACTIVE code as well as a missing one, and the
+     * caller must treat both the same way: leave the product's `gstRate` and
+     * `hsnCode` alone rather than writing a zero. Deactivating a code must not
+     * silently re-rate the next listing to 0% — that is indistinguishable from a
+     * deliberate exemption, which is the whole reason `gstRate` distinguishes
+     * `undefined` from `0`.
+     */
+    findResolvable(id: string): Promise<TaxCodeDocument | null>;
+    /**
+     * Create with a DERIVED id, so the same HSN cannot exist twice.
+     *
+     * Two rows for one HSN is the failure worth preventing structurally: an
+     * admin edits one, categories point at the other, and the rate that reaches
+     * an invoice is whichever the data happens to reference. A 409 here is the
+     * right answer — the request is well-formed and the world already has it.
+     */
+    create(input: TaxCodeCreateInput): Promise<TaxCodeDocument>;
+    update(id: string, data: TaxCodeUpdateInput): Promise<TaxCodeDocument>;
+}
+export declare const taxCodesRepository: TaxCodesRepository;