@mohasinac/appkit 2.2.0 → 2.3.0

package/dist/monitoring/server-logger.js

@@ -1,289 +0,0 @@
-import "server-only";
-/**
- * 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 { appendFile, mkdir, readdir, rename, stat, unlink } from "fs/promises";
-import { existsSync } from "fs";
-import path from "path";
-import { redactPii } from "../security/pii-redact";
-import { AppError } from "../errors";
-const LOGS_DIR = path.join(process.cwd(), "logs");
-const MAX_LOG_FILE_SIZE = 10 * 1024 * 1024;
-const MAX_LOG_FILES = 10;
-const isFileLoggingEnabled = !process.env.VERCEL;
-function serializeError(error) {
-    const serialized = {
-        name: error.name,
-        message: error.message,
-    };
-    if (error.stack) {
-        serialized.stack = error.stack;
-    }
-    for (const [key, value] of Object.entries(error)) {
-        serialized[key] = value;
-    }
-    return serialized;
-}
-function normalizeLogData(data) {
-    if (data instanceof Error)
-        return serializeError(data);
-    if (Array.isArray(data))
-        return data.map(normalizeLogData);
-    if (data instanceof Date || data === null || data === undefined)
-        return data;
-    if (typeof data === "object") {
-        return Object.fromEntries(Object.entries(data).map(([key, value]) => [
-            key,
-            normalizeLogData(value),
-        ]));
-    }
-    return data;
-}
-async function ensureLogsDir() {
-    if (!existsSync(LOGS_DIR)) {
-        await mkdir(LOGS_DIR, { recursive: true });
-    }
-}
-function getLogFilePath(level) {
-    const date = new Date().toISOString().split("T")[0];
-    return path.join(LOGS_DIR, `${level}-${date}.log`);
-}
-function formatLogEntry(entry) {
-    const sanitized = entry.data ? redactPii(entry.data) : undefined;
-    const dataStr = sanitized
-        ? `\n  Data: ${JSON.stringify(sanitized, null, 2)}`
-        : "";
-    return `[${entry.level.toUpperCase()}] ${entry.timestamp} - ${entry.message}${dataStr}\n\n`;
-}
-async function cleanOldLogFiles(logsDir) {
-    try {
-        const files = await readdir(logsDir);
-        const logFiles = files
-            .filter((file) => file.endsWith(".log"))
-            .map((file) => ({
-            name: file,
-            path: path.join(logsDir, file),
-        }));
-        if (logFiles.length <= MAX_LOG_FILES)
-            return;
-        const filesWithStats = await Promise.all(logFiles.map(async (file) => ({
-            ...file,
-            mtime: (await stat(file.path)).mtime,
-        })));
-        filesWithStats.sort((left, right) => left.mtime.getTime() - right.mtime.getTime());
-        const filesToDelete = filesWithStats.slice(0, filesWithStats.length - MAX_LOG_FILES);
-        await Promise.all(filesToDelete.map((file) => unlink(file.path)));
-    }
-    catch {
-        // Logger failures must never break the request path.
-    }
-}
-async function rotateLogFileIfNeeded(filePath) {
-    try {
-        if (!existsSync(filePath))
-            return;
-        const fileStats = await stat(filePath);
-        if (fileStats.size < MAX_LOG_FILE_SIZE)
-            return;
-        const timestamp = Date.now();
-        const dir = path.dirname(filePath);
-        const filename = path.basename(filePath, ".log");
-        const rotatedPath = path.join(dir, `${filename}.${timestamp}.log`);
-        await rename(filePath, rotatedPath);
-        await cleanOldLogFiles(dir);
-    }
-    catch {
-        // Logger failures must never break the request path.
-    }
-}
-async function writeLog(entry) {
-    try {
-        await ensureLogsDir();
-        const filePath = getLogFilePath(entry.level);
-        await rotateLogFileIfNeeded(filePath);
-        await appendFile(filePath, formatLogEntry(entry));
-    }
-    catch (error) {
-        console.error("Failed to write log:", error);
-    }
-}
-export const serverLogger = {
-    debug(message, data) {
-        const sanitized = data ? redactPii(normalizeLogData(data)) : undefined;
-        console.debug(`[DEBUG] ${message}`, sanitized);
-    },
-    info(message, data) {
-        const sanitized = data ? redactPii(normalizeLogData(data)) : undefined;
-        const entry = {
-            level: "info",
-            message,
-            timestamp: new Date().toISOString(),
-            data: sanitized,
-        };
-        console.info(`[INFO] ${message}`, sanitized);
-        if (isFileLoggingEnabled)
-            writeLog(entry).catch(() => { });
-    },
-    warn(message, data) {
-        const sanitized = data ? redactPii(normalizeLogData(data)) : undefined;
-        const entry = {
-            level: "warn",
-            message,
-            timestamp: new Date().toISOString(),
-            data: sanitized,
-        };
-        console.warn(`[WARN] ${message}`, sanitized);
-        if (isFileLoggingEnabled)
-            writeLog(entry).catch(() => { });
-    },
-    error(message, data) {
-        const sanitized = data ? redactPii(normalizeLogData(data)) : undefined;
-        const entry = {
-            level: "error",
-            message,
-            timestamp: new Date().toISOString(),
-            data: sanitized,
-        };
-        console.error(`[ERROR] ${message}`, sanitized);
-        if (isFileLoggingEnabled)
-            writeLog(entry).catch(() => { });
-    },
-};
-/** Pull the commonly needed headers from a NextRequest in one call. */
-export const extractRequestMetadata = (request) => ({
-    method: request.method,
-    url: request.url,
-    userAgent: request.headers.get("user-agent") ?? "unknown",
-    ip: request.headers.get("x-forwarded-for") ??
-        request.headers.get("x-real-ip") ??
-        "unknown",
-    referer: request.headers.get("referer") ?? "none",
-});
-function buildServerMeta(error, context) {
-    const base = {
-        ...context,
-        timestamp: new Date().toISOString(),
-    };
-    if (error instanceof AppError) {
-        base.error = {
-            name: error.name,
-            message: error.message,
-            code: error.code,
-            statusCode: error.statusCode,
-            data: error.data,
-        };
-    }
-    else if (error instanceof Error) {
-        base.error = {
-            name: error.name,
-            message: error.message,
-            stack: error.stack,
-        };
-    }
-    else {
-        base.error = error;
-    }
-    return base;
-}
-export const logServerError = (message, error, context) => {
-    serverLogger.error(message, buildServerMeta(error, context));
-};
-export const logServerWarning = (message, data) => {
-    serverLogger.warn(message, { ...data, timestamp: new Date().toISOString() });
-};
-export const logServerInfo = (message, data) => {
-    serverLogger.info(message, { ...data, timestamp: new Date().toISOString() });
-};
-export const logServerDebug = (message, data) => {
-    serverLogger.debug(message, { ...data, timestamp: new Date().toISOString() });
-};
-export const logApiRouteError = (endpoint, error, request, context) => {
-    logServerError(`API Route Error: ${endpoint}`, error, {
-        ...context,
-        endpoint,
-        ...(request ? extractRequestMetadata(request) : {}),
-    });
-};
-export const logDatabaseError = (operation, collection, error, context) => {
-    logServerError(`Database Error: ${operation} on ${collection}`, error, {
-        ...context,
-        operation,
-        collection,
-        type: "database",
-    });
-};
-export const logServerAuthError = (operation, error, context) => {
-    logServerError(`Authentication Error: ${operation}`, error, {
-        ...context,
-        operation,
-        type: "authentication",
-    });
-};
-export const logAuthorizationError = (userId, resource, action, context) => {
-    logServerWarning(`Authorization Failed: User ${userId} attempted ${action} on ${resource}`, {
-        ...context,
-        userId,
-        resource,
-        action,
-        type: "authorization",
-    });
-};
-export const logEmailError = (recipient, error, context) => {
-    logServerError(`Email Send Failed to ${recipient}`, error, {
-        ...context,
-        recipient,
-        type: "email",
-    });
-};
-export const logStorageError = (operation, filePath, error, context) => {
-    logServerError(`Storage Error: ${operation} on ${filePath}`, error, {
-        ...context,
-        operation,
-        filePath,
-        type: "storage",
-    });
-};
-export const logExternalApiError = (serviceName, endpoint, error, context) => {
-    logServerError(`External API Error: ${serviceName} - ${endpoint}`, error, {
-        ...context,
-        serviceName,
-        endpoint,
-        type: "external-api",
-    });
-};
-export const logSlowOperation = (operation, duration, threshold = 1000, context) => {
-    if (duration <= threshold) {
-        return;
-    }
-    logServerWarning(`Slow Operation: ${operation} took ${duration}ms`, {
-        ...context,
-        operation,
-        duration,
-        threshold,
-        type: "performance",
-    });
-};
-export const logSecurityEvent = (event, severity, context) => {
-    const message = `Security Event: ${event}`;
-    const fullContext = {
-        ...context,
-        event,
-        type: "security",
-    };
-    if (severity === "error") {
-        serverLogger.error(message, fullContext);
-        return;
-    }
-    if (severity === "warn") {
-        serverLogger.warn(message, fullContext);
-        return;
-    }
-    serverLogger.info(message, fullContext);
-};

