@koolbase/react-native 9.2.0 → 10.0.1

package/dist/database.js

@@ -1,852 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.KoolbaseDatabase = void 0;
-const errors_1 = require("./errors");
-const cache_store_1 = require("./cache-store");
-const offline_state_1 = require("./offline-state");
-const conflict_1 = require("./conflict");
-const pending_write_1 = require("./pending-write");
-const cache_store_2 = require("./cache-store");
-const sync_engine_1 = require("./sync-engine");
-const record_1 = require("./record");
-const database_errors_1 = require("./database-errors");
-function generateWriteId() {
-    return 'local_' + Math.random().toString(36).slice(2) + Date.now().toString(36);
-}
-// Record ids are UUIDs from birth: the server honors a caller-supplied UUID id,
-// so the optimistic identity and the server identity are the same string and
-// chained offline writes need no remapping on replay. Write ids (above) stay
-// local_-prefixed — they are idempotency keys, never addresses.
-function generateRecordId() {
-    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, c => {
-        const r = (Math.random() * 16) | 0;
-        return (c === 'x' ? r : (r & 0x3) | 0x8).toString(16);
-    });
-}
-function batchOpToWire(op) {
-    switch (op.type) {
-        case 'insert':
-            return { type: 'insert', collection: op.collection, data: op.data };
-        case 'update':
-            return { type: 'update', record_id: op.recordId, data: op.data };
-        case 'delete':
-            return { type: 'delete', record_id: op.recordId };
-        case 'upsert':
-            return {
-                type: 'upsert',
-                collection: op.collection,
-                match: op.match,
-                data: op.data,
-            };
-    }
-}
-class KoolbaseDatabase {
-    constructor(config, getUserId, getToken, onSessionExpired) {
-        /**
-         * 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.
-         */
-        this.conflictResolver = {
-            resolveWithLocal: async (id) => {
-                const c = await this.requireConflict(id);
-                await this.applyResolution(c, c.local ?? {});
-            },
-            resolveWithMerge: async (id, data) => {
-                const c = await this.requireConflict(id);
-                await this.applyResolution(c, data);
-            },
-            resolveWithServer: async (id) => {
-                const c = await this.requireConflict(id);
-                // The server's version stands. Recorded as a decision by removing the
-                // conflict, rather than the change quietly disappearing.
-                await this.dropConflict(c.id);
-            },
-            abandon: async (id) => {
-                const c = await this.requireConflict(id);
-                await this.dropConflict(c.id);
-            },
-        };
-        this.config = config;
-        this.getUserId = getUserId;
-        this.getToken = getToken;
-        this.onSessionExpired = onSessionExpired;
-        this.syncEngine = new sync_engine_1.SyncEngine(config, getUserId, getToken, undefined, onSessionExpired);
-        this.syncEngine.start();
-    }
-    // getUserId is kept only for local cache keys / offline metadata; request
-    // identity now comes solely from the verified access token.
-    async buildHeaders() {
-        const token = await this.getToken();
-        return {
-            'Content-Type': 'application/json',
-            'x-api-key': this.config.publicKey,
-            ...(token ? { Authorization: `Bearer ${token}` } : {}),
-        };
-    }
-    async request(method, path, body) {
-        const res = await fetch(`${this.config.baseUrl}${path}`, {
-            method,
-            headers: await this.buildHeaders(),
-            body: body ? JSON.stringify(body) : undefined,
-        });
-        // A 204 carries no body, and some error responses carry none either.
-        // Parsing unconditionally would throw before the status was ever checked,
-        // which is why delete was written to bypass this path — and why its errors
-        // went unreported.
-        const text = await res.text();
-        let data = null;
-        if (text.length > 0) {
-            try {
-                data = JSON.parse(text);
-            }
-            catch {
-                // Leave data null: a body that is not JSON is not more informative than
-                // the status, and failing to parse it must not mask the status.
-            }
-        }
-        if (!res.ok) {
-            const err = (0, database_errors_1.koolbaseDataError)(res.status, data ?? {}, `Request failed: ${res.status}`);
-            if (err instanceof errors_1.KoolbaseUnauthenticatedError) {
-                await this.onSessionExpired?.();
-            }
-            throw err;
-        }
-        return data;
-    }
-    /**
-     * 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.
-     */
-    async requestWithStatus(method, path, body) {
-        const res = await fetch(`${this.config.baseUrl}${path}`, {
-            method,
-            headers: await this.buildHeaders(),
-            body: body ? JSON.stringify(body) : undefined,
-        });
-        const text = await res.text();
-        let data = null;
-        if (text.length > 0) {
-            try {
-                data = JSON.parse(text);
-            }
-            catch {
-                // Not JSON: the status is more informative than an unparseable body,
-                // and failing to parse must not mask it.
-            }
-        }
-        if (!res.ok) {
-            const err = (0, database_errors_1.koolbaseDataError)(res.status, data ?? {}, `Request failed: ${res.status}`);
-            if (err instanceof errors_1.KoolbaseUnauthenticatedError) {
-                await this.onSessionExpired?.();
-            }
-            throw err;
-        }
-        return { status: res.status, data: data };
-    }
-    // ─── Query (cache-first) ───────────────────────────────────────────────────
-    async runQuery(collection, options) {
-        const raw = await this.request('POST', '/v1/sdk/db/query', {
-            collection,
-            filters: options.filters ?? {},
-            limit: options.limit ?? 20,
-            offset: options.offset ?? 0,
-            order_by: options.orderBy,
-            order_desc: options.orderDesc ?? false,
-            populate: options.populate ?? [],
-        });
-        const records = raw.records.map(record_1.recordFromWire);
-        // Individually, as well as under the query key. The query cache answers
-        // "what did this query return"; the record cache answers "what is the
-        // latest copy of this record" — and an offline mutation composes against
-        // the second. Without this, listing records and editing one, the most
-        // ordinary flow there is, would have no baseline and be refused.
-        //
-        // Only the top-level records. Populated relations arrive embedded rather
-        // than fetched in their own right, and caching them as if they were would
-        // risk storing a shape that is not the whole record.
-        const userId = this.getUserId() ?? 'anonymous';
-        await Promise.all(records.map((r) => r.collection
-            ? (0, cache_store_1.cacheRecord)(userId, r.collection, r.id, r.data, r.revision)
-            : Promise.resolve()));
-        return { records, total: raw.total };
-    }
-    /**
-     * 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`.
-     */
-    async query(collection, options = {}) {
-        const userId = this.getUserId() ?? 'anonymous';
-        const queryHash = (0, cache_store_2.hashQuery)(collection, options);
-        const cached = await (0, cache_store_2.getCached)(userId, collection, queryHash);
-        if (cached) {
-            this.runQuery(collection, options)
-                .then(result => (0, cache_store_2.setCached)(userId, collection, queryHash, result))
-                .catch(() => {
-                // Network unavailable — cached data already returned
-            });
-            return { ...cached, isFromCache: true };
-        }
-        const result = await this.runQuery(collection, options);
-        await (0, cache_store_2.setCached)(userId, collection, queryHash, result);
-        return { ...result, isFromCache: false };
-    }
-    // ─── Insert (online-first with offline fallback) ───────────────────────────
-    /**
-     * 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.
-     */
-    async insert(collection, data) {
-        const userId = this.getUserId() ?? 'anonymous';
-        try {
-            // Online path: await the server and return the authoritative record
-            // (with the server-assigned id). Refresh the collection cache so the
-            // next query sees real data instead of a stale optimistic copy.
-            const raw = await this.request('POST', '/v1/sdk/db/insert', { collection, data });
-            const record = (0, record_1.recordFromWire)(raw);
-            await (0, cache_store_2.invalidateCache)(userId, collection);
-            // The response carries a fresh revision, so caching it keeps the
-            // baseline current for whatever edits this record next.
-            await (0, cache_store_1.cacheRecord)(userId, collection, record.id, record.data, record.revision);
-            return record;
-        }
-        catch (e) {
-            // Server-reachable rejection: the server saw the request and refused.
-            // Surface to the caller without writing optimistic state or queuing —
-            // the server has already decided it will not accept this write, and
-            // queuing it would just spin SyncEngine until max retries.
-            // Anything the server answered with — a refusal, a conflict, a rejected
-            // credential — must not be queued: it will be refused again on every
-            // retry. Checked against the root rather than the data family, because a
-            // rejected credential belongs to no single surface.
-            if (e instanceof errors_1.KoolbaseError)
-                throw e;
-            // The queue is per-user, and signed out there is no user: filing this
-            // into the anonymous bucket would queue real work where no signed-in
-            // sync ever looks — the fake-zero's origin. Refusing is honest; the
-            // caller knows the change did not save and can say so.
-            if (!this.getUserId()) {
-                throw new errors_1.KoolbaseUnauthenticatedError('Signed out and offline — this change cannot be queued for sync.');
-            }
-            // Genuine network failure → offline path: save to local cache and
-            // queue for SyncEngine to retry when online. Return the optimistic
-            // record so the UI has something to render in the meantime.
-            const recordId = generateRecordId();
-            const optimisticRecord = {
-                id: recordId,
-                createdBy: userId,
-                data: { ...data, id: recordId },
-                createdAt: new Date().toISOString(),
-                updatedAt: new Date().toISOString(),
-            };
-            await (0, cache_store_2.optimisticallyInsert)(userId, collection, optimisticRecord);
-            // No baseline: an insert has no prior state, and the record does not
-            // exist on the server yet, so there is nothing to be conditional against.
-            // An offline edit to it composes against this queued write instead.
-            await (0, offline_state_1.queueWrite)(userId, {
-                id: generateWriteId(),
-                operation: 'insert',
-                collection,
-                recordId: optimisticRecord.id,
-                // The record's UUID travels inside the payload: the server honors a
-                // caller-supplied id, which is what keeps offline identity alive across
-                // the boundary — the whole reason record ids are UUIDs from birth.
-                data: optimisticRecord.data,
-            });
-            return optimisticRecord;
-        }
-    }
-    // ─── Upsert (online-only) ─────────────────────────────────────────────────
-    /**
-     * 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.
-     */
-    async upsert(collection, match, data) {
-        const { status, data: body } = await this.requestWithStatus('POST', '/v1/sdk/db/upsert', { collection, match, data });
-        const created = status === 201;
-        const record = (0, record_1.recordFromWire)(body);
-        // Keep the cache fresh, same intent as insert's post-success invalidate.
-        const userId = this.getUserId() ?? 'anonymous';
-        await (0, cache_store_2.invalidateCache)(userId, collection);
-        await (0, cache_store_1.cacheRecord)(userId, collection, record.id, record.data, record.revision);
-        return { record, created };
-    }
-    // ─── Delete where (online-only) ─────────────────────────────────────────────
-    /**
-     * 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.
-     */
-    async deleteWhere(collection, filters) {
-        const body = await this.request('POST', '/v1/sdk/db/delete-where', { collection, filters });
-        const userId = this.getUserId() ?? 'anonymous';
-        await (0, cache_store_2.invalidateCache)(userId, collection);
-        return body.deleted ?? 0;
-    }
-    // ─── Batch (atomic, online-only) ────────────────────────────────────────────
-    /**
-     * 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),
-     * ]);
-     */
-    async batch(operations) {
-        if (operations.length === 0) {
-            throw new Error('batch requires at least one operation');
-        }
-        const body = await this.request('POST', '/v1/sdk/db/batch', {
-            operations: operations.map(batchOpToWire),
-        });
-        const results = (body.results ?? []).map(r => ({
-            type: r.type ?? '',
-            record: r.record
-                ? (0, record_1.recordFromWire)(r.record)
-                : undefined,
-            created: r.created,
-            deleted: r.deleted ?? false,
-        }));
-        // Keep the cache consistent with what committed. Insert/upsert carry the
-        // collection in the input op; update/delete address records by id, so we
-        // don't know the collection at this layer — those refresh naturally on
-        // the next query for the affected collection.
-        const userId = this.getUserId() ?? 'anonymous';
-        // Records returned by a batch carry their own collection on the wire, so
-        // they can be cached even where the input op did not name one — which is
-        // what the invalidation below cannot do. A batch commits transactionally, so
-        // every record here landed together and carries a fresh revision.
-        for (const r of results) {
-            if (r.record?.collection) {
-                await (0, cache_store_1.cacheRecord)(userId, r.record.collection, r.record.id, r.record.data, r.record.revision);
-            }
-        }
-        const touched = new Set();
-        for (const op of operations) {
-            if (op.type === 'insert' || op.type === 'upsert') {
-                touched.add(op.collection);
-            }
-        }
-        for (const col of touched) {
-            await (0, cache_store_2.invalidateCache)(userId, col);
-        }
-        return results;
-    }
-    // ─── Get single record ──────────────────────────────────────────────────────
-    // ─── Get single record ──────────────────────────────────────────────────────
-    async get(recordId) {
-        const raw = await this.request('GET', `/v1/sdk/db/records/${recordId}`);
-        const record = (0, record_1.recordFromWire)(raw);
-        // Opening a record then editing it is the other ordinary flow, and a deep
-        // link reaches it without a query ever having run.
-        if (record.collection) {
-            await (0, cache_store_1.cacheRecord)(this.getUserId() ?? 'anonymous', record.collection, record.id, record.data, record.revision);
-        }
-        return record;
-    }
-    // ─── Conflicts ──────────────────────────────────────────────────────────────
-    /**
-     * 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.
-     */
-    async pendingWrites() {
-        const userId = this.requireUserId('the pending-write queue');
-        const { pending } = await (0, offline_state_1.readOfflineState)(userId);
-        return pending.map(pending_write_1.toPendingWrite);
-    }
-    async conflicts() {
-        const userId = this.requireUserId('the conflict list');
-        const { conflicts } = await (0, offline_state_1.readOfflineState)(userId);
-        return conflicts.map((c) => new conflict_1.KoolbaseConflict(c.id, c.reason, c.operation, c.collection, c.recordId, c.local, c.baseline, c.server, c.baseRevision, c.serverRevision, c.createdAt, this.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.
-     */
-    requireUserId(doing) {
-        const userId = this.getUserId();
-        if (!userId) {
-            throw new errors_1.KoolbaseUnauthenticatedError(`Signed out — ${doing} is per-user state and has no answer without a user.`);
-        }
-        return userId;
-    }
-    async requireConflict(id) {
-        const userId = this.requireUserId('conflict resolution');
-        const { conflicts } = await (0, offline_state_1.readOfflineState)(userId);
-        const found = conflicts.find((c) => c.id === id);
-        if (!found) {
-            throw new database_errors_1.KoolbaseDataError('That conflict is no longer outstanding — it may already have been resolved.', 'conflict_not_found');
-        }
-        return found;
-    }
-    async dropConflict(id) {
-        const userId = this.requireUserId('conflict resolution');
-        await (0, offline_state_1.mutateOfflineState)(userId, (s) => {
-            s.conflicts = s.conflicts.filter((c) => c.id !== id);
-        });
-    }
-    /**
-     * 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.
-     */
-    async applyResolution(c, payload) {
-        const rev = c.serverRevision;
-        try {
-            if (c.operation === 'insert') {
-                // Resolving a rejected insert IS the insert, retried — with amended
-                // data via resolveWithMerge (the "fix the colliding title" path).
-                // Unconditional: there is no revision to be conditional against,
-                // because there is no record. The conflict's id rides as the
-                // idempotency key, so a resolution whose response is lost returns the
-                // original on retry rather than duplicating — the queue's own
-                // lost-response discipline, extended to the one insert path that
-                // lacked it.
-                await this.request('POST', '/v1/sdk/db/insert', {
-                    collection: c.collection,
-                    data: payload,
-                    idempotency_key: c.id,
-                });
-            }
-            else if (c.operation === 'delete') {
-                const q = rev !== undefined ? `?expected_revision=${rev}` : '';
-                await this.request('DELETE', `/v1/sdk/db/records/${c.recordId}${q}`);
-            }
-            else {
-                await this.request('PATCH', `/v1/sdk/db/records/${c.recordId}`, { data: payload, ...(rev !== undefined ? { expected_revision: rev } : {}) });
-            }
-        }
-        catch (e) {
-            // A refusal must teach the stored conflict, not just gate it. The 409
-            // carries the server's current revision and record; absorbing them makes
-            // the NEXT attempt conditional against reality. Without this, every
-            // retry replays the stale condition and a conflict whose resolution
-            // fails once is permanently unresolvable except by abandon —
-            // device-proven: three identical refusals against an unchanged server.
-            const details = e instanceof database_errors_1.KoolbaseDataError ? e.details : undefined;
-            const current = details?.current_revision;
-            const record = details?.record;
-            if (typeof current === 'number') {
-                await (0, offline_state_1.mutateOfflineState)(this.requireUserId('conflict resolution'), (st) => {
-                    const stored = st.conflicts.find((x) => x.id === c.id);
-                    if (!stored)
-                        return;
-                    stored.serverRevision = current;
-                    // Storing the fresh server snapshot IS the divergence update: the
-                    // public conflict computes divergentFields from local vs server.
-                    if (record)
-                        stored.server = record;
-                });
-                throw new database_errors_1.KoolbaseDataError('The record has changed again while deciding. The conflict now ' +
-                    'reflects the server\'s current state — review and retry.', 'revision_mismatch');
-            }
-            throw e;
-        }
-        await this.dropConflict(c.id);
-        await (0, cache_store_2.invalidateCache)(this.getUserId() ?? 'anonymous', c.collection);
-    }
-    // ─── Update (online-first with offline fallback) ───────────────────────────
-    /**
-     * 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.
-     */
-    async resolveBaseline(userId, recordId) {
-        const state = await (0, offline_state_1.readOfflineState)(userId);
-        const queued = state.pending.filter((w) => w.recordId === recordId);
-        if (queued.length > 0) {
-            let projected = null;
-            for (const w of queued) {
-                if (w.operation === 'insert')
-                    projected = { ...(w.data ?? {}) };
-                else if (w.operation === 'update')
-                    projected = { ...(projected ?? {}), ...(w.data ?? {}) };
-                else if (w.operation === 'delete')
-                    projected = null;
-            }
-            // A chain ending in a delete leaves nothing to build on: editing a record
-            // already removed locally is a contradiction in the SDK's own state, not
-            // a conflict to resolve against the server.
-            if (projected === null)
-                return null;
-            return {
-                baseline: projected,
-                revision: queued[queued.length - 1].baseRevision,
-                collection: queued[0].collection,
-            };
-        }
-        const cached = await (0, cache_store_1.getCachedRecord)(userId, recordId);
-        if (!cached)
-            return null;
-        return { baseline: cached.data, revision: cached.revision, collection: cached.collection };
-    }
-    async update(recordId, data) {
-        const userId = this.getUserId() ?? 'anonymous';
-        // Resolved before the request, so a network failure has somewhere to go.
-        const base = await this.resolveBaseline(userId, recordId);
-        try {
-            const raw = await this.request('PATCH', `/v1/sdk/db/records/${recordId}`, { data });
-            const updated = (0, record_1.recordFromWire)(raw);
-            if (updated.collection) {
-                await (0, cache_store_1.cacheRecord)(userId, updated.collection, updated.id, updated.data, updated.revision);
-            }
-            return updated;
-        }
-        catch (e) {
-            // Server-reachable rejection: surface to caller without queuing — the
-            // server already refused the write and will refuse it again on retry.
-            // Anything the server answered with — a refusal, a conflict, a rejected
-            // credential — must not be queued: it will be refused again on every
-            // retry. Checked against the root rather than the data family, because a
-            // rejected credential belongs to no single surface.
-            if (e instanceof errors_1.KoolbaseError)
-                throw e;
-            // Genuine network failure. Queueable only if the SDK knows what the
-            // change was composed against — without that, replay would apply it
-            // blindly and overwrite whatever happened while the device was away.
-            if (!base) {
-                throw new errors_1.KoolbaseOfflineBaselineUnavailableError('This record must be read at least once before it can be updated offline.');
-            }
-            await (0, offline_state_1.queueWrite)(userId, {
-                id: generateWriteId(),
-                operation: 'update',
-                collection: base.collection,
-                recordId,
-                data,
-                baseline: base.baseline,
-                baseRevision: base.revision,
-            });
-            const merged = { ...base.baseline, ...data };
-            await (0, cache_store_1.cacheRecord)(userId, base.collection, recordId, merged, base.revision);
-            // Optimistic: durable locally and queued to send, not yet accepted.
-            return {
-                id: recordId,
-                collection: base.collection,
-                data: merged,
-                createdAt: '',
-                updatedAt: new Date().toISOString(),
-                revision: base.revision,
-            };
-        }
-    }
-    // ─── Delete ─────────────────────────────────────────────────────────────────
-    async delete(recordId) {
-        const userId = this.getUserId() ?? 'anonymous';
-        const base = await this.resolveBaseline(userId, recordId);
-        try {
-            await this.request('DELETE', `/v1/sdk/db/records/${recordId}`);
-            await (0, cache_store_1.removeCachedRecord)(userId, recordId);
-        }
-        catch (e) {
-            // A server that answered has refused: a permission denial or a missing
-            // record will be refused again on every retry, so surface it rather than
-            // queueing. An app told a delete succeeded when it did not has no way to
-            // learn otherwise.
-            // Anything the server answered with — a refusal, a conflict, a rejected
-            // credential — must not be queued: it will be refused again on every
-            // retry. Checked against the root rather than the data family, because a
-            // rejected credential belongs to no single surface.
-            if (e instanceof errors_1.KoolbaseError)
-                throw e;
-            // Genuine network failure. Queued here rather than before the request,
-            // which would leave a successful delete in the queue to replay later
-            // against a record that may since have been recreated under the same id.
-            // A delete replayed without knowing what the record was would remove
-            // something the user last saw hours earlier and which may have changed
-            // since — the more destructive kind of stale write.
-            if (!base) {
-                throw new errors_1.KoolbaseOfflineBaselineUnavailableError('This record must be read at least once before it can be deleted offline.');
-            }
-            await (0, offline_state_1.queueWrite)(userId, {
-                id: generateWriteId(),
-                operation: 'delete',
-                collection: base.collection,
-                recordId,
-                baseline: base.baseline,
-                baseRevision: base.revision,
-            });
-            // The queued write holds its own copy of the baseline, so removing the
-            // cached record costs nothing and keeps local reads consistent with what
-            // the user just did.
-            await (0, cache_store_1.removeCachedRecord)(userId, recordId);
-        }
-    }
-    // ─── 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) {
-        await this.request('POST', '/v1/sdk/db/set-vector', {
-            record_id: recordId,
-            field,
-            vector,
-        });
-    }
-    /**
-     * 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) {
-        await this.request('POST', '/v1/sdk/db/delete-vector', {
-            record_id: recordId,
-            field,
-        });
-    }
-    /**
-     * 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',
-     * });
-     */
-    async embedText(opts) {
-        const body = {
-            collection: opts.collection,
-            record_id: opts.recordId,
-            vector_field: opts.vectorField,
-        };
-        if (opts.text && opts.text.length > 0) {
-            body.text = opts.text;
-        }
-        await this.request('POST', '/v1/sdk/db/embed-text', body);
-    }
-    /**
-     * 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.
-     */
-    async searchSemantic(opts) {
-        const hasVector = Array.isArray(opts.queryVector) && opts.queryVector.length > 0;
-        const hasText = typeof opts.queryText === 'string' && opts.queryText.trim().length > 0;
-        if (!hasVector && !hasText) {
-            throw new Error('searchSemantic: provide either queryVector or queryText.');
-        }
-        if (hasVector && hasText) {
-            throw new Error('searchSemantic: provide only one of queryVector or queryText.');
-        }
-        if (opts.minSimilarity !== undefined &&
-            (opts.minSimilarity < 0 || opts.minSimilarity > 100)) {
-            throw new Error(`searchSemantic: minSimilarity must be between 0 and 100, got ${opts.minSimilarity}.`);
-        }
-        const body = {
-            collection: opts.collection,
-            field: opts.field,
-            limit: opts.limit ?? 20,
-            // Always send mode so the server uses the SDK's intent rather
-            // than its own default. Omitting for 'semantic' would also work
-            // (server defaults to semantic) but explicit is safer if the
-            // server's default ever shifts.
-            mode: opts.mode ?? 'semantic',
-        };
-        if (hasVector)
-            body.query_vector = opts.queryVector;
-        if (hasText)
-            body.query_text = opts.queryText;
-        if (opts.where && Object.keys(opts.where).length > 0) {
-            body.where = opts.where;
-        }
-        if (opts.minSimilarity !== undefined) {
-            body.min_similarity = opts.minSimilarity;
-        }
-        const raw = await this.request('POST', '/v1/sdk/db/search-semantic', body);
-        // A hit carries the complete public record, not a projection, so these are
-        // safe to cache as baselines. A trimmed record would be worse than none: an
-        // offline edit would compose against an incomplete picture and conflict
-        // detection would compare against fields that were never there.
-        const hits = (raw.results ?? []).map((r) => ({
-            record: (0, record_1.recordFromWire)(r.record),
-            distance: r.distance,
-        }));
-        const searchUserId = this.getUserId() ?? 'anonymous';
-        await Promise.all(hits.map((h) => h.record.collection
-            ? (0, cache_store_1.cacheRecord)(searchUserId, h.record.collection, h.record.id, h.record.data, h.record.revision)
-            : Promise.resolve()));
-        return {
-            hits: hits,
-            total: raw.total ?? (raw.results ?? []).length,
-        };
-    }
-    // ─── Manual sync ────────────────────────────────────────────────────────────
-    async syncPendingWrites() {
-        await this.syncEngine.flush();
-    }
-}
-exports.KoolbaseDatabase = KoolbaseDatabase;