@mohasinac/appkit 4.53.1 → 4.54.0

package/dist/.build-stamp.json

@@ -1,8 +1,8 @@
 {
   "stampVersion": 1,
-  "version": "4.53.1",
-  "head": "d45b9f65d4b73c4c4a079a8ee5553600ddd0c251",
+  "version": "4.54.0",
+  "head": "9acce85ff44a5e7a1d6110bedceb5f29dc0e999c",
   "branch": "main",
   "dirty": false,
-  "builtAt": "2026-10-19T21:36:59.723Z"
+  "builtAt": "2026-10-20T05:45:17.216Z"
 }

package/dist/_internal/client/theme/ThemeProvider.js

@@ -20,7 +20,21 @@ function readModePreference() {
     catch (_err) {
         void normalizeError(_err); /* localStorage unavailable in privacy/iframe context */
     }
-    return "auto";
+    /*
+     * 🛑 LIGHT, not "auto" — a product decision, not a technical one.
+     *
+     * "auto" follows `prefers-color-scheme`, and most phones and an increasing
+     * share of desktops now report dark. That made dark the de-facto default
+     * for a storefront whose product photography is shot on white: every
+     * listing tile rendered a bright cut-out against a near-black card, which
+     * is the opposite of how the catalogue was designed to read.
+     *
+     * This changes the DEFAULT only. A visitor who has chosen either mode has
+     * "light"/"dark"/"auto" in localStorage and is returned above, untouched —
+     * including anyone who deliberately picked "auto". The dark theme itself is
+     * unchanged and one click away.
+     */
+    return "light";
 }
 function resolveEffectiveMode(preference) {
     if (preference === "light" || preference === "dark")

package/dist/_internal/server/features/auth/capabilities.js

@@ -5,7 +5,7 @@
  * Call this server-side only — never trust client-provided capability arrays.
  */
 import { storeRepository } from "../../../../repositories/index.js";
-import { DEFAULT_STORE_CAPABILITIES, } from "../../../../features/auth/permissions/constants.js";
+import { DEFAULT_STORE_CAPABILITIES, resolveStoreCapabilities, } from "../../../../features/auth/permissions/constants.js";
 /**
  * Return the resolved capability set for a store.
  * Falls back to DEFAULT_STORE_CAPABILITIES when the store has no capabilities field.
@@ -16,10 +16,12 @@ export async function getStoreCapabilities(storeId) {
     const store = await storeRepository.findById(storeId);
     if (!store)
         return [...DEFAULT_STORE_CAPABILITIES];
-    const raw = store.capabilities;
-    if (Array.isArray(raw) && raw.length > 0)
-        return raw;
-    return [...DEFAULT_STORE_CAPABILITIES];
+    /*
+     * The merge itself lives in `resolveStoreCapabilities` so a caller holding
+     * the store document already can run the same rule without a second read.
+     * This function is now just "fetch, then resolve".
+     */
+    return resolveStoreCapabilities(store.capabilities);
 }
 /**
  * Check whether a store has a specific capability.

package/dist/_internal/server/features/categories/price-guidance-resolve.d.ts

@@ -0,0 +1,66 @@
+import type { CategoryPriceGuidance } from "../../../../features/categories/schemas/category-content";
+/**
+ * How far up the chain to look.
+ *
+ * `parentIds` holds the FULL ancestor chain (CLAUDE.md § "Category Tree"), and
+ * the forest is four tiers, so eight is slack rather than a limit. It exists so
+ * a malformed chain cannot turn one lookup into an unbounded read.
+ */
+export declare const MAX_GUIDANCE_ANCESTORS = 8;
+/** The fields of a category document this resolution reads. */
+export interface GuidanceLeafDoc {
+    id?: string;
+    name?: string;
+    parentIds?: string[];
+    productDefaults?: {
+        priceGuidance?: CategoryPriceGuidance;
+    };
+}
+/**
+ * A resolved band together with WHERE it came from.
+ *
+ * 🛑 The provenance is not decoration, and a caller that drops it will
+ * misattribute. `MARKET_BANDS` is keyed on era and part leaves, never on the
+ * ~216 named-model leaves, so a model lookup almost always resolves an
+ * ancestor's band — "typical for Burst DB" is a true statement about the data
+ * and "typical for Rage Longinus" is not. A renderer needs to be able to say
+ * which one it is showing.
+ */
+export interface ResolvedGuidance {
+    guidance: CategoryPriceGuidance;
+    /** The node the band was read off — the leaf itself, or an ancestor. */
+    fromCategoryId: string;
+    fromName?: string;
+    /** `false` when the leaf carried its own band. */
+    inherited: boolean;
+}
+/**
+ * Nearest-first ancestor walk for one leaf.
+ *
+ * The leaf's own band wins; only a leaf with none falls back to the nearest
+ * ancestor that has one.
+ *
+ * 🛑 ONE bounded `findByIds`, never a sequential walk. A seller form hits this
+ * on every category change, and paying up to eight round trips for a hint is
+ * how a hint becomes the slowest thing on the page.
+ *
+ * 🛑 `parentIds` is stored ROOT-FIRST, so it is reversed to walk nearest-first.
+ * Walking it as stored would hand a model leaf the ROOT's band — and since the
+ * root carries a tax default but no market band, that would usually resolve to
+ * nothing and read as "no data" for a leaf whose era has a measured band.
+ */
+export declare function resolveInheritedGuidance(leaf: GuidanceLeafDoc): Promise<CategoryPriceGuidance | undefined>;
+/**
+ * The same resolution for MANY leaves, in two batched reads total.
+ *
+ * Read 1 fetches the leaves; read 2 fetches the UNION of every ancestor id
+ * none of them resolved locally. A per-leaf `resolveInheritedGuidance` would be
+ * N+1 reads against Rule #6's ~3-round-trip budget, and the tool resolves up to
+ * `PRICE_INDEX_SEARCH_LIMIT` leaves at once.
+ *
+ * Leaves that resolve to nothing are ABSENT from the returned map rather than
+ * present with `undefined` — the caller distinguishes "no band applies here"
+ * from "this id does not exist", and both are legitimate answers it must be
+ * able to tell apart.
+ */
+export declare function resolveInheritedGuidanceMany(ids: readonly string[]): Promise<Map<string, ResolvedGuidance>>;

