Connecting & auth

Creating a client

import { FinnClient } from '@riseanalytics/finn-sdk';

const finn = new FinnClient({
  url: 'https://finn.example.com',
  apiKey: process.env.FINN_API_KEY,
});

Constructing a client does not open a connection — it just holds config. Call connect() when you’re ready:

await finn.connect(); // opens the WebSocket and authenticates
// ... use the client ...
await finn.disconnect(); // closes it

Options

Everything except url is optional.

Option	Type	Default	Description
`url`	`string`	—	Required. Base URL of the Finn backend, e.g. `https://finn.example.com` or `wss://…`.
`apiKey`	`string`	—	Static API key, sent as the WebSocket handshake auth token.
`getApiKey`	`() => string \| Promise<string>`	—	Alternative to `apiKey`: resolve the key at connect time (e.g. for rotation).
`path`	`string`	`'/ws'`	Socket.IO path on the backend.
`sessionId`	`string`	—	Resume a prior session.
`systemPrompt`	`string`	—	Client-level system-prompt default applied to new conversations. See System prompts.
`reconnection`	`boolean`	`true`	Auto-reconnect on a dropped socket.
`timeoutMs`	`number`	`10000`	Connect timeout in milliseconds.

Authentication

Finn uses a single static API key. Provide it either directly or lazily:

// Direct
const finn = new FinnClient({ url, apiKey: 'your-key' });

// Resolved at connect time — handy for rotating secrets
const finn = new FinnClient({
  url,
  getApiKey: async () => await vault.read('finn/api-key'),
});

If the key is missing or rejected, connect() rejects with a FinnError whose code is 'unauthorized', and the client emits an unauthorized event.

Lifecycle events

Subscribe with on(event, handler):

finn.on('unauthorized', () => console.error('API key rejected'));
finn.on('rateLimit', (info) => console.warn('rate limited', info));
finn.on('disconnect', (reason) => console.warn('disconnected:', reason));

Event	Payload	Fires when
`unauthorized`	—	The API key is missing or rejected.
`rateLimit`	`RateLimitInfo`	The backend signals a rate limit.
`disconnect`	`reason: string`	The socket drops (auto-reconnect may follow if enabled).