local-lite 0.0.21 → 0.0.24

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 local-lite contributors
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 local-lite contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -91,11 +91,11 @@ 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.
-* **📨 Action Outbox & Email Queue:** Enqueue transactional emails, push notifications, and webhooks offline with idempotency keys, automatic retry backoff, crash recovery, and TTL expiration.
-* **⚡ Fast Key-Value & Encrypted Preferences (`client.kv`):** Typed storage, TTL expiration, and AES-256-GCM zero-knowledge secret protection.
-* **🔍 Instant Full-Text Search (`client.search`):** SQLite FTS5 indexer with prefix matching, BM25 rank scoring, and highlighting.
-* **📁 Offline Media & Blob Storage (`client.storage`):** Decoupled binary attachments, SHA-256 verification, and cloud sync queue (S3/Supabase/Firebase).
+* **🔑 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.
+* **📨 Action Outbox & Email Queue:** Enqueue transactional emails, push notifications, and webhooks offline with idempotency keys, automatic retry backoff, crash recovery, and TTL expiration.
+* **⚡ Fast Key-Value & Encrypted Preferences (`client.kv`):** Typed storage, TTL expiration, and AES-256-GCM zero-knowledge secret protection.
+* **🔍 Instant Full-Text Search (`client.search`):** SQLite FTS5 indexer with prefix matching, BM25 rank scoring, and highlighting.
+* **📁 Offline Media & Blob Storage (`client.storage`):** Decoupled binary attachments, SHA-256 verification, and cloud sync queue (S3/Supabase/Firebase).
 * **⏰ Offline Job Scheduler & Background Cron (`client.scheduler`):** Persistent background task runner supporting human schedules and 5-field cron.
 
 
