Client Lifecycle

One-time initialization

Call KalamClient.init() once at app startup. It initializes the underlying Rust runtime.

await KalamClient.init();

Do not call KalamClient.connect(...) before init().

Creating a client

final client = await KalamClient.connect(
  url: 'http://localhost:8080',
  authProvider: () async => Auth.jwt(await getJwt()),
  timeout: const Duration(seconds: 30),
  maxRetries: 3,
  disableCompression: false,
);

Notes:

• connect(...) returns a ready-to-use handle; you don’t separately call connect() and disconnect() like the TypeScript client.
• Most methods use HTTP; subscriptions additionally use WebSocket under the hood.

auth vs authProvider

• authProvider is preferred for expiring tokens. It is invoked before each (re-)connection attempt.
• The auth option is deprecated; it cannot refresh automatically.

If both are set, authProvider takes precedence.

Refreshing auth in place

If you provided an authProvider, you can re-fetch and push updated credentials into the client:

await client.refreshAuth();
 
Timer.periodic(const Duration(minutes: 55), (_) => client.refreshAuth());

refreshAuth() does nothing if no authProvider was provided.

Connection handlers

Use connectionHandlers to receive lifecycle events (connect/disconnect/errors) and optional raw message debugging.

final client = await KalamClient.connect(
  url: 'http://localhost:8080',
  authProvider: () async => Auth.jwt(await getJwt()),
  connectionHandlers: ConnectionHandlers(
    onConnect: () => print('connected'),
    onDisconnect: (reason) => print('disconnected: ${reason.message}'),
    onError: (error) => print('error: ${error.message}'),
    onReceive: (message) => print('[recv] $message'),
    onSend: (message) => print('[send] $message'),
  ),
);

Handlers are only active when you pass at least one callback.

Use onReceive / onSend only for local debugging; avoid logging sensitive data (tokens, PII) in production.

Disposing

Call dispose() when the client is no longer needed:

await client.dispose();

After disposing, do not call query() or subscribe() on the same instance.

If you keep a single client for the whole app lifetime, dispose it only when the app is shutting down.

Next

• Health & Server Setup
• Authentication