local-lite 0.0.10 → 0.0.12

package/README.md

@@ -87,6 +87,8 @@ This recovers sync state; it does not repair corrupt SQLite files or cancel hung
 * **📶 Network-Aware:** Automatically pauses polling when offline and triggers immediate sync flushes the instant connectivity is restored.
 * **🔄 Infinite-Loop Safe:** Incoming remote deltas update local tables and fire reactive UI listeners without echoing back into the outbox.
 * **☁️ Database Backups:** Export and restore SQLite snapshots independently of your live sync backend.
+* **🔑 Google Sign-In Out of the Box:** Secure, zero-backend Google OAuth 2.0 (PKCE) authentication with automatic token refresh, user profile retrieval, persistent session storage, and `useGoogleAuth()` hook.
+
 
 ---
 
@@ -244,8 +246,50 @@ export function TodoScreen() {
 }
 ```
 
+### 3. Google Sign-In (Out of the Box)
+
+`local-lite` provides a zero-backend, PKCE-secured Google OAuth 2.0 client with automatic token refreshing, user profile retrieval, and React hooks.
+
+```tsx
+import * as WebBrowser from 'expo-web-browser';
+import * as Linking from 'expo-linking';
+import { GoogleAuthClient } from 'local-lite/auth';
+import { useGoogleAuth } from 'local-lite/react';
+
+const googleAuth = new GoogleAuthClient({
+  clientId: 'YOUR_GOOGLE_CLIENT_ID.apps.googleusercontent.com',
+  redirectUri: Linking.createURL('oauth'),
+  authorize: async ({ authorizationUrl, redirectUri }) => {
+    const res = await WebBrowser.openAuthSessionAsync(authorizationUrl, redirectUri);
+    if (res.type !== 'success' || !res.url) return null;
+    const url = new URL(res.url);
+    return {
+      code: url.searchParams.get('code') || '',
+      state: url.searchParams.get('state') || '',
+    };
+  },
+});
+
+export function UserProfileHeader() {
+  const { user, isSignedIn, loading, signIn, signOut } = useGoogleAuth(googleAuth);
+
+  if (loading) return <Text>Loading...</Text>;
+  if (!isSignedIn) {
+    return <Button title="Sign in with Google" onPress={signIn} />;
+  }
+
+  return (
+    <View>
+      <Text>Welcome, {user?.name} ({user?.email})</Text>
+      <Button title="Sign Out" onPress={signOut} />
+    </View>
+  );
+}
+```
+
 ---
 
+
 ## Supabase Backend Setup & Schema
 
 To synchronize with Supabase using zero-clock-skew delta queries and `deleted: true` soft deletes, execute the following script in your Supabase project (**Dashboard → SQL Editor**):

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

@@ -19,3 +19,13 @@ export declare class MemoryDemoRemoteAdapter implements RemoteDBAdapter {
     emitLiveChanges(changes: DeltaChanges): void;
     clear(): void;
 }
+/**
+ * Built-in No-Op Remote Adapter for local-only / offline operation.
+ * Acknowledges all local outbox pushes with 0 latency, performs no remote pulls,
+ * and maintains zero cloud backend connections.
+ */
+export declare class NoopRemoteAdapter implements RemoteDBAdapter {
+    pushChanges(_operations: SyncOperation[]): Promise<boolean>;
+    fetchChanges(_sinceTimestamp: number): Promise<DeltaChanges>;
+    subscribeToLiveChanges(_callback: (changes: DeltaChanges) => void): () => void;
+}

package/dist/adapters/remote/demo.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MemoryDemoRemoteAdapter = void 0;
+exports.NoopRemoteAdapter = exports.MemoryDemoRemoteAdapter = void 0;
 /**
  * Built-in In-Memory Demo Remote Adapter.
  * Useful for prototyping, offline testing, and previewing without a live backend.
@@ -47,3 +47,23 @@ class MemoryDemoRemoteAdapter {
     }
 }
 exports.MemoryDemoRemoteAdapter = MemoryDemoRemoteAdapter;
+/**
+ * Built-in No-Op Remote Adapter for local-only / offline operation.
+ * Acknowledges all local outbox pushes with 0 latency, performs no remote pulls,
+ * and maintains zero cloud backend connections.
+ */
+class NoopRemoteAdapter {
+    async pushChanges(_operations) {
+        return true;
+    }
+    async fetchChanges(_sinceTimestamp) {
+        return {
+            timestamp: Date.now(),
+            changes: [],
+        };
+    }
+    subscribeToLiveChanges(_callback) {
+        return () => { };
+    }
+}
+exports.NoopRemoteAdapter = NoopRemoteAdapter;

package/dist/auth/google.d.ts

@@ -0,0 +1,75 @@
+import { GoogleDriveBackupStorage } from '../backups/cloud-storage.js';
+export declare const GOOGLE_AUTHORIZATION_ENDPOINT = "https://accounts.google.com/o/oauth2/v2/auth";
+export declare const GOOGLE_TOKEN_ENDPOINT = "https://oauth2.googleapis.com/token";
+export declare const GOOGLE_USERINFO_ENDPOINT = "https://www.googleapis.com/oauth2/v3/userinfo";
+export declare const DEFAULT_GOOGLE_AUTH_SCOPES: string[];
+export interface GoogleUser {
+    id: string;
+    email: string;
+    emailVerified: boolean;
+    name: string;
+    givenName?: string;
+    familyName?: string;
+    picture?: string;
+    locale?: string;
+}
+export interface GoogleAuthTokens {
+    accessToken: string;
+    refreshToken?: string;
+    idToken?: string;
+    expiresAt: number;
+    tokenType?: string;
+    scope?: string;
+}
+export interface GoogleAuthTokenStore {
+    getTokens(): Promise<GoogleAuthTokens | null>;
+    setTokens(tokens: GoogleAuthTokens): Promise<void>;
+    removeTokens(): Promise<void>;
+    getUser(): Promise<GoogleUser | null>;
+    setUser(user: GoogleUser | null): Promise<void>;
+}
+export interface GoogleAuthKeyValueStorage {
+    getItem(key: string): Promise<unknown>;
+    setItem(key: string, value: unknown): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
+export interface GoogleAuthorizationRequest {
+    authorizationUrl: string;
+    redirectUri: string;
+    state: string;
+}
+export interface GoogleAuthorizationResponse {
+    code: string;
+    state: string;
+}
+export interface GoogleAuthClientOptions {
+    clientId: string;
+    redirectUri: string;
+    scopes?: string[];
+    authorize: (request: GoogleAuthorizationRequest) => Promise<GoogleAuthorizationResponse | null>;
+    tokenStore?: GoogleAuthTokenStore;
+    storage?: GoogleAuthKeyValueStorage;
+    randomBytes?: (length: number) => Uint8Array;
+    fetch?: typeof fetch;
+    prompt?: 'consent' | 'select_account' | 'none';
+    accessType?: 'offline' | 'online';
+}
+export declare function createInMemoryGoogleTokenStore(): GoogleAuthTokenStore;
+export declare function createGoogleAuthTokenStore(storage: GoogleAuthKeyValueStorage, prefix?: string): GoogleAuthTokenStore;
+export declare class GoogleAuthClient {
+    private readonly options;
+    private readonly tokenStore;
+    private readonly fetcher;
+    private readonly listeners;
+    private currentUser;
+    constructor(options: GoogleAuthClientOptions);
+    onAuthStateChange(listener: (user: GoogleUser | null) => void): () => void;
+    private notify;
+    signIn(): Promise<GoogleUser | null>;
+    signOut(): Promise<void>;
+    isSignedIn(): Promise<boolean>;
+    getUser(): Promise<GoogleUser | null>;
+    getValidAccessToken(): Promise<string>;
+    private fetchUserProfile;
+    createDriveBackupStorage(): GoogleDriveBackupStorage;
+}

package/dist/auth/google.js

@@ -0,0 +1,323 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GoogleAuthClient = exports.DEFAULT_GOOGLE_AUTH_SCOPES = exports.GOOGLE_USERINFO_ENDPOINT = exports.GOOGLE_TOKEN_ENDPOINT = exports.GOOGLE_AUTHORIZATION_ENDPOINT = void 0;
+exports.createInMemoryGoogleTokenStore = createInMemoryGoogleTokenStore;
+exports.createGoogleAuthTokenStore = createGoogleAuthTokenStore;
+const sha2_js_1 = require("@noble/hashes/sha2.js");
+const utils_js_1 = require("@noble/hashes/utils.js");
+const cloud_storage_js_1 = require("../backups/cloud-storage.js");
+exports.GOOGLE_AUTHORIZATION_ENDPOINT = 'https://accounts.google.com/o/oauth2/v2/auth';
+exports.GOOGLE_TOKEN_ENDPOINT = 'https://oauth2.googleapis.com/token';
+exports.GOOGLE_USERINFO_ENDPOINT = 'https://www.googleapis.com/oauth2/v3/userinfo';
+exports.DEFAULT_GOOGLE_AUTH_SCOPES = ['openid', 'email', 'profile'];
+function secureRandomBytes(length) {
+    const crypto = globalThis.crypto;
+    if (!crypto?.getRandomValues) {
+        throw new Error('Secure random number generation is unavailable.');
+    }
+    return crypto.getRandomValues(new Uint8Array(length));
+}
+function base64UrlEncode(bytes) {
+    const alphabet = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+    let result = '';
+    for (let index = 0; index < bytes.length; index += 3) {
+        const first = bytes[index];
+        const second = bytes[index + 1];
+        const third = bytes[index + 2];
+        result += alphabet[first >> 2];
+        result += alphabet[((first & 3) << 4) | (second === undefined ? 0 : second >> 4)];
+        if (second !== undefined) {
+            result += alphabet[((second & 15) << 2) | (third === undefined ? 0 : third >> 6)];
+        }
+        if (third !== undefined)
+            result += alphabet[third & 63];
+    }
+    return result;
+}
+function validateTokens(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const tokens = value;
+    return (typeof tokens.accessToken === 'string' &&
+        typeof tokens.expiresAt === 'number' &&
+        (tokens.refreshToken === undefined || typeof tokens.refreshToken === 'string') &&
+        (tokens.idToken === undefined || typeof tokens.idToken === 'string'));
+}
+function validateUser(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const user = value;
+    return (typeof user.id === 'string' &&
+        typeof user.email === 'string' &&
+        typeof user.name === 'string');
+}
+function createInMemoryGoogleTokenStore() {
+    let storedTokens = null;
+    let storedUser = null;
+    return {
+        getTokens: async () => storedTokens,
+        setTokens: async (tokens) => {
+            storedTokens = tokens;
+        },
+        removeTokens: async () => {
+            storedTokens = null;
+        },
+        getUser: async () => storedUser,
+        setUser: async (user) => {
+            storedUser = user;
+        },
+    };
+}
+function createGoogleAuthTokenStore(storage, prefix = 'local-lite-google-auth') {
+    const tokensKey = `${prefix}-tokens`;
+    const userKey = `${prefix}-user`;
+    return {
+        getTokens: async () => {
+            const raw = await storage.getItem(tokensKey);
+            return validateTokens(raw) ? raw : null;
+        },
+        setTokens: tokens => storage.setItem(tokensKey, tokens),
+        removeTokens: () => storage.removeItem(tokensKey),
+        getUser: async () => {
+            const raw = await storage.getItem(userKey);
+            return validateUser(raw) ? raw : null;
+        },
+        setUser: async (user) => {
+            if (user) {
+                await storage.setItem(userKey, user);
+            }
+            else {
+                await storage.removeItem(userKey);
+            }
+        },
+    };
+}
+async function parseTokenResponse(response) {
+    try {
+        return (await response.json());
+    }
+    catch {
+        throw new Error(`Google OAuth request failed (${response.status}).`);
+    }
+}
+function throwOAuthError(payload, status) {
+    throw new Error(payload.error_description ||
+        payload.error ||
+        `Google OAuth request failed (${status}).`);
+}
+class GoogleAuthClient {
+    options;
+    tokenStore;
+    fetcher;
+    listeners = new Set();
+    currentUser = null;
+    constructor(options) {
+        this.options = options;
+        if (!options.clientId?.trim()) {
+            throw new Error('Google OAuth client ID is required.');
+        }
+        if (!options.redirectUri?.trim()) {
+            throw new Error('Google OAuth redirect URI is required.');
+        }
+        this.fetcher = options.fetch ?? fetch;
+        if (options.tokenStore) {
+            this.tokenStore = options.tokenStore;
+        }
+        else if (options.storage) {
+            this.tokenStore = createGoogleAuthTokenStore(options.storage);
+        }
+        else {
+            this.tokenStore = createInMemoryGoogleTokenStore();
+        }
+    }
+    onAuthStateChange(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    notify(user) {
+        this.currentUser = user;
+        for (const listener of this.listeners) {
+            try {
+                listener(user);
+            }
+            catch (err) {
+                console.error('Error in GoogleAuthClient auth listener:', err);
+            }
+        }
+    }
+    async signIn() {
+        const randomBytes = this.options.randomBytes ?? secureRandomBytes;
+        const verifierBytes = randomBytes(32);
+        const stateBytes = randomBytes(32);
+        if (verifierBytes.length !== 32 || stateBytes.length !== 32) {
+            throw new Error('The randomBytes provider returned an invalid number of bytes.');
+        }
+        const codeVerifier = base64UrlEncode(verifierBytes);
+        const codeChallenge = base64UrlEncode((0, sha2_js_1.sha256)((0, utils_js_1.utf8ToBytes)(codeVerifier)));
+        const state = base64UrlEncode(stateBytes);
+        const scopes = this.options.scopes && this.options.scopes.length > 0
+            ? this.options.scopes
+            : exports.DEFAULT_GOOGLE_AUTH_SCOPES;
+        const authorizationParams = new URLSearchParams({
+            client_id: this.options.clientId,
+            redirect_uri: this.options.redirectUri,
+            response_type: 'code',
+            scope: scopes.join(' '),
+            access_type: this.options.accessType ?? 'offline',
+            prompt: this.options.prompt ?? 'select_account',
+            code_challenge: codeChallenge,
+            code_challenge_method: 'S256',
+            state,
+        });
+        const authorization = await this.options.authorize({
+            authorizationUrl: `${exports.GOOGLE_AUTHORIZATION_ENDPOINT}?${authorizationParams.toString()}`,
+            redirectUri: this.options.redirectUri,
+            state,
+        });
+        if (!authorization) {
+            return null;
+        }
+        if (authorization.state !== state) {
+            throw new Error('Google OAuth state validation failed. Please try connecting again.');
+        }
+        if (!authorization.code) {
+            throw new Error('Google OAuth did not return an authorization code.');
+        }
+        const response = await this.fetcher(exports.GOOGLE_TOKEN_ENDPOINT, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: new URLSearchParams({
+                client_id: this.options.clientId,
+                code: authorization.code,
+                code_verifier: codeVerifier,
+                grant_type: 'authorization_code',
+                redirect_uri: this.options.redirectUri,
+            }).toString(),
+        });
+        const payload = await parseTokenResponse(response);
+        if (!response.ok) {
+            throwOAuthError(payload, response.status);
+        }
+        if (!payload.access_token) {
+            throw new Error('Google OAuth did not return an access token.');
+        }
+        const priorTokens = await this.tokenStore.getTokens();
+        const storedTokens = {
+            accessToken: payload.access_token,
+            refreshToken: payload.refresh_token ?? priorTokens?.refreshToken,
+            idToken: payload.id_token ?? priorTokens?.idToken,
+            expiresAt: Date.now() + (payload.expires_in ?? 3600) * 1000,
+            tokenType: payload.token_type,
+            scope: payload.scope,
+        };
+        await this.tokenStore.setTokens(storedTokens);
+        const user = await this.fetchUserProfile(storedTokens.accessToken);
+        if (this.tokenStore.setUser) {
+            await this.tokenStore.setUser(user);
+        }
+        this.notify(user);
+        return user;
+    }
+    async signOut() {
+        await this.tokenStore.removeTokens();
+        if (this.tokenStore.setUser) {
+            await this.tokenStore.setUser(null);
+        }
+        this.notify(null);
+    }
+    async isSignedIn() {
+        const tokens = await this.tokenStore.getTokens();
+        return validateTokens(tokens);
+    }
+    async getUser() {
+        if (this.currentUser) {
+            return this.currentUser;
+        }
+        if (this.tokenStore.getUser) {
+            const cached = await this.tokenStore.getUser();
+            if (cached) {
+                this.currentUser = cached;
+                return cached;
+            }
+        }
+        const tokens = await this.tokenStore.getTokens();
+        if (!validateTokens(tokens)) {
+            return null;
+        }
+        try {
+            const accessToken = await this.getValidAccessToken();
+            const user = await this.fetchUserProfile(accessToken);
+            if (this.tokenStore.setUser) {
+                await this.tokenStore.setUser(user);
+            }
+            this.currentUser = user;
+            return user;
+        }
+        catch {
+            return null;
+        }
+    }
+    async getValidAccessToken() {
+        const tokens = await this.tokenStore.getTokens();
+        if (!validateTokens(tokens)) {
+            throw new Error('No Google account signed in. Please sign in first.');
+        }
+        if (tokens.expiresAt > Date.now() + 60_000) {
+            return tokens.accessToken;
+        }
+        if (!tokens.refreshToken) {
+            throw new Error('Your Google sign-in session expired. Please sign in again.');
+        }
+        const response = await this.fetcher(exports.GOOGLE_TOKEN_ENDPOINT, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: new URLSearchParams({
+                client_id: this.options.clientId,
+                grant_type: 'refresh_token',
+                refresh_token: tokens.refreshToken,
+            }).toString(),
+        });
+        const payload = await parseTokenResponse(response);
+        if (!response.ok) {
+            throwOAuthError(payload, response.status);
+        }
+        if (!payload.access_token) {
+            throw new Error('Google OAuth token refresh did not return an access token.');
+        }
+        const updatedTokens = {
+            accessToken: payload.access_token,
+            refreshToken: payload.refresh_token ?? tokens.refreshToken,
+            idToken: payload.id_token ?? tokens.idToken,
+            expiresAt: Date.now() + (payload.expires_in ?? 3600) * 1000,
+            tokenType: payload.token_type ?? tokens.tokenType,
+            scope: payload.scope ?? tokens.scope,
+        };
+        await this.tokenStore.setTokens(updatedTokens);
+        return updatedTokens.accessToken;
+    }
+    async fetchUserProfile(accessToken) {
+        const res = await this.fetcher(exports.GOOGLE_USERINFO_ENDPOINT, {
+            headers: { Authorization: `Bearer ${accessToken}` },
+        });
+        if (!res.ok) {
+            throw new Error(`Failed to fetch Google user profile (${res.status}).`);
+        }
+        const raw = (await res.json());
+        return {
+            id: raw.sub,
+            email: raw.email,
+            emailVerified: Boolean(raw.email_verified),
+            name: raw.name || raw.email || 'Google User',
+            givenName: raw.given_name,
+            familyName: raw.family_name,
+            picture: raw.picture,
+            locale: raw.locale,
+        };
+    }
+    createDriveBackupStorage() {
+        return new cloud_storage_js_1.GoogleDriveBackupStorage(() => this.getValidAccessToken(), this.fetcher);
+    }
+}
+exports.GoogleAuthClient = GoogleAuthClient;

package/dist/auth/index.d.ts

@@ -0,0 +1 @@
+export * from './google.js';

package/dist/auth/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./google.js"), exports);

package/dist/config/index.d.ts

@@ -13,7 +13,7 @@ export { NodeSQLiteAdapter } from '../adapters/local/node-sqlite.js';
 export { SupabaseRemoteAdapter } from '../adapters/remote/supabase.js';
 export { ConvexRemoteAdapter } from '../adapters/remote/convex.js';
 export { FirestoreRemoteAdapter } from '../adapters/remote/firestore.js';
-export { MemoryDemoRemoteAdapter } from '../adapters/remote/demo.js';
+export { MemoryDemoRemoteAdapter, NoopRemoteAdapter } from '../adapters/remote/demo.js';
 /**
  * Type-safe configuration helper function (similar to defineConfig in Vite/Tailwind).
  */

package/dist/config/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MemoryDemoRemoteAdapter = exports.FirestoreRemoteAdapter = exports.ConvexRemoteAdapter = exports.SupabaseRemoteAdapter = exports.NodeSQLiteAdapter = exports.SqlJsAdapter = exports.LibSQLAdapter = exports.BetterSQLite3Adapter = exports.OpSQLiteAdapter = exports.ExpoSQLiteAdapter = exports.LocalFirstClient = exports.resolveRemoteAdapter = exports.resolveLocalAdapter = void 0;
+exports.NoopRemoteAdapter = exports.MemoryDemoRemoteAdapter = exports.FirestoreRemoteAdapter = exports.ConvexRemoteAdapter = exports.SupabaseRemoteAdapter = exports.NodeSQLiteAdapter = exports.SqlJsAdapter = exports.LibSQLAdapter = exports.BetterSQLite3Adapter = exports.OpSQLiteAdapter = exports.ExpoSQLiteAdapter = exports.LocalFirstClient = exports.resolveRemoteAdapter = exports.resolveLocalAdapter = void 0;
 exports.defineSyncConfig = defineSyncConfig;
 exports.createSyncClient = createSyncClient;
 const client_js_1 = require("../core/client.js");
@@ -51,6 +51,7 @@ var firestore_js_1 = require("../adapters/remote/firestore.js");
 Object.defineProperty(exports, "FirestoreRemoteAdapter", { enumerable: true, get: function () { return firestore_js_1.FirestoreRemoteAdapter; } });
 var demo_js_1 = require("../adapters/remote/demo.js");
 Object.defineProperty(exports, "MemoryDemoRemoteAdapter", { enumerable: true, get: function () { return demo_js_1.MemoryDemoRemoteAdapter; } });
+Object.defineProperty(exports, "NoopRemoteAdapter", { enumerable: true, get: function () { return demo_js_1.NoopRemoteAdapter; } });
 /**
  * Type-safe configuration helper function (similar to defineConfig in Vite/Tailwind).
  */

package/dist/config/resolve-local.js

@@ -7,6 +7,8 @@ const better_sqlite3_js_1 = require("../adapters/local/better-sqlite3.js");
 const libsql_js_1 = require("../adapters/local/libsql.js");
 const sql_js_js_1 = require("../adapters/local/sql-js.js");
 const node_sqlite_js_1 = require("../adapters/local/node-sqlite.js");
+const dynamic_js_1 = require("../utils/dynamic.js");
+const EXPO_SQLITE_PKG = ['expo', 'sqlite'].join('-');
 /**
  * Resolves or instantiates the appropriate LocalDBAdapter based on the provided configuration.
  * Auto-detects Expo SQLite, OP-SQLite, better-sqlite3, LibSQL, sql.js, and Node.js built-in sqlite.
@@ -51,19 +53,11 @@ async function resolveLocalAdapter(config) {
     // 9. Auto-open by name using expo-sqlite if available
     if (typeof rawDb === 'string' || config.databaseName) {
         const dbName = typeof rawDb === 'string' ? rawDb : (config.databaseName ?? 'local_lite.db');
-        let expoSqlite;
-        try {
-            if (typeof require === 'function') {
-                expoSqlite = require('expo-sqlite');
-            }
-        }
-        catch {
-            // ignore
+        let expoSqlite = (0, dynamic_js_1.safeDynamicRequire)(EXPO_SQLITE_PKG);
+        if (!expoSqlite) {
+            expoSqlite = await (0, dynamic_js_1.safeDynamicImport)(EXPO_SQLITE_PKG);
         }
         try {
-            if (!expoSqlite) {
-                expoSqlite = await import('expo-sqlite');
-            }
             if (expoSqlite && typeof expoSqlite.openDatabaseAsync === 'function') {
                 const expoDb = await expoSqlite.openDatabaseAsync(dbName);
                 return new expo_sqlite_js_1.ExpoSQLiteAdapter(expoDb);

package/dist/config/resolve-remote.d.ts

@@ -2,6 +2,6 @@ import { RemoteDBAdapter } from '../adapters/remote/index.js';
 import { LocalLiteConfig } from './types.js';
 /**
  * Resolves or instantiates the appropriate RemoteDBAdapter based on the provided configuration.
- * Supports Supabase, Convex, Firebase / Firestore, in-memory demo adapter, or custom adapters.
+ * Supports Supabase, Convex, Firebase / Firestore, in-memory demo adapter, local-only mode, or custom adapters.
  */
 export declare function resolveRemoteAdapter(config: LocalLiteConfig): Promise<RemoteDBAdapter>;

package/dist/config/resolve-remote.js

@@ -5,9 +5,13 @@ const supabase_js_1 = require("../adapters/remote/supabase.js");
 const convex_js_1 = require("../adapters/remote/convex.js");
 const firestore_js_1 = require("../adapters/remote/firestore.js");
 const demo_js_1 = require("../adapters/remote/demo.js");
+const dynamic_js_1 = require("../utils/dynamic.js");
+// Construct dynamically to prevent Metro, Webpack, and Rollup from treating
+// optional peer dependencies as unconditional build-time dependencies.
+const SUPABASE_PKG = ['@supabase', 'supabase-js'].join('/');
 /**
  * Resolves or instantiates the appropriate RemoteDBAdapter based on the provided configuration.
- * Supports Supabase, Convex, Firebase / Firestore, in-memory demo adapter, or custom adapters.
+ * Supports Supabase, Convex, Firebase / Firestore, in-memory demo adapter, local-only mode, or custom adapters.
  */
 async function resolveRemoteAdapter(config) {
     // 1. Explicit custom remote adapter
@@ -53,34 +57,27 @@ async function resolveRemoteAdapter(config) {
     }
     // 5. Supabase with URL + anonKey (lazy dynamic import)
     if (config.supabase?.url && config.supabase?.anonKey) {
-        let supabaseModule;
-        // In CommonJS / React Native Metro environments, synchronous require avoids async chunk split failure
-        try {
-            if (typeof require === 'function') {
-                supabaseModule = require('@supabase/supabase-js');
-            }
-        }
-        catch {
-            // ignore
-        }
+        let supabaseModule = (0, dynamic_js_1.safeDynamicRequire)(SUPABASE_PKG);
         if (!supabaseModule && typeof globalThis?.supabase?.createClient === 'function') {
             supabaseModule = globalThis.supabase;
         }
         if (!supabaseModule) {
-            try {
-                supabaseModule = await import('@supabase/supabase-js');
-            }
-            catch {
-                throw new Error('To initialize Supabase from url and anonKey, please install @supabase/supabase-js or provide a pre-configured client to config.supabase.client');
-            }
+            supabaseModule = await (0, dynamic_js_1.safeDynamicImport)(SUPABASE_PKG);
+        }
+        if (!supabaseModule) {
+            throw new Error('To initialize Supabase from url and anonKey, please install @supabase/supabase-js or provide a pre-configured client to config.supabase.client');
         }
         const createClientFn = supabaseModule.createClient || supabaseModule.default?.createClient;
         const supabaseClient = createClientFn(config.supabase.url, config.supabase.anonKey);
         return new supabase_js_1.SupabaseRemoteAdapter(supabaseClient, getSupabaseOptions());
     }
-    // 6. Explicitly selected demo backend only; never acknowledge writes into a temporary backend implicitly.
+    // 6. Local-only standalone mode
+    if (config.localOnly === true) {
+        return new demo_js_1.NoopRemoteAdapter();
+    }
+    // 7. Explicitly selected demo backend only; never acknowledge writes into a temporary backend implicitly.
     if (config.inMemoryRemote === true) {
         return new demo_js_1.MemoryDemoRemoteAdapter(300);
     }
-    throw new Error('No remote adapter configured. Please specify config.supabase, config.convex, config.firebase, or config.remote. For demos only, explicitly set config.inMemoryRemote: true.');
+    throw new Error('No remote adapter configured. Please specify config.supabase, config.convex, config.firebase, or config.remote. For local-only use, set config.localOnly: true. For demos, set config.inMemoryRemote: true.');
 }

package/dist/config/types.d.ts

@@ -120,6 +120,13 @@ export interface LocalLiteConfig {
      * Default: false
      */
     inMemoryRemote?: boolean;
+    /**
+     * Run purely local-only without requiring any remote cloud backend.
+     * Disables cloud sync pushes and pulls while preserving all local SQLite features,
+     * schema management, outbox tracking, and transactions.
+     * Default: false
+     */
+    localOnly?: boolean;
     /**
      * Conflict resolution strategy. Default: 'last-write-wins'
      */

package/dist/core/sync-worker.js

@@ -7,6 +7,7 @@ const outbox_store_js_1 = require("./outbox-store.js");
 const meta_store_js_1 = require("./meta-store.js");
 const table_manager_js_1 = require("./table-manager.js");
 const logger_js_1 = require("../utils/logger.js");
+const REACT_NATIVE_PKG = ['react', 'native'].join('-');
 /** Maximum outbox records sent per push cycle. */
 const PUSH_BATCH_SIZE = 50;
 /** Maximum incoming delta changes applied in a single database transaction. */

package/dist/index.d.ts

@@ -18,3 +18,5 @@ export * from './utils/uuid.js';
 export * from './utils/sql.js';
 export * from './utils/logger.js';
 export * from './schema/index.js';
+export * from './auth/index.js';
+export * from './backups/index.js';

package/dist/index.js

@@ -33,3 +33,5 @@ __exportStar(require("./utils/uuid.js"), exports);
 __exportStar(require("./utils/sql.js"), exports);
 __exportStar(require("./utils/logger.js"), exports);
 __exportStar(require("./schema/index.js"), exports);
+__exportStar(require("./auth/index.js"), exports);
+__exportStar(require("./backups/index.js"), exports);

package/dist/react/auth.d.ts

@@ -0,0 +1,11 @@
+import type { GoogleAuthClient, GoogleUser } from '../auth/google.js';
+export interface UseGoogleAuthResult {
+    user: GoogleUser | null;
+    isSignedIn: boolean;
+    loading: boolean;
+    error: Error | null;
+    signIn: () => Promise<GoogleUser | null>;
+    signOut: () => Promise<void>;
+    refetchUser: () => Promise<GoogleUser | null>;
+}
+export declare function useGoogleAuth(client: GoogleAuthClient | null | undefined): UseGoogleAuthResult;

package/dist/react/auth.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useGoogleAuth = useGoogleAuth;
+const react_1 = require("react");
+function useGoogleAuth(client) {
+    const [user, setUser] = (0, react_1.useState)(null);
+    const [loading, setLoading] = (0, react_1.useState)(true);
+    const [error, setError] = (0, react_1.useState)(null);
+    (0, react_1.useEffect)(() => {
+        if (!client) {
+            setUser(null);
+            setLoading(false);
+            return;
+        }
+        let isMounted = true;
+        client
+            .getUser()
+            .then(currentUser => {
+            if (isMounted) {
+                setUser(currentUser);
+                setLoading(false);
+            }
+        })
+            .catch(err => {
+            if (isMounted) {
+                setError(err instanceof Error ? err : new Error(String(err)));
+                setLoading(false);
+            }
+        });
+        const unsubscribe = client.onAuthStateChange(updatedUser => {
+            if (isMounted) {
+                setUser(updatedUser);
+            }
+        });
+        return () => {
+            isMounted = false;
+            unsubscribe();
+        };
+    }, [client]);
+    const signIn = (0, react_1.useCallback)(async () => {
+        if (!client)
+            throw new Error('GoogleAuthClient is not initialized.');
+        setError(null);
+        setLoading(true);
+        try {
+            const res = await client.signIn();
+            setUser(res);
+            return res;
+        }
+        catch (err) {
+            const e = err instanceof Error ? err : new Error(String(err));
+            setError(e);
+            throw e;
+        }
+        finally {
+            setLoading(false);
+        }
+    }, [client]);
+    const signOut = (0, react_1.useCallback)(async () => {
+        if (!client)
+            return;
+        setError(null);
+        setLoading(true);
+        try {
+            await client.signOut();
+            setUser(null);
+        }
+        catch (err) {
+            const e = err instanceof Error ? err : new Error(String(err));
+            setError(e);
+            throw e;
+        }
+        finally {
+            setLoading(false);
+        }
+    }, [client]);
+    const refetchUser = (0, react_1.useCallback)(async () => {
+        if (!client)
+            return null;
+        const res = await client.getUser();
+        setUser(res);
+        return res;
+    }, [client]);
+    return {
+        user,
+        isSignedIn: Boolean(user),
+        loading,
+        error,
+        signIn,
+        signOut,
+        refetchUser,
+    };
+}

package/dist/react/index.d.ts

@@ -117,3 +117,4 @@ export * from './theme.js';
 export * from './BenchmarkModal.js';
 export { SyncInspector, SyncIndicator } from './SyncInspector.js';
 export type { SyncInspectorProps, SyncIndicatorProps } from './SyncInspector.js';
+export * from './auth.js';

package/dist/react/index.js

@@ -594,3 +594,4 @@ __exportStar(require("./BenchmarkModal.js"), exports);
 var SyncInspector_js_1 = require("./SyncInspector.js");
 Object.defineProperty(exports, "SyncInspector", { enumerable: true, get: function () { return SyncInspector_js_1.SyncInspector; } });
 Object.defineProperty(exports, "SyncIndicator", { enumerable: true, get: function () { return SyncInspector_js_1.SyncIndicator; } });
+__exportStar(require("./auth.js"), exports);

package/dist/utils/dynamic.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Safely loads an optional dependency at runtime without triggering
+ * ahead-of-time static analysis in bundlers like Metro, Webpack, or Rollup.
+ */
+export declare function safeDynamicRequire(pkgName: string): any;
+export declare function safeDynamicImport(pkgName: string): Promise<any>;

package/dist/utils/dynamic.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.safeDynamicRequire = safeDynamicRequire;
+exports.safeDynamicImport = safeDynamicImport;
+/**
+ * Safely loads an optional dependency at runtime without triggering
+ * ahead-of-time static analysis in bundlers like Metro, Webpack, or Rollup.
+ */
+function safeDynamicRequire(pkgName) {
+    try {
+        const req = typeof __non_webpack_require__ !== 'undefined'
+            ? __non_webpack_require__
+            : typeof require === 'function'
+                ? require
+                : undefined;
+        return req ? req(pkgName) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function safeDynamicImport(pkgName) {
+    try {
+        // Metro's AST worker rejects `import(dynamicVariable)` with "Invalid call at line ...: import(...)".
+        // Evaluating via new Function bypasses the bundler AST parser entirely while working in Node/browser.
+        const dynamicImport = new Function('specifier', 'return import(specifier);');
+        return await dynamicImport(pkgName);
+    }
+    catch {
+        return undefined;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "local-lite",
-  "version": "0.0.10",
+  "version": "0.0.12",
   "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",
@@ -46,6 +46,11 @@
       "import": "./dist/adapters/remote/firestore.js",
       "default": "./dist/adapters/remote/firestore.js"
     },
+    "./auth": {
+      "types": "./dist/auth/index.d.ts",
+      "import": "./dist/auth/index.js",
+      "default": "./dist/auth/index.js"
+    },
     "./backups": {
       "types": "./dist/backups/index.d.ts",
       "import": "./dist/backups/index.js",