@nuraly/lumenjs 0.1.3 → 0.2.0

package/dist/communication/handlers/presence.js

@@ -0,0 +1,76 @@
+// ── Typing ──────────────────────────────────────────────────────
+export function handleTypingStart(ctx, data) {
+    ctx.store.setTyping(data.conversationId, ctx.userId, () => {
+        // Auto-expire: broadcast typing stopped
+        ctx.broadcastAll(`conv:${data.conversationId}`, {
+            event: 'typing:update',
+            data: { conversationId: data.conversationId, userId: ctx.userId, isTyping: false },
+        });
+    });
+    ctx.broadcast(`conv:${data.conversationId}`, {
+        event: 'typing:update',
+        data: { conversationId: data.conversationId, userId: ctx.userId, isTyping: true },
+    });
+}
+export function handleTypingStop(ctx, data) {
+    ctx.store.clearTyping(data.conversationId, ctx.userId);
+    ctx.broadcast(`conv:${data.conversationId}`, {
+        event: 'typing:update',
+        data: { conversationId: data.conversationId, userId: ctx.userId, isTyping: false },
+    });
+}
+// ── Presence ────────────────────────────────────────────────────
+/** Broadcast online status to all conversation rooms when a user connects */
+export function handleConnect(ctx) {
+    const conversations = ctx.store.getUserConversations(ctx.userId);
+    if (conversations.size === 0)
+        return;
+    const entry = ctx.store.getPresence(ctx.userId);
+    if (!entry)
+        return;
+    const payload = {
+        event: 'presence:changed',
+        data: { userId: ctx.userId, status: entry.status, lastSeen: entry.lastSeen },
+    };
+    for (const convId of conversations) {
+        ctx.broadcastAll(`conv:${convId}`, payload);
+    }
+}
+export function handlePresenceUpdate(ctx, data) {
+    const entry = ctx.store.setPresence(ctx.userId, data.status);
+    const payload = {
+        event: 'presence:changed',
+        data: { userId: ctx.userId, status: entry.status, lastSeen: entry.lastSeen },
+    };
+    // Broadcast to all conversation rooms the user has joined
+    for (const convId of ctx.store.getUserConversations(ctx.userId)) {
+        ctx.broadcastAll(`conv:${convId}`, payload);
+    }
+}
+/** Called on disconnect to clean up user state */
+export function handleDisconnect(ctx, socketId) {
+    const userId = ctx.store.unmapUserSocket(socketId);
+    if (!userId)
+        return;
+    // Clear all typing indicators for this user
+    const clearedConversations = ctx.store.clearAllTypingForUser(userId);
+    for (const convId of clearedConversations) {
+        ctx.broadcastAll(`conv:${convId}`, {
+            event: 'typing:update',
+            data: { conversationId: convId, userId, isTyping: false },
+        });
+    }
+    // If user has no more connected sockets, set presence to offline and broadcast
+    if (!ctx.store.isUserOnline(userId)) {
+        const entry = ctx.store.setPresence(userId, 'offline');
+        const payload = {
+            event: 'presence:changed',
+            data: { userId, status: 'offline', lastSeen: entry.lastSeen },
+        };
+        // Broadcast offline to all conversation rooms before cleaning up membership
+        for (const convId of ctx.store.getUserConversations(userId)) {
+            ctx.broadcastAll(`conv:${convId}`, payload);
+        }
+        ctx.store.removeUserFromAllConversations(userId);
+    }
+}

package/dist/communication/handlers.d.ts

@@ -0,0 +1,5 @@
+export type { HandlerContext } from './handlers/context.js';
+export { handleConversationCreate, handleConversationJoin, handleConversationLeave, handleConversationArchive, handleConversationMute, handleConversationPin, } from './handlers/conversation.js';
+export { handleMessageSend, handleMessageRead, handleMessageReact, handleMessageEdit, handleMessageDelete, handleMessageForward, } from './handlers/messaging.js';
+export { handleTypingStart, handleTypingStop, handleConnect, handlePresenceUpdate, handleDisconnect, } from './handlers/presence.js';
+export { handleFileUploadRequest } from './handlers/file-upload.js';

