@finatic/client 0.0.141 → 0.9.0

package/src/index.ts

@@ -91,6 +91,7 @@ export { PaginatedResult } from './types/common/pagination';
 export * from './utils/errors';
 export * from './utils/events';
 export * from './utils/themeUtils';
+export * from './lib/logger';
 
 // Theme presets
 export { portalThemePresets } from './themes/portalPresets';

package/src/lib/logger/index.ts

@@ -0,0 +1,3 @@
+export * from './logger';
+export * from './logger.types';
+

package/src/lib/logger/logger.ts

@@ -0,0 +1,332 @@
+import { Logger, LoggerExtra, LoggerMetadata, LoggerOptions, LogLevel, LogVerbosity } from './logger.types';
+
+const LOG_LEVEL_ORDER: Record<Exclude<LogLevel, 'silent'>, number> = {
+  error: 0,
+  warn: 1,
+  info: 2,
+  debug: 3,
+};
+
+const LEVEL_TO_CONSOLE: Record<Exclude<LogLevel, 'silent'>, keyof Console> = {
+  error: 'error',
+  warn: 'warn',
+  info: 'info',
+  debug: 'debug',
+};
+
+const DEFAULT_LOGGER_NAME = 'FinaticLogger';
+
+const parseLogLevel = (value: unknown, fallback: LogLevel): LogLevel => {
+  if (typeof value !== 'string') {
+    return fallback;
+  }
+
+  const normalized = value.toLowerCase().trim() as LogLevel;
+  if (normalized === 'silent' || normalized === 'error' || normalized === 'warn' || normalized === 'info' || normalized === 'debug') {
+    return normalized;
+  }
+
+  return fallback;
+};
+
+const parseVerbosity = (value: unknown, fallback: LogVerbosity): LogVerbosity => {
+  if (typeof value !== 'string' && typeof value !== 'number') {
+    return fallback;
+  }
+
+  const numeric = typeof value === 'number' ? value : Number.parseInt(value, 10);
+  if (Number.isNaN(numeric)) {
+    return fallback;
+  }
+
+  if (numeric <= 0) {
+    return 0;
+  }
+
+  if (numeric >= 3) {
+    return 3;
+  }
+
+  return numeric as LogVerbosity;
+};
+
+const resolveEnv = (key: string): string | undefined => {
+  try {
+    if (typeof process !== 'undefined' && process.env && typeof process.env[key] === 'string') {
+      return process.env[key];
+    }
+  } catch {
+    // ignore
+  }
+
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const metaEnv = typeof import.meta !== 'undefined' ? (import.meta as any).env : undefined;
+    if (metaEnv && typeof metaEnv[key] === 'string') {
+      return metaEnv[key];
+    }
+  } catch {
+    // ignore
+  }
+
+  try {
+    if (typeof globalThis !== 'undefined') {
+      const value = (globalThis as Record<string, unknown>)[key];
+      if (typeof value === 'string') {
+        return value;
+      }
+    }
+  } catch {
+    // ignore
+  }
+
+  return undefined;
+};
+
+const resolveDefaultLogLevel = (explicitLevel?: LogLevel): LogLevel => {
+  if (explicitLevel) {
+    return explicitLevel;
+  }
+
+  const envLevel =
+    resolveEnv('FINATIC_LOG_LEVEL') ||
+    resolveEnv('VITE_FINATIC_LOG_LEVEL') ||
+    resolveEnv('NEXT_PUBLIC_FINATIC_LOG_LEVEL') ||
+    resolveEnv('NEXT_FINATIC_LOG_LEVEL') ||
+    resolveEnv('REACT_APP_FINATIC_LOG_LEVEL') ||
+    resolveEnv('NUXT_PUBLIC_FINATIC_LOG_LEVEL') ||
+    resolveEnv('NX_FINATIC_LOG_LEVEL');
+
+  if (envLevel) {
+    return parseLogLevel(envLevel, 'silent');
+  }
+
+  return 'silent';
+};
+
+const resolveVerbosity = (): LogVerbosity => {
+  const envVerbosity =
+    resolveEnv('FINATIC_LOG_VERBOSITY') ||
+    resolveEnv('VITE_FINATIC_LOG_VERBOSITY') ||
+    resolveEnv('NEXT_PUBLIC_FINATIC_LOG_VERBOSITY') ||
+    resolveEnv('NEXT_FINATIC_LOG_VERBOSITY') ||
+    resolveEnv('REACT_APP_FINATIC_LOG_VERBOSITY') ||
+    resolveEnv('NUXT_PUBLIC_FINATIC_LOG_VERBOSITY') ||
+    resolveEnv('NX_FINATIC_LOG_VERBOSITY');
+
+  if (envVerbosity) {
+    return parseVerbosity(envVerbosity, 1);
+  }
+
+  return 1;
+};
+
+const resolveBaseMetadata = (): LoggerMetadata => {
+  const base: LoggerMetadata = {
+    timestamp: new Date().toISOString(),
+  };
+
+  try {
+    if (typeof globalThis !== 'undefined') {
+      if (typeof (globalThis as Window).location !== 'undefined') {
+        base.host = (globalThis as Window).location.hostname;
+      }
+      if (typeof (globalThis as Window).navigator !== 'undefined') {
+        base.user_agent = (globalThis as Window).navigator.userAgent;
+      }
+    }
+  } catch {
+    // ignore
+  }
+
+  try {
+    if (typeof process !== 'undefined') {
+      base.pid = process.pid;
+    }
+  } catch {
+    // ignore
+  }
+
+  return base;
+};
+
+const normalizeError = (error: unknown): Record<string, unknown> | undefined => {
+  if (!error) {
+    return undefined;
+  }
+
+  if (error instanceof Error) {
+    return {
+      type: error.name,
+      message: error.message,
+      stacktrace: error.stack,
+    };
+  }
+
+  if (typeof error === 'object') {
+    return { ...(error as Record<string, unknown>) };
+  }
+
+  return {
+    type: 'Error',
+    message: String(error),
+  };
+};
+
+const shouldLog = (requestedLevel: Exclude<LogLevel, 'silent'>, currentLevel: LogLevel): boolean => {
+  if (currentLevel === 'silent') {
+    return false;
+  }
+
+  const currentOrder = LOG_LEVEL_ORDER[currentLevel];
+  const requestedOrder = LOG_LEVEL_ORDER[requestedLevel];
+
+  return requestedOrder <= currentOrder;
+};
+
+const buildPayload = (
+  name: string,
+  level: Exclude<LogLevel, 'silent'>,
+  message: string,
+  defaultMetadata: LoggerMetadata | undefined,
+  extra: LoggerExtra | undefined,
+  verbosity: LogVerbosity,
+): Record<string, unknown> => {
+  const payload: Record<string, unknown> = {
+    timestamp: new Date().toISOString(),
+    message,
+  };
+
+  if (verbosity >= 1 && extra) {
+    if (extra.module) {
+      payload.module = extra.module;
+    }
+    if (extra.function) {
+      payload.function = extra.function;
+    }
+  }
+
+  if (verbosity >= 2) {
+    if (extra?.duration_ms !== undefined) {
+      payload.duration_ms = extra.duration_ms;
+    }
+    if (extra?.event) {
+      payload.event = extra.event;
+    }
+    if (extra?.error) {
+      payload.error = normalizeError(extra.error);
+    }
+  }
+
+  if (verbosity >= 3) {
+    payload.level = level.toUpperCase();
+    payload.name = name;
+    const baseMetadata = resolveBaseMetadata();
+    const mergedMetadata: LoggerMetadata = {
+      ...baseMetadata,
+      ...(defaultMetadata || {}),
+      ...(extra?.metadata || {}),
+    };
+    if (Object.keys(mergedMetadata).length > 0) {
+      payload.metadata = mergedMetadata;
+    }
+  }
+
+  const restKeys = ['module', 'function', 'event', 'duration_ms', 'error', 'metadata'];
+  if (extra) {
+    Object.entries(extra).forEach(([key, value]) => {
+      if (!restKeys.includes(key) && value !== undefined) {
+        payload[key] = value;
+      }
+    });
+  }
+
+  return payload;
+};
+
+const consoleWrite = (
+  consoleLevel: keyof Console,
+  name: string,
+  level: Exclude<LogLevel, 'silent'>,
+  message: string,
+  payload: Record<string, unknown>,
+): void => {
+  if (typeof console === 'undefined' || typeof console[consoleLevel] !== 'function') {
+    return;
+  }
+
+  const prefix = `${level.toUpperCase()}: ${name} || ${message}`;
+  console[consoleLevel](prefix, payload);
+};
+
+export const setupLogger = (nameOrOptions: string | LoggerOptions, level?: LogLevel, defaultMetadata?: LoggerMetadata): Logger => {
+  const options: LoggerOptions =
+    typeof nameOrOptions === 'string'
+      ? {
+          name: nameOrOptions,
+          level,
+          defaultMetadata,
+        }
+      : nameOrOptions;
+
+  const loggerName = options.name || DEFAULT_LOGGER_NAME;
+  let currentLevel: LogLevel = resolveDefaultLogLevel(options.level);
+  const loggerDefaultMetadata = options.defaultMetadata;
+  const verbosity = resolveVerbosity();
+
+  const log = (requestedLevel: Exclude<LogLevel, 'silent'>, message: string, extra?: LoggerExtra) => {
+    if (!shouldLog(requestedLevel, currentLevel)) {
+      return;
+    }
+
+    const payload = buildPayload(loggerName, requestedLevel, message, loggerDefaultMetadata, extra, verbosity);
+    consoleWrite(LEVEL_TO_CONSOLE[requestedLevel], loggerName, requestedLevel, message, payload);
+  };
+
+  return {
+    getLevel: () => currentLevel,
+    setLevel: (nextLevel: LogLevel) => {
+      currentLevel = nextLevel;
+    },
+    debug: (message: string, extra?: LoggerExtra) => log('debug', message, extra),
+    info: (message: string, extra?: LoggerExtra) => log('info', message, extra),
+    warn: (message: string, extra?: LoggerExtra) => log('warn', message, extra),
+    error: (message: string, extra?: LoggerExtra) => log('error', message, extra),
+    exception: (message: string, error: unknown, extra?: LoggerExtra) => {
+      log('error', message, {
+        ...extra,
+        error,
+        event: extra?.event || 'exception',
+      });
+    },
+  };
+};
+
+export const buildLoggerExtra = (metadata: LoggerMetadata): LoggerExtra => ({
+  metadata,
+});
+
+export const logStartEnd =
+  (logger: Logger) =>
+  <Args extends unknown[], ReturnType>(fn: (...args: Args) => ReturnType | Promise<ReturnType>) =>
+  async (...args: Args): Promise<ReturnType> => {
+    const start = Date.now();
+    const functionName = fn.name || 'anonymous';
+    logger.debug('START', { module: 'logStartEnd', function: functionName, event: 'start' });
+
+    try {
+      const result = await fn(...args);
+      const duration = Date.now() - start;
+      logger.info('END', { module: 'logStartEnd', function: functionName, event: 'end', duration_ms: duration });
+      return result;
+    } catch (error) {
+      const duration = Date.now() - start;
+      logger.exception('EXCEPTION', error, {
+        module: 'logStartEnd',
+        function: functionName,
+        duration_ms: duration,
+      });
+      throw error;
+    }
+  };
+

