@tumbaland/frontend-core 1.1.1 → 1.2.1

package/dist/apiClient.d.ts

@@ -7,6 +7,8 @@ export interface ApiClientOptions {
 export interface ApiRequestOptions extends RequestInit {
     /** Skip the onUnauthorized callback for this call (e.g. an auth-check that expects 401 as a normal "not logged in" result, not a hard redirect). */
     skipAuthRedirect?: boolean;
+    /** Serialized onto the URL as a query string; undefined/null values are omitted. */
+    params?: Record<string, string | number | boolean | undefined | null>;
 }
 export declare class ApiError extends Error {
     status: number;
@@ -18,9 +20,7 @@ export declare class ApiError extends Error {
  * correlation/session headers, structured errors, and an opt-in 401 →
  * redirect-to-auth hook, per TECHNICAL_REVIEW.md P1.3. `authService` and
  * `groupService` don't route through this: they use different auth
- * transports (cookie vs. Bearer token) that predate this client. New
- * call sites (the many per-front album/finance/etc. service files that
- * still hand-roll fetch) can adopt this incrementally.
+ * transports (cookie vs. Bearer token) that predate this client.
  */
 export declare function createApiClient(options: ApiClientOptions): {
     request: <T = unknown>(path: string, init?: ApiRequestOptions) => Promise<T>;

package/dist/apiClient.js

@@ -1,4 +1,18 @@
-import { getCorrelationId, getSessionId } from '@tumbaland/components';
+import { getCorrelationId, getSessionId } from './monitoring';
+function appendParams(path, params) {
+    if (!params)
+        return path;
+    const searchParams = new URLSearchParams();
+    Object.entries(params).forEach(([key, value]) => {
+        if (value !== undefined && value !== null) {
+            searchParams.append(key, String(value));
+        }
+    });
+    const query = searchParams.toString();
+    if (!query)
+        return path;
+    return `${path}${path.includes('?') ? '&' : '?'}${query}`;
+}
 export class ApiError extends Error {
     constructor(status, message, body) {
         super(message);
@@ -12,14 +26,12 @@ export class ApiError extends Error {
  * correlation/session headers, structured errors, and an opt-in 401 →
  * redirect-to-auth hook, per TECHNICAL_REVIEW.md P1.3. `authService` and
  * `groupService` don't route through this: they use different auth
- * transports (cookie vs. Bearer token) that predate this client. New
- * call sites (the many per-front album/finance/etc. service files that
- * still hand-roll fetch) can adopt this incrementally.
+ * transports (cookie vs. Bearer token) that predate this client.
  */
 export function createApiClient(options) {
     async function request(path, init = {}) {
-        const { skipAuthRedirect, headers, ...rest } = init;
-        const response = await fetch(`${options.baseUrl()}${path}`, {
+        const { skipAuthRedirect, headers, params, ...rest } = init;
+        const response = await fetch(`${options.baseUrl()}${appendParams(path, params)}`, {
             credentials: 'include',
             ...rest,
             headers: {

package/dist/authService.js

@@ -1,4 +1,4 @@
-import { getCorrelationId, getSessionId } from '@tumbaland/components';
+import { getCorrelationId, getSessionId } from './monitoring';
 const AUTH_CACHE_TTL = 5 * 60 * 1000;
 function authHeaders() {
     return {

package/dist/groupService.js

@@ -1,4 +1,4 @@
-import { getCorrelationId, getSessionId } from '@tumbaland/components';
+import { getCorrelationId, getSessionId } from './monitoring';
 function groupHeaders() {
     return {
         'Content-Type': 'application/json',

package/dist/index.d.ts

@@ -5,3 +5,5 @@ export type { AuthServiceConfig, AuthService } from './authService';
 export { createGroupService } from './groupService';
 export type { GroupServiceConfig, GroupService } from './groupService';
 export type { User, AuthResponse, Group, ApiResponse } from './types';
+export { initMonitoring, captureException, captureMessage, setUser, setTag, startTransaction, recordMetric, initWebVitals, flushLogs, initConsoleInterception, generateCorrelationId, getCorrelationId, getSessionId, logger } from './monitoring';
+export type { MonitoringConfig } from './monitoring';

package/dist/index.js

@@ -2,3 +2,5 @@
 export { createApiClient, ApiError } from './apiClient';
 export { createAuthService } from './authService';
 export { createGroupService } from './groupService';
+// Monitoring: headless logging, error capture, correlation IDs, and web-vitals
+export { initMonitoring, captureException, captureMessage, setUser, setTag, startTransaction, recordMetric, initWebVitals, flushLogs, initConsoleInterception, generateCorrelationId, getCorrelationId, getSessionId, logger } from './monitoring';

package/dist/monitoring/batch.d.ts

@@ -0,0 +1,2 @@
+export declare const queueLog: (logData: any) => void;
+export declare const flushLogs: () => Promise<void>;

package/dist/monitoring/batch.js

@@ -0,0 +1,87 @@
+// Batch logging system for efficient log transmission
+import { getMonitoringConfig } from './config';
+// Log batching for better performance
+let logBatch = [];
+let batchTimeout = null;
+const BATCH_SIZE = 10;
+const BATCH_INTERVAL = 5000; // 5 seconds
+// Send batched logs
+const sendBatch = async () => {
+    if (logBatch.length === 0)
+        return;
+    const config = getMonitoringConfig();
+    if (!config.elkUrl)
+        return;
+    const batchToSend = [...logBatch];
+    logBatch = [];
+    try {
+        const response = await fetch(config.elkUrl, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(batchToSend),
+        });
+        if (!response.ok) {
+            throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+        }
+    }
+    catch (error) {
+        // Log error without triggering console interception to prevent recursion
+        const originalWarn = console.warn;
+        console.warn = () => { }; // Temporarily disable console.warn
+        try {
+            console.warn('Failed to send log batch, dropping logs:', error);
+            // Optional: log failed batch to console in development
+            if (config.isDevelopment) {
+                batchToSend.forEach(log => {
+                    console.warn('📝 [DROPPED LOG]:', JSON.stringify(log));
+                });
+            }
+        }
+        finally {
+            console.warn = originalWarn; // Restore original console.warn
+        }
+    }
+};
+// Queue log for batching
+export const queueLog = (logData) => {
+    logBatch.push(logData);
+    // Send immediately if batch is full
+    if (logBatch.length >= BATCH_SIZE) {
+        if (batchTimeout) {
+            clearTimeout(batchTimeout);
+            batchTimeout = null;
+        }
+        sendBatch();
+        return;
+    }
+    // Schedule batch send
+    if (!batchTimeout) {
+        batchTimeout = setTimeout(() => {
+            batchTimeout = null;
+            sendBatch();
+        }, BATCH_INTERVAL);
+    }
+};
+// Flush logs before page unload
+export const flushLogs = async () => {
+    if (batchTimeout) {
+        clearTimeout(batchTimeout);
+        batchTimeout = null;
+    }
+    await sendBatch();
+};
+// Set up page unload handler
+if (typeof window !== 'undefined') {
+    window.addEventListener('beforeunload', () => {
+        // Synchronous flush for critical logs - use sendBeacon for reliable delivery during page unload
+        const config = getMonitoringConfig();
+        if (logBatch.length > 0 && navigator.sendBeacon && config.elkUrl) {
+            // Use sendBeacon for reliable delivery during page unload
+            const blob = new Blob([JSON.stringify(logBatch)], { type: 'application/json' });
+            navigator.sendBeacon(config.elkUrl, blob);
+            logBatch = [];
+        }
+    });
+}

package/dist/monitoring/config.d.ts

@@ -0,0 +1,16 @@
+export interface MonitoringConfig {
+    isDevelopment: boolean;
+    service: string;
+    component: string;
+    elkUrl?: string;
+    captureConsoleLevels?: ('debug' | 'info' | 'warn' | 'error')[];
+}
+export declare const isInterceptingConsole: () => boolean;
+export declare const getMonitoringConfig: () => MonitoringConfig;
+export declare const updateMonitoringConfig: (config: Partial<MonitoringConfig>) => void;
+export declare const initMonitoring: (environment?: string, options?: {
+    service?: string;
+    component?: string;
+    elkUrl?: string;
+    captureConsoleLevels?: ("debug" | "info" | "warn" | "error")[];
+}) => void;

package/dist/monitoring/config.js

@@ -0,0 +1,53 @@
+// Global monitoring configuration
+let monitoringConfig = {
+    isDevelopment: false,
+    service: 'frontend',
+    component: 'frontend'
+};
+// Flag to prevent recursive console interception
+export const isInterceptingConsole = () => {
+    return typeof window !== 'undefined' && window._monitoringInterceptingConsole === true;
+};
+// Get current monitoring configuration
+export const getMonitoringConfig = () => monitoringConfig;
+// Update monitoring configuration
+export const updateMonitoringConfig = (config) => {
+    monitoringConfig = { ...monitoringConfig, ...config };
+};
+// Initialize local monitoring (no remote services)
+export const initMonitoring = (environment = 'development', options = {}) => {
+    const { service = 'frontend', component = 'frontend', elkUrl, captureConsoleLevels = ['error', 'warn'] // Default to error and warn only
+     } = options;
+    // Update global config
+    updateMonitoringConfig({
+        isDevelopment: environment === 'development',
+        service,
+        component,
+        elkUrl
+    });
+    console.log(`📊 Local monitoring initialized (${environment} mode) for ${service}/${component}`);
+    console.log(`📝 Console interception enabled for levels: ${captureConsoleLevels.join(', ')}`);
+    // Initialize console interception and error handlers after modules are loaded
+    Promise.all([
+        import('./console'),
+        import('./errors')
+    ]).then(([{ initConsoleInterception }, { captureException, captureMessage }]) => {
+        // Initialize console interception with capture function
+        initConsoleInterception(captureConsoleLevels, captureMessage);
+        // Set up global error handlers
+        if (typeof window !== 'undefined') {
+            window.addEventListener('error', (event) => {
+                captureException(event.error || new Error(event.message), {
+                    filename: event.filename,
+                    lineno: event.lineno,
+                    colno: event.colno
+                });
+            });
+            window.addEventListener('unhandledrejection', (event) => {
+                captureException(new Error(`Unhandled promise rejection: ${event.reason}`), {
+                    type: 'unhandledrejection'
+                });
+            });
+        }
+    });
+};

package/dist/monitoring/console.d.ts

@@ -0,0 +1,3 @@
+type CaptureMessageFn = (message: string, level: 'debug' | 'info' | 'warn' | 'error', context?: any) => void;
+export declare const initConsoleInterception: (captureConsoleLevels?: ("debug" | "info" | "warn" | "error")[], captureMessageFn?: CaptureMessageFn) => void;
+export {};

package/dist/monitoring/console.js

@@ -0,0 +1,40 @@
+// Console interception for automatic log capture
+import { isInterceptingConsole } from './config';
+// Initialize console interception
+export const initConsoleInterception = (captureConsoleLevels = ['error', 'warn'], captureMessageFn) => {
+    // If no capture function provided, skip interception
+    if (!captureMessageFn)
+        return;
+    // Helper function to conditionally intercept console methods
+    const interceptConsole = (methodName, level) => {
+        if (!captureConsoleLevels.includes(level))
+            return;
+        const originalMethod = console[methodName];
+        console[methodName] = (...args) => {
+            // Call original console method
+            originalMethod.apply(console, args);
+            // Prevent recursive interception by checking the global flag
+            if (isInterceptingConsole())
+                return;
+            // Send to logging API with recursion protection
+            try {
+                const message = args.map(arg => typeof arg === 'object' ? JSON.stringify(arg) : String(arg)).join(' ');
+                // Set interception flag to prevent recursion during capture
+                window._monitoringInterceptingConsole = true;
+                captureMessageFn(message, level, {
+                    source: `console.${methodName}`,
+                    args: args
+                });
+            }
+            finally {
+                window._monitoringInterceptingConsole = false;
+            }
+        };
+    };
+    // Intercept console methods based on configuration
+    interceptConsole('error', 'error');
+    interceptConsole('warn', 'warn');
+    interceptConsole('log', 'info');
+    interceptConsole('info', 'info');
+    interceptConsole('debug', 'debug');
+};

package/dist/monitoring/errors.d.ts

@@ -0,0 +1,12 @@
+export declare const captureException: (error: Error, context?: any, options?: {
+    isDevelopment?: boolean;
+    service?: string;
+    component?: string;
+    elkUrl?: string;
+}) => Promise<void>;
+export declare const captureMessage: (message: string, level?: "debug" | "info" | "warn" | "error", context?: any, options?: {
+    isDevelopment?: boolean;
+    service?: string;
+    component?: string;
+    elkUrl?: string;
+}) => Promise<void>;

package/dist/monitoring/errors.js

@@ -0,0 +1,67 @@
+// Error and message tracking
+import { getMonitoringConfig, isInterceptingConsole } from './config';
+import { queueLog } from './batch';
+import { getCorrelationId, getSessionId } from './utils';
+// Error tracking with local ELK logging
+export const captureException = async (error, context, options = {}) => {
+    const config = { ...getMonitoringConfig(), ...options };
+    const errorData = {
+        timestamp: new Date().toISOString(),
+        level: 'error',
+        service: config.service,
+        component: config.component,
+        message: error.message,
+        stack: error.stack,
+        userAgent: typeof navigator !== 'undefined' ? navigator.userAgent : undefined,
+        url: typeof window !== 'undefined' ? window.location.href : undefined,
+        context: context || {},
+        correlationId: getCorrelationId(),
+        sessionId: getSessionId()
+    };
+    // Always log to console for development
+    if (config.isDevelopment) {
+        const originalIsIntercepting = isInterceptingConsole();
+        window._monitoringInterceptingConsole = true;
+        try {
+            console.error('🚨 Frontend Error:', errorData);
+        }
+        finally {
+            window._monitoringInterceptingConsole = originalIsIntercepting;
+        }
+    }
+    // Send to local ELK stack if available (batched)
+    if (config.elkUrl) {
+        queueLog(errorData);
+    }
+};
+export const captureMessage = async (message, level = 'info', context, options = {}) => {
+    const config = { ...getMonitoringConfig(), ...options };
+    const logData = {
+        timestamp: new Date().toISOString(),
+        level: level.toLowerCase(),
+        service: config.service,
+        component: config.component,
+        message,
+        url: typeof window !== 'undefined' ? window.location.href : undefined,
+        userAgent: typeof navigator !== 'undefined' ? navigator.userAgent : undefined,
+        context: context || {},
+        correlationId: getCorrelationId(),
+        sessionId: getSessionId()
+    };
+    // Always log to console for development
+    if (config.isDevelopment) {
+        const originalIsIntercepting = isInterceptingConsole();
+        window._monitoringInterceptingConsole = true;
+        try {
+            const logLevel = level.toUpperCase();
+            console.log(`[${logLevel}] ${message}`, context || '');
+        }
+        finally {
+            window._monitoringInterceptingConsole = originalIsIntercepting;
+        }
+    }
+    // Send to local ELK stack if available (batched)
+    if (config.elkUrl) {
+        queueLog(logData);
+    }
+};

package/dist/monitoring/index.d.ts

@@ -0,0 +1,9 @@
+export { initMonitoring } from './config';
+export { captureException, captureMessage } from './errors';
+export { setUser, setTag } from './performance';
+export { startTransaction, recordMetric, initWebVitals } from './performance';
+export { flushLogs } from './batch';
+export { initConsoleInterception } from './console';
+export { generateCorrelationId, getCorrelationId, getSessionId } from './utils';
+export { logger } from './logger';
+export type { MonitoringConfig } from './config';

package/dist/monitoring/index.js

@@ -0,0 +1,17 @@
+// Main monitoring exports - modular architecture
+// Configuration and initialization
+export { initMonitoring } from './config';
+// Error and message tracking
+export { captureException, captureMessage } from './errors';
+// User and tag tracking
+export { setUser, setTag } from './performance';
+// Performance monitoring
+export { startTransaction, recordMetric, initWebVitals } from './performance';
+// Batch logging utilities
+export { flushLogs } from './batch';
+// Console interception (for advanced usage)
+export { initConsoleInterception } from './console';
+// Correlation ID utilities
+export { generateCorrelationId, getCorrelationId, getSessionId } from './utils';
+// Small ergonomic logger wrapping captureMessage/captureException
+export { logger } from './logger';

package/dist/monitoring/logger.d.ts

@@ -0,0 +1,6 @@
+export declare const logger: {
+    debug: (message: string, context?: Record<string, unknown>) => Promise<void>;
+    info: (message: string, context?: Record<string, unknown>) => Promise<void>;
+    warn: (message: string, context?: Record<string, unknown>) => Promise<void>;
+    error: (message: string, error?: unknown, context?: Record<string, unknown>) => void;
+};

package/dist/monitoring/logger.js

@@ -0,0 +1,18 @@
+// Small frontend logger — routes through the same captureMessage/captureException
+// pipeline as console interception, but as an explicit call so it's captured
+// regardless of the per-app captureConsoleLevels configuration (which usually only
+// intercepts 'error'/'warn'), and carries structured context instead of a string blob.
+import { captureException, captureMessage } from './errors';
+export const logger = {
+    debug: (message, context) => captureMessage(message, 'debug', context),
+    info: (message, context) => captureMessage(message, 'info', context),
+    warn: (message, context) => captureMessage(message, 'warn', context),
+    error: (message, error, context) => {
+        if (error instanceof Error) {
+            captureException(error, { message, ...context });
+        }
+        else {
+            captureMessage(message, 'error', error !== undefined ? { error, ...context } : context);
+        }
+    }
+};

package/dist/monitoring/performance.d.ts

@@ -0,0 +1,24 @@
+export declare const setUser: (user: {
+    id: string;
+    email?: string;
+    username?: string;
+}, options?: {
+    isDevelopment?: boolean;
+}) => void;
+export declare const setTag: (key: string, value: string, options?: {
+    isDevelopment?: boolean;
+}) => void;
+export declare const startTransaction: (name: string, op: string, options?: {
+    isDevelopment?: boolean;
+}) => {
+    finish: () => void;
+};
+export declare const recordMetric: (name: string, value: number | {
+    value: number;
+    id?: string;
+}, unit?: string, options?: {
+    isDevelopment?: boolean;
+}) => void;
+export declare const initWebVitals: (options?: {
+    isDevelopment?: boolean;
+}) => Promise<void>;

package/dist/monitoring/performance.js

@@ -0,0 +1,118 @@
+// Performance monitoring utilities
+import { getMonitoringConfig, isInterceptingConsole } from './config';
+// Web vitals will be loaded dynamically
+let webVitals = null;
+// User tracking (local storage only)
+export const setUser = (user, options = {}) => {
+    const config = { ...getMonitoringConfig(), ...options };
+    if (config.isDevelopment) {
+        const originalIsIntercepting = isInterceptingConsole();
+        window._monitoringInterceptingConsole = true;
+        try {
+            console.log('👤 User set:', user);
+        }
+        finally {
+            window._monitoringInterceptingConsole = originalIsIntercepting;
+        }
+    }
+    // Could store in localStorage for persistence if needed
+};
+export const setTag = (key, value, options = {}) => {
+    const config = { ...getMonitoringConfig(), ...options };
+    if (config.isDevelopment) {
+        const originalIsIntercepting = isInterceptingConsole();
+        window._monitoringInterceptingConsole = true;
+        try {
+            console.log(`🏷️ Tag set: ${key} = ${value}`);
+        }
+        finally {
+            window._monitoringInterceptingConsole = originalIsIntercepting;
+        }
+    }
+    // Store tags locally if needed for context
+};
+// Performance monitoring utilities (local only)
+export const startTransaction = (name, op, options = {}) => {
+    const config = { ...getMonitoringConfig(), ...options };
+    const startTime = Date.now();
+    if (config.isDevelopment) {
+        const originalIsIntercepting = isInterceptingConsole();
+        window._monitoringInterceptingConsole = true;
+        try {
+            console.log(`⏱️ Transaction started: ${name} (${op})`);
+        }
+        finally {
+            window._monitoringInterceptingConsole = originalIsIntercepting;
+        }
+    }
+    return {
+        finish: () => {
+            const duration = Date.now() - startTime;
+            recordMetric(`${name}_duration`, duration, 'ms', { isDevelopment: config.isDevelopment });
+            if (config.isDevelopment) {
+                const originalIsIntercepting = isInterceptingConsole();
+                window._monitoringInterceptingConsole = true;
+                try {
+                    console.log(`✅ Transaction finished: ${name} (${duration}ms)`);
+                }
+                finally {
+                    window._monitoringInterceptingConsole = originalIsIntercepting;
+                }
+            }
+        }
+    };
+};
+export const recordMetric = (name, value, unit = 'ms', options = {}) => {
+    const config = { ...getMonitoringConfig(), ...options };
+    // Handle both number and metric object formats
+    const metricValue = typeof value === 'number' ? value : value.value;
+    // Always log to console for development with better formatting
+    if (config.isDevelopment) {
+        const originalIsIntercepting = isInterceptingConsole();
+        window._monitoringInterceptingConsole = true;
+        try {
+            const formattedValue = unit === 'ms' ? `${metricValue.toFixed(2)}ms` : `${metricValue}${unit}`;
+            console.log(`📊 Performance: ${name} = ${formattedValue}`);
+        }
+        finally {
+            window._monitoringInterceptingConsole = originalIsIntercepting;
+        }
+    }
+    // Note: Sentry performance measurement removed due to API changes
+    // Can be re-added when Sentry API is updated
+};
+// Basic performance observer for web vitals
+export const initWebVitals = async (options = {}) => {
+    const config = { ...getMonitoringConfig(), ...options };
+    if (config.isDevelopment) {
+        const originalIsIntercepting = isInterceptingConsole();
+        window._monitoringInterceptingConsole = true;
+        try {
+            console.log('📊 Web Vitals monitoring initialized (development mode)');
+        }
+        finally {
+            window._monitoringInterceptingConsole = originalIsIntercepting;
+        }
+        try {
+            // Dynamic import of web-vitals
+            const webVitalsModule = await import('web-vitals');
+            webVitals = webVitalsModule;
+            // Use the new web-vitals API (v5+)
+            webVitals.onCLS((metric) => recordMetric('CLS', metric, 'unitless', { isDevelopment: config.isDevelopment }));
+            webVitals.onFCP((metric) => recordMetric('FCP', metric, 'ms', { isDevelopment: config.isDevelopment }));
+            webVitals.onLCP((metric) => recordMetric('LCP', metric, 'ms', { isDevelopment: config.isDevelopment }));
+            webVitals.onTTFB((metric) => recordMetric('TTFB', metric, 'ms', { isDevelopment: config.isDevelopment }));
+            // Note: FID is deprecated in web-vitals v5
+        }
+        catch (e) {
+            const originalIsIntercepting = isInterceptingConsole();
+            window._monitoringInterceptingConsole = true;
+            try {
+                console.warn('Web Vitals library not available - install web-vitals package');
+            }
+            finally {
+                window._monitoringInterceptingConsole = originalIsIntercepting;
+            }
+        }
+    }
+};

package/dist/monitoring/utils.d.ts

@@ -0,0 +1,3 @@
+export declare const generateCorrelationId: () => string;
+export declare const getSessionId: () => string;
+export declare const getCorrelationId: () => string;

package/dist/monitoring/utils.js

@@ -0,0 +1,25 @@
+// Utility functions for monitoring
+// Generate correlation ID using crypto.randomUUID()
+export const generateCorrelationId = () => {
+    return crypto.randomUUID();
+};
+// Get or create a session ID (persistent across the user's session)
+let sessionId = null;
+export const getSessionId = () => {
+    if (!sessionId) {
+        sessionId = generateCorrelationId();
+    }
+    return sessionId;
+};
+// Get correlation ID from server-set meta tag or generate request-specific ID
+export const getCorrelationId = () => {
+    // Try to get from server-set meta tag first (proxy-generated)
+    if (typeof document !== 'undefined') {
+        const metaTag = document.querySelector('meta[name="x-correlation-id"]');
+        if (metaTag && metaTag.getAttribute('content')) {
+            return metaTag.getAttribute('content');
+        }
+    }
+    // Fallback: generate per-request correlation ID
+    return generateCorrelationId();
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tumbaland/frontend-core",
-  "version": "1.1.1",
+  "version": "1.2.1",
   "description": "Shared frontend auth/group/API-client logic for Tumbaland frontends",
   "author": "Tumbaland",
   "license": "MIT",
@@ -18,7 +18,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@tumbaland/components": "*"
+    "web-vitals": "^5.3.0"
   },
   "devDependencies": {
     "@types/node": "^26.1.0",