@finatic/client 0.9.1 → 0.9.2

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
 

package/dist/index.d.ts

@@ -1,7 +1,6 @@
 import * as axios from 'axios';
 import { AxiosInstance, RawAxiosRequestConfig, AxiosPromise, AxiosRequestConfig, AxiosResponse } from 'axios';
 import * as z from 'zod';
-import NodeCache from 'node-cache';
 
 /**
  * Finatic FastAPI Backend
@@ -4375,12 +4374,11 @@ declare const defaultConfig: SdkConfig;
 declare function getConfig(overrides?: Partial<SdkConfig>): SdkConfig;
 
 /**
- * Structured logger utility with browser-safe fallback (Phase 2C).
+ * Structured logger utility with browser-safe console logging (Phase 2C).
  *
  * Generated - do not edit directly.
  *
- * This logger automatically falls back to console-based logging when pino fails
- * in browser environments (Vite, Next.js, etc.).
+ * This logger uses browser console APIs for all logging in browser environments.
  */
 
 type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
@@ -5700,15 +5698,23 @@ declare function numberSchema(min?: number, max?: number, defaultVal?: number):
 declare function stringSchema(min?: number, max?: number, defaultVal?: string): z.ZodString;
 
 /**
- * Response caching utility with node-cache (Phase 2B).
+ * Response caching utility with browser-compatible Map-based cache (Phase 2B).
  *
  * Generated - do not edit directly.
  */
 
+interface BrowserCache {
+    get(key: string): any | undefined;
+    set(key: string, value: any, ttl?: number): boolean;
+    del(key: string): number;
+    clear(): void;
+    keys(): string[];
+    has(key: string): boolean;
+}
 /**
  * Get or create cache instance.
  */
-declare function getCache(config?: SdkConfig): NodeCache | null;
+declare function getCache(config?: SdkConfig): BrowserCache | null;
 /**
  * Generate cache key from method and parameters.
  */

package/dist/index.js

@@ -1,8 +1,6 @@
 'use strict';
 
 var pRetry = require('p-retry');
-var pino = require('pino');
-var NodeCache = require('node-cache');
 var z = require('zod');
 var globalAxios = require('axios');
 
@@ -93,14 +91,12 @@ async function retryApiCall(fn, options = {}, config) {
 }
 
 /**
- * Structured logger utility with browser-safe fallback (Phase 2C).
+ * Structured logger utility with browser-safe console logging (Phase 2C).
  *
  * Generated - do not edit directly.
  *
- * This logger automatically falls back to console-based logging when pino fails
- * in browser environments (Vite, Next.js, etc.).
+ * This logger uses browser console APIs for all logging in browser environments.
  */
-// @ts-ignore - pino types available via @types/pino
 let _loggerInstance = null;
 /**
  * Get environment variable from various sources (browser and Node.js).
@@ -145,30 +141,6 @@ function isProduction() {
         return true;
     return false;
 }
-/**
- * Detect if we're in a browser environment.
- */
-function isBrowser() {
-    // Check for window object (browser)
-    if (typeof window !== 'undefined') {
-        return true;
-    }
-    // Check for globalThis in browser-like environments
-    if (typeof globalThis !== 'undefined') {
-        // In browsers, process might be polyfilled but process.stdout won't exist
-        try {
-            const proc = globalThis.process;
-            if (proc && typeof proc.stdout === 'undefined') {
-                return true;
-            }
-        }
-        catch {
-            // If we can't check, assume browser if window exists
-            return typeof window !== 'undefined';
-        }
-    }
-    return false;
-}
 /**
  * Get or create a logger instance with browser-safe fallback.
  */
@@ -176,36 +148,13 @@ function getLogger(config) {
     if (_loggerInstance) {
         return _loggerInstance;
     }
-    // In browser environments, skip pino entirely and use browser-safe logger
-    if (isBrowser()) {
-        return getBrowserSafeLogger(config);
-    }
-    // Try to use pino first (Node.js environments)
-    try {
-        const logLevel = (config?.logLevel || getEnvVar('FINATIC_LOG_LEVEL') || 'error');
-        const pinoConfig = {
-            level: logLevel === 'silent' ? 'silent' : logLevel,
-            ...(config?.structuredLogging !== false && {
-                formatters: {
-                    level: (label) => {
-                        return { level: label };
-                    },
-                },
-                timestamp: true,
-            }),
-        };
-        _loggerInstance = pino(pinoConfig);
-        return _loggerInstance;
-    }
-    catch (error) {
-        // Fallback to browser-safe logger if pino fails
-        return getBrowserSafeLogger(config, error);
-    }
+    // Client SDK always uses browser-safe logger (no pino)
+    return getBrowserSafeLogger(config);
 }
 /**
- * Browser-safe logger fallback for environments where pino fails.
+ * Browser-safe logger for Client SDK.
  */
