local-lite 0.0.20 → 0.0.22

package/dist/adapters/remote/convex.d.ts

@@ -1,6 +1,7 @@
 import { RemoteDBAdapter } from './index.js';
 import { DeltaChanges, SyncOperation, PushResult } from '../../core/types.js';
 import { SyncLogger, CustomLogger, LogLevel } from '../../utils/logger.js';
+import { createConvexStorageUploader, ConvexStorageUploaderOptions, ConvexStorageUploaderInstance } from '../../storage/convex.js';
 export interface ConvexRemoteAdapterOptions {
     /**
      * Tables synchronized with Convex.
@@ -68,4 +69,10 @@ export declare class ConvexRemoteAdapter implements RemoteDBAdapter {
      * Cleans up live subscriptions.
      */
     destroy(): void;
+    /**
+     * Helper to create a remote storage uploader targeting Convex File Storage.
+     * Connects local-lite offline blob/file storage directly to Convex File Storage.
+     */
+    createStorageUploader(options?: ConvexStorageUploaderOptions): ConvexStorageUploaderInstance;
 }
+export { createConvexStorageUploader, type ConvexStorageUploaderOptions, type ConvexStorageUploaderInstance, };

package/dist/adapters/remote/convex.js

@@ -1,7 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ConvexRemoteAdapter = void 0;
+exports.createConvexStorageUploader = exports.ConvexRemoteAdapter = void 0;
 const logger_js_1 = require("../../utils/logger.js");
+const convex_js_1 = require("../../storage/convex.js");
+Object.defineProperty(exports, "createConvexStorageUploader", { enumerable: true, get: function () { return convex_js_1.createConvexStorageUploader; } });
 class ConvexRemoteAdapter {
     client;
     tables;
@@ -177,5 +179,12 @@ class ConvexRemoteAdapter {
             this.unsubscribeLive = undefined;
         }
     }
+    /**
+     * Helper to create a remote storage uploader targeting Convex File Storage.
+     * Connects local-lite offline blob/file storage directly to Convex File Storage.
+     */
+    createStorageUploader(options = {}) {
+        return (0, convex_js_1.createConvexStorageUploader)(this.client, options);
+    }
 }
 exports.ConvexRemoteAdapter = ConvexRemoteAdapter;

package/dist/adapters/remote/firestore.d.ts

@@ -1,6 +1,7 @@
 import { RemoteDBAdapter } from './index.js';
 import { DeltaChanges, SyncOperation, PushResult } from '../../core/types.js';
 import { SyncLogger, CustomLogger, LogLevel } from '../../utils/logger.js';
+import { createFirebaseStorageUploader, FirebaseStorageUploaderOptions, FirebaseStorageUploaderInstance } from '../../storage/firebase.js';
 export interface FirestoreAdapterOptions {
     /**
      * Collections (tables) synchronized with Firestore.
@@ -62,4 +63,10 @@ export declare class FirestoreRemoteAdapter implements RemoteDBAdapter {
      * Cleans up all active real-time listeners.
      */
     destroy(): void;
+    /**
+     * Helper to create a remote storage uploader targeting Firebase Cloud Storage.
+     * Connects local-lite offline blob/file storage directly to Firebase Storage.
+     */
+    createStorageUploader(storageOrApp?: any, options?: FirebaseStorageUploaderOptions): FirebaseStorageUploaderInstance;
 }
+export { FirestoreRemoteAdapter as FirestoreAdapter, createFirebaseStorageUploader, type FirebaseStorageUploaderOptions, type FirebaseStorageUploaderInstance, };

package/dist/adapters/remote/firestore.js

@@ -1,7 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FirestoreRemoteAdapter = void 0;
+exports.createFirebaseStorageUploader = exports.FirestoreAdapter = exports.FirestoreRemoteAdapter = void 0;
 const logger_js_1 = require("../../utils/logger.js");
+const firebase_js_1 = require("../../storage/firebase.js");
+Object.defineProperty(exports, "createFirebaseStorageUploader", { enumerable: true, get: function () { return firebase_js_1.createFirebaseStorageUploader; } });
 /**
  * Safely extracts epoch milliseconds from numbers, Firestore Timestamps, or ISO strings.
  */
@@ -328,5 +330,25 @@ class FirestoreRemoteAdapter {
         }
         this.unsubscribers = [];
     }
