@od-oneapp/observability 2026.1.1301

package/src/core/manager.ts

@@ -0,0 +1,361 @@
+/**
+ * @fileoverview ObservabilityManager - Core orchestrator for multiple observability providers
+ * ObservabilityManager - Core orchestrator for multiple observability providers
+ */
+
+import { logError, logWarn } from '@repo/shared/logs';
+
+import type { ObservabilityPlugin, ObservabilityServerPlugin, PluginLifecycle } from './plugin';
+import type {
+  Breadcrumb,
+  LogLevel,
+  ObservabilityContext,
+  ObservabilityScope,
+  ObservabilityServer,
+  ObservabilityUser,
+} from './types';
+
+/**
+ * Manager that orchestrates multiple observability plugins
+ * Broadcasts all method calls to enabled plugins
+ */
+export class ObservabilityManager implements ObservabilityServer {
+  private plugins = new Map<string, ObservabilityPlugin | ObservabilityServerPlugin>();
+  private initialized = false;
+  private initializationPromise: Promise<void> | null = null;
+  private lifecycle: PluginLifecycle = {};
+  private initializationError: Error | null = null;
+
+  /**
+   * Create a new ObservabilityManager instance.
+   *
+   * @param lifecycle - Optional lifecycle callbacks for plugin events
+   */
+  constructor(lifecycle?: PluginLifecycle) {
+    if (lifecycle) {
+      this.lifecycle = lifecycle;
+    }
+  }
+
+  /**
+   * Add a plugin to the manager
+   */
+  addPlugin(plugin: ObservabilityPlugin | ObservabilityServerPlugin): this {
+    this.plugins.set(plugin.name, plugin);
+    return this;
+  }
+
+  /**
+   * Get a specific plugin by name.
+   *
+   * @param name - Name of the plugin to retrieve
+   * @returns Plugin instance if found, undefined otherwise
+   */
+  getPlugin<T extends ObservabilityPlugin>(name: string): T | undefined {
+    return this.plugins.get(name) as T;
+  }
+
+  /**
+   * Get all registered plugins.
+   *
+   * @returns Array of all registered plugins
+   */
+  getPlugins(): ObservabilityPlugin[] {
+    return Array.from(this.plugins.values());
+  }
+
+  /**
+   * List all registered plugins (alias for getPlugins).
+   *
+   * @returns Array of all registered plugins
+   */
+  listPlugins(): ObservabilityPlugin[] {
+    return this.getPlugins();
+  }
+
+  /**
+   * Initialize all plugins
+   * Note: Failed initialization is retryable - subsequent calls will re-attempt initialization.
+   * This allows recovery from transient failures (network issues, temporary misconfigurations).
+   */
+  async initialize(): Promise<void> {
+    // If there's already an initialization in progress, wait for it
+    if (this.initializationPromise) {
+      return this.initializationPromise;
+    }
+
+    // If already initialized successfully, return early
+    if (this.initialized) {
+      return;
+    }
+
+    // Allow retry if previous attempt failed
+    if (this.initializationError) {
+      // Log retry attempt for debugging
+      logWarn('ObservabilityManager: Retrying failed initialization');
+      // Clear previous error to allow fresh attempt
+      this.initializationError = null;
+    }
+
+    // Create the initialization promise and store it to prevent concurrent calls
+    this.initializationPromise = this.doInitialize();
+
+    try {
+      await this.initializationPromise;
+    } finally {
+      // Clear the promise after initialization completes (success or failure)
+      this.initializationPromise = null;
+    }
+  }
+
+  private async doInitialize(): Promise<void> {
+    const initPromises = Array.from(this.plugins.values())
+      .filter(plugin => plugin.enabled && plugin.initialize)
+      .map(async plugin => {
+        try {
+          if (plugin.initialize) {
+            await plugin.initialize();
+          }
+          this.lifecycle.onInitialized?.(plugin);
+        } catch (error) {
+          logError(`Failed to initialize plugin ${plugin.name}`, {
+            error,
+            pluginName: plugin.name,
+          });
+          this.lifecycle.onError?.(error as Error, plugin);
+          // Re-throw to propagate error to Promise.all
+          throw error;
+        }
+      });
+
+    try {
+      await Promise.all(initPromises);
+      this.initialized = true;
+    } catch (error) {
+      this.initializationError = error instanceof Error ? error : new Error(String(error));
+      throw this.initializationError;
+    }
+  }
+
+  /**
+   * Check if initialization had an error
+   * @returns `true` if initialization failed, `false` otherwise
+   */
+  hasInitializationError(): boolean {
+    return this.initializationError !== null;
+  }
+
+  /**
+   * Get the initialization error if one occurred
+   * @returns The initialization error or `null` if no error
+   */
+  getInitializationError(): Error | null {
+    return this.initializationError;
+  }
+
+  /**
+   * Shutdown all plugins
+   */
+  async shutdown(): Promise<void> {
+    const shutdownPromises = Array.from(this.plugins.values())
+      .filter(plugin => plugin.shutdown)
+      .map(async plugin => {
+        try {
+          if (plugin.shutdown) {
+            await plugin.shutdown();
+          }
+          this.lifecycle.onShutdown?.(plugin);
+        } catch (error) {
+          logError(`Failed to shutdown plugin ${plugin.name}`, { error, pluginName: plugin.name });
+          this.lifecycle.onError?.(error as Error, plugin);
+        }
+      });
+
+    await Promise.allSettled(shutdownPromises);
+    this.initialized = false;
+  }
+
+  /**
+   * Broadcast exception to all enabled plugins.
+   *
+   * @param error - Error object or unknown error value
+   * @param context - Optional additional context data
+   */
+  captureException(error: Error | unknown, context?: ObservabilityContext): void {
+    this.broadcast(plugin => plugin.captureException(error, context));
+  }
+
+  /**
+   * Broadcast message to all enabled plugins.
+   *
+   * @param message - Message to log
+   * @param level - Log level (default: 'info')
+   * @param context - Optional additional context data
+   */
+  captureMessage(message: string, level: LogLevel = 'info', context?: ObservabilityContext): void {
+    this.broadcast(plugin => plugin.captureMessage(message, level, context));
+  }
+
+  /**
+   * Validate and sanitize user data to prevent injection and DoS attacks
+   * @param user - User data to validate
+   * @returns Validated user data with length limits and format validation applied
+   */
+  private validateUser(user: ObservabilityUser | null): ObservabilityUser | null {
+    if (!user) return null;
+
+    // Validate required ID field
+    const id = String(user.id).trim().slice(0, 255);
+    if (!id) {
+      // Log warning but don't throw - graceful degradation
+      logWarn('ObservabilityManager: User ID is empty, ignoring user data');
+      return null;
+    }
+
+    const validated: ObservabilityUser = { id };
+
+    // Validate email format if provided
+    if ('email' in user && user.email) {
+      const email = String(user.email).trim().slice(0, 255);
+      // More robust email validation - RFC 5322 simplified but stricter
+      // Allows: alphanumeric, dots, plus, hyphens, underscores before @
+      // Requires: valid domain with at least one dot after @
+      if (
+        email &&
+        // eslint-disable-next-line security/detect-unsafe-regex -- Safe: bounded input (max 255 chars), RFC 5322 compliant pattern
+        /^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/.test(
+          email,
+        )
+      ) {
+        validated.email = email;
+      }
+    }
+
+    // Validate username if provided
+    if ('username' in user && user.username) {
+      const username = String(user.username).trim().slice(0, 255);
+      if (username) {
+        validated.username = username;
+      }
+    }
+
+    // Validate IP address format if provided
+    if ('ip_address' in user && user.ip_address) {
+      const ip = String(user.ip_address).trim();
+      // Stricter IP validation
+      // IPv4: Each octet must be 0-255
+      const isValidIPv4 =
+        // eslint-disable-next-line security/detect-unsafe-regex -- Safe: bounded pattern for IPv4 validation, input is trimmed string
+        /^(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$/.test(
+          ip,
+        );
+      // IPv6: Basic format check (full validation is complex, this catches most invalid cases)
+      const looksLikeIPv6 =
+        /^[0-9a-fA-F:]+$/.test(ip) && ip.includes(':') && ip.split(':').length <= 8;
+
+      if (isValidIPv4 || looksLikeIPv6) {
+        validated.ip_address = ip.slice(0, 45); // IPv6 max length
+      }
+    }
+
+    return validated;
+  }
+
+  /**
+   * Set user on all enabled plugins
+   * User data is validated and sanitized before being set
+   * @param user - User data to set (will be validated)
+   */
+  setUser(user: ObservabilityUser | null): void {
+    const validatedUser = this.validateUser(user);
+    this.broadcast(plugin => plugin.setUser(validatedUser));
+  }
+
+  /**
+   * Add breadcrumb to all enabled plugins.
+   *
+   * @param breadcrumb - Breadcrumb data to add
+   */
+  addBreadcrumb(breadcrumb: Breadcrumb): void {
+    this.broadcast(plugin => plugin.addBreadcrumb(breadcrumb));
+  }
+
+  /**
+   * Execute callback within scope for all enabled plugins.
+   *
+   * @param callback - Callback that receives the scope
+   */
+  withScope(callback: (scope: ObservabilityScope) => void): void {
+    this.broadcast(plugin => plugin.withScope(callback));
+  }
+
+  /**
+   * Flush all plugins that support it.
+   *
+   * Waits for all enabled plugins with flush capability to send pending events.
+   *
+   * @param timeout - Maximum time to wait in milliseconds
+   * @returns Promise resolving to true if all plugins flushed successfully
+   */
+  async flush(timeout?: number): Promise<boolean> {
+    const flushPromises = Array.from(this.plugins.values())
+      .filter((plugin): plugin is ObservabilityServerPlugin => {
+        return plugin.enabled && 'flush' in plugin && typeof plugin.flush === 'function';
+      })
+      .map(plugin => plugin.flush(timeout));
+
+    if (flushPromises.length === 0) {
+      return true;
+    }
+
+    const results = await Promise.allSettled(flushPromises);
+    return results.every(result => result.status === 'fulfilled' && result.value === true);
+  }
+
+  /**
+   * Helper to broadcast a method call to all enabled plugins
+   * Uses nested try-catch to ensure errors in error handling don't prevent other plugins from executing
+   */
+  private broadcast(fn: (plugin: ObservabilityPlugin) => void): void {
+    this.plugins.forEach(plugin => {
+      if (plugin.enabled) {
+        try {
+          fn(plugin);
+        } catch (error) {
+          // Safely handle error without throwing - nested try-catch ensures resilience
+          try {
+            logError(`Plugin ${plugin.name} error`, { error, pluginName: plugin.name });
+          } catch {
+            // Logger unavailable - continue silently
+          }
+
+          try {
+            this.lifecycle.onError?.(error as Error, plugin);
+          } catch {
+            // Error handler failed - continue to next plugin
+          }
+        }
+      }
+    });
+  }
+
+  /**
+   * Check if manager has any enabled plugins.
+   *
+   * @returns True if at least one plugin is enabled, false otherwise
+   */
+  hasEnabledPlugins(): boolean {
+    return Array.from(this.plugins.values()).some(plugin => plugin.enabled);
+  }
+
+  /**
+   * Get names of all enabled plugins.
+   *
+   * @returns Array of plugin names that are currently enabled
+   */
+  getEnabledPluginNames(): string[] {
+    return Array.from(this.plugins.values())
+      .filter(plugin => plugin.enabled)
+      .map(plugin => plugin.name);
+  }
+}

package/src/core/plugin.ts

@@ -0,0 +1,61 @@
+/**
+ * @fileoverview Core plugin interface for observability providers
+ * Core plugin interface for observability providers
+ */
+
+import type { ObservabilityClient, ObservabilityServer } from './types';
+
+/**
+ * Base plugin interface that all observability providers must implement
+ */
+export interface ObservabilityPlugin<TClient = any> extends ObservabilityClient {
+  /**
+   * Unique name for this plugin
+   */
+  name: string;
+
+  /**
+   * Whether this plugin is currently enabled
+   */
+  enabled: boolean;
+
+  /**
+   * Get the native client instance (e.g., Sentry SDK)
+   * This allows direct access to provider-specific features
+   */
+  getClient(): TClient | undefined;
+
+  /**
+   * Initialize the plugin with optional configuration
+   */
+  initialize?(config?: any): Promise<void>;
+
+  /**
+   * Cleanup resources when shutting down
+   */
+  shutdown?(): Promise<void>;
+}
+
+/**
+ * Server-side plugin interface with additional flush capability
+ */
+export interface ObservabilityServerPlugin<TClient = any>
+  extends ObservabilityPlugin<TClient>, ObservabilityServer {
+  // Inherits flush() from ObservabilityServer
+}
+
+/**
+ * Factory function type for creating plugins
+ */
+export type PluginFactory<TConfig = any, TPlugin = ObservabilityPlugin> = (
+  config?: TConfig,
+) => TPlugin;
+
+/**
+ * Plugin lifecycle events
+ */
+export interface PluginLifecycle {
+  onError?: (error: Error, plugin: ObservabilityPlugin) => void;
+  onInitialized?: (plugin: ObservabilityPlugin) => void;
+  onShutdown?: (plugin: ObservabilityPlugin) => void;
+}

package/src/core/types.ts

@@ -0,0 +1,151 @@
+/**
+ * @fileoverview Core types for the observability package
+ * Core types for the observability package
+ * These types are provider-agnostic and define the common interface
+ */
+
+/**
+ * User information for observability context.
+ *
+ * Represents a user associated with observability events. All fields are validated
+ * and sanitized by ObservabilityManager to prevent injection attacks.
+ */
+export interface ObservabilityUser {
+  /** Unique identifier for the user */
+  id: string;
+  /** User's email address (validated format) */
+  email?: string;
+  /** User's username */
+  username?: string;
+  /** User's IP address (IPv4 or IPv6, validated format) */
+  ip_address?: string;
+  /**
+   * @deprecated Additional custom fields are deprecated and will be removed in a future version.
+   * Custom fields are stripped by validateUser() for security.
+   * Only the defined fields above are validated and sanitized by the ObservabilityManager.
+   */
+  [key: string]: unknown;
+}
+
+/**
+ * Additional context data for observability events.
+ *
+ * Can contain any key-value pairs to provide additional information about
+ * an event. Values are serialized when sent to observability providers.
+ */
+export interface ObservabilityContext {
+  [key: string]: unknown;
+}
+
+/**
+ * Scope for isolating observability context.
+ *
+ * Represents a provider-agnostic scope that can be used to set
+ * context-specific tags, user info, and other metadata.
+ */
+export interface ObservabilityScope {
+  setTag(key: string, value: string): void;
+  setExtra(key: string, value: unknown): void;
+  setUser(user: ObservabilityUser | null): void;
+  setLevel(level: LogLevel): void;
+  [key: string]: unknown;
+}
+
+/**
+ * Log level for observability messages.
+ *
+ * Ordered from most verbose (debug) to least verbose (error).
+ */
+export type LogLevel = 'debug' | 'info' | 'warning' | 'error';
+
+/**
+ * Breadcrumb for tracking user actions and events.
+ *
+ * Breadcrumbs provide a trail of events leading up to an error or important event,
+ * helping with debugging and understanding user flow.
+ */
+export interface Breadcrumb {
+  /** The message describing the breadcrumb */
+  message: string;
+  /** Category of the breadcrumb (e.g., 'navigation', 'user', 'http') */
+  category?: string;
+  /** Severity level of the breadcrumb */
+  level?: LogLevel | 'critical';
+  /** Additional data associated with the breadcrumb */
+  data?: Record<string, unknown>;
+  /** Timestamp when the breadcrumb occurred (Unix timestamp in milliseconds) */
+  timestamp?: number;
+}
+
+/**
+ * Client-side observability interface.
+ *
+ * Defines the core methods available in all environments (browser, server, edge).
+ * All methods are synchronous and fire-and-forget.
+ */
+export interface ObservabilityClient {
+  /**
+   * Capture an exception/error.
+   *
+   * @param error - Error object or unknown error value
+   * @param context - Optional additional context data
+   */
+  captureException(error: Error | unknown, context?: ObservabilityContext): void;
+  /**
+   * Capture a log message.
+   *
+   * @param message - Message to log
+   * @param level - Log level (default: 'info')
+   * @param context - Optional additional context data
+   */
+  captureMessage(message: string, level?: LogLevel, context?: ObservabilityContext): void;
+  /**
+   * Set the current user context.
+   *
+   * @param user - User information, or null to clear
+   */
+  setUser(user: ObservabilityUser | null): void;
+  /**
+   * Add a breadcrumb to track user actions.
+   *
+   * @param breadcrumb - Breadcrumb data
+   */
+  addBreadcrumb(breadcrumb: Breadcrumb): void;
+  /**
+   * Execute a callback within a new scope.
+   *
+   * @param callback - Callback that receives the scope
+   */
+  withScope(callback: (scope: ObservabilityScope) => void): void;
+}
+
+/**
+ * Server-side observability interface.
+ *
+ * Extends ObservabilityClient with additional server-specific capabilities
+ * like flushing pending events before shutdown.
+ */
+export interface ObservabilityServer extends ObservabilityClient {
+  /**
+   * Flush pending events to providers.
+   *
+   * Waits for all pending events to be sent before resolving. Useful before
+   * application shutdown to ensure all events are delivered.
+   *
+   * @param timeout - Maximum time to wait in milliseconds
+   * @returns Promise resolving to true if all events flushed, false otherwise
+   */
+  flush(timeout?: number): Promise<boolean>;
+}
+
+/**
+ * Configuration for observability system.
+ */
+export interface ObservabilityConfig {
+  /** Whether observability is enabled */
+  enabled?: boolean;
+  /** Environment name */
+  environment?: 'development' | 'preview' | 'production';
+  /** Enable debug logging */
+  debug?: boolean;
+}

package/src/factory/builder.ts

@@ -0,0 +1,132 @@
+/**
+ * @fileoverview ObservabilityBuilder - Fluent API for building observability instances
+ * ObservabilityBuilder - Fluent API for building observability instances
+ */
+
+import { logError } from '@repo/shared/logs';
+
+import { ObservabilityManager } from '../core/manager';
+
+import type {
+  ObservabilityPlugin,
+  ObservabilityServerPlugin,
+  PluginLifecycle,
+} from '../core/plugin';
+
+/**
+ * Builder for creating configured ObservabilityManager instances
+ */
+export class ObservabilityBuilder {
+  private plugins: (ObservabilityPlugin | ObservabilityServerPlugin)[] = [];
+  private lifecycle: PluginLifecycle = {};
+  private autoInitialize = true;
+
+  /**
+   * Add a plugin to the observability stack
+   * @param plugin - Observability plugin to add
+   * @returns Builder instance for chaining
+   */
+  withPlugin(plugin: ObservabilityPlugin | ObservabilityServerPlugin): this {
+    if (plugin) {
+      this.plugins.push(plugin);
+    }
+    return this;
+  }
+
+  /**
+   * Add multiple plugins at once
+   * @param plugins - Array of observability plugins to add
+   * @returns Builder instance for chaining
+   */
+  withPlugins(plugins: (ObservabilityPlugin | ObservabilityServerPlugin)[]): this {
+    if (plugins && Array.isArray(plugins)) {
+      const validPlugins = plugins.filter(plugin => plugin != null);
+      this.plugins.push(...validPlugins);
+    }
+    return this;
+  }
+
+  /**
+   * Set lifecycle callbacks for plugin management
+   * @param lifecycle - Lifecycle callback configuration
+   * @returns Builder instance for chaining
+   */
+  withLifecycle(lifecycle: PluginLifecycle): this {
+    this.lifecycle = { ...this.lifecycle, ...lifecycle };
+    return this;
+  }
+
+  /**
+   * Configure whether to auto-initialize plugins (default: true)
+   */
+  withAutoInitialize(autoInitialize: boolean): this {
+    this.autoInitialize = autoInitialize;
+    return this;
+  }
+
+  /**
+   * Build the ObservabilityManager instance
+   * @returns Configured ObservabilityManager instance
+   */
+  build(): ObservabilityManager {
+    const manager = new ObservabilityManager(this.lifecycle);
+
+    // Add all plugins
+    this.plugins.forEach(plugin => manager.addPlugin(plugin));
+
+    // Auto-initialize if enabled and not in edge runtime
+    if (
+      this.autoInitialize &&
+      typeof process !== 'undefined' &&
+      process.env.NEXT_RUNTIME !== 'edge'
+    ) {
+      // Initialize asynchronously with safe error handling
+      void (async () => {
+        try {
+          await manager.initialize();
+        } catch (error) {
+          // Store error in manager for later inspection
+          // Note: We can't directly set private property, but manager stores it internally
+
+          // Try logError, but don't fail if unavailable
+          try {
+            logError('Failed to initialize observability', { error });
+          } catch {
+            // Logger unavailable - error is stored in manager via initialize() method
+          }
+        }
+      })();
+    }
+
+    return manager;
+  }
+
+  /**
+   * Build and initialize the ObservabilityManager instance
+   * @returns Promise resolving to initialized ObservabilityManager
+   */
+  async buildWithAutoInit(): Promise<ObservabilityManager> {
+    const manager = new ObservabilityManager(this.lifecycle);
+
+    // Add all plugins
+    this.plugins.forEach(plugin => manager.addPlugin(plugin));
+
+    // Initialize all plugins - catch errors but still return manager (graceful degradation)
+    try {
+      await manager.initialize();
+    } catch {
+      // Error is stored in manager, but we still return it for graceful degradation
+      // This allows the application to continue even if observability initialization fails
+    }
+
+    return manager;
+  }
+
+  /**
+   * Create a new builder instance
+   * @returns New ObservabilityBuilder instance
+   */
+  static create(): ObservabilityBuilder {
+    return new ObservabilityBuilder();
+  }
+}