Image-transformation options for KoolbaseStorageClient.publicUrl and
KoolbaseObject.publicUrl. Each field maps to one Cloudflare Image
Transformations parameter; unset fields are omitted.
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.
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 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
dependency at its core while koolbaseDataErrorFromResponse offers a
convenience wrapper.
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.
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.
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).
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.
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 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 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.
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.
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.
