@mohasinac/appkit 4.21.0 → 4.23.0

package/dist/features/layout/BottomActions.js

@@ -114,7 +114,7 @@ export default function BottomActions() {
         setPickerOpen(false);
         setInfoOpen(false);
     });
-    const { actions, bulk, infoLabel, secondaryLabel, infoPanel, desktop } = state;
+    const { actions, bulk, infoLabel, secondaryLabel, infoPanel, infoOpenSignal, desktop } = state;
     // Desktop reveal-on-scroll. Kept as a plain passive listener to match BackToTop —
     // there is no shared scroll-position hook in the codebase and one consumer doesn't
     // justify inventing one. Only armed when a page actually opts into "after-scroll".
@@ -144,6 +144,23 @@ export default function BottomActions() {
         if (!hasInfoPanel)
             setInfoOpen(false);
     }, [hasInfoPanel]);
+    /*
+     * Force-open on a bumped signal — a failed form submit, today. Depends on
+     * the counter alone, so a re-render with the same value never re-opens what
+     * the user has since collapsed. `hasInfoPanel` is read but deliberately NOT
+     * a dependency: publishing the panel and bumping the signal are two separate
+     * setState calls, so re-running on `hasInfoPanel` would open the panel again
+     * one render after the user closed it.
+     */
+    const lastSignalRef = useRef(undefined);
+    useEffect(() => {
+        if (infoOpenSignal == null)
+            return;
+        if (lastSignalRef.current === infoOpenSignal)
+            return;
+        lastSignalRef.current = infoOpenSignal;
+        setInfoOpen(true);
+    }, [infoOpenSignal]);
     // Keep selectedActionId in sync with available bulk actions
     useEffect(() => {
         if (!isBulkMode) {

package/dist/features/layout/BottomActionsContext.d.ts

@@ -109,6 +109,19 @@ export interface BottomActionsState {
      * bulk mode, which owns the same space for its action picker.
      */
     infoPanel?: React.ReactNode;
+    /**
+     * A COUNTER, not a boolean — bump it to force `infoPanel` open once.
+     *
+     * `BottomActions` owns `infoOpen` in local state so the user can collapse
+     * the panel at will. A boolean `forceOpen` would fight that: it stays true,
+     * so every subsequent render re-opens what they just closed. A counter
+     * expresses the real intent — "this is a NEW event, show it" — and fires
+     * exactly once per increment.
+     *
+     * Used by a form's failed submit: the error list should appear without a
+     * tap, and stay dismissible afterwards.
+     */
+    infoOpenSignal?: number;
 }
 interface BottomActionsContextValue {
     state: BottomActionsState;
@@ -131,10 +144,16 @@ interface BottomActionsContextValue {
     setSecondaryLabel: (label: string | undefined) => void;
     /** Set or clear the expandable panel revealed above the bar. */
     setInfoPanel: (panel: React.ReactNode | undefined) => void;
+    /** Set the force-open counter. See BottomActionsState.infoOpenSignal. */
+    setInfoOpenSignal: (signal: number | undefined) => void;
     /** Set the desktop visibility policy. */
     setDesktopMode: (mode: BottomActionsDesktopMode | undefined) => void;
     /** Clear all state (called on feature unmount). */
     clearAll: () => void;
+    claim: (id: string) => void;
+    release: (id: string) => void;
+    /** The id currently allowed to publish. `useBottomActions` gates on this. */
+    topClaimId: string | null;
 }
 export declare function BottomActionsProvider({ children, }: {
     children: React.ReactNode;

package/dist/features/layout/BottomActionsContext.js

@@ -47,6 +47,32 @@ export function BottomActionsProvider({ children, }) {
     const actionCallbacksRef = useRef(new Map());
     const bulkCallbacksRef = useRef(new Map());
     const bulkClearRef = useRef(undefined);
+    // Stack of claimant ids, oldest first. The last entry owns the bar.
+    const claimsRef = useRef([]);
+    const [topClaimId, setTopClaimId] = useState(null);
+    const claim = useCallback((id) => {
+        if (claimsRef.current.includes(id))
+            return;
+        claimsRef.current = [...claimsRef.current, id];
+        setTopClaimId(id);
+    }, []);
+    const release = useCallback((id) => {
+        const next = claimsRef.current.filter((c) => c !== id);
+        if (next.length === claimsRef.current.length)
+            return;
+        claimsRef.current = next;
+        const newTop = next.length > 0 ? next[next.length - 1] : null;
+        setTopClaimId(newTop);
+        // Only blank the bar when nobody is left. Otherwise the newly-top
+        // consumer republishes on the very next effect pass, so clearing here
+        // would be a visible flicker of an empty bar.
+        if (newTop === null) {
+            actionCallbacksRef.current = new Map();
+            bulkCallbacksRef.current = new Map();
+            bulkClearRef.current = undefined;
+            setState(EMPTY);
+        }
+    }, []);
     const setActions = useCallback((actions) => {
         // Update callback map (always latest)
         actionCallbacksRef.current = new Map(actions.map((a) => [a.id, a.onClick]));
@@ -90,6 +116,9 @@ export function BottomActionsProvider({ children, }) {
     const setInfoPanel = useCallback((infoPanel) => {
         setState((prev) => ({ ...prev, infoPanel }));
     }, []);
+    const setInfoOpenSignal = useCallback((infoOpenSignal) => {
+        setState((prev) => (prev.infoOpenSignal === infoOpenSignal ? prev : { ...prev, infoOpenSignal }));
+    }, []);
     const setDesktopMode = useCallback((desktop) => {
         setState((prev) => (prev.desktop === desktop ? prev : { ...prev, desktop }));
     }, []);
@@ -109,8 +138,12 @@ export function BottomActionsProvider({ children, }) {
         setInfoLabel,
         setSecondaryLabel,
         setInfoPanel,
+        setInfoOpenSignal,
         setDesktopMode,
         clearAll,
+        claim,
+        release,
+        topClaimId,
     }), [
         state,
         setActions,
@@ -118,8 +151,12 @@ export function BottomActionsProvider({ children, }) {
         setInfoLabel,
         setSecondaryLabel,
         setInfoPanel,
+        setInfoOpenSignal,
         setDesktopMode,
         clearAll,
+        claim,
+        release,
+        topClaimId,
     ]);
     return (_jsx(BottomActionsContext.Provider, { value: value, children: children }));
 }

package/dist/features/layout/hooks/useBottomActions.d.ts

@@ -11,10 +11,20 @@ export interface UseBottomActionsOptions {
      * See BottomActionsState.infoPanel.
      */
     infoPanel?: React.ReactNode;
+    /** Bump to force `infoPanel` open once. See BottomActionsState.infoOpenSignal. */
+    infoOpenSignal?: number;
     /**
      * Whether the bar may also show on desktop. Defaults to "hidden" (mobile/tablet only),
      * so pages that don't opt in behave exactly as before.
      */
     desktop?: BottomActionsDesktopMode;
+    /**
+     * Set false to opt out entirely — no claim is taken, so this consumer is
+     * invisible to the stack and cannot displace whoever currently owns the
+     * bar. Load-bearing: `useFormBottomActions` is called unconditionally from
+     * `<Form>`, which mounts on ~75 surfaces, and a claim from each of those
+     * would push a listing's bulk bar off the stack for nothing.
+     */
+    enabled?: boolean;
 }
 export declare function useBottomActions(options?: UseBottomActionsOptions): void;

package/dist/features/layout/hooks/useBottomActions.js

@@ -1,8 +1,28 @@
 "use client";
-import { useEffect, useRef } from "react";
+import { useEffect, useId, useRef } from "react";
 import { useBottomActionsContext, } from "../BottomActionsContext";
 export function useBottomActions(options = {}) {
-    const { setActions, setBulkConfig, setInfoLabel, setSecondaryLabel, setInfoPanel, setDesktopMode, clearAll, } = useBottomActionsContext();
+    const { setActions, setBulkConfig, setInfoLabel, setSecondaryLabel, setInfoPanel, setInfoOpenSignal, setDesktopMode, claim, release, topClaimId, } = useBottomActionsContext();
+    /*
+     * One bar, many potential claimants. `DataListingView` already holds it on
+     * ~70 admin screens, so a form opened in a drawer over a listing used to
+     * overwrite the listing's bar and blank it on close.
+     *
+     * Claim on mount, release on unmount. `isTop` gates every publish below, so
+     * a backgrounded consumer stops writing — and because `isTop` is a
+     * dependency of each effect, regaining the top re-publishes everything
+     * automatically. That is what restores the listing's bar when the form
+     * closes, with no cooperation needed from either side.
+     */
+    const enabled = options.enabled !== false;
+    const claimId = useId();
+    useEffect(() => {
+        if (!enabled)
+            return;
+        claim(claimId);
+        return () => release(claimId);
+    }, [claim, release, claimId, enabled]);
+    const isTop = enabled && topClaimId === claimId;
     const actionsRef = useRef(options.actions ?? []);
     actionsRef.current = options.actions ?? [];
     const bulkRef = useRef(options.bulk);
@@ -14,17 +34,25 @@ export function useBottomActions(options = {}) {
         ? `${options.bulk.selectedCount}|${options.bulk.actions.map((a) => `${a.id}|${a.label}|${a.variant}|${a.badge}|${a.disabled}|${a.loading}|${a.grow}`).join(",")}`
         : "";
     useEffect(() => {
+        if (!isTop)
+            return;
         setActions(actionsRef.current);
-    }, [setActions, actionKey]);
+    }, [setActions, actionKey, isTop]);
     useEffect(() => {
+        if (!isTop)
+            return;
         setBulkConfig(bulkRef.current);
-    }, [setBulkConfig, bulkCountKey]);
+    }, [setBulkConfig, bulkCountKey, isTop]);
     useEffect(() => {
+        if (!isTop)
+            return;
         setInfoLabel(options.infoLabel);
-    }, [setInfoLabel, options.infoLabel]);
+    }, [setInfoLabel, options.infoLabel, isTop]);
     useEffect(() => {
+        if (!isTop)
+            return;
         setSecondaryLabel(options.secondaryLabel);
-    }, [setSecondaryLabel, options.secondaryLabel]);
+    }, [setSecondaryLabel, options.secondaryLabel, isTop]);
     // A ReactNode is a fresh object on every render, so it can't be a dependency
     // without looping. Mirror it through a ref and re-publish whenever anything
     // the panel actually derives from changes — callers pass `infoLabel`, which
@@ -33,12 +61,21 @@ export function useBottomActions(options = {}) {
     infoPanelRef.current = options.infoPanel;
     const hasInfoPanel = options.infoPanel != null;
     useEffect(() => {
+        if (!isTop)
+            return;
         setInfoPanel(infoPanelRef.current);
-    }, [setInfoPanel, hasInfoPanel, options.infoLabel, options.secondaryLabel]);
+    }, [setInfoPanel, hasInfoPanel, options.infoLabel, options.secondaryLabel, isTop]);
     useEffect(() => {
-        setDesktopMode(options.desktop);
-    }, [setDesktopMode, options.desktop]);
+        if (!isTop)
+            return;
+        setInfoOpenSignal(options.infoOpenSignal);
+    }, [setInfoOpenSignal, options.infoOpenSignal, isTop]);
     useEffect(() => {
-        return () => clearAll();
-    }, [clearAll]);
+        if (!isTop)
+            return;
+        setDesktopMode(options.desktop);
+    }, [setDesktopMode, options.desktop, isTop]);
+    // NOTE: no clearAll() on unmount any more — `release()` above owns that, and
+    // only blanks the bar when the stack empties. Clearing here would flash an
+    // empty bar between a drawer closing and the listing behind it republishing.
 }

