@mohasinac/appkit 4.22.0 → 4.24.0

package/dist/_internal/shared/features/notifications/action-url.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Where does a notification LAND?
+ *
+ * ## The problem this solves
+ *
+ * `actionUrl` was set by **5 of 40** `sendNotification()` call sites, so the
+ * other 35 arrived in the bell as text with nothing to click. Every writer
+ * that did set one hand-wrote the path, which is the same drift the ROUTES
+ * map exists to prevent.
+ *
+ * Worse, the destination is **role-dependent**: an offer notification sent to
+ * the buyer belongs at `/user/offers`, the same event sent to the seller at
+ * `/store/offers`, and an admin escalation at `/admin/offers`. A per-writer
+ * literal cannot express that, so writers that guessed a single path sent
+ * half their recipients somewhere they have no permission to be.
+ *
+ * ## Honest fallbacks, not invented pages
+ *
+ * `bid`, `offer` and `review` still have **no per-record page in any role** —
+ * W8 fixed those dead-end listings with a detail MODAL, not a route. So this
+ * resolver points them at the list the record lives in. That is a real,
+ * permitted, useful destination; fabricating `/user/bids/{id}` would produce
+ * a 404 and `audit-nav-page-wiring` would (correctly) fail on the ROUTES key.
+ *
+ * When those pages are built, change the entry here and all 40 call sites
+ * follow. That is the whole point of the indirection.
+ */
+import type { NotificationRelatedType } from "../../../../features/admin/schemas/firestore";
+/**
+ * Which portal the recipient reads this in.
+ *
+ * Deliberately NOT the `role` string off the session: a seller is also a
+ * buyer, and which portal a notification belongs to is a property of the
+ * EVENT, not of the person. The order-shipped notification goes to the buyer
+ * in `/user`, and the same shipment's payout notification goes to the same
+ * human in `/store`.
+ */
+export type NotificationAudience = "buyer" | "seller" | "admin";
+/**
+ * Resolve the page a notification should open.
+ *
+ * Returns `undefined` when there is genuinely nowhere to go — a `promotion`
+ * or a `welcome` has no record behind it — so the caller renders a plain,
+ * non-clickable row rather than a link to the dashboard the user is already
+ * looking at.
+ */
+export declare function resolveNotificationActionUrl(relatedType: NotificationRelatedType | undefined, relatedId: string | undefined, audience: NotificationAudience): string | undefined;

package/dist/_internal/shared/features/notifications/action-url.js

