@koolbase/react-native 9.0.0 → 9.2.0

package/dist/device-id.d.ts

@@ -0,0 +1 @@
+export declare function getOrCreateDeviceId(): Promise<string>;

package/dist/device-id.js

@@ -0,0 +1,60 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getOrCreateDeviceId = getOrCreateDeviceId;
+const async_storage_1 = __importDefault(require("@react-native-async-storage/async-storage"));
+// Single source of the anonymous device identifier for the whole SDK.
+// Generated once, persisted, and shared by messaging (registration keying),
+// feature flags (rollout bucketing: stableHash(deviceId + ":" + key) % 100),
+// code push (targeting), and analytics. Previously each subsystem was handed a
+// hardcoded 'rn-device' literal, so every RN device collided on one messaging
+// registration row and bucketed identically for every rollout — a 10% flag was
+// on for everyone or no one, never 10%.
+//
+// The id is anonymous, not a secret: what matters is uniform DISTRIBUTION so
+// hash(id) % 100 is even, not unpredictability. We use crypto.getRandomValues
+// when the runtime provides it (best distribution, no modulo bias) and fall
+// back to Math.random otherwise — mirroring the runtime-guarded crypto use
+// already in code-push.ts, and adding no dependency (per the SDK's stated
+// preference against a crypto-grade UUID dependency for non-security ids).
+const DEVICE_ID_KEY = 'koolbase:device_id';
+let _cached = null;
+async function getOrCreateDeviceId() {
+    if (_cached)
+        return _cached;
+    try {
+        const existing = await async_storage_1.default.getItem(DEVICE_ID_KEY);
+        if (existing) {
+            _cached = existing;
+            return existing;
+        }
+        const newId = generateUUID();
+        await async_storage_1.default.setItem(DEVICE_ID_KEY, newId);
+        _cached = newId;
+        return newId;
+    }
+    catch {
+        // Storage unavailable — return an ephemeral (unpersisted) id so the SDK
+        // stays functional rather than throwing. Not stable across launches.
+        return generateUUID();
+    }
+}
+// UUID v4. Uses crypto.getRandomValues where available for uniform,
+// modulo-bias-free bytes; Math.random fallback keeps it dependency-free.
+function generateUUID() {
+    const bytes = new Uint8Array(16);
+    const c = typeof crypto !== 'undefined' ? crypto : undefined;
+    if (c && typeof c.getRandomValues === 'function') {
+        c.getRandomValues(bytes);
+    }
+    else {
+        for (let i = 0; i < 16; i++)
+            bytes[i] = (Math.random() * 256) | 0;
+    }
+    bytes[6] = (bytes[6] & 0x0f) | 0x40; // version 4
+    bytes[8] = (bytes[8] & 0x3f) | 0x80; // variant
+    const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}

