NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
pub.dev, #4236 most downloaded on pub.dev
Flutter SDK for Koolbase — feature flags, remote config, version enforcement, authentication, storage, database, realtime, OTA updates, and code push for mobile apps.
Latest stable
12.53.0
Last release 15 days ago
05 Nov 2026
Ships on a steady schedule
a new release about every 9 days
Nearly every release is documented
notes for 60 of the last 60 stable releases
Nothing withdrawn
no release was ever pulled
8 months old
149 releases · first in 2026
Drag across the ruler to compare, or tap a release to open it.
12.5.0: session management, audit log, and resend verification withou…
12.5.0: session management, audit log, and resend verification withou…
…t a session
auth.listSessions(), auth.revokeSession(id), auth.revokeAllOtherSessions().
Three endpoints had been live on the server the whole time and no SDK
exposed any of them — so "sign out my other devices" existed and was
unreachable.
listSessions returns where the user is signed in: device label, IP, user
agent, timestamps, and isCurrent marking this device. Token hashes are
never included; the server excludes them.
revokeAllOtherSessions keeps this session and returns how many ended,
which is what the feature means after a lost phone.
Revoking the current session through revokeSession ends this one too. The
local session is not cleared there — the SDK cannot tell from the response
which session it was, and the next request's 401 handles it. A UI listing
sessions knows which row is current from isCurrent and should call
logout() for that one.
auth.auditLog({limit, offset}) — the account's own security history,
for a "recent activity" screen: sign-ins, failures, lockouts, password
changes, verification. Each event carries what its type is allowed to say
and nothing more; the server sanitizes them against a per-type field
allowlist. Returns a page with the total across all pages.
auth.resendVerificationEmailToAddress(email) — ask for a new
verification email with no session. Built for the TypeScript SDKs on
20 September; this SDK had the same dead end.
A project requiring verified contact issues no session until the account verifies and refuses login until then, so a user whose email went to spam or who waited past the link expiry could not sign in to ask for another. Returns nothing and reveals nothing: the server answers identically whether the address has an account, has none, or is already verified. Show the same "check your email" either way, and never say "we sent it".
The six x-koolbase-* identity headers this SDK sends are now pinned by a
test against the set the API allows, so they cannot drift without failing
here.
Your coding agent can read these notes before it upgrades. Set up the MCP server →
One column per month.
Fourteen exceptions reported codes the API has never emitted. EmailAlreadyInUseException said email_taken for a server that says email_in_use; UserDis
Fourteen exceptions reported codes the API has never emitted.
EmailAlreadyInUseException said email_taken for a server that says
email_in_use; UserDisabledException said user_disabled for
account_disabled; the Apple and Google exceptions each reported a
provider-split code where the server sends one unified code. code is a
public field, and anyone reading it instead of catching by type was
comparing against a string that would never arrive. Catching by type has
always worked and is unaffected.
invalid_refresh_token was unmapped in the database path — the code the
server actually sends when a session is over. It fell through to the
generic fallback, so koolbaseDataErrorNotifying never fired for it and
the session was not cleared. An app could keep a token the server refuses,
which is the failure that notifier exists to prevent. It now produces
KoolbaseSessionExpiredException, which four doc comments told
applications to catch and nothing had ever thrown.
A function that timed out was indistinguishable from one that threw. A
504 fell into the generic 5xx branch and arrived as
FunctionExecutionException. Those need different answers — a timeout
means retry or raise the limit; an exception means fix the code. Now
FunctionTimeoutException, and 429 gets FunctionRateLimitException.
Forty-four error codes the API emits were not mapped, arriving as bare
exceptions so an app's on clause silently never ran. Thirteen in auth,
including token_expired, token_used, account_exists,
oauth_only_account and insufficient_scope; the rest across database,
storage and functions, including revision_mismatch's siblings,
plan_limit_reached (shared across all three families, carrying resource,
limit and plan), ambiguous_match and upload_expired.
KoolbaseNotFoundException and KoolbaseValidationException report the
code they were built from, not their category. Each stood for several
codes while reporting one, so a collection_not_found response produced an
exception saying not_found.
Why these were missing: The API wrote error codes through four different helpers, so no single search found them all. It now declares every code as a constant in one file, with a test that fails the build on a literal — which made the comparison against this SDK exact for the first time. That is how these were found.
Both halves are now guarded here: one test asserts every code maps to its own exception, another that every exception reports a code the server sends. The auth error mapping had never had a test before this release.
12.3.0: auth.changePassword for the signed-in user
12.3.0: auth.changePassword for the signed-in user
Until now an app on Koolbase could not offer a change-password screen. Verifies the current password, signs out every other session, keeps this device in. Two new typed exceptions so a wrong current password and a rejected new password are distinguishable without string matching.
auth.changePassword(currentPassword:, newPassword:). An app could not
offer a change-password screen until now; the only route to a new
password was the reset email. The current password is verified first.
On success every other session for the user is signed out and this
device stays in -- a password is usually changed because someone else
may have it.InvalidPasswordException when the current password is wrong, or the
account signed up through a provider and has no password to change;
the server returns the same code for both so a caller cannot probe an
account's sign-in methods.WeakPasswordException is now actually thrown. It was defined and
mapped to KoolbaseErrorCode.validation but nothing raised it: the
server sent a too-short password back as an uncoded 400 on register,
and as invalid_token on reset. All three password paths now return
weak_password, so the same catch covers signup, reset and change.Pagination. KoolbaseCollectionList and KoolbaseCollectionGrid show a "Load more" past the last loaded record while the collection has more -- exact, f
KoolbaseCollectionList and KoolbaseCollectionGrid show
a "Load more" past the last loaded record while the collection has
more -- exact, from the query's total, not a guess from a short page.
KoolbaseCollectionController gains loadMore(), hasMore and
loadingMore. A list that showed twenty and stopped was quietly
claiming to be the whole collection.loadMore does not resubscribe: the realtime subscription stays on
the first page, so a live insert updates that page in place and the
pages loaded after it stay put. refresh() resets to one page.Koolbase.db.aggregate(...): count, sum, avg, min, max over the whole authorized set, grouped by a field or a calendar bucket. Every result carries its
Koolbase.db.aggregate(...): count, sum, avg, min, max over
the whole authorized set, grouped by a field or a calendar bucket.
Every result carries its accounting -- how many records contributed
and how many were skipped as missing or non-numeric -- so a total is
never a bare number. A calendar bucket requires a timezone; the
KoolbaseGroupBy.month(...) constructors make it impossible to omit.
Online-only. Read rules apply inside the query.initialize no longer refuses the browser. Code push is skipped (no binary, no bundle cache — path_provider has no web implementation) and codePush thr
12.0.0: Flutter Web
initialize no longer refuses the browser. Code push is skipped (no
binary, no bundle cache — path_provider has no web implementation)
and codePush throws with isCodePushAvailable false; offline sync is
skipped (drift on web needs wasm shipped beside the app). Auth,
database, storage, realtime and functions run. Proven on the example
app in Chrome against api.koolbase.com from a trusted origin.
Koolbase.initialize no longer refuses the browser: auth,
database, storage, realtime and functions work. Two capabilities are
absent on web and say so — code push (no binary to patch;
Koolbase.codePush throws, Koolbase.isCodePushAvailable is false) and
offline sync (reads are live, writes go straight out). A web app's
origin must be added under Configuration → Trusted Origins in the
dashboard; that list now governs API CORS as well as storage.Koolbase.codePush throws UnsupportedError on web instead of
initialize throwing. Guard with kIsWeb or isCodePushAvailable.README documents KoolbaseCollectionList.visible; install snippet at ^11.6.1.
KoolbaseCollectionList.visible; install snippet at ^11.6.1.11.6.0: KoolbaseCollectionList.visible
11.6.0: KoolbaseCollectionList.visible
Transform the loaded records before both the empty decision and the
rows. Runs on every build over what is already loaded; it does not
query. The Designer's search-on-list is built on it.
KoolbaseCollectionList.visible: transform the loaded records before both
the empty decision and the rows. Runs on every build over what is already
loaded; it does not query. A filter that leaves nothing shows the empty slot.Widget tests can now build Koolbase screens. Koolbase.initializeForTesting() sets up enough SDK for widgets to render — db and auth exist, every HTTP
Koolbase.initializeForTesting()
sets up enough SDK for widgets to render — db and auth exist, every HTTP
request answers with an empty success, auth storage is in memory — and none
of the platform channels a widget test cannot answer. resetForTesting()
pairs with it. InMemoryAuthStorage is public for your own tests.httpClient passed to the database client now reaches every query and
document reference. It was accepted and never used: queries called the
package-level http.post, so a test client was cosmetic and the database
could not be exercised without a network.Device outcomes are now attributable. Every patch event the SDK sent omitted patch_id, and the server only increments a patch's counters when that fie
patch_id, and the server only increments a patch's counters when that field
is present — so every download and activation ever reported landed in the
events table and moved no number. The staged patch id is now persisted
alongside the staged patch number and promoted on activation, so the id
survives the process boundary between downloading a patch and applying it.patch_activated. The reconcile branch that promotes a
staged patch on Android logged and returned without sending anything, so the
platform carrying almost all real traffic had never recorded a single
activation.patch_failed with a
reason. Previously a device that could not install a patch was
indistinguishable from one that never tried.app_version is populated on events rather than sent as an empty string.A patch, not a minor: refusing on a platform that was never supported adds no capability, and the version should say 'safe to take' rather than 'somet
11.4.1
A patch, not a minor: refusing on a platform that was never supported
adds no capability, and the version should say 'safe to take' rather
than 'something new arrived'.
Koolbase.initialize rather than starting a
client whose most important features silently do nothing. Code push, OTA
updates, offline-first sync and version enforcement have no browser
equivalent, so this SDK targets Android and iOS; the message points at the
JS SDK. The package began compiling for web in 11.4.0, which is precisely
why an explicit refusal became necessary — a working-looking client is
worse than a clear no.platforms: is declared in the pubspec (android, ios) rather than inferred,
so pub.dev states the boundary instead of guessing at it.patch_client is split by conditional export, and local_database passes
drift's web options. Both are what make the package compile off-device at
all; neither makes web a supported target.11.4.0: runtime storage public URLs via bootstrap-learned project ide…
11.4.0: runtime storage public URLs via bootstrap-learned project ide…
…ntity
publicUrlFor(bucket:, path:, transform:) needs no projectId — identity
arrives with the bootstrap payload the SDK already fetches, caches and
refreshes. Typed KoolbaseStorageProjectIdentityException while identity
is unavailable (distinct from null = private bucket); the throw nudges a
refresh so the session heals without restart. Update gate compares
project_id explicitly since it lives outside the payload hash. README,
CHANGELOG updated.
Koolbase.storage.publicUrlFor(bucket:, path:, transform:) — the runtime
form of publicUrl that needs no projectId argument. The SDK learns its
project identity from the bootstrap payload it already fetches and caches;
apps never carry or compose project identity themselves.KoolbaseStorageProjectIdentityException (code
project_identity_unavailable) — thrown while identity has not yet
arrived, i.e. a fresh install that has never completed a bootstrap.
Deliberately distinct from a null public URL, which means the project is
known and the object simply has no public URL (private bucket). The throw
also nudges a background bootstrap refresh, so the session heals once
connectivity returns — no restart needed.project_id (server-side from this release) and
the update gate compares it explicitly: identity is outside the payload
hash (it can never change), so version comparison alone would have
discarded the first identity-bearing payload on apps with unchanged
flags/config.publicUrl(projectId:, ...) is unchanged — still the right
tool for build-time URL generation where the caller holds the id.KoolbaseError: one canonical error type across the whole SDK
KoolbaseError: one canonical error type across the whole SDK
Catch anything, call KoolbaseError.from(e), branch on code. The 44 typed
exceptions are unchanged; this sits above them so an app can branch on what a
failure MEANS without knowing the SDK's internal taxonomy.
Found by measuring: across 14,732 lines, four places in the entire SDK catch a
transport failure. A database read that loses connection has been throwing a
raw SocketException straight through to the caller — on a phone with patchy
signal, the most common failure there is, and the one with no typed home.
Normalization is total: an unmapped server code, a bare string, an integer all
become a KoolbaseError rather than escaping. This runs in error paths, where a
second failure has nowhere to go.
Eleven codes. The bar for adding one is that an application could reasonably do
something DIFFERENT because of it — rateLimited because waiting is not
retrying, contactNotVerified because it routes to "resend verification" not
"check your password". retryable is derived from code, never stored, so the two
cannot disagree. details carries structured context through rather than
flattening it, including the server's current record on a revision mismatch.
message is developer diagnostic data and must never reach an end user. Written
into the doc comment, not just the changelog.
Also fixes the README's first auth example, which called a method that does not
exist (Koolbase.auth.register). signUp appeared nowhere in 1382 lines, so the
front page had no correct path to creating a user — including no mention of
SignUpResult.verificationRequired, where the account exists but no session was
issued.
Additive only. Nothing throws differently, no signature moved.
KoolbaseError — one canonical, platform-wide error type. Catch anything,
call KoolbaseError.from(e), branch on code. The 44 typed exceptions stay
exactly as they are; this sits above them, so an app that wants to branch on
what a failure MEANS no longer has to know the SDK's internal taxonomy.SocketException straight through to the
caller. On a phone with patchy signal that is the most common failure there
is, and it was the one failure with no typed home. KoolbaseError.from maps
SocketException, TimeoutException and ClientException to
KoolbaseErrorCode.network, which makes it actionable for the first time.KoolbaseError rather than escaping. This
runs in error paths, where a second failure has nowhere to go.KoolbaseErrorCode has eleven members, and the bar for adding one is that
an application could reasonably do something DIFFERENT because of it.
rateLimited exists because waiting is not retrying. contactNotVerified
exists because it routes to "resend verification", not "check your
password". Diagnostic distinctions that change nothing an app does stay in
message and rawCode, where they belong.retryable is derived from code, not stored, so the two can never
disagree.details carries structured context through normalization rather than
flattening it: the field that collided, the path that was taken, and — for a
revision mismatch — the server's current record, which is returned WITH the
refusal precisely so that deciding what to do next needs no second fetch.message is developer diagnostic data and must never be shown to an end
user. It is English-only, it is not stable API, and it names formats and
infrastructure: "Phone number must be in E.164 format", "SMS provider not
configured for this project". Map code to your own product copy. That is
also the localisation boundary — your copy table translates, the SDK does
not.catch clauses keep working unchanged.Analytics events now carry the signed-in user automatically. identify() existed, but nothing errored when an app never called it — so every event land
identify()
existed, but nothing errored when an app never called it — so every event
landed anonymous, and retention, funnels and any per-user analysis were
quietly worthless. Found by looking at a real project: 53 events, 8
registered users, zero events carrying a user id. The SDK already knows who
is signed in; it should say so.identify() still wins where an app has its own identity system, and the
existing reset() releases that override — without it, events keep carrying
the previous user after they sign out.Koolbase.fiscal — authority-grade sales recording. submit() records a transaction and drives fiscalization; status() follows it and returns the certif
Koolbase.fiscal — authority-grade sales recording. submit() records a
transaction and drives fiscalization; status() follows it and returns the
certification the tax authority granted (in Ghana: the GRA signature,
receipt number and verification QR a compliant receipt must carry). Live
for Ghana's GRA E-VAT; the reference adapter runs the same machine —
gapless numbering, sealed immutable documents, full evidence — anywhere an
authority integration doesn't exist yet.clientRef you pass is idempotent: resubmitting the same reference
always returns the same intent, never a second fiscal number. A timed-out
submit may still have fiscalized, so retrying or polling both converge on
the truth — the exception message says so rather than leaving you guessing.clientRef makes
that replay a single call.FiscalIntentResult exposes status, numbers, blockedReason,
certification, isFiscalized and isPending. A blocked result means
nothing was consumed — no fiscal number was spent — so fixing the cause and
resubmitting the same reference resumes that exact transaction. A
fiscalized result with a null certification is valid for document kinds
the authority acknowledges without certifying (purchase records); it is
never an error.fix: offline writes refuse signed-out — never enqueue under a null owner
fix: offline writes refuse signed-out — never enqueue under a null owner
A ticket parked on-device while the SDK session was dead was enqueued
with userId null. Every per-user surface then did its job correctly —
pendingWrites() throws signed-out, reads and replay filter by owner — so
the null-owner row matched nothing, forever: physically present,
invisible, unreplayable. The write neither failed nor succeeded; it
vanished into a bucket nobody owns.
All three offline enqueue sites (insert fallback, queued update, queued
delete) now throw KoolbaseUnauthenticatedException signed-out. Signed-in
behavior byte-for-byte unchanged. Mutation-pinned: removing the insert
guard fails 'writes to NO bucket'. Mirrors the RN SDK's Aug 4 fix of the
same bug family. v11.1.1
KoolbaseUnauthenticatedException when no
user is signed in, instead of enqueueing under a null owner. A null-owner
queue row is invisible to every per-user read and replay — the write
neither fails nor succeeds; it vanishes. Found on device as a parked
ticket that never reached the server. Signed-in offline behavior is
unchanged. Mirrors the React Native SDK's fix of the same bug.feat: get(fresh: true) — cache-skipping network read
feat: get(fresh: true) — cache-skipping network read
SWR cannot express read-after-write: a cached answer is the state before
your write, and awaiting the background-refresh stream proved racy
on-device (a local projection tracked the server exactly one sale
behind). get(fresh: true) skips the cache and returns the network's
answer; the read still updates the cache, so SWR callers benefit.
Plain get() unchanged. Fake queries in tests updated to the new
signature. v11.1.0
KoolbaseQuery.get() gains fresh: true — skips the cache and returns
the network's answer directly. Required for read-after-write (verifying
the effect of a write you just made), reconciliation, and local
projections that must only ingest server-provenance data. A fresh read
still updates the cache, so SWR callers benefit from it. Plain get()
behavior is unchanged.feat(auth)!: SignUpResult + ContactNotVerifiedException (11.0.0)
feat(auth)!: SignUpResult + ContactNotVerifiedException (11.0.0)
BREAKING: signUp returns SignUpResult, not KoolbaseUser.
The server can now withhold a session at registration when a project requires
a verified contact channel. The old return type could not express 'account
created, not signed in' — the session-less 201 reached AuthSession.fromJson
and threw 'type Null is not a subtype of type String' on the absent
access_token. Observed on device before this fix.
SignUpResult carries the user in both cases and a verificationRequired flag,
so consumers must branch. Deliberately not a nullable user or nullable
session on the public surface: that would push the same null-check onto every
caller and reproduce the crash one layer up.
The session is persisted only when one was issued. Calling _setSession with
null would leave the SDK half-authenticated — reporting a signed-in user with
no token.
signUp no longer routes through _parseSession. That parser assumes tokens
exist, which is correct for login and refresh and wrong for registration
under this policy; loosening it would have weakened login's contract for no
reason.
ContactNotVerifiedException maps the server's contact_not_verified code on
login. Credentials were correct and the policy refused, so it is distinct
from InvalidCredentialsException — apps route to resend-verification rather
than telling the user to re-check a password that was right.
Added only to _checkError, not to the Apple/Google parsers: OAuth satisfies
the requirement by definition (a provider attestation IS a verified contact),
so the server never emits this code on those paths.
Enforcement is off for every project that existed before the server-side
release, so verificationRequired is false and behaviour is unchanged unless a
customer opts in.
feat: KoolbaseCollectionGrid (10.5.0)
feat: KoolbaseCollectionGrid (10.5.0)
The same collection laid out as a grid. Deliberately thin: it shares
KoolbaseCollectionController with KoolbaseCollectionList, so
stale-while-revalidate, pull-to-refresh and the loading/empty/error
slots behave identically — the two differ only in layout, and sharing
the controller is what keeps them from drifting on the hard parts.
Fixed crossAxisCount rather than responsive reflow: a caller who needs
reflow can vary it from a LayoutBuilder, and building it in would have
meant guessing at tile sizing for everyone else.
Tests are narrow on purpose — the controller's properties are already
covered by the list's tests, so re-testing them here would test the
same code twice. The query fake moves to test/support so two copies
can't drift.
README's 'for grids, drive the controller directly' is no longer true
and now documents the widget instead.
10.4.0: streams fetch on listen, and writes refresh them
10.4.0: streams fetch on listen, and writes refresh them
Two gaps that both surfaced as "the UI just does not update" — nothing
errored, nothing logged, the data was simply absent. Both were found by
building an app against the SDK rather than by reading it.
.stream was a bare relay off a broadcast controller: get() performed the
fetch and pushed refreshes into it, so a stream-only listener waited
forever on a collection nothing else had read. It now fetches on first
listen, cache-first exactly as get() is.
Every write invalidated the collection cache and stopped, which only
affects the NEXT query. A listener already watching sat unchanged until
something happened to re-fetch — a message sent into a chat thread did
not appear in that thread. insert, upsert, deleteWhere, batch, and
conflict resolution now refresh open queries on the collection.
Each query re-runs ITSELF, so a stream only receives records matching its
own filters. The refresh is a registered closure per stream rather than
one rebuilt from the stream key: a key carries collection, filters, and
user but not ordering, limit, or populated fields, so a reconstructed
query would push the wrong records into a stream that never asked.
Mutation-verified: dropping the collection filter refreshes every query
in the process, failing three tests.
README gains a Live queries section — .stream was undocumented — and its
where() example is corrected to the real named-argument signature.
KoolbaseAuthGate, KoolbaseAuthScope, KoolbaseCollectionList, and KoolbaseCollectionController ship as the first behavioral widgets: the SDK now encode
KoolbaseAuthGate, KoolbaseAuthScope, KoolbaseCollectionList, and
KoolbaseCollectionController ship as the first behavioral widgets: the
SDK now encodes auth branching and the stale-while-revalidate list
contract as composable components rather than patterns every app
hand-writes. Query refresh streams are now keyed by query identity
rather than collection name, matching their documented contract — see
the changelog behavior note. README gains a Widgets section and catches
up two versions of version-string drift (was still ^10.1.2).
database: insert-conflicts are real, and resolvable (10.2.0)
database: insert-conflicts are real, and resolvable (10.2.0)
The Flutter twin of RN 94d8a21, closing the cross-SDK batch. Unique
constraints made insert-conflicts a genuine third kind: a queued insert
refused as a duplicate is held like any terminal refusal — but the client
coerced its operation to update (ConflictOperation admitted only two members),
and resolving one issued a PATCH against a record id that exists nowhere.
Storage never lied; only the mapper did.
ConflictOperation gains insert. Resolving a rejected insert IS the insert,
retried: resolveWithMerge carries amended data (the fix-the-colliding-title
path), unconditional — no record, no revision to be conditional against — with
the conflict's id as the idempotency key, so a resolution whose response is
lost returns the original on retry rather than duplicating. Wire-proven on the
exact route. resolveWithServer means the colliding row stands: clears with
zero requests, asserted by request count.
Seeded through the production path (enqueue → moveToRejected). Mutation-
verified: deleting the insert branch resurfaces the pre-fix wrong-verb PATCH,
caught by name by a scripted client that refuses unknown routes loudly.
README documents the insert-conflict resolution semantics in the same change.
database: a refused resolution teaches the stored conflict (10.1.2)
database: a refused resolution teaches the stored conflict (10.1.2)
The Flutter twin of RN fb4480d, live in a published SDK until now. Resolution
was conditional on the revision the ORIGINAL refusal reported; when the record
moved again mid-decision, the 409 — carrying current_revision and the record —
was correctly refused and entirely discarded by _resolveWrite. Every retry
replayed the stale condition; abandon was the only exit. Device-proven on RN
(three identical refusals against an unchanged server).
Flutter's factory already parsed the 409 fully into
KoolbaseRevisionMismatchException — the information died one method later. The
fix is one catch: refreshConflict absorbs currentRevision and currentRecord
into the Drift row (honoring serverState's own documented contract — 'as
returned with the refusal, so resolving does not need a fetch' — which the
CREATING refusal honored and the resolution refusal violated), then rethrows
with review-and-retry.
Proven by the revision sequence [8, 9]: the second attempt is conditional
against the LEARNED revision and succeeds without the server moving again.
Seeded through the production path (enqueue → moveToConflict). Mutation-
verified: removing the refreshConflict call fails the storage assertion.
The resolution HTTP path gained an injectable client (httpClient param) —
an unmockable resolution path is why no test ever caught this.
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Breaking: `Koolbase.messaging.send()` removed. Sending push notifications is server-initiated only — it requires a secret kb_live_ key and must run on
Breaking: Koolbase.messaging.send() removed. Sending push notifications is server-initiated only — it requires a secret kb_live_ key and must run on
your backend or in a Koolbase Function, never in the app. The publishable key the SDK holds ships inside your app binary; allowing it to send would let
anyone who extracts it push to your users. The API already rejects publishable-key sends with 401. Device registration
(Koolbase.messaging.registerToken) is unchanged. See docs: /sdk/messaging.
Fixed: in-app functions.deploy() now uses the auto-refreshing session token. It previously read a manually-set static token that expired after 15
minutes while invoke() (which already auto-refreshed) kept working — so a long-lived app could see deploys fail while invocations succeeded. deploy()
now shares invoke()'s token path. The removed setAuthToken() method is no longer needed; the SDK manages the session token itself.
Fix: package failed to compile on stock Flutter (all platforms). 9.4.0 unconditionally imported dart:_internal (VM code-push bindings that resolve onl
Fix: package failed to compile on stock Flutter (all platforms). 9.4.0 unconditionally imported dart:_internal (VM code-push bindings that
resolve only against the Koolbase-patched engine). The stock Dart frontend rejects platform-private imports at kernel compile, so every build failed with
"Can't access platform private library" — analyzer-clean, caught only at build time. The bindings are now a stock-safe stub: on a stock engine, code push
reports "engine not present" through existing failure paths (koolbaseBuildId() returns '', applyKoolbasePatch returns sentinel -990). No API changes; upgrading from 9.4.0 requires no code changes.
Code Push (VM-level, iOS): flash-free boot apply. Koolbase.initialize now completes the iOS boot-time patch apply (local disk only, ~5ms measured on d
Koolbase.initialize now completes the iOS boot-time patch apply (local disk only, ~5ms measured on device) before returning, so the app's first frame already runs the patched code — the brief v1→v2 flash on cold launch is gone, with zero configuration. The network check/download remains fully asynchronous and can never block startup.patch_downloaded (on successful stage), patch_activated (on the boot that promotes a new patch, with patch_number), and patch_failed (on rejection, with the rejection code and whether the artifact was newly staged or the durable copy) to /v1/code-push/patch-events. Dashboards and rollout decisions can now count real device activations instead of inferring installs from patch-check serves. Fire-and-forget: event reporting never delays boot and failures are silent.Nothing published for this version
Code Push (VM-level): the client now reports flutter_version on patch-check so the resolver can refuse a patch built on a different Flutter engine ver
flutter_version on patch-check so the resolver can refuse a patch built on a different Flutter engine version.
assets/koolbase_flutter_version asset (written by koolbase build / koolbase release) and sends it alongside build_id / release_version.flutter_version, closing two cross-engine mis-serve cases (colliding build_id across engine versions; release_version matching on app version alone).flutter_version and the server falls back to legacy matching — no change for apps already in the field.Widen package_info_plus to >=8.0.0 <10.0.0 and flutter_secure_storage to >=9.0.0 <11.0.0. The SDK only uses the stable surface of both (PackageInfo ve
package_info_plus to >=8.0.0 <10.0.0 and flutter_secure_storage to >=9.0.0 <11.0.0. The SDK only uses the stable surface of both (PackageInfo version/buildNumber; SecureStorage read/write/delete with default AndroidOptions and standard KeychainAccessibility), so the previous latest-major pins needlessly blocked — and for secure_storage risked force-migrating — host apps on the prior major.Code Push (bundle): recall/rollback now actually reverts a recalled bundle on device.
Code Push (VM-level): KoolbaseVmPatchClient — over-the-air Dart code updates for Android.
KoolbaseVmPatchClient — over-the-air Dart code updates for Android.
None. mode and minSimilarity are both optional; existing searchSemantic callers continue to work unchanged. Major bump reflects the conceptual expansi
mode and minSimilarity are both optional; existing
searchSemantic callers continue to work unchanged. Major bump reflects
the conceptual expansion of the search contract (three retrieval modes
instead of one), not API-breaking removals.KoolbaseQuery.searchSemantic accepts a new mode parameter of type
KoolbaseSearchMode. Three retrieval strategies are supported:
KoolbaseSearchMode.semantic (default) — pure vector search via HNSW
on cosine distance. Best for fuzzy / conceptual queries.KoolbaseSearchMode.lexical — pure BM25 over the field's source text
via Postgres ts_rank_cd. Best for exact terms, codes, names.KoolbaseSearchMode.hybrid — vector + lexical fused with reciprocal
rank fusion (k=60). Generally the strongest default for production
search.KoolbaseQuery.searchSemantic accepts a new minSimilarity parameter
(0..100, optional). Server-side filter that drops results below the
given similarity percentage before they cross the wire. Saves bandwidth
on weak matches. Only valid for semantic and hybrid modes; the server
rejects it on lexical mode (BM25 ranks aren't comparable to cosine
similarity).KoolbaseSearchMode enum exported from
package:koolbase_flutter/koolbase_flutter.dart.source_field configured. The lexical sidecar table populates
automatically on record write via the same hook that drives auto-embed.KoolbaseQuery.searchSemantic: the queryVector parameter is now optional. Existing callers continue to work unchanged — the breaking aspect is that the
KoolbaseQuery.searchSemantic: the queryVector parameter is now optional.
Existing callers continue to work unchanged — the breaking aspect is that
the SDK now validates that exactly one of queryVector / queryText is
supplied, and throws ArgumentError otherwise.KoolbaseQuery.searchSemantic accepts a new queryText parameter. When
supplied, the server embeds it inline using the vector field's configured
provider (Gemini or OpenAI) before running HNSW lookup. No client-side
embedding model required for typical search use cases.KoolbaseQuery.embedText queues an embedding job for a specific record's
vector field. Used for backfilling vectors on records that pre-date the
auto-embed hook, or for embedding text other than the record's
configured source field.771728d or later (Phase 2 Stage A3a).embedding_provider, embedding_model, and source_field configured
(see docs).Semantic search via vector similarity — query records by meaning, not just by field equality. New methods on the database namespace mirror the server-
Koolbase.db.doc(id).setVector(field, vector) — store a vector for a recordKoolbase.db.doc(id).getVector(field) — read a stored vectorKoolbase.db.doc(id).deleteVector(field) — remove a vectorKoolbase.db.collection(name).searchSemantic(field:, queryVector:, limit:, where:) — HNSW similarity search with optional filter scoping, returning ranked hits with cosine distanceKoolbaseVector, KoolbaseSemanticHit, KoolbaseSemanticSearchResultKoolbaseVectorDimensionMismatchException for length-mismatch errorsdimensions=1536 parameter (Matryoshka truncation)..get() does: owner/scoped/conditional rules are applied after the HNSW lookup, so strict rules may return fewer than limit results in this version.Purely additive — no existing methods or types changed. Upgrading from 6.x requires only flutter pub upgrade koolbase_flutter and a re-run of flutter pub get.
No breaking changes. All new APIs are additive; existing publicUrl calls without transform produce the exact same URL they did in 6.3.0.
Object versioning support — full read + write surface against versioned buckets. None of this changes existing behavior on non-versioned buckets.
KoolbaseObjectVersion model — one entry in a path's version timeline.
Carries versionId, size, metadata, isDeleteMarker, isCurrent,
createdAt and the rest of the version-row shape.KoolbaseStorageClient.listVersions({bucket, path}) — returns the full
timeline newest-first, current + history mixed.KoolbaseStorageClient.getVersion({bucket, path, versionId}) — metadata
for one specific version.KoolbaseStorageClient.restoreVersion({bucket, path, versionId}) — brings
a history version back to current; the previously-current row is
snapshotted to history first, so the restore is itself a versioned event.KoolbaseStorageClient.purgeVersion({bucket, path, versionId}) — hard
removes a single history version (row + R2 bytes).KoolbaseStorageClient.getDownloadUrl(...) accepts an optional
versionId — when present, the returned URL points to that specific
version's bytes from .versions/.KoolbaseStorageClient.delete(...) accepts an optional forcePurge
— true wipes the entire timeline for the path (all history rows,
all .versions/ R2 keys, canonical, and the current row).KoolbaseImageTransform value class — width, height,
format, quality, fit, dpr, gravity. Pair with the new
KoolbaseImageFormat, KoolbaseImageFit, and
KoolbaseImageGravity enums for type-safe option construction.
Out-of-range numeric values clamp silently to Cloudflare's
valid ranges (width/height 1–2000, quality 1–100, dpr 1–3).KoolbaseStorageClient.publicUrl({transform}) and
KoolbaseObject.publicUrl(bucket, {transform}) accept an
optional transform; the resulting URL hits Cloudflare's image
pipeline at cdn.koolbase.com/cdn-cgi/image/<opts>/... and
serves a resized, re-encoded copy of the source. Original URL
behavior unchanged when transform is omitted.KoolbaseStorageClient.publicUrlWithPreset({projectId, presetName, bucket, path}) and
KoolbaseObject.publicUrlWithPreset(bucket, presetName)
resolve a named preset stored server-side (managed via the
dashboard or REST API) at cdn.koolbase.com/p/{project_id}/ {preset_name}/{bucket}/{path}. Edit the preset once on the
server and every URL using it updates as the edge cache rolls
over.publicUrl calls without transform produce the exact same
URL they did in 6.3.0.KoolbaseObject gains an r2Bucket: String field identifying
which physical R2 bucket holds the object's bytes. Always
populated. 'koolbase-storage-public' means the object has a
stable CDN URL; anything else (typically 'koolbase-storage')
means it's in private storage and reads go through a presigned
URL via getDownloadUrl.KoolbaseObject.publicUrl(String bucketName) returns the stable
https://cdn.koolbase.com/... URL for the object when it lives
in the public R2 bucket, null otherwise. Use this when you
have an object instance and want a safe URL — returns null
rather than a URL that 404s for private or legacy public-bucket
files.KoolbaseStorageClient.publicUrl({projectId, bucket, path}) —
static helper that builds the CDN URL pattern unconditionally.
Use for build-time URL generation where you have the inputs but
don't need (or want) a check that the file is actually in a
public bucket.getDownloadUrl already returns the CDN URL
for objects in public buckets since the server-side Gap #2 deploy
on Jun 2 2026 — this release just makes that URL constructible
without a network round-trip.No breaking changes. All new APIs are additive; existing publicUrl calls without transform produce the exact same URL they did in 6.3.0.
KoolbaseImageTransform value class — width, height,
format, quality, fit, dpr, gravity. Pair with the new
KoolbaseImageFormat, KoolbaseImageFit, and
KoolbaseImageGravity enums for type-safe option construction.
Out-of-range numeric values clamp silently to Cloudflare's
valid ranges (width/height 1–2000, quality 1–100, dpr 1–3).KoolbaseStorageClient.publicUrl({transform}) and
KoolbaseObject.publicUrl(bucket, {transform}) accept an
optional transform; the resulting URL hits Cloudflare's image
pipeline at cdn.koolbase.com/cdn-cgi/image/<opts>/... and
serves a resized, re-encoded copy of the source. Original URL
behavior unchanged when transform is omitted.KoolbaseStorageClient.publicUrlWithPreset({projectId, presetName, bucket, path}) and
KoolbaseObject.publicUrlWithPreset(bucket, presetName)
resolve a named preset stored server-side (managed via the
dashboard or REST API) at cdn.koolbase.com/p/{project_id}/ {preset_name}/{bucket}/{path}. Edit the preset once on the
server and every URL using it updates as the edge cache rolls
over.publicUrl calls without transform produce the exact same
URL they did in 6.3.0.No breaking changes. getDownloadUrl already returns the CDN URL for objects in public buckets since the server-side Gap #2 deploy on Jun 2 2026 — this…
KoolbaseObject gains an r2Bucket: String field identifying
which physical R2 bucket holds the object's bytes. Always
populated. 'koolbase-storage-public' means the object has a
stable CDN URL; anything else (typically 'koolbase-storage')
means it's in private storage and reads go through a presigned
URL via getDownloadUrl.KoolbaseObject.publicUrl(String bucketName) returns the stable
https://cdn.koolbase.com/... URL for the object when it lives
in the public R2 bucket, null otherwise. Use this when you
have an object instance and want a safe URL — returns null
rather than a URL that 404s for private or legacy public-bucket
files.KoolbaseStorageClient.publicUrl({projectId, bucket, path}) —
static helper that builds the CDN URL pattern unconditionally.
Use for build-time URL generation where you have the inputs but
don't need (or want) a check that the file is actually in a
public bucket.getDownloadUrl already returns the CDN URL
for objects in public buckets since the server-side Gap #2 deploy
on Jun 2 2026 — this release just makes that URL constructible
without a network round-trip.feat(storage): custom object metadata. Attach arbitrary key/value pairs to stored objects at upload time, mutate via merge semantics post-upload, read
KoolbaseObject.
KoolbaseStorageClient.upload() gains an optional
metadata: Map<String, String> named param. Set at confirm time;
REPLACES prior metadata on the overwrite: true path (matches
GCS semantics — a new upload at a path produces a new object,
not a patch of the old).KoolbaseStorageClient.updateMetadata() method with merge
semantics: keys with a non-null value are set/updated, keys with
null are deleted, keys absent from the payload are untouched.
One call handles add, update, and delete atomically.KoolbaseObject gains a metadata: Map<String, String> field.
Always non-null — {} when empty, never null — so callers can
treat it as a guaranteed map without nil checks.KoolbaseStorageMetadataInvalidException (extends
KoolbaseStorageException) thrown for server-side validation
failures. Its detail field names the failing key and rule
(e.g. key "bad key": must match [a-z0-9_]+,
exceeds 50 keys (got 53)) so callers can surface actionable
errors without guessing what shape rule was violated.[a-z0-9_]+, values ≤1024
chars, leading underscore reserved for system keys.Storage error mapper switches on lowercase wire codes (path_conflict, quota_exceeded, file_too_large, mime_not_allowed) after the server normalized st
path_conflict,
quota_exceeded, file_too_large, mime_not_allowed) after the server
normalized storage codes to lowercase snake_case. Without this patch,
v6.1.0 customers see generic KoolbaseStorageException instead of the
typed subclass for storage limit errors. No semantic changes beyond
the case match.feat(storage): three new typed exceptions for bucket-limit failures introduced server-side in Storage #2. All extend KoolbaseStorageException so exist
KoolbaseStorageException so existing catch-all blocks continue to
work; catch the specifics to branch on the kind of limit hit.
KoolbaseStorageQuotaExceededException — 409 + QUOTA_EXCEEDED,
thrown when an upload would push the bucket past its
max_size_bytes cap.KoolbaseStorageFileTooLargeException — 413 + FILE_TOO_LARGE,
thrown when a single file exceeds the bucket's
max_file_size_bytes cap.KoolbaseStorageMimeTypeException — 415 + MIME_NOT_ALLOWED,
thrown when an upload's content-type isn't in the bucket's
allowed_mime_types allowlist (supports type/* wildcards).koolbaseStorageError / koolbaseStorageErrorFromResponse)
recognizes the new codes and the new HTTP statuses (413, 415).on KoolbaseStorageException keep working; the new types let callers
surface clearer messages or prompt the user to delete files / pick a
smaller file / pick a different file type.Koolbase.realtime.on / onRecordCreated / onRecordUpdated / onRecordDeleted no longer take a projectId — the project is derived from your session token
Koolbase.realtime.on / onRecordCreated / onRecordUpdated / onRecordDeleted no longer take a projectId — the project is derived from your session token, matching the React Native SDK. Migrate on(projectId: ..., collection: 'x') to on(collection: 'x').KoolbaseStorageClient.upload() is now safe-by-default. Uploads to a
path where an object already exists are rejected with a new
KoolbaseStorageConflictException instead of silently overwriting the
existing object. Pass overwrite: true to opt into the previous
replacing behavior.KoolbaseStorageException subtypes
instead of generic Exception — catching Exception still works but
catching the specific subtypes (or the KoolbaseStorageException base)
gives you cleaner branching.KoolbaseStorageException — base class for all storage failures, mirroring
the KoolbaseDataException pattern from the database layer.KoolbaseStorageConflictException (code: PATH_CONFLICT) — thrown when an
upload would replace an existing object and overwrite: false. Exposes the
colliding path from the server response.KoolbaseStorageNotFoundException, KoolbaseStorageValidationException,
KoolbaseStoragePermissionException — typed exceptions for the other
storage error classes (404, 400, 403). Storage operations now throw these
instead of a generic Exception.koolbaseStorageError(statusCode, body) and
koolbaseStorageErrorFromResponse(res) — code-first response-to-exception
mappers, matching the database layer's pattern.If your app uploads to deterministic paths (e.g. avatars/{user_id}.png)
and relied on the upload silently replacing the previous file:
// Before — silent overwrite
await Koolbase.storage.upload(
bucket: 'avatars',
path: 'me.png',
file: file,
);
// After — explicit overwrite
await Koolbase.storage.upload(
bucket: 'avatars',
path: 'me.png',
file: file,
overwrite: true,
);
If you want a conflict prompt (recommended for user-supplied filenames):
try {
await Koolbase.storage.upload(
bucket: 'documents',
path: filename,
file: file,
);
} on KoolbaseStorageConflictException catch (e) {
final ok = await showConfirm('${e.path} already exists. Overwrite?');
if (ok) {
await Koolbase.storage.upload(
bucket: 'documents',
path: filename,
file: file,
overwrite: true,
);
}
}
If you catch generic exceptions from storage operations, consider
catching KoolbaseStorageException (or specific subtypes) for cleaner
error handling:
try {
await Koolbase.storage.upload(...);
} on KoolbaseStorageConflictException {
// Path already exists — prompt user
} on KoolbaseStorageNotFoundException {
// Bucket missing or deleted
} on KoolbaseStoragePermissionException {
// Caller not authorized
} on KoolbaseStorageException catch (e) {
// Any other storage error
showError(e.message);
}
PATH_CONFLICT 409 support
(shipped alongside this release).Koolbase.realtime.on / onRecordCreated / onRecordUpdated / onRecordDeleted no longer take a projectId — the project is derived from your session token, matching the React Native SDK. Migrate on(projectId: ..., collection: 'x') to on(collection: 'x').KoolbaseStorageClient.upload() is now safe-by-default. Uploads to a
path where an object already exists are rejected with a new
KoolbaseStorageConflictException instead of silently overwriting the
existing object. Pass overwrite: true to opt into the previous
replacing behavior.KoolbaseStorageException subtypes
instead of generic Exception — catching Exception still works but
catching the specific subtypes (or the KoolbaseStorageException base)
gives you cleaner branching.KoolbaseStorageException — base class for all storage failures, mirroring
the KoolbaseDataException pattern from the database layer.KoolbaseStorageConflictException (code: PATH_CONFLICT) — thrown when an
upload would replace an existing object and overwrite: false. Exposes the
colliding path from the server response.KoolbaseStorageNotFoundException, KoolbaseStorageValidationException,
KoolbaseStoragePermissionException — typed exceptions for the other
storage error classes (404, 400, 403). Storage operations now throw these
instead of a generic Exception.koolbaseStorageError(statusCode, body) and
koolbaseStorageErrorFromResponse(res) — code-first response-to-exception
mappers, matching the database layer's pattern.If your app uploads to deterministic paths (e.g. avatars/{user_id}.png)
and relied on the upload silently replacing the previous file:
// Before — silent overwrite
await Koolbase.storage.upload(
bucket: 'avatars',
path: 'me.png',
file: file,
);
// After — explicit overwrite
await Koolbase.storage.upload(
bucket: 'avatars',
path: 'me.png',
file: file,
overwrite: true,
);
If you want a conflict prompt (recommended for user-supplied filenames):
try {
await Koolbase.storage.upload(
bucket: 'documents',
path: filename,
file: file,
);
} on KoolbaseStorageConflictException catch (e) {
final ok = await showConfirm('${e.path} already exists. Overwrite?');
if (ok) {
await Koolbase.storage.upload(
bucket: 'documents',
path: filename,
file: file,
overwrite: true,
);
}
}
If you catch generic exceptions from storage operations, consider
catching KoolbaseStorageException (or specific subtypes) for cleaner
error handling:
try {
await Koolbase.storage.upload(...);
} on KoolbaseStorageConflictException {
// Path already exists — prompt user
} on KoolbaseStorageNotFoundException {
// Bucket missing or deleted
} on KoolbaseStoragePermissionException {
// Caller not authorized
} on KoolbaseStorageException catch (e) {
// Any other storage error
showError(e.message);
}
PATH_CONFLICT 409 support
(shipped alongside this release).setToken was never wired), so it never connected. Switched to the same token-provider model as the other clients; it now authenticates with the user session and streams created/updated/deleted events.KoolbaseRealtimeClient.setToken — dead push-model plumbing that was never wired. The token now flows from the SDK automatically.userId parameter —
identity comes from the active session automatically.Realtime now connects. The client was protocol-correct but was never handed an access token (the push-based setToken was never wired), so it never con
setToken was never wired), so it never connected. Switched to the same token-provider model as the other clients; it now authenticates with the user session and streams created/updated/deleted events.KoolbaseRealtimeClient.setToken — dead push-model plumbing that was never wired. The token now flows from the SDK automatically.Data-plane requests (database, storage, functions, offline sync) authenticate with the signed-in user's access token (Authorization: Bearer) instead o
userId parameter —
identity comes from the active session automatically.Code Push — mandatory bundles. The SDK now honors a bundle's mandatory flag (set from the dashboard or via PATCH /mandatory). When a mandatory bundle
mandatory flag (set from the dashboard or via PATCH /mandatory). When a mandatory bundle is staged for the next launch:
Koolbase.codePush.hasMandatoryUpdate returns true — poll it on resume to gate your UI.onMandatoryUpdate callback on KoolbaseConfig fires immediately with MandatoryUpdateInfo(version, bundleId), so you can prompt the user to restart and apply the required update.Removed the Koolbase.ota client (KoolbaseOtaClient) and its models (OtaCheckResult, OtaProgress, OtaDownloadState). Use Koolbase.codePush for config/f
Koolbase.ota client (KoolbaseOtaClient) and its models
(OtaCheckResult, OtaProgress, OtaDownloadState). Use Koolbase.codePush
for config/flag/directive overrides, or Koolbase Storage for shipping and
reading raw files. This consolidates onto a single bundle client — matching the
React Native SDK and the server, which already use code push exclusively.sign_in_with_apple dependency — it was only used by the removed
KoolbaseAppleAuth. The current signInWithApple({identityToken}) is
library-agnostic, so the SDK no longer pulls it. If your app uses Apple
Sign-In, declare sign_in_with_apple in your own pubspec.yaml.Koolbase.ota client (KoolbaseOtaClient) and its models
(OtaCheckResult, OtaProgress, OtaDownloadState). Use Koolbase.codePush
for config/flag/directive overrides, or Koolbase Storage for shipping and
reading raw files. This consolidates onto a single bundle client — matching the
React Native SDK and the server, which already use code push exclusively.sign_in_with_apple dependency — it was only used by the removed
KoolbaseAppleAuth. The current signInWithApple({identityToken}) is
library-agnostic, so the SDK no longer pulls it. If your app uses Apple
Sign-In, declare sign_in_with_apple in your own pubspec.yaml.code
(with status/message fallback for older servers), retiring brittle message
string-matching.KoolbaseNotFoundException,
KoolbaseValidationException, KoolbasePermissionException,
KoolbaseRateLimitException — plus a shared KoolbaseDataException base.
Database operations now throw these (code-first) instead of a generic
Exception.KoolbaseConflictException now exposes the collided field when the
server reports it.insert no longer queues a server-rejected write (e.g. a unique
conflict) as an offline write — 4xx rejections surface immediately; only
genuine network failures are queued.Auth exceptions are now selected from the server's stable error code (with status/message fallback for older servers), retiring brittle message string
code
(with status/message fallback for older servers), retiring brittle message
string-matching.KoolbaseNotFoundException,
KoolbaseValidationException, KoolbasePermissionException,
KoolbaseRateLimitException — plus a shared KoolbaseDataException base.
Database operations now throw these (code-first) instead of a generic
Exception.KoolbaseConflictException now exposes the collided field when the
server reports it.insert no longer queues a server-rejected write (e.g. a unique
conflict) as an offline write — 4xx rejections surface immediately; only
genuine network failures are queued.Added KoolbaseConflictException, thrown by insert, update, and upsert when a write violates a collection's unique constraint (HTTP 409). Catch it to h
KoolbaseConflictException, thrown by insert, update, and upsert when a write violates a collection's unique constraint (HTTP 409). Catch it to handle duplicates.Docs: document upsert and deleteWhere in the README (no code changes).
upsert and deleteWhere in the README (no code changes).Added Koolbase.db.upsert(collection:, match:, data:) — insert-or-update by a match filter; returns KoolbaseUpsertResult { record, created }. Online-on
Koolbase.db.upsert(collection:, match:, data:) — insert-or-update by a match filter; returns KoolbaseUpsertResult { record, created }. Online-only.Koolbase.db.deleteWhere(collection:, filters:) — bulk delete by filter; returns the number of records deleted. Online-only.Flat record shape. KoolbaseRecord no longer wraps your fields under a data envelope. Your fields are now top-level, with system metadata in a reserved
KoolbaseRecord no longer wraps your fields under a
data envelope. Your fields are now top-level, with system metadata in a
reserved $-prefixed namespace: $id, $createdAt, $updatedAt,
$collection, and $createdBy (when set).KoolbaseRecord.projectId and KoolbaseRecord.collectionId —
internal identifiers are no longer exposed on records.record['field'] — direct field access, shorthand for record.data['field'].record.collection — the record's collection name.populate()) and realtime payloads now use
the same flat $-shape as direct reads.record.projectId / record.collectionId usage — those fields
are gone.record.data['field'] still works; record['field'] is the new shorthand.Replaced the deprecated KoolbaseAppleAuth.signIn() example with the new Koolbase.auth.signInWithApple(identityToken: ..., nonce: ..., fullName: ...) v…
Koolbase.auth.signInWithGoogle(idToken: ..., nonce: ...). Routes to
the server endpoint at /v1/sdk/auth/oauth/google with RS256-only
JWKS verification against Google's certs endpoint, multi-audience
support (iOS / Android / web client IDs configured per environment),
15-minute replay defense, and optional nonce check.auth_exceptions.dart:
GoogleSignInNotConfiguredException, InvalidGoogleTokenException,
GoogleEmailRequiredException. Reuses existing OAuthEmailConflictException
and UserDisabledException.google_sign_in packageimport 'package:google_sign_in/google_sign_in.dart';
final googleUser = await GoogleSignIn().signIn();
final googleAuth = await googleUser?.authentication;
final user = await Koolbase.auth.signInWithGoogle(
idToken: googleAuth!.idToken!,
);
Same as Apple Sign-In (v2.10.0). A new Google identity attaches to an
existing user only when BOTH the Google email AND the existing user's
email are verified, AND emails match (case-insensitive). Otherwise
sign-in either creates a new user (no email collision) or surfaces
OAuthEmailConflictException.
Before users can sign in with Google, configure the provider for your
environment. Run this against your Koolbase project's project_oauth_configs
(dashboard UI for OAuth config lands in a later release):
UPDATE project_oauth_configs
SET google_client_ids = ARRAY[
'<your-ios-client-id>.apps.googleusercontent.com',
'<your-android-client-id>.apps.googleusercontent.com',
'<your-web-client-id>.apps.googleusercontent.com'
],
enabled = true
WHERE environment_id = '<your-env-id>'
AND provider = 'google';
Get the client IDs from Google Cloud Console under Credentials → OAuth 2.0 Client IDs. You'll need one per platform (iOS, Android, web).
Koolbase.auth.signInWithGoogle reference. Google
Sign-In is planned for v2.11.0 — noted explicitly in the OAuth section.KoolbaseAppleAuth.signIn() example with the
new Koolbase.auth.signInWithApple(identityToken: ..., nonce: ..., fullName: ...)
v2.10.0 API using the sign_in_with_apple package.Koolbase.auth.authStateChanges.listen() example.^2.8.0 to ^2.10.0.Nothing published for this version
Nothing published for this version