Web (@agentimhq/client-web) API

Generated from the source and its doc comments (sdk/client-web/src/client.ts, sdk/client-web/src/view.ts, sdk/client-web/src/store.ts).

npm install @agentimhq/client-web

`ClientOptions`

interface ClientOptions

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

`ClientOptions.url`

url: string

https://chat.example.com.

`ClientOptions.deviceId`

deviceId: string

This device’s id, the same every run (1..64 of A-Z a-z 0-9 _ -).

`ClientOptions.deviceName`

deviceName?: string

A name for this device in the user’s device list, like “Maya’s laptop”.

`ClientOptions.platform`

platform?: string

The platform reported to the server (web, ios, android…), for the device list and push.

`ClientOptions.tokenProvider`

tokenProvider: () => Promise<string>

A client token from your backend; throw TokenRefused to stop.

`ClientOptions.store`

store?: Store | 'indexeddb' | 'memory'

The cache: IndexedDB by default where there is one, else memory.

`ClientOptions.storeName`

storeName?: string

Name of the IndexedDB databases (default agentim-<deviceId>).

`ClientOptions.wasm`

wasm?: WasmSource

The core module (default: agentim_core.wasm next to this file).

`ClientOptions.multiTab`

multiTab?: boolean

Share one connection between tabs (default: where the browser can).

`ClientOptions.WebSocket`

WebSocket?: typeof WebSocket

The WebSocket class to use, for Node and tests; browsers have their own.

`ClientOptions.clientName`

clientName?: string

This app’s name, sent with each connection (for diagnostics and the server’s minimum-version rules).

`ClientOptions.clientVersion`

clientVersion?: string

This app’s version, sent with clientName.

`ClientOptions.log`

log?: (m: string) => void

Receives the client’s diagnostic lines (connections, retries, failures); none by default.

`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.connection`

readonly connection = new Observable<Connection>({ state: 'closed' })

The connection state (closed, connecting, connected, disconnected, suspended, failed) and why; subscribe to follow it.

`AgentIMClient.conversations`

readonly conversations = new Observable<any[]>([])

The conversation list, newest first, kept up to date.

`AgentIMClient.create`

static async create(o: ClientOptions): Promise<AgentIMClient>

Starts a client with its options: the server address, this device’s id, the token provider and the cache. Nothing connects until connect. In a browser the first tab holds the connection; other tabs share it.

`AgentIMClient.command`

async command(cmd: Record<string, unknown>, blobs?: Record<string, Blob>): Promise<any>

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

`AgentIMClient.on`

on(type: string, fn: Listener): () => void

Events: operation, side, signal, reset, storage, event, read, mute.

`AgentIMClient.connect`

connect()

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

`AgentIMClient.close`

close()

Disconnects; the queue and the cache stay. connect again picks up where it stopped.

`AgentIMClient.logout`

logout()

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

`AgentIMClient.dispose`

async dispose()

Stops this tab’s part (the next tab takes over the connection).

`AgentIMClient.messages`

messages(convId: string): Messages

The conversation’s messages, kept up to date while subscribed.

`AgentIMClient.refreshConversations`

async refreshConversations()

Loads the conversation list (it updates by itself afterwards).

`AgentIMClient.sendFile`

async sendFile(convId: string, file: Blob, opts: { name?: string; caption?: string; replyTo?: string; clientMsgId?: string; keepMetadata?: boolean } = {})

Sends a file or an image: shown at once as uploading (with progress), sent when it is up. An image loses its EXIF and GPS (unless keepMetadata) and gets a thumbnail of 320 pixels.

`AgentIMClient.localPreview`

localPreview(key?: string | null): string | undefined

A local address for a file this tab is sending (payload.local_thumb or local_source).

`AgentIMClient.fileUrl`

fileUrl(convId: string, fileId: string, variant: 'original' | 'thumb' = 'original'): Promise<{ url: string; variant: string; expires_at: number }>

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

`AgentIMClient.send`

send(convId: string, text: string, opts: { kind?: string; payload?: unknown; replyTo?: string; clientMsgId?: string; threadId?: string; alsoInConv?: boolean } = {})

