@mohasinac/appkit 2.8.9 → 3.0.0

package/dist/errors/__tests__/error-mapping.test.js

@@ -0,0 +1,122 @@
+import { describe, expect, it } from "vitest";
+import { mapToHttpError, HTTP_ERROR_CODES } from "../error-mapping";
+import { ApiError } from "../api-error";
+import { ValidationError } from "../validation-error";
+import { AuthenticationError } from "../authentication-error";
+import { AuthorizationError } from "../authorization-error";
+import { NotFoundError } from "../not-found-error";
+import { DatabaseError } from "../database-error";
+import { RazorpayUnreachableError } from "../razorpay-unreachable";
+describe("mapToHttpError", () => {
+    describe("AppError subclasses", () => {
+        it("maps ValidationError → 400 VALIDATION_FAILED", () => {
+            const r = mapToHttpError(new ValidationError("bad email"));
+            expect(r.status).toBe(400);
+            expect(r.code).toBe(HTTP_ERROR_CODES.VALIDATION_FAILED);
+            expect(r.message).toBe("bad email");
+        });
+        it("maps AuthenticationError → 401 UNAUTHENTICATED", () => {
+            const r = mapToHttpError(new AuthenticationError("nope"));
+            expect(r.status).toBe(401);
+            expect(r.code).toBe(HTTP_ERROR_CODES.UNAUTHENTICATED);
+        });
+        it("maps AuthorizationError → 403 FORBIDDEN", () => {
+            const r = mapToHttpError(new AuthorizationError("denied"));
+            expect(r.status).toBe(403);
+            expect(r.code).toBe(HTTP_ERROR_CODES.FORBIDDEN);
+        });
+        it("maps NotFoundError → 404 NOT_FOUND", () => {
+            const r = mapToHttpError(new NotFoundError("missing"));
+            expect(r.status).toBe(404);
+            expect(r.code).toBe(HTTP_ERROR_CODES.NOT_FOUND);
+        });
+        it("maps RazorpayUnreachableError → 503 UPSTREAM_UNAVAILABLE", () => {
+            const r = mapToHttpError(new RazorpayUnreachableError("network"));
+            expect(r.status).toBe(503);
+            expect(r.code).toBe(HTTP_ERROR_CODES.UPSTREAM_UNAVAILABLE);
+        });
+        it("maps ApiError → its declared status + code", () => {
+            const r = mapToHttpError(new ApiError(418, "teapot"));
+            expect(r.status).toBe(418);
+            expect(r.code).toBe("API_ERROR");
+            expect(r.message).toBe("teapot");
+        });
+    });
+    describe("DatabaseError wrapping FirestoreError", () => {
+        it("unwraps numeric FirestoreError 5 → 404 NOT_FOUND", () => {
+            const dbErr = new DatabaseError("doc missing", { code: 5, message: "not-found" });
+            const r = mapToHttpError(dbErr);
+            expect(r.status).toBe(404);
+            expect(r.code).toBe(HTTP_ERROR_CODES.NOT_FOUND);
+        });
+        it("unwraps numeric FirestoreError 7 → 403 PERMISSION_DENIED", () => {
+            const r = mapToHttpError(new DatabaseError("denied", { code: 7 }));
+            expect(r.status).toBe(403);
+            expect(r.code).toBe(HTTP_ERROR_CODES.PERMISSION_DENIED);
+        });
+        it("unwraps numeric FirestoreError 10 → 409 CONCURRENT_MODIFICATION", () => {
+            const r = mapToHttpError(new DatabaseError("aborted", { code: 10 }));
+            expect(r.status).toBe(409);
+            expect(r.code).toBe(HTTP_ERROR_CODES.CONCURRENT_MODIFICATION);
+        });
+        it("falls back to 500 DATABASE_ERROR when inner cause is not FirestoreError", () => {
+            const r = mapToHttpError(new DatabaseError("disk full", undefined));
+            expect(r.status).toBe(500);
+        });
+    });
+    describe("bare FirestoreError-shaped objects", () => {
+        it("maps numeric code 7 → 403 PERMISSION_DENIED", () => {
+            const r = mapToHttpError({ code: 7, message: "permission-denied" });
+            expect(r.status).toBe(403);
+            expect(r.code).toBe(HTTP_ERROR_CODES.PERMISSION_DENIED);
+        });
+        it("maps string code permission-denied → 403", () => {
+            const r = mapToHttpError({ code: "permission-denied", message: "no" });
+            expect(r.status).toBe(403);
+            expect(r.code).toBe(HTTP_ERROR_CODES.PERMISSION_DENIED);
+        });
+    });
+    describe("Zod-shaped errors", () => {
+        it("maps Zod-like { issues } → 400 VALIDATION_FAILED with issues", () => {
+            const r = mapToHttpError({ issues: [{ path: ["email"], message: "bad" }] });
+            expect(r.status).toBe(400);
+            expect(r.code).toBe(HTTP_ERROR_CODES.VALIDATION_FAILED);
+            expect(r.issues).toHaveLength(1);
+        });
+    });
+    describe("Unknown errors", () => {
+        it("scrubs in production mode", () => {
+            const r = mapToHttpError(new Error("DB password=secret"), {
+                isProduction: true,
+            });
+            expect(r.status).toBe(500);
+            expect(r.message).toBe("An internal error occurred");
+        });
+        it("preserves message in dev mode", () => {
+            const r = mapToHttpError(new Error("specific dev message"));
+            expect(r.status).toBe(500);
+            expect(r.message).toBe("specific dev message");
+        });
+        it("handles string throws", () => {
+            const r = mapToHttpError("oops");
+            expect(r.status).toBe(500);
+            expect(r.message).toBe("oops");
+        });
+        it("handles undefined throws", () => {
+            const r = mapToHttpError(undefined);
+            expect(r.status).toBe(500);
+        });
+    });
+    describe("Legacy { status } objects", () => {
+        it("maps { status: 401 } → 401 UNAUTHENTICATED", () => {
+            const r = mapToHttpError({ status: 401, message: "auth" });
+            expect(r.status).toBe(401);
+            expect(r.code).toBe(HTTP_ERROR_CODES.UNAUTHENTICATED);
+        });
+        it("maps { statusCode: 404 } → 404 NOT_FOUND", () => {
+            const r = mapToHttpError({ statusCode: 404, message: "gone" });
+            expect(r.status).toBe(404);
+            expect(r.code).toBe(HTTP_ERROR_CODES.NOT_FOUND);
+        });
+    });
+});

