@koolbase/react-native 9.1.0 → 9.2.0

package/README.md

@@ -16,7 +16,14 @@ Auth, database, storage, realtime, functions, feature flags, remote config, vers
 3. Add the SDK:
 
 ```bash
-   npm install @koolbase/react-native
+   npm install @koolbase/react-native \\
+  @react-native-async-storage/async-storage @react-native-community/netinfo react-native-keychain
+
+> The three native modules are peer dependencies — your app installs them so
+> exactly one copy of each exists. Two copies of a native module in one app is
+> a runtime failure that looks like an SDK bug, which is why they are not
+> bundled.
+
    # or
    yarn add @koolbase/react-native
    # or
@@ -321,15 +328,92 @@ const deleted = await Koolbase.db.deleteWhere('sessions', {
 
 ### Offline-first
 
+Reads come from a local cache when the network is unavailable, and `insert`,
+`update`, and `delete` are queued and sent when it returns.
+
 ```typescript
 const { records, isFromCache } = await Koolbase.db.query('posts', { limit: 20 });
 if (isFromCache) console.log('Served from local cache');
 
+// Queued offline, applied on reconnect
+await Koolbase.db.update(id, { title: 'Corrected' });
+await Koolbase.db.delete(id);
+
+// Sync happens on reconnect. To force it:
 await Koolbase.db.syncPendingWrites();
 ```
 
+A server-side rejection is never queued. A unique-constraint violation, a
+validation failure, or a permission denial surfaces immediately — only a genuine
+network failure defers.
+
+#### Editing offline requires having read the record
+
+An update or delete is queued only if the SDK knows what the record looked like
+when the change was made. Replaying a change without that means applying it
+blindly: whatever else happened to the record in the meantime is overwritten,
+silently, with nobody able to tell.
+
+The SDK has that state if the record has been seen on this device — through a
+query, a single read, a realtime event, or because it was created here and is
+still queued. If it has not, the write is refused rather than queued:
+
+```typescript
+try {
+  await Koolbase.db.update(id, { title: 'Corrected' });
+} catch (e) {
+  if (e instanceof KoolbaseOfflineBaselineUnavailableError) {
+    // Never seen on this device. Read it, or make the change while online.
+  }
+}
+```
+
+That is deliberate rather than lenient. Queueing it anyway would mean most
+offline updates are conflict-safe and some quietly are not, which is a worse
+guarantee than a clear refusal.
+
+#### When a queued write cannot be applied
+
+On replay the server applies a queued write only if the record still carries the
+revision the change was based on. If something changed it meanwhile — another
+device, another user, a Function — the write is refused and held for a decision.
+It is not lost, and not applied, and it survives restarts.
+
+```typescript
+const conflicts = await Koolbase.db.conflicts();
+
+for (const c of conflicts) {
+  c.local;             // the change the user made
+  c.server;            // the record as the server holds it now
+  c.divergentFields;   // where they disagree
+  c.reason;            // why it is waiting
+
+  await c.resolveWithLocal();       // reapply the user's change
+  await c.resolveWithServer();      // keep the server's version
+  await c.resolveWithMerge({ ... }); // something composed from both
+  await c.abandon();                // drop it, neither side wins
+}
+```
+
+`reason` distinguishes two situations. `concurrent_modification` means the record
+moved while the change was queued. `baseline_unavailable` means the change was
+queued by a version of this SDK that did not record what it was based on — those
+are migrated on upgrade rather than replayed, since there is nothing to check
+them against.
+
+Resolving is itself conditional: if the record has moved again while someone was
+deciding, resolution produces a new conflict rather than overwriting a change
+nobody has seen.
+
+> **These do not expire.** An app that never reads `conflicts()` accumulates
+> them in local storage indefinitely, invisible to the user, with the changes
+> they hold never applied. If you support offline editing, surface them
+> somewhere. Automatic expiry would hide the problem while quietly losing the
+> work.
+
 ---
 
+
 ### Atomic batch writes
 
 Run multiple writes in a single server-side transaction. All operations commit together or none are applied — any failure rolls back the entire batch.
@@ -375,7 +459,10 @@ try {
 }
 ```
 
