@mohasinac/appkit 4.42.18 → 4.44.0

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

@@ -124,13 +124,37 @@ export interface ProductPrintMeta {
     /** Limited-edition print run size; omitted for open editions. */
     editionSize?: number;
 }
+/**
+ * Licensed manufacture vs. an unbranded 1st copy vs. not established.
+ *
+ * 🛑 THERE IS NO "fake" VALUE, and that is a product decision rather than an
+ * omission. A poor-quality counterfeit — BAS's own buying guide names cadmium
+ * and lead in the metal parts — is not a listing state we offer. It is a
+ * report, and it belongs in the scam registry, which already has 27 scam
+ * types and an evidence model.
+ *
+ * "reproduction" is the midfake tier: largely Chinese, no manufacturer's
+ * marque, generally decent quality, and some WBO formats permit certain repro
+ * parts — so it is sellable WHEN LABELLED. "unverified" exists because the
+ * alternative is far worse: without it, an honest seller who does not know
+ * would have to pick "original", and silence would be indistinguishable from
+ * a genuine claim.
+ *
+ * 🛑 And the buyer-facing framing to design against is NOT "fake". The
+ * counterfeit seller in the crawl makes no authenticity claim at all — zero
+ * occurrences of original/Takara/authentic/replica/fake across 1,277 products
+ * — and sells itself as an "aftermarket brand" with "upgraded components".
+ * "Aftermarket" and "custom" are the words our buyers will be sold, so the
+ * help copy has to answer that, not a word nobody uses.
+ */
+export type ProductAuthenticity = "original" | "reproduction" | "unverified";
 export interface ProductDocument extends BaseDocument {
     title: string;
     description: string;
     slug?: string;
-    /** Tester sandbox flag — set on shared admin-seeded test products; swept by testerSandboxCleanup. */
+    /** Test-data flag — set on shared admin-seeded test products; swept by testDataCleanup. */
     isTestData?: boolean;
-    /** When isTestData, the cutoff after which testerSandboxCleanup deletes this doc (cascades to bids). */
+    /** When isTestData, the cutoff after which testDataCleanup deletes this doc (cascades to bids). */
     testDataExpiresAt?: Date;
     seoTitle?: string;
     seoDescription?: string;
@@ -251,10 +275,46 @@ export interface ProductDocument extends BaseDocument {
     isSold?: boolean;
     /** When true, an EMI order for this product ships as soon as it's confirmed instead of waiting for every installment to be paid. Default false. */
     allowShipBeforeEmiComplete?: boolean;
-    /** P-8 GST — buyer-facing tax rate on this product (%). Unset/0 = exempt. */
+    /**
+     * P-8 GST — buyer-facing tax rate on this product (%).
+     *
+     * 🛑 `undefined` and `0` MEAN DIFFERENT THINGS. Zero is a deliberate
+     * exemption (live plants and animals); undefined is "nobody has said".
+     * So the test is `== null`, NEVER `input.gstRate || default`, which would
+     * silently overwrite every exempt row with the default rate. And there is
+     * deliberately no entry for this in `DEFAULT_PRODUCT_DATA` — a default
+     * there makes `undefined` unreachable in new rows while existing rows
+     * still lack it, which is the `finalSale` trap one field over.
+     *
+     * Written by `deriveTaxonomy` from the category's `taxCodeId`, but the
+     * SCALAR is what every reader and the order-item snapshot use: a tax-code
+     * edit must change future derivations, never retroactively re-rate an
+     * invoice already issued.
+     */
     gstRate?: 0 | 5 | 12 | 18 | 28;
-    /** P-8 GST — Harmonized System of Nomenclature code for GST-compliant invoices. */
+    /** P-8 GST — HSN code for GST-compliant invoices. Resolved alongside `gstRate`. */
     hsnCode?: string;
+    /**
+     * WHO MADE IT — distinct from `condition` (how worn) and from `brand`
+     * (whose marque is on it, which a reproduction has none of). The two axes
+     * are independent: an original can be broken and a reproduction can be
+     * mint.
+     *
+     * 🛑 This is BOTH a field and a feature, deliberately, and it is the only
+     * place in this schema where that duplication is justified. Structurally
+     * it is a classifier and belongs in the `authenticity` FeatureGroup — but
+     * a feature can be OMITTED and nothing notices. A mislabelled
+     * reproduction is a refund; a mislabelled counterfeit is a child handling
+     * leaded metal. The enum makes the question unskippable and writes the
+     * matching feature, so the facet, the badge and search all read one
+     * vocabulary.
+     *
+     * Validated by the competitor crawl: worldhobbyshop ships a nav category
+     * called "MidFake Beyblades" and an FAQ promising that authenticity and
+     * condition are both disclosed per listing. Hence "Midfake" as the LABEL
+     * on the reproduction tier — it is the word buyers search.
+     */
+    authenticity?: ProductAuthenticity;
     /** Print-specific metadata for "art" / "stickers" listings — printed-only physical goods. Optional on every listing type; only populated for art/stickers. */
     printMeta?: ProductPrintMeta;
     promotionEndDate?: Date;
@@ -423,7 +483,7 @@ export declare const PRODUCT_COLLECTION: "products";
 export declare const PRODUCT_INDEXED_FIELDS: readonly ["storeId", "status", "category", "featured", "listingType", "isPromoted", "isOnSale", "isSold", "searchTxt", "createdAt", "barcodeId"];
 export declare const DEFAULT_PRODUCT_DATA: Partial<ProductDocument>;
 export declare const PRODUCT_PUBLIC_FIELDS: readonly ["allowOffers", "minOfferPercent", "id", "title", "description", "category", "subcategory", "brand", "price", "currency", "stockQuantity", "availableQuantity", "images", "status", "storeName", "featured", "tags", "specifications", "features", "shippingInfo", "returnPolicy", "finalSale", "listingType", "auctionEndDate", "startingBid", "currentBid", "bidCount", "reservePrice", "buyNowPrice", "minBidIncrement", "autoExtendable", "auctionExtensionMinutes", "auctionShippingPaidBy", "bidsHaveStarted", "grading", "card", "classified", "digitalCode", "liveItem", "catalogProductId", "preOrderDeliveryDate", "preOrderDepositPercent", "preOrderDepositAmount", "preOrderMaxQuantity", "preOrderCurrentCount", "preOrderProductionStatus", "preOrderCancellable", "condition", "insurance", "insuranceCost", "shippingPaidBy", "isPromoted", "isOnSale", "isSold", "slug", "seoTitle", "seoDescription", "seoKeywords", "viewCount", "customFields", "customSections", "sublistingCategoryId", "groupId", "isGroupParent", "groupParentSlug", "groupChildSlugs", "groupTitle", "createdAt"];
-export declare const PRODUCT_UPDATABLE_FIELDS: readonly ["title", "description", "category", "subcategory", "brand", "price", "stockQuantity", "images", "status", "tags", "specifications", "features", "shippingInfo", "returnPolicy", "finalSale", "pickupAddressId", "condition", "insurance", "shippingPaidBy", "autoExtendable", "auctionExtensionMinutes", "auctionShippingPaidBy", "reservePrice", "buyNowPrice", "minBidIncrement", "bidsHaveStarted", "grading", "card", "classified", "digitalCode", "liveItem", "catalogProductId", "listingType", "preOrderDeliveryDate", "preOrderDepositPercent", "preOrderDepositAmount", "preOrderMaxQuantity", "preOrderProductionStatus", "preOrderCancellable", "isOnSale", "isSold", "allowShipBeforeEmiComplete", "printMeta", "seoTitle", "seoDescription", "seoKeywords", "customFields", "customSections", "sublistingCategoryId", "groupId", "isGroupParent", "groupParentSlug", "groupChildSlugs", "groupTitle", "barcodeId"];
+export declare const PRODUCT_UPDATABLE_FIELDS: readonly ["title", "description", "category", "subcategory", "brand", "price", "stockQuantity", "images", "status", "tags", "specifications", "features", "shippingInfo", "returnPolicy", "finalSale", "pickupAddressId", "condition", "insurance", "shippingPaidBy", "autoExtendable", "auctionExtensionMinutes", "auctionShippingPaidBy", "reservePrice", "buyNowPrice", "minBidIncrement", "bidsHaveStarted", "grading", "card", "classified", "digitalCode", "liveItem", "catalogProductId", "listingType", "preOrderDeliveryDate", "preOrderDepositPercent", "preOrderDepositAmount", "preOrderMaxQuantity", "preOrderProductionStatus", "preOrderCancellable", "isOnSale", "isSold", "allowShipBeforeEmiComplete", "gstRate", "hsnCode", "authenticity", "printMeta", "seoTitle", "seoDescription", "seoKeywords", "customFields", "customSections", "sublistingCategoryId", "groupId", "isGroupParent", "groupParentSlug", "groupChildSlugs", "groupTitle", "barcodeId"];
 export type ProductCreateInput = Omit<ProductDocument, "id" | "createdAt" | "updatedAt" | "availableQuantity" | "bidCount" | "currentBid" | "auctionOriginalEndDate">;
 export type ProductUpdateInput = Partial<Pick<ProductDocument, (typeof PRODUCT_UPDATABLE_FIELDS)[number]>>;
 export type ProductAdminUpdateInput = Partial<Omit<ProductDocument, "id" | "createdAt">>;

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

@@ -173,6 +173,15 @@ export const PRODUCT_UPDATABLE_FIELDS = [
     "isOnSale",
     "isSold",
     "allowShipBeforeEmiComplete",
+    /*
+     * B3 — these three were MISSING, so the fields existed on the document
+     * and were not type-legal to update: ProductUpdateInput is derived from
+     * this list, so an admin or seller form could accept a GST rate and the
+     * repository would refuse to write it.
+     */
+    "gstRate",
+    "hsnCode",
+    "authenticity",
     "printMeta",
     "seoTitle",
     "seoDescription",

package/dist/features/products/schemas/product-features.d.ts

@@ -17,7 +17,22 @@
 export declare const PRODUCT_FEATURES_COLLECTION: "productFeatures";
 export declare const PRODUCT_FEATURE_PREFIX: "feature-";
 export declare const MAX_STORE_CUSTOM_FEATURES = 20;
-export declare const MAX_FEATURES_PER_PRODUCT = 10;
+/**
+ * Hard cap on `product.features[].length`.
+ *
+ * 🛑 RAISED 10 → 24 (B3). Ten was sized for *badges* — a handful of
+ * "Free Shipping"-style trust marks. This collection is now the platform's one
+ * controlled VOCABULARY (`tags` is retired), and a single realistic listing
+ * spends six before anything optional: a reproduction, new-in-box,
+ * japan-import, attack-type, right-spin, limited-release bey. A TCG single
+ * adds language + format + grade on top.
+ *
+ * 24 rather than unbounded because `features[]` is `array-contains`-indexed and
+ * feeds `buildProductSearchTxt`, which truncates at 600 tokens SILENTLY — an
+ * unbounded feature list would quietly evict real title/description tokens
+ * from the search index.
+ */
+export declare const MAX_FEATURES_PER_PRODUCT = 24;
 export type ProductFeatureScope = "platform" | "store";
 export type ProductFeatureCategory = "shipping" | "seller" | "condition" | "platform" | "auction" | "preorder" | "custom";
 export type ProductFeatureProductType = "product" | "auction" | "preorder" | "prize-draw" | "classified" | "digital-code" | "live" | "art" | "stickers" | "all";
@@ -27,6 +42,90 @@ export type ProductFeatureProductType = "product" | "auction" | "preorder" | "pr
  */
 export type ProductFeatureIcon = string;
 export declare function isFeatureIconPath(icon: string): boolean;
+/**
+ * The vocabulary's namespace.
+ *
+ * 🛑 NOT the same axis as `category` above, which groups features by the
+ * SURFACE that shows them (shipping/seller/platform/auction/preorder) and is
+ * what drives badge placement. `group` namespaces what a feature MEANS, and
+ * drives the filter drawer: one facet section per group, rather than one flat
+ * 60-value checkbox list.
+ *
+ * Namespacing is load-bearing because **the same word means different things
+ * per vertical**: "sealed" on a TCG booster box is a factory seal, on a bey it
+ * is an unopened blister; "premium" is a Hot Wheels sub-line, not a quality
+ * claim. A single flat vocabulary would have to pick one meaning.
+ *
+ * Values derived from the measured competitor crawl — see
+ * `docs/research/competitor-crawl-2026-10/vocabulary.md`, which records the
+ * `n` behind each group.
+ */
+export type FeatureGroup = 
+/** How worn / how packaged. Independent of `authenticity`. */
+"condition"
+/** Who made it. Mirrors `ProductDocument.authenticity`; see the note there. */
+ | "authenticity"
+/** Regular / limited / early / random-booster / RLC — a real price multiplier. */
+ | "release"
+/** Beyblade battle type: attack · defense · stamina · balance. */
+ | "type"
+/** right-spin · left-spin · dual-spin. */
+ | "spin"
+/** Merchandising state: clearance, on-sale, best-seller. */
+ | "commercial"
+/** Where it came from: japan-import · imported · domestic. */
+ | "sourcing"
+/** Hot Wheels chase variants, incl. the India-only blister card. */
+ | "chase"
+/** PSA/BGS/CGC grade. Pairs with the `sublisting` + `itemCode` axis. */
+ | "grade"
+/** TCG print language. */
+ | "tcg-lang"
+/** TCG product format — booster box vs single differs ~20× in price. */
+ | "tcg-format"
+/** Figure scale, finish and packaging state. */
+ | "figure"
+/** WBO / limited format legality. */
+ | "tournament"
+/**
+ * The CHARACTER the item is of, or belongs to.
+ *
+ * ONE axis across every vertical here, which is the point: a bey's anime
+ * blader (Dragoon G -> Tyson Granger), a comic figure's hero (a Marvel
+ * Legends Spider-Man -> Spider-Man), an anime figure's character
+ * (Nendoroid Luffy -> Monkey D. Luffy), a card's franchise face. A
+ * collector who wants "everything Spider-Man" wants the figure, the card
+ * and the die-cast together, and no category tree can give them that —
+ * each of those three lives under a different root.
+ *
+ * 93 bladers ship with B5, GENERATED from the corpus. Figure and card
+ * characters join in B6, as the same group with the same mechanics; only
+ * the slug prefix differs (`blader-` vs `character-`), so a URL says which
+ * kind of name it is.
+ *
+ * 🛑 A FEATURE and never a tree node, for the reason §4.4 gives: a
+ * character crosses every generation. Tyson Granger owns nine beys spanning
+ * Spin Gear, Magnacore, Engine Gear and HMS, so a `category-tyson-granger`
+ * node would either duplicate all nine under a second parent or break the
+ * one-chain-per-product invariant that lets a category page match on its
+ * own id alone.
+ *
+ * As a feature it is clickable from any listing surface
+ * (`?features=feature-blader-tyson-granger`), it faceted-filters, it is
+ * indexed into `searchTxt` so "Tyson" finds Dragoon, and it composes with
+ * the generation tree rather than competing with it — browse Beyblade
+ * Original, then narrow to Tyson's.
+ */
+ | "character";
+export declare const FEATURE_GROUP_VALUES: readonly ["condition", "authenticity", "release", "type", "spin", "commercial", "sourcing", "chase", "grade", "tcg-lang", "tcg-format", "figure", "tournament", "character"];
+/**
+ * Human-facing section headings for the filter drawer, one per group.
+ *
+ * A `Record<FeatureGroup, string>` on purpose: a fourteenth group cannot
+ * compile without a label, which is the failure mode Root Cause #61 describes
+ * (ten hand-written enumerations of one union, nine of which drifted).
+ */
+export declare const FEATURE_GROUP_LABEL: Record<FeatureGroup, string>;
 export interface ProductFeatureDocument {
     id: string;
     slug: string;
@@ -37,17 +136,48 @@ export interface ProductFeatureDocument {
     /** CSS variable token key, e.g. "--appkit-color-primary". Optional — defaults to neutral. */
     iconColor?: string;
     category: ProductFeatureCategory;
+    /**
+     * The vocabulary namespace — see `FeatureGroup`. Optional only so the 10
+     * pre-B3 rows keep parsing; the seed sets it on every row and the admin form
+     * requires it. An ungrouped feature renders in no facet section.
+     */
+    group?: FeatureGroup;
     scope: ProductFeatureScope;
     productTypes: ProductFeatureProductType[];
     /** Required when scope === "store". */
     storeId?: string;
     isActive: boolean;
     displayOrder: number;
+    /**
+     * Alternative spellings that should FIND this feature.
+     *
+     * Three sources, all measured — see
+     * `docs/research/competitor-crawl-2026-10/counterfeit-signals.md`:
+     *   · part-code pairs, so "rubber flat" finds `RF` and `RF` finds "rubber flat"
+     *   · JP / romaji names
+     *   · 🛑 the counterfeit seller's systematic MISSPELLINGS (`Pegasis`,
+     *     `Jupitar`, `Fireblase`). A counterfeiter's trademark-evasion spelling
+     *     is exactly what a real buyer mistypes, so indexing them makes our
+     *     search tolerant of real typos at zero query-time cost.
+     *
+     * 🛑 Budgeted, not unbounded: these fold into `searchTxt`, which truncates at
+     * 600 tokens SILENTLY, so an over-long alias list evicts tokens nobody chose
+     * to drop.
+     */
+    aliases?: string[];
+    /**
+     * Edge-n-gram search index for this collection, so the picker can search at
+     * all. 🛑 Must be built from the LABEL and `aliases`, never from the slug:
+     * `feature-nib` tokenises to `feature`/`nib`, so the label "New in Box" is
+     * unfindable, which is the same defect `buildProductSearchTxt` has today for
+     * `features[]` (it indexes the raw ids).
+     */
+    searchTxt?: string[];
     createdAt: Date;
     updatedAt: Date;
 }
 export type ProductFeatureCreateInput = Omit<ProductFeatureDocument, "id" | "slug" | "createdAt" | "updatedAt">;
-export type ProductFeatureUpdateInput = Partial<Pick<ProductFeatureDocument, "label" | "description" | "icon" | "iconColor" | "category" | "productTypes" | "isActive" | "displayOrder">>;
+export type ProductFeatureUpdateInput = Partial<Pick<ProductFeatureDocument, "label" | "description" | "icon" | "iconColor" | "category" | "group" | "aliases" | "productTypes" | "isActive" | "displayOrder">>;
 export declare const PRODUCT_FEATURE_SIEVE_FIELDS: {
     readonly label: {
         readonly canFilter: true;
@@ -69,6 +199,14 @@ export declare const PRODUCT_FEATURE_SIEVE_FIELDS: {
         readonly canFilter: true;
         readonly canSort: false;
     };
+    readonly group: {
+        readonly canFilter: true;
+        readonly canSort: false;
+    };
+    readonly searchTxt: {
+        readonly canFilter: true;
+        readonly canSort: false;
+    };
     readonly isActive: {
         readonly canFilter: true;
         readonly canSort: false;

package/dist/features/products/schemas/product-features.js

@@ -17,16 +17,77 @@
 export const PRODUCT_FEATURES_COLLECTION = "productFeatures";
 export const PRODUCT_FEATURE_PREFIX = "feature-";
 export const MAX_STORE_CUSTOM_FEATURES = 20;
-export const MAX_FEATURES_PER_PRODUCT = 10;
+/**
+ * Hard cap on `product.features[].length`.
+ *
+ * 🛑 RAISED 10 → 24 (B3). Ten was sized for *badges* — a handful of
+ * "Free Shipping"-style trust marks. This collection is now the platform's one
+ * controlled VOCABULARY (`tags` is retired), and a single realistic listing
+ * spends six before anything optional: a reproduction, new-in-box,
+ * japan-import, attack-type, right-spin, limited-release bey. A TCG single
+ * adds language + format + grade on top.
+ *
+ * 24 rather than unbounded because `features[]` is `array-contains`-indexed and
+ * feeds `buildProductSearchTxt`, which truncates at 600 tokens SILENTLY — an
+ * unbounded feature list would quietly evict real title/description tokens
+ * from the search index.
+ */
+export const MAX_FEATURES_PER_PRODUCT = 24;
 export function isFeatureIconPath(icon) {
     return icon.trimStart().startsWith("M ") || icon.trimStart().startsWith("m ");
 }
+export const FEATURE_GROUP_VALUES = [
+    "condition",
+    "authenticity",
+    "release",
+    "type",
+    "spin",
+    "commercial",
+    "sourcing",
+    "chase",
+    "grade",
+    "tcg-lang",
+    "tcg-format",
+    "figure",
+    "tournament",
+    "character",
+];
+/**
+ * Human-facing section headings for the filter drawer, one per group.
+ *
+ * A `Record<FeatureGroup, string>` on purpose: a fourteenth group cannot
+ * compile without a label, which is the failure mode Root Cause #61 describes
+ * (ten hand-written enumerations of one union, nine of which drifted).
+ */
+export const FEATURE_GROUP_LABEL = {
+    condition: "Condition",
+    authenticity: "Authenticity",
+    release: "Release type",
+    type: "Battle type",
+    spin: "Spin direction",
+    commercial: "Offers",
+    sourcing: "Sourcing",
+    chase: "Chase & rarity",
+    grade: "Grading",
+    "tcg-lang": "Card language",
+    "tcg-format": "Card format",
+    figure: "Figure details",
+    tournament: "Tournament legality",
+    character: "Blader & character",
+};
 export const PRODUCT_FEATURE_SIEVE_FIELDS = {
     label: { canFilter: true, canSort: true },
     slug: { canFilter: true, canSort: false },
     scope: { canFilter: true, canSort: false },
     storeId: { canFilter: true, canSort: false },
     category: { canFilter: true, canSort: false },
+    group: { canFilter: true, canSort: false },
+    /*
+     * The picker's search. `array-contains` on an edge-n-gram index, the same
+     * shape every other searchable collection uses — a flat Checkbox grid is
+     * fine for 10 rows and unusable at ~60.
+     */
+    searchTxt: { canFilter: true, canSort: false },
     isActive: { canFilter: true, canSort: false },
     displayOrder: { canFilter: false, canSort: true },
     createdAt: { canFilter: false, canSort: true },

package/dist/features/promotions/repository/coupons.repository.js

@@ -458,7 +458,12 @@ export class CouponsRepository extends BaseRepository {
                 message: "Minimum purchase requirement not met",
             };
         }
-        const discountAmount = calculateDiscount(coupon, eligibleSubtotal);
+        /*
+         * `eligible` is passed through, not just its subtotal — `buy_x_get_y`
+         * needs the individual unit prices to know which units are free, and
+         * without them it silently returned 0 for every BOGO coupon ever created.
+         */
+        const discountAmount = calculateDiscount(coupon, eligibleSubtotal, eligible);
         return {
             valid: true,
             coupon,

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

@@ -163,5 +163,48 @@ export declare function sellerCouponCodePrefix(storeSlug: string): string;
 export declare function buildSellerCouponCode(storeSlug: string, sellerCode: string): string;
 export declare function isCouponValid(coupon: CouponDocument): boolean;
 export declare function canUserUseCoupon(coupon: CouponDocument, userUsageCount: number): boolean;
-export declare function calculateDiscount(coupon: CouponDocument, orderTotal: number): number;
+/** One cart line, as much of it as a BOGO calculation needs. */
+export interface DiscountableLine {
+    price: number;
+    quantity: number;
+}
+/**
+ * "Buy X, get Y free" over the ELIGIBLE lines.
+ *
+ * 🛑 THE BUG THIS CLOSES: a BOGO coupon discounted ₹0.
+ *
+ * `calculateDiscount` had `case "buy_x_get_y": discountAmount = 0`, sharing a
+ * branch with `free_shipping`. That zero is CORRECT for free shipping — the
+ * waiver is honoured downstream as a shipping line, not as a discount — but
+ * `buy_x_get_y` had no second path anywhere: `coupon.bxgy` had **zero read
+ * sites in the repo**. So an admin could create and save a BOGO coupon,
+ * `validateCouponForCart` would answer "Coupon is valid", `CouponCard` would
+ * render a BOGO badge, and the buyer paid full price.
+ *
+ * WHY THIS NEEDS ITS OWN FUNCTION: BOGO cannot be computed from a total. Which
+ * units are free depends on individual unit prices, so the line items are
+ * required input. `calculateDiscount(coupon, total)` structurally could not
+ * express it, which is how the `= 0` came to look like a complete branch.
+ *
+ * THE RULE: units are grouped in blocks of `buyQuantity + getQuantity`, and in
+ * each complete block the CHEAPEST `getQuantity` units are free. Cheapest-free
+ * is the conventional retail reading of "buy 2 get 1 free" and the one a buyer
+ * expects to be charged; awarding the dearest would make the same promotion
+ * worth a different amount depending on basket order.
+ *
+ * 🛑 An INCOMPLETE block earns nothing. "Buy 2 get 1" on 2 units is a block of
+ * 2 against a required 3, so the discount is 0 — not a partial credit.
+ */
+export declare function calculateBxgyDiscount(bxgy: BXGYConfig | undefined, lines: readonly DiscountableLine[]): number;
+export declare function calculateDiscount(coupon: CouponDocument, orderTotal: number, 
+/**
+ * The eligible lines, for the types that need them.
+ *
+ * Optional because one of the two callers — `validateCoupon(code, userId,
+ * orderTotal)` — only ever has a total. That caller gets 0 for a BOGO
+ * coupon, which is honest: the discount is genuinely unknowable without the
+ * basket. `validateCouponForCart` DOES hold the eligible lines (it already
+ * reduces them to `eligibleSubtotal`) and passes them.
+ */
+lines?: readonly DiscountableLine[]): number;
 export declare function getTieredDiscount(tiers: TieredDiscount[] | undefined, orderTotal: number): number;

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

@@ -133,7 +133,75 @@ export function canUserUseCoupon(coupon, userUsageCount) {
         return true;
     return userUsageCount < coupon.usage.perUserLimit;
 }
-export function calculateDiscount(coupon, orderTotal) {
+/**
+ * "Buy X, get Y free" over the ELIGIBLE lines.
+ *
+ * 🛑 THE BUG THIS CLOSES: a BOGO coupon discounted ₹0.
+ *
+ * `calculateDiscount` had `case "buy_x_get_y": discountAmount = 0`, sharing a
+ * branch with `free_shipping`. That zero is CORRECT for free shipping — the
+ * waiver is honoured downstream as a shipping line, not as a discount — but
+ * `buy_x_get_y` had no second path anywhere: `coupon.bxgy` had **zero read
+ * sites in the repo**. So an admin could create and save a BOGO coupon,
+ * `validateCouponForCart` would answer "Coupon is valid", `CouponCard` would
+ * render a BOGO badge, and the buyer paid full price.
+ *
+ * WHY THIS NEEDS ITS OWN FUNCTION: BOGO cannot be computed from a total. Which
+ * units are free depends on individual unit prices, so the line items are
+ * required input. `calculateDiscount(coupon, total)` structurally could not
+ * express it, which is how the `= 0` came to look like a complete branch.
+ *
+ * THE RULE: units are grouped in blocks of `buyQuantity + getQuantity`, and in
+ * each complete block the CHEAPEST `getQuantity` units are free. Cheapest-free
+ * is the conventional retail reading of "buy 2 get 1 free" and the one a buyer
+ * expects to be charged; awarding the dearest would make the same promotion
+ * worth a different amount depending on basket order.
+ *
+ * 🛑 An INCOMPLETE block earns nothing. "Buy 2 get 1" on 2 units is a block of
+ * 2 against a required 3, so the discount is 0 — not a partial credit.
+ */
+export function calculateBxgyDiscount(bxgy, lines) {
+    if (!bxgy)
+        return 0;
+    const buy = Math.floor(bxgy.buyQuantity);
+    const get = Math.floor(bxgy.getQuantity);
+    // A non-positive `get` awards nothing; a non-positive `buy` would make every
+    // unit free, which is a misconfiguration, not a promotion.
+    if (!Number.isFinite(buy) || !Number.isFinite(get) || buy <= 0 || get <= 0)
+        return 0;
+    // Expand to one entry per UNIT — a line of quantity 3 contributes 3 prices,
+    // because the free units are counted in units, not in lines.
+    const unitPrices = [];
+    for (const line of lines) {
+        const qty = Math.floor(line.quantity);
+        if (!Number.isFinite(qty) || qty <= 0)
+            continue;
+        if (!Number.isFinite(line.price) || line.price < 0)
+            continue;
+        for (let i = 0; i < qty; i++)
+            unitPrices.push(line.price);
+    }
+    const blockSize = buy + get;
+    const freeUnits = Math.floor(unitPrices.length / blockSize) * get;
+    if (freeUnits <= 0)
+        return 0;
+    unitPrices.sort((a, b) => a - b);
+    let discount = 0;
+    for (let i = 0; i < freeUnits; i++)
+        discount += unitPrices[i];
+    return discount;
+}
+export function calculateDiscount(coupon, orderTotal, 
+/**
+ * The eligible lines, for the types that need them.
+ *
+ * Optional because one of the two callers — `validateCoupon(code, userId,
+ * orderTotal)` — only ever has a total. That caller gets 0 for a BOGO
+ * coupon, which is honest: the discount is genuinely unknowable without the
+ * basket. `validateCouponForCart` DOES hold the eligible lines (it already
+ * reduces them to `eligibleSubtotal`) and passes them.
+ */
+lines) {
     if (coupon.discount.minPurchase && orderTotal < coupon.discount.minPurchase)
         return 0;
     let discountAmount = 0;
@@ -149,8 +217,14 @@ export function calculateDiscount(coupon, orderTotal) {
         case "fixed":
             discountAmount = Math.min(coupon.discount.value, orderTotal);
             break;
-        case "free_shipping":
         case "buy_x_get_y":
+            // Needs the basket — see calculateBxgyDiscount. Capped at the total so a
+            // misconfigured coupon cannot discount more than is being bought.
+            discountAmount = Math.min(calculateBxgyDiscount(coupon.bxgy, lines ?? []), orderTotal);
+            break;
+        case "free_shipping":
+            // Genuinely 0 HERE. The waiver is applied as a shipping line downstream,
+            // not as a discount — this is the one type for which zero is the answer.
             discountAmount = 0;
             break;
     }

package/dist/features/reviews/repository/reviews.repository.d.ts

@@ -42,6 +42,28 @@ declare class ReviewRepository extends BaseRepository<ReviewDocument> {
     findApprovedByUser(userId: string): Promise<ReviewDocument[]>;
     findPending(): Promise<ReviewDocument[]>;
     findByStatus(status: ReviewStatus): Promise<ReviewDocument[]>;
+    /**
+     * How many approved reviews there are site-wide, and their mean rating.
+     *
+     * 🛑 Replaces `reviewRepository.findAll()` on the homepage render path, which
+     * was an **unbounded full-collection scan** whose entire output was a count
+     * and an average: two numbers, billed one read per document, on every cold
+     * render. It was the single largest Firestore read on the site and it existed
+     * to print `"35+"` and `"4.6★"`.
+     *
+     * A Firestore aggregation is billed at **one read per 1000 index entries
+     * matched**, so this is ~1 read at any catalogue size this project will see,
+     * and it is EXACT rather than a daily-stale rollup — which is why no scheduled
+     * job was added for it (the three sibling presets in `live-stats.ts` already
+     * use `count()` for the same reason).
+     *
+     * Returns `average: null` when there are no approved reviews, so the caller
+     * renders nothing rather than `0.0★` — an empty catalogue is not a bad rating.
+     */
+    getApprovedSiteRatingSummary(): Promise<{
+        count: number;
+        average: number | null;
+    }>;
     findFeatured(limit?: number): Promise<ReviewDocument[]>;
     approve(reviewId: string, moderatorId: string, moderatorNote?: string): Promise<ReviewDocument>;
     reject(reviewId: string, moderatorId: string, rejectionReason: string, moderatorNote?: string): Promise<ReviewDocument>;

package/dist/features/reviews/repository/reviews.repository.js

@@ -130,6 +130,41 @@ class ReviewRepository extends BaseRepository {
     async findByStatus(status) {
         return this.findBy(REVIEW_FIELDS.STATUS, status);
     }
+    /**
+     * How many approved reviews there are site-wide, and their mean rating.
+     *
+     * 🛑 Replaces `reviewRepository.findAll()` on the homepage render path, which
+     * was an **unbounded full-collection scan** whose entire output was a count
+     * and an average: two numbers, billed one read per document, on every cold
+     * render. It was the single largest Firestore read on the site and it existed
+     * to print `"35+"` and `"4.6★"`.
+     *
+     * A Firestore aggregation is billed at **one read per 1000 index entries
+     * matched**, so this is ~1 read at any catalogue size this project will see,
+     * and it is EXACT rather than a daily-stale rollup — which is why no scheduled
+     * job was added for it (the three sibling presets in `live-stats.ts` already
+     * use `count()` for the same reason).
+     *
+     * Returns `average: null` when there are no approved reviews, so the caller
+     * renders nothing rather than `0.0★` — an empty catalogue is not a bad rating.
+     */
+    async getApprovedSiteRatingSummary() {
+        const base = this.getCollection().where(REVIEW_FIELDS.STATUS, "==", "approved");
+        const buckets = [];
+        for (let r = REVIEW_MIN_RATING; r <= REVIEW_MAX_RATING; r++)
+            buckets.push(r);
+        const counts = await Promise.all(buckets.map((rating) => getFirestoreCount(base.where(REVIEW_FIELDS.RATING, "==", rating))));
+        let count = 0;
+        let weighted = 0;
+        buckets.forEach((rating, i) => {
+            const n = counts[i] ?? 0;
+            count += n;
+            weighted += n * rating;
+        });
+        // null, not 0 — an empty catalogue has no rating, and rendering "0.0★" would
+        // state the opposite of the truth.
+        return { count, average: count > 0 ? weighted / count : null };
+    }
     async findFeatured(limit = 18) {
         const snapshot = await this.db
             .collection(this.collection)

package/dist/features/seller/actions/seller-actions.js

@@ -26,6 +26,7 @@ import { couponsRepository } from "../../promotions/repository/coupons.repositor
 import { generateStoreSlug } from "../../stores/schemas/firestore";
 import { siteSettingsRepository } from "../../admin/repository/site-settings.repository";
 import { computePayoutDeduction } from "../../../_internal/shared/fees/calculator";
+import { ordersTaxableValue } from "../../../_internal/shared/checkout/order-math";
 import { getDefaultCurrency } from "../../../core/baseline-resolver";
 import { finalizeStagedMediaUrl, finalizeStagedMediaField, finalizeStagedMediaArray, } from "../../media/finalize";
 import { StoreStatusValues } from "../../stores/schemas/firestore";
@@ -222,7 +223,18 @@ async function computeSellerEarnings(sellerId) {
     }
     const paidOutIds = await payoutRepository.getPaidOutOrderIds(sellerId);
     const eligibleOrders = deliveredOrders.filter((o) => !paidOutIds.has(o.id));
-    const grossAmount = eligibleOrders.reduce((sum, o) => sum + (o.totalPrice ?? 0), 0);
+    /*
+     * The TAXABLE VALUE — see `orderTaxableValue`. This figure is what the
+     * seller sees as their earnings, so it must match what the two payout JOBS
+     * compute to the rupee; a seller shown one number and paid another is worse
+     * than either number being wrong on its own.
+     *
+     * Prices are tax-inclusive, so a seller listing at ₹999 @5% earns from a
+     * ₹951.43 taxable value — the ₹47.57 is GST we remit. A seller who would
+     * rather net ₹999 sets `pricesIncludeGst: false` and their typed price is
+     * grossed up at write time.
+     */
+    const grossAmount = ordersTaxableValue(eligibleOrders);
     const siteSettings = await siteSettingsRepository.getSingleton();
     const deduction = computePayoutDeduction(grossAmount, siteSettings.commissions);
     return {
@@ -319,7 +331,10 @@ export async function bulkSellerOrder(userId, userRole, userDisplayName, userEma
     }
     if (eligible.length === 0)
         throw new ValidationError("No eligible orders found.");
-    const grossAmount = eligible.reduce((sum, o) => sum + (o.totalPrice ?? 0), 0);
+    /* The TAXABLE VALUE — see `orderTaxableValue`. Fourth and last of the four
+     * paths C0 converged; a half-migration means the manual button and the
+     * scheduled job pay differently for the same orders. */
+    const grossAmount = ordersTaxableValue(eligible);
     const bulkSiteSettings = await siteSettingsRepository.getSingleton();
     const bulkDeduction = computePayoutDeduction(grossAmount, bulkSiteSettings.commissions);
     const payoutDoc = await payoutRepository.create({