local-lite 0.0.19 → 0.0.21

package/dist/keys/types.d.ts

@@ -0,0 +1,95 @@
+export interface GenerateApiKeyOptions {
+    /**
+     * Prefix for the API key (e.g. 'prop', 'sk_live', 'pk_test').
+     * Default: 'key'
+     */
+    prefix?: string;
+    /**
+     * Number of random entropy bytes (higher is more secure).
+     * Default: 24 bytes (192 bits of entropy)
+     */
+    byteLength?: number;
+    /**
+     * Whether to embed a 4-byte checksum at the end of the key for instant validation.
+     * Default: true
+     */
+    withChecksum?: boolean;
+    /**
+     * Human-readable label or description for this key.
+     */
+    name?: string;
+    /**
+     * Arbitrary metadata (e.g. { businessId, scopes, ownerId }).
+     */
+    metadata?: Record<string, any>;
+    /**
+     * Expiration window in milliseconds from creation time.
+     */
+    expiresInMs?: number;
+    /**
+     * Explicit expiration timestamp in milliseconds.
+     */
+    expiresAt?: number;
+}
+export interface GeneratedApiKey {
+    /**
+     * The raw plaintext key string to return to the user (only shown once!).
+     * e.g. "prop_a7F9x..._c4b2"
+     */
+    key: string;
+    /**
+     * Cryptographic SHA-256 hash of the key for secure database storage.
+     */
+    keyHash: string;
+    /**
+     * Key prefix.
+     */
+    prefix: string;
+    /**
+     * Masked display string safe to show in UI (e.g. "prop_...c4b2").
+     */
+    display: string;
+}
+export interface ApiKeyRecord {
+    id: string;
+    name: string;
+    prefix: string;
+    display: string;
+    keyHash: string;
+    metadata?: Record<string, any>;
+    createdAt: number;
+    expiresAt?: number | null;
+    lastUsedAt?: number | null;
+    revoked: boolean;
+    revokedAt?: number | null;
+}
+export type KeyVerificationStatus = 'VALID' | 'INVALID' | 'EXPIRED' | 'REVOKED' | 'MALFORMED';
+export interface VerifyStoredKeyResult {
+    valid: boolean;
+    status: KeyVerificationStatus;
+    record?: ApiKeyRecord;
+    error?: string;
+}
+export interface CreateSignedTokenOptions<T = Record<string, any>> {
+    payload: T;
+    secret: string;
+    expiresInMs?: number;
+    expiresAt?: number;
+    tokenId?: string;
+}
+export interface VerifySignedTokenResult<T = Record<string, any>> {
+    valid: boolean;
+    expired?: boolean;
+    payload?: T;
+    expiresAt?: number | null;
+    tokenId?: string;
+    error?: string;
+}
+export interface RenewSignedTokenOptions {
+    extendMs?: number;
+    newExpiresAt?: number;
+    secret?: string;
+}
+export interface ApiKeyManagerOptions {
+    tableName?: string;
+}

package/dist/keys/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/kv/index.d.ts

@@ -0,0 +1,3 @@
+export * from './types.js';
+export * from './store.js';
+export * from './manager.js';

package/dist/kv/index.js

@@ -0,0 +1,19 @@
+"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("./types.js"), exports);
+__exportStar(require("./store.js"), exports);
+__exportStar(require("./manager.js"), exports);

package/dist/kv/manager.d.ts

