@mohasinac/appkit 4.29.1 → 4.30.1

package/dist/_internal/client/features/layout/SidebarCollapseToggle.js

@@ -14,5 +14,5 @@ export function SidebarCollapseToggle({ expanded, onToggle, expandedLabel = "Col
     // Chevron rotation direction mirrors along with the dock side so it keeps
     // pointing "into" the collapsed panel regardless of which edge it's on.
     const chevronRotated = edge === "left" ? !expanded : expanded;
-    return (_jsx(IconButton, { type: "button", onClick: onToggle, "aria-label": expanded ? expandedLabel : collapsedLabel, "aria-expanded": expanded, variant: "ghost", style: HANDLE_STYLE, className: `w-9 shrink-0 ${roundedClass} shadow-lg transition-all duration-200 hover:shadow-xl hover:brightness-110 active:scale-[0.96]`, icon: _jsx("svg", { className: `w-4 h-4 drop-shadow-sm transition-transform duration-300 ${chevronRotated ? "rotate-180" : ""}`, style: CHEVRON_STYLE, fill: "none", stroke: "currentColor", viewBox: "0 0 24 24", "aria-hidden": "true", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", strokeWidth: 2.5, d: "M15 19l-7-7 7-7" }) }) }));
+    return (_jsx(IconButton, { type: "button", onClick: onToggle, "aria-label": expanded ? expandedLabel : collapsedLabel, "aria-expanded": expanded, variant: "ghost", style: HANDLE_STYLE, className: `w-9 shrink-0 ${roundedClass} shadow-lg transition-all duration-200 hover:shadow-xl hover:brightness-110 active:scale-[0.96]`, icon: _jsx("svg", { className: `w-4 h-4 drop-shadow-sm transition-transform duration-300 ${chevronRotated ? "rotate-180" : ""} shrink-0`, style: CHEVRON_STYLE, fill: "none", stroke: "currentColor", viewBox: "0 0 24 24", "aria-hidden": "true", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", strokeWidth: 2.5, d: "M15 19l-7-7 7-7" }) }) }));
 }

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

@@ -4,7 +4,7 @@ export declare const blogPostInputSchema: z.ZodObject<{
     slug: z.ZodString;
     excerpt: z.ZodOptional<z.ZodString>;
     content: z.ZodString;
-    coverImage: z.ZodOptional<z.ZodString>;
+    coverImage: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
     youtubeId: z.ZodOptional<z.ZodString>;
     category: z.ZodString;
     tags: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
@@ -44,7 +44,7 @@ export declare const blogPostUpdateSchema: z.ZodObject<Omit<{
     slug: z.ZodOptional<z.ZodString>;
     excerpt: z.ZodOptional<z.ZodOptional<z.ZodString>>;
     content: z.ZodOptional<z.ZodString>;
-    coverImage: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    coverImage: z.ZodOptional<z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>>;
     youtubeId: z.ZodOptional<z.ZodOptional<z.ZodString>>;
     category: z.ZodOptional<z.ZodString>;
     tags: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString, "many">>>;

package/dist/_internal/shared/features/blog/schema.js

@@ -1,11 +1,12 @@
 import { z } from "zod";
 import { BLOG_TITLE_MAX_LENGTH, BLOG_EXCERPT_MAX_LENGTH } from "./config";
+import { mediaUrlSchema } from "../../../../validation/schemas";
 export const blogPostInputSchema = z.object({
     title: z.string().min(3).max(BLOG_TITLE_MAX_LENGTH),
     slug: z.string().min(1).regex(/^blog-[a-z0-9-]+$/, "Slug must start with 'blog-'"),
     excerpt: z.string().max(BLOG_EXCERPT_MAX_LENGTH).optional(),
     content: z.string().max(100000),
-    coverImage: z.string().url().optional(),
+    coverImage: mediaUrlSchema.optional(),
     youtubeId: z.string().optional(),
     category: z.string().min(1),
     tags: z.array(z.string()).max(10).default([]),

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

@@ -3,7 +3,7 @@ export declare const brandInputSchema: z.ZodObject<{
     name: z.ZodString;
     slug: z.ZodString;
     description: z.ZodOptional<z.ZodString>;
-    logoURL: z.ZodOptional<z.ZodString>;
+    logoURL: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
     website: z.ZodOptional<z.ZodString>;
     country: z.ZodOptional<z.ZodString>;
     founded: z.ZodOptional<z.ZodNumber>;
@@ -34,7 +34,7 @@ export declare const brandUpdateSchema: z.ZodObject<Omit<{
     name: z.ZodOptional<z.ZodString>;
     slug: z.ZodOptional<z.ZodString>;
     description: z.ZodOptional<z.ZodOptional<z.ZodString>>;
-    logoURL: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    logoURL: z.ZodOptional<z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>>;
     website: z.ZodOptional<z.ZodOptional<z.ZodString>>;
     country: z.ZodOptional<z.ZodOptional<z.ZodString>>;
     founded: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;

package/dist/_internal/shared/features/brands/schema.js

@@ -1,10 +1,12 @@
 import { z } from "zod";
 import { BRAND_NAME_MAX_LENGTH, BRAND_DESCRIPTION_MAX_LENGTH } from "./config";
+import { mediaUrlSchema } from "../../../../validation/schemas";
 export const brandInputSchema = z.object({
     name: z.string().min(1).max(BRAND_NAME_MAX_LENGTH),
     slug: z.string().min(1).regex(/^brand-[a-z0-9-]+$/, "Slug must start with 'brand-' and contain only lowercase letters, numbers, and hyphens"),
     description: z.string().max(BRAND_DESCRIPTION_MAX_LENGTH).optional(),
-    logoURL: z.string().url().optional(),
+    logoURL: mediaUrlSchema.optional(),
+    // `website` is a genuine EXTERNAL link, not stored media — stays `.url()`.
     website: z.string().url().optional(),
     country: z.string().optional(),
     founded: z.number().int().min(1800).max(new Date().getFullYear()).optional(),

package/dist/_internal/shared/features/categories/bundle-schemas.d.ts

@@ -60,7 +60,7 @@ export declare const bundleQueryRuleSchema: z.ZodDiscriminatedUnion<"type", [z.Z
     orderBy?: "price-asc" | "price-desc" | "createdAt-desc" | undefined;
 }>]>;
 export declare const bundleDisplaySchema: z.ZodObject<{
-    coverImage: z.ZodOptional<z.ZodString>;
+    coverImage: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
     icon: z.ZodOptional<z.ZodString>;
     color: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
@@ -148,7 +148,7 @@ export declare const bundleCreateSchema: z.ZodObject<{
         drawCount?: number | undefined;
     }>, "many">>;
     display: z.ZodOptional<z.ZodObject<{
-        coverImage: z.ZodOptional<z.ZodString>;
+        coverImage: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
         icon: z.ZodOptional<z.ZodString>;
         color: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
@@ -295,7 +295,7 @@ export declare const bundleUpdateSchema: z.ZodObject<{
         drawCount?: number | undefined;
     }>, "many">>;
     display: z.ZodOptional<z.ZodObject<{
-        coverImage: z.ZodOptional<z.ZodString>;
+        coverImage: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
         icon: z.ZodOptional<z.ZodString>;
         color: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {

package/dist/_internal/shared/features/categories/bundle-schemas.js

@@ -9,6 +9,7 @@
  */
 import { z } from "zod";
 import { BUNDLE_MAX_ITEMS, BUNDLE_DRAW_COUNT_MAX, BUNDLE_KIND_SPECIAL, BUNDLE_KIND_BRAND, } from "./bundle-config";
+import { mediaUrlSchema } from "../../../../validation/schemas";
 const productIdsSchema = z.array(z.string().min(1)).min(0).max(BUNDLE_MAX_ITEMS);
 /**
  * Per-member detail — mirrors BundleItemDetail in the Firestore schema.
@@ -39,7 +40,7 @@ export const bundleQueryRuleSchema = z.discriminatedUnion("type", [
     }),
 ]);
 export const bundleDisplaySchema = z.object({
-    coverImage: z.string().url().optional(),
+    coverImage: mediaUrlSchema.optional(),
     icon: z.string().optional(),
     color: z.string().optional(),
 });

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

@@ -8,7 +8,7 @@ export declare const eventInputSchema: z.ZodObject<{
     startsAt: z.ZodString;
     endsAt: z.ZodString;
     maxEntries: z.ZodOptional<z.ZodNumber>;
-    imageUrl: z.ZodOptional<z.ZodString>;
+    imageUrl: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
     location: z.ZodOptional<z.ZodString>;
     isOnline: z.ZodDefault<z.ZodBoolean>;
     entryFee: z.ZodDefault<z.ZodNumber>;
@@ -48,7 +48,7 @@ export declare const eventUpdateSchema: z.ZodObject<Omit<{
     startsAt: z.ZodOptional<z.ZodString>;
     endsAt: z.ZodOptional<z.ZodString>;
     maxEntries: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
-    imageUrl: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    imageUrl: z.ZodOptional<z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>>;
     location: z.ZodOptional<z.ZodOptional<z.ZodString>>;
     isOnline: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
     entryFee: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;

package/dist/_internal/shared/features/events/schema.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { EVENT_TITLE_MAX_LENGTH, EVENT_DESCRIPTION_MAX_LENGTH } from "./config";
+import { mediaUrlSchema } from "../../../../validation/schemas";
 export const eventInputSchema = z.object({
     title: z.string().min(3).max(EVENT_TITLE_MAX_LENGTH),
     slug: z.string().min(1).regex(/^event-[a-z0-9-]+$/, "Slug must start with 'event-'"),
@@ -9,7 +10,7 @@ export const eventInputSchema = z.object({
     startsAt: z.string().datetime({ offset: true }),
     endsAt: z.string().datetime({ offset: true }),
     maxEntries: z.number().int().min(1).optional(),
-    imageUrl: z.string().url().optional(),
+    imageUrl: mediaUrlSchema.optional(),
     location: z.string().max(300).optional(),
     isOnline: z.boolean().default(false),
     entryFee: z.number().min(0).default(0),

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

@@ -8,8 +8,8 @@ export declare const productInputSchema: z.ZodObject<{
     currency: z.ZodDefault<z.ZodString>;
     stockQuantity: z.ZodDefault<z.ZodNumber>;
     availableQuantity: z.ZodDefault<z.ZodNumber>;
-    mainImage: z.ZodString;
-    images: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    mainImage: z.ZodEffects<z.ZodString, string, string>;
+    images: z.ZodDefault<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
     condition: z.ZodOptional<z.ZodEnum<["new", "like_new", "good", "fair", "poor", "used", "refurbished", "broken"]>>;
     tags: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
     seoTitle: z.ZodOptional<z.ZodString>;
@@ -81,8 +81,8 @@ export declare const productUpdateSchema: z.ZodObject<{
     currency: z.ZodOptional<z.ZodDefault<z.ZodString>>;
     stockQuantity: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
     availableQuantity: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
-    mainImage: z.ZodOptional<z.ZodString>;
-    images: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString, "many">>>;
+    mainImage: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    images: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>>;
     condition: z.ZodOptional<z.ZodOptional<z.ZodEnum<["new", "like_new", "good", "fair", "poor", "used", "refurbished", "broken"]>>>;
     tags: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString, "many">>>;
     seoTitle: z.ZodOptional<z.ZodOptional<z.ZodString>>;
@@ -154,8 +154,8 @@ export declare const auctionInputSchema: z.ZodObject<{
     currency: z.ZodDefault<z.ZodString>;
     stockQuantity: z.ZodDefault<z.ZodNumber>;
     availableQuantity: z.ZodDefault<z.ZodNumber>;
-    mainImage: z.ZodString;
-    images: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    mainImage: z.ZodEffects<z.ZodString, string, string>;
+    images: z.ZodDefault<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
     condition: z.ZodOptional<z.ZodEnum<["new", "like_new", "good", "fair", "poor", "used", "refurbished", "broken"]>>;
     tags: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
     seoTitle: z.ZodOptional<z.ZodString>;
@@ -255,8 +255,8 @@ export declare const preOrderInputSchema: z.ZodObject<{
     currency: z.ZodDefault<z.ZodString>;
     stockQuantity: z.ZodDefault<z.ZodNumber>;
     availableQuantity: z.ZodDefault<z.ZodNumber>;
-    mainImage: z.ZodString;
-    images: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    mainImage: z.ZodEffects<z.ZodString, string, string>;
+    images: z.ZodDefault<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
     condition: z.ZodOptional<z.ZodEnum<["new", "like_new", "good", "fair", "poor", "used", "refurbished", "broken"]>>;
     tags: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
     seoTitle: z.ZodOptional<z.ZodString>;

package/dist/_internal/shared/features/products/schema.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { mediaUrlSchema } from "../../../../validation/schemas";
 const priceSchema = z.number().min(0, "Price must be non-negative");
 const conditionSchema = z.enum(["new", "like_new", "good", "fair", "poor", "used", "refurbished", "broken"]);
 export const productInputSchema = z.object({
@@ -10,8 +11,8 @@ export const productInputSchema = z.object({
     currency: z.string().default("INR"),
     stockQuantity: z.number().int().min(0).default(0),
     availableQuantity: z.number().int().min(0).default(0),
-    mainImage: z.string().url("mainImage must be a valid URL"),
-    images: z.array(z.string().url()).max(20).default([]),
+    mainImage: mediaUrlSchema,
+    images: z.array(mediaUrlSchema).max(20).default([]),
     condition: conditionSchema.optional(),
     tags: z.array(z.string()).max(20).default([]),
     seoTitle: z.string().max(70).optional(),

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

@@ -5,7 +5,7 @@ export declare const createReviewSchema: z.ZodObject<{
     rating: z.ZodNumber;
     title: z.ZodString;
     comment: z.ZodString;
-    images: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    images: z.ZodDefault<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
     orderId: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     title: string;

package/dist/_internal/shared/features/reviews/schema.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { mediaUrlSchema } from "../../../../validation/schemas";
 import { REVIEW_BODY_MAX_LENGTH, REVIEW_BODY_MIN_LENGTH, REVIEW_TITLE_MAX_LENGTH, REVIEW_MIN_RATING, REVIEW_MAX_RATING, REVIEW_IMAGES_MAX, REVIEW_REPLY_MAX_LENGTH, } from "./config";
 export const createReviewSchema = z.object({
     productId: z.string().min(1),
@@ -16,7 +17,7 @@ export const createReviewSchema = z.object({
      * never consulted it.
      */
     comment: z.string().min(REVIEW_BODY_MIN_LENGTH).max(REVIEW_BODY_MAX_LENGTH),
-    images: z.array(z.string().url()).max(REVIEW_IMAGES_MAX).default([]),
+    images: z.array(mediaUrlSchema).max(REVIEW_IMAGES_MAX).default([]),
     orderId: z.string().optional(),
 });
 export const replyToReviewSchema = z.object({

package/dist/_internal/shared/types/action-result.d.ts

@@ -14,8 +14,6 @@ export type ActionResult<T> = {
     code?: string;
     error: string;
     issues?: unknown[];
-    /** Legacy server-action shape — kept for compat. */
-    fieldErrors?: Record<string, string[]>;
     /** Legacy debug field — only populated in dev. */
     debug?: {
         stack?: string;

package/dist/client/api/surface-error.d.ts

@@ -18,6 +18,15 @@ export interface SurfaceErrorOptions {
     setFieldError?: (field: string, message: string) => void;
     /** next-intl style translator. Falls back to the raw error message when undefined. */
     translate?: (key: string) => string;
+    /**
+     * Curated copy preferred over `err.message` when the error carries no
+     * mapped display message. Lets a caller keep wording better than the raw
+     * server string WITHOUT adding a second toast of its own.
+     *
+     * Never overrides field-level `issues` — those are more specific than any
+     * caller-supplied sentence.
+     */
+    fallbackMessage?: string;
     /** Optional reporter for the clientErrors / serverErrors collection. */
     report?: (payload: {
         code: string;

package/dist/client/api/surface-error.js

@@ -1,5 +1,6 @@
 import { isApiError } from "./ApiError";
 import { ApiClientError } from "../../http/ApiClient";
+import { applyZodIssues, hasAttachableIssue } from "../../ui/forms/apply-zod-issues";
 import { normalizeError } from "../../errors/normalize";
 import { getErrorDisplay } from "../../errors/error-display-map";
 /** True for `ApiError` instances and for `ApiClientError` (the lower-level
@@ -9,11 +10,36 @@ import { getErrorDisplay } from "../../errors/error-display-map";
 function hasStableErrorCode(err) {
     return isApiError(err) || (err instanceof ApiClientError && typeof err.code === "string");
 }
+/** Field-level issues carried by either error shape, when present. */
+function issuesOf(err) {
+    if (isApiError(err))
+        return err.issues;
+    if (err instanceof ApiClientError)
+        return err.issues;
+    return undefined;
+}
 export function surfaceError(err, opts) {
-    const { showToast, setFieldError, translate, report } = opts;
+    const { showToast, setFieldError, translate, report, fallbackMessage } = opts;
+    // ISSUES FIRST. A validation failure names the fields it is about, and the
+    // right place for "photoURL must be …" is under the photoURL input — not a
+    // toast that says "Validation failed" and nothing else.
+    //
+    // This branch could not fire before: `errorResponse` serialised Zod issues
+    // under a `details` key that `ApiClientError` never read, so `err.issues`
+    // was always undefined and every schema rejection on every route fell
+    // through to the generic toast below.
+    //
+    // `ERROR_DISPLAY_MAP` deliberately has no `field` for VALIDATION_FAILED —
+    // a validation failure is not tied to one fixed field, which is exactly why
+    // the routing has to come from the issues themselves.
+    const issues = issuesOf(err);
+    if (setFieldError && hasAttachableIssue(issues)) {
+        applyZodIssues(issues, (name, message) => setFieldError(name, message ?? ""));
+        return; // inline errors only — no toast
+    }
     if (hasStableErrorCode(err)) {
         const display = getErrorDisplay(err.code);
-        const message = translate?.(display.messageKey) ?? err.message;
+        const message = translate?.(display.messageKey) ?? fallbackMessage ?? err.message;
         if (display.field && setFieldError) {
             setFieldError(display.field, message);
             return;
@@ -24,7 +50,7 @@ export function surfaceError(err, opts) {
     // Non-ApiError — this is a programming error or unhandled exception.
     // Report it (workstream 13) so clientErrors picks it up.
     const message = err instanceof Error ? err.message : "Something went wrong. Please try again.";
-    const fallback = translate?.("errors.codes.CLIENT_UNHANDLED") ?? message;
+    const fallback = fallbackMessage ?? translate?.("errors.codes.CLIENT_UNHANDLED") ?? message;
     showToast(fallback, "error");
     if (report) {
         try {

package/dist/client/api/useApiMutation.d.ts

@@ -16,6 +16,16 @@ export interface UseApiMutationOptions<TData, TError, TVariables, TContext> exte
     /** When set, a `loading` toast is shown on mutate and finalized on settle. */
     loadingMessage?: string;
     successMessage?: string;
+    /**
+     * Curated failure copy, preferred over `err.message` by the ONE surface.
+     *
+     * Exists so a caller with wording better than the raw server message
+     * ("Could not mark notification as read.") does not have to add a second
+     * toast in its own `onError` to say it — which is what produced two and
+     * three stacked banners for a single failure. A server error that carries
+     * field `issues` still wins: those route to inline field errors.
+     */
+    errorMessage?: string;
     /** Translation function (next-intl style); falls back to raw message. */
     translate?: (key: string) => string;
     /** Form field error setter (FormShell context). Optional. */

package/dist/client/api/useApiMutation.js

@@ -6,7 +6,7 @@ import { surfaceError } from "./surface-error";
 export function useApiMutation(options) {
     const { showToast, updateToast } = useToast();
     const loadingIdRef = React.useRef(null);
-    const { loadingMessage, successMessage, translate, setFieldError, reportClientError, onMutate, onError, onSuccess, onSettled, ...rest } = options;
+    const { loadingMessage, successMessage, errorMessage, translate, setFieldError, reportClientError, onMutate, onError, onSuccess, onSettled, ...rest } = options;
     return useMutation({
         ...rest,
         onMutate: (async (variables, ctx) => {
@@ -20,6 +20,7 @@ export function useApiMutation(options) {
                 showToast,
                 setFieldError,
                 translate,
+                fallbackMessage: errorMessage,
                 report: reportClientError,
             });
             onError?.(err, variables, context, ctx);

package/dist/core/server-action.d.ts

@@ -1,15 +1,5 @@
-export type ActionResult<TOutput> = {
-    ok: true;
-    data: TOutput;
-} | {
-    ok: false;
-    error: string;
-    code?: string;
-    fieldErrors?: Record<string, string[]>;
-    debug?: {
-        stack?: string;
-    };
-};
+export type { ActionResult } from "../_internal/shared/types/action-result";
+import type { ActionResult } from "../_internal/shared/types/action-result";
 export interface ActionMiddlewareContext<TInput = unknown, TOutput = unknown> {
     actionName: string;
     input: TInput;
@@ -50,7 +40,7 @@ export interface ServerActionOptions<TInput, TOutput> {
     name?: string;
     /**
      * Zod-compatible schema for input validation.
-     * If validation fails, returns `{ ok: false, fieldErrors }` before the handler runs.
+     * If validation fails, returns `{ ok: false, issues }` before the handler runs.
      */
     schema?: SafeParseSchema<TInput>;
     /**
@@ -79,4 +69,3 @@ export interface ServerActionOptions<TInput, TOutput> {
  * and can be exported directly from an `actions/` file.
  */
 export declare function createServerAction<TInput = unknown, TOutput = unknown>(options: ServerActionOptions<TInput, TOutput>): (rawInput: TInput) => Promise<ActionResult<TOutput>>;
-export {};

package/dist/core/server-action.js

@@ -1,4 +1,6 @@
 import { normalizeError } from "../errors/normalize";
+import { toApiIssues } from "../errors/error-envelope";
+import { HTTP_ERROR_CODES } from "../errors/error-mapping";
 /**
  * createServerAction — @mohasinac/appkit/core
  *
@@ -65,8 +67,15 @@ export function createServerAction(options) {
         if (options.schema) {
             const parsed = options.schema.safeParse(rawInput);
             if (!parsed.success) {
-                const fieldErrors = parsed.error.flatten?.().fieldErrors ?? {};
-                return { ok: false, error: "Validation failed", fieldErrors };
+                // `issues` (not the old `fieldErrors`, which had zero readers) so a
+                // server action's validation failure routes to inline field errors
+                // through the same path an HTTP route's does.
+                return {
+                    ok: false,
+                    error: "Validation failed",
+                    code: HTTP_ERROR_CODES.VALIDATION_FAILED,
+                    issues: toApiIssues(parsed.error.issues),
+                };
             }
             input = parsed.data;
         }

package/dist/errors/error-envelope.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The ONE shape of an HTTP error body.
+ *
+ * WHY THIS FILE EXISTS
+ * --------------------
+ * There were four independent producers of an error response, and the client
+ * read a shape none of them fully emitted:
+ *
+ *   - `next/api/api-response.ts`  → `{success, error, details}`  — no `code`
+ *   - `next/api/routeHandler.ts`  → `{ok, success, code, error, issues, requestId}`
+ *   - `errors/error-handler.ts`   → `{..., data: {issues}}`      — issues nested
+ *   - `core/server-action.ts`     → `{ok, error, fieldErrors}`
+ *
+ * while `http/ApiClient.ts`'s `ApiClientError` reads exactly three keys off the
+ * body: `code`, `issues`, `requestId`.
+ *
+ * The consequence was silent and app-wide. On every route built with
+ * `createApiHandler`, a Zod rejection serialised its issues under `details`,
+ * which nothing reads — so `err.code` was `undefined`, `surfaceError`'s
+ * `hasStableErrorCode()` check failed, the `ERROR_DISPLAY_MAP` branch was
+ * skipped, and the user got a bare toast reading "Validation failed" with no
+ * field name. `applyZodIssues(err.issues, …)` was dead code everywhere.
+ *
+ * Every producer now builds its body here, so the wire shape and the reader
+ * cannot drift again. `scripts/audit-api-error-envelope.mjs` enforces it in
+ * both directions.
+ */
+import type { ApiIssue } from "../client/api/ApiError";
+export interface ApiErrorEnvelope {
+    ok: false;
+    /**
+     * @deprecated Mirrors `ok` for consumers that still read `body.success`.
+     * `audit-server-action-envelope.mjs` is designed to start failing once the
+     * last reader is gone, at which point this key is removed.
+     */
+    success: false;
+    code: string;
+    error: string;
+    issues?: ApiIssue[];
+    requestId?: string;
+}
+/**
+ * Default stable code for an HTTP status, for producers that don't carry one.
+ *
+ * Mirrors the mapping already applied in `mapToHttpError`'s status branch —
+ * extracted so there is one table rather than two that can disagree about
+ * what a 409 is called.
+ */
+export declare function codeForStatus(status: number): string;
+/**
+ * Narrow raw Zod issues to the wire shape.
+ *
+ * Deliberately picks ONLY `path`, `message` and `code`. A `ZodIssue` can also
+ * carry `received` / `expected` / `unionErrors`, and `received` is the value
+ * the user actually submitted — i.e. potentially their email, phone or
+ * address. Spreading the issue wholesale would publish that in an error body
+ * and into any client-error log that captures it.
+ *
+ * The `unknown` parameter is the point: this is the sole entry point for issue
+ * arrays arriving from THREE mutually unassignable sources — zod v3
+ * `ZodIssue[]` (appkit), zod v4 `$ZodIssue[]` (the consumer app, a different
+ * major), and the `unknown[]` that `mapToHttpError` already returns. Narrowing
+ * it to any one of them makes the other two uncallable. This function exists
+ * precisely to be the place that narrows.
+ */
+export declare function toApiIssues(input: unknown): ApiIssue[] | undefined;
+export declare function buildErrorEnvelope(input: {
+    message: string;
+    status?: number;
+    code?: string;
+    issues?: ApiIssue[];
+    requestId?: string;
+}): ApiErrorEnvelope;

package/dist/errors/error-envelope.js

@@ -0,0 +1,96 @@
+/**
+ * The ONE shape of an HTTP error body.
+ *
+ * WHY THIS FILE EXISTS
+ * --------------------
+ * There were four independent producers of an error response, and the client
+ * read a shape none of them fully emitted:
+ *
+ *   - `next/api/api-response.ts`  → `{success, error, details}`  — no `code`
+ *   - `next/api/routeHandler.ts`  → `{ok, success, code, error, issues, requestId}`
+ *   - `errors/error-handler.ts`   → `{..., data: {issues}}`      — issues nested
+ *   - `core/server-action.ts`     → `{ok, error, fieldErrors}`
+ *
+ * while `http/ApiClient.ts`'s `ApiClientError` reads exactly three keys off the
+ * body: `code`, `issues`, `requestId`.
+ *
+ * The consequence was silent and app-wide. On every route built with
+ * `createApiHandler`, a Zod rejection serialised its issues under `details`,
+ * which nothing reads — so `err.code` was `undefined`, `surfaceError`'s
+ * `hasStableErrorCode()` check failed, the `ERROR_DISPLAY_MAP` branch was
+ * skipped, and the user got a bare toast reading "Validation failed" with no
+ * field name. `applyZodIssues(err.issues, …)` was dead code everywhere.
+ *
+ * Every producer now builds its body here, so the wire shape and the reader
+ * cannot drift again. `scripts/audit-api-error-envelope.mjs` enforces it in
+ * both directions.
+ */
+import { HTTP_ERROR_CODES } from "./error-mapping";
+/**
+ * Default stable code for an HTTP status, for producers that don't carry one.
+ *
+ * Mirrors the mapping already applied in `mapToHttpError`'s status branch —
+ * extracted so there is one table rather than two that can disagree about
+ * what a 409 is called.
+ */
+export function codeForStatus(status) {
+    if (status === 401)
+        return HTTP_ERROR_CODES.UNAUTHENTICATED;
+    if (status === 403)
+        return HTTP_ERROR_CODES.FORBIDDEN;
+    if (status === 404)
+        return HTTP_ERROR_CODES.NOT_FOUND;
+    if (status === 409)
+        return HTTP_ERROR_CODES.ALREADY_EXISTS;
+    if (status === 429)
+        return HTTP_ERROR_CODES.RATE_LIMITED;
+    if (status >= 500)
+        return HTTP_ERROR_CODES.INTERNAL;
+    return HTTP_ERROR_CODES.VALIDATION_FAILED;
+}
+/**
+ * Narrow raw Zod issues to the wire shape.
+ *
+ * Deliberately picks ONLY `path`, `message` and `code`. A `ZodIssue` can also
+ * carry `received` / `expected` / `unionErrors`, and `received` is the value
+ * the user actually submitted — i.e. potentially their email, phone or
+ * address. Spreading the issue wholesale would publish that in an error body
+ * and into any client-error log that captures it.
+ *
+ * The `unknown` parameter is the point: this is the sole entry point for issue
+ * arrays arriving from THREE mutually unassignable sources — zod v3
+ * `ZodIssue[]` (appkit), zod v4 `$ZodIssue[]` (the consumer app, a different
+ * major), and the `unknown[]` that `mapToHttpError` already returns. Narrowing
+ * it to any one of them makes the other two uncallable. This function exists
+ * precisely to be the place that narrows.
+ */
+export function toApiIssues(input) {
+    if (!Array.isArray(input) || input.length === 0)
+        return undefined;
+    const mapped = [];
+    for (const raw of input) {
+        if (typeof raw !== "object" || raw === null)
+            continue;
+        const issue = raw;
+        if (typeof issue.message !== "string")
+            continue;
+        mapped.push({
+            message: issue.message,
+            ...(Array.isArray(issue.path)
+                ? { path: issue.path.filter((p) => typeof p === "string" || typeof p === "number") }
+                : {}),
+            ...(typeof issue.code === "string" ? { code: issue.code } : {}),
+        });
+    }
+    return mapped.length ? mapped : undefined;
+}
+export function buildErrorEnvelope(input) {
+    return {
+        ok: false,
+        success: false,
+        code: input.code ?? codeForStatus(input.status ?? 400),
+        error: input.message,
+        ...(input.issues?.length ? { issues: input.issues } : {}),
+        ...(input.requestId ? { requestId: input.requestId } : {}),
+    };
+}

package/dist/errors/error-handler.js

@@ -1,6 +1,7 @@
 import { NextResponse } from "next/server.js";
 import { AppError } from "./base-error";
 import { mapToHttpError } from "./error-mapping";
+import { buildErrorEnvelope, toApiIssues } from "./error-envelope";
 /**
  * Handle API errors with consistent response format.
  * Use in Next.js API route catch blocks.
@@ -23,16 +24,22 @@ export function handleApiError(error) {
             data: error instanceof AppError ? error.data : undefined,
         });
     }
+    // `issues` go at the TOP LEVEL. They used to be nested under
+    // `data.issues`, and `ApiClientError` reads `body.issues` — so this
+    // producer's field errors were as dead as `api-response.ts`'s were.
+    //
+    // `statusCode` is dropped: it only ever duplicated the HTTP status, and
+    // nothing read it off the body.
     return NextResponse.json({
-        success: false,
-        error: mapped.message,
-        code: mapped.code,
-        statusCode: mapped.status,
+        ...buildErrorEnvelope({
+            message: mapped.message,
+            status: mapped.status,
+            code: mapped.code,
+            issues: toApiIssues(mapped.issues),
+        }),
         ...(error instanceof AppError && error.data !== undefined
             ? { data: error.data }
-            : mapped.issues
-                ? { data: { issues: mapped.issues } }
-                : {}),
+            : {}),
     }, { status: mapped.status });
 }
 /**

package/dist/features/account/components/NotificationBell.js

@@ -96,7 +96,7 @@ export function NotificationBell({ limit = 10, viewAllHref, labels, icons, rende
 }
 function renderBellButton(props) {
     const { hideOnMobile, buttonClassName, labels, unreadCount, handleToggle, isOpen } = props;
-    return (_jsxs(Button, { onClick: handleToggle, rounded: "xl", className: `${hideOnMobile ? "hidden md:flex" : "flex"} p-[0.625rem] md:p-[0.75rem] transition-colors relative text-[var(--appkit-color-text-muted)] hover:bg-[var(--appkit-color-bg)] hover:text-[var(--appkit-color-text)] ${buttonClassName}`, "aria-label": labels.title, "aria-expanded": isOpen, children: [_jsx("svg", { className: "w-6 h-6 md:w-7 md:h-7", fill: "none", stroke: "currentColor", viewBox: "0 0 24 24", "aria-hidden": "true", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", strokeWidth: 2, d: "M15 17h5l-1.405-1.405A2.032 2.032 0 0118 14.158V11a6.002 6.002 0 00-4-5.659V5a2 2 0 10-4 0v.341C7.67 6.165 6 8.388 6 11v3.159c0 .538-.214 1.055-.595 1.436L4 17h5m6 0v1a3 3 0 11-6 0v-1m6 0H9" }) }), unreadCount > 0 && (_jsx(Span, { size: "xs", weight: "semibold", className: CLS_UNREAD_BADGE, children: unreadCount > 99 ? "99+" : unreadCount }))] }));
+    return (_jsxs(Button, { onClick: handleToggle, rounded: "xl", className: `${hideOnMobile ? "hidden md:flex" : "flex"} p-[0.625rem] md:p-[0.75rem] transition-colors relative text-[var(--appkit-color-text-muted)] hover:bg-[var(--appkit-color-bg)] hover:text-[var(--appkit-color-text)] ${buttonClassName}`, "aria-label": labels.title, "aria-expanded": isOpen, children: [_jsx("svg", { className: "w-6 h-6 md:w-7 md:h-7 shrink-0", fill: "none", stroke: "currentColor", viewBox: "0 0 24 24", "aria-hidden": "true", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", strokeWidth: 2, d: "M15 17h5l-1.405-1.405A2.032 2.032 0 0118 14.158V11a6.002 6.002 0 00-4-5.659V5a2 2 0 10-4 0v.341C7.67 6.165 6 8.388 6 11v3.159c0 .538-.214 1.055-.595 1.436L4 17h5m6 0v1a3 3 0 11-6 0v-1m6 0H9" }) }), unreadCount > 0 && (_jsx(Span, { size: "xs", weight: "semibold", className: CLS_UNREAD_BADGE, children: unreadCount > 99 ? "99+" : unreadCount }))] }));
 }
 function renderNotificationDropdown(props) {
     const { dropdownClassName, labels, unreadCount, isMarkingAll, handleMarkAllRead, isLoading, notifications, notificationIcons, handleMarkRead, handleMarkReadAndClose, renderActionLink, viewAllHref, setIsOpen } = props;