package/dist/errors.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The root of every error the SDK raises.
+ *
+ * Each subsystem has its own family beneath this — data, storage, auth — so an
+ * application can catch narrowly where it wants to and broadly where it does
+ * not:
+ *
+ * ```ts
+ * try {
+ *   await Koolbase.storage.upload(...);
+ * } catch (e) {
+ *   if (e instanceof KoolbaseUnauthenticatedError) return goToLogin();
+ *   if (e instanceof KoolbaseStorageError) return showError(e.message);
+ *   throw e;
+ * }
+ * ```
+ *
+ * The families used to be unrelated roots, which meant a failure belonging to no
+ * single subsystem — a rejected credential, discovered by whichever call
+ * happened to make it — had to be redefined in each one.
+ */
+export declare class KoolbaseError extends Error {
+    code?: string;
+    constructor(message: string, code?: string);
+}
+/**
+ * The server would not accept the caller's credentials.
+ *
+ * Raised by any surface — a query, an upload, a Function invoke — because a
+ * session stops working for the whole SDK at once, not one subsystem at a time.
+ *
+ * Named for what the server actually reports. A 401 covers an expired session, a
+ * revoked key, a malformed header, and no credentials at all, and the server
+ * does not distinguish them: calling this "session expired" would claim a
+ * precision that does not exist, and an app that signed a user out on a revoked
+ * API key would be acting on it.
+ *
+ * When the SDK holds a session it clears it before throwing, so by the time an
+ * application catches this the user is already signed out.
+ */
+export declare class KoolbaseUnauthenticatedError extends KoolbaseError {
+    constructor(message: string);
+}
+/**
+ * An offline update or delete could not be queued, because the SDK has no
+ * record of what the change was composed against.
+ *
+ * Replaying a mutation without knowing the state it was based on means applying
+ * it blindly: whatever changed on the server in the meantime is overwritten,
+ * silently, with nobody able to tell it happened.
+ *
+ * A baseline is available when the record is in the local cache — read through
+ * a query, a single fetch, or seen over the socket — or when it was created
+ * offline and its insert is still queued. It is unavailable when the record has
+ * never been seen on this device, so read it first, or make the change while
+ * online where the server arbitrates directly.
+ *
+ * Deliberate rather than lenient. Queueing these anyway would mean most offline
+ * updates are conflict-safe and some quietly are not, which is a worse guarantee
+ * than a clear refusal.
+ */
+export declare class KoolbaseOfflineBaselineUnavailableError extends KoolbaseError {
+    constructor(message: string);
+}