@@ -0,0 +1,111 @@
+/**
+ * Where does a notification LAND?
+ *
+ * ## The problem this solves
+ *
+ * `actionUrl` was set by **5 of 40** `sendNotification()` call sites, so the
+ * other 35 arrived in the bell as text with nothing to click. Every writer
+ * that did set one hand-wrote the path, which is the same drift the ROUTES
+ * map exists to prevent.
+ *
+ * Worse, the destination is **role-dependent**: an offer notification sent to
+ * the buyer belongs at `/user/offers`, the same event sent to the seller at
+ * `/store/offers`, and an admin escalation at `/admin/offers`. A per-writer
+ * literal cannot express that, so writers that guessed a single path sent
+ * half their recipients somewhere they have no permission to be.
+ *
+ * ## Honest fallbacks, not invented pages
+ *
+ * `bid`, `offer` and `review` still have **no per-record page in any role** —
+ * W8 fixed those dead-end listings with a detail MODAL, not a route. So this
+ * resolver points them at the list the record lives in. That is a real,
+ * permitted, useful destination; fabricating `/user/bids/{id}` would produce
+ * a 404 and `audit-nav-page-wiring` would (correctly) fail on the ROUTES key.
+ *
+ * When those pages are built, change the entry here and all 40 call sites
+ * follow. That is the whole point of the indirection.
+ */
+import { ROUTES } from "../../../../next/routing/route-map";
+/**
+ * Resolve the page a notification should open.
+ *
+ * Returns `undefined` when there is genuinely nowhere to go — a `promotion`
+ * or a `welcome` has no record behind it — so the caller renders a plain,
+ * non-clickable row rather than a link to the dashboard the user is already
+ * looking at.
+ */
+export function resolveNotificationActionUrl(relatedType, relatedId, audience) {
+    if (!relatedType || !relatedId)
+        return undefined;
+    switch (relatedType) {
+        case "order":
+            return audience === "admin"
+                ? String(ROUTES.ADMIN.ORDER_DETAIL(relatedId))
+                : audience === "seller"
+                    ? String(ROUTES.STORE.ORDER_DETAIL(relatedId))
+                    : String(ROUTES.USER.ORDER_DETAIL(relatedId));
+        case "product":
+            // The public listing page — the one destination that is the same for
+            // everyone, because a product page is public.
+            return String(ROUTES.PUBLIC.PRODUCT_DETAIL(relatedId));
+        // ── List-level, because no per-record page exists in ANY role ─────────
+        // W8 gave these listings a detail modal rather than a route. Linking the
+        // list is honest; a fabricated `/…/{id}` would 404.
+        case "bid":
+            return audience === "admin"
+                ? String(ROUTES.ADMIN.BIDS)
+                : audience === "seller"
+                    ? String(ROUTES.STORE.BIDS)
+                    : String(ROUTES.USER.BIDS);
+        case "offer":
+            return audience === "admin"
+                ? String(ROUTES.ADMIN.OFFERS)
+                : audience === "seller"
+                    ? String(ROUTES.STORE.OFFERS)
+                    : String(ROUTES.USER.OFFERS);
+        case "review":
+            // The public review page exists; the admin/seller sides are modals.
+            return String(ROUTES.PUBLIC.REVIEW_DETAIL(relatedId));
+        case "blog":
+            return String(ROUTES.BLOG.ARTICLE(relatedId));
+        case "user":
+            // Only an admin has a per-user page. A user notified ABOUT themselves
+            // (a ban, a role change) belongs on their own account hub, not on a
+            // page they cannot open.
+            return audience === "admin"
+                ? String(ROUTES.ADMIN.USER_DETAIL(relatedId))
+                : String(ROUTES.USER.PROFILE);
+        case "support_ticket":
+            return audience === "admin"
+                ? String(ROUTES.ADMIN.SUPPORT_TICKET_BY_ID(relatedId))
+                : String(ROUTES.USER.SUPPORT_TICKET(relatedId));
+        case "scammer":
+            // Admin-only surface — the public scam registry is browsed, not
+            // notified about.
+            return audience === "admin" ? String(ROUTES.ADMIN.SCAMMER_BY_ID(relatedId)) : undefined;
+        case "catalogueItem":
+            // The owner edits it; an admin reviews it from the approvals queue,
+            // which is a list because approval is a queue-shaped job.
+            return audience === "admin"
+                ? String(ROUTES.ADMIN.CATALOGUE_APPROVALS)
+                : String(ROUTES.USER.CATALOGUE_EDIT(relatedId));
+        case "payout":
+            return audience === "admin"
+                ? String(ROUTES.ADMIN.PAYOUT_DETAIL(relatedId))
+                : String(ROUTES.STORE.PAYOUT_DETAIL(relatedId));
+        case "store":
+            return audience === "admin"
+                ? String(ROUTES.ADMIN.STORE_DETAIL(relatedId))
+                : String(ROUTES.STORE.DASHBOARD);
+        default: {
+            /*
+             * Exhaustiveness. A new `relatedType` cannot compile without an answer
+             * to "where does this land", which is precisely the check that was
+             * missing when `catalogueItem` was smuggled in behind an `as never`.
+             */
+            const _exhaustive = relatedType;
+            void _exhaustive;
+            return undefined;
+        }
+    }
+}

package/dist/_internal/shared/features/products/schema.d.ts