-When the device is offline, these writes are queued and synced automatically when connectivity returns.
+When the device is offline, `insert`, `update`, and `delete` are queued and sent
+when connectivity returns — an update or delete only if the record has been read
+on this device, so the change has something to be applied against. See
+[Offline-first](#offline-first).
 
 ---
 
@@ -921,6 +1008,22 @@ handling doesn't depend on message text.
 
 All data-layer failures extend `KoolbaseDataError` (which extends `Error`):
 
+Two errors are raised by any subsystem, because they are not about any one of
+them:
+
+| Error | When |
+|---|---|
+| `KoolbaseUnauthenticatedError` | The server would not accept the caller's credentials (401) — an expired session, a revoked key, or none at all; it does not distinguish. Raised by database, storage, Functions, and background sync alike, since a session stops working for the whole SDK at once. **The SDK has already signed the user out by the time you catch this** — route to login rather than retrying. |
+| `KoolbaseOfflineBaselineUnavailableError` | An offline update or delete could not be queued: the record has never been seen on this device, so there is nothing to apply the change against. Read it first, or make the change online. |
+
+Note the difference from `KoolbasePermissionError` (403), which means the
+credentials *were* accepted and this caller may not proceed. It does not sign
+anyone out, and signing someone out for opening the wrong record would be worse
+than the failure itself.
+
+All errors extend `KoolbaseError`, so `e instanceof KoolbaseError` catches
+anything the SDK raises.
+
 | Error | When |
 |---|---|
 | `KoolbaseConflictError` | A write violates a unique constraint (409). Exposes `.field` — the field that collided, when the server reports it. |
@@ -931,12 +1034,19 @@ All data-layer failures extend `KoolbaseDataError` (which extends `Error`):
 | `KoolbaseVectorDimensionMismatchError` | A vector's length doesn't match the field's declared dimension (400, code `vector_dimension_mismatch`). |
 
 ```ts
-import { KoolbaseConflictError, KoolbaseDataError } from '@koolbase/react-native';
+import {
+  KoolbaseConflictError,
+  KoolbaseDataError,
+  KoolbaseUnauthenticatedError,
+} from '@koolbase/react-native';
 
 try {
   await Koolbase.db.upsert('users', { email }, { name });
 } catch (e) {
-  if (e instanceof KoolbaseConflictError) {
+  if (e instanceof KoolbaseUnauthenticatedError) {
+    // Already signed out — the session was cleared before this threw.
+    goToLogin();
+  } else if (e instanceof KoolbaseConflictError) {
     showError(`That ${e.field ?? 'value'} is already taken.`);
   } else if (e instanceof KoolbaseDataError) {
     showError(e.message);
@@ -944,10 +1054,16 @@ try {
 }
 ```
 
-> `query`, `get`, `upsert`, and `deleteWhere` throw these typed errors. `insert`,
-> `update`, and `delete` are optimistic/offline-first — they queue and sync in
-> the background, so their conflicts surface via the sync engine, not as a
-> thrown error.
+> `insert`, `update`, and `delete` queue when the network is unreachable, but
+> they still throw. A server that answered has refused — a permission denial, a
+> unique-constraint violation, a rejected credential — and that is surfaced
+> rather than queued, since it would be refused again on every retry. An update
+> or delete also throws `KoolbaseOfflineBaselineUnavailableError` when the record
+> has never been seen on this device.
+>
+> What does not throw is a write refused during replay, hours after it was made:
+> nobody is waiting on it, so it becomes a conflict you read from
+> `Koolbase.db.conflicts()`.
 
 ---
 
@@ -1021,7 +1137,7 @@ Manage your projects at [app.koolbase.com](https://app.koolbase.com)
 
 - [GitHub Issues](https://github.com/kennedyowusu/koolbase-react-native/issues)
 - [docs.koolbase.com](https://docs.koolbase.com)
-- Email: <hello@koolbase.com>
+- Email: <dev@koolbase.com>
 
 ## License
 

package/dist/auth-errors.d.ts

@@ -1,10 +1,10 @@
+import { KoolbaseError } from './errors';
 /**
  * Base error type for all Koolbase auth errors. Catchable via
  * `instanceof KoolbaseAuthError` to handle any auth-related failure
  * generically; subclasses let you handle specific cases.
  */
-export declare class KoolbaseAuthError extends Error {
-    code?: string;
+export declare class KoolbaseAuthError extends KoolbaseError {
     constructor(message: string, code?: string);
 }
 export declare class InvalidCredentialsError extends KoolbaseAuthError {

package/dist/auth-errors.js

@@ -1,15 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GoogleEmailRequiredError = exports.InvalidGoogleTokenError = exports.GoogleSignInNotConfiguredError = exports.OAuthEmailConflictError = exports.AppleEmailRequiredError = exports.InvalidAppleTokenError = exports.AppleSignInNotConfiguredError = exports.SmsConfigMissingError = exports.PhoneAlreadyLinkedError = exports.OtpRateLimitError = exports.OtpMaxAttemptsError = exports.OtpInvalidError = exports.OtpExpiredError = exports.InvalidPhoneNumberError = exports.NetworkError = exports.RateLimitError = exports.UnlockTokenInvalidError = exports.AccountLockedError = exports.TokenRevokedError = exports.SessionExpiredError = exports.WeakPasswordError = exports.UserDisabledError = exports.EmailAlreadyInUseError = exports.InvalidCredentialsError = exports.KoolbaseAuthError = void 0;
+const errors_1 = require("./errors");
 /**
  * Base error type for all Koolbase auth errors. Catchable via
  * `instanceof KoolbaseAuthError` to handle any auth-related failure
  * generically; subclasses let you handle specific cases.
  */
-class KoolbaseAuthError extends Error {
+class KoolbaseAuthError extends errors_1.KoolbaseError {
     constructor(message, code) {
-        super(message);
-        this.code = code;
+        super(message, code);
         this.name = 'KoolbaseAuthError';
         Object.setPrototypeOf(this, KoolbaseAuthError.prototype);
     }

package/dist/auth.d.ts

@@ -56,6 +56,20 @@ export declare class KoolbaseAuth {
      */
     private authedRequest;
     private setSessionInternal;
+    /**
+     * Discards the stored session without contacting the server.
+     *
+     * For when the session is already known to be unusable — the server rejected
+     * the token, or a build was pointed at a different project and the persisted
+     * session belongs to the old one. Unlike `logout()` there is no server call:
+     * the token has already been refused, and asking for it to be revoked would
+     * only add a round trip that cannot succeed.
+     *
+     * Safe in any state, including with no session at all. The SDK calls this
+     * itself when a request is rejected as unauthenticated, so most apps will not
+     * need to.
+     */
+    clearStoredSession(): Promise<void>;
     private clearSessionInternal;
     restoreSession(): Promise<RestoreResult>;
     register(params: RegisterParams): Promise<KoolbaseUser>;

package/dist/auth.js

@@ -144,6 +144,22 @@ class KoolbaseAuth {
         }
         this.fireAuthStateChange();
     }
+    /**
+     * Discards the stored session without contacting the server.
+     *
+     * For when the session is already known to be unusable — the server rejected
+     * the token, or a build was pointed at a different project and the persisted
+     * session belongs to the old one. Unlike `logout()` there is no server call:
+     * the token has already been refused, and asking for it to be revoked would
+     * only add a round trip that cannot succeed.
+     *
+     * Safe in any state, including with no session at all. The SDK calls this
+     * itself when a request is rejected as unauthenticated, so most apps will not
+     * need to.
+     */
+    async clearStoredSession() {
+        await this.clearSessionInternal();
+    }
     async clearSessionInternal() {
         this.session = null;
         if (this.storage) {

package/dist/cache-store.d.ts

@@ -1,11 +1,50 @@
-import { KoolbaseRecord, PendingWrite, QueryResult } from './types';
+import { KoolbaseRecord, LegacyPendingWrite, QueryResult } from './types';
 export declare function hashQuery(collection: string, options: Record<string, unknown>): string;
 export declare function getCached(userId: string, collection: string, queryHash: string): Promise<QueryResult | null>;
 export declare function setCached(userId: string, collection: string, queryHash: string, result: QueryResult): Promise<void>;
 export declare function invalidateCache(userId: string, collection: string): Promise<void>;
+/**
+ * Drops everything cached for a user.
+ *
+ * Deliberately spares the write queue. The prefix covers every key for this
+ * user, and the queue lives under one of them — so clearing the cache used to
+ * delete offline writes the user believes are saved, silently and
+ * irrecoverably. A cache is what can be refetched; queued writes are not that.
+ */
 export declare function clearUserCache(userId: string): Promise<void>;
-export declare function getWriteQueue(userId: string): Promise<PendingWrite[]>;
-export declare function addToWriteQueue(userId: string, write: Omit<PendingWrite, 'retries' | 'createdAt'>): Promise<void>;
+/**
+ * A record as the SDK last saw it, with the revision it was read at.
+ *
+ * Separate from the query cache, which answers "what did this query return".
+ * This answers "what is the latest copy of this record" — and an offline
+ * mutation composes against the second. Scanning query blobs for one would mean
+ * the same record appearing in several snapshots at different revisions, with no
+ * principled way to choose.
+ *
+ * Keyed with `record` where a collection name would sit, so invalidateCache —
+ * which scopes to a collection and runs after every write — cannot reach these.
+ * A user's own edit must not remove the baseline they need for the next one.
+ */
+export interface CachedRecord {
+    collection: string;
+    data: Record<string, unknown>;
+    revision?: number;
+    cachedAt: string;
+}
+export declare function getCachedRecord(userId: string, recordId: string): Promise<CachedRecord | null>;
+/**
+ * Stores a record, refusing to move it backwards.
+ *
+ * Query responses can arrive out of order — a slow request from an earlier
+ * screen resolving after a fresh one — and an older copy overwriting a newer
+ * would compose the next mutation against a stale revision, producing a conflict
+ * the user never caused. False conflicts teach people to force-overwrite, which
+ * is worse than none.
+ */
+export declare function cacheRecord(userId: string, collection: string, recordId: string, data: Record<string, unknown>, revision?: number): Promise<void>;
+export declare function removeCachedRecord(userId: string, recordId: string): Promise<void>;
+export declare function getWriteQueue(userId: string): Promise<LegacyPendingWrite[]>;
+export declare function addToWriteQueue(userId: string, write: Omit<LegacyPendingWrite, 'retries' | 'createdAt'>): Promise<void>;
 export declare function removeFromWriteQueue(userId: string, writeId: string): Promise<void>;
 export declare function incrementWriteRetry(userId: string, writeId: string): Promise<void>;
 export declare function optimisticallyInsert(userId: string, collection: string, record: KoolbaseRecord): Promise<void>;

package/dist/cache-store.js

@@ -8,6 +8,9 @@ exports.getCached = getCached;
 exports.setCached = setCached;
 exports.invalidateCache = invalidateCache;
 exports.clearUserCache = clearUserCache;
+exports.getCachedRecord = getCachedRecord;
+exports.cacheRecord = cacheRecord;
+exports.removeCachedRecord = removeCachedRecord;
 exports.getWriteQueue = getWriteQueue;
 exports.addToWriteQueue = addToWriteQueue;
 exports.removeFromWriteQueue = removeFromWriteQueue;
@@ -57,11 +60,20 @@ async function invalidateCache(userId, collection) {
         // ignore
     }
 }
+/**
+ * Drops everything cached for a user.
+ *
+ * Deliberately spares the write queue. The prefix covers every key for this
+ * user, and the queue lives under one of them — so clearing the cache used to
+ * delete offline writes the user believes are saved, silently and
+ * irrecoverably. A cache is what can be refetched; queued writes are not that.
+ */
 async function clearUserCache(userId) {
     try {
         const keys = await async_storage_1.default.getAllKeys();
         const prefix = `koolbase:${CACHE_VERSION}:${userId}:`;
-        const toDelete = keys.filter(k => k.startsWith(prefix));
+        const queueKey = writeQueueKey(userId);
+        const toDelete = keys.filter(k => k.startsWith(prefix) && k !== queueKey);
         for (const key of toDelete) {
             await async_storage_1.default.removeItem(key);
         }
@@ -70,6 +82,55 @@ async function clearUserCache(userId) {
         // ignore
     }
 }
+function recordCacheKey(userId, recordId) {
+    return `koolbase:${CACHE_VERSION}:${userId}:record:${recordId}`;
+}
+async function getCachedRecord(userId, recordId) {
+    try {
+        const raw = await async_storage_1.default.getItem(recordCacheKey(userId, recordId));
+        return raw ? JSON.parse(raw) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Stores a record, refusing to move it backwards.
+ *
+ * Query responses can arrive out of order — a slow request from an earlier
+ * screen resolving after a fresh one — and an older copy overwriting a newer
+ * would compose the next mutation against a stale revision, producing a conflict
+ * the user never caused. False conflicts teach people to force-overwrite, which
+ * is worse than none.
+ */
+async function cacheRecord(userId, collection, recordId, data, revision) {
+    try {
+        const existing = await getCachedRecord(userId, recordId);
+        if (existing?.revision !== undefined &&
+            revision !== undefined &&
+            revision < existing.revision) {
+            return;
+        }
+        const entry = {
+            collection,
+            data,
+            revision,
+            cachedAt: new Date().toISOString(),
+        };
+        await async_storage_1.default.setItem(recordCacheKey(userId, recordId), JSON.stringify(entry));
+    }
+    catch {
+        // ignore
+    }
+}
+async function removeCachedRecord(userId, recordId) {
+    try {
+        await async_storage_1.default.removeItem(recordCacheKey(userId, recordId));
+    }
+    catch {
+        // ignore
+    }
+}
 // ─── Write Queue ────────────────────────────────────────────────────────────
 async function getWriteQueue(userId) {
     try {

package/dist/conflict.d.ts

@@ -0,0 +1,80 @@
+import { ConflictReason } from './offline-state';
+/** Resolves conflicts by id. */
+export interface ConflictResolver {
+    resolveWithLocal(conflictId: string): Promise<void>;
+    resolveWithServer(conflictId: string): Promise<void>;
+    resolveWithMerge(conflictId: string, data: Record<string, unknown>): Promise<void>;
+    abandon(conflictId: string): Promise<void>;
+}
+/**
+ * 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.
+ */
+export declare class KoolbaseConflict {
+    readonly id: string;
+    readonly reason: ConflictReason;
+    readonly operation: 'insert' | 'update' | 'delete';
+    readonly collection: string;
+    readonly recordId: string;
+    /** The change the user made, still unapplied. */
+    readonly local: Record<string, unknown> | undefined;
+    /** The record as it was when the change was composed, where that is known. */
+    readonly baseline: Record<string, unknown> | undefined;
+    /**
+     * 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.
+     */
+    readonly server: Record<string, unknown> | undefined;
+    readonly baseRevision: number | undefined;
+    readonly serverRevision: number | undefined;
+    readonly createdAt: string;
+    private readonly resolver;
+    constructor(id: string, reason: ConflictReason, operation: 'insert' | 'update' | 'delete', collection: string, recordId: string, 
+    /** The change the user made, still unapplied. */
+    local: Record<string, unknown> | undefined, 
+    /** The record as it was when the change was composed, where that is known. */
+    baseline: Record<string, unknown> | undefined, 
+    /**
+     * 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: Record<string, unknown> | undefined, baseRevision: number | undefined, serverRevision: number | undefined, createdAt: string, resolver: ConflictResolver);
+    /**
+     * 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(): string[];
+    /** How long this has been waiting. Metadata, not a deletion rule. */
+    get ageMs(): number;
+    /**
+     * 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(): Promise<void>;
+    /** Keeps the server's version and discards the user's change, as a decision. */
+    resolveWithServer(): Promise<void>;
+    /** Applies something the application composed from both versions. */
+    resolveWithMerge(data: Record<string, unknown>): Promise<void>;
+    /** Drops the change without claiming either version won. */
+    abandon(): Promise<void>;
+}

package/dist/conflict.js

@@ -0,0 +1,84 @@
+"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,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;