@mohasinac/appkit 4.58.0 → 4.60.0

package/dist/_internal/server/features/points/adjust.js

@@ -0,0 +1,121 @@
+import { pointsRepository } from "../../../../features/points/repository/points.repository.js";
+import { pointsExpiryFrom } from "../../../../features/points/schemas/firestore.js";
+import { AdminAuditActionValues } from "../../../../features/audit-log/schemas/firestore.js";
+import { recordAdminAction } from "../audit-log/actions.js";
+import { sendNotification } from "../../../../features/admin/actions/notification-actions.js";
+import { normalizeError } from "../../../../errors/normalize.js";
+import { serverLogger } from "../../../../monitoring/index.js";
+/**
+ * `admin_adjustment`'s first HUMAN writer.
+ *
+ * ## Why this is the last piece of D48 rather than the first
+ *
+ * `admin_adjustment` and `redemption_reversal` were both fully specified —
+ * signed-amount invariant, mandatory `adminReason`, the lot — and had **zero
+ * writers**. The reversal got one when cancellation was built. This is the
+ * other, and it was left until last on purpose: it is the only path by which a
+ * human can create spendable money from nothing, so it should not have existed
+ * before the ledger could expire a batch, consume FIFO, reverse a spend and
+ * reconcile against its own mirror. All four now do.
+ *
+ * ## 🛑 The one writer it must NOT be confused with
+ *
+ * `expireLapsedBatches` also appends `admin_adjustment`, with
+ * `actorUid: "system:points-expiry"`, and its docstring calls that **the one
+ * place a system actor may write an adjustment** — because expiry is a rule
+ * with a date attached rather than a discretionary decision.
+ *
+ * So this function takes a REAL `actorUid` and never that sentinel. Reusing it
+ * would make a human's decision indistinguishable from a scheduled rule in the
+ * one record that exists to tell them apart.
+ *
+ * ## Credits expire; debits and the reason do not
+ *
+ * A positive adjustment gets `pointsExpiryFrom(now)` like any other credit — an
+ * admin-granted goodwill credit is not more permanent than an earned one, and
+ * leaving `expiresAt` absent would mean NEVER EXPIRES, quietly making this the
+ * one way to mint a perpetual balance.
+ *
+ * A negative adjustment passes nothing, matching every other spend: there is
+ * nothing left to expire.
+ *
+ * ## Two records, deliberately
+ *
+ * The ledger entry answers "why does this account have 53 points". The
+ * `adminAuditLog` row answers "what have admins done lately". The second is the
+ * one you need when the account is not yet suspected, which is why a feature
+ * that already records `actorUid` on the entry still writes both.
+ *
+ * ## The buyer is told
+ *
+ * A balance that changes with no explanation is indistinguishable from a bug,
+ * and the buyer is the only party who cannot query the ledger. `description` is
+ * the buyer-facing line and is already mandatory in the schema; the
+ * notification carries it. `adminReason` is NOT sent — it is written for the
+ * next admin and may name an internal case.
+ *
+ * Best-effort: a notification that fails must not undo an applied adjustment,
+ * because the money has already moved and the ledger is the record that
+ * matters.
+ */
+export async function adjustUserPoints(input, actor) {
+    /*
+     * 🛑 No validation here, on purpose. `pointsAdjustFormSchema` is parsed at
+     * the route and `isPointsEntryWellFormed` is re-checked inside
+     * `append()` — which THROWS rather than writing a row it knows is
+     * malformed. A third copy of the rule here is the sixth-hand-rolled-copy
+     * shape (Root Cause #75); what this function owns is the side effects.
+     */
+    const isCredit = input.amount > 0;
+    const { entryId, balance } = await pointsRepository.append({
+        userId: input.userId,
+        kind: "admin_adjustment",
+        amount: input.amount,
+        description: input.description,
+        adminReason: input.adminReason,
+        actorUid: actor.uid,
+        ...(isCredit ? { expiresAt: pointsExpiryFrom(new Date()) } : {}),
+    });
+    serverLogger.info("adjustUserPoints", {
+        actorUid: actor.uid,
+        userId: input.userId,
+        amount: input.amount,
+        balance,
+        entryId,
+    });
+    void recordAdminAction({
+        actorUid: actor.uid,
+        actorName: actor.name,
+        action: AdminAuditActionValues.POINTS_ADJUST,
+        targetType: "user",
+        targetId: input.userId,
+        reason: input.adminReason,
+        metadata: { amount: input.amount, balanceAfter: balance, entryId },
+    });
+    await sendNotification({
+        userId: input.userId,
+        type: "account_action",
+        /*
+         * `account_action` is email-ELIGIBLE, which is correct here: a balance that
+         * changed is money news, and the buyer is the one party who cannot query
+         * the ledger to find out why.
+         *
+         * 🛑 And the type is right rather than convenient — `account_action` means
+         * "something was done TO your account by us", which is exactly this. It was
+         * split away from support-ticket and scam-report activity precisely so a
+         * type-level email decision could distinguish them.
+         */
+        priority: "normal",
+        title: isCredit ? "Points added to your account" : "Points removed from your account",
+        message: input.description,
+        relatedType: "user",
+        relatedId: input.userId,
+    }).catch((err) => {
+        void normalizeError(err);
+        serverLogger.warn("adjustUserPoints: buyer notification failed (adjustment stands)", {
+            userId: input.userId,
+            entryId,
+        });
+    });
+    return { entryId, balance };
+}