+    /**
+     * Helper to create a remote storage uploader targeting Firebase Cloud Storage.
+     * Connects local-lite offline blob/file storage directly to Firebase Storage.
+     */
+    createStorageUploader(storageOrApp, options = {}) {
+        let client = storageOrApp;
+        let opts = options;
+        if (storageOrApp &&
+            !storageOrApp.ref &&
+            !storageOrApp.storage &&
+            !storageOrApp.app &&
+            typeof storageOrApp === 'object' &&
+            ('bucket' in storageOrApp || 'storageModule' in storageOrApp || 'basePath' in storageOrApp)) {
+            opts = storageOrApp;
+            client = this.db.app || this.db;
+        }
+        const resolvedClient = client || this.db.app || this.db;
+        return (0, firebase_js_1.createFirebaseStorageUploader)(resolvedClient, opts);
+    }
 }
 exports.FirestoreRemoteAdapter = FirestoreRemoteAdapter;
+exports.FirestoreAdapter = FirestoreRemoteAdapter;

package/dist/adapters/remote/supabase.d.ts

@@ -2,6 +2,7 @@ import type { SupabaseClient } from '@supabase/supabase-js';
 import { RemoteDBAdapter } from './index.js';
 import { DeltaChanges, PushResult, SyncOperation } from '../../core/types.js';
 import { SyncLogger, CustomLogger, LogLevel } from '../../utils/logger.js';
+import { createSupabaseStorageUploader, type SupabaseStorageUploaderOptions, type SupabaseStorageUploaderInstance } from '../../storage/supabase.js';
 export interface SupabaseAdapterOptions {
     /**
      * The list of Postgres tables to sync.
@@ -123,4 +124,10 @@ export declare class SupabaseRemoteAdapter implements RemoteDBAdapter {
      * Clean up active realtime channels.
      */
     destroy(): void;
+    /**
+     * Helper to create a remote storage uploader targeting Supabase Storage buckets.
+     * Connects local-lite offline blob/file storage directly to Supabase Storage.
+     */
+    createStorageUploader(options: SupabaseStorageUploaderOptions): SupabaseStorageUploaderInstance;
 }
+export { SupabaseRemoteAdapter as SupabaseAdapter, createSupabaseStorageUploader, type SupabaseStorageUploaderOptions, type SupabaseStorageUploaderInstance, };

package/dist/adapters/remote/supabase.js

@@ -1,7 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SupabaseRemoteAdapter = void 0;
+exports.createSupabaseStorageUploader = exports.SupabaseAdapter = exports.SupabaseRemoteAdapter = void 0;
 const logger_js_1 = require("../../utils/logger.js");
+const supabase_js_1 = require("../../storage/supabase.js");
+Object.defineProperty(exports, "createSupabaseStorageUploader", { enumerable: true, get: function () { return supabase_js_1.createSupabaseStorageUploader; } });
 class SupabaseRemoteAdapter {
     clientResolver;
     activeLiveCallback;
@@ -25,7 +27,8 @@ class SupabaseRemoteAdapter {
             typeof clientOrOptions === 'object' &&
             !('channel' in clientOrOptions) &&
             !('from' in clientOrOptions) &&
-            !('auth' in clientOrOptions)) {
+            !('auth' in clientOrOptions) &&
+            !('storage' in clientOrOptions)) {
             client = null;
             options = clientOrOptions;
         }
@@ -640,5 +643,13 @@ class SupabaseRemoteAdapter {
             this.activeChannel = undefined;
         }
     }
+    /**
+     * Helper to create a remote storage uploader targeting Supabase Storage buckets.
+     * Connects local-lite offline blob/file storage directly to Supabase Storage.
+     */
+    createStorageUploader(options) {
+        return (0, supabase_js_1.createSupabaseStorageUploader)(this.getClient(), options);
+    }
 }
 exports.SupabaseRemoteAdapter = SupabaseRemoteAdapter;
+exports.SupabaseAdapter = SupabaseRemoteAdapter;

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,16 +212,34 @@ 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);
         this.kv = new index_js_4.KVManager(this.db, this.events, config.kv);
         this.search = new index_js_5.SearchManager(this.db, this.events, (table, id) => this.findById(table, id));
+        let storageUploader = config.storage?.uploader;
+        if (!storageUploader && config.storage) {
+            if (typeof this.remote?.createStorageUploader === 'function' &&
+                (config.storage.autoRemote !== false &&
+                    (config.storage.autoRemote || config.storage.bucket || config.storage.uploadMutation))) {
+                try {
+                    storageUploader = this.remote.createStorageUploader(config.storage);
+                }
+                catch { }
+            }
+        }
         this.storage = new index_js_6.BlobStorageManager(this.db, {
             network: config.network,
             ...config.storage,
+            uploader: storageUploader,
         });
         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 +407,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>;