package/dist/_internal/server/features/categories/price-guidance-resolve.js

@@ -0,0 +1,138 @@
+/*
+ * WHY: Two surfaces now need "the price guidance that applies to this leaf":
+ *      the seller form's hint (`/api/categories/[id]/price-guidance`) and the
+ *      public realised-price tool's gated market half
+ *      (`/api/tools/price-index/market`). The ancestor walk was written
+ *      privately inside the first of those, which is exactly the shape Root
+ *      Cause #75 describes — a rule reachable by copy-paste gets copied, and
+ *      the copy never learns about the branch added later.
+ * WHAT: The nearest-first inherited `priceGuidance` resolution, for one leaf
+ *       and for many, in one place.
+ *
+ * EXPORTS:
+ *   MAX_GUIDANCE_ANCESTORS      — the walk bound
+ *   ResolvedGuidance            — a band PLUS which node it came from
+ *   resolveInheritedGuidance    — one leaf document -> its applicable guidance
+ *   resolveInheritedGuidanceMany — N leaf ids -> a Map, two batched reads
+ *
+ * 🛑 Why a leaf's OWN band wins. `MARKET_BANDS` is keyed on era / part /
+ *    launcher / stadium leaves (`category-burst-db`, `category-metal-energy-rings`),
+ *    never on the ~216 named-model leaves — the crawl measured a generation,
+ *    not a bey. So a model leaf has no band of its own and inherits its era's,
+ *    which is the whole reason this walk exists rather than a direct read.
+ *
+ * @tag domain:categories
+ * @tag layer:server
+ * @tag pattern:resolver
+ * @tag access:server-only
+ * @tag consumers:categories/api/[id]/price-guidance,price-index/market
+ * @tag sideEffects:none
+ */
+import { categoriesRepository } from "../../../../features/categories/repository/categories.repository.js";
+/**
+ * How far up the chain to look.
+ *
+ * `parentIds` holds the FULL ancestor chain (CLAUDE.md § "Category Tree"), and
+ * the forest is four tiers, so eight is slack rather than a limit. It exists so
+ * a malformed chain cannot turn one lookup into an unbounded read.
+ */
+export const MAX_GUIDANCE_ANCESTORS = 8;
+/**
+ * Nearest-first ancestor walk for one leaf.
+ *
+ * The leaf's own band wins; only a leaf with none falls back to the nearest
+ * ancestor that has one.
+ *
+ * 🛑 ONE bounded `findByIds`, never a sequential walk. A seller form hits this
+ * on every category change, and paying up to eight round trips for a hint is
+ * how a hint becomes the slowest thing on the page.
+ *
+ * 🛑 `parentIds` is stored ROOT-FIRST, so it is reversed to walk nearest-first.
+ * Walking it as stored would hand a model leaf the ROOT's band — and since the
+ * root carries a tax default but no market band, that would usually resolve to
+ * nothing and read as "no data" for a leaf whose era has a measured band.
+ */
+export async function resolveInheritedGuidance(leaf) {
+    if (leaf.productDefaults?.priceGuidance)
+        return leaf.productDefaults.priceGuidance;
+    const parentIds = (leaf.parentIds ?? []).slice(0, MAX_GUIDANCE_ANCESTORS);
+    if (parentIds.length === 0)
+        return undefined;
+    const nearestFirst = [...parentIds].reverse();
+    const ancestors = await categoriesRepository.findByIds(nearestFirst);
+    const byId = new Map(ancestors.map((a) => [a.id, a]));
+    for (const pid of nearestFirst) {
+        const guidance = byId.get(pid)?.productDefaults?.priceGuidance;
+        if (guidance)
+            return guidance;
+    }
+    return undefined;
+}
+/**
+ * The same resolution for MANY leaves, in two batched reads total.
+ *
+ * Read 1 fetches the leaves; read 2 fetches the UNION of every ancestor id
+ * none of them resolved locally. A per-leaf `resolveInheritedGuidance` would be
+ * N+1 reads against Rule #6's ~3-round-trip budget, and the tool resolves up to
+ * `PRICE_INDEX_SEARCH_LIMIT` leaves at once.
+ *
+ * Leaves that resolve to nothing are ABSENT from the returned map rather than
+ * present with `undefined` — the caller distinguishes "no band applies here"
+ * from "this id does not exist", and both are legitimate answers it must be
+ * able to tell apart.
+ */
+export async function resolveInheritedGuidanceMany(ids) {
+    const out = new Map();
+    const unique = [...new Set(ids.filter((id) => typeof id === "string" && id.length > 0))];
+    if (unique.length === 0)
+        return out;
+    const leaves = (await categoriesRepository.getManyByIds(unique));
+    /*
+     * Everything still unanswered after the leaves' own bands, paired with the
+     * nearest-first chain it needs — collected before the second read so that
+     * read is one call for every leaf at once.
+     */
+    const pending = [];
+    const wanted = new Set();
+    for (const leaf of leaves) {
+        const id = leaf.id;
+        if (!id)
+            continue;
+        const own = leaf.productDefaults?.priceGuidance;
+        if (own) {
+            out.set(id, {
+                guidance: own,
+                fromCategoryId: id,
+                ...(leaf.name ? { fromName: leaf.name } : {}),
+                inherited: false,
+            });
+            continue;
+        }
+        const chain = [...(leaf.parentIds ?? []).slice(0, MAX_GUIDANCE_ANCESTORS)].reverse();
+        if (chain.length === 0)
+            continue;
+        pending.push({ id, chain });
+        for (const pid of chain)
+            wanted.add(pid);
+    }
+    if (pending.length === 0)
+        return out;
+    const ancestors = (await categoriesRepository.findByIds([...wanted]));
+    const byId = new Map(ancestors.filter((a) => a.id).map((a) => [a.id, a]));
+    for (const { id, chain } of pending) {
+        for (const pid of chain) {
+            const ancestor = byId.get(pid);
+            const guidance = ancestor?.productDefaults?.priceGuidance;
+            if (guidance) {
+                out.set(id, {
+                    guidance,
+                    fromCategoryId: pid,
+                    ...(ancestor?.name ? { fromName: ancestor.name } : {}),
+                    inherited: true,
+                });
+                break;
+            }
+        }
+    }
+    return out;
+}

