@finatic/client 0.9.0 → 0.9.2

package/README.md

@@ -1,465 +1,290 @@
 # Finatic Client SDK
 
-A comprehensive browser SDK for integrating Finatic Client into your web applications.
+A comprehensive browser SDK for integrating Finatic into your web applications. Connect your users to multiple brokerages through a unified, standardized interface.
+
+**Finatic is a brokerage first aggregator. We simplify, standardize and enhance broker data.**
 
 ## Installation
 
 ```bash
 npm install @finatic/client
-# or
+```
+
+Or using yarn:
+
+```bash
 yarn add @finatic/client
 ```
 
-## Basic Usage
+## Quick Start (5 Minutes)
 
-### Simple Initialization
+### 1. Initialize the SDK
 
 ```typescript
 import { FinaticConnect } from '@finatic/client';
 
-// Just pass the token - everything else uses defaults
-const finatic = await FinaticConnect.init('your-one-time-token');
-```
-
-### With User ID (for returning users)
-
-```typescript
-// Pass token and user ID from previous session
-const finatic = await FinaticConnect.init('your-one-time-token', 'user-123');
+// Initialize with a one-time token (obtained from your backend)
+const finatic = await FinaticConnect.init('your-one-time-token', undefined, {
+  baseUrl: 'https://api.finatic.dev', // Optional, defaults to production
+  logLevel: 'info', // Optional: 'debug' | 'info' | 'warn' | 'error'
+});
 ```
 
-### With Custom Configuration
+**Note:** The Client SDK requires a one-time token (not an API key). Get this token from your backend server using the Server SDK's `getToken()` method.
 
-```typescript
-// Pass token, user ID, and custom API URL
-const finatic = await FinaticConnect.init('your-one-time-token', 'user-123', {
-  baseUrl: 'https://api.finatic.dev',
-});
-```
+### 2. Open the Portal for Authentication
 
-## Portal Management
+The portal allows users to connect their broker accounts. You can either:
 
-### Opening the Portal
+**Option A: Open portal in iframe (recommended)**
 
 ```typescript
-// Open the portal with basic configuration
-await finatic.openPortal({
-  onSuccess: userId => {
-    console.log('Authentication successful:', userId);
+await finatic.openPortal(
+  'dark', // Theme: 'light' | 'dark' | theme object
+  ['alpaca', 'tradier'], // Optional: Filter specific brokers
+  'user@example.com', // Optional: Pre-fill email
+  'modal', // Mode: 'modal' | 'fullscreen'
+  (userId) => {
+    // User successfully authenticated
+    console.log('User authenticated:', userId);
   },
-  onError: error => {
-    console.error('Authentication failed:', error);
+  (error) => {
+    // Handle authentication error
+    console.error('Portal error:', error);
   },
-  onClose: () => {
+  () => {
+    // Portal was closed
     console.log('Portal closed');
-  },
-});
-
-// Open portal with broker filtering
-await finatic.openPortal({
-  brokers: ['alpaca', 'robinhood'], // Only show these brokers
-  onSuccess: userId => {
-    console.log('Authentication successful:', userId);
-  },
-});
-
-// Open portal with theming
-await finatic.openPortal({
-  theme: {
-    primaryColor: '#007bff',
-    logoUrl: 'https://example.com/logo.png',
-  },
-});
-```
-
-### Closing the Portal
-
-```typescript
-// Close the portal
-await finatic.closePortal();
+  }
+);
 ```
 
-## Data Access
-
-### Paginated Data Access
-
-The SDK provides a consistent pagination pattern using `get*()` methods with navigation:
+**Option B: Get portal URL and redirect**
 
 ```typescript
-// Get orders with pagination
-const ordersPage = await finatic.getOrders({
-  page: 1,
-  perPage: 50,
-  filter: { status: 'filled', symbol: 'AAPL' },
-});
-
-// Navigate through pages
-const nextPage = await ordersPage.nextPage();
-const prevPage = await ordersPage.previousPage();
+const portalUrl = await finatic.getPortalUrl(
+  'dark', // Theme
+  ['alpaca'], // Optional: Filter brokers
+  'user@example.com', // Optional: Pre-fill email
+  'dark' // Mode
+);
 
-// 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);
+// Redirect user to portal URL
+window.location.href = portalUrl;
 ```
 
-### Get All Data (Convenience Methods)
+### 3. Check Authentication Status
 
 ```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();
-```
-
-### Convenience Filter Methods
+// Check if user is authenticated
+const isAuthenticated = finatic.isAuthed();
 
-```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');
+// Get current user ID
+const userId = finatic.getUserId();
 ```
 
-## Trading Operations
+### 4. Fetch Data
 
