@koolbase/core 12.13.1 → 12.15.0

package/dist/cjs/auth.d.ts

@@ -1,5 +1,5 @@
 import { AuthStateListener, KoolbaseConfig, KoolbaseSession, KoolbaseUser, LinkPhoneParams, LoginParams, OtpSendResult, PhoneVerifyResult, RegisterParams, RestoreResult, KoolbaseAuditPage, KoolbaseSessionInfo, ResendVerificationResult, SendOtpParams, SignUpResult, SignInWithAppleParams, VerifyOtpParams } from './types.js';
-import type { SignInWithGoogleParams } from './types.js';
+import type { SignInWithGoogleParams, SignOutReason } from './types.js';
 export declare class KoolbaseAuth {
     private config;
     private storage;
@@ -9,6 +9,10 @@ export declare class KoolbaseAuth {
     private timeoutMs;
     private ongoingRefresh;
     private listeners;
+    /** Why the last session ended (#104); null while signed in or never signed in. */
+    private signOutReason;
+    /** The last renewal failed for want of a connection, not because the server refused it (#96). */
+    private renewalUnavailable;
     constructor(config: KoolbaseConfig);
     /**
      * Subscribe to authentication state changes. The listener fires:
@@ -82,6 +86,29 @@ export declare class KoolbaseAuth {
      * need to.
      */
     clearStoredSession(): Promise<void>;
+    /**
+     * Why the last session ended (#104): `'signed_out'` when the person signed
+     * out (or deleted their account), `'session_ended'` when it ended on its own
+     * -- revoked, past renewal, signed out on another device. null while signed
+     * in. Read it in an onAuthStateChange listener to say "You were signed out"
+     * only when they did not ask to be.
+     */
+    get lastSignOutReason(): SignOutReason | null;
+    /**
+     * A data request carrying `refused` came back unauthenticated. Renews the
+     * session and returns the token to send again with, or null when there is
+     * none -- nobody is signed in, or the server refused the renewal too, which
+     * ends the session (#96).
+     */
+    renewRejected(refused: string): Promise<string | null>;
+    /**
+     * A data request was refused as unauthenticated and renewing could not
+     * help: the session is over, so it ends here and every listener hears it.
+     * Unless the renewal failed only for want of a connection -- then the
+     * session may well be good, and signing someone out for a dropped network
+     * would be wrong (#96).
+     */
+    sessionRejected(): Promise<void>;
     private clearSessionInternal;
     restoreSession(): Promise<RestoreResult>;
     /**
@@ -164,6 +191,9 @@ export declare class KoolbaseAuth {
     private parseAppleSessionResponse;
     refresh(refreshToken?: string): Promise<KoolbaseSession>;
     private _doRefresh;
+    private readStored;
+    /** A newer session another tab stored after renewing `spent`, made current; null if none. */
+    private adoptNewer;
     logout(): Promise<boolean>;
     forgotPassword(email: string): Promise<void>;
     /**

package/dist/cjs/auth.js

@@ -11,6 +11,10 @@ class KoolbaseAuth {
         this.session = null;
         this.ongoingRefresh = null;
         this.listeners = new Set();
+        /** Why the last session ended (#104); null while signed in or never signed in. */
+        this.signOutReason = null;
+        /** The last renewal failed for want of a connection, not because the server refused it (#96). */
+        this.renewalUnavailable = false;
         this.config = config;
         this.metadata = new device_metadata_js_1.DeviceMetadata(config.appVersion);
         this.fetchFn = config.fetch ?? ((url, init) => (0, network_js_1.koolbaseFetch)(url, init));
@@ -152,6 +156,7 @@ class KoolbaseAuth {
     }
     async setSessionInternal(session) {
         this.session = session;
+        this.signOutReason = null;
         if (this.storage) {
             try {
                 await this.storage.saveSession(session);
@@ -178,9 +183,52 @@ class KoolbaseAuth {
      * need to.
      */
     async clearStoredSession() {
-        await this.clearSessionInternal();
+        await this.clearSessionInternal('session_ended');
     }
-    async clearSessionInternal() {
+    /**
+     * Why the last session ended (#104): `'signed_out'` when the person signed
+     * out (or deleted their account), `'session_ended'` when it ended on its own
+     * -- revoked, past renewal, signed out on another device. null while signed
+     * in. Read it in an onAuthStateChange listener to say "You were signed out"
+     * only when they did not ask to be.
+     */
+    get lastSignOutReason() {
+        return this.signOutReason;
+    }
+    /**
+     * A data request carrying `refused` came back unauthenticated. Renews the
+     * session and returns the token to send again with, or null when there is
+     * none -- nobody is signed in, or the server refused the renewal too, which
+     * ends the session (#96).
+     */
+    async renewRejected(refused) {
+        if (!this.session)
+            return null;
+        // Another request renewed it while this one was out.
+        if (this.session.accessToken !== refused)
+            return this.session.accessToken;
+        try {
+            return (await this.refresh()).accessToken;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * A data request was refused as unauthenticated and renewing could not
+     * help: the session is over, so it ends here and every listener hears it.
+     * Unless the renewal failed only for want of a connection -- then the
+     * session may well be good, and signing someone out for a dropped network
+     * would be wrong (#96).
+     */
+    async sessionRejected() {
+        if (!this.session || this.renewalUnavailable)
+            return;
+        await this.clearSessionInternal('session_ended');
+    }
+    async clearSessionInternal(reason = 'session_ended') {
+        if (this.session)
+            this.signOutReason = reason;
         this.session = null;
         if (this.storage) {
             try {
@@ -208,7 +256,28 @@ class KoolbaseAuth {
             : 0;
         const oneMinuteMs = 60 * 1000;
         if (expiresAt > Date.now() + oneMinuteMs) {
-            return types_js_1.RestoreResult.Restored;
+            // Valid by the clock is not valid: the session may have been signed out
+            // on another device, revoked, or the account disabled since. Ask the
+            // server before saying it is restored (#104). No answer -- offline, a
+            // timeout, a server error -- keeps the optimistic session: Offline.
+            try {
+                const res = await this.authRequest('/v1/sdk/auth/me', { method: 'GET', includeAuth: true });
+                if (res.ok) {
+                    try {
+                        await this.updateUserAndPersist(this.mapUser(await res.json()));
+                    }
+                    catch {
+                        // The session is good; a user that will not parse keeps the stored one.
+                    }
+                    return types_js_1.RestoreResult.Restored;
+                }
+                if (res.status !== 401)
+                    return types_js_1.RestoreResult.Offline;
+                // Refused: the access token is done. The refresh token decides.
+            }
+            catch {
+                return types_js_1.RestoreResult.Offline;
+            }
         }
         try {
             await this.refresh(persisted.refreshToken);
@@ -224,8 +293,8 @@ class KoolbaseAuth {
             // key or the request rather than the user's session — and deleting the
             // refresh token on that reading signs someone out with no way back.
             // Nothing reaches here with it today; it stays out so nothing does.
-            if (e instanceof auth_errors_js_1.SessionExpiredError) {
-                await this.clearSessionInternal();
+            if (isRejection(e)) {
+                await this.clearSessionInternal('session_ended');
                 return types_js_1.RestoreResult.Expired;
             }
             return types_js_1.RestoreResult.Offline;
@@ -498,17 +567,77 @@ class KoolbaseAuth {
         return promise;
     }
     async _doRefresh(refreshToken) {
-        const token = refreshToken ?? this.session?.refreshToken;
+        // The newest refresh token is the stored one: another tab of the same app
+        // may have renewed the session, and its in-memory copy here is spent.
+        const stored = refreshToken ? null : await this.readStored();
+        const token = refreshToken ?? stored?.refreshToken ?? this.session?.refreshToken;
         if (!token) {
             throw new auth_errors_js_1.SessionExpiredError();
         }
-        const res = await this.authRequest('/v1/sdk/auth/refresh', {
-            method: 'POST',
-            body: { refresh_token: token },
-        });
-        const session = await this.parseSessionResponse(res, true);
-        await this.setSessionInternal(session);
-        return session;
+        try {
+            const res = await this.authRequest('/v1/sdk/auth/refresh', {
+                method: 'POST',
+                body: { refresh_token: token },
+            });
+            const session = await this.parseSessionResponse(res, true);
+            this.renewalUnavailable = false;
+            await this.setSessionInternal(session);
+            return session;
+        }
+        catch (e) {
+            if (!isRejection(e)) {
+                // No answer, or a server error: the session may be fine. Keep it.
+                this.renewalUnavailable = true;
+                throw e;
+            }
+            this.renewalUnavailable = false;
+            // Two tabs renewing at the same moment send the same token; the
+            // server renews one and refuses the other. The winner's session is in
+            // storage: take it rather than signing out (#96).
+            const adopted = await this.adoptNewer(token);
+            if (adopted)
+                return adopted;
+            await this.clearSessionInternal('session_ended');
+            throw e;
+        }
+    }
+    async readStored() {
+        if (!this.storage)
+            return null;
+        try {
+            return await this.storage.readSession();
+        }
+        catch {
+            return null;
+        }
+    }
+    /** A newer session another tab stored after renewing `spent`, made current; null if none. */
+    async adoptNewer(spent) {
+        for (const wait of [0, 400]) {
+            if (wait)
+                await new Promise((r) => setTimeout(r, wait));
+            const stored = await this.readStored();
+            if (!stored || stored.refreshToken === spent)
+                continue;
+            const expiresAt = stored.expiresAt ? new Date(stored.expiresAt).getTime() : 0;
+            if (expiresAt > Date.now() + 60 * 1000) {
+                await this.setSessionInternal(stored);
+                return stored;
+            }
+            try {
+                const res = await this.authRequest('/v1/sdk/auth/refresh', {
+                    method: 'POST',
+                    body: { refresh_token: stored.refreshToken },
+                });
+                const session = await this.parseSessionResponse(res, true);
+                await this.setSessionInternal(session);
+                return session;
+            }
+            catch {
+                return null;
+            }
+        }
+        return null;
     }
     async logout() {
         let serverSucceeded = true;
@@ -529,7 +658,7 @@ class KoolbaseAuth {
             serverSucceeded = false;
         }
         finally {
-            await this.clearSessionInternal();
+            await this.clearSessionInternal('signed_out');
         }
         return serverSucceeded;
     }
@@ -692,7 +821,7 @@ class KoolbaseAuth {
             includeAuth: true,
         });
         await this.checkResponse(res);
-        await this.clearSessionInternal();
+        await this.clearSessionInternal('signed_out');
     }
     /**
      * Every session the signed-in user has — a "where you're signed in" list.
@@ -815,8 +944,14 @@ class KoolbaseAuth {
         try {
             return await this._ensureValidToken();
         }
-        catch {
-            return null;
+        catch (e) {
+            // Refused: the session has ended (and been cleared); go api-key-only.
+            if (isRejection(e))
+                return null;
+            // No answer: the session may be fine, so the request must not go out
+            // as a signed-out visitor (whose refusal would end it). It fails as
+            // the network failure it is, and the caller retries (#96).
+            throw e;
         }
     }
     async setSession(session) {
@@ -1064,9 +1199,9 @@ class KoolbaseAuth {
             return session.accessToken;
         }
         catch (e) {
-            if (e instanceof auth_errors_js_1.KoolbaseAuthError)
-                throw e;
-            throw new auth_errors_js_1.SessionExpiredError();
+            // A refusal stays a refusal; a network failure stays one too, rather
+            // than being reported as an ended session (#96).
+            throw e;
         }
     }
     mapUser(raw) {
@@ -1314,3 +1449,15 @@ class KoolbaseAuth {
     }
 }
 exports.KoolbaseAuth = KoolbaseAuth;
+/**
+ * Whether an error is the server refusing the session -- it ended -- rather
+ * than no answer at all (#96). Only a refusal signs anyone out.
+ */
+function isRejection(e) {
+    if (e instanceof auth_errors_js_1.SessionExpiredError || e instanceof auth_errors_js_1.TokenRevokedError || e instanceof auth_errors_js_1.UserDisabledError)
+        return true;
+    if (e instanceof auth_errors_js_1.KoolbaseAuthError) {
+        return ['invalid_refresh_token', 'token_revoked', 'account_disabled', 'mfa_session_insufficient', 'unauthenticated'].includes(e.code ?? '');
+    }
+    return false;
+}

package/dist/cjs/cache-store.d.ts

@@ -67,3 +67,8 @@ export declare function optimisticallyInsert(userId: string, collection: string,
  * to get rid of one record.
  */
 export declare function removeFromCachedQueries(userId: string, collection: string, recordId: string): Promise<void>;
+/**
+ * Applies an offline edit to the record wherever a cached result holds it, so
+ * a saved list shows what the user just changed rather than what it was.
+ */
+export declare function updateInCachedQueries(userId: string, collection: string, recordId: string, data: Record<string, unknown>): Promise<void>;

package/dist/cjs/cache-store.js

@@ -14,6 +14,7 @@ exports.removeFromWriteQueue = removeFromWriteQueue;
 exports.incrementWriteRetry = incrementWriteRetry;
 exports.optimisticallyInsert = optimisticallyInsert;
 exports.removeFromCachedQueries = removeFromCachedQueries;
+exports.updateInCachedQueries = updateInCachedQueries;
 const platform_js_1 = require("./platform.js");
 const CACHE_VERSION = 'v1';
 function cacheKey(userId, collection, queryHash) {
@@ -244,3 +245,33 @@ async function removeFromCachedQueries(userId, collection, recordId) {
         // ignore
     }
 }
+/**
+ * Applies an offline edit to the record wherever a cached result holds it, so
+ * a saved list shows what the user just changed rather than what it was.
+ */
+async function updateInCachedQueries(userId, collection, recordId, data) {
+    try {
+        const keys = await (0, platform_js_1.getPlatform)().storage.getAllKeys();
+        const prefix = `koolbase:${CACHE_VERSION}:${userId}:${collection}:`;
+        for (const key of keys.filter(k => k.startsWith(prefix))) {
+            const raw = await (0, platform_js_1.getPlatform)().storage.getItem(key);
+            if (!raw)
+                continue;
+            const cached = JSON.parse(raw);
+            if (!Array.isArray(cached.records))
+                continue;
+            let changed = false;
+            cached.records = cached.records.map(r => {
+                if (r.id !== recordId)
+                    return r;
+                changed = true;
+                return { ...r, data: { ...(r.data ?? {}), ...data } };
+            });
+            if (changed)
+                await (0, platform_js_1.getPlatform)().storage.setItem(key, JSON.stringify(cached));
+        }
+    }
+    catch {
+        // ignore
+    }
+}

package/dist/cjs/connectivity.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Whether the device reports a network connection. A hint, not a promise that
+ * Koolbase is reachable: requests can still fail while online.
+ *
+ * 'unknown' until the platform first answers -- a real state, not a guess. An
+ * app should neither show "offline" nor run online-only logic on it.
+ */
+export type ConnectivityState = 'unknown' | 'online' | 'offline';
+/**
+ * The device's connectivity, as state an app can render: getState() for now,
+ * subscribe() for changes (the shape React's useSyncExternalStore takes).
+ */
+export declare class KoolbaseConnectivity {
+    private state;
+    private readonly listeners;
+    private stop;
+    private heard;
+    /** Starts following the platform. Called once by Koolbase.initialize. */
+    start(): void;
+    getState(): ConnectivityState;
+    /** Called on every change. Returns the unsubscribe. */
+    subscribe(listener: () => void): () => void;
+    dispose(): void;
+    private set;
+}

package/dist/cjs/connectivity.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KoolbaseConnectivity = void 0;
+const platform_js_1 = require("./platform.js");
+/**
+ * The device's connectivity, as state an app can render: getState() for now,
+ * subscribe() for changes (the shape React's useSyncExternalStore takes).
+ */
+class KoolbaseConnectivity {
+    constructor() {
+        this.state = 'unknown';
+        this.listeners = new Set();
+        this.stop = null;
+        // A change event is fresher than the first read: once one arrives, a late
+        // answer to that read is ignored.
+        this.heard = false;
+    }
+    /** Starts following the platform. Called once by Koolbase.initialize. */
+    start() {
+        if (this.stop)
+            return;
+        const network = (0, platform_js_1.getPlatform)().network;
+        this.stop = network.onChange((online) => {
+            this.heard = true;
+            this.set(online ? 'online' : 'offline');
+        });
+        if (network.current) {
+            network.current().then((online) => {
+                if (!this.heard && online !== null && online !== undefined)
+                    this.set(online ? 'online' : 'offline');
+            }, () => { });
+        }
+    }
+    getState() {
+        return this.state;
+    }
+    /** Called on every change. Returns the unsubscribe. */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => { this.listeners.delete(listener); };
+    }
+    dispose() {
+        this.stop?.();
+        this.stop = null;
+        this.listeners.clear();
+    }
+    set(next) {
+        if (next === this.state)
+            return;
+        this.state = next;
+        for (const listener of [...this.listeners]) {
+            try {
+                listener();
+            }
+            catch { /* one broken listener must not stop the rest */ }
+        }
+    }
+}
+exports.KoolbaseConnectivity = KoolbaseConnectivity;

package/dist/cjs/database.d.ts

@@ -119,6 +119,16 @@ export declare class KoolbaseDatabase {
      */
     batch(operations: BatchOp[]): Promise<BatchResult[]>;
     get(recordId: string): Promise<KoolbaseRecord>;
+    /**
+     * The device's saved copy of a record: what this device last read, with the
+     * changes queued on it applied. Never contacts the server. Null when there is
+     * none: never read here, or deleted on this device.
+     *
+     * For showing something at once while get() asks the server -- saved-first,
+     * never saved-only. Kept data and revision, not createdAt or createdBy, which
+     * the saved copy does not hold (empty strings here).
+     */
+    getSaved(recordId: string): Promise<KoolbaseRecord | null>;
     /**
      * Writes that could not be applied, waiting for a decision.
      *
@@ -134,6 +144,28 @@ export declare class KoolbaseDatabase {
      * moment matters. Snapshot, not a live handle; per-user.
      */
     pendingWrites(): Promise<PendingWrite[]>;
+    /**
+     * The pending writes now, and again whenever they change -- here, in another
+     * tab, or because the signed-in user changed. For a sync badge that reflects
+     * reality. null while signed out: per-user state has no answer then, and a
+     * fake empty list is how a badge says "all synced" while a user's changes
+     * sit queued. Returns the unsubscribe.
+     */
+    watchPendingWrites(listener: (writes: PendingWrite[] | null) => void): () => void;
+    /** The unresolved conflicts now, and again whenever they change. null while signed out. */
+    watchConflicts(listener: (conflicts: KoolbaseConflict[] | null) => void): () => void;
+    /**
+     * The signed-in user changed: every watcher reads again, for the new user
+     * (or null, signed out). Koolbase.initialize wires it to auth changes.
+     */
+    sessionChanged(): void;
+    private readonly stateWatchers;
+    private offStateChange;
+    /**
+     * One watcher: reads at once, then on every change to the signed-in user's
+     * offline state. Reads can finish out of order; only the latest delivers.
+     */
+    private watchState;
     /**
      * Count and total over a whole collection, with the read rule applied
      * inside the query.