Sends a text (or a custom kind with its payload): 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`

edit(convId: string, target: { msgId?: string; clientMsgId?: string }, text: string)

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

`AgentIMClient.recall`

recall(convId: string, target: { msgId?: string; clientMsgId?: string })

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

`AgentIMClient.read`

read(convId: string, seq?: number)

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

`AgentIMClient.feedback`

feedback(convId: string, msgId: string, rating: 'up' | 'down', reason?: string)

Rates an agent’s message up or down, with an optional reason.

`AgentIMClient.react`

react(convId: string, msgId: string, key: string): Promise<{ changed: boolean; seq?: number }>

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

`AgentIMClient.unreact`

unreact(convId: string, msgId: string, key: string): Promise<{ changed: boolean; seq?: number }>

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

`AgentIMClient.listReactions`

listReactions(convId: string, msgId: string, key: string, opts: { afterSeq?: number; limit?: number } = {})

Who reacted to a message with a key, oldest first.

`AgentIMClient.pin`

pin(convId: string, msgId: string): Promise<{ changed: boolean; seq?: number }>

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

`AgentIMClient.unpin`

unpin(convId: string, msgId: string): Promise<{ changed: boolean; seq?: number }>

Unpins a message.

`AgentIMClient.listPins`

listPins(convId: string, opts: { beforeSeq?: number; limit?: number } = {})

The conversation’s pinned messages, latest pin first.

`AgentIMClient.pullThread`

pullThread(convId: string, threadId: string, opts: { afterSeq?: number; limit?: number } = {})

A thread’s root and its replies after afterSeq.

`AgentIMClient.listThreads`

listThreads(opts: { convId?: string; before?: number; limit?: number } = {})

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

`AgentIMClient.readThread`

readThread(convId: string, threadId: string, seq: number)

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

`AgentIMClient.followThread`

followThread(convId: string, threadId: string, follow = true)

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

`AgentIMClient.msgSummary`

msgSummary(convId: string, msgIds: string[])

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

`AgentIMClient.respond`

respond(convId: string, msgId: string, blockId: string, r: { action?: string; values?: Record<string, unknown> })

Answers a card: a button (action) or a filled form (values).

`AgentIMClient.retry`

retry(convId: string, clientMsgId: string)

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

`AgentIMClient.discard`

discard(convId: string, clientMsgId: string)

Drops a failed or waiting message from the queue.

`AgentIMClient.focus`

focus(convId: string | null)

The conversation on screen (or none): its agents’ replies stream in live.

`AgentIMClient.pendingOps`

pendingOps()

What waits in the offline queue.

`AgentIMClient.call`

call(op: string, args: Record<string, unknown> = {})

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

`AgentIMClient.debugState`

debugState()

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

`Commands`

interface Commands

What a view needs from its client.

`Commands.command`

command(cmd: Record<string, unknown>): Promise<any>

Runs one core command and resolves with its answer; the typed methods are built on this.

`TokenRefused`

class TokenRefused

Thrown by a token provider when your backend refuses the user: the client stops instead of retrying.

`AgentIMError`

class AgentIMError

A refused or failed command: code is the error code, retryable whether trying again may work.

`AgentIMError.code`

code: string

The error code: the server’s (forbidden, not_found, conflict, bad_request, …) or the client’s (disconnected, timeout, closed, unauthenticated).

`AgentIMError.retryable`

retryable: boolean

Whether the same request may work later.

`AgentIMError.retryAfterMs`

retryAfterMs?: number

How long the server asked to wait before trying again.

`Observable`

class Observable

A value the UI follows: get() returns the same object until it changes.

`Observable.get`

get = (): T => this.v

The current value (the same object until it changes, for React’s useSyncExternalStore).

`Observable.subscribe`

subscribe = (fn: (v: T) => void): (() => void) =>

Calls fn on every change; returns the function that stops it.

`Observable.set`

set(v: T)

Replaces the value and tells the subscribers.

`Connection`

interface Connection

The connection state and why.

`Connection.state`

state: 'closed' | 'connecting' | 'connected' | 'disconnected' | 'suspended' | 'failed'

closed (not started or closed), connecting, connected, disconnected (waiting to reconnect), suspended (offline, or down for a long time: retries less often) or failed (stopped: the token was refused or the account deactivated).

`Connection.reason`

reason?: string | null

Why it is not connected (an error code), when it is not.

`Connection.retryAt`

retryAt?: number | null

When the next reconnect attempt is due (Unix ms), while waiting to reconnect.

`Message`

interface Message

One message as shown in a list.

`Message.key`

key: string

The list identity: local:<client_msg_id> for a message sent from this device until the server’s copy replaces it (in one change), then its msg_id.

`Message.msg_id`

msg_id: string

The server’s id (local:<client_msg_id> until the server has it).

`Message.mine`

mine?: boolean

Whether I sent it (from any of my devices).

`Message.client_msg_id`

client_msg_id?: string

The id this device gave the message, for retries.

`Message.conv_id`

conv_id: string

The conversation it belongs to.

`Message.content`

content: string

The text (for a streaming reply, what has arrived so far).

`Message.status`

status: 'sent' | 'sending' | 'uploading' | 'failed'

sent, sending (queued or on its way), uploading (its file is uploading) or failed (refused; retry or discard it).

`Message.order`

order: number

The sort position in the list.

`Messages`

class Messages

One conversation’s messages as shown: snapshot, then changes.

`Messages.hasOlder`

hasOlder = false

Whether older messages can still be loaded.

`Messages.olderEnd`

olderEnd?: string

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

`Messages.reset`

reset(list: Message[], hasOlder?: boolean, olderEnd?: string)

@internal

`Messages.apply`

apply(changes: any[])

@internal

`Messages.applyEvent`

applyEvent(e: { reset?: boolean; changes?: any[] })

@internal A messages event: with reset the view is replaced by the changes in one step, so no one sees it empty in between.

`Messages.loadOlder`

async loadOlder(): Promise<boolean>

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

`Messages.jumpTo`

jumpTo(seq: number)

A page around a message (it stays loaded).

`Batch`

interface Batch

One atomic write to the cache: everything in it is written or nothing is.

`Batch.id`

id: number

The batch number; the core waits for each in order.

`Batch.convs`

convs: Array<{ conv_id: string; [k: string]: unknown }>

Conversations to write (replacing the stored ones).

`Batch.put_messages`

put_messages: Array<Record<string, any>>

Messages to write.

`Batch.remove_messages`

remove_messages: Array<[string, string]>

Messages to delete, as [conv_id, key].

`Batch.put_ops`

put_ops: Array<Record<string, any>>

Queued operations to write (the offline queue).

`Batch.remove_ops`

remove_ops: string[]

Queued operations that are done, by id.

`Batch.meta`

meta?: { account?: string | null } | null

Which account the cache belongs to; a different account wipes it.

`Snapshot`

interface Snapshot

What the cache holds at start: the account, the conversations, the queue and recent messages.

`Snapshot.account`

account: string | null

The account the cache belongs to, or null when empty.

`Snapshot.convs`

convs: unknown[]

The stored conversations.

`Snapshot.ops`

ops: unknown[]

The stored offline queue, in order.

`Snapshot.messages`

messages: unknown[]

The newest messages of each conversation, up to the page size.

`Failure`

type Failure = 'full' | 'corrupt' | 'unavailable'

Why a write failed, as the core names it.

`StoreError`

class StoreError

Why the cache could not be written: full, corrupt or unavailable.

`Store`

interface Store

A cache for the client (IndexedDB in browsers, memory elsewhere); implement it to keep the cache somewhere else.

`Store.kind`

readonly kind: 'indexeddb' | 'memory'

indexeddb or memory.

`Store.open`

open(): Promise<void>

Opens the cache; fails with StoreError when it cannot.

`Store.snapshot`

snapshot(page: number): Promise<Snapshot>

Reads what the cache holds, with up to page messages per conversation.

`Store.page`

page(convId: string, beforeSeq: number, limit: number): Promise<unknown[]>

Reads up to limit older messages of a conversation before beforeSeq.

`Store.write`

write(b: Batch): Promise<void>

Writes one batch atomically.

`Store.wipe`

wipe(): Promise<void>

Deletes everything (sign-out, a different account).

`Store.persisted`

persisted?: boolean

navigator.storage.persist() result, when asked.

`MemoryStore`

class MemoryStore

Nothing kept after the page closes.

`MemoryStore.kind`

readonly kind = 'memory'

memory.

`MemoryStore.open`

async open() {}

Nothing to open.

`MemoryStore.snapshot`

async snapshot(page: number): Promise<Snapshot>

What the core reads at start: the account, conversations, the queue and the newest page messages of each conversation.

`MemoryStore.page`

async page(convId: string, before: number, limit: number)

Messages of a conversation before a seq, for paging back.

`MemoryStore.write`

async write(b: Batch)

Writes a batch from the core atomically.

`MemoryStore.wipe`

async wipe()

Deletes everything (logout, another account).

`IndexedDBStore`

class IndexedDBStore

IndexedDB, one per account and device (name). Asks the browser to keep it (navigator.storage.persist()) unless told not to.

`IndexedDBStore.kind`

readonly kind = 'indexeddb'

indexeddb.

`IndexedDBStore.persisted`

persisted?: boolean

Whether the browser agreed to keep the cache (navigator.storage.persist()).

`IndexedDBStore.open`

async open()

Opens (or creates) the cache and the queue databases and the encryption key.

`IndexedDBStore.snapshot`

async snapshot(page: number): Promise<Snapshot>

What the core reads at start: the account, conversations, the queue and the newest page messages of each conversation.

`IndexedDBStore.page`

async page(convId: string, before: number, limit: number)

Messages of a conversation before a seq, for paging back.

`IndexedDBStore.write`

async write(b: Batch)

Writes a batch from the core in one transaction (the queue in its own database).

`IndexedDBStore.wipe`

async wipe()

Deletes both databases (logout, another account).