package/dist/errors/__tests__/safe-read.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/errors/__tests__/safe-read.test.js

@@ -0,0 +1,39 @@
+import { describe, expect, it, vi } from "vitest";
+import { safeRead, installDegradedReadReporter } from "../safe-read";
+describe("safeRead", () => {
+    it("returns the data on success without invoking the reporter", async () => {
+        const reporter = vi.fn();
+        installDegradedReadReporter(reporter);
+        const result = await safeRead(async () => 42, {
+            route: "/test",
+            key: "k",
+            fallback: -1,
+        });
+        expect(result).toBe(42);
+        expect(reporter).not.toHaveBeenCalled();
+    });
+    it("returns the fallback and reports on failure", async () => {
+        const reporter = vi.fn();
+        installDegradedReadReporter(reporter);
+        const fallback = ["empty"];
+        const result = await safeRead(async () => {
+            throw new Error("boom");
+        }, { route: "/test", key: "k2", fallback });
+        expect(result).toBe(fallback);
+        expect(reporter).toHaveBeenCalledTimes(1);
+        const call = reporter.mock.calls[0][0];
+        expect(call.route).toBe("/test");
+        expect(call.key).toBe("k2");
+        expect(call.code).toBe("DEGRADED_READ");
+        expect(call.message).toBe("boom");
+    });
+    it("never throws when the reporter itself throws", async () => {
+        installDegradedReadReporter(() => {
+            throw new Error("reporter broken");
+        });
+        const result = await safeRead(async () => {
+            throw new Error("inner");
+        }, { route: "/x", key: "y", fallback: null });
+        expect(result).toBeNull();
+    });
+});

package/dist/errors/api-error.js

