@nuraly/lumenjs 0.1.3 → 0.2.0

package/dist/communication/types.d.ts

@@ -0,0 +1,454 @@
+import type { StorageAdapter } from '../storage/adapters/types.js';
+export interface CommunicationConfig {
+    /** Socket.io namespace for communication events (default: '/nk/communication') */
+    namespace?: string;
+    /** WebRTC ICE/TURN server configuration */
+    iceServers?: RTCIceServerConfig[];
+    /** Default media constraints for calls */
+    mediaConstraints?: MediaConstraintDefaults;
+    /** Maximum message length in characters */
+    maxMessageLength?: number;
+    /** Enable read receipts globally */
+    readReceipts?: boolean;
+    /** Enable typing indicators globally */
+    typingIndicators?: boolean;
+    /** Message history page size */
+    pageSize?: number;
+    /** End-to-end encryption settings */
+    encryption?: EncryptionConfig;
+    /** Rate limiting for message sends */
+    rateLimit?: RateLimitConfig;
+    /** File upload constraints */
+    fileUpload?: FileUploadConfig;
+    /** Typing indicator timeout in ms. Default: 5000 */
+    typingTimeoutMs?: number;
+    /** Message retention in days. 0 = keep forever. Default: 0 */
+    messageRetentionDays?: number;
+    /** Socket reconnection config */
+    reconnection?: ReconnectionConfig;
+    /** Storage adapter for chat file uploads. Required for file:request-upload support. */
+    storage?: StorageAdapter;
+}
+export interface RateLimitConfig {
+    /** Max messages per window. Default: 30 */
+    maxMessages: number;
+    /** Window duration in seconds. Default: 60 */
+    windowSeconds: number;
+}
+export interface FileUploadConfig {
+    /** Maximum file size in bytes. Default: 25MB (26214400) */
+    maxFileSize: number;
+    /** Maximum attachments per message. Default: 10 */
+    maxAttachmentsPerMessage: number;
+    /** Allowed MIME types. Empty array = allow all. Default: common image/video/document types */
+    allowedMimeTypes?: string[];
+}
+export interface ReconnectionConfig {
+    /** Max reconnection attempts. Default: 10 */
+    maxRetries: number;
+    /** Base delay between retries in ms. Default: 1000 */
+    baseDelayMs: number;
+    /** Max delay cap in ms. Default: 30000 */
+    maxDelayMs: number;
+}
+export interface EncryptionConfig {
+    /** Enable E2E encryption for messages */
+    enabled: boolean;
+    /** How often clients should rotate pre-keys (ms). Default: 7 days */
+    keyRotationInterval?: number;
+    /** Number of one-time pre-keys each client should upload. Default: 100 */
+    oneTimePreKeyCount?: number;
+}
+export interface RTCIceServerConfig {
+    urls: string | string[];
+    username?: string;
+    credential?: string;
+}
+export interface MediaConstraintDefaults {
+    audio?: boolean | MediaTrackConstraintSet;
+    video?: boolean | MediaTrackConstraintSet;
+}
+export interface MediaTrackConstraintSet {
+    width?: number | {
+        min?: number;
+        max?: number;
+        ideal?: number;
+    };
+    height?: number | {
+        min?: number;
+        max?: number;
+        ideal?: number;
+    };
+    frameRate?: number | {
+        min?: number;
+        max?: number;
+        ideal?: number;
+    };
+    facingMode?: string;
+    echoCancellation?: boolean;
+    noiseSuppression?: boolean;
+}
+export interface Conversation {
+    id: string;
+    type: 'direct' | 'group';
+    name?: string;
+    participants: Participant[];
+    lastMessage?: Message;
+    createdAt: string;
+    updatedAt: string;
+    unreadCount: number;
+    pinned?: boolean;
+    muted?: boolean;
+    archived?: boolean;
+}
+export interface Participant {
+    userId: string;
+    displayName: string;
+    avatarUrl?: string;
+    role?: 'owner' | 'admin' | 'member';
+    joinedAt: string;
+    presence: PresenceStatus;
+}
+export type PresenceStatus = 'online' | 'offline' | 'away' | 'busy';
+export interface PresenceUpdate {
+    userId: string;
+    status: PresenceStatus;
+    lastSeen?: string;
+}
+export interface Message {
+    id: string;
+    conversationId: string;
+    senderId: string;
+    content: string;
+    type: 'text' | 'image' | 'file' | 'audio' | 'system';
+    createdAt: string;
+    updatedAt?: string;
+    replyTo?: string;
+    attachment?: MessageAttachment;
+    status: MessageStatus;
+    readBy: ReadReceipt[];
+    /** Whether this message is end-to-end encrypted */
+    encrypted?: boolean;
+    /** Encrypted envelope — present when encrypted is true. Server stores this as opaque blob. */
+    envelope?: EncryptedEnvelope;
+}
+export type MessageStatus = 'sending' | 'sent' | 'delivered' | 'read' | 'failed';
+export interface MessageAttachment {
+    url: string;
+    mimeType: string;
+    fileName: string;
+    fileSize: number;
+    width?: number;
+    height?: number;
+    /** Audio/video duration in seconds */
+    duration?: number;
+    thumbnailUrl?: string;
+}
+export interface ReadReceipt {
+    userId: string;
+    readAt: string;
+}
+export interface TypingIndicator {
+    conversationId: string;
+    userId: string;
+    isTyping: boolean;
+}
+export interface MessageForward {
+    messageId: string;
+    fromConversationId: string;
+    toConversationId: string;
+}
+export type CallType = 'audio' | 'video';
+export type CallState = 'idle' | 'initiating' | 'ringing' | 'connecting' | 'connected' | 'reconnecting' | 'ended';
+export type CallEndReason = 'completed' | 'rejected' | 'missed' | 'busy' | 'failed' | 'cancelled';
+export interface Call {
+    id: string;
+    conversationId: string;
+    type: CallType;
+    state: CallState;
+    callerId: string;
+    calleeIds: string[];
+    startedAt?: string;
+    answeredAt?: string;
+    endedAt?: string;
+    endReason?: CallEndReason;
+    participants: CallParticipant[];
+}
+export interface CallParticipant {
+    userId: string;
+    joinedAt: string;
+    audioMuted: boolean;
+    videoMuted: boolean;
+    screenSharing: boolean;
+}
+export interface SignalOffer {
+    callId: string;
+    fromUserId: string;
+    toUserId: string;
+    type: 'offer' | 'answer';
+    sdp: string;
+    /** Indicates this offer is a renegotiation (e.g., adding a screen share track mid-call) */
+    renegotiation?: boolean;
+}
+export interface SignalIceCandidate {
+    callId: string;
+    fromUserId: string;
+    toUserId: string;
+    candidate: string;
+    sdpMLineIndex: number | null;
+    sdpMid: string | null;
+}
+export interface SignalIceRestart {
+    callId: string;
+    fromUserId: string;
+    toUserId: string;
+}
+export interface ConnectionQualityReport {
+    callId: string;
+    userId: string;
+    /** Round-trip time in ms */
+    rtt?: number;
+    /** Packet loss percentage (0-100) */
+    packetLoss?: number;
+    /** Jitter in ms */
+    jitter?: number;
+    /** Quality level derived from metrics */
+    quality: 'excellent' | 'good' | 'fair' | 'poor';
+    /** Estimated available bandwidth in kbps */
+    availableBandwidth?: number;
+}
+export interface CallInitiate {
+    conversationId: string;
+    type: CallType;
+    calleeIds: string[];
+}
+export interface CallResponse {
+    callId: string;
+    action: 'accept' | 'reject';
+}
+export interface CallHangup {
+    callId: string;
+    reason: CallEndReason;
+}
+export interface CallMediaToggle {
+    callId: string;
+    audio?: boolean;
+    video?: boolean;
+    screenShare?: boolean;
+}
+/** A single pre-key (identity, signed, or one-time) */
+export interface PreKey {
+    keyId: number;
+    publicKey: string;
+}
+/** A user's public key bundle uploaded to the server */
+export interface KeyBundle {
+    userId: string;
+    /** Long-term identity public key */
+    identityKey: string;
+    /** Signed pre-key (rotated periodically) */
+    signedPreKey: PreKey;
+    /** Signature of signedPreKey by identityKey */
+    signedPreKeySignature: string;
+    /** One-time pre-keys (each consumed once during session setup) */
+    oneTimePreKeys: PreKey[];
+    /** When this bundle was uploaded */
+    uploadedAt: string;
+}
+/** Encrypted message envelope — server treats this as an opaque blob */
+export interface EncryptedEnvelope {
+    /** Sender's user ID */
+    senderId: string;
+    /** Recipient's user ID (for 1:1); in groups, one envelope per recipient */
+    recipientId: string;
+    /** Session identifier for this sender-recipient pair */
+    sessionId: string;
+    /** Base64-encoded ciphertext */
+    ciphertext: string;
+    /** 'prekey' for first message (includes key exchange), 'message' for subsequent */
+    messageType: 'prekey' | 'message';
+    /** Sender's identity public key (included for verification) */
+    senderIdentityKey: string;
+    /** Ephemeral public key (present in prekey messages for X3DH) */
+    senderEphemeralKey?: string;
+    /** Which one-time pre-key was used (present in prekey messages) */
+    usedOneTimePreKeyId?: number;
+}
+/** Client requests a recipient's key bundle for session setup */
+export interface KeyExchangeRequest {
+    recipientId: string;
+}
+/** Server responds with the recipient's public keys */
+export interface KeyExchangeResponse {
+    recipientId: string;
+    identityKey: string;
+    signedPreKey: PreKey;
+    signedPreKeySignature: string;
+    /** One one-time pre-key (consumed — won't be returned again) */
+    oneTimePreKey?: PreKey;
+}
+export interface CommunicationClientEvents {
+    'message:send': (data: {
+        conversationId: string;
+        content: string;
+        type: Message['type'];
+        replyTo?: string;
+        attachment?: MessageAttachment;
+    }) => void;
+    'message:read': (data: {
+        conversationId: string;
+        messageId: string;
+    }) => void;
+    'typing:start': (data: {
+        conversationId: string;
+    }) => void;
+    'typing:stop': (data: {
+        conversationId: string;
+    }) => void;
+    'presence:update': (data: {
+        status: PresenceStatus;
+    }) => void;
+    'conversation:create': (data: {
+        type: 'direct' | 'group';
+        name?: string;
+        participantIds: string[];
+    }) => void;
+    'conversation:join': (data: {
+        conversationId: string;
+    }) => void;
+    'conversation:leave': (data: {
+        conversationId: string;
+    }) => void;
+    'conversation:archive': (data: {
+        conversationId: string;
+        archived: boolean;
+    }) => void;
+    'conversation:mute': (data: {
+        conversationId: string;
+        muted: boolean;
+    }) => void;
+    'conversation:pin': (data: {
+        conversationId: string;
+        pinned: boolean;
+    }) => void;
+    'message:forward': (data: MessageForward) => void;
+    'call:initiate': (data: CallInitiate) => void;
+    'call:respond': (data: CallResponse) => void;
+    'call:hangup': (data: CallHangup) => void;
+    'call:media-toggle': (data: CallMediaToggle) => void;
+    'call:add-participant': (data: {
+        callId: string;
+        userId: string;
+    }) => void;
+    'call:remove-participant': (data: {
+        callId: string;
+        userId: string;
+    }) => void;
+    'signal:offer': (data: SignalOffer) => void;
+    'signal:answer': (data: SignalOffer) => void;
+    'signal:ice-candidate': (data: SignalIceCandidate) => void;
+    'signal:ice-restart': (data: SignalIceRestart) => void;
+    'call:quality-report': (data: ConnectionQualityReport) => void;
+    'encryption:upload-keys': (data: KeyBundle) => void;
+    'encryption:request-keys': (data: KeyExchangeRequest) => void;
+    'encryption:session-init': (data: {
+        recipientId: string;
+        sessionId: string;
+        envelope: EncryptedEnvelope;
+    }) => void;
+    /**
+     * Request a presigned upload URL for a chat file attachment.
+     * For E2E-encrypted chats: client encrypts the file locally before uploading.
+     * The server issues a presigned PUT URL — it never sees the plaintext content.
+     */
+    'file:request-upload': (data: {
+        conversationId: string;
+        mimeType: string;
+        size: number;
+        fileName: string;
+    }) => void;
+}
+export interface CommunicationServerEvents {
+    'message:new': (data: Message) => void;
+    'message:updated': (data: Message) => void;
+    'message:status': (data: {
+        messageId: string;
+        status: MessageStatus;
+    }) => void;
+    'message:error': (data: {
+        code: string;
+        message: string;
+    }) => void;
+    'typing:update': (data: TypingIndicator) => void;
+    'presence:changed': (data: PresenceUpdate) => void;
+    'conversation:updated': (data: Conversation) => void;
+    'conversation:new': (data: Conversation) => void;
+    'message:forwarded': (data: Message & {
+        forwardedFrom?: {
+            conversationId: string;
+            messageId: string;
+        };
+    }) => void;
+    'read-receipt:update': (data: {
+        conversationId: string;
+        messageId: string;
+        readBy: ReadReceipt;
+    }) => void;
+    'call:incoming': (data: Call) => void;
+    'call:state-changed': (data: {
+        callId: string;
+        state: CallState;
+        endReason?: CallEndReason;
+    }) => void;
+    'call:participant-joined': (data: {
+        callId: string;
+        participant: CallParticipant;
+    }) => void;
+    'call:participant-left': (data: {
+        callId: string;
+        userId: string;
+    }) => void;
+    'call:media-changed': (data: {
+        callId: string;
+        userId: string;
+        audio?: boolean;
+        video?: boolean;
+        screenShare?: boolean;
+    }) => void;
+    'signal:offer': (data: SignalOffer) => void;
+    'signal:answer': (data: SignalOffer) => void;
+    'signal:ice-candidate': (data: SignalIceCandidate) => void;
+    'signal:ice-restart': (data: SignalIceRestart) => void;
+    'call:quality-changed': (data: ConnectionQualityReport) => void;
+    'encryption:keys-response': (data: KeyExchangeResponse) => void;
+    'encryption:session-established': (data: {
+        sessionId: string;
+        senderId: string;
+    }) => void;
+    'encryption:session-init': (data: {
+        senderId: string;
+        sessionId: string;
+        envelope: EncryptedEnvelope;
+    }) => void;
+    'encryption:keys-depleted': (data: {
+        userId: string;
+    }) => void;
+    /** Presigned upload URL ready — client should PUT the (encrypted) file to uploadUrl */
+    'file:upload-ready': (data: {
+        fileId: string;
+        uploadUrl: string;
+        key: string;
+        expiresAt: string;
+    }) => void;
+    /** File upload request was rejected */
+    'file:upload-error': (data: {
+        code: string;
+        message: string;
+    }) => void;
+}
+export interface NkCommunication {
+    config: CommunicationConfig;
+    conversations: Conversation[];
+    activeCall?: Call;
+    encryptionEnabled?: boolean;
+}