package/src/lib/logger/logger.types.ts

@@ -0,0 +1,34 @@
+export type LogLevel = 'silent' | 'error' | 'warn' | 'info' | 'debug';
+
+export interface LoggerMetadata {
+  [key: string]: unknown;
+}
+
+export interface LoggerExtra {
+  metadata?: LoggerMetadata;
+  module?: string;
+  function?: string;
+  event?: string;
+  duration_ms?: number;
+  error?: unknown;
+  [key: string]: unknown;
+}
+
+export interface LoggerOptions {
+  name: string;
+  level?: LogLevel;
+  defaultMetadata?: LoggerMetadata;
+}
+
+export interface Logger {
+  getLevel: () => LogLevel;
+  setLevel: (level: LogLevel) => void;
+  debug: (message: string, extra?: LoggerExtra) => void;
+  info: (message: string, extra?: LoggerExtra) => void;
+  warn: (message: string, extra?: LoggerExtra) => void;
+  error: (message: string, extra?: LoggerExtra) => void;
+  exception: (message: string, error: unknown, extra?: LoggerExtra) => void;
+}
+
+export type LogVerbosity = 0 | 1 | 2 | 3;
+

package/src/mocks/MockApiClient.ts

@@ -47,6 +47,11 @@ import {
   OrderValidationError,
 } from '../utils/errors';
 import { MockDataProvider, MockConfig } from './MockDataProvider';
