@mohasinac/appkit 2.3.0 → 2.3.2

package/dist/instrumentation/index.d.ts

@@ -0,0 +1,64 @@
+/**
+ * @mohasinac/instrumentation
+ *
+ * Minimal Next.js instrumentation hook factory.
+ *
+ * ## What belongs HERE (in Next.js instrumentation)
+ *
+ *   - Provider/DI registration via registerProviders() — this MUST run before
+ *     any API route handler calls getProviders().
+ *
+ * ## What belongs in Firebase Functions instead of Next.js instrumentation
+ *
+ *   On Vercel Hobby (free) tier, each serverless function invocation is billed
+ *   and cold-start time is limited. Heavy observability setup should live in
+ *   Firebase Functions (free tier: 2 M invocations/month, 400 K GB-seconds):
+ *
+ *   - APM / OpenTelemetry tracing — use a Firebase scheduled function to poll
+ *     or process trace data asynchronously.
+ *   - Error alerting / log aggregation — use Firestore triggers or scheduled
+ *     jobs in functions/src/ (already present in this project).
+ *   - Health checks / uptime monitoring — Firebase scheduled function pinging
+ *     an internal pub/sub or writing to Firestore.
+ *   - Performance budget checks — scheduled Firebase function reading Cloud
+ *     Run metrics and writing summaries to Firestore.
+ *
+ * ## Usage (in app root instrumentation.ts)
+ *
+ * ```ts
+ * import { createInstrumentation } from "./";
+ *
+ * const { register } = createInstrumentation({
+ *   onNodeServer: async () => {
+ *     await import("./src/providers.config");
+ *   },
+ * });
+ *
+ * export { register };
+ * ```
+ */
+export interface InstrumentationConfig {
+    /**
+     * Called ONCE when the Node.js runtime initialises (never on Edge runtime).
+     * Use this to register providers and do any one-time server setup that must
+     * complete before the first API route handler runs.
+     *
+     * Keep this function fast (< 50 ms). Any slow I/O, monitoring agents, or
+     * APM SDKs should live in Firebase Functions instead.
+     */
+    onNodeServer: () => Promise<void>;
+}
+export interface InstrumentationHook {
+    /**
+     * The `register` export required by Next.js instrumentation.ts.
+     * Next.js calls this exactly once per server process start.
+     */
+    register: () => Promise<void>;
+}
+/**
+ * Creates a Next.js-compatible instrumentation hook.
+ *
+ * The returned `register` function is a no-op on the Edge runtime and calls
+ * `onNodeServer` exactly once on the Node.js runtime.
+ */
+export declare function createInstrumentation(config: InstrumentationConfig): InstrumentationHook;

package/dist/instrumentation/index.js

@@ -0,0 +1,55 @@
+/**
+ * @mohasinac/instrumentation
+ *
+ * Minimal Next.js instrumentation hook factory.
+ *
+ * ## What belongs HERE (in Next.js instrumentation)
+ *
+ *   - Provider/DI registration via registerProviders() — this MUST run before
+ *     any API route handler calls getProviders().
+ *
+ * ## What belongs in Firebase Functions instead of Next.js instrumentation
+ *
+ *   On Vercel Hobby (free) tier, each serverless function invocation is billed
+ *   and cold-start time is limited. Heavy observability setup should live in
+ *   Firebase Functions (free tier: 2 M invocations/month, 400 K GB-seconds):
+ *
+ *   - APM / OpenTelemetry tracing — use a Firebase scheduled function to poll
+ *     or process trace data asynchronously.
+ *   - Error alerting / log aggregation — use Firestore triggers or scheduled
+ *     jobs in functions/src/ (already present in this project).
+ *   - Health checks / uptime monitoring — Firebase scheduled function pinging
+ *     an internal pub/sub or writing to Firestore.
+ *   - Performance budget checks — scheduled Firebase function reading Cloud
+ *     Run metrics and writing summaries to Firestore.
+ *
+ * ## Usage (in app root instrumentation.ts)
+ *
+ * ```ts
+ * import { createInstrumentation } from "./";
+ *
+ * const { register } = createInstrumentation({
+ *   onNodeServer: async () => {
+ *     await import("./src/providers.config");
+ *   },
+ * });
+ *
+ * export { register };
+ * ```
+ */
+/**
+ * Creates a Next.js-compatible instrumentation hook.
+ *
+ * The returned `register` function is a no-op on the Edge runtime and calls
+ * `onNodeServer` exactly once on the Node.js runtime.
+ */
+export function createInstrumentation(config) {
+    return {
+        register: async () => {
+            // Skip on Edge — providers use Node.js APIs (firebase-admin, etc.)
+            if (process.env.NEXT_RUNTIME === "edge")
+                return;
+            await config.onNodeServer();
+        },
+    };
+}

