API reference

Everything the package exports, from @riseanalytics/finn-sdk.

import { FinnClient, FinnError, VERSION } from '@riseanalytics/finn-sdk';
import type {
  FinnClientOptions,
  SendMessageOptions,
  MessageTurn,
  TokenChunk,
  TurnResult,
  AskResult,
  RateLimitInfo,
  FinnErrorCode,
} from '@riseanalytics/finn-sdk';

FinnClient

new FinnClient(options: FinnClientOptions)

Methods

Method	Signature	Description
connect	() => Promise<void>	Open the WebSocket and authenticate. Rejects with a FinnError on failure.
disconnect	() => Promise<void>	Close the connection.
sendMessage	(text: string, options?: SendMessageOptions) => MessageTurn	Send a message; returns a MessageTurn to stream from.
ask	(text: string, options?: SendMessageOptions) => Promise<AskResult>	Non-streaming: send a message and resolve once with the full answer text + result.
askJson	<T>(text: string, options?: SendMessageOptions) => Promise<T>	Like ask, but extracts and JSON.parses the answer. Rejects invalid_json if it can’t parse. Prompt for JSON yourself.
on	(event, handler) => void	Subscribe to a lifecycle event: unauthorized, rateLimit, disconnect.

FinnClientOptions

interface FinnClientOptions {
  url: string;                                   // required — backend base URL
  apiKey?: string;                               // static API key
  getApiKey?: () => string | Promise<string>;    // resolve the key at connect time
  path?: string;                                 // Socket.IO path. Default '/ws'
  sessionId?: string;                            // resume a prior session
  systemPrompt?: string;                         // client default for new conversations
  reconnection?: boolean;                        // auto-reconnect. Default true
  timeoutMs?: number;                            // connect timeout (ms). Default 10000
}

See Connecting & auth for details on each option.

SendMessageOptions

interface SendMessageOptions {
  conversationId?: string;   // continue an existing conversation
  systemPrompt?: string;     // per-conversation override (new conversations only)
}

MessageTurn

The return value of sendMessage(). It’s an AsyncIterable<TokenChunk>, plus:

interface MessageTurn extends AsyncIterable<TokenChunk> {
  readonly conversationId: Promise<string>;   // resolves once the conversation exists
  readonly completed: Promise<TurnResult>;    // resolves when the turn finishes
  interrupt(): void;                          // ask the backend to stop this turn
}

completed rejects with a FinnError if the turn fails. See Sending messages & streaming.

TokenChunk

interface TokenChunk {
  text: string;            // a piece of the streamed answer
  messageId: string;
  conversationId: string;
}

TurnResult

interface TurnResult {
  conversationId: string;
  messageId?: string;
  tokenUsage?: { input: number; output: number; total: number };
  turnState?: string;
  interrupted: boolean;    // true if interrupt() ended the turn
}

AskResult

Returned by ask() — a TurnResult plus the complete answer text.

interface AskResult extends TurnResult {
  text: string;            // the full answer, every token concatenated
}

FinnError

class FinnError extends Error {
  code: FinnErrorCode;
  conversationId?: string;
  details?: unknown;
}

type FinnErrorCode =
  | 'unauthorized'
  | 'rate_limited'
  | 'timeout'
  | 'conversation_read_only'
  | 'stream_error'
  | 'disconnected';

See Error handling for what each code means.

RateLimitInfo

The payload of the rateLimit event — a free-form object of backend-provided rate-limit metadata.

VERSION

const VERSION: string; // the SDK package version, e.g. '0.1.0'