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.
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.
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.
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.
