docs
/
Client Integration

Flutter offline

The SDK's network behavior, scoped read caches, uncertain writes, and recovery after reconnection.

The Flutter client reads live. It has session storage but no record cache, connectivity monitor, durable write queue, conflict resolver, or background sync. The chat package also keeps messages in memory. An app that needs offline behavior must implement it explicitly.

Storage boundaries

LayerSDK behaviorApplication responsibility
Active sessionAccess/refresh tokens in secure storage; user in preferencesConfigure platform support and isolate environments
Remembered sessionsSaved records, including token copies, in preferencesUse a secure custom SessionStore if retaining them
Business recordsNo persistent cacheChoose storage, encryption, expiry and account scope
Pending writesNo queueDesign persistence, idempotency and reconciliation per operation

Partition caches by API origin, organization and identity. A cache key such as leads alone can expose one organization's records after a switch. Stored data also needs a timestamp so the UI can say when it was last fetched.

Fall back only for a network failure

Connectivity describes a network interface, not whether AppEngine is reachable. Make the request and handle its outcome. The following cache contract and helper can be used with an application-provided implementation; it deliberately does not prescribe a storage package:

import 'package:appmint_flutter_client/appmint_flutter_client.dart';

class CachedRows {
  const CachedRows(this.rows, this.savedAt, {this.stale = false});
  final List<Map<String, dynamic>> rows;
  final DateTime savedAt;
  final bool stale;
}

abstract class RowCache {
  Future<CachedRows?> read(String scope);
  Future<void> write(String scope, CachedRows value);
  Future<void> clear(String scope);
}

Future<CachedRows> readWithCache({
  required String scope,
  required RowCache cache,
  required Future<List<Map<String, dynamic>>> Function() fetch,
}) async {
  final List<Map<String, dynamic>> rows;
  try {
    rows = await fetch();
  } on AppmintNetworkException {
    final old = await cache.read(scope);
    if (old == null) rethrow;
    return CachedRows(old.rows, old.savedAt, stale: true);
  }
  final fresh = CachedRows(rows, DateTime.now().toUtc());
  await cache.write(scope, fresh);
  return fresh;
}

This example propagates cache read/write errors so the app can report a storage failure separately. Decide whether a failed cache write should prevent showing a successful fresh read. Never catch every exception and silently show old data: 403, expired sessions, invalid queries and malformed responses need different recovery. A cached private record is not proof of current permission.

Reconnection and lifecycle

Retry a failed read from a visible refresh action or after a network/resume signal. Coalesce those triggers so they do not launch overlapping refreshes. Cancel subscriptions in dispose, check mounted after awaited work, and ignore responses from an earlier user or org after switching context. A request timeout does not cancel work already accepted by the server.

Normal HTTP calls already retry recognized timeout and connection failures. See request retries before adding another retry loop. Multipart uploads and socket acknowledgments have different timeout and error behavior.

Writes with an unknown outcome

If a response is lost, the server may already have saved the action. The current SDK retries ordinary writes on recognized transport failures, including timeouts. For non-idempotent actions use transientRetries: 1, prevent duplicate submissions while a call is pending, and read back the domain record after an ambiguous failure. The separate 401 retry still applies.

A client-generated operation ID prevents duplication only when the server explicitly enforces it for that route. The generic repository has no documented universal idempotency-key contract. Its duplicate-create response is not a replacement for a durable operation ledger.

If a domain supports queueing, each entry needs the exact request payload, org, actor, creation time, dependency order and an operation identifier recognized by that server. Validate authorization again before replaying. Keep failed and conflicting entries visible; remove one only after confirmed acceptance. Do not replay a previous user's pending work under a new user's session.

What can be stale

A previously loaded catalog or schedule can remain useful with a timestamp. Live stock, payment state, ticket validity, queue position and access decisions need a fresh authoritative result before acting. A ticket scan must confirm admission with the server; a payment UI must not show “paid” because a request was queued. Provider delivery and card-reader acceptance require their own confirmation beyond a local saved row.

Sign-out and organization changes

auth.signOut() clears the SDK's active session. It leaves remembered accounts, application preferences, cached business records, pending actions and chat session IDs alone. Your application must clear or lock those scoped resources and dispose account-bound controllers. Do the same for a forced sign-out from auth.changes and for switchOrganization. Preserve unrelated hardware and layout settings only when their ownership allows it.

See authentication, request errors, and the example apps for the live-request integrations this cache layer sits around.