@finatic/client 0.0.140 → 0.0.141

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
@@ -1192,6 +1308,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;
@@ -1496,6 +1680,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[]>;
 }
 
 /**
@@ -1535,4 +1752,4 @@ declare function createCustomThemeFromPreset(preset: string, modifications: Part
 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 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, 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 };

package/dist/index.js

@@ -1411,6 +1411,155 @@ class ApiClient {
             },
         });
     }
+    /**
+     * Get order fills for a specific order
+     * @param orderId - The order ID
+     * @param filter - Optional filter parameters
+     * @returns Promise with order fills response
+     */
+    async getOrderFills(orderId, filter) {
+        const accessToken = await this.getValidAccessToken();
+        const params = {};
+        if (filter?.connection_id) {
+            params.connection_id = filter.connection_id;
+        }
+        if (filter?.limit) {
+            params.limit = filter.limit.toString();
+        }
+        if (filter?.offset) {
+            params.offset = filter.offset.toString();
+        }
+        return this.request(`/brokers/data/orders/${orderId}/fills`, {
+            method: 'GET',
+            headers: {
+                Authorization: `Bearer ${accessToken}`,
+            },
+            params,
+        });
+    }
+    /**
+     * Get order events for a specific order
+     * @param orderId - The order ID
+     * @param filter - Optional filter parameters
+     * @returns Promise with order events response
+     */
+    async getOrderEvents(orderId, filter) {
+        const accessToken = await this.getValidAccessToken();
+        const params = {};
+        if (filter?.connection_id) {
+            params.connection_id = filter.connection_id;
+        }
+        if (filter?.limit) {
+            params.limit = filter.limit.toString();
+        }
+        if (filter?.offset) {
+            params.offset = filter.offset.toString();
+        }
+        return this.request(`/brokers/data/orders/${orderId}/events`, {
+            method: 'GET',
+            headers: {
+                Authorization: `Bearer ${accessToken}`,
+            },
+            params,
+        });
+    }
+    /**
+     * Get order groups
+     * @param filter - Optional filter parameters
+     * @returns Promise with order groups response
+     */
+    async getOrderGroups(filter) {
+        const accessToken = await this.getValidAccessToken();
+        const params = {};
+        if (filter?.broker_id) {
+            params.broker_id = filter.broker_id;
+        }
+        if (filter?.connection_id) {
+            params.connection_id = filter.connection_id;
+        }
+        if (filter?.limit) {
+            params.limit = filter.limit.toString();
+        }
+        if (filter?.offset) {
+            params.offset = filter.offset.toString();
+        }
+        if (filter?.created_after) {
+            params.created_after = filter.created_after;
+        }
+        if (filter?.created_before) {
+            params.created_before = filter.created_before;
+        }
+        return this.request('/brokers/data/orders/groups', {
+            method: 'GET',
+            headers: {
+                Authorization: `Bearer ${accessToken}`,
+            },
+            params,
+        });
+    }
+    /**
+     * Get position lots (tax lots for positions)
+     * @param filter - Optional filter parameters
+     * @returns Promise with position lots response
+     */
+    async getPositionLots(filter) {
+        const accessToken = await this.getValidAccessToken();
+        const params = {};
+        if (filter?.broker_id) {
+            params.broker_id = filter.broker_id;
+        }
+        if (filter?.connection_id) {
+            params.connection_id = filter.connection_id;
+        }
+        if (filter?.account_id) {
+            params.account_id = filter.account_id;
+        }
+        if (filter?.symbol) {
+            params.symbol = filter.symbol;
+        }
+        if (filter?.position_id) {
+            params.position_id = filter.position_id;
+        }
+        if (filter?.limit) {
+            params.limit = filter.limit.toString();
+        }
+        if (filter?.offset) {
+            params.offset = filter.offset.toString();
+        }
+        return this.request('/brokers/data/positions/lots', {
+            method: 'GET',
+            headers: {
+                Authorization: `Bearer ${accessToken}`,
+            },
+            params,
+        });
+    }
+    /**
+     * 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
+     */
+    async getPositionLotFills(lotId, filter) {
+        const accessToken = await this.getValidAccessToken();
+        const params = {};
+        if (filter?.connection_id) {
+            params.connection_id = filter.connection_id;
+        }
+        if (filter?.limit) {
+            params.limit = filter.limit.toString();
+        }
+        if (filter?.offset) {
+            params.offset = filter.offset.toString();
+        }
+        return this.request(`/brokers/data/positions/lots/${lotId}/fills`, {
+            method: 'GET',
+            headers: {
+                Authorization: `Bearer ${accessToken}`,
+            },
+            params,
+        });
+    }
 }
 
 class EventEmitter {
@@ -5885,6 +6034,69 @@ 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
+     */
+    async getOrderFills(orderId, filter) {
+        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
+     */
+    async getOrderEvents(orderId, filter) {
+        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
+     */
+    async getOrderGroups(filter) {
+        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
+     */
+    async getPositionLots(filter) {
+        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
+     */
+    async getPositionLotFills(lotId, filter) {
+        if (!(await this.isAuthenticated())) {
+            throw new AuthenticationError('User is not authenticated');
+        }
+        const response = await this.apiClient.getPositionLotFills(lotId, filter);
+        return response.response_data;
+    }
 }
 FinaticConnect.instance = null;