package/dist/communication/handlers.js

@@ -0,0 +1,5 @@
+// Barrel re-export — keeps the public API identical for all existing consumers.
+export { handleConversationCreate, handleConversationJoin, handleConversationLeave, handleConversationArchive, handleConversationMute, handleConversationPin, } from './handlers/conversation.js';
+export { handleMessageSend, handleMessageRead, handleMessageReact, handleMessageEdit, handleMessageDelete, handleMessageForward, } from './handlers/messaging.js';
+export { handleTypingStart, handleTypingStop, handleConnect, handlePresenceUpdate, handleDisconnect, } from './handlers/presence.js';
+export { handleFileUploadRequest } from './handlers/file-upload.js';

package/dist/communication/index.d.ts

@@ -0,0 +1,9 @@
+export type { CommunicationConfig, RTCIceServerConfig, MediaConstraintDefaults, MediaTrackConstraintSet, Conversation, Participant, PresenceStatus, PresenceUpdate, Message, MessageStatus, MessageAttachment, ReadReceipt, TypingIndicator, MessageForward, CallType, CallState, CallEndReason, Call, CallParticipant, SignalOffer, SignalIceCandidate, SignalIceRestart, ConnectionQualityReport, CallInitiate, CallResponse, CallHangup, CallMediaToggle, CommunicationClientEvents, CommunicationServerEvents, RateLimitConfig, FileUploadConfig, ReconnectionConfig, EncryptionConfig, PreKey, KeyBundle, EncryptedEnvelope, KeyExchangeRequest, KeyExchangeResponse, NkCommunication, } from './types.js';
+export { CommunicationStore, useCommunicationStore } from './store.js';
+export type { PresenceEntry } from './store.js';
+export type { HandlerContext } from './handlers.js';
+export type { SignalingContext } from './signaling.js';
+export type { EncryptionContext } from './encryption.js';
+export { createCommunicationHandler, createCommunicationApiHandlers } from './server.js';
+export type { CommunicationHandlerOptions } from './server.js';
+export { ensureCommunicationTables } from './schema.js';

package/dist/communication/index.js

@@ -0,0 +1,7 @@
+// ── Types ─────────────────────────────────────────────────────────
+// ── Store ─────────────────────────────────────────────────────────
+export { CommunicationStore, useCommunicationStore } from './store.js';
+// ── Server (main entry points) ────────────────────────────────────
+export { createCommunicationHandler, createCommunicationApiHandlers } from './server.js';
+// ── Schema ────────────────────────────────────────────────────────
+export { ensureCommunicationTables } from './schema.js';

package/dist/communication/link-preview.d.ts

@@ -0,0 +1,18 @@
+interface LinkPreview {
+    url: string;
+    title: string | null;
+    description: string | null;
+    image: string | null;
+    domain: string;
+}
+interface Db {
+    get<T = any>(sql: string, ...params: any[]): Promise<T | undefined>;
+    run(sql: string, ...params: any[]): Promise<any>;
+}
+/**
+ * Fetch Open Graph metadata from a URL and cache it.
+ */
+export declare function fetchLinkPreview(url: string, db?: Db): Promise<LinkPreview | null>;
+/** Extract URLs from message text */
+export declare function extractUrls(text: string): string[];
+export {};

package/dist/communication/link-preview.js

