@koolbase/core 12.2.0 → 12.3.0

package/dist/cjs/analytics.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KoolbaseAnalytics = void 0;
+const network_js_1 = require("./network.js");
 const platform_js_1 = require("./platform.js");
 const device_id_js_1 = require("./device-id.js");
 // ─── KoolbaseAnalytics ───────────────────────────────────────────────────────
@@ -102,7 +103,7 @@ class KoolbaseAnalytics {
         const batch = [...this.queue];
         this.queue = [];
         try {
-            const response = await fetch(`${this.config.baseUrl}/v1/analytics/events`, {
+            const response = await (0, network_js_1.koolbaseFetch)(`${this.config.baseUrl}/v1/analytics/events`, {
                 method: 'POST',
                 headers: {
                     'Content-Type': 'application/json',

package/dist/cjs/auth.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KoolbaseAuth = void 0;
+const network_js_1 = require("./network.js");
 const types_js_1 = require("./types.js");
 const auth_errors_js_1 = require("./auth-errors.js");
 const platform_js_1 = require("./platform.js");
@@ -12,7 +13,7 @@ class KoolbaseAuth {
         this.listeners = new Set();
         this.config = config;
         this.metadata = new device_metadata_js_1.DeviceMetadata(config.appVersion);
-        this.fetchFn = config.fetch ?? ((url, init) => fetch(url, init));
+        this.fetchFn = config.fetch ?? ((url, init) => (0, network_js_1.koolbaseFetch)(url, init));
         this.timeoutMs = config.authTimeout ?? 10000;
         if (config.authStorage) {
             this.storage = config.authStorage;

package/dist/cjs/database.d.ts

@@ -47,6 +47,12 @@ export declare class KoolbaseDatabase {
      * store for `update`/`delete`.
      */
     query(collection: string, options?: QueryOptions): Promise<QueryResult>;
+    /**
+     * Forget this client's cached query results for a collection, so the next
+     * `query` waits for the server. For data changed elsewhere: by a Function,
+     * a server, or another user. The SDK's own writes already do this.
+     */
+    invalidate(collection: string): Promise<void>;
     /**
      * Insert a new record into a collection.
      *

package/dist/cjs/database.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KoolbaseDatabase = void 0;
+const network_js_1 = require("./network.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");
@@ -88,7 +89,7 @@ class KoolbaseDatabase {
         };
     }
     async request(method, path, body) {
-        const res = await fetch(`${this.config.baseUrl}${path}`, {
+        const res = await (0, network_js_1.koolbaseFetch)(`${this.config.baseUrl}${path}`, {
             method,
             headers: await this.buildHeaders(),
             body: body ? JSON.stringify(body) : undefined,
@@ -126,7 +127,7 @@ class KoolbaseDatabase {
      * 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}`, {
+        const res = await (0, network_js_1.koolbaseFetch)(`${this.config.baseUrl}${path}`, {
             method,
             headers: await this.buildHeaders(),
             body: body ? JSON.stringify(body) : undefined,
@@ -197,20 +198,31 @@ class KoolbaseDatabase {
      */
     async query(collection, options = {}) {
         const userId = this.getUserId() ?? 'anonymous';
-        const queryHash = (0, cache_store_js_2.hashQuery)(collection, options);
-        const cached = await (0, cache_store_js_2.getCached)(userId, collection, queryHash);
+        // The cache policy is how to read, not what to read: it stays out of the
+        // query's identity, so both policies share one cache entry.
+        const { cache: cachePolicy, ...queryOptions } = options;
+        const queryHash = (0, cache_store_js_2.hashQuery)(collection, queryOptions);
+        const cached = cachePolicy === 'network-only' ? null : await (0, cache_store_js_2.getCached)(userId, collection, queryHash);
         if (cached) {
-            this.runQuery(collection, options)
+            this.runQuery(collection, queryOptions)
                 .then(result => (0, cache_store_js_2.setCached)(userId, collection, queryHash, result))
                 .catch(() => {
                 // Network unavailable — cached data already returned
             });
             return { ...cached, isFromCache: true };
         }
-        const result = await this.runQuery(collection, options);
+        const result = await this.runQuery(collection, queryOptions);
         await (0, cache_store_js_2.setCached)(userId, collection, queryHash, result);
         return { ...result, isFromCache: false };
     }
+    /**
+     * Forget this client's cached query results for a collection, so the next
+     * `query` waits for the server. For data changed elsewhere: by a Function,
+     * a server, or another user. The SDK's own writes already do this.
+     */
+    async invalidate(collection) {
+        await (0, cache_store_js_2.invalidateCache)(this.getUserId() ?? 'anonymous', collection);
+    }
     // ─── Insert (online-first with offline fallback) ───────────────────────────
     /**
      * Insert a new record into a collection.

package/dist/cjs/fiscal.js

@@ -4,6 +4,7 @@ exports.KoolbaseFiscal = exports.KoolbaseFiscalError = void 0;
 exports.isFiscalized = isFiscalized;
 exports.isPending = isPending;
 exports.decodeFiscalResponse = decodeFiscalResponse;
+const network_js_1 = require("./network.js");
 const errors_js_1 = require("./errors.js");
 const KNOWN_STATUSES = [
     'created', 'blocked', 'queued', 'submitting',
@@ -112,7 +113,7 @@ class KoolbaseFiscal {
         const controller = new AbortController();
         const timer = setTimeout(() => controller.abort(), params.timeoutMs ?? 30000);
         try {
-            const res = await fetch(`${this.config.baseUrl}/v1/sdk/fiscal/submit`, {
+            const res = await (0, network_js_1.koolbaseFetch)(`${this.config.baseUrl}/v1/sdk/fiscal/submit`, {
                 method: 'POST',
                 headers: await this.buildHeaders(),
                 signal: controller.signal,
@@ -150,7 +151,7 @@ class KoolbaseFiscal {
                 device_id: params.deviceId,
                 client_ref: params.clientRef,
             });
-            const res = await fetch(`${this.config.baseUrl}/v1/sdk/fiscal/status?${q.toString()}`, { method: 'GET', headers: await this.buildHeaders(), signal: controller.signal });
+            const res = await (0, network_js_1.koolbaseFetch)(`${this.config.baseUrl}/v1/sdk/fiscal/status?${q.toString()}`, { method: 'GET', headers: await this.buildHeaders(), signal: controller.signal });
             return await this.decode(res);
         }
         catch (e) {

package/dist/cjs/flags.d.ts

@@ -4,7 +4,7 @@ export declare class KoolbaseFlags {
     private payload;
     private deviceId;
     constructor(config: KoolbaseConfig, deviceId: string);
-    fetch(appVersion: string, platform: string): Promise<void>;
+    koolbaseFetch(appVersion: string, platform: string): Promise<void>;
     isEnabled(key: string): boolean;
     getString(key: string, fallback?: string): string;
     getNumber(key: string, fallback?: number): number;

package/dist/cjs/flags.js

@@ -1,15 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KoolbaseFlags = void 0;
+const network_js_1 = require("./network.js");
 class KoolbaseFlags {
     constructor(config, deviceId) {
         this.payload = null;
         this.config = config;
         this.deviceId = deviceId;
     }
-    async fetch(appVersion, platform) {
+    async koolbaseFetch(appVersion, platform) {
         try {
-            const res = await fetch(`${this.config.baseUrl}/v1/bootstrap?public_key=${this.config.publicKey}&device_id=${this.deviceId}&app_version=${appVersion}&platform=${platform}`);
+            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) {
                 this.payload = await res.json();
             }

package/dist/cjs/functions.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KoolbaseFunctions = void 0;
+const network_js_1 = require("./network.js");
 const function_errors_js_1 = require("./function-errors.js");
 const errors_js_1 = require("./errors.js");
 const types_js_1 = require("./types.js");
@@ -13,7 +14,7 @@ class KoolbaseFunctions {
     // ─── Deploy ────────────────────────────────────────────────────────────────
     async deploy(options) {
         const runtime = options.runtime ?? types_js_1.FunctionRuntime.Deno;
-        const res = await fetch(`${this.config.baseUrl}/v1/sdk/functions/deploy`, {
+        const res = await (0, network_js_1.koolbaseFetch)(`${this.config.baseUrl}/v1/sdk/functions/deploy`, {
             method: 'POST',
             headers: {
                 'Content-Type': 'application/json',
@@ -57,7 +58,7 @@ class KoolbaseFunctions {
         if (userToken) {
             headers['Authorization'] = `Bearer ${userToken}`;
         }
-        const res = await fetch(`${this.config.baseUrl}/v1/sdk/functions/${name}`, {
+        const res = await (0, network_js_1.koolbaseFetch)(`${this.config.baseUrl}/v1/sdk/functions/${name}`, {
             method: 'POST',
             headers,
             body: JSON.stringify({ body: body ?? {} }),

package/dist/cjs/index.d.ts

@@ -1,5 +1,6 @@
 export * from './types.js';
 export * from './errors.js';
+export * from './network.js';
 export * from './aggregate.js';
 export * from './conflict.js';
 export * from './pending-write.js';

package/dist/cjs/index.js

@@ -22,6 +22,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.memoryPlatform = exports.getPlatform = exports.setPlatform = exports.RestoreResult = exports.koolbaseSdkVersion = exports.getOrCreateDeviceId = exports.KoolbaseMessaging = exports.isPending = exports.isFiscalized = exports.decodeFiscalResponse = exports.KoolbaseFiscalError = exports.KoolbaseFiscal = exports.KoolbaseAnalytics = exports.KoolbaseStorage = exports.KoolbaseRealtime = exports.KoolbaseFunctions = exports.KoolbaseFlags = exports.KoolbaseDatabase = exports.KoolbaseAuth = void 0;
 __exportStar(require("./types.js"), exports);
 __exportStar(require("./errors.js"), exports);
+__exportStar(require("./network.js"), exports);
 __exportStar(require("./aggregate.js"), exports);
 __exportStar(require("./conflict.js"), exports);
 __exportStar(require("./pending-write.js"), exports);

package/dist/cjs/messaging.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KoolbaseMessaging = void 0;
+const network_js_1 = require("./network.js");
 // ─── KoolbaseMessaging ────────────────────────────────────────────────────────
 class KoolbaseMessaging {
     constructor(config) {
@@ -13,7 +14,7 @@ class KoolbaseMessaging {
     // ─── Register token ───────────────────────────────────────────────────────
     async registerToken(options) {
         try {
-            const response = await fetch(`${this.config.baseUrl}/v1/messaging/register`, {
+            const response = await (0, network_js_1.koolbaseFetch)(`${this.config.baseUrl}/v1/messaging/register`, {
                 method: 'POST',
                 headers: {
                     'Content-Type': 'application/json',

package/dist/cjs/network.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Network failures, made actionable.
+ *
+ * A browser rejects a request it may not make cross-origin with the same bare
+ * TypeError ("Failed to fetch") as a dead network, and deliberately hides which
+ * it was. The SDK cannot tell them apart either, so it names the likely causes,
+ * starting with the one only the app's developer can fix: Trusted Origins.
+ *
+ * It stays a TypeError, so code that tells a network failure from a server
+ * rejection that way (the offline queue) behaves exactly as before.
+ */
+export declare class KoolbaseNetworkError extends TypeError {
+    code: string;
+    readonly url: string;
+    readonly origin?: string;
+    constructor(url: string, cause: unknown);
+}
+/** fetch, with network failures turned into a KoolbaseNetworkError. */
+export declare function koolbaseFetch(input: string, init?: RequestInit): Promise<Response>;

package/dist/cjs/network.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KoolbaseNetworkError = void 0;
+exports.koolbaseFetch = koolbaseFetch;
+/**
+ * Network failures, made actionable.
+ *
+ * A browser rejects a request it may not make cross-origin with the same bare
+ * TypeError ("Failed to fetch") as a dead network, and deliberately hides which
+ * it was. The SDK cannot tell them apart either, so it names the likely causes,
+ * starting with the one only the app's developer can fix: Trusted Origins.
+ *
+ * It stays a TypeError, so code that tells a network failure from a server
+ * rejection that way (the offline queue) behaves exactly as before.
+ */
+class KoolbaseNetworkError extends TypeError {
+    constructor(url, cause) {
+        const loc = globalThis.location;
+        const origin = loc?.origin && loc.origin !== 'null' ? loc.origin : undefined;
+        const reason = cause instanceof Error ? cause.message : String(cause);
+        let host = url;
+        try {
+            host = new URL(url).origin;
+        }
+        catch {
+            // keep the raw url
+        }
+        let message = `Could not reach Koolbase at ${host} (${reason}).`;
+        message += origin
+            ? ` If you are online, check that this site's address (${origin}) is in the project's Trusted Origins in the Koolbase dashboard.`
+            : ' Check the network connection and the configured base URL.';
+        super(message);
+        this.code = 'network_error';
+        this.name = 'KoolbaseNetworkError';
+        this.url = url;
+        this.origin = origin;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.KoolbaseNetworkError = KoolbaseNetworkError;
+/** fetch, with network failures turned into a KoolbaseNetworkError. */
+async function koolbaseFetch(input, init) {
+    try {
+        return await fetch(input, init);
+    }
+    catch (e) {
+        // A request the caller cancelled keeps its meaning.
+        if (e?.name === 'AbortError')
+            throw e;
+        throw new KoolbaseNetworkError(input, e);
+    }
+}

package/dist/cjs/storage.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KoolbaseStorage = void 0;
+const network_js_1 = require("./network.js");
 const errors_js_1 = require("./errors.js");
 const storage_errors_js_1 = require("./storage-errors.js");
 // --- Cloudflare image-transform URL helpers -------------------------------
@@ -97,7 +98,7 @@ class KoolbaseStorage {
             ? options.file.type || 'application/octet-stream'
             : options.file.type;
         // ─── Step 1: Get presigned upload URL ───
-        const urlRes = await fetch(`${this.config.baseUrl}/v1/sdk/storage/upload-url`, {
+        const urlRes = await (0, network_js_1.koolbaseFetch)(`${this.config.baseUrl}/v1/sdk/storage/upload-url`, {
             method: 'POST',
             headers: {
                 ...(await this.buildHeaders()),
@@ -123,9 +124,9 @@ class KoolbaseStorage {
         // the two hosts differ here and nowhere else in this method.
         const fileBlob = isBlob
             ? options.file
-            : await (await fetch(options.file.uri)).blob();
+            : await (await (0, network_js_1.koolbaseFetch)(options.file.uri)).blob();
         const fileSize = fileBlob.size;
-        const uploadRes = await fetch(upload_url, {
+        const uploadRes = await (0, network_js_1.koolbaseFetch)(upload_url, {
             method: 'PUT',
             headers: { 'Content-Type': contentType },
             body: fileBlob,
@@ -152,7 +153,7 @@ class KoolbaseStorage {
         if (options.metadata !== undefined) {
             confirmBody.metadata = options.metadata;
         }
-        const confirmRes = await fetch(`${this.config.baseUrl}/v1/sdk/storage/confirm`, {
+        const confirmRes = await (0, network_js_1.koolbaseFetch)(`${this.config.baseUrl}/v1/sdk/storage/confirm`, {
             method: 'POST',
             headers: {
                 ...(await this.buildHeaders()),
@@ -203,7 +204,7 @@ class KoolbaseStorage {
      * // -> { category: 'landscape', tag: 'sunset' }
      */
     async updateMetadata(bucket, path, metadata) {
-        const res = await fetch(`${this.config.baseUrl}/v1/sdk/storage/objects/metadata`, {
+        const res = await (0, network_js_1.koolbaseFetch)(`${this.config.baseUrl}/v1/sdk/storage/objects/metadata`, {
             method: 'PATCH',
             headers: {
                 ...(await this.buildHeaders()),
@@ -226,7 +227,7 @@ class KoolbaseStorage {
         if (versionId) {
             url += `&version_id=${encodeURIComponent(versionId)}`;
         }
-        const res = await fetch(url, { headers: await this.buildHeaders() });
+        const res = await (0, network_js_1.koolbaseFetch)(url, { headers: await this.buildHeaders() });
         if (!res.ok) {
             throw await this.error(res, 'Failed to get download URL');
         }
@@ -321,7 +322,7 @@ class KoolbaseStorage {
         const url = forcePurge
             ? `${this.config.baseUrl}/v1/sdk/storage/object?force_purge=true`
             : `${this.config.baseUrl}/v1/sdk/storage/object`;
-        const res = await fetch(url, {
+        const res = await (0, network_js_1.koolbaseFetch)(url, {
             method: 'DELETE',
             headers: {
                 ...(await this.buildHeaders()),
@@ -348,7 +349,7 @@ class KoolbaseStorage {
     async listVersions(bucket, path) {
         const url = `${this.config.baseUrl}/v1/sdk/storage/object-versions` +
             `?bucket=${encodeURIComponent(bucket)}&path=${encodeURIComponent(path)}`;
-        const res = await fetch(url, { headers: await this.buildHeaders() });
+        const res = await (0, network_js_1.koolbaseFetch)(url, { headers: await this.buildHeaders() });
         if (!res.ok) {
             throw await this.error(res, 'Failed to list versions');
         }
@@ -364,7 +365,7 @@ class KoolbaseStorage {
     async getVersion(bucket, path, versionId) {
         const url = `${this.config.baseUrl}/v1/sdk/storage/object-versions/${encodeURIComponent(versionId)}` +
             `?bucket=${encodeURIComponent(bucket)}&path=${encodeURIComponent(path)}`;
-        const res = await fetch(url, { headers: await this.buildHeaders() });
+        const res = await (0, network_js_1.koolbaseFetch)(url, { headers: await this.buildHeaders() });
         if (!res.ok) {
             throw await this.error(res, 'Failed to fetch version');
         }
@@ -383,7 +384,7 @@ class KoolbaseStorage {
     async restoreVersion(bucket, path, versionId) {
         const url = `${this.config.baseUrl}/v1/sdk/storage/object-versions/${encodeURIComponent(versionId)}/restore` +
             `?bucket=${encodeURIComponent(bucket)}&path=${encodeURIComponent(path)}`;
-        const res = await fetch(url, {
+        const res = await (0, network_js_1.koolbaseFetch)(url, {
             method: 'POST',
             headers: await this.buildHeaders(),
         });
@@ -401,7 +402,7 @@ class KoolbaseStorage {
     async purgeVersion(bucket, path, versionId) {
         const url = `${this.config.baseUrl}/v1/sdk/storage/object-versions/${encodeURIComponent(versionId)}` +
             `?bucket=${encodeURIComponent(bucket)}&path=${encodeURIComponent(path)}`;
-        const res = await fetch(url, {
+        const res = await (0, network_js_1.koolbaseFetch)(url, {
             method: 'DELETE',
             headers: await this.buildHeaders(),
         });

package/dist/cjs/sync-engine.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SyncEngine = void 0;
+const network_js_1 = require("./network.js");
 const offline_state_js_1 = require("./offline-state.js");
 const errors_js_1 = require("./errors.js");
 const platform_js_1 = require("./platform.js");
@@ -245,7 +246,7 @@ class SyncEngine {
             : `${this.config.baseUrl}/v1/sdk/db/records/${write.recordId}`;
         let res;
         if (write.operation === 'insert') {
-            res = await fetch(url, {
+            res = await (0, network_js_1.koolbaseFetch)(url, {
                 method: 'POST',
                 headers,
                 // The write's own id: generated at enqueue, identical on every retry.
@@ -259,7 +260,7 @@ class SyncEngine {
             });
         }
         else if (write.operation === 'update') {
-            res = await fetch(url, {
+            res = await (0, network_js_1.koolbaseFetch)(url, {
                 method: 'PATCH',
                 headers,
                 // The revision the change was composed against. The server applies it
@@ -278,7 +279,7 @@ class SyncEngine {
             const q = write.baseRevision !== undefined
                 ? `?expected_revision=${write.baseRevision}`
                 : '';
-            res = await fetch(`${url}${q}`, { method: 'DELETE', headers });
+            res = await (0, network_js_1.koolbaseFetch)(`${url}${q}`, { method: 'DELETE', headers });
         }
         if (res.status === 401)
             throw new errors_js_1.KoolbaseUnauthenticatedError('unauthorized');

package/dist/cjs/types.d.ts

@@ -239,6 +239,13 @@ export interface QueryOptions {
     orderBy?: string;
     orderDesc?: boolean;
     populate?: string[];
+    /**
+     * How to read: 'default' is cache-first, refreshed in the background;
+     * 'network-only' skips the cache and waits for the server (the result still
+     * refreshes the cache). Use 'network-only' after a write this client did not
+     * make, by a Function or another user, when you need the server's state now.
+     */
+    cache?: 'default' | 'network-only';
 }
 export interface QueryResult {
     records: KoolbaseRecord[];

package/dist/esm/analytics.js

@@ -1,3 +1,4 @@
+import { koolbaseFetch } from './network.js';
 import { getPlatform } from './platform.js';
 import { getOrCreateDeviceId } from './device-id.js';
 // ─── KoolbaseAnalytics ───────────────────────────────────────────────────────
@@ -99,7 +100,7 @@ export class KoolbaseAnalytics {
         const batch = [...this.queue];
         this.queue = [];
         try {
-            const response = await fetch(`${this.config.baseUrl}/v1/analytics/events`, {
+            const response = await koolbaseFetch(`${this.config.baseUrl}/v1/analytics/events`, {
                 method: 'POST',
                 headers: {
                     'Content-Type': 'application/json',

package/dist/esm/auth.js

@@ -1,3 +1,4 @@
+import { koolbaseFetch } from './network.js';
 import { RestoreResult, } from './types.js';
 import { AccountLockedError, EmailAlreadyInUseError, InvalidCredentialsError, InvalidPhoneNumberError, KoolbaseAuthError, OtpExpiredError, OtpInvalidError, OtpMaxAttemptsError, OtpRateLimitError, PhoneAlreadyLinkedError, IdentityNotFoundError, InsufficientScopeError, MalformedSessionResponseError, ProviderIdentityAlreadyLinkedError, AccountExistsError, ContactNotVerifiedError, CurrentPasswordIncorrectError, HideRequiresVerificationError, InsufficientAuthorityError, LastCredentialError, OAuthOnlyAccountError, SessionRequiredError, SignupsDisabledError, TokenAlreadyUsedError, TokenExpiredError, UnsupportedOAuthProviderError, RateLimitError, VerificationResendCooldownError, VerificationResendDailyCapError, SessionExpiredError, SmsConfigMissingError, UnlockTokenInvalidError, UserDisabledError, WeakPasswordError, AppleEmailRequiredError, AppleSignInNotConfiguredError, InvalidAppleTokenError, OAuthEmailConflictError, GoogleEmailRequiredError, GoogleSignInNotConfiguredError, InvalidGoogleTokenError, EmailCodeDisabledError, MfaRequiredError, RecentAuthRequiredError, RecentMfaRequiredError, MfaAlreadyEnabledError, MfaEnrollmentNotFoundError, MfaNotEnabledError, } from './auth-errors.js';
 import { getPlatform } from './platform.js';
@@ -9,7 +10,7 @@ export class KoolbaseAuth {
         this.listeners = new Set();
         this.config = config;
         this.metadata = new DeviceMetadata(config.appVersion);
-        this.fetchFn = config.fetch ?? ((url, init) => fetch(url, init));
+        this.fetchFn = config.fetch ?? ((url, init) => koolbaseFetch(url, init));
         this.timeoutMs = config.authTimeout ?? 10000;
         if (config.authStorage) {
             this.storage = config.authStorage;

package/dist/esm/database.d.ts

@@ -47,6 +47,12 @@ export declare class KoolbaseDatabase {
      * store for `update`/`delete`.
      */
     query(collection: string, options?: QueryOptions): Promise<QueryResult>;
+    /**
+     * Forget this client's cached query results for a collection, so the next
+     * `query` waits for the server. For data changed elsewhere: by a Function,
+     * a server, or another user. The SDK's own writes already do this.
+     */
+    invalidate(collection: string): Promise<void>;
     /**
      * Insert a new record into a collection.
      *

package/dist/esm/database.js

@@ -1,3 +1,4 @@
+import { koolbaseFetch } from './network.js';
 import { KoolbaseError, KoolbaseOfflineBaselineUnavailableError, KoolbaseUnauthenticatedError, } from './errors.js';
 import { cacheRecord, getCachedRecord, removeCachedRecord } from './cache-store.js';
 import { readOfflineState, mutateOfflineState, queueWrite, } from './offline-state.js';
@@ -85,7 +86,7 @@ export class KoolbaseDatabase {
         };
     }
     async request(method, path, body) {
-        const res = await fetch(`${this.config.baseUrl}${path}`, {
+        const res = await koolbaseFetch(`${this.config.baseUrl}${path}`, {
             method,
             headers: await this.buildHeaders(),
             body: body ? JSON.stringify(body) : undefined,
@@ -123,7 +124,7 @@ export class KoolbaseDatabase {
      * 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}`, {
+        const res = await koolbaseFetch(`${this.config.baseUrl}${path}`, {
             method,
             headers: await this.buildHeaders(),
             body: body ? JSON.stringify(body) : undefined,
@@ -194,20 +195,31 @@ export class KoolbaseDatabase {
      */
     async query(collection, options = {}) {
         const userId = this.getUserId() ?? 'anonymous';
-        const queryHash = hashQuery(collection, options);
-        const cached = await getCached(userId, collection, queryHash);
+        // The cache policy is how to read, not what to read: it stays out of the
+        // query's identity, so both policies share one cache entry.
+        const { cache: cachePolicy, ...queryOptions } = options;
+        const queryHash = hashQuery(collection, queryOptions);
+        const cached = cachePolicy === 'network-only' ? null : await getCached(userId, collection, queryHash);
         if (cached) {
-            this.runQuery(collection, options)
+            this.runQuery(collection, queryOptions)
                 .then(result => setCached(userId, collection, queryHash, result))
                 .catch(() => {
                 // Network unavailable — cached data already returned
             });
             return { ...cached, isFromCache: true };
         }
-        const result = await this.runQuery(collection, options);
+        const result = await this.runQuery(collection, queryOptions);
         await setCached(userId, collection, queryHash, result);
         return { ...result, isFromCache: false };
     }
+    /**
+     * Forget this client's cached query results for a collection, so the next
+     * `query` waits for the server. For data changed elsewhere: by a Function,
+     * a server, or another user. The SDK's own writes already do this.
+     */
+    async invalidate(collection) {
+        await invalidateCache(this.getUserId() ?? 'anonymous', collection);
+    }
     // ─── Insert (online-first with offline fallback) ───────────────────────────
     /**
      * Insert a new record into a collection.

package/dist/esm/fiscal.js

@@ -1,3 +1,4 @@
+import { koolbaseFetch } from './network.js';
 import { KoolbaseError, KoolbaseUnauthenticatedError } from './errors.js';
 const KNOWN_STATUSES = [
     'created', 'blocked', 'queued', 'submitting',
@@ -105,7 +106,7 @@ export class KoolbaseFiscal {
         const controller = new AbortController();
         const timer = setTimeout(() => controller.abort(), params.timeoutMs ?? 30000);
         try {
-            const res = await fetch(`${this.config.baseUrl}/v1/sdk/fiscal/submit`, {
+            const res = await koolbaseFetch(`${this.config.baseUrl}/v1/sdk/fiscal/submit`, {
                 method: 'POST',
                 headers: await this.buildHeaders(),
                 signal: controller.signal,
@@ -143,7 +144,7 @@ export class KoolbaseFiscal {
                 device_id: params.deviceId,
                 client_ref: params.clientRef,
             });
-            const res = await fetch(`${this.config.baseUrl}/v1/sdk/fiscal/status?${q.toString()}`, { method: 'GET', headers: await this.buildHeaders(), signal: controller.signal });
+            const res = await koolbaseFetch(`${this.config.baseUrl}/v1/sdk/fiscal/status?${q.toString()}`, { method: 'GET', headers: await this.buildHeaders(), signal: controller.signal });
             return await this.decode(res);
         }
         catch (e) {

package/dist/esm/flags.d.ts

@@ -4,7 +4,7 @@ export declare class KoolbaseFlags {
     private payload;
     private deviceId;
     constructor(config: KoolbaseConfig, deviceId: string);
-    fetch(appVersion: string, platform: string): Promise<void>;
+    koolbaseFetch(appVersion: string, platform: string): Promise<void>;
     isEnabled(key: string): boolean;
     getString(key: string, fallback?: string): string;
     getNumber(key: string, fallback?: number): number;

package/dist/esm/flags.js

@@ -1,12 +1,13 @@
+import { koolbaseFetch } from './network.js';
 export class KoolbaseFlags {
     constructor(config, deviceId) {
         this.payload = null;
         this.config = config;
         this.deviceId = deviceId;
     }
-    async fetch(appVersion, platform) {
+    async koolbaseFetch(appVersion, platform) {
         try {
-            const res = await fetch(`${this.config.baseUrl}/v1/bootstrap?public_key=${this.config.publicKey}&device_id=${this.deviceId}&app_version=${appVersion}&platform=${platform}`);
+            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) {
                 this.payload = await res.json();
             }

package/dist/esm/functions.js

@@ -1,3 +1,4 @@
+import { koolbaseFetch } from './network.js';
 import { functionInvokeError } from './function-errors.js';
 import { KoolbaseUnauthenticatedError } from './errors.js';
 import { FunctionRuntime, } from './types.js';
@@ -10,7 +11,7 @@ export class KoolbaseFunctions {
     // ─── Deploy ────────────────────────────────────────────────────────────────
     async deploy(options) {
         const runtime = options.runtime ?? FunctionRuntime.Deno;
-        const res = await fetch(`${this.config.baseUrl}/v1/sdk/functions/deploy`, {
+        const res = await koolbaseFetch(`${this.config.baseUrl}/v1/sdk/functions/deploy`, {
             method: 'POST',
             headers: {
                 'Content-Type': 'application/json',
@@ -54,7 +55,7 @@ export class KoolbaseFunctions {
         if (userToken) {
             headers['Authorization'] = `Bearer ${userToken}`;
         }
-        const res = await fetch(`${this.config.baseUrl}/v1/sdk/functions/${name}`, {
+        const res = await koolbaseFetch(`${this.config.baseUrl}/v1/sdk/functions/${name}`, {
             method: 'POST',
             headers,
             body: JSON.stringify({ body: body ?? {} }),

package/dist/esm/index.d.ts

@@ -1,5 +1,6 @@
 export * from './types.js';
 export * from './errors.js';
+export * from './network.js';
 export * from './aggregate.js';
 export * from './conflict.js';
 export * from './pending-write.js';

package/dist/esm/index.js

@@ -5,6 +5,7 @@
 // code installs the platform package, never this one directly.
 export * from './types.js';
 export * from './errors.js';
+export * from './network.js';
 export * from './aggregate.js';
 export * from './conflict.js';
 export * from './pending-write.js';

package/dist/esm/messaging.js

@@ -1,3 +1,4 @@
+import { koolbaseFetch } from './network.js';
 // ─── KoolbaseMessaging ────────────────────────────────────────────────────────
 export class KoolbaseMessaging {
     constructor(config) {
@@ -10,7 +11,7 @@ export class KoolbaseMessaging {
     // ─── Register token ───────────────────────────────────────────────────────
     async registerToken(options) {
         try {
-            const response = await fetch(`${this.config.baseUrl}/v1/messaging/register`, {
+            const response = await koolbaseFetch(`${this.config.baseUrl}/v1/messaging/register`, {
                 method: 'POST',
                 headers: {
                     'Content-Type': 'application/json',

package/dist/esm/network.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Network failures, made actionable.
+ *
+ * A browser rejects a request it may not make cross-origin with the same bare
+ * TypeError ("Failed to fetch") as a dead network, and deliberately hides which
+ * it was. The SDK cannot tell them apart either, so it names the likely causes,
+ * starting with the one only the app's developer can fix: Trusted Origins.
+ *
+ * It stays a TypeError, so code that tells a network failure from a server
+ * rejection that way (the offline queue) behaves exactly as before.
+ */
+export declare class KoolbaseNetworkError extends TypeError {
+    code: string;
+    readonly url: string;
+    readonly origin?: string;
+    constructor(url: string, cause: unknown);
+}
+/** fetch, with network failures turned into a KoolbaseNetworkError. */
+export declare function koolbaseFetch(input: string, init?: RequestInit): Promise<Response>;

package/dist/esm/network.js

@@ -0,0 +1,47 @@
+/**
+ * Network failures, made actionable.
+ *
+ * A browser rejects a request it may not make cross-origin with the same bare
+ * TypeError ("Failed to fetch") as a dead network, and deliberately hides which
+ * it was. The SDK cannot tell them apart either, so it names the likely causes,
+ * starting with the one only the app's developer can fix: Trusted Origins.
+ *
+ * It stays a TypeError, so code that tells a network failure from a server
+ * rejection that way (the offline queue) behaves exactly as before.
+ */
+export class KoolbaseNetworkError extends TypeError {
+    constructor(url, cause) {
+        const loc = globalThis.location;
+        const origin = loc?.origin && loc.origin !== 'null' ? loc.origin : undefined;
+        const reason = cause instanceof Error ? cause.message : String(cause);
+        let host = url;
+        try {
+            host = new URL(url).origin;
+        }
+        catch {
+            // keep the raw url
+        }
+        let message = `Could not reach Koolbase at ${host} (${reason}).`;
+        message += origin
+            ? ` If you are online, check that this site's address (${origin}) is in the project's Trusted Origins in the Koolbase dashboard.`
+            : ' Check the network connection and the configured base URL.';
+        super(message);
+        this.code = 'network_error';
+        this.name = 'KoolbaseNetworkError';
+        this.url = url;
+        this.origin = origin;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/** fetch, with network failures turned into a KoolbaseNetworkError. */
+export async function koolbaseFetch(input, init) {
+    try {
+        return await fetch(input, init);
+    }
+    catch (e) {
+        // A request the caller cancelled keeps its meaning.
+        if (e?.name === 'AbortError')
+            throw e;
+        throw new KoolbaseNetworkError(input, e);
+    }
+}

package/dist/esm/storage.js

@@ -1,3 +1,4 @@
+import { koolbaseFetch } from './network.js';
 import { KoolbaseUnauthenticatedError } from './errors.js';
 import { KoolbaseStorageError, koolbaseStorageErrorFromResponse, } from './storage-errors.js';
 // --- Cloudflare image-transform URL helpers -------------------------------
@@ -94,7 +95,7 @@ export class KoolbaseStorage {
             ? options.file.type || 'application/octet-stream'
             : options.file.type;
         // ─── Step 1: Get presigned upload URL ───
-        const urlRes = await fetch(`${this.config.baseUrl}/v1/sdk/storage/upload-url`, {
+        const urlRes = await koolbaseFetch(`${this.config.baseUrl}/v1/sdk/storage/upload-url`, {
             method: 'POST',
             headers: {
                 ...(await this.buildHeaders()),
@@ -120,9 +121,9 @@ export class KoolbaseStorage {
         // the two hosts differ here and nowhere else in this method.
         const fileBlob = isBlob
             ? options.file
-            : await (await fetch(options.file.uri)).blob();
+            : await (await koolbaseFetch(options.file.uri)).blob();
         const fileSize = fileBlob.size;
-        const uploadRes = await fetch(upload_url, {
+        const uploadRes = await koolbaseFetch(upload_url, {
             method: 'PUT',
             headers: { 'Content-Type': contentType },
             body: fileBlob,
@@ -149,7 +150,7 @@ export class KoolbaseStorage {
         if (options.metadata !== undefined) {
             confirmBody.metadata = options.metadata;
         }
-        const confirmRes = await fetch(`${this.config.baseUrl}/v1/sdk/storage/confirm`, {
+        const confirmRes = await koolbaseFetch(`${this.config.baseUrl}/v1/sdk/storage/confirm`, {
             method: 'POST',
             headers: {
                 ...(await this.buildHeaders()),
@@ -200,7 +201,7 @@ export class KoolbaseStorage {
      * // -> { category: 'landscape', tag: 'sunset' }
      */
     async updateMetadata(bucket, path, metadata) {
-        const res = await fetch(`${this.config.baseUrl}/v1/sdk/storage/objects/metadata`, {
+        const res = await koolbaseFetch(`${this.config.baseUrl}/v1/sdk/storage/objects/metadata`, {
             method: 'PATCH',
             headers: {
                 ...(await this.buildHeaders()),
@@ -223,7 +224,7 @@ export class KoolbaseStorage {
         if (versionId) {
             url += `&version_id=${encodeURIComponent(versionId)}`;
         }
-        const res = await fetch(url, { headers: await this.buildHeaders() });
+        const res = await koolbaseFetch(url, { headers: await this.buildHeaders() });
         if (!res.ok) {
             throw await this.error(res, 'Failed to get download URL');
         }
@@ -318,7 +319,7 @@ export class KoolbaseStorage {
         const url = forcePurge
             ? `${this.config.baseUrl}/v1/sdk/storage/object?force_purge=true`
             : `${this.config.baseUrl}/v1/sdk/storage/object`;
-        const res = await fetch(url, {
+        const res = await koolbaseFetch(url, {
             method: 'DELETE',
             headers: {
                 ...(await this.buildHeaders()),
@@ -345,7 +346,7 @@ export class KoolbaseStorage {
     async listVersions(bucket, path) {
         const url = `${this.config.baseUrl}/v1/sdk/storage/object-versions` +
             `?bucket=${encodeURIComponent(bucket)}&path=${encodeURIComponent(path)}`;
-        const res = await fetch(url, { headers: await this.buildHeaders() });
+        const res = await koolbaseFetch(url, { headers: await this.buildHeaders() });
         if (!res.ok) {
             throw await this.error(res, 'Failed to list versions');
         }
@@ -361,7 +362,7 @@ export class KoolbaseStorage {
     async getVersion(bucket, path, versionId) {
         const url = `${this.config.baseUrl}/v1/sdk/storage/object-versions/${encodeURIComponent(versionId)}` +
             `?bucket=${encodeURIComponent(bucket)}&path=${encodeURIComponent(path)}`;
-        const res = await fetch(url, { headers: await this.buildHeaders() });
+        const res = await koolbaseFetch(url, { headers: await this.buildHeaders() });
         if (!res.ok) {
             throw await this.error(res, 'Failed to fetch version');
         }
@@ -380,7 +381,7 @@ export class KoolbaseStorage {
     async restoreVersion(bucket, path, versionId) {
         const url = `${this.config.baseUrl}/v1/sdk/storage/object-versions/${encodeURIComponent(versionId)}/restore` +
             `?bucket=${encodeURIComponent(bucket)}&path=${encodeURIComponent(path)}`;
-        const res = await fetch(url, {
+        const res = await koolbaseFetch(url, {
             method: 'POST',
             headers: await this.buildHeaders(),
         });
@@ -398,7 +399,7 @@ export class KoolbaseStorage {
     async purgeVersion(bucket, path, versionId) {
         const url = `${this.config.baseUrl}/v1/sdk/storage/object-versions/${encodeURIComponent(versionId)}` +
             `?bucket=${encodeURIComponent(bucket)}&path=${encodeURIComponent(path)}`;
-        const res = await fetch(url, {
+        const res = await koolbaseFetch(url, {
             method: 'DELETE',
             headers: await this.buildHeaders(),
         });

package/dist/esm/sync-engine.js

@@ -1,3 +1,4 @@
+import { koolbaseFetch } from './network.js';
 import { readOfflineState, mutateOfflineState, migrateLegacyQueue, flushLockName, } from './offline-state.js';
 import { KoolbaseUnauthenticatedError } from './errors.js';
 import { getPlatform } from './platform.js';
@@ -242,7 +243,7 @@ export class SyncEngine {
             : `${this.config.baseUrl}/v1/sdk/db/records/${write.recordId}`;
         let res;
         if (write.operation === 'insert') {
-            res = await fetch(url, {
+            res = await koolbaseFetch(url, {
                 method: 'POST',
                 headers,
                 // The write's own id: generated at enqueue, identical on every retry.
@@ -256,7 +257,7 @@ export class SyncEngine {
             });
         }
         else if (write.operation === 'update') {
-            res = await fetch(url, {
+            res = await koolbaseFetch(url, {
                 method: 'PATCH',
                 headers,
                 // The revision the change was composed against. The server applies it
@@ -275,7 +276,7 @@ export class SyncEngine {
             const q = write.baseRevision !== undefined
                 ? `?expected_revision=${write.baseRevision}`
                 : '';
-            res = await fetch(`${url}${q}`, { method: 'DELETE', headers });
+            res = await koolbaseFetch(`${url}${q}`, { method: 'DELETE', headers });
         }
         if (res.status === 401)
             throw new KoolbaseUnauthenticatedError('unauthorized');

package/dist/esm/types.d.ts

@@ -239,6 +239,13 @@ export interface QueryOptions {
     orderBy?: string;
     orderDesc?: boolean;
     populate?: string[];
+    /**
+     * How to read: 'default' is cache-first, refreshed in the background;
+     * 'network-only' skips the cache and waits for the server (the result still
+     * refreshes the cache). Use 'network-only' after a write this client did not
+     * make, by a Function or another user, when you need the server's state now.
+     */
+    cache?: 'default' | 'network-only';
 }
 export interface QueryResult {
     records: KoolbaseRecord[];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@koolbase/core",
-  "version": "12.2.0",
-  "description": "Koolbase SDK core \u2014 shared behaviour behind @koolbase/react-native and @koolbase/js. Install one of those, not this.",
+  "version": "12.3.0",
+  "description": "Koolbase SDK core — 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": [