package/dist/next/ErrorBoundary.d.ts

@@ -1,19 +0,0 @@
-import React, { Component, type ErrorInfo, type ReactNode } from "react";
-export interface ErrorBoundaryProps {
-    children: ReactNode;
-    fallback?: ReactNode;
-    renderFallback?: (error: Error | null, reset: () => void) => ReactNode;
-    onError?: (error: Error, errorInfo: ErrorInfo) => void;
-}
-interface ErrorBoundaryState {
-    hasError: boolean;
-    error: Error | null;
-}
-export declare class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
-    constructor(props: ErrorBoundaryProps);
-    static getDerivedStateFromError(error: Error): ErrorBoundaryState;
-    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
-    private reset;
-    render(): string | number | bigint | boolean | import("react/jsx-runtime").JSX.Element | Iterable<React.ReactNode> | Promise<string | number | bigint | boolean | React.ReactPortal | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | null | undefined> | null | undefined;
-}
-export {};

package/dist/next/ErrorBoundary.js

@@ -1,35 +0,0 @@
-"use client";
-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";
-function DefaultFallback({ error, onReset, }) {
-    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", 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) {
-        super(props);
-        this.reset = () => {
-            this.setState({ hasError: false, error: null });
-        };
-        this.state = { hasError: false, error: null };
-    }
-    static getDerivedStateFromError(error) {
-        return { hasError: true, error };
-    }
-    componentDidCatch(error, errorInfo) {
-        this.props.onError?.(error, errorInfo);
-    }
-    render() {
-        if (!this.state.hasError) {
-            return this.props.children;
-        }
-        if (this.props.renderFallback) {
-            return this.props.renderFallback(this.state.error, this.reset);
-        }
-        if (this.props.fallback) {
-            return this.props.fallback;
-        }
-        return _jsx(DefaultFallback, { error: this.state.error, onReset: this.reset });
-    }
-}

