amba library
amba SDK for Flutter.
Pre-built native binaries ship with the package as platform-specific assets — no extra install steps. Every method JSON-encodes its arguments, calls into the bundled engine, and JSON-decodes the response.
── Architecture: Constructor DI ─────────────────────────────────────
AmbaBindings is the engine surface — an abstract class whose
concrete implementation forwards every call into the bundled
native engine. Anything that needs to call the engine accepts
an AmbaBindings instance via constructor injection. There are no
hidden globals, no test-only setters, no statics that mutate at
runtime; the only static is the customer-friendly singleton holder
inside Amba that gets populated by Amba.configure.
Tests construct an AmbaClient directly with a fake binding:
final client = AmbaClient(bindings: FakeBindings());
await client.events.track('test');
They never touch Amba's static state. This is the same pattern Stripe / OkHttp / URLSession / AWS SDK use — the wrapper is just a thin convenience over the injectable client.
Classes
- Achievement
- AchievementProgress
- AchievementsNamespace
- AiNamespace
- Amba
- Top-level amba SDK convenience API.
- AmbaApiErrorCode
-
Stable error codes surfaced by the SDK. Strings rather than an enum
so customers can extend with custom codes by simply throwing
AmbaApiError("MY_CODE", "...")without coordinating with this package's types. - AmbaBindings
-
Abstract surface over every C function the SDK calls. The production
implementation (
_AmbaBindings) loads the bundled engine and forwards each call. Tests / advanced consumers provide their own implementation and inject it via AmbaClient. - AmbaClient
- An amba SDK client wired against a specific AmbaBindings.
- AnthropicMessagesNamespace
- AnthropicNamespace
- AppSession
-
A customer-defined "app session" tracked by the
sessionsnamespace (NEW in 4.0). Distinct from the auth Session above — these are the user-facing engagement sessions ("user opened app", "user backgrounded"), not the SDK's JWT envelope. - AuthNamespace
- CatalogItem
- CatalogNamespace
- Challenge
- ChallengeProgress
- ChallengesNamespace
- CollectionsNamespace
- ConfigNamespace
- ContentItem
- ContentNamespace
- Conversation
- CurrenciesNamespace
- CurrencyBalance
- CurrencyTransaction
- DeepLink
- DeepLinksNamespace
- DiagnosticsNamespace
- Wire-verify namespace. The single ping method round-trips the SDK <-> control-plane connection and returns a PingResult the caller can use to confirm the SDK is talking to the right project with the right key in the right environment.
- EntitlementsNamespace
- EventsNamespace
- FeedItem
- FeedResponse
- FeedsNamespace
- FlagsNamespace
- Friendship
- FriendsNamespace
- Group
- GroupMember
- GroupsNamespace
- InventoryItem
- InventoryNamespace
- Leaderboard
- LeaderboardEntry
- LeaderboardsNamespace
- LeagueCohort
- Cohort identity — which weekly cohort the requester belongs to.
- LeagueCohortMember
- Per-member anonymised standing inside a cohort. Notably no user id — only displayName, since the cohort listing must not leak user ids to other clients.
- LeagueCohortView
-
Reply from
leagues.cohort— the cohort plus every member's anonymised standing. - LeagueMembership
-
Reply from
leagues.me— the requester's current standing in their active cohort. - LeaguesNamespace
-
Amba.leagues— tiered weekly leaderboard cohorts. NEW in 4.0. - LeagueTier
- League tier metadata (Bronze, Silver, Gold, …).
- MediaAsset
-
Storage asset metadata returned by
storage.list,storage.commit,storage.upload. Mirrors theMediaAssetwire shape. - Message
- MessagingNamespace
- ModerationNamespace
- OnboardingNamespace
- OnboardingStatus
- PingResult
- Server-echoed wire-verify result. Every field is decided by the SERVER — none of it is trusted from the request. Comparing serverProjectId against the project id the customer thinks they configured will catch "wrong key, right project id" misconfiguration on the spot.
- PurchaseOption
- PurchaseResult
- PushNamespace
- PushTokenInfo
- ReferralClaim
- ReferralCode
- ReferralsNamespace
- Report
- Review
- ReviewsNamespace
- Role
- RolesNamespace
- Session
- Snapshot of the current session as visible to the SDK consumer.
- SessionsNamespace
-
Amba.sessions— list/revoke active app sessions. NEW in 4.0. - StorageNamespace
- Store
- StoresNamespace
- Streak
- StreaksNamespace
- SyncChange
-
Single offline mutation captured client-side for replay via
sync.pushChanges. NEW in 4.0. - SyncConflict
-
Server-wins conflict reported by
sync.pushChangeswhen the device'sclient_timestampis older than the server'slast_synced_atfor the same row. resolution is always"server_wins"today; the field is exposed so future strategies (last-write-wins, custom merge) can extend without a breaking change. serverData carries the authoritative server payload the app should reconcile against its local cache. - SyncNamespace
-
Amba.sync— offline change replay. NEW in 4.0. - SyncPullResult
-
Reply from
sync.pullChanges— the batch of changes newer than the supplied checkpoint, the new cursor, and whether more pages are available. - SyncPushResult
-
Reply from
sync.pushChanges— how many of the batched changes the server applied, the per-row conflicts, and the new checkpoint cursor to feed back intopullChanges. - User
-
Authenticated end-user identity. Mirrors the engine's
Userserde shape (snake_case on the wire); Dart property names use lowerCamelCase. Optional fields fall back tonull/ empty. - UsersNamespace
-
Amba.users— profile read/update. NEW in 4.0. - XpBalance
- XpNamespace
- XpTransaction
Exceptions / Errors
- AmbaApiError
- Typed error thrown by every Dart SDK call. Callers can pattern-match against code for stable branching, or grab raw payload metadata (HTTP body, validation field paths, etc.) from details.
- AmbaException
- Base exception class for the amba SDK.