@finatic/client 0.0.139 → 0.0.141

package/README.md

@@ -37,540 +37,429 @@ const finatic = await FinaticConnect.init('your-one-time-token', 'user-123', {
 });
 ```
 
-// Open the portal
-await finatic.openPortal({
-onSuccess: (userId) => {
-console.log('Authentication successful:', userId);
-},
-onError: (error) => {
-console.error('Authentication failed:', error);
-},
-onClose: () => {
-console.log('Portal closed');
-}
-});
-
-// After successful authentication, you can use these methods:
-
-// Get list of supported brokers
-const brokers = await finatic.getBrokerList();
-
-// Get broker accounts with pagination
-const accountsPage = await finatic.getAccounts({
-page: 1,
-perPage: 100
-});
-
-// Navigate through pages
-const nextPage = await accountsPage.nextPage();
-const prevPage = await accountsPage.previousPage();
-
-// Get all accounts (convenience method)
-const allAccounts = await finatic.getAllAccounts();
-
-// Get orders with filtering
-const ordersPage = await finatic.getOrders({
-page: 1,
-perPage: 50,
-filter: { status: 'filled', symbol: 'AAPL' }
-});
+## Portal Management
 
-// Get positions
-const positionsPage = await finatic.getPositions({
-page: 1,
-perPage: 100
-});
+### Opening the Portal
 
-// Place orders
-await finatic.placeOrder({
-symbol: 'AAPL',
-side: 'buy',
-quantity: 10,
-type: 'market',
-timeInForce: 'day'
+```typescript
+// Open the portal with basic configuration
+await finatic.openPortal({
+  onSuccess: userId => {
+    console.log('Authentication successful:', userId);
+  },
+  onError: error => {
+    console.error('Authentication failed:', error);
+  },
+  onClose: () => {
+    console.log('Portal closed');
+  },
 });
 
 // Open portal with broker filtering
 await finatic.openPortal({
-brokers: ['alpaca', 'robinhood'] // Only show these brokers
+  brokers: ['alpaca', 'robinhood'], // Only show these brokers
+  onSuccess: userId => {
+    console.log('Authentication successful:', userId);
+  },
 });
 
