@mohasinac/appkit 4.70.0 → 4.71.2

package/dist/_internal/server/features/giveaway/metadata.d.ts

@@ -0,0 +1,6 @@
+import type { Metadata } from "next";
+import type { GiveawayEventClient } from "./data";
+export declare function buildGiveawayMetadata(event: GiveawayEventClient | null, opts?: {
+    siteName?: string;
+    baseUrl?: string;
+}): Metadata;

package/dist/_internal/server/features/giveaway/metadata.js

@@ -0,0 +1,31 @@
+export function buildGiveawayMetadata(event, opts) {
+    if (!event) {
+        return {
+            title: "Giveaway Not Found",
+            description: "This giveaway no longer exists.",
+        };
+    }
+    const siteName = opts?.siteName ?? "the platform";
+    const title = `${event.title} — ${siteName} Giveaway`;
+    const description = typeof event.description === "string" && event.description.length > 0
+        ? event.description.slice(0, 155)
+        : `Enter the ${event.title} giveaway on ${siteName}.`;
+    const coverUrl = event.coverImage && typeof event.coverImage.url === "string"
+        ? event.coverImage.url
+        : event.coverImageUrl;
+    return {
+        title,
+        description,
+        openGraph: {
+            title,
+            description,
+            ...(coverUrl ? { images: [{ url: coverUrl }] } : {}),
+        },
+        twitter: {
+            card: "summary_large_image",
+            title,
+            description,
+            ...(coverUrl ? { images: [coverUrl] } : {}),
+        },
+    };
+}