package/dist/_internal/server/features/checkout/actions.d.ts

@@ -113,7 +113,6 @@ export interface CheckoutPricingPreviewStore {
     subtotal: number;
     shippingFee: number;
     codHandlingFee: number;
-    whatsappNotifyFee: number;
     giftWrapFee: number;
     shipmentProtectionFee: number;
     saleProtectionFee: number;
@@ -145,7 +144,6 @@ export interface CheckoutPricingPreview {
     subtotal: number;
     shippingFee: number;
     codHandlingFee: number;
-    whatsappNotifyFee: number;
     giftWrapFee: number;
     shipmentProtectionFee: number;
     saleProtectionFee: number;
@@ -168,7 +166,7 @@ export interface CheckoutPricingPreview {
 /**
  * Read-only "what will I actually be charged" preview for the checkout
  * Order Summary. Reuses the exact same building blocks
- * createCheckoutOrderAction / verifyAndPlacePhonePeOrderAction use when an
+ * createCheckoutOrderAction / verifyAndPlaceGatewayOrderAction use when an
  * order is actually placed — resolveShippingCost, the compute*Fee helpers,
  * computeGroupCouponDiscount, and the GST calc — so the number shown to the
  * buyer can never diverge from what gets charged/recorded. Never decrements
@@ -184,9 +182,27 @@ export declare function attachPaymentAction(input: {
     paymentId: string;
     paidAmount: number;
 }): Promise<void>;
-export interface VerifyAndPlacePhonePeOrderInput {
-    /** PhonePe's merchantOrderId — our own id, generated in PhonePeProvider.createOrder(). */
+export interface VerifyAndPlaceGatewayOrderInput {
+    /**
+     * The gateway order id every lookup for this payment is keyed on, and what
+     * gets stored as `order.paymentId`: PhonePe's own `merchantOrderId`
+     * (generated in `PhonePeProvider.createOrder()`), or Razorpay's `order_…`.
+     */
     merchantOrderId: string;
+    /**
+     * Razorpay's client callback, when the buyer-present path has it. Omit on
+     * the webhook path and for PhonePe, which has no such callback.
+     *
+     * Verified IN ADDITION to the server-side order fetch, never instead of it
+     * — see the block comment above. A present-but-invalid signature is a hard
+     * failure: it means the browser's callback was forged or tampered with,
+     * even if the order did turn out to be paid.
+     */
+    razorpaySignature?: {
+        razorpay_order_id: string;
+        razorpay_payment_id: string;
+        razorpay_signature: string;
+    };
     /**
      * Buyer identity. Omit on the webhook path — no session exists there, so
      * it's resolved from `uid` packed into PhonePe's `metaInfo` at
@@ -205,4 +221,4 @@ export interface VerifyAndPlacePhonePeOrderInput {
      */
     outOfStockPolicy?: OutOfStockPolicy;
 }
-export declare function verifyAndPlacePhonePeOrderAction(input: VerifyAndPlacePhonePeOrderInput): Promise<CheckoutOrderResult>;
+export declare function verifyAndPlaceGatewayOrderAction(input: VerifyAndPlaceGatewayOrderInput): Promise<CheckoutOrderResult>;