package/dist/monitoring/analytics.d.ts

@@ -0,0 +1,79 @@
+export declare const ANALYTICS_EVENTS: {
+    readonly PAGE_VIEW: "page_view";
+    readonly LOGIN: "login";
+    readonly SIGN_UP: "sign_up";
+    readonly LOGOUT: "logout";
+    readonly VIEW_ITEM: "view_item";
+    readonly ADD_TO_CART: "add_to_cart";
+    readonly PURCHASE: "purchase";
+    readonly PLACE_BID: "place_bid";
+    readonly WIN_AUCTION: "win_auction";
+    readonly SEARCH: "search";
+    readonly VIEW_FAQ: "view_faq";
+};
+export type AnalyticsEvent = (typeof ANALYTICS_EVENTS)[keyof typeof ANALYTICS_EVENTS];
+export declare function initializeAnalytics(params: {
+    app: unknown;
+    enabled?: boolean;
+    currency?: string;
+}): Promise<void>;
+export declare const trackEvent: (eventName: string, eventParams?: Record<string, unknown>) => void;
+export declare const setAnalyticsUserId: (userId: string | null) => void;
+export declare const setAnalyticsUserProperties: (properties: Record<string, string | number | boolean>) => void;
+export declare const trackPageView: (page_path: string, page_title: string) => void;
+export declare const trackAuth: {
+    login: (method: "email" | "google" | "apple") => void;
+    register: (method: "email" | "google" | "apple") => void;
+    logout: () => void;
+};
+export declare const trackEcommerce: {
+    viewProduct: (product: {
+        id: string;
+        name: string;
+        category: string;
+        price: number;
+        currency?: string;
+    }) => void;
+    addToCart: (product: {
+        id: string;
+        name: string;
+        category: string;
+        price: number;
+        quantity: number;
+        currency?: string;
+    }) => void;
+    purchase: (order: {
+        id: string;
+        total: number;
+        tax?: number;
+        shipping?: number;
+        currency?: string;
+        items: Array<{
+            id: string;
+            name: string;
+            category: string;
+            price: number;
+            quantity: number;
+        }>;
+    }) => void;
+    placeBid: (product: {
+        id: string;
+        name: string;
+        bidAmount: number;
+    }) => void;
+    winAuction: (product: {
+        id: string;
+        name: string;
+        finalBid: number;
+    }) => void;
+};
+export declare const trackContent: {
+    search: (searchTerm: string, resultsCount: number) => void;
+    viewFaq: (faqId: string, question: string) => void;
+};
+export declare const trackForm: {
+    submit: (formName: string) => void;
+};
+export declare const trackAdmin: {
+    action: (action: string, target: string) => void;
+};

package/dist/monitoring/analytics.js

