local-lite 0.0.20 → 0.0.21

package/dist/auth/index.d.ts

@@ -2,3 +2,4 @@ export * from './google.js';
 export * from './microsoft.js';
 export * from './github.js';
 export * from './apple.js';
+export * from './session.js';

package/dist/auth/index.js

@@ -18,3 +18,4 @@ __exportStar(require("./google.js"), exports);
 __exportStar(require("./microsoft.js"), exports);
 __exportStar(require("./github.js"), exports);
 __exportStar(require("./apple.js"), exports);
+__exportStar(require("./session.js"), exports);

package/dist/auth/session.d.ts

@@ -0,0 +1,107 @@
+import { DBExecutable } from '../core/schema-manager.js';
+import { EventEmitter } from '../reactive/event-emitter.js';
+export declare const DEFAULT_SESSIONS_TABLE = "_local_sessions";
+export declare const DEFAULT_OFFLINE_DURATION_MS: number;
+export interface SessionRecord<TUser = any> {
+    id: string;
+    userId: string;
+    user: TUser;
+    token?: string | null;
+    refreshToken?: string | null;
+    provider?: string | null;
+    createdAt: number;
+    lastActiveAt: number;
+    expiresAt?: number | null;
+    offlineAccessUntil?: number | null;
+    metadata?: Record<string, any> | null;
+    isActive: boolean;
+}
+export interface CreateSessionOptions<TUser = any> {
+    id?: string;
+    userId: string;
+    user: TUser;
+    token?: string | null;
+    refreshToken?: string | null;
+    provider?: string | null;
+    expiresAt?: number | null;
+    /**
+     * Duration in ms the session remains valid while offline without re-authenticating.
+     * Default: 30 days. Set to 0 or Infinity for unlimited offline access.
+     */
+    offlineDurationMs?: number;
+    metadata?: Record<string, any>;
+    /**
+     * Whether to activate this session as the active user immediately.
+     * Default: true
+     */
+    setActive?: boolean;
+}
+export interface SessionManagerOptions {
+    tableName?: string;
+    defaultOfflineDurationMs?: number;
+    network?: {
+        isOnline(): boolean | Promise<boolean>;
+    };
+}
+export declare function mapSessionRow<TUser = any>(r: any): SessionRecord<TUser>;
+export declare class SessionManager {
+    private db;
+    private events?;
+    private tableName;
+    private defaultOfflineDurationMs;
+    private network?;
+    constructor(db: DBExecutable, events?: EventEmitter | undefined, options?: SessionManagerOptions);
+    /**
+     * Ensures the _local_sessions schema exists.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Creates or updates a user session, persisting it to local SQLite so it remains available offline.
+     */
+    createSession<TUser = any>(options: CreateSessionOptions<TUser>): Promise<SessionRecord<TUser>>;
+    /**
+     * Retrieves the currently active session.
+     * If offline, the session remains active even if server tokens expired, as long as offlineAccessUntil is valid.
+     */
+    getActiveSession<TUser = any>(): Promise<SessionRecord<TUser> | null>;
+    /**
+     * Returns true if there is an active valid session (works offline and online).
+     */
+    isAuthenticated(): Promise<boolean>;
+    /**
+     * Retrieves the authenticated user profile object, or null if signed out.
+     */
+    getUser<TUser = any>(): Promise<TUser | null>;
+    /**
+     * Updates last active timestamp.
+     */
+    touch(sessionId?: string): Promise<void>;
+    /**
+     * Partially updates the active user's profile data in SQLite.
+     */
+    updateUser<TUser = any>(partialUser: Partial<TUser>): Promise<SessionRecord<TUser> | null>;
+    /**
+     * Updates access tokens without re-authenticating or resetting the offline grace period.
+     */
+    updateTokens(tokens: {
+        token?: string | null;
+        refreshToken?: string | null;
+        expiresAt?: number | null;
+    }): Promise<void>;
+    /**
+     * Signs out the active user session.
+     */
+    clearSession(): Promise<void>;
+    /**
+     * Completely purges all stored sessions (e.g. factory reset or privacy wipe).
+     */
+    purgeAllSessions(): Promise<void>;
+    /**
+     * Lists all sessions currently cached in SQLite.
+     */
+    listSessions<TUser = any>(): Promise<SessionRecord<TUser>[]>;
+    /**
+     * Switches the active session to a different account (e.g., multi-account or organization switching offline).
+     */
+    switchSession<TUser = any>(sessionIdOrUserId: string): Promise<SessionRecord<TUser> | null>;
+}

