Types & Models

This page documents the most important public models returned by the Dart/Flutter SDK.

Query models

`QueryResponse`

Returned by client.query(...).

success: bool
results: List<QueryResult> (one per statement)
tookMs: double?
error: ErrorDetail?

Convenience helpers:

rows → first result’s List<Map<String, KalamCellValue>>
columns → first result’s List<SchemaField>

Implementation note: the SDK parses row JSON and keeps schema metadata (SchemaField) so you can build higher-level typed mappers in your app.

`QueryResult`

columns: List<SchemaField>
rows: List<Map<String, KalamCellValue>>
rowCount: int
message: String?

`SchemaField`

Column metadata includes flag helpers:

isPrimaryKey (flag contains pk)
isNonNull (flag contains nn)
isUnique (flag contains uq)

Authentication models

`LoginResponse`

Returned by login(...) and refreshToken(...).

accessToken: String
refreshToken: String?
expiresAt: String
refreshExpiresAt: String?
user: LoginUserInfo

expiresAt and refreshExpiresAt are returned as strings (server-provided timestamps). Treat them as opaque unless you control the formatting.

Connection handlers

To receive lifecycle events, pass ConnectionHandlers to KalamClient.connect(...).

Callbacks include:

onConnect()
onDisconnect(DisconnectReason reason)
onError(ConnectionErrorInfo error)
onReceive(String message)
onSend(String message)
onEvent(ConnectionEvent event)

Lifecycle event types:

ConnectEvent
DisconnectEvent
ConnectionErrorEvent
ReceiveEvent / SendEvent (debug hooks)

Logging types

The SDK logging API uses Level from package:logger/logger.dart.

KalamLogger.level: Level
KalamLogger.listener: LogListener?
LogListener = void Function(LogEntry entry)
LogEntry fields: level, message, tag, timestamp

KalamClient.connect(...) also accepts logLevel and logListener so you can configure SDK logs at construction time.

Subscription event types

subscribe(...) returns a Stream<ChangeEvent>.

Event classes:

AckEvent — includes subscriptionId, schema, and snapshot info
InitialDataBatch — initial snapshot rows, potentially in batches
InsertEvent
UpdateEvent — sparse typed rows plus columnIndexes
DeleteEvent
SubscriptionError

All row-bearing events expose typed Map<String, KalamCellValue> rows (for example InsertEvent.row). For UpdateEvent, those maps are sparse and contain only changed columns plus PK and _seq.

AckEvent and InitialDataBatch include snapshot batching fields (batchNum, hasMore, status).

Subscription management models

`SubscriptionInfo`

Returned by client.getSubscriptions().

id: String — subscription ID
query: String — SQL query
lastSeqId: SeqId? — last received sequence ID (use for resume with from)
lastEventTimeMs: int? — last event timestamp (millis since epoch)
createdAtMs: int — creation timestamp (millis since epoch)
closed: bool — whether the subscription is closed

KalamCellValue & typed rows

Every cell in a typed row is a KalamCellValue — a wrapper class with safe accessor methods that mirrors the Rust KalamCellValue newtype.


import 'package:kalam_link/kalam_link.dart';
 
final rows = response.rows; // List<Map<String, KalamCellValue>>
for (final row in rows) {
  final name  = row['name']?.asString();    // String?
  final score = row['score']?.asDouble();   // double?
  final born  = row['created_at']?.asDate(); // DateTime?
  final url   = row['avatar']?.asFileUrl(
    'http://localhost:18080', 'default', 'users',
  );
}

Use the current helper directly:


final rows = response.rows; // List<Map<String, KalamCellValue>>

See Cell Values (KalamCellValue) for the full API including FILE column support and all accessor methods.