local-lite 0.0.17 → 0.0.19

package/README.md

@@ -91,7 +91,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.
+* **🔑 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.
 
 
 ---
@@ -294,6 +295,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',
+});
+```
+
+---
+
 ## 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/index.d.ts

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

package/dist/actions/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/actions/manager.d.ts

@@ -0,0 +1,71 @@
+import { LocalDBAdapter } from '../adapters/local/index.js';
+import { EventEmitter } from '../reactive/event-emitter.js';
+import { ActionFilterOptions, ActionHandler, ActionManagerOptions, ActionPruneOptions, ActionRecord, EmailHandler, EmailPayload, EnqueueActionOptions, FlushActionsResult, SendEmailOptions } from './types.js';
+export declare class ActionManager {
+    private db;
+    private events;
+    private isOnlineFn;
+    private options;
+    private tableName;
+    private handlers;
+    private isFlushing;
+    private flushRerunRequested;
+    private networkUnsubscribe?;
+    constructor(db: LocalDBAdapter, events: EventEmitter, isOnline: () => Promise<boolean>, options?: ActionManagerOptions);
+    /**
+     * Stops active network listeners.
+     */
+    stop(): void;
+    /**
+     * Initializes the action store: creates tables/indexes and resets stale executing states.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Enqueues an asynchronous action with offline durability and idempotency checks.
+     */
+    enqueue<TPayload = any, TResult = any>(opts: EnqueueActionOptions<TPayload>): Promise<ActionRecord<TPayload, TResult>>;
+    /**
+     * Convenience helper to enqueue a transactional email with offline resilience.
+     */
+    sendEmail(options: SendEmailOptions): Promise<ActionRecord<EmailPayload, any>>;
+    /**
+     * Registers a local executor for a specific action name.
+     * Returns an unregister function.
+     */
+    registerHandler<TPayload = any, TResult = any>(action: string, handler: ActionHandler<TPayload, TResult>): () => void;
+    /**
+     * Registers a dedicated handler for 'send_email' actions.
+     */
+    registerEmailHandler(handler: EmailHandler): () => void;
+    /**
+     * Flushes all pending actions whose handlers are registered locally.
+     * Actions without a registered handler remain in the queue (e.g. to be synced to cloud functions).
+     */
+    private flushPromise?;
+    /**
+     * Flushes all pending actions whose handlers are registered locally.
+     * Actions without a registered handler remain in the queue (e.g. to be synced to cloud functions).
+     */
+    flush(): Promise<FlushActionsResult>;
+    private performFlush;
+    /**
+     * Retrieves an action record by ID.
+     */
+    get(id: string): Promise<ActionRecord | null>;
+    /**
+     * Lists action records with optional filtering.
+     */
+    list(filter?: ActionFilterOptions): Promise<ActionRecord[]>;
+    /**
+     * Cancels a pending action before it has been executed.
+     */
+    cancel(id: string): Promise<boolean>;
+    /**
+     * Prunes completed, failed, expired, or cancelled actions from local storage.
+     */
+    prune(options?: ActionPruneOptions): Promise<number>;
+    /**
+     * Checks network connectivity via the configured provider.
+     */
+    isOnline(): Promise<boolean>;
+}

package/dist/actions/manager.js

@@ -0,0 +1,287 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ActionManager = void 0;
+const uuid_js_1 = require("../utils/uuid.js");
+const store_js_1 = require("./store.js");
+class ActionManager {
+    db;
+    events;
+    isOnlineFn;
+    options;
+    tableName;
+    handlers = new Map();
+    isFlushing = false;
+    flushRerunRequested = false;
+    networkUnsubscribe;
+    constructor(db, events, isOnline, options = {}) {
+        this.db = db;
+        this.events = events;
+        this.isOnlineFn = isOnline;
+        this.options = {
+            defaultMaxRetries: 3,
+            autoFlushOnOnline: true,
+            autoFlushOnEnqueue: false,
+            ...options,
+        };
+        this.tableName = options.tableName || store_js_1.DEFAULT_ACTIONS_TABLE;
+        if (this.options.network && this.options.autoFlushOnOnline) {
+            let lastOnline = undefined;
+            this.networkUnsubscribe = this.options.network.subscribe((online) => {
+                if (online && lastOnline === false) {
+                    this.flush().catch(() => { });
+                }
+                lastOnline = online;
+            });
+        }
+    }
+    /**
+     * Stops active network listeners.
+     */
+    stop() {
+        if (this.networkUnsubscribe) {
+            this.networkUnsubscribe();
+            this.networkUnsubscribe = undefined;
+        }
+    }
+    /**
+     * Initializes the action store: creates tables/indexes and resets stale executing states.
+     */
+    async initialize() {
+        await store_js_1.ActionStore.ensureSchema(this.db, this.tableName);
+        await store_js_1.ActionStore.resetStaleExecuting(this.db, this.tableName);
+    }
+    /**
+     * Enqueues an asynchronous action with offline durability and idempotency checks.
+     */
+    async enqueue(opts) {
+        if (!opts.action || typeof opts.action !== 'string') {
+            throw new Error('Action name is required and must be a string');
+        }
+        // 1. Idempotency check: if key already exists, return existing record
+        if (opts.idempotencyKey) {
+            const existing = await store_js_1.ActionStore.findByIdempotencyKey(this.db, this.tableName, opts.idempotencyKey);
+            if (existing) {
+                return existing;
+            }
+        }
+        const now = Date.now();
+        const expiresAt = opts.expiresAt !== undefined
+            ? opts.expiresAt
+            : opts.ttlMs !== undefined
+                ? now + opts.ttlMs
+                : this.options.defaultTtlMs !== undefined
+                    ? now + this.options.defaultTtlMs
+                    : null;
+        const record = {
+            id: (0, uuid_js_1.generateUUID)(),
+            action: opts.action,
+            payload: opts.payload,
+            idempotencyKey: opts.idempotencyKey ?? null,
+            status: 'PENDING',
+            createdAt: now,
+            expiresAt,
+            executedAt: null,
+            retryCount: 0,
+            maxRetries: opts.maxRetries ?? this.options.defaultMaxRetries ?? 3,
+            lastError: null,
+            result: null,
+        };
+        await store_js_1.ActionStore.insertRecord(this.db, this.tableName, record);
+        this.events.emit('action:enqueued', record);
+        // Auto-flush if configured
+        if (this.options.autoFlushOnEnqueue) {
+            this.flush().catch(() => { });
+        }
+        return record;
+    }
+    /**
+     * Convenience helper to enqueue a transactional email with offline resilience.
+     */
+    async sendEmail(options) {
+        const { idempotencyKey, ttlMs, expiresAt, maxRetries, ...emailPayload } = options;
+        if (!emailPayload.to) {
+            throw new Error("Email 'to' recipient is required");
+        }
+        if (!emailPayload.subject) {
+            throw new Error("Email 'subject' is required");
+        }
+        return this.enqueue({
+            action: 'send_email',
+            payload: emailPayload,
+            idempotencyKey,
+            ttlMs,
+            expiresAt,
+            maxRetries,
+        });
+    }
+    /**
+     * Registers a local executor for a specific action name.
+     * Returns an unregister function.
+     */
+    registerHandler(action, handler) {
+        this.handlers.set(action, handler);
+        return () => {
+            if (this.handlers.get(action) === handler) {
+                this.handlers.delete(action);
+            }
+        };
+    }
+    /**
+     * Registers a dedicated handler for 'send_email' actions.
+     */
+    registerEmailHandler(handler) {
+        return this.registerHandler('send_email', (record, context) => handler(record.payload, record, context));
+    }
+    /**
+     * Flushes all pending actions whose handlers are registered locally.
+     * Actions without a registered handler remain in the queue (e.g. to be synced to cloud functions).
+     */
+    flushPromise;
+    /**
+     * Flushes all pending actions whose handlers are registered locally.
+     * Actions without a registered handler remain in the queue (e.g. to be synced to cloud functions).
+     */
+    async flush() {
+        if (this.flushPromise) {
+            this.flushRerunRequested = true;
+            return this.flushPromise;
+        }
+        this.flushPromise = this.performFlush().finally(() => {
+            this.flushPromise = undefined;
+        });
+        return this.flushPromise;
+    }
+    async performFlush() {
+        const result = {
+            processed: 0,
+            completed: 0,
+            failed: 0,
+            expired: 0,
+            skipped: 0,
+        };
+        try {
+            do {
+                this.flushRerunRequested = false;
+                const online = await this.isOnline();
+                if (!online) {
+                    break;
+                }
+                const pending = await store_js_1.ActionStore.getPending(this.db, this.tableName, 50);
+                if (pending.length === 0) {
+                    break;
+                }
+                const context = {
+                    db: this.db,
+                    isOnline: this.isOnlineFn,
+                };
+                for (const action of pending) {
+                    result.processed++;
+                    const now = Date.now();
+                    // 1. Check TTL expiration
+                    if (action.expiresAt && action.expiresAt <= now) {
+                        await store_js_1.ActionStore.updateStatus(this.db, this.tableName, action.id, 'EXPIRED');
+                        const expiredRecord = { ...action, status: 'EXPIRED' };
+                        result.expired++;
+                        this.events.emit('action:expired', expiredRecord);
+                        continue;
+                    }
+                    // 2. Lookup handler
+                    const handler = this.handlers.get(action.action);
+                    if (!handler) {
+                        // No local handler; leave as PENDING for remote sync replication
+                        result.skipped++;
+                        continue;
+                    }
+                    // 3. Mark EXECUTING
+                    await store_js_1.ActionStore.updateStatus(this.db, this.tableName, action.id, 'EXECUTING');
+                    this.events.emit('action:executing', { ...action, status: 'EXECUTING' });
+                    // 4. Execute handler
+                    try {
+                        const res = await handler(action, context);
+                        const executedAt = Date.now();
+                        await store_js_1.ActionStore.updateStatus(this.db, this.tableName, action.id, 'COMPLETED', {
+                            executedAt,
+                            result: res ?? null,
+                        });
+                        result.completed++;
+                        this.events.emit('action:completed', {
+                            ...action,
+                            status: 'COMPLETED',
+                            executedAt,
+                            result: res ?? null,
+                        });
+                    }
+                    catch (err) {
+                        const nextRetry = action.retryCount + 1;
+                        const isFinalFailure = nextRetry >= action.maxRetries;
+                        const newStatus = isFinalFailure ? 'FAILED' : 'PENDING';
+                        const errorMsg = err instanceof Error ? err.message : String(err);
+                        await store_js_1.ActionStore.updateStatus(this.db, this.tableName, action.id, newStatus, {
+                            retryCount: nextRetry,
+                            lastError: errorMsg,
+                        });
+                        if (isFinalFailure) {
+                            result.failed++;
+                            this.events.emit('action:failed', {
+                                ...action,
+                                status: 'FAILED',
+                                retryCount: nextRetry,
+                                lastError: errorMsg,
+                            });
+                        }
+                        else {
+                            this.events.emit('action:retry', {
+                                ...action,
+                                status: 'PENDING',
+                                retryCount: nextRetry,
+                                lastError: errorMsg,
+                            });
+                        }
+                    }
+                }
+            } while (this.flushRerunRequested);
+        }
+        finally { }
+        return result;
+    }
+    /**
+     * Retrieves an action record by ID.
+     */
+    async get(id) {
+        return store_js_1.ActionStore.findById(this.db, this.tableName, id);
+    }
+    /**
+     * Lists action records with optional filtering.
+     */
+    async list(filter) {
+        return store_js_1.ActionStore.list(this.db, this.tableName, filter);
+    }
+    /**
+     * Cancels a pending action before it has been executed.
+     */
+    async cancel(id) {
+        const cancelled = await store_js_1.ActionStore.cancel(this.db, this.tableName, id);
+        if (cancelled) {
+            this.events.emit('action:cancelled', { id });
+        }
+        return cancelled;
+    }
+    /**
+     * Prunes completed, failed, expired, or cancelled actions from local storage.
+     */
+    async prune(options) {
+        return store_js_1.ActionStore.prune(this.db, this.tableName, options);
+    }
+    /**
+     * Checks network connectivity via the configured provider.
+     */
+    async isOnline() {
+        try {
+            return await this.isOnlineFn();
+        }
+        catch {
+            return true;
+        }
+    }
+}
+exports.ActionManager = ActionManager;

package/dist/actions/store.d.ts

@@ -0,0 +1,54 @@
+import { DBExecutable } from '../core/schema-manager.js';
+import { ActionFilterOptions, ActionPruneOptions, ActionRecord, ActionStatus } from './types.js';
+export declare const DEFAULT_ACTIONS_TABLE = "_local_actions";
+/**
+ * Maps raw database row into a typed ActionRecord.
+ */
+export declare function mapActionRow(r: any): ActionRecord;
+export declare class ActionStore {
+    /**
+     * Initializes the action outbox schema and indexes if they do not exist.
+     */
+    static ensureSchema(db: DBExecutable, tableName?: string): Promise<void>;
+    /**
+     * Resets interrupted 'EXECUTING' records back to 'PENDING' on startup.
+     */
+    static resetStaleExecuting(db: DBExecutable, tableName?: string): Promise<void>;
+    /**
+     * Inserts an action record into storage.
+     */
+    static insertRecord(db: DBExecutable, tableName: string | undefined, record: ActionRecord): Promise<void>;
+    /**
+     * Finds an action record by ID.
+     */
+    static findById(db: DBExecutable, tableName: string | undefined, id: string): Promise<ActionRecord | null>;
+    /**
+     * Finds an existing action by its idempotency key.
+     */
+    static findByIdempotencyKey(db: DBExecutable, tableName: string | undefined, key: string): Promise<ActionRecord | null>;
+    /**
+     * Retrieves pending actions ordered by creation timestamp.
+     */
+    static getPending(db: DBExecutable, tableName?: string, limit?: number): Promise<ActionRecord[]>;
+    /**
+     * Updates the status and optional metadata fields of an action record.
+     */
+    static updateStatus(db: DBExecutable, tableName: string | undefined, id: string, status: ActionStatus, updates?: {
+        executedAt?: number | null;
+        retryCount?: number;
+        lastError?: string | null;
+        result?: any;
+    }): Promise<void>;
+    /**
+     * Queries action records with optional filtering.
+     */
+    static list(db: DBExecutable, tableName?: string, filter?: ActionFilterOptions): Promise<ActionRecord[]>;
+    /**
+     * Cancels a pending action if it has not yet executed.
+     */
+    static cancel(db: DBExecutable, tableName: string | undefined, id: string): Promise<boolean>;
+    /**
+     * Prunes old completed, failed, or expired action records.
+     */
+    static prune(db: DBExecutable, tableName?: string, options?: ActionPruneOptions): Promise<number>;
+}

package/dist/actions/store.js

@@ -0,0 +1,202 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ActionStore = exports.DEFAULT_ACTIONS_TABLE = void 0;
+exports.mapActionRow = mapActionRow;
+exports.DEFAULT_ACTIONS_TABLE = '_local_actions';
+/**
+ * Maps raw database row into a typed ActionRecord.
+ */
+function mapActionRow(r) {
+    return {
+        id: r.id,
+        action: r.action,
+        payload: r.payload ? (typeof r.payload === 'string' ? JSON.parse(r.payload) : r.payload) : {},
+        idempotencyKey: r.idempotency_key ?? null,
+        status: r.status,
+        createdAt: Number(r.created_at || 0),
+        expiresAt: r.expires_at != null ? Number(r.expires_at) : null,
+        executedAt: r.executed_at != null ? Number(r.executed_at) : null,
+        retryCount: Number(r.retry_count || 0),
+        maxRetries: Number(r.max_retries || 3),
+        lastError: r.last_error ?? null,
+        result: r.result ? (typeof r.result === 'string' ? JSON.parse(r.result) : r.result) : null,
+    };
+}
+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 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);`);
+        await db.execute(`CREATE INDEX IF NOT EXISTS idx_${tableName}_action ON ${tableName} (action, status);`);
+    }
+    /**
+     * Resets interrupted 'EXECUTING' records back to 'PENDING' on startup.
+     */
+    static async resetStaleExecuting(db, tableName = exports.DEFAULT_ACTIONS_TABLE) {
+        await db.execute(`UPDATE ${tableName} SET status = 'PENDING' WHERE status = 'EXECUTING';`);
+    }
+    /**
+     * 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
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?);`, [
+            record.id,
+            record.action,
+            typeof record.payload === 'string' ? record.payload : JSON.stringify(record.payload ?? {}),
+            record.idempotencyKey ?? null,
+            record.status,
+            record.createdAt,
+            record.expiresAt ?? null,
+            record.executedAt ?? null,
+            record.retryCount,
+            record.maxRetries,
+            record.lastError ?? null,
+            record.result ? (typeof record.result === 'string' ? record.result : JSON.stringify(record.result)) : null,
+        ]);
+    }
+    /**
+     * Finds an action record by ID.
+     */
+    static async findById(db, tableName = exports.DEFAULT_ACTIONS_TABLE, id) {
+        const rows = await db.execute(`SELECT * FROM ${tableName} WHERE id = ? LIMIT 1;`, [id]);
+        if (!rows || rows.length === 0)
+            return null;
+        return mapActionRow(rows[0]);
+    }
+    /**
+     * Finds an existing action by its idempotency key.
+     */
+    static async findByIdempotencyKey(db, tableName = exports.DEFAULT_ACTIONS_TABLE, key) {
+        const rows = await db.execute(`SELECT * FROM ${tableName} WHERE idempotency_key = ? LIMIT 1;`, [key]);
+        if (!rows || rows.length === 0)
+            return null;
+        return mapActionRow(rows[0]);
+    }
+    /**
+     * Retrieves pending actions ordered by creation timestamp.
+     */
+    static async getPending(db, tableName = exports.DEFAULT_ACTIONS_TABLE, limit = 50) {
+        const rows = await db.execute(`SELECT * FROM ${tableName} WHERE status = 'PENDING' ORDER BY created_at ASC LIMIT ?;`, [limit]);
+        return (rows || []).map(mapActionRow);
+    }
+    /**
+     * Updates the status and optional metadata fields of an action record.
+     */
+    static async updateStatus(db, tableName = exports.DEFAULT_ACTIONS_TABLE, id, status, updates = {}) {
+        const sets = ['status = ?'];
+        const params = [status];
+        if (updates.executedAt !== undefined) {
+            sets.push('executed_at = ?');
+            params.push(updates.executedAt);
+        }
+        if (updates.retryCount !== undefined) {
+            sets.push('retry_count = ?');
+            params.push(updates.retryCount);
+        }
+        if (updates.lastError !== undefined) {
+            sets.push('last_error = ?');
+            params.push(updates.lastError);
+        }
+        if (updates.result !== undefined) {
+            sets.push('result = ?');
+            params.push(updates.result ? JSON.stringify(updates.result) : null);
+        }
+        params.push(id);
+        await db.execute(`UPDATE ${tableName} SET ${sets.join(', ')} WHERE id = ?;`, params);
+    }
+    /**
+     * Queries action records with optional filtering.
+     */
+    static async list(db, tableName = exports.DEFAULT_ACTIONS_TABLE, filter = {}) {
+        const conditions = [];
+        const params = [];
+        if (filter.status) {
+            if (Array.isArray(filter.status)) {
+                if (filter.status.length > 0) {
+                    conditions.push(`status IN (${filter.status.map(() => '?').join(', ')})`);
+                    params.push(...filter.status);
+                }
+            }
+            else {
+                conditions.push(`status = ?`);
+                params.push(filter.status);
+            }
+        }
+        if (filter.action) {
+            if (Array.isArray(filter.action)) {
+                if (filter.action.length > 0) {
+                    conditions.push(`action IN (${filter.action.map(() => '?').join(', ')})`);
+                    params.push(...filter.action);
+                }
+            }
+            else {
+                conditions.push(`action = ?`);
+                params.push(filter.action);
+            }
+        }
+        const whereClause = conditions.length > 0 ? ` WHERE ${conditions.join(' AND ')}` : '';
+        let limitClause = '';
+        if (filter.limit !== undefined) {
+            limitClause = ` LIMIT ?`;
+            params.push(filter.limit);
+            if (filter.offset !== undefined) {
+                limitClause += ` OFFSET ?`;
+                params.push(filter.offset);
+            }
+        }
+        const rows = await db.execute(`SELECT * FROM ${tableName}${whereClause} ORDER BY created_at DESC${limitClause};`, params);
+        return (rows || []).map(mapActionRow);
+    }
+    /**
+     * Cancels a pending action if it has not yet executed.
+     */
+    static async cancel(db, tableName = exports.DEFAULT_ACTIONS_TABLE, id) {
+        const rows = await db.execute(`UPDATE ${tableName} SET status = 'CANCELLED' WHERE id = ? AND status = 'PENDING';`, [id]);
+        // In drivers that return affected rows or execute successfully
+        const record = await this.findById(db, tableName, id);
+        return record?.status === 'CANCELLED';
+    }
+    /**
+     * Prunes old completed, failed, or expired action records.
+     */
+    static async prune(db, tableName = exports.DEFAULT_ACTIONS_TABLE, options = {}) {
+        const now = Date.now();
+        let deletedCount = 0;
+        if (options.completedOlderThanMs !== undefined) {
+            const cutoff = now - options.completedOlderThanMs;
+            await db.execute(`DELETE FROM ${tableName} WHERE status = 'COMPLETED' AND executed_at IS NOT NULL AND executed_at <= ?;`, [cutoff]);
+        }
+        if (options.failedOlderThanMs !== undefined) {
+            const cutoff = now - options.failedOlderThanMs;
+            await db.execute(`DELETE FROM ${tableName} WHERE status = 'FAILED' AND created_at <= ?;`, [cutoff]);
+        }
+        if (options.expiredOlderThanMs !== undefined) {
+            const cutoff = now - options.expiredOlderThanMs;
+            await db.execute(`DELETE FROM ${tableName} WHERE status = 'EXPIRED' AND created_at <= ?;`, [cutoff]);
+        }
+        if (options.cancelledOlderThanMs !== undefined) {
+            const cutoff = now - options.cancelledOlderThanMs;
+            await db.execute(`DELETE FROM ${tableName} WHERE status = 'CANCELLED' AND created_at <= ?;`, [cutoff]);
+        }
+        return deletedCount;
+    }
+}
+exports.ActionStore = ActionStore;