package/dist/auth/session.js

@@ -0,0 +1,259 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionManager = exports.DEFAULT_OFFLINE_DURATION_MS = exports.DEFAULT_SESSIONS_TABLE = void 0;
+exports.mapSessionRow = mapSessionRow;
+const uuid_js_1 = require("../utils/uuid.js");
+exports.DEFAULT_SESSIONS_TABLE = '_local_sessions';
+exports.DEFAULT_OFFLINE_DURATION_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
+function mapSessionRow(r) {
+    let userData;
+    try {
+        userData = typeof r.user_data === 'string' ? JSON.parse(r.user_data) : r.user_data;
+    }
+    catch {
+        userData = r.user_data;
+    }
+    let metadata = null;
+    if (r.metadata) {
+        try {
+            metadata = typeof r.metadata === 'string' ? JSON.parse(r.metadata) : r.metadata;
+        }
+        catch {
+            metadata = null;
+        }
+    }
+    return {
+        id: String(r.id),
+        userId: String(r.user_id),
+        user: userData,
+        token: r.token || null,
+        refreshToken: r.refresh_token || null,
+        provider: r.provider || null,
+        createdAt: Number(r.created_at || 0),
+        lastActiveAt: Number(r.last_active_at || 0),
+        expiresAt: r.expires_at != null ? Number(r.expires_at) : null,
+        offlineAccessUntil: r.offline_access_until != null ? Number(r.offline_access_until) : null,
+        metadata,
+        isActive: r.is_active === 1 || r.is_active === '1' || r.is_active === true,
+    };
+}
+class SessionManager {
+    db;
+    events;
+    tableName;
+    defaultOfflineDurationMs;
+    network;
+    constructor(db, events, options = {}) {
+        this.db = db;
+        this.events = events;
+        this.tableName = options.tableName ?? exports.DEFAULT_SESSIONS_TABLE;
+        this.defaultOfflineDurationMs = options.defaultOfflineDurationMs ?? exports.DEFAULT_OFFLINE_DURATION_MS;
+        this.network = options.network;
+    }
+    /**
+     * Ensures the _local_sessions schema exists.
+     */
+    async initialize() {
+        await this.db.execute(`CREATE TABLE IF NOT EXISTS ${this.tableName} (
+        id TEXT PRIMARY KEY,
+        user_id TEXT NOT NULL,
+        user_data TEXT NOT NULL,
+        token TEXT,
+        refresh_token TEXT,
+        provider TEXT,
+        created_at INTEGER NOT NULL,
+        last_active_at INTEGER NOT NULL,
+        expires_at INTEGER,
+        offline_access_until INTEGER,
+        metadata TEXT,
+        is_active INTEGER NOT NULL DEFAULT 1
+      );`);
+        await this.db.execute(`CREATE INDEX IF NOT EXISTS idx_${this.tableName}_user ON ${this.tableName} (user_id);`);
+        await this.db.execute(`CREATE INDEX IF NOT EXISTS idx_${this.tableName}_active ON ${this.tableName} (is_active);`);
+    }
+    /**
+     * Creates or updates a user session, persisting it to local SQLite so it remains available offline.
+     */
+    async createSession(options) {
+        const id = options.id || `sess_${(0, uuid_js_1.generateUUID)()}`;
+        const now = Date.now();
+        const offlineDuration = options.offlineDurationMs !== undefined
+            ? options.offlineDurationMs
+            : this.defaultOfflineDurationMs;
+        const offlineAccessUntil = offlineDuration === 0 || offlineDuration === Infinity
+            ? null
+            : now + offlineDuration;
+        const setActive = options.setActive !== false;
+        const userDataStr = JSON.stringify(options.user ?? {});
+        const metadataStr = options.metadata ? JSON.stringify(options.metadata) : null;
+        if (setActive) {
+            // Deactivate other sessions
+            await this.db.execute(`UPDATE ${this.tableName} SET is_active = ?;`, [0]);
+        }
+        const sql = `
+      INSERT INTO ${this.tableName} (id, user_id, user_data, token, refresh_token, provider, created_at, last_active_at, expires_at, offline_access_until, metadata, is_active)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(id) DO UPDATE SET
+        user_id = excluded.user_id,
+        user_data = excluded.user_data,
+        token = excluded.token,
+        refresh_token = excluded.refresh_token,
+        provider = excluded.provider,
+        last_active_at = excluded.last_active_at,
+        expires_at = excluded.expires_at,
+        offline_access_until = excluded.offline_access_until,
+        metadata = excluded.metadata,
+        is_active = excluded.is_active;
+    `;
+        await this.db.execute(sql, [
+            id,
+            options.userId,
+            userDataStr,
+            options.token ?? null,
+            options.refreshToken ?? null,
+            options.provider ?? null,
+            now,
+            now,
+            options.expiresAt ?? null,
+            offlineAccessUntil,
+            metadataStr,
+            setActive ? 1 : 0,
+        ]);
+        const session = {
+            id,
+            userId: options.userId,
+            user: options.user,
+            token: options.token || null,
+            refreshToken: options.refreshToken || null,
+            provider: options.provider || null,
+            createdAt: now,
+            lastActiveAt: now,
+            expiresAt: options.expiresAt || null,
+            offlineAccessUntil,
+            metadata: options.metadata || null,
+            isActive: setActive,
+        };
+        this.events?.emit(this.tableName, { operation: 'SET_SESSION', session });
+        return session;
+    }
+    /**
+     * Retrieves the currently active session.
+     * If offline, the session remains active even if server tokens expired, as long as offlineAccessUntil is valid.
+     */
+    async getActiveSession() {
+        const rows = await this.db.execute(`SELECT * FROM ${this.tableName} WHERE is_active = ? LIMIT 1;`, [1]);
+        if (!rows || rows.length === 0) {
+            return null;
+        }
+        const session = mapSessionRow(rows[0]);
+        const now = Date.now();
+        // Check if offline access grace period has expired
+        if (session.offlineAccessUntil != null && now > session.offlineAccessUntil) {
+            await this.clearSession();
+            return null;
+        }
+        // Touch last active
+        await this.touch(session.id);
+        return session;
+    }
+    /**
+     * Returns true if there is an active valid session (works offline and online).
+     */
+    async isAuthenticated() {
+        const session = await this.getActiveSession();
+        return session !== null;
+    }
+    /**
+     * Retrieves the authenticated user profile object, or null if signed out.
+     */
+    async getUser() {
+        const session = await this.getActiveSession();
+        return session ? session.user : null;
+    }
+    /**
+     * Updates last active timestamp.
+     */
+    async touch(sessionId) {
+        const now = Date.now();
+        if (sessionId) {
+            await this.db.execute(`UPDATE ${this.tableName} SET last_active_at = ? WHERE id = ?;`, [now, sessionId]);
+        }
+        else {
+            await this.db.execute(`UPDATE ${this.tableName} SET last_active_at = ? WHERE is_active = ?;`, [now, 1]);
+        }
+    }
+    /**
+     * Partially updates the active user's profile data in SQLite.
+     */
+    async updateUser(partialUser) {
+        const session = await this.getActiveSession();
+        if (!session)
+            return null;
+        const updatedUser = {
+            ...session.user,
+            ...partialUser,
+        };
+        const userDataStr = JSON.stringify(updatedUser);
+        const now = Date.now();
+        await this.db.execute(`UPDATE ${this.tableName} SET user_data = ?, last_active_at = ? WHERE id = ?;`, [userDataStr, now, session.id]);
+        session.user = updatedUser;
+        session.lastActiveAt = now;
+        this.events?.emit(this.tableName, { operation: 'UPDATE_USER', session });
+        return session;
+    }
+    /**
+     * Updates access tokens without re-authenticating or resetting the offline grace period.
+     */
+    async updateTokens(tokens) {
+        const session = await this.getActiveSession();
+        if (!session)
+            return;
+        const token = tokens.token !== undefined ? tokens.token : session.token;
+        const refreshToken = tokens.refreshToken !== undefined ? tokens.refreshToken : session.refreshToken;
+        const expiresAt = tokens.expiresAt !== undefined ? tokens.expiresAt : session.expiresAt;
+        const now = Date.now();
+        await this.db.execute(`UPDATE ${this.tableName} SET token = ?, refresh_token = ?, expires_at = ?, last_active_at = ? WHERE id = ?;`, [token, refreshToken, expiresAt, now, session.id]);
+        session.token = token;
+        session.refreshToken = refreshToken;
+        session.expiresAt = expiresAt;
+        this.events?.emit(this.tableName, { operation: 'UPDATE_TOKENS', session });
+    }
+    /**
+     * Signs out the active user session.
+     */
+    async clearSession() {
+        await this.db.execute(`UPDATE ${this.tableName} SET is_active = ? WHERE is_active = ?;`, [0, 1]);
+        this.events?.emit(this.tableName, { operation: 'CLEAR_SESSION' });
+    }
+    /**
+     * Completely purges all stored sessions (e.g. factory reset or privacy wipe).
+     */
+    async purgeAllSessions() {
+        await this.db.execute(`DELETE FROM ${this.tableName};`);
+        this.events?.emit(this.tableName, { operation: 'PURGE_SESSIONS' });
+    }
+    /**
+     * Lists all sessions currently cached in SQLite.
+     */
+    async listSessions() {
+        const rows = await this.db.execute(`SELECT * FROM ${this.tableName} ORDER BY last_active_at DESC;`);
+        return (rows || []).map((r) => mapSessionRow(r));
+    }
+    /**
+     * Switches the active session to a different account (e.g., multi-account or organization switching offline).
+     */
+    async switchSession(sessionIdOrUserId) {
+        const rows = await this.db.execute(`SELECT * FROM ${this.tableName} WHERE id = ? OR user_id = ? LIMIT 1;`, [sessionIdOrUserId, sessionIdOrUserId]);
+        if (!rows || rows.length === 0) {
+            return null;
+        }
+        const targetSession = mapSessionRow(rows[0]);
+        await this.db.execute(`UPDATE ${this.tableName} SET is_active = ?;`, [0]);
+        await this.db.execute(`UPDATE ${this.tableName} SET is_active = ?, last_active_at = ? WHERE id = ?;`, [1, Date.now(), targetSession.id]);
+        targetSession.isActive = true;
+        targetSession.lastActiveAt = Date.now();
+        this.events?.emit(this.tableName, { operation: 'SWITCH_SESSION', session: targetSession });
+        return targetSession;
+    }
+}
+exports.SessionManager = SessionManager;