package/dist/next/IAuthVerifier.d.ts

@@ -1,54 +0,0 @@
-/**
- * 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 };
- *   },
- * };
- * ```
- */
-/**
- * Minimal user shape returned by a successful auth verification.
- * Implementors may return additional fields; createApiHandler only consumes
- * `uid` and `role`.
- */
-export interface AuthVerifiedUser {
-    uid: string;
-    email?: string;
-    role?: string;
-    [key: string]: unknown;
-}
-/**
- * Generic auth verifier interface.
- *
- * An implementation should:
- * - Verify the session token/cookie cryptographically.
- * - Throw or return `null` when verification fails (both are handled by
- *   createApiHandler — returning null triggers a 401; throwing triggers
- *   handleApiError which maps to a 401 for AuthenticationError subclasses).
- */
-export interface IAuthVerifier {
-    /**
-     * Verify a session token (cookie value, JWT, or any string credential) and
-     * return the decoded user payload, or `null` if invalid.
-     *
-     * @param token - Raw session token (typically an httpOnly cookie value).
-     * @returns Verified user, or `null` when the token is expired / invalid.
-     * @throws May throw an `AuthenticationError` subclass; createApiHandler
-     *         will convert it to a 401 response via handleApiError.
-     */
-    verify(token: string): Promise<AuthVerifiedUser | null>;
-}

package/dist/next/IAuthVerifier.js