package/dist/communication/types.js

@@ -0,0 +1 @@
+export {};

package/dist/create.d.ts

@@ -0,0 +1 @@
+export declare function createProject(name: string, template: string): Promise<void>;

package/dist/create.js

@@ -0,0 +1,55 @@
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+const TEMPLATES = ['default', 'blog', 'dashboard', 'social'];
+const BINARY_EXTENSIONS = new Set([
+    '.png', '.jpg', '.jpeg', '.gif', '.ico', '.webp', '.avif',
+    '.woff', '.woff2', '.ttf', '.eot', '.otf',
+    '.mp4', '.mp3', '.zip', '.tar', '.gz',
+]);
+export async function createProject(name, template) {
+    if (!name) {
+        console.error('Please provide a project name: lumenjs create <name>');
+        process.exit(1);
+    }
+    if (!TEMPLATES.includes(template)) {
+        console.error(`Unknown template "${template}". Available: ${TEMPLATES.join(', ')}`);
+        process.exit(1);
+    }
+    const targetDir = path.resolve(name);
+    if (fs.existsSync(targetDir) && fs.readdirSync(targetDir).length > 0) {
+        console.error(`Directory "${name}" already exists and is not empty.`);
+        process.exit(1);
+    }
+    // Templates are at package-root/templates/ (sibling to dist/)
+    const __dirname = path.dirname(fileURLToPath(import.meta.url));
+    const templateDir = path.join(__dirname, '..', 'templates', template);
+    if (!fs.existsSync(templateDir)) {
+        console.error(`Template directory not found: ${templateDir}`);
+        process.exit(1);
+    }
+    fs.mkdirSync(targetDir, { recursive: true });
+    copyDir(templateDir, targetDir, name);
+    console.log(`\n  Project created at ./${name}\n`);
+    console.log(`  cd ${name}`);
+    console.log(`  npm install`);
+    console.log(`  npx lumenjs dev\n`);
+}
+function copyDir(src, dest, projectName) {
+    for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+        const srcPath = path.join(src, entry.name);
+        const destPath = path.join(dest, entry.name);
+        if (entry.isDirectory()) {
+            fs.mkdirSync(destPath, { recursive: true });
+            copyDir(srcPath, destPath, projectName);
+        }
+        else if (BINARY_EXTENSIONS.has(path.extname(entry.name).toLowerCase())) {
+            fs.copyFileSync(srcPath, destPath);
+        }
+        else {
+            let content = fs.readFileSync(srcPath, 'utf-8');
+            content = content.replace(/\{\{PROJECT_NAME\}\}/g, projectName);
+            fs.writeFileSync(destPath, content);
+        }
+    }
+}