@@ -0,0 +1,115 @@
+import crypto from 'node:crypto';
+function isPrivateUrl(urlStr) {
+    try {
+        const parsed = new URL(urlStr);
+        // Only allow http/https schemes
+        if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')
+            return true;
+        const hostname = parsed.hostname.toLowerCase();
+        // Loopback and unspecified addresses
+        if (hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '[::1]' || hostname === '0.0.0.0')
+            return true;
+        // Single-label hostnames (no dots)
+        if (!hostname.includes('.'))
+            return true;
+        // Cloud metadata endpoints
+        if (hostname === 'metadata.google.internal' || hostname === 'metadata.internal')
+            return true;
+        // IPv6 addresses — block all private/reserved ranges
+        if (hostname.startsWith('[')) {
+            const ipv6 = hostname.slice(1, -1).toLowerCase();
+            if (ipv6 === '::1' || ipv6 === '::' || ipv6.startsWith('fe80:') || ipv6.startsWith('fd') || ipv6.startsWith('fc'))
+                return true;
+            return true; // Block all bracketed IPv6 for safety
+        }
+        // IPv4 private ranges
+        const parts = hostname.split('.').map(Number);
+        if (parts.length === 4 && parts.every(n => !isNaN(n))) {
+            if (parts[0] === 10)
+                return true;
+            if (parts[0] === 172 && parts[1] >= 16 && parts[1] <= 31)
+                return true;
+            if (parts[0] === 192 && parts[1] === 168)
+                return true;
+            if (parts[0] === 169 && parts[1] === 254)
+                return true; // link-local + cloud metadata
+            if (parts[0] === 0)
+                return true;
+            if (parts[0] === 127)
+                return true; // full loopback range
+        }
+        return false;
+    }
+    catch {
+        return true;
+    }
+}
+/**
+ * Fetch Open Graph metadata from a URL and cache it.
+ */
+export async function fetchLinkPreview(url, db) {
+    if (isPrivateUrl(url))
+        return null;
+    const urlHash = crypto.createHash('sha256').update(url).digest('hex').slice(0, 16);
+    // Check cache
+    if (db) {
+        const cached = await db.get('SELECT * FROM link_previews WHERE url_hash = ?', urlHash);
+        if (cached) {
+            return { url: cached.url, title: cached.title, description: cached.description, image: cached.image, domain: cached.domain };
+        }
+    }
+    try {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 5000);
+        const res = await fetch(url, {
+            headers: { 'User-Agent': 'LumenJS LinkPreview/1.0' },
+            signal: controller.signal,
+            redirect: 'follow',
+        });
+        clearTimeout(timeout);
+        // Re-check final URL after redirects to prevent SSRF via redirect
+        if (res.url && res.url !== url && isPrivateUrl(res.url))
+            return null;
+        if (!res.ok)
+            return null;
+        const contentType = res.headers.get('content-type') || '';
+        if (!contentType.includes('text/html'))
+            return null;
+        const html = await res.text();
+        const domain = new URL(url).hostname;
+        const title = extractMeta(html, 'og:title') || extractTag(html, 'title');
+        const description = extractMeta(html, 'og:description') || extractMeta(html, 'description');
+        const image = extractMeta(html, 'og:image');
+        const preview = { url, title, description, image, domain };
+        // Cache
+        if (db) {
+            await db.run('INSERT OR REPLACE INTO link_previews (url_hash, url, title, description, image, domain) VALUES (?, ?, ?, ?, ?, ?)', urlHash, url, title, description, image, domain);
+        }
+        return preview;
+    }
+    catch {
+        return null;
+    }
+}
+/** Extract URLs from message text */
+export function extractUrls(text) {
+    const regex = /https?:\/\/[^\s<>"')\]]+/g;
+    const matches = text.match(regex);
+    return matches ? [...new Set(matches)].slice(0, 3) : [];
+}
+function extractMeta(html, name) {
+    // Match <meta property="og:title" content="..."> or <meta name="description" content="...">
+    const regex = new RegExp(`<meta[^>]+(?:property|name)=["']${name}["'][^>]+content=["']([^"']+)["']`, 'i');
+    const match = html.match(regex);
+    if (match)
+        return match[1];
+    // Try reversed order: content before property
+    const regex2 = new RegExp(`<meta[^>]+content=["']([^"']+)["'][^>]+(?:property|name)=["']${name}["']`, 'i');
+    const match2 = html.match(regex2);
+    return match2 ? match2[1] : null;
+}
+function extractTag(html, tag) {
+    const regex = new RegExp(`<${tag}[^>]*>([^<]+)</${tag}>`, 'i');
+    const match = html.match(regex);
+    return match ? match[1].trim() : null;
+}

package/dist/communication/schema.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Communication module DB schema.
+ * Call ensureCommunicationTables(db) to create all required tables.
+ */
+interface Db {
+    exec(sql: string): Promise<void>;
+    isPg?: boolean;
+}
+export declare function ensureCommunicationTables(db: Db): Promise<void>;
+export {};

package/dist/communication/schema.js

@@ -0,0 +1,101 @@
+/**
+ * Communication module DB schema.
+ * Call ensureCommunicationTables(db) to create all required tables.
+ */
+export async function ensureCommunicationTables(db) {
+    if (db.isPg)
+        return;
+    await db.exec(`
+    CREATE TABLE IF NOT EXISTS conversations (
+      id TEXT PRIMARY KEY,
+      type TEXT NOT NULL CHECK(type IN ('direct', 'group')),
+      name TEXT,
+      created_at TEXT NOT NULL DEFAULT (datetime('now')),
+      updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+
+    CREATE TABLE IF NOT EXISTS conversation_participants (
+      conversation_id TEXT NOT NULL,
+      user_id TEXT NOT NULL,
+      role TEXT NOT NULL DEFAULT 'member',
+      joined_at TEXT NOT NULL DEFAULT (datetime('now')),
+      PRIMARY KEY (conversation_id, user_id),
+      FOREIGN KEY (conversation_id) REFERENCES conversations(id) ON DELETE CASCADE
+    );
+
+    CREATE TABLE IF NOT EXISTS messages (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      conversation_id TEXT NOT NULL,
+      sender_id TEXT NOT NULL,
+      content TEXT NOT NULL DEFAULT '',
+      type TEXT NOT NULL DEFAULT 'text',
+      reply_to TEXT,
+      attachment TEXT,
+      status TEXT NOT NULL DEFAULT 'sent',
+      encrypted INTEGER NOT NULL DEFAULT 0,
+      created_at TEXT NOT NULL DEFAULT (datetime('now')),
+      updated_at TEXT,
+      FOREIGN KEY (conversation_id) REFERENCES conversations(id) ON DELETE CASCADE
+    );
+
+    CREATE TABLE IF NOT EXISTS read_receipts (
+      message_id INTEGER NOT NULL,
+      user_id TEXT NOT NULL,
+      read_at TEXT NOT NULL DEFAULT (datetime('now')),
+      PRIMARY KEY (message_id, user_id),
+      FOREIGN KEY (message_id) REFERENCES messages(id) ON DELETE CASCADE
+    );
+
+    CREATE TABLE IF NOT EXISTS encryption_keys (
+      user_id TEXT PRIMARY KEY,
+      identity_key TEXT NOT NULL,
+      signed_pre_key_id INTEGER NOT NULL,
+      signed_pre_key TEXT NOT NULL,
+      signed_pre_key_signature TEXT NOT NULL,
+      uploaded_at TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+
+    CREATE TABLE IF NOT EXISTS encryption_prekeys (
+      user_id TEXT NOT NULL,
+      key_id INTEGER NOT NULL,
+      public_key TEXT NOT NULL,
+      PRIMARY KEY (user_id, key_id),
+      FOREIGN KEY (user_id) REFERENCES encryption_keys(user_id) ON DELETE CASCADE
+    );
+
+    CREATE TABLE IF NOT EXISTS message_reactions (
+      message_id INTEGER NOT NULL,
+      user_id TEXT NOT NULL,
+      emoji TEXT NOT NULL,
+      created_at TEXT NOT NULL DEFAULT (datetime('now')),
+      PRIMARY KEY (message_id, user_id, emoji),
+      FOREIGN KEY (message_id) REFERENCES messages(id) ON DELETE CASCADE
+    );
+
+    CREATE TABLE IF NOT EXISTS attachments (
+      id TEXT PRIMARY KEY,
+      filename TEXT NOT NULL,
+      mimetype TEXT NOT NULL,
+      size INTEGER NOT NULL,
+      url TEXT NOT NULL,
+      thumbnail_url TEXT,
+      uploaded_by TEXT NOT NULL,
+      encrypted INTEGER NOT NULL DEFAULT 0,
+      created_at TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+
+    CREATE TABLE IF NOT EXISTS link_previews (
+      url_hash TEXT PRIMARY KEY,
+      url TEXT NOT NULL,
+      title TEXT,
+      description TEXT,
+      image TEXT,
+      domain TEXT,
+      fetched_at TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_messages_conversation ON messages(conversation_id, created_at);
+    CREATE INDEX IF NOT EXISTS idx_participants_user ON conversation_participants(user_id);
+    CREATE INDEX IF NOT EXISTS idx_reactions_message ON message_reactions(message_id);
+  `);
+}

package/dist/communication/server.d.ts

@@ -0,0 +1,86 @@
+import type { CommunicationConfig } from './types.js';
+import type { LumenDb } from '../db/index.js';
+import type { StorageAdapter } from '../storage/adapters/types.js';
+/** Options for creating a communication socket handler */
+export interface CommunicationHandlerOptions {
+    /** Communication config overrides */
+    config?: Partial<CommunicationConfig>;
+    /** Extract userId from socket handshake headers/query. Default: reads X-User-Id header or userId query param */
+    getUserId?: (headers: Record<string, any>, query: Record<string, any>) => string | undefined;
+    /** LumenJS database instance — if provided, messages are persisted */
+    db?: LumenDb;
+    /**
+     * Storage adapter for chat file uploads.
+     * Falls back to the global singleton (useStorage()) if not provided.
+     * Required for file:request-upload support.
+     */
+    storage?: StorageAdapter;
+}
+/**
+ * Creates a LumenJS-compatible socket handler for communication.
+ *
+ * Usage in a page file:
+ * ```ts
+ * import { createCommunicationHandler } from '@nuraly/lumenjs/dist/communication/server.js';
+ * export const socket = createCommunicationHandler();
+ * ```
+ */
+export declare function createCommunicationHandler(options?: CommunicationHandlerOptions): (ctx: {
+    on: (event: string, handler: (...args: any[]) => void) => void;
+    push: (data: any) => void;
+    room: {
+        join: (name: string) => void;
+        leave: (name: string) => void;
+        broadcast: (name: string, data: any) => void;
+        broadcastAll: (name: string, data: any) => void;
+    };
+    params: Record<string, string>;
+    headers: Record<string, any>;
+    locale?: string;
+    socket: any;
+}) => (() => void) | undefined;
+/**
+ * Creates reusable API handler functions for communication REST endpoints.
+ *
+ * Usage in an API route:
+ * ```ts
+ * import { createCommunicationApiHandlers } from '@nuraly/lumenjs/dist/communication/server.js';
+ * import { useDb } from '@nuraly/lumenjs/dist/db/index.js';
+ *
+ * const communication = createCommunicationApiHandlers(useDb());
+ *
+ * export function GET(req) {
+ *   return communication.getConversations(req.query.userId);
+ * }
+ * ```
+ */
+export declare function createCommunicationApiHandlers(db: LumenDb): {
+    /** List conversations for a user */
+    getConversations(userId: string, opts?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<any[]>;
+    /** Get paginated message history for a conversation */
+    getMessages(conversationId: string, opts?: {
+        limit?: number;
+        before?: string;
+    }): Promise<any[]>;
+    /** Create a new conversation */
+    createConversation(data: {
+        type: "direct" | "group";
+        name?: string;
+        participantIds: string[];
+    }): Promise<any>;
+    /** Search messages by content */
+    searchMessages(query: string, opts?: {
+        conversationId?: string;
+        limit?: number;
+    }): Promise<any[]>;
+    /** Get a single message by ID */
+    getMessage(messageId: string): Promise<any>;
+    /** Delete a message (soft delete by setting content to empty) */
+    deleteMessage(messageId: string, userId: string): Promise<{
+        changes: number;
+        lastInsertRowid: number | bigint;
+    }>;
+};

package/dist/communication/server.js

@@ -0,0 +1,212 @@
+import { useCommunicationStore } from './store.js';
+import { handleConversationCreate, handleConversationJoin, handleConversationLeave, handleConversationArchive, handleConversationMute, handleConversationPin, handleMessageSend, handleMessageRead, handleMessageReact, handleMessageEdit, handleMessageDelete, handleMessageForward, handleTypingStart, handleTypingStop, handlePresenceUpdate, handleConnect, handleDisconnect, handleFileUploadRequest, } from './handlers.js';
+import { handleCallInitiate, handleCallRespond, handleCallHangup, handleCallMediaToggle, handleCallAddParticipant, handleCallRemoveParticipant, handleSignalOffer, handleSignalAnswer, handleSignalIceCandidate, handleSignalIceRestart, handleCallQualityReport, } from './signaling.js';
+import { handleUploadKeys, handleRequestKeys, handleSessionInit, } from './encryption.js';
+import { useStorage } from '../storage/index.js';
+const defaultGetUserId = (headers, query) => {
+    return headers['x-user-id'] || query.userId || undefined;
+};
+/**
+ * Creates a LumenJS-compatible socket handler for communication.
+ *
+ * Usage in a page file:
+ * ```ts
+ * import { createCommunicationHandler } from '@nuraly/lumenjs/dist/communication/server.js';
+ * export const socket = createCommunicationHandler();
+ * ```
+ */
+export function createCommunicationHandler(options = {}) {
+    const getUserId = options.getUserId || defaultGetUserId;
+    const store = useCommunicationStore();
+    const resolvedConfig = { ...options.config };
+    // Apply configurable typing timeout to the store
+    if (resolvedConfig.typingTimeoutMs != null) {
+        store.typingTimeoutMs = resolvedConfig.typingTimeoutMs;
+    }
+    return (ctx) => {
+        const query = ctx.socket?.handshake?.query || {};
+        const userId = getUserId(ctx.headers, query);
+        if (!userId) {
+            console.warn('[LumenJS:Communication] No userId found in socket handshake. Connection rejected.');
+            ctx.socket?.disconnect?.();
+            return;
+        }
+        const socketId = ctx.socket?.id || crypto.randomUUID();
+        // Register socket and check if this is the user's first connection
+        const isFirstSocket = !store.isUserOnline(userId);
+        store.mapUserSocket(userId, socketId);
+        store.setPresence(userId, 'online');
+        // Build handler context
+        const handlerCtx = {
+            userId,
+            store,
+            config: resolvedConfig,
+            push: ctx.push,
+            broadcastAll: ctx.room.broadcastAll,
+            broadcast: ctx.room.broadcast,
+            joinRoom: ctx.room.join,
+            leaveRoom: ctx.room.leave,
+            emitToUser: (targetUserId, data) => {
+                const sockets = store.getSocketsForUser(targetUserId);
+                const io = ctx.socket?.nsp;
+                if (io) {
+                    for (const sid of sockets) {
+                        io.to(sid).emit('nk:data', data);
+                    }
+                }
+            },
+            db: options.db,
+            storage: options.storage ?? useStorage() ?? undefined,
+        };
+        // Build signaling context
+        const signalingCtx = {
+            userId,
+            store,
+            emitToSocket: (sid, data) => {
+                // For targeted emit, we use the raw socket.io namespace
+                const io = ctx.socket?.nsp;
+                if (io) {
+                    io.to(sid).emit('nk:data', data);
+                }
+            },
+            broadcastAll: ctx.room.broadcastAll,
+        };
+        // Broadcast online status if this is the user's first socket
+        if (isFirstSocket) {
+            handleConnect(handlerCtx);
+        }
+        // ── Payload Validation ────────────────────────────────────
+        /** Validate socket event payload is a non-null object with expected string fields. */
+        function validated(data, requiredStrings, handler) {
+            if (!data || typeof data !== 'object')
+                return;
+            for (const field of requiredStrings) {
+                if (typeof data[field] !== 'string' || data[field].length === 0)
+                    return;
+            }
+            handler(data);
+        }
+        // ── Chat Events ──────────────────────────────────────────
+        ctx.on('conversation:create', (data) => validated(data, ['type'], () => handleConversationCreate(handlerCtx, data)));
+        ctx.on('conversation:join', (data) => validated(data, ['conversationId'], () => handleConversationJoin(handlerCtx, data)));
+        ctx.on('conversation:leave', (data) => validated(data, ['conversationId'], () => handleConversationLeave(handlerCtx, data)));
+        ctx.on('conversation:archive', (data) => validated(data, ['conversationId'], () => handleConversationArchive(handlerCtx, data)));
+        ctx.on('conversation:mute', (data) => validated(data, ['conversationId'], () => handleConversationMute(handlerCtx, data)));
+        ctx.on('conversation:pin', (data) => validated(data, ['conversationId'], () => handleConversationPin(handlerCtx, data)));
+        ctx.on('message:send', (data) => validated(data, ['conversationId', 'content'], () => handleMessageSend(handlerCtx, data)));
+        ctx.on('message:react', (data) => validated(data, ['messageId', 'conversationId', 'emoji'], () => handleMessageReact(handlerCtx, data)));
+        ctx.on('message:edit', (data) => validated(data, ['messageId', 'conversationId', 'content'], () => handleMessageEdit(handlerCtx, data)));
+        ctx.on('message:delete', (data) => validated(data, ['messageId', 'conversationId'], () => handleMessageDelete(handlerCtx, data)));
+        ctx.on('message:read', (data) => validated(data, ['messageId', 'conversationId'], () => handleMessageRead(handlerCtx, data)));
+        ctx.on('message:forward', (data) => validated(data, ['messageId', 'fromConversationId', 'toConversationId'], () => handleMessageForward(handlerCtx, data)));
+        ctx.on('typing:start', (data) => validated(data, ['conversationId'], () => handleTypingStart(handlerCtx, data)));
+        ctx.on('typing:stop', (data) => validated(data, ['conversationId'], () => handleTypingStop(handlerCtx, data)));
+        ctx.on('presence:update', (data) => validated(data, ['status'], () => handlePresenceUpdate(handlerCtx, data)));
+        // ── Call Events ──────────────────────────────────────────
+        ctx.on('call:initiate', (data) => handleCallInitiate(signalingCtx, data));
+        ctx.on('call:respond', (data) => handleCallRespond(signalingCtx, data));
+        ctx.on('call:hangup', (data) => handleCallHangup(signalingCtx, data));
+        ctx.on('call:media-toggle', (data) => handleCallMediaToggle(signalingCtx, data));
+        ctx.on('call:add-participant', (data) => handleCallAddParticipant(signalingCtx, data));
+        ctx.on('call:remove-participant', (data) => handleCallRemoveParticipant(signalingCtx, data));
+        // ── WebRTC Signaling ─────────────────────────────────────
+        ctx.on('signal:offer', (data) => handleSignalOffer(signalingCtx, data));
+        ctx.on('signal:answer', (data) => handleSignalAnswer(signalingCtx, data));
+        ctx.on('signal:ice-candidate', (data) => handleSignalIceCandidate(signalingCtx, data));
+        ctx.on('signal:ice-restart', (data) => handleSignalIceRestart(signalingCtx, data));
+        ctx.on('call:quality-report', (data) => handleCallQualityReport(signalingCtx, data));
+        // ── E2E Encryption ─────────────────────────────────────────
+        const encryptionCtx = {
+            userId,
+            store,
+            push: ctx.push,
+            emitToUser: (targetUserId, data) => {
+                const sockets = store.getSocketsForUser(targetUserId);
+                const io = ctx.socket?.nsp;
+                if (io) {
+                    for (const sid of sockets) {
+                        io.to(sid).emit('nk:data', data);
+                    }
+                }
+            },
+            db: options.db,
+        };
+        ctx.on('encryption:upload-keys', (data) => handleUploadKeys(encryptionCtx, data));
+        ctx.on('encryption:request-keys', (data) => handleRequestKeys(encryptionCtx, data));
+        ctx.on('encryption:session-init', (data) => handleSessionInit(encryptionCtx, data));
+        // ── File Upload ───────────────────────────────────────────
+        ctx.on('file:request-upload', (data) => handleFileUploadRequest(handlerCtx, data));
+        // ── Cleanup on Disconnect ────────────────────────────────
+        return () => {
+            handleDisconnect(handlerCtx, socketId);
+        };
+    };
+}
+/**
+ * Creates reusable API handler functions for communication REST endpoints.
+ *
+ * Usage in an API route:
+ * ```ts
+ * import { createCommunicationApiHandlers } from '@nuraly/lumenjs/dist/communication/server.js';
+ * import { useDb } from '@nuraly/lumenjs/dist/db/index.js';
+ *
+ * const communication = createCommunicationApiHandlers(useDb());
+ *
+ * export function GET(req) {
+ *   return communication.getConversations(req.query.userId);
+ * }
+ * ```
+ */
+export function createCommunicationApiHandlers(db) {
+    return {
+        /** List conversations for a user */
+        async getConversations(userId, opts) {
+            const limit = opts?.limit || 50;
+            const offset = opts?.offset || 0;
+            return db.all(`SELECT c.*,
+                (SELECT COUNT(*) FROM messages m WHERE m.conversation_id = c.id
+                 AND m.id NOT IN (SELECT message_id FROM read_receipts WHERE user_id = ?)) as unread_count
+         FROM conversations c
+         JOIN conversation_participants cp ON cp.conversation_id = c.id
+         WHERE cp.user_id = ?
+         ORDER BY c.updated_at DESC
+         LIMIT ? OFFSET ?`, userId, userId, limit, offset);
+        },
+        /** Get paginated message history for a conversation */
+        async getMessages(conversationId, opts) {
+            const limit = opts?.limit || 50;
+            if (opts?.before) {
+                return db.all(`SELECT * FROM messages WHERE conversation_id = ? AND created_at < ?
+           ORDER BY created_at DESC LIMIT ?`, conversationId, opts.before, limit);
+            }
+            return db.all(`SELECT * FROM messages WHERE conversation_id = ?
+         ORDER BY created_at DESC LIMIT ?`, conversationId, limit);
+        },
+        /** Create a new conversation */
+        async createConversation(data) {
+            const now = new Date().toISOString();
+            const convId = crypto.randomUUID();
+            await db.run(`INSERT INTO conversations (id, type, name, created_at, updated_at) VALUES (?, ?, ?, ?, ?)`, convId, data.type, data.name || null, now, now);
+            for (const uid of data.participantIds) {
+                await db.run(`INSERT INTO conversation_participants (conversation_id, user_id, role, joined_at) VALUES (?, ?, 'member', ?)`, convId, uid, now);
+            }
+            return db.get(`SELECT * FROM conversations WHERE id = ?`, convId);
+        },
+        /** Search messages by content */
+        async searchMessages(query, opts) {
+            const limit = opts?.limit || 20;
+            if (opts?.conversationId) {
+                return db.all(`SELECT * FROM messages WHERE conversation_id = ? AND content LIKE ? ORDER BY created_at DESC LIMIT ?`, opts.conversationId, `%${query}%`, limit);
+            }
+            return db.all(`SELECT * FROM messages WHERE content LIKE ? ORDER BY created_at DESC LIMIT ?`, `%${query}%`, limit);
+        },
+        /** Get a single message by ID */
+        async getMessage(messageId) {
+            return db.get(`SELECT * FROM messages WHERE id = ?`, messageId);
+        },
+        /** Delete a message (soft delete by setting content to empty) */
+        async deleteMessage(messageId, userId) {
+            return db.run(`UPDATE messages SET content = '', type = 'system', updated_at = ? WHERE id = ? AND sender_id = ?`, new Date().toISOString(), messageId, userId);
+        },
+    };
+}