+import { setupLogger, buildLoggerExtra, LoggerExtra } from '../lib/logger';
+
+const mockApiLogger = setupLogger('FinaticClientSDK.MockApiClient', undefined, {
+  codebase: 'FinaticClientSDK',
+});
 
 /**
  * Mock API Client that implements the same interface as the real ApiClient
@@ -71,6 +76,15 @@ export class MockApiClient {
   // Mock data provider
   private mockDataProvider: MockDataProvider;
   private readonly mockApiOnly: boolean;
+  private readonly logger = mockApiLogger;
+
+  private buildLoggerExtra(functionName: string, metadata?: Record<string, unknown>): LoggerExtra {
+    return {
+      module: 'MockApiClient',
+      function: functionName,
+      ...(metadata ? buildLoggerExtra(metadata) : {}),
+    };
+  }
 
   constructor(baseUrl: string, deviceInfo?: DeviceInfo, mockConfig?: MockConfig) {
     this.baseUrl = baseUrl;
@@ -80,9 +94,13 @@ export class MockApiClient {
 
     // Log that mocks are being used
     if (this.mockApiOnly) {
-      console.log('🔧 Finatic SDK: Using MOCK API Client (API only - real portal)');
+      this.logger.info('Using mock API client (API only, real portal)', this.buildLoggerExtra('constructor', {
+        mock_api_only: true,
+      }));
     } else {
-      console.log('🔧 Finatic SDK: Using MOCK API Client');
+      this.logger.info('Using mock API client', this.buildLoggerExtra('constructor', {
+        mock_api_only: false,
+      }));
     }
   }
 
@@ -339,14 +357,12 @@ export class MockApiClient {
     const accessToken = await this.getValidAccessToken();
 
     // Debug logging
-    console.log('MockApiClient.placeBrokerOrder Debug:', {
-      params,
-      tradingContext: this.tradingContext,
-      paramsBroker: params.broker,
-      contextBroker: this.tradingContext.broker,
-      paramsAccountNumber: params.accountNumber,
-      contextAccountNumber: this.tradingContext.accountNumber,
-    });
+    this.logger.debug('placeBrokerOrder parameters', this.buildLoggerExtra('placeBrokerOrder', {
+      has_params_broker: Boolean(params.broker),
+      has_context_broker: Boolean(this.tradingContext.broker),
+      has_params_account: Boolean(params.accountNumber),
+      has_context_account: Boolean(this.tradingContext.accountNumber),
+    }));
 
     const fullParams: BrokerOrderParams = {
       broker:
@@ -374,7 +390,13 @@ export class MockApiClient {
       order_id: params.order_id,
     };
 
-    console.log('MockApiClient.placeBrokerOrder Debug - Final params:', fullParams);
+    this.logger.debug('placeBrokerOrder normalized parameters', this.buildLoggerExtra('placeBrokerOrder', {
+      broker: fullParams.broker,
+      account_number_present: Boolean(fullParams.accountNumber),
+      symbol: fullParams.symbol,
+      order_type: fullParams.orderType,
+      asset_type: fullParams.assetType,
+    }));
     return this.mockDataProvider.mockPlaceOrder(fullParams);
   }
 
@@ -427,14 +449,18 @@ export class MockApiClient {
   }
 
   setAccount(accountNumber: string, accountId?: string): void {
-    console.log('MockApiClient.setAccount Debug:', {
-      accountNumber,
-      accountId,
-      previousContext: { ...this.tradingContext },
-    });
+    this.logger.debug('setAccount invoked', this.buildLoggerExtra('setAccount', {
+      account_number: accountNumber,
+      account_id_present: Boolean(accountId),
+      had_existing_account: Boolean(this.tradingContext.accountNumber),
+    }));
     this.tradingContext.accountNumber = accountNumber;
     this.tradingContext.accountId = accountId;
-    console.log('MockApiClient.setAccount Debug - Updated context:', this.tradingContext);
+    this.logger.debug('setAccount updated context', this.buildLoggerExtra('setAccount', {
+      broker: this.tradingContext.broker,
+      account_number_present: Boolean(this.tradingContext.accountNumber),
+      account_id_present: Boolean(this.tradingContext.accountId),
+    }));
   }
 
 

package/src/types/common/pagination.ts

@@ -2,6 +2,18 @@
  * Pagination-related types and classes
  */
 
