Dart (Flutter) API

Generated from the source and its doc comments (sdk/client-flutter/lib/agentim_client.dart).

dart pub add agentim_client

`ClientOptions`

class ClientOptions

How the client starts: the server address, this device’s id, the cache, the token provider and how it names itself.

`TokenRefused`

class TokenRefused implements Exception

Thrown by a token provider when the backend refuses the user.

`AgentIMError`

class AgentIMError implements Exception

The server’s code (forbidden, not_found, conflict, bad_request, blocked, rate_limited…) or the client’s (disconnected, timeout, closed…); unknown codes pass through as they are.

`AgentIMError.toString`

String toString()

code: message.

`Observed`

class Observed<T>

A value the UI follows: [value] stays the same object until it changes.

`Observed.value`

T get value

The current value.

`Observed.watch`

Stream<T> watch() async*

The current value, then every change.

`Connection`

class Connection

The connection state and why: state is closed, connecting, connected, disconnected, suspended or failed.

`Messages`

class Messages

One conversation’s messages as shown, oldest first; each has key, content, status (sent, sending, failed), state, sender_type…

`Messages.olderEnd`

String? olderEnd;

Why nothing older can be loaded: start (the beginning) or retention (deleted by the retention period).

`Messages.debugApplyEvent`

void debugApplyEvent(Map<String, dynamic> e)

Applies a messages event as the client does, for tests.

`Messages.loadOlder`

Future<bool> loadOlder()

The page before the oldest shown: the cache first, then the server. False at the start.

`Messages.jumpTo`

Future<void> jumpTo(int seq)

A page around a message (it stays loaded).

`AgentIMClient`

class AgentIMClient

The AgentIM client for one account on one device: keeps the connection, syncs, sends the offline queue in order, keeps the local cache, and turns everything into observable state.

`AgentIMClient.version`

static String version()

The version of the native core.

`AgentIMClient.create`

static AgentIMClient create(ClientOptions o)

Starts a client with its options: the server address, this device’s id, the token provider and the cache. Nothing connects until connect.

`AgentIMClient.command`

Future<Object?> command(Map<String, Object?> cmd)

Any core command ({'cmd': …}); completes with its result.

`AgentIMClient.setNetwork`

void setNetwork(bool online)

The platform’s network: call on every change (connectivity_plus).

`AgentIMClient.setForeground`

void setForeground(bool foreground)

The app came to the foreground or went to the background (AppLifecycleListener).

`AgentIMClient.messages`

Messages messages(String convId)

The conversation’s messages, kept up to date.

`AgentIMClient.connect`

Future<void> connect()

Connects and keeps connecting: reconnects with backoff when the network or the server goes, syncs what it missed, sends the offline queue.

`AgentIMClient.disconnect`

Future<void> disconnect()

Closes the connection (the client stays usable; [dispose] frees it).

`AgentIMClient.logout`

Future<void> logout()

Logs out here: closes and wipes the cache and the queue (GDPR).

`AgentIMClient.sendFile`

Future<Map<String, dynamic>> sendFile(

Returns {client_msg_id, key} once the message is queued and shown. Sends a file or a photo from a path: shown at once as uploading, sent when it is up. A photo loses its EXIF and GPS (unless [keepMetadata]) and gets a 320-pixel thumbnail (docs/en/design/messaging.md).

`AgentIMClient.fileUrl`

Future<Map<String, dynamic>> fileUrl(String convId, String fileId, {String variant = 'original'}) async

A link (valid a few minutes) to read a file: original or thumb.

`AgentIMClient.send`

Future<Map<String, dynamic>> send(String convId, String text, {String? clientMsgId, String? replyTo, String? threadId, bool alsoInConv = false}) async

Sends a text, optionally as a reply: shown at once as sending, sent when the connection allows, in order. Returns the client_msg_id and the local key; a retry with the same client_msg_id is the same message.

`AgentIMClient.edit`

Future<void> edit(String convId, String msgId, String text)

Edits one of my messages (by msgId, or by clientMsgId while it is still queued); the change shows at once.

`AgentIMClient.recall`

Future<void> recall(String convId, String msgId)

Recalls one of my messages for everyone; a message still in the queue is simply not sent.

`AgentIMClient.read`

Future<void> read(String convId, {int? seq})

Marks the conversation read up to seq (default: the newest) on all my devices.

`AgentIMClient.retry`

Future<void> retry(String convId, String clientMsgId)

Sends a failed message again (the same client_msg_id, so it is never doubled).

`AgentIMClient.discard`

Future<void> discard(String convId, String clientMsgId)

Drops a failed or waiting message from the queue.

`AgentIMClient.react`

Future<Object?> react(String convId, String msgId, String key)

Adds a reaction (one emoji, or one of the app’s :names:); adding it twice changes nothing.

`AgentIMClient.unreact`

Future<Object?> unreact(String convId, String msgId, String key)

Removes my reaction; removing one that is not there changes nothing.

`AgentIMClient.pin`

Future<Object?> pin(String convId, String msgId)

Pins a message to the conversation; pinning it again changes nothing.

`AgentIMClient.unpin`

Future<Object?> unpin(String convId, String msgId)

Unpins a message.

`AgentIMClient.listPins`

Future<Object?> listPins(String convId)

The conversation’s pinned messages, latest pin first.

`AgentIMClient.pullThread`

Future<Object?> pullThread(String convId, String threadId, {int afterSeq = 0})

A thread’s root and its replies after afterSeq.

`AgentIMClient.listThreads`

Future<Object?> listThreads({String? convId})

The threads I follow (in one conversation, or all), latest reply first, with unread counts.

`AgentIMClient.readThread`

Future<Object?> readThread(String convId, String threadId, int seq)

Marks a thread read up to seq on all my devices.

`AgentIMClient.followThread`

Future<Object?> followThread(String convId, String threadId, {bool follow = true})

Follows a thread (its replies notify me) or stops following it.

`AgentIMClient.msgSummary`

Future<Object?> msgSummary(String convId, List<String> msgIds)

The thread summary, reactions and pin of up to 100 messages (for messages loaded from history).

`AgentIMClient.call`

Future<Object?> call(String op, [Map<String, Object?> args = const {}])

A request that needs the server now (approvals, decisions, queries).

`AgentIMClient.debugState`

Future<Object?> debugState()

Everything that helps report a problem: the connection, positions, the queue and recent failures.

`AgentIMClient.dispose`

void dispose()

Stops the client; no event is handled after it returns. Waiting calls fail with closed.