@mohasinac/appkit 4.59.0 → 4.60.1

package/dist/_internal/server/jobs/core/weeklyPayoutEligibility.js

@@ -6,13 +6,36 @@ import { storeRepository, userRepository, orderRepository, payoutRepository, sit
 import { BATCH_LIMIT } from "../handlers/messages.js";
 import { getDefaultCurrency } from "../../../../core/index.js";
 import { computePayoutDeduction } from "../../../shared/fees/calculator.js";
-import { ordersTaxableValue } from "../../../shared/checkout/order-math.js";
+import { payoutCutoff } from "../../../shared/fees/payout-hold.js";
+import { PROTECTION_CLAIM_WINDOW_HOURS } from "../../../shared/features/shipping/protections.js";
+import { ordersTaxableValue, ordersShippingReimbursement, } from "../../../shared/checkout/order-math.js";
 export async function runWeeklyPayoutEligibility(ctx) {
     // `FEATURE_PAYOUTS` gate deleted 2026-10-19 — see `autoPayoutEligibility.ts`.
-    ctx.logger.info("Starting weekly payout eligibility sweep");
     const siteSettings = await siteSettingsRepository.getSingleton();
     const commissions = siteSettings.commissions;
-    const eligible = await orderRepository.getEligibleForPayoutSweep();
+    /*
+     * 🛑 This sweep used to call `getEligibleForPayoutSweep()`, which filtered
+     * on `payoutStatus == "eligible" && status == "delivered"` and **nothing
+     * else** — no time cutoff of any kind. So every Saturday it paid out orders
+     * delivered the day before, which made the 7-day hold in the sibling daily
+     * job unreachable as a floor: whatever that one withheld, this one released.
+     *
+     * It now consumes the SAME `payoutCutoff` the daily sweep does. Two sweeps
+     * with two predicates is how one intended hold ended up honoured by neither.
+     */
+    const { cutoff, hold } = payoutCutoff({
+        payoutHoldDays: commissions?.payoutHoldDays,
+        returnWindowDays: siteSettings.returns?.windowDays,
+        maxClaimWindowHours: Math.max(PROTECTION_CLAIM_WINDOW_HOURS.shipping, PROTECTION_CLAIM_WINDOW_HOURS.sale),
+    }, { onWarn: (m, meta) => ctx.logger.warn(m, meta) });
+    ctx.logger.info("Starting weekly payout eligibility sweep", {
+        holdDays: hold.days,
+        holdSource: hold.source,
+        cutoff: cutoff.toISOString(),
+    });
+    const eligible = await orderRepository.getEligibleAutomatic(cutoff, {
+        onWarn: (m, meta) => ctx.logger.warn(m, meta),
+    });
     if (eligible.length === 0) {
         ctx.logger.info("No eligible delivered orders found");
         return { payoutsCreated: 0, ordersProcessed: 0, payoutIds: [] };
@@ -44,7 +67,15 @@ export async function runWeeklyPayoutEligibility(ctx) {
          * `autoPayoutEligibility` must agree, or the weekly run and the automatic
          * one pay different amounts for the same orders. */
         const grossAmount = ordersTaxableValue(orders.map((o) => o.data));
-        const { platformFee, gatewayFee, gstOnFee, netAmount } = computePayoutDeduction(grossAmount, commissions);
+        const { platformFee, gatewayFee, gstOnFee, netAmount } = computePayoutDeduction(grossAmount, commissions, 
+        /*
+         * D45 — postage refunded to the seller, added AFTER the fee bases so no
+         * commission is charged on a cost being refunded. `.data` for the same
+         * reason `ordersTaxableValue` above needs it: `orders` holds
+         * `{ id, data }` wrappers, and passing the wrapper would read every field
+         * as undefined and silently reimburse zero.
+         */
+        ordersShippingReimbursement(orders.map((o) => o.data)));
         /*
          * 🛑 REVEALED before building a payout — see the identical note in
          * `autoPayoutEligibility.ts`. `findById` is ciphertext-by-default and

package/dist/_internal/server/jobs/handlers/boxRollupReconcile.d.ts

@@ -0,0 +1,2 @@
+import type { ScheduleHandler } from "../runtime/types";
+export declare const boxRollupReconcileHandler: ScheduleHandler;

package/dist/_internal/server/jobs/handlers/boxRollupReconcile.js

@@ -0,0 +1,15 @@
+import { runBoxRollupReconcile } from "../core/boxRollupReconcile.js";
+/*
+ * 🛑 Wrapped rather than assigned directly. `ScheduleHandler` is
+ * `(ctx) => Promise<void>` and `runBoxRollupReconcile` resolves to a
+ * `BoxRollupReconcileResult`, which is NOT assignable — TypeScript's
+ * return-type `void` exemption covers `() => void`, where any return value is
+ * discardable, but it does not reach through `Promise<T>` to `Promise<void>`.
+ *
+ * The result is deliberately still returned by the core function: the
+ * scheduler has no use for it, but a manual trigger does, and the job already
+ * logs `drifted` itself so nothing is lost by dropping it here.
+ */
+export const boxRollupReconcileHandler = async (ctx) => {
+    await runBoxRollupReconcile(ctx);
+};

package/dist/_internal/server/jobs/handlers/countersReconcileNow.d.ts

@@ -0,0 +1,65 @@
+import type { CallableHandler } from "../runtime/types";
+/**
+ * What an on-demand reconcile reports back to its caller.
+ *
+ * `degraded` is the point of this type. See the handler.
+ */
+export interface CountersReconcileNowResult {
+    categoryRows: number;
+    publishedProductsScanned: number;
+    drifted: number;
+    written: number;
+    countsWritten: number;
+    unknownCategory: number;
+    storesProcessed: number;
+    storeErrors: number;
+    /**
+     * `true` when drift was found and nothing was written — the signature of a
+     * run that did no work while reporting completion. See the handler.
+     */
+    degraded: boolean;
+    ranForMs: number;
+}
+/**
+ * Run the counters reconciliation on demand and RETURN what it did.
+ *
+ * ## Why this exists at all
+ *
+ * `countersReconcile` already runs daily at 03:00 UTC, and that is the right
+ * cadence for drift that accumulates on its own. It is the wrong cadence for
+ * drift you have just CAUSED: seeding a collection, purging demo data, or a
+ * bulk import all leave the counters wrong immediately, and waiting until the
+ * next night means the catalogue reads as empty until then.
+ *
+ * Measured 2026-10-21: a demo purge left all 17 stocked categories reading
+ * `total=0` while their products were filed correctly — `category-beyblade-x`
+ * stored 0 against an actual 14. Nothing errored, because a wrong count is
+ * just a number; the only symptom is a human seeing an empty category.
+ *
+ * ## 🛑 Why it returns a summary instead of void
+ *
+ * The scheduled handler returns `void` and reports through logs, which is
+ * fine for a cron nobody watches. An on-demand run has a caller waiting on an
+ * answer, and the failure that matters here is SILENT: `runCountersReconcile`
+ * catches its own category and store errors and still logs
+ * "Counters reconciliation complete". Driving it standalone produced exactly
+ * that — `processed: 0, errors: 1`, then "complete" — three times in a row
+ * while writing nothing, because `ctx.db` was missing.
+ *
+ * So the one thing this must never do is answer 200-with-success for a run
+ * that wrote nothing. `drifted > 0 && written === 0` is that signature, and
+ * it is surfaced as `degraded` rather than buried in a log line. A caller
+ * that sees `degraded: true` has been told the run failed even though it
+ * completed.
+ *
+ * ## Why it wraps the logger rather than changing the core
+ *
+ * `runCountersReconcile` already emits its own counts as structured metadata
+ * on two "reconciliation complete" lines. Reading those is enough, and leaves
+ * the scheduled path byte-identical — one implementation, two entry points,
+ * which is the shape the Functions registry is for. Changing the core's
+ * signature to return a summary would mean the cron and the callable run
+ * different code, and the whole reason this bug was findable is that they do
+ * not.
+ */
+export declare const countersReconcileNowHandler: CallableHandler<void, CountersReconcileNowResult>;

package/dist/_internal/server/jobs/handlers/countersReconcileNow.js

@@ -0,0 +1,89 @@
+import { runCountersReconcile } from "../core/countersReconcile.js";
+const num = (m, k) => typeof m?.[k] === "number" ? m[k] : 0;
+/**
+ * Run the counters reconciliation on demand and RETURN what it did.
+ *
+ * ## Why this exists at all
+ *
+ * `countersReconcile` already runs daily at 03:00 UTC, and that is the right
+ * cadence for drift that accumulates on its own. It is the wrong cadence for
+ * drift you have just CAUSED: seeding a collection, purging demo data, or a
+ * bulk import all leave the counters wrong immediately, and waiting until the
+ * next night means the catalogue reads as empty until then.
+ *
+ * Measured 2026-10-21: a demo purge left all 17 stocked categories reading
+ * `total=0` while their products were filed correctly — `category-beyblade-x`
+ * stored 0 against an actual 14. Nothing errored, because a wrong count is
+ * just a number; the only symptom is a human seeing an empty category.
+ *
+ * ## 🛑 Why it returns a summary instead of void
+ *
+ * The scheduled handler returns `void` and reports through logs, which is
+ * fine for a cron nobody watches. An on-demand run has a caller waiting on an
+ * answer, and the failure that matters here is SILENT: `runCountersReconcile`
+ * catches its own category and store errors and still logs
+ * "Counters reconciliation complete". Driving it standalone produced exactly
+ * that — `processed: 0, errors: 1`, then "complete" — three times in a row
+ * while writing nothing, because `ctx.db` was missing.
+ *
+ * So the one thing this must never do is answer 200-with-success for a run
+ * that wrote nothing. `drifted > 0 && written === 0` is that signature, and
+ * it is surfaced as `degraded` rather than buried in a log line. A caller
+ * that sees `degraded: true` has been told the run failed even though it
+ * completed.
+ *
+ * ## Why it wraps the logger rather than changing the core
+ *
+ * `runCountersReconcile` already emits its own counts as structured metadata
+ * on two "reconciliation complete" lines. Reading those is enough, and leaves
+ * the scheduled path byte-identical — one implementation, two entry points,
+ * which is the shape the Functions registry is for. Changing the core's
+ * signature to return a summary would mean the cron and the callable run
+ * different code, and the whole reason this bug was findable is that they do
+ * not.
+ */
+export const countersReconcileNowHandler = async (_input, ctx) => {
+    const startedAt = Date.now();
+    let categories;
+    let stores;
+    /*
+     * A pass-through logger: everything still reaches the real one, so the
+     * Function's logs are unchanged and this cannot swallow a message.
+     */
+    const capturing = {
+        info: (msg, meta) => {
+            if (msg.includes("[categories] reconciliation complete"))
+                categories = meta;
+            if (msg.includes("[stores] reconciliation complete"))
+                stores = meta;
+            ctx.logger.info(msg, meta);
+        },
+        warn: (msg, meta) => ctx.logger.warn(msg, meta),
+        error: (msg, err, meta) => ctx.logger.error(msg, err, meta),
+    };
+    await runCountersReconcile({ ...ctx, logger: capturing });
+    const drifted = num(categories, "drifted");
+    const written = num(categories, "written");
+    const result = {
+        categoryRows: num(categories, "categoryRows"),
+        publishedProductsScanned: num(categories, "publishedProductsScanned"),
+        drifted,
+        written,
+        countsWritten: num(categories, "countsWritten"),
+        unknownCategory: num(categories, "unknownCategory"),
+        storesProcessed: num(stores, "processed"),
+        storeErrors: num(stores, "errors"),
+        /*
+         * 🛑 Also degraded when the category pass reported NOTHING. A missing
+         * summary means `reconcileCategories` threw before its final log line --
+         * which `runCountersReconcile` catches and continues past, so the run
+         * still "completes" with zero evidence it did anything.
+         */
+        degraded: (drifted > 0 && written === 0) || categories === undefined,
+        ranForMs: Date.now() - startedAt,
+    };
+    if (result.degraded) {
+        ctx.logger.error("[countersReconcileNow] completed but wrote nothing against observed drift — treat as FAILED", undefined, { ...result });
+    }
+    return result;
+};

package/dist/_internal/server/jobs/handlers/index.d.ts

@@ -16,6 +16,9 @@ export { cleanupRtdbEventsHandler } from "./cleanupRtdbEvents";
 export { auctionSettlementHandler } from "./auctionSettlement";
 export { autoPayoutEligibilityHandler } from "./autoPayoutEligibility";
 export { countersReconcileHandler } from "./countersReconcile";
+export { paymentReconcileHandler } from "./paymentReconcile";
+export { obligationSweepHandler } from "./obligationSweep";
+export { boxRollupReconcileHandler } from "./boxRollupReconcile";
 export { onOrderCreateHandler } from "./onOrderCreate";
 export { onOrderStatusChangeHandler } from "./onOrderStatusChange";
 export { onJobCreatedHandler } from "./onJobCreated";
@@ -29,6 +32,7 @@ export { paymentReviewAutoApproveHandler } from "./paymentReviewAutoApprove";
 export { productStatsSyncHandler } from "./productStatsSync";
 export { revenueRollupHandler } from "./revenueRollup";
 export { priceIndexRollupHandler } from "./priceIndexRollup";
+export { marketPriceRollupHandler } from "./marketPriceRollup";
 export { searchIndexBuildHandler } from "./searchIndexBuild";
 export { analyticsAlertEvaluateHandler } from "./analyticsAlertEvaluate";
 export { pageViewRollupHandler } from "./pageViewRollup";
@@ -40,6 +44,7 @@ export { onCategoryWriteHandler } from "./onCategoryWrite";
 export { onProductWriteHandler } from "./onProductWrite";
 export { onStoreWriteHandler } from "./onStoreWrite";
 export { adminAnalyticsHandler, type AdminAnalyticsResult } from "./adminAnalytics";
+export { countersReconcileNowHandler, type CountersReconcileNowResult, } from "./countersReconcileNow";
 export { storeAnalyticsHandler, type StoreAnalyticsInput, type StoreAnalyticsResult, } from "./storeAnalytics";
 export { listingProcessorHandler, supportedListingCollections, type ListingRequestBody, type ListingResponseBody, } from "./listingProcessor";
 export { bundleStockSyncHandler } from "./bundleStockSync";

package/dist/_internal/server/jobs/handlers/index.js

@@ -16,6 +16,9 @@ export { cleanupRtdbEventsHandler } from "./cleanupRtdbEvents.js";
 export { auctionSettlementHandler } from "./auctionSettlement.js";
 export { autoPayoutEligibilityHandler } from "./autoPayoutEligibility.js";
 export { countersReconcileHandler } from "./countersReconcile.js";
+export { paymentReconcileHandler } from "./paymentReconcile.js";
+export { obligationSweepHandler } from "./obligationSweep.js";
+export { boxRollupReconcileHandler } from "./boxRollupReconcile.js";
 export { onOrderCreateHandler } from "./onOrderCreate.js";
 export { onOrderStatusChangeHandler } from "./onOrderStatusChange.js";
 export { onJobCreatedHandler } from "./onJobCreated.js";
@@ -29,6 +32,7 @@ export { paymentReviewAutoApproveHandler } from "./paymentReviewAutoApprove.js";
 export { productStatsSyncHandler } from "./productStatsSync.js";
 export { revenueRollupHandler } from "./revenueRollup.js";
 export { priceIndexRollupHandler } from "./priceIndexRollup.js";
+export { marketPriceRollupHandler } from "./marketPriceRollup.js";
 export { searchIndexBuildHandler } from "./searchIndexBuild.js";
 export { analyticsAlertEvaluateHandler } from "./analyticsAlertEvaluate.js";
 export { pageViewRollupHandler } from "./pageViewRollup.js";
@@ -40,6 +44,7 @@ export { onCategoryWriteHandler } from "./onCategoryWrite.js";
 export { onProductWriteHandler } from "./onProductWrite.js";
 export { onStoreWriteHandler } from "./onStoreWrite.js";
 export { adminAnalyticsHandler } from "./adminAnalytics.js";
+export { countersReconcileNowHandler, } from "./countersReconcileNow.js";
 export { storeAnalyticsHandler, } from "./storeAnalytics.js";
 export { listingProcessorHandler, supportedListingCollections, } from "./listingProcessor.js";
 // SB1-L (S7-PrizeDraws) — bundle sync, event raffles, and spin-the-wheel.

package/dist/_internal/server/jobs/handlers/marketPriceRollup.d.ts

@@ -0,0 +1,2 @@
+import type { ScheduleHandler } from "../runtime/types";
+export declare const marketPriceRollupHandler: ScheduleHandler;

package/dist/_internal/server/jobs/handlers/marketPriceRollup.js

@@ -0,0 +1,2 @@
+import { runMarketPriceRollup } from "../core/marketPriceRollup.js";
+export const marketPriceRollupHandler = runMarketPriceRollup;

package/dist/_internal/server/jobs/handlers/obligationSweep.d.ts

@@ -0,0 +1,2 @@
+import type { ScheduleHandler } from "../runtime/types";
+export declare const obligationSweepHandler: ScheduleHandler;

package/dist/_internal/server/jobs/handlers/obligationSweep.js

@@ -0,0 +1,15 @@
+import { runObligationSweep } from "../core/obligationSweep.js";
+/*
+ * 🛑 Wrapped rather than assigned directly. `ScheduleHandler` is
+ * `(ctx) => Promise<void>` and `runObligationSweep` resolves a RESULT object,
+ * which is not assignable: the return-type `void` exemption covers
+ * `() => void`, where any return value is discardable, but it does not reach
+ * through `Promise<T>` to `Promise<void>`.
+ *
+ * The result stays on the core function deliberately — the scheduler has no
+ * use for it, a manual trigger does, and the job logs its own summary either
+ * way. Same shape as `boxRollupReconcileHandler`.
+ */
+export const obligationSweepHandler = async (ctx) => {
+    await runObligationSweep(ctx);
+};

package/dist/_internal/server/jobs/handlers/onShipmentAllocationSync.js

@@ -1,4 +1,21 @@
 import { allocateShipmentCosts } from "../../../../features/shipments/utils/cost-allocation.js";
+import { siteSettingsRepository } from "../../../../features/admin/repository/site-settings.repository.js";
+/*
+ * ── D58: the admin saw 6 while this used 4 ───────────────────────────────
+ *
+ * 🛑 `siteSettings.laborRate.maxHoursPerDay` is admin-editable and read by
+ * NOTHING (verified: zero readers outside the form, the schema and the seed).
+ * The form's own fallback is **6**; this constant is **4**. So an admin could
+ * set the value, see it persist, and the allocation would keep using a
+ * different number — which is the same class as D13's silent control, with
+ * the extra twist that the two numbers disagreed.
+ *
+ * Now read from settings with this as the FALLBACK, so the admin control is
+ * live and the two cannot diverge. 4 is kept as the fallback rather than 6
+ * because 4 is what every existing allocation was computed with — switching
+ * the default to the form's 6 would silently re-base historical cost figures,
+ * which is worse than the disagreement it fixes.
+ */
 const DEFAULT_MAX_HOURS_PER_DAY = 4;
 /*
  * 🛑 THIS COMPARISON IS LOAD-BEARING. GETTING IT WRONG IS AN INFINITE LOOP THAT
@@ -75,13 +92,25 @@ async function recomputeShipmentAllocation(shipmentId, ctx) {
     // matching what the admin editor's preview also uses.
     const laborRatePerHour = shipment.laborRatePerHour ?? 0;
     const laborHoursSpent = shipment.laborHoursSpent ?? 0;
+    /*
+     * One settings read per allocation. This job is a Firestore trigger on a
+     * single shipment, not a sweep, so the read is bounded — and the
+     * alternative (keep ignoring the admin control) is the defect.
+     */
+    const laborSettings = await siteSettingsRepository
+        .getSingleton()
+        .then((s) => s.laborRate)
+        .catch(() => undefined);
+    const settingsMaxHours = laborSettings?.maxHoursPerDay;
     const { perLot, totals } = allocateShipmentCosts({
         lots: allocationInputs,
         customsTotal: shipment.customsTotal ?? 0,
         shippingTotal: shipment.shippingTotal ?? 0,
         laborHoursSpent,
         laborRatePerHour,
-        maxHoursPerDay: DEFAULT_MAX_HOURS_PER_DAY,
+        maxHoursPerDay: typeof settingsMaxHours === "number" && Number.isFinite(settingsMaxHours) && settingsMaxHours > 0
+            ? settingsMaxHours
+            : DEFAULT_MAX_HOURS_PER_DAY,
     });
     const batch = ctx.db.batch();
     let anyLotChanged = false;

package/dist/_internal/server/jobs/handlers/paymentReconcile.d.ts

@@ -0,0 +1,2 @@
+import type { ScheduleHandler } from "../runtime/types";
+export declare const paymentReconcileHandler: ScheduleHandler;

package/dist/_internal/server/jobs/handlers/paymentReconcile.js

@@ -0,0 +1,6 @@
+import { runPaymentReconcile } from "../core/paymentReconcile.js";
+/* Wrapped for the same reason as `obligationSweepHandler` — see the note
+ * there: a `Promise<Result>` is not assignable to a `Promise<void>` handler. */
+export const paymentReconcileHandler = async (ctx) => {
+    await runPaymentReconcile(ctx);
+};

package/dist/_internal/shared/actions/action-registry.d.ts

@@ -29,7 +29,7 @@ import type { IconKey } from "../../../ui/icons/icon-registry";
 /** What KIND of action — drives default UI affordance (link vs button vs danger). */
 export type ActionKind = "primary" | "secondary" | "danger" | "ghost" | "link" | "chip";
 /** Resource bucket — keyed top-level in the ACTIONS tree. */
-export type ActionResource = "PRODUCT" | "AUCTION" | "PRE_ORDER" | "PRIZE_DRAW" | "DIGITAL_CODE" | "BUNDLE" | "GROUP" | "CATEGORY" | "BRAND" | "PART" | "BEY" | "SUBLISTING" | "STORE" | "BLOG" | "EVENT" | "REVIEW" | "SHIPMENT" | "CATALOGUE" | "USER" | "SELLER" | "ADMIN" | "CART" | "CHECKOUT" | "NAV" | "MEDIA" | "SUPPORT" | "LOTTERY" | "TESTER";
+export type ActionResource = "PRODUCT" | "AUCTION" | "PRE_ORDER" | "PRIZE_DRAW" | "DIGITAL_CODE" | "BUNDLE" | "GROUP" | "CATEGORY" | "BRAND" | "PART" | "BEY" | "FAQ" | "SUBLISTING" | "STORE" | "BLOG" | "EVENT" | "REVIEW" | "SHIPMENT" | "CATALOGUE" | "USER" | "SELLER" | "ADMIN" | "CART" | "CHECKOUT" | "NAV" | "MEDIA" | "SUPPORT" | "LOTTERY" | "TESTER";
 /** Confirmation modal config — when set, <Button action={...}> opens
  *  a confirm dialog before firing the actual handler. */
 export interface ActionConfirmation {

package/dist/_internal/shared/actions/action-registry.js

@@ -483,6 +483,53 @@ export const ACTIONS = {
             },
         },
     },
+    /*
+     * FAQ — a real record with its own `faq-` slug, admin editor and endpoint,
+     * which had no bucket here at all. That absence is what kept the owner
+     * toolbar off every FAQ: `RESOURCE_LEAVES` resolves its labels and confirm
+     * copy through this tree, so a missing bucket is a missing control.
+     */
+    FAQ: {
+        view: {
+            iconKey: "view",
+            id: "faq.view",
+            label: "View",
+            ariaLabel: "View FAQ",
+            description: "Open this question on the help centre.",
+            kind: "secondary",
+        },
+        edit: {
+            iconKey: "edit",
+            id: "faq.edit",
+            label: "Edit",
+            ariaLabel: "Edit FAQ",
+            description: "Correct this question or its answer.",
+            kind: "secondary",
+            permissions: ["admin"],
+        },
+        delete: {
+            iconKey: "delete",
+            id: "faq.delete",
+            label: "Delete",
+            ariaLabel: "Delete FAQ",
+            description: "Remove this question from the help centre.",
+            kind: "danger",
+            permissions: ["admin"],
+            confirmation: {
+                title: "Remove this question from the help centre?",
+                /*
+                 * 🛑 Names the two places it disappears from, because a FAQ is
+                 * surfaced in more than one: `showOnHomepage` and `showInFooter` are
+                 * fields on the document, so deleting one can quietly empty a
+                 * homepage block an admin never associated with this screen.
+                 */
+                body: "It stops appearing in the help centre, and in the homepage and footer blocks if it was " +
+                    "flagged for those. Seeded questions come back on the next reseed — to remove one for " +
+                    "good, take it out of the seed data.",
+                confirmLabel: "Remove",
+            },
+        },
+    },
     BEY: {
         view: {
             iconKey: "view",
@@ -1696,6 +1743,30 @@ export const ACTIONS = {
             kind: "secondary",
             permissions: ["admin"],
         },
+        /**
+         * Credit or debit a buyer's points by hand — `admin_adjustment`'s first
+         * human writer (D48).
+         *
+         * 🛑 `permissions: ["admin"]` only, no moderator. 1 point = ₹1 of spendable
+         * discount, so a credit is a liability the platform must honour and a debit
+         * removes value a buyer already holds. `ban-user` admits a moderator
+         * because a ban is reversible and moves no money; this is neither.
+         *
+         * No `confirmation` block, deliberately — the drawer it opens IS the
+         * confirmation, and it collects three mandatory fields (a signed amount
+         * under `POINTS_ADJUSTMENT_MAX`, a buyer-facing line, and a ≥10-character
+         * internal reason). A confirm dialog in front of a form that already
+         * demands a written justification is a click that asks nothing.
+         */
+        "adjust-user-points": {
+            iconKey: "points",
+            id: "admin.adjust-user-points",
+            label: "Adjust points",
+            ariaLabel: "Credit or debit this user's points",
+            description: "Credit or debit a buyer's points balance, with a reason recorded in the ledger and the admin audit log.",
+            kind: "secondary",
+            permissions: ["admin"],
+        },
         "bulk-suspend-users": {
             iconKey: "ban",
             id: "admin.bulk-suspend-users",

package/dist/_internal/shared/checkout/coupon-discount.d.ts

@@ -0,0 +1,73 @@
+/**
+ * How a buyer-applied coupon splits across the sellers in one cart.
+ *
+ * WHY THIS MOVED HERE (2026-10-21): the implementation was module-private
+ * inside `_internal/server/features/checkout/actions.ts`, where three order
+ * paths could reach it and the **gateway capture route could not**.
+ *
+ * 🛑 So `/api/payment/create-order` — the one place that decides what the
+ * buyer's card is actually charged — had NO COUPON TERM ANYWHERE IN THE FILE.
+ * Measured: zero occurrences of "coupon" or "discount", and
+ *
+ *     rawTotal = subtotalRs + platformFee + gstOnFee + addonFees + shippingFee
+ *
+ * while `createOrderForGroup` (COD/UPI), `previewCheckoutPricing` and
+ * `createRazorpayGroupOrder` all compute `max(0, total − couponDiscount) + …`.
+ *
+ * The consequence is a live overcharge on every coupon order paid by card: the
+ * preview shows ₹X−discount, the gateway captures ₹X, and the order records
+ * ₹X−discount. And it is invisible in our own data, because the post-capture
+ * amount guard is ONE-SIDED (`paid < expected − 1`), so an over-capture never
+ * trips it. Nothing in the system disagreed with itself; only the buyer's card
+ * statement did.
+ *
+ * `_internal/shared/` rather than `_internal/server/` because this is pure
+ * arithmetic with no Firestore reach, and because `_internal/shared` is the
+ * only one of the three a consumer route can be served from. It is the first
+ * increment of the single-pipeline extraction.
+ */
+import type { CartAppliedCoupon } from "../../../features/cart/schemas/firestore";
+export interface GroupCouponDiscountResult {
+    couponDiscount: number;
+    appliedDiscounts: {
+        code: string;
+        couponId?: string;
+        type: "coupon" | "deal" | "auto";
+        discountAmount: number;
+        scope?: "admin" | "seller";
+        storeId?: string;
+    }[];
+}
+/**
+ * Prorates every buyer-applied coupon against one seller-group's total.
+ *
+ * Pure — no side effects. Usage-accumulator bookkeeping is layered on by the
+ * callers that actually place an order, which is what lets the preview and the
+ * capture route call this without recording a redemption.
+ *
+ * A seller-scoped coupon applies only to its own store's group; an admin
+ * coupon prorates across every group by `groupTotal / cartSubtotal`. Clamped
+ * to the group total at the end, so a coupon can never make a group negative.
+ */
+export declare function computeGroupCouponDiscount(appliedCoupons: CartAppliedCoupon[], groupLines: {
+    itemId: string;
+    lineTotal: number;
+}[], groupTotal: number, cartSubtotal: number, storeId: string | undefined): GroupCouponDiscountResult;
+/**
+ * The whole cart's discount, summed over its seller-groups.
+ *
+ * 🛑 This exists so a caller holding only a cart-wide subtotal cannot be
+ * tempted to apply a coupon to it directly. Doing so is wrong in two ways that
+ * cancel out on a single-seller cart and diverge on a multi-seller one: a
+ * seller-scoped coupon would be applied to other sellers' items, and the
+ * per-group clamp (`min(discount, groupTotal)`) would not bind. The capture
+ * route holds exactly that shape, which is how it ended up with no discount at
+ * all rather than a wrong one.
+ */
+export declare function computeCartCouponDiscount(appliedCoupons: CartAppliedCoupon[], groups: {
+    storeId: string | undefined;
+    lines: {
+        itemId: string;
+        lineTotal: number;
+    }[];
+}[]): GroupCouponDiscountResult;

package/dist/_internal/shared/checkout/coupon-discount.js

@@ -0,0 +1,103 @@
+/**
+ * How a buyer-applied coupon splits across the sellers in one cart.
+ *
+ * WHY THIS MOVED HERE (2026-10-21): the implementation was module-private
+ * inside `_internal/server/features/checkout/actions.ts`, where three order
+ * paths could reach it and the **gateway capture route could not**.
+ *
+ * 🛑 So `/api/payment/create-order` — the one place that decides what the
+ * buyer's card is actually charged — had NO COUPON TERM ANYWHERE IN THE FILE.
+ * Measured: zero occurrences of "coupon" or "discount", and
+ *
+ *     rawTotal = subtotalRs + platformFee + gstOnFee + addonFees + shippingFee
+ *
+ * while `createOrderForGroup` (COD/UPI), `previewCheckoutPricing` and
+ * `createRazorpayGroupOrder` all compute `max(0, total − couponDiscount) + …`.
+ *
+ * The consequence is a live overcharge on every coupon order paid by card: the
+ * preview shows ₹X−discount, the gateway captures ₹X, and the order records
+ * ₹X−discount. And it is invisible in our own data, because the post-capture
+ * amount guard is ONE-SIDED (`paid < expected − 1`), so an over-capture never
+ * trips it. Nothing in the system disagreed with itself; only the buyer's card
+ * statement did.
+ *
+ * `_internal/shared/` rather than `_internal/server/` because this is pure
+ * arithmetic with no Firestore reach, and because `_internal/shared` is the
+ * only one of the three a consumer route can be served from. It is the first
+ * increment of the single-pipeline extraction.
+ */
+import { roundRupees } from "../../../utils/number.formatter.js";
+/**
+ * Prorates every buyer-applied coupon against one seller-group's total.
+ *
+ * Pure — no side effects. Usage-accumulator bookkeeping is layered on by the
+ * callers that actually place an order, which is what lets the preview and the
+ * capture route call this without recording a redemption.
+ *
+ * A seller-scoped coupon applies only to its own store's group; an admin
+ * coupon prorates across every group by `groupTotal / cartSubtotal`. Clamped
+ * to the group total at the end, so a coupon can never make a group negative.
+ */
+export function computeGroupCouponDiscount(appliedCoupons, groupLines, groupTotal, cartSubtotal, storeId) {
+    let couponDiscount = 0;
+    const appliedDiscounts = [];
+    for (const coupon of appliedCoupons) {
+        let couponGroupDiscount = 0;
+        const isSellerScoped = coupon.scope === "seller" && coupon.storeId;
+        if (isSellerScoped) {
+            if (coupon.storeId !== storeId)
+                continue;
+            if (coupon.applicableItemIds?.length) {
+                const eligibleTotal = groupLines
+                    .filter((l) => coupon.applicableItemIds.includes(l.itemId))
+                    .reduce((s, l) => s + l.lineTotal, 0);
+                couponGroupDiscount =
+                    eligibleTotal > 0
+                        ? Math.min(roundRupees((eligibleTotal / groupTotal) * coupon.discountAmount), eligibleTotal)
+                        : 0;
+            }
+            else {
+                couponGroupDiscount = Math.min(coupon.discountAmount, groupTotal);
+            }
+        }
+        else if (cartSubtotal > 0) {
+            couponGroupDiscount = Math.min(roundRupees((groupTotal / cartSubtotal) * coupon.discountAmount), groupTotal);
+        }
+        if (couponGroupDiscount > 0) {
+            couponDiscount += couponGroupDiscount;
+            appliedDiscounts.push({
+                code: coupon.code,
+                couponId: coupon.couponId,
+                type: "coupon",
+                discountAmount: couponGroupDiscount,
+                scope: coupon.scope,
+                storeId: coupon.storeId,
+            });
+        }
+    }
+    couponDiscount = Math.min(couponDiscount, groupTotal);
+    return { couponDiscount, appliedDiscounts };
+}
+/**
+ * The whole cart's discount, summed over its seller-groups.
+ *
+ * 🛑 This exists so a caller holding only a cart-wide subtotal cannot be
+ * tempted to apply a coupon to it directly. Doing so is wrong in two ways that
+ * cancel out on a single-seller cart and diverge on a multi-seller one: a
+ * seller-scoped coupon would be applied to other sellers' items, and the
+ * per-group clamp (`min(discount, groupTotal)`) would not bind. The capture
+ * route holds exactly that shape, which is how it ended up with no discount at
+ * all rather than a wrong one.
+ */
+export function computeCartCouponDiscount(appliedCoupons, groups) {
+    const cartSubtotal = groups.reduce((sum, g) => sum + g.lines.reduce((s, l) => s + l.lineTotal, 0), 0);
+    let couponDiscount = 0;
+    const appliedDiscounts = [];
+    for (const group of groups) {
+        const groupTotal = group.lines.reduce((s, l) => s + l.lineTotal, 0);
+        const res = computeGroupCouponDiscount(appliedCoupons, group.lines, groupTotal, cartSubtotal, group.storeId);
+        couponDiscount += res.couponDiscount;
+        appliedDiscounts.push(...res.appliedDiscounts);
+    }
+    return { couponDiscount: roundRupees(couponDiscount), appliedDiscounts };
+}