+import { setupLogger, buildLoggerExtra, LoggerExtra } from '../../lib/logger';
+
+const paginationLogger = setupLogger('FinaticClientSDK.Pagination', undefined, {
+  codebase: 'FinaticClientSDK',
+});
+
+const buildPaginationExtra = (functionName: string, metadata?: Record<string, unknown>): LoggerExtra => ({
+  module: 'PaginatedResult',
+  function: functionName,
+  ...(metadata ? buildLoggerExtra(metadata) : {}),
+});
+
 export interface ApiPaginationInfo {
   has_more: boolean;
   next_offset: number;
@@ -62,7 +74,10 @@ export class PaginatedResult<T> {
     try {
       return await this.navigationCallback(this.metadata.nextOffset, this.metadata.limit);
     } catch (error) {
-      console.error('Error fetching next page:', error);
+      paginationLogger.exception('Error fetching next page', error, buildPaginationExtra('nextPage', {
+        next_offset: this.metadata.nextOffset,
+        limit: this.metadata.limit,
+      }));
       return null;
     }
   }
@@ -76,7 +91,10 @@ export class PaginatedResult<T> {
     try {
       return await this.navigationCallback(previousOffset, this.metadata.limit);
     } catch (error) {
-      console.error('Error fetching previous page:', error);
+      paginationLogger.exception('Error fetching previous page', error, buildPaginationExtra('previousPage', {
+        previous_offset: previousOffset,
+        limit: this.metadata.limit,
+      }));
       return null;
     }
   }
@@ -90,7 +108,11 @@ export class PaginatedResult<T> {
     try {
       return await this.navigationCallback(offset, this.metadata.limit);
     } catch (error) {
-      console.error('Error fetching page:', pageNumber, error);
+      paginationLogger.exception('Error fetching page', error, buildPaginationExtra('goToPage', {
+        page_number: pageNumber,
+        offset,
+        limit: this.metadata.limit,
+      }));
       return null;
     }
   }
@@ -103,7 +125,9 @@ export class PaginatedResult<T> {
     try {
       return await this.navigationCallback(0, this.metadata.limit);
     } catch (error) {
-      console.error('Error fetching first page:', error);
+      paginationLogger.exception('Error fetching first page', error, buildPaginationExtra('firstPage', {
+        limit: this.metadata.limit,
+      }));
       return null;
     }
   }
@@ -127,7 +151,9 @@ export class PaginatedResult<T> {
     try {
       return await findLast(this);
     } catch (error) {
-      console.error('Error fetching last page:', error);
+      paginationLogger.exception('Error fetching last page', error, buildPaginationExtra('lastPage', {
+        limit: this.metadata.limit,
+      }));
       return null;
     }
   }

package/src/utils/brokerUtils.ts

@@ -2,6 +2,18 @@
  * Broker filtering utility functions
  */
 
+import { setupLogger, buildLoggerExtra, LoggerExtra } from '../lib/logger';
+
+const brokerLogger = setupLogger('FinaticClientSDK.BrokerUtils', undefined, {
+  codebase: 'FinaticClientSDK',
+});
+
+const buildBrokerExtra = (functionName: string, metadata?: Record<string, unknown>): LoggerExtra => ({
+  module: 'BrokerUtils',
+  function: functionName,
+  ...(metadata ? buildLoggerExtra(metadata) : {}),
+});
+
 // Supported broker names and their corresponding IDs (including aliases)
 const SUPPORTED_BROKERS: Record<string, string> = {
   'alpaca': 'alpaca',
@@ -52,7 +64,11 @@ export function appendBrokerFilterToURL(baseUrl: string, brokerNames?: string[])
     const { brokerIds, warnings } = convertBrokerNamesToIds(brokerNames);
 
     // Log warnings for unsupported broker names
-    warnings.forEach(warning => console.warn(`[FinaticConnect] ${warning}`));
+    warnings.forEach(warning =>
+      brokerLogger.warn('Unsupported broker name provided', buildBrokerExtra('appendBrokerFilterToURL', {
+        warning,
+      })),
+    );
 
     // Only add broker filter if we have valid broker IDs
     if (brokerIds.length > 0) {
@@ -62,7 +78,10 @@ export function appendBrokerFilterToURL(baseUrl: string, brokerNames?: string[])
 
     return url.toString();
   } catch (error) {
-    console.error('Failed to append broker filter to URL:', error);
+    brokerLogger.exception('Failed to append broker filter to URL', error, buildBrokerExtra('appendBrokerFilterToURL', {
+      base_url: baseUrl,
+      brokers_count: brokerNames?.length ?? 0,
+    }));
     return baseUrl;
   }
 }

package/src/utils/events.ts

@@ -1,5 +1,11 @@
+import { setupLogger, buildLoggerExtra } from '../lib/logger';
+
 type EventCallback = (...args: any[]) => void;
 
+const eventsLogger = setupLogger('FinaticClientSDK.Events', undefined, {
+  codebase: 'FinaticClientSDK',
+});
+
 export class EventEmitter {
   private events: Map<string, Set<EventCallback>> = new Map();
 
@@ -30,7 +36,13 @@ export class EventEmitter {
         try {
           callback(...args);
         } catch (error) {
-          console.error(`Error in event handler for ${event}:`, error);
+          eventsLogger.exception('Error in event handler', error, {
+            module: 'EventEmitter',
+            function: 'emit',
+            ...buildLoggerExtra({
+              event_name: event,
+            }),
+          });
         }
       });
     }