package/dist/features/layout/hooks/useFormBottomActions.d.ts

@@ -0,0 +1,57 @@
+import { type FormShellContextValue } from "../../../ui/forms/FormShell";
+export interface UseFormBottomActionsOptions {
+    /** Runs when the pinned primary button is pressed. */
+    onSubmit: () => void | Promise<void>;
+    /** Omit to render no Cancel button — a settings page with nowhere to go back to. */
+    onCancel?: () => void;
+    submitLabel?: string;
+    cancelLabel?: string;
+    isLoading?: boolean;
+    disabled?: boolean;
+    /** Set false to leave the bar to someone else on this route. */
+    enabled?: boolean;
+    /**
+     * Read the form state from here instead of the ambient context. `<Form>`
+     * needs it: the hook runs in `Form`'s body, which is ABOVE the provider
+     * `Form` itself renders, so the ambient lookup would find the parent's
+     * context or none at all.
+     */
+    ctx?: FormShellContextValue;
+}
+/**
+ * Pin a form's Save/Cancel row to the bottom of a phone screen, and turn its
+ * validation errors into a pull-up sheet above it.
+ *
+ * ## Nothing here is new chrome
+ *
+ * This is `useBottomActions` with a form-shaped payload. The cart's bottom bar
+ * — "Total ₹777 · Details ⌃" over a pinned CTA — is 100% that primitive's
+ * output already, so the sheet mechanics, the collapse rule
+ * (`grid-rows-[1fr] ↔ [0fr]`, background on the innermost div),
+ * click-outside-to-close, the `ResizeObserver` that publishes
+ * `--bottom-chrome-height`, and all three bottom-edge offsets come for free.
+ * Re-deriving any of that would be a second, worse copy.
+ *
+ * ## Three details that will bite anyone editing this
+ *
+ * 1. **The label must encode the count.** `useBottomActions` re-publishes
+ *    `infoPanel` only when `hasInfoPanel`, `infoLabel` or `secondaryLabel`
+ *    change — a ReactNode is a fresh object every render and cannot be a
+ *    dependency without looping. "Fix 6 issues" → "Fix 5 issues" is
+ *    therefore what pushes the updated list through. A generic label like
+ *    "Errors" would freeze the sheet's contents at whatever they were the
+ *    first time it opened.
+ *
+ * 2. **The panel is rendered outside the form's provider.** `BottomActions`
+ *    lives in the layout shell, so the detached node cannot reach
+ *    `FormShellContext` by itself — hence `<FormErrorList ctx={ctx}>` with
+ *    the context passed explicitly.
+ *
+ * 3. **Suppressed inside a Modal or SideDrawer.** An overlay owns its own
+ *    footer, and a viewport-fixed bar would render *behind* the backdrop,
+ *    below the dialog it belongs to. `useIsInsideOverlay()` is how the
+ *    overlay tells us, because neither portal leaves a detectable trace in
+ *    the DOM at the form's position.
+ */
+export declare function useFormBottomActions({ onSubmit, onCancel, submitLabel, cancelLabel, isLoading, disabled, enabled, ctx: ctxProp, }: UseFormBottomActionsOptions): void;
+export default useFormBottomActions;

