Finatic Client SDK

A comprehensive browser SDK for integrating Finatic Client into your web applications.

Installation

npm install @finatic/client
# or
yarn add @finatic/client

Basic Usage

Simple Initialization

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)

// Pass token and user ID from previous session
const finatic = await FinaticConnect.init('your-one-time-token', 'user-123');

With Custom Configuration

// Pass token, user ID, and custom API URL
const finatic = await FinaticConnect.init('your-one-time-token', 'user-123', {
  baseUrl: 'https://api.finatic.dev'
});

// 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' } });

// Get positions const positionsPage = await finatic.getPositions({ page: 1, perPage: 100 });

// Place orders await finatic.placeOrder({ symbol: 'AAPL', side: 'buy', quantity: 10, type: 'market', timeInForce: 'day' });

// 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

#### `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
await finatic.openPortal({
  theme: { preset: 'corporateBlue' }
});

// Available presets: 'dark', 'light', 'corporateBlue', 'purple', 'green', 'orange'

Using Custom Themes

// 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'
  }
};

await finatic.openPortal({
  theme: { custom: customTheme }
});

Theme Utilities

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);

// Create a custom theme from a preset
const modifiedTheme = createCustomThemeFromPreset('dark', {
  colors: {
    background: {
      primary: '#000000'
    }
  }
});

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?)

Returns all orders across all pages.

• 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.

• brokerId (string): Broker ID

Returns: Promise<BrokerDataOrder[]>

getPositionsByBroker(brokerId)

Returns positions for a specific broker.

• brokerId (string): Broker ID

Returns: Promise<BrokerDataPosition[]>

Broker Information

getBrokerList()

Returns a list of supported brokers.

Returns: Promise<BrokerInfo[]>

getBrokerConnections()

Returns broker connections for the authenticated user.

Returns: Promise<BrokerConnection[]>

Trading

placeOrder(order)

Places a new order.

• 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

cancelOrder(orderId, broker?)

Cancels an existing order.

• orderId (string): Order ID to cancel
• broker (string, optional): Broker name

modifyOrder(orderId, modifications, broker?)

Modifies an existing order.

• orderId (string): Order ID to modify
• modifications (object): Order modifications
• broker (string, optional): Broker name

Authentication

isAuthenticated()

Returns true if the user is authenticated.

isAuthed()

Returns true if the user is fully authenticated (has userId, access token, and refresh token).

getUserId()

Returns the current user ID, or null if not authenticated.

revokeToken()

Revokes the current access token.

Pagination Navigation

The PaginatedResult object returned by paginated methods includes navigation methods:

nextPage()

Returns the next page of results.

Returns: Promise<PaginatedResult | null>

previousPage()

Returns the previous page of results.

Returns: Promise<PaginatedResult | null>

firstPage()

Returns the first page of results.

Returns: Promise<PaginatedResult>

goToPage(pageNumber)

Goes to a specific page.

• pageNumber (number): Page number to navigate to

Returns: Promise<PaginatedResult | null>

Error Handling

The SDK throws specific error types for different scenarios:

import { 
  ApiError, 
  SessionError, 
  AuthenticationError, 
  AuthorizationError,
  RateLimitError,
  CompanyAccessError 
} from '@finatic/client';

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');
  }
}

Browser Support

This SDK is designed for modern browsers and requires:

• ES2020 support
• Fetch API
• Promise support
• LocalStorage (for token caching)

License

MIT