package/dist/actions/types.d.ts

@@ -0,0 +1,91 @@
+import { LocalDBAdapter } from '../adapters/local/index.js';
+import { CustomLogger } from '../utils/logger.js';
+import { NetworkStatusProvider } from '../core/types.js';
+export type ActionStatus = 'PENDING' | 'EXECUTING' | 'COMPLETED' | 'FAILED' | 'EXPIRED' | 'CANCELLED';
+export interface ActionRecord<TPayload = any, TResult = any> {
+    id: string;
+    action: string;
+    payload: TPayload;
+    idempotencyKey?: string | null;
+    status: ActionStatus;
+    createdAt: number;
+    expiresAt?: number | null;
+    executedAt?: number | null;
+    retryCount: number;
+    maxRetries: number;
+    lastError?: string | null;
+    result?: TResult | null;
+}
+export interface EnqueueActionOptions<TPayload = any> {
+    action: string;
+    payload: TPayload;
+    idempotencyKey?: string | null;
+    ttlMs?: number;
+    expiresAt?: number | null;
+    maxRetries?: number;
+}
+export interface ActionHandlerContext {
+    db: LocalDBAdapter;
+    isOnline: () => Promise<boolean>;
+}
+export type ActionHandler<TPayload = any, TResult = any> = (action: ActionRecord<TPayload, TResult>, context: ActionHandlerContext) => Promise<TResult | void> | TResult | void;
+export interface ActionFilterOptions {
+    status?: ActionStatus | ActionStatus[];
+    action?: string | string[];
+    limit?: number;
+    offset?: number;
+}
+export interface ActionPruneOptions {
+    completedOlderThanMs?: number;
+    failedOlderThanMs?: number;
+    expiredOlderThanMs?: number;
+    cancelledOlderThanMs?: number;
+}
+export interface FlushActionsResult {
+    processed: number;
+    completed: number;
+    failed: number;
+    expired: number;
+    skipped: number;
+}
+export interface ActionManagerOptions {
+    tableName?: string;
+    defaultMaxRetries?: number;
+    defaultTtlMs?: number;
+    autoFlushOnOnline?: boolean;
+    autoFlushOnEnqueue?: boolean;
+    network?: NetworkStatusProvider;
+    logger?: boolean | CustomLogger;
+}
+export interface EmailAttachment {
+    filename: string;
+    content?: string;
+    url?: string;
+    contentType?: string;
+}
+export interface EmailPayload {
+    to: string | string[];
+    subject: string;
+    html?: string;
+    text?: string;
+    from?: string;
+    replyTo?: string;
+    cc?: string | string[];
+    bcc?: string | string[];
+    template?: string;
+    templateData?: Record<string, any>;
+    headers?: Record<string, string>;
+    attachments?: EmailAttachment[];
+    metadata?: Record<string, any>;
+}
+export interface SendEmailOptions extends EmailPayload {
+    idempotencyKey?: string;
+    ttlMs?: number;
+    expiresAt?: number;
+    maxRetries?: number;
+}
+export type EmailHandlerResult = {
+    messageId?: string;
+    [key: string]: any;
+} | void;
+export type EmailHandler = (email: EmailPayload, action: ActionRecord<EmailPayload, any>, context: ActionHandlerContext) => Promise<EmailHandlerResult> | EmailHandlerResult;

