Contributing / agents: see
AGENTS.mdfor build·test·verify (incl.melos bootstrap), conventions, and the "What NOT to do" rulings (Claude Code reads it viaCLAUDE.md). Governed by the Simple Zen SOP family (Notion).
Federated Flutter plugin providing a typed query API for device data (contacts,
media, files, calendar, messages, calls). Android is the reference backend;
non-Android platforms provide a mix of native bridges, filesystem fallback, and
honest capability reporting via getCapabilities().
Federated-only source of truth:
packages/contains plugin implementations and platform interface.example/contains sample app and integration tests.
packages/simple_query: app-facing facadepackages/simple_query_platform_interface: contracts, models, and errorspackages/simple_query_shared: shared infrastructure for non-Android platformspackages/simple_query_android: Android backendpackages/simple_query_ios: iOS backendpackages/simple_query_macos: macOS backendpackages/simple_query_windows: Windows backendpackages/simple_query_linux: Linux backend
- Typed filter/query model (
QueryRequest,QueryBuilder) with canonical field vocabulary enforced per domain (QueryFieldCatalog). - Capability discovery (
getCapabilities). - Deterministic standardized errors (
SimpleQueryErrorwith machine-readableSimpleQueryErrorCode). - Permission-aware: simple_query checks current grant state and fails fast
with
permissionDenied, but never requests permissions — that stays the app's job (use any permission library you like). Seedocs/DESIGN.md. - Streaming pagination (
SimpleQuery.queryPaginated) that walksnextCursor/nextOffsetto exhaustion, cancellable via the subscription. - Self-closing binary-content wrapper (
BinaryContent,withBinaryContent) so callers never juggle barehandleIdstrings. - Typed record views (
ContactRecord,CallRecord, etc.) withrecord.raw(untouched source map) andrecord.extras(OEM/niche columns the canonical contract doesn't name). - First-class custom content provider access via
SimpleQuery.queryRaw(contentUri: ...)for in-house providers. - Unified observe contract with fallback polling where native streams are unavailable.
- Explicit sequential best-effort fallback batch semantics outside Android.
- Explicit
platformData.rootPathrequirement for non-Android fallbackfiles/mediaoperations.
Capability behavior is explicitly platform- and domain-gated. Check capabilities at runtime before issuing operations.
| Domain | Android | iOS | macOS | Windows | Linux |
|---|---|---|---|---|---|
| contacts | Full CRUD + observe | Native (read-only) | Native (read-only) | WinRT (read-only) | EDS (if installed) |
| media | Full CRUD + stream + observe | Filesystem fallback | Filesystem fallback | Filesystem fallback | Filesystem fallback |
| files | Full CRUD + stream + observe | Filesystem fallback | Filesystem fallback | Filesystem fallback | Filesystem fallback |
| calendar | Full CRUD + observe | Native (read-only) | Native (read-only) | WinRT (read-only) | EDS (if installed) |
| messages | Full CRUD + observe | Not available (OS restricted) | Not available (OS restricted) | Not available (OS restricted) | Not available (OS restricted) |
| calls | Full CRUD + observe | Not available (OS restricted) | Not available (OS restricted) | Not available (OS restricted) | Not available (OS restricted) |
| platformSpecific | Provider extensions | Diagnostic + photos | Diagnostic + photos | Diagnostic + storage | Diagnostic + tracker/XDG |
| Topic | File |
|---|---|
| Design principles (read before contributing) | docs/DESIGN.md |
| Cross-platform semantics | docs/API_SEMANTICS.md |
| Canonical error codes | docs/ERROR_MAPPING.md |
| Migration from raw ContentProvider / native APIs | docs/MIGRATION.md |
| Platform support matrix | docs/PLATFORM_SUPPORT_MATRIX.md |
| Platform extensions (index) | docs/EXTENSIONS.md |
| Release process | UNFY-345 in Linear |
# Per-package tests
cd packages/simple_query
flutter test
# Whole-workspace verification
dart run melos run analyze
dart run melos run test
# Regenerate pigeon glue after editing any pigeon.dart
./tool/regen_pigeon.sh