@mohasinac/appkit 2.1.3 → 2.3.0

package/src/instrumentation/index.ts

@@ -1,77 +0,0 @@
-/**
- * @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 function createInstrumentation(
-  config: InstrumentationConfig,
-): InstrumentationHook {
-  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/src/monitoring/cache-metrics.ts

@@ -1,105 +0,0 @@
-/**
- * Cache Performance Metrics — pure localStorage implementation.
- * No Firebase dependencies.
- */
-
-interface CacheMetrics {
-  hits: number;
-  misses: number;
-  totalRequests: number;
-  hitRate: number;
-  lastReset: string;
-}
-
-const STORAGE_KEY = "mohasinac:cache_metrics";
-const RESET_INTERVAL_MS = 3_600_000; // 1 hour
-
-function nowISO(): string {
-  return new Date().toISOString();
-}
-
-function initializeMetrics(): CacheMetrics {
-  const m: CacheMetrics = {
-    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(): CacheMetrics {
-  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) as CacheMetrics;
-    if (Date.now() - new Date(m.lastReset).getTime() > RESET_INTERVAL_MS) {
-      return initializeMetrics();
-    }
-    return m;
-  } catch {
-    return initializeMetrics();
-  }
-}
-
-function saveMetrics(m: CacheMetrics): void {
-  if (typeof localStorage !== "undefined") {
-    localStorage.setItem(STORAGE_KEY, JSON.stringify(m));
-  }
-}
-
-export function recordCacheHit(): void {
-  const m = getCacheMetrics();
-  m.hits++;
-  m.totalRequests++;
-  m.hitRate = m.totalRequests > 0 ? m.hits / m.totalRequests : 0;
-  saveMetrics(m);
-}
-
-export function recordCacheMiss(): void {
-  const m = getCacheMetrics();
-  m.misses++;
-  m.totalRequests++;
-  m.hitRate = m.totalRequests > 0 ? m.hits / m.totalRequests : 0;
-  saveMetrics(m);
-}
-
-export function resetCacheMetrics(): void {
-  initializeMetrics();
-}
-
-export function getCacheHitRate(): number {
-  return getCacheMetrics().hitRate;
-}
-
-export function isCacheHitRateLow(threshold: number = 0.5): boolean {
-  return getCacheHitRate() < threshold;
-}
-
-export function getCacheStatistics(): {
-  hitRate: string;
-  totalRequests: number;
-  hits: number;
-  misses: number;
-} {
-  const m = getCacheMetrics();
-  return {
-    hitRate: `${(m.hitRate * 100).toFixed(1)}%`,
-    totalRequests: m.totalRequests,
-    hits: m.hits,
-    misses: m.misses,
-  };
-}

package/src/monitoring/client-logger.ts

@@ -1,83 +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";
-import { AppError } from "../errors";
-
-export interface ClientErrorContext {
-  userId?: string;
-  component?: string;
-  action?: string;
-  url?: string;
-  method?: string;
-  statusCode?: number;
-  [key: string]: unknown;
-}
-
-function buildClientMeta(
-  error: unknown,
-  context?: ClientErrorContext,
-): Record<string, unknown> {
-  const base: Record<string, unknown> = {
-    ...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: string,
-  error: unknown,
-  context?: ClientErrorContext,
-): void => {
-  logger.error(message, buildClientMeta(error, context));
-};
-
-export const logClientWarning = (
-  message: string,
-  data?: ClientErrorContext,
-): void => {
-  logger.warn(message, { ...data, timestamp: new Date().toISOString() });
-};
-
-export const logClientInfo = (
-  message: string,
-  data?: ClientErrorContext,
-): void => {
-  logger.info(message, { ...data, timestamp: new Date().toISOString() });
-};
-
-export const logClientDebug = (
-  message: string,
-  data?: ClientErrorContext,
-): void => {
-  logger.debug(message, { ...data, timestamp: new Date().toISOString() });
-};

package/src/monitoring/error-tracking.ts

@@ -1,115 +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 enum ErrorSeverity {
-  LOW = "low",
-  MEDIUM = "medium",
-  HIGH = "high",
-  CRITICAL = "critical",
-}
-
-export 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;
-
-const TRACKER_KEY = "__mohasinac_error_tracker__" as const;
-
-declare global {
-  // eslint-disable-next-line no-var
-  var __mohasinac_error_tracker__: ErrorTrackerFn | undefined;
-}
-
-function getTracker(): ErrorTrackerFn {
-  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: ErrorTrackerFn): void {
-  (globalThis as Record<string, unknown>)[TRACKER_KEY] = fn;
-}
-
-export function trackError(
-  error: Error | string,
-  category: ErrorCategory = ErrorCategory.UNKNOWN,
-  severity: ErrorSeverity = ErrorSeverity.MEDIUM,
-  context?: ErrorContext,
-): void {
-  getTracker()(error, category, severity, context);
-}
-
-export function trackApiError(
-  error: Error | string,
-  context?: ErrorContext,
-): void {
-  trackError(error, ErrorCategory.API, ErrorSeverity.HIGH, context);
-}
-
-export function trackAuthError(
-  error: Error | string,
-  context?: ErrorContext,
-): void {
-  trackError(error, ErrorCategory.AUTHENTICATION, ErrorSeverity.HIGH, context);
-}
-
-export function trackValidationError(
-  error: Error | string,
-  context?: ErrorContext,
-): void {
-  trackError(error, ErrorCategory.VALIDATION, ErrorSeverity.LOW, context);
-}
-
-export function trackDatabaseError(
-  error: Error | string,
-  context?: ErrorContext,
-): void {
-  trackError(error, ErrorCategory.DATABASE, ErrorSeverity.CRITICAL, context);
-}
-
-export function trackPermissionError(
-  error: Error | string,
-  context?: ErrorContext,
-): void {
-  trackError(error, ErrorCategory.PERMISSION, ErrorSeverity.MEDIUM, context);
-}

package/src/monitoring/index.ts

@@ -1,52 +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,
-} from "./client-logger";
-export type { ClientErrorContext } from "./client-logger";
-export {
-  logServerError,
-  logServerWarning,
-  logServerInfo,
-  logServerDebug,
-  extractRequestMetadata,
-} from "./server-logger";
-export type { ServerErrorContext } from "./server-logger";
-export {
-  setPerformanceProvider,
-  startTrace,
-  stopTrace,
-  addTraceAttribute,
-  addTraceMetric,
-} from "./performance";
-export type { PerformanceTrace, PerformanceProvider } from "./performance";