package/dist/_internal/server/features/giveaway/og.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Giveaway OG image renderer.
+ *
+ * ## Why this did not exist
+ *
+ * `giveaway/[id]` was the single entry in `verify-og-coverage`'s
+ * `OG_KNOWN_GAPS` — the one public dynamic detail page shipping without an
+ * `opengraph-image.tsx`, carried as a baseline since 2026-05-23 with the note
+ * "OG image follows in a follow-up". Metadata already resolved
+ * (`buildGiveawayMetadata`), so a shared link rendered a title and whatever the
+ * event's cover image happened to be, with none of the branded card every
+ * other listing type gets.
+ *
+ * ## 🛑 No money, and no per-slot prices
+ *
+ * An OG image is a public image URL with its contents burned into the pixels:
+ * no sign-in gate reaches it and no paywall markup describes it, which is why
+ * all eight money-bearing renderers were stripped (Root Cause #93). A giveaway
+ * is the sharpest case in the codebase — `toClientGiveawayConfig` is an
+ * allow-list that exists specifically to keep `price` and `weight` off every
+ * slot — so this renderer takes the CLIENT shape and reads only what that
+ * allow-list already permits: the slot count, and how many are still free.
+ *
+ * "6 of 200 slots left" is a fact about availability rather than a disclosed
+ * amount, and it is the half of the card that earns the click — exactly the
+ * line `renderClearanceOg` draws for "Free entry".
+ */
+import type { ReactElement } from "react";
+import type { GiveawayEventClient } from "./data";
+export interface GiveawayOgData {
+    title: string;
+    imageUrl?: string | null;
+    slotsLabel?: string | null;
+    statusLabel?: string | null;
+}
+export declare function renderGiveawayOg(event: GiveawayEventClient | null | undefined, opts: {
+    siteName: string;
+    baseUrl?: string;
+}): ReactElement;
+export declare function renderGiveawayOgImage(data: GiveawayOgData, siteName: string): ReactElement;

package/dist/_internal/server/features/giveaway/og.js

@@ -0,0 +1,79 @@
+/**
+ * Giveaway OG image renderer.
+ *
+ * ## Why this did not exist
+ *
+ * `giveaway/[id]` was the single entry in `verify-og-coverage`'s
+ * `OG_KNOWN_GAPS` — the one public dynamic detail page shipping without an
+ * `opengraph-image.tsx`, carried as a baseline since 2026-05-23 with the note
+ * "OG image follows in a follow-up". Metadata already resolved
+ * (`buildGiveawayMetadata`), so a shared link rendered a title and whatever the
+ * event's cover image happened to be, with none of the branded card every
+ * other listing type gets.
+ *
+ * ## 🛑 No money, and no per-slot prices
+ *
+ * An OG image is a public image URL with its contents burned into the pixels:
+ * no sign-in gate reaches it and no paywall markup describes it, which is why
+ * all eight money-bearing renderers were stripped (Root Cause #93). A giveaway
+ * is the sharpest case in the codebase — `toClientGiveawayConfig` is an
+ * allow-list that exists specifically to keep `price` and `weight` off every
+ * slot — so this renderer takes the CLIENT shape and reads only what that
+ * allow-list already permits: the slot count, and how many are still free.
+ *
+ * "6 of 200 slots left" is a fact about availability rather than a disclosed
+ * amount, and it is the half of the card that earns the click — exactly the
+ * line `renderClearanceOg` draws for "Free entry".
+ */
+import { renderOgLayout } from "../seo/og-layout.js";
+import { resolveOgImageUrl } from "../seo/og.js";
+/**
+ * The event's own status, as a human badge. `active` is deliberately absent:
+ * a live giveaway is the default case, so a chip saying so costs a badge slot
+ * and tells the reader nothing they would not assume.
+ */
+const STATUS_BADGE_TEXT = {
+    draft: "Not yet open",
+    paused: "Paused",
+    ended: "Closed",
+    cancelled: "Cancelled",
+};
+export function renderGiveawayOg(event, opts) {
+    const cfg = event?.giveawayConfig;
+    const slots = cfg?.slots ?? [];
+    /*
+     * Counted from the slot array rather than read from `totalSlots`, which is
+     * the mirror the admin write path derives FROM `slots.length` — and a mirror
+     * is the field most likely to disagree (Root Cause #42). The array is here
+     * either way, so counting it costs nothing.
+     */
+    const total = slots.length;
+    const free = slots.filter((s) => !s.isBooked).length;
+    const slotsLabel = total > 0
+        ? free > 0
+            ? `${free.toLocaleString("en-IN")} of ${total.toLocaleString("en-IN")} slots left`
+            : `All ${total.toLocaleString("en-IN")} slots claimed`
+        : null;
+    const coverUrl = event?.coverImage && typeof event.coverImage.url === "string"
+        ? event.coverImage.url
+        : (event?.coverImageUrl ?? null);
+    return renderGiveawayOgImage({
+        title: event?.title ?? "Giveaway",
+        imageUrl: resolveOgImageUrl(coverUrl, opts.baseUrl),
+        slotsLabel,
+        statusLabel: event?.status ? (STATUS_BADGE_TEXT[event.status] ?? null) : null,
+    }, opts.siteName);
+}
+export function renderGiveawayOgImage(data, siteName) {
+    const badges = [data.statusLabel].filter((s) => Boolean(s));
+    return renderOgLayout({
+        title: data.title,
+        subtitle: data.slotsLabel ?? undefined,
+        imageUrl: data.imageUrl,
+        siteName: `${siteName} · Giveaway`,
+        badges: badges.length > 0 ? badges : undefined,
+        // Violet, distinct from the prize-draw amber beside it in the nav — the two
+        // are different products and a shared accent makes shared links ambiguous.
+        theme: { accentColor: "#8b5cf6" },
+    });
+}

package/dist/_internal/server/features/homepage/index.js

@@ -3,6 +3,6 @@
 // live homepage is `MarketplaceHomepageView`, which reads its repositories
 // directly — and the only part worth keeping, the feature-flag gate, moved to
 // `_internal/shared/features/homepage/section-gate.ts` and is now actually
-// applied. The rest was a Rule #6 liability: `findActiveAuctions()` /
+// applied. The rest was a Rule #6 liability: `findActiveCollectorDrops()` /
 // `findActivePreOrders()` were unbounded `.get()` collection scans.
 export { HOMEPAGE_FEATURED_REVIEWS_LIMIT, HOMEPAGE_RECENT_BLOG_POSTS_LIMIT, HOMEPAGE_MAX_SECTIONS, } from "../../../shared/features/homepage/config.js";

package/dist/_internal/server/features/inventory/reservations.d.ts

@@ -52,7 +52,7 @@ export interface ReserveStockInput {
  *
  * 🛑 Refuses rather than over-reserving. A seller's stock is a real number of
  * real objects, so "reserve 5, only 3 left" is a **409** — the request is
- * well-formed and the world moved, which is the same distinction the lottery
+ * well-formed and the world moved, which is the same distinction the giveaway
  * config write makes for a slot somebody has already pulled.
  */
 export declare function reserveStock(input: ReserveStockInput): Promise<string>;

package/dist/_internal/server/features/inventory/reservations.js

@@ -51,7 +51,7 @@ import { RESERVATION_DEFAULT_TTL_HOURS, RESERVATION_MAX_TTL_HOURS, STOCK_RESERVA
  *
  * 🛑 Refuses rather than over-reserving. A seller's stock is a real number of
  * real objects, so "reserve 5, only 3 left" is a **409** — the request is
- * well-formed and the world moved, which is the same distinction the lottery
+ * well-formed and the world moved, which is the same distinction the giveaway
  * config write makes for a slot somebody has already pulled.
  */
 export async function reserveStock(input) {

package/dist/_internal/server/features/maintenance/cache-admin.d.ts

@@ -0,0 +1,44 @@
+export interface NamedCacheStatus {
+    id: string;
+    label: string;
+    cached: boolean;
+    ageMs: number | null;
+    ttlMs: number | null;
+    expiresInMs: number | null;
+}
+export interface KeyedCacheStatus {
+    id: string;
+    label: string;
+    entryCount: number;
+}
+export interface CacheAdminStatus {
+    named: NamedCacheStatus[];
+    keyed: KeyedCacheStatus[];
+}
+export declare function getCacheAdminStatus(): CacheAdminStatus;
+/**
+ * Item 8 (overhaul brief) — admin-configurable cache TTLs, write side. Only
+ * named sources are overridable today (the two visible in this panel with a
+ * real `ttlMs`) — keyed sources (products) report an entry COUNT, not a
+ * TTL, in `KeyedCacheStatus`, so there is nothing here yet to override.
+ *
+ * Merges into whatever overrides already exist rather than replacing the
+ * whole map, since this writes through the same `updateSingleton()` every
+ * other admin setting uses, and a sibling tab's concurrent save must not
+ * silently drop a cache-TTL change this one just made (or vice versa).
+ *
+ * `minutes < 0` is rejected by the caller's own Zod schema, not here — this
+ * function's job is the merge-and-write, not input validation.
+ */
+export declare function setNamedCacheTtlOverride(id: string, minutes: number): Promise<void>;
+export type CacheClearTarget = {
+    kind: "named";
+    id: string;
+} | {
+    kind: "keyed";
+    id: string;
+} | {
+    kind: "all";
+};
+/** Returns the number of cache entries actually removed. */
+export declare function clearAdminCache(target: CacheClearTarget): number;

package/dist/_internal/server/features/maintenance/cache-admin.js

@@ -0,0 +1,85 @@
+/**
+ * Admin cache status + clear — item 8 §18 (overhaul brief).
+ *
+ * `CacheManager` itself has no notion of "which repositories use it" — that
+ * knowledge is repository-specific, so the two real cache sources (site
+ * settings' 2 fixed named keys, products' dynamic per-id/per-slug prefix) are
+ * named here rather than guessed generically from key strings. A third
+ * repository adopting `CacheManager` later is a one-line addition to
+ * `NAMED_SOURCES`/`KEYED_SOURCES`, not a second hand-written UI section.
+ */
+import { cacheManager } from "../../../../core/CacheManager.js";
+import { siteSettingsRepository } from "../../../../features/admin/repository/site-settings.repository.js";
+import { productRepository } from "../../../../features/products/repository/products.repository.js";
+function namedSources() {
+    const keys = siteSettingsRepository.adminCacheKeys();
+    return [
+        { id: "site-settings-main", label: "Site settings", key: keys.main },
+        { id: "site-settings-flags", label: "Site settings — feature flags", key: keys.flags },
+    ];
+}
+function keyedSources() {
+    return [{ id: "products", label: "Products", prefix: productRepository.cachePrefix() }];
+}
+export function getCacheAdminStatus() {
+    const allKeys = cacheManager.keys();
+    return {
+        named: namedSources().map(({ id, label, key }) => {
+            const meta = cacheManager.getEntryMeta(key);
+            return {
+                id,
+                label,
+                cached: meta !== null,
+                ageMs: meta?.ageMs ?? null,
+                ttlMs: meta?.ttl ?? null,
+                expiresInMs: meta?.expiresInMs ?? null,
+            };
+        }),
+        keyed: keyedSources().map(({ id, label, prefix }) => ({
+            id,
+            label,
+            entryCount: allKeys.filter((k) => k.startsWith(prefix)).length,
+        })),
+    };
+}
+/**
+ * Item 8 (overhaul brief) — admin-configurable cache TTLs, write side. Only
+ * named sources are overridable today (the two visible in this panel with a
+ * real `ttlMs`) — keyed sources (products) report an entry COUNT, not a
+ * TTL, in `KeyedCacheStatus`, so there is nothing here yet to override.
+ *
+ * Merges into whatever overrides already exist rather than replacing the
+ * whole map, since this writes through the same `updateSingleton()` every
+ * other admin setting uses, and a sibling tab's concurrent save must not
+ * silently drop a cache-TTL change this one just made (or vice versa).
+ *
+ * `minutes < 0` is rejected by the caller's own Zod schema, not here — this
+ * function's job is the merge-and-write, not input validation.
+ */
+export async function setNamedCacheTtlOverride(id, minutes) {
+    if (!namedSources().some((s) => s.id === id)) {
+        throw new Error(`"${id}" is not a known named cache source`);
+    }
+    const current = await siteSettingsRepository.getSingleton();
+    await siteSettingsRepository.updateSingleton({
+        cacheTtlOverrideMinutes: { ...current.cacheTtlOverrideMinutes, [id]: minutes },
+    });
+}
+/** Returns the number of cache entries actually removed. */
+export function clearAdminCache(target) {
+    if (target.kind === "all") {
+        const count = cacheManager.keys().length;
+        cacheManager.clear();
+        return count;
+    }
+    if (target.kind === "named") {
+        const source = namedSources().find((s) => s.id === target.id);
+        if (!source)
+            return 0;
+        return cacheManager.delete(source.key) ? 1 : 0;
+    }
+    const source = keyedSources().find((s) => s.id === target.id);
+    if (!source)
+        return 0;
+    return cacheManager.clearByPrefix(source.prefix);
+}

package/dist/_internal/server/features/media/contextGuards.d.ts

@@ -11,13 +11,13 @@
  */
 import { type AllowedMime } from "../../../shared/media/limits";
 import { type MediaFilenameContext } from "../../../../utils/id-generators";
-import type { FirestoreDocument } from "@mohasinac/appkit";
+import type { FirestoreDocument } from "../../../../schemas/types";
 export declare const CONTEXT_LIMITS: {
     readonly PRODUCT_IMAGE_MAX: number;
     readonly PRODUCT_VIDEO_MAX: 1;
     readonly REVIEW_IMAGE_MAX: 5;
     readonly REVIEW_VIDEO_MAX: 1;
-    readonly AUCTION_IMAGE_MAX: number;
+    readonly COLLECTOR_DROP_IMAGE_MAX: number;
     readonly PREORDER_IMAGE_MAX: number;
     readonly EVENT_COVER_MAX: 1;
     readonly EVENT_IMAGE_MAX: 10;

package/dist/_internal/server/features/media/contextGuards.js

@@ -41,14 +41,14 @@ export const CONTEXT_LIMITS = {
      * its 5th image as index 6, so the last slot of every product form was
      * rejected by the signed-URL endpoint.
      *
-     * FLAT across listing types — auctions and pre-orders are products with
+     * FLAT across listing types — collector drops and pre-orders are products with
      * different sale mechanics, not products that deserve fewer photos.
      */
     PRODUCT_IMAGE_MAX: PRODUCT_IMAGE_INDEX_MAX,
     PRODUCT_VIDEO_MAX: PRODUCT_MAX_VIDEOS,
     REVIEW_IMAGE_MAX: 5,
     REVIEW_VIDEO_MAX: 1,
-    AUCTION_IMAGE_MAX: PRODUCT_IMAGE_INDEX_MAX,
+    COLLECTOR_DROP_IMAGE_MAX: PRODUCT_IMAGE_INDEX_MAX,
     PREORDER_IMAGE_MAX: PRODUCT_IMAGE_INDEX_MAX,
     EVENT_COVER_MAX: 1,
     EVENT_IMAGE_MAX: 10,
@@ -159,9 +159,9 @@ function applyMediaContextGuardsInner({ detectedMime, context: ctx, }) {
             error: "review-video context requires a video file",
         };
     }
-    if (ctx.type === "auction-image") {
+    if (ctx.type === "collectordrop-image") {
         const idx = ctx.index ?? 1;
-        const err = indexGuard(idx, CONTEXT_LIMITS.AUCTION_IMAGE_MAX, "Auction image index exceeds max allowed");
+        const err = indexGuard(idx, CONTEXT_LIMITS.COLLECTOR_DROP_IMAGE_MAX, "Collector Drop image index exceeds max allowed");
         if (err)
             return err;
     }

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

@@ -115,6 +115,17 @@ export async function openConversationWithSeller(buyerId, storeId) {
     }
     return createOrOpenConversation(buyerId, store.ownerId);
 }
+/*
+ * 🛑 `openConversationWithAssistant` was REMOVED 2026-10-31 — the customer
+ * assistant feature dropped the shared buyer<->seller inbox as its storage
+ * (owner's instruction) in favour of its own `assistantHistory/{userId}`
+ * document (`_internal/server/features/assistant/history-store.ts`). This
+ * was its only caller. `ASSISTANT_PARTICIPANT_ID` and the `"assistant"`
+ * `ParticipantRole` value are left in place deliberately — removing a type
+ * union member is a wider, unrelated change, and `ConversationsInboxView`'s
+ * label-derivation fix stays correct whether or not that branch is ever
+ * reached again.
+ */
 export async function listConversationsForUser(userId, opts = {}) {
     return conversationsRepository.listForUser(userId, opts);
 }

package/dist/_internal/server/features/order-completion/actions.js

@@ -101,7 +101,7 @@ function orderLinesOf(order) {
      * cancelled or the array is rewritten — and `expandCartLineToOrderRows` fans
      * a grouped line into N rows, so rewrites happen. A rating would then attach
      * to a different product than the one it was written about. That is the
-     * merge-by-index hazard the lottery-slot fix is about, one feature over.
+     * merge-by-index hazard the giveaway-slot fix is about, one feature over.
      *
      * Keyed on `productId` plus an occurrence counter instead: stable under
      * reordering and under the removal of OTHER lines, and only ambiguous if two

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

@@ -56,8 +56,9 @@ export declare function adminRejectPaymentAsFraudAction(orderId: string, note: s
  * might be wrong"). Only valid when `autoApproved === true` — a manually
  * reviewed order already went through human judgment and disputes on it go
  * through the existing return/refund flow instead. Callable by the buyer,
- * the seller (store owner), or admin/moderator. Does not itself reverse
- * payment/order status — surfaces to the admin queue for investigation.
+ * the seller (store owner), or staff holding `admin:orders:write`. Does not
+ * itself reverse payment/order status — surfaces to the admin queue for
+ * investigation.
  */
 export declare function raiseOrderDisputeAction(orderId: string, input: {
     kind: DisputeKind;

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

@@ -12,7 +12,7 @@
  */
 import { wrapAction } from "../../../shared/types/action-result.js";
 import { adminNotificationsRepository, orderRepository, storeRepository } from "../../../../repositories/index.js";
-import { requireRoleUser } from "../../../../providers/auth-firebase/helpers.js";
+import { requireRoleUser, requireAuthUser } from "../../../../providers/auth-firebase/helpers.js";
 import { createOrderSchema, updateOrderStatusSchema, cancelOrderSchema, returnRequestSchema, } from "../../../shared/features/orders/schema.js";
 import { isFinalSaleExempt } from "../../../shared/features/orders/return-reasons.js";
 import { DISPUTE_KIND_LABEL, checkDisputeGate, isDisputeKind, } from "../../../shared/features/orders/dispute-reasons.js";
@@ -22,7 +22,29 @@ import { assertOrderCancellable, assertReturnWindowOpen } from "./service.js";
 import { cancelOrderWithRefund } from "./cancellation-refund.js";
 import { ValidationError } from "../../../shared/errors/index.js";
 import { OrderNotFoundError, OrderOwnershipError } from "../../../shared/features/orders/errors.js";
-import { isAdminUser, isModeratorUser } from "../../../../features/auth/role-predicates.js";
+/*
+ * ── Moderation is a PERMISSION here, not a role ──────────────────────────────
+ *
+ * These gates read `isAdminUser(user) || isModeratorUser(user)` until
+ * 2026-11-08. Collapsing `moderator` into `employee` (A9) made the second half
+ * true for EVERY employee, so the three payment-override actions below —
+ * declare a manual payment received, extend a payment window, cancel an order
+ * and enqueue a 7-day hard ban — widened to every employee account as a side
+ * effect of a role rename.
+ *
+ * Owner's decision: keep the fold, gate the sites on an explicit permission.
+ * So the question asked here is "does this user hold
+ * `admin:orders:payment-override`?" — admin holds it unconditionally
+ * (`permissionsFor` short-circuits), an employee holds it only if GRANTED, and
+ * no role bundle confers it.
+ *
+ * ⚠ `canModerateServer` and not the synchronous `can()`: the per-person grant
+ * lives in `permissions[]` on the user document and never reaches the session
+ * cookie, so the sync form would deny a correctly configured employee.
+ */
+import { isAdminUser } from "../../../../features/auth/role-predicates.js";
+import { canModerateServer } from "../auth/permissions.js";
+import { AuthorizationError } from "../../../../errors/index.js";
 import { sendNotification } from "../../../../features/admin/actions/notification-actions.js";
 import { restoreStockForOrder } from "../checkout/stock-restore.js";
 import { getAdminDb } from "../../../../providers/db-firebase/index.js";
@@ -37,6 +59,7 @@ import { PAYMENT_WINDOW_MS, PAYMENT_FRAUD_REJECTED_REASON, isManualPaymentMethod
 import { deadlinesFor } from "../../../shared/obligations/deadlines.js";
 import { normalizeError } from "../../../../errors/normalize.js";
 import { serverLogger } from "../../../../monitoring/index.js";
+import { formatMoney } from "../../../../utils/number.formatter.js";
 export async function createOrderAction(input) {
     return wrapAction(async () => {
         const user = await requireRoleUser(["user", "buyer", "seller", "admin"]);
@@ -181,7 +204,7 @@ function notifyAdminsOfPaymentProof(order) {
             await adminNotificationsRepository.create({
                 category: "payouts",
                 title: "Payment proof awaiting review",
-                body: `${order.userName} uploaded proof for "${order.productTitle}" (₹${order.totalPrice.toLocaleString("en-IN")}). Review before the 2-hour auto-approve window closes.`,
+                body: `${order.userName} uploaded proof for "${order.productTitle}" (${formatMoney(order.totalPrice)}). Review before the 2-hour auto-approve window closes.`,
                 severity: "warning",
                 isRead: false,
                 entityType: "order",
@@ -263,9 +286,16 @@ export async function attachPaymentProofAction(orderId, proof) {
 }
 export async function adminVerifyPaymentAction(orderId) {
     return wrapAction(async () => {
-        const user = await requireRoleUser(["admin", "moderator"]);
-        if (!isAdminUser(user) && !isModeratorUser(user)) {
-            throw new ValidationError("Only admin or moderator can verify payments");
+        /*
+         * Authenticate, then ask the capability question — no role literal at all.
+         * `requireRoleUser(["admin","moderator"])` used to stand here, which matched
+         * the SCALAR `role` claim on the session cookie: it refused a real employee
+         * outright and admitted anyone whose stale cookie still said "moderator".
+         * The permission check below reads the live document instead.
+         */
+        const user = await requireAuthUser();
+        if (!(await canModerateServer(user.uid, "orders:payment-override"))) {
+            throw new AuthorizationError("Verifying a payment requires the admin:orders:payment-override permission");
         }
         const order = await orderRepository.findById(orderId);
         if (!order)
@@ -300,9 +330,9 @@ export async function adminVerifyPaymentAction(orderId) {
  */
 export async function adminRequestProofReuploadAction(orderId, note) {
     return wrapAction(async () => {
-        const user = await requireRoleUser(["admin", "moderator"]);
-        if (!isAdminUser(user) && !isModeratorUser(user)) {
-            throw new ValidationError("Only admin or moderator can request a proof re-upload");
+        const user = await requireAuthUser();
+        if (!(await canModerateServer(user.uid, "orders:payment-override"))) {
+            throw new AuthorizationError("Requesting a proof re-upload requires the admin:orders:payment-override permission");
         }
         if (!note.trim())
             throw new ValidationError(REASON_REQUIRED_MSG);
@@ -349,9 +379,9 @@ export async function adminRequestProofReuploadAction(orderId, note) {
  */
 export async function adminRejectPaymentAsFraudAction(orderId, note) {
     return wrapAction(async () => {
-        const user = await requireRoleUser(["admin", "moderator"]);
-        if (!isAdminUser(user) && !isModeratorUser(user)) {
-            throw new ValidationError("Only admin or moderator can reject a payment as fraudulent");
+        const user = await requireAuthUser();
+        if (!(await canModerateServer(user.uid, "orders:payment-override"))) {
+            throw new AuthorizationError("Rejecting a payment as fraudulent requires the admin:orders:payment-override permission");
         }
         if (!note.trim())
             throw new ValidationError(REASON_REQUIRED_MSG);
@@ -389,12 +419,21 @@ export async function adminRejectPaymentAsFraudAction(orderId, note) {
  * might be wrong"). Only valid when `autoApproved === true` — a manually
  * reviewed order already went through human judgment and disputes on it go
  * through the existing return/refund flow instead. Callable by the buyer,
- * the seller (store owner), or admin/moderator. Does not itself reverse
- * payment/order status — surfaces to the admin queue for investigation.
+ * the seller (store owner), or staff holding `admin:orders:write`. Does not
+ * itself reverse payment/order status — surfaces to the admin queue for
+ * investigation.
  */
 export async function raiseOrderDisputeAction(orderId, input) {
     return wrapAction(async () => {
-        const user = await requireRoleUser(["user", "buyer", "seller", "admin"]);
+        /*
+         * `requireAuthUser`, not `requireRoleUser([...])`. The tuple here listed
+         * user/buyer/seller/admin and matched the scalar `role` claim, so an
+         * employee granted `admin:orders:write` was refused before the real gate
+         * below ever ran — a half-converted gate in the worst direction. Who may
+         * act is decided by ownership-or-permission a few lines down, which is the
+         * one place that should know.
+         */
+        const user = await requireAuthUser();
         if (!isDisputeKind(input.kind))
             throw new ValidationError("Pick what kind of problem this is.");
         if (!input.reasonId?.trim())
@@ -403,12 +442,25 @@ export async function raiseOrderDisputeAction(orderId, input) {
         if (!order)
             throw new OrderNotFoundError(orderId);
         const isBuyer = order.userId === user.uid;
+        /*
+         * ── Ownership first, permission second — and exactly ONCE ───────────────
+         *
+         * Was `!isAdminUser(user) && !isModeratorUser(user)` evaluated twice, with
+         * the moderator half now true for every employee. It is a permission
+         * question (`admin:orders:write` — act on an order you neither bought nor
+         * sold), and the answer needs a document read, so it is computed once and
+         * ONLY when ownership has already failed: a buyer disputing their own
+         * order must not pay a Firestore round-trip to be allowed (Rule #6).
+         */
+        const isStaff = isBuyer
+            ? false
+            : await canModerateServer(user.uid, "orders:act-on-any");
         let isSeller = false;
-        if (!isBuyer && !isAdminUser(user) && !isModeratorUser(user) && order.storeId) {
+        if (!isBuyer && !isStaff && order.storeId) {
             const store = await storeRepository.findById(order.storeId);
             isSeller = store?.ownerId === user.uid;
         }
-        if (!isBuyer && !isSeller && !isAdminUser(user) && !isModeratorUser(user)) {
+        if (!isBuyer && !isSeller && !isStaff) {
             throw new OrderOwnershipError(orderId);
         }
         /*

package/dist/_internal/server/features/orders/adapters.js

@@ -65,12 +65,29 @@ export function orderDocumentToOrder(doc) {
             quantity: item.quantity,
             currency: doc.currency,
             storeId: doc.storeId,
-            // SB8-F — surface prize-draw reveal-state to the API response so
+            // SB8-F — surface clearance reveal-state to the API response so
             // user-orders pages can render the "X reveals pending" badge.
             ...(item.listingType ? { listingType: item.listingType } : {}),
             ...(item.prizeRevealStatus
                 ? { prizeRevealStatus: item.prizeRevealStatus }
                 : {}),
+            /*
+             * The reveal timestamp and the allocation pointer, for the same
+             * Root-Cause-#57 reason as every other snapshot in this mapper: a
+             * field that exists on the document and reaches no client might as
+             * well not exist. Here it is the buyer's own evidence that the pick
+             * was the platform's — withholding it would leave the anti-fraud
+             * trace visible only to the party being audited's adjudicator.
+             */
+            ...(item.revealedAt ? { revealedAt: item.revealedAt } : {}),
+            ...(item.allocationId ? { allocationId: item.allocationId } : {}),
+            /*
+             * Manual-release state. `releasedBy` is deliberately NOT forwarded —
+             * which staff member released a code is operational, not the buyer's
+             * business, and the audit log already holds it.
+             */
+            ...(item.fulfilmentState ? { fulfilmentState: item.fulfilmentState } : {}),
+            ...(item.releasedAt ? { releasedAt: item.releasedAt } : {}),
             ...(item.cancelledQuantity != null
                 ? { cancelledQuantity: item.cancelledQuantity }
                 : {}),
@@ -164,8 +181,8 @@ export function orderDocumentToOrder(doc) {
         address,
         orderStatus: doc.status,
         paymentStatus: doc.paymentStatus,
-        // Which checkout lane produced this order (standard / auction / offer /
-        // preorder / prize-draw). Drives the lane tabs on /user/orders. Absent on
+        // Which checkout lane produced this order (standard / collector drop / offer /
+        // preorder / clearance). Drives the lane tabs on /user/orders. Absent on
         // orders written before `orderType` existed — every reader must treat a
         // missing value as "standard" rather than filtering it out.
         orderType: doc.orderType,
@@ -269,6 +286,24 @@ export function orderDocumentToOrder(doc) {
         supplierGstin: doc.supplierGstin,
         supplierLegalName: doc.supplierLegalName,
         supplierAddress: doc.supplierAddress,
+        /*
+         * 🛑 Root Cause #57, in the one place it is most visible: this adapter
+         * mapped the CGST/SGST/IGST split above and dropped the field that
+         * EXPLAINS it.
+         *
+         * Place of supply is what decides whether a supply is intra-State
+         * (CGST+SGST) or inter-State (IGST). Without it the HTML invoice showed a
+         * split it could not justify — and the PDF, which reads the raw
+         * `OrderDocument` rather than going through here, printed the line
+         * correctly. So the two invoices for ONE order disagreed on a Rule 46(n)
+         * field, and the buyer-facing one was the deficient half.
+         *
+         * Nothing was wrong with the data: `createOrderForGroup` has always
+         * written it. It simply never crossed the client boundary, which is why
+         * the gap reads as "this order has no place of supply" rather than as a
+         * dropped field.
+         */
+        placeOfSupply: doc.placeOfSupply,
         codHandlingFee: doc.codHandlingFee,
         trackingNumber: doc.trackingNumber,
         shippingCarrier: doc.shippingCarrier,

package/dist/_internal/server/features/orders/balance.d.ts

@@ -66,9 +66,12 @@ export declare function balanceDueOn(order: OrderDocument): number | null;
  * only — so every seller got a 403 before reaching this function at all. A
  * broken gate masked an absent one, exactly as in Root Cause #98.
  */
-export declare function openBalanceCollection(orderId: string, actor: {
+export declare function openBalanceCollection(orderId: string, 
+/** `roles` is the authority; `role` stays accepted for un-normalised callers. */
+actor: {
     uid: string;
-    role: string;
+    role?: string;
+    roles?: readonly string[] | null;
 }, now?: Date): Promise<OrderDocument>;
 /**
  * The buyer submits a proof.