@@ -299,46 +299,46 @@ export function UserProfileHeader() {
 ---
 
 
-### 4. Offline Actions & Inbuilt Email Queue
-
-`local-lite` includes a durable **Generic Action Outbox** (`client.actions`) for side-effects that should not be lost when offline:
-
-```typescript
-import { client } from './sync.config';
-
-// ⚡ 1. Enqueue transactional email offline (0ms latency, safe if app closes)
-const emailAction = await client.actions.sendEmail({
-  to: 'customer@example.com',
-  subject: 'Order #1042 Confirmed',
-  html: '<h1>Thank you for your purchase!</h1>',
-  template: 'order_receipt',
-  templateData: { orderId: 1042, total: '$49.99' },
-  idempotencyKey: 'order_receipt_1042', // Prevents sending twice
-  ttlMs: 24 * 60 * 60 * 1000,           // Expire if offline for >24 hours
-});
-
-// ⚡ 2. Register local dispatcher (or let rows replicate to Supabase/Convex/Firebase)
-client.actions.registerEmailHandler(async (email) => {
-  // Dispatch via your transactional provider or backend API
-  const response = await fetch('https://api.resend.com/emails', {
-    method: 'POST',
-    headers: { Authorization: `Bearer ${process.env.RESEND_API_KEY}` },
-    body: JSON.stringify(email),
-  });
-  const data = await response.json();
-  return { messageId: data.id };
-});
-
-// ⚡ 3. Enqueue arbitrary asynchronous actions (e.g., push notifications, analytics)
-await client.actions.enqueue({
-  action: 'push_notification',
-  payload: { title: 'New chat message', token: 'fcm-xxx' },
-  idempotencyKey: 'chat_msg_99',
-});
-```
-
----
-
+### 4. Offline Actions & Inbuilt Email Queue
+
+`local-lite` includes a durable **Generic Action Outbox** (`client.actions`) for side-effects that should not be lost when offline:
+
+```typescript
+import { client } from './sync.config';
+
+// ⚡ 1. Enqueue transactional email offline (0ms latency, safe if app closes)
+const emailAction = await client.actions.sendEmail({
+  to: 'customer@example.com',
+  subject: 'Order #1042 Confirmed',
+  html: '<h1>Thank you for your purchase!</h1>',
+  template: 'order_receipt',
+  templateData: { orderId: 1042, total: '$49.99' },
+  idempotencyKey: 'order_receipt_1042', // Prevents sending twice
+  ttlMs: 24 * 60 * 60 * 1000,           // Expire if offline for >24 hours
+});
+
+// ⚡ 2. Register local dispatcher (or let rows replicate to Supabase/Convex/Firebase)
+client.actions.registerEmailHandler(async (email) => {
+  // Dispatch via your transactional provider or backend API
+  const response = await fetch('https://api.resend.com/emails', {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${process.env.RESEND_API_KEY}` },
+    body: JSON.stringify(email),
+  });
+  const data = await response.json();
+  return { messageId: data.id };
+});
+
+// ⚡ 3. Enqueue arbitrary asynchronous actions (e.g., push notifications, analytics)
+await client.actions.enqueue({
+  action: 'push_notification',
+  payload: { title: 'New chat message', token: 'fcm-xxx' },
+  idempotencyKey: 'chat_msg_99',
+});
+```
+
+---
+
 ## 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/actions/store.js

@@ -27,19 +27,19 @@ class ActionStore {
      * Initializes the action outbox schema and indexes if they do not exist.
      */
     static async ensureSchema(db, tableName = exports.DEFAULT_ACTIONS_TABLE) {
-        await db.execute(`CREATE TABLE IF NOT EXISTS ${tableName} (
-        id TEXT PRIMARY KEY,
-        action TEXT NOT NULL,
-        payload TEXT NOT NULL,
-        idempotency_key TEXT UNIQUE,
-        status TEXT NOT NULL DEFAULT 'PENDING',
-        created_at INTEGER NOT NULL,
-        expires_at INTEGER,
-        executed_at INTEGER,
-        retry_count INTEGER NOT NULL DEFAULT 0,
-        max_retries INTEGER NOT NULL DEFAULT 3,
-        last_error TEXT,
-        result TEXT
+        await db.execute(`CREATE TABLE IF NOT EXISTS ${tableName} (
+        id TEXT PRIMARY KEY,
+        action TEXT NOT NULL,
+        payload TEXT NOT NULL,
+        idempotency_key TEXT UNIQUE,
+        status TEXT NOT NULL DEFAULT 'PENDING',
+        created_at INTEGER NOT NULL,
+        expires_at INTEGER,
+        executed_at INTEGER,
+        retry_count INTEGER NOT NULL DEFAULT 0,
+        max_retries INTEGER NOT NULL DEFAULT 3,
+        last_error TEXT,
+        result TEXT
       );`);
         await db.execute(`CREATE INDEX IF NOT EXISTS idx_${tableName}_status ON ${tableName} (status, created_at);`);
         await db.execute(`CREATE INDEX IF NOT EXISTS idx_${tableName}_idempotency ON ${tableName} (idempotency_key);`);
@@ -55,8 +55,8 @@ class ActionStore {
      * Inserts an action record into storage.
      */
     static async insertRecord(db, tableName = exports.DEFAULT_ACTIONS_TABLE, record) {
-        await db.execute(`INSERT INTO ${tableName} (
-        id, action, payload, idempotency_key, status, created_at, expires_at, executed_at, retry_count, max_retries, last_error, result
+        await db.execute(`INSERT INTO ${tableName} (
+        id, action, payload, idempotency_key, status, created_at, expires_at, executed_at, retry_count, max_retries, last_error, result
       ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?);`, [
             record.id,
             record.action,

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/session.js

@@ -54,19 +54,19 @@ class SessionManager {
      * 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 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);`);
@@ -90,20 +90,20 @@ class SessionManager {
             // 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;
+        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,

package/dist/core/client.d.ts

@@ -347,7 +347,21 @@ export declare class LocalFirstClient {
         dropTables?: boolean;
         includeInternal?: boolean;
     }): Promise<void>;
-    private getAllTableNames;
+    /**
+   * Checks if a table name belongs to internal system, FTS, or engine tables.
+   */
+    isInternalTable(tableName: string): boolean;
+    /**
+     * Returns list of database tables.
+     * By default, internal tables (FTS shadow tables, local-lite engine tables) are excluded.
+     * Pass `{ includeInternal: true }` to include internal tables.
+     */
+    getTables(options?: {
+        includeInternal?: boolean;
+    }): Promise<string[]>;
+    getAllTableNames(options?: {
+        includeInternal?: boolean;
+    }): Promise<string[]>;
     /**
      * Exports the entire local database state as a portable binary snapshot.
      * If the local adapter has a native export mechanism (e.g. serialize or export),

package/dist/core/client.js

@@ -219,9 +219,21 @@ class LocalFirstClient {
         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, {
@@ -966,22 +978,50 @@ class LocalFirstClient {
         await this.resetSyncCursor();
         this.events.emit('reset', { dropTables: options.dropTables ?? false });
     }
-    async getAllTableNames() {
+    /**
+   * Checks if a table name belongs to internal system, FTS, or engine tables.
+   */
+    isInternalTable(tableName) {
+        return (0, sql_js_1.isInternalTable)(tableName);
+    }
+    /**
+     * Returns list of database tables.
+     * By default, internal tables (FTS shadow tables, local-lite engine tables) are excluded.
+     * Pass `{ includeInternal: true }` to include internal tables.
+     */
+    async getTables(options = {}) {
+        const includeInternal = options.includeInternal ?? false;
+        const allTables = await this.getAllTableNames(options);
+        if (includeInternal) {
+            return allTables;
+        }
+        return allTables.filter(name => !(0, sql_js_1.isInternalTable)(name));
+    }
+    async getAllTableNames(options = {}) {
+        const includeInternal = options.includeInternal ?? false;
         const list = new Set(this.tables);
-        list.add('sync_outbox');
-        list.add('sync_meta');
+        if (includeInternal) {
+            list.add('sync_outbox');
+            list.add('sync_meta');
+        }
         try {
-            const rows = await this.db.execute(`SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'`);
+            const rows = await this.db.execute(`SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' AND name NOT LIKE 'android_%'`);
             if (Array.isArray(rows)) {
                 for (const r of rows) {
-                    if (r.name)
-                        list.add(r.name);
+                    if (r.name) {
+                        if (includeInternal || !(0, sql_js_1.isInternalTable)(r.name)) {
+                            list.add(r.name);
+                        }
+                    }
                 }
             }
         }
         catch {
             // Non-SQLite database adapter, fallback to configured tables
         }
+        if (!includeInternal) {
+            return Array.from(list).filter(name => !(0, sql_js_1.isInternalTable)(name));
+        }
         return Array.from(list);
     }
     /**

package/dist/core/maintenance.d.ts

@@ -62,5 +62,7 @@ export declare class DatabaseMaintenance {
     /**
      * Gathers storage metrics: table row counts, outbox status distribution, and database size.
      */
-    getStorageStats(): Promise<StorageStats>;
+    getStorageStats(options?: {
+        includeInternal?: boolean;
+    }): Promise<StorageStats>;
 }

package/dist/core/maintenance.js

@@ -76,17 +76,21 @@ class DatabaseMaintenance {
     /**
      * Gathers storage metrics: table row counts, outbox status distribution, and database size.
      */
-    async getStorageStats() {
+    async getStorageStats(options = {}) {
+        const includeInternal = options.includeInternal ?? false;
         // 1. Table row counts
         const tableCounts = {};
         let tableNames = [];
         try {
-            const masterRows = await this.db.execute(`SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'`);
+            const masterRows = await this.db.execute(`SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' AND name NOT LIKE 'android_%'`);
             tableNames = masterRows.map((r) => r.name);
         }
         catch {
             tableNames = this.getKnownTables();
         }
+        if (!includeInternal) {
+            tableNames = tableNames.filter(name => !(0, sql_js_1.isInternalTable)(name));
+        }
         for (const tableName of tableNames) {
             try {
                 const safeTable = (0, sql_js_1.escapeIdentifier)(tableName);

package/dist/core/meta-store.js

@@ -7,9 +7,9 @@ class MetaStore {
      * This table is strictly local to the device and is never synced to the remote server.
      */
     static async ensureSchema(db) {
-        await db.execute(`CREATE TABLE IF NOT EXISTS sync_meta (
-        key TEXT PRIMARY KEY,
-        value TEXT NOT NULL
+        await db.execute(`CREATE TABLE IF NOT EXISTS sync_meta (
+        key TEXT PRIMARY KEY,
+        value TEXT NOT NULL
       );`);
     }
     /**