package/dist/features/layout/hooks/useFormBottomActions.js

@@ -0,0 +1,89 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useContext, useMemo } from "react";
+import { FormShellContext } from "../../../ui/forms/FormShell";
+import { FormErrorList } from "../../../ui/forms/FormErrorList";
+import { useIsInsideOverlay } from "../../../ui/components/overlay-context";
+import { useBottomActions } from "./useBottomActions";
+/**
+ * Pin a form's Save/Cancel row to the bottom of a phone screen, and turn its
+ * validation errors into a pull-up sheet above it.
+ *
+ * ## Nothing here is new chrome
+ *
+ * This is `useBottomActions` with a form-shaped payload. The cart's bottom bar
+ * — "Total ₹777 · Details ⌃" over a pinned CTA — is 100% that primitive's
+ * output already, so the sheet mechanics, the collapse rule
+ * (`grid-rows-[1fr] ↔ [0fr]`, background on the innermost div),
+ * click-outside-to-close, the `ResizeObserver` that publishes
+ * `--bottom-chrome-height`, and all three bottom-edge offsets come for free.
+ * Re-deriving any of that would be a second, worse copy.
+ *
+ * ## Three details that will bite anyone editing this
+ *
+ * 1. **The label must encode the count.** `useBottomActions` re-publishes
+ *    `infoPanel` only when `hasInfoPanel`, `infoLabel` or `secondaryLabel`
+ *    change — a ReactNode is a fresh object every render and cannot be a
+ *    dependency without looping. "Fix 6 issues" → "Fix 5 issues" is
+ *    therefore what pushes the updated list through. A generic label like
+ *    "Errors" would freeze the sheet's contents at whatever they were the
+ *    first time it opened.
+ *
+ * 2. **The panel is rendered outside the form's provider.** `BottomActions`
+ *    lives in the layout shell, so the detached node cannot reach
+ *    `FormShellContext` by itself — hence `<FormErrorList ctx={ctx}>` with
+ *    the context passed explicitly.
+ *
+ * 3. **Suppressed inside a Modal or SideDrawer.** An overlay owns its own
+ *    footer, and a viewport-fixed bar would render *behind* the backdrop,
+ *    below the dialog it belongs to. `useIsInsideOverlay()` is how the
+ *    overlay tells us, because neither portal leaves a detectable trace in
+ *    the DOM at the form's position.
+ */
+export function useFormBottomActions({ onSubmit, onCancel, submitLabel = "Save", cancelLabel = "Cancel", isLoading = false, disabled = false, enabled = true, ctx: ctxProp, }) {
+    const ambient = useContext(FormShellContext);
+    const ctx = ctxProp ?? ambient;
+    const insideOverlay = useIsInsideOverlay();
+    const active = enabled && !insideOverlay && ctx != null;
+    const errorCount = ctx ? Object.keys(ctx.errors).length : 0;
+    const showErrors = !!ctx?.submitAttempted && errorCount > 0;
+    const actions = useMemo(() => {
+        if (!active)
+            return [];
+        const list = [];
+        if (onCancel) {
+            list.push({
+                id: "form-cancel",
+                label: cancelLabel,
+                variant: "outline",
+                grow: false,
+                onClick: onCancel,
+                disabled: isLoading,
+            });
+        }
+        list.push({
+            id: "form-submit",
+            label: submitLabel,
+            variant: "primary",
+            grow: true,
+            loading: isLoading,
+            disabled: disabled || isLoading,
+            onClick: () => void onSubmit(),
+        });
+        return list;
+    }, [active, onCancel, cancelLabel, submitLabel, isLoading, disabled, onSubmit]);
+    useBottomActions({
+        actions,
+        // Encodes the count on purpose — see (1) in the header.
+        infoLabel: showErrors
+            ? `Fix ${errorCount} ${errorCount === 1 ? "issue" : "issues"}`
+            : undefined,
+        infoPanel: showErrors && ctx ? _jsx(FormErrorList, { ctx: ctx }) : undefined,
+        // Bumped by every submit attempt, so a second failed Save re-opens a
+        // sheet the user collapsed — while an ordinary re-render does not.
+        infoOpenSignal: showErrors ? ctx?.submitAttemptCount : undefined,
+        // No claim at all when inactive — see UseBottomActionsOptions.enabled.
+        enabled: active,
+    });
+}
+export default useFormBottomActions;