-function getBrowserSafeLogger(config, pinoError) {
+function getBrowserSafeLogger(config) {
     // Log level hierarchy (matching pino's numeric levels)
     const LOG_LEVELS = {
         silent: 0,
@@ -236,7 +185,7 @@ function getBrowserSafeLogger(config, pinoError) {
     };
     const logLevel = getEffectiveLogLevel();
     const structuredLogging = config?.structuredLogging ?? false;
-    const isProd = isProduction();
+    isProduction();
     /**
      * Check if we should log at this level.
      */
@@ -369,10 +318,6 @@ function getBrowserSafeLogger(config, pinoError) {
             }
         },
     };
-    // Only warn about fallback logger if pino failed (not if we're in browser)
-    if (pinoError && !isProd) {
-        console.warn('[Finatic SDK] Using fallback logger due to pino initialization error:', pinoError);
-    }
     _loggerInstance = fallbackLogger;
     return _loggerInstance;
 }
@@ -440,11 +385,96 @@ function handleError(error, requestId) {
 }
 
 /**
- * Response caching utility with node-cache (Phase 2B).
+ * Response caching utility with browser-compatible Map-based cache (Phase 2B).
  *
  * Generated - do not edit directly.
  */
-// @ts-ignore - node-cache types available via @types/node-cache
+class MapBasedCache {
+    constructor(maxSize = 1000, defaultTtl = 300) {
+        this.cleanupInterval = null;
+        this.cache = new Map();
+        this.maxSize = maxSize;
+        this.defaultTtl = defaultTtl;
+        this.startCleanup();
+    }
+    startCleanup() {
+        // Clean up expired entries every minute
+        if (typeof window !== 'undefined') {
+            this.cleanupInterval = window.setInterval(() => {
+                this.cleanup();
+            }, 60000);
+        }
+    }
+    cleanup() {
+        const now = Date.now();
+        const keysToDelete = [];
+        for (const [key, entry] of this.cache.entries()) {
+            if (entry.expires < now) {
+                keysToDelete.push(key);
+            }
+        }
+        keysToDelete.forEach(key => this.cache.delete(key));
+    }
+    evictLRU() {
+        if (this.cache.size < this.maxSize) {
+            return;
+        }
+        // Simple LRU: remove oldest entry (first in Map)
+        const firstKey = this.cache.keys().next().value;
+        if (firstKey) {
+            this.cache.delete(firstKey);
+        }
+    }
+    get(key) {
+        const entry = this.cache.get(key);
+        if (!entry) {
+            return undefined;
+        }
+        // Check if expired
+        if (entry.expires < Date.now()) {
+            this.cache.delete(key);
+            return undefined;
+        }
+        return entry.value;
+    }
+    set(key, value, ttl) {
+        // Evict if at max size
+        if (this.cache.size >= this.maxSize && !this.cache.has(key)) {
+            this.evictLRU();
+        }
+        const expires = Date.now() + (ttl || this.defaultTtl) * 1000;
+        this.cache.set(key, { value, expires });
+        return true;
+    }
+    del(key) {
+        return this.cache.delete(key) ? 1 : 0;
+    }
+    clear() {
+        this.cache.clear();
+    }
+    keys() {
+        return Array.from(this.cache.keys());
+    }
+    has(key) {
+        const entry = this.cache.get(key);
+        if (!entry) {
+            return false;
+        }
+        // Check if expired
+        if (entry.expires < Date.now()) {
+            this.cache.delete(key);
+            return false;
+        }
+        return true;
+    }
+    destroy() {
+        if (this.cleanupInterval !== null && typeof window !== 'undefined') {
+            window.clearInterval(this.cleanupInterval);
+            this.cleanupInterval = null;
+        }
+        this.cache.clear();
+    }
+}
 let _cacheInstance = null;
 /**
  * Get or create cache instance.
@@ -456,11 +486,7 @@ function getCache(config) {
     if (_cacheInstance) {
         return _cacheInstance;
     }
-    _cacheInstance = new NodeCache({
-        stdTTL: config.cacheTtl || 300,
-        maxKeys: config.cacheMaxSize || 1000,
-        useClones: false,
-    });
+    _cacheInstance = new MapBasedCache(config.cacheMaxSize || 1000, config.cacheTtl || 300);
     return _cacheInstance;
 }
 /**