@mohasinac/appkit 4.59.0 → 4.60.1

package/dist/_internal/server/features/reviews/actions.js

@@ -31,8 +31,9 @@ export async function createReviewAction(input) {
             // line translated it. Both now use the document's own name.
             comment,
             images: images ?? [],
-            verified: false,
-            status: "pending",
+            /* `verified` and `status` are set by `createReview` itself and are
+               omitted from `ReviewCreateInput` — passing them here duplicated the
+               repository default and was the reason the input type demanded them. */
         });
     });
 }

package/dist/_internal/server/features/search/index-build/sources.js

@@ -134,7 +134,26 @@ export const PUBLIC_INDEX_SOURCES = [
              * those words appeared was a facet nobody searches. Humanised, so
              * "pre-order" and "digital code" read as words rather than slugs.
              */
-            const human = (v) => (str(v) ?? "").replace(/[-_]/g, " ");
+            /*
+             * Capitalised, not just de-slugged.
+             *
+             * This returned the lowercase value, so a shopper's result subtitle read
+             * "Beyblade · Victory Valkyrie Boost Variable · standard · new" — two
+             * database values sitting in a line of otherwise presentable text, which
+             * is the audit's "subtitles print raw field values".
+             *
+             * 🛑 Casing is FREE here, which is the only reason to do it in the index
+             * rather than at the renderer. `prepareIndex` matches through
+             * `normalizeSearchText`, which lowercases both the haystack and the
+             * query — so "Standard" is still found by typing "standard", and the
+             * searchability this field exists for (see the note above) is untouched.
+             * The alternative, a second display-only string per record, would grow
+             * every row of an index the client downloads.
+             */
+            const human = (v) => {
+                const words = (str(v) ?? "").replace(/[-_]/g, " ").trim();
+                return words ? words.charAt(0).toUpperCase() + words.slice(1) : "";
+            };
             return {
                 title,
                 // Leaf-first, so [0] is the most specific label.

package/dist/_internal/server/features/shipping/reconcile.d.ts

@@ -4,8 +4,17 @@ export interface ReconcileShippingResult {
     outcome: "credited" | "seller-absorbed" | "exact" | null;
     sellerAbsorbs: number;
     buyerPoints: number;
+    /**
+     * Rupees of postage the seller is owed back — `min(spent, charged)`.
+     *
+     * 🛑 Computed on BOTH branches, because today the platform keeps shipping in
+     * the quoted path too, so D45 is a fix for both rather than a new rule for
+     * one. Whether it is PAID is a separate gate: `isReimbursableShipment`
+     * refuses a Shiprocket-booked parcel, which we paid for ourselves.
+     */
+    reimbursable: number;
     /** Why nothing happened, when `outcome` is null. For logs and the UI. */
-    skipped?: "no-quote" | "already-reconciled" | "no-buyer";
+    skipped?: "no-quote" | "already-reconciled" | "no-buyer" | "awaiting-evidence";
 }
 /**
  * 🛑 IDEMPOTENT, and the guard is `order.shippingReconciliation` being unset.

package/dist/_internal/server/features/shipping/reconcile.js

@@ -29,7 +29,13 @@ import { serverLogger } from "../../../../monitoring/index.js";
 export async function reconcileOrderShipping(orderId, actual) {
     const order = await orderRepository.findById(orderId);
     if (!order) {
-        return { outcome: null, sellerAbsorbs: 0, buyerPoints: 0, skipped: "no-quote" };
+        return {
+            outcome: null,
+            sellerAbsorbs: 0,
+            buyerPoints: 0,
+            reimbursable: 0,
+            skipped: "no-quote",
+        };
     }
     /*
      * No quote means this order never went through the courier picker — a
@@ -39,13 +45,31 @@ export async function reconcileOrderShipping(orderId, actual) {
      * against a number that was never a courier quote.
      */
     if (!order.selectedShippingQuote) {
-        return { outcome: null, sellerAbsorbs: 0, buyerPoints: 0, skipped: "no-quote" };
+        /*
+         * 🛑 THIS SKIP BRANCH IS THE D45 CASE, and that is why it is still a skip
+         * HERE rather than being handled inline.
+         *
+         * No quote means the seller shipped manually, so there is no quoted figure
+         * to measure a saving against — and the money question is a different one:
+         * what did the postage actually cost, proven by a receipt an admin has
+         * approved. That is an admin-triggered event, not a dispatch-triggered one,
+         * so it lives in `approveShippingReimbursement` below. Both write the SAME
+         * `shippingReconciliation` field and therefore share one idempotency key.
+         */
+        return {
+            outcome: null,
+            sellerAbsorbs: 0,
+            buyerPoints: 0,
+            reimbursable: 0,
+            skipped: "no-quote",
+        };
     }
     if (order.shippingReconciliation) {
         return {
             outcome: null,
             sellerAbsorbs: order.shippingReconciliation.sellerAbsorbs,
             buyerPoints: order.shippingReconciliation.buyerPoints,
+            reimbursable: order.shippingReconciliation.reimbursable ?? 0,
             skipped: "already-reconciled",
         };
     }
@@ -63,7 +87,13 @@ export async function reconcileOrderShipping(orderId, actual) {
                 orderId,
                 buyerPoints: result.buyerPoints,
             });
-            return { outcome: null, sellerAbsorbs: 0, buyerPoints: 0, skipped: "no-buyer" };
+            return {
+                outcome: null,
+                sellerAbsorbs: 0,
+                buyerPoints: 0,
+                reimbursable: 0,
+                skipped: "no-buyer",
+            };
         }
         await pointsRepository.append({
             userId: buyerUid,
@@ -89,5 +119,6 @@ export async function reconcileOrderShipping(orderId, actual) {
         outcome: result.buyerPoints > 0 ? "credited" : result.sellerAbsorbs > 0 ? "seller-absorbed" : "exact",
         sellerAbsorbs: result.sellerAbsorbs,
         buyerPoints: result.buyerPoints,
+        reimbursable: result.reimbursable,
     };
 }

package/dist/_internal/server/features/shipping/reimbursement.d.ts

@@ -0,0 +1,117 @@
+/**
+ * The self-shipped postage reimbursement — D45's other half.
+ *
+ * ## Why this is a separate module from `reconcile.ts`
+ *
+ * `reconcileOrderShipping` runs at DISPATCH, on an order that went through the
+ * courier picker, and compares a quote against a declared spend. This runs on
+ * an order with NO quote, is triggered by a seller submitting evidence and then
+ * by an admin approving it, and compares what the buyer paid against an
+ * approved receipt. Different trigger, different inputs, different actor.
+ *
+ * 🛑 But they write the SAME `shippingReconciliation` field, and that is
+ * deliberate: two records of "what shipping actually cost" on one order is the
+ * denormalised-mirror trap (Root Cause #42). Sharing the field also shares the
+ * idempotency key — its presence is what stops a double-approval paying twice,
+ * exactly as it stops a double-dispatch crediting points twice.
+ *
+ * ## The owner's rule, verbatim
+ *
+ * *"If seller ships on their own then they have to upload the receipt of the
+ * shipment with the tracking number so that it is paid to them directly; if
+ * they use our platform's integration (Shiprocket) to place the order, they do
+ * not get the money, the platform keeps it… The seller may set an initial value
+ * of shipping but the only approved amount will be given to them."*
+ *
+ * Plus: reimbursement **capped at what the buyer paid**, and the saving to the
+ * **buyer as points**.
+ *
+ * ## The invariant worth stating
+ *
+ * **The platform nets exactly zero on shipping in every case.**
+ *
+ * | buyer paid | approved receipt | seller gets | buyer gets | platform |
+ * |---|---|---|---|---|
+ * | ₹120 | ₹80  | ₹80  | ₹40 points | **₹0** |
+ * | ₹80  | ₹120 | ₹80  | —          | **₹0** |
+ * | ₹100 | ₹100 | ₹100 | —          | **₹0** |
+ */
+import type { ReconcileShippingResult } from "./reconcile";
+export interface SubmitShippingEvidenceInput {
+    orderId: string;
+    /** What the seller says the postage cost. An ESTIMATE, not an entitlement. */
+    declaredAmount: number;
+    evidenceUrl?: string;
+    trackingNumber?: string;
+}
+/**
+ * The seller submits postage evidence on a self-shipped order.
+ *
+ * ## 🛑 It records a CLAIM and moves nothing
+ *
+ * *"The seller may set an initial value of shipping but the only approved
+ * amount will be given to them."* So this writes `declaredAmount` and stops.
+ * The entitlement is `approvedAmount`, written only once a human has read the
+ * receipt — and they are separate fields rather than one that gets
+ * overwritten, because a seller who claims ₹120 and is approved ₹80 must leave
+ * both figures visible.
+ *
+ * ## 🛑 The platform-booked refusal is about WHO BOOKED, not about evidence
+ *
+ * `isReimbursableShipment` keys on the booking. Gating on "a receipt exists"
+ * would be the exploitable version: a seller could upload a receipt for a
+ * parcel we paid Shiprocket for and be reimbursed for our own spend.
+ *
+ * Refused HERE as well as at approval, so the seller is told at submission
+ * rather than after waiting for a review that could only ever decline. That is
+ * the dead-end shape avoided (Root Cause #56).
+ */
+export declare function submitShippingEvidence(input: SubmitShippingEvidenceInput): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+}>;
+export interface ApproveShippingReimbursementInput {
+    orderId: string;
+    /** What an admin will actually pay. May differ from the declared amount. */
+    approvedAmount: number;
+    /** Why, when it differs from what was declared. */
+    note?: string;
+    /** 🛑 An admin uid. Never `"system"` — see below. */
+    approvedBy: string;
+}
+/**
+ * An admin approves a postage reimbursement.
+ *
+ * ## 🛑 Never automatic, and the ABSENCE of a system path is the enforcement
+ *
+ * This moves money to a seller on the strength of a document somebody has to
+ * look at. There is no overload accepting `"system"`, and the guard below
+ * throws on it — the same shape and the same reason as
+ * `paymentCasesRepository.resolve()`. A rule enforced by a flag can be flipped;
+ * a rule enforced by the absence of a code path cannot.
+ *
+ * ## 🛑 The cap is `shippingFee`, NOT the quote — and getting that backwards is easy
+ *
+ * There is no `selectedShippingQuote` on this branch; its absence is what makes
+ * it this branch. The distinction between the two figures is real:
+ *
+ *   · the QUOTE answers *"did the seller save money against what they told the
+ *     buyer"* — the right basis for the dispatch-time comparison;
+ *   · `shippingFee` answers *"what did the buyer actually hand over"* — the
+ *     right basis for a cap, and the owner's stated one.
+ *
+ * Reading the quote here would be `undefined` and would cap everything at
+ * zero. Conversely, inventing a quote from `shippingFee` on the OTHER branch
+ * would compare a real spend against a number that was never a courier quote,
+ * which is exactly why that branch refuses to do it.
+ *
+ * ## The saving still goes to the buyer, because it is ONE rule for both branches
+ *
+ * A buyer's outcome must not depend on whether a courier picker happened to be
+ * involved in their order.
+ */
+export declare function approveShippingReimbursement(input: ApproveShippingReimbursementInput): Promise<ReconcileShippingResult & {
+    approved: number;
+}>;

