@mohasinac/appkit 2.2.0 → 2.3.0

package/dist/monitoring/cache-metrics.d.ts

@@ -1,24 +0,0 @@
-/**
- * Cache Performance Metrics — pure localStorage implementation.
- * No Firebase dependencies.
- */
-interface CacheMetrics {
-    hits: number;
-    misses: number;
-    totalRequests: number;
-    hitRate: number;
-    lastReset: string;
-}
-export declare function getCacheMetrics(): CacheMetrics;
-export declare function recordCacheHit(): void;
-export declare function recordCacheMiss(): void;
-export declare function resetCacheMetrics(): void;
-export declare function getCacheHitRate(): number;
-export declare function isCacheHitRateLow(threshold?: number): boolean;
-export declare function getCacheStatistics(): {
-    hitRate: string;
-    totalRequests: number;
-    hits: number;
-    misses: number;
-};
-export {};

package/dist/monitoring/cache-metrics.js

@@ -1,83 +0,0 @@
-/**
- * Cache Performance Metrics — pure localStorage implementation.
- * No Firebase dependencies.
- */
-const STORAGE_KEY = "mohasinac:cache_metrics";
-const RESET_INTERVAL_MS = 3600000; // 1 hour
-function nowISO() {
-    return new Date().toISOString();
-}
-function initializeMetrics() {
-    const m = {
-        hits: 0,
-        misses: 0,
-        totalRequests: 0,
-        hitRate: 0,
-        lastReset: nowISO(),
-    };
-    if (typeof localStorage !== "undefined") {
-        localStorage.setItem(STORAGE_KEY, JSON.stringify(m));
-    }
-    return m;
-}
-export function getCacheMetrics() {
-    if (typeof localStorage === "undefined") {
-        return {
-            hits: 0,
-            misses: 0,
-            totalRequests: 0,
-            hitRate: 0,
-            lastReset: nowISO(),
-        };
-    }
-    const stored = localStorage.getItem(STORAGE_KEY);
-    if (!stored)
-        return initializeMetrics();
-    try {
-        const m = JSON.parse(stored);
-        if (Date.now() - new Date(m.lastReset).getTime() > RESET_INTERVAL_MS) {
-            return initializeMetrics();
-        }
-        return m;
-    }
-    catch {
-        return initializeMetrics();
-    }
-}
-function saveMetrics(m) {
-    if (typeof localStorage !== "undefined") {
-        localStorage.setItem(STORAGE_KEY, JSON.stringify(m));
-    }
-}
-export function recordCacheHit() {
-    const m = getCacheMetrics();
-    m.hits++;
-    m.totalRequests++;
-    m.hitRate = m.totalRequests > 0 ? m.hits / m.totalRequests : 0;
-    saveMetrics(m);
-}
-export function recordCacheMiss() {
-    const m = getCacheMetrics();
-    m.misses++;
-    m.totalRequests++;
-    m.hitRate = m.totalRequests > 0 ? m.hits / m.totalRequests : 0;
-    saveMetrics(m);
-}
-export function resetCacheMetrics() {
-    initializeMetrics();
-}
-export function getCacheHitRate() {
-    return getCacheMetrics().hitRate;
-}
-export function isCacheHitRateLow(threshold = 0.5) {
-    return getCacheHitRate() < threshold;
-}
-export function getCacheStatistics() {
-    const m = getCacheMetrics();
-    return {
-        hitRate: `${(m.hitRate * 100).toFixed(1)}%`,
-        totalRequests: m.totalRequests,
-        hits: m.hits,
-        misses: m.misses,
-    };
-}

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

@@ -1,29 +0,0 @@
-/**
- * Client-Side Error Logging Utilities
- *
- * Wraps the Logger singleton for use in React components, client hooks, and
- * browser-only code. Automatically attaches timestamp, userAgent, and current URL.
- *
- * For server-side logging use `server-logger.ts`.
- */
-export interface ClientErrorContext {
-    userId?: string;
-    component?: string;
-    action?: string;
-    url?: string;
-    method?: string;
-    statusCode?: number;
-    [key: string]: unknown;
-}
-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 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;
-export declare const logPaymentError: (transactionId: string, error: unknown, context?: ClientErrorContext) => void;
-export declare const logApplicationError: (category: string, message: string, error: unknown, context?: ClientErrorContext) => void;
-export declare const initializeClientLogger: () => void;

package/dist/monitoring/client-logger.js

