@techfinityedge/koolbase-react-native 5.4.0 → 6.0.0

package/README.md

@@ -379,6 +379,66 @@ When the device is offline, these writes are queued and synced automatically whe
 
 ---
 
+### Semantic search
+
+Find records by meaning, not just by field equality. Store an embedding
+vector on a record, then search the collection for nearest neighbors to a
+query vector — useful for similarity search over user-supplied embeddings.
+
+Declare a vector field on the collection from the dashboard or CLI first
+(picking a dimension; v1 supports 384, 768, 1024, and 1536). Then write
+and search from the SDK:
+
+```typescript
+// Set a vector for one record
+await Koolbase.db.setVector(
+  articleId,
+  'embedding',
+  await myEmbeddingModel.encode(article.content),
+);
+
+// Read it back
+const v = await Koolbase.db.getVector(articleId, 'embedding');
+console.log(`${v.vector.length}-dim, updated ${v.updatedAt}`);
+
+// Search the collection for nearest neighbors
+const result = await Koolbase.db.searchSemantic({
+  collection: 'articles',
+  field: 'embedding',
+  queryVector: await myEmbeddingModel.encode(userQuery),
+  limit: 10,
+});
+
+for (const hit of result.hits) {
+  // hit.distance is cosine distance: lower = more similar
+  // (0 = identical direction, 1 ≈ orthogonal, 2 = opposite)
+  console.log(hit.record.data.title, hit.distance.toFixed(3));
+}
+
+// Optionally scope the search with an equality filter
+const scoped = await Koolbase.db.searchSemantic({
+  collection: 'articles',
+  field: 'embedding',
+  queryVector: queryEmbedding,
+  limit: 10,
+  where: { category: 'tech' },
+});
+
+// Remove a record's vector when you no longer need it
+await Koolbase.db.deleteVector(articleId, 'embedding');
+```
+
+A few behaviors worth knowing:
+
+- **Vector length must match the declared dimension.** Mismatches throw `KoolbaseVectorDimensionMismatchError` with the expected and actual dimensions in the message.
+- **Online-only.** Vector operations are not cached locally or queued offline — HNSW similarity search has no useful offline semantics, so deferred writes could corrupt your view of what's stored.
+- **Read rule applies post-search.** Semantic search respects the collection's read rule the same way `query()` does: `owner`/`scoped`/`conditional` records are filtered to the caller after the HNSW lookup, so strict rules may return fewer than `limit` results.
+- **Higher dimensions coming.** OpenAI's `text-embedding-3-large` ships at 3072 dimensions, supported in a future release once pgvector is upgraded. In the meantime, use your model's `dimensions=1536` parameter (Matryoshka truncation) for full compatibility.
+
+See [Semantic search docs](https://docs.koolbase.com/database/vectors) for setup, dimension guidance, and embedding model recommendations.
+
+---
+
 ## Storage
 
 Upload and serve files via presigned URLs to Cloudflare R2. Uploads are
@@ -485,6 +545,64 @@ so nothing leaks.
 
 ---
 
+### Object versioning
+
+For buckets with versioning enabled, every overwrite preserves the prior
+content as a history version, and deletes are soft (recoverable until
+force-purged). Enable versioning on a bucket from the dashboard.
+
+```typescript
+// List all versions of a path, newest first
+const versions = await Koolbase.storage.listVersions('documents', 'contract.pdf');
+
+for (const v of versions) {
+  console.log(`${v.versionId}: size=${v.size} isCurrent=${v.isCurrent}`);
+}
+
+// Download a specific historical version
+const url = await Koolbase.storage.getDownloadUrl(
+  'documents',
+  'contract.pdf',
+  '019e98ed-eed6-7e71-...',
+);
+
+// Bring a history version back as current
+// (the existing current is snapshotted to history first)
+const restored = await Koolbase.storage.restoreVersion(
+  'documents',
+  'contract.pdf',
+  '019e98ed-eed6-7e71-...',
+);
+
+// Hard-remove a single history version (row + R2 bytes)
+await Koolbase.storage.purgeVersion(
+  'documents',
+  'contract.pdf',
+  'old-version-id',
+);
+
+// Wipe the entire timeline for a path - every version, every R2 key
+await Koolbase.storage.delete('documents', 'contract.pdf', true);
+```
+
+A few behaviors worth knowing:
+
+- **Overwrite snapshots automatically.** Upload to a path that already
+  exists in a versioned bucket and the prior bytes are preserved as
+  history; the upload becomes the new current.
+- **Delete is soft by default.** On a versioned bucket, `delete`
+  snapshots the current content and records a delete marker. The
+  content is still recoverable via `restoreVersion` until force-purged.
+- **Restore is itself a versioned event.** The previously-current row
+  gets snapshotted before the target's bytes overwrite canonical. The
+  restored row gets a fresh `versionId`; the target stays in history at
+  its original id - so you can always undo a restore.
+- **Delete markers can be listed but not downloaded.** A marker has
+  `size === 0`, `isDeleteMarker === true`, and no bytes. Calling
+  `getDownloadUrl` with a marker's `versionId` throws.
+
+---
+
 ## Realtime
 
 Subscribe to live changes on a collection. Uses the signed-in user's session, so
@@ -697,13 +815,13 @@ handling doesn't depend on message text.
 All data-layer failures extend `KoolbaseDataError` (which extends `Error`):
 
 | Error | When |
-| `KoolbaseStorageConflictError` | An upload targets a path that's already taken and `overwrite: false` (409, code `PATH_CONFLICT`). Exposes `.path` — the colliding path. |
-| `KoolbaseStorageNotFoundError` | The bucket or object doesn't exist (404). |
-| `KoolbaseStorageValidationError` | The request was rejected as invalid — bad path, missing field (400). |
-| `KoolbaseStoragePermissionError` | The caller is not allowed to perform the operation (403). |
-| `KoolbaseStorageQuotaError` | An upload would push the bucket past its `max_size_bytes` cap (409, code `QUOTA_EXCEEDED`). |
-| `KoolbaseStorageFileTooLargeError` | A single file exceeds the bucket's `max_file_size_bytes` cap (413, code `FILE_TOO_LARGE`). |
-| `KoolbaseStorageMimeTypeError` | The upload's content-type isn't in the bucket's `allowed_mime_types` allowlist (415, code `MIME_NOT_ALLOWED`). |
+|---|---|
+| `KoolbaseConflictError` | A write violates a unique constraint (409). Exposes `.field` — the field that collided, when the server reports it. |
+| `KoolbaseNotFoundError` | The record or collection doesn't exist (404). |
+| `KoolbaseValidationError` | The request was rejected as invalid (400). |
+| `KoolbasePermissionError` | An access rule denied the operation (403). |
+| `KoolbaseRateLimitError` | The caller is being rate-limited (429). |
+| `KoolbaseVectorDimensionMismatchError` | A vector's length doesn't match the field's declared dimension (400, code `vector_dimension_mismatch`). |
 
 ```ts
 import { KoolbaseConflictError, KoolbaseDataError } from '@techfinityedge/koolbase-react-native';
@@ -770,8 +888,8 @@ try {
 ## What's included
 
 - Authentication: email + password, Apple Sign-In, Google Sign-In, phone + OTP
-- Database with offline-first cache, realtime subscriptions, and populate
-- Storage with presigned uploads and downloads, safe-by-default conflict handling
+- Database with offline-first cache, realtime subscriptions, populate for related records, semantic search over vectors
+- Storage with presigned uploads and downloads, safe-by-default conflict handling, image transforms, object versioning (history + restore + soft-delete)
 - Realtime subscriptions over WebSocket
 - Authenticated functions (`ctx.auth` exposes the caller automatically)
 - Feature flags and remote config

package/dist/database-errors.d.ts

@@ -69,6 +69,24 @@ export declare class KoolbasePermissionError extends KoolbaseDataError {
 export declare class KoolbaseRateLimitError extends KoolbaseDataError {
     constructor(message?: string);
 }
+/**
+ * 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.
+ *
+ * @example
+ * try {
+ *   await koolbase.db.setVector(id, 'embedding', [0.1, 0.2]); // 2 dims
+ * } catch (e) {
+ *   if (e instanceof KoolbaseVectorDimensionMismatchError) {
+ *     showError(e.message); // "expected 1536, got 2"
+ *   }
+ * }
+ */
+export declare class KoolbaseVectorDimensionMismatchError extends KoolbaseDataError {
+    constructor(message?: string);
+}
 /**
  * Maps a non-2xx data-layer response to a typed {@link KoolbaseDataError},
  * preferring the server's stable `code` and falling back to the HTTP status

package/dist/database-errors.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.KoolbaseRateLimitError = exports.KoolbasePermissionError = exports.KoolbaseValidationError = exports.KoolbaseNotFoundError = exports.KoolbaseConflictError = exports.KoolbaseDataError = void 0;
+exports.KoolbaseVectorDimensionMismatchError = exports.KoolbaseRateLimitError = exports.KoolbasePermissionError = exports.KoolbaseValidationError = exports.KoolbaseNotFoundError = exports.KoolbaseConflictError = exports.KoolbaseDataError = void 0;
 exports.koolbaseDataError = koolbaseDataError;
 /**
  * Base class for errors surfaced by the Koolbase data layer (database reads
@@ -103,6 +103,29 @@ class KoolbaseRateLimitError extends KoolbaseDataError {
     }
 }
 exports.KoolbaseRateLimitError = KoolbaseRateLimitError;
+/**
+ * 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.
+ *
+ * @example
+ * try {
+ *   await koolbase.db.setVector(id, 'embedding', [0.1, 0.2]); // 2 dims
+ * } catch (e) {
+ *   if (e instanceof KoolbaseVectorDimensionMismatchError) {
+ *     showError(e.message); // "expected 1536, got 2"
+ *   }
+ * }
+ */
+class KoolbaseVectorDimensionMismatchError extends KoolbaseDataError {
+    constructor(message) {
+        super(message ?? 'Vector dimension does not match field declaration', 'vector_dimension_mismatch');
+        this.name = 'KoolbaseVectorDimensionMismatchError';
+        Object.setPrototypeOf(this, KoolbaseVectorDimensionMismatchError.prototype);
+    }
+}
+exports.KoolbaseVectorDimensionMismatchError = KoolbaseVectorDimensionMismatchError;
 /**
  * Maps a non-2xx data-layer response to a typed {@link KoolbaseDataError},
  * preferring the server's stable `code` and falling back to the HTTP status
@@ -119,13 +142,19 @@ function koolbaseDataError(status, body, fallbackMessage = 'Request failed') {
         case 'not_found':
         case 'record_not_found':
         case 'collection_not_found':
+        case 'vector_not_found':
+        case 'vector_field_not_found':
             return new KoolbaseNotFoundError(message);
         case 'permission_denied':
             return new KoolbasePermissionError(message);
         case 'rate_limit':
             return new KoolbaseRateLimitError(message);
         case 'validation_error':
+        case 'vector_collection_mismatch':
+        case 'unsupported_dimension':
             return new KoolbaseValidationError(message);
+        case 'vector_dimension_mismatch':
+            return new KoolbaseVectorDimensionMismatchError(message);
     }
     // ─── status fallback (pre-code servers) ───
     switch (status) {

package/dist/database.d.ts

@@ -1,4 +1,4 @@
-import { KoolbaseConfig, KoolbaseRecord, QueryOptions, QueryResult, UpsertResult, BatchOp, BatchResult } from './types';
+import { KoolbaseConfig, KoolbaseRecord, QueryOptions, QueryResult, UpsertResult, BatchOp, BatchResult, KoolbaseVector, SemanticSearchResult } from './types';
 export declare class KoolbaseDatabase {
     private config;
     private getUserId;
@@ -90,5 +90,83 @@ export declare class KoolbaseDatabase {
      */
     update(recordId: string, data: Record<string, unknown>): Promise<KoolbaseRecord>;
     delete(recordId: string): Promise<void>;
+    /**
+     * Write (or replace) a vector for a record on the named `field`.
+     *
+     * The field must already be declared on the collection via the dashboard
+     * or CLI. `vector.length` must match the field's declared dimension;
+     * otherwise throws `KoolbaseVectorDimensionMismatchError`.
+     *
+     * Online-only — vectors are not cached locally or queued offline because
+     * HNSW similarity search has no useful offline semantics.
+     *
+     * @example
+     * await Koolbase.db.setVector(
+     *   articleId,
+     *   'embedding',
+     *   await myEmbeddingModel.encode(article.content),
+     * );
+     */
+    setVector(recordId: string, field: string, vector: number[]): Promise<void>;
+    /**
+     * Read a record's stored vector on the named `field`.
+     *
+     * Throws `KoolbaseNotFoundError` if either the field is not declared or
+     * no vector has been set for this record on this field. Throws
+     * `KoolbasePermissionError` if the caller cannot read this record per
+     * the collection's read rule.
+     *
+     * Online-only.
+     *
+     * @example
+     * const v = await Koolbase.db.getVector(articleId, 'embedding');
+     * console.log(`${v.vector.length}-dim, updated ${v.updatedAt}`);
+     */
+    getVector(recordId: string, field: string): Promise<KoolbaseVector>;
+    /**
+     * Remove a record's stored vector on the named `field`.
+     *
+     * Online-only. Throws `KoolbaseNotFoundError` if no vector is set for
+     * `(recordId, field)`; throws `KoolbasePermissionError` if the caller
+     * cannot write this record per the collection's write rule.
+     *
+     * Note: this removes the vector from the dimension table but does NOT
+     * remove the field declaration itself — the field stays on the
+     * collection and is still settable on other records.
+     */
+    deleteVector(recordId: string, field: string): Promise<void>;
+    /**
+     * Semantic search via HNSW vector similarity.
+     *
+     * Ranks records in `collection` by cosine distance between the supplied
+     * `queryVector` and each record's stored vector on `field`. Returns up
+     * to `limit` (default 20) nearest hits, with the collection's read rule
+     * applied — owner/scoped/conditional records are filtered to the caller.
+     *
+     * `where` is an optional equality filter map on record `data` fields,
+     * applied AFTER the HNSW lookup, so very strict filters may return
+     * fewer than `limit` results.
+     *
+     * Online-only.
+     *
+     * @example
+     * const result = await Koolbase.db.searchSemantic({
+     *   collection: 'articles',
+     *   field: 'embedding',
+     *   queryVector: await myEmbeddingModel.encode(userQuery),
+     *   limit: 10,
+     *   where: { category: 'tech' },
+     * });
+     * for (const hit of result.hits) {
+     *   console.log(hit.record.data.title, hit.distance);
+     * }
+     */
+    searchSemantic(opts: {
+        collection: string;
+        field: string;
+        queryVector: number[];
+        limit?: number;
+        where?: Record<string, unknown>;
+    }): Promise<SemanticSearchResult>;
     syncPendingWrites(): Promise<void>;
 }

package/dist/database.js

@@ -319,6 +319,126 @@ class KoolbaseDatabase {
             // Queued for sync — will retry when online
         }
     }
+    // ─── Vectors ────────────────────────────────────────────────────────────────
+    /**
+     * Write (or replace) a vector for a record on the named `field`.
+     *
+     * The field must already be declared on the collection via the dashboard
+     * or CLI. `vector.length` must match the field's declared dimension;
+     * otherwise throws `KoolbaseVectorDimensionMismatchError`.
+     *
+     * Online-only — vectors are not cached locally or queued offline because
+     * HNSW similarity search has no useful offline semantics.
+     *
+     * @example
+     * await Koolbase.db.setVector(
+     *   articleId,
+     *   'embedding',
+     *   await myEmbeddingModel.encode(article.content),
+     * );
+     */
+    async setVector(recordId, field, vector) {
+        const res = await fetch(`${this.config.baseUrl}/v1/sdk/db/set-vector`, {
+            method: 'POST',
+            headers: await this.buildHeaders(),
+            body: JSON.stringify({ record_id: recordId, field, vector }),
+        });
+        if (res.status !== 204) {
+            const body = await res.json().catch(() => ({}));
+            throw (0, database_errors_1.koolbaseDataError)(res.status, body, 'Set vector failed');
+        }
+    }
+    /**
+     * Read a record's stored vector on the named `field`.
+     *
+     * Throws `KoolbaseNotFoundError` if either the field is not declared or
+     * no vector has been set for this record on this field. Throws
+     * `KoolbasePermissionError` if the caller cannot read this record per
+     * the collection's read rule.
+     *
+     * Online-only.
+     *
+     * @example
+     * const v = await Koolbase.db.getVector(articleId, 'embedding');
+     * console.log(`${v.vector.length}-dim, updated ${v.updatedAt}`);
+     */
+    async getVector(recordId, field) {
+        const raw = await this.request('POST', '/v1/sdk/db/get-vector', { record_id: recordId, field });
+        return {
+            recordId: raw.record_id,
+            fieldName: raw.field_name,
+            vector: raw.vector,
+            createdAt: raw.created_at,
+            updatedAt: raw.updated_at,
+        };
+    }
+    /**
+     * Remove a record's stored vector on the named `field`.
+     *
+     * Online-only. Throws `KoolbaseNotFoundError` if no vector is set for
+     * `(recordId, field)`; throws `KoolbasePermissionError` if the caller
+     * cannot write this record per the collection's write rule.
+     *
+     * Note: this removes the vector from the dimension table but does NOT
+     * remove the field declaration itself — the field stays on the
+     * collection and is still settable on other records.
+     */
+    async deleteVector(recordId, field) {
+        const res = await fetch(`${this.config.baseUrl}/v1/sdk/db/delete-vector`, {
+            method: 'POST',
+            headers: await this.buildHeaders(),
+            body: JSON.stringify({ record_id: recordId, field }),
+        });
+        if (res.status !== 204) {
+            const body = await res.json().catch(() => ({}));
+            throw (0, database_errors_1.koolbaseDataError)(res.status, body, 'Delete vector failed');
+        }
+    }
+    /**
+     * Semantic search via HNSW vector similarity.
+     *
+     * Ranks records in `collection` by cosine distance between the supplied
+     * `queryVector` and each record's stored vector on `field`. Returns up
+     * to `limit` (default 20) nearest hits, with the collection's read rule
+     * applied — owner/scoped/conditional records are filtered to the caller.
+     *
+     * `where` is an optional equality filter map on record `data` fields,
+     * applied AFTER the HNSW lookup, so very strict filters may return
+     * fewer than `limit` results.
+     *
+     * Online-only.
+     *
+     * @example
+     * const result = await Koolbase.db.searchSemantic({
+     *   collection: 'articles',
+     *   field: 'embedding',
+     *   queryVector: await myEmbeddingModel.encode(userQuery),
+     *   limit: 10,
+     *   where: { category: 'tech' },
+     * });
+     * for (const hit of result.hits) {
+     *   console.log(hit.record.data.title, hit.distance);
+     * }
+     */
+    async searchSemantic(opts) {
+        const body = {
+            collection: opts.collection,
+            field: opts.field,
+            query_vector: opts.queryVector,
+            limit: opts.limit ?? 20,
+        };
+        if (opts.where && Object.keys(opts.where).length > 0) {
+            body.where = opts.where;
+        }
+        const raw = await this.request('POST', '/v1/sdk/db/search-semantic', body);
+        return {
+            hits: (raw.results ?? []).map(r => ({
+                record: (0, record_1.recordFromWire)(r.record),
+                distance: r.distance,
+            })),
+            total: raw.total ?? (raw.results ?? []).length,
+        };
+    }
     // ─── Manual sync ────────────────────────────────────────────────────────────
     async syncPendingWrites() {
         await this.syncEngine.flush();

package/dist/storage.d.ts

@@ -1,4 +1,4 @@
-import { KoolbaseConfig, UploadOptions, UploadResult, KoolbaseObject, KoolbaseImageTransform } from './types';
+import { KoolbaseConfig, UploadOptions, UploadResult, KoolbaseObject, KoolbaseObjectVersion, KoolbaseImageTransform } from './types';
 /**
  * Koolbase storage client — uploads, downloads, and deletes via presigned
  * Cloudflare R2 URLs.
@@ -72,7 +72,7 @@ export declare class KoolbaseStorage {
     /**
      * Get a signed download URL for a file.
      */
-    getDownloadUrl(bucket: string, path: string): Promise<string>;
+    getDownloadUrl(bucket: string, path: string, versionId?: string): Promise<string>;
     /**
      * Build the stable public CDN URL for a file in a public bucket.
      *
@@ -145,5 +145,40 @@ export declare class KoolbaseStorage {
     /**
      * Delete a file from a bucket.
      */
-    delete(bucket: string, path: string): Promise<void>;
+    delete(bucket: string, path: string, forcePurge?: boolean): Promise<void>;
+    /**
+     * List all versions of a file path, newest-first. Returns a flat list
+     * mixing the current row (with `isCurrent: true`) and all history
+     * rows. Delete markers are included so callers can render the full
+     * timeline; filter client-side to hide them if the UI only wants
+     * restorable versions.
+     *
+     * Returns an empty array (not an error) when the path has no history
+     * and no current row.
+     */
+    listVersions(bucket: string, path: string): Promise<KoolbaseObjectVersion[]>;
+    /**
+     * Fetch metadata for a single version by id. Works against both the
+     * current row and any history row — the response's `isCurrent` tells
+     * you which.
+     */
+    getVersion(bucket: string, path: string, versionId: string): Promise<KoolbaseObjectVersion>;
+    /**
+     * Bring a history version back as the current version. The
+     * previously-current row (if any) is snapshotted into history first,
+     * so this operation is itself a versioned event you can undo. The
+     * restored row gets a freshly-minted version_id; the target stays in
+     * history at its original version_id.
+     *
+     * Throws if the bucket has versioning off, if the target is the
+     * already-current version, or if the target is a delete marker.
+     */
+    restoreVersion(bucket: string, path: string, versionId: string): Promise<KoolbaseObject>;
+    /**
+     * Hard-remove a single history version — both the metadata row and
+     * the .versions/ R2 bytes (or just the row, for delete markers).
+     * Refuses to operate on the current version; use {@link delete} with
+     * `forcePurge: true` to wipe everything for a path.
+     */
+    purgeVersion(bucket: string, path: string, versionId: string): Promise<void>;
 }

package/dist/storage.js

@@ -195,9 +195,12 @@ class KoolbaseStorage {
     /**
      * Get a signed download URL for a file.
      */
-    async getDownloadUrl(bucket, path) {
-        const url = `${this.config.baseUrl}/v1/sdk/storage/download-url` +
+    async getDownloadUrl(bucket, path, versionId) {
+        let url = `${this.config.baseUrl}/v1/sdk/storage/download-url` +
             `?bucket=${encodeURIComponent(bucket)}&path=${encodeURIComponent(path)}`;
+        if (versionId) {
+            url += `&version_id=${encodeURIComponent(versionId)}`;
+        }
         const res = await fetch(url, { headers: await this.buildHeaders() });
         if (!res.ok) {
             throw await (0, storage_errors_1.koolbaseStorageErrorFromResponse)(res, 'Failed to get download URL');
@@ -289,8 +292,11 @@ class KoolbaseStorage {
     /**
      * Delete a file from a bucket.
      */
-    async delete(bucket, path) {
-        const res = await fetch(`${this.config.baseUrl}/v1/sdk/storage/object`, {
+    async delete(bucket, path, forcePurge) {
+        const url = forcePurge
+            ? `${this.config.baseUrl}/v1/sdk/storage/object?force_purge=true`
+            : `${this.config.baseUrl}/v1/sdk/storage/object`;
+        const res = await fetch(url, {
             method: 'DELETE',
             headers: {
                 ...(await this.buildHeaders()),
@@ -304,6 +310,82 @@ class KoolbaseStorage {
             throw await (0, storage_errors_1.koolbaseStorageErrorFromResponse)(res, 'Failed to delete file');
         }
     }
+    /**
+     * List all versions of a file path, newest-first. Returns a flat list
+     * mixing the current row (with `isCurrent: true`) and all history
+     * rows. Delete markers are included so callers can render the full
+     * timeline; filter client-side to hide them if the UI only wants
+     * restorable versions.
+     *
+     * Returns an empty array (not an error) when the path has no history
+     * and no current row.
+     */
+    async listVersions(bucket, path) {
+        const url = `${this.config.baseUrl}/v1/sdk/storage/object-versions` +
+            `?bucket=${encodeURIComponent(bucket)}&path=${encodeURIComponent(path)}`;
+        const res = await fetch(url, { headers: await this.buildHeaders() });
+        if (!res.ok) {
+            throw await (0, storage_errors_1.koolbaseStorageErrorFromResponse)(res, 'Failed to list versions');
+        }
+        const data = (await res.json());
+        const list = Array.isArray(data.versions) ? data.versions : [];
+        return list.map((v) => fromVersionJson(v));
+    }
+    /**
+     * Fetch metadata for a single version by id. Works against both the
+     * current row and any history row — the response's `isCurrent` tells
+     * you which.
+     */
+    async getVersion(bucket, path, versionId) {
+        const url = `${this.config.baseUrl}/v1/sdk/storage/object-versions/${encodeURIComponent(versionId)}` +
+            `?bucket=${encodeURIComponent(bucket)}&path=${encodeURIComponent(path)}`;
+        const res = await fetch(url, { headers: await this.buildHeaders() });
+        if (!res.ok) {
+            throw await (0, storage_errors_1.koolbaseStorageErrorFromResponse)(res, 'Failed to fetch version');
+        }
+        return fromVersionJson((await res.json()));
+    }
+    /**
+     * Bring a history version back as the current version. The
+     * previously-current row (if any) is snapshotted into history first,
+     * so this operation is itself a versioned event you can undo. The
+     * restored row gets a freshly-minted version_id; the target stays in
+     * history at its original version_id.
+     *
+     * Throws if the bucket has versioning off, if the target is the
+     * already-current version, or if the target is a delete marker.
+     */
+    async restoreVersion(bucket, path, versionId) {
+        const url = `${this.config.baseUrl}/v1/sdk/storage/object-versions/${encodeURIComponent(versionId)}/restore` +
+            `?bucket=${encodeURIComponent(bucket)}&path=${encodeURIComponent(path)}`;
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: await this.buildHeaders(),
+        });
+        if (!res.ok) {
+            throw await (0, storage_errors_1.koolbaseStorageErrorFromResponse)(res, 'Failed to restore version');
+        }
+        return mapObjectFromServer(await res.json());
+    }
+    /**
+     * Hard-remove a single history version — both the metadata row and
+     * the .versions/ R2 bytes (or just the row, for delete markers).
+     * Refuses to operate on the current version; use {@link delete} with
+     * `forcePurge: true` to wipe everything for a path.
+     */
+    async purgeVersion(bucket, path, versionId) {
+        const url = `${this.config.baseUrl}/v1/sdk/storage/object-versions/${encodeURIComponent(versionId)}` +
+            `?bucket=${encodeURIComponent(bucket)}&path=${encodeURIComponent(path)}`;
+        const res = await fetch(url, {
+            method: 'DELETE',
+            headers: await this.buildHeaders(),
+        });
+        if (res.status === 204)
+            return;
+        if (!res.ok) {
+            throw await (0, storage_errors_1.koolbaseStorageErrorFromResponse)(res, 'Failed to purge version');
+        }
+    }
 }
 exports.KoolbaseStorage = KoolbaseStorage;
 /**
@@ -327,3 +409,30 @@ function mapObjectFromServer(raw) {
         updatedAt: raw.updated_at,
     };
 }
+/**
+ * Maps the snake_case server JSON of a version row to the camelCase
+ * {@link KoolbaseObjectVersion}. Mirrors `fromObjectJson` shape.
+ */
+function fromVersionJson(j) {
+    const rawMeta = j.metadata;
+    const metadata = {};
+    if (rawMeta && typeof rawMeta === 'object') {
+        for (const [k, v] of Object.entries(rawMeta)) {
+            if (typeof v === 'string')
+                metadata[k] = v;
+        }
+    }
+    return {
+        versionId: j.version_id ?? null,
+        path: j.path,
+        size: Number(j.size ?? 0),
+        contentType: j.content_type ?? null,
+        etag: j.etag ?? null,
+        metadata,
+        r2Bucket: j.r2_bucket ?? '',
+        userId: j.user_id ?? null,
+        isDeleteMarker: Boolean(j.is_delete_marker),
+        isCurrent: Boolean(j.is_current),
+        createdAt: j.created_at,
+    };
+}

package/dist/types.d.ts

@@ -147,6 +147,41 @@ export interface PendingWrite {
     retries: number;
     createdAt: string;
 }
+/**
+ * A stored vector retrieved by `KoolbaseDatabase.getVector()`. The `vector`
+ * field carries the float values exactly as stored on the server; the
+ * `recordId` + `fieldName` pair identifies which slot they came from.
+ */
+export interface KoolbaseVector {
+    recordId: string;
+    fieldName: string;
+    vector: number[];
+    /** ISO 8601 timestamp from the server. */
+    createdAt: string;
+    /** ISO 8601 timestamp from the server. */
+    updatedAt: string;
+}
+/**
+ * One ranked hit from `KoolbaseDatabase.searchSemantic()`. `record` is
+ * the full record (same wire shape as a record returned by query/get).
+ * `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).
+ */
+export interface KoolbaseSemanticHit {
+    record: KoolbaseRecord;
+    distance: number;
+}
+/**
+ * Result of `KoolbaseDatabase.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).
+ */
+export interface SemanticSearchResult {
+    hits: KoolbaseSemanticHit[];
+    total: number;
+}
 export interface UploadOptions {
     bucket: string;
     path: string;
@@ -212,6 +247,48 @@ export interface KoolbaseObject {
     /** ISO 8601 timestamp from the server. */
     updatedAt: string;
 }
+/**
+ * One entry in an object's version timeline. Covers both the current
+ * row (when {@link isCurrent} is true) and every history row, including
+ * soft-delete markers (when {@link isDeleteMarker} is true — size 0, no
+ * fetchable bytes). Returned from {@link KoolbaseStorage.listVersions}
+ * and {@link KoolbaseStorage.getVersion}; the underlying bytes are
+ * downloadable via {@link KoolbaseStorage.getDownloadUrl} with the
+ * `versionId` argument.
+ *
+ * `versionId` may be null only on legacy rows uploaded before versioning
+ * was enabled on the bucket — for those, {@link isCurrent} is true and
+ * the row carries no history identity yet (gets backfilled on the next
+ * overwrite).
+ */
+export interface KoolbaseObjectVersion {
+    versionId: string | null;
+    path: string;
+    size: number;
+    contentType: string | null;
+    etag: string | null;
+    metadata: Record<string, string>;
+    r2Bucket: string;
+    userId: string | null;
+    /**
+     * True for a tombstone row recording a soft-delete event. Size is 0
+     * and there are no R2 bytes — treat as "the path was deleted at this
+     * time" rather than fetchable content.
+     */
+    isDeleteMarker: boolean;
+    /**
+     * True for the row that currently lives in `storage_objects` (i.e.
+     * what a no-versionId download returns). False for everything in
+     * `storage_object_versions`.
+     */
+    isCurrent: boolean;
+    /**
+     * For the current row this is the time the current version became
+     * current (overwrite or upload time). For history rows it's the time
+     * the version was originally uploaded.
+     */
+    createdAt: string;
+}
 /**
  * Result of a successful `KoolbaseStorage.upload()` call.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techfinityedge/koolbase-react-native",
-  "version": "5.4.0",
+  "version": "6.0.0",
   "description": "React Native SDK for Koolbase — auth, database, storage, realtime, feature flags, and functions in one package.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",