package/dist/features/layout/index.d.ts

@@ -30,6 +30,8 @@ export { BottomActionsProvider, useBottomActionsContext, } from "./BottomActions
 export type { BottomAction, BottomBulkConfig, BottomActionsState, BottomActionsDesktopMode, } from "./BottomActionsContext";
 export { useBottomActions } from "./hooks/useBottomActions";
 export type { UseBottomActionsOptions } from "./hooks/useBottomActions";
+export { useFormBottomActions } from "./hooks/useFormBottomActions";
+export type { UseFormBottomActionsOptions } from "./hooks/useFormBottomActions";
 export { default as BottomActions } from "./BottomActions";
 export { BottomChrome } from "./BottomChrome";
 export type { BottomChromeProps } from "./BottomChrome";

package/dist/features/layout/index.js

@@ -16,6 +16,7 @@ export { LayoutClient } from "./LayoutClient";
 export { AppLayoutShell } from "./AppLayoutShell";
 export { BottomActionsProvider, useBottomActionsContext, } from "./BottomActionsContext";
 export { useBottomActions } from "./hooks/useBottomActions";
+export { useFormBottomActions } from "./hooks/useFormBottomActions";
 export { default as BottomActions } from "./BottomActions";
 export { BottomChrome } from "./BottomChrome";
 export { BottomNavbar } from "./BottomNavbar";

