KletsoClient class final

The Kletso client: one per app (through Kletso.init) or one per test.

Owns the session, the realtime KletsoConnection, the per-conversation state and the public observables. Everything is exposed as KletsoValueListenables and one broadcast events stream so hosts can wrap it in whatever state library they use.

Constructors

KletsoClient(KletsoConfig config, {KletsoApi? api, KletsoTransport? transport, Client? httpClient, Random? random, KletsoLogger? logger, KletsoDevice? device, KletsoTokenStore? tokenStore})
Creates a client. All dependencies are injectable: api and transport for fakes, httpClient for MockClient (used only when api or transport are not supplied), random for deterministic ids and backoff, logger for log capture, tokenStore to persist the anonymous visitor id.

Properties

activeAgentId → String
The agent used for new conversations.
no setter
activeConversation → KletsoValueListenable<KletsoConversation?>
The conversation messages shows, or null before the first one.
no setter
agentTyping → KletsoValueListenable<bool>
Whether the agent is composing (from agent.typing, with a TTL).
no setter
config → KletsoConfig
The configuration this client was created with.
final
connection → KletsoValueListenable<KletsoConnectionState>
Realtime connection state.
no setter
context → Map<String, Object?>
Read-only view of the runtime context.
no setter
conversations → KletsoValueListenable<List<KletsoConversation>>
The end user's conversations, most recent first.
no setter
events → Stream<KletsoEvent>
Every protocol and client event. Broadcast; late listeners miss earlier events, use the value listenables for state.
no setter
hashCode → int
The hash code for this object.
no setterinherited
isAuthenticated → bool
Whether a session exists.
no setter
messages → KletsoValueListenable<List<KletsoMessage>>
Messages of the active conversation, oldest first.
no setter
notifications → Stream<KletsoNotification>
Proactive app.notify notifications, deduped on notificationId, whether they arrived live or through handlePushPayload. The Flutter layer's KletsoNotificationHost renders them; hosts may listen too.
no setter
pushToken → KletsoPushToken?
The push token registered for this session, if any.
no setter
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
session → KletsoValueListenable<KletsoSessionBootstrap?>
Session bootstrap (agent info, theme, allowlists); null until authenticate or identifyAnonymous succeeded.
no setter
voice → KletsoVoiceController
Voice sessions on the active conversation (D78). Install the platform audio with KletsoVoice.install(client) from package:kletso_voice; check voice.available before showing a microphone button.
no setter

Methods

authenticate({required String token, KletsoUserTokenRefresher? onTokenExpired}) → Future<void>
Creates a session for the end user identified by the host-signed token. onTokenExpired is asked for a fresh token when the runtime rejects the old one. Throws KletsoAuthException when the key or token is rejected.
dispose() → Future<void>
Releases every resource. The client is unusable afterwards.
ensureConversation() → Future<KletsoConversation>
Returns the active conversation, reusing the most recent one or starting a new one when there is none.
handlePushPayload(Map<Object?, Object?> message) → bool
Feeds a push message's data map (FCM RemoteMessage.data, APNs userInfo, Web Push payload) into the client. The runtime puts a full kletso.events/v1 envelope under the kletso key, as a JSON string or a map. Returns true when it was a Kletso notification that had not been seen yet; anything else is ignored so hosts can call this for every push they receive.
identifyAnonymous() → Future<void>
Creates an anonymous session. The visitor id is persisted through the KletsoTokenStore so a returning visitor keeps their conversations.
listConversations() → Future<List<KletsoConversation>>
Fetches the end user's conversations and updates conversations.
logout() → Future<void>
Ends the session on the runtime and clears every trace of the user on the device (conversations, messages, context, visitor id).
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
pause() → Future<void>
Closes the socket without forgetting anything (app went to background).
registerPushToken(KletsoPushToken token) → Future<void>
Registers the device's push token so the runtime can deliver app.notify events while the app is in the background. Call it after authenticating and again whenever the host's push plugin rotates the token. The SDK bundles no push plugin (D57).
reportLocalAction({required String name, required JsonMap args, required String surfaceId, required String componentId, required String actionId, required bool handled}) → void
Reports that a local action ran on the device. Emits KletsoLocalActionRan and, when config.reportLocalActions is on, tells the runtime for analytics.
reportUnknownComponent({required String type, required String surfaceId}) → void
Reports a component type that nothing could render.
resume() → Future<void>
Reconnects after pause.
screen(String name) → void
Fires a screen trigger.
send(KletsoOutbound outbound) → Future<void>
Sends outbound on the active conversation (starting one if needed). Completes once the frame is queued; delivery and the reply arrive as events. Throws KletsoStateException without a session.
setContext(Map<String, Object?> context) → void
Replaces the runtime context.
startConversation({String? title}) → Future<KletsoConversation>
Creates a conversation with the active agent and makes it active.
switchConversation(String conversationId) → Future<void>
Makes conversationId active; its state is restored instantly when it was seen before, otherwise replayed from the runtime.
toString() → String
A string representation of this object.
inherited
track(String name, [Map<String, Object?> properties = const <String, Object?>{}]) → void
Fires an event trigger.
unregisterPushToken() → Future<void>
Removes the registered push token (log out, opt out).
updateContext(Map<String, Object?> changes) → void
Merges changes into the runtime context.
useAgent(String agentId) → void
Uses agentId for conversations started from now on.

Operators

operator ==(Object other) → bool
The equality operator.
inherited