@finatic/client 0.0.140 → 0.0.142

package/src/core/client/FinaticConnect.ts

@@ -27,6 +27,17 @@ import {
 import { FinaticConnectOptions, PortalOptions } from '../../types/connect';
 import { appendThemeToURL } from '../../utils/themeUtils';
 import { appendBrokerFilterToURL } from '../../utils/brokerUtils';
+import { setupLogger, buildLoggerExtra, LoggerExtra } from '../../lib/logger';
+
+const finaticConnectLogger = setupLogger('FinaticClientSDK.FinaticConnect', undefined, {
+  codebase: 'FinaticClientSDK',
+});
+
+const makeFinaticConnectExtra = (functionName: string, metadata?: Record<string, unknown>): LoggerExtra => ({
+  module: 'FinaticConnect',
+  function: functionName,
+  ...(metadata ? buildLoggerExtra(metadata) : {}),
+});
 // Supabase import removed - SDK no longer depends on Supabase
 
 interface DeviceInfo {
@@ -57,6 +68,16 @@ export class FinaticConnect extends EventEmitter {
   private readonly SESSION_REFRESH_BUFFER_HOURS = 16; // Refresh session at 16 hours
   private sessionStartTime: number | null = null;
 
+  private readonly logger = finaticConnectLogger;
+
+  private buildLoggerExtra(functionName: string, metadata?: Record<string, unknown>): LoggerExtra {
+    return {
+      module: 'FinaticConnect',
+      function: functionName,
+      ...(metadata ? buildLoggerExtra(metadata) : {}),
+    };
+  }
+
   constructor(options: FinaticConnectOptions, deviceInfo?: DeviceInfo) {
     super();
     this.options = options;
@@ -112,7 +133,7 @@ export class FinaticConnect extends EventEmitter {
   private async linkUserToSession(userId: string): Promise<boolean> {
     try {
       if (!this.sessionId) {
-        console.error('No session ID available for user linking');
+        this.logger.error('No session ID available for user linking', this.buildLoggerExtra('linkUserToSession'));
         return false;
       }
 
@@ -126,14 +147,20 @@ export class FinaticConnect extends EventEmitter {
       });
 
       if (response.error) {
-        console.error('Failed to link user to session:', response.error);
+        this.logger.error('Failed to link user to session', {
+          ...this.buildLoggerExtra('linkUserToSession', {
+            session_id: this.sessionId,
+            user_id: userId,
+          }),
+          error: response.error,
+        });
         return false;
       }
 
-      console.log('User linked to session successfully');
+      this.logger.info('User linked to session successfully', this.buildLoggerExtra('linkUserToSession', { session_id: this.sessionId, user_id: userId }));
       return true;
     } catch (error) {
-      console.error('Error linking user to session:', error);
+      this.logger.exception('Error linking user to session', error, this.buildLoggerExtra('linkUserToSession', { session_id: this.sessionId, user_id: userId }));
       return false;
     }
   }
@@ -322,7 +349,7 @@ export class FinaticConnect extends EventEmitter {
     // Safari-specific fix: Clear instance if it exists but has no valid session
     // This prevents stale instances from interfering with new requests
     if (FinaticConnect.instance && !FinaticConnect.instance.sessionId) {
-      console.log('[FinaticConnect] Clearing stale instance for Safari compatibility');
+      finaticConnectLogger.debug('Clearing stale instance for Safari compatibility', makeFinaticConnectExtra('init'));
       FinaticConnect.instance = null;
     }
 
@@ -390,7 +417,7 @@ export class FinaticConnect extends EventEmitter {
             // Emit success event
             FinaticConnect.instance.emit('success', normalizedUserId);
           } else {
-            console.warn('Failed to link user to session during initialization');
+            finaticConnectLogger.warn('Failed to link user to session during initialization', makeFinaticConnectExtra('init', { user_id: normalizedUserId }));
           }
         } catch (error) {
           FinaticConnect.instance.emit('error', error as Error);
@@ -423,7 +450,7 @@ export class FinaticConnect extends EventEmitter {
       // Try to link user to session
       const linked = await this.linkUserToSession(userId);
       if (!linked) {
-        console.warn('Failed to link user to session during initialization');
+        this.logger.warn('Failed to link user to session during initialization', this.buildLoggerExtra('initializeWithUser', { user_id: userId }));
         // Don't throw error, just continue without authentication
         return;
       }
@@ -537,7 +564,7 @@ export class FinaticConnect extends EventEmitter {
             // Try to link user to session via API
             const linked = await this.linkUserToSession(userId);
             if (!linked) {
-              console.warn('Failed to link user to session, but continuing with authentication');
+              this.logger.warn('Failed to link user to session, continuing with authentication', this.buildLoggerExtra('openPortal.onSuccess', { user_id: userId }));
             }
 
             // Emit portal success event
@@ -573,7 +600,13 @@ export class FinaticConnect extends EventEmitter {
           options?.onClose?.();
         },
         onEvent: (type: string, data: any) => {
-          console.log('[FinaticConnect] Portal event received:', type, data);
+          this.logger.debug('Portal event received', {
+            ...this.buildLoggerExtra('openPortal.onEvent', {
+              event_type: type,
+              payload_present: Boolean(data),
+            }),
+            event: 'portal-event',
+          });
 
           // Emit generic event
           this.emit('event', type, data);
@@ -1293,7 +1326,7 @@ export class FinaticConnect extends EventEmitter {
       this.validateSessionKeepAlive();
     }, this.SESSION_KEEP_ALIVE_INTERVAL);
 
-    console.log('[FinaticConnect] Session keep-alive started (5-minute intervals)');
+    this.logger.debug('Session keep-alive started', this.buildLoggerExtra('startSessionKeepAlive', { interval_ms: this.SESSION_KEEP_ALIVE_INTERVAL }));
   }
 
   /**
@@ -1303,7 +1336,7 @@ export class FinaticConnect extends EventEmitter {
     if (this.sessionKeepAliveInterval) {
       clearInterval(this.sessionKeepAliveInterval);
       this.sessionKeepAliveInterval = null;
-      console.log('[FinaticConnect] Session keep-alive stopped');
+      this.logger.debug('Session keep-alive stopped', this.buildLoggerExtra('stopSessionKeepAlive'));
     }
   }
 
@@ -1312,12 +1345,12 @@ export class FinaticConnect extends EventEmitter {
    */
   private async validateSessionKeepAlive(): Promise<void> {
     if (!this.sessionId || !(await this.isAuthenticated())) {
-      console.log('[FinaticConnect] Session keep-alive skipped - no active session');
+      this.logger.debug('Session keep-alive skipped - no active session', this.buildLoggerExtra('validateSessionKeepAlive'));
       return;
     }
 
     try {
-      console.log('[FinaticConnect] Validating session for keep-alive...');
+      this.logger.debug('Validating session for keep-alive', this.buildLoggerExtra('validateSessionKeepAlive', { session_id: this.sessionId }));
 
       // Check if we need to refresh the session (at 16 hours)
       if (this.shouldRefreshSession()) {
@@ -1326,10 +1359,10 @@ export class FinaticConnect extends EventEmitter {
       }
 
       // Session keep-alive - assume session is active if we have a session ID
-      console.log('[FinaticConnect] Session keep-alive successful');
+      this.logger.debug('Session keep-alive successful', this.buildLoggerExtra('validateSessionKeepAlive', { session_id: this.sessionId }));
       this.currentSessionState = 'active';
     } catch (error) {
-      console.warn('[FinaticConnect] Session keep-alive error:', error);
+      this.logger.exception('Session keep-alive error', error, this.buildLoggerExtra('validateSessionKeepAlive', { session_id: this.sessionId }));
       // Don't throw errors during keep-alive - just log them
     }
   }
@@ -1346,15 +1379,17 @@ export class FinaticConnect extends EventEmitter {
     const hoursUntilRefresh = this.SESSION_REFRESH_BUFFER_HOURS - sessionAgeHours;
 
     if (hoursUntilRefresh <= 0) {
-      console.log(
-        `[FinaticConnect] Session is ${sessionAgeHours.toFixed(1)} hours old - triggering refresh`
-      );
+      this.logger.info('Session age threshold exceeded - triggering refresh', this.buildLoggerExtra('shouldRefreshSession', {
+        session_age_hours: Number(sessionAgeHours.toFixed(1)),
+      }));
       return true;
     }
 
     // Log when refresh will occur (every 5 minutes during keep-alive)
     if (hoursUntilRefresh <= 1) {
-      console.log(`[FinaticConnect] Session will refresh in ${hoursUntilRefresh.toFixed(1)} hours`);
+      this.logger.debug('Session refresh scheduled', this.buildLoggerExtra('shouldRefreshSession', {
+        hours_until_refresh: Number(hoursUntilRefresh.toFixed(1)),
+      }));
     }
 
     return false;
@@ -1365,26 +1400,35 @@ export class FinaticConnect extends EventEmitter {
    */
   private async refreshSessionAutomatically(): Promise<void> {
     if (!this.sessionId) {
-      console.warn('[FinaticConnect] Cannot refresh session - no session ID');
+      this.logger.warn('Cannot refresh session - missing session ID', this.buildLoggerExtra('refreshSessionAutomatically'));
       return;
     }
 
     try {
-      console.log('[FinaticConnect] Automatically refreshing session (16+ hours old)...');
+      this.logger.info('Automatically refreshing session', this.buildLoggerExtra('refreshSessionAutomatically', {
+        session_id: this.sessionId,
+      }));
       const response = await this.apiClient.refreshSession();
 
       if (response.success) {
-        console.log('[FinaticConnect] Session automatically refreshed successfully');
-        console.log('[FinaticConnect] New session expires at:', response.response_data.expires_at);
+        this.logger.info('Session automatically refreshed successfully', this.buildLoggerExtra('refreshSessionAutomatically', {
+          session_id: this.sessionId,
+          status: response.response_data.status,
+          expires_at: response.response_data.expires_at,
+        }));
         this.currentSessionState = response.response_data.status;
 
         // Update session start time to prevent immediate re-refresh
         this.sessionStartTime = Date.now();
       } else {
-        console.warn('[FinaticConnect] Automatic session refresh failed');
+        this.logger.warn('Automatic session refresh failed', this.buildLoggerExtra('refreshSessionAutomatically', {
+          session_id: this.sessionId,
+        }));
       }
     } catch (error) {
-      console.warn('[FinaticConnect] Automatic session refresh error:', error);
+      this.logger.exception('Automatic session refresh error', error, this.buildLoggerExtra('refreshSessionAutomatically', {
+        session_id: this.sessionId,
+      }));
       // Don't throw errors during automatic refresh - just log them
     }
   }
@@ -1406,7 +1450,9 @@ export class FinaticConnect extends EventEmitter {
   private async handleVisibilityChange(): Promise<void> {
     // For 24-hour sessions, we don't want to complete sessions on visibility changes
     // This prevents sessions from being closed when users switch tabs or apps
-    console.log('[FinaticConnect] Page visibility changed to:', document.visibilityState);
+    this.logger.debug('Page visibility changed', this.buildLoggerExtra('handleVisibilityChange', {
+      visibility_state: document.visibilityState,
+    }));
 
     // Only pause keep-alive when hidden, but don't complete the session
     if (document.visibilityState === 'hidden') {
@@ -1431,7 +1477,7 @@ export class FinaticConnect extends EventEmitter {
 
       if (isMockMode) {
         // Mock the completion response
-        console.log('[FinaticConnect] Mock session completion for session:', sessionId);
+        this.logger.debug('Mock session completion', this.buildLoggerExtra('completeSession', { session_id: sessionId }));
         return;
       }
 
@@ -1444,13 +1490,16 @@ export class FinaticConnect extends EventEmitter {
       });
 
       if (response.ok) {
-        console.log('[FinaticConnect] Session completed successfully');
+        this.logger.info('Session completed successfully', this.buildLoggerExtra('completeSession', { session_id: sessionId }));
       } else {
-        console.warn('[FinaticConnect] Failed to complete session:', response.status);
+        this.logger.warn('Failed to complete session', this.buildLoggerExtra('completeSession', {
+          session_id: sessionId,
+          response_status: response.status,
+        }));
       }
     } catch (error) {
       // Silent failure - don't throw errors during cleanup
-      console.warn('[FinaticConnect] Session cleanup failed:', error);
+      this.logger.exception('Session cleanup failed', error, this.buildLoggerExtra('completeSession', { session_id: sessionId }));
     }
   }
 
@@ -1471,6 +1520,87 @@ export class FinaticConnect extends EventEmitter {
     return this.apiClient.disconnectCompany(connectionId);
   }
 
+  /**
+   * Get order fills for a specific order
+   * @param orderId - The order ID
+   * @param filter - Optional filter parameters
+   * @returns Promise with order fills response
+   */
+  public async getOrderFills(
+    orderId: string,
+    filter?: import('../../types/api/broker').OrderFillsFilter
+  ): Promise<import('../../types/api/broker').OrderFill[]> {
+    if (!(await this.isAuthenticated())) {
+      throw new AuthenticationError('User is not authenticated');
+    }
+    const response = await this.apiClient.getOrderFills(orderId, filter);
+    return response.response_data;
+  }
+
+  /**
+   * Get order events for a specific order
+   * @param orderId - The order ID
+   * @param filter - Optional filter parameters
+   * @returns Promise with order events response
+   */
+  public async getOrderEvents(
+    orderId: string,
+    filter?: import('../../types/api/broker').OrderEventsFilter
+  ): Promise<import('../../types/api/broker').OrderEvent[]> {
+    if (!(await this.isAuthenticated())) {
+      throw new AuthenticationError('User is not authenticated');
+    }
+    const response = await this.apiClient.getOrderEvents(orderId, filter);
+    return response.response_data;
+  }
+
+  /**
+   * Get order groups
+   * @param filter - Optional filter parameters
+   * @returns Promise with order groups response
+   */
+  public async getOrderGroups(
+    filter?: import('../../types/api/broker').OrderGroupsFilter
+  ): Promise<import('../../types/api/broker').OrderGroup[]> {
+    if (!(await this.isAuthenticated())) {
+      throw new AuthenticationError('User is not authenticated');
+    }
+    const response = await this.apiClient.getOrderGroups(filter);
+    return response.response_data;
+  }
+
+  /**
+   * Get position lots (tax lots for positions)
+   * @param filter - Optional filter parameters
+   * @returns Promise with position lots response
+   */
+  public async getPositionLots(
+    filter?: import('../../types/api/broker').PositionLotsFilter
+  ): Promise<import('../../types/api/broker').PositionLot[]> {
+    if (!(await this.isAuthenticated())) {
+      throw new AuthenticationError('User is not authenticated');
+    }
+    const response = await this.apiClient.getPositionLots(filter);
+    return response.response_data;
+  }
+
+  /**
+   * Get position lot fills for a specific lot
+   * @param lotId - The position lot ID
+   * @param filter - Optional filter parameters
+   * @returns Promise with position lot fills response
+   */
+  public async getPositionLotFills(
+    lotId: string,
+    filter?: import('../../types/api/broker').PositionLotFillsFilter
+  ): Promise<import('../../types/api/broker').PositionLotFill[]> {
+    if (!(await this.isAuthenticated())) {
+      throw new AuthenticationError('User is not authenticated');
+    }
+    const response = await this.apiClient.getPositionLotFills(lotId, filter);
+    return response.response_data;
+  }
+
   // Duplicate getBalances method removed - using the paginated version above
 
 }

package/src/core/portal/PortalUI.ts

@@ -1,3 +1,9 @@
+import { setupLogger, buildLoggerExtra, LoggerExtra } from '../../lib/logger';
+
+const portalLogger = setupLogger('FinaticClientSDK.PortalUI', undefined, {
+  codebase: 'FinaticClientSDK',
+});
+
 export class PortalUI {
   private iframe: HTMLIFrameElement | null = null;
   private container: HTMLDivElement | null = null;
@@ -12,12 +18,22 @@ export class PortalUI {
   };
   private originalBodyStyle: string | null = null;
 
+  private readonly logger = portalLogger;
+
   constructor(portalUrl: string) {
     this.createContainer();
   }
 
+  private buildLoggerExtra(functionName: string, metadata?: Record<string, unknown>): LoggerExtra {
+    return {
+      module: 'PortalUI',
+      function: functionName,
+      ...(metadata ? buildLoggerExtra(metadata) : {}),
+    };
+  }
+
   private createContainer(): void {
-    console.debug('[PortalUI] Creating container and iframe');
+    this.logger.debug('Creating portal container and iframe', this.buildLoggerExtra('createContainer'));
     this.container = document.createElement('div');
     this.container.style.cssText = `
             position: fixed;
@@ -74,7 +90,7 @@ export class PortalUI {
 
     this.container.appendChild(this.iframe);
     document.body.appendChild(this.container);
-    console.debug('[PortalUI] Container and iframe created successfully');
+    this.logger.debug('Portal container and iframe created successfully', this.buildLoggerExtra('createContainer'));
   }
 
   /**
@@ -91,7 +107,7 @@ export class PortalUI {
       document.body.style.width = '100%';
       document.body.style.top = `-${window.scrollY}px`;
 
-      console.debug('[PortalUI] Background scroll locked');
+      this.logger.debug('Background scroll locked', this.buildLoggerExtra('lockScroll'));
     }
   }
 
@@ -110,7 +126,7 @@ export class PortalUI {
       window.scrollTo(0, parseInt(scrollY || '0') * -1);
 
       this.originalBodyStyle = null;
-      console.debug('[PortalUI] Background scroll unlocked');
+      this.logger.debug('Background scroll unlocked', this.buildLoggerExtra('unlockScroll'));
     }
   }
 
@@ -168,17 +184,18 @@ export class PortalUI {
   private handleMessage(event: MessageEvent): void {
     // Verify origin matches the portal URL
     if (!this.portalOrigin || event.origin !== this.portalOrigin) {
-      console.warn(
-        '[PortalUI] Received message from unauthorized origin:',
-        event.origin,
-        'Expected:',
-        this.portalOrigin
-      );
+      this.logger.warn('Received message from unauthorized origin', this.buildLoggerExtra('handleMessage', {
+        received_origin: event.origin,
+        expected_origin: this.portalOrigin || 'unknown',
+      }));
       return;
     }
 
     const { type, userId, access_token, refresh_token, error, height, data } = event.data;
-    console.log('[PortalUI] Received message:', event.data);
+    this.logger.debug('Received portal message', this.buildLoggerExtra('handleMessage', {
+      message_type: type,
+      has_data: Boolean(data),
+    }));
 
     switch (type) {
       case 'portal-success': {
@@ -225,19 +242,26 @@ export class PortalUI {
         break;
 
       default:
-        console.warn('[PortalUI] Received unhandled message type:', type);
+        this.logger.warn('Received unhandled message type', this.buildLoggerExtra('handleMessage', {
+          message_type: type,
+        }));
     }
   }
 
   private handlePortalSuccess(userId: string, tokens?: { access_token?: string; refresh_token?: string }): void {
     if (!userId) {
-      console.error('[PortalUI] Missing userId in portal-success message');
+      this.logger.error('Missing userId in portal-success message', this.buildLoggerExtra('handlePortalSuccess'));
       return;
     }
 
-    console.log('[PortalUI] Portal success - User connected:', userId);
+    this.logger.info('Portal success - user connected', this.buildLoggerExtra('handlePortalSuccess', {
+      user_id_present: Boolean(userId),
+      tokens_provided: Boolean(tokens?.access_token && tokens?.refresh_token),
+    }));
     if (tokens?.access_token && tokens?.refresh_token) {
-      console.log('[PortalUI] Tokens received for user:', userId);
+      this.logger.debug('Tokens received for user', this.buildLoggerExtra('handlePortalSuccess', {
+        tokens_provided: true,
+      }));
     }
 
     // Pass userId to parent (SDK will handle tokens internally)
@@ -245,23 +269,30 @@ export class PortalUI {
   }
 
   private handlePortalError(error: string): void {
-    console.error('[PortalUI] Portal error:', error);
+    this.logger.error('Portal error received', this.buildLoggerExtra('handlePortalError', {
+      error_message: error,
+    }));
     this.options?.onError?.(new Error(error || 'Unknown portal error'));
   }
 
   private handlePortalClose(): void {
-    console.log('[PortalUI] Portal closed by user');
+    this.logger.info('Portal closed by user', this.buildLoggerExtra('handlePortalClose'));
     this.options?.onClose?.();
     this.hide();
   }
 
   private handleGenericEvent(data: any): void {
     if (!data || !data.type) {
-      console.warn('[PortalUI] Invalid event data:', data);
+      this.logger.warn('Invalid event data received', this.buildLoggerExtra('handleGenericEvent', {
+        has_type: Boolean(data?.type),
+      }));
       return;
     }
 
-    console.log('[PortalUI] Generic event received:', data.type, data.data);
+    this.logger.debug('Generic event received', this.buildLoggerExtra('handleGenericEvent', {
+      event_type: data.type,
+      payload_present: Boolean(data.data),
+    }));
 
     // Emit the event to be handled by the SDK
     // This will be implemented in FinaticConnect
@@ -272,7 +303,7 @@ export class PortalUI {
 
   private handleSuccess(userId: string): void {
     if (!userId) {
-      console.error('[PortalUI] Missing required fields in success message');
+      this.logger.error('Missing required fields in success message', this.buildLoggerExtra('handleSuccess'));
       return;
     }
 
@@ -281,19 +312,23 @@ export class PortalUI {
   }
 
   private handleError(error: string): void {
-    console.error('[PortalUI] Received error:', error);
+    this.logger.error('Received portal error message', this.buildLoggerExtra('handleError', {
+      error_message: error,
+    }));
     this.options?.onError?.(new Error(error || 'Unknown error'));
   }
 
   private handleClose(): void {
-    console.log('[PortalUI] Received close message');
+    this.logger.debug('Received close message', this.buildLoggerExtra('handleClose'));
     this.options?.onClose?.();
     this.hide();
   }
 
   private handleResize(height: number): void {
     if (height && this.iframe) {
-      console.log('[PortalUI] Received resize message:', height);
+      this.logger.debug('Received resize message', this.buildLoggerExtra('handleResize', {
+        height,
+      }));
       this.iframe.style.height = `${height}px`;
     }
   }

package/src/index.ts

@@ -48,6 +48,18 @@ export type {
   FilteredAccountsResponse,
   FilteredBalancesResponse,
   BrokerConnection,
+  OrderFill,
+  OrderEvent,
+  OrderLeg,
+  OrderGroup,
+  OrderGroupOrder,
+  PositionLot,
+  PositionLotFill,
+  OrderFillsFilter,
+  OrderEventsFilter,
+  OrderGroupsFilter,
+  PositionLotsFilter,
+  PositionLotFillsFilter,
 } from './types';
 
 export type { FinaticConnectOptions, FinaticUserToken, PortalMessage } from './types/connect';
@@ -79,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';
+