@@ -41,7 +41,7 @@ export declare const productInputSchema: z.ZodObject<{
     condition?: "new" | "used" | "refurbished" | "like_new" | "good" | "fair" | "poor" | "broken" | undefined;
     insurance?: boolean | undefined;
     insuranceCost?: number | undefined;
-    shippingPaidBy?: "seller" | "buyer" | undefined;
+    shippingPaidBy?: "buyer" | "seller" | undefined;
     seoTitle?: string | undefined;
     seoDescription?: string | undefined;
     seoKeywords?: string[] | undefined;
@@ -65,7 +65,7 @@ export declare const productInputSchema: z.ZodObject<{
     condition?: "new" | "used" | "refurbished" | "like_new" | "good" | "fair" | "poor" | "broken" | undefined;
     insurance?: boolean | undefined;
     insuranceCost?: number | undefined;
-    shippingPaidBy?: "seller" | "buyer" | undefined;
+    shippingPaidBy?: "buyer" | "seller" | undefined;
     seoTitle?: string | undefined;
     seoDescription?: string | undefined;
     seoKeywords?: string[] | undefined;
@@ -114,7 +114,7 @@ export declare const productUpdateSchema: z.ZodObject<{
     condition?: "new" | "used" | "refurbished" | "like_new" | "good" | "fair" | "poor" | "broken" | undefined;
     insurance?: boolean | undefined;
     insuranceCost?: number | undefined;
-    shippingPaidBy?: "seller" | "buyer" | undefined;
+    shippingPaidBy?: "buyer" | "seller" | undefined;
     seoTitle?: string | undefined;
     seoDescription?: string | undefined;
     seoKeywords?: string[] | undefined;
@@ -138,7 +138,7 @@ export declare const productUpdateSchema: z.ZodObject<{
     condition?: "new" | "used" | "refurbished" | "like_new" | "good" | "fair" | "poor" | "broken" | undefined;
     insurance?: boolean | undefined;
     insuranceCost?: number | undefined;
-    shippingPaidBy?: "seller" | "buyer" | undefined;
+    shippingPaidBy?: "buyer" | "seller" | undefined;
     seoTitle?: string | undefined;
     seoDescription?: string | undefined;
     seoKeywords?: string[] | undefined;
@@ -201,7 +201,7 @@ export declare const auctionInputSchema: z.ZodObject<{
     condition?: "new" | "used" | "refurbished" | "like_new" | "good" | "fair" | "poor" | "broken" | undefined;
     insurance?: boolean | undefined;
     insuranceCost?: number | undefined;
-    shippingPaidBy?: "seller" | "buyer" | undefined;
+    shippingPaidBy?: "buyer" | "seller" | undefined;
     reservePrice?: number | undefined;
     buyNowPrice?: number | undefined;
     minBidIncrement?: number | undefined;
@@ -233,7 +233,7 @@ export declare const auctionInputSchema: z.ZodObject<{
     condition?: "new" | "used" | "refurbished" | "like_new" | "good" | "fair" | "poor" | "broken" | undefined;
     insurance?: boolean | undefined;
     insuranceCost?: number | undefined;
-    shippingPaidBy?: "seller" | "buyer" | undefined;
+    shippingPaidBy?: "buyer" | "seller" | undefined;
     reservePrice?: number | undefined;
     buyNowPrice?: number | undefined;
     minBidIncrement?: number | undefined;
@@ -299,7 +299,7 @@ export declare const preOrderInputSchema: z.ZodObject<{
     condition?: "new" | "used" | "refurbished" | "like_new" | "good" | "fair" | "poor" | "broken" | undefined;
     insurance?: boolean | undefined;
     insuranceCost?: number | undefined;
-    shippingPaidBy?: "seller" | "buyer" | undefined;
+    shippingPaidBy?: "buyer" | "seller" | undefined;
     preOrderDepositPercent?: number | undefined;
     preOrderMaxQuantity?: number | undefined;
     seoTitle?: string | undefined;
@@ -327,7 +327,7 @@ export declare const preOrderInputSchema: z.ZodObject<{
     condition?: "new" | "used" | "refurbished" | "like_new" | "good" | "fair" | "poor" | "broken" | undefined;
     insurance?: boolean | undefined;
     insuranceCost?: number | undefined;
-    shippingPaidBy?: "seller" | "buyer" | undefined;
+    shippingPaidBy?: "buyer" | "seller" | undefined;
     preOrderDepositPercent?: number | undefined;
     preOrderMaxQuantity?: number | undefined;
     preOrderProductionStatus?: "upcoming" | "in_production" | "ready_to_ship" | undefined;

package/dist/_internal/shared/features/promotions/schema.d.ts

@@ -75,7 +75,7 @@ export declare const createCouponSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     code: string;
     type: "fixed" | "percentage" | "free_shipping" | "buy_x_get_y";
-    scope: "admin" | "seller";
+    scope: "seller" | "admin";
     name: string;
     discount: {
         value: number;
@@ -99,7 +99,7 @@ export declare const createCouponSchema: z.ZodObject<{
 }, {
     code: string;
     type: "fixed" | "percentage" | "free_shipping" | "buy_x_get_y";
-    scope: "admin" | "seller";
+    scope: "seller" | "admin";
     name: string;
     discount: {
         value: number;
@@ -177,7 +177,7 @@ export declare const updateCouponSchema: z.ZodObject<Omit<{
     }>>>;
 }, "code">, "strip", z.ZodTypeAny, {
     type?: "fixed" | "percentage" | "free_shipping" | "buy_x_get_y" | undefined;
-    scope?: "admin" | "seller" | undefined;
+    scope?: "seller" | "admin" | undefined;
     name?: string | undefined;
     discount?: {
         value: number;
@@ -200,7 +200,7 @@ export declare const updateCouponSchema: z.ZodObject<Omit<{
     } | undefined;
 }, {
     type?: "fixed" | "percentage" | "free_shipping" | "buy_x_get_y" | undefined;
-    scope?: "admin" | "seller" | undefined;
+    scope?: "seller" | "admin" | undefined;
     name?: string | undefined;
     discount?: {
         value: number;

package/dist/_internal/shared/history/index.d.ts

@@ -1,4 +1,4 @@
-export type { HistoryActorRole, HistoryActor, FieldChange, StatusChangeEntry, AppendHistoryResult, } from "./types";
+export type { HistoryActorRole, HistoryActor, FieldChange, StatusChangeEntry, AppendHistoryResult, SerialisedStatusChangeEntry, } from "./types";
 export { STATUS_HISTORY_MAX } from "./types";
 export type { BuildHistoryEntryInput } from "./history";
 export { diffTrackedFields, buildHistoryEntry, appendHistoryEntry, withHistory, } from "./history";

package/dist/_internal/shared/history/types.d.ts

@@ -59,3 +59,19 @@ export interface AppendHistoryResult {
      */
     truncatedCount: number;
 }
+/**
+ * A `StatusChangeEntry` after it has crossed the RSC boundary.
+ *
+ * Identical except `at` is an ISO string. Server Components must serialise
+ * before handing history to a `"use client"` component: every other date prop
+ * on those drawers is already a string, and mixing the two is how a
+ * `toLocaleString` on a string ends up rendering "Invalid Date".
+ *
+ * Declared once here rather than restated per page — two client files had
+ * hand-written copies, which is both a duplication and (because each spelled
+ * `changes` as `Record<string, { from: unknown; to: unknown }>`) an untyped
+ * seam `audit-unknown-leakage` correctly refused.
+ */
+export interface SerialisedStatusChangeEntry extends Omit<StatusChangeEntry, "at"> {
+    at: string;
+}

package/dist/client.d.ts

@@ -164,6 +164,8 @@ export type { ColorPickerFieldProps } from "./ui/forms";
 export { ColorPickerField } from "./ui/forms";
 export type { FormErrorSummaryProps } from "./ui/forms";
 export { FormErrorSummary } from "./ui/forms";
+export { RecordStatusTimeline } from "./features/status-history/index";
+export type { SerialisedStatusChangeEntry } from "./_internal/shared/history/types";
 export type { FormErrorListProps } from "./ui/forms";
 export { FormErrorList } from "./ui/forms";
 export { useFormBottomActions } from "./features/layout/index";

package/dist/client.js

@@ -222,6 +222,7 @@ export { FieldCheckbox } from "./ui/forms";
 export { FieldTextarea } from "./ui/forms";
 export { ColorPickerField } from "./ui/forms";
 export { FormErrorSummary } from "./ui/forms";
+export { RecordStatusTimeline } from "./features/status-history/index";
 export { FormErrorList } from "./ui/forms";
 export { useFormBottomActions } from "./features/layout/index";
 export { OverlayContext, useIsInsideOverlay } from "./ui/components/overlay-context";

package/dist/constants/field-names.d.ts

@@ -341,6 +341,18 @@ export declare const AD_FIELDS: {
         readonly PAUSED: "paused";
     };
 };
+/**
+ * The ad fields whose changes earn a `statusHistory` entry.
+ *
+ * Ads live inside the `siteSettings` singleton and have no repository, so
+ * `withHistory` is called from the route directly — it is a pure function, so
+ * that is fine. This list lives here beside `AD_FIELDS` rather than in a
+ * schema module because ads have no schema module of their own.
+ *
+ * The scheduling dates are tracked alongside `status`: an ad silently
+ * rescheduled reads on the timeline as the same kind of event as one paused.
+ */
+export declare const AD_TRACKED_FIELDS: readonly ["status", "startAt", "endAt"];
 export declare const EVENT_FIELDS: {
     readonly ID: "id";
     readonly TITLE: "title";

package/dist/constants/field-names.js

@@ -390,6 +390,18 @@ export const AD_FIELDS = {
         PAUSED: "paused",
     },
 };
+/**
+ * The ad fields whose changes earn a `statusHistory` entry.
+ *
+ * Ads live inside the `siteSettings` singleton and have no repository, so
+ * `withHistory` is called from the route directly — it is a pure function, so
+ * that is fine. This list lives here beside `AD_FIELDS` rather than in a
+ * schema module because ads have no schema module of their own.
+ *
+ * The scheduling dates are tracked alongside `status`: an ad silently
+ * rescheduled reads on the timeline as the same kind of event as one paused.
+ */
+export const AD_TRACKED_FIELDS = ["status", "startAt", "endAt"];
 // ============================================================================
 // EVENT FIELDS
 // ============================================================================

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/admin-actions.js

@@ -72,8 +72,11 @@ export async function adminUpdatePayout(adminId, id, input) {
         throw new NotFoundError("Payout not found");
     }
     const updateData = {
-        ...(input.status !== undefined ? { status: input.status } : {}),
         ...(input.adminNote !== undefined ? { adminNote: input.adminNote } : {}),
+        // The payment reference. Absent from this pick until 2026-08-26, so every
+        // payout marked paid was stored WITHOUT the UTR the modal required — see
+        // PAYOUT_ADMIN_UPDATEABLE_FIELDS for the full trace.
+        ...(input.transactionId !== undefined ? { transactionId: input.transactionId } : {}),
         ...(input.processedAt
             ? {
                 processedAt: input.processedAt instanceof Date
@@ -82,12 +85,19 @@ export async function adminUpdatePayout(adminId, id, input) {
             }
             : {}),
     };
-    const updated = await payoutRepository.update(id, updateData);
+    /*
+     * Through `updateStatus`, not a bare `update`, so the change lands on the
+     * payout's own timeline — `existing` is threaded in as `prior`, so that
+     * costs no second read of a document this function already holds.
+     */
+    const updated = input.status !== undefined
+        ? await payoutRepository.updateStatus(id, input.status, updateData, { actor: { role: "admin", uid: adminId }, trigger: "adminUpdatePayout" }, existing)
+        : await payoutRepository.update(id, updateData);
     serverLogger.info("adminUpdatePayout", {
         adminId,
         payoutId: id,
     });
-    if (updateData.status === "paid") {
+    if (input.status === "paid") {
         void recordAdminAction({
             actorUid: adminId,
             action: AdminAuditActionValues.PAYOUT_MARK_PAID,

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;