API reference

Everything the package exports.

Node.js
Python

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

from finn_sdk import (
    FinnClient,
    FinnError,
    MessageTurn,
    TokenChunk,
    TurnResult,
    AskResult,
    __version__,
)

`FinnClient`

Node.js
Python

new FinnClient(options: FinnClientOptions)

FinnClient(url, *, api_key=None, get_api_key=None, path="/ws",
           session_id=None, system_prompt=None, reconnection=True,
           timeout_ms=10000)

Methods

Method	Node.js signature	Python signature	Description
connect	`connect() => Promise<void>`	`await connect()`	Open the WebSocket and authenticate. Fails with a `FinnError`.
disconnect	`disconnect() => Promise<void>`	`await disconnect()`	Close the connection.
send message	`sendMessage(text, options?) => MessageTurn`	`await send_message(text, *, conversation_id=None, system_prompt=None) -> MessageTurn`	Send a message; returns a `MessageTurn` to stream from.
ask	`ask(text, options?) => Promise<AskResult>`	`await ask(text, ...) -> AskResult`	Non-streaming: send and resolve once with the full answer text + result.
ask JSON	`askJson<T>(text, options?) => Promise<T>`	`await ask_json(text, ...) -> Any`	Like `ask`, but extracts and parses the answer as JSON. Fails `invalid_json` if it can’t parse. Prompt for JSON yourself.
on	`on(event, handler) => this`	`on(event, handler) -> self`	Subscribe to a lifecycle event: `connected`, `reconnect`, `unauthorized`, `rateLimit`, `disconnect`.

The Python client is also an async context manager — async with FinnClient(...) as finn: connects on enter and disconnects on exit.

Client options

Node.js (`FinnClientOptions`)	Python (kwargs)	Description
`url` (required)	`url`	Backend base URL.
`apiKey`	`api_key`	Static API key.
`getApiKey`	`get_api_key`	Resolve the key at connect time.
`path` (`'/ws'`)	`path`	Socket.IO path.
`sessionId`	`session_id`	Resume a prior session.
`systemPrompt`	`system_prompt`	Client default for new conversations.
`reconnection` (`true`)	`reconnection`	Auto-reconnect.
`timeoutMs` (`10000`)	`timeout_ms`	Connect timeout (ms).

See Connecting & auth for details on each option.

Send options

Continue a conversation or override the system prompt when sending a message.

Node.js (`SendMessageOptions`)	Python (kwargs)	Description
`conversationId`	`conversation_id`	Continue an existing conversation.
`systemPrompt`	`system_prompt`	Per-conversation override (new conversations only).

`MessageTurn`

The return value of sendMessage() / send_message(). It’s an async-iterable of token chunks, plus:

Node.js
Python

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
}

class MessageTurn:                 # async-iterable of TokenChunk
    conversation_id: Awaitable[str]   # await it: resolves once the conversation exists
    completed: Awaitable[TurnResult]  # await it: resolves when the turn finishes
    def interrupt(self) -> None: ...  # ask the backend to stop this turn

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

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

@dataclass
class TokenChunk:
    text: str               # a piece of the streamed answer
    message_id: str
    conversation_id: str

`TurnResult`

Node.js
Python

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

@dataclass
class TurnResult:
    conversation_id: str
    interrupted: bool = False   # True if interrupt() ended the turn
    message_id: str | None = None
    token_usage: dict | None = None   # {'input': int, 'output': int, 'total': int}
    turn_state: str | None = None

`AskResult`

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

`FinnError`

Node.js
Python

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

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

class FinnError(Exception):
    code: str      # one of the codes below
    message: str
    conversation_id: str | None
    details: object | None

# codes: "unauthorized" | "rate_limited" | "timeout"
#      | "conversation_read_only" | "stream_error"
#      | "disconnected" | "invalid_json"

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

VERSION (Node.js) / __version__ (Python) — the SDK package version string, e.g. '0.1.0'.