@@ -0,0 +1,52 @@
+import { DBExecutable } from '../core/schema-manager.js';
+import { EventEmitter } from '../reactive/event-emitter.js';
+import { KVRecord, KVSetOptions, KVSetSecretOptions, KVStoreOptions } from './types.js';
+export declare class KVManager {
+    private db;
+    private tableName;
+    private events?;
+    constructor(db: DBExecutable, eventsOrOptions?: EventEmitter | KVStoreOptions, options?: KVStoreOptions);
+    initialize(): Promise<void>;
+    /**
+     * Sets a value in the key-value store with optional TTL.
+     * Emits an event on the event emitter if configured.
+     */
+    set(key: string, value: any, options?: KVSetOptions): Promise<void>;
+    /**
+     * Retrieves the value for a key, returning defaultValue if not found or expired.
+     */
+    get<T = any>(key: string, defaultValue?: T): Promise<T | undefined>;
+    /**
+     * Retrieves the full KVRecord metadata for a key.
+     */
+    getRecord(key: string): Promise<KVRecord | null>;
+    /**
+     * Checks whether a non-expired key exists in the store.
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Removes a key from the store.
+     * Emits an event on the event emitter if configured.
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Lists all non-expired keys, optionally filtered by a prefix.
+     */
+    keys(prefix?: string): Promise<string[]>;
+    /**
+     * Clears all stored key-value pairs.
+     */
+    clear(): Promise<void>;
+    /**
+     * Stores an encrypted secret using AES-256-GCM + PBKDF2 passphrase encryption.
+     */
+    setSecret(key: string, secretValue: any, options: KVSetSecretOptions): Promise<void>;
+    /**
+     * Decrypts and retrieves a stored secret.
+     */
+    getSecret<T = any>(key: string, passphrase: string, defaultValue?: T): Promise<T | undefined>;
+    /**
+     * Purges all expired keys immediately.
+     */
+    pruneExpired(): Promise<number>;
+}

package/dist/kv/manager.js

@@ -0,0 +1,164 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KVManager = void 0;
+const encryption_js_1 = require("../backups/encryption.js");
+const signed_token_js_1 = require("../keys/signed-token.js");
+const store_js_1 = require("./store.js");
+class KVManager {
+    db;
+    tableName;
+    events;
+    constructor(db, eventsOrOptions, options) {
+        this.db = db;
+        let opts = {};
+        if (eventsOrOptions && typeof eventsOrOptions.emit === 'function') {
+            this.events = eventsOrOptions;
+            opts = options || {};
+        }
+        else if (eventsOrOptions) {
+            opts = eventsOrOptions;
+        }
+        this.tableName = opts.tableName ?? store_js_1.DEFAULT_KV_TABLE;
+    }
+    async initialize() {
+        await store_js_1.KVStore.ensureSchema(this.db, this.tableName);
+    }
+    /**
+     * Sets a value in the key-value store with optional TTL.
+     * Emits an event on the event emitter if configured.
+     */
+    async set(key, value, options = {}) {
+        const now = Date.now();
+        const expiresAt = options.expiresAt !== undefined
+            ? options.expiresAt
+            : options.ttlMs !== undefined
+                ? now + options.ttlMs
+                : null;
+        let type;
+        let valueStr;
+        if (typeof value === 'string') {
+            type = 'string';
+            valueStr = value;
+        }
+        else if (typeof value === 'number') {
+            type = 'number';
+            valueStr = String(value);
+        }
+        else if (typeof value === 'boolean') {
+            type = 'boolean';
+            valueStr = value ? '1' : '0';
+        }
+        else {
+            type = 'json';
+            valueStr = JSON.stringify(value ?? null);
+        }
+        await store_js_1.KVStore.set(this.db, this.tableName, key, valueStr, type, now, expiresAt);
+        this.events?.emit(this.tableName, { operation: 'SET', key, value });
+    }
+    /**
+     * Retrieves the value for a key, returning defaultValue if not found or expired.
+     */
+    async get(key, defaultValue) {
+        const record = await store_js_1.KVStore.get(this.db, this.tableName, key);
+        if (!record)
+            return defaultValue;
+        if (record.expiresAt && record.expiresAt <= Date.now()) {
+            // Lazy deletion of expired key
+            store_js_1.KVStore.delete(this.db, this.tableName, key).catch(() => { });
+            return defaultValue;
+        }
+        return record.value;
+    }
+    /**
+     * Retrieves the full KVRecord metadata for a key.
+     */
+    async getRecord(key) {
+        const record = await store_js_1.KVStore.get(this.db, this.tableName, key);
+        if (!record)
+            return null;
+        if (record.expiresAt && record.expiresAt <= Date.now()) {
+            store_js_1.KVStore.delete(this.db, this.tableName, key).catch(() => { });
+            return null;
+        }
+        return record;
+    }
+    /**
+     * Checks whether a non-expired key exists in the store.
+     */
+    async has(key) {
+        const val = await this.get(key);
+        return val !== undefined;
+    }
+    /**
+     * Removes a key from the store.
+     * Emits an event on the event emitter if configured.
+     */
+    async delete(key) {
+        await store_js_1.KVStore.delete(this.db, this.tableName, key);
+        this.events?.emit(this.tableName, { operation: 'DELETE', key });
+    }
+    /**
+     * Lists all non-expired keys, optionally filtered by a prefix.
+     */
+    async keys(prefix) {
+        return store_js_1.KVStore.listKeys(this.db, this.tableName, prefix);
+    }
+    /**
+     * Clears all stored key-value pairs.
+     */
+    async clear() {
+        await store_js_1.KVStore.clear(this.db, this.tableName);
+        this.events?.emit(this.tableName, { operation: 'CLEAR' });
+    }
+    /**
+     * Stores an encrypted secret using AES-256-GCM + PBKDF2 passphrase encryption.
+     */
+    async setSecret(key, secretValue, options) {
+        if (!options.passphrase) {
+            throw new Error('Passphrase is required to store encrypted secret.');
+        }
+        const strValue = typeof secretValue === 'string' ? secretValue : JSON.stringify(secretValue);
+        const plainBytes = new TextEncoder().encode(strValue);
+        const encryptedBytes = await (0, encryption_js_1.encryptBackupData)(plainBytes, options.passphrase);
+        const encryptedBase64 = (0, signed_token_js_1.base64UrlEncode)(encryptedBytes);
+        const now = Date.now();
+        const expiresAt = options.expiresAt !== undefined
+            ? options.expiresAt
+            : options.ttlMs !== undefined
+                ? now + options.ttlMs
+                : null;
+        await store_js_1.KVStore.set(this.db, this.tableName, key, encryptedBase64, 'encrypted', now, expiresAt);
+        this.events?.emit(this.tableName, { operation: 'SET_SECRET', key });
+    }
+    /**
+     * Decrypts and retrieves a stored secret.
+     */
+    async getSecret(key, passphrase, defaultValue) {
+        const record = await store_js_1.KVStore.get(this.db, this.tableName, key);
+        if (!record)
+            return defaultValue;
+        if (record.expiresAt && record.expiresAt <= Date.now()) {
+            store_js_1.KVStore.delete(this.db, this.tableName, key).catch(() => { });
+            return defaultValue;
+        }
+        if (record.type !== 'encrypted') {
+            return record.value;
+        }
+        const encryptedBytes = (0, signed_token_js_1.base64UrlDecode)(record.value);
+        const decryptedBytes = await (0, encryption_js_1.decryptBackupData)(encryptedBytes, passphrase);
+        const text = new TextDecoder().decode(decryptedBytes);
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    }
+    /**
+     * Purges all expired keys immediately.
+     */
+    async pruneExpired() {
+        return store_js_1.KVStore.pruneExpired(this.db, this.tableName);
+    }
+}
+exports.KVManager = KVManager;

