In-memory storage for tests. Holds a session for the life of the
object and forgets it after; never touches the keychain. Also what
Koolbase.initializeForTesting uses, so an auth gate can restore to
signed-out and render its children without a platform channel.
A bucket's files as a list (storage S4): only the files the signed-in
person may view, a page at a time, with pull to refresh and Load more.
It reloads by itself after an upload, delete, move, copy, metadata
change or restore made through this SDK in the bucket.
One file's details, by path, handed to builder (storage S4) -- a SCOPE,
not a screen: it adds no scrolling and no layout of its own, like
KoolbaseRecordView. Only a file the signed-in person may view is
shown; anything else is notFound. Loading, not found and error are
slotted. A change made through this SDK in the bucket shows by itself:
deleted or moved away, the file is notFound; replaced, its new size.
Image-transformation options for KoolbaseStorageClient.publicUrl and
KoolbaseObject.publicUrl. Each field maps to one Cloudflare Image
Transformations parameter; unset fields are omitted.
One record of a collection, by id, handed to builder -- a SCOPE, not a
screen: it adds no scrolling and no layout of its own. The widget
builder returns is the caller's, and everything inside it reads the
record it was given, as a list row's children read theirs. Loading,
not-found and error are slotted.
The default section header of KoolbaseCollectionList.groupBy: the
label in small, muted text on an opaque background (so it can pin over
rows), announced as a heading.
One ranked hit from a semantic search. record carries the full
record (same wire shape as a record returned by query/get), and
distance is the cosine distance between the query vector and the
stored vector — lower means more similar. Range: 0 (identical
direction) to 2 (opposite direction).
Result of KoolbaseQuery.searchSemantic. hits is the ranked list
of nearest neighbors (best match first); total is the count of
hits returned (matches hits.length in v1 — preserved as a separate
field for future pagination).
A stored vector retrieved by KoolbaseDocRef.getVector. The vector
field carries the float values exactly as stored on the server, and
the field-name + record-id pair identifies which slot they came from.
System B (VM-level) code-push client — companion to KoolbaseCodePushClient
(System A runtime bundles). This one ships compiled-Dart patches: it checks
the resolver for a patch matching the running binary, downloads the signed
.kbpatch, and stages it where the patched Flutter engine reads it at the
NEXT cold launch. The engine verifies (Ed25519 + build_id) and applies
before any Dart runs, then renames the staged file to mark it applied; on the
following launch this client reconciles that into the persisted current_patch.
One open realtime connection, as the client uses it: what arrives, how to
send, how to close. The client opens it through a RealtimeConnector, so
its lifecycle can be tested without a server.
What the user was trying to do when the write was refused.
insert since unique constraints made insert-conflicts real: a queued
insert refused as a duplicate is held like any other terminal refusal.
Resolving one IS the insert, retried — resolveWithMerge carries amended
data (the "fix the colliding title" path); resolveWithServer means the
colliding row stands, and clears without a request.
Output format for image transformations served via Cloudflare's
/cdn-cgi/image/ URL prefix. auto negotiates the best modern format
(typically webp or avif) based on the requesting browser's Accept
header; pin an explicit format only when you need deterministic output.
Why the last session ended (#104): the person signed out, or the session
ended on its own -- revoked, past renewal, signed out on another device.
An app tells them apart to say "You were signed out" only when the person
did not ask to be.
Maps a non-2xx storage-layer response to a typed
KoolbaseStorageException, preferring the server's stable code and
falling back to the HTTP status for older or uncoded responses. The
caller decodes the body once and passes (statusCode, body); this
keeps the mapper free of an http dependency at its core while
koolbaseStorageErrorFromResponse offers a convenience wrapper.
Thrown when the account is temporarily locked due to too many failed
login attempts (brute-force protection). The server uses progressive
5/10/20-attempt lockouts; if an unlock email was issued (level 2+),
the user can clear the lock by clicking that link, which calls
KoolbaseAuthClient.unlock with the token.
The project has switched off signing in with an emailed code — 403
email_code_disabled. Applies to every address alike, so it reveals
nothing about which accounts exist.
Thrown when a fiscal operation fails for non-auth reasons: network
errors, malformed responses, or server-side refusals. Carries the
HTTP status when one was received.
The API key's scope is below what the operation requires. Scopes rank
read < write < admin. The key is valid — a different key or a dashboard
session is needed, so do not tell the user to sign in again.
The current password given to changePassword did not match, 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
which sign-in methods an account has.
Thrown when a collection cannot be deleted because another collection has
a reference field pointing at it — 409 collection_referenced. Remove
that reference first.
Base class for errors surfaced by the Koolbase data layer (database
reads and writes). Every data error carries a human-readable message
and, when the server provides one, its stable code (e.g. not_found,
validation_error, unique_violation).
Authenticated, and not permitted to do this — a destructive operation
such as a seed overwrite or a snapshot restore. Distinct from
KoolbasePermissionException, which is a rule denying a record.
Thrown when the requested record or collection does not exist — the
server responds with 404 and code not_found / record_not_found /
collection_not_found.
Maps a non-2xx data-layer response to a typed KoolbaseDataException,
preferring the server's stable code and falling back to the HTTP status
for older or uncoded responses. The caller decodes the body once and
passes (statusCode, body); this keeps the mapper free of an http
Thrown when the server rejects the session token itself — expired, revoked,
or belonging to a different project than the one this app is configured for.
Thrown when the caller is authenticated but not allowed to perform the
operation — the server responds with 403 and code permission_denied
(typically a collection access rule rejecting the write/read).
Thrown when a write (insert, update, or upsert) is rejected because the
value would violate a collection's unique constraint — the server responds
with 409 Conflict and code unique_violation. Catch this to handle
duplicates, e.g. an email or username that's already taken.
A seed or import operation was refused. code says which stage:
invalid_seed_file, seed_key_not_unique, seed_needs_decision, or
seed_conflicts_require_force. One class rather than four: these are
dashboard and CLI operations, and a caller handles them the same way —
show the reason and let a human decide.
Thrown when an upload is rejected because an object already exists at
the requested path — the server responds with 409 Conflict and code
path_conflict. Catch this to give the user an "overwrite this file?"
prompt, then retry the upload with overwrite: true.
Base class for errors surfaced by the Koolbase storage layer (uploads,
downloads, deletes, and bucket/object operations). Every storage error
carries a human-readable message and, when the server provides one,
its stable code (e.g. path_conflict).
Thrown when a single file exceeds the bucket's configured
max_file_size_bytes — the server responds with 413 Payload Too Large
and code file_too_large. The server cleans up the underlying R2
object before returning. The configured per-file limit lives on the
bucket record; check Bucket.maxFileSizeBytes to surface a clear
"files must be under X MB" message at the call site.
Thrown when an object metadata payload (either at upload-confirm time
or via updateMetadata) fails server-side validation — the server
responds with 400 and code metadata_invalid.
Thrown when an upload's content-type isn't in the bucket's configured
allowed_mime_types allowlist — the server responds with 415
Unsupported Media Type and code mime_not_allowed. The check runs at
presign time, so no bytes are transferred before rejection.
Thrown when the requested bucket or object does not exist — the server
responds with 404. Also surfaced for cross-tenant access attempts
(Koolbase's 404-over-403 convention prevents enumeration in
multi-tenant contexts).
Thrown by KoolbaseStorageClient.publicUrlFor when the SDK has not yet
learned which project it belongs to. Project identity arrives with the
bootstrap payload (and persists in its cache); it is unavailable when the
very first bootstrap has not completed — a fresh install starting
offline — or when the server predates identity metadata.
Thrown when an upload would push the bucket past its configured
max_size_bytes quota — the server responds with 409 Conflict and code
quota_exceeded. The server cleans up the underlying R2 object before
returning; nothing leaks. Catch this to surface a "bucket is full"
message or prompt the caller to delete older files. The per-bucket
quota is set at bucket creation time and is currently immutable.
Minting a presigned upload URL failed. Not the user's doing and not a
retry they can fix — distinct from KoolbaseUploadExpiredException,
which is a retry that will work.
Thrown when the supplied vector's length does not match the dimension
declared on the collection's vector field — the server responds with
400 and code vector_dimension_mismatch. The message includes both
the expected and actual dimensions so you can surface a precise error.
The first factor passed, and this account needs a second: sign-in is not
finished. Pass challengeToken to verifyMfa with a code from the
person's authenticator app, or to verifyRecoveryCode. Apps that never
enable MFA never see this.
Connecting a Google or Apple identity that another account already holds.
About the provider identity itself, where AccountExistsException is
about the email.
Thrown when the server rate-limits a non-phone authentication endpoint
(HTTP 429 without the "account temporarily locked" marker). Phone OTP
endpoints throw OtpRateLimitException instead — they have a separate
rate-limiter on the server.
Thrown when the access token references a session that has been
revoked centrally — either by the user (via the sessions endpoint) or
by an administrator. Distinct from SessionExpiredException which
indicates the access token TTL elapsed without a successful refresh.
Thrown when the unlock token (from a brute-force unlock email) is
invalid or expired. Unlock tokens are one-shot — once consumed, the
same token can't be reused.
