v_chat_persistence_drift 0.1.0-rc.6

Drift offline persistence adapter for the V Chat end-user SDK.

v_chat_persistence_drift

Drift persistence for the V Chat end-user SDK. Release candidate 0.1.0-rc.6 supports Dart >=3.10.0-0 <4.0.0 and depends on v_chat_core ^0.1.0-rc.6.

Use this package when you compose VChatClient yourself and need the released scoped offline, realtime-recovery, and push-receipt storage ports. Flutter applications should normally install v_chat_flutter, which creates and owns this adapter with the platform-appropriate Drift database.

Installation

dart pub add v_chat_persistence_drift

Your application must also provide a Drift QueryExecutor appropriate for its runtime. The adapter does not choose a filesystem location, encryption policy, or platform database driver.

Compose it with v_chat_core

import 'package:drift/drift.dart';
import 'package:v_chat_core/v_chat_core.dart';
import 'package:v_chat_persistence_drift/v_chat_persistence_drift.dart';

Future<void> runChatSession({
  required QueryExecutor databaseExecutor,
  required TokenProvider tokenProvider,
}) async {
  final store = DriftOfflineStore(executor: databaseExecutor);

  final client = VChatClient(
    options: VChatClientOptions(
      appId: '00000000-0000-4000-8000-000000000001',
      apiBaseUri: Uri.parse('https://api.example.com'),
    ),
    tokenProvider: tokenProvider,
    offlineStore: store,
  );

  try {
    await client.connectUser(userId: 'current-user-id');
    await client.conversations.refresh();
  } finally {
    await client.dispose();
  }
}

VChatClient initializes the supplied store during connectUser, assumes ownership, and closes it from dispose(). If you use DriftOfflineStore without VChatClient, your adapter layer must call initialize() before its first operation and close() when the database is no longer needed. Do not share one store or executor across clients that can dispose independently. v_chat_flutter handles composition and ownership automatically.

What is persisted

Every row is keyed by the immutable V Chat client scope:

environment + api authority + tenantId + appId + userId

The schema stores bounded, validated SDK state:

• confirmed channel, membership, message, reply, attachment, conversation, and unread entities;
• local query metadata used to label bounded cached pages;
• realtime recovery checkpoints and version fences;
• bounded quarantined event metadata for diagnostics;
• pending-command records exposed by the storage contract; and
• content-light push-notification receipt IDs for durable deduplication.

Only server-confirmed representations and tombstones are durable. A cached row is presentation state, not proof of current authorization or remote completeness.

What is never persisted

This adapter deliberately excludes:

• app-user tokens, application credentials, realtime tickets, signed attachment URLs, and signed headers;
• sockets, connection IDs, subscription handles, heartbeat state, retry timers, presence, and typing state;
• attachment bytes and arbitrary HTTP request or response bodies;
• opaque remote pagination cursors as durable sync truth; and
• automatic offline replay of message or attachment mutations.

Do not add secrets or private URLs to cached entity payloads, pending commands, checkpoints, or diagnostic records.

Store capabilities

DriftOfflineStore implements the v_chat_core offline contracts used by VChatClient:

• atomic applySyncBatch commits for entities, page metadata, checkpoints, and dead letters;
• exact-entity and scoped query reads plus watch streams;
• version-aware single and batch merges;
• pending-command enqueue, query, state transition, and deletion;
• realtime recovery checkpoint load, save, and delete;
• bounded dead-letter quarantine;
• durable push-notification receipt claiming and clearing; and
• exact-scope reset and purge operations.

Most applications should access these capabilities through VChatClient; the store API is public primarily so the core runtime can remain platform-neutral.

Bounds and validation

The defaults are intentionally finite:

Constructor option	Default	Valid range
maxPageSize	500	1..500
maxWriteBatch	2000	1..2000
maxEntitiesPerScope	10000	1..100000
maxPageMetadataPerScope	500	1..10000
maxPendingCommandsPerScope	1000	1..10000
maxCheckpointsPerScope	100	1..1000
maxDeadLettersPerScope	100	1..1000

Invalid configuration throws VChatConfigurationException. Runtime storage failures are mapped to stable VChatStorageException values by the adapter.

Reset, logout, and account switching

• resetCachedState(scope) deletes confirmed cached entities, page metadata, recovery checkpoints, and quarantined events for exactly one scope. It deliberately retains pending commands.
• purgeScope(scope) performs the same reset and also deletes pending commands for that scope.
• VChatClient.disconnect(clearLocalData: true) is the normal high-level logout path when local data for the connected scope must be removed.

Never construct a scope from unverified UI input to inspect another user. Let the connected client derive scope from the verified token/session boundary.

Schema and upgrades

The current internal Drift schema is version 3. Database tables and generated implementation files are internal; import only package:v_chat_persistence_drift/v_chat_persistence_drift.dart and use DriftOfflineStore. Do not depend on table names or generated database classes.

Package consumers do not run code generation. Contributors changing the internal Drift schema run:

dart run build_runner build --delete-conflicting-outputs

Schema changes must remain rolling-upgrade safe and preserve exact-scope isolation.

Support and security

Read the repository support, security, and privacy policies before production adoption. This is a release candidate; pin the exact version and review the changelog before upgrading.