@koolbase/react-native 9.1.0 → 10.0.0

package/dist/database-errors.js

@@ -1,173 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-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
- * and writes). Every data error carries a `message` and, when the server
- * provides one, its stable `code` (e.g. `not_found`, `validation_error`,
- * `unique_violation`).
- *
- * Catch this to handle any data-layer failure generically, or catch a
- * specific subclass to branch on the kind of failure.
- */
-class KoolbaseDataError extends Error {
-    constructor(message, code) {
-        super(message);
-        this.code = code;
-        this.name = 'KoolbaseDataError';
-        Object.setPrototypeOf(this, KoolbaseDataError.prototype);
-    }
-}
-exports.KoolbaseDataError = KoolbaseDataError;
-/**
- * Thrown when a write is rejected because the value would violate a
- * collection's unique constraint — the server responds with 409 Conflict.
- * Catch it to handle duplicates, e.g. an email or username already in use.
- *
- * `field` names the field that collided, when the server reports it
- * (`details.field`) — useful when a collection has more than one unique
- * constraint and you need to know which value clashed.
- *
- * Surfaced by `insert`, `update`, and `upsert` whenever the server is
- * reachable and rejects the write with a 409. These writes are online-first:
- * a server-side conflict throws immediately. Only a genuine network failure
- * falls back to the offline queue, where a conflict that surfaces at sync
- * time is handled by the sync engine rather than thrown here.
- *
- * @example
- * try {
- *   await koolbase.db.upsert('users', { email }, { name });
- * } catch (e) {
- *   if (e instanceof KoolbaseConflictError) {
- *     showError(`That ${e.field ?? 'value'} is already registered.`);
- *   }
- * }
- */
-class KoolbaseConflictError extends KoolbaseDataError {
-    constructor(message, field) {
-        super(message ?? 'Value violates a unique constraint', 'unique_violation');
-        this.field = field;
-        this.name = 'KoolbaseConflictError';
-        Object.setPrototypeOf(this, KoolbaseConflictError.prototype);
-    }
-}
-exports.KoolbaseConflictError = KoolbaseConflictError;
-/**
- * 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`.
- */
-class KoolbaseNotFoundError extends KoolbaseDataError {
-    constructor(message) {
-        super(message ?? 'The requested resource was not found', 'not_found');
-        this.name = 'KoolbaseNotFoundError';
-        Object.setPrototypeOf(this, KoolbaseNotFoundError.prototype);
-    }
-}
-exports.KoolbaseNotFoundError = KoolbaseNotFoundError;
-/**
- * Thrown when the request is rejected as invalid — the server responds with
- * 400 and code `validation_error`.
- */
-class KoolbaseValidationError extends KoolbaseDataError {
-    constructor(message) {
-        super(message ?? 'The request was invalid', 'validation_error');
-        this.name = 'KoolbaseValidationError';
-        Object.setPrototypeOf(this, KoolbaseValidationError.prototype);
-    }
-}
-exports.KoolbaseValidationError = KoolbaseValidationError;
-/**
- * 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 read/write).
- */
-class KoolbasePermissionError extends KoolbaseDataError {
-    constructor(message) {
-        super(message ?? 'You do not have permission to perform this action', 'permission_denied');
-        this.name = 'KoolbasePermissionError';
-        Object.setPrototypeOf(this, KoolbasePermissionError.prototype);
-    }
-}
-exports.KoolbasePermissionError = KoolbasePermissionError;
-/**
- * Thrown when the server is rate-limiting the caller — 429 with code
- * `rate_limit`. Back off and retry after a short delay.
- */
-class KoolbaseRateLimitError extends KoolbaseDataError {
-    constructor(message) {
-        super(message ?? 'Too many requests, please slow down', 'rate_limit');
-        this.name = 'KoolbaseRateLimitError';
-        Object.setPrototypeOf(this, KoolbaseRateLimitError.prototype);
-    }
-}
-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
- * for older or uncoded responses. Always returns an error to throw.
- */
-function koolbaseDataError(status, body, fallbackMessage = 'Request failed') {
-    const code = body?.code;
-    const message = body?.error ?? fallbackMessage;
-    const field = body?.details?.field;
-    // ─── code-first ───
-    switch (code) {
-        case 'unique_violation':
-            return new KoolbaseConflictError(message, field);
-        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) {
-        case 409:
-            return new KoolbaseConflictError(message);
-        case 404:
-            return new KoolbaseNotFoundError(message);
-        case 403:
-            return new KoolbasePermissionError(message);
-        case 429:
-            return new KoolbaseRateLimitError(message);
-        case 400:
-            return new KoolbaseValidationError(message);
-    }
-    return new KoolbaseDataError(message, code);
-}

package/dist/database.d.ts

