@finatic/client 0.9.1 → 0.9.3

package/README.md

@@ -1,6 +1,6 @@
-# Client
+# Finatic Client SDK
 
-A comprehensive browser SDK for integrating Finatic Client into your web applications. Connect your users to multiple brokerages through a unified, standardized interface.
+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.**
 
@@ -10,80 +10,276 @@ A comprehensive browser SDK for integrating Finatic Client into your web applica
 npm install @finatic/client
 ```
 
-## Quick Start
+Or using yarn:
+
+```bash
+yarn add @finatic/client
+```
+
+## Quick Start (5 Minutes)
+
+### 1. Initialize the SDK
 
 ```typescript
-import { FinaticClient from '@finatic/client';
+import { FinaticConnect } from '@finatic/client';
 
-// TODO: Add example usage
+// 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'
+});
 ```
 
-## Documentation
+**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.
 
-Full documentation is available at [docs.finatic.com](/client/typescript).
+### 2. Open the Portal for Authentication
 
-## Development
+The portal allows users to connect their broker accounts. You can either:
 
-```bash
-# Install dependencies
-npm install
+**Option A: Open portal in iframe (recommended)**
 
-# Build
-npm run build
+```typescript
+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);
+  },
+  (error) => {
+    // Handle authentication error
+    console.error('Portal error:', error);
+  },
+  () => {
+    // Portal was closed
+    console.log('Portal closed');
+  }
+);
+```
+
+**Option B: Get portal URL and redirect**
 
-# Run tests
-npm test
+```typescript
+const portalUrl = await finatic.getPortalUrl(
+  'dark', // Theme
+  ['alpaca'], // Optional: Filter brokers
+  'user@example.com', // Optional: Pre-fill email
+  'dark' // Mode
+);
+
+// Redirect user to portal URL
+window.location.href = portalUrl;
+```
 
-# Lint
-npm run lint
+### 3. Check Authentication Status
 
-# Format
-npm run format
+```typescript
+// Check if user is authenticated
+const isAuthenticated = finatic.isAuthed();
+
+// Get current user ID
+const userId = finatic.getUserId();
 ```
 
-## Quality Checks
+### 4. Fetch Data
 
-Run all quality checks to ensure code quality:
+Once authenticated, you can fetch broker data:
 
-```bash
-# Run all quality checks (format, lint, type check, build)
-npm run quality:check
+```typescript
+// Get all orders (automatically paginates through all pages)
+const allOrders = await finatic.getAllOrders();
+
+// Get orders with filters (single page)
+const orders = await finatic.getOrders({
+  brokerId: 'alpaca',
+  accountId: '123456789',
+  orderStatus: 'filled',
+  limit: 100,
+  offset: 0,
+});
+
+// Get all positions
+const allPositions = await finatic.getAllPositions();
+
+// Get positions with filters
+const positions = await finatic.getPositions({
+  brokerId: 'alpaca',
+  symbol: 'AAPL',
+  limit: 50,
+});
+
+// Get all accounts
+const allAccounts = await finatic.getAllAccounts();
+
+// Get balances
+const balances = await finatic.getBalances({
+  brokerId: 'alpaca',
+  accountId: '123456789',
+});
+```
+
+## Complete Example
 
-# Fix all auto-fixable issues (format, lint) and build
-npm run quality:fix
+```typescript
+import { FinaticConnect } from '@finatic/client';
+
+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);
+    }
+  );
+}
+
+setupFinatic();
 ```
 
-Individual quality checks:
+## Available Data Methods
 
-```bash
-# Format check (without modifying files)
-npm run format:check
-# Format fix (modifies files)
-npm run format:fix
+### Orders
+
+- `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)
+
+### Positions
+
+- `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)
+
+### Accounts & Balances
+
+- `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)
 
-# Lint check
-npm run lint
-# Lint fix (modifies files)
-npm run lint:fix
+### Broker Management
 
-# Type check
-npm run type:check
+- `getBrokers()` - Get available brokers
+- `getBrokerConnections()` - Get connected broker accounts
+- `disconnectCompanyFromBroker({ connectionId })` - Disconnect a broker
 
-# Syntax check (strict linting)
-npm run syntax:check
-# Syntax fix (modifies files)
-npm run syntax:fix
+### Company
 
-# Import check
-npm run import:check
+- `getCompany({ companyId })` - Get company information
 
-# Build check
-npm run build
+## Method Parameters
+
+Most data methods accept optional parameters:
+
+```typescript
+{
+  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
+}
+```
+
+## Event Handling
+
+The SDK extends EventEmitter, so you can listen to events:
+
+```typescript
+// Listen for portal events
+finatic.on('portal:success', (userId: string) => {
+  console.log('Portal authentication successful:', userId);
+});
+
+finatic.on('portal:error', (error: Error) => {
+  console.error('Portal error:', error);
+});
+
+finatic.on('portal:close', () => {
+  console.log('Portal closed');
+});
+```
+
+## Response Format
+
+All data methods return a `FinaticResponse` object:
+
+```typescript
+{
+  success: {
+    data: T[], // Array of data items
+    // ... other metadata
+  },
+  error?: {
+    message: string;
+    code?: string;
+  },
+  warning?: string[]
+}
+```
+
+Access the data:
+
+```typescript
+const result = await finatic.getOrders();
+if (result.success) {
+  const orders = result.success.data;
+  // Use orders...
+} else {
+  console.error('Error:', result.error?.message);
+}
+```
+
+## Configuration Options
+
+```typescript
+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
+});
 ```
 
+## Documentation
+
+Full API documentation is available at [https://finatic.dev/docs](https://finatic.dev/doc).
+
 ## License
 
-MIT License
+PROPRIETARY
 
 ## Copyright