package/dist/features/messages/schemas/index.d.ts

@@ -21,7 +21,7 @@ export declare const conversationMessageSchema: z.ZodObject<{
     body: string;
     isRead: boolean;
     senderId: string;
-    senderRole: "seller" | "buyer";
+    senderRole: "buyer" | "seller";
     sentAt: string | Date | z.objectOutputType<{
         toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
     }, z.ZodTypeAny, "passthrough">;
@@ -31,7 +31,7 @@ export declare const conversationMessageSchema: z.ZodObject<{
     body: string;
     isRead: boolean;
     senderId: string;
-    senderRole: "seller" | "buyer";
+    senderRole: "buyer" | "seller";
     sentAt: string | Date | z.objectInputType<{
         toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
     }, z.ZodTypeAny, "passthrough">;
@@ -79,7 +79,7 @@ export declare const conversationFirestoreSchema: z.ZodObject<{
         body: string;
         isRead: boolean;
         senderId: string;
-        senderRole: "seller" | "buyer";
+        senderRole: "buyer" | "seller";
         sentAt: string | Date | z.objectOutputType<{
             toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
         }, z.ZodTypeAny, "passthrough">;
@@ -89,7 +89,7 @@ export declare const conversationFirestoreSchema: z.ZodObject<{
         body: string;
         isRead: boolean;
         senderId: string;
-        senderRole: "seller" | "buyer";
+        senderRole: "buyer" | "seller";
         sentAt: string | Date | z.objectInputType<{
             toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
         }, z.ZodTypeAny, "passthrough">;
@@ -127,7 +127,7 @@ export declare const conversationFirestoreSchema: z.ZodObject<{
         body: string;
         isRead: boolean;
         senderId: string;
-        senderRole: "seller" | "buyer";
+        senderRole: "buyer" | "seller";
         sentAt: string | Date | z.objectOutputType<{
             toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
         }, z.ZodTypeAny, "passthrough">;
@@ -160,7 +160,7 @@ export declare const conversationFirestoreSchema: z.ZodObject<{
         body: string;
         isRead: boolean;
         senderId: string;
-        senderRole: "seller" | "buyer";
+        senderRole: "buyer" | "seller";
         sentAt: string | Date | z.objectInputType<{
             toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
         }, z.ZodTypeAny, "passthrough">;

package/dist/features/orders/schemas/index.d.ts

@@ -128,9 +128,9 @@ export declare const orderRefundEventSchema: z.ZodObject<{
     overrideReason: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     type: "full" | "partial";
+    reason: string;
     amount: number;
     refundId: string;
-    reason: string;
     refundedAt: string | Date | z.objectOutputType<{
         toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
     }, z.ZodTypeAny, "passthrough">;
@@ -143,9 +143,9 @@ export declare const orderRefundEventSchema: z.ZodObject<{
     overrideReason?: string | undefined;
 }, {
     type: "full" | "partial";
+    reason: string;
     amount: number;
     refundId: string;
-    reason: string;
     refundedAt: string | Date | z.objectInputType<{
         toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
     }, z.ZodTypeAny, "passthrough">;
@@ -168,14 +168,14 @@ export declare const appliedOrderDiscountSchema: z.ZodObject<{
     code: string;
     type: "auto" | "coupon" | "deal";
     discountAmount: number;
-    scope?: "admin" | "seller" | undefined;
+    scope?: "seller" | "admin" | undefined;
     storeId?: string | undefined;
     couponId?: string | undefined;
 }, {
     code: string;
     type: "auto" | "coupon" | "deal";
     discountAmount: number;
-    scope?: "admin" | "seller" | undefined;
+    scope?: "seller" | "admin" | undefined;
     storeId?: string | undefined;
     couponId?: string | undefined;
 }>;
@@ -326,14 +326,14 @@ export declare const orderFirestoreSchema: z.ZodObject<{
         code: string;
         type: "auto" | "coupon" | "deal";
         discountAmount: number;
-        scope?: "admin" | "seller" | undefined;
+        scope?: "seller" | "admin" | undefined;
         storeId?: string | undefined;
         couponId?: string | undefined;
     }, {
         code: string;
         type: "auto" | "coupon" | "deal";
         discountAmount: number;
-        scope?: "admin" | "seller" | undefined;
+        scope?: "seller" | "admin" | undefined;
         storeId?: string | undefined;
         couponId?: string | undefined;
     }>, "many">>;
@@ -464,9 +464,9 @@ export declare const orderFirestoreSchema: z.ZodObject<{
         overrideReason: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         type: "full" | "partial";
+        reason: string;
         amount: number;
         refundId: string;
-        reason: string;
         refundedAt: string | Date | z.objectOutputType<{
             toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
         }, z.ZodTypeAny, "passthrough">;
@@ -479,9 +479,9 @@ export declare const orderFirestoreSchema: z.ZodObject<{
         overrideReason?: string | undefined;
     }, {
         type: "full" | "partial";
+        reason: string;
         amount: number;
         refundId: string;
-        reason: string;
         refundedAt: string | Date | z.objectInputType<{
             toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
         }, z.ZodTypeAny, "passthrough">;
@@ -622,7 +622,7 @@ export declare const orderFirestoreSchema: z.ZodObject<{
         code: string;
         type: "auto" | "coupon" | "deal";
         discountAmount: number;
-        scope?: "admin" | "seller" | undefined;
+        scope?: "seller" | "admin" | undefined;
         storeId?: string | undefined;
         couponId?: string | undefined;
     }[] | undefined;
@@ -654,9 +654,9 @@ export declare const orderFirestoreSchema: z.ZodObject<{
     paymentBatchId?: string | undefined;
     refunds?: {
         type: "full" | "partial";
+        reason: string;
         amount: number;
         refundId: string;
-        reason: string;
         refundedAt: string | Date | z.objectOutputType<{
             toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
         }, z.ZodTypeAny, "passthrough">;
@@ -770,7 +770,7 @@ export declare const orderFirestoreSchema: z.ZodObject<{
         code: string;
         type: "auto" | "coupon" | "deal";
         discountAmount: number;
-        scope?: "admin" | "seller" | undefined;
+        scope?: "seller" | "admin" | undefined;
         storeId?: string | undefined;
         couponId?: string | undefined;
     }[] | undefined;
@@ -802,9 +802,9 @@ export declare const orderFirestoreSchema: z.ZodObject<{
     paymentBatchId?: string | undefined;
     refunds?: {
         type: "full" | "partial";
+        reason: string;
         amount: number;
         refundId: string;
-        reason: string;
         refundedAt: string | Date | z.objectInputType<{
             toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
         }, z.ZodTypeAny, "passthrough">;

package/dist/features/payments/repository/payout.repository.d.ts

@@ -7,6 +7,14 @@
 import { BaseRepository, parseSieveDateValue, type SieveModel, type FirebaseSieveResult } from "../../../providers/db-firebase";
 import type { DocumentReference, WriteResult } from "firebase-admin/firestore";
 import type { PayoutDocument, PayoutCreateInput, PayoutRefundDeduction, PayoutStatus, PayoutUpdateInput } from "../schemas";
+import { type HistoryActor } from "../../../_internal/shared/history/index";
+/** Who/why for a payout write that lands in `statusHistory`. */
+export interface PayoutWriteContext {
+    actor?: HistoryActor;
+    trigger?: string;
+    reason?: string;
+    note?: string;
+}
 export declare class PayoutRepository extends BaseRepository<PayoutDocument> {
     constructor();
     /** Decrypt PII fields on a payout document after Firestore read */
@@ -46,12 +54,17 @@ export declare class PayoutRepository extends BaseRepository<PayoutDocument> {
         data: PayoutDocument;
     }>>;
     /**
-     * Update payout status (admin action)
+     * Update payout status (admin action).
+     *
+     * `prior` keeps the timeline entry read-free — the admin route already
+     * fetches the payout to authorise the change (Rule #6).
      */
-    updateStatus(payoutId: string, status: PayoutStatus, extra?: PayoutUpdateInput): Promise<PayoutDocument>;
-    markProcessing(ref: DocumentReference): Promise<WriteResult>;
-    recordSuccess(ref: DocumentReference, razorpayPayoutId: string, razorpayStatus: string): Promise<WriteResult>;
-    recordFailure(ref: DocumentReference, failureCount: number, reason: string, isFinal: boolean): Promise<WriteResult>;
+    updateStatus(payoutId: string, status: PayoutStatus, extra?: PayoutUpdateInput, ctx?: PayoutWriteContext, prior?: PayoutDocument | null): Promise<PayoutDocument>;
+    markProcessing(ref: DocumentReference, ctx?: PayoutWriteContext, prior?: PayoutDocument | null): Promise<WriteResult>;
+    recordSuccess(ref: DocumentReference, razorpayPayoutId: string, razorpayStatus: string, ctx?: PayoutWriteContext, prior?: PayoutDocument | null): Promise<WriteResult>;
+    recordFailure(ref: DocumentReference, failureCount: number, reason: string, isFinal: boolean, ctx?: PayoutWriteContext, prior?: PayoutDocument | null): Promise<WriteResult>;
+    /** Append a timeline entry when the patch touches a tracked field. */
+    private withPayoutHistory;
     /**
      * Get all order IDs that have already been paid out for a seller.
      * Used to avoid double-paying the same orders.