package/dist/db/auto-migrate.d.ts

@@ -0,0 +1,3 @@
+import type Database from 'better-sqlite3';
+import type { TableDefinition } from './table.js';
+export declare function autoMigrate(db: Database.Database, projectDir: string, tables: Map<string, TableDefinition>): void;

package/dist/db/auto-migrate.js

@@ -0,0 +1,100 @@
+import path from 'path';
+import fs from 'fs';
+function parseBaseType(typeStr) {
+    // Extract just the base type (first word), lowercased
+    return typeStr.trim().split(/\s+/)[0].toLowerCase();
+}
+function buildCreateTableSQL(table) {
+    const cols = table.columns
+        .map(c => `  ${c.name} ${c.type}`)
+        .join(',\n');
+    return `CREATE TABLE ${table.name} (\n${cols}\n);`;
+}
+function buildAddColumnSQL(tableName, colName, colType) {
+    return `ALTER TABLE ${tableName} ADD COLUMN ${colName} ${colType};`;
+}
+function generateTimestamp() {
+    const now = new Date();
+    const pad = (n) => String(n).padStart(2, '0');
+    return `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}_${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
+}
+export function autoMigrate(db, projectDir, tables) {
+    if (process.env.NODE_ENV === 'production')
+        return;
+    if (tables.size === 0)
+        return;
+    const migrationsDir = path.join(projectDir, 'data', 'migrations');
+    for (const [tableName, definition] of tables) {
+        const existingColumns = getExistingColumns(db, tableName);
+        if (!existingColumns) {
+            // Table doesn't exist — generate CREATE TABLE
+            const sql = buildCreateTableSQL(definition);
+            writeMigrationFile(migrationsDir, `auto_${tableName}_create`, sql);
+            continue;
+        }
+        // Table exists — diff columns
+        const existingColNames = new Set(existingColumns.map(c => c.name.toLowerCase()));
+        const definedColNames = new Set(definition.columns.map(c => c.name.toLowerCase()));
+        // Find new columns to add
+        const addStatements = [];
+        for (const col of definition.columns) {
+            if (!existingColNames.has(col.name.toLowerCase())) {
+                addStatements.push(buildAddColumnSQL(tableName, col.name, col.type));
+            }
+        }
+        if (addStatements.length > 0) {
+            const colNames = definition.columns
+                .filter(c => !existingColNames.has(c.name.toLowerCase()))
+                .map(c => c.name);
+            const suffix = colNames.length === 1
+                ? `add_${colNames[0]}`
+                : `add_${colNames.length}_columns`;
+            writeMigrationFile(migrationsDir, `auto_${tableName}_${suffix}`, addStatements.join('\n'));
+        }
+        // Warn about columns in DB but not in definition (potential drops)
+        for (const existing of existingColumns) {
+            if (!definedColNames.has(existing.name.toLowerCase())) {
+                console.warn(`[LumenJS] Column "${existing.name}" exists in table "${tableName}" but is not in defineTable(). ` +
+                    `SQLite does not support DROP COLUMN in older versions — create a manual migration if needed.`);
+            }
+        }
+        // Warn about type mismatches
+        const existingByName = new Map(existingColumns.map(c => [c.name.toLowerCase(), c]));
+        for (const col of definition.columns) {
+            const existing = existingByName.get(col.name.toLowerCase());
+            if (existing) {
+                const definedBase = parseBaseType(col.type);
+                const existingBase = parseBaseType(existing.type);
+                if (definedBase !== existingBase) {
+                    console.warn(`[LumenJS] Column "${col.name}" in table "${tableName}" has type "${existing.type}" in DB ` +
+                        `but "${col.type}" in defineTable(). SQLite does not support ALTER COLUMN — create a manual migration if needed.`);
+                }
+            }
+        }
+    }
+}
+function getExistingColumns(db, tableName) {
+    try {
+        const columns = db.pragma(`table_info(${tableName})`);
+        if (columns.length === 0)
+            return null;
+        return columns;
+    }
+    catch {
+        return null;
+    }
+}
+function writeMigrationFile(migrationsDir, label, sql) {
+    if (!fs.existsSync(migrationsDir)) {
+        fs.mkdirSync(migrationsDir, { recursive: true });
+    }
+    const timestamp = generateTimestamp();
+    const filename = `${timestamp}_${label}.sql`;
+    const filePath = path.join(migrationsDir, filename);
+    // Avoid duplicate generation if file with same label already exists (not yet applied)
+    const existing = fs.readdirSync(migrationsDir).filter(f => f.endsWith(`_${label}.sql`));
+    if (existing.length > 0)
+        return;
+    fs.writeFileSync(filePath, sql + '\n', 'utf-8');
+    console.log(`[LumenJS] Generated migration: ${filename}`);
+}

package/dist/db/client.d.ts

@@ -0,0 +1,3 @@
+import { LumenDb } from './index.js';
+export { LumenDb, waitForSeed } from './index.js';
+export declare function useDb(): LumenDb;

package/dist/db/client.js

@@ -0,0 +1,18 @@
+/**
+ * Public-facing DB module for user loaders and API routes.
+ * Auto-detects project directory from process.env or cwd.
+ */
+import { getProjectDir, setProjectDir } from './context.js';
+import { useDb as _useDb } from './index.js';
+export { LumenDb, waitForSeed } from './index.js';
+export function useDb() {
+    try {
+        getProjectDir();
+    }
+    catch {
+        // Auto-set from env or cwd
+        const dir = process.env.LUMENJS_PROJECT_DIR || process.cwd();
+        setProjectDir(dir);
+    }
+    return _useDb();
+}

package/dist/db/index.d.ts

@@ -1,19 +1,23 @@
 import Database from 'better-sqlite3';
-export declare class LumenDb {
-    private db;
-    constructor(db: Database.Database);
-    /** SELECT multiple rows */
-    all<T = any>(sql: string, ...params: any[]): T[];
-    /** SELECT single row */
-    get<T = any>(sql: string, ...params: any[]): T | undefined;
-    /** INSERT/UPDATE/DELETE */
-    run(sql: string, ...params: any[]): {
+export { defineTable, getRegisteredTables } from './table.js';
+export type { TableDefinition, TableColumn } from './table.js';
+export { waitForSeed } from './seed.js';
+export declare abstract class LumenDb {
+    abstract all<T = any>(sql: string, ...params: any[]): Promise<T[]>;
+    abstract get<T = any>(sql: string, ...params: any[]): Promise<T | undefined>;
+    abstract run(sql: string, ...params: any[]): Promise<{
         changes: number;
         lastInsertRowid: number | bigint;
-    };
-    /** Multi-statement DDL */
-    exec(sql: string): void;
-    /** Access the underlying better-sqlite3 instance */
+    }>;
+    abstract exec(sql: string): Promise<void>;
+    abstract withTransaction<T>(fn: () => Promise<T>): Promise<T>;
+    readonly isPg: boolean;
+    /** Raw SQLite Database — only available in SQLite mode */
     get raw(): Database.Database;
 }
 export declare function useDb(): LumenDb;
+/**
+ * Returns a promise that resolves when the initial DB migrations have completed.
+ * Useful for waiting before serving the first request in PG mode.
+ */
+export declare function waitForMigrations(): Promise<void>;