@koolbase/core 10.0.0

package/dist/esm/database.d.ts

@@ -0,0 +1,298 @@
+import { KoolbaseConflict } from './conflict.js';
+import { PendingWrite } from './pending-write.js';
+import { KoolbaseConfig, KoolbaseRecord, QueryOptions, QueryResult, UpsertResult, BatchOp, BatchResult, KoolbaseVector, SemanticSearchResult, SearchMode } from './types.js';
+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>;
+}