package/dist/core/client.d.ts

@@ -15,6 +15,7 @@ import { KVManager, type KVStoreOptions } from '../kv/index.js';
 import { SearchManager } from '../search/index.js';
 import { BlobStorageManager, type BlobStorageManagerOptions } from '../storage/index.js';
 import { JobScheduler, type JobSchedulerOptions } from '../scheduler/index.js';
+import { SessionManager, type SessionManagerOptions } from '../auth/session.js';
 export interface LocalFirstClientConfig {
     local: LocalDBAdapter;
     remote: RemoteDBAdapter;
@@ -50,6 +51,7 @@ export interface LocalFirstClientConfig {
     kv?: KVStoreOptions;
     storage?: BlobStorageManagerOptions;
     scheduler?: JobSchedulerOptions;
+    session?: SessionManagerOptions;
 }
 export declare class TransactionalClient {
     private parent;
@@ -103,6 +105,7 @@ export declare class LocalFirstClient {
     readonly search: SearchManager;
     readonly storage: BlobStorageManager;
     readonly scheduler: JobScheduler;
+    readonly session: SessionManager;
     private primaryKey;
     private migrations;
     private autoStart;

package/dist/core/client.js

@@ -20,6 +20,7 @@ const index_js_4 = require("../kv/index.js");
 const index_js_5 = require("../search/index.js");
 const index_js_6 = require("../storage/index.js");
 const index_js_7 = require("../scheduler/index.js");
+const session_js_1 = require("../auth/session.js");
 function hasFunctionFilter(value) {
     if (typeof value === 'function')
         return true;
@@ -178,6 +179,7 @@ class LocalFirstClient {
     search;
     storage;
     scheduler;
+    session;
     primaryKey;
     migrations;
     autoStart;
@@ -210,6 +212,8 @@ class LocalFirstClient {
             '_local_job_runs',
             '_local_api_keys',
             '_local_actions',
+            '_local_sessions',
+            '_local_sessions',
         ]);
         const actionNetwork = config.actions?.network ?? config.network;
         this.keys = new index_js_3.ApiKeyManager(this.db, config.keys);
@@ -220,6 +224,10 @@ class LocalFirstClient {
             ...config.storage,
         });
         this.scheduler = new index_js_7.JobScheduler(this.db, config.scheduler);
+        this.session = new session_js_1.SessionManager(this.db, this.events, {
+            network: config.network,
+            ...config.session,
+        });
         this.actions = new index_js_2.ActionManager(this.db, this.events, () => Promise.resolve(actionNetwork ? actionNetwork.isOnline() : true), {
             network: actionNetwork,
             ...config.actions,
@@ -387,6 +395,7 @@ class LocalFirstClient {
         await this.kv.initialize();
         await this.storage.initialize();
         await this.scheduler.initialize();
+        await this.session.initialize();
         if (this.migrations.length > 0) {
             await this.db.transaction(async (tx) => {
                 for (const query of this.migrations) {

package/dist/react/index.d.ts

@@ -133,3 +133,4 @@ export * from './auth.js';
 export * from './backups.js';
 export * from './kv.js';
 export * from './search.js';
+export * from './session.js';

package/dist/react/index.js

@@ -648,3 +648,4 @@ __exportStar(require("./auth.js"), exports);
 __exportStar(require("./backups.js"), exports);
 __exportStar(require("./kv.js"), exports);
 __exportStar(require("./search.js"), exports);
+__exportStar(require("./session.js"), exports);

package/dist/react/session.d.ts

@@ -0,0 +1,26 @@
+import { LocalFirstClient } from '../core/client.js';
+import { SessionRecord, CreateSessionOptions } from '../auth/session.js';
+export interface UseSessionResult<TUser = any> {
+    session: SessionRecord<TUser> | null;
+    user: TUser | null;
+    isAuthenticated: boolean;
+    isOffline: boolean;
+    loading: boolean;
+    createSession: (options: CreateSessionOptions<TUser>) => Promise<SessionRecord<TUser>>;
+    updateUser: (partialUser: Partial<TUser>) => Promise<SessionRecord<TUser> | null>;
+    updateTokens: (tokens: {
+        token?: string | null;
+        refreshToken?: string | null;
+        expiresAt?: number | null;
+    }) => Promise<void>;
+    signOut: () => Promise<void>;
+    refetchSession: () => Promise<SessionRecord<TUser> | null>;
+}
+/**
+ * Reactive React hook for persistent, offline-first user session management.
+ * The session remains authenticated even when offline, ensuring uninterrupted UX.
+ *
+ * Example:
+ * const { user, isAuthenticated, isOffline, signOut } = useSession(client);
+ */
+export declare function useSession<TUser = any>(client: LocalFirstClient | null | undefined): UseSessionResult<TUser>;

package/dist/react/session.js

@@ -0,0 +1,118 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useSession = useSession;
+const react_1 = require("react");
+/**
+ * Reactive React hook for persistent, offline-first user session management.
+ * The session remains authenticated even when offline, ensuring uninterrupted UX.
+ *
+ * Example:
+ * const { user, isAuthenticated, isOffline, signOut } = useSession(client);
+ */
+function useSession(client) {
+    const [session, setSession] = (0, react_1.useState)(null);
+    const [loading, setLoading] = (0, react_1.useState)(true);
+    const [isOffline, setIsOffline] = (0, react_1.useState)(false);
+    const loadSession = (0, react_1.useCallback)(async () => {
+        if (!client) {
+            setSession(null);
+            setLoading(false);
+            return null;
+        }
+        try {
+            const active = await client.session.getActiveSession();
+            setSession(active);
+            return active;
+        }
+        catch {
+            return null;
+        }
+        finally {
+            setLoading(false);
+        }
+    }, [client]);
+    (0, react_1.useEffect)(() => {
+        if (!client) {
+            setSession(null);
+            setLoading(false);
+            return;
+        }
+        let isMounted = true;
+        // Check network
+        const checkNetwork = () => {
+            const net = client.syncWorker?.networkStatusProvider;
+            if (net && typeof net.isOnline === 'function') {
+                const res = net.isOnline();
+                if (typeof res === 'boolean') {
+                    if (isMounted)
+                        setIsOffline(!res);
+                }
+                else if (res && typeof res.then === 'function') {
+                    res.then((online) => {
+                        if (isMounted)
+                            setIsOffline(!online);
+                    });
+                }
+            }
+        };
+        checkNetwork();
+        loadSession();
+        // Listen to session changes
+        const unsubscribeSession = client.events.on('_local_sessions', () => {
+            if (isMounted) {
+                loadSession();
+            }
+        });
+        // Listen to network changes if available
+        const unsubscribeNetwork = client.events.on('network', (status) => {
+            if (isMounted && status && typeof status.online === 'boolean') {
+                setIsOffline(!status.online);
+            }
+        });
+        return () => {
+            isMounted = false;
+            unsubscribeSession();
+            if (typeof unsubscribeNetwork === 'function') {
+                unsubscribeNetwork();
+            }
+        };
+    }, [client, loadSession]);
+    const createSession = (0, react_1.useCallback)(async (options) => {
+        if (!client)
+            throw new Error('Client not provided to useSession.');
+        const res = await client.session.createSession(options);
+        setSession(res);
+        return res;
+    }, [client]);
+    const updateUser = (0, react_1.useCallback)(async (partialUser) => {
+        if (!client)
+            return null;
+        const res = await client.session.updateUser(partialUser);
+        setSession(res);
+        return res;
+    }, [client]);
+    const updateTokens = (0, react_1.useCallback)(async (tokens) => {
+        if (!client)
+            return;
+        await client.session.updateTokens(tokens);
+        await loadSession();
+    }, [client, loadSession]);
+    const signOut = (0, react_1.useCallback)(async () => {
+        if (!client)
+            return;
+        await client.session.clearSession();
+        setSession(null);
+    }, [client]);
+    return {
+        session,
+        user: session ? session.user : null,
+        isAuthenticated: session !== null,
+        isOffline,
+        loading,
+        createSession,
+        updateUser,
+        updateTokens,
+        signOut,
+        refetchSession: loadSession,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "local-lite",
-  "version": "0.0.20",
+  "version": "0.0.21",
   "description": "Never let a lost connection break a promise. Local-first sync that faithfully keeps data safe until you're back online.",
   "license": "MIT",
   "main": "dist/index.js",