package/dist/actions/types.js

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

package/dist/core/client.d.ts

@@ -9,6 +9,7 @@ import { SyncLogger, CustomLogger, LogLevel } from '../utils/logger.js';
 import { QueryBuilder, AggregateSpec, AggregateResult } from './query-builder.js';
 import { type ExportJsonOptions, type ImportJsonOptions, type ExportCsvOptions, type ImportCsvOptions, type ImportSummary } from '../utils/portability.js';
 import { type BackupStorage, type CreateDatabaseBackupOptions, type EncryptedBackupOptions, type RestoreEncryptedBackupOptions } from '../backups/index.js';
+import { ActionManager, type ActionManagerOptions } from '../actions/index.js';
 export interface LocalFirstClientConfig {
     local: LocalDBAdapter;
     remote: RemoteDBAdapter;
@@ -39,6 +40,7 @@ export interface LocalFirstClientConfig {
      * - `false`: disabled
      */
     touchUpdatedAt?: boolean | string;
+    actions?: ActionManagerOptions;
 }
 export declare class TransactionalClient {
     private parent;
@@ -86,6 +88,7 @@ export declare class LocalFirstClient {
     /** Local column stamped on INSERT/UPDATE writes, or null when disabled. */
     touchColumn: string | null;
     readonly maintenance: DatabaseMaintenance;
+    readonly actions: ActionManager;
     private primaryKey;
     private migrations;
     private autoStart;

package/dist/core/client.js

@@ -14,6 +14,7 @@ const query_js_1 = require("./query.js");
 const query_builder_js_1 = require("./query-builder.js");
 const portability_js_1 = require("../utils/portability.js");
 const index_js_1 = require("../backups/index.js");
+const index_js_2 = require("../actions/index.js");
 function hasFunctionFilter(value) {
     if (typeof value === 'function')
         return true;
@@ -166,6 +167,7 @@ class LocalFirstClient {
     /** Local column stamped on INSERT/UPDATE writes, or null when disabled. */
     touchColumn;
     maintenance;
+    actions;
     primaryKey;
     migrations;
     autoStart;
@@ -191,6 +193,11 @@ class LocalFirstClient {
                     : this.remote?.updatedAtColumn || 'updated_at';
         this.schemaManager = new schema_manager_js_1.SchemaManager();
         this.maintenance = new maintenance_js_1.DatabaseMaintenance(this.db, () => this.tables);
+        const actionNetwork = config.actions?.network ?? config.network;
+        this.actions = new index_js_2.ActionManager(this.db, this.events, () => Promise.resolve(actionNetwork ? actionNetwork.isOnline() : true), {
+            network: actionNetwork,
+            ...config.actions,
+        });
         const workerOptions = {
             network: config.network,
             conflictResolver: config.conflictResolver,
@@ -349,6 +356,7 @@ class LocalFirstClient {
         await outbox_store_js_1.OutboxStore.ensureSchema(this.db);
         await meta_store_js_1.MetaStore.ensureSchema(this.db);
         await outbox_store_js_1.OutboxStore.resetStaleProcessing(this.db);
+        await this.actions.initialize();
         if (this.migrations.length > 0) {
             await this.db.transaction(async (tx) => {
                 for (const query of this.migrations) {
@@ -862,6 +870,7 @@ class LocalFirstClient {
      */
     stop() {
         this.syncWorker.stop();
+        this.actions.stop();
     }
     /**
      * Stops background sync workers, cleans up remote listeners,

package/dist/index.d.ts

@@ -14,7 +14,7 @@ export * from './adapters/local/index.js';
 export * from './adapters/remote/index.js';
 export * from './adapters/network/index.js';
 export * from './config/index.js';
-export type * from './react/index.js';
+export * from './react/index.js';
 export * from './utils/uuid.js';
 export * from './utils/sql.js';
 export * from './utils/logger.js';
@@ -22,3 +22,4 @@ export * from './utils/portability.js';
 export * from './schema/index.js';
 export * from './auth/index.js';
 export * from './backups/index.js';
+export * from './actions/index.js';

package/dist/index.js

@@ -30,6 +30,7 @@ __exportStar(require("./adapters/local/index.js"), exports);
 __exportStar(require("./adapters/remote/index.js"), exports);
 __exportStar(require("./adapters/network/index.js"), exports);
 __exportStar(require("./config/index.js"), exports);
+__exportStar(require("./react/index.js"), exports);
 __exportStar(require("./utils/uuid.js"), exports);
 __exportStar(require("./utils/sql.js"), exports);
 __exportStar(require("./utils/logger.js"), exports);
@@ -37,3 +38,4 @@ __exportStar(require("./utils/portability.js"), exports);
 __exportStar(require("./schema/index.js"), exports);
 __exportStar(require("./auth/index.js"), exports);
 __exportStar(require("./backups/index.js"), exports);
+__exportStar(require("./actions/index.js"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "local-lite",
-  "version": "0.0.17",
+  "version": "0.0.19",
   "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",
@@ -100,6 +100,11 @@
       "types": "./dist/core/index.d.ts",
       "import": "./dist/core/index.js",
       "default": "./dist/core/index.js"
+    },
+    "./actions": {
+      "types": "./dist/actions/index.d.ts",
+      "import": "./dist/actions/index.js",
+      "default": "./dist/actions/index.js"
     }
   },
   "scripts": {
@@ -153,7 +158,7 @@
     "@types/node": "^26.6.5",
     "@types/react": "^19.3.0",
     "@types/uuid": "^11.0.0",
-    "expo-sqlite": "^58.0.13",
+    "expo-sqlite": "^58.0.14",
     "react": "^19.3.1",
     "typescript": "^7.0.2",
     "vitest": "^5.0.5"