NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
pub.dev
pub.dev, #4489 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 17 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.
Messaging (R138): registerToken sends the signed-in person's session, so the API ties the device to them -- before, every registration was ownerless a
registerToken sends the signed-in person's session, so the API ties the device to them -- before, every registration was ownerless and sends to a user never reached their devices. It posts on the app's HTTP client, accepts web as a platform, and remembers the last token: signing in or out registers it again by itself. initializeForTesting sets messaging up on the test's client (device test-device). userId is kept but ignored (the API takes the owner from the session).A change refused on replay because the record changed elsewhere (409 revision_mismatch) is recorded as that conflict again, with the server's version
revision_mismatch) is recorded as that conflict again, with the server's version that came with it. It was filed as a plain refusal: the conflict read "refused" instead of "changed elsewhere", and keeping the server's version had nothing to show.Your coding agent can read these notes before it upgrades. Set up the MCP server →
One column per month.
KoolbaseRecordView follows the app's own writes to its collection, as KoolbaseCollectionList does: after an update it shows the device's saved copy at
KoolbaseRecordView follows the app's own writes to its collection, as KoolbaseCollectionList does: after an update it shows the device's saved copy at once (which holds the change, made online or queued offline), then the server's. Before, a shown record kept its old values until the screen was opened again -- a "Mark done" on a detail screen left it saying not done.Koolbase.initializeForTesting(offline: true) sets up the offline layer as an app's is, on an in-memory database: a write the network fails is queued a
Koolbase.initializeForTesting(offline: true) sets up the offline layer as an app's is, on an in-memory database: a write the network fails is queued and shown from the device's copy, and Koolbase.db.syncPendingWrites() replays the queue through the test's httpClient, so a widget test plays a server that accepts or refuses each change (a refused one becomes a conflict). Nothing listens for connectivity. resetForTesting closes it.SyncEngine takes an optional httpClient (the session client by default, as before). Nothing changes in an app.Koolbase.initializeForTesting(httpClient:) now sets up Koolbase.storage on that client: its API calls through the session client, an upload's bytes an
Koolbase.initializeForTesting(httpClient:) now sets up Koolbase.storage on that client: its API calls through the session client, an upload's bytes and a download through the client itself (lent, never closed). A widget test can play the storage server, hold an upload open and cancel it. Storage was unset before, so a test touching it failed.KoolbaseStorageClient takes an optional httpClient (every API call; the session client by default, as before) and transferClient (a new client per transfer; http.Client() by default, as before). Nothing changes in an app.Koolbase.initializeForTesting takes an optional realtimeConnector. With it, Koolbase.realtime is set up and opens its connection through that connecto
Koolbase.initializeForTesting takes an optional realtimeConnector. With it, Koolbase.realtime is set up and opens its connection through that connector, so a widget test can play the realtime server: a live list or record subscribes through the SDK's own realtime client and follows what the test sends. Without it, realtime stays unset, as before. resetForTesting now disposes the realtime client.Koolbase.initializeForTesting(httpClient:) now answers Koolbase.functions through that client too (it was not set up, so a test calling a Function fai
Koolbase.initializeForTesting(httpClient:) now answers Koolbase.functions through that client too (it was not set up, so a test calling a Function failed). KoolbaseFunctionsClient takes an optional httpClient.package_info_plus 10 is allowed (>=8.0.0 <11.0.0). Before, an app could not add geolocator 14.0.3 or later beside Koolbase: its Linux plugin needs pac
package_info_plus 10 is allowed (>=8.0.0 <11.0.0). Before, an app could not add geolocator 14.0.3 or later beside Koolbase: its Linux plugin needs package_info_plus 10, so pub get failed. PackageInfo.fromPlatform() and the fields Koolbase reads are unchanged; an app on an older Flutter keeps resolving 8 or 9.KoolbaseCollectionList(scrollController:) and KoolbaseFileList(scrollController:): a controller the app holds, so a "Back to top" can move the list --
KoolbaseCollectionList(scrollController:) and KoolbaseFileList(scrollController:): a controller the app holds, so a "Back to top" can move the list -- vertical, sideways, grouped and empty alike (A2.3). The list never disposes a controller it was given. Null keeps its own, as before.KoolbaseCollectionList: a query that fails after the list subscribed -- the session ended, the network went -- no longer throws an uncaught error. Bef
KoolbaseCollectionList: a query that fails after the list subscribed -- the session ended, the network went -- no longer throws an uncaught error. Before the list has loaded it shows its error state; after, the records it shows stay.Koolbase.initializeForTesting wires the session as an app's is: auth runs on the given client with an in-memory session, and data requests go through
Koolbase.initializeForTesting wires the session as an app's is: auth runs on the given client with an in-memory session, and data requests go through the session client, so a refused request renews once and a refused renewal ends the session. A test can sign in, have the session end and sign out against a fake server while the SDK's own code runs.`signInWithApple(authorizationCode:, client:)` (A0 piece 6): pass the Apple credential's authorizationCode, and the server keeps the token it revokes
signInWithApple(authorizationCode:, client:) (A0 piece 6): pass the Apple credential's authorizationCode, and the server keeps the token it revokes when the account is deleted, as Apple asks. client: 'web' when the code came from Apple's web sign-in. Both optional; without them sign-in works as before, and that account's token can't be revoked.`KoolbaseAggregateResult.fewerThan` and `KoolbaseAggregateGroup.fewerThan` (#299): below the collection's count minimum the API does not say the numbe
KoolbaseAggregateResult.fewerThan and KoolbaseAggregateGroup.fewerThan (#299): below the collection's count minimum the API does not say the number -- show "Fewer than N", never 0. Null when the number is said. Only a count that sees beyond what the caller may read, under the collection's Count rule.`ResendCooldownException.retryAfter` (#244): how long until another verification email may be sent, from the server's Retry-After -- as @koolbase/js's
ResendCooldownException.retryAfter (#244): how long until another verification email may be sent, from the server's Retry-After -- as @koolbase/js's VerificationResendCooldownError.cooldownUntil. Null when it did not say.A rate-limited request says when to try again (#244).
A rate-limited request says when to try again (#244).
RateLimitException.retryAfter: how long until the server would take the request again -- its retry_after, or its Retry-After header -- for a countdown ("Resend in 7:42"). Null when it did not say. An emailed sign-in code that is refused for sending too many now carries it.A list says how many rows it shows (#224).
A list says how many rows it shows (#224).
KoolbaseCollectionList(onRows: (rows) { ... }): null while the list loads, after a failed first load, and while a search is being answered with nothing yet to show; otherwise the number of rows shown, after visible (a search that matches nothing is 0). Called after the frame, only when the number changes. With empty: (context) => const SizedBox.shrink(), an empty list takes no space and something else on the screen -- its heading -- can follow it.Totals take the typed filter. Same contract as @koolbase/* 12.34.0.
Totals take the typed filter. Same contract as @koolbase/* 12.34.0.
KoolbaseAggregate(filter: KbWhere, timezone: ...): the same tree a list's query takes (#165): and/or groups, ranges, dates, KbValue.now(). "Upcoming events" now counts exactly what the list shows; the server applies it inside the read rule.filter with where (the list of filters) throws ArgumentError before anything is sent. Existing totals are sent exactly as before.A list reloads when a chip changes, for real (#194): a query that reads the screen's state when called (as a Koolbase Designer export's does) is now c
A list follows its query (#194).
A list follows its query (#194).
KoolbaseCollectionList and KoolbaseCollectionGrid read again when their query's filters change: a chip chosen, a dropdown, screen state. Before, the query was taken once and a rebuild with new filters was ignored. The same filters in a new closure (every rebuild, a relative KbValue.now()) read nothing.KoolbaseCollectionController.setQuery(builder): the same, for a controller you hold.KoolbaseTestData query is keyed by its filters, as a real one is.Search by meaning takes the typed filter (#173). Same contract as @koolbase/* 12.33.0.
Search by meaning takes the typed filter (#173). Same contract as @koolbase/* 12.33.0.
searchSemantic(filter: KbWhere, timezone: ...): the same tree filter() takes on a query (#165): and/or groups, ranges, dates, KbValue.now() and the other server-resolved operands, the caller. Semantic, lexical and hybrid all apply it inside the collection's read rule, so "chill events" can be searched within upcoming events only.filter with where (the map of equals) throws ArgumentError before anything is sent. Existing searches are sent exactly as before.query_invalid, query_field_untyped, query_timezone_invalid, ...).Typed queries (#165): filters with and/or groups, ranges and dates, and sorts by a field's declared type. Same contract as @koolbase/* 12.32.0.
Typed queries (#165): filters with and/or groups, ranges and dates, and sorts by a field's declared type. Same contract as @koolbase/* 12.32.0.
filter(KbWhere): a tree of conditions. KbWhere.and / KbWhere.or group them, up to 3 deep. KbField(name) gives the operators: eq, neq, gt, gte, lt, lte, contains, startsWith, isIn, notIn, between, before, after, onOrBefore, onOrAfter, on, isEmpty, isNotEmpty, isTrue, isFalse. The server checks each against the field's declared type and runs the filter after the collection's read rule, so a filter only narrows what the caller may read.KbValue.now(), startOfToday(), startOfTomorrow(), startOfWeek(), startOfNextWeek(), startOfMonth(), with an offset, and the signed-in caller, KbValue.callerUserId() / KbValue.callerClaim(name), read from the session, never from the app.sort([KbSort.desc('featured'), KbSort.asc('starts_at')]): up to 3 fields, typed by the declaration, empty values last both ways, ties broken by the record's id.on resolve in the device's IANA zone (flutter_timezone), or the one named with timezone('Europe/London').filter/sort with where(isEqualTo:)/orderBy throws ArgumentError before anything is sent. Existing queries are sent exactly as before.query_invalid, query_too_complex, query_operator_invalid, query_field_untyped, query_timezone_invalid, query_caller_path_invalid, query_sort_invalid, query_sort_untyped) arrive as KoolbaseValidationException with the code.A failed Koolbase request leaves a trace in a debug build (#169). Same contract as @koolbase/* 12.31.0.
A failed Koolbase request leaves a trace in a debug build (#169). Same contract as @koolbase/* 12.31.0.
kDebugMode), every Koolbase request that fails as the caller receives it prints one line, [Koolbase] POST /v1/sdk/auth/email/code -> 401 invalid_public_key: ...: the method, the path, the status and the server's reason. Never the host, the query, a header, the key, a token or the request body. A 401 that renewing the session answers is not printed. Release builds print nothing.A refused app key is reported as the setup problem it is, never as a wrong password and never by signing the user out (#168, #169). Same contract as @
A refused app key is reported as the setup problem it is, never as a wrong password and never by signing the user out (#168, #169). Same contract as @koolbase/* 12.30.0.
KoolbaseInvalidPublicKeyException (invalid_public_key, 401): the app's Koolbase key is unknown or revoked, or its project is deleted or not ready. The API answers this on any route since #169. It is deliberately not a KoolbaseUnauthenticatedException, so it never clears the session; KoolbaseError files it under server, as other misconfigurations, with invalid_public_key as the raw code.InvalidCredentialsException ("Invalid email or password"), whatever the cause. It is now a generic KoolbaseAuthException carrying the server's reason. A refresh's 401 is still a session that expired. The API sends invalid_credentials whenever a password is wrong.Errors the API added in #161 and #162 arrive as their own exceptions, not generic ones. Same contract as @koolbase/* 12.29.0.
Errors the API added in #161 and #162 arrive as their own exceptions, not generic ones. Same contract as @koolbase/* 12.29.0.
KoolbaseServiceUnavailableException (placement_unavailable, 503): the project's database could not be reached just now; nothing was read or written. retryable is true. Any request can meet it: a query, an upload, a sign-in.KoolbaseAutoEmbeddingManagedException (auto_embedding_managed, 409): the vector field is filled by automatic embedding, so setVector, deleteVector and text sent for it are refused. Write the record's fields; the vector follows.KoolbaseReembedConfirmationRequiredException (reembed_confirmation_required, 409): a change to a field's embedding would embed the collection again. estimate carries the records, estimated input tokens, provider, model and who is billed; send the change again with confirm_reembed: true to make it.KoolbaseEmbeddingModelUnsupportedException (embedding_model_unsupported, 400): a model Koolbase does not offer, one shut down by its provider, or a size it cannot store.placement_unavailable 503 used to arrive as a generic KoolbaseDataException or KoolbaseStorageException. It is now the shared KoolbaseServiceUnavailableException (like KoolbasePlanLimitException), so on KoolbaseDataException no longer catches it; catch KoolbaseException for every SDK failure.A search the server cannot run never replaces the list (#160).
A search the server cannot run never replaces the list (#160).
KoolbaseCollectionList(search:): when the server cannot answer the search (offline, say), the list shows visible's matches among the records loaded under a line saying so, with a retry -- no longer the error slot in place of the list. When it refuses the search (a field_search it will not take, as when the collection's fields changed since the app was built), or the search is wider than it takes (a Choice matching more than 100 values, text over 100 characters), the list is read unsearched and visible filters it, under a line saying so; the server is not asked again while the list lives.KoolbaseCollectionController.searchLoadedOnly: true while the search is not run on the server, so records are the list unsearched for the app to filter.`KoolbaseQuery.fieldSearch(KoolbaseFieldSearch(text:, fields:, choices:))`: records whose named text fields contain the text, ignoring case, inside th
Search on the server (#160).
KoolbaseQuery.fieldSearch(KoolbaseFieldSearch(text:, fields:, choices:)): records whose named text fields contain the text, ignoring case, inside the read rule and the filters and before the page -- so the total and every page are of the matches. A Choice field is searched by its labels (KoolbaseChoiceSearch(field:, values:, listed:): the values whose label matches, and every value it declares). A searched query always asks the server and is not kept as the query's offline copy. Needs the API with field_search.KoolbaseCollectionList(search:): the list shows the search's matches, page after page. Changing it keeps the list and searches again once the typing pauses (250 ms); the newest search wins. Until the server answers, visible filters what is loaded as a preview under a thin progress bar, and an empty preview shows the loading slot, not the empty one. A search the server cannot answer shows the error slot, with a retry. KoolbaseCollectionController.setSearch, searching, searchError, retrySearch.KoolbaseTestData answers a search as the server matches it.`KoolbaseUser.avatar` (KoolbaseAvatarFile: bucket, path): where the photo is stored, when it is one of the user's files. Read it like any stored file
The profile photo as a file.
KoolbaseUser.avatar (KoolbaseAvatarFile: bucket, path): where the photo is stored, when it is one of the user's files. Read it like any stored file -- in one of the project's image presets (getDownloadUrl(..., preset:), publicUrlFor(..., preset:)), and signed when the bucket is private. Kept with the persisted session.updateProfile(avatar:): sets the photo to a file the user uploaded -- the bucket and the path the upload returned. A file someone else uploaded is refused. avatarUrl then follows it: a public bucket's permanent link, null for a private one. removeAvatar: true removes the photo. One of avatar, avatarUrl or removeAvatar at a time; setting avatarUrl stops the photo being a file.The signed-in user's claims (#155b).
The signed-in user's claims (#155b).
KoolbaseUser.claims and claim(key): the trusted claims this user may read about themselves -- a role, an organisation -- only the keys the project's owner made readable by the user (Auth -> Claims -> a definition's "Readable by the user"). Null when there are none. On every session and on getCurrentUser(); a changed role arrives on the next refresh. Kept with the persisted session.toJson, absent when there are none.Presets for private buckets (#146).
Presets for private buckets (#146).
getDownloadUrl(..., preset:): names one of the project's image presets. An image's current version is given sized as the preset says -- a private bucket's as a signed address good for an hour, issued after the bucket's rules let this person see the file. Anything not an image is given as it is.Image presets for stored files (#146).
Image presets for stored files (#146).
publicUrlFor(..., preset:): names one of the project's image presets (Storage → Presets). The URL is the named-preset form, cdn.koolbase.com/p/{project}/{preset}/{bucket}/{path}, sized at the edge as the preset says; a transform is not used with it. Public buckets only, as presets are.Malware scanning (storage S6) and declared-field codes (#116, #117).
Malware scanning (storage S6) and declared-field codes (#116, #117).
KoolbaseStorageMalwareException (malware_found): an upload refused because malware was found in it. Nothing of it was kept; the message names what was found.KoolbaseStorageQuarantinedException (quarantined, 423): a file found to contain malware after it was stored. No link is given for it.KoolbaseFieldProblem.code may also be too_small or too_large (a number outside its declared minimum or maximum) and user (a user field given something that is not a user's id).Several uploads in a queue (storage S4).
Several uploads in a queue (storage S4).
KoolbaseUploadQueue: add([KoolbaseQueueFile(bucket:, path:, bytes:)]) returns ids; items (each with its own status, progress and error), progress, running, done, failed; cancel(id), cancelAll(), retry(id), clearFinished(), whenIdle(). A ChangeNotifier, for an upload list with a row per file.progress is the files' average, a cancelled one left out.cancelAll, whenIdle, clearFinished, nothing after dispose.One file's details (storage S4).
One file's details (storage S4).
KoolbaseFileView(bucket:, path:, builder:): one file's details -- name, size, type, dates, who uploaded it, its permanent link while the bucket is public -- for a file detail screen. loading, notFound and error (with a retry) are slotted, as on KoolbaseRecordView. Its data half is KoolbaseFileController.A file's path is encoded in the address of getDownloadUrl, listVersions, getVersion, restoreVersion and purgeVersion. A name with "&", "#", "+" or "%"
getDownloadUrl, listVersions, getVersion, restoreVersion and purgeVersion. A name with "&", "#", "+" or "%" in it -- "Q&A.pdf", "C#.txt", "1+1.png" -- asked for a different file or none.A bucket's files as a list (storage S4).
A bucket's files as a list (storage S4).
KoolbaseFileList(bucket:, itemBuilder:): the files the signed-in person may view, a page at a time, with pull to refresh and Load more; prefix, sort, descending and limit choose which and in what order; loading, empty and error (with a retry) are slotted, as on KoolbaseCollectionList. scrollsWithPage for a list inside a scrolling page. Its data half is KoolbaseFilesController.KoolbaseFileInfo.toMap(): a file's fields by name.Large uploads in parts, resumable; downloads you can follow (storage S3).
Large uploads in parts, resumable; downloads you can follow (storage S3).
KoolbaseStorageClient.multipartThreshold): three at a time, each to its own link. A part that fails for a passing reason is sent again, up to four times; an expired link is renewed. upload, uploadBytes and startUpload choose this themselves; progress is the bytes of the whole file.task.uploadId (set once it begins) resumes it with storage.resumeUpload(bucket:, uploadId:, bytes:), for a day, sending only what is missing -- after the network returns or the app restarts. Cancelling abandons it.storage.downloadBytes(bucket:, path:, onProgress:): a file's bytes, reported as they arrive.KoolbaseUploadIncompleteException (missing). Needs the Koolbase API from October 2026.Move and copy a file (storage S1b).
Move and copy a file (storage S1b).
storage.move(bucket:, from:, to:, toBucket:) and storage.copy(...): within a bucket or into another, without uploading again. The bucket's rules decide (a copy needs view on the file, a move needs delete on it; both need upload at the destination, whose limits apply as to an upload). The destination must be free. Within one bucket a move keeps the file's kept versions. A copy is the caller's file; a moved file keeps its owner.KoolbaseStorageFileInUseException (field, records): a move refused while records point at the file; change them first, or copy it. KoolbaseStorageNameHasHistoryException: a move to a name a deleted file's kept versions still use. Needs the Koolbase API from October 2026.Uploads you can follow and cancel, and a bucket's files (storage S1).
Uploads you can follow and cancel, and a bucket's files (storage S1).
storage.startUpload returns a KoolbaseUploadTask: progress (a stream of KoolbaseUploadProgress: pending, uploading with bytesSent of bytesTotal, verifying, then completed, failed or cancelled), cancel() until the server begins checking the bytes, and result. Only completed means the file can be referenced from a record. On iOS and Android the bytes are reported a chunk at a time; on the web the browser sends them in one piece, so progress moves from 0 to the total there.upload and uploadBytes take onProgress. The confirm now names its upload (upload_id), so it takes exactly the bytes this upload sent.storage.listFiles: a page of a bucket's files you may view -- the bucket's view rule is checked on every file -- with prefix, limit, sort (KoolbaseFileSort) and descending; pass nextCursor back for the next page. storage.getFileInfo: one file's details, with its permanent link while the bucket is public.KoolbaseUploadCancelledException, KoolbaseStorageNetworkException, KoolbaseUploadNotFoundException, KoolbaseStorageBusyException (retry shortly), KoolbaseStorageInvalidCursorException, KoolbaseStorageSignInRequiredException (nobody signed in; not a session that ended). Needs the Koolbase API from October 2026.Retry shows that it is working (#97). When a list, grid or record view's first load fails, its default view's Retry now turns into a spinner and "Retr
KoolbaseCollectionGrid showed the raw error text there; it now shows the same view. A failed retry keeps its newest error on the controller.`storage.uploadBytes`: upload a file's contents (#107B). For a file with no path on disk -- the web, where a picked file is bytes -- uploadBytes(bucke
storage.uploadBytes: upload a file's contents (#107B). For a file with no path on disk -- the web, where a picked file is bytes -- uploadBytes(bucket:, path:, bytes:) does what upload does, with the same rules (no overwrite unless asked, metadata, the content type from the path) and the same UploadResult. upload(file:) now reads the file and calls it.upload does.A refused write says which fields (#107B). A write that does not fit its collection's declared fields throws KoolbaseValidationException with fields:
KoolbaseValidationException with fields: a KoolbaseFieldProblem per field, with the field, a stable code (required, not_declared, or what the field expects: text, number, whole_number, boolean, date, datetime, choice, file) and the English problem for developers. A form can now show each under its own input, in its own words. KoolbaseError.from carries them as details['fields'] (field and code only). Needs the Koolbase API from October 2026; from an older server fields is empty, as before.KoolbaseError details.A record a list showed opens at once, on the web too (#103). getSaved() -- what KoolbaseRecordView shows while it asks the server -- now also answers
getSaved() -- what KoolbaseRecordView shows while it asks the server -- now also answers from the records this app has read while it runs, kept in memory, when there is no offline copy. The web build has no offline storage, so a detail screen opened from a list started on a loader every time. Kept per user and cleared on sign-out; at most 500; an older copy never replaces a newer one; never used as an offline edit's baseline.Sessions that last, and end cleanly (#96, #104).
Sessions that last, and end cleanly (#96, #104).
restoreSession() checks a saved session whose token has not expired yet, instead of trusting it. A session ended on the server (signed out elsewhere, revoked) restores as RestoreResult.expired and the saved copy is removed, so the app opens signed out. No network restores as offline and keeps the session.lastSignOutReason: KoolbaseSignOutReason.signedOut when the person signed out (or deleted the account), sessionEnded when the session ended on its own. An app says "Your session ended" only for the second.Sections: `KoolbaseCollectionList(groupBy: ...)`. Give each record a section key, such as its day or its status, and the list puts a header above each
KoolbaseCollectionList(groupBy: ...). Give each record a section key, such as its day or its status, and the list puts a header above each run of records with the same key. While the list scrolls by itself the current header stays pinned at the top until the next one pushes it away; with scrollsWithPage the headers sit inline. Records from Load more join the last section when they share its key. Separators are drawn between rows of a section, never around a header. Sort the query by the same field: an unsorted list repeats a header wherever its key comes back. Vertical lists only.sectionHeaderBuilder builds a header from its key; the default is the new KoolbaseSectionHeader: small muted text on an opaque background, announced as a heading.groupBy unchanged.Horizontal lists: `KoolbaseCollectionList(scrollDirection: Axis.horizontal)`. Rows sit side by side at their own width, each as tall as the tallest, s
KoolbaseCollectionList(scrollDirection: Axis.horizontal). Rows sit side by side at their own width, each as tall as the tallest, so the list needs no height, even inside a scrolling page. It scrolls sideways; the next page loads as the end comes near, and Load more stays as the last item. The default separator is a VerticalDivider, between rows only. scrollsWithPage and pull-to-refresh are vertical and do not apply. Rows must be able to say their height (a card, a column, a sized image; not a scrollable). Vertical stays the default.Offline observability: what an app needs to show offline state honestly. Same contract as @koolbase/* 12.14.0.
Offline observability: what an app needs to show offline state honestly. Same contract as @koolbase/* 12.14.0.
Koolbase.connectivity -- KoolbaseConnectivityState.unknown | online | offline, with state and changes. Whether the device reports a connection: a hint, not a promise the server is reachable. unknown until the platform first answers, so an app neither flashes "offline" nor runs online-only logic on a guess.watchPendingWrites() follows sign-in and sign-out. It re-reads for the new user (or reports signed out) instead of waiting for the queue to change. db.sessionChanged(), wired to auth by Koolbase.initialize.db.doc(id).getSaved() returns the device's saved copy (with changes queued on this device applied) without the network. KoolbaseRecordController shows it at once with isSaved true while the server is asked: success replaces it (isSaved false), failure keeps it, not found is notFound. Opening a record offline now shows the saved copy instead of an error.isFromCache true) instead of staying as it was.An offline add keeps one id. The id the app is given is now the id the record is created under when it syncs. Before, the server created the record un
Offline correctness fixes.
Realtime for signed-out visitors. With nobody signed in, live lists and live record views on a collection anyone can read (read rule public) now updat
public) now update live: the SDK connects with the project's public key. Any other collection behaves as a normal list or view until a user signs in. Needs the Koolbase API from 2026-10-04 or later. Same contract as @koolbase/* 12.13.0.KoolbaseRealtimeClient.sessionChanged() does this; Koolbase.initialize wires it to authStateChanges.Live record views: `KoolbaseRecordView(..., live: true)` (also KoolbaseRecordController(live: true)). When Koolbase realtime reports a change to THIS
KoolbaseRecordView(..., live: true) (also KoolbaseRecordController(live: true)). When Koolbase realtime reports a change to THIS record, it is read again silently -- no refreshing state -- and a burst of changes within 250 ms is one read. When it is deleted, the view shows not-found at once, and a read still in flight is dropped. Changes to other records in the collection are ignored: no extra reads. Same contract as @koolbase/* 12.12.0.liveEvents): a silent re-read on a change, other records ignored, one read for a burst, a delete at once and without a read, a delete dropping a pending re-read, no subscription unless live or without an id, and dispose unsubscribing and cancelling.Realtime subscriptions are counted exactly. Two listeners on one collection -- a live list and a live grid on the same screen -- were counted twice bu
idleGrace, 1 s). A listener back within it -- navigating back to a screen -- keeps the same connection; one after it opens a fresh one. Nothing reconnects without a subscription. Same contract as @koolbase/* 12.11.1.connector), without a server: one connection for many listeners, unsubscribing only when the last listener leaves, the close after the moment, reuse within it, a fresh connection after it, nothing opened for nobody, and recovery from a failed token.Live lists: `KoolbaseCollectionList(..., live: true)` and KoolbaseCollectionGrid(..., live: true) (also KoolbaseCollectionController(live: true)). Whe
KoolbaseCollectionList(..., live: true) and KoolbaseCollectionGrid(..., live: true)
(also KoolbaseCollectionController(live: true)). When Koolbase realtime reports a record
created, updated or deleted in the collection, the list re-reads its first page from the network,
silently -- no refreshing state -- and a burst of changes within 250 ms is one read. The list's
own query is what re-runs, so filters, order and read rules stay exactly right. A failed re-read
keeps what is shown. Same contract as @koolbase/* 12.11.0.Live lists refresh after `doc(id).update` and `doc(id).delete`. Every open query on the record's collection re-runs in the background, as it already d
doc(id).update and doc(id).delete. Every open query on the
record's collection re-runs in the background, as it already did after insert, upsert,
batch and deleteWhere; before, an update or delete through a document reference left every
list showing that collection stale until it was reloaded. A delete of a record never read on
this device refreshes every open query rather than guessing its collection
(refreshAllCollectionStreams).update or delete with
expectedRevision is refused because the record changed (KoolbaseRevisionMismatchException),
the collection's open queries re-run, so the list already shows the newer data.##, which the release workflow
reads; with # every GitHub release since the workflow began had empty notes.Merge pull request #9 from koolbase/release/12.13.0
Merge pull request #9 from koolbase/release/12.13.0
fix: KoolbaseCollectionGrid inside a scrolling page
KoolbaseCollectionGrid works inside a scrolling page: its empty state fills a height
only when there is one (it threw "BoxConstraints forces an infinite height"), and
scrollsWithPage: true lays the cells out at their natural height with Load more below
them, as the list's page mode does. The grid now renders from KoolbaseTestData too.Merge pull request #8 from koolbase/release/12.12.0
Merge pull request #8 from koolbase/release/12.12.0
feat: KoolbaseTestData, populated widget tests for lists and record views (12.12.0)
KoolbaseTestData (package:koolbase_flutter/testing.dart): records supplied to
KoolbaseCollectionList and KoolbaseRecordView in widget tests, so a screen can be
pumped populated. It replaces only the data source; controllers, paging, states and
rendering are the production code. Lists page like the server (limit, offset, exact
total); an unknown record id is not found, as the API answers. Testing and
certification infrastructure, not a local-data API.Merge pull request #7 from koolbase/release/12.11.0
Merge pull request #7 from koolbase/release/12.11.0
feat: KoolbaseCollectionList(scrollsWithPage) for a list inside a scrolling page (12.11.0)
KoolbaseCollectionList(scrollsWithPage: true), for a list inside a scrolling page.
The rows lay out at their natural height and the page does the scrolling; Load more
stays a row; pull-to-refresh belongs to the page, so the list adds none. Without it,
a list with records inside a scrolling column cannot size itself ("Vertical viewport
was given unbounded height"). The default is unchanged.Merge pull request #6 from koolbase/release/12.10.0
Merge pull request #6 from koolbase/release/12.10.0
feat: KoolbaseRecordView, one record by id as a scope (12.10.0)
KoolbaseRecordView: one record by id, as a scope. Hands the record to
builder, which returns the caller's own widget: it adds no scrolling or
layout, the way a list row's children read their record. loading,
notFound and error are slotted, with defaults. notFound covers a missing
id, a record that does not exist, one this user may not read (the API does not
tell them apart) and a record from a different collection. A changed id
starts a new load, so the same detail route opened for another record never
shows the previous one.KoolbaseRecordController: the same without the widget. A failed refresh
keeps the record shown.Merge pull request #4 from koolbase/release/12.9.0
Merge pull request #4 from koolbase/release/12.9.0
feat: analytics is opt-in, network errors carry a userMessage (12.9.0)
analyticsEnabled: true in
KoolbaseConfig to send events. While it is off, Koolbase.analytics calls do
nothing (the first logs how to turn it on), so apps that track events, and
KoolbaseNavigatorObserver(client: Koolbase.analytics), keep working.KoolbaseError.userMessage: a short message that is safe to show to people for
network errors ("We can't connect right now. Check your connection and try
again."), alongside the detailed message for developers. On the web, the
network error's message also names the page's address and Trusted Origins.Koolbase.db.invalidate(collection) forgets cached query results for a
collection, so the next query waits for the server.Two-step sign-in (MFA). Every sign-in method now throws MfaRequiredException carrying a challengeToken when the person's account has an authenticator
Two-step sign-in (MFA). Every sign-in method now throws
MfaRequiredException carrying a challengeToken when the person's account
has an authenticator on — including phone, Google and Apple, whose error
parsers all map it (a source test now enforces this for any parser added
later). verifyMfa(email: …, code: …) and verifyRecoveryCode(challengeToken: …, code: …) finish sign-in and store the session.
For managing MFA: enrollMfa(), confirmMfaEnrollment(code), mfaStatus(),
stepUpMfa(…), disableMfa(), and regenerateRecoveryCodes(). Six new
exceptions — MfaRequiredException, RecentAuthRequiredException,
RecentMfaRequiredException, MfaAlreadyEnabledException,
MfaEnrollmentNotFoundException and MfaNotEnabledException — each
registered in the error-code fidelity suite.
Sign in with an emailed code. requestEmailCode(email) sends a six-digit code; signInWithEmailCode(email: ..., code: ...) signs in and stores the sessi
Sign in with an emailed code. requestEmailCode(email) sends a
six-digit code; signInWithEmailCode(email: ..., code: ...) signs in and
stores the session exactly as login does. No password needed.
An unknown address becomes an account only while the project accepts
sign-ups, checked at the moment of sign-in. Each code works once and allows
three attempts. requestEmailCode resolves the same way whether or not the
address has an account, so it cannot be used to check who is registered.
A project can switch this off; requests then throw
EmailCodeDisabledException. The OTP exceptions phone sign-in already uses
— OtpInvalidException, OtpExpiredException, OtpMaxAttemptsException —
now come from the shared mapping, so every path that returns them throws the
class an app catches.
Reference errors are catchable. KoolbaseReferenceInvalidException,
KoolbaseReferenceInUseException, KoolbaseDanglingReferencesException
(carrying the offending records) and KoolbaseCollectionReferencedException,
for collections with declared references.
12.6.0: UploadResult exposes path and publicUrl, so a persisted uploa…
12.6.0: UploadResult exposes path and publicUrl, so a persisted uploa…
…d is never a signed URL that expires
UploadResult exposes path and publicUrl, not only a signed
downloadUrl.
downloadUrl is signed and expires, so persisting it produces a broken
image later. What to persist instead depends on the bucket: path for a
private bucket (display it through the storage client), publicUrl for a
public one — a stable CDN URL, null for a private bucket.
UploadResult also carries the bucket the object went to, which
publicUrl needs. upload() always sets it; the field is nullable only so
existing constructors keep compiling.
Found through the Designer: its exporter reads upload-result fields by
name, so a binding to an upload's path emitted code that did not compile.