-// Disconnect a company from a broker connection
-const disconnectResponse = await finatic.disconnectCompany('connection-uuid-here');
-console.log('Disconnect action:', disconnectResponse.response_data.action);
-
-// Close the portal when done
-finatic.closePortal();
-
-````
-
-## API Reference
-
-### Initialization
-
-#### `FinaticConnect.init(token, userId?, options?)`
-
-Initialize the Finatic Client SDK.
-
-- `token` (string): One-time token from your backend
-- `userId` (string, optional): Pre-authenticated user ID from previous session
-- `options` (object, optional): Configuration options
-  - `baseUrl` (string, optional): Custom API base URL
-
-Returns: Promise<FinaticConnect>
-
-### Portal Management
-
-#### `openPortal(options?)`
-
-Opens the authentication portal in an iframe.
-
-- `options` (object, optional): Portal options
-  - `onSuccess` (function): Called when authentication succeeds
-  - `onError` (function): Called when authentication fails
-  - `onClose` (function): Called when portal is closed
-  - `onEvent` (function): Called when portal events occur
-  - `theme` (object, optional): Theme configuration
-    - `preset` (string, optional): Preset theme name ('dark', 'light', 'corporateBlue', 'purple', 'green', 'orange')
-    - `custom` (object, optional): Custom theme configuration object
-  - `brokers` (string[], optional): List of broker names to filter by (only these brokers will be shown)
-
-#### `closePortal()`
-
-Closes the authentication portal.
-
-### Portal Theming
-
-The Finatic Portal supports dynamic theme switching via URL parameters. You can customize the portal's appearance to match your application's branding.
-
-#### Using Preset Themes
-
-```javascript
-// Use a preset theme
+// Open portal with theming
 await finatic.openPortal({
-  theme: { preset: 'corporateBlue' }
-});
-
-// Available presets: 'dark', 'light', 'corporateBlue', 'purple', 'green', 'orange'
-````
-
-#### Using Custom Themes
-
-```javascript
-// Use a custom theme
-const customTheme = {
-  mode: 'dark',
-  colors: {
-    background: {
-      primary: '#1a1a1a',
-      secondary: '#2a2a2a',
-      tertiary: '#3a3a3a',
-      accent: 'rgba(59, 130, 246, 0.1)',
-      glass: 'rgba(255, 255, 255, 0.05)',
-    },
-    status: {
-      connected: '#10B981',
-      disconnected: '#EF4444',
-      warning: '#F59E0B',
-      pending: '#8B5CF6',
-      error: '#EF4444',
-      success: '#10B981',
-    },
-    text: {
-      primary: '#F8FAFC',
-      secondary: '#CBD5E1',
-      muted: '#94A3B8',
-      inverse: '#1a1a1a',
-    },
-    border: {
-      primary: 'rgba(59, 130, 246, 0.2)',
-      secondary: 'rgba(255, 255, 255, 0.1)',
-      hover: 'rgba(59, 130, 246, 0.4)',
-      focus: 'rgba(59, 130, 246, 0.6)',
-      accent: '#3B82F6',
-    },
-    input: {
-      background: '#334155',
-      border: 'rgba(59, 130, 246, 0.2)',
-      borderFocus: '#3B82F6',
-      text: '#F8FAFC',
-      placeholder: '#94A3B8',
-    },
-    button: {
-      primary: {
-        background: '#3B82F6',
-        text: '#FFFFFF',
-        hover: '#2563EB',
-        active: '#1D4ED8',
-      },
-      secondary: {
-        background: 'transparent',
-        text: '#3B82F6',
-        border: '#3B82F6',
-        hover: 'rgba(59, 130, 246, 0.1)',
-        active: 'rgba(59, 130, 246, 0.2)',
-      },
-    },
-  },
-  branding: {
-    primaryColor: '#3B82F6',
+  theme: {
+    primaryColor: '#007bff',
+    logoUrl: 'https://example.com/logo.png',
   },
-};
-
-await finatic.openPortal({
-  theme: { custom: customTheme },
 });
 ```
 
-#### Theme Utilities
-
-```javascript
-import {
-  generatePortalThemeURL,
-  appendThemeToURL,
-  getThemePreset,
-  validateCustomTheme,
-  createCustomThemeFromPreset,
-  portalThemePresets,
-} from 'finatic-sdk';
-
-// Generate a themed portal URL
-const themedUrl = generatePortalThemeURL('http://localhost:5173/companies', {
-  preset: 'corporateBlue',
-});
-
-// Get a theme preset
-const darkTheme = getThemePreset('dark');
-
-// Validate a custom theme
-const isValid = validateCustomTheme(customTheme);
+### Closing the Portal
 
-// Create a custom theme from a preset
-const modifiedTheme = createCustomThemeFromPreset('dark', {
-  colors: {
-    background: {
-      primary: '#000000',
-    },
-  },
-});
+```typescript
+// Close the portal
+await finatic.closePortal();
 ```
 
-### Portal Broker Filtering
-
-The Finatic Portal supports broker filtering via URL parameters. You can restrict which brokers are displayed in the portal by specifying a list of allowed broker names.
-
-#### Supported Brokers
-
-The following broker names are supported:
-
-- `alpaca` - Alpaca Markets
-- `robinhood` - Robinhood
-- `tasty_trade` - TastyTrade
-- `ninja_trader` - NinjaTrader
+## Data Access
 
-#### Using Broker Filtering
+### Paginated Data Access
 
-```javascript
-// Show only specific brokers
-await finatic.openPortal({
-  brokers: ['alpaca', 'robinhood'],
-});
+The SDK provides a consistent pagination pattern using `get*()` methods with navigation:
 
-// Show only one broker
-await finatic.openPortal({
-  brokers: ['tasty_trade'],
+```typescript
+// Get orders with pagination
+const ordersPage = await finatic.getOrders({
+  page: 1,
+  perPage: 50,
+  filter: { status: 'filled', symbol: 'AAPL' },
 });
 
-// Combine with theme
-await finatic.openPortal({
-  theme: { preset: 'dark' },
-  brokers: ['alpaca', 'ninja_trader'],
-});
+// Navigate through pages
+const nextPage = await ordersPage.nextPage();
+const prevPage = await ordersPage.previousPage();
+
+// Check pagination status
+console.log('Has next page:', ordersPage.hasNext);
+console.log('Has previous page:', ordersPage.hasPrevious);
+console.log('Current page:', ordersPage.page);
+console.log('Total pages:', ordersPage.totalPages);
 ```
 
-#### Error Handling
-
-If you pass an unsupported broker name, it will be logged as a warning to the console, but the portal will still open with the supported brokers:
+### Get All Data (Convenience Methods)
 
-```javascript
-// This will log a warning for 'unsupported_broker' but continue with 'alpaca'
-await finatic.openPortal({
-  brokers: ['alpaca', 'unsupported_broker'],
-});
+```typescript
+// Get all data across all pages
+const allOrders = await finatic.getAllOrders();
+const allPositions = await finatic.getAllPositions();
+const allAccounts = await finatic.getAllAccounts();
+const allBalances = await finatic.getAllBalances();
 ```
 
-#### Broker Filtering Utilities
-
-```javascript
-import {
-  convertBrokerNamesToIds,
-  appendBrokerFilterToURL,
-  getSupportedBrokerNames,
-  isBrokerSupported,
-} from 'finatic-sdk';
-
-// Convert broker names to IDs
-const { brokerIds, warnings } = convertBrokerNamesToIds(['alpaca', 'robinhood']);
+### Convenience Filter Methods
 
-// Get list of supported broker names
-const supportedBrokers = getSupportedBrokerNames();
-
-// Check if a broker is supported
-const isSupported = isBrokerSupported('alpaca');
+```typescript
+// Get filtered data
+const openPositions = await finatic.getOpenPositions();
+const filledOrders = await finatic.getFilledOrders();
+const pendingOrders = await finatic.getPendingOrders();
+const activeAccounts = await finatic.getActiveAccounts();
+
+// Get data by symbol
+const aaplOrders = await finatic.getOrdersBySymbol('AAPL');
+const aaplPositions = await finatic.getPositionsBySymbol('AAPL');
+
+// Get data by broker
+const robinhoodOrders = await finatic.getOrdersByBroker('robinhood');
+const robinhoodPositions = await finatic.getPositionsByBroker('robinhood');
 ```
 
-### Data Access (Paginated)
-
-#### `getAccounts(params?)`
-
-Returns paginated broker accounts.
-
-- `params` (object, optional): Query parameters
-  - `page` (number, optional): Page number (default: 1)
-  - `perPage` (number, optional): Items per page (default: 100)
-  - `filter` (object, optional): Filter parameters
-
-Returns: Promise<PaginatedResult<BrokerDataAccount[]>>
-
-#### `getOrders(params?)`
-
-Returns paginated order history.
-
-- `params` (object, optional): Query parameters
-  - `page` (number, optional): Page number (default: 1)
-  - `perPage` (number, optional): Items per page (default: 100)
-  - `filter` (object, optional): Filter parameters
-
-Returns: Promise<PaginatedResult<BrokerDataOrder[]>>
-
-#### `getPositions(params?)`
-
-Returns paginated positions.
-
-- `params` (object, optional): Query parameters
-  - `page` (number, optional): Page number (default: 1)
-  - `perPage` (number, optional): Items per page (default: 100)
-  - `filter` (object, optional): Filter parameters
-
-Returns: Promise<PaginatedResult<BrokerDataPosition[]>>
-
-### Data Access (Get All - Convenience Methods)
-
-#### `getAllAccounts(filter?)`
-
-Returns all broker accounts across all pages.
-
-- `filter` (object, optional): Filter parameters
-
-Returns: Promise<BrokerDataAccount[]>
-
-#### `getAllOrders(filter?)`
+## Trading Operations
 
-Returns all orders across all pages.
+### General Order Placement
 
-- `filter` (object, optional): Filter parameters
-
-Returns: Promise<BrokerDataOrder[]>
-
-#### `getAllPositions(filter?)`
-
-Returns all positions across all pages.
-
-- `filter` (object, optional): Filter parameters
-
-Returns: Promise<BrokerDataPosition[]>
-
-### Convenience Methods
-
-#### `getOpenPositions()`
-
-Returns only open positions.
-
-Returns: Promise<BrokerDataPosition[]>
-
-#### `getFilledOrders()`
-
-Returns only filled orders.
-
-Returns: Promise<BrokerDataOrder[]>
-
-#### `getPendingOrders()`
-
-Returns only pending orders.
-
-Returns: Promise<BrokerDataOrder[]>
-
-#### `getActiveAccounts()`
-
-Returns only active accounts.
-
-Returns: Promise<BrokerDataAccount[]>
-
-#### `getOrdersBySymbol(symbol)`
-
-Returns orders for a specific symbol.
-
-- `symbol` (string): Stock symbol
-
-Returns: Promise<BrokerDataOrder[]>
-
-#### `getPositionsBySymbol(symbol)`
-
-Returns positions for a specific symbol.
-
-- `symbol` (string): Stock symbol
-
-Returns: Promise<BrokerDataPosition[]>
-
-#### `getOrdersByBroker(brokerId)`
-
-Returns orders for a specific broker.
+```typescript
+// Place a market order
+const orderResponse = await finatic.placeOrder({
+  symbol: 'AAPL',
+  side: 'buy',
+  quantity: 10,
+  orderType: 'market',
+  timeInForce: 'day',
+});
 
-- `brokerId` (string): Broker ID
+// Place a limit order
+const limitOrderResponse = await finatic.placeOrder({
+  symbol: 'AAPL',
+  side: 'buy',
+  quantity: 10,
+  orderType: 'limit',
+  price: 150.0,
+  timeInForce: 'gtc',
+});
+```
 
-Returns: Promise<BrokerDataOrder[]>
+### Asset-Specific Order Methods
 
-#### `getPositionsByBroker(brokerId)`
+#### Stock Orders
 
-Returns positions for a specific broker.
+```typescript
+// Stock market order
+const response = await finatic.placeStockMarketOrder('AAPL', 10, 'buy', 'robinhood', '123456789');
+
+// Stock limit order
+const response = await finatic.placeStockLimitOrder(
+  'AAPL',
+  10,
+  'buy',
+  150.0,
+  'gtc',
+  'robinhood',
+  '123456789'
+);
+
+// Stock stop order
+const response = await finatic.placeStockStopOrder(
+  'AAPL',
+  10,
+  'sell',
+  140.0,
+  'gtc',
+  'robinhood',
+  '123456789'
+);
+```
 
-- `brokerId` (string): Broker ID
+#### Crypto Orders
 
-Returns: Promise<BrokerDataPosition[]>
+```typescript
+// Crypto market order
+const response = await finatic.placeCryptoMarketOrder(
+  'BTC-USD',
+  0.1,
+  'buy',
+  'coinbase',
+  '123456789'
+);
+
+// Crypto limit order
+const response = await finatic.placeCryptoLimitOrder(
+  'BTC-USD',
+  0.1,
+  'buy',
+  50000.0,
+  'gtc',
+  'coinbase',
+  '123456789'
+);
+```
 
-### Broker Information
+#### Options Orders
 
-#### `getBrokerList()`
+```typescript
+// Options market order
+const response = await finatic.placeOptionsMarketOrder(
+  'AAPL240315C00150000',
+  1,
+  'buy',
+  'tasty_trade',
+  '123456789'
+);
+
+// Options limit order
+const response = await finatic.placeOptionsLimitOrder(
+  'AAPL240315C00150000',
+  1,
+  'buy',
+  5.0,
+  'gtc',
+  'tasty_trade',
+  '123456789'
+);
+```
 
-Returns a list of supported brokers.
+#### Futures Orders
 
-Returns: Promise<BrokerInfo[]>
+```typescript
+// Futures market order
+const response = await finatic.placeFuturesMarketOrder('ES', 1, 'buy', 'ninja_trader', '123456789');
+
+// Futures limit order
+const response = await finatic.placeFuturesLimitOrder(
+  'ES',
+  1,
+  'buy',
+  4500.0,
+  'gtc',
+  'ninja_trader',
+  '123456789'
+);
+```
 
-#### `getBrokerConnections()`
+### Order Management
 
-Returns broker connections for the authenticated user.
+```typescript
+// Cancel an order
+const response = await finatic.cancelOrder('order-123', 'robinhood', 'connection-456');
+
+// Modify an order
+const response = await finatic.modifyOrder(
+  'order-123',
+  { price: 155.0, quantity: 5 },
+  'robinhood',
+  'connection-456'
+);
+```
 
-Returns: Promise<BrokerConnection[]>
+## Broker Information
 
-#### `disconnectCompany(connectionId)`
+```typescript
+// Get list of supported brokers
+const brokers = await finatic.getBrokerList();
 
-Disconnects a company from a broker connection.
+// Get broker connections
+const connections = await finatic.getBrokerConnections();
 
-- `connectionId` (string): The connection ID to disconnect
+// Disconnect a company from a broker connection
+const disconnectResponse = await finatic.disconnectCompany('connection-uuid-here');
+console.log('Disconnect action:', disconnectResponse.response_data.action);
+```
 
-Returns: Promise<DisconnectCompanyResponse>
+## Authentication
 
-The response includes:
+```typescript
+// Check authentication status
+const isAuthenticated = finatic.isAuthed();
+const isAuthenticatedAlt = finatic.is_authenticated();
 
-- `success` (boolean): Whether the operation was successful
-- `response_data.action` (string): Either 'company_access_removed' or 'connection_deleted'
-- `response_data.remaining_companies` (number, optional): Number of remaining companies if connection still exists
-- `response_data.message` (string): Human-readable message about the action taken
+// Get user ID
+const userId = finatic.getUserId();
 
-### Trading
+// Set user ID (for returning users)
+finatic.setUserId('user-123');
+```
 
-#### `placeOrder(order)`
+## Error Handling
 
-Places a new order.
+```typescript
+import { AuthenticationError, ApiError, ValidationError } from '@finatic/client';
 
-- `order` (object): Order details
-  - `symbol` (string): Stock symbol
-  - `side` (string): 'buy' or 'sell'
-  - `quantity` (number): Number of shares
-  - `type` (string): 'market', 'limit', 'stop', or 'stop_limit'
-  - `timeInForce` (string): 'day', 'gtc', 'opg', 'cls', 'ioc', or 'fok'
-  - `price` (number, optional): Limit price
-  - `stopPrice` (number, optional): Stop price
+try {
+  const orders = await finatic.getOrders();
+} catch (error) {
+  if (error instanceof AuthenticationError) {
+    console.error('Authentication failed:', error.message);
+  } else if (error instanceof ValidationError) {
+    console.error('Invalid request:', error.message);
+  } else if (error instanceof ApiError) {
+    console.error('API error:', error.message);
+  }
+}
+```
 
-#### `cancelOrder(orderId, broker?)`
+## Advanced Usage
 
-Cancels an existing order.
+### Custom Filters
 
-- `orderId` (string): Order ID to cancel
-- `broker` (string, optional): Broker name
+```typescript
+// Get orders with custom filters
+const orders = await finatic.getOrders({
+  page: 1,
+  perPage: 50,
+  filter: {
+    status: 'filled',
+    symbol: 'AAPL',
+    broker: 'robinhood',
+  },
+});
+```
 
-#### `modifyOrder(orderId, modifications, broker?)`
+### Pagination Navigation
 
-Modifies an existing order.
+```typescript
+// Get paginated results with navigation
+const ordersPage = await finatic.getOrders({ page: 1, perPage: 100 });
 
-- `orderId` (string): Order ID to modify
-- `modifications` (object): Order modifications
-- `broker` (string, optional): Broker name
+// Navigate through pages
+if (ordersPage.hasNext) {
+  const nextPage = await ordersPage.nextPage();
+}
 
-### Authentication
+if (ordersPage.hasPrevious) {
+  const prevPage = await ordersPage.previousPage();
+}
+```
 
-#### `isAuthed()`
+### Session Management
 
-Returns true if the user is fully authenticated (has userId, access token, and refresh token).
+```typescript
+// The SDK automatically manages sessions
+// Sessions are kept alive for 24 hours by default
+// No manual session management required
+```
 
-#### `getUserId()`
+## Order and Position Detail Data
 
-Returns the current user ID, or `null` if not authenticated.
+### Getting Order Fills
 
-### Pagination Navigation
+Order fills represent individual execution fills for an order:
 
-The `PaginatedResult` object returned by paginated methods includes navigation methods:
+```typescript
+// Get fills for a specific order
+const fills = await finatic.getOrderFills('order-123', {
+  connection_id: 'connection-456',
+  limit: 50,
+  offset: 0,
+});
+```
 
-#### `nextPage()`
+### Getting Order Events
 
-Returns the next page of results.
+Order events represent lifecycle events for an order:
 
-Returns: Promise<PaginatedResult<T> | null>
+```typescript
+// Get events for a specific order
+const events = await finatic.getOrderEvents('order-123', {
+  connection_id: 'connection-456',
+  limit: 100,
+});
+```
 
-#### `previousPage()`
+### Getting Order Groups
 
-Returns the previous page of results.
+Order groups contain multiple related orders:
 
-Returns: Promise<PaginatedResult<T> | null>
+```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,
+});
+```
 
-#### `firstPage()`
+### Getting Position Lots (Tax Lots)
 
-Returns the first page of results.
+Position lots are used for tax reporting and track when positions were opened/closed:
 
-Returns: Promise<PaginatedResult<T>>
+```typescript
+// Get position lots for tax reporting
+const lots = await finatic.getPositionLots({
+  broker_id: 'robinhood',
+  account_id: '123456789',
+  symbol: 'AAPL',
+  limit: 100,
+});
+```
 
-#### `goToPage(pageNumber)`
+### Getting Position Lot Fills
 
-Goes to a specific page.
+Position lot fills show the execution details for each lot:
 
-- `pageNumber` (number): Page number to navigate to
+```typescript
+// Get fills for a specific position lot
+const lotFills = await finatic.getPositionLotFills('lot-123', {
+  connection_id: 'connection-456',
+  limit: 50,
+});
+```
 
-Returns: Promise<PaginatedResult<T> | null>
+## Type Definitions
 
-## Error Handling
+The SDK includes comprehensive TypeScript definitions for all data structures:
 
-The SDK throws specific error types for different scenarios:
+- `BrokerDataOrder`: Order information
+- `BrokerDataPosition`: Position information
+- `BrokerDataAccount`: Account information
+- `BrokerBalance`: Balance information
+- `BrokerInfo`: Broker information
+- `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
 
-```typescript
-import {
-  ApiError,
-  SessionError,
-  AuthenticationError,
-  AuthorizationError,
-  RateLimitError,
-  CompanyAccessError,
-} from '@finatic/client';
+## Error Types
 
-try {
-  await finatic.openPortal();
-} catch (error) {
-  if (error instanceof CompanyAccessError) {
-    console.log('No broker connections found for this company');
-  } else if (error instanceof AuthenticationError) {
-    console.log('Authentication failed');
-  }
-}
-```
+- `AuthenticationError`: Authentication failures
+- `ApiError`: API request failures
+- `ValidationError`: Invalid request parameters
+- `ConnectionError`: Network connectivity issues
 
 ## Browser Support
 
-This SDK is designed for modern browsers and requires:
+- Chrome 80+
+- Firefox 75+
+- Safari 13+
+- Edge 80+
+
+## Requirements
 
-- ES2020 support
-- Fetch API
-- Promise support
-- LocalStorage (for token caching)
+- Modern browser with ES2018+ support
+- No external dependencies
 
 ## License
 
-MIT
+MIT License