-### General Order Placement
+Once authenticated, you can fetch broker data:
 
 ```typescript
-// Place a market order
-const orderResponse = await finatic.placeOrder({
-  symbol: 'AAPL',
-  side: 'buy',
-  quantity: 10,
-  orderType: 'market',
-  timeInForce: 'day',
-});
+// Get all orders (automatically paginates through all pages)
+const allOrders = await finatic.getAllOrders();
 
-// Place a limit order
-const limitOrderResponse = await finatic.placeOrder({
-  symbol: 'AAPL',
-  side: 'buy',
-  quantity: 10,
-  orderType: 'limit',
-  price: 150.0,
-  timeInForce: 'gtc',
+// Get orders with filters (single page)
+const orders = await finatic.getOrders({
+  brokerId: 'alpaca',
+  accountId: '123456789',
+  orderStatus: 'filled',
+  limit: 100,
+  offset: 0,
 });
-```
 
-### Asset-Specific Order Methods
+// Get all positions
+const allPositions = await finatic.getAllPositions();
 
-#### Stock Orders
+// Get positions with filters
+const positions = await finatic.getPositions({
+  brokerId: 'alpaca',
+  symbol: 'AAPL',
+  limit: 50,
+});
 
-```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'
-);
+// Get all accounts
+const allAccounts = await finatic.getAllAccounts();
 
-// Stock stop order
-const response = await finatic.placeStockStopOrder(
-  'AAPL',
-  10,
-  'sell',
-  140.0,
-  'gtc',
-  'robinhood',
-  '123456789'
-);
+// Get balances
+const balances = await finatic.getBalances({
+  brokerId: 'alpaca',
+  accountId: '123456789',
+});
 ```
 
-#### Crypto Orders
+## Complete Example
 
 ```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'
-);
-```
-
-#### Options Orders
+import { FinaticConnect } from '@finatic/client';
 
-```typescript
-// Options market order
-const response = await finatic.placeOptionsMarketOrder(
-  'AAPL240315C00150000',
-  1,
-  'buy',
-  'tasty_trade',
-  '123456789'
-);
+async function setupFinatic() {
+  // 1. Initialize SDK (get token from your backend)
+  const token = await fetch('/api/finatic/token').then((r) => r.text());
+  const finatic = await FinaticConnect.init(token);
+
+  // 2. Open portal for authentication
+  await finatic.openPortal(
+    'dark',
+    undefined, // Show all brokers
+    undefined, // No pre-filled email
+    'modal',
+    async (userId) => {
+      console.log('User authenticated:', userId);
+
+      // 3. Fetch data after authentication
+      const orders = await finatic.getAllOrders();
+      const positions = await finatic.getAllPositions();
+      const accounts = await finatic.getAllAccounts();
+
+      console.log('Orders:', orders);
+      console.log('Positions:', positions);
+      console.log('Accounts:', accounts);
+    },
+    (error) => {
+      console.error('Authentication failed:', error);
+    }
+  );
+}
 
-// Options limit order
-const response = await finatic.placeOptionsLimitOrder(
-  'AAPL240315C00150000',
-  1,
-  'buy',
-  5.0,
-  'gtc',
-  'tasty_trade',
-  '123456789'
-);
+setupFinatic();
 ```
 
-#### Futures Orders
+## Available Data Methods
 
-```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'
-);
-```
+### Orders
 
-### Order Management
+- `getOrders(params?)` - Get single page of orders
+- `getAllOrders(params?)` - Get all orders (auto-paginated)
+- `getOrderFills({ orderId, ... })` - Get fills for a specific order
+- `getAllOrderFills({ orderId, ... })` - Get all fills (auto-paginated)
+- `getOrderEvents({ orderId, ... })` - Get events for a specific order
+- `getAllOrderEvents({ orderId, ... })` - Get all events (auto-paginated)
+- `getOrderGroups(params?)` - Get order groups
+- `getAllOrderGroups(params?)` - Get all order groups (auto-paginated)
 
-```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'
-);
-```
+### Positions
 
-## Broker Information
+- `getPositions(params?)` - Get single page of positions
+- `getAllPositions(params?)` - Get all positions (auto-paginated)
+- `getPositionLots(params?)` - Get position lots
+- `getAllPositionLots(params?)` - Get all position lots (auto-paginated)
+- `getPositionLotFills({ lotId, ... })` - Get fills for a specific lot
+- `getAllPositionLotFills({ lotId, ... })` - Get all fills (auto-paginated)
 
-```typescript
-// Get list of supported brokers
-const brokers = await finatic.getBrokerList();
+### Accounts & Balances
 
-// Get broker connections
-const connections = await finatic.getBrokerConnections();
+- `getAccounts(params?)` - Get single page of accounts
+- `getAllAccounts(params?)` - Get all accounts (auto-paginated)
+- `getBalances(params?)` - Get balances
+- `getAllBalances(params?)` - Get all balances (auto-paginated)
 
-// Disconnect a company from a broker connection
-const disconnectResponse = await finatic.disconnectCompany('connection-uuid-here');
-console.log('Disconnect action:', disconnectResponse.response_data.action);
-```
+### Broker Management
 