package/src/utils/themeUtils.ts

@@ -1,5 +1,16 @@
 import { PortalTheme, PortalThemeConfig } from '../types/portal';
 import { portalThemePresets } from '../themes/portalPresets';
+import { setupLogger, buildLoggerExtra, LoggerExtra } from '../lib/logger';
+
+const themeLogger = setupLogger('FinaticClientSDK.ThemeUtils', undefined, {
+  codebase: 'FinaticClientSDK',
+});
+
+const buildThemeExtra = (functionName: string, metadata?: Record<string, unknown>): LoggerExtra => ({
+  module: 'ThemeUtils',
+  function: functionName,
+  ...(metadata ? buildLoggerExtra(metadata) : {}),
+});
 
 /**
  * Generate a portal URL with theme parameters
@@ -27,7 +38,10 @@ export function generatePortalThemeURL(baseUrl: string, theme?: PortalTheme): st
 
     return url.toString();
   } catch (error) {
-    console.error('Failed to generate theme URL:', error);
+    themeLogger.exception('Failed to generate theme URL', error, buildThemeExtra('generatePortalThemeURL', {
+      base_url: baseUrl,
+      has_theme: Boolean(theme),
+    }));
     return baseUrl;
   }
 }
@@ -58,7 +72,10 @@ export function appendThemeToURL(baseUrl: string, theme?: PortalTheme): string {
 
     return url.toString();
   } catch (error) {
-    console.error('Failed to append theme to URL:', error);
+    themeLogger.exception('Failed to append theme to URL', error, buildThemeExtra('appendThemeToURL', {
+      base_url: baseUrl,
+      has_theme: Boolean(theme),
+    }));
     return baseUrl;
   }
 }
@@ -118,7 +135,7 @@ export function validateCustomTheme(theme: PortalThemeConfig): boolean {
 
     return true;
   } catch (error) {
-    console.error('Theme validation error:', error);
+    themeLogger.exception('Theme validation error', error, buildThemeExtra('validateCustomTheme'));
     return false;
   }
 }
@@ -135,7 +152,9 @@ export function createCustomThemeFromPreset(
 ): PortalThemeConfig | null {
   const baseTheme = getThemePreset(preset);
   if (!baseTheme) {
-    console.error(`Preset theme '${preset}' not found`);
+    themeLogger.warn('Preset theme not found', buildThemeExtra('createCustomThemeFromPreset', {
+      preset,
+    }));
     return null;
   }