@@ -1,208 +0,0 @@
-import { KoolbaseConfig, KoolbaseRecord, QueryOptions, QueryResult, UpsertResult, BatchOp, BatchResult, KoolbaseVector, SemanticSearchResult, SearchMode } from './types';
-export declare class KoolbaseDatabase {
-    private config;
-    private getUserId;
-    private getToken;
-    private syncEngine;
-    constructor(config: KoolbaseConfig, getUserId: () => string | null, getToken: () => Promise<string | null>);
-    private buildHeaders;
-    private request;
-    private runQuery;
-    query(collection: string, options?: QueryOptions): Promise<QueryResult>;
-    /**
-     * Insert a new record into a collection.
-     *
-     * Online-first: awaits the server so a server-side rejection (unique
-     * violation, validation error, permission denial) surfaces as the typed
-     * `KoolbaseDataError` subclass — `insert` now throws `KoolbaseConflictError`
-     * with the offending field on a 409, matching `upsert` and `update`.
-     *
-     * On genuine network failure (server unreachable, timeout) the write is
-     * accepted optimistically: saved to the local cache and queued for sync
-     * when connectivity returns.
-     */
-    insert(collection: string, data: Record<string, unknown>): Promise<KoolbaseRecord>;
-    /**
-     * Insert a record, or update the existing one matching `match`.
-     *
-     * The server decides: exactly one match updates it, no match inserts a new
-     * record (seeded with the `match` fields), more than one match is an error.
-     * Returns the resulting record and a `created` flag (true = inserted, false
-     * = updated).
-     *
-     * Online-only by design. Unlike `insert`, an upsert is NOT queued offline:
-     * the insert-vs-update decision needs the server's authoritative view of
-     * what already exists, so deferring it could create a duplicate or apply a
-     * wrong update on later sync. It throws on network failure instead. A raw
-     * fetch is used (not `request`) so the status code is readable: 201 =
-     * created, 200 = updated.
-     */
-    upsert(collection: string, match: Record<string, unknown>, data: Record<string, unknown>): Promise<UpsertResult>;
-    /**
-     * Bulk-delete every record in `collection` matching `filters`.
-     *
-     * The server applies the collection's delete rule (scoping to the caller for
-     * owner/scoped rules) and returns the number of records deleted.
-     *
-     * Online-only by design — like upsert, this is NOT queued offline: a bulk
-     * delete needs the server's authoritative view of what matches, so it throws
-     * on network failure rather than risk deleting the wrong set on later sync.
-     * The collection cache is invalidated on success.
-     */
-    deleteWhere(collection: string, filters: Record<string, unknown>): Promise<number>;
-    /**
-     * Run multiple writes as a single atomic transaction.
-     *
-     * All `operations` commit together or none are applied — the server runs
-     * them in one database transaction and rolls back entirely on any failure.
-     * Operations apply in order and may span multiple collections.
-     *
-     * Online-only by design (like `upsert` and `deleteWhere`): atomicity needs
-     * the server's authoritative view, so a batch is never queued offline — it
-     * throws on network failure. A server-side rejection throws a
-     * `KoolbaseDataException` whose message identifies which operation failed;
-     * nothing was persisted.
-     *
-     * Returns one `BatchResult` per operation, in order.
-     *
-     * @example
-     * const results = await Koolbase.db.batch([
-     *   BatchOp.insert('orders', { total: 50 }),
-     *   BatchOp.update(inventoryId, { stock: 9 }),
-     *   BatchOp.upsert('counters', { match: { name: 'orders' }, data: { value: 1 } }),
-     *   BatchOp.delete(cartItemId),
-     * ]);
-     */
-    batch(operations: BatchOp[]): Promise<BatchResult[]>;
-    get(recordId: string): Promise<KoolbaseRecord>;
-    /**
-     * Update a record's fields by id.
-     *
-     * Online-first: awaits the server so a server-side rejection (unique
-     * violation, not found, permission denial) surfaces as the typed
-     * `KoolbaseDataError` subclass. An update that would violate a unique
-     * constraint now throws `KoolbaseConflictError` with the offending field —
-     * same shape as `insert` and `upsert`.
-     *
-     * On genuine network failure the update is queued for sync and a partial
-     * optimistic record is returned so the UI can re-render the new fields
-     * immediately.
-     */
-    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>;
-    /**
-     * Queue an embedding job for a record's vector field. The server's
-     * embedding worker picks it up within ~1 second.
-     *
-     * If `text` is omitted, the vector field's configured `source_field`
-     * value on the record is used.
-     *
-     * @example
-     * await Koolbase.db.embedText({
-     *   collection: 'articles',
-     *   recordId: article.$id,
-     *   vectorField: 'content_embedding',
-     * });
-     */
-    embedText(opts: {
-        collection: string;
-        recordId: string;
-        vectorField: string;
-        text?: string;
-    }): Promise<void>;
-    /**
-     * Search for records based on their semantic similarity to a query.
-     *
-     * @example
-     * // Server-side embedding — most common:
-     * const result = await Koolbase.db.searchSemantic({
-     *   collection: 'articles',
-     *   field: 'content_embedding',
-     *   queryText: 'how do I configure CI/CD?',
-     *   limit: 10,
-     * });
-     *
-     * // Client-side embedding:
-     * const result = await Koolbase.db.searchSemantic({
-     *   collection: 'articles',
-     *   field: 'content_embedding',
-     *   queryVector: precomputed,
-     *   limit: 10,
-     * });
-     *
-     * // Hybrid search (vector + BM25, RRF-fused):
-     * const result = await Koolbase.db.searchSemantic({
-     *   collection: 'articles',
-     *   field: 'content_embedding',
-     *   queryText: 'how do I configure CI/CD?',
-     *   mode: 'hybrid',
-     *   minSimilarity: 70,
-     * });
-     *
-     * `mode` selects the retrieval strategy:
-     * - `'semantic'` (default) — pure vector search via HNSW
-     * - `'lexical'` — pure BM25 over the field's source text
-     * - `'hybrid'` — vector + lexical, RRF-fused (k=60)
-     *
-     * `minSimilarity` (0..100, optional) filters out results below the
-     * given similarity percentage server-side. Saves bandwidth on weak
-     * matches. Only valid for semantic and hybrid; rejected by the
-     * server on lexical mode.
-     */
-    searchSemantic(opts: {
-        collection: string;
-        field: string;
-        queryVector?: number[];
-        queryText?: string;
-        limit?: number;
-        where?: Record<string, unknown>;
-        mode?: SearchMode;
-        minSimilarity?: number;
-    }): Promise<SemanticSearchResult>;
-    syncPendingWrites(): Promise<void>;
-}