-## Authentication
+- `getBrokers()` - Get available brokers
+- `getBrokerConnections()` - Get connected broker accounts
+- `disconnectCompanyFromBroker({ connectionId })` - Disconnect a broker
 
-```typescript
-// Check authentication status
-const isAuthenticated = finatic.isAuthed();
-const isAuthenticatedAlt = finatic.is_authenticated();
+### Company
 
-// Get user ID
-const userId = finatic.getUserId();
+- `getCompany({ companyId })` - Get company information
 
-// Set user ID (for returning users)
-finatic.setUserId('user-123');
-```
+## Method Parameters
 
-## Error Handling
+Most data methods accept optional parameters:
 
 ```typescript
-import { AuthenticationError, ApiError, ValidationError } from '@finatic/client';
-
-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);
-  }
+{
+  brokerId?: string;        // Filter by broker (e.g., 'alpaca', 'tradier')
+  connectionId?: string;   // Filter by connection ID
+  accountId?: string;       // Filter by account ID
+  symbol?: string;          // Filter by symbol (e.g., 'AAPL')
+  limit?: number;           // Page size (default: varies by endpoint)
+  offset?: number;          // Pagination offset (default: 0)
+  includeMetadata?: boolean; // Include metadata in response
+  // ... other filters specific to each method
 }
 ```
 
-## Advanced Usage
+## Event Handling
 
-### Custom Filters
+The SDK extends EventEmitter, so you can listen to events:
 
 ```typescript
-// Get orders with custom filters
-const orders = await finatic.getOrders({
-  page: 1,
-  perPage: 50,
-  filter: {
-    status: 'filled',
-    symbol: 'AAPL',
-    broker: 'robinhood',
-  },
+// Listen for portal events
+finatic.on('portal:success', (userId: string) => {
+  console.log('Portal authentication successful:', userId);
 });
-```
-
-### Pagination Navigation
-
-```typescript
-// Get paginated results with navigation
-const ordersPage = await finatic.getOrders({ page: 1, perPage: 100 });
 
-// Navigate through pages
-if (ordersPage.hasNext) {
-  const nextPage = await ordersPage.nextPage();
-}
-
-if (ordersPage.hasPrevious) {
-  const prevPage = await ordersPage.previousPage();
-}
-```
-
-### Session Management
-
-```typescript
-// The SDK automatically manages sessions
-// Sessions are kept alive for 24 hours by default
-// 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,
+finatic.on('portal:error', (error: Error) => {
+  console.error('Portal error:', error);
 });
-```
-
-### 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,
+finatic.on('portal:close', () => {
+  console.log('Portal closed');
 });
 ```
 
-### Getting Order Groups
+## Response Format
 
-Order groups contain multiple related orders:
+All data methods return a `FinaticResponse` object:
 
 ```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,
-});
+{
+  success: {
+    data: T[], // Array of data items
+    // ... other metadata
+  },
+  error?: {
+    message: string;
+    code?: string;
+  },
+  warning?: string[]
+}
 ```
 
-### Getting Position Lots (Tax Lots)
-
-Position lots are used for tax reporting and track when positions were opened/closed:
+Access the data:
 
 ```typescript
-// Get position lots for tax reporting
-const lots = await finatic.getPositionLots({
-  broker_id: 'robinhood',
-  account_id: '123456789',
-  symbol: 'AAPL',
-  limit: 100,
-});
+const result = await finatic.getOrders();
+if (result.success) {
+  const orders = result.success.data;
+  // Use orders...
+} else {
+  console.error('Error:', result.error?.message);
+}
 ```
 
-### Getting Position Lot Fills
-
-Position lot fills show the execution details for each lot:
+## Configuration Options
 
 ```typescript
-// Get fills for a specific position lot
-const lotFills = await finatic.getPositionLotFills('lot-123', {
-  connection_id: 'connection-456',
-  limit: 50,
+const finatic = await FinaticConnect.init(token, userId, {
+  baseUrl: 'https://api.finatic.dev', // API base URL
+  logLevel: 'info', // 'debug' | 'info' | 'warn' | 'error'
+  structuredLogging: false, // Enable structured JSON logging
+  // ... other options
 });
 ```
 
-## Type Definitions
-
-The SDK includes comprehensive TypeScript definitions for all data structures:
-
-- `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
+## Documentation
 
-## Error Types
+Full API documentation is available at [https://finatic.dev/docs](https://finatic.dev/doc).
 
-- `AuthenticationError`: Authentication failures
-- `ApiError`: API request failures
-- `ValidationError`: Invalid request parameters
-- `ConnectionError`: Network connectivity issues
-
-## Browser Support
+## License
 
-- Chrome 80+
-- Firefox 75+
-- Safari 13+
-- Edge 80+
+PROPRIETARY
 
-## Requirements
+## Copyright
 
-- Modern browser with ES2018+ support
-- No external dependencies
+© Copyright 2025 Finatic. All Rights Reserved.
 
-## License
+---
 
-MIT License
+**Finatic** - Fast. Secure. Standardized.