@techfinityedge/koolbase-react-native 5.5.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
@@ -755,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';
@@ -828,7 +888,7 @@ try {
 ## What's included
 
 - Authentication: email + password, Apple Sign-In, Google Sign-In, phone + OTP
-- Database with offline-first cache, realtime subscriptions, and populate
+- 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)

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/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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techfinityedge/koolbase-react-native",
-  "version": "5.5.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",