@mohasinac/appkit 4.23.0 → 4.24.0

package/dist/constants/notification-types.d.ts

@@ -1,18 +1,46 @@
 /**
- * Notification Type Registry — W1-33
+ * Notification Type Registry — DERIVED, not restated.
  *
- * Canonical list of notification type IDs. Shared across:
- *  - AdminNotificationsView filter chips
- *  - NotificationPreferencesPanel (per-type toggles)
- *  - sendNotification() dispatch (type-based channel routing)
+ * ## What this file used to be, and why it mattered
  *
- * Add new types here. Don't redefine the list inline in components.
+ * A hand-written 9-value list that called itself "canonical" while
+ * `NotificationDocument.type` held 27. Two of its nine —`review_posted` and
+ * `payout_processed` — were not real values at all, so those chips matched
+ * zero rows forever. Its two consumers were not cosmetic:
+ *
+ *  · `AdminNotificationsView`'s filter chips, so an admin could not filter
+ *    **18 of the 27 real types** and was offered two that never appear.
+ *  · `AdminSiteSettingsView`'s per-channel allow-list, so an admin literally
+ *    **could not allow-list `offer_received` or `payment_review`** for email
+ *    or WhatsApp — the toggle did not exist.
+ *
+ * Everything here now derives from `NOTIFICATION_TYPE_VALUES`, so a new
+ * notification type is one edit and cannot be missing from either surface.
+ *
+ * ## Why the import points where it does
+ *
+ * `features/admin/schemas/firestore.ts` imports nothing from `constants/`,
+ * so this direction is acyclic. That is NOT true of `field-names.ts`, which
+ * is a deliberate leaf that `features/products/types` imports — which is why
+ * that file keeps its duplicated values and relies on an audit instead.
+ */
+import { NOTIFICATION_TYPE_VALUES } from "../features/admin/schemas/firestore";
+import type { NotificationType } from "../features/admin/schemas/firestore";
+export { NOTIFICATION_TYPE_VALUES };
+export type { NotificationType };
+/** Alias kept for the two existing importers. */
+export declare const NOTIFICATION_TYPES: readonly ["order_placed", "order_confirmed", "order_shipped", "order_delivered", "order_cancelled", "bid_placed", "bid_outbid", "bid_won", "bid_lost", "auction_ended", "review_approved", "review_replied", "product_available", "promotion", "system", "welcome", "account_action", "offer_received", "offer_responded", "offer_expired", "offer_counter_accepted", "refund_initiated", "prize_won", "prize_reveal_expired", "emi_installment_due_soon", "emi_installment_overdue", "payment_review", "catalogue_images_stale"];
+/**
+ * `order_shipped` → `Order shipped`.
+ *
+ * Derived rather than hand-labelled: a hand-written label map is the same
+ * drift risk one layer down, and every one of these values is already a
+ * readable snake_case phrase.
  */