@@ -1,23 +0,0 @@
-/**
- * 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

@@ -1,29 +0,0 @@
-/**
- * Standardized API Response Utilities
- *
- * Provides consistent response formatting across all Next.js API routes.
- * No app-specific dependencies — safe to use in any project.
- */
-import { NextResponse } from "next/server";
-export interface ApiSuccessResponse<T = unknown> {
-    success: true;
-    data?: T;
-    message?: string;
-    meta?: Record<string, unknown>;
-}
-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 errorResponse(error: string, status?: number, details?: unknown): NextResponse<ApiErrorResponse>;
-/** Pre-built shorthand factories for common HTTP error responses. */
-export declare const ApiErrors: {
-    unauthorized: (message?: string) => NextResponse<ApiErrorResponse>;
-    forbidden: (message?: string) => NextResponse<ApiErrorResponse>;
-    notFound: (resource?: string) => NextResponse<ApiErrorResponse>;
-    badRequest: (message?: string, details?: unknown) => NextResponse<ApiErrorResponse>;
-    internalError: (message?: string) => NextResponse<ApiErrorResponse>;
-    validationError: (details: unknown) => NextResponse<ApiErrorResponse>;
-};

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

@@ -1,31 +0,0 @@
-/**
- * Standardized API Response Utilities
- *
- * Provides consistent response formatting across all Next.js API routes.
- * No app-specific dependencies — safe to use in any project.
- */
-import { NextResponse } from "next/server";
-export function successResponse(data, message, status = 200, meta) {
-    return NextResponse.json({
-        success: true,
-        ...(data !== undefined && { data }),
-        ...(message && { message }),
-        ...(meta && { meta }),
-    }, { status });
-}
-export function errorResponse(error, status = 400, details) {
-    return NextResponse.json({
-        success: false,
-        error,
-        ...(details !== undefined && { details }),
-    }, { status });
-}
-/** Pre-built shorthand factories for common HTTP error responses. */
-export const ApiErrors = {
-    unauthorized: (message = "Unauthorized") => errorResponse(message, 401),
-    forbidden: (message = "Forbidden") => errorResponse(message, 403),
-    notFound: (resource = "Resource") => errorResponse(`${resource} not found`, 404),
-    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.d.ts

@@ -1,48 +0,0 @@
-interface SafeParseSchema<TInput> {
-    safeParse: (input: unknown) => {
-        success: true;
-        data: TInput;
-    } | {
-        success: false;
-        error: {
-            issues?: unknown[];
-        };
-    };
-}
-export interface ApiRateLimitResult {
-    success: boolean;
-    limit: number;
-    remaining: number;
-    reset: number;
-}
-export interface ApiHandlerOptions<TInput, TParams extends Record<string, string>, TRole, TRateLimitConfig, TUser> {
-    auth?: boolean;
-    roles?: TRole[];
-    rateLimit?: TRateLimitConfig;
-    schema?: SafeParseSchema<TInput>;
-    handler: (ctx: {
-        request: Request;
-        user?: TUser;
-        body?: TInput;
-        params?: TParams;
-    }) => Promise<Response>;
-}
-export interface ApiHandlerFactoryDeps<TRole, TRateLimitConfig, TUser> {
-    applyRateLimit: (request: Request, config: TRateLimitConfig) => Promise<ApiRateLimitResult>;
-    requireAuthFromRequest: (request: Request) => Promise<TUser>;
-    requireRoleFromRequest: (request: Request, roles: TRole[]) => Promise<TUser>;
-    errorResponse: (message: string, status: number, issues?: unknown) => Response;
-    handleApiError: (error: unknown) => Response;
-    getRateLimitExceededMessage: () => string;
-    logTiming: (entry: {
-        method: string;
-        path: string;
-        status?: number;
-        durationMs: number;
-        error?: string;
-    }) => void;
-}
-export declare function createApiHandlerFactory<TRole, TRateLimitConfig, TUser>(deps: ApiHandlerFactoryDeps<TRole, TRateLimitConfig, TUser>): <TInput = unknown, TParams extends Record<string, string> = Record<string, string>>(options: ApiHandlerOptions<TInput, TParams, TRole, TRateLimitConfig, TUser>) => (request: Request, context: {
-    params: Promise<TParams>;
-}) => Promise<Response>;
-export {};

package/dist/next/api/apiHandler.js

@@ -1,87 +0,0 @@
-export function createApiHandlerFactory(deps) {
-    return function createApiHandler(options) {
-        return async (request, context) => {
-            const startMs = performance.now();
-            try {
-                let rateLimitHeaders;
-                if (options.rateLimit) {
-                    const rateLimitResult = await deps.applyRateLimit(request, options.rateLimit);
-                    rateLimitHeaders = {
-                        "RateLimit-Limit": String(rateLimitResult.limit),
-                        "RateLimit-Remaining": String(rateLimitResult.remaining),
-                        "RateLimit-Reset": String(rateLimitResult.reset),
-                    };
-                    if (!rateLimitResult.success) {
-                        return new Response(JSON.stringify({
-                            success: false,
-                            error: deps.getRateLimitExceededMessage(),
-                        }), {
-                            status: 429,
-                            headers: {
-                                "Content-Type": "application/json",
-                                ...rateLimitHeaders,
-                            },
-                        });
-                    }
-                }
-                let user;
-                if (options.roles && options.roles.length > 0) {
-                    user = await deps.requireRoleFromRequest(request, options.roles);
-                }
-                else if (options.auth) {
-                    user = await deps.requireAuthFromRequest(request);
-                }
-                let validatedBody;
-                if (options.schema) {
-                    if (typeof options.schema.safeParse === "function") {
-                        const body = await request.json();
-                        const result = options.schema.safeParse(body);
-                        if (!result.success) {
-                            return deps.errorResponse("Validation failed", 400, result.error.issues);
-                        }
-                        validatedBody = result.data;
-                    }
-                    else {
-                        try {
-                            validatedBody = (await request.json());
-                        }
-                        catch {
-                            validatedBody = undefined;
-                        }
-                    }
-                }
-                const resolvedParams = context?.params
-                    ? await context.params
-                    : undefined;
-                const response = await options.handler({
-                    request,
-                    user,
-                    body: validatedBody,
-                    params: resolvedParams,
-                });
-                response.headers.set("Access-Control-Max-Age", "86400");
-                if (rateLimitHeaders) {
-                    for (const [key, value] of Object.entries(rateLimitHeaders)) {
-                        response.headers.set(key, value);
-                    }
-                }
-                deps.logTiming({
-                    method: request.method,
-                    path: new URL(request.url).pathname,
-                    status: response.status,
-                    durationMs: Math.round(performance.now() - startMs),
-                });
-                return response;
-            }
-            catch (error) {
-                deps.logTiming({
-                    method: request.method,
-                    path: new URL(request.url).pathname,
-                    durationMs: Math.round(performance.now() - startMs),
-                    error: error instanceof Error ? error.message : String(error),
-                });
-                return deps.handleApiError(error);
-            }
-        };
-    };
-}

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

@@ -1,57 +0,0 @@
-/**
- * Generic API error handler for Next.js API routes.
- *
- * Framework-agnostic version of the app's handleApiError. Business-specific
- * error classes and loggers are injected via factory options so this module
- * has zero knowledge of Firebase, Resend, or letitrip.in domain logic.
- *
- * @example
- * ```ts
- * // apps/web/src/lib/api/error-handler.ts
- * import { createApiErrorHandler } from '..';
- * import { AppError } from '@/lib/errors';
- * 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',
- * });
- * ```
- */
-import { NextResponse } from "next/server.js";
-/** Minimal logger interface — satisfied by Winston, Pino, or console. */
-export interface IApiErrorLogger {
-    error(message: string, meta?: Record<string, unknown>): void;
-}
-/** Options for createApiErrorHandler factory. */
-export interface ApiErrorHandlerOptions<TAppError> {
-    /**
-     * Type guard — returns true when the thrown value is your app's AppError
-     * (or any subclass) that has statusCode / toJSON methods.
-     */
-    isAppError(err: unknown): err is TAppError;
-    /** Extract the HTTP status code from your AppError. */
-    getStatusCode(err: TAppError): number;
-    /** Serialise the error to a JSON-safe shape for the response body. */
-    toJSON(err: TAppError): unknown;
-    /** Logger used for 5xx and unexpected errors. */
-    logger: IApiErrorLogger;
-    /** Error code included in the 500 response body. */
-    internalErrorCode?: string;
-    /** Error message included in the 500 response body. */
-    internalErrorMessage?: string;
-}
-/**
- * Build a typed handleApiError function bound to your app's error hierarchy.
- *
- * The returned function:
- * - Returns a typed NextResponse for known AppError subclasses.
- * - Returns a 400 with validation details for Zod-like error shapes.
- * - Logs unexpected errors server-side; returns a generic 500 (no stack trace
- *   leaks to the client).
- */
-export declare function createApiErrorHandler<TAppError>(options: ApiErrorHandlerOptions<TAppError>): (error: unknown) => NextResponse;