package/dist/_internal/server/features/shipping/reimbursement.js

@@ -0,0 +1,223 @@
+/**
+ * The self-shipped postage reimbursement — D45's other half.
+ *
+ * ## Why this is a separate module from `reconcile.ts`
+ *
+ * `reconcileOrderShipping` runs at DISPATCH, on an order that went through the
+ * courier picker, and compares a quote against a declared spend. This runs on
+ * an order with NO quote, is triggered by a seller submitting evidence and then
+ * by an admin approving it, and compares what the buyer paid against an
+ * approved receipt. Different trigger, different inputs, different actor.
+ *
+ * 🛑 But they write the SAME `shippingReconciliation` field, and that is
+ * deliberate: two records of "what shipping actually cost" on one order is the
+ * denormalised-mirror trap (Root Cause #42). Sharing the field also shares the
+ * idempotency key — its presence is what stops a double-approval paying twice,
+ * exactly as it stops a double-dispatch crediting points twice.
+ *
+ * ## The owner's rule, verbatim
+ *
+ * *"If seller ships on their own then they have to upload the receipt of the
+ * shipment with the tracking number so that it is paid to them directly; if
+ * they use our platform's integration (Shiprocket) to place the order, they do
+ * not get the money, the platform keeps it… The seller may set an initial value
+ * of shipping but the only approved amount will be given to them."*
+ *
+ * Plus: reimbursement **capped at what the buyer paid**, and the saving to the
+ * **buyer as points**.
+ *
+ * ## The invariant worth stating
+ *
+ * **The platform nets exactly zero on shipping in every case.**
+ *
+ * | buyer paid | approved receipt | seller gets | buyer gets | platform |
+ * |---|---|---|---|---|
+ * | ₹120 | ₹80  | ₹80  | ₹40 points | **₹0** |
+ * | ₹80  | ₹120 | ₹80  | —          | **₹0** |
+ * | ₹100 | ₹100 | ₹100 | —          | **₹0** |
+ */
+import { orderRepository } from "../../../../features/orders/repository/orders.repository.js";
+import { pointsRepository } from "../../../../features/points/repository/points.repository.js";
+import { reconcileShipping, isReimbursableShipment, } from "../../../shared/shipping/quote.js";
+import { serverLogger } from "../../../../monitoring/index.js";
+/**
+ * The seller submits postage evidence on a self-shipped order.
+ *
+ * ## 🛑 It records a CLAIM and moves nothing
+ *
+ * *"The seller may set an initial value of shipping but the only approved
+ * amount will be given to them."* So this writes `declaredAmount` and stops.
+ * The entitlement is `approvedAmount`, written only once a human has read the
+ * receipt — and they are separate fields rather than one that gets
+ * overwritten, because a seller who claims ₹120 and is approved ₹80 must leave
+ * both figures visible.
+ *
+ * ## 🛑 The platform-booked refusal is about WHO BOOKED, not about evidence
+ *
+ * `isReimbursableShipment` keys on the booking. Gating on "a receipt exists"
+ * would be the exploitable version: a seller could upload a receipt for a
+ * parcel we paid Shiprocket for and be reimbursed for our own spend.
+ *
+ * Refused HERE as well as at approval, so the seller is told at submission
+ * rather than after waiting for a review that could only ever decline. That is
+ * the dead-end shape avoided (Root Cause #56).
+ */
+export async function submitShippingEvidence(input) {
+    const order = await orderRepository.findById(input.orderId);
+    if (!order)
+        return { ok: false, reason: "That order does not exist." };
+    if (!isReimbursableShipment(order)) {
+        return {
+            ok: false,
+            reason: "This parcel was booked and paid for through the platform's courier integration, so there is no postage to reimburse.",
+        };
+    }
+    if (order.shippingReimbursement?.approvedAt) {
+        return { ok: false, reason: "A reimbursement has already been approved on this order." };
+    }
+    if (!Number.isFinite(input.declaredAmount) || input.declaredAmount < 0) {
+        return { ok: false, reason: "The declared postage needs to be a number." };
+    }
+    await orderRepository.update(input.orderId, {
+        shippingReimbursement: {
+            declaredAmount: input.declaredAmount,
+            ...(input.evidenceUrl ? { evidenceUrl: input.evidenceUrl } : {}),
+            ...(input.trackingNumber ? { trackingNumber: input.trackingNumber } : {}),
+            submittedAt: new Date(),
+            /*
+             * No approved values carried forward — there are none, because the
+             * `approvedAt` guard above refuses resubmission after approval. Before
+             * approval a seller may correct their claim freely, which is the right
+             * affordance: the alternative is a support ticket to fix a typo.
+             */
+        },
+    });
+    return { ok: true };
+}
+/**
+ * An admin approves a postage reimbursement.
+ *
+ * ## 🛑 Never automatic, and the ABSENCE of a system path is the enforcement
+ *
+ * This moves money to a seller on the strength of a document somebody has to
+ * look at. There is no overload accepting `"system"`, and the guard below
+ * throws on it — the same shape and the same reason as
+ * `paymentCasesRepository.resolve()`. A rule enforced by a flag can be flipped;
+ * a rule enforced by the absence of a code path cannot.
+ *
+ * ## 🛑 The cap is `shippingFee`, NOT the quote — and getting that backwards is easy
+ *
+ * There is no `selectedShippingQuote` on this branch; its absence is what makes
+ * it this branch. The distinction between the two figures is real:
+ *
+ *   · the QUOTE answers *"did the seller save money against what they told the
+ *     buyer"* — the right basis for the dispatch-time comparison;
+ *   · `shippingFee` answers *"what did the buyer actually hand over"* — the
+ *     right basis for a cap, and the owner's stated one.
+ *
+ * Reading the quote here would be `undefined` and would cap everything at
+ * zero. Conversely, inventing a quote from `shippingFee` on the OTHER branch
+ * would compare a real spend against a number that was never a courier quote,
+ * which is exactly why that branch refuses to do it.
+ *
+ * ## The saving still goes to the buyer, because it is ONE rule for both branches
+ *
+ * A buyer's outcome must not depend on whether a courier picker happened to be
+ * involved in their order.
+ */
+export async function approveShippingReimbursement(input) {
+    const nothing = {
+        outcome: null,
+        sellerAbsorbs: 0,
+        buyerPoints: 0,
+        reimbursable: 0,
+        approved: 0,
+    };
+    if (!input.approvedBy || input.approvedBy === "system") {
+        /*
+         * Thrown, not returned. A caller that ignored an `{ ok: false }` here would
+         * have approved a payout with no human behind it, and that is not a
+         * condition to hand back as data for someone to forget to check.
+         */
+        throw new Error("A shipping reimbursement must be approved by a named admin — there is no system approver.");
+    }
+    const order = await orderRepository.findById(input.orderId);
+    if (!order)
+        return { ...nothing, skipped: "no-quote" };
+    if (!isReimbursableShipment(order)) {
+        return { ...nothing, skipped: "no-quote" };
+    }
+    if (!order.shippingReimbursement) {
+        /*
+         * Its own skip reason rather than a silent zero: "the seller has not
+         * claimed yet" and "we decided nothing is owed" are different facts, and an
+         * operator surface has to be able to tell them apart.
+         */
+        return { ...nothing, skipped: "awaiting-evidence" };
+    }
+    if (order.shippingReconciliation) {
+        return {
+            outcome: null,
+            sellerAbsorbs: order.shippingReconciliation.sellerAbsorbs,
+            buyerPoints: order.shippingReconciliation.buyerPoints,
+            reimbursable: order.shippingReconciliation.reimbursable ?? 0,
+            approved: order.shippingReimbursement.approvedAmount ?? 0,
+            skipped: "already-reconciled",
+        };
+    }
+    const chargedToBuyer = typeof order.shippingFee === "number" && Number.isFinite(order.shippingFee)
+        ? Math.max(0, order.shippingFee)
+        : 0;
+    const spent = Math.max(0, input.approvedAmount);
+    /*
+     * The SAME pure function the quoted branch uses, fed the buyer-paid figure as
+     * the charged rate. One formula, both branches — which is the whole reason
+     * `reimbursable` was added to it rather than computed a second time here
+     * (Root Cause #75).
+     *
+     * The courier ids are a matched sentinel pair so `courierChanged` comes out
+     * false: on a self-shipped order the buyer never chose a courier, so "the
+     * seller changed it" is not a fact that exists.
+     */
+    const result = reconcileShipping({ chargedRate: chargedToBuyer, courierId: "self-shipped" }, { actualRate: spent, courierId: "self-shipped", courierName: "Seller-arranged" });
+    if (result.buyerPoints > 0 && order.userId) {
+        await pointsRepository.append({
+            userId: order.userId,
+            kind: "shipping_saving",
+            amount: result.buyerPoints,
+            orderId: input.orderId,
+            /*
+             * Names both figures. "₹40 points" alone is unexplainable weeks later,
+             * and this string is written once and never re-derived, so it stays true
+             * of the moment it describes.
+             */
+            description: `Shipping saving on ${input.orderId}: you paid ₹${chargedToBuyer} for postage, ` +
+                `the approved cost was ₹${spent}.`,
+        });
+    }
+    await orderRepository.update(input.orderId, {
+        shippingReimbursement: {
+            ...order.shippingReimbursement,
+            approvedAmount: spent,
+            approvedBy: input.approvedBy,
+            approvedAt: new Date(),
+            ...(input.note ? { approvalNote: input.note } : {}),
+        },
+        shippingReconciliation: { ...result, reconciledAt: new Date() },
+    });
+    serverLogger.info("shipping reimbursement approved", {
+        orderId: input.orderId,
+        declared: order.shippingReimbursement.declaredAmount,
+        approved: spent,
+        chargedToBuyer,
+        buyerPoints: result.buyerPoints,
+        approvedBy: input.approvedBy,
+    });
+    return {
+        outcome: result.buyerPoints > 0 ? "credited" : result.sellerAbsorbs > 0 ? "seller-absorbed" : "exact",
+        sellerAbsorbs: result.sellerAbsorbs,
+        buyerPoints: result.buyerPoints,
+        reimbursable: result.reimbursable,
+        approved: spent,
+    };
+}

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

