@koolbase/react-native 9.1.0 → 9.2.0

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

@@ -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

@@ -41,6 +41,13 @@ 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);
@@ -65,10 +72,14 @@ 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));
+        _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)();

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>;