package/src/monitoring/performance.ts

@@ -1,64 +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;
-}
-
-const PROVIDER_KEY = "__mohasinac_perf_provider__" as const;
-
-declare global {
-  // eslint-disable-next-line no-var
-  var __mohasinac_perf_provider__: PerformanceProvider | undefined;
-}
-
-/** Register a concrete performance backend (call once in instrumentation). */
-export function setPerformanceProvider(provider: PerformanceProvider): void {
-  (globalThis as Record<string, unknown>)[PROVIDER_KEY] = provider;
-}
-
-function getProvider(): PerformanceProvider | undefined {
-  return globalThis.__mohasinac_perf_provider__;
-}
-
-/** Start a named trace. Returns `null` when no provider is registered. */
-export function startTrace(name: string): PerformanceTrace | null {
-  return getProvider()?.startTrace(name) ?? null;
-}
-
-/** Stop a trace returned by `startTrace`. Safe to call with `null`. */
-export function stopTrace(t: PerformanceTrace | null): void {
-  t?.stop();
-}
-
-/** Attach a string attribute to a trace. Safe to call with `null`. */
-export function addTraceAttribute(
-  t: PerformanceTrace | null,
-  key: string,
-  value: string,
-): void {
-  t?.putAttribute(key, value);
-}
-
-/** Record a numeric metric on a trace. Safe to call with `null`. */
-export function addTraceMetric(
-  t: PerformanceTrace | null,
-  key: string,
-  value: number,
-): void {
-  t?.putMetric(key, value);
-}

package/src/monitoring/runtime.ts

@@ -1,33 +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(): void {
-  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(): void {}

package/src/monitoring/server-logger.ts

@@ -1,93 +0,0 @@
-/**
- * Server-Side Error Logging Utilities
- *
- * Wraps the Logger singleton for use in API routes, server components, and
- * server actions. Attaches request metadata when a NextRequest is available.
- *
- * IMPORTANT: Only import this file in server-side code. For client-side code
- * use `client-logger.ts`.
- */
-
-import { logger } from "../core";
-import { AppError } from "../errors";
-import { type NextRequest } from "next/server";
-
-export interface ServerErrorContext {
-  userId?: string;
-  endpoint?: string;
-  method?: string;
-  statusCode?: number;
-  requestId?: string;
-  [key: string]: unknown;
-}
-
-/** Pull the commonly needed headers from a NextRequest in one call. */
-export const extractRequestMetadata = (request: NextRequest) => ({
-  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: unknown,
-  context?: ServerErrorContext,
-): Record<string, unknown> {
-  const base: Record<string, unknown> = {
-    ...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: string,
-  error: unknown,
-  context?: ServerErrorContext,
-): void => {
-  logger.error(message, buildServerMeta(error, context));
-};
-
-export const logServerWarning = (
-  message: string,
-  data?: ServerErrorContext,
-): void => {
-  logger.warn(message, { ...data, timestamp: new Date().toISOString() });
-};
-
-export const logServerInfo = (
-  message: string,
-  data?: ServerErrorContext,
-): void => {
-  logger.info(message, { ...data, timestamp: new Date().toISOString() });
-};
-
-export const logServerDebug = (
-  message: string,
-  data?: ServerErrorContext,
-): void => {
-  logger.debug(message, { ...data, timestamp: new Date().toISOString() });
-};

package/src/next/IAuthVerifier.ts

@@ -1,56 +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>;
-}