@nuraly/lumenjs 0.1.3 → 0.1.4

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);
+        },
+    };
+}

package/dist/communication/signaling.d.ts

@@ -0,0 +1,43 @@
+import type { CallType, CallEndReason, SignalOffer, SignalIceCandidate, SignalIceRestart, ConnectionQualityReport } from './types.js';
+import type { CommunicationStore } from './store.js';
+/** Context for signaling handlers */
+export interface SignalingContext {
+    userId: string;
+    store: CommunicationStore;
+    /** Emit to a specific socket by ID */
+    emitToSocket: (socketId: string, data: any) => void;
+    /** Broadcast to all sockets in a room */
+    broadcastAll: (room: string, data: any) => void;
+}
+export declare function handleCallInitiate(ctx: SignalingContext, data: {
+    conversationId: string;
+    type: CallType;
+    calleeIds: string[];
+}): void;
+export declare function handleCallRespond(ctx: SignalingContext, data: {
+    callId: string;
+    action: 'accept' | 'reject';
+}): void;
+export declare function handleCallHangup(ctx: SignalingContext, data: {
+    callId: string;
+    reason: CallEndReason;
+}): void;
+export declare function handleCallMediaToggle(ctx: SignalingContext, data: {
+    callId: string;
+    audio?: boolean;
+    video?: boolean;
+    screenShare?: boolean;
+}): void;
+export declare function handleCallAddParticipant(ctx: SignalingContext, data: {
+    callId: string;
+    userId: string;
+}): void;
+export declare function handleCallRemoveParticipant(ctx: SignalingContext, data: {
+    callId: string;
+    userId: string;
+}): void;
+export declare function handleSignalOffer(ctx: SignalingContext, data: SignalOffer): void;
+export declare function handleSignalAnswer(ctx: SignalingContext, data: SignalOffer): void;
+export declare function handleSignalIceCandidate(ctx: SignalingContext, data: SignalIceCandidate): void;
+export declare function handleSignalIceRestart(ctx: SignalingContext, data: SignalIceRestart): void;
+export declare function handleCallQualityReport(ctx: SignalingContext, data: ConnectionQualityReport): void;

package/dist/communication/signaling.js

