v9.0.0

Breaking changes

• Package renamed from @techfinityedge/koolbase-react-native to @koolbase/react-native for brand consistency with the rest of the Koolbase SDKs and tooling. This is the only change in this release — the API surface, behavior, and exports are identical to 8.0.0.
• Migration: replace the dependency in package.json (@techfinityedge/koolbase-react-native → @koolbase/react-native) and update every import path accordingly. No code changes beyond the import specifier are required. The old package is deprecated on npm and will receive no further updates.

v8.0.0

Breaking changes

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

Added

• KoolbaseDatabase.searchSemantic accepts a new mode parameter of
  type SearchMode. Three retrieval strategies are supported:
  • 'semantic' (default) — pure vector search via HNSW on cosine
    distance. Best for fuzzy / conceptual queries.
  • 'lexical' — pure BM25 over the field's source text via Postgres
    ts_rank_cd. Best for exact terms, codes, names, acronyms.
  • 'hybrid' — vector + lexical fused with reciprocal rank fusion
    (k=60). Generally the strongest default for production search.
• KoolbaseDatabase.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).
• New SearchMode type exported from @techfinityedge/koolbase-react-native.

Server requirements

• Requires Koolbase API release with hybrid search shipped (June 8 2026
  or later).
• Lexical and hybrid modes require the vector field to have a
  source_field configured. The lexical sidecar table populates
  automatically on record write via the same hook that drives auto-embed.

v7.0.0

Breaking changes

• KoolbaseDatabase.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 Error otherwise.

Added

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

Server requirements

• Requires Koolbase API release 771728d or later (Phase 2 Stage A3a).
• Auto-embed on record write is automatic once a vector field has its
  embedding_provider, embedding_model, and source_field configured
  (see docs).

v6.0.0

feat: v6.0.0 — vector search SDK methods (setVector / getVector / del…

v5.5.0

feat(storage): object versioning - listVersions, getVersion, restoreV…

v5.4.0

feat(storage): edge image transforms (Gap #8) — v5.4.0

KoolbaseImageTransform type + format/fit/gravity unions for direct
transforms via Cloudflare /cdn-cgi/image/. Named presets via
publicUrlWithPreset resolving server-managed option sets at
cdn.koolbase.com/p/{project_id}/{preset_name}/...

- KoolbaseStorage.publicUrl({..., transform}) — optional opts
- KoolbaseStorage.publicUrlWithPreset({...})
- KoolbaseStorage.publicUrlForObjectWithPreset(obj, bucket, name)
- README: new Image transforms section
- CHANGELOG: 5.4.0 entry

Additive, backward-compatible. Existing publicUrl calls without
transform unchanged.

v5.3.0

feat(storage): public bucket CDN URLs (Gap #2 SDK polish, v5.3.0)

Code ready; npm publish DEFERRED — local build blocked on Node engine
mismatch (current 20.19.0, react-native@0.85 + transitive
metro-runtime require ≥20.19.4). Same blocker affects @types/react-native
and direct react-native install equally. Resolves with `nvm install 20`
(or any 20.19.4+) — orthogonal to the SDK code in this commit.

Parallel to koolbase_flutter v6.3.0 (just published to pub.dev). When
the build env is unblocked, run `yarn build && npm publish` from main
to ship v5.3.0 to npm. No further code changes required.

types.ts — KoolbaseObject

  Adds r2Bucket: string carrying the physical R2 bucket the object's
  bytes live in. 'koolbase-storage-public' means the object has a
  stable CDN URL; anything else (typically 'koolbase-storage') means
  it lives in private storage and reads go through a presigned URL.

storage.ts — KoolbaseStorage

  Object JSON mapper extended to surface server's r2_bucket field as
  r2Bucket. Defaults to 'koolbase-storage' when absent (older cached
  responses, non-Koolbase JSON) — matches server migration default.

  Two new static methods:

  publicUrl({ projectId, bucket, path }) -> string
    Build-time helper. Returns the CDN URL pattern unconditionally,
    no public-bucket check. Use when you have the inputs and want
    the URL (SSR, static gen, batch).

  publicUrlForObject(obj, bucket) -> string | null
    Safer constructor for when you have a KoolbaseObject. Returns
    null for private-bucket objects and for legacy public-bucket
    files still in private R2.

  Both methods encode each path segment with encodeURIComponent then
  rejoin on '/' — preserves slash separators while escaping spaces,
  parens, hashes, query characters.

README + CHANGELOG

  README Storage section gains a 'Public bucket URLs' subsection
  between the main upload/download example and 'Handling upload
  conflicts'. CHANGELOG entry under 5.3.0 follows the same shape as
  v6.3.0 on the Flutter side.

No breaking changes to public API.

v5.2.0

Added — storage

• Custom object metadata. Attach arbitrary key/value pairs to stored
  objects at upload time, mutate via merge semantics post-upload, read
  alongside any KoolbaseObject.
  • KoolbaseStorage.upload({ metadata }) accepts an optional
    metadata: Record<string, string> field on UploadOptions. 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).
  • New KoolbaseStorage.updateMetadata(bucket, path, metadata)
    method with merge semantics: keys with a non-null string 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: Record<string, string> field.
    Always non-null — empty object {} when no metadata is set —
    so callers can treat it as a guaranteed record without null
    checks. Defensive decode handles missing/null metadata field
    gracefully so older cached responses don't crash the mapper.
• New KoolbaseStorageMetadataInvalidError (extends
  KoolbaseStorageError) thrown for server-side validation
  failures (HTTP 400, code metadata_invalid). 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.
• Mapper recognizes metadata_invalid and extracts detail from the
  response body.

Notes

• Validation rules (enforced server-side): ≤50 keys per object, ≤8KB
  total (sum of all key + value lengths), keys 1–64 chars matching
  [a-z0-9_]+, values ≤1024 chars, leading underscore reserved for
  system keys.
• Backwards-compatible: pure additive surface. v5.1.1 → v5.2.0. Existing
  upload() callers without metadata continue working unchanged;
  catching KoolbaseStorageError still catches the new metadata error.
• Pairs with koolbase_flutter v6.2.0 (published earlier today). Same
  client surface (upload({ metadata }), updateMetadata), same error
  type semantics, same merge contract.

v5.1.0

Added — storage

• Three new typed errors covering the bucket-limit failure modes
  introduced server-side in Storage #2. All extend
  KoolbaseStorageError, so existing instanceof KoolbaseStorageError
  catch-all blocks continue to work; check the specific type to branch
  on the kind of limit hit.
  • KoolbaseStorageQuotaError — 409 + QUOTA_EXCEEDED, thrown when
    an upload would push the bucket past its max_size_bytes cap.
  • KoolbaseStorageFileTooLargeError — 413 + FILE_TOO_LARGE, thrown
    when a single file exceeds the bucket's max_file_size_bytes cap.
  • KoolbaseStorageMimeTypeError — 415 + MIME_NOT_ALLOWED, thrown
    when an upload's content-type isn't in the bucket's
    allowed_mime_types allowlist (supports type/* wildcards).
• Mapper (koolbaseStorageError / koolbaseStorageErrorFromResponse)
  recognizes the new codes via code-first lookup and the new HTTP
  statuses (413, 415) via status fallback.

Notes

• Backwards-compatible: pure additive surface. v5.0.0 → v5.1.0.
• Status-fallback for 409 remains KoolbaseStorageConflictError (path
  collisions are the more common case); modern servers always emit
  code, so the ambiguity only affects very old API responses.
• Pairs with koolbase_flutter v6.1.0 (published earlier today). Same
  three error types, same code-first mapper extension.