@mohasinac/appkit 2.8.9 → 3.0.0

package/dist/monitoring/analytics.js

@@ -1,3 +1,4 @@
+import { normalizeError } from "../errors/normalize";
 import { getAnalytics, isSupported, logEvent, setUserId, setUserProperties, } from "firebase/analytics";
 import { logger } from "../core/Logger";
 let analytics = null;
@@ -30,6 +31,7 @@ export async function initializeAnalytics(params) {
         analytics = getAnalytics(params.app);
     }
     catch (error) {
+        void normalizeError(error);
         analytics = null;
         logger.warn("Firebase Analytics disabled", { error });
     }
@@ -41,6 +43,7 @@ export const trackEvent = (eventName, eventParams) => {
         logEvent(analytics, eventName, eventParams);
     }
     catch (error) {
+        void normalizeError(error);
         logger.error(`Failed to log event ${eventName}`, { error });
     }
 };
@@ -51,6 +54,7 @@ export const setAnalyticsUserId = (userId) => {
         setUserId(analytics, userId);
     }
     catch (error) {
+        void normalizeError(error);
         logger.error("Failed to set user ID", { error });
     }
 };
@@ -61,6 +65,7 @@ export const setAnalyticsUserProperties = (properties) => {
         setUserProperties(analytics, properties);
     }
     catch (error) {
+        void normalizeError(error);
         logger.error("Failed to set user properties", { error });
     }
 };

package/dist/monitoring/client-logger.d.ts

@@ -6,6 +6,7 @@
  *
  * For server-side logging use `server-logger.ts`.
  */
