@finatic/client 0.0.140 → 0.0.142

package/README.md

@@ -356,6 +356,73 @@ if (ordersPage.hasPrevious) {
 // No manual session management required
 ```
 
+## Order and Position Detail Data
+
+### Getting Order Fills
+
+Order fills represent individual execution fills for an order:
+
+```typescript
+// Get fills for a specific order
+const fills = await finatic.getOrderFills('order-123', {
+  connection_id: 'connection-456',
+  limit: 50,
+  offset: 0,
+});
+```
+
+### Getting Order Events
+
+Order events represent lifecycle events for an order:
+
+```typescript
+// Get events for a specific order
+const events = await finatic.getOrderEvents('order-123', {
+  connection_id: 'connection-456',
+  limit: 100,
+});
+```
+
+### Getting Order Groups
+
+Order groups contain multiple related orders:
+
+```typescript
+// Get order groups with filters
+const groups = await finatic.getOrderGroups({
+  broker_id: 'robinhood',
+  connection_id: 'connection-456',
+  created_after: '2024-01-01T00:00:00Z',
+  limit: 50,
+});
+```
+
+### Getting Position Lots (Tax Lots)
+
+Position lots are used for tax reporting and track when positions were opened/closed:
+
+```typescript
+// Get position lots for tax reporting
+const lots = await finatic.getPositionLots({
+  broker_id: 'robinhood',
+  account_id: '123456789',
+  symbol: 'AAPL',
+  limit: 100,
+});
+```
+
+### Getting Position Lot Fills
+
+Position lot fills show the execution details for each lot:
+
+```typescript
+// Get fills for a specific position lot
+const lotFills = await finatic.getPositionLotFills('lot-123', {
+  connection_id: 'connection-456',
+  limit: 50,
+});
+```
+
 ## Type Definitions
 
 The SDK includes comprehensive TypeScript definitions for all data structures:
@@ -368,6 +435,11 @@ The SDK includes comprehensive TypeScript definitions for all data structures:
 - `BrokerConnection`: Connection information
 - `OrderResponse`: Order operation responses
 - `PaginatedResult`: Paginated data responses
+- `OrderFill`: Order fill information
+- `OrderEvent`: Order event information
+- `OrderGroup`: Order group information
+- `PositionLot`: Position lot (tax lot) information
+- `PositionLotFill`: Position lot fill information
 
 ## Error Types
 

package/dist/index.d.ts

@@ -473,6 +473,122 @@ interface DisconnectCompanyResponse {
     message: string;
     status_code: number;
 }
+interface OrderFill {
+    id: string;
+    order_id: string;
+    leg_id: string | null;
+    price: number;
+    quantity: number;
+    executed_at: string;
+    execution_id: string | null;
+    trade_id: string | null;
+    venue: string | null;
+    commission_fee: number | null;
+    created_at: string;
+    updated_at: string;
+}
+interface OrderEvent {
+    id: string;
+    order_id: string;
+    order_group_id: string | null;
+    event_type: string | null;
+    event_time: string;
+    event_id: string | null;
+    order_status: string | null;
+    inferred: boolean;
+    confidence: number | null;
+    reason_code: string | null;
+    recorded_at: string | null;
+}
+interface OrderLeg {
+    id: string;
+    order_id: string;
+    leg_index: number;
+    asset_type: string;
+    broker_provided_symbol: string | null;
+    quantity: number;
+    filled_quantity: number | null;
+    avg_fill_price: number | null;
+    created_at: string | null;
+    updated_at: string | null;
+}
+interface OrderGroupOrder extends BrokerDataOrder {
+    legs: OrderLeg[];
+}
+interface OrderGroup {
+    id: string;
+    user_broker_connection_id: string | null;
+    created_at: string;
+    updated_at: string;
+    orders: OrderGroupOrder[];
+}
+interface PositionLot {
+    id: string;
+    position_id: string | null;
+    user_broker_connection_id: string;
+    broker_provided_account_id: string;
+    instrument_key: string;
+    asset_type: string | null;
+    side: 'long' | 'short' | null;
+    open_quantity: number;
+    closed_quantity: number;
+    remaining_quantity: number;
+    open_price: number;
+    close_price_avg: number | null;
+    cost_basis: number;
+    cost_basis_w_commission: number;
+    realized_pl: number;
+    realized_pl_w_commission: number;
+    lot_opened_at: string;
+    lot_closed_at: string | null;
+    position_group_id: string | null;
+    created_at: string;
+    updated_at: string;
+    position_lot_fills?: PositionLotFill[];
+}
+interface PositionLotFill {
+    id: string;
+    lot_id: string;
+    order_fill_id: string;
+    fill_price: number;
+    fill_quantity: number;
+    executed_at: string;
+    commission_share: number | null;
+    created_at: string;
+    updated_at: string;
+}
+interface OrderFillsFilter {
+    connection_id?: string;
+    limit?: number;
+    offset?: number;
+}
+interface OrderEventsFilter {
+    connection_id?: string;
+    limit?: number;
+    offset?: number;
+}
+interface OrderGroupsFilter {
+    broker_id?: string;
+    connection_id?: string;
+    limit?: number;
+    offset?: number;
+    created_after?: string;
+    created_before?: string;
+}
+interface PositionLotsFilter {
+    broker_id?: string;
+    connection_id?: string;
+    account_id?: string;
+    symbol?: string;
+    position_id?: string;
+    limit?: number;
+    offset?: number;
+}
+interface PositionLotFillsFilter {
+    connection_id?: string;
+    limit?: number;
+    offset?: number;
+}
 
 /**
  * Order-related types
@@ -1011,6 +1127,8 @@ declare class ApiClient {
     private tradingContext;
     private companyId;
     private csrfToken;
+    private readonly logger;
+    private buildLoggerExtra;
     constructor(baseUrl: string, deviceInfo?: DeviceInfo$1);
     /**
      * Set session context (session ID, company ID, CSRF token)
@@ -1192,6 +1310,74 @@ declare class ApiClient {
      * @returns Promise with disconnect response
      */
     disconnectCompany(connectionId: string): Promise<DisconnectCompanyResponse>;
+    /**
+     * Get order fills for a specific order
+     * @param orderId - The order ID
+     * @param filter - Optional filter parameters
+     * @returns Promise with order fills response
+     */
+    getOrderFills(orderId: string, filter?: OrderFillsFilter): Promise<{
+        _id: string;
+        response_data: OrderFill[];
+        message: string;
+        status_code: number;
+        warnings: null;
+        errors: null;
+    }>;
+    /**
+     * Get order events for a specific order
+     * @param orderId - The order ID
+     * @param filter - Optional filter parameters
+     * @returns Promise with order events response
+     */
+    getOrderEvents(orderId: string, filter?: OrderEventsFilter): Promise<{
+        _id: string;
+        response_data: OrderEvent[];
+        message: string;
+        status_code: number;
+        warnings: null;
+        errors: null;
+    }>;
+    /**
+     * Get order groups
+     * @param filter - Optional filter parameters
+     * @returns Promise with order groups response
+     */
+    getOrderGroups(filter?: OrderGroupsFilter): Promise<{
+        _id: string;
+        response_data: OrderGroup[];
+        message: string;
+        status_code: number;
+        warnings: null;
+        errors: null;
+    }>;
+    /**
+     * Get position lots (tax lots for positions)
+     * @param filter - Optional filter parameters
+     * @returns Promise with position lots response
+     */
+    getPositionLots(filter?: PositionLotsFilter): Promise<{
+        _id: string;
+        response_data: PositionLot[];
+        message: string;
+        status_code: number;
+        warnings: null;
+        errors: null;
+    }>;
+    /**
+     * 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
+     */
+    getPositionLotFills(lotId: string, filter?: PositionLotFillsFilter): Promise<{
+        _id: string;
+        response_data: PositionLotFill[];
+        message: string;
+        status_code: number;
+        warnings: null;
+        errors: null;
+    }>;
 }
 
 type EventCallback = (...args: any[]) => void;
@@ -1230,6 +1416,8 @@ declare class FinaticConnect extends EventEmitter {
     private readonly SESSION_VALIDATION_TIMEOUT;
     private readonly SESSION_REFRESH_BUFFER_HOURS;
     private sessionStartTime;
+    private readonly logger;
+    private buildLoggerExtra;
     constructor(options: FinaticConnectOptions, deviceInfo?: DeviceInfo);
     private linkUserToSession;
     /**
@@ -1496,6 +1684,39 @@ declare class FinaticConnect extends EventEmitter {
      * @throws AuthenticationError if user is not authenticated
      */
     disconnectCompany(connectionId: string): Promise<DisconnectCompanyResponse>;
+    /**
+     * Get order fills for a specific order
+     * @param orderId - The order ID
+     * @param filter - Optional filter parameters
+     * @returns Promise with order fills response
+     */
+    getOrderFills(orderId: string, filter?: OrderFillsFilter): Promise<OrderFill[]>;
+    /**
+     * Get order events for a specific order
+     * @param orderId - The order ID
+     * @param filter - Optional filter parameters
+     * @returns Promise with order events response
+     */
+    getOrderEvents(orderId: string, filter?: OrderEventsFilter): Promise<OrderEvent[]>;
+    /**
+     * Get order groups
+     * @param filter - Optional filter parameters
+     * @returns Promise with order groups response
+     */
+    getOrderGroups(filter?: OrderGroupsFilter): Promise<OrderGroup[]>;
+    /**
+     * Get position lots (tax lots for positions)
+     * @param filter - Optional filter parameters
+     * @returns Promise with position lots response
+     */
+    getPositionLots(filter?: PositionLotsFilter): Promise<PositionLot[]>;
+    /**
+     * 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
+     */
+    getPositionLotFills(lotId: string, filter?: PositionLotFillsFilter): Promise<PositionLotFill[]>;
 }
 
 /**
@@ -1532,7 +1753,40 @@ declare function validateCustomTheme(theme: PortalThemeConfig): boolean;
  */
 declare function createCustomThemeFromPreset(preset: string, modifications: Partial<PortalThemeConfig>): PortalThemeConfig | null;
 
+type LogLevel = 'silent' | 'error' | 'warn' | 'info' | 'debug';
+interface LoggerMetadata {
+    [key: string]: unknown;
+}
+interface LoggerExtra {
+    metadata?: LoggerMetadata;
+    module?: string;
+    function?: string;
+    event?: string;
+    duration_ms?: number;
+    error?: unknown;
+    [key: string]: unknown;
+}
+interface LoggerOptions {
+    name: string;
+    level?: LogLevel;
+    defaultMetadata?: LoggerMetadata;
+}
+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;
+}
+type LogVerbosity = 0 | 1 | 2 | 3;
+
+declare const setupLogger: (nameOrOptions: string | LoggerOptions, level?: LogLevel, defaultMetadata?: LoggerMetadata) => Logger;
+declare const buildLoggerExtra: (metadata: LoggerMetadata) => LoggerExtra;
+declare const logStartEnd: (logger: Logger) => <Args extends unknown[], ReturnType>(fn: (...args: Args) => ReturnType | Promise<ReturnType>) => (...args: Args) => Promise<ReturnType>;
+
 declare const portalThemePresets: Record<string, PortalThemeConfig>;
 
-export { ApiClient, ApiError, AuthenticationError, AuthorizationError, BaseError, CompanyAccessError, EventEmitter, FinaticConnect, NetworkError, OrderError, OrderValidationError, PaginatedResult, RateLimitError, SecurityError, SessionError, TokenError, TradingNotEnabledError, appendThemeToURL, createCustomThemeFromPreset, generatePortalThemeURL, getThemePreset, portalThemePresets, validateCustomTheme };
-export type { AccountsFilter, ApiConfig, ApiResponse, BalancesFilter, BrokerAccount, BrokerBalance, BrokerConnection, BrokerDataAccount, BrokerDataOptions, BrokerDataOrder, BrokerDataPosition, BrokerExtras$1 as BrokerExtras, BrokerInfo, BrokerOrder, BrokerOrderParams, BrokerPosition, CryptoOrderOptions, DeviceInfo$1 as DeviceInfo, FilteredAccountsResponse, FilteredBalancesResponse, FilteredOrdersResponse, FilteredPositionsResponse, FinaticConnectOptions, FinaticUserToken, Holding, OptionsOrder, OptionsOrderOptions, Order, OrderNotFoundError, OrderResponse, OrdersFilter, OtpRequestResponse, OtpVerifyResponse, PerformanceMetrics, PortalMessage, PortalProps, PortalResponse, PortalTheme, PortalThemeConfig, PortalThemePreset, PortalUrlResponse, Portfolio, PortfolioSnapshot, PositionsFilter, RefreshTokenRequest, RefreshTokenResponse, RequestHeaders, SessionAuthenticateResponse, SessionInitResponse, SessionResponse, SessionStatus, SessionValidationResponse, TokenInfo, TradeAccessDeniedError, TradingContext, UserToken, ValidationError };
+export { ApiClient, ApiError, AuthenticationError, AuthorizationError, BaseError, CompanyAccessError, EventEmitter, FinaticConnect, NetworkError, OrderError, OrderValidationError, PaginatedResult, RateLimitError, SecurityError, SessionError, TokenError, TradingNotEnabledError, appendThemeToURL, buildLoggerExtra, createCustomThemeFromPreset, generatePortalThemeURL, getThemePreset, logStartEnd, portalThemePresets, setupLogger, validateCustomTheme };
+export type { AccountsFilter, ApiConfig, ApiResponse, BalancesFilter, BrokerAccount, BrokerBalance, BrokerConnection, BrokerDataAccount, BrokerDataOptions, BrokerDataOrder, BrokerDataPosition, BrokerExtras$1 as BrokerExtras, BrokerInfo, BrokerOrder, BrokerOrderParams, BrokerPosition, CryptoOrderOptions, DeviceInfo$1 as DeviceInfo, FilteredAccountsResponse, FilteredBalancesResponse, FilteredOrdersResponse, FilteredPositionsResponse, FinaticConnectOptions, FinaticUserToken, Holding, LogLevel, LogVerbosity, Logger, LoggerExtra, LoggerMetadata, LoggerOptions, OptionsOrder, OptionsOrderOptions, Order, OrderEvent, OrderEventsFilter, OrderFill, OrderFillsFilter, OrderGroup, OrderGroupOrder, OrderGroupsFilter, OrderLeg, OrderNotFoundError, OrderResponse, OrdersFilter, OtpRequestResponse, OtpVerifyResponse, PerformanceMetrics, PortalMessage, PortalProps, PortalResponse, PortalTheme, PortalThemeConfig, PortalThemePreset, PortalUrlResponse, Portfolio, PortfolioSnapshot, PositionLot, PositionLotFill, PositionLotFillsFilter, PositionLotsFilter, PositionsFilter, RefreshTokenRequest, RefreshTokenResponse, RequestHeaders, SessionAuthenticateResponse, SessionInitResponse, SessionResponse, SessionStatus, SessionValidationResponse, TokenInfo, TradeAccessDeniedError, TradingContext, UserToken, ValidationError };