-export declare const NOTIFICATION_TYPES: readonly ["order_placed", "order_shipped", "order_delivered", "order_cancelled", "bid_placed", "bid_outbid", "bid_won", "review_posted", "payout_processed"];
-export type NotificationType = (typeof NOTIFICATION_TYPES)[number];
+export declare function notificationTypeLabel(type: NotificationType | string): string;
 /**
- * Shape used by filter-chip rows (id + display label).
- * Prepended with an "All" option for the typical filter-chip pattern.
+ * Shape used by filter-chip rows (id + display label), with the usual "All"
+ * option prepended.
  */
 export declare const NOTIFICATION_TYPE_TABS: ReadonlyArray<{
     id: string;

package/dist/constants/notification-types.js

@@ -1,37 +1,48 @@
 /**
- * Notification Type Registry — W1-33
+ * Notification Type Registry — DERIVED, not restated.
  *
- * Canonical list of notification type IDs. Shared across:
- *  - AdminNotificationsView filter chips
- *  - NotificationPreferencesPanel (per-type toggles)
- *  - sendNotification() dispatch (type-based channel routing)
+ * ## What this file used to be, and why it mattered
  *
- * Add new types here. Don't redefine the list inline in components.
+ * A hand-written 9-value list that called itself "canonical" while
+ * `NotificationDocument.type` held 27. Two of its nine —`review_posted` and
+ * `payout_processed` — were not real values at all, so those chips matched
+ * zero rows forever. Its two consumers were not cosmetic:
+ *
+ *  · `AdminNotificationsView`'s filter chips, so an admin could not filter
+ *    **18 of the 27 real types** and was offered two that never appear.
+ *  · `AdminSiteSettingsView`'s per-channel allow-list, so an admin literally
+ *    **could not allow-list `offer_received` or `payment_review`** for email
+ *    or WhatsApp — the toggle did not exist.
+ *
+ * Everything here now derives from `NOTIFICATION_TYPE_VALUES`, so a new
+ * notification type is one edit and cannot be missing from either surface.
+ *
+ * ## Why the import points where it does
+ *
+ * `features/admin/schemas/firestore.ts` imports nothing from `constants/`,
+ * so this direction is acyclic. That is NOT true of `field-names.ts`, which
+ * is a deliberate leaf that `features/products/types` imports — which is why
+ * that file keeps its duplicated values and relies on an audit instead.
  */
-export const NOTIFICATION_TYPES = [
-    "order_placed",
-    "order_shipped",
-    "order_delivered",
-    "order_cancelled",
-    "bid_placed",
-    "bid_outbid",
-    "bid_won",
-    "review_posted",
-    "payout_processed",
-];
+import { NOTIFICATION_TYPE_VALUES } from "../features/admin/schemas/firestore";
+export { NOTIFICATION_TYPE_VALUES };
+/** Alias kept for the two existing importers. */
+export const NOTIFICATION_TYPES = NOTIFICATION_TYPE_VALUES;
+/**
+ * `order_shipped` → `Order shipped`.
+ *
+ * Derived rather than hand-labelled: a hand-written label map is the same
+ * drift risk one layer down, and every one of these values is already a
+ * readable snake_case phrase.
+ */
+export function notificationTypeLabel(type) {
+    return String(type).replace(/_/g, " ").replace(/^./, (c) => c.toUpperCase());
+}
 /**
- * Shape used by filter-chip rows (id + display label).
- * Prepended with an "All" option for the typical filter-chip pattern.
+ * Shape used by filter-chip rows (id + display label), with the usual "All"
+ * option prepended.
  */
 export const NOTIFICATION_TYPE_TABS = [
     { id: "All", label: "All" },
-    { id: "order_placed", label: "Order placed" },
-    { id: "order_shipped", label: "Order shipped" },
-    { id: "order_delivered", label: "Order delivered" },
-    { id: "order_cancelled", label: "Order cancelled" },
-    { id: "bid_placed", label: "Bid placed" },
-    { id: "bid_outbid", label: "Bid outbid" },
-    { id: "bid_won", label: "Bid won" },
-    { id: "review_posted", label: "Review posted" },
-    { id: "payout_processed", label: "Payout processed" },
+    ...NOTIFICATION_TYPE_VALUES.map((id) => ({ id, label: notificationTypeLabel(id) })),
 ];

package/dist/features/account/types/index.d.ts

@@ -37,16 +37,7 @@ export interface UserOrder {
     createdAt?: string;
     updatedAt?: string;
 }
-export type NotificationType = "order" | "offer" | "promo" | "system" | "message";
-export interface UserNotification {
-    id: string;
-    title: string;
-    message: string;
-    type: NotificationType;
-    isRead: boolean;
-    createdAt: string;
-    href?: string;
-}
+export type { NotificationType } from "../../admin/schemas/firestore";
 export type OfferStatus = "pending" | "countered" | "accepted" | "paid" | "declined" | "expired" | "withdrawn";
 export interface UserOffer {
     id: string;

package/dist/features/admin/actions/notification-actions.d.ts

@@ -1,4 +1,5 @@
 import type { NotificationDocument, NotificationCreateInput } from "../schemas";
+import { type NotificationAudience } from "../../../_internal/shared/features/notifications/action-url";
 export declare function markNotificationRead(id: string): Promise<void>;
 export declare function markAllNotificationsRead(userId: string): Promise<number>;
 export declare function deleteNotification(id: string): Promise<void>;
@@ -16,6 +17,17 @@ export interface SendNotificationInput extends NotificationCreateInput {
     emailHtml?: string;
     /** Buyer paid the ₹10 WhatsApp order-updates addon — enables WhatsApp channel for this notification even when the user has no standing WhatsApp subscription. */
     orderWhatsappAddonPaid?: boolean;
+    /**
+     * Which portal the recipient reads this in — decides where `actionUrl`
+     * points when the caller does not supply one.
+     *
+     * Defaults from the notification TYPE, not from the recipient's role: a
+     * seller is also a buyer, and `order_shipped` belongs in `/user` while the
+     * payout for that same order belongs in `/store`. Pass it explicitly only
+     * when one type genuinely reaches two audiences — `offer_received` goes to
+     * the seller, `offer_responded` back to the buyer.
+     */
+    audience?: NotificationAudience;
 }
 export interface SendNotificationResult {
     notification: NotificationDocument;

package/dist/features/admin/actions/notification-actions.js

@@ -7,6 +7,30 @@ import { isChannelHealthy, withChannelRetry } from "../../../_internal/server/no
 import { enqueueJob } from "../../jobs/actions/enqueue-job";
 import { serverLogger } from "../../../monitoring";
 import { decryptPii } from "../../../security/index";
+import { resolveNotificationActionUrl, } from "../../../_internal/shared/features/notifications/action-url";
+import { renderNotificationEmail } from "../../email/notification-templates";
+/**
+ * A notification's `actionUrl` is a site-relative path — correct for the
+ * in-app bell, useless in an email, where a bare `/user/orders/x` is not a
+ * link at all.
+ *
+ * `NEXT_PUBLIC_APP_URL` is the same source `ApiClient` uses for its own
+ * server-side base, so there is one answer to "what host is this" rather than
+ * a second one on `siteSettings` to drift from it.
+ *
+ * Falls back to returning the path unchanged rather than guessing a host: a
+ * wrong absolute URL sends the reader to someone else's site, while a
+ * relative one merely fails to be clickable. The template also drops the
+ * button entirely when this is undefined.
+ */
+function absoluteActionUrl(path) {
+    if (!path)
+        return undefined;
+    if (/^https?:\/\//i.test(path))
+        return path;
+    const base = process.env.NEXT_PUBLIC_APP_URL?.replace(/\/+$/, "");
+    return base ? `${base}${path}` : path;
+}
 import { DEFAULT_NOTIFICATION_CHANNELS, meetsMinPriority, } from "../schemas/firestore";
 /**
  * Notification types whose WhatsApp send is gated behind the buyer's
@@ -24,7 +48,27 @@ const ORDER_GATED_TYPES = new Set([
     "order_cancelled",
     "refund_initiated",
 ]);
-/** Notification type → the flat `SiteSettingsCredentials` field holding its approved Meta template name. */
+/**
+ * Notification type → the flat `SiteSettingsCredentials` field holding its
+ * approved Meta template name.
+ *
+ * 🛑 **`Partial` here is CORRECT and is not the `typeToPrefsKey` mistake.**
+ *
+ * The distinction is what a missing key MEANS. A missing `typeToPrefsKey`
+ * entry silently ignored a user's opt-out — a real setting that read as
+ * honoured and was not. A missing entry here means "no Meta-approved template
+ * exists for this type", which is a fact about the Meta account, not a bug:
+ * six of the 28 types have one, and the rest legitimately fall back to
+ * free-form (which Meta accepts inside the 24-hour customer-service window
+ * and rejects outside it — the runner already logs that rejection).
+ *
+ * Getting six approved templates is a Meta Business review process, not a
+ * code change, so listing all 28 here with empty values would be a
+ * `Record<…>` that lies about coverage.
+ *
+ * The six that ARE approved are the order lifecycle, which is also the set
+ * gated behind the buyer's ₹10 addon above — the two lists agree on purpose.
+ */
 const WHATSAPP_TEMPLATE_FIELD = {
     order_placed: "whatsappTemplateOrderPlaced",
     order_confirmed: "whatsappTemplateOrderConfirmed",
@@ -56,6 +100,46 @@ export async function listNotifications(userId, limit = 20) {
 export async function getUnreadNotificationCount(userId) {
     return notificationRepository.getUnreadCount(userId);
 }
+/**
+ * Which portal each notification type belongs to.
+ *
+ * `Record<NotificationType, …>`, so a new type cannot compile without an
+ * answer — the same discipline `typeToPrefsKey` needed after it silently
+ * omitted three types and ignored those users' opt-outs.
+ */
+const TYPE_AUDIENCE = {
+    // Buyer-facing: the order lifecycle they are waiting on.
+    order_placed: "buyer",
+    order_confirmed: "buyer",
+    order_shipped: "buyer",
+    order_delivered: "buyer",
+    order_cancelled: "buyer",
+    refund_initiated: "buyer",
+    payment_review: "buyer",
+    emi_installment_due_soon: "buyer",
+    emi_installment_overdue: "buyer",
+    prize_won: "buyer",
+    prize_reveal_expired: "buyer",
+    product_available: "buyer",
+    bid_placed: "buyer",
+    bid_outbid: "buyer",
+    bid_won: "buyer",
+    bid_lost: "buyer",
+    offer_responded: "buyer",
+    offer_counter_accepted: "buyer",
+    offer_expired: "buyer",
+    review_replied: "buyer",
+    catalogue_images_stale: "buyer",
+    // Seller-facing.
+    auction_ended: "seller", // "your auction closed with no winner"
+    offer_received: "seller",
+    review_approved: "seller",
+    // Account-level, which lives in the user portal for everyone.
+    welcome: "buyer",
+    account_action: "buyer",
+    system: "buyer",
+    promotion: "buyer",
+};
 /**
  * Create an in-app notification and fan out to enabled external channels.
  *
@@ -67,9 +151,26 @@ export async function getUnreadNotificationCount(userId) {
  *   5. The required credentials are set in siteSettings.credentials
  */
 export async function sendNotification(input) {
-    const { userEmail, userPhone, emailHtml, ...notifInput } = input;
+    const { userEmail, userPhone, emailHtml, audience, ...notifInput } = input;
+    /*
+     * Fill `actionUrl` when the caller did not.
+     *
+     * It was set by 5 of 40 call sites, so 35 notifications arrived in the bell
+     * as text with nothing to click. Resolving it HERE rather than asking 35
+     * writers to remember means the destination is right by construction, and
+     * changing where a `bid` notification lands is one edit rather than a sweep.
+     *
+     * A caller-supplied value always wins — a few writers legitimately point at
+     * something the relatedType cannot express (the payment-proof upload page
+     * rather than the order page).
+     */
+    const resolvedActionUrl = notifInput.actionUrl ??
+        resolveNotificationActionUrl(notifInput.relatedType, notifInput.relatedId, audience ?? TYPE_AUDIENCE[notifInput.type] ?? "buyer");
     // Always write the in-app notification first.
-    const notification = await notificationRepository.create(notifInput);
+    const notification = await notificationRepository.create({
+        ...notifInput,
+        ...(resolvedActionUrl ? { actionUrl: resolvedActionUrl } : {}),
+    });
     // Load channel config + credentials (one Firestore read).
     let settings;
     try {
@@ -102,6 +203,20 @@ export async function sendNotification(input) {
     const resolvedPhone = userPhone ??
         (fetchedUserDoc?.phoneNumber ? decryptPii(fetchedUserDoc.phoneNumber) : undefined);
     // Map NotificationType to a NotificationTypePrefs key.
+    /*
+     * 🛑 COMPLETE and compile-checked: `Record<NotificationType, …>`, not
+     * `Partial<Record<string, …>>`.
+     *
+     * The partial version silently omitted `emi_installment_due_soon`,
+     * `emi_installment_overdue` and `payment_review` — and a missing key means
+     * `typeKey` is undefined, so the opt-out check below never fires and the
+     * user's preference is IGNORED. A silently-ignored opt-out is worse than a
+     * missing feature: the toggle is right there, it reads as honoured, and
+     * mail keeps arriving.
+     *
+     * Typed on the union so the next type added cannot compile without an
+     * answer to "which toggle silences this".
+     */
     const typeToPrefsKey = {
         order_placed: "orderUpdates", order_confirmed: "orderUpdates",
         order_shipped: "orderUpdates", order_delivered: "orderUpdates",
@@ -116,6 +231,19 @@ export async function sendNotification(input) {
         product_available: "system",
         prize_won: "orderUpdates",
         prize_reveal_expired: "orderUpdates",
+        // Money owed on an order. Under orderUpdates rather than a new toggle:
+        // an EMI installment IS an order update, and inventing an eighth
+        // preference key means an existing user's saved prefs have no value for
+        // it — which reads as "off" or "on" depending on the default and is a
+        // migration nobody asked for.
+        emi_installment_due_soon: "orderUpdates",
+        emi_installment_overdue: "orderUpdates",
+        // The manual-payment review queue — the buyer's proof was verified,
+        // rejected, or needs re-uploading. Squarely an order update.
+        payment_review: "orderUpdates",
+        // "Your catalogue photos are going stale" — housekeeping about the user's
+        // own account, which is what `system` covers.
+        catalogue_images_stale: "system",
     };
     const typeKey = typeToPrefsKey[type];
     // If the user has explicitly disabled this notification type, skip all external channels.
@@ -138,7 +266,24 @@ export async function sendNotification(input) {
                 await withChannelRetry("email", () => emailProvider.send({
                     to: resolvedEmail,
                     subject: title,
-                    html: emailHtml ?? `<p>${message}</p>`,
+                    /*
+                     * A real template, not `<p>{message}</p>`.
+                     *
+                     * `emailHtml` existed on the input from the day the channel was
+                     * built and NOT ONE of the 40 call sites passed it, so all 28
+                     * types shipped a bare paragraph — no framing, no branding,
+                     * nothing to click. Rendering here rather than asking 40 writers
+                     * to remember is what makes that structurally impossible to
+                     * regress: a caller-supplied `emailHtml` still wins, for the
+                     * handful of flows with genuinely bespoke mail.
+                     */
+                    html: emailHtml ??
+                        renderNotificationEmail(type, {
+                            title,
+                            message,
+                            siteName: fromName,
+                            actionUrl: absoluteActionUrl(resolvedActionUrl),
+                        }),
                     text: message,
                 }));
                 emailStatus = "sent";

package/dist/features/admin/schemas/firestore.d.ts

@@ -4,7 +4,18 @@
  */
 import type { AboutContentDocument } from "../../about/schemas/firestore";
 export declare const ADMIN_CHECKOUT_BYPASS_FLAG_KEY: "adminCheckoutBypass";
-export type NotificationType = "order_placed" | "order_confirmed" | "order_shipped" | "order_delivered" | "order_cancelled" | "bid_placed" | "bid_outbid" | "bid_won" | "bid_lost" | "auction_ended" | "review_approved" | "review_replied" | "product_available" | "promotion" | "system" | "welcome" | "account_action" | "offer_received" | "offer_responded" | "offer_expired" | "offer_counter_accepted" | "refund_initiated" | "prize_won" | "prize_reveal_expired" | "emi_installment_due_soon" | "emi_installment_overdue" | "payment_review";
+export declare const NOTIFICATION_TYPE_VALUES: readonly ["order_placed", "order_confirmed", "order_shipped", "order_delivered", "order_cancelled", "bid_placed", "bid_outbid", "bid_won", "bid_lost", "auction_ended", "review_approved", "review_replied", "product_available", "promotion", "system", "welcome", "account_action", "offer_received", "offer_responded", "offer_expired", "offer_counter_accepted", "refund_initiated", "prize_won", "prize_reveal_expired", "emi_installment_due_soon", "emi_installment_overdue", "payment_review", "catalogue_images_stale"];
+export type NotificationType = (typeof NOTIFICATION_TYPE_VALUES)[number];
+/**
+ * What a notification points AT. Drives the shared `actionUrl` resolver, so a
+ * value here without a per-record page in some role is a notification that
+ * lands nowhere.
+ *
+ * Runtime array for the same reason as the type union above — and
+ * `catalogueItem` was being sent with an `as never` cast rather than added.
+ */
+export declare const NOTIFICATION_RELATED_TYPE_VALUES: readonly ["order", "product", "bid", "review", "blog", "user", "offer", "support_ticket", "scammer", "catalogueItem", "payout", "store"];
+export type NotificationRelatedType = (typeof NOTIFICATION_RELATED_TYPE_VALUES)[number];
 import type { BaseDocument } from "../../../_internal/shared/types/base-document";
 export type NotificationPriority = "low" | "normal" | "high";
 export interface NotificationDocument extends BaseDocument {
@@ -19,7 +30,7 @@ export interface NotificationDocument extends BaseDocument {
     isRead: boolean;
     readAt?: Date;
     relatedId?: string;
-    relatedType?: "order" | "product" | "bid" | "review" | "blog" | "user" | "offer" | "support_ticket" | "scammer";
+    relatedType?: NotificationRelatedType;
     /** Outcome of the async whatsappNotify job for this notification's WhatsApp send, if one was enqueued. */
     whatsappStatus?: "queued" | "sent" | "failed" | "skipped";
     /** jobs/{id} doc that ran (or is running) the WhatsApp send for this notification. */
@@ -82,7 +93,7 @@ export type NotificationUpdateInput = Partial<Pick<NotificationDocument, "isRead
 export declare const notificationQueryHelpers: {
     readonly byUser: (userId: string) => readonly ["userId", "==", string];
     readonly unread: (userId: string) => readonly [readonly ["userId", "==", string], readonly ["isRead", "==", false]];
-    readonly byType: (type: NotificationType) => readonly ["type", "==", NotificationType];
+    readonly byType: (type: NotificationType) => readonly ["type", "==", "system" | "welcome" | "promotion" | "order_placed" | "order_confirmed" | "order_shipped" | "order_delivered" | "order_cancelled" | "bid_placed" | "bid_outbid" | "bid_won" | "bid_lost" | "auction_ended" | "review_approved" | "review_replied" | "product_available" | "account_action" | "offer_received" | "offer_responded" | "offer_expired" | "offer_counter_accepted" | "refund_initiated" | "prize_won" | "prize_reveal_expired" | "emi_installment_due_soon" | "emi_installment_overdue" | "payment_review" | "catalogue_images_stale"];
 };
 export interface ChatRoomDocument extends BaseDocument {
     buyerId: string;

package/dist/features/admin/schemas/firestore.js

@@ -8,6 +8,85 @@ import { DEFAULT_AUCTION_BID_INCREMENT_TIERS } from "../../../_internal/shared/f
 // single occurrence in schemas. Splitting the literal makes the substring
 // audit-invisible while keeping the runtime key correct.
 export const ADMIN_CHECKOUT_BYPASS_FLAG_KEY = "adminCheckoutBypass";
+/*
+ * 🛑 The ONE notification-type union. Four existed until 2026-08-26:
+ *
+ *   · this one (27) — what `NotificationDocument.type` actually holds
+ *   · `constants/notification-types.ts` (9) — fed the admin filter chips and
+ *     the per-channel allow-list, so the admin list could not filter 18 of
+ *     the 27 real types and an admin literally could not allow-list
+ *     `offer_received` or `payment_review` for email or WhatsApp
+ *   · `features/account/types/index.ts` (5: order|offer|promo|system|message)
+ *     — a different vocabulary entirely, on a `UserNotification` type with
+ *     zero real consumers
+ *   · `seed/factories/notification.factory.ts` (9) — and THIS is the one
+ *     `appkit/src/index.ts` exported publicly as `NotificationType`, so every
+ *     external consumer got the seed factory's guess
+ *
+ * Between them they invented FOUR values no notification has ever had:
+ * `review_posted`, `payout_processed`, `review_received`, `payout_completed`.
+ * Note the first two and the last two are different spellings of the same two
+ * imagined concepts, which is how independent copies drift.
+ *
+ * A runtime array with the type derived from it, so a Zod enum, a chip list
+ * and a `Record<NotificationType, …>` all resolve here and a new value is one
+ * edit. Same shape as `ALL_LISTING_TYPES` after Root Cause #61.
+ */
+export const NOTIFICATION_TYPE_VALUES = [
+    "order_placed",
+    "order_confirmed",
+    "order_shipped",
+    "order_delivered",
+    "order_cancelled",
+    "bid_placed",
+    "bid_outbid",
+    "bid_won",
+    "bid_lost",
+    "auction_ended",
+    "review_approved",
+    "review_replied",
+    "product_available",
+    "promotion",
+    "system",
+    "welcome",
+    "account_action",
+    "offer_received",
+    "offer_responded",
+    "offer_expired",
+    "offer_counter_accepted",
+    "refund_initiated",
+    "prize_won",
+    "prize_reveal_expired",
+    "emi_installment_due_soon",
+    "emi_installment_overdue",
+    "payment_review",
+    // Was being SENT with an `as never` cast on the whole payload, which is how
+    // it stayed off this union: the cast silenced the one signal that would
+    // have said so, and with it every other field's type-check on that call.
+    "catalogue_images_stale",
+];
+/**
+ * What a notification points AT. Drives the shared `actionUrl` resolver, so a
+ * value here without a per-record page in some role is a notification that
+ * lands nowhere.
+ *
+ * Runtime array for the same reason as the type union above — and
+ * `catalogueItem` was being sent with an `as never` cast rather than added.
+ */
+export const NOTIFICATION_RELATED_TYPE_VALUES = [
+    "order",
+    "product",
+    "bid",
+    "review",
+    "blog",
+    "user",
+    "offer",
+    "support_ticket",
+    "scammer",
+    "catalogueItem",
+    "payout",
+    "store",
+];
 export const NOTIFICATIONS_COLLECTION = "notifications";
 export const NOTIFICATIONS_INDEXED_FIELDS = [
     "userId",

package/dist/features/cart/actions/cart-actions.d.ts

@@ -5,6 +5,22 @@
  * are handled by the calling server action in the consumer.
  */
 import type { AddToCartInput, CartDocument, UpdateCartItemInput } from "../schemas";
+/**
+ * Lane gate. While a higher-obligation lane (a won auction, then an accepted
+ * offer) is outstanding, no NEW shopping may be added — otherwise the buyer can
+ * keep deferring something they already committed to by piling more into the
+ * cart. Enforced on the server, not only in the UI: the UI hint is a courtesy,
+ * this is the rule.
+ *
+ * 🛑 Every add-to-cart entry point must call this. It lived inline inside
+ * `addItemToCart` and therefore covered exactly one of the four ways a line can
+ * be created — `addBundleToCartAction` and `POST /api/cart` both call
+ * `cartRepository.addItem` directly and so bypassed it entirely, letting a buyer
+ * with an unpaid auction win keep shopping.
+ *
+ * Returns the loaded cart so the caller doesn't pay a second read.
+ */
+export declare function assertCanAddNewItems(userId: string): Promise<CartDocument>;
 export declare function addItemToCart(userId: string, input: AddToCartInput): Promise<CartDocument>;
 /** Error code the client maps to a lane-aware message. */
 export declare const CART_LANE_BLOCKED = "CART_LANE_BLOCKED";

package/dist/features/cart/actions/cart-actions.js

@@ -27,6 +27,31 @@ async function resolveStoreName(storeId, candidate) {
     const store = await storeRepository.findById(storeId).catch(() => null);
     return store?.storeName ?? storeId;
 }
+/**
+ * Lane gate. While a higher-obligation lane (a won auction, then an accepted
+ * offer) is outstanding, no NEW shopping may be added — otherwise the buyer can
+ * keep deferring something they already committed to by piling more into the
+ * cart. Enforced on the server, not only in the UI: the UI hint is a courtesy,
+ * this is the rule.
+ *
+ * 🛑 Every add-to-cart entry point must call this. It lived inline inside
+ * `addItemToCart` and therefore covered exactly one of the four ways a line can
+ * be created — `addBundleToCartAction` and `POST /api/cart` both call
+ * `cartRepository.addItem` directly and so bypassed it entirely, letting a buyer
+ * with an unpaid auction win keep shopping.
+ *
+ * Returns the loaded cart so the caller doesn't pay a second read.
+ */
+export async function assertCanAddNewItems(userId) {
+    const cart = await cartRepository.getOrCreate(userId);
+    if (!canAddNewItems(cart.items ?? [])) {
+        const blocking = activeLane(cart.items ?? []);
+        throw new ValidationError(blocking === CART_LANE.AUCTION
+            ? "Settle your won auction first — you can add other items once it's paid for."
+            : "Complete your accepted offer first — you can add other items once it's paid for.", { code: CART_LANE_BLOCKED });
+    }
+    return cart;
+}
 export async function addItemToCart(userId, input) {
     serverLogger.debug("addItemToCart", { userId, productId: input.productId });
     // SB-UNI-F 2026-05-13 — capability gate. Classified + live listings reject
@@ -36,18 +61,7 @@ export async function addItemToCart(userId, input) {
     if (!canAddToCart(input.listingType)) {
         throw new ValidationError(`Listings of type "${input.listingType}" cannot be added to the cart.`);
     }
-    // Lane gate. While a higher-obligation lane (a won auction, then an accepted
-    // offer) is outstanding, no NEW shopping may be added — otherwise the buyer
-    // can keep deferring something they already committed to by piling more into
-    // the cart. Enforced here, on the server, not only in the UI: the UI hint is
-    // a courtesy, this is the rule.
-    const cart = await cartRepository.getOrCreate(userId);
-    if (!canAddNewItems(cart.items ?? [])) {
-        const blocking = activeLane(cart.items ?? []);
-        throw new ValidationError(blocking === CART_LANE.AUCTION
-            ? "Settle your won auction first — you can add other items once it's paid for."
-            : "Complete your accepted offer first — you can add other items once it's paid for.", { code: CART_LANE_BLOCKED });
-    }
+    await assertCanAddNewItems(userId);
     const storeName = await resolveStoreName(input.storeId, input.storeName);
     return cartRepository.addItem(userId, { ...input, storeName });
 }

package/dist/features/cart/components/CartDrawer.js

@@ -2,6 +2,7 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { Aside, Button, Div, Heading, Row, Span, Stack, Text, TextLink } from "../../../ui";
 import { MediaImage } from "../../media/MediaImage";
+import { QuantityStepper } from "../../../ui/components/QuantityStepper";
 import { formatCurrency } from "../../../utils/number.formatter";
 import { ACTIONS } from "../../../_internal/shared/actions/action-registry";
 import { useHandMode } from "../../../_internal/client/hand-mode";
@@ -18,7 +19,7 @@ export function CartItemRow({ item, onQtyChange, onRemove, href, isOutOfStock =
     return (_jsxs(Div, { layout: "flex", gap: isRow ? "3" : "4", surface: isRow ? "none" : "card", padding: isRow ? "none" : "sm", className: `min-w-0 transition-opacity ${isOutOfStock ? "opacity-60" : ""}`, children: [_jsx(Div, { surface: "muted", className: `relative ${isRow ? "h-16 w-16" : "h-20 w-20"} flex-shrink-0 ${__O.hidden}`, rounded: "lg", children: item.meta.image && (_jsx(MediaImage, { src: item.meta.image, alt: item.meta.title, size: "thumbnail" })) }), _jsxs(Stack, { justify: "between", className: "flex-1 min-w-0", children: [_jsxs(Row, { gap: "xs", className: "min-w-0", align: "start", children: [href ? (_jsx(TextLink, { href: href, target: "_blank", rel: "noopener noreferrer", weight: "medium", className: "text-[var(--appkit-color-text)] hover:underline underline-offset-2 line-clamp-2", children: item.meta.title })) : (_jsx(Text, { truncate: 2, weight: "medium", color: "primary", children: item.meta.title })), isOutOfStock && (_jsx(Span, { padding: "pill-2xs", color: "error", surface: "danger-surface", weight: "semibold", className: "flex-shrink-0 text-[10px] tracking-wide", rounded: "default", transform: "uppercase", children: "Out of Stock" }))] }), item.meta.attributes &&
                         Object.keys(item.meta.attributes).length > 0 && (_jsx(Text, { className: "text-[var(--appkit-color-text-muted)]", size: "xs", truncate: 1, children: Object.entries(item.meta.attributes)
                             .map(([k, v]) => `${k}: ${v}`)
-                            .join(", ") })), _jsxs(Row, { justify: "between", className: "min-w-0", gap: "sm", children: [_jsx(Text, { className: "text-[var(--appkit-color-text)]", weight: "semibold", children: formatCurrency(item.meta.price * item.quantity, item.meta.currency) }), onQtyChange && !isOutOfStock && (_jsxs(Row, { gap: "sm", children: [_jsx(Button, { rounded: "full", onClick: () => onQtyChange(item.id, item.quantity - 1), disabled: item.quantity <= 1, variant: "outline", size: "sm", className: "h-7 w-7 justify-center border border-neutral-200 border-[var(--appkit-color-border)] text-[length:var(--appkit-text-sm)] disabled:opacity-40", children: "\u2212" }), _jsx(Span, { size: "sm", className: "min-w-[1.5rem]", align: "center", children: item.quantity }), _jsx(Button, { rounded: "full", onClick: () => onQtyChange(item.id, item.quantity + 1), variant: "outline", size: "sm", className: "h-7 w-7 justify-center border border-neutral-200 border-[var(--appkit-color-border)] text-[length:var(--appkit-text-sm)]", children: "+" })] })), isOutOfStock && (_jsxs(Span, { size: "xs", color: "muted", children: ["Qty: ", item.quantity] }))] })] }), onRemove && (_jsx(Button, { onClick: () => onRemove(item.id), variant: "ghost", size: "sm", "aria-label": ACTIONS.CART["remove-item"].ariaLabel, className: CLS_REMOVE_BTN, children: "\u2715" }))] }));
+                            .join(", ") })), _jsxs(Row, { justify: "between", className: "min-w-0", gap: "sm", children: [_jsx(Text, { className: "text-[var(--appkit-color-text)]", weight: "semibold", children: formatCurrency(item.meta.price * item.quantity, item.meta.currency) }), onQtyChange && !isOutOfStock && (_jsx(QuantityStepper, { value: item.quantity, onChange: (next) => onQtyChange(item.id, next), min: 1, ariaLabel: `Quantity for ${item.meta.title}`, decrementLabel: ACTIONS.CART["decrease-quantity"].ariaLabel, incrementLabel: ACTIONS.CART["increase-quantity"].ariaLabel })), isOutOfStock && (_jsxs(Span, { size: "xs", color: "muted", children: ["Qty: ", item.quantity] }))] })] }), onRemove && (_jsx(Button, { onClick: () => onRemove(item.id), variant: "ghost", size: "sm", "aria-label": ACTIONS.CART["remove-item"].ariaLabel, className: CLS_REMOVE_BTN, children: "\u2715" }))] }));
 }
 export function CartDrawer({ isOpen, onClose, items, subtotal = 0, currency, isLoading, onQtyChange, onRemove, onCheckout, labels = {}, }) {
     const { hand } = useHandMode();