@@ -22,9 +22,24 @@ export interface ResolvedStoreTabs {
 }
 export declare function resolveStoreTabs(storeSlug: string, storeId: string | undefined, settings: SiteSettingsSnapshot): Promise<ResolvedStoreTabs>;
 /**
- * Where the bare `/stores/[slug]` route should land: the first listing-type
- * tab holding anything, else Coupons, else Reviews, else About. `about` is
- * always present in `tabs`, so this never falls through to nothing.
+ * Where the bare `/stores/[slug]` route should land.
+ *
+ * Order: **About when the store has written one**, else the first
+ * listing-type tab holding anything, else Coupons, else Reviews, else About.
+ * `about` is always present in `tabs`, so this never falls through to nothing.
+ *
+ * 🛑 About was promoted to first on 2026-10-21, deliberately. Previously the
+ * richest listing tab always won, so any stocked store sent every visitor
+ * straight to a filtered product grid — the storefront read as a search
+ * result, and a seller who had written an introduction was the only person who
+ * ever saw it.
+ *
+ * It is gated on the store ACTUALLY having About content rather than applied
+ * unconditionally: landing on an empty About page would be strictly worse than
+ * landing on products, so the old behaviour remains the fallback. The caller
+ * supplies the flag because this module takes a `storeId`, not the document,
+ * and giving it store-shape knowledge it does not otherwise need would make it
+ * a second place that decides what "has an About" means.
  */
