@koolbase/react-native 9.2.0 → 10.0.1

package/dist/conflict.js

@@ -1,84 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.KoolbaseConflict = void 0;
-/**
- * A queued offline write that could not be applied, waiting for a decision.
- *
- * Not an error to dismiss and not a write to retry: retrying cannot help, and
- * discarding it would lose a change the user believes is saved. It waits, and
- * keeps waiting across restarts, until the application decides.
- *
- * Only the application can decide. Whether a later edit should win depends on
- * what the data means, and a platform that chooses for everyone is wrong for
- * someone.
- */
-class KoolbaseConflict {
-    constructor(id, reason, operation, collection, recordId, 
-    /** The change the user made, still unapplied. */
-    local, 
-    /** The record as it was when the change was composed, where that is known. */
-    baseline, 
-    /**
-     * The record as the server held it when the write was refused, captured with
-     * the refusal so deciding needs no fetch and cannot race one.
-     *
-     * Undefined when the reason is `baseline_unavailable` — nothing was ever
-     * sent, so the server never answered.
-     */
-    server, baseRevision, serverRevision, createdAt, resolver) {
-        this.id = id;
-        this.reason = reason;
-        this.operation = operation;
-        this.collection = collection;
-        this.recordId = recordId;
-        this.local = local;
-        this.baseline = baseline;
-        this.server = server;
-        this.baseRevision = baseRevision;
-        this.serverRevision = serverRevision;
-        this.createdAt = createdAt;
-        this.resolver = resolver;
-    }
-    /**
-     * Fields where the user's change and the server's version disagree.
-     *
-     * Only the fields the change touches: a record accumulates values the write
-     * never asserted, and listing those would bury the real disagreement. Empty
-     * when there is no server version to compare against.
-     */
-    get divergentFields() {
-        if (!this.local)
-            return [];
-        if (!this.server)
-            return Object.keys(this.local);
-        return Object.keys(this.local).filter((k) => JSON.stringify(this.server[k]) !== JSON.stringify(this.local[k]));
-    }
-    /** How long this has been waiting. Metadata, not a deletion rule. */
-    get ageMs() {
-        return Date.now() - new Date(this.createdAt).getTime();
-    }
-    /**
-     * Reapplies the user's change to the record as it stands now.
-     *
-     * An explicit decision to overwrite the server's version of the fields that
-     * disagree. Conditional where a revision is known, so a record that moved
-     * again while someone was deciding produces a new conflict rather than an
-     * unnoticed overwrite.
-     */
-    resolveWithLocal() {
-        return this.resolver.resolveWithLocal(this.id);
-    }
-    /** Keeps the server's version and discards the user's change, as a decision. */
-    resolveWithServer() {
-        return this.resolver.resolveWithServer(this.id);
-    }
-    /** Applies something the application composed from both versions. */
-    resolveWithMerge(data) {
-        return this.resolver.resolveWithMerge(this.id, data);
-    }
-    /** Drops the change without claiming either version won. */
-    abandon() {
-        return this.resolver.abandon(this.id);
-    }
-}
-exports.KoolbaseConflict = KoolbaseConflict;

package/dist/database-errors.d.ts

@@ -1,101 +0,0 @@
-import { KoolbaseError } from './errors';
-/**
- * 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.
- */
-export declare class KoolbaseDataError extends KoolbaseError {
-    /**
-     * Structured payload from the server's error body, when it sent one — e.g. a
-     * revision_mismatch 409 carries {expected_revision, current_revision,
-     * record}. Attached by the factory; absent when the body had none.
-     */
-    details?: Record<string, unknown>;
-    constructor(message: string, code?: string);
-}
-/**
- * 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.`);
- *   }
- * }
- */
-export declare class KoolbaseConflictError extends KoolbaseDataError {
-    field?: string;
-    constructor(message?: string, field?: string);
-}
-/**
- * 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`.
- */
-export declare class KoolbaseNotFoundError extends KoolbaseDataError {
-    constructor(message?: string);
-}
-/**
- * Thrown when the request is rejected as invalid — the server responds with
- * 400 and code `validation_error`.
- */
-export declare class KoolbaseValidationError extends KoolbaseDataError {
-    constructor(message?: string);
-}
-/**
- * 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).
- */
-export declare class KoolbasePermissionError extends KoolbaseDataError {
-    constructor(message?: string);
-}
-/**
- * Thrown when the server is rate-limiting the caller — 429 with code
- * `rate_limit`. Back off and retry after a short delay.
- */
-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
- * for older or uncoded responses. Always returns an error to throw.
- */
-export declare function koolbaseDataError(status: number, body: any, fallbackMessage?: string): KoolbaseError;

package/dist/database-errors.js