+import type { FirestoreValue, JsonValue } from "../schemas/types";
 export interface ClientErrorContext {
     userId?: string;
     component?: string;
@@ -13,14 +14,14 @@ export interface ClientErrorContext {
     url?: string;
     method?: string;
     statusCode?: number;
-    [key: string]: unknown;
+    [key: string]: FirestoreValue;
 }
 export declare const logClientError: (message: string, error: unknown, context?: ClientErrorContext) => void;
 export declare const logClientWarning: (message: string, data?: ClientErrorContext) => void;
 export declare const logClientInfo: (message: string, data?: ClientErrorContext) => void;
 export declare const logClientDebug: (message: string, data?: ClientErrorContext) => void;
 export declare const logApiError: (endpoint: string, response: Response, context?: ClientErrorContext) => Promise<void>;
-export declare const logValidationError: (formName: string, errors: Record<string, unknown>, context?: ClientErrorContext) => void;
+export declare const logValidationError: (formName: string, errors: Record<string, JsonValue>, context?: ClientErrorContext) => void;
 export declare const logNavigationError: (route: string, error: unknown, context?: ClientErrorContext) => void;
 export declare const logAuthError: (operation: string, error: unknown, context?: ClientErrorContext) => void;
 export declare const logUploadError: (fileName: string, error: unknown, context?: ClientErrorContext) => void;

package/dist/monitoring/client-logger.js

@@ -8,7 +8,9 @@
  */
 import { logger } from "../core/Logger";
 import { AppError } from "../errors";
-function buildClientMeta(error, context) {
+function buildClientMeta(
+// audit-unknown-ok: error-handler entry point — accepts thrown values of any shape
+error, context) {
     const base = {
         ...context,
         timestamp: new Date().toISOString(),
@@ -21,22 +23,29 @@ function buildClientMeta(error, context) {
             message: error.message,
             code: error.code,
             statusCode: error.statusCode,
-            data: error.data,
+            data: error.data === undefined || error.data === null
+                ? null
+                : JSON.parse(JSON.stringify(error.data)),
         };
     }
     else if (error instanceof Error) {
         base.error = {
             name: error.name,
             message: error.message,
-            stack: error.stack,
+            stack: error.stack ?? null,
         };
     }
     else {
-        base.error = error;
+        base.error = typeof error === "string" || typeof error === "number" ||
+            typeof error === "boolean" || error === null || error === undefined
+            ? error
+            : JSON.stringify(error);
     }
     return base;
 }
-export const logClientError = (message, error, context) => {
+export const logClientError = (message, 
+// audit-unknown-ok: error-handler entry point — accepts thrown values of any shape
+error, context) => {
     logger.error(message, buildClientMeta(error, context));
 };
 export const logClientWarning = (message, data) => {
@@ -49,6 +58,7 @@ export const logClientDebug = (message, data) => {
     logger.debug(message, { ...data, timestamp: new Date().toISOString() });
 };
 export const logApiError = async (endpoint, response, context) => {
+    // audit-unknown-ok: client logger — accepts arbitrary serialisable values
     let responseBody;
     try {
         responseBody = await response.clone().json();
@@ -61,7 +71,7 @@ export const logApiError = async (endpoint, response, context) => {
         endpoint,
         status: response.status,
         statusText: response.statusText,
-        responseBody,
+        responseBody: typeof responseBody === "string" ? responseBody : JSON.stringify(responseBody),
     });
 };
 export const logValidationError = (formName, errors, context) => {
@@ -71,35 +81,45 @@ export const logValidationError = (formName, errors, context) => {
         validationErrors: errors,
     });
 };
-export const logNavigationError = (route, error, context) => {
+export const logNavigationError = (route, 
+// audit-unknown-ok: error-handler entry point — accepts thrown values of any shape
+error, context) => {
     logClientError(`Navigation error to ${route}`, error, {
         ...context,
         route,
         type: "navigation",
     });
 };
-export const logAuthError = (operation, error, context) => {
+export const logAuthError = (operation, 
+// audit-unknown-ok: error-handler entry point — accepts thrown values of any shape
+error, context) => {
     logClientError(`Authentication error: ${operation}`, error, {
         ...context,
         operation,
         type: "authentication",
     });
 };
-export const logUploadError = (fileName, error, context) => {
+export const logUploadError = (fileName, 
+// audit-unknown-ok: error-handler entry point — accepts thrown values of any shape
+error, context) => {
     logClientError(`File upload failed: ${fileName}`, error, {
         ...context,
         fileName,
         type: "upload",
     });
 };
-export const logPaymentError = (transactionId, error, context) => {
+export const logPaymentError = (transactionId, 
+// audit-unknown-ok: error-handler entry point — accepts thrown values of any shape
+error, context) => {
     logClientError(`Payment error: ${transactionId}`, error, {
         ...context,
         transactionId,
         type: "payment",
     });
 };
-export const logApplicationError = (category, message, error, context) => {
+export const logApplicationError = (category, message, 
+// audit-unknown-ok: error-handler entry point — accepts thrown values of any shape
+error, context) => {
     logClientError(`[${category}] ${message}`, error, {
         ...context,
         category,

package/dist/monitoring/error-tracking.d.ts

@@ -4,6 +4,7 @@
  * Implementations that require Firebase Crashlytics or external SDKs should
  * be wired in the app's monitoring setup by calling setErrorTracker().
  */
+import type { JsonValue } from "../schemas/types";
 export declare enum ErrorSeverity {
     LOW = "low",
     MEDIUM = "medium",
@@ -26,7 +27,7 @@ export interface ErrorContext {
     page?: string;
     component?: string;
     action?: string;
-    metadata?: Record<string, unknown>;
+    metadata?: Record<string, JsonValue>;
 }
 export interface TrackedError {
     message: string;

package/dist/monitoring/error-tracking.js

@@ -32,6 +32,7 @@ function getTracker() {
 }
 /** Override the default console-based tracker with a custom implementation. */
 export function setErrorTracker(fn) {
+    // audit-unknown-ok: observability adapter — global type augmentation
     globalThis[TRACKER_KEY] = fn;
 }
 export function trackError(error, category = ErrorCategory.UNKNOWN, severity = ErrorSeverity.MEDIUM, context) {

package/dist/monitoring/performance.js

@@ -11,6 +11,7 @@
 const PROVIDER_KEY = "__mohasinac_perf_provider__";
 /** Register a concrete performance backend (call once in instrumentation). */
 export function setPerformanceProvider(provider) {
+    // audit-unknown-ok: performance adapter — global type augmentation
     globalThis[PROVIDER_KEY] = provider;
 }
 function getProvider() {

package/dist/monitoring/server-logger.d.ts

@@ -1,3 +1,4 @@
+import type { FirestoreValue } from "../schemas/types";
 /**
  * Server-Side Error Logging Utilities
  *
@@ -15,7 +16,7 @@ export interface ServerErrorContext {
     method?: string;
     statusCode?: number;
     requestId?: string;
-    [key: string]: unknown;
+    [key: string]: FirestoreValue;
 }
 export declare const serverLogger: {
     debug(message: string, data?: unknown): void;

package/dist/monitoring/server-logger.js

@@ -1,13 +1,4 @@
-/**
- * Server-Side Error Logging Utilities
- *
- * Shared logger for API routes, server components, and server actions.
- * Attaches request metadata when a NextRequest is available and writes
- * structured log files in local environments.
- *
- * IMPORTANT: Only import this file in server-side code. For client-side code
- * use `client-logger.ts`.
- */
+import { normalizeError } from "../errors/normalize";
 import { redactPii } from "../security/pii-redact";
 import { AppError } from "../errors";
 // fs/path are Node.js built-ins that must NOT be imported at the top level.
@@ -15,17 +6,13 @@ import { AppError } from "../errors";
 // from the instrumentation hook, which is compiled for both Edge and Node.
 // Using require() calls inside functions keeps the imports out of the static
 // analysis graph and prevents Edge Runtime warnings.
-/* eslint-disable @typescript-eslint/no-require-imports */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
 function nodeRequire(id) { return require(id); }
 function nodeFsPromises() { return nodeRequire("fs/promises"); }
 function nodeFs() { return nodeRequire("fs"); }
 function nodePath() { return nodeRequire("path"); }
 // process.cwd() is a Node.js-only API. Access it through module.require so
 // Next.js Edge static analysis does not flag this file.
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
 function nodeCwd() { return module.require("process").cwd(); }
-/* eslint-enable @typescript-eslint/no-require-imports */
 function getLogsDir() {
     return nodePath().join(nodeCwd(), "logs");
 }
@@ -41,10 +28,22 @@ function serializeError(error) {
         serialized.stack = error.stack;
     }
     for (const [key, value] of Object.entries(error)) {
-        serialized[key] = value;
+        // Error custom properties are serialised via normalizeLogData downstream;
+        // FirestoreValue admits Date and JsonValue. Non-conforming values are
+        // dropped to "[unserializable]" placeholder.
+        serialized[key] =
+            value === null || value === undefined ||
+                typeof value === "string" || typeof value === "number" ||
+                typeof value === "boolean" || value instanceof Date
+                ? value
+                : JSON.stringify(value);
     }
     return serialized;
 }
+// audit-unknown-ok: this is the entry-point normaliser that accepts arbitrary
+// log-data payloads (Error, Date, primitive, object). Output is bounded by the
+// downstream JSON-stringify contract.
+// audit-unknown-ok: type-narrowing entry point — accepts any value, narrows by typeof/Array.isArray
 function normalizeLogData(data) {
     if (data instanceof Error)
         return serializeError(data);
@@ -75,10 +74,10 @@ function formatLogEntry(entry) {
     let dataStr = "";
     if (sanitized !== undefined) {
         try {
-            dataStr = `\n  Data: ${JSON.stringify(sanitized, null, 2)}`;
+            dataStr = `\n Data: ${JSON.stringify(sanitized, null, 2)}`;
         }
         catch {
-            dataStr = `\n  Data: [non-serializable — ${typeof sanitized}]`;
+            dataStr = `\n Data: [non-serializable — ${typeof sanitized}]`;
         }
     }
     return `[${entry.level.toUpperCase()}] ${entry.timestamp} - ${entry.message}${dataStr}\n\n`;
@@ -134,14 +133,17 @@ async function writeLog(entry) {
         await nodeFsPromises().appendFile(filePath, formatLogEntry(entry));
     }
     catch (error) {
+        void normalizeError(error);
         console.error("Failed to write log:", error);
     }
 }
 export const serverLogger = {
+    // audit-unknown-ok: logger entry-point — accepts arbitrary log data, normalised internally
     debug(message, data) {
         const sanitized = data ? redactPii(normalizeLogData(data)) : undefined;
         console.debug(`[DEBUG] ${message}`, sanitized);
     },
+    // audit-unknown-ok: logger entry-point — accepts arbitrary log data
     info(message, data) {
         const sanitized = data ? redactPii(normalizeLogData(data)) : undefined;
         const entry = {
@@ -154,6 +156,7 @@ export const serverLogger = {
         if (isFileLoggingEnabled)
             writeLog(entry).catch(() => { }); // audit-silent-catch-ok: logger must never throw
     },
+    // audit-unknown-ok: logger entry-point — accepts arbitrary log data
     warn(message, data) {
         const sanitized = data ? redactPii(normalizeLogData(data)) : undefined;
         const entry = {
@@ -166,6 +169,7 @@ export const serverLogger = {
         if (isFileLoggingEnabled)
             writeLog(entry).catch(() => { }); // audit-silent-catch-ok: logger must never throw
     },
+    // audit-unknown-ok: logger entry-point — accepts arbitrary log data
     error(message, data) {
         const sanitized = data ? redactPii(normalizeLogData(data)) : undefined;
         const entry = {
@@ -189,7 +193,9 @@ export const extractRequestMetadata = (request) => ({
         "unknown",
     referer: request.headers.get("referer") ?? "none",
 });
-function buildServerMeta(error, context) {
+function buildServerMeta(
+// audit-unknown-ok: error-handler entry point — receives thrown values
+error, context) {
     const base = {
         ...context,
         timestamp: new Date().toISOString(),
@@ -200,22 +206,29 @@ function buildServerMeta(error, context) {
             message: error.message,
             code: error.code,
             statusCode: error.statusCode,
-            data: error.data,
+            data: error.data === undefined || error.data === null
+                ? null
+                : JSON.parse(JSON.stringify(error.data)),
         };
     }
     else if (error instanceof Error) {
         base.error = {
             name: error.name,
             message: error.message,
-            stack: error.stack,
+            stack: error.stack ?? null,
         };
     }
     else {
-        base.error = error;
+        base.error = typeof error === "string" || typeof error === "number" ||
+            typeof error === "boolean" || error === null || error === undefined
+            ? error
+            : JSON.stringify(error);
     }
     return base;
 }
-export const logServerError = (message, error, context) => {
+export const logServerError = (message, 
+// audit-unknown-ok: error-handler entry point — receives thrown values
+error, context) => {
     serverLogger.error(message, buildServerMeta(error, context));
 };
 export const logServerWarning = (message, data) => {
@@ -227,14 +240,18 @@ export const logServerInfo = (message, data) => {
 export const logServerDebug = (message, data) => {
     serverLogger.debug(message, { ...data, timestamp: new Date().toISOString() });
 };
-export const logApiRouteError = (endpoint, error, request, context) => {
+export const logApiRouteError = (endpoint, 
+// audit-unknown-ok: error-handler entry point — receives thrown values
+error, request, context) => {
     logServerError(`API Route Error: ${endpoint}`, error, {
         ...context,
         endpoint,
         ...(request ? extractRequestMetadata(request) : {}),
     });
 };
-export const logDatabaseError = (operation, collection, error, context) => {
+export const logDatabaseError = (operation, collection, 
+// audit-unknown-ok: error-handler entry point — receives thrown values
+error, context) => {
     logServerError(`Database Error: ${operation} on ${collection}`, error, {
         ...context,
         operation,
@@ -242,7 +259,9 @@ export const logDatabaseError = (operation, collection, error, context) => {
         type: "database",
     });
 };
-export const logServerAuthError = (operation, error, context) => {
+export const logServerAuthError = (operation, 
+// audit-unknown-ok: error-handler entry point — receives thrown values
+error, context) => {
     logServerError(`Authentication Error: ${operation}`, error, {
         ...context,
         operation,
@@ -258,14 +277,18 @@ export const logAuthorizationError = (userId, resource, action, context) => {
         type: "authorization",
     });
 };
-export const logEmailError = (recipient, error, context) => {
+export const logEmailError = (recipient, 
+// audit-unknown-ok: error-handler entry point — receives thrown values
+error, context) => {
     logServerError(`Email Send Failed to ${recipient}`, error, {
         ...context,
         recipient,
         type: "email",
     });
 };
-export const logStorageError = (operation, filePath, error, context) => {
+export const logStorageError = (operation, filePath, 
+// audit-unknown-ok: error-handler entry point — receives thrown values
+error, context) => {
     logServerError(`Storage Error: ${operation} on ${filePath}`, error, {
         ...context,
         operation,
@@ -273,7 +296,9 @@ export const logStorageError = (operation, filePath, error, context) => {
         type: "storage",
     });
 };
-export const logExternalApiError = (serviceName, endpoint, error, context) => {
+export const logExternalApiError = (serviceName, endpoint, 
+// audit-unknown-ok: error-handler entry point — receives thrown values
+error, context) => {
     logServerError(`External API Error: ${serviceName} - ${endpoint}`, error, {
         ...context,
         serviceName,

package/dist/next/ErrorBoundary.js

@@ -3,9 +3,8 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Component } from "react";
 import { Button } from "../ui/components/Button";
 import { Heading, Text } from "../ui/components/Typography";
-import { THEME_CONSTANTS } from "../tokens";
 function DefaultFallback({ error, onReset, }) {
-    return (_jsxs("div", { className: `flex min-h-[40vh] flex-col items-center justify-center ${THEME_CONSTANTS.spacing.gap.md} rounded-xl border border-zinc-200 bg-white p-6 text-center dark:border-slate-700 dark:bg-slate-900`, "data-section": "errorboundary-div-445", children: [_jsx(Heading, { level: 2, children: "Something went wrong" }), _jsx(Text, { variant: "secondary", children: "An unexpected error occurred. Please try again." }), process.env.NODE_ENV === "development" && error ? (_jsx("pre", { className: "max-w-full overflow-auto rounded-md bg-zinc-100 p-3 text-left text-xs dark:bg-slate-800", children: error.message })) : null, _jsx(Button, { type: "button", onClick: onReset, children: "Try again" })] }));
+    return (_jsxs("div", { className: "flex min-h-[40vh] flex-col items-center justify-center gap-4 rounded-xl border border-zinc-200 bg-white p-6 text-center dark:border-slate-700 dark:bg-slate-900", "data-section": "errorboundary-div-445", children: [_jsx(Heading, { level: 2, children: "Something went wrong" }), _jsx(Text, { variant: "secondary", children: "An unexpected error occurred. Please try again." }), process.env.NODE_ENV === "development" && error ? (_jsx("pre", { className: "max-w-full overflow-auto rounded-md bg-zinc-100 p-3 text-left text-xs dark:bg-slate-800", children: error.message })) : null, _jsx(Button, { type: "button", onClick: onReset, children: "Try again" })] }));
 }
 export class ErrorBoundary extends Component {
     constructor(props) {

package/dist/next/IAuthVerifier.d.ts

@@ -1,3 +1,4 @@
+import type { JsonValue } from "../schemas/types";
 /**
  * IAuthVerifier — Injectable auth interface for createApiHandler.
  *
@@ -13,10 +14,10 @@
  * import { getAdminAuth } from '@/lib/firebase/admin';
  *
  * export const firebaseAuthVerifier: IAuthVerifier = {
- *   async verify(sessionCookie) {
- *     const decoded = await getAdminAuth().verifySessionCookie(sessionCookie, true);
- *     return { uid: decoded.uid, role: decoded.role as string | undefined };
- *   },
+ * async verify(sessionCookie) {
+ * const decoded = await getAdminAuth().verifySessionCookie(sessionCookie, true);
+ * return { uid: decoded.uid, role: decoded.role as string | undefined };
+ * },
  * };
  * ```
  */
@@ -29,7 +30,7 @@ export interface AuthVerifiedUser {
     uid: string;
     email?: string;
     role?: string;
-    [key: string]: unknown;
+    [key: string]: JsonValue | undefined;
 }
 /**
  * Generic auth verifier interface.

package/dist/next/IAuthVerifier.js

@@ -1,23 +1 @@
-/**
- * IAuthVerifier — Injectable auth interface for createApiHandler.
- *
- * Decouples @mohasinac/next from any specific auth provider (Firebase, Auth.js, etc.).
- * The consuming app provides a concrete implementation backed by its own
- * auth SDK. The interface is intentionally minimal — only what createApiHandler
- * needs: a uid and an optional role string.
- *
- * @example
- * ```ts
- * // apps/web/src/lib/firebase/auth-verifier.ts
- * import type { IAuthVerifier, AuthVerifiedUser } from './';
- * import { getAdminAuth } from '@/lib/firebase/admin';
- *
- * export const firebaseAuthVerifier: IAuthVerifier = {
- *   async verify(sessionCookie) {
- *     const decoded = await getAdminAuth().verifySessionCookie(sessionCookie, true);
- *     return { uid: decoded.uid, role: decoded.role as string | undefined };
- *   },
- * };
- * ```
- */
 export {};

package/dist/next/api/api-response.d.ts

@@ -5,18 +5,19 @@
  * No app-specific dependencies — safe to use in any project.
  */
 import { NextResponse } from "next/server";
+import type { JsonValue } from "@mohasinac/appkit";
 export interface ApiSuccessResponse<T = unknown> {
     success: true;
     data?: T;
     message?: string;
-    meta?: Record<string, unknown>;
+    meta?: Record<string, JsonValue>;
 }
 export interface ApiErrorResponse {
     success: false;
     error: string;
     details?: unknown;
 }
-export declare function successResponse<T>(data?: T, message?: string, status?: number, meta?: Record<string, unknown>): NextResponse<ApiSuccessResponse<T>>;
+export declare function successResponse<T>(data?: T, message?: string, status?: number, meta?: Record<string, JsonValue>): NextResponse<ApiSuccessResponse<T>>;
 export declare function errorResponse(error: string, status?: number, details?: unknown): NextResponse<ApiErrorResponse>;
 /** Pre-built shorthand factories for common HTTP error responses. */
 export declare const ApiErrors: {
@@ -25,5 +26,5 @@ export declare const ApiErrors: {
     notFound: (resource?: string) => NextResponse<ApiErrorResponse>;
     badRequest: (message?: string, details?: unknown) => NextResponse<ApiErrorResponse>;
     internalError: (message?: string) => NextResponse<ApiErrorResponse>;
-    validationError: (details: unknown) => NextResponse<ApiErrorResponse>;
+    validationError: (details: Error) => NextResponse<ApiErrorResponse>;
 };

package/dist/next/api/api-response.js

@@ -13,7 +13,9 @@ export function successResponse(data, message, status = 200, meta) {
         ...(meta && { meta }),
     }, { status });
 }
-export function errorResponse(error, status = 400, details) {
+export function errorResponse(error, status = 400, 
+// audit-unknown-ok: Generic response wrapper — issues field arbitrary
+details) {
     return NextResponse.json({
         success: false,
         error,
@@ -25,6 +27,7 @@ export const ApiErrors = {
     unauthorized: (message = "Unauthorized") => errorResponse(message, 401),
     forbidden: (message = "Forbidden") => errorResponse(message, 403),
     notFound: (resource = "Resource") => errorResponse(`${resource} not found`, 404),
+    // audit-unknown-ok: Generic response wrapper — issues field arbitrary
     badRequest: (message = "Bad request", details) => errorResponse(message, 400, details),
     internalError: (message = "Internal server error") => errorResponse(message, 500),
     validationError: (details) => errorResponse("Validation failed", 422, details),

package/dist/next/api/apiHandler.js

@@ -1,4 +1,6 @@
+import { normalizeError } from "../../errors/normalize";
 async function validateSchema(request, schema) {
+    // audit-unknown-ok: Next.js route dispatcher boundary
     if (typeof schema.safeParse === "function") {
         const body = await request.json();
         const result = schema.safeParse(body);
@@ -12,6 +14,7 @@ async function validateSchema(request, schema) {
         return { validationError: false, data };
     }
     catch {
+        // audit-unknown-ok: TS structural escape — TInput
         return { validationError: false, data: undefined };
     }
 }
@@ -44,7 +47,9 @@ async function applyRateLimitCheck(request, config, applyRateLimit, getRateLimit
     }
     return { blocked: false, headers };
 }
-async function applySchemaValidation(request, schema, errorResponse) {
+async function applySchemaValidation(request, schema, 
+// audit-unknown-ok: Next.js route dispatcher boundary
+errorResponse) {
     const schemaResult = await validateSchema(request, schema);
     if (schemaResult.validationError) {
         return { invalid: true, response: errorResponse("Validation failed", 400, schemaResult.issues) };
@@ -113,6 +118,7 @@ export function createApiHandlerFactory(deps) {
                 return response;
             }
             catch (error) {
+                void normalizeError(error);
                 deps.logTiming({
                     method: request.method,
                     path: new URL(request.url).pathname,

package/dist/next/api/errorHandler.d.ts

@@ -13,12 +13,12 @@
  * import { serverLogger } from '@/lib/server-logger';
  *
  * export const handleApiError = createApiErrorHandler({
- *   isAppError: (e): e is AppError => e instanceof AppError,
- *   getStatusCode: (e) => e.statusCode,
- *   toJSON: (e) => e.toJSON(),
- *   logger: serverLogger,
- *   internalErrorCode: 'GEN_INTERNAL_ERROR',
- *   internalErrorMessage: 'An internal server error occurred',
+ * isAppError: (e): e is AppError => e instanceof AppError,
+ * getStatusCode: (e) => e.statusCode,
+ * toJSON: (e) => e.toJSON(),
+ * logger: serverLogger,
+ * internalErrorCode: 'GEN_INTERNAL_ERROR',
+ * internalErrorMessage: 'An internal server error occurred',
  * });
  * ```
  */

package/dist/next/api/errorHandler.js

@@ -13,12 +13,12 @@
  * import { serverLogger } from '@/lib/server-logger';
  *
  * export const handleApiError = createApiErrorHandler({
- *   isAppError: (e): e is AppError => e instanceof AppError,
- *   getStatusCode: (e) => e.statusCode,
- *   toJSON: (e) => e.toJSON(),
- *   logger: serverLogger,
- *   internalErrorCode: 'GEN_INTERNAL_ERROR',
- *   internalErrorMessage: 'An internal server error occurred',
+ * isAppError: (e): e is AppError => e instanceof AppError,
+ * getStatusCode: (e) => e.statusCode,
+ * toJSON: (e) => e.toJSON(),
+ * logger: serverLogger,
+ * internalErrorCode: 'GEN_INTERNAL_ERROR',
+ * internalErrorMessage: 'An internal server error occurred',
  * });
  * ```
  */
@@ -34,12 +34,14 @@ import { NextResponse } from "next/server.js";
  */
 export function createApiErrorHandler(options) {
     const { isAppError, getStatusCode, toJSON, logger, internalErrorCode = "INTERNAL_ERROR", internalErrorMessage = "An internal server error occurred", } = options;
+    // audit-unknown-ok: error-handler entry point — accepts thrown values of any shape
     return function handleApiError(error) {
         // Known AppError subclass — structured response
         if (isAppError(error)) {
             const status = getStatusCode(error);
             if (status >= 500) {
                 logger.error("API Error", {
+                    // audit-unknown-ok: error JSON serialization boundary
                     body: toJSON(error),
                 });
             }
@@ -49,6 +51,7 @@ export function createApiErrorHandler(options) {
         if (error !== null &&
             typeof error === "object" &&
             "issues" in error &&
+            // audit-unknown-ok: error JSON serialization boundary
             Array.isArray(error.issues)) {
             return NextResponse.json({
                 success: false,

package/dist/next/api/parseJsonBody.d.ts

@@ -0,0 +1,16 @@
+import type { FirestoreDocument } from "@mohasinac/appkit";
+/**
+ * Strict JSON body parser for createRouteHandler handlers that need a body
+ * but don't yet use the wrapper's `schema` option. Replaces the silent
+ * `.catch(() => ({}))` pattern.
+ *
+ * On parse failure: throws ValidationError which the route wrapper maps to
+ * 400 / VALIDATION_FAILED. NEVER returns `{}` on failure.
+ *
+ * @example
+ *   const body = await parseJsonBody<{ name: string }>(request);
+ *   const body = await parseJsonBody<{ name?: string }>(request, { allowEmpty: true });
+ */
+export declare function parseJsonBody<T = FirestoreDocument>(request: Request, options?: {
+    allowEmpty?: boolean;
+}): Promise<T>;