| name | at_client_skills-sdk |
| description | Use this skill when a developer is building a Dart or Flutter app that depends on at_client or at_client_flutter from pub.dev, stores or shares data via the Atsign Protocol, needs onboarding (CRAM new-atSign, atKeys file, keychain, APKAM) or APKAM enrollment, or asks about AtCollection<T>, CItem<T>, Query<T>, sub-collections, event streams, read receipts, wherePath typed predicates, or watchWithTree deep hierarchies. Also use when the developer asks how to send or receive notifications via NotificationService, which pub.dev packages to add, how to unit-test without a live atServer, or whether to use AtCollection vs notifications+SQLite. Warns against deprecated AtCollectionModel, at_common_flutter, at_backupkey_flutter, at_invitation_flutter, at_sync_ui_flutter, and at_theme_flutter.
|
| license | BSD-3-Clause |
| compatibility | Claude Code and any agentskills.io-compatible agent. |
| user-invocable | true |
| metadata | {"version":"1.1.0","last_modified":"Tue, 23 Jun 2026 00:00:00 GMT"} |
atsign-dart-sdk Skill
Audience: developers adding at_client / at_client_flutter to their own
Dart or Flutter app from pub.dev — not developers editing the SDK repo itself.
1. CRITICAL: Use the Modern Collection API
Always use AtCollection<T>. Never use AtCollectionModel.
// ✅ CORRECT — modern API
import 'package:at_client/at_client.dart';
final todos = await atClient.collection<Todo>(
'todos.my_app',
const Duration(days: 7),
fromJson: Todo.fromJson,
typeTag: 'Todo',
);
// ❌ WRONG — deprecated, do not use
class MyModel extends AtCollectionModel { ... } // @Deprecated("Use AtClient.collection...")
The entire AtCollectionModel hierarchy is annotated
@Deprecated("Use AtClient.collection for collection-style operations").
If asked how to use AtCollectionModel: do NOT show any
AtCollectionModel code, even in a "before/deprecated" comparison. Show ONLY
the AtCollection<T> pattern above, state it is deprecated, and quote the
@Deprecated message.
Read references/01-deprecation-guide.md
for the full migration table from old to new API.
2. Package Map
Install with dart pub add — it pins the latest compatible version for you:
| Use case | packages to add |
|---|
| Dart CLI / server / IoT | at_client |
| Flutter app | at_client_flutter (re-exports at_client — one dep) |
| CLI / headless Dart | at_client, at_cli_commons |
| APKAM / custom auth flows | at_client or at_client_flutter, plus at_auth |
| Raw cryptographic operations | at_client or at_client_flutter, plus at_chops |
Never add: at_common_flutter, at_backupkey_flutter,
at_invitation_flutter, at_sync_ui_flutter, at_theme_flutter
Read references/06-package-map.md for
per-use-case checklists and the full list of in-migration packages to avoid.
3. Getting an AtCollection<T>
Obtain via AtClient.collection(...) — never construct AtCollection directly.
final todos = await atClient.collection<Todo>(
'todos.my_app', // namespace: MUST contain '.' (fully qualified)
const Duration(days: 7), // defaultExpiration for new items
fromJson: Todo.fromJson, // auto-registers factory; typeTag required with this
typeTag: 'Todo', // pin as a string literal — NOT T.toString()
cleanupOrphansOnCreation: true, // recommended when using sub-collections
eventSource: EventSource.both, // default (see below)
);
- Cached per
(namespace, eventSource) pair — same namespace + different
eventSource = separate instances
namespace must contain . (e.g. 'todos.my_app') — throws
ArgumentError otherwisetypeTag is mandatory when fromJson is supplied — always a string
literal, never derived from T.toString() (minifier renames types in
release builds)
EventSource:
| Value | Events seen |
|---|
EventSource.data | All local keystore mutations (requires SyncService running) |
EventSource.notifs | Cross-atSign writes via notification pipeline only |
EventSource.both | Both sources; same change may fire twice (no dedup); default |
Read references/02-atcollection-api.md for
the complete API surface including getDescendant, cleanupOrphans, and
registerFactory.
4. CRUD Cheatsheet
// create — strict: throws StateError if id already exists
final item = await todos.create(
obj: Todo('buy milk'),
sharedWith: {'@bob'.toAtsign()},
);
// upsert — idempotent: use for re-runnable publishers
await todos.upsert(id: 'my-known-id', obj: Todo('buy milk'));
// update — mutate, then persist
item.obj.done = true;
await todos.update(item);
// updateSharedWith — change recipients without rewriting the item
await todos.updateSharedWith(item, {'@alice'.toAtsign(), '@carol'.toAtsign()});
// delete
await todos.delete(item); // throws StateError if has sub-items
await todos.delete(item, cascade: true); // removes self-owned descendants first
5. Reading Data
final all = await todos.getItems();
final mine = await todos.getItems(owner: atClient.atSign);
final one = await todos.getOrNull('abc', atClient.atSign); // null if not found
final one2 = await todos.get('abc', atClient.atSign); // throws if not found
final has = await todos.exists('abc', atClient.atSign);
// Streaming — decode errors surface as stream errors (not silently swallowed)
todos.getItemsAsStream()
.handleError((e) => _log.warning('decode error: $e'))
.listen((item) => handle(item));
6. Query Builder
Queries are immutable — each modifier returns a new Query<T>. Execution
is always on-device (E2E encryption means the atServer cannot filter
plaintext).
final q = todos.query()
.where((t) => !t.obj.done)
.orderBy((t) => t.obj.due)
.thenBy((t) => t.obj.title)
.limit(20);
final list = await q.get(); // Future<List<CItem<Todo>>>
final live = q.watch(); // Stream<List<CItem<Todo>>>
final count = await q.count();
final any = await q.any();
final first = await q.firstOrNull();
Typed predicates (wherePath): prefer over .where() when you want future
push-down optimisation on indexed fields.
abstract class $Todo {
static final done = PathField<bool>(path: ['obj','done'], extract: (i) => (i.obj as Todo).done);
static final due = PathField<DateTime>(path: ['obj','due'], extract: (i) => (i.obj as Todo).due);
}
todos.query()
.wherePath($Todo.done.eq(false).and($Todo.due.lt(DateTime.now())))
.watch();
Read references/03-query-api.md for all terminals
(distinct, groupBy, watchWithSub, watchWithTree) and the full
PathField operator list.
7. Sub-collections
// Create a sub-collection — NEVER call atClient.collection(composedNamespace)
final notes = todos.subCollection<TodoNote>(
parent: todo,
subName: 'notes', // must NOT contain '.'
defaultExpiration: const Duration(days: 30),
fromJson: TodoNote.fromJson,
typeTag: 'TodoNote',
);
// Walk ancestry from a CSubItemUpdated event
final leaf = await todos.getDescendant<Reply>(
ancestry: event.ancestry, // root-to-direct-parent; ancestry.last is direct parent
id: event.id,
owner: event.owner,
leafExpiration: const Duration(days: 7),
); // returns null if any ancestor expired
// ⚠️ THROWS ArgumentError if any CAncestor.owner in ancestry is null.
// CAncestor.owner IS null on CSubItemDeleted events — never call getDescendant from a delete handler.
// Cache the ancestry from the preceding CSubItemUpdated if you need it on delete.
For 3+ levels use watchWithTree with SubSpec<U>. Each TreeNode<T> has a
parent (CItem<T>) and branches (Map<String, List<TreeNode<dynamic>>>).
When handling sub-collection events, ancestry is always root-first:
ancestry[0] is the root ancestor, ancestry.last is the direct parent.
Read references/03-query-api.md when working with
deep hierarchies.
8. Events & Streams
collection.updates // Stream<CItemUpdated>
collection.deletes // Stream<CItemDeleted> (item.wasExpired flag)
collection.readReceipts // Stream<CReadReceipt> (r.from, r.readAt)
collection.subUpdates // Stream<CSubItemUpdated> (ancestry chain; ancestry.last = direct parent)
collection.subDeletes // Stream<CSubItemDeleted> (ancestry[n].owner is null — cache from subUpdates)
collection.availableEvents // Stream<CItemAvailable> (e.availableAt fired)
collection.expiringSoonEvents(leadTime: const Duration(hours: 1))
Flutter subscribe/dispose:
late StreamSubscription<CItemUpdated> _sub;
@override void initState() { super.initState(); _sub = collection.updates.listen((_) => setState(() {})); }
@override void dispose() { _sub.cancel(); super.dispose(); }
Read references/04-events-api.md for all event
class fields, the EventSource decision guide, and the ancestry ordering
(root-first: ancestry[0] = root, ancestry.last = direct parent of the leaf).
9. Read Receipts
await item.markReadByMe(); // mark as read (idempotent)
final readers = await item.readBy; // Future<Set<Atsign>>
item.readBySnapshot; // sync snapshot
final didRead = await item.wasMarkedReadByMe();
collection.readReceipts.listen((r) => print('${r.from} read ${r.id} at ${r.readAt}'));
10. Flutter Auth (at_client_flutter)
Four auth flows — all end with the same _setupAtClient() call.
Flow 2 (existing .atKeys file) — most common for returning developers:
final atKeysIo = await AtKeysFileDialog.show(context);
final authRequest = AtAuthRequest(atKeysIo!.getAtsign(),
atKeysIo: atKeysIo, rootDomain: AtRootDomain.atsignDomain);
final response = await PkamDialog.show(context,
request: authRequest, backupKeys: [KeychainAtKeysIo()]);
if (response?.isSuccessful == true) await _setupAtClient(authRequest.rootDomain, response!);
Flow 3 (device keychain — returning user on same device):
final atSigns = await KeychainStorage().getAllAtsigns();
final request = await AtSignSelectionDialog.show(context, existingAtSigns: atSigns);
final authRequest = AtAuthRequest(request!.atSign,
atKeysIo: KeychainAtKeysIo(), rootDomain: request.rootDomain);
final response = await PkamDialog.show(context,
request: authRequest, backupKeys: [KeychainAtKeysIo()]);
if (response?.isSuccessful == true) await _setupAtClient(authRequest.rootDomain, response!);
Post-auth setup (all flows — takes just the root domain, so it works for
all 4 flows):
Future<void> _setupAtClient(AtRootDomain atRootDomain, AuthResponse response) async {
final dir = await getApplicationSupportDirectory();
final acp = AtClientPreference()
..rootDomain = atRootDomain.rootDomain
..rootPort = atRootDomain.rootPort
..namespace = 'my_namespace'
..commitLogPath = dir.path
..hiveStoragePath = dir.path;
await AtClientManager.getInstance().setCurrentAtSign(
response.atSign, 'my_namespace', acp,
enrollmentId: response.enrollmentId,
atChops: response.atChops,
atLookUp: response.atLookUp,
);
}
AtClientManager.getInstance().reset(); // logout
Read references/05-flutter-auth.md for all 4
flows (including Flow 1: CRAM new-atSign and Flow 4: APKAM enrollment) with
complete code.
11. Domain-Object Checklist
class Todo {
String title; bool done; DateTime due;
Todo(this.title, {this.done = false, required this.due});
Map<String, dynamic> toJson() => {'title': title, 'done': done, 'due': due.toIso8601String()};
factory Todo.fromJson(Map<String, dynamic> j) => Todo(j['title'] as String,
done: j['done'] as bool, due: DateTime.parse(j['due'] as String));
}
// Call once at startup — before any atClient.collection() call
AtCollection.registerFactory<Todo>(Todo.fromJson, typeTag: 'Todo');
typeTag must be a string literal — never T.toString() (breaks in release
builds)- Primitives (
String, Map<String,dynamic>, List, Uint8List) need no
registration
- Use
typeTag: 'binary' for Uint8List
Read references/08-domain-object-patterns.md
for polymorphic types, schema evolution, and the full re-registration rules.
12. Architecture Decision: AtCollection vs Notifications+SQLite
| AtCollection<T> | Notifications + SQLite |
|---|
| Data shape | Typed records, discrete items | High-frequency events / telemetry |
| Persistence | Synced via atServer | Local-only, from notifications |
| Volume | Low-medium (hundreds-thousands) | High (per-second metrics, logs) |
| Example | Todos, notes, contacts | Live dashboard, analytics |
These patterns are complementary and can coexist in the same app.
Sending / receiving notifications (the fire-and-forget side):
// Send — returns the notification id; body is usually JSON
await atClient.notificationService.send(
to: '@bob'.toAtsign(),
namespace: 'sample.my_app',
body: jsonEncode(payload),
expiration: const Duration(minutes: 5), // short TTL for telemetry
);
// Receive — subscribe to a namespace regex; decrypt encrypted payloads
atClient.notificationService
.subscribe(regex: r'sample\..*\.my_app', shouldDecrypt: true)
.listen((n) => handle(n.value));
Read references/10-architecture-guide.md
for the full decision guide and the dockerstats Notifications+SQLite example.
See packages/at_client/example/bin/notifications.dart for a minimal
send/subscribe walkthrough.
13. Testing Without a Live atServer
import 'package:at_client/at_client.dart'; // test hooks are re-exported here
final ctrl = StreamController<AtNotification>.broadcast();
final coll = collectionWithInjectedNotifications<Todo>(
fakeAtClient, 'todos.my_app', const Duration(days: 7),
notifications: ctrl.stream, fromJson: Todo.fromJson, typeTag: 'Todo',
);
clearFactoriesForTest(); // call in setUp() to prevent cross-test pollution
Available helpers: collectionWithInjectedNotifications,
collectionWithInjectedDataEvents,
collectionWithInjectedBoth, handleNotificationForTest,
handleDataEventForTest,clearFactoriesForTest,
clearMissingFactoryWarningsForTest
Read references/09-testing-patterns.md for
the complete test template including the correct AtNotification constructor
and MockAtClient stubs.
14. Deprecated — Do Not Use
| Avoid | Use instead |
|---|
AtCollectionModel / AtJsonCollectionModel | AtCollection<T> via atClient.collection(...) |
at_common_flutter | at_client_flutter |
at_backupkey_flutter | Copy at_client_flutter backup-key snippet |
at_invitation_flutter | Copy at_client_flutter invitation snippet |
at_sync_ui_flutter, at_theme_flutter | Deprecated — do not use |
at_chat_flutter, at_contacts_flutter, at_contacts_group_flutter, at_events_flutter, at_follows_flutter, at_location_flutter, at_notify_flutter | In migration — copy example code instead |
Read references/01-deprecation-guide.md
for the full migration table from old AtCollectionModel patterns to
AtCollection<T>.
15. Canonical Examples & Future Scope
packages/at_client/example/bin/collections_domain_objects.dartpackages/at_client/example/bin/collections_subcollections.dartpackages/at_client/example/bin/collections_todos.dart — terminal-UI (TUI)
todos app using AtCollection + query().watch() (Dart/CLI reference)packages/at_client/example/bin/notifications.dart — minimal
NotificationService send/subscribepackages/at_client_flutter/examples/todos/ — canonical Flutter reference apppackages/at_client_flutter/examples/dockerstats/ — notifications + SQLite
If asked about migrating from atClient.put() / atClient.get() to
AtCollection<T>: Both APIs share the same underlying atServer keystore but
use different key-naming conventions — AtCollection data will not appear in
raw get() queries and vice versa. Migration is non-trivial: read existing
data with the raw API and re-write it through AtCollection<T>. Always test
in a staging environment before touching production data. A formal migration
guide is coming in skill v2.0.