package/dist/kv/store.d.ts

@@ -0,0 +1,13 @@
+import { DBExecutable } from '../core/schema-manager.js';
+import { KVRecord } from './types.js';
+export declare const DEFAULT_KV_TABLE = "_local_kv";
+export declare function mapKVRow(r: any): KVRecord;
+export declare class KVStore {
+    static ensureSchema(db: DBExecutable, tableName?: string): Promise<void>;
+    static set(db: DBExecutable, tableName: string | undefined, key: string, valueStr: string, type: string, now: number, expiresAt: number | null): Promise<void>;
+    static get(db: DBExecutable, tableName: string | undefined, key: string): Promise<KVRecord | null>;
+    static delete(db: DBExecutable, tableName: string | undefined, key: string): Promise<boolean>;
+    static listKeys(db: DBExecutable, tableName?: string, prefix?: string): Promise<string[]>;
+    static clear(db: DBExecutable, tableName?: string): Promise<void>;
+    static pruneExpired(db: DBExecutable, tableName?: string): Promise<number>;
+}

package/dist/kv/store.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KVStore = exports.DEFAULT_KV_TABLE = void 0;
+exports.mapKVRow = mapKVRow;
+exports.DEFAULT_KV_TABLE = '_local_kv';
+function mapKVRow(r) {
+    let val = r.value;
+    const type = r.type;
+    if (type === 'number') {
+        val = Number(val);
+    }
+    else if (type === 'boolean') {
+        val = val === 'true' || val === '1' || val === 1;
+    }
+    else if (type === 'json') {
+        try {
+            val = JSON.parse(val);
+        }
+        catch {
+            // fallback
+        }
+    }
+    return {
+        key: r.key,
+        value: val,
+        type: r.type,
+        createdAt: Number(r.created_at || 0),
+        updatedAt: Number(r.updated_at || 0),
+        expiresAt: r.expires_at != null ? Number(r.expires_at) : null,
+    };
+}
+class KVStore {
+    static async ensureSchema(db, tableName = exports.DEFAULT_KV_TABLE) {
+        await db.execute(`CREATE TABLE IF NOT EXISTS ${tableName} (
+        key TEXT PRIMARY KEY,
+        value TEXT NOT NULL,
+        type TEXT NOT NULL,
+        created_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL,
+        expires_at INTEGER
+      );`);
+        await db.execute(`CREATE INDEX IF NOT EXISTS idx_${tableName}_expires ON ${tableName} (expires_at);`);
+    }
+    static async set(db, tableName = exports.DEFAULT_KV_TABLE, key, valueStr, type, now, expiresAt) {
+        await db.execute(`INSERT INTO ${tableName} (key, value, type, created_at, updated_at, expires_at)
+       VALUES (?, ?, ?, ?, ?, ?)
+       ON CONFLICT(key) DO UPDATE SET
+         value = excluded.value,
+         type = excluded.type,
+         updated_at = excluded.updated_at,
+         expires_at = excluded.expires_at;`, [key, valueStr, type, now, now, expiresAt]);
+    }
+    static async get(db, tableName = exports.DEFAULT_KV_TABLE, key) {
+        const rows = await db.execute(`SELECT * FROM ${tableName} WHERE key = ? LIMIT 1;`, [key]);
+        if (!rows || rows.length === 0)
+            return null;
+        return mapKVRow(rows[0]);
+    }
+    static async delete(db, tableName = exports.DEFAULT_KV_TABLE, key) {
+        await db.execute(`DELETE FROM ${tableName} WHERE key = ?;`, [key]);
+        return true;
+    }
+    static async listKeys(db, tableName = exports.DEFAULT_KV_TABLE, prefix) {
+        let rows;
+        if (prefix) {
+            rows = await db.execute(`SELECT key, expires_at FROM ${tableName} WHERE key LIKE ? ORDER BY key ASC;`, [`${prefix}%`]);
+        }
+        else {
+            rows = await db.execute(`SELECT key, expires_at FROM ${tableName} ORDER BY key ASC;`);
+        }
+        const now = Date.now();
+        return (rows || [])
+            .filter((r) => r.expires_at == null || Number(r.expires_at) > now)
+            .map((r) => r.key);
+    }
+    static async clear(db, tableName = exports.DEFAULT_KV_TABLE) {
+        await db.execute(`DELETE FROM ${tableName};`);
+    }
+    static async pruneExpired(db, tableName = exports.DEFAULT_KV_TABLE) {
+        const now = Date.now();
+        await db.execute(`DELETE FROM ${tableName} WHERE expires_at IS NOT NULL AND expires_at <= ?;`, [now]);
+        return 0;
+    }
+}
+exports.KVStore = KVStore;