@@ -1,200 +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;
-const errors_1 = require("./errors");
-/**
- * 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 errors_1.KoolbaseError {
-    constructor(message, code) {
-        super(message, 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;
-    const attach = (err) => {
-        // The body's structured details ride along on data errors — a
-        // revision_mismatch 409 carries the current revision and record, and
-        // discarding them here is how a refused conflict-resolution became
-        // permanently unresolvable: the information arrived and died in this file.
-        if (err instanceof KoolbaseDataError && body?.details) {
-            err.details = body.details;
-        }
-        return err;
-    };
-    // Status-first for auth: a 401 means the credentials were not accepted,
-    // whatever code the body claims. Trusting a mislabelled body here bypasses
-    // session-clearing and strands the app signed-in with dead credentials.
-    if (status === 401) {
-        return new errors_1.KoolbaseUnauthenticatedError(message);
-    }
-    // ─── code-first ───
-    switch (code) {
-        case 'unique_violation':
-            return attach(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 attach(new KoolbaseNotFoundError(message));
-        case 'unauthenticated':
-        case 'session_expired':
-        case 'invalid_token':
-            return attach(new errors_1.KoolbaseUnauthenticatedError(message));
-        case 'permission_denied':
-            return attach(new KoolbasePermissionError(message));
-        case 'rate_limit':
-            return attach(new KoolbaseRateLimitError(message));
-        case 'validation_error':
-        case 'vector_collection_mismatch':
-        case 'unsupported_dimension':
-            return attach(new KoolbaseValidationError(message));
-        case 'vector_dimension_mismatch':
-            return attach(new KoolbaseVectorDimensionMismatchError(message));
-    }
-    // ─── status fallback (pre-code servers) ───
-    switch (status) {
-        case 409:
-            return attach(new KoolbaseConflictError(message));
-        case 404:
-            return attach(new KoolbaseNotFoundError(message));
-        case 401:
-            // The status carries the meaning: every 401 from this server reports the
-            // same code, so it cannot say whether the session expired, the key was
-            // revoked, or the header was malformed. Safe to treat uniformly because a
-            // permission failure is 403 — a 401 means the credentials were not
-            // accepted, not that this caller may not proceed.
-            return attach(new errors_1.KoolbaseUnauthenticatedError(message));
-        case 403:
-            return attach(new KoolbasePermissionError(message));
-        case 429:
-            return attach(new KoolbaseRateLimitError(message));
-        case 400:
-            return attach(new KoolbaseValidationError(message));
-    }
-    return attach(new KoolbaseDataError(message, code));
-}

package/dist/database.d.ts

@@ -1,298 +0,0 @@
-import { KoolbaseConflict } from './conflict';
-import { PendingWrite } from './pending-write';
-import { KoolbaseConfig, KoolbaseRecord, QueryOptions, QueryResult, UpsertResult, BatchOp, BatchResult, KoolbaseVector, SemanticSearchResult, SearchMode } from './types';
-export declare class KoolbaseDatabase {
-    private config;
-    private getUserId;
-    private getToken;
-    /**
-     * Called when the server rejects the caller's credentials.
-     *
-     * A session stops working for the whole SDK at once, so it is cleared before
-     * the error reaches the caller — otherwise the app keeps believing it is
-     * signed in and every subsequent call fails the same way, with no path back
-     * to login.
-     */
-    private onSessionExpired?;
-    private syncEngine;
-    constructor(config: KoolbaseConfig, getUserId: () => string | null, getToken: () => Promise<string | null>, onSessionExpired?: () => Promise<void>);
-    private buildHeaders;
-    private request;
-    /**
-     * Like [request], but returns the status alongside the body.
-     *
-     * Several operations need it — upsert distinguishes create from update by a
-     * 201, batch reports per-operation outcomes — and needing it was why they
-     * hand-rolled their own fetch, each mapping errors slightly differently and
-     * none of them clearing a rejected session. One path, two shapes of result.
-     */
-    private requestWithStatus;
-    private runQuery;
-    /**
-     * Query records, cache-first (stale-while-revalidate).
-     *
-     * A cache hit is returned immediately with `isFromCache: true`, and a
-     * background refresh updates the cache for the next call — so a repeat
-     * query converges on the server's state one call behind it. Only a cache
-     * miss awaits the network (`isFromCache: false`).
-     *
-     * Two consequences worth designing for: results can be one refresh stale,
-     * even online — re-query if you need convergence after a known write; and
-     * background refresh failures are swallowed by design (the cached result
-     * has already been returned), so a dead network looks identical to a slow
-     * refresh. Check `isFromCache` when the difference matters.
-     *
-     * The cache is per-user and persisted; it doubles as the offline baseline
-     * store for `update`/`delete`.
-     */
-    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>;
-    /**
-     * Writes that could not be applied, waiting for a decision.
-     *
-     * Held rather than discarded, and surviving restarts. An app that never reads
-     * these accumulates them invisibly, with the changes they hold never applied —
-     * so if you support offline editing, surface them somewhere.
-     */
-    /**
-     * Changes made offline, waiting to be sent. Oldest first.
-     *
-     * For sync indicators ("3 changes waiting") and for warning a user who is
-     * about to log out with unsynced edits — see [PendingWrite] for why that
-     * moment matters. Snapshot, not a live handle; per-user.
-     */
-    pendingWrites(): Promise<PendingWrite[]>;
-    conflicts(): Promise<KoolbaseConflict[]>;
-    /**
-     * Resolves by id, reloading the stored conflict first.
-     *
-     * A conflict object handed to a UI can sit there while someone decides, and a
-     * sync pass may resolve it or another write supersede it meanwhile. Acting on
-     * values captured when the object was built would write against a state that
-     * no longer exists.
-     */
-    private readonly conflictResolver;
-    /**
-     * Per-user state demands a user. Signed out, "no answer" must not be
-     * disguised as "empty" — tonight's fake-zero: the display read the anonymous
-     * bucket while a signed-in user's writes sat unseen in theirs.
-     */
-    private requireUserId;
-    private requireConflict;
-    private dropConflict;
-    /**
-     * Issues the resolving write, conditional on the revision the refusal
-     * reported, and clears the conflict only once the server accepts it.
-     *
-     * Clearing first would lose the change if the write then failed.
-     */
-    private applyResolution;
-    /**
-     * 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.
-     */
-    /**
-     * The record's state as the SDK last knew it, for composing an offline
-     * mutation against.
-     *
-     * Two sources, in order. A record created offline is not in the cache as a
-     * server record, but its queued insert holds the state a later edit builds on
-     * — insert-then-correct is the ordinary offline sequence. Otherwise the cached
-     * copy, with the revision it was read at.
-     *
-     * Null when neither exists: never seen on this device, or a queued delete has
-     * already removed it locally.
-     */
-    private resolveBaseline;
-    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>;
-}