package/dist/errors.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KoolbaseOfflineBaselineUnavailableError = exports.KoolbaseUnauthenticatedError = exports.KoolbaseError = void 0;
+/**
+ * The root of every error the SDK raises.
+ *
+ * Each subsystem has its own family beneath this — data, storage, auth — so an
+ * application can catch narrowly where it wants to and broadly where it does
+ * not:
+ *
+ * ```ts
+ * try {
+ *   await Koolbase.storage.upload(...);
+ * } catch (e) {
+ *   if (e instanceof KoolbaseUnauthenticatedError) return goToLogin();
+ *   if (e instanceof KoolbaseStorageError) return showError(e.message);
+ *   throw e;
+ * }
+ * ```
+ *
+ * The families used to be unrelated roots, which meant a failure belonging to no
+ * single subsystem — a rejected credential, discovered by whichever call
+ * happened to make it — had to be redefined in each one.
+ */
+class KoolbaseError extends Error {
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = 'KoolbaseError';
+        // Required for `instanceof` to work across the prototype chain when
+        // targeting ES5-era output, which TypeScript's class extension otherwise
+        // breaks. Every subclass repeats it for the same reason.
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.KoolbaseError = KoolbaseError;
+/**
+ * The server would not accept the caller's credentials.
+ *
+ * Raised by any surface — a query, an upload, a Function invoke — because a
+ * session stops working for the whole SDK at once, not one subsystem at a time.
+ *
+ * Named for what the server actually reports. A 401 covers an expired session, a
+ * revoked key, a malformed header, and no credentials at all, and the server
+ * does not distinguish them: calling this "session expired" would claim a
+ * precision that does not exist, and an app that signed a user out on a revoked
+ * API key would be acting on it.
+ *
+ * When the SDK holds a session it clears it before throwing, so by the time an
+ * application catches this the user is already signed out.
+ */
+class KoolbaseUnauthenticatedError extends KoolbaseError {
+    constructor(message) {
+        super(message, 'unauthenticated');
+        this.name = 'KoolbaseUnauthenticatedError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.KoolbaseUnauthenticatedError = KoolbaseUnauthenticatedError;
+/**
+ * An offline update or delete could not be queued, because the SDK has no
+ * record of what the change was composed against.
+ *
+ * Replaying a mutation without knowing the state it was based on means applying
+ * it blindly: whatever changed on the server in the meantime is overwritten,
+ * silently, with nobody able to tell it happened.
+ *
+ * A baseline is available when the record is in the local cache — read through
+ * a query, a single fetch, or seen over the socket — or when it was created
+ * offline and its insert is still queued. It is unavailable when the record has
+ * never been seen on this device, so read it first, or make the change while
+ * online where the server arbitrates directly.
+ *
+ * Deliberate rather than lenient. Queueing these anyway would mean most offline
+ * updates are conflict-safe and some quietly are not, which is a worse guarantee
+ * than a clear refusal.
+ */
+class KoolbaseOfflineBaselineUnavailableError extends KoolbaseError {
+    constructor(message) {
+        super(message, 'offline_baseline_unavailable');
+        this.name = 'KoolbaseOfflineBaselineUnavailableError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.KoolbaseOfflineBaselineUnavailableError = KoolbaseOfflineBaselineUnavailableError;

package/dist/function-errors.d.ts

@@ -0,0 +1,51 @@
+import { KoolbaseError } from './errors';
+/**
+ * A Function call did not succeed.
+ *
+ * Every failure used to be a bare `Error`, so an application could only match on
+ * message text — and a missing Function, a caller without permission, a Function
+ * that threw, and an exhausted plan limit all looked alike, though they call for
+ * entirely different responses.
+ */
+export declare class FunctionInvokeError extends KoolbaseError {
+    statusCode?: number;
+    constructor(message: string, statusCode?: number, code?: string);
+}
+/** No Function by that name is deployed to this project. */
+export declare class FunctionNotFoundError extends FunctionInvokeError {
+    constructor(message: string);
+}
+/**
+ * The caller may not invoke this Function.
+ *
+ * Distinct from an authentication failure: the credentials were accepted and
+ * this caller is not permitted. Retrying will not help, and signing the user out
+ * would be wrong.
+ */
+export declare class FunctionPermissionError extends FunctionInvokeError {
+    constructor(message: string);
+}
+/** The Function rejected its arguments. */
+export declare class FunctionValidationError extends FunctionInvokeError {
+    constructor(message: string);
+}
+/**
+ * The project's Function invocations are used up.
+ *
+ * Nothing about the call is wrong — retrying will not help until the plan
+ * allows it. The one failure here fixed by changing a plan rather than code.
+ */
+export declare class FunctionQuotaExceededError extends FunctionInvokeError {
+    constructor(message: string);
+}
+/**
+ * The Function ran and threw.
+ *
+ * The message is the Function's own, not the platform's — it comes from the code
+ * that was deployed.
+ */
+export declare class FunctionExecutionError extends FunctionInvokeError {
+    constructor(message: string, statusCode?: number);
+}
+/** Builds the right error for a failed invocation. */
+export declare function functionInvokeError(status: number, message: string): KoolbaseError;

package/dist/function-errors.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FunctionExecutionError = exports.FunctionQuotaExceededError = exports.FunctionValidationError = exports.FunctionPermissionError = exports.FunctionNotFoundError = exports.FunctionInvokeError = void 0;
+exports.functionInvokeError = functionInvokeError;
+const errors_1 = require("./errors");
+/**
+ * A Function call did not succeed.
+ *
+ * Every failure used to be a bare `Error`, so an application could only match on
+ * message text — and a missing Function, a caller without permission, a Function
+ * that threw, and an exhausted plan limit all looked alike, though they call for
+ * entirely different responses.
+ */
+class FunctionInvokeError extends errors_1.KoolbaseError {
+    constructor(message, statusCode, code) {
+        super(message, code);
+        this.statusCode = statusCode;
+        this.name = 'FunctionInvokeError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.FunctionInvokeError = FunctionInvokeError;
+/** No Function by that name is deployed to this project. */
+class FunctionNotFoundError extends FunctionInvokeError {
+    constructor(message) {
+        super(message, 404, 'not_found');
+        this.name = 'FunctionNotFoundError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.FunctionNotFoundError = FunctionNotFoundError;
+/**
+ * The caller may not invoke this Function.
+ *
+ * Distinct from an authentication failure: the credentials were accepted and
+ * this caller is not permitted. Retrying will not help, and signing the user out
+ * would be wrong.
+ */
+class FunctionPermissionError extends FunctionInvokeError {
+    constructor(message) {
+        super(message, 403, 'permission_denied');
+        this.name = 'FunctionPermissionError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.FunctionPermissionError = FunctionPermissionError;
+/** The Function rejected its arguments. */
+class FunctionValidationError extends FunctionInvokeError {
+    constructor(message) {
+        super(message, 400, 'validation_error');
+        this.name = 'FunctionValidationError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.FunctionValidationError = FunctionValidationError;
+/**
+ * The project's Function invocations are used up.
+ *
+ * Nothing about the call is wrong — retrying will not help until the plan
+ * allows it. The one failure here fixed by changing a plan rather than code.
+ */
+class FunctionQuotaExceededError extends FunctionInvokeError {
+    constructor(message) {
+        super(message, 402, 'limit_reached');
+        this.name = 'FunctionQuotaExceededError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.FunctionQuotaExceededError = FunctionQuotaExceededError;
+/**
+ * The Function ran and threw.
+ *
+ * The message is the Function's own, not the platform's — it comes from the code
+ * that was deployed.
+ */
+class FunctionExecutionError extends FunctionInvokeError {
+    constructor(message, statusCode) {
+        super(message, statusCode, 'execution_failed');
+        this.name = 'FunctionExecutionError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.FunctionExecutionError = FunctionExecutionError;
+/** Builds the right error for a failed invocation. */
+function functionInvokeError(status, message) {
+    switch (status) {
+        case 401:
+            // Not a Function failure. A rejected credential stops the whole SDK
+            // working, so it raises the shared type.
+            return new errors_1.KoolbaseUnauthenticatedError(message);
+        case 403:
+            return new FunctionPermissionError(message);
+        case 404:
+            return new FunctionNotFoundError(message);
+        case 400:
+            return new FunctionValidationError(message);
+        case 402:
+            return new FunctionQuotaExceededError(message);
+    }
+    if (status >= 500)
+        return new FunctionExecutionError(message, status);
+    return new FunctionInvokeError(message, status);
+}

package/dist/functions.d.ts

@@ -2,7 +2,14 @@ import { KoolbaseConfig, FunctionInvokeResult, DeployOptions, DeployResult } fro
 export declare class KoolbaseFunctions {
     private config;
     private getUserAccessToken?;
-    constructor(config: KoolbaseConfig, getUserAccessToken?: () => Promise<string | null>);
+    /**
+     * Called when the server rejects the caller's credentials.
+     *
+     * A session stops working for the whole SDK at once, so an app whose failing
+     * call happens to be a Function invoke must not keep believing it is signed in.
+     */
+    private onSessionExpired?;
+    constructor(config: KoolbaseConfig, getUserAccessToken?: () => Promise<string | null>, onSessionExpired?: () => Promise<void>);
     deploy(options: DeployOptions): Promise<DeployResult>;
     invoke(name: string, body?: Record<string, unknown>): Promise<FunctionInvokeResult>;
 }

package/dist/functions.js

@@ -1,10 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KoolbaseFunctions = void 0;
+const function_errors_1 = require("./function-errors");
+const errors_1 = require("./errors");
 const types_1 = require("./types");
 class KoolbaseFunctions {
-    constructor(config, getUserAccessToken) {
+    constructor(config, getUserAccessToken, onSessionExpired) {
         this.config = config;
+        this.onSessionExpired = onSessionExpired;
         this.getUserAccessToken = getUserAccessToken;
     }
     // ─── Deploy ────────────────────────────────────────────────────────────────
@@ -25,8 +28,13 @@ class KoolbaseFunctions {
         });
         const data = await res.json().catch(() => null);
         if (!res.ok) {
-            throw new Error(data?.error ??
-                'Function deploy failed');
+            const message = data?.error ??
+                'Function deploy failed';
+            const err = (0, function_errors_1.functionInvokeError)(res.status, message);
+            if (err instanceof errors_1.KoolbaseUnauthenticatedError) {
+                await this.onSessionExpired?.();
+            }
+            throw err;
         }
         const d = data;
         return {
@@ -57,8 +65,13 @@ class KoolbaseFunctions {
         const data = await res.json().catch(() => null);
         const success = res.status >= 200 && res.status < 300;
         if (!success) {
-            throw new Error(data?.error ??
-                'Function invocation failed');
+            const message = data?.error ??
+                'Function invocation failed';
+            const err = (0, function_errors_1.functionInvokeError)(res.status, message);
+            if (err instanceof errors_1.KoolbaseUnauthenticatedError) {
+                await this.onSessionExpired?.();
+            }
+            throw err;
         }
         return {
             statusCode: res.status,

package/dist/index.d.ts

@@ -4,7 +4,7 @@ import { KoolbaseAnalytics } from './analytics';
 import { KoolbaseMessaging } from './messaging';
 export { KoolbaseMessaging } from './messaging';
 export { KoolbaseAppleAuth } from './apple-auth';
-export type { RegisterTokenOptions, SendOptions } from './messaging';
+export type { RegisterTokenOptions } from './messaging';
 import { FlowResult } from './logic-engine';
 export { KoolbaseAnalytics } from './analytics';
 export type { FlowResult } from './logic-engine';
@@ -17,6 +17,10 @@ import { KoolbaseRealtime } from './realtime';
 import { KoolbaseStorage } from './storage';
 import { KoolbaseConfig, VersionCheckResult } from './types';
 export * from './types';
+export * from './errors';
+export * from './conflict';
+export * from './pending-write';
+export * from './function-errors';
 export * from './auth-errors';
 export * from './database-errors';
 export * from './storage-errors';

package/dist/index.js

@@ -13,12 +13,8 @@ var __createBinding = (this && this.__createBinding) || (Object.create ? (functi
 var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 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 = exports.SecureAuthStorage = exports.RestoreResult = exports.koolbaseSdkVersion = exports.Koolbase = exports.KoolbaseStorage = exports.KoolbaseRealtime = exports.KoolbaseFunctions = exports.KoolbaseFlags = exports.KoolbaseDatabase = exports.KoolbaseAuth = exports.KoolbaseCodePush = exports.KoolbaseAnalytics = exports.KoolbaseAppleAuth = exports.KoolbaseMessaging = void 0;
-const async_storage_1 = __importDefault(require("@react-native-async-storage/async-storage"));
 const auth_1 = require("./auth");
 Object.defineProperty(exports, "KoolbaseAuth", { enumerable: true, get: function () { return auth_1.KoolbaseAuth; } });
 const code_push_1 = require("./code-push");
@@ -43,7 +39,15 @@ const realtime_1 = require("./realtime");
 Object.defineProperty(exports, "KoolbaseRealtime", { enumerable: true, get: function () { return realtime_1.KoolbaseRealtime; } });
 const storage_1 = require("./storage");
 Object.defineProperty(exports, "KoolbaseStorage", { enumerable: true, get: function () { return storage_1.KoolbaseStorage; } });
+const device_id_1 = require("./device-id");
 __exportStar(require("./types"), exports);
+// The root, and the authentication failure any surface can raise. Listed
+// first: an application catching broadly needs these more than it needs any
+// single subsystem's types.
+__exportStar(require("./errors"), exports);
+__exportStar(require("./conflict"), exports);
+__exportStar(require("./pending-write"), exports);
+__exportStar(require("./function-errors"), exports);
 __exportStar(require("./auth-errors"), exports);
 __exportStar(require("./database-errors"), exports);
 __exportStar(require("./storage-errors"), exports);
@@ -68,17 +72,24 @@ exports.Koolbase = {
         if (_initialized)
             return;
         _auth = new auth_1.KoolbaseAuth(config);
-        _db = new database_1.KoolbaseDatabase(config, () => _auth?.currentUser?.id ?? null, () => _auth?.validAccessToken() ?? Promise.resolve(null));
-        _storage = new storage_1.KoolbaseStorage(config, () => _auth?.validAccessToken() ?? Promise.resolve(null));
-        _realtime = new realtime_1.KoolbaseRealtime(config, () => _auth?.validAccessToken() ?? Promise.resolve(null));
-        _functions = new functions_1.KoolbaseFunctions(config, () => _auth?.validAccessToken() ?? Promise.resolve(null));
-        _flags = new flags_1.KoolbaseFlags(config, 'rn-device');
+        _db = new database_1.KoolbaseDatabase(config, () => _auth?.currentUser?.id ?? null, () => _auth?.validAccessToken() ?? Promise.resolve(null), 
+        // A session the server refuses is not a session. Clearing it here means an
+        // app catching KoolbaseUnauthenticatedError is already signed out and can
+        // route to login, rather than looping on a dead token.
+        async () => { await _auth?.clearStoredSession(); });
+        _storage = new storage_1.KoolbaseStorage(config, () => _auth?.validAccessToken() ?? Promise.resolve(null), async () => { await _auth?.clearStoredSession(); });
+        _realtime = new realtime_1.KoolbaseRealtime(config, () => _auth?.validAccessToken() ?? Promise.resolve(null), () => _auth?.currentUser?.id ?? null);
+        _functions = new functions_1.KoolbaseFunctions(config, () => _auth?.validAccessToken() ?? Promise.resolve(null), async () => { await _auth?.clearStoredSession(); });
+        // One anonymous device id for the whole SDK — bucketing (flags), targeting
+        // (code push), and registration keying (messaging) must all agree on it.
+        const deviceId = await (0, device_id_1.getOrCreateDeviceId)();
+        _flags = new flags_1.KoolbaseFlags(config, deviceId);
         _codePush = new code_push_1.KoolbaseCodePush(config, config.codePushChannel ?? 'stable');
         // Initialize code push — loads cached bundle then checks in background
         await _codePush.init({
             appVersion: '1.0.0', // override with your app version
             platform: 'react-native',
-            deviceId: 'rn-device',
+            deviceId,
         });
         // Initialize analytics
         if (config.analyticsEnabled !== false) {
@@ -88,8 +99,7 @@ exports.Koolbase = {
         // Initialize messaging
         if (config.messagingEnabled !== false) {
             _messaging = new messaging_1.KoolbaseMessaging(config);
-            const storedDeviceId = await async_storage_1.default.getItem('koolbase:device_id');
-            _messaging.setDeviceId(storedDeviceId ?? 'rn-device');
+            _messaging.setDeviceId(deviceId);
         }
         _initialized = true;
     },

package/dist/messaging.d.ts

@@ -4,17 +4,10 @@ export interface RegisterTokenOptions {
     platform: 'android' | 'ios';
     userId?: string;
 }
-export interface SendOptions {
-    to: string;
-    title: string;
-    body: string;
-    data?: Record<string, unknown>;
-}
 export declare class KoolbaseMessaging {
     private config;
     private deviceId;
     constructor(config: KoolbaseConfig);
     setDeviceId(deviceId: string): void;
     registerToken(options: RegisterTokenOptions): Promise<boolean>;
-    send(options: SendOptions): Promise<boolean>;
 }

package/dist/messaging.js

@@ -32,27 +32,5 @@ class KoolbaseMessaging {
             return false;
         }
     }
-    // ─── Send notification ────────────────────────────────────────────────────
-    async send(options) {
-        try {
-            const response = await fetch(`${this.config.baseUrl}/v1/messaging/send`, {
-                method: 'POST',
-                headers: {
-                    'Content-Type': 'application/json',
-                    'x-api-key': this.config.publicKey,
-                },
-                body: JSON.stringify({
-                    token: options.to,
-                    title: options.title,
-                    body: options.body,
-                    data: options.data ?? {},
-                }),
-            });
-            return response.ok;
-        }
-        catch {
-            return false;
-        }
-    }
 }
 exports.KoolbaseMessaging = KoolbaseMessaging;

package/dist/offline-state.d.ts

@@ -0,0 +1,97 @@
+export declare function recordKey(userId: string, collection: string, recordId: string): string;
+/** A write waiting to be sent. */
+export interface QueuedWrite {
+    id: string;
+    operation: 'insert' | 'update' | 'delete';
+    collection: string;
+    recordId?: string;
+    data?: Record<string, unknown>;
+    /**
+     * The record as the client last saw it, for update and delete.
+     *
+     * Copied in at enqueue time rather than looked up at replay: the record cache
+     * can be evicted or invalidated in between, and a write whose baseline
+     * depends on something else surviving is not durable. From here on the write
+     * is self-contained.
+     */
+    baseline?: Record<string, unknown>;
+    /** The revision that baseline carried, sent so the server can refuse atomically. */
+    baseRevision?: number;
+    retries: number;
+    enqueuedAt: string;
+}
+/**
+ * Why a write is waiting for a decision.
+ *
+ * Kept distinct because they are different situations and an app showing them
+ * to someone should say different things. One means two people changed the same
+ * thing; the other means we never knew what the change was based on, so there is
+ * nothing to compare it against.
+ */
+export type ConflictReason = 
+/** The record moved between the change being made and the queue reaching it. */
+'concurrent_modification'
+/**
+ * Queued by a version of this SDK that did not record what the change was
+ * composed against. It cannot be replayed safely — there is nothing to check
+ * it against — so it waits rather than overwriting whatever is there now.
+ */
+ | 'baseline_unavailable'
+/**
+ * The server refused the write for a reason retrying cannot change — the data
+ * no longer satisfies the collection's rules, the record is gone, the caller
+ * is not permitted, a unique value is taken.
+ *
+ * Held rather than retried or dropped. Retrying sends identical bytes to
+ * identical rules; dropping loses a change the user believes is saved. Neither
+ * tells them anything.
+ */
+ | 'rejected';
+/** A write the server would not apply, held until someone decides. */
+export interface QueuedConflict {
+    reason: ConflictReason;
+    id: string;
+    operation: 'insert' | 'update' | 'delete';
+    collection: string;
+    recordId: string;
+    local?: Record<string, unknown>;
+    baseline?: Record<string, unknown>;
+    server?: Record<string, unknown>;
+    baseRevision?: number;
+    serverRevision?: number;
+    /** What the server said, when it refused for a terminal reason. */
+    message?: string;
+    createdAt: string;
+}
+export interface OfflineState {
+    pending: QueuedWrite[];
+    conflicts: QueuedConflict[];
+}
+export declare class OfflineStateTooLargeError extends Error {
+    constructor(bytes: number);
+}
+export declare function readOfflineState(userId: string): Promise<OfflineState>;
+/**
+ * Reads, mutates, and writes the state under the user's lock.
+ *
+ * Every mutation goes through here. A caller that reads and writes separately
+ * reintroduces the race this exists to prevent.
+ */
+export declare function mutateOfflineState(userId: string, mutate: (state: OfflineState) => void): Promise<void>;
+/** Adds a write to the queue, under the user's lock. */
+export declare function queueWrite(userId: string, write: Omit<QueuedWrite, 'retries' | 'enqueuedAt'>): Promise<void>;
+/**
+ * Moves writes queued by an earlier version into the current state.
+ *
+ * Runs once, before any replay, and never contacts the network. Migration that
+ * depended on connectivity would give the same input two different outcomes
+ * depending on whether the device happened to be online at startup — which is
+ * how a bug becomes unreproducible.
+ *
+ * Inserts carry everything they need and simply move across. Updates and
+ * deletes do not: they were queued before baselines were recorded, so replaying
+ * one would apply it blindly and overwrite whatever changed in the meantime.
+ * They are preserved as waiting for a decision instead — the change is not lost,
+ * and nothing is written on a guess.
+ */
+export declare function migrateLegacyQueue(userId: string): Promise<void>;