@@ -1,5 +1,6 @@
 import { AppError } from "./base-error";
 export class ApiError extends AppError {
+    // audit-unknown-ok: ApiError subclass — cause/issues canonical
     constructor(statusCode, message, data) {
         super(statusCode, message, "API_ERROR", data);
     }

package/dist/errors/authentication-error.js

@@ -1,5 +1,6 @@
 import { AppError } from "./base-error";
 export class AuthenticationError extends AppError {
+    // audit-unknown-ok: AuthError data — caller-defined
     constructor(message, data) {
         super(401, message, "AUTHENTICATION_ERROR", data);
     }

package/dist/errors/authorization-error.js

@@ -1,5 +1,6 @@
 import { AppError } from "./base-error";
 export class AuthorizationError extends AppError {
+    // audit-unknown-ok: AuthorizationError data
     constructor(message, data) {
         super(403, message, "AUTHORIZATION_ERROR", data);
     }

package/dist/errors/base-error.js

@@ -1,5 +1,7 @@
 export class AppError extends Error {
-    constructor(statusCode, message, code, data) {
+    constructor(statusCode, message, code, 
+    // audit-unknown-ok: base-error data — accepts arbitrary serialisable values
+    data) {
         super(message);
         this.statusCode = statusCode;
         this.message = message;

package/dist/errors/database-error.js

@@ -1,5 +1,6 @@
 import { AppError } from "./base-error";
 export class DatabaseError extends AppError {
+    // audit-unknown-ok: DatabaseError data
     constructor(message, data) {
         super(500, message, "DATABASE_ERROR", data);
     }

package/dist/errors/error-display-map.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Per-code display metadata.
+ *  - `field`: when present + a FormShellContext is in scope, the client wrapper
+ *    routes the error inline as a field error instead of a toast.
+ *  - `messageKey`: a `next-intl` key under `errors.codes.*` resolved at render time.
+ *    Falls back to `errors.codes.UNKNOWN` then to the raw `Error.message` if absent.
+ */
+export interface ErrorDisplayEntry {
+    field?: string;
+    messageKey: string;
+}
+export declare const ERROR_DISPLAY_MAP: Record<string, ErrorDisplayEntry>;
+/** Look up display metadata; returns a generic entry when the code is unknown. */
+export declare function getErrorDisplay(code: string): ErrorDisplayEntry;

package/dist/errors/error-display-map.js

@@ -0,0 +1,233 @@
+import { ERROR_CODES, BID_ERROR_CODES, OFFER_ERROR_CODES } from "./error-codes";
+import { HTTP_ERROR_CODES } from "./error-mapping";
+const k = (code) => `errors.codes.${code}`;
+export const ERROR_DISPLAY_MAP = {
+    // ---------- AuthN / sessions ----------
+    [ERROR_CODES.AUTH_INVALID_CREDENTIALS]: {
+        field: "password",
+        messageKey: k(ERROR_CODES.AUTH_INVALID_CREDENTIALS),
+    },
+    [ERROR_CODES.AUTH_TOKEN_EXPIRED]: {
+        messageKey: k(ERROR_CODES.AUTH_TOKEN_EXPIRED),
+    },
+    [ERROR_CODES.AUTH_TOKEN_INVALID]: {
+        messageKey: k(ERROR_CODES.AUTH_TOKEN_INVALID),
+    },
+    [ERROR_CODES.AUTH_SESSION_EXPIRED]: {
+        messageKey: k(ERROR_CODES.AUTH_SESSION_EXPIRED),
+    },
+    [ERROR_CODES.AUTH_EMAIL_NOT_VERIFIED]: {
+        messageKey: k(ERROR_CODES.AUTH_EMAIL_NOT_VERIFIED),
+    },
+    // ---------- Validation ----------
+    [ERROR_CODES.VALIDATION_REQUIRED_FIELD]: {
+        messageKey: k(ERROR_CODES.VALIDATION_REQUIRED_FIELD),
+    },
+    [ERROR_CODES.VALIDATION_INVALID_INPUT]: {
+        messageKey: k(ERROR_CODES.VALIDATION_INVALID_INPUT),
+    },
+    [ERROR_CODES.VALIDATION_INVALID_EMAIL]: {
+        field: "email",
+        messageKey: k(ERROR_CODES.VALIDATION_INVALID_EMAIL),
+    },
+    [ERROR_CODES.VALIDATION_INVALID_PASSWORD]: {
+        field: "password",
+        messageKey: k(ERROR_CODES.VALIDATION_INVALID_PASSWORD),
+    },
+    [ERROR_CODES.VALIDATION_INVALID_PHONE]: {
+        field: "phone",
+        messageKey: k(ERROR_CODES.VALIDATION_INVALID_PHONE),
+    },
+    // ---------- User ----------
+    [ERROR_CODES.USER_NOT_FOUND]: { messageKey: k(ERROR_CODES.USER_NOT_FOUND) },
+    [ERROR_CODES.USER_ALREADY_EXISTS]: {
+        field: "email",
+        messageKey: k(ERROR_CODES.USER_ALREADY_EXISTS),
+    },
+    [ERROR_CODES.USER_NOT_AUTHENTICATED]: {
+        messageKey: k(ERROR_CODES.USER_NOT_AUTHENTICATED),
+    },
+    [ERROR_CODES.USER_ACCOUNT_DISABLED]: {
+        messageKey: k(ERROR_CODES.USER_ACCOUNT_DISABLED),
+    },
+    // ---------- Database ----------
+    [ERROR_CODES.DB_OPERATION_FAILED]: {
+        messageKey: k(ERROR_CODES.DB_OPERATION_FAILED),
+    },
+    [ERROR_CODES.DB_NOT_FOUND]: { messageKey: k(ERROR_CODES.DB_NOT_FOUND) },
+    [ERROR_CODES.DB_DUPLICATE_ENTRY]: {
+        messageKey: k(ERROR_CODES.DB_DUPLICATE_ENTRY),
+    },
+    // ---------- Email ----------
+    [ERROR_CODES.EMAIL_SEND_FAILED]: {
+        messageKey: k(ERROR_CODES.EMAIL_SEND_FAILED),
+    },
+    [ERROR_CODES.EMAIL_INVALID_TEMPLATE]: {
+        messageKey: k(ERROR_CODES.EMAIL_INVALID_TEMPLATE),
+    },
+    [ERROR_CODES.EMAIL_RATE_LIMITED]: {
+        messageKey: k(ERROR_CODES.EMAIL_RATE_LIMITED),
+    },
+    [ERROR_CODES.EMAIL_DELIVERY_FAILED]: {
+        messageKey: k(ERROR_CODES.EMAIL_DELIVERY_FAILED),
+    },
+    // ---------- Password ----------
+    [ERROR_CODES.PWD_RESET_TOKEN_EXPIRED]: {
+        messageKey: k(ERROR_CODES.PWD_RESET_TOKEN_EXPIRED),
+    },
+    [ERROR_CODES.PWD_RESET_TOKEN_INVALID]: {
+        messageKey: k(ERROR_CODES.PWD_RESET_TOKEN_INVALID),
+    },
+    [ERROR_CODES.PWD_TOO_WEAK]: {
+        field: "password",
+        messageKey: k(ERROR_CODES.PWD_TOO_WEAK),
+    },
+    [ERROR_CODES.PWD_HISTORY_REUSE]: {
+        field: "password",
+        messageKey: k(ERROR_CODES.PWD_HISTORY_REUSE),
+    },
+    [ERROR_CODES.PWD_SAME_AS_CURRENT]: {
+        field: "password",
+        messageKey: k(ERROR_CODES.PWD_SAME_AS_CURRENT),
+    },
+    // ---------- Authorization ----------
+    [ERROR_CODES.AUTHZ_FORBIDDEN]: {
+        messageKey: k(ERROR_CODES.AUTHZ_FORBIDDEN),
+    },
+    [ERROR_CODES.AUTHZ_INSUFFICIENT_ROLE]: {
+        messageKey: k(ERROR_CODES.AUTHZ_INSUFFICIENT_ROLE),
+    },
+    // ---------- General ----------
+    [ERROR_CODES.GEN_BAD_REQUEST]: {
+        messageKey: k(ERROR_CODES.GEN_BAD_REQUEST),
+    },
+    [ERROR_CODES.GEN_NOT_FOUND]: { messageKey: k(ERROR_CODES.GEN_NOT_FOUND) },
+    [ERROR_CODES.GEN_INTERNAL_ERROR]: {
+        messageKey: k(ERROR_CODES.GEN_INTERNAL_ERROR),
+    },
+    [ERROR_CODES.GEN_SERVICE_UNAVAILABLE]: {
+        messageKey: k(ERROR_CODES.GEN_SERVICE_UNAVAILABLE),
+    },
+    [ERROR_CODES.GEN_RATE_LIMITED]: {
+        messageKey: k(ERROR_CODES.GEN_RATE_LIMITED),
+    },
+    [ERROR_CODES.GEN_UNKNOWN]: { messageKey: k(ERROR_CODES.GEN_UNKNOWN) },
+    // ---------- Bids ----------
+    [BID_ERROR_CODES.PRODUCT_NOT_FOUND]: {
+        messageKey: k(BID_ERROR_CODES.PRODUCT_NOT_FOUND),
+    },
+    [BID_ERROR_CODES.NOT_AUCTION]: {
+        messageKey: k(BID_ERROR_CODES.NOT_AUCTION),
+    },
+    [BID_ERROR_CODES.AUCTION_ENDED]: {
+        messageKey: k(BID_ERROR_CODES.AUCTION_ENDED),
+    },
+    [BID_ERROR_CODES.TOO_LOW]: {
+        field: "amount",
+        messageKey: k(BID_ERROR_CODES.TOO_LOW),
+    },
+    [BID_ERROR_CODES.INCREMENT_VIOLATED]: {
+        field: "amount",
+        messageKey: k(BID_ERROR_CODES.INCREMENT_VIOLATED),
+    },
+    [BID_ERROR_CODES.SELF_BID]: { messageKey: k(BID_ERROR_CODES.SELF_BID) },
+    [BID_ERROR_CODES.USER_BANNED]: {
+        messageKey: k(BID_ERROR_CODES.USER_BANNED),
+    },
+    [BID_ERROR_CODES.BUY_NOW_UNAVAILABLE]: {
+        messageKey: k(BID_ERROR_CODES.BUY_NOW_UNAVAILABLE),
+    },
+    [BID_ERROR_CODES.BUY_NOW_BIDS_STARTED]: {
+        messageKey: k(BID_ERROR_CODES.BUY_NOW_BIDS_STARTED),
+    },
+    [BID_ERROR_CODES.BUY_NOW_NO_PRICE]: {
+        messageKey: k(BID_ERROR_CODES.BUY_NOW_NO_PRICE),
+    },
+    // ---------- Offers ----------
+    [OFFER_ERROR_CODES.DISABLED]: { messageKey: k(OFFER_ERROR_CODES.DISABLED) },
+    [OFFER_ERROR_CODES.PRICE_TOO_LOW]: {
+        field: "amount",
+        messageKey: k(OFFER_ERROR_CODES.PRICE_TOO_LOW),
+    },
+    [OFFER_ERROR_CODES.LIMIT_REACHED]: {
+        messageKey: k(OFFER_ERROR_CODES.LIMIT_REACHED),
+    },
+    [OFFER_ERROR_CODES.ALREADY_ACTIVE]: {
+        messageKey: k(OFFER_ERROR_CODES.ALREADY_ACTIVE),
+    },
+    [OFFER_ERROR_CODES.EXPIRED]: { messageKey: k(OFFER_ERROR_CODES.EXPIRED) },
+    [OFFER_ERROR_CODES.CHECKOUT_EXPIRED]: {
+        messageKey: k(OFFER_ERROR_CODES.CHECKOUT_EXPIRED),
+    },
+    [OFFER_ERROR_CODES.WRONG_STATE]: {
+        messageKey: k(OFFER_ERROR_CODES.WRONG_STATE),
+    },
+    // ---------- HTTP / mapped wire codes (from error-mapping.ts) ----------
+    [HTTP_ERROR_CODES.VALIDATION_FAILED]: {
+        messageKey: k(HTTP_ERROR_CODES.VALIDATION_FAILED),
+    },
+    [HTTP_ERROR_CODES.UNAUTHENTICATED]: {
+        messageKey: k(HTTP_ERROR_CODES.UNAUTHENTICATED),
+    },
+    [HTTP_ERROR_CODES.FORBIDDEN]: { messageKey: k(HTTP_ERROR_CODES.FORBIDDEN) },
+    [HTTP_ERROR_CODES.PERMISSION_DENIED]: {
+        messageKey: k(HTTP_ERROR_CODES.PERMISSION_DENIED),
+    },
+    [HTTP_ERROR_CODES.NOT_FOUND]: { messageKey: k(HTTP_ERROR_CODES.NOT_FOUND) },
+    [HTTP_ERROR_CODES.ALREADY_EXISTS]: {
+        messageKey: k(HTTP_ERROR_CODES.ALREADY_EXISTS),
+    },
+    [HTTP_ERROR_CODES.RATE_LIMITED]: {
+        messageKey: k(HTTP_ERROR_CODES.RATE_LIMITED),
+    },
+    [HTTP_ERROR_CODES.PRECONDITION_FAILED]: {
+        messageKey: k(HTTP_ERROR_CODES.PRECONDITION_FAILED),
+    },
+    [HTTP_ERROR_CODES.CONCURRENT_MODIFICATION]: {
+        messageKey: k(HTTP_ERROR_CODES.CONCURRENT_MODIFICATION),
+    },
+    [HTTP_ERROR_CODES.INTERNAL]: { messageKey: k(HTTP_ERROR_CODES.INTERNAL) },
+    [HTTP_ERROR_CODES.UNAVAILABLE]: {
+        messageKey: k(HTTP_ERROR_CODES.UNAVAILABLE),
+    },
+    [HTTP_ERROR_CODES.UPSTREAM_UNAVAILABLE]: {
+        messageKey: k(HTTP_ERROR_CODES.UPSTREAM_UNAVAILABLE),
+    },
+    [HTTP_ERROR_CODES.NETWORK_ERROR]: {
+        messageKey: k(HTTP_ERROR_CODES.NETWORK_ERROR),
+    },
+    [HTTP_ERROR_CODES.REQUEST_TIMEOUT]: {
+        messageKey: k(HTTP_ERROR_CODES.REQUEST_TIMEOUT),
+    },
+    [HTTP_ERROR_CODES.DEGRADED_READ]: {
+        messageKey: k(HTTP_ERROR_CODES.DEGRADED_READ),
+    },
+    [HTTP_ERROR_CODES.PAYMENT_ROLLBACK_ATTEMPTED]: {
+        messageKey: k(HTTP_ERROR_CODES.PAYMENT_ROLLBACK_ATTEMPTED),
+    },
+    [HTTP_ERROR_CODES.PAYMENT_ROLLBACK_FAILED]: {
+        messageKey: k(HTTP_ERROR_CODES.PAYMENT_ROLLBACK_FAILED),
+    },
+    [HTTP_ERROR_CODES.VERIFICATION_EMAIL_FAILED]: {
+        messageKey: k(HTTP_ERROR_CODES.VERIFICATION_EMAIL_FAILED),
+    },
+    [HTTP_ERROR_CODES.CONFIRMATION_EMAIL_FAILED]: {
+        messageKey: k(HTTP_ERROR_CODES.CONFIRMATION_EMAIL_FAILED),
+    },
+    [HTTP_ERROR_CODES.CLIENT_BOUNDARY]: {
+        messageKey: k(HTTP_ERROR_CODES.CLIENT_BOUNDARY),
+    },
+    [HTTP_ERROR_CODES.CLIENT_PROMISE_REJECTION]: {
+        messageKey: k(HTTP_ERROR_CODES.CLIENT_PROMISE_REJECTION),
+    },
+    [HTTP_ERROR_CODES.CLIENT_WINDOW_ERROR]: {
+        messageKey: k(HTTP_ERROR_CODES.CLIENT_WINDOW_ERROR),
+    },
+    [HTTP_ERROR_CODES.CLIENT_UNHANDLED]: {
+        messageKey: k(HTTP_ERROR_CODES.CLIENT_UNHANDLED),
+    },
+};
+/** Look up display metadata; returns a generic entry when the code is unknown. */
+export function getErrorDisplay(code) {
+    return ERROR_DISPLAY_MAP[code] ?? { messageKey: "errors.codes.UNKNOWN" };
+}

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

@@ -1,4 +1,5 @@
 import { NextResponse } from "next/server.js";
+import type { JsonValue } from "@mohasinac/appkit";
 import { AppError } from "./base-error";
 /**
  * Handle API errors with consistent response format.
@@ -9,7 +10,7 @@ export declare function handleApiError(error: unknown): NextResponse;
  * Log an error with optional context. Wraps console.error for package portability;
  * replace with your structured logger if needed.
  */
-export declare function logError(error: unknown, context?: Record<string, unknown>): void;
+export declare function logError(error: unknown, context?: Record<string, JsonValue>): void;
 /**
  * Type guard — check if a value is an AppError instance.
  */

package/dist/errors/error-handler.js

@@ -5,6 +5,7 @@ import { ERROR_CODES, ERROR_MESSAGES_BY_CODE } from "./error-codes";
  * Handle API errors with consistent response format.
  * Use in Next.js API route catch blocks.
  */
+// audit-unknown-ok: type-narrowing entry point — accepts any value, narrows by typeof/Array.isArray
 export function handleApiError(error) {
     if (error instanceof AppError) {
         if (error.statusCode >= 500) {
@@ -41,7 +42,9 @@ export function handleApiError(error) {
  * Log an error with optional context. Wraps console.error for package portability;
  * replace with your structured logger if needed.
  */
-export function logError(error, context) {
+export function logError(
+// audit-unknown-ok: error-handler entry point — accepts thrown values of any shape
+error, context) {
     console.error("[Application Error]", {
         ...(context && { context }),
         error: error instanceof Error
@@ -52,6 +55,7 @@ export function logError(error, context) {
 /**
  * Type guard — check if a value is an AppError instance.
  */
+// audit-unknown-ok: type-narrowing entry point — accepts any value, narrows by typeof/Array.isArray
 export function isAppError(error) {
     return error instanceof AppError;
 }

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

@@ -0,0 +1,49 @@
+/**
+ * Codes emitted by the wire that are not present in the AppError-class enums.
+ * Added so the client display map and i18n keys can resolve them.
+ */
+export declare const HTTP_ERROR_CODES: {
+    readonly VALIDATION_FAILED: "VALIDATION_FAILED";
+    readonly UNAUTHENTICATED: "UNAUTHENTICATED";
+    readonly FORBIDDEN: "FORBIDDEN";
+    readonly PERMISSION_DENIED: "PERMISSION_DENIED";
+    readonly NOT_FOUND: "NOT_FOUND";
+    readonly ALREADY_EXISTS: "ALREADY_EXISTS";
+    readonly RATE_LIMITED: "RATE_LIMITED";
+    readonly PRECONDITION_FAILED: "PRECONDITION_FAILED";
+    readonly CONCURRENT_MODIFICATION: "CONCURRENT_MODIFICATION";
+    readonly INTERNAL: "INTERNAL";
+    readonly UNAVAILABLE: "UNAVAILABLE";
+    readonly UPSTREAM_UNAVAILABLE: "UPSTREAM_UNAVAILABLE";
+    readonly NETWORK_ERROR: "NETWORK_ERROR";
+    readonly REQUEST_TIMEOUT: "REQUEST_TIMEOUT";
+    readonly DEGRADED_READ: "DEGRADED_READ";
+    readonly PAYMENT_ROLLBACK_ATTEMPTED: "PAYMENT_ROLLBACK_ATTEMPTED";
+    readonly PAYMENT_ROLLBACK_FAILED: "PAYMENT_ROLLBACK_FAILED";
+    readonly VERIFICATION_EMAIL_FAILED: "VERIFICATION_EMAIL_FAILED";
+    readonly CONFIRMATION_EMAIL_FAILED: "CONFIRMATION_EMAIL_FAILED";
+    readonly CLIENT_BOUNDARY: "CLIENT_BOUNDARY";
+    readonly CLIENT_PROMISE_REJECTION: "CLIENT_PROMISE_REJECTION";
+    readonly CLIENT_WINDOW_ERROR: "CLIENT_WINDOW_ERROR";
+    readonly CLIENT_UNHANDLED: "CLIENT_UNHANDLED";
+};
+export type HttpErrorCode = (typeof HTTP_ERROR_CODES)[keyof typeof HTTP_ERROR_CODES];
+export interface MappedError {
+    status: number;
+    code: string;
+    message: string;
+    issues?: unknown[];
+}
+/**
+ * Map any thrown value to a stable HTTP error envelope shape.
+ *
+ * Order of precedence:
+ *  - AppError subclasses use their declared statusCode + code
+ *  - DatabaseError unwraps its `data` to look for a wrapped FirestoreError
+ *  - FirestoreError (numeric .code or string .code) maps via the table above
+ *  - ZodError shape maps to 400 VALIDATION_FAILED + issues
+ *  - Unknown Error → 500 INTERNAL; message scrubbed when isProduction
+ */
+export declare function mapToHttpError(err: unknown, opts?: {
+    isProduction?: boolean;
+}): MappedError;