-export declare function getDefaultStoreTabPath(storeSlug: string, storeId: string | undefined, settings: SiteSettingsSnapshot): Promise<string>;
+export declare function getDefaultStoreTabPath(storeSlug: string, storeId: string | undefined, settings: SiteSettingsSnapshot, hasAboutContent?: boolean): Promise<string>;
 export {};

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

@@ -114,11 +114,31 @@ export async function resolveStoreTabs(storeSlug, storeId, settings) {
     return { dropdownTabs, tabs, listingCounts, couponsCount, reviewsCount };
 }
 /**
- * Where the bare `/stores/[slug]` route should land: the first listing-type
- * tab holding anything, else Coupons, else Reviews, else About. `about` is
- * always present in `tabs`, so this never falls through to nothing.
+ * Where the bare `/stores/[slug]` route should land.
+ *
+ * Order: **About when the store has written one**, else the first
+ * listing-type tab holding anything, else Coupons, else Reviews, else About.
+ * `about` is always present in `tabs`, so this never falls through to nothing.
+ *
+ * 🛑 About was promoted to first on 2026-10-21, deliberately. Previously the
+ * richest listing tab always won, so any stocked store sent every visitor
+ * straight to a filtered product grid — the storefront read as a search
+ * result, and a seller who had written an introduction was the only person who
+ * ever saw it.
+ *
+ * It is gated on the store ACTUALLY having About content rather than applied
+ * unconditionally: landing on an empty About page would be strictly worse than
+ * landing on products, so the old behaviour remains the fallback. The caller
+ * supplies the flag because this module takes a `storeId`, not the document,
+ * and giving it store-shape knowledge it does not otherwise need would make it
+ * a second place that decides what "has an About" means.
  */
