@mohasinac/appkit 4.14.0 → 4.16.0

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

@@ -2,13 +2,13 @@
 import { wrapAction } from "@mohasinac/appkit/server";
 import { bidRepository, productRepository, userRepository, siteSettingsRepository } from "../../../../repositories";
 import { requireRoleUser } from "../../../../providers/auth-firebase/helpers";
-import { placeBidSchema } from "../../../shared/features/auctions/schema";
+import { placeBidActionSchema } from "../../../shared/features/auctions/schema";
 import { assertAuctionActive, assertBidAmount, assertNotAuctionOwner, shouldAutoExtend, computeExtendedEndDate, } from "./service";
 import { ValidationError } from "../../../shared/errors/index";
 export async function placeBidAction(input) {
     return wrapAction(async () => {
         const user = await requireRoleUser(["buyer", "seller", "admin"]);
-        const parsed = placeBidSchema.safeParse(input);
+        const parsed = placeBidActionSchema.safeParse(input);
         if (!parsed.success)
             throw new ValidationError(parsed.error.issues[0]?.message ?? "Invalid bid input");
         const { auctionId, amount } = parsed.data;

package/dist/_internal/server/features/cart/service.d.ts

@@ -1,8 +1,8 @@
 import type { z } from "zod";
 import type { addToCartSchema } from "../../../shared/features/cart/schema";
-type AddToCartInput = z.infer<typeof addToCartSchema>;
+type AddToCartActionInput = z.infer<typeof addToCartSchema>;
 export declare function assertCartCapacity(userId: string, addingQty: number): Promise<void>;
 export declare function assertValidQuantity(quantity: number): void;
-export declare function upsertCartItem(userId: string, item: AddToCartInput): Promise<void>;
-export declare function mergeGuestItems(userId: string, guestItems: AddToCartInput[]): Promise<void>;
+export declare function upsertCartItem(userId: string, item: AddToCartActionInput): Promise<void>;
+export declare function mergeGuestItems(userId: string, guestItems: AddToCartActionInput[]): Promise<void>;
 export {};

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

@@ -1,4 +1,5 @@
 import { normalizeError } from "../../../../errors/normalize";
+import { buildOrderSourceContext } from "./source-context";
 import { roundRupees } from "../../../../utils/number.formatter";
 /**
  * Checkout server actions (appkit).
@@ -488,6 +489,10 @@ async function createOrderForGroup(group, orderType, ctx) {
     const displayedUpiId = hasPaymentWindow
         ? await resolveDisplayedUpiId(firstItem.storeId, siteContactUpiVpa)
         : undefined;
+    // Both creation paths call the SAME builder — two hand-written copies is the
+    // create-vs-create axis of Root Cause #39, and these two functions have
+    // already drifted once before (add-on fees, Root Cause #65).
+    const sourceContext = await buildOrderSourceContext(firstItem, firstProduct, orderType);
     const order = await unitOfWork.orders.create({
         productId: firstItem.productId,
         productTitle: firstItem.productTitle,
@@ -502,6 +507,11 @@ async function createOrderForGroup(group, orderType, ctx) {
         storeName: firstItem.storeName || undefined,
         items: orderItems,
         orderType,
+        // How the buyer earned the right to buy at this price. `orderType` cannot
+        // answer that — it has five values, and both a settled win and a buyout
+        // are "auction". Written ONCE here and never recomputed: the auction and
+        // offer documents it summarises are mutable and eventually archived.
+        sourceContext,
         offerId: firstItem.offerId ?? undefined,
         // Distinguishes a Buy Now purchase from a settled auction win. Both are
         // orderType "auction"; only this one gets the 24h admin-review window.
@@ -1204,6 +1214,10 @@ async function createRazorpayGroupOrder(group, orderType, ctx) {
     const extraOrderFields = {
         ...groupRuleRzp.decorateOrderDoc(group[0].item, group[0].product),
     };
+    // Both creation paths call the SAME builder — two hand-written copies is the
+    // create-vs-create axis of Root Cause #39, and these two functions have
+    // already drifted once before (add-on fees, Root Cause #65).
+    const sourceContext = await buildOrderSourceContext(firstItem, group[0].product, orderType);
     const order = await unitOfWork.orders.create({
         productId: firstItem.productId,
         productTitle: firstItem.productTitle,
@@ -1218,6 +1232,11 @@ async function createRazorpayGroupOrder(group, orderType, ctx) {
         storeName: firstItem.storeName || undefined,
         items: orderItems,
         orderType,
+        // How the buyer earned the right to buy at this price. `orderType` cannot
+        // answer that — it has five values, and both a settled win and a buyout
+        // are "auction". Written ONCE here and never recomputed: the auction and
+        // offer documents it summarises are mutable and eventually archived.
+        sourceContext,
         offerId: firstItem.offerId ?? undefined,
         // Distinguishes a Buy Now purchase from a settled auction win. Both are
         // orderType "auction"; only this one gets the 24h admin-review window.

package/dist/_internal/server/features/checkout/source-context.d.ts

@@ -0,0 +1,5 @@
+import type { CartItemDocument } from "../../../../features/cart/schemas/firestore";
+import type { ProductDocument } from "../../../../features/products/schemas/firestore";
+import type { OrderSourceContext } from "../../../../features/orders/schemas/firestore";
+import type { OrderType } from "../../../../features/orders/utils/order-splitter";
+export declare function buildOrderSourceContext(item: CartItemDocument, product: ProductDocument, orderType: OrderType): Promise<OrderSourceContext | undefined>;

package/dist/_internal/server/features/checkout/source-context.js

@@ -0,0 +1,157 @@
+/*
+ * WHY: An order records WHAT was bought and WHAT it cost, and nothing about how
+ *      the buyer earned the right to buy it at that price. `orderType` has five
+ *      values and cannot even separate "won at ₹4,200 against 11 bids" from
+ *      "bought out at ₹6,000 while the standing bid was ₹3,800" — both land as
+ *      `orderType: "auction"`. Everything else was recoverable only by reading
+ *      the auction or offer document, which is mutable and eventually archived.
+ * WHAT: `buildOrderSourceContext()` — the ONE builder for `OrderSourceContext`,
+ *       called by both order-creation paths (manual/COD and Razorpay).
+ *
+ * ## Why one shared function and not two inline blocks
+ *
+ * `createOrderForGroup` and `createRazorpayGroupOrder` are near-identical
+ * ~200-line twins that already drifted once on add-on fees (Root Cause #65).
+ * Two hand-written copies of this would be the create-vs-create axis of Root
+ * Cause #39: one lane records provenance, the other silently doesn't, and the
+ * difference is invisible until someone compares two orders months later.
+ *
+ * ## Written once, never recomputed
+ *
+ * These numbers describe a moment. `product.price` moves, `currentBid` is a
+ * mirror that a pending buyout deliberately never writes to, and a settled
+ * auction is eventually archived. Recomputing later would silently rewrite
+ * history, so nothing outside order creation may write this field.
+ *
+ * ## Read cost
+ *
+ * Standard, pre-order and prize-draw cost **zero** extra reads — everything
+ * comes from the product already in hand. Only the auction and offer lanes pay:
+ * one `findByProductSorted` for auctions (bid count, winner, runner-up, the
+ * standing bid — all four from one query) and one `findById` for offers. Since
+ * a checkout is single-lane by construction, a standard cart never pays either.
+ *
+ * ## Failure is non-fatal, deliberately
+ *
+ * A missing bid or offer document returns `undefined` rather than throwing. The
+ * money path must not fail because a provenance record could not be assembled —
+ * an order with no `sourceContext` is a thinner record; a checkout that 500s
+ * after payment authorisation is a support ticket.
+ *
+ * EXPORTS:
+ *   buildOrderSourceContext
+ *
+ * @tag domain:checkout,orders
+ * @tag layer:server-feature
+ * @tag pattern:none
+ * @tag access:server
+ * @tag consumers:checkout/actions.ts
+ * @tag sideEffects:firestore-read
+ */
+import { bidRepository } from "../../../../features/auctions/repository/bid.repository";
+import { offerRepository } from "../../../../features/seller/repository/offer.repository";
+import { normalizeError } from "../../../../errors/normalize";
+import { serverLogger } from "../../../../monitoring";
+/** Bids that count toward "against N bidders" — a buyout is excluded. */
+function competitiveBids(bids) {
+    return bids.filter((b) => !b.isBuyout).sort((a, b) => b.bidAmount - a.bidAmount);
+}
+export async function buildOrderSourceContext(item, product, orderType) {
+    try {
+        // The offer lane is checked BEFORE orderType, because an accepted offer on
+        // a standard listing arrives as orderType "offer" but an accepted offer on
+        // a classified does not — the cart line's own `offerId` is the reliable
+        // discriminator, exactly as `laneOf()` treats it.
+        if (item.offerId) {
+            const offer = await offerRepository.findById(item.offerId);
+            if (!offer)
+                return undefined;
+            return {
+                path: "offer-accepted",
+                offerId: offer.id,
+                offeredAmount: offer.offerAmount,
+                listPriceAtOffer: offer.listedPrice,
+                counterAmount: offer.counterAmount,
+                // Persisted since W2. Before the chain fields existed this number was
+                // genuinely unknowable — each counter created an unlinked document.
+                counterRounds: offer.counterRound ?? 1,
+                acceptedBy: offer.storeId,
+                acceptedAt: offer.acceptedAt ?? offer.respondedAt ?? new Date(),
+                checkoutDeadline: offer.checkoutDeadline,
+            };
+        }
+        if (item.bidId) {
+            const bids = await bidRepository.findByProductSorted(item.productId);
+            const rivals = competitiveBids(bids);
+            const auctionId = item.auctionId ?? item.productId;
+            if (item.isBuyout) {
+                return {
+                    path: "auction-buy-now",
+                    auctionId,
+                    bidId: item.bidId,
+                    buyNowPrice: item.lockedPrice ?? product.buyNowPrice ?? item.price,
+                    listPrice: product.price,
+                    // From the bids, not `product.currentBid` — a pending buyout never
+                    // writes that mirror, so reading it would understate the auction.
+                    standingBidAtBuyout: rivals[0]?.bidAmount ?? 0,
+                    bidCount: rivals.length,
+                    boughtAt: new Date(),
+                    checkoutDeadline: item.checkoutDeadline ?? new Date(),
+                    auctionEndDate: product.auctionEndDate,
+                };
+            }
+            const winning = bids.find((b) => b.id === item.bidId);
+            const winningAmount = winning?.bidAmount ?? item.lockedPrice ?? item.price;
+            const reserve = product.reservePrice;
+            return {
+                path: "auction-won",
+                auctionId,
+                bidId: item.bidId,
+                winningBidAmount: winningAmount,
+                bidCount: rivals.length,
+                startingBid: product.startingBid ?? 0,
+                reservePrice: reserve,
+                // No reserve set means the reserve cannot fail, so it is met.
+                reserveMet: reserve == null ? true : winningAmount >= reserve,
+                auctionEndedAt: product.auctionEndDate ?? new Date(),
+                runnerUpAmount: rivals.find((b) => b.id !== item.bidId)?.bidAmount,
+            };
+        }
+        if (orderType === "preorder") {
+            const deposit = product.preOrderDepositAmount ??
+                (product.preOrderDepositPercent != null
+                    ? (product.price * product.preOrderDepositPercent) / 100
+                    : 0);
+            return {
+                path: "pre-order",
+                depositAmount: deposit,
+                balanceDue: Math.max(0, product.price - deposit),
+                expectedDeliveryDate: product.preOrderDeliveryDate,
+            };
+        }
+        if (orderType === "prize-draw") {
+            return {
+                path: "prize-draw",
+                prizeDrawProductId: item.productId,
+                pricePerEntry: product.pricePerEntry ?? product.price,
+                entryCount: item.quantity,
+                // `prizeDrawMode` is reveal-vs-lottery, a different axis. The reveal
+                // TIMING is what this records: a draw with a reveal window is
+                // scheduled, one without reveals as soon as it sells out.
+                revealMode: product.prizeRevealWindowEnd ? "scheduled" : "instant",
+            };
+        }
+        return { path: "standard", listPrice: product.price };
+    }
+    catch (err) {
+        const normalized = normalizeError(err);
+        // Non-fatal by design — see the header. Logged loudly so a systematic
+        // failure shows up as a pattern rather than as quietly thinner orders.
+        serverLogger.warn("[checkout] could not build sourceContext", {
+            productId: item.productId,
+            orderType,
+            error: normalized.message,
+        });
+        return undefined;
+    }
+}

package/dist/_internal/server/features/offers/adapters.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Offer document → API shape.
+ *
+ * Offers had **no adapter at all** before this: all three routes
+ * (`/api/user/offers`, `/api/store/offers`, `/api/admin/offers`) returned raw
+ * `OfferDocument`s straight from the repository, carrying live `Date`
+ * objects. `UserOffersPanel.relativeTime` still has a defensive
+ * `date instanceof Date ? … : new Date(…)` branch precisely because the shape
+ * it receives depends on whether the value survived JSON serialisation.
+ *
+ * Mirrors `orders/adapters.ts`, including its `toIsoOrUndefined` helper.
+ */
+import type { OfferDocument } from "../../../../features/seller/schemas";
+import type { FieldChange } from "../../../shared/history/index";
+/** One entry on an offer's timeline — dates as ISO, ready for JSON. */
+export interface OfferTimelineEntry {
+    at: string;
+    actorUid?: string;
+    actorRole: "buyer" | "seller" | "admin" | "system";
+    changes: Record<string, FieldChange>;
+    reason?: string;
+    note?: string;
+    trigger: string;
+}
+/** One round of a negotiation, as rendered in the chain rail. */
+export interface OfferChainRound {
+    id: string;
+    counterRound: number;
+    status: OfferDocument["status"];
+    offerAmount: number;
+    counterAmount?: number;
+    /**
+     * `withdrawn` + a `supersededByOfferId` is NOT a walk-away — the buyer
+     * countered. The timeline renders it neutral ("Superseded") rather than
+     * negative ("Withdrawn"), which is why this flag is carried explicitly
+     * instead of being re-derived in the component.
+     */
+    superseded: boolean;
+    createdAt: string;
+    respondedAt?: string;
+    sellerNote?: string;
+    buyerNote?: string;
+}
+export interface Offer {
+    id: string;
+    productId: string;
+    productTitle: string;
+    productSlug?: string;
+    productImageUrl?: string;
+    storeId: string;
+    storeName: string;
+    offerAmount: number;
+    listedPrice: number;
+    counterAmount?: number;
+    lockedPrice?: number;
+    currency: string;
+    status: OfferDocument["status"];
+    buyerNote?: string;
+    sellerNote?: string;
+    expiresAt: string;
+    acceptedAt?: string;
+    checkoutDeadline?: string;
+    respondedAt?: string;
+    paidOrderId?: string;
+    paidAt?: string;
+    createdAt: string;
+    updatedAt: string;
+    timeline?: OfferTimelineEntry[];
+    timelineTruncated?: number;
+    previousOfferId?: string;
+    supersededByOfferId?: string;
+    chainRootOfferId?: string;
+    counterRound?: number;
+    /** True when this round was superseded by the buyer's own counter. */
+    superseded: boolean;
+    cancelledByAdminUid?: string;
+    cancelReason?: string;
+    buyerUid?: string;
+    buyerName?: string;
+    buyerEmail?: string;
+}
+export interface OfferAdapterOptions {
+    /**
+     * Include `buyerUid`/`buyerName`/`buyerEmail`.
+     *
+     * Default **false**, deliberately. The seller-facing route masks buyer
+     * identity, and a route that forgot to call `maskOfferForSeller` would
+     * previously have shipped it verbatim — there was no adapter to stop it.
+     * Making the omission the default means forgetting the flag under-shares
+     * rather than leaks.
+     */
+    includeBuyerIdentity?: boolean;
+}
+export declare function offerDocumentToOffer(doc: OfferDocument, opts?: OfferAdapterOptions): Offer;
+/**
+ * A chain round — the compact shape the timeline needs, without re-sending
+ * the whole document for every round.
+ *
+ * Buyer identity is never included: the chain is rendered on all three
+ * portals from one component, and the seller's view must not gain identity
+ * it is masked from elsewhere.
+ */
+export declare function offerToChainRound(doc: OfferDocument): OfferChainRound;

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

@@ -0,0 +1,88 @@
+/**
+ * Offer document → API shape.
+ *
+ * Offers had **no adapter at all** before this: all three routes
+ * (`/api/user/offers`, `/api/store/offers`, `/api/admin/offers`) returned raw
+ * `OfferDocument`s straight from the repository, carrying live `Date`
+ * objects. `UserOffersPanel.relativeTime` still has a defensive
+ * `date instanceof Date ? … : new Date(…)` branch precisely because the shape
+ * it receives depends on whether the value survived JSON serialisation.
+ *
+ * Mirrors `orders/adapters.ts`, including its `toIsoOrUndefined` helper.
+ */
+function toIsoOrUndefined(value) {
+    return value instanceof Date ? value.toISOString() : undefined;
+}
+function toIso(value) {
+    return value instanceof Date ? value.toISOString() : String(value);
+}
+export function offerDocumentToOffer(doc, opts = {}) {
+    const superseded = doc.status === "withdrawn" && Boolean(doc.supersededByOfferId);
+    return {
+        id: doc.id,
+        productId: doc.productId,
+        productTitle: doc.productTitle,
+        productSlug: doc.productSlug,
+        productImageUrl: doc.productImageUrl,
+        storeId: doc.storeId,
+        storeName: doc.storeName,
+        offerAmount: doc.offerAmount,
+        listedPrice: doc.listedPrice,
+        counterAmount: doc.counterAmount,
+        lockedPrice: doc.lockedPrice,
+        currency: doc.currency,
+        status: doc.status,
+        buyerNote: doc.buyerNote,
+        sellerNote: doc.sellerNote,
+        expiresAt: toIso(doc.expiresAt),
+        acceptedAt: toIsoOrUndefined(doc.acceptedAt),
+        checkoutDeadline: toIsoOrUndefined(doc.checkoutDeadline),
+        respondedAt: toIsoOrUndefined(doc.respondedAt),
+        paidOrderId: doc.paidOrderId,
+        paidAt: toIsoOrUndefined(doc.paidAt),
+        createdAt: toIso(doc.createdAt),
+        updatedAt: toIso(doc.updatedAt),
+        timeline: doc.statusHistory?.map((entry) => ({
+            at: entry.at instanceof Date ? entry.at.toISOString() : String(entry.at),
+            actorUid: entry.actorUid,
+            actorRole: entry.actorRole,
+            changes: entry.changes,
+            reason: entry.reason,
+            note: entry.note,
+            trigger: entry.trigger,
+        })),
+        timelineTruncated: doc.statusHistoryTruncated,
+        previousOfferId: doc.previousOfferId,
+        supersededByOfferId: doc.supersededByOfferId,
+        chainRootOfferId: doc.chainRootOfferId,
+        counterRound: doc.counterRound,
+        superseded,
+        cancelledByAdminUid: doc.cancelledByAdminUid,
+        cancelReason: doc.cancelReason,
+        ...(opts.includeBuyerIdentity
+            ? { buyerUid: doc.buyerUid, buyerName: doc.buyerName, buyerEmail: doc.buyerEmail }
+            : {}),
+    };
+}
+/**
+ * A chain round — the compact shape the timeline needs, without re-sending
+ * the whole document for every round.
+ *
+ * Buyer identity is never included: the chain is rendered on all three
+ * portals from one component, and the seller's view must not gain identity
+ * it is masked from elsewhere.
+ */
+export function offerToChainRound(doc) {
+    return {
+        id: doc.id,
+        counterRound: doc.counterRound ?? 1,
+        status: doc.status,
+        offerAmount: doc.offerAmount,
+        counterAmount: doc.counterAmount,
+        superseded: doc.status === "withdrawn" && Boolean(doc.supersededByOfferId),
+        createdAt: toIso(doc.createdAt),
+        respondedAt: toIsoOrUndefined(doc.respondedAt),
+        sellerNote: doc.sellerNote,
+        buyerNote: doc.buyerNote,
+    };
+}

package/dist/_internal/server/features/offers/index.d.ts

@@ -0,0 +1,2 @@
+export { offerDocumentToOffer, offerToChainRound, } from "./adapters";
+export type { Offer, OfferAdapterOptions, OfferChainRound, OfferTimelineEntry, } from "./adapters";

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

@@ -0,0 +1 @@
+export { offerDocumentToOffer, offerToChainRound, } from "./adapters";

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

@@ -104,6 +104,30 @@ export function orderDocumentToOrder(doc) {
         paymentReviewOutcome: doc.paymentReviewOutcome,
         paymentReviewNote: doc.paymentReviewNote,
         cancellationReason: doc.cancellationReason,
+        // ── W2: history + provenance ──────────────────────────────────────────
+        //
+        // `Order.timeline` has existed, been exported, and had ZERO writers since
+        // it was declared — `OrderStatusTimeline` synthesised its steps from four
+        // scalar dates instead, so a status change with no dedicated date field
+        // (payment reviewed, refund posted) was simply invisible.
+        //
+        // `statusHistory` is that field's real source. Dates are serialised to
+        // ISO here for the same reason every other date on this shape is: the
+        // client receives JSON, and a raw `Date` arrives as a string that no
+        // longer satisfies the type.
+        timeline: doc.statusHistory?.map((entry) => ({
+            at: entry.at instanceof Date ? entry.at.toISOString() : String(entry.at),
+            actorUid: entry.actorUid,
+            actorRole: entry.actorRole,
+            changes: entry.changes,
+            reason: entry.reason,
+            note: entry.note,
+            trigger: entry.trigger,
+        })),
+        /** Entries trimmed off the front — so the UI never implies "this is all of it". */
+        timelineTruncated: doc.statusHistoryTruncated,
+        /** How the buyer acquired the right to buy. Written once, at creation. */
+        sourceContext: doc.sourceContext,
         createdAt: doc.createdAt instanceof Date
             ? doc.createdAt.toISOString()
             : String(doc.createdAt),

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

@@ -21,10 +21,10 @@ export async function runOfferExpiry(ctx) {
     else {
         ctx.logger.info(`Found ${expiredOffers.length} expired offer(s) to process`);
     }
-    const expiredIds = [];
+    const expired = [];
     for (const offer of expiredOffers) {
         try {
-            expiredIds.push(offer.id);
+            expired.push(offer);
             await sendNotification({
                 userId: offer.buyerUid,
                 type: "offer_expired",
@@ -42,9 +42,9 @@ export async function runOfferExpiry(ctx) {
             });
         }
     }
-    if (expiredIds.length > 0) {
+    if (expired.length > 0) {
         try {
-            await offerRepository.expireMany(expiredIds);
+            await offerRepository.expireMany(expired, { trigger: "runOfferExpiry:active" });
         }
         catch (err) {
             ctx.logger.error("Failed to batch-expire offers", err);
@@ -54,8 +54,8 @@ export async function runOfferExpiry(ctx) {
     await expireAcceptedPastCheckoutDeadline(ctx);
     await lapseUnpaidAuctionWins(ctx);
     ctx.logger.info("Offer expiry complete", {
-        processed: expiredIds.length,
-        skipped: expiredOffers.length - expiredIds.length,
+        processed: expired.length,
+        skipped: expiredOffers.length - expired.length,
     });
 }
 /**
@@ -81,14 +81,14 @@ async function expireAcceptedPastCheckoutDeadline(ctx) {
     if (stale.length === 0)
         return;
     ctx.logger.info(`Found ${stale.length} accepted offer(s) past their checkout deadline`);
-    const ids = [];
+    const lapsed = [];
     for (const offer of stale) {
         try {
             // Drop the locked cart line first — leaving it behind would keep the
             // buyer's offer lane non-empty and block their standard checkout on an
             // offer they can no longer act on.
             await cartRepository.removeItemsByOfferId(offer.buyerUid, offer.id);
-            ids.push(offer.id);
+            lapsed.push(offer);
             await sendNotification({
                 userId: offer.buyerUid,
                 type: "offer_expired",
@@ -106,9 +106,9 @@ async function expireAcceptedPastCheckoutDeadline(ctx) {
             });
         }
     }
-    if (ids.length > 0) {
+    if (lapsed.length > 0) {
         try {
-            await offerRepository.expireMany(ids);
+            await offerRepository.expireMany(lapsed, { trigger: "runOfferExpiry:acceptedLapsed" });
         }
         catch (err) {
             void normalizeError(err);

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

@@ -25,6 +25,7 @@
 import type { UserRole } from "../../../features/auth/types";
 import type { ListingType } from "../../../features/products/types/index";
 import type { CategoryType } from "../../../features/categories/types/index";
+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. */
@@ -63,8 +64,14 @@ export interface ActionDef {
     listingTypeScope?: readonly ListingType[];
     /** Category-type scope — same but for category discriminators. */
     categoryTypeScope?: readonly CategoryType[];
-    /** Optional icon name (resolved by the consumer's icon set). */
-    iconKey?: string;
+    /**
+     * Icon for this action, resolved through `ICONS` in `ui/icons/icon-registry`.
+     *
+     * Typed `IconKey`, not `string`: as a bare string this field was set on 2 of
+     * 220 actions and rendered by nothing for months, and a typo was a silent
+     * no-op. A key outside the registry is now a compile error.
+     */
+    iconKey?: IconKey;
     /** Optional confirmation modal config. */
     confirmation?: ActionConfirmation;
 }