package/dist/kv/types.d.ts

@@ -0,0 +1,27 @@
+export interface KVSetOptions {
+    /**
+     * Time-to-live in milliseconds from current time.
+     */
+    ttlMs?: number;
+    /**
+     * Explicit Unix timestamp in milliseconds when this key expires.
+     */
+    expiresAt?: number;
+}
+export interface KVSetSecretOptions extends KVSetOptions {
+    /**
+     * Passphrase used to encrypt the value using AES-256-GCM.
+     */
+    passphrase: string;
+}
+export interface KVRecord<T = any> {
+    key: string;
+    value: T;
+    type: 'string' | 'number' | 'boolean' | 'json' | 'encrypted';
+    createdAt: number;
+    updatedAt: number;
+    expiresAt?: number | null;
+}
+export interface KVStoreOptions {
+    tableName?: string;
+}

package/dist/kv/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/react/index.d.ts

@@ -131,3 +131,6 @@ export { SyncInspector } from './SyncInspector.js';
 export type { SyncInspectorProps } from './SyncInspector.js';
 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

@@ -646,3 +646,6 @@ var SyncInspector_js_1 = require("./SyncInspector.js");
 Object.defineProperty(exports, "SyncInspector", { enumerable: true, get: function () { return SyncInspector_js_1.SyncInspector; } });
 __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/kv.d.ts

