State, streams and errors
The listenables and streams on KletsoClient, sending structured values, conversations, and the exception hierarchy.
Listenables
| Member | Type | Meaning |
|---|---|---|
connection | KletsoValueListenable<KletsoConnectionState> | closed, connecting, open, reconnecting |
session | KletsoValueListenable<KletsoSessionBootstrap?> | Session, end user, agent info, theme, URL allowlist |
messages | KletsoValueListenable<List<KletsoMessage>> | Active conversation, oldest first, including pending echoes and surfaces |
conversations | KletsoValueListenable<List<KletsoConversation>> | Most recent first |
activeConversation | KletsoValueListenable<KletsoConversation?> | |
agentTyping | KletsoValueListenable<bool> | True while deltas arrive, with a TTL |
context | Map<String, Object?> | Current context (read-only view) |
Use .asFlutter() (from kletso_flutter) to get a ValueListenable for ValueListenableBuilder.
Streams
events: everyKletsoEvent:KletsoServerEvent(envelope),KletsoConnectionChanged,KletsoClientError,KletsoUnknownComponent,KletsoLocalActionRan.notifications:KletsoNotification(payload, conversation, sourceliveorpush), deduplicated.ui.commandResults,ui.notificationResults: outcomes of server commands and notifications.
Conversations
await client.startConversation(title: 'Support');
await client.switchConversation(id);
final list = await client.listConversations();
final c = await client.ensureConversation(); // most recent open one, or a new oneSending
await client.send(KletsoOutbound.text('Where is my order?'));
await client.send(KletsoOutbound.value({'intent': 'select_flight', 'flightId': 'NH873'}, label: 'NH873'));KletsoOutbound.action, .form and .confirm exist for widgets; the built-in blocks use them. Every send adds an optimistic echo to messages and is queued if offline. Sending before identifyAnonymous/authenticate throws KletsoStateException.
Exceptions
All extend KletsoException: KletsoNetworkException, KletsoTimeoutException, KletsoAuthException (expired flag), KletsoRateLimitException, KletsoProtocolException, KletsoServerException (code, statusCode, retryable), KletsoToolException, KletsoWorkflowException, KletsoStateException, KletsoQueueOverflowException. Connection-level failures are delivered as KletsoClientError on events rather than thrown into your UI.