@@ -0,0 +1,171 @@
+import { getAnalytics, isSupported, logEvent, setUserId, setUserProperties, } from "firebase/analytics";
+import { logger } from "../core/Logger";
+let analytics = null;
+let analyticsEnabled = false;
+let ecommerceCurrency = "USD";
+export const ANALYTICS_EVENTS = {
+    PAGE_VIEW: "page_view",
+    LOGIN: "login",
+    SIGN_UP: "sign_up",
+    LOGOUT: "logout",
+    VIEW_ITEM: "view_item",
+    ADD_TO_CART: "add_to_cart",
+    PURCHASE: "purchase",
+    PLACE_BID: "place_bid",
+    WIN_AUCTION: "win_auction",
+    SEARCH: "search",
+    VIEW_FAQ: "view_faq",
+};
+export async function initializeAnalytics(params) {
+    analyticsEnabled = params.enabled ?? true;
+    if (params.currency) {
+        ecommerceCurrency = params.currency;
+    }
+    if (!analyticsEnabled)
+        return;
+    try {
+        const supported = await isSupported();
+        if (!supported)
+            return;
+        analytics = getAnalytics(params.app);
+    }
+    catch (error) {
+        analytics = null;
+        logger.warn("Firebase Analytics disabled", { error });
+    }
+}
+export const trackEvent = (eventName, eventParams) => {
+    if (!analytics || !analyticsEnabled)
+        return;
+    try {
+        logEvent(analytics, eventName, eventParams);
+    }
+    catch (error) {
+        logger.error(`Failed to log event ${eventName}`, { error });
+    }
+};
+export const setAnalyticsUserId = (userId) => {
+    if (!analytics || !analyticsEnabled)
+        return;
+    try {
+        setUserId(analytics, userId);
+    }
+    catch (error) {
+        logger.error("Failed to set user ID", { error });
+    }
+};
+export const setAnalyticsUserProperties = (properties) => {
+    if (!analytics || !analyticsEnabled)
+        return;
+    try {
+        setUserProperties(analytics, properties);
+    }
+    catch (error) {
+        logger.error("Failed to set user properties", { error });
+    }
+};
+export const trackPageView = (page_path, page_title) => {
+    trackEvent(ANALYTICS_EVENTS.PAGE_VIEW, {
+        page_path,
+        page_title,
+    });
+};
+export const trackAuth = {
+    login: (method) => {
+        trackEvent(ANALYTICS_EVENTS.LOGIN, { method });
+    },
+    register: (method) => {
+        trackEvent(ANALYTICS_EVENTS.SIGN_UP, { method });
+    },
+    logout: () => {
+        trackEvent(ANALYTICS_EVENTS.LOGOUT);
+    },
+};
+export const trackEcommerce = {
+    viewProduct: (product) => {
+        const currency = product.currency ?? ecommerceCurrency;
+        trackEvent(ANALYTICS_EVENTS.VIEW_ITEM, {
+            currency,
+            value: product.price,
+            items: [
+                {
+                    item_id: product.id,
+                    item_name: product.name,
+                    item_category: product.category,
+                    price: product.price,
+                },
+            ],
+        });
+    },
+    addToCart: (product) => {
+        const currency = product.currency ?? ecommerceCurrency;
+        trackEvent(ANALYTICS_EVENTS.ADD_TO_CART, {
+            currency,
+            value: product.price * product.quantity,
+            items: [
+                {
+                    item_id: product.id,
+                    item_name: product.name,
+                    item_category: product.category,
+                    price: product.price,
+                    quantity: product.quantity,
+                },
+            ],
+        });
+    },
+    purchase: (order) => {
+        const currency = order.currency ?? ecommerceCurrency;
+        trackEvent(ANALYTICS_EVENTS.PURCHASE, {
+            transaction_id: order.id,
+            currency,
+            value: order.total,
+            tax: order.tax || 0,
+            shipping: order.shipping || 0,
+            items: order.items.map((item) => ({
+                item_id: item.id,
+                item_name: item.name,
+                item_category: item.category,
+                price: item.price,
+                quantity: item.quantity,
+            })),
+        });
+    },
+    placeBid: (product) => {
+        trackEvent(ANALYTICS_EVENTS.PLACE_BID, {
+            product_id: product.id,
+            product_name: product.name,
+            bid_amount: product.bidAmount,
+        });
+    },
+    winAuction: (product) => {
+        trackEvent(ANALYTICS_EVENTS.WIN_AUCTION, {
+            product_id: product.id,
+            product_name: product.name,
+            final_bid: product.finalBid,
+        });
+    },
+};
+export const trackContent = {
+    search: (searchTerm, resultsCount) => {
+        trackEvent(ANALYTICS_EVENTS.SEARCH, {
+            search_term: searchTerm,
+            results_count: resultsCount,
+        });
+    },
+    viewFaq: (faqId, question) => {
+        trackEvent(ANALYTICS_EVENTS.VIEW_FAQ, {
+            faq_id: faqId,
+            question,
+        });
+    },
+};
+export const trackForm = {
+    submit: (formName) => {
+        trackEvent("form_submit", { form_name: formName });
+    },
+};
+export const trackAdmin = {
+    action: (action, target) => {
+        trackEvent("admin_action", { action, target });
+    },
+};

package/dist/monitoring/browser.d.ts

@@ -0,0 +1,10 @@
+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 { 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/browser.js

@@ -0,0 +1,6 @@
+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 { 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/cache-metrics.d.ts

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

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

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

@@ -0,0 +1,127 @@
+/**
+ * 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,
+        });
+    });
+};