@koolbase/core 12.7.0 → 12.9.0

package/dist/cjs/database.d.ts

@@ -207,8 +207,19 @@ export declare class KoolbaseDatabase {
      * already removed it locally.
      */
     private resolveBaseline;
-    update(recordId: string, data: Record<string, unknown>): Promise<KoolbaseRecord>;
-    delete(recordId: string): Promise<void>;
+    update(recordId: string, data: Record<string, unknown>, 
+    /** expectedRevision: apply only if the record still carries it; refused
+     *  with KoolbaseRevisionMismatchError otherwise (as the Flutter SDK). */
+    options?: {
+        expectedRevision?: number;
+    }): Promise<KoolbaseRecord>;
+    delete(recordId: string, 
+    /** expectedRevision: delete only if the record still carries it (as the
+     *  Flutter SDK) -- removing a record someone changed a moment ago is the
+     *  more destructive stale write. */
+    options?: {
+        expectedRevision?: number;
+    }): Promise<void>;
     /**
      * Write (or replace) a vector for a record on the named `field`.
      *

package/dist/cjs/database.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.KoolbaseDatabase = void 0;
 const network_js_1 = require("./network.js");
 const query_refresh_js_1 = require("./query-refresh.js");
+const database_errors_js_1 = require("./database-errors.js");
 const errors_js_1 = require("./errors.js");
 const cache_store_js_1 = require("./cache-store.js");
 const offline_state_js_1 = require("./offline-state.js");
@@ -11,7 +12,7 @@ const pending_write_js_1 = require("./pending-write.js");
 const cache_store_js_2 = require("./cache-store.js");
 const sync_engine_js_1 = require("./sync-engine.js");
 const record_js_1 = require("./record.js");
-const database_errors_js_1 = require("./database-errors.js");
+const database_errors_js_2 = require("./database-errors.js");
 function generateWriteId() {
     return 'local_' + Math.random().toString(36).slice(2) + Date.now().toString(36);
 }
@@ -111,7 +112,7 @@ class KoolbaseDatabase {
             }
         }
         if (!res.ok) {
-            const err = (0, database_errors_js_1.koolbaseDataError)(res.status, data ?? {}, `Request failed: ${res.status}`);
+            const err = (0, database_errors_js_2.koolbaseDataError)(res.status, data ?? {}, `Request failed: ${res.status}`);
             if (err instanceof errors_js_1.KoolbaseUnauthenticatedError) {
                 await this.onSessionExpired?.();
             }
@@ -145,7 +146,7 @@ class KoolbaseDatabase {
             }
         }
         if (!res.ok) {
-            const err = (0, database_errors_js_1.koolbaseDataError)(res.status, data ?? {}, `Request failed: ${res.status}`);
+            const err = (0, database_errors_js_2.koolbaseDataError)(res.status, data ?? {}, `Request failed: ${res.status}`);
             if (err instanceof errors_js_1.KoolbaseUnauthenticatedError) {
                 await this.onSessionExpired?.();
             }
@@ -230,7 +231,7 @@ class KoolbaseDatabase {
      */
     async invalidate(collection) {
         await (0, cache_store_js_2.invalidateCache)(this.getUserId() ?? 'anonymous', collection);
-        await (0, query_refresh_js_1.refreshCollectionQueries)(collection);
+        void (0, query_refresh_js_1.refreshCollectionQueries)(collection);
     }
     // ─── Insert (online-first with offline fallback) ───────────────────────────
     /**
@@ -254,7 +255,7 @@ class KoolbaseDatabase {
             const raw = await this.request('POST', '/v1/sdk/db/insert', { collection, data });
             const record = (0, record_js_1.recordFromWire)(raw);
             await (0, cache_store_js_2.invalidateCache)(userId, collection);
-            await (0, query_refresh_js_1.refreshCollectionQueries)(collection);
+            void (0, query_refresh_js_1.refreshCollectionQueries)(collection);
             // The response carries a fresh revision, so caching it keeps the
             // baseline current for whatever edits this record next.
             await (0, cache_store_js_1.cacheRecord)(userId, collection, record.id, record.data, record.revision);
@@ -329,7 +330,7 @@ class KoolbaseDatabase {
         // Keep the cache fresh, same intent as insert's post-success invalidate.
         const userId = this.getUserId() ?? 'anonymous';
         await (0, cache_store_js_2.invalidateCache)(userId, collection);
-        await (0, query_refresh_js_1.refreshCollectionQueries)(collection);
+        void (0, query_refresh_js_1.refreshCollectionQueries)(collection);
         await (0, cache_store_js_1.cacheRecord)(userId, collection, record.id, record.data, record.revision);
         return { record, created };
     }
@@ -349,7 +350,7 @@ class KoolbaseDatabase {
         const body = await this.request('POST', '/v1/sdk/db/delete-where', { collection, filters });
         const userId = this.getUserId() ?? 'anonymous';
         await (0, cache_store_js_2.invalidateCache)(userId, collection);
-        await (0, query_refresh_js_1.refreshCollectionQueries)(collection);
+        void (0, query_refresh_js_1.refreshCollectionQueries)(collection);
         return body.deleted ?? 0;
     }
     // ─── Batch (atomic, online-only) ────────────────────────────────────────────
@@ -413,7 +414,7 @@ class KoolbaseDatabase {
         }
         for (const col of touched) {
             await (0, cache_store_js_2.invalidateCache)(userId, col);
-            await (0, query_refresh_js_1.refreshCollectionQueries)(col);
+            void (0, query_refresh_js_1.refreshCollectionQueries)(col);
         }
         return results;
     }
@@ -535,7 +536,7 @@ class KoolbaseDatabase {
         const { conflicts } = await (0, offline_state_js_1.readOfflineState)(userId);
         const found = conflicts.find((c) => c.id === id);
         if (!found) {
-            throw new database_errors_js_1.KoolbaseDataError('That conflict is no longer outstanding — it may already have been resolved.', 'conflict_not_found');
+            throw new database_errors_js_2.KoolbaseDataError('That conflict is no longer outstanding — it may already have been resolved.', 'conflict_not_found');
         }
         return found;
     }
@@ -584,7 +585,7 @@ class KoolbaseDatabase {
             // 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_js_1.KoolbaseDataError ? e.details : undefined;
+            const details = e instanceof database_errors_js_2.KoolbaseDataError ? e.details : undefined;
             const current = details?.current_revision;
             const record = details?.record;
             if (typeof current === 'number') {
@@ -598,14 +599,14 @@ class KoolbaseDatabase {
                     if (record)
                         stored.server = record;
                 });
-                throw new database_errors_js_1.KoolbaseDataError('The record has changed again while deciding. The conflict now ' +
+                throw new database_errors_js_2.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_js_2.invalidateCache)(this.getUserId() ?? 'anonymous', c.collection);
-        await (0, query_refresh_js_1.refreshCollectionQueries)(c.collection);
+        void (0, query_refresh_js_1.refreshCollectionQueries)(c.collection);
     }
     // ─── Update (online-first with offline fallback) ───────────────────────────
     /**
@@ -662,12 +663,15 @@ class KoolbaseDatabase {
             return null;
         return { baseline: cached.data, revision: cached.revision, collection: cached.collection };
     }
-    async update(recordId, data) {
+    async update(recordId, data, 
+    /** expectedRevision: apply only if the record still carries it; refused
+     *  with KoolbaseRevisionMismatchError otherwise (as the Flutter SDK). */
+    options = {}) {
         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 raw = await this.request('PATCH', `/v1/sdk/db/records/${recordId}`, { data, ...(options.expectedRevision !== undefined ? { expected_revision: options.expectedRevision } : {}) });
             const updated = (0, record_js_1.recordFromWire)(raw);
             // Its collection's live queries re-run (every one, if the record's
             // collection is not known).
@@ -675,7 +679,7 @@ class KoolbaseDatabase {
             if (updated.collection) {
                 await (0, cache_store_js_1.cacheRecord)(userId, updated.collection, updated.id, updated.data, updated.revision);
             }
-            await (0, query_refresh_js_1.refreshCollectionQueries)(refreshed);
+            void (0, query_refresh_js_1.refreshCollectionQueries)(refreshed);
             return updated;
         }
         catch (e) {
@@ -685,6 +689,10 @@ class KoolbaseDatabase {
             // 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.
+            // Refused as stale: the server holds newer data, so show it -- the
+            // collection's live queries re-run in the background (as Flutter).
+            if (e instanceof database_errors_js_1.KoolbaseRevisionMismatchError)
+                void (0, query_refresh_js_1.refreshCollectionQueries)(base?.collection);
             if (e instanceof errors_js_1.KoolbaseError)
                 throw e;
             // Genuine network failure. Queueable only if the SDK knows what the
@@ -716,15 +724,19 @@ class KoolbaseDatabase {
         }
     }
     // ─── Delete ─────────────────────────────────────────────────────────────────
-    async delete(recordId) {
+    async delete(recordId, 
+    /** expectedRevision: delete only if the record still carries it (as the
+     *  Flutter SDK) -- removing a record someone changed a moment ago is the
+     *  more destructive stale write. */
+    options = {}) {
         const userId = this.getUserId() ?? 'anonymous';
         const base = await this.resolveBaseline(userId, recordId);
         try {
-            await this.request('DELETE', `/v1/sdk/db/records/${recordId}`);
+            await this.request('DELETE', `/v1/sdk/db/records/${recordId}${options.expectedRevision !== undefined ? `?expected_revision=${options.expectedRevision}` : ''}`);
             await (0, cache_store_js_1.removeCachedRecord)(userId, recordId);
             // Its collection is known from the baseline when the record was seen;
             // otherwise every live query re-runs, rather than a guess.
-            await (0, query_refresh_js_1.refreshCollectionQueries)(base?.collection);
+            void (0, query_refresh_js_1.refreshCollectionQueries)(base?.collection);
         }
         catch (e) {
             // A server that answered has refused: a permission denial or a missing
@@ -735,6 +747,10 @@ class KoolbaseDatabase {
             // 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.
+            // Refused as stale: the server holds newer data, so show it -- the
+            // collection's live queries re-run in the background (as Flutter).
+            if (e instanceof database_errors_js_1.KoolbaseRevisionMismatchError)
+                void (0, query_refresh_js_1.refreshCollectionQueries)(base?.collection);
             if (e instanceof errors_js_1.KoolbaseError)
                 throw e;
             // Genuine network failure. Queued here rather than before the request,

package/dist/cjs/flags.d.ts

@@ -3,8 +3,21 @@ export declare class KoolbaseFlags {
     private config;
     private payload;
     private deviceId;
+    private lastArgs;
+    private inFlight;
     constructor(config: KoolbaseConfig, deviceId: string);
     koolbaseFetch(appVersion: string, platform: string): Promise<void>;
+    /**
+     * The project id learned from the bootstrap payload, or '' while the first
+     * bootstrap has not completed (storage's publicUrlFor reads it).
+     */
+    projectId(): string;
+    /**
+     * Fetch the bootstrap payload again with the last arguments -- a nudge from
+     * storage when identity is missing, so a startup failure heals within the
+     * session. One fetch at a time; never throws.
+     */
+    refresh(): Promise<void>;
     isEnabled(key: string): boolean;
     getString(key: string, fallback?: string): string;
     getNumber(key: string, fallback?: number): number;

package/dist/cjs/flags.js

@@ -5,10 +5,15 @@ const network_js_1 = require("./network.js");
 class KoolbaseFlags {
     constructor(config, deviceId) {
         this.payload = null;
+        // The last bootstrap's arguments, so a nudge can refresh with the same ones;
+        // and the fetch in flight, so nudges never stack.
+        this.lastArgs = null;
+        this.inFlight = null;
         this.config = config;
         this.deviceId = deviceId;
     }
     async koolbaseFetch(appVersion, platform) {
+        this.lastArgs = { appVersion, platform };
         try {
             const res = await (0, network_js_1.koolbaseFetch)(`${this.config.baseUrl}/v1/bootstrap?public_key=${this.config.publicKey}&device_id=${this.deviceId}&app_version=${appVersion}&platform=${platform}`);
             if (res.ok) {
@@ -17,6 +22,25 @@ class KoolbaseFlags {
         }
         catch (_) { }
     }
+    /**
+     * The project id learned from the bootstrap payload, or '' while the first
+     * bootstrap has not completed (storage's publicUrlFor reads it).
+     */
+    projectId() {
+        return this.payload?.project_id ?? '';
+    }
+    /**
+     * Fetch the bootstrap payload again with the last arguments -- a nudge from
+     * storage when identity is missing, so a startup failure heals within the
+     * session. One fetch at a time; never throws.
+     */
+    refresh() {
+        if (this.inFlight)
+            return this.inFlight;
+        const args = this.lastArgs ?? { appVersion: this.config.appVersion ?? '0.0.0', platform: 'unknown' };
+        this.inFlight = this.koolbaseFetch(args.appVersion, args.platform).finally(() => { this.inFlight = null; });
+        return this.inFlight;
+    }
     isEnabled(key) {
         const flag = this.payload?.flags[key];
         if (!flag || !flag.enabled || flag.kill_switch)

package/dist/cjs/storage-errors.d.ts

@@ -7,6 +7,22 @@ import { KoolbaseError } from './errors.js';
 export declare class KoolbaseStorageError extends KoolbaseError {
     constructor(message: string, code?: string);
 }
+/**
+ * Thrown by {@link KoolbaseStorage.publicUrlFor} when the SDK has not yet
+ * learned which project it belongs to. Project identity arrives with the
+ * bootstrap payload; it is unavailable until the first bootstrap completes
+ * (an app starting offline) or when the server predates identity metadata.
+ *
+ * A DIFFERENT state from a `null` public URL: null means the project is
+ * known but the object cannot have a public URL (private bucket). This one is
+ * transient: it heals on the next successful bootstrap, which calling
+ * publicUrlFor also nudges.
+ *
+ * Stable `code`: `project_identity_unavailable`.
+ */
+export declare class KoolbaseStorageProjectIdentityError extends KoolbaseStorageError {
+    constructor();
+}
 /**
  * Thrown when an upload is rejected because an object already exists at
  * the requested path — the server responds with 409 Conflict and code

package/dist/cjs/storage-errors.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.KoolbaseStorageMetadataInvalidError = exports.KoolbaseStorageMimeTypeError = exports.KoolbaseStorageFileTooLargeError = exports.KoolbaseStorageQuotaError = exports.KoolbaseCapBelowUsageError = exports.KoolbaseUploadExpiredError = exports.KoolbaseUploadURLFailedError = exports.KoolbaseStoragePermissionError = exports.KoolbaseStorageValidationError = exports.KoolbaseStorageNotFoundError = exports.KoolbaseStorageConflictError = exports.KoolbaseStorageError = void 0;
+exports.KoolbaseStorageMetadataInvalidError = exports.KoolbaseStorageMimeTypeError = exports.KoolbaseStorageFileTooLargeError = exports.KoolbaseStorageQuotaError = exports.KoolbaseCapBelowUsageError = exports.KoolbaseUploadExpiredError = exports.KoolbaseUploadURLFailedError = exports.KoolbaseStoragePermissionError = exports.KoolbaseStorageValidationError = exports.KoolbaseStorageNotFoundError = exports.KoolbaseStorageConflictError = exports.KoolbaseStorageProjectIdentityError = exports.KoolbaseStorageError = void 0;
 exports.koolbaseStorageError = koolbaseStorageError;
 exports.koolbaseStorageErrorFromResponse = koolbaseStorageErrorFromResponse;
 const errors_js_1 = require("./errors.js");
@@ -17,6 +17,27 @@ class KoolbaseStorageError extends errors_js_1.KoolbaseError {
     }
 }
 exports.KoolbaseStorageError = KoolbaseStorageError;
+/**
+ * Thrown by {@link KoolbaseStorage.publicUrlFor} when the SDK has not yet
+ * learned which project it belongs to. Project identity arrives with the
+ * bootstrap payload; it is unavailable until the first bootstrap completes
+ * (an app starting offline) or when the server predates identity metadata.
+ *
+ * A DIFFERENT state from a `null` public URL: null means the project is
+ * known but the object cannot have a public URL (private bucket). This one is
+ * transient: it heals on the next successful bootstrap, which calling
+ * publicUrlFor also nudges.
+ *
+ * Stable `code`: `project_identity_unavailable`.
+ */
+class KoolbaseStorageProjectIdentityError extends KoolbaseStorageError {
+    constructor() {
+        super('The SDK has not yet learned its project identity -- it arrives with the first successful bootstrap. Retry after connectivity is available.', 'project_identity_unavailable');
+        this.name = 'KoolbaseStorageProjectIdentityError';
+        Object.setPrototypeOf(this, KoolbaseStorageProjectIdentityError.prototype);
+    }
+}
+exports.KoolbaseStorageProjectIdentityError = KoolbaseStorageProjectIdentityError;
 /**
  * Thrown when an upload is rejected because an object already exists at
  * the requested path — the server responds with 409 Conflict and code

package/dist/cjs/storage.d.ts

@@ -19,7 +19,11 @@ export declare class KoolbaseStorage {
      * keeps believing it is signed in.
      */
     private onSessionExpired?;
-    constructor(config: KoolbaseConfig, getToken: () => Promise<string | null>, onSessionExpired?: () => Promise<void>);
+    /** The project id from the bootstrap payload, '' until it arrives. */
+    private projectIdProvider?;
+    /** A background bootstrap refresh, nudged when identity is missing. */
+    private nudgeBootstrap?;
+    constructor(config: KoolbaseConfig, getToken: () => Promise<string | null>, onSessionExpired?: () => Promise<void>, projectIdProvider?: () => string, nudgeBootstrap?: () => void);
     /**
      * Builds the error for a failed response and clears the session when the
      * credentials were refused, before the error reaches the caller.
@@ -87,6 +91,20 @@ export declare class KoolbaseStorage {
      * Get a signed download URL for a file.
      */
     getDownloadUrl(bucket: string, path: string, versionId?: string): Promise<string>;
+    /**
+     * The stable public CDN URL for a file in a public bucket, using the project
+     * identity the SDK learned at bootstrap -- the runtime form of
+     * {@link KoolbaseStorage.publicUrl}, needing no projectId (as Flutter's).
+     *
+     * Throws {@link KoolbaseStorageProjectIdentityError} while identity is
+     * unavailable, and nudges a background bootstrap refresh so a later call in
+     * the same session succeeds once connectivity returns.
+     */
+    publicUrlFor(args: {
+        bucket: string;
+        path: string;
+        transform?: KoolbaseImageTransform;
+    }): string;
     /**
      * Build the stable public CDN URL for a file in a public bucket.
      *

package/dist/cjs/storage.js

@@ -1,9 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KoolbaseStorage = void 0;
+const storage_errors_js_1 = require("./storage-errors.js");
 const network_js_1 = require("./network.js");
 const errors_js_1 = require("./errors.js");
-const storage_errors_js_1 = require("./storage-errors.js");
+const storage_errors_js_2 = require("./storage-errors.js");
 // --- Cloudflare image-transform URL helpers -------------------------------
 // Module-private — callers use KoolbaseStorage.publicUrl / publicUrlForObject.
 function clampInt(v, min, max) {
@@ -42,17 +43,19 @@ function serializeTransform(t) {
  * `overwrite: true` is passed.
  */
 class KoolbaseStorage {
-    constructor(config, getToken, onSessionExpired) {
+    constructor(config, getToken, onSessionExpired, projectIdProvider, nudgeBootstrap) {
         this.config = config;
         this.getToken = getToken;
         this.onSessionExpired = onSessionExpired;
+        this.projectIdProvider = projectIdProvider;
+        this.nudgeBootstrap = nudgeBootstrap;
     }
     /**
      * Builds the error for a failed response and clears the session when the
      * credentials were refused, before the error reaches the caller.
      */
     async error(res, fallback) {
-        const err = await (0, storage_errors_js_1.koolbaseStorageErrorFromResponse)(res, fallback);
+        const err = await (0, storage_errors_js_2.koolbaseStorageErrorFromResponse)(res, fallback);
         if (err instanceof errors_js_1.KoolbaseUnauthenticatedError) {
             await this.onSessionExpired?.();
         }
@@ -134,7 +137,7 @@ class KoolbaseStorage {
         if (!uploadRes.ok) {
             // R2 PUT errors don't follow the Koolbase error shape — surface as a
             // generic storage error rather than trying to decode a Koolbase body.
-            throw new storage_errors_js_1.KoolbaseStorageError(`Upload to storage failed: ${uploadRes.status}`);
+            throw new storage_errors_js_2.KoolbaseStorageError(`Upload to storage failed: ${uploadRes.status}`);
         }
         const etag = uploadRes.headers.get('etag') ?? '';
         // ─── Step 3: Confirm upload ───
@@ -234,6 +237,23 @@ class KoolbaseStorage {
         const data = (await res.json());
         return data.url;
     }
+    /**
+     * The stable public CDN URL for a file in a public bucket, using the project
+     * identity the SDK learned at bootstrap -- the runtime form of
+     * {@link KoolbaseStorage.publicUrl}, needing no projectId (as Flutter's).
+     *
+     * Throws {@link KoolbaseStorageProjectIdentityError} while identity is
+     * unavailable, and nudges a background bootstrap refresh so a later call in
+     * the same session succeeds once connectivity returns.
+     */
+    publicUrlFor(args) {
+        const pid = this.projectIdProvider?.() ?? '';
+        if (pid === '') {
+            this.nudgeBootstrap?.();
+            throw new storage_errors_js_1.KoolbaseStorageProjectIdentityError();
+        }
+        return KoolbaseStorage.publicUrl({ projectId: pid, bucket: args.bucket, path: args.path, transform: args.transform });
+    }
     /**
      * Build the stable public CDN URL for a file in a public bucket.
      *

package/dist/cjs/types.d.ts

@@ -457,6 +457,9 @@ export interface RealtimeEvent {
 export type RealtimeCallback = (event: RealtimeEvent) => void;
 export interface BootstrapPayload {
     payload_version: string;
+    /** The project this public key belongs to: storage's publicUrlFor builds CDN
+     *  URLs with it. Absent from servers that predate identity metadata. */
+    project_id?: string;
     flags: Record<string, {
         enabled: boolean;
         rollout_percentage: number;

package/dist/esm/database.d.ts

@@ -207,8 +207,19 @@ export declare class KoolbaseDatabase {
      * already removed it locally.
      */
     private resolveBaseline;
-    update(recordId: string, data: Record<string, unknown>): Promise<KoolbaseRecord>;
-    delete(recordId: string): Promise<void>;
+    update(recordId: string, data: Record<string, unknown>, 
+    /** expectedRevision: apply only if the record still carries it; refused
+     *  with KoolbaseRevisionMismatchError otherwise (as the Flutter SDK). */
+    options?: {
+        expectedRevision?: number;
+    }): Promise<KoolbaseRecord>;
+    delete(recordId: string, 
+    /** expectedRevision: delete only if the record still carries it (as the
+     *  Flutter SDK) -- removing a record someone changed a moment ago is the
+     *  more destructive stale write. */
+    options?: {
+        expectedRevision?: number;
+    }): Promise<void>;
     /**
      * Write (or replace) a vector for a record on the named `field`.
      *

package/dist/esm/database.js

@@ -1,5 +1,6 @@
 import { koolbaseFetch } from './network.js';
 import { refreshCollectionQueries } from './query-refresh.js';
+import { KoolbaseRevisionMismatchError } from './database-errors.js';
 import { KoolbaseError, KoolbaseOfflineBaselineUnavailableError, KoolbaseUnauthenticatedError, } from './errors.js';
 import { cacheRecord, getCachedRecord, removeCachedRecord } from './cache-store.js';
 import { readOfflineState, mutateOfflineState, queueWrite, } from './offline-state.js';
@@ -227,7 +228,7 @@ export class KoolbaseDatabase {
      */
     async invalidate(collection) {
         await invalidateCache(this.getUserId() ?? 'anonymous', collection);
-        await refreshCollectionQueries(collection);
+        void refreshCollectionQueries(collection);
     }
     // ─── Insert (online-first with offline fallback) ───────────────────────────
     /**
@@ -251,7 +252,7 @@ export class KoolbaseDatabase {
             const raw = await this.request('POST', '/v1/sdk/db/insert', { collection, data });
             const record = recordFromWire(raw);
             await invalidateCache(userId, collection);
-            await refreshCollectionQueries(collection);
+            void refreshCollectionQueries(collection);
             // The response carries a fresh revision, so caching it keeps the
             // baseline current for whatever edits this record next.
             await cacheRecord(userId, collection, record.id, record.data, record.revision);
@@ -326,7 +327,7 @@ export class KoolbaseDatabase {
         // Keep the cache fresh, same intent as insert's post-success invalidate.
         const userId = this.getUserId() ?? 'anonymous';
         await invalidateCache(userId, collection);
-        await refreshCollectionQueries(collection);
+        void refreshCollectionQueries(collection);
         await cacheRecord(userId, collection, record.id, record.data, record.revision);
         return { record, created };
     }
@@ -346,7 +347,7 @@ export class KoolbaseDatabase {
         const body = await this.request('POST', '/v1/sdk/db/delete-where', { collection, filters });
         const userId = this.getUserId() ?? 'anonymous';
         await invalidateCache(userId, collection);
-        await refreshCollectionQueries(collection);
+        void refreshCollectionQueries(collection);
         return body.deleted ?? 0;
     }
     // ─── Batch (atomic, online-only) ────────────────────────────────────────────
@@ -410,7 +411,7 @@ export class KoolbaseDatabase {
         }
         for (const col of touched) {
             await invalidateCache(userId, col);
-            await refreshCollectionQueries(col);
+            void refreshCollectionQueries(col);
         }
         return results;
     }
@@ -602,7 +603,7 @@ export class KoolbaseDatabase {
         }
         await this.dropConflict(c.id);
         await invalidateCache(this.getUserId() ?? 'anonymous', c.collection);
-        await refreshCollectionQueries(c.collection);
+        void refreshCollectionQueries(c.collection);
     }
     // ─── Update (online-first with offline fallback) ───────────────────────────
     /**
@@ -659,12 +660,15 @@ export class KoolbaseDatabase {
             return null;
         return { baseline: cached.data, revision: cached.revision, collection: cached.collection };
     }
-    async update(recordId, data) {
+    async update(recordId, data, 
+    /** expectedRevision: apply only if the record still carries it; refused
+     *  with KoolbaseRevisionMismatchError otherwise (as the Flutter SDK). */
+    options = {}) {
         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 raw = await this.request('PATCH', `/v1/sdk/db/records/${recordId}`, { data, ...(options.expectedRevision !== undefined ? { expected_revision: options.expectedRevision } : {}) });
             const updated = recordFromWire(raw);
             // Its collection's live queries re-run (every one, if the record's
             // collection is not known).
@@ -672,7 +676,7 @@ export class KoolbaseDatabase {
             if (updated.collection) {
                 await cacheRecord(userId, updated.collection, updated.id, updated.data, updated.revision);
             }
-            await refreshCollectionQueries(refreshed);
+            void refreshCollectionQueries(refreshed);
             return updated;
         }
         catch (e) {
@@ -682,6 +686,10 @@ export class KoolbaseDatabase {
             // 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.
+            // Refused as stale: the server holds newer data, so show it -- the
+            // collection's live queries re-run in the background (as Flutter).
+            if (e instanceof KoolbaseRevisionMismatchError)
+                void refreshCollectionQueries(base?.collection);
             if (e instanceof KoolbaseError)
                 throw e;
             // Genuine network failure. Queueable only if the SDK knows what the
@@ -713,15 +721,19 @@ export class KoolbaseDatabase {
         }
     }
     // ─── Delete ─────────────────────────────────────────────────────────────────
-    async delete(recordId) {
+    async delete(recordId, 
+    /** expectedRevision: delete only if the record still carries it (as the
+     *  Flutter SDK) -- removing a record someone changed a moment ago is the
+     *  more destructive stale write. */
+    options = {}) {
         const userId = this.getUserId() ?? 'anonymous';
         const base = await this.resolveBaseline(userId, recordId);
         try {
-            await this.request('DELETE', `/v1/sdk/db/records/${recordId}`);
+            await this.request('DELETE', `/v1/sdk/db/records/${recordId}${options.expectedRevision !== undefined ? `?expected_revision=${options.expectedRevision}` : ''}`);
             await removeCachedRecord(userId, recordId);
             // Its collection is known from the baseline when the record was seen;
             // otherwise every live query re-runs, rather than a guess.
-            await refreshCollectionQueries(base?.collection);
+            void refreshCollectionQueries(base?.collection);
         }
         catch (e) {
             // A server that answered has refused: a permission denial or a missing
@@ -732,6 +744,10 @@ export class KoolbaseDatabase {
             // 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.
+            // Refused as stale: the server holds newer data, so show it -- the
+            // collection's live queries re-run in the background (as Flutter).
+            if (e instanceof KoolbaseRevisionMismatchError)
+                void refreshCollectionQueries(base?.collection);
             if (e instanceof KoolbaseError)
                 throw e;
             // Genuine network failure. Queued here rather than before the request,

package/dist/esm/flags.d.ts

@@ -3,8 +3,21 @@ export declare class KoolbaseFlags {
     private config;
     private payload;
     private deviceId;
+    private lastArgs;
+    private inFlight;
     constructor(config: KoolbaseConfig, deviceId: string);
     koolbaseFetch(appVersion: string, platform: string): Promise<void>;
+    /**
+     * The project id learned from the bootstrap payload, or '' while the first
+     * bootstrap has not completed (storage's publicUrlFor reads it).
+     */
+    projectId(): string;
+    /**
+     * Fetch the bootstrap payload again with the last arguments -- a nudge from
+     * storage when identity is missing, so a startup failure heals within the
+     * session. One fetch at a time; never throws.
+     */
+    refresh(): Promise<void>;
     isEnabled(key: string): boolean;
     getString(key: string, fallback?: string): string;
     getNumber(key: string, fallback?: number): number;

package/dist/esm/flags.js

@@ -2,10 +2,15 @@ import { koolbaseFetch } from './network.js';
 export class KoolbaseFlags {
     constructor(config, deviceId) {
         this.payload = null;
+        // The last bootstrap's arguments, so a nudge can refresh with the same ones;
+        // and the fetch in flight, so nudges never stack.
+        this.lastArgs = null;
+        this.inFlight = null;
         this.config = config;
         this.deviceId = deviceId;
     }
     async koolbaseFetch(appVersion, platform) {
+        this.lastArgs = { appVersion, platform };
         try {
             const res = await koolbaseFetch(`${this.config.baseUrl}/v1/bootstrap?public_key=${this.config.publicKey}&device_id=${this.deviceId}&app_version=${appVersion}&platform=${platform}`);
             if (res.ok) {
@@ -14,6 +19,25 @@ export class KoolbaseFlags {
         }
         catch (_) { }
     }
+    /**
+     * The project id learned from the bootstrap payload, or '' while the first
+     * bootstrap has not completed (storage's publicUrlFor reads it).
+     */
+    projectId() {
+        return this.payload?.project_id ?? '';
+    }
+    /**
+     * Fetch the bootstrap payload again with the last arguments -- a nudge from
+     * storage when identity is missing, so a startup failure heals within the
+     * session. One fetch at a time; never throws.
+     */
+    refresh() {
+        if (this.inFlight)
+            return this.inFlight;
+        const args = this.lastArgs ?? { appVersion: this.config.appVersion ?? '0.0.0', platform: 'unknown' };
+        this.inFlight = this.koolbaseFetch(args.appVersion, args.platform).finally(() => { this.inFlight = null; });
+        return this.inFlight;
+    }
     isEnabled(key) {
         const flag = this.payload?.flags[key];
         if (!flag || !flag.enabled || flag.kill_switch)

package/dist/esm/storage-errors.d.ts

@@ -7,6 +7,22 @@ import { KoolbaseError } from './errors.js';
 export declare class KoolbaseStorageError extends KoolbaseError {
     constructor(message: string, code?: string);
 }
+/**
+ * Thrown by {@link KoolbaseStorage.publicUrlFor} when the SDK has not yet
+ * learned which project it belongs to. Project identity arrives with the
+ * bootstrap payload; it is unavailable until the first bootstrap completes
+ * (an app starting offline) or when the server predates identity metadata.
+ *
+ * A DIFFERENT state from a `null` public URL: null means the project is
+ * known but the object cannot have a public URL (private bucket). This one is
+ * transient: it heals on the next successful bootstrap, which calling
+ * publicUrlFor also nudges.
+ *
+ * Stable `code`: `project_identity_unavailable`.
+ */
+export declare class KoolbaseStorageProjectIdentityError extends KoolbaseStorageError {
+    constructor();
+}
 /**
  * Thrown when an upload is rejected because an object already exists at
  * the requested path — the server responds with 409 Conflict and code

package/dist/esm/storage-errors.js

@@ -11,6 +11,26 @@ export class KoolbaseStorageError extends KoolbaseError {
         Object.setPrototypeOf(this, KoolbaseStorageError.prototype);
     }
 }
+/**
+ * Thrown by {@link KoolbaseStorage.publicUrlFor} when the SDK has not yet
+ * learned which project it belongs to. Project identity arrives with the
+ * bootstrap payload; it is unavailable until the first bootstrap completes
+ * (an app starting offline) or when the server predates identity metadata.
+ *
+ * A DIFFERENT state from a `null` public URL: null means the project is
+ * known but the object cannot have a public URL (private bucket). This one is
+ * transient: it heals on the next successful bootstrap, which calling
+ * publicUrlFor also nudges.
+ *
+ * Stable `code`: `project_identity_unavailable`.
+ */
+export class KoolbaseStorageProjectIdentityError extends KoolbaseStorageError {
+    constructor() {
+        super('The SDK has not yet learned its project identity -- it arrives with the first successful bootstrap. Retry after connectivity is available.', 'project_identity_unavailable');
+        this.name = 'KoolbaseStorageProjectIdentityError';
+        Object.setPrototypeOf(this, KoolbaseStorageProjectIdentityError.prototype);
+    }
+}
 /**
  * Thrown when an upload is rejected because an object already exists at
  * the requested path — the server responds with 409 Conflict and code

package/dist/esm/storage.d.ts

@@ -19,7 +19,11 @@ export declare class KoolbaseStorage {
      * keeps believing it is signed in.
      */
     private onSessionExpired?;
-    constructor(config: KoolbaseConfig, getToken: () => Promise<string | null>, onSessionExpired?: () => Promise<void>);
+    /** The project id from the bootstrap payload, '' until it arrives. */
+    private projectIdProvider?;
+    /** A background bootstrap refresh, nudged when identity is missing. */
+    private nudgeBootstrap?;
+    constructor(config: KoolbaseConfig, getToken: () => Promise<string | null>, onSessionExpired?: () => Promise<void>, projectIdProvider?: () => string, nudgeBootstrap?: () => void);
     /**
      * Builds the error for a failed response and clears the session when the
      * credentials were refused, before the error reaches the caller.
@@ -87,6 +91,20 @@ export declare class KoolbaseStorage {
      * Get a signed download URL for a file.
      */
     getDownloadUrl(bucket: string, path: string, versionId?: string): Promise<string>;
+    /**
+     * The stable public CDN URL for a file in a public bucket, using the project
+     * identity the SDK learned at bootstrap -- the runtime form of
+     * {@link KoolbaseStorage.publicUrl}, needing no projectId (as Flutter's).
+     *
+     * Throws {@link KoolbaseStorageProjectIdentityError} while identity is
+     * unavailable, and nudges a background bootstrap refresh so a later call in
+     * the same session succeeds once connectivity returns.
+     */
+    publicUrlFor(args: {
+        bucket: string;
+        path: string;
+        transform?: KoolbaseImageTransform;
+    }): string;
     /**
      * Build the stable public CDN URL for a file in a public bucket.
      *

package/dist/esm/storage.js

@@ -1,3 +1,4 @@
+import { KoolbaseStorageProjectIdentityError } from './storage-errors.js';
 import { koolbaseFetch } from './network.js';
 import { KoolbaseUnauthenticatedError } from './errors.js';
 import { KoolbaseStorageError, koolbaseStorageErrorFromResponse, } from './storage-errors.js';
@@ -39,10 +40,12 @@ function serializeTransform(t) {
  * `overwrite: true` is passed.
  */
 export class KoolbaseStorage {
-    constructor(config, getToken, onSessionExpired) {
+    constructor(config, getToken, onSessionExpired, projectIdProvider, nudgeBootstrap) {
         this.config = config;
         this.getToken = getToken;
         this.onSessionExpired = onSessionExpired;
+        this.projectIdProvider = projectIdProvider;
+        this.nudgeBootstrap = nudgeBootstrap;
     }
     /**
      * Builds the error for a failed response and clears the session when the
@@ -231,6 +234,23 @@ export class KoolbaseStorage {
         const data = (await res.json());
         return data.url;
     }
+    /**
+     * The stable public CDN URL for a file in a public bucket, using the project
+     * identity the SDK learned at bootstrap -- the runtime form of
+     * {@link KoolbaseStorage.publicUrl}, needing no projectId (as Flutter's).
+     *
+     * Throws {@link KoolbaseStorageProjectIdentityError} while identity is
+     * unavailable, and nudges a background bootstrap refresh so a later call in
+     * the same session succeeds once connectivity returns.
+     */
+    publicUrlFor(args) {
+        const pid = this.projectIdProvider?.() ?? '';
+        if (pid === '') {
+            this.nudgeBootstrap?.();
+            throw new KoolbaseStorageProjectIdentityError();
+        }
+        return KoolbaseStorage.publicUrl({ projectId: pid, bucket: args.bucket, path: args.path, transform: args.transform });
+    }
     /**
      * Build the stable public CDN URL for a file in a public bucket.
      *

package/dist/esm/types.d.ts

@@ -457,6 +457,9 @@ export interface RealtimeEvent {
 export type RealtimeCallback = (event: RealtimeEvent) => void;
 export interface BootstrapPayload {
     payload_version: string;
+    /** The project this public key belongs to: storage's publicUrlFor builds CDN
+     *  URLs with it. Absent from servers that predate identity metadata. */
+    project_id?: string;
     flags: Record<string, {
         enabled: boolean;
         rollout_percentage: number;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@koolbase/core",
-  "version": "12.7.0",
-  "description": "Koolbase SDK core — shared behaviour behind @koolbase/react-native and @koolbase/js. Install one of those, not this.",
+  "version": "12.9.0",
+  "description": "Koolbase SDK core \u2014 shared behaviour behind @koolbase/react-native and @koolbase/js. Install one of those, not this.",
   "main": "./dist/cjs/index.js",
   "types": "./dist/esm/index.d.ts",
   "files": [