@koolbase/react-native 9.0.0 → 9.2.0

package/dist/database-errors.d.ts

@@ -1,3 +1,4 @@
+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
@@ -7,8 +8,13 @@
  * 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 Error {
-    code?: string;
+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);
 }
 /**
@@ -92,4 +98,4 @@ export declare class KoolbaseVectorDimensionMismatchError extends KoolbaseDataEr
  * 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): KoolbaseDataError;
+export declare function koolbaseDataError(status: number, body: any, fallbackMessage?: string): KoolbaseError;

package/dist/database-errors.js

@@ -2,6 +2,7 @@
 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
@@ -11,10 +12,9 @@ exports.koolbaseDataError = koolbaseDataError;
  * 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 {
+class KoolbaseDataError extends errors_1.KoolbaseError {
     constructor(message, code) {
-        super(message);
-        this.code = code;
+        super(message, code);
         this.name = 'KoolbaseDataError';
         Object.setPrototypeOf(this, KoolbaseDataError.prototype);
     }
@@ -135,39 +135,66 @@ 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 new KoolbaseConflictError(message, field);
+            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 new KoolbaseNotFoundError(message);
+            return attach(new KoolbaseNotFoundError(message));
+        case 'unauthenticated':
+        case 'session_expired':
+        case 'invalid_token':
+            return attach(new errors_1.KoolbaseUnauthenticatedError(message));
         case 'permission_denied':
-            return new KoolbasePermissionError(message);
+            return attach(new KoolbasePermissionError(message));
         case 'rate_limit':
-            return new KoolbaseRateLimitError(message);
+            return attach(new KoolbaseRateLimitError(message));
         case 'validation_error':
         case 'vector_collection_mismatch':
         case 'unsupported_dimension':
-            return new KoolbaseValidationError(message);
+            return attach(new KoolbaseValidationError(message));
         case 'vector_dimension_mismatch':
-            return new KoolbaseVectorDimensionMismatchError(message);
+            return attach(new KoolbaseVectorDimensionMismatchError(message));
     }
     // ─── status fallback (pre-code servers) ───
     switch (status) {
         case 409:
-            return new KoolbaseConflictError(message);
+            return attach(new KoolbaseConflictError(message));
         case 404:
-            return new KoolbaseNotFoundError(message);
+            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 new KoolbasePermissionError(message);
+            return attach(new KoolbasePermissionError(message));
         case 429:
-            return new KoolbaseRateLimitError(message);
+            return attach(new KoolbaseRateLimitError(message));
         case 400:
-            return new KoolbaseValidationError(message);
+            return attach(new KoolbaseValidationError(message));
     }
-    return new KoolbaseDataError(message, code);
+    return attach(new KoolbaseDataError(message, code));
 }

package/dist/database.d.ts

@@ -1,13 +1,50 @@
+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>);
+    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.
@@ -75,6 +112,46 @@ export declare class KoolbaseDatabase {
      */
     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.
      *
@@ -88,6 +165,19 @@ export declare class KoolbaseDatabase {
      * 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>;
     /**