local-lite 0.0.20 → 0.0.22

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/dist/storage/convex.d.ts

@@ -0,0 +1,43 @@
+import { BlobRecord, RemoteStorageUploader } from './types.js';
+export interface ConvexStorageUploaderOptions {
+    /**
+     * Name or function reference for Convex mutation that generates an upload URL.
+     * Default: 'sync:generateUploadUrl' (or can be `api.files.generateUploadUrl`)
+     */
+    uploadMutation?: any;
+    /**
+     * Optional arguments passed to uploadMutation.
+     */
+    uploadMutationArgs?: Record<string, any> | ((blob: BlobRecord) => Record<string, any>);
+    /**
+     * Optional name or function reference for Convex query that gets a serving URL from a storageId.
+     * e.g. `api.files.getUrl`
+     */
+    getUrlQuery?: any;
+    /**
+     * Optional name or function reference for Convex mutation called after file is uploaded,
+     * allowing you to persist metadata or link the storageId to your Convex schema.
+     */
+    saveFileMutation?: any;
+    /**
+     * Optional name or function reference for Convex mutation called when a file is deleted.
+     */
+    deleteMutation?: any;
+    /**
+     * Custom path / metadata transformation.
+     */
+    pathTransform?: (key: string, blob?: BlobRecord) => string;
+    /**
+     * Custom fetch function (defaults to global fetch).
+     */
+    fetchFn?: typeof fetch;
+}
+export interface ConvexStorageUploaderInstance extends RemoteStorageUploader {
+    getUrl(storageId: string): Promise<string | null>;
+    getDownloadUrl(keyOrStorageId: string): Promise<string>;
+    delete(storageIdOrKey: string): Promise<void>;
+}
+/**
+ * Creates a RemoteStorageUploader that syncs binary files to Convex File Storage.
+ */
+export declare function createConvexStorageUploader(convex: any, options?: ConvexStorageUploaderOptions): ConvexStorageUploaderInstance;

package/dist/storage/convex.js

@@ -0,0 +1,112 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createConvexStorageUploader = createConvexStorageUploader;
+/**
+ * Creates a RemoteStorageUploader that syncs binary files to Convex File Storage.
+ */
+function createConvexStorageUploader(convex, options = {}) {
+    const uploadMutation = options.uploadMutation ?? 'sync:generateUploadUrl';
+    const fetchFn = options.fetchFn ?? (typeof fetch !== 'undefined' ? fetch : undefined);
+    if (!convex) {
+        throw new Error('Convex client must be provided to createConvexStorageUploader.');
+    }
+    // Cache of key/storageId mapping
+    const storageIdMap = new Map();
+    return {
+        async upload(blob, data) {
+            if (!fetchFn) {
+                throw new Error('Fetch API is not available in the current environment.');
+            }
+            // 1. Generate upload URL via mutation
+            const mutationArgs = typeof options.uploadMutationArgs === 'function'
+                ? options.uploadMutationArgs(blob)
+                : options.uploadMutationArgs || {};
+            let postUrl;
+            if (typeof convex.mutation === 'function') {
+                postUrl = await convex.mutation(uploadMutation, mutationArgs);
+            }
+            else if (typeof convex === 'function') {
+                postUrl = await convex(uploadMutation, mutationArgs);
+            }
+            else {
+                throw new Error('Convex client must support .mutation() method.');
+            }
+            if (!postUrl || typeof postUrl !== 'string') {
+                throw new Error(`Convex generateUploadUrl mutation did not return a valid URL: ${JSON.stringify(postUrl)}`);
+            }
+            // 2. POST binary data to upload URL
+            const response = await fetchFn(postUrl, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': blob.mimeType || 'application/octet-stream',
+                },
+                body: data,
+            });
+            if (!response.ok) {
+                throw new Error(`Convex file upload failed with status ${response.status}: ${response.statusText}`);
+            }
+            const jsonResult = await response.json();
+            const storageId = jsonResult?.storageId || jsonResult?.id || jsonResult;
+            if (!storageId) {
+                throw new Error('Convex upload response did not contain a valid storageId.');
+            }
+            storageIdMap.set(blob.key, storageId);
+            // 3. Optional: save file record in Convex schema
+            if (options.saveFileMutation) {
+                const filePayload = {
+                    storageId,
+                    key: blob.key,
+                    name: blob.name,
+                    mimeType: blob.mimeType,
+                    size: blob.size,
+                    sha256: blob.sha256,
+                    metadata: blob.metadata,
+                };
+                if (typeof convex.mutation === 'function') {
+                    await convex.mutation(options.saveFileMutation, filePayload);
+                }
+            }
+            // 4. Resolve serving URL if query is provided
+            let remoteUrl = storageId;
+            if (options.getUrlQuery) {
+                const resolved = await this.getUrl(storageId);
+                if (resolved) {
+                    remoteUrl = resolved;
+                }
+            }
+            return {
+                remoteUrl,
+                storageId,
+                metadata: { storageId },
+            };
+        },
+        async getUrl(storageId) {
+            if (!options.getUrlQuery) {
+                return null;
+            }
+            try {
+                if (typeof convex.query === 'function') {
+                    return await convex.query(options.getUrlQuery, { storageId });
+                }
+                return null;
+            }
+            catch {
+                return null;
+            }
+        },
+        async getDownloadUrl(keyOrStorageId) {
+            const storageId = storageIdMap.get(keyOrStorageId) || keyOrStorageId;
+            const url = await this.getUrl(storageId);
+            return url || storageId;
+        },
+        async delete(storageIdOrKey) {
+            const storageId = storageIdMap.get(storageIdOrKey) || storageIdOrKey;
+            storageIdMap.delete(storageIdOrKey);
+            if (options.deleteMutation) {
+                if (typeof convex.mutation === 'function') {
+                    await convex.mutation(options.deleteMutation, { storageId });
+                }
+            }
+        },
+    };
+}