package/dist/_internal/server/features/points/award.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Award purchase points on a COMPLETED order — the owner's rule, made real.
+ *
+ * ## Why this had to wait for completion to exist
+ *
+ * *"Points only get issued on successful purchases after buyer put reviews,
+ * then only, if no review no points, that marks the complete order; they are
+ * also assigned if the user [raises] no issues or updates after 7 days of
+ * delivery."* Then: *"auto assigned after 7 days of delivery, when order is
+ * marked complete; if review is given and order marked complete by the buyer
+ * before — immediate disburse."*
+ *
+ * So the trigger is completion, and completion has TWO writers — the buyer's
+ * fast path and the 7-day `order-complete` sweep — converging on one fact,
+ * `completedAt`.
+ *
+ * ## 🛑 `pointsAwardedAt` IS the idempotency key, and it cannot be added later
+ *
+ * `pointsLedger` is append-only. An append does not deduplicate itself, and
+ * `pointsRepository.append` takes no key — so two completion triggers firing
+ * on one order would credit twice, **permanently, with no way to net it off.**
+ * That is why the award was deliberately NOT written when the completion fact
+ * was (the sweep's own comment says so): writing the expensive half of a
+ * feature before its key exists is how an append-only ledger acquires a double
+ * credit nobody can remove.
+ *
+ * The pattern is copied from `reconcileOrderShipping`, which faced exactly this
+ * and solved it without a transaction: it writes `order.shippingReconciliation`
+ * in the same step as the credit, precisely so that field can be the key.
+ *
+ * ## The base is post-discount GOODS
+ *
+ * Not the order total. "5% of what you paid" read literally includes shipping
+ * and the platform fee, so we would issue points against postage handed to a
+ * courier. And it excludes the points tender itself, or points breed points.
+ *
+ * `orderTaxableValue` is reused rather than a fresh sum: it is already the
+ * post-discount, per-line, tax-backed-out goods figure, and it is already the
+ * payout base — so the number the seller is paid on and the number they fund
+ * points on are the same number, which is the property that makes the
+ * seller-funded model explicable to them.
+ *
+ * ## 🛑 The STORE bears it
+ *
+ * Owner: *"so stores bear it"*, framed as *"like a sale discount for getting a
+ * repeat customer."* So it is a DEDUCTION TERM in the payout, never a
+ * clawback — and that works only because of an ordering guarantee worth
+ * stating: `payout-release` is `blockedBy: ["order-complete"]`, so the gate
+ * opens BECAUSE the order completed, and completion is the same event that
+ * issues the points. The award is therefore always strictly before the payout
+ * is computed, by construction rather than by timing luck.
+ */
+import type { OrderDocument } from "../../../../features/orders/schemas/firestore";
+export interface AwardPurchasePointsResult {
+    awarded: number;
+    skipped?: "already-awarded" | "not-complete" | "no-buyer" | "nothing-earnable";
+}
+/**
+ * Award points for one completed order. Safe to call from both triggers.
+ *
+ * Takes the order rather than an id when the caller already holds one — both
+ * completion paths do, and re-reading it would pay a Firestore read to learn
+ * what the caller just wrote.
+ */
+export declare function awardPurchasePoints(order: OrderDocument): Promise<AwardPurchasePointsResult>;

package/dist/_internal/server/features/points/award.js

@@ -0,0 +1,145 @@
+/**
+ * Award purchase points on a COMPLETED order — the owner's rule, made real.
+ *
+ * ## Why this had to wait for completion to exist
+ *
+ * *"Points only get issued on successful purchases after buyer put reviews,
+ * then only, if no review no points, that marks the complete order; they are
+ * also assigned if the user [raises] no issues or updates after 7 days of
+ * delivery."* Then: *"auto assigned after 7 days of delivery, when order is
+ * marked complete; if review is given and order marked complete by the buyer
+ * before — immediate disburse."*
+ *
+ * So the trigger is completion, and completion has TWO writers — the buyer's
+ * fast path and the 7-day `order-complete` sweep — converging on one fact,
+ * `completedAt`.
+ *
+ * ## 🛑 `pointsAwardedAt` IS the idempotency key, and it cannot be added later
+ *
+ * `pointsLedger` is append-only. An append does not deduplicate itself, and
+ * `pointsRepository.append` takes no key — so two completion triggers firing
+ * on one order would credit twice, **permanently, with no way to net it off.**
+ * That is why the award was deliberately NOT written when the completion fact
+ * was (the sweep's own comment says so): writing the expensive half of a
+ * feature before its key exists is how an append-only ledger acquires a double
+ * credit nobody can remove.
+ *
+ * The pattern is copied from `reconcileOrderShipping`, which faced exactly this
+ * and solved it without a transaction: it writes `order.shippingReconciliation`
+ * in the same step as the credit, precisely so that field can be the key.
+ *
+ * ## The base is post-discount GOODS
+ *
+ * Not the order total. "5% of what you paid" read literally includes shipping
+ * and the platform fee, so we would issue points against postage handed to a
+ * courier. And it excludes the points tender itself, or points breed points.
+ *
+ * `orderTaxableValue` is reused rather than a fresh sum: it is already the
+ * post-discount, per-line, tax-backed-out goods figure, and it is already the
+ * payout base — so the number the seller is paid on and the number they fund
+ * points on are the same number, which is the property that makes the
+ * seller-funded model explicable to them.
+ *
+ * ## 🛑 The STORE bears it
+ *
+ * Owner: *"so stores bear it"*, framed as *"like a sale discount for getting a
+ * repeat customer."* So it is a DEDUCTION TERM in the payout, never a
+ * clawback — and that works only because of an ordering guarantee worth
+ * stating: `payout-release` is `blockedBy: ["order-complete"]`, so the gate
+ * opens BECAUSE the order completed, and completion is the same event that
+ * issues the points. The award is therefore always strictly before the payout
+ * is computed, by construction rather than by timing luck.
+ */
+import { orderRepository } from "../../../../features/orders/repository/orders.repository.js";
+import { pointsRepository } from "../../../../features/points/repository/points.repository.js";
+import { POINTS_EARN_PERCENT, pointsExpiryFrom, } from "../../../../features/points/schemas/firestore.js";
+import { orderTaxableValue } from "../../../shared/checkout/order-math.js";
+import { normalizeError } from "../../../../errors/normalize.js";
+import { serverLogger } from "../../../../monitoring/index.js";
+function roundPoints(value) {
+    return Math.round(value * 100) / 100;
+}
+/**
+ * Award points for one completed order. Safe to call from both triggers.
+ *
+ * Takes the order rather than an id when the caller already holds one — both
+ * completion paths do, and re-reading it would pay a Firestore read to learn
+ * what the caller just wrote.
+ */
+export async function awardPurchasePoints(order) {
+    /*
+     * The key. Checked first and checked again by the caller's own write
+     * ordering — a double call is the NORMAL case here, not an edge: the buyer
+     * completes early and the 7-day sweep later finds the order already
+     * complete, or a retried action runs twice.
+     */
+    if (order.pointsAwardedAt) {
+        return { awarded: 0, skipped: "already-awarded" };
+    }
+    if (!order.completedAt) {
+        /*
+         * Refused rather than treated as an implicit completion. The award is a
+         * consequence of a fact somebody recorded; inferring the fact from the
+         * award's own call site would let any caller mint points by asking.
+         */
+        return { awarded: 0, skipped: "not-complete" };
+    }
+    if (!order.userId) {
+        serverLogger.error("purchase points: completed order has no buyer", {
+            orderId: order.id,
+        });
+        return { awarded: 0, skipped: "no-buyer" };
+    }
+    const goods = orderTaxableValue(order);
+    const amount = roundPoints((goods * POINTS_EARN_PERCENT) / 100);
+    if (amount <= 0) {
+        /*
+         * A fully-cancelled or zero-value order. Marked as awarded anyway below so
+         * the sweep stops revisiting it — "we looked and there was nothing to
+         * give" is a decision, and leaving it unmarked would re-read this order on
+         * every tick forever.
+         */
+        await orderRepository
+            .update(order.id, { pointsAwardedAt: new Date() })
+            .catch((err) => {
+            void normalizeError(err);
+        });
+        return { awarded: 0, skipped: "nothing-earnable" };
+    }
+    const now = new Date();
+    await pointsRepository.append({
+        userId: order.userId,
+        kind: "purchase_earn",
+        amount,
+        orderId: order.id,
+        /*
+         * Names the base and the rate, because "47 points" alone is unexplainable
+         * later — and written once rather than re-derived, so it stays true of this
+         * moment even if the order is edited afterwards.
+         */
+        description: `${POINTS_EARN_PERCENT}% back on ${order.id}: ₹${goods.toFixed(2)} of items.`,
+        expiresAt: pointsExpiryFrom(now),
+    });
+    /*
+     * 🛑 The key is written AFTER the credit, and that ordering is deliberate.
+     *
+     * A crash between them leaves a credited buyer and an order that looks
+     * unawarded — so the next trigger credits a second time. That is the lesser
+     * evil, and the same choice `reconcileOrderShipping` documents: the reverse
+     * ordering would mark the order done and then fail to pay, which is money a
+     * buyer was promised and silently never got. An extra credit is visible in
+     * the ledger and reversible by an `admin_adjustment`; a missing one is
+     * invisible to everybody.
+     */
+    await orderRepository.update(order.id, {
+        pointsAwardedAt: now,
+        pointsAwarded: amount,
+    });
+    serverLogger.info("purchase points awarded", {
+        orderId: order.id,
+        userId: order.userId,
+        goods,
+        amount,
+    });
+    return { awarded: amount };
+}

package/dist/_internal/server/features/price-index/market.d.ts

@@ -1,4 +1,14 @@
 import { PRICE_GUIDANCE_TAX_BASIS } from "../../../shared/features/categories/price-guidance";
+/**
+ * Where a row's figures came from, and therefore what may be claimed for them.
+ *
+ * 🛑 This is not decoration and a renderer that drops it will overclaim. A
+ * `computed` row is a mode over dated sightings of THIS leaf and may be
+ * labelled "most common price, last 6 months". A `seeded` row is the 2026-10
+ * crawl's median for an entire GENERATION, frozen at one date — calling that
+ * "most common" or "recent" would be false in both halves.
+ */
+export type PriceIndexMarketOrigin = "computed" | "seeded";
 export interface PriceIndexMarketRow {
     categoryId: string;
     /**
@@ -16,6 +26,29 @@ export interface PriceIndexMarketRow {
     p75?: number;
     sampleSize?: number;
     asOf?: string;
+    origin: PriceIndexMarketOrigin;
+    /**
+     * The price sightings cluster on. `computed` rows only.
+     *
+     * 🛑 Optional even there: absent means no price bucket held two or more
+     * sightings, so there is no cluster and the renderer must fall back to
+     * `median` under a different label rather than printing a lone sighting as
+     * though it were a consensus.
+     */
+    mode?: number;
+    modeCount?: number;
+    /** Observed low/high over the window below. `computed` rows only. */
+    low?: number;
+    high?: number;
+    /**
+     * 🛑 FALSE means `low`/`high`/`mode` describe ALL TIME — the six-month window
+     * held too little to stand alone. The renderer must relabel; a stale figure
+     * is indistinguishable from a current one once printed.
+     */
+    basedOnRecent?: boolean;
+    windowDays?: number;
+    /** Newest sighting behind a `computed` row. Not the rollup time. */
+    lastSeenAt?: string;
     /**
      * The share of competitor listings at this level that are SOLD OUT (0.85,
      * measured across the five largest catalogues).

package/dist/_internal/server/features/price-index/market.js

@@ -55,6 +55,7 @@
  */
 import { resolveInheritedGuidanceMany } from "../categories/price-guidance-resolve.js";
 import { PRICE_GUIDANCE_TAX_BASIS } from "../../../shared/features/categories/price-guidance.js";
+import { marketPriceIndexRepository } from "../../../../features/categories/repository/market-price-index.repository.js";
 import { PRICE_INDEX_SEARCH_LIMIT } from "./search.js";
 /**
  * Market bands for the leaves the client already resolved.
@@ -72,9 +73,60 @@ export async function getPriceIndexMarketForIds(rawIds) {
     const ids = [...new Set(rawIds.filter((id) => typeof id === "string" && id.length > 0))].slice(0, PRICE_INDEX_SEARCH_LIMIT);
     if (ids.length === 0)
         return [];
-    const guidanceById = await resolveInheritedGuidanceMany(ids);
+    /*
+     * Both halves in parallel. The computed read is one `getAll`, the seeded one
+     * is two batched reads — three round trips total against Rule #6's budget,
+     * and sequencing them would make it three in series for no benefit since
+     * neither depends on the other.
+     */
+    const [guidanceById, computedById] = await Promise.all([
+        resolveInheritedGuidanceMany(ids),
+        marketPriceIndexRepository.getManyForLeaves(ids),
+    ]);
     const rows = [];
     for (const id of ids) {
+        /*
+         * 🛑 A COMPUTED band for this exact leaf outranks any seeded one.
+         *
+         * The seeded band is a crawl median for a whole generation, so every model
+         * in an era carries the same number — which is how Dragoon MS and Strata
+         * Dragoon MS, different beys with different markets, both reported ₹3,999.
+         * A computed band is dated sightings of THIS leaf. Where both exist the
+         * specific measurement wins; where only the generation band exists it still
+         * shows, labelled as the generation's.
+         *
+         * 🛑 Looked up for the LEAF ONLY, deliberately. Computed bands do not walk
+         * the ancestor chain: observations are recorded against the thing that was
+         * actually priced, so an era-level row would be evidence about the era and
+         * inheriting it down to a model would re-create the exact conflation this
+         * precedence exists to end. The seeded band remains the inherited fallback,
+         * and it says so on the card.
+         */
+        const computed = computedById.get(id)?.byKind?.ask;
+        if (computed) {
+            rows.push({
+                categoryId: id,
+                origin: "computed",
+                median: computed.median,
+                ...(computed.mode === undefined
+                    ? {}
+                    : { mode: computed.mode, modeCount: computed.modeCount }),
+                low: computed.low,
+                high: computed.high,
+                sampleSize: computed.sampleSize,
+                basedOnRecent: computed.basedOnRecent,
+                windowDays: computed.windowDays,
+                ...(toIso(computed.lastSeenAt) ? { lastSeenAt: toIso(computed.lastSeenAt) } : {}),
+                /*
+                 * A computed band is this leaf's own measurement by construction — it
+                 * is keyed on the leaf id and never inherited — so `inherited` is
+                 * false and no `via*` attribution applies.
+                 */
+                inherited: false,
+                taxBasis: PRICE_GUIDANCE_TAX_BASIS,
+            });
+            continue;
+        }
         const resolved = guidanceById.get(id);
         const market = resolved?.guidance.market;
         // No band anywhere up the chain. Omitted, never zeroed.
@@ -82,6 +134,7 @@ export async function getPriceIndexMarketForIds(rawIds) {
             continue;
         rows.push({
             categoryId: id,
+            origin: "seeded",
             median: market.median,
             ...(market.p25 === undefined ? {} : { p25: market.p25 }),
             ...(market.p75 === undefined ? {} : { p75: market.p75 }),

package/dist/_internal/server/features/products/data.js

@@ -14,6 +14,9 @@ import { PRODUCT_COLLECTION } from "../../../../features/products/schemas/firest
 import { PRODUCTS_SITEMAP_LIMIT } from "../../../shared/features/products/config.js";
 import { isListingRowAvailable } from "../../../shared/listing-types/_registry.js";
 import { isPubliclyVisible } from "../../../shared/listing-types/availability.js";
+import { isListingTypeEnabled } from "../../../shared/listing-types/feature-flags.js";
+import { normalizeListingType } from "../../../../features/products/utils/listing-type.js";
+import { getSiteSettingsSafe } from "../site-settings/safe-settings.js";
 import { PRODUCT_FIELDS } from "../../../../constants/field-names.js";
 import { SIEVE_OP, sieveAnd, sieveFilter, sortBy } from "../../../../utils/sieve-builder.js";
 import { REVIEW_FIELDS } from "../../../../constants/field-names.js";
@@ -163,7 +166,17 @@ export async function listSitemapProducts() {
             .select("slug", "id", "updatedAt", "listingType")
             .limit(PRODUCTS_SITEMAP_LIMIT)
             .get();
-        return snapshot.docs.map((doc) => {
+        /*
+         * 🛑 A disabled listing type must not be advertised to search engines.
+         * This is the furthest-reaching surface of the lot: a sitemap entry
+         * survives the admin toggle, gets crawled, and lands a visitor on a type
+         * the site has switched off. Filtered in memory rather than in the query
+         * because the enabled set is a settings map, not a Firestore field.
+         */
+        const settings = await getSiteSettingsSafe();
+        return snapshot.docs
+            .filter((doc) => isListingTypeEnabled(normalizeListingType(doc.data()), settings))
+            .map((doc) => {
             const data = doc.data();
             const rawListingType = data.listingType;
             const listingType = rawListingType === "auction" ||
@@ -190,25 +203,21 @@ export async function listSitemapProducts() {
 // ---------------------------------------------------------------------------
 const RELATED_QUERY_PAGE_SIZE = 9;
 const RELATED_DISPLAY_LIMIT = 8;
-/** Firestore doc → card-grid shape. Shared by every related/similar-items carousel. */
-/**
- * Excludes the current product, anything not publicly visible, and anything
- * no longer available — ended auctions, closed prize-draws, filled pre-orders,
- * depleted code pools, sold-out stock.
- *
- * This used to be a private `isValidRelatedItem` here, and it was the only
- * per-type availability predicate in the codebase — which meant it was also
- * the only place three bugs could hide: it read `codesAvailable` at the top
- * level when the schema nests it under `digitalCode.codesAvailable` (so that
- * branch never fired), it excluded `status` values ("sold", "out_of_stock",
- * "discontinued") that are not members of the real `ProductStatus` union, and
- * it had no branch at all for classified / live / art / stickers. It now
- * shares one definition with the listing query and the homepage.
- */
-function toRelatedItems(docs, currentProductId) {
+function toRelatedItems(docs, currentProductId, settings) {
     const now = new Date();
     return docs
-        .filter((r) => r.id !== currentProductId && isPubliclyVisible(r) && isListingRowAvailable(r, now))
+        .filter((r) => r.id !== currentProductId &&
+        isPubliclyVisible(r) &&
+        /*
+         * 🛑 A DISABLED listing type must not appear here. Related items are
+         * pure DISCOVERY — unlike a won auction sitting in the cart, nothing
+         * here is an obligation the buyer already holds, so there is no reason
+         * to surface a type the admin has switched off. Without this an
+         * auction card rendered on every related carousel with auctions
+         * disabled, and it was reachable by clicking it.
+         */
+        isListingTypeEnabled(normalizeListingType(r), settings) &&
+        isListingRowAvailable(r, now))
         .slice(0, RELATED_DISPLAY_LIMIT)
         .map(toProductItem);
 }
@@ -256,10 +265,19 @@ export const computeRelatedItems = cache(async (product) => {
                 .catch(() => [])
             : Promise.resolve([]),
     ]);
+    /*
+     * Fetched AFTER the four queries rather than inside the Promise.all: it is
+     * a cached single-doc read, and keeping it out of the fan-out keeps the
+     * four product queries parallel. `getSiteSettingsSafe` returns null on
+     * failure, and `isListingTypeEnabled` reads a missing flag as ENABLED — so
+     * a settings read that fails shows everything rather than hiding the page,
+     * which is the right failure direction for a discovery surface.
+     */
+    const settings = await getSiteSettingsSafe();
     return {
-        relatedItems: toRelatedItems(sameCategoryDocs, currentProductId),
-        relatedByBrand: toRelatedItems(sameBrandDocs, currentProductId),
-        relatedByTags: toRelatedItems(tagOverlapDocs, currentProductId),
-        relatedByStore: toRelatedItems(sameStoreDocs, currentProductId),
+        relatedItems: toRelatedItems(sameCategoryDocs, currentProductId, settings),
+        relatedByBrand: toRelatedItems(sameBrandDocs, currentProductId, settings),
+        relatedByTags: toRelatedItems(tagOverlapDocs, currentProductId, settings),
+        relatedByStore: toRelatedItems(sameStoreDocs, currentProductId, settings),
     };
 });

package/dist/_internal/server/features/protection-claims/actions.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Filing and adjudicating a protection claim — the first callers
+ * `protectionAvailability()` and `adjudicateClaim()` have ever had.
+ *
+ * ## What was wrong (D11)
+ *
+ * We charge 2% (min ₹30) shipment protection and 3% (min ₹49) sale protection
+ * at four money sites. The decision logic, the custody state machine, the
+ * window constants and the order fields all existed with **zero callers**, and
+ * the refund path did not know the add-on existed. A FAQ promised *"we pursue
+ * the courier and refund you"* and *"refunded no questions asked"*.
+ *
+ * ## The two gates, and why both are server-side
+ *
+ * 1. **Did the buyer actually buy this cover?** Read off the ORDER's own
+ *    `shipmentProtectionFee` / `saleProtectionFee` — the amount charged — not
+ *    off the live store or the live settings. A seller must not be able to
+ *    withdraw cover after the sale, which is the same snapshot reasoning
+ *    `finalSale` uses on the refund path.
+ * 2. **Is the window still open?** The `claim-shipping` / `claim-sale`
+ *    obligations, derived from `deliveryDate` through
+ *    `PROTECTION_CLAIM_WINDOW_HOURS` (48h / 168h). One definition, shared with
+ *    the sweep that closes the window and earns the premium.
+ */
+import { type ActionResult } from "../../../shared/types/action-result";
+import { type ProtectionClaimDocument, type ProtectionClaimReason } from "../../../../features/protection-claims/schemas/firestore";
+import { adjudicateClaim, type ClaimFinding } from "../../../shared/features/shipping/protections";
+import { deadlinesFor } from "../../../shared/obligations/deadlines";
+export interface FileProtectionClaimInput {
+    orderId: string;
+    reason: ProtectionClaimReason;
+    detail: string;
+    itemIds?: string[];
+    evidenceUrls?: string[];
+}
+/**
+ * File a claim as the buyer.
+ *
+ * 🛑 The COVER KIND is derived from the reason, never taken from the caller.
+ * `REASON_TO_KIND` maps transit failures to shipment cover and item failures
+ * to sale cover — because letting the buyer pick would let them file a
+ * non-delivery against the 7-day sale window after the 48-hour transit window
+ * had closed, which is the window rule defeated by a dropdown.
+ */
+export declare function fileProtectionClaimAction(input: FileProtectionClaimInput): Promise<ActionResult<{
+    claimId: string;
+}>>;
+/**
+ * Adjudicate as an admin or moderator.
+ *
+ * 🛑 THE FINDING DECIDES WHO PAYS, NEVER WHETHER A PROTECTED BUYER IS
+ * REFUNDED. `adjudicateClaim` encodes that and this action does not
+ * second-guess it: on protected cover a `change-of-mind` finding STILL refunds
+ * the buyer and moves the cost to the platform, raising a report — because the
+ * promise sold was unconditional, and the only honest enforcement against
+ * repeat abuse is withdrawing FUTURE eligibility, not denying this claim.
+ *
+ * 🛑 It records the decision and does NOT move money. The refund is
+ * `processRefundAction`'s job, with its own idempotency key — and keeping them
+ * apart means a claim that adjudicated but failed to refund leaves an `upheld`
+ * claim with no `refundId`, which is a findable state rather than a lost one.
+ */
+export declare function adjudicateProtectionClaimAction(claimId: string, finding: ClaimFinding): Promise<ActionResult<{
+    outcome: ReturnType<typeof adjudicateClaim>;
+}>>;
+/** A buyer's own claims, for their order detail page. */
+export declare function getMyProtectionClaimsAction(): Promise<ActionResult<ProtectionClaimDocument[]>>;
+/** Whether this order can be claimed against right now, for rendering the CTA. */
+export declare function canClaimProtection(order: Parameters<typeof deadlinesFor>[0], kind: "shipping" | "sale"): Promise<{
+    can: boolean;
+    reason?: string;
+}>;