@@ -0,0 +1,9 @@
+import { LocalFirstClient } from '../core/client.js';
+/**
+ * Reactive React hook for client.kv key-value preferences.
+ * Automatically re-renders whenever the key is updated or deleted.
+ *
+ * Example:
+ * const [theme, setTheme, loading] = useKV(client, 'theme', 'light');
+ */
+export declare function useKV<T = any>(client: LocalFirstClient | null | undefined, key: string, defaultValue?: T): [T | undefined, (value: T) => Promise<void>, boolean];

package/dist/react/kv.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useKV = useKV;
+const react_1 = require("react");
+/**
+ * Reactive React hook for client.kv key-value preferences.
+ * Automatically re-renders whenever the key is updated or deleted.
+ *
+ * Example:
+ * const [theme, setTheme, loading] = useKV(client, 'theme', 'light');
+ */
+function useKV(client, key, defaultValue) {
+    const [value, setValueState] = (0, react_1.useState)(defaultValue);
+    const [loading, setLoading] = (0, react_1.useState)(true);
+    (0, react_1.useEffect)(() => {
+        if (!client) {
+            setValueState(defaultValue);
+            setLoading(false);
+            return;
+        }
+        let isMounted = true;
+        const load = async () => {
+            try {
+                const val = await client.kv.get(key, defaultValue);
+                if (isMounted) {
+                    setValueState(val);
+                    setLoading(false);
+                }
+            }
+            catch {
+                if (isMounted)
+                    setLoading(false);
+            }
+        };
+        load();
+        const unsubscribe = client.events.on('_local_kv', (e) => {
+            if (!e || e.key === key || !e.key) {
+                load();
+            }
+        });
+        return () => {
+            isMounted = false;
+            unsubscribe();
+        };
+    }, [client, key, defaultValue]);
+    const setKVValue = (0, react_1.useCallback)(async (newValue) => {
+        if (!client)
+            return;
+        await client.kv.set(key, newValue);
+        setValueState(newValue);
+    }, [client, key]);
+    return [value, setKVValue, loading];
+}

package/dist/react/search.d.ts

@@ -0,0 +1,19 @@
+import { LocalFirstClient } from '../core/client.js';
+import { SearchQueryOptions, SearchResult } from '../search/types.js';
+export interface UseSearchOptions extends SearchQueryOptions {
+    /**
+     * Debounce delay in milliseconds (default: 150ms).
+     */
+    debounceMs?: number;
+}
+/**
+ * Reactive React hook for instant full-text search with automatic debouncing.
+ *
+ * Example:
+ * const { results, loading, error } = useSearch(client, 'properties', searchQuery);
+ */
+export declare function useSearch<T = any>(client: LocalFirstClient | null | undefined, table: string, queryText: string, options?: UseSearchOptions): {
+    results: SearchResult<T>[];
+    loading: boolean;
+    error: Error | null;
+};

package/dist/react/search.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useSearch = useSearch;
+const react_1 = require("react");
+/**
+ * Reactive React hook for instant full-text search with automatic debouncing.
+ *
+ * Example:
+ * const { results, loading, error } = useSearch(client, 'properties', searchQuery);
+ */
+function useSearch(client, table, queryText, options) {
+    const [results, setResults] = (0, react_1.useState)([]);
+    const [loading, setLoading] = (0, react_1.useState)(false);
+    const [error, setError] = (0, react_1.useState)(null);
+    const debounceMs = options?.debounceMs ?? 150;
+    (0, react_1.useEffect)(() => {
+        if (!client || !table || !queryText.trim()) {
+            setResults([]);
+            setLoading(false);
+            return;
+        }
+        let isMounted = true;
+        setLoading(true);
+        const timer = setTimeout(async () => {
+            try {
+                const res = await client.search.query(table, queryText, options);
+                if (isMounted) {
+                    setResults(res);
+                    setError(null);
+                }
+            }
+            catch (err) {
+                if (isMounted) {
+                    setError(err instanceof Error ? err : new Error(String(err)));
+                }
+            }
+            finally {
+                if (isMounted) {
+                    setLoading(false);
+                }
+            }
+        }, debounceMs);
+        return () => {
+            isMounted = false;
+            clearTimeout(timer);
+        };
+    }, [client, table, queryText, debounceMs]);
+    return { results, loading, error };
+}

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>;