@airoom/nextmin-node 2.0.2 → 2.0.3

package/dist/api/router/setupChatWidgetRoutes.js

@@ -0,0 +1,207 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setupChatWidgetRoutes = setupChatWidgetRoutes;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const LocalAIService_1 = require("../../services/LocalAIService");
+const OpenAIService_1 = require("../../services/OpenAIService");
+const Logger_1 = __importDefault(require("../../utils/Logger"));
+function setupChatWidgetRoutes(ctx, chatWidget) {
+    if (!chatWidget || !chatWidget.enabled) {
+        Logger_1.default.info('APIRouter', 'Chat widget is disabled. Skipping route setup.');
+        return;
+    }
+    const router = ctx.router;
+    const localAI = new LocalAIService_1.LocalAIService();
+    const openAI = new OpenAIService_1.OpenAIService();
+    // Prewarm the local LLM model in the background during server boot
+    localAI.prewarm(chatWidget.localModelPath).catch(err => {
+        Logger_1.default.warn('ChatWidget', 'Failed to prewarm local AI model on startup', err);
+    });
+    /**
+     * POST /_chatwidget/message
+     * Handle user messages and generate reply via Cloudflare AI Search.
+     */
+    router.post('/_chatwidget/message', async (req, res) => {
+        const { message, history, chatbotName, headerText, threadId, pagePath } = req.body;
+        if (!message || typeof message !== 'string') {
+            return res.status(400).json({
+                success: false,
+                error: 'Message parameter is required and must be a string.'
+            });
+        }
+        // Validate conversation message limit to protect token usage
+        const maxMessages = chatWidget?.maxMessagesPerThread !== undefined ? chatWidget.maxMessagesPerThread : 15;
+        if (maxMessages > 0) {
+            const userMessageCount = Array.isArray(history)
+                ? history.filter((m) => m.role === 'user').length
+                : 0;
+            if (userMessageCount >= maxMessages) {
+                return res.status(400).json({
+                    success: false,
+                    error: 'To keep our answers highly focused and accurate, this session has completed. Please start a fresh chat to continue!'
+                });
+            }
+        }
+        const chatHistory = Array.isArray(history) ? history.slice(-6) : [];
+        // Fallback default system prompt if not specified in server parameters
+        const botName = chatbotName || headerText || 'AI Site Assistant';
+        const baseUrl = chatWidget?.siteUrl ? chatWidget.siteUrl.replace(/\/$/, '') : '';
+        const urlInstruction = baseUrl
+            ? `If you find a related URL or path in the website context (like an admin panel, docs, or other page), you MUST strictly tell the user "I found this URL. Did you mean this? ${baseUrl}/path" (e.g. "I found this URL. Did you mean this? ${baseUrl}/admin"). Never say the URL/path is "not explicitly mentioned" or give a long, verbose robotic explanation; keep it extremely direct and present the URL.`
+            : `If you find a related URL or path in the website context (like an admin panel, docs, or other page), you MUST strictly tell the user "I found this URL. Did you mean this? [label](/path)" (e.g. "I found this URL. Did you mean this? [Admin](/admin)"). Never say the URL/path is "not explicitly mentioned" or give a long, verbose robotic explanation; keep it extremely direct and present the URL.`;
+        const FRIENDLY_FALLBACK = "Thanks for asking! 😊 I don't have enough information on that just yet, but we're working on it. Please check back soon or visit our website for the latest details!";
+        const defaultSystemPrompt = `You are a friendly, professional live support agent named ${botName} for our website. Your goal is to help users naturally and warmly.
+
+STRICT RULES — follow these exactly:
+1. Use the website context provided below to answer the user's questions.
+2. Talk like a real human support team member. Use first-person plural pronouns ("we", "our", "us") when referring to the website, company, or project (e.g. say "We support MongoDB" or "our packages" instead of "NextMin supports" or "the project has").
+3. NEVER use robotic phrases like "Based on the provided website content", "according to the text", "the context states", "the documentation says", or "is not explicitly mentioned in the context". Speak naturally as if you know all the facts yourself.
+4. If you cannot find the answer in the website context (for example: custom pricing, specific enterprise options, or details not covered in the context), respond with EXACTLY this message and nothing else: "${FRIENDLY_FALLBACK}"
+5. Keep your answers concise, clear, and friendly. Use friendly emojis naturally (e.g. 😊, 🚀, 👍).
+6. NEVER mention file names, database keys, ".txt", ".json" file extensions, or internal source names.
+7. ${urlInstruction}
+8. For greetings (hi, hello, hey) or chit-chat, respond warmly and briefly, welcome the user, and ask how you can help them today.`;
+        const defaultOpenaiSystemPrompt = `You are a friendly, professional live support agent named ${botName} for our website. Your goal is to help users naturally and warmly based ONLY on the website context provided through File Search.
+
+STRICT RULES — follow these exactly:
+1. Base your answers strictly on the website context. If you cannot find the answer in the context, respond with EXACTLY this message and nothing else: "${FRIENDLY_FALLBACK}"
+2. Talk like a real human support team member. Use first-person plural pronouns ("we", "our", "us") when referring to the website, company, or project (e.g. say "We support MongoDB" or "our packages" instead of "NextMin supports" or "the project has").
+3. NEVER use robotic phrases like "Based on the provided website content", "according to the text", "the context states", "the documentation says", or "is not explicitly mentioned in the context". Speak naturally as if you know all the facts yourself.
+4. Keep your answers concise, clear, and friendly. Use friendly emojis naturally (e.g. 😊, 🚀, 👍).
+5. NEVER mention file names, database keys, ".txt", ".json" file extensions, or internal source names.
+6. ${urlInstruction}
+7. For greetings (hi, hello, hey) or chit-chat, respond warmly and briefly, welcome the user, and ask how you can help them today.
+8. LANGUAGE RULES: Detect the language of the user's input. You MUST respond in the exact same language (e.g., if the user asks in Bengali, reply in Bengali; if in Spanish, reply in Spanish; if in English, reply in English). Translate all relevant facts from the website context into the user's language accurately.`;
+        let pageContext = '';
+        let effectiveThreadId = threadId || 'default-thread';
+        let isPageSpecificChat = false;
+        if (pagePath && typeof pagePath === 'string') {
+            let cleanPath = pagePath;
+            if (cleanPath.includes('?'))
+                cleanPath = cleanPath.split('?')[0];
+            if (cleanPath.includes('#'))
+                cleanPath = cleanPath.split('#')[0];
+            const cleanPathname = cleanPath.replace(/[^a-zA-Z0-9_\-]/g, '_') || 'index';
+            const key = `page-${cleanPathname}`;
+            effectiveThreadId = `${effectiveThreadId}_${cleanPathname}`;
+            isPageSpecificChat = true;
+            // Check strictly in .nextmin/scraped-pages/
+            const candidates = [
+                path_1.default.join(process.cwd(), '.nextmin', 'scraped-pages', `${key}.txt`),
+                path_1.default.join(process.cwd(), '.nextmin', 'scraped-pages', `${cleanPathname}.txt`),
+            ];
+            for (const candidatePath of candidates) {
+                if (fs_1.default.existsSync(candidatePath)) {
+                    pageContext = fs_1.default.readFileSync(candidatePath, 'utf-8');
+                    Logger_1.default.info('ChatWidget', `Loaded exact page context for pagePath: ${pagePath} from ${candidatePath} (${pageContext.length} chars)`);
+                    break;
+                }
+            }
+        }
+        const pageTitleName = chatbotName || headerText || (pagePath ? pagePath : 'this page');
+        let systemPromptText;
+        if (isPageSpecificChat) {
+            systemPromptText = `You are a friendly, professional live support agent for our website, acting as the dedicated support assistant for "${pageTitleName}".
+The user is currently viewing the page "${pagePath}" ("${pageTitleName}").
+${pageContext ? `
+EXACT ACTIVE PAGE CONTEXT:
+${pageContext}
+` : ''}
+
+CRITICAL DIRECTIVE FOR PAGE-SPECIFIC CHAT:
+The user is currently viewing "${pageTitleName}" (${pagePath}).
+When the user asks questions such as "Why choose this doctor?", "What are their qualifications?", "Where is their chamber?", "Visiting hours?", "Contact info?", "How to book an appointment?", or refers to "this page", "this doctor", "this hospital", "this item", "them", "him", "her", they are strictly referring to "${pageTitleName}".
+${pageContext ? 'You MUST answer questions about this page using the EXACT ACTIVE PAGE CONTEXT provided above.' : `You must search the vector store specifically for "${pageTitleName}" or canonical URL "${pagePath}".`} Do NOT introduce, discuss, or substitute any other entity or person with a similar name.
+
+STRICT RULES — follow these exactly:
+1. Base your answers strictly on the context for "${pageTitleName}". Do NOT introduce, discuss, or substitute any other page, item, person, or subject.
+2. Talk like a real human support team member. Use first-person plural pronouns ("we", "our", "us") when referring to the website, company, or project.
+3. NEVER use robotic phrases like "Based on the provided website content", "according to the text", or "is not explicitly mentioned". Speak naturally as if you know all the facts yourself.
+4. Keep your answers concise, clear, and friendly. Use friendly emojis naturally.
+5. NEVER mention file names, database keys, ".txt", ".json" file extensions, or internal source names.
+6. ${urlInstruction}
+7. LANGUAGE RULES: Detect the language of the user's input. You MUST respond in the exact same language (e.g., if the user asks in Bengali, reply in Bengali; if in English, reply in English). Translate the facts accurately.`;
+        }
+        else {
+            systemPromptText = chatWidget?.systemPrompt || (chatWidget?.enableOpenai !== false ? defaultOpenaiSystemPrompt : defaultSystemPrompt);
+        }
+        try {
+            Logger_1.default.info('ChatWidget', `Received question: "${message}" (threadId: ${effectiveThreadId}, pagePath: ${pagePath || 'none'})`);
+            // Set headers for streaming response
+            res.setHeader('Content-Type', 'text/plain; charset=utf-8');
+            res.setHeader('Transfer-Encoding', 'chunked');
+            res.setHeader('Cache-Control', 'no-cache');
+            res.setHeader('Connection', 'keep-alive');
+            let chunkWritten = false;
+            let usedOpenAI = false;
+            // Try OpenAI first if enabled and API Key is configured
+            if (chatWidget?.enableOpenai !== false) {
+                if (process.env.OPENAI_API_KEY) {
+                    try {
+                        usedOpenAI = true;
+                        await openAI.generateAnswerStream(effectiveThreadId, message, systemPromptText, (chunk) => {
+                            res.write(chunk);
+                            chunkWritten = true;
+                        }, false // Always enable vector store search (single source of truth)
+                        );
+                        if (!chunkWritten) {
+                            Logger_1.default.warn('ChatWidget', `OpenAI stream finished but no chunks were written.`);
+                            usedOpenAI = false; // Trigger fallback
+                        }
+                    }
+                    catch (openaiErr) {
+                        Logger_1.default.warn('ChatWidget', `OpenAI Responses API call failed. Falling back to local model. Reason: ${openaiErr.message || openaiErr}`);
+                        usedOpenAI = false;
+                        chunkWritten = false;
+                    }
+                }
+                else {
+                    Logger_1.default.warn('ChatWidget', 'enableOpenai is true but OPENAI_API_KEY is not defined in environment variables. Falling back to local model.');
+                }
+            }
+            // If OpenAI was not used, or if it failed and wrote no chunks, run the local model as a fallback
+            if (!usedOpenAI && !chunkWritten) {
+                Logger_1.default.info('ChatWidget', 'Running Local model (offline fallback)...');
+                const rawReply = await localAI.generateAnswer(chatHistory, message, systemPromptText, chatWidget?.localModelPath, chatWidget?.threads, effectiveThreadId, (chunk) => {
+                    res.write(chunk);
+                    chunkWritten = true;
+                });
+                if (!chunkWritten) {
+                    const uncertaintyPhrases = [
+                        /i (don'?t|do not) have (that|this|enough|any|much) (information|info|data|detail)/i,
+                        /i (can'?t|cannot|could not|couldn'?t) (find|answer|provide|tell)/i,
+                        /not (available|found|mentioned|covered|included|specified|provided) in (the )?(context|content|information|docs|documentation)/i,
+                        /the (context|content|provided information|documentation) does(n'?t| not) (contain|include|mention|have|cover)/i,
+                        /there('?s| is) no (information|data|detail|mention) (about|on|regarding)/i,
+                        /i'?m (unable|not able) to (answer|find|provide|tell)/i,
+                        /based on (the )?(available |provided |given )?(context|information|content), i (cannot|can'?t|am unable)/i,
+                    ];
+                    const isUncertainResponse = uncertaintyPhrases.some(pattern => pattern.test(rawReply));
+                    const pageFallback = `I am here to help you with information about ${pageTitleName} only. If you need other general information about the site, please start a new chat session! 😊`;
+                    const reply = isUncertainResponse ? (isPageSpecificChat ? pageFallback : FRIENDLY_FALLBACK) : rawReply;
+                    if (isUncertainResponse) {
+                        Logger_1.default.info('ChatWidget', `LLM expressed uncertainty — replaced with friendly fallback.`);
+                    }
+                    res.write(reply);
+                }
+            }
+            res.end();
+        }
+        catch (err) {
+            Logger_1.default.error('ChatWidget', 'Chat response generation failed', err);
+            if (!res.headersSent) {
+                return res.status(500).json({
+                    success: false,
+                    error: err.message || 'Internal server error while generating chat response.'
+                });
+            }
+            else {
+                res.end();
+            }
+        }
+    });
+}

package/dist/api/router/setupFileRoutes.js

@@ -6,6 +6,54 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.setupFileRoutes = setupFileRoutes;
 const multer_1 = __importDefault(require("multer"));
 const Logger_1 = __importDefault(require("../../utils/Logger"));
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const crypto_1 = __importDefault(require("crypto"));
+const os_1 = __importDefault(require("os"));
+const CACHE_DIR = path_1.default.join(os_1.default.tmpdir(), 'nextmin_img_cache');
+try {
+    if (!fs_1.default.existsSync(CACHE_DIR)) {
+        fs_1.default.mkdirSync(CACHE_DIR, { recursive: true });
+    }
+}
+catch (_) { }
+const WIN1252_MAP = {
+    0x20AC: 0x80, 0x201A: 0x82, 0x0192: 0x83, 0x201E: 0x84,
+    0x2026: 0x85, 0x2020: 0x86, 0x2021: 0x87, 0x02C6: 0x88,
+    0x2030: 0x89, 0x0160: 0x8A, 0x2039: 0x8B, 0x0152: 0x8C,
+    0x017D: 0x8E, 0x2018: 0x91, 0x2019: 0x92, 0x201C: 0x93,
+    0x201D: 0x94, 0x2022: 0x95, 0x2013: 0x96, 0x2014: 0x97,
+    0x02DC: 0x98, 0x2122: 0x99, 0x0161: 0x9A, 0x203A: 0x9B,
+    0x0153: 0x9C, 0x017E: 0x9E, 0x0178: 0x9F,
+};
+function fixUtf8Filename(name) {
+    if (!name)
+        return '';
+    if (/[\u0980-\u09FF]/.test(name)) {
+        return name;
+    }
+    try {
+        const bytes = [];
+        for (let i = 0; i < name.length; i++) {
+            const code = name.charCodeAt(i);
+            if (WIN1252_MAP[code] !== undefined) {
+                bytes.push(WIN1252_MAP[code]);
+            }
+            else if (code <= 0xFF) {
+                bytes.push(code);
+            }
+            else {
+                return name;
+            }
+        }
+        const decoded = Buffer.from(bytes).toString('utf-8');
+        if (!decoded.includes('\ufffd')) {
+            return decoded;
+        }
+    }
+    catch { }
+    return name;
+}
 function setupFileRoutes(ctx) {
     if (!ctx.fileStorage)
         return;
@@ -23,23 +71,46 @@ function setupFileRoutes(ctx) {
                     .status(400)
                     .json({ error: true, message: 'No files uploaded' });
             }
+            // Fix Multer's default latin1 header decoding to proper UTF-8 for non-ASCII filenames
+            for (const f of files) {
+                if (f.originalname) {
+                    f.originalname = fixUtf8Filename(f.originalname);
+                }
+            }
+            // Validate that every uploaded file has a valid, non-empty name before extension
+            for (const f of files) {
+                const rawName = (f.originalname || '').trim();
+                const baseName = rawName.replace(/\.[^/.]+$/, '').trim();
+                if (!baseName) {
+                    return res.status(400).json({
+                        error: true,
+                        message: `Uploaded file '${f.originalname || 'unknown'}' does not have a valid filename. Please give the file a descriptive name before uploading.`,
+                    });
+                }
+            }
             const results = await Promise.all(files.map(async (f) => {
+                const rawOriginalName = (req.body?.originalName && typeof req.body.originalName === 'string' ? req.body.originalName : null) ||
+                    f.originalname;
                 const out = await ctx.fileStorage.upload({
-                    originalFilename: f.originalname,
+                    originalFilename: rawOriginalName,
                     body: f.buffer,
                     contentType: f.mimetype,
-                    metadata: { originalName: f.originalname || '' },
+                    metadata: { originalName: rawOriginalName || '' },
                 });
+                let url = out.url;
+                if (ctx.dbAdapter && typeof ctx.dbAdapter.formatUrlForRead === 'function') {
+                    url = ctx.dbAdapter.formatUrlForRead(url);
+                }
                 return {
                     provider: out.provider,
                     bucket: out.bucket,
                     key: out.key,
-                    url: out.url,
+                    url,
                     etag: out.etag,
                     contentType: out.contentType,
                     size: out.size,
                     metadata: out.metadata,
-                    originalName: f.originalname,
+                    originalName: rawOriginalName,
                 };
             }));
             return res.json({
@@ -49,9 +120,10 @@ function setupFileRoutes(ctx) {
             });
         }
         catch (err) {
+            const statusCode = err?.statusCode === 409 || err?.code === 'FILE_EXISTS' ? 409 : 400;
             return res
-                .status(400)
-                .json({ error: true, message: err?.message ?? 'Upload failed' });
+                .status(statusCode)
+                .json({ error: true, message: err?.message ?? 'Upload failed', code: err?.code });
         }
     });
     ctx.router.get('/files/:key(*)', async (req, res) => {
@@ -62,20 +134,115 @@ function setupFileRoutes(ctx) {
             }
             // Ensure no leading slash for storage providers
             key = key.replace(/^\/+/, '');
+            const width = req.query.w ? parseInt(String(req.query.w), 10) : undefined;
+            const height = req.query.h ? parseInt(String(req.query.h), 10) : undefined;
+            const quality = req.query.q ? Math.min(100, Math.max(10, parseInt(String(req.query.q), 10))) : 80;
+            const raw = req.query.raw === 'true' || req.query.fmt === 'original' || req.query.fmt === 'raw';
+            const targetFormat = raw ? undefined : (req.query.fmt ? String(req.query.fmt).toLowerCase() : 'webp');
+            const isImageByKey = /\.(jpg|jpeg|png|webp|avif|gif)$/i.test(key) || Boolean(req.query.w || req.query.h || req.query.q || req.query.fmt);
+            let cacheFilePath = null;
+            if (isImageByKey && !raw) {
+                const hash = crypto_1.default.createHash('md5')
+                    .update(`${key}_w${width || 0}_h${height || 0}_q${quality}_fmt${targetFormat || 'webp'}`)
+                    .digest('hex');
+                const ext = targetFormat || 'webp';
+                cacheFilePath = path_1.default.join(CACHE_DIR, `${hash}.${ext}`);
+                if (fs_1.default.existsSync(cacheFilePath)) {
+                    try {
+                        const cachedBuf = fs_1.default.readFileSync(cacheFilePath);
+                        const mimeType = (ext === 'jpeg' || ext === 'jpg') ? 'image/jpeg' : ((ext === 'png') ? 'image/png' : ((ext === 'avif') ? 'image/avif' : 'image/webp'));
+                        res.setHeader('Content-Type', mimeType);
+                        res.setHeader('Content-Length', cachedBuf.length);
+                        res.setHeader('Cache-Control', 'public, max-age=31536000, immutable');
+                        res.setHeader('X-Cache', 'HIT');
+                        return res.send(cachedBuf);
+                    }
+                    catch (_) { }
+                }
+            }
             Logger_1.default.info('FileProxy', `Fetching file from storage: ${key}`);
-            const { body, contentType, size } = await ctx.fileStorage.download(key);
+            let { body, contentType, size } = await ctx.fileStorage.download(key);
+            const isImage = isImageByKey || contentType?.startsWith('image/');
+            // If file is an image and raw format is not explicitly requested, serve converted WebP (with optional resizing)
+            if (isImage && !raw) {
+                try {
+                    let buffer = null;
+                    if (body && typeof body.transformToByteArray === 'function') {
+                        const data = await body.transformToByteArray();
+                        buffer = Buffer.from(data);
+                    }
+                    else if (Buffer.isBuffer(body)) {
+                        buffer = body;
+                    }
+                    else if (body && typeof body.pipe === 'function') {
+                        const chunks = [];
+                        for await (const chunk of body) {
+                            chunks.push(chunk);
+                        }
+                        buffer = Buffer.concat(chunks);
+                    }
+                    if (buffer) {
+                        let sharp;
+                        try {
+                            sharp = require('sharp');
+                        }
+                        catch { }
+                        if (sharp) {
+                            let pipeline = sharp(buffer);
+                            if (width || height) {
+                                pipeline = pipeline.resize({
+                                    width: width || undefined,
+                                    height: height || undefined,
+                                    fit: 'inside',
+                                    withoutEnlargement: true,
+                                });
+                            }
+                            if (targetFormat === 'jpeg' || targetFormat === 'jpg') {
+                                pipeline = pipeline.jpeg({ quality });
+                                contentType = 'image/jpeg';
+                            }
+                            else if (targetFormat === 'png') {
+                                pipeline = pipeline.png({ quality });
+                                contentType = 'image/png';
+                            }
+                            else if (targetFormat === 'avif') {
+                                pipeline = pipeline.avif({ quality });
+                                contentType = 'image/avif';
+                            }
+                            else {
+                                // Default to WebP format for fast delivery & small file size
+                                pipeline = pipeline.webp({ quality });
+                                contentType = 'image/webp';
+                            }
+                            const resizedBuf = await pipeline.toBuffer();
+                            buffer = resizedBuf;
+                            size = resizedBuf.length;
+                            body = resizedBuf;
+                            if (cacheFilePath) {
+                                fs_1.default.writeFile(cacheFilePath, resizedBuf, () => { });
+                            }
+                        }
+                    }
+                }
+                catch (imgErr) {
+                    Logger_1.default.warn('FileProxy', `Image processing failed: ${imgErr.message}`);
+                }
+            }
             if (contentType)
                 res.setHeader('Content-Type', contentType);
             if (size)
                 res.setHeader('Content-Length', size);
             // Cache for 1 year if it's an image
-            if (contentType?.startsWith('image/')) {
+            if (isImage) {
                 res.setHeader('Cache-Control', 'public, max-age=31536000, immutable');
             }
             else {
                 res.setHeader('Cache-Control', 'public, max-age=86400');
             }
-            if (body && typeof body.pipe === 'function') {
+            if (Buffer.isBuffer(body)) {
+                res.send(body);
+            }
+            else if (body && typeof body.pipe === 'function') {
                 body.pipe(res);
             }
             else if (body && typeof body.transformToByteArray === 'function') {
@@ -88,7 +255,21 @@ function setupFileRoutes(ctx) {
         }
         catch (err) {
             Logger_1.default.warn('FileProxy', `Failed to fetch file ${req.params.key}: ${err.message}`);
-            if (err.name === 'NoSuchKey' || err.code === 'NoSuchKey' || err.name === 'NotFound' || err.code === 'NotFound') {
+            const isMissing = err.name === 'NoSuchKey' || err.code === 'NoSuchKey' || err.name === 'NotFound' || err.code === 'NotFound' || err.statusCode === 404;
+            const keyStr = String(req.params.key || '');
+            const isImageRequest = /\.(png|jpg|jpeg|webp|avif|gif|svg)$/i.test(keyStr) || !!req.query.w || !!req.query.h;
+            if (isMissing && isImageRequest) {
+                const FALLBACK_SVG = `<svg xmlns="http://www.w3.org/2000/svg" width="300" height="300" viewBox="0 0 300 300" fill="none">
+  <rect width="300" height="300" fill="#F1F5F9" rx="12"/>
+  <rect x="0.5" y="0.5" width="299" height="299" rx="11.5" stroke="#CBD5E1"/>
+  <path d="M150 125C158.284 125 165 118.284 165 110C165 101.716 158.284 95 150 95C141.716 95 135 101.716 141.716 125 150 125Z" fill="#94A3B8"/>
+  <path fill-rule="evenodd" clip-rule="evenodd" d="M90 205C87.2386 205 85 202.761 85 200V175C85 168.37 90.37 163 97 163H108.172C110.824 163 113.368 164.054 115.243 165.929L135 185.686L158.757 161.929C160.632 160.054 163.176 159 165.828 159H203C209.63 159 215 164.37 215 171V200C215 202.761 212.761 205 210 205H90Z" fill="#94A3B8"/>
+</svg>`;
+                res.setHeader('Content-Type', 'image/svg+xml');
+                res.setHeader('Cache-Control', 'public, max-age=86400');
+                return res.status(200).send(FALLBACK_SVG);
+            }
+            if (isMissing) {
                 return res.status(404).json({ error: true, message: 'File not found in storage' });
             }
             return res.status(500).json({ error: true, message: err?.message ?? 'Download failed' });
@@ -102,23 +283,46 @@ function setupFileRoutes(ctx) {
                     .status(400)
                     .json({ error: true, message: 'No files uploaded' });
             }
+            // Fix Multer's default latin1/win1252 header decoding to proper UTF-8 for non-ASCII filenames
+            for (const f of files) {
+                if (f.originalname) {
+                    f.originalname = fixUtf8Filename(f.originalname);
+                }
+            }
+            // Validate that every uploaded file has a valid, non-empty name before extension
+            for (const f of files) {
+                const rawName = (f.originalname || '').trim();
+                const baseName = rawName.replace(/\.[^/.]+$/, '').trim();
+                if (!baseName) {
+                    return res.status(400).json({
+                        error: true,
+                        message: `Uploaded file '${f.originalname || 'unknown'}' does not have a valid filename. Please give the file a descriptive name before uploading.`,
+                    });
+                }
+            }
             const results = await Promise.all(files.map(async (f) => {
+                const rawOriginalName = (req.body?.originalName && typeof req.body.originalName === 'string' ? req.body.originalName : null) ||
+                    f.originalname;
                 const out = await ctx.fileStorage.upload({
-                    originalFilename: f.originalname,
+                    originalFilename: rawOriginalName,
                     body: f.buffer,
                     contentType: f.mimetype,
-                    metadata: { originalName: f.originalname || '' },
+                    metadata: { originalName: rawOriginalName || '' },
                 });
+                let url = out.url;
+                if (ctx.dbAdapter && typeof ctx.dbAdapter.formatUrlForRead === 'function') {
+                    url = ctx.dbAdapter.formatUrlForRead(url);
+                }
                 return {
                     provider: out.provider,
                     bucket: out.bucket,
                     key: out.key,
-                    url: out.url,
+                    url,
                     etag: out.etag,
                     contentType: out.contentType,
                     size: out.size,
                     metadata: out.metadata,
-                    originalName: f.originalname,
+                    originalName: rawOriginalName,
                 };
             }));
             return res.json({
@@ -128,9 +332,10 @@ function setupFileRoutes(ctx) {
             });
         }
         catch (err) {
+            const statusCode = err?.statusCode === 409 || err?.code === 'FILE_EXISTS' ? 409 : 400;
             return res
-                .status(400)
-                .json({ error: true, message: err?.message ?? 'Upload failed' });
+                .status(statusCode)
+                .json({ error: true, message: err?.message ?? 'Upload failed', code: err?.code });
         }
     });
     ctx.router.delete('/files/:key(*)', fileAuthMiddleware, async (req, res) => {

package/dist/api/router/utils.d.ts

@@ -61,7 +61,8 @@ export type ParsedQuery = {
 export declare function parseQuery(req: Request, allowedKeys?: Set<string>): ParsedQuery;
 export declare function extractIds(val: unknown): string[];
 export declare function refInfoFromAttr(attr: any): {
-    ref: string;
+    ref?: string;
+    refPath?: string;
     isArray: boolean;
 } | null;
 export declare const dedupeBy: <T, K extends string | number>(rows: T[], key: (r: T) => K) => T[];

package/dist/api/router/utils.js

@@ -331,13 +331,15 @@ function extractIds(val) {
 function refInfoFromAttr(attr) {
     if (!attr)
         return null;
-    if (Array.isArray(attr) && attr[0] && attr[0].ref) {
-        return { ref: String(attr[0].ref), isArray: true };
-    }
-    const a = Array.isArray(attr) ? attr?.[0] : attr;
+    const isArray = Array.isArray(attr);
+    const a = isArray ? attr?.[0] : attr;
+    if (!a)
+        return null;
     const t = (typeof a?.type === 'string' ? a.type : String(a?.type || '')).toLowerCase();
-    if (a?.ref && (t === 'objectid' || t === 'ref')) {
-        return { ref: String(a.ref), isArray: false };
+    const refPath = a.refPath ? String(a.refPath) : undefined;
+    const ref = a.ref ? String(a.ref) : undefined;
+    if ((refPath || ref) && (t === 'objectid' || t === 'ref' || isArray)) {
+        return { ref, refPath, isArray };
     }
     return null;
 }

package/dist/cli.d.ts

@@ -1 +1,2 @@
+#!/usr/bin/env node
 export {};