@@ -1,127 +0,0 @@
-/**
- * Client-Side Error Logging Utilities
- *
- * Wraps the Logger singleton for use in React components, client hooks, and
- * browser-only code. Automatically attaches timestamp, userAgent, and current URL.
- *
- * For server-side logging use `server-logger.ts`.
- */
-import { logger } from "../core/Logger";
-import { AppError } from "../errors";
-function buildClientMeta(error, context) {
-    const base = {
-        ...context,
-        timestamp: new Date().toISOString(),
-        userAgent: typeof navigator !== "undefined" ? navigator.userAgent : "unknown",
-        url: typeof window !== "undefined" ? window.location.href : "unknown",
-    };
-    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 logClientError = (message, error, context) => {
-    logger.error(message, buildClientMeta(error, context));
-};
-export const logClientWarning = (message, data) => {
-    logger.warn(message, { ...data, timestamp: new Date().toISOString() });
-};
-export const logClientInfo = (message, data) => {
-    logger.info(message, { ...data, timestamp: new Date().toISOString() });
-};
-export const logClientDebug = (message, data) => {
-    logger.debug(message, { ...data, timestamp: new Date().toISOString() });
-};
-export const logApiError = async (endpoint, response, context) => {
-    let responseBody;
-    try {
-        responseBody = await response.clone().json();
-    }
-    catch {
-        responseBody = await response.clone().text();
-    }
-    logClientError(`API Error: ${endpoint}`, new Error(response.statusText), {
-        ...context,
-        endpoint,
-        status: response.status,
-        statusText: response.statusText,
-        responseBody,
-    });
-};
-export const logValidationError = (formName, errors, context) => {
-    logClientWarning(`Form validation failed: ${formName}`, {
-        ...context,
-        formName,
-        validationErrors: errors,
-    });
-};
-export const logNavigationError = (route, error, context) => {
-    logClientError(`Navigation error to ${route}`, error, {
-        ...context,
-        route,
-        type: "navigation",
-    });
-};
-export const logAuthError = (operation, error, context) => {
-    logClientError(`Authentication error: ${operation}`, error, {
-        ...context,
-        operation,
-        type: "authentication",
-    });
-};
-export const logUploadError = (fileName, error, context) => {
-    logClientError(`File upload failed: ${fileName}`, error, {
-        ...context,
-        fileName,
-        type: "upload",
-    });
-};
-export const logPaymentError = (transactionId, error, context) => {
-    logClientError(`Payment error: ${transactionId}`, error, {
-        ...context,
-        transactionId,
-        type: "payment",
-    });
-};
-export const logApplicationError = (category, message, error, context) => {
-    logClientError(`[${category}] ${message}`, error, {
-        ...context,
-        category,
-    });
-};
-let clientLoggerInitialized = false;
-export const initializeClientLogger = () => {
-    if (typeof window === "undefined" || clientLoggerInitialized) {
-        return;
-    }
-    clientLoggerInitialized = true;
-    window.addEventListener("unhandledrejection", (event) => {
-        logClientError("Unhandled Promise Rejection", event.reason, {
-            type: "unhandled-rejection",
-        });
-    });
-    window.addEventListener("error", (event) => {
-        logClientError("Global Error", event.error ?? event.message, {
-            type: "global-error",
-            filename: event.filename,
-            lineno: event.lineno,
-            colno: event.colno,
-        });
-    });
-};

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

@@ -1,50 +0,0 @@
-/**
- * Error Tracking — Provider-agnostic types, enums, and utilities.
- *
- * Implementations that require Firebase Crashlytics or external SDKs should
- * be wired in the app's monitoring setup by calling setErrorTracker().
- */
-export declare enum ErrorSeverity {
-    LOW = "low",
-    MEDIUM = "medium",
-    HIGH = "high",
-    CRITICAL = "critical"
-}
-export declare enum ErrorCategory {
-    AUTHENTICATION = "authentication",
-    API = "api",
-    DATABASE = "database",
-    VALIDATION = "validation",
-    NETWORK = "network",
-    PERMISSION = "permission",
-    UI = "ui",
-    UNKNOWN = "unknown"
-}
-export interface ErrorContext {
-    userId?: string;
-    userRole?: string;
-    page?: string;
-    component?: string;
-    action?: string;
-    metadata?: Record<string, unknown>;
-}
-export interface TrackedError {
-    message: string;
-    stack?: string;
-    category: ErrorCategory;
-    severity: ErrorSeverity;
-    context?: ErrorContext;
-    timestamp: string;
-}
-export type ErrorTrackerFn = (error: Error | string, category: ErrorCategory, severity: ErrorSeverity, context?: ErrorContext) => void;
-declare global {
-    var __mohasinac_error_tracker__: ErrorTrackerFn | undefined;
-}
-/** Override the default console-based tracker with a custom implementation. */
-export declare function setErrorTracker(fn: ErrorTrackerFn): void;
-export declare function trackError(error: Error | string, category?: ErrorCategory, severity?: ErrorSeverity, context?: ErrorContext): void;
-export declare function trackApiError(error: Error | string, context?: ErrorContext): void;
-export declare function trackAuthError(error: Error | string, context?: ErrorContext): void;
-export declare function trackValidationError(error: Error | string, context?: ErrorContext): void;
-export declare function trackDatabaseError(error: Error | string, context?: ErrorContext): void;
-export declare function trackPermissionError(error: Error | string, context?: ErrorContext): void;

package/dist/monitoring/error-tracking.js

@@ -1,54 +0,0 @@
-/**
- * Error Tracking — Provider-agnostic types, enums, and utilities.
- *
- * Implementations that require Firebase Crashlytics or external SDKs should
- * be wired in the app's monitoring setup by calling setErrorTracker().
- */
-export var ErrorSeverity;
-(function (ErrorSeverity) {
-    ErrorSeverity["LOW"] = "low";
-    ErrorSeverity["MEDIUM"] = "medium";
-    ErrorSeverity["HIGH"] = "high";
-    ErrorSeverity["CRITICAL"] = "critical";
-})(ErrorSeverity || (ErrorSeverity = {}));
-export var ErrorCategory;
-(function (ErrorCategory) {
-    ErrorCategory["AUTHENTICATION"] = "authentication";
-    ErrorCategory["API"] = "api";
-    ErrorCategory["DATABASE"] = "database";
-    ErrorCategory["VALIDATION"] = "validation";
-    ErrorCategory["NETWORK"] = "network";
-    ErrorCategory["PERMISSION"] = "permission";
-    ErrorCategory["UI"] = "ui";
-    ErrorCategory["UNKNOWN"] = "unknown";
-})(ErrorCategory || (ErrorCategory = {}));
-const TRACKER_KEY = "__mohasinac_error_tracker__";
-function getTracker() {
-    return (globalThis.__mohasinac_error_tracker__ ??
-        ((error, category, severity, context) => {
-            const msg = error instanceof Error ? error.message : error;
-            console.error(`[${severity.toUpperCase()}][${category}] ${msg}`, context);
-        }));
-}
-/** Override the default console-based tracker with a custom implementation. */
-export function setErrorTracker(fn) {
-    globalThis[TRACKER_KEY] = fn;
-}
-export function trackError(error, category = ErrorCategory.UNKNOWN, severity = ErrorSeverity.MEDIUM, context) {
-    getTracker()(error, category, severity, context);
-}
-export function trackApiError(error, context) {
-    trackError(error, ErrorCategory.API, ErrorSeverity.HIGH, context);
-}
-export function trackAuthError(error, context) {
-    trackError(error, ErrorCategory.AUTHENTICATION, ErrorSeverity.HIGH, context);
-}
-export function trackValidationError(error, context) {
-    trackError(error, ErrorCategory.VALIDATION, ErrorSeverity.LOW, context);
-}
-export function trackDatabaseError(error, context) {
-    trackError(error, ErrorCategory.DATABASE, ErrorSeverity.CRITICAL, context);
-}
-export function trackPermissionError(error, context) {
-    trackError(error, ErrorCategory.PERMISSION, ErrorSeverity.MEDIUM, context);
-}

package/dist/monitoring/index.d.ts

@@ -1,12 +0,0 @@
-export { ErrorSeverity, ErrorCategory, setErrorTracker, trackError, trackApiError, trackAuthError, trackValidationError, trackDatabaseError, trackPermissionError, } from "./error-tracking";
-export type { ErrorContext, TrackedError, ErrorTrackerFn, } from "./error-tracking";
-export { getCacheMetrics, recordCacheHit, recordCacheMiss, resetCacheMetrics, getCacheHitRate, isCacheHitRateLow, getCacheStatistics, } from "./cache-metrics";
-export { setupGlobalErrorHandler, setupCacheMonitoring } from "./runtime";
-export { logClientError, logClientWarning, logClientInfo, logClientDebug, logApiError, logValidationError, logNavigationError, logAuthError, logUploadError, logPaymentError, logApplicationError, initializeClientLogger, } from "./client-logger";
-export type { ClientErrorContext } from "./client-logger";
-export { serverLogger, logServerError, logServerWarning, logServerInfo, logServerDebug, extractRequestMetadata, logApiRouteError, logDatabaseError, logServerAuthError, logAuthorizationError, logEmailError, logStorageError, logExternalApiError, logSlowOperation, logSecurityEvent, } from "./server-logger";
-export type { ServerErrorContext } from "./server-logger";
-export { setPerformanceProvider, startTrace, stopTrace, addTraceAttribute, addTraceMetric, } from "./performance";
-export type { PerformanceTrace, PerformanceProvider } from "./performance";
-export { ANALYTICS_EVENTS, initializeAnalytics, trackEvent, setAnalyticsUserId, setAnalyticsUserProperties, trackPageView, trackAuth, trackEcommerce, trackContent, trackForm, trackAdmin, } from "./analytics";
-export type { AnalyticsEvent } from "./analytics";

package/dist/monitoring/index.js

@@ -1,7 +0,0 @@
-export { ErrorSeverity, ErrorCategory, setErrorTracker, trackError, trackApiError, trackAuthError, trackValidationError, trackDatabaseError, trackPermissionError, } from "./error-tracking";
-export { getCacheMetrics, recordCacheHit, recordCacheMiss, resetCacheMetrics, getCacheHitRate, isCacheHitRateLow, getCacheStatistics, } from "./cache-metrics";
-export { setupGlobalErrorHandler, setupCacheMonitoring } from "./runtime";
-export { logClientError, logClientWarning, logClientInfo, logClientDebug, logApiError, logValidationError, logNavigationError, logAuthError, logUploadError, logPaymentError, logApplicationError, initializeClientLogger, } from "./client-logger";
-export { serverLogger, logServerError, logServerWarning, logServerInfo, logServerDebug, extractRequestMetadata, logApiRouteError, logDatabaseError, logServerAuthError, logAuthorizationError, logEmailError, logStorageError, logExternalApiError, logSlowOperation, logSecurityEvent, } from "./server-logger";
-export { setPerformanceProvider, startTrace, stopTrace, addTraceAttribute, addTraceMetric, } from "./performance";
-export { ANALYTICS_EVENTS, initializeAnalytics, trackEvent, setAnalyticsUserId, setAnalyticsUserProperties, trackPageView, trackAuth, trackEcommerce, trackContent, trackForm, trackAdmin, } from "./analytics";

package/dist/monitoring/performance.d.ts

@@ -1,31 +0,0 @@
-/**
- * Provider-Agnostic Performance Tracing
- *
- * Provides a thin abstraction over any performance tracing backend.
- * Wire a concrete implementation via `setPerformanceProvider()` — e.g. a
- * Firebase Performance, Datadog RUM, or web-vitals adapter.
- *
- * Without a provider the helpers are silent no-ops, so they are safe to call
- * in any environment.
- */
-export interface PerformanceTrace {
-    stop(): void;
-    putAttribute(key: string, value: string): void;
-    putMetric(key: string, value: number): void;
-}
-export interface PerformanceProvider {
-    startTrace(name: string): PerformanceTrace;
-}
-declare global {
-    var __mohasinac_perf_provider__: PerformanceProvider | undefined;
-}
-/** Register a concrete performance backend (call once in instrumentation). */
-export declare function setPerformanceProvider(provider: PerformanceProvider): void;
-/** Start a named trace. Returns `null` when no provider is registered. */
-export declare function startTrace(name: string): PerformanceTrace | null;
-/** Stop a trace returned by `startTrace`. Safe to call with `null`. */
-export declare function stopTrace(t: PerformanceTrace | null): void;
-/** Attach a string attribute to a trace. Safe to call with `null`. */
-export declare function addTraceAttribute(t: PerformanceTrace | null, key: string, value: string): void;
-/** Record a numeric metric on a trace. Safe to call with `null`. */
-export declare function addTraceMetric(t: PerformanceTrace | null, key: string, value: number): void;

package/dist/monitoring/performance.js

@@ -1,34 +0,0 @@
-/**
- * Provider-Agnostic Performance Tracing
- *
- * Provides a thin abstraction over any performance tracing backend.
- * Wire a concrete implementation via `setPerformanceProvider()` — e.g. a
- * Firebase Performance, Datadog RUM, or web-vitals adapter.
- *
- * Without a provider the helpers are silent no-ops, so they are safe to call
- * in any environment.
- */
-const PROVIDER_KEY = "__mohasinac_perf_provider__";
-/** Register a concrete performance backend (call once in instrumentation). */
-export function setPerformanceProvider(provider) {
-    globalThis[PROVIDER_KEY] = provider;
-}
-function getProvider() {
-    return globalThis.__mohasinac_perf_provider__;
-}
-/** Start a named trace. Returns `null` when no provider is registered. */
-export function startTrace(name) {
-    return getProvider()?.startTrace(name) ?? null;
-}
-/** Stop a trace returned by `startTrace`. Safe to call with `null`. */
-export function stopTrace(t) {
-    t?.stop();
-}
-/** Attach a string attribute to a trace. Safe to call with `null`. */
-export function addTraceAttribute(t, key, value) {
-    t?.putAttribute(key, value);
-}
-/** Record a numeric metric on a trace. Safe to call with `null`. */
-export function addTraceMetric(t, key, value) {
-    t?.putMetric(key, value);
-}

package/dist/monitoring/runtime.d.ts

@@ -1,17 +0,0 @@
-/**
- * Global Runtime Error Bootstrap
- *
- * Sets up window-level unhandled error/rejection forwarding to the
- * configured error tracker. Import once in instrumentation.ts or layout.tsx.
- */
-/**
- * Attach window-level listeners that forward uncaught errors and unhandled
- * promise rejections to `trackError`. Safe to call multiple times — only
- * registers once per window lifecycle.
- */
-export declare function setupGlobalErrorHandler(): void;
-/**
- * Placeholder — wire up cache metric collection here once a backend flush
- * target is configured (e.g. flush to Datadog / custom endpoint).
- */
-export declare function setupCacheMonitoring(): void;

package/dist/monitoring/runtime.js

@@ -1,28 +0,0 @@
-/**
- * Global Runtime Error Bootstrap
- *
- * Sets up window-level unhandled error/rejection forwarding to the
- * configured error tracker. Import once in instrumentation.ts or layout.tsx.
- */
-import { trackError } from "./error-tracking";
-/**
- * Attach window-level listeners that forward uncaught errors and unhandled
- * promise rejections to `trackError`. Safe to call multiple times — only
- * registers once per window lifecycle.
- */
-export function setupGlobalErrorHandler() {
-    if (typeof window === "undefined") {
-        return;
-    }
-    window.addEventListener("unhandledrejection", (event) => {
-        trackError(event.reason);
-    });
-    window.addEventListener("error", (event) => {
-        trackError(event.error ?? event.message);
-    });
-}
-/**
- * Placeholder — wire up cache metric collection here once a backend flush
- * target is configured (e.g. flush to Datadog / custom endpoint).
- */
-export function setupCacheMonitoring() { }

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

@@ -1,37 +0,0 @@
-import "server-only";
-import { type NextRequest } from "next/server";
-export interface ServerErrorContext {
-    userId?: string;
-    endpoint?: string;
-    method?: string;
-    statusCode?: number;
-    requestId?: string;
-    [key: string]: unknown;
-}
-export declare const serverLogger: {
-    debug(message: string, data?: unknown): void;
-    info(message: string, data?: unknown): void;
-    warn(message: string, data?: unknown): void;
-    error(message: string, data?: unknown): void;
-};
-/** Pull the commonly needed headers from a NextRequest in one call. */
-export declare const extractRequestMetadata: (request: NextRequest) => {
-    method: string;
-    url: string;
-    userAgent: string;
-    ip: string;
-    referer: string;
-};
-export declare const logServerError: (message: string, error: unknown, context?: ServerErrorContext) => void;
-export declare const logServerWarning: (message: string, data?: ServerErrorContext) => void;
-export declare const logServerInfo: (message: string, data?: ServerErrorContext) => void;
-export declare const logServerDebug: (message: string, data?: ServerErrorContext) => void;
-export declare const logApiRouteError: (endpoint: string, error: unknown, request?: NextRequest, context?: ServerErrorContext) => void;
-export declare const logDatabaseError: (operation: string, collection: string, error: unknown, context?: ServerErrorContext) => void;
-export declare const logServerAuthError: (operation: string, error: unknown, context?: ServerErrorContext) => void;
-export declare const logAuthorizationError: (userId: string, resource: string, action: string, context?: ServerErrorContext) => void;
-export declare const logEmailError: (recipient: string, error: unknown, context?: ServerErrorContext) => void;
-export declare const logStorageError: (operation: string, filePath: string, error: unknown, context?: ServerErrorContext) => void;
-export declare const logExternalApiError: (serviceName: string, endpoint: string, error: unknown, context?: ServerErrorContext) => void;
-export declare const logSlowOperation: (operation: string, duration: number, threshold?: number, context?: ServerErrorContext) => void;
-export declare const logSecurityEvent: (event: string, severity: "info" | "warn" | "error", context?: ServerErrorContext) => void;