@@ -0,0 +1,271 @@
+/** Emit data to all sockets belonging to a user */
+function emitToUser(ctx, targetUserId, data) {
+    const sockets = ctx.store.getSocketsForUser(targetUserId);
+    for (const sid of sockets) {
+        ctx.emitToSocket(sid, data);
+    }
+}
+// ── Call Lifecycle ───────────────────────────────────────────────
+export function handleCallInitiate(ctx, data) {
+    // Check if caller is already in a call
+    const existingCall = ctx.store.getActiveCallForUser(ctx.userId);
+    if (existingCall) {
+        emitToUser(ctx, ctx.userId, {
+            event: 'call:state-changed',
+            data: { callId: existingCall.id, state: existingCall.state, error: 'already_in_call' },
+        });
+        return;
+    }
+    const callId = crypto.randomUUID();
+    const now = new Date().toISOString();
+    const call = {
+        id: callId,
+        conversationId: data.conversationId,
+        type: data.type,
+        state: 'initiating',
+        callerId: ctx.userId,
+        calleeIds: data.calleeIds,
+        startedAt: now,
+        participants: [{
+                userId: ctx.userId,
+                joinedAt: now,
+                audioMuted: false,
+                videoMuted: data.type === 'audio',
+                screenSharing: false,
+            }],
+    };
+    ctx.store.addCall(call);
+    // Notify caller that call is initiating
+    emitToUser(ctx, ctx.userId, {
+        event: 'call:state-changed',
+        data: { callId, state: 'initiating' },
+    });
+    // Notify each callee with incoming call
+    for (const calleeId of data.calleeIds) {
+        // Check if callee is busy (exclude the current call being initiated)
+        const calleeActiveCall = ctx.store.getActiveCallForUser(calleeId);
+        if (calleeActiveCall && calleeActiveCall.id !== callId) {
+            emitToUser(ctx, ctx.userId, {
+                event: 'call:state-changed',
+                data: { callId, state: 'ended', endReason: 'busy' },
+            });
+            ctx.store.updateCallState(callId, 'ended', 'busy');
+            ctx.store.removeCall(callId);
+            return;
+        }
+        emitToUser(ctx, calleeId, { event: 'call:incoming', data: call });
+    }
+    // Update state to ringing
+    ctx.store.updateCallState(callId, 'ringing');
+}
+export function handleCallRespond(ctx, data) {
+    const call = ctx.store.getCall(data.callId);
+    if (!call)
+        return;
+    if (data.action === 'reject') {
+        ctx.store.updateCallState(data.callId, 'ended', 'rejected');
+        // Notify all parties
+        emitToUser(ctx, call.callerId, {
+            event: 'call:state-changed',
+            data: { callId: data.callId, state: 'ended', endReason: 'rejected' },
+        });
+        emitToUser(ctx, ctx.userId, {
+            event: 'call:state-changed',
+            data: { callId: data.callId, state: 'ended', endReason: 'rejected' },
+        });
+        ctx.store.removeCall(data.callId);
+        return;
+    }
+    // Accept — add callee as participant
+    const now = new Date().toISOString();
+    const participant = {
+        userId: ctx.userId,
+        joinedAt: now,
+        audioMuted: false,
+        videoMuted: call.type === 'audio',
+        screenSharing: false,
+    };
+    ctx.store.addCallParticipant(data.callId, participant);
+    ctx.store.updateCallState(data.callId, 'connecting');
+    // Notify caller that callee accepted
+    emitToUser(ctx, call.callerId, {
+        event: 'call:participant-joined',
+        data: { callId: data.callId, participant },
+    });
+    emitToUser(ctx, call.callerId, {
+        event: 'call:state-changed',
+        data: { callId: data.callId, state: 'connecting' },
+    });
+    // Notify callee of connecting state
+    emitToUser(ctx, ctx.userId, {
+        event: 'call:state-changed',
+        data: { callId: data.callId, state: 'connecting' },
+    });
+}
+export function handleCallHangup(ctx, data) {
+    const call = ctx.store.getCall(data.callId);
+    if (!call)
+        return;
+    // Remove the user who hung up
+    ctx.store.removeCallParticipant(data.callId, ctx.userId);
+    // Notify other participants
+    for (const p of call.participants) {
+        if (p.userId === ctx.userId)
+            continue;
+        emitToUser(ctx, p.userId, {
+            event: 'call:participant-left',
+            data: { callId: data.callId, userId: ctx.userId },
+        });
+    }
+    // Also notify caller/callees who may not be in participants yet (e.g., still ringing)
+    const allUsers = new Set([call.callerId, ...call.calleeIds]);
+    allUsers.delete(ctx.userId);
+    // If no participants left (or only one), end the call
+    const remainingParticipants = call.participants.filter(p => p.userId !== ctx.userId);
+    if (remainingParticipants.length <= 1) {
+        ctx.store.updateCallState(data.callId, 'ended', data.reason);
+        for (const uid of allUsers) {
+            emitToUser(ctx, uid, {
+                event: 'call:state-changed',
+                data: { callId: data.callId, state: 'ended', endReason: data.reason },
+            });
+        }
+        ctx.store.removeCall(data.callId);
+    }
+}
+export function handleCallMediaToggle(ctx, data) {
+    const call = ctx.store.getCall(data.callId);
+    if (!call)
+        return;
+    const participant = call.participants.find(p => p.userId === ctx.userId);
+    if (!participant)
+        return;
+    if (data.audio !== undefined)
+        participant.audioMuted = !data.audio;
+    if (data.video !== undefined)
+        participant.videoMuted = !data.video;
+    if (data.screenShare !== undefined)
+        participant.screenSharing = data.screenShare;
+    // Notify all other participants
+    for (const p of call.participants) {
+        if (p.userId === ctx.userId)
+            continue;
+        emitToUser(ctx, p.userId, {
+            event: 'call:media-changed',
+            data: {
+                callId: data.callId,
+                userId: ctx.userId,
+                audio: data.audio,
+                video: data.video,
+                screenShare: data.screenShare,
+            },
+        });
+    }
+}
+// ── Mid-Call Participant Management ──────────────────────────────
+export function handleCallAddParticipant(ctx, data) {
+    const call = ctx.store.getCall(data.callId);
+    if (!call)
+        return;
+    // Only existing participants can add someone
+    const isParticipant = call.participants.some(p => p.userId === ctx.userId);
+    if (!isParticipant)
+        return;
+    // Don't add someone already in the call
+    if (call.participants.some(p => p.userId === data.userId))
+        return;
+    // Check if the target user is already in another call
+    const targetActiveCall = ctx.store.getActiveCallForUser(data.userId);
+    if (targetActiveCall) {
+        emitToUser(ctx, ctx.userId, {
+            event: 'call:state-changed',
+            data: { callId: data.callId, state: call.state, error: 'user_busy' },
+        });
+        return;
+    }
+    // Add to calleeIds so they are tracked
+    if (!call.calleeIds.includes(data.userId)) {
+        call.calleeIds.push(data.userId);
+    }
+    // Send incoming call notification to the new user
+    emitToUser(ctx, data.userId, { event: 'call:incoming', data: call });
+}
+export function handleCallRemoveParticipant(ctx, data) {
+    const call = ctx.store.getCall(data.callId);
+    if (!call)
+        return;
+    // Only the caller (owner) or admins can kick participants
+    if (ctx.userId !== call.callerId)
+        return;
+    // Can't remove yourself (use hangup instead)
+    if (data.userId === ctx.userId)
+        return;
+    // Check the target is actually in the call
+    const targetParticipant = call.participants.find(p => p.userId === data.userId);
+    if (!targetParticipant)
+        return;
+    ctx.store.removeCallParticipant(data.callId, data.userId);
+    // Notify all remaining participants
+    for (const p of call.participants) {
+        if (p.userId === data.userId)
+            continue;
+        emitToUser(ctx, p.userId, {
+            event: 'call:participant-left',
+            data: { callId: data.callId, userId: data.userId },
+        });
+    }
+    // Notify the removed user
+    emitToUser(ctx, data.userId, {
+        event: 'call:participant-left',
+        data: { callId: data.callId, userId: data.userId },
+    });
+    emitToUser(ctx, data.userId, {
+        event: 'call:state-changed',
+        data: { callId: data.callId, state: 'ended', endReason: 'completed' },
+    });
+}
+// ── WebRTC Signal Relay ─────────────────────────────────────────
+/** Verify the sender is part of an active call with the target user. */
+function verifyCallMembership(ctx, fromUserId, toUserId) {
+    // Ensure fromUserId matches the authenticated user
+    if (fromUserId !== ctx.userId)
+        return false;
+    // Check both users are participants in the same active call
+    const call = ctx.store.getActiveCallForUser(ctx.userId);
+    if (!call)
+        return false;
+    const isTarget = call.callerId === toUserId || call.calleeIds.includes(toUserId) ||
+        call.participants.some(p => p.userId === toUserId);
+    return isTarget;
+}
+export function handleSignalOffer(ctx, data) {
+    if (!verifyCallMembership(ctx, data.fromUserId, data.toUserId))
+        return;
+    emitToUser(ctx, data.toUserId, { event: 'signal:offer', data });
+}
+export function handleSignalAnswer(ctx, data) {
+    if (!verifyCallMembership(ctx, data.fromUserId, data.toUserId))
+        return;
+    emitToUser(ctx, data.toUserId, { event: 'signal:answer', data });
+}
+export function handleSignalIceCandidate(ctx, data) {
+    if (!verifyCallMembership(ctx, data.fromUserId, data.toUserId))
+        return;
+    emitToUser(ctx, data.toUserId, { event: 'signal:ice-candidate', data });
+}
+export function handleSignalIceRestart(ctx, data) {
+    if (!verifyCallMembership(ctx, data.fromUserId, data.toUserId))
+        return;
+    emitToUser(ctx, data.toUserId, { event: 'signal:ice-restart', data });
+}
+export function handleCallQualityReport(ctx, data) {
+    const call = ctx.store.getCall(data.callId);
+    if (!call)
+        return;
+    // Broadcast quality report to all other participants in the call
+    for (const p of call.participants) {
+        if (p.userId === ctx.userId)
+            continue;
+        emitToUser(ctx, p.userId, { event: 'call:quality-changed', data });
+    }
+}