package/dist/storage/expo.d.ts

@@ -0,0 +1,132 @@
+import { FileDriver } from './types.js';
+export interface ExpoFileSystemModule {
+    File?: any;
+    Directory?: any;
+    Paths?: any;
+    documentDirectory?: string | null;
+    cacheDirectory?: string | null;
+    EncodingType?: {
+        UTF8: string;
+        Base64: string;
+    };
+    getInfoAsync?(fileUri: string, options?: {
+        md5?: boolean;
+        size?: boolean;
+    }): Promise<{
+        exists: boolean;
+        isDirectory?: boolean;
+        size?: number;
+        uri?: string;
+    }>;
+    writeAsStringAsync?(fileUri: string, contents: string, options?: {
+        encoding?: string;
+    }): Promise<void>;
+    readAsStringAsync?(fileUri: string, options?: {
+        encoding?: string;
+        length?: number;
+        position?: number;
+    }): Promise<string>;
+    makeDirectoryAsync?(fileUri: string, options?: {
+        intermediates?: boolean;
+    }): Promise<void>;
+    deleteAsync?(fileUri: string, options?: {
+        idempotent?: boolean;
+    }): Promise<void>;
+    copyAsync?(options: {
+        from: string;
+        to: string;
+    }): Promise<void>;
+    moveAsync?(options: {
+        from: string;
+        to: string;
+    }): Promise<void>;
+    downloadAsync?(url: string, fileUri: string, options?: {
+        md5?: boolean;
+        headers?: Record<string, string>;
+        sessionType?: any;
+    }): Promise<{
+        uri: string;
+        status: number;
+        headers: Record<string, string>;
+        md5?: string;
+    }>;
+}
+export interface ExpoFileDriverOptions {
+    /**
+     * The modern `File` class from `expo-file-system` (SDK >57/58).
+     * e.g. `import { File } from 'expo-file-system'`
+     */
+    File?: any;
+    /**
+     * The modern `Directory` class from `expo-file-system`.
+     * e.g. `import { Directory } from 'expo-file-system'`
+     */
+    Directory?: any;
+    /**
+     * The modern `Paths` object from `expo-file-system`.
+     * e.g. `import { Paths } from 'expo-file-system'`
+     */
+    Paths?: any;
+    /**
+     * The `expo-file-system` module instance.
+     * e.g. `import * as FileSystem from 'expo-file-system'`
+     */
+    fileSystem?: ExpoFileSystemModule | any;
+    /**
+     * Base directory path or `Directory` instance for storing files.
+     * Defaults to: `new Directory(Paths.document, 'local-lite-blobs')`
+     */
+    baseDir?: any;
+    /**
+     * Whether to store files in `Paths.cache` instead of `Paths.document`.
+     * Files in cache directory may be cleared by the OS if device storage runs low.
+     * Default: false
+     */
+    useCache?: boolean;
+}
+/**
+ * Universal binary <-> base64 utilities compatible with Node, Browser, and React Native (Hermes).
+ */
+export declare function bytesToBase64(bytes: Uint8Array): string;
+export declare function base64ToBytes(base64: string): Uint8Array;
+/**
+ * FileDriver implementation for Expo / React Native environments.
+ * Uses modern Expo (>57/58) `File`, `Directory`, and `Paths` APIs when available,
+ * with seamless fallback for legacy `expo-file-system` environments.
+ */
+export declare class ExpoFileDriver implements FileDriver {
+    private FileClass?;
+    private DirectoryClass?;
+    private PathsObj?;
+    private legacyFs?;
+    private baseDirOption?;
+    private useCache;
+    private resolvedBaseDir;
+    private resolvedBaseDirPath;
+    private ensuredDirs;
+    constructor(options?: ExpoFileDriverOptions);
+    private resolveClasses;
+    private getBaseDirectory;
+    /**
+     * Resolves a key to a modern Expo `File` instance (if File class is available)
+     * or a string URI path.
+     */
+    private resolveFileOrUri;
+    resolveUri(key: string): Promise<string>;
+    getUri(key: string): Promise<string>;
+    private ensureDirectory;
+    write(key: string, data: Uint8Array): Promise<string>;
+    read(key: string): Promise<Uint8Array | null>;
+    delete(key: string): Promise<void>;
+    exists(key: string): Promise<boolean>;
+    getSize(key: string): Promise<number>;
+    /**
+     * Fast file copy from an existing local URI (e.g. from expo-image-picker or expo-document-picker)
+     * into local-lite managed storage without reading entire file contents into memory.
+     */
+    copyFrom(sourceUri: string, key: string): Promise<string>;
+    /**
+     * Downloads a remote URL directly to the destination key on disk.
+     */
+    downloadFrom(remoteUrl: string, key: string): Promise<string>;
+}