-export async function getDefaultStoreTabPath(storeSlug, storeId, settings) {
+export async function getDefaultStoreTabPath(storeSlug, storeId, settings, hasAboutContent) {
     const { dropdownTabs, tabs } = await resolveStoreTabs(storeSlug, storeId, settings);
+    if (hasAboutContent) {
+        const about = tabs.find((t) => t.value === "about");
+        if (about)
+            return about.href;
+    }
     return (dropdownTabs[0] ?? tabs[0]).href;
 }

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

@@ -19,6 +19,36 @@ interface GatewayInput {
     readonly action?: string;
     readonly [key: string]: unknown;
 }
+/**
+ * Recompute every category and store counter, on demand.
+ *
+ * `countersReconcile` already runs this nightly at 03:00 UTC, which is right
+ * for drift that accumulates on its own and wrong for drift you have just
+ * caused. A seed, a purge or a bulk import leaves the counters wrong
+ * immediately — and a catalogue that reads as empty until tomorrow morning is
+ * not an acceptable gap. Measured 2026-10-21: a demo purge left all 17 stocked
+ * categories reporting zero while their products were filed perfectly.
+ *
+ * 🛑 DELIBERATELY NOT IN `GATEWAY_HANDLERS`, and that is the whole reason it
+ * is defined separately rather than added to the multiplexer.
+ *
+ * The gateway runs at **120s**; this job's scheduled twin runs at **540s** and
+ * needs it — the category pass alone walks 4,699 rows. Behind the gateway the
+ * same handler would silently get a quarter of its budget and time out
+ * part-way, which on a reconciler means it stops after writing SOME counters
+ * and leaves the taxonomy half-corrected, with a 200 and no error.
+ *
+ * That is precisely Root Cause #85: one handler reachable by two entry points
+ * with different ceilings, where nothing at the call site says which one
+ * served it. The rule there was to align the budgets; here they cannot be
+ * aligned without raising the gateway for six unrelated handlers, so the job
+ * stays out of it instead.
+ *
+ * Matching `timeoutSeconds` and `memory` to the scheduled definition is the
+ * same discipline — cron and callable must run under identical limits, or a
+ * job that works nightly fails on demand for reasons no log explains.
+ */
+export declare const countersReconcileNow: import("./types").HttpsFunctionDefinition<void, import("../jobs").CountersReconcileNowResult>;
 export declare const gateway: import("./types").HttpsFunctionDefinition<GatewayInput, unknown>;
-export declare const HTTPS_FUNCTIONS: readonly [import("./types").HttpsFunctionDefinition<void, import("../jobs").AdminAnalyticsResult>, import("./types").HttpsFunctionDefinition<import("../jobs").StoreAnalyticsInput, import("../jobs").StoreAnalyticsResult>, import("./types").HttpsFunctionDefinition<void, import("../jobs").PromotionsCallableResult>, import("./types").HttpsFunctionDefinition<import("../jobs").ListingRequestBody, import("../jobs").ListingResponseBody>, import("./types").HttpsFunctionDefinition<import("../jobs").TriggerEventRaffleInput, import("../jobs").TriggerEventRaffleResult>, import("./types").HttpsFunctionDefinition<import("../jobs").AssignSpinPrizeInput, import("../jobs").AssignSpinPrizeResult>, import("./types").HttpsFunctionDefinition<GatewayInput, unknown>];
+export declare const HTTPS_FUNCTIONS: readonly [import("./types").HttpsFunctionDefinition<void, import("../jobs").AdminAnalyticsResult>, import("./types").HttpsFunctionDefinition<import("../jobs").StoreAnalyticsInput, import("../jobs").StoreAnalyticsResult>, import("./types").HttpsFunctionDefinition<void, import("../jobs").PromotionsCallableResult>, import("./types").HttpsFunctionDefinition<import("../jobs").ListingRequestBody, import("../jobs").ListingResponseBody>, import("./types").HttpsFunctionDefinition<import("../jobs").TriggerEventRaffleInput, import("../jobs").TriggerEventRaffleResult>, import("./types").HttpsFunctionDefinition<import("../jobs").AssignSpinPrizeInput, import("../jobs").AssignSpinPrizeResult>, import("./types").HttpsFunctionDefinition<void, import("../jobs").CountersReconcileNowResult>, import("./types").HttpsFunctionDefinition<GatewayInput, unknown>];
 export {};

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

@@ -9,7 +9,7 @@
  * single URL so callers only manage one env var. It dispatches by the
  * `action` field on the request body.
  */
-import { adminAnalyticsHandler, assignSpinPrizeHandler, listingProcessorHandler, promotionsHandler, storeAnalyticsHandler, triggerEventRaffleHandler, } from "../jobs/handlers/index.js";
+import { adminAnalyticsHandler, assignSpinPrizeHandler, countersReconcileNowHandler, listingProcessorHandler, promotionsHandler, storeAnalyticsHandler, triggerEventRaffleHandler, } from "../jobs/handlers/index.js";
 import { defineFunction } from "./define.js";
 const REGION = "asia-south1";
 // Consumer-specific env var name — chosen at consumer install time, not appkit.
@@ -115,6 +115,56 @@ export const assignSpinPrize = defineFunction({
         secretEnvVar: SECRET_ENV,
     },
 });
+/**
+ * Recompute every category and store counter, on demand.
+ *
+ * `countersReconcile` already runs this nightly at 03:00 UTC, which is right
+ * for drift that accumulates on its own and wrong for drift you have just
+ * caused. A seed, a purge or a bulk import leaves the counters wrong
+ * immediately — and a catalogue that reads as empty until tomorrow morning is
+ * not an acceptable gap. Measured 2026-10-21: a demo purge left all 17 stocked
+ * categories reporting zero while their products were filed perfectly.
+ *
+ * 🛑 DELIBERATELY NOT IN `GATEWAY_HANDLERS`, and that is the whole reason it
+ * is defined separately rather than added to the multiplexer.
+ *
+ * The gateway runs at **120s**; this job's scheduled twin runs at **540s** and
+ * needs it — the category pass alone walks 4,699 rows. Behind the gateway the
+ * same handler would silently get a quarter of its budget and time out
+ * part-way, which on a reconciler means it stops after writing SOME counters
+ * and leaves the taxonomy half-corrected, with a 200 and no error.
+ *
+ * That is precisely Root Cause #85: one handler reachable by two entry points
+ * with different ceilings, where nothing at the call site says which one
+ * served it. The rule there was to align the budgets; here they cannot be
+ * aligned without raising the gateway for six unrelated handlers, so the job
+ * stays out of it instead.
+ *
+ * Matching `timeoutSeconds` and `memory` to the scheduled definition is the
+ * same discipline — cron and callable must run under identical limits, or a
+ * job that works nightly fails on demand for reasons no log explains.
+ */
+export const countersReconcileNow = defineFunction({
+    name: "countersReconcileNow",
+    description: "Recompute category + store counters on demand (after a seed, purge or bulk import).",
+    trigger: { kind: "https" },
+    handler: countersReconcileNowHandler,
+    options: {
+        region: REGION,
+        /* Identical to the `countersReconcile` schedule — see above. */
+        timeoutSeconds: 540,
+        memory: "256MiB",
+        /*
+         * 🛑 ONE instance. Two concurrent reconciles read the same products and
+         * write the same counters, so the loser's writes land on top of a tally
+         * computed from a different snapshot. The scheduled twin is also
+         * `maxInstances: 1`.
+         */
+        maxInstances: 1,
+        cors: false,
+        secretEnvVar: SECRET_ENV,
+    },
+});
 const GATEWAY_HANDLERS = {
     listingProcessor: listingProcessorHandler,
     adminAnalytics: adminAnalyticsHandler,
@@ -158,5 +208,6 @@ export const HTTPS_FUNCTIONS = [
     listingProcessor,
     triggerEventRaffle,
     assignSpinPrize,
+    countersReconcileNow,
     gateway,
 ];