@xeplr/utils 1.0.0

package/lib/email.js

@@ -0,0 +1,303 @@
+const nodemailer = require('nodemailer');
+const fs = require('fs');
+const path = require('path');
+
+let _config = null;
+let _queue = null;
+let _deadLetterQueue = null;
+
+/**
+ * Configure the email service.
+ * @param {object} config
+ * @param {string} config.provider - 'smtp' | 'aws' | 'azure' | 'brevo'
+ * @param {object} [config.smtp] - { host, port, user, pass, from }
+ * @param {object} [config.aws] - { region, accessKeyId, secretAccessKey, from }
+ * @param {object} [config.azure] - { connectionString, from }
+ * @param {object} [config.brevo] - { apiKey, fromEmail, fromName }
+ * @param {boolean} [config.useQueue=false] - Queue emails with retry instead of sending immediately
+ * @param {number} [config.maxRetries=3] - Max retry attempts per email
+ * @param {number} [config.retryIntervalInSeconds=60] - Seconds between retry attempts
+ * @param {string} [config.store='memory'] - Queue store: 'memory' or 'redis'
+ * @param {string} [config.redisKey='xeplr:queue:email'] - Redis key for email queue
+ */
+function configureEmail(config) {
+  _config = config;
+
+  if (config.useQueue) {
+    var Queue = require('./queue');
+    var maxRetries = config.maxRetries || 3;
+    var storeType = config.store || 'memory';
+
+    _deadLetterQueue = new Queue({
+      store: storeType,
+      redisKey: config.deadLetterKey || 'xeplr:queue:email:dead',
+      autoIntervalInSeconds: 0,
+      maxEmptyTicks: 0
+    });
+
+    _queue = new Queue({
+      store: storeType,
+      redisKey: config.redisKey || 'xeplr:queue:email',
+      autoIntervalInSeconds: config.retryIntervalInSeconds || 60,
+      maxEmptyTicks: 0,
+      action: async function(item) {
+        try {
+          await _sendDirect(item.to, item.subject, item.html, item.cc, item.attachments);
+        } catch (err) {
+          var attempt = (item._retries || 0) + 1;
+          if (attempt < maxRetries) {
+            console.error('[xeplr-email] send failed (attempt ' + attempt + '/' + maxRetries + '): ' + err.message + ' — will retry');
+            _queue.addToQueue({ to: item.to, subject: item.subject, html: item.html, cc: item.cc, attachments: item.attachments, _retries: attempt });
+          } else {
+            console.error('[xeplr-email] send failed after ' + maxRetries + ' attempts, moved to dead letter queue');
+            _deadLetterQueue.addToQueue({ to: item.to, subject: item.subject, html: item.html, cc: item.cc, attachments: item.attachments, error: err.message, failedAt: new Date().toISOString() });
+          }
+        }
+      }
+    });
+  }
+}
+
+function getConfig() {
+  if (_config) return _config;
+
+  // Fall back to environment variables
+  const provider = (process.env.EMAIL_PROVIDER || 'smtp').toLowerCase();
+  return {
+    provider,
+    smtp: {
+      host: process.env.SMTP_HOST,
+      port: parseInt(process.env.SMTP_PORT) || 587,
+      user: process.env.SMTP_USER,
+      pass: process.env.SMTP_PASS,
+      from: process.env.SMTP_FROM
+    },
+    aws: {
+      region: process.env.AWS_REGION,
+      accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+      from: process.env.AWS_SES_FROM
+    },
+    azure: {
+      connectionString: process.env.AZURE_COMMUNICATION_CONNECTION_STRING,
+      from: process.env.AZURE_EMAIL_FROM
+    },
+    brevo: {
+      apiKey: process.env.BREVO_API_KEY,
+      fromEmail: process.env.BREVO_FROM_EMAIL,
+      fromName: process.env.BREVO_FROM_NAME || 'App'
+    }
+  };
+}
+
+function buildAttachments(attachments) {
+  if (!attachments || !attachments.length) return [];
+  return attachments.map(function(filePath) {
+    return {
+      filename: path.basename(filePath),
+      content: fs.readFileSync(filePath)
+    };
+  });
+}
+
+async function sendViaSMTP(to, subject, html, cc, attachments) {
+  var cfg = getConfig().smtp;
+  var transporter = nodemailer.createTransport({
+    host: cfg.host,
+    port: cfg.port,
+    secure: false,
+    auth: { user: cfg.user, pass: cfg.pass }
+  });
+
+  var mailOptions = { from: cfg.from, to, subject, html };
+  if (cc && cc.length) mailOptions.cc = cc;
+  if (attachments && attachments.length) mailOptions.attachments = buildAttachments(attachments);
+
+  await transporter.sendMail(mailOptions);
+}
+
+async function sendViaAWS(to, subject, html, cc, attachments) {
+  var cfg = getConfig().aws;
+
+  // If there are attachments or cc, use SESv2 with raw email via nodemailer
+  if ((attachments && attachments.length) || (cc && cc.length)) {
+    var { SESv2Client, SendEmailCommand } = require('@aws-sdk/client-sesv2');
+    var transporter = nodemailer.createTransport({ streamTransport: true });
+
+    var mailOptions = { from: cfg.from, to, subject, html };
+    if (cc && cc.length) mailOptions.cc = cc;
+    if (attachments && attachments.length) mailOptions.attachments = buildAttachments(attachments);
+
+    var info = await transporter.sendMail(mailOptions);
+    var rawMessage = await streamToBuffer(info.message);
+
+    var client = new SESv2Client({
+      region: cfg.region,
+      credentials: { accessKeyId: cfg.accessKeyId, secretAccessKey: cfg.secretAccessKey }
+    });
+
+    await client.send(new SendEmailCommand({
+      Content: { Raw: { Data: rawMessage } }
+    }));
+    return;
+  }
+
+  var { SESClient, SendEmailCommand: SimpleSendCommand } = require('@aws-sdk/client-ses');
+
+  var client = new SESClient({
+    region: cfg.region,
+    credentials: { accessKeyId: cfg.accessKeyId, secretAccessKey: cfg.secretAccessKey }
+  });
+
+  var command = new SimpleSendCommand({
+    Source: cfg.from,
+    Destination: { ToAddresses: to },
+    Message: {
+      Subject: { Data: subject },
+      Body: { Html: { Data: html } }
+    }
+  });
+
+  await client.send(command);
+}
+
+async function sendViaAzure(to, subject, html, cc, attachments) {
+  var { EmailClient } = require('@azure/communication-email');
+  var cfg = getConfig().azure;
+
+  var message = {
+    senderAddress: cfg.from,
+    content: { subject, html },
+    recipients: {
+      to: to.map(function(addr) { return { address: addr }; })
+    }
+  };
+
+  if (cc && cc.length) {
+    message.recipients.cc = cc.map(function(addr) { return { address: addr }; });
+  }
+
+  if (attachments && attachments.length) {
+    message.attachments = attachments.map(function(filePath) {
+      return {
+        name: path.basename(filePath),
+        contentType: 'application/octet-stream',
+        contentInBase64: fs.readFileSync(filePath).toString('base64')
+      };
+    });
+  }
+
+  var client = new EmailClient(cfg.connectionString);
+  var poller = await client.beginSend(message);
+  await poller.pollUntilDone();
+}
+
+async function sendViaBrevo(to, subject, html, cc, attachments) {
+  var cfg = getConfig().brevo;
+
+  var payload = {
+    sender: { name: cfg.fromName, email: cfg.fromEmail },
+    to: to.map(function(addr) { return { email: addr }; }),
+    subject,
+    htmlContent: html
+  };
+
+  if (cc && cc.length) {
+    payload.cc = cc.map(function(addr) { return { email: addr }; });
+  }
+
+  if (attachments && attachments.length) {
+    payload.attachment = attachments.map(function(filePath) {
+      return {
+        name: path.basename(filePath),
+        content: fs.readFileSync(filePath).toString('base64')
+      };
+    });
+  }
+
+  var res = await fetch('https://api.brevo.com/v3/smtp/email', {
+    method: 'POST',
+    headers: {
+      'accept': 'application/json',
+      'content-type': 'application/json',
+      'api-key': cfg.apiKey
+    },
+    body: JSON.stringify(payload)
+  });
+
+  if (!res.ok) {
+    var err = await res.json();
+    throw new Error('Brevo email failed: ' + (err.message || JSON.stringify(err)));
+  }
+}
+
+/**
+ * Send an email directly (no queue).
+ */
+async function _sendDirect(to, subject, html, cc, attachments) {
+  to = Array.isArray(to) ? to : [to];
+  var provider = getConfig().provider;
+
+  switch (provider) {
+    case 'smtp':
+      return sendViaSMTP(to, subject, html, cc, attachments);
+    case 'aws':
+      return sendViaAWS(to, subject, html, cc, attachments);
+    case 'azure':
+      return sendViaAzure(to, subject, html, cc, attachments);
+    case 'brevo':
+      return sendViaBrevo(to, subject, html, cc, attachments);
+    default:
+      throw new Error('Unknown email provider: ' + provider);
+  }
+}
+
+/**
+ * Send an email. If useQueue is enabled, queues with retry. Otherwise sends directly.
+ * @param {string|string[]} to - Recipient emails
+ * @param {string} subject - Email subject
+ * @param {string} html - HTML body
+ * @param {string[]} [cc] - CC recipients
+ * @param {string[]} [attachments] - File paths to attach
+ */
+async function sendEmail(to, subject, html, cc, attachments) {
+  if (_queue) {
+    _queue.addToQueue({ to: Array.isArray(to) ? to : [to], subject, html, cc, attachments, _retries: 0 });
+    return;
+  }
+  return _sendDirect(to, subject, html, cc, attachments);
+}
+
+function streamToBuffer(stream) {
+  return new Promise(function(resolve, reject) {
+    var chunks = [];
+    stream.on('data', function(chunk) { chunks.push(chunk); });
+    stream.on('end', function() { resolve(Buffer.concat(chunks)); });
+    stream.on('error', reject);
+  });
+}
+
+/**
+ * Get the dead letter queue (failed emails after max retries).
+ * Returns null if queue is not enabled.
+ */
+function getDeadLetterQueue() {
+  return _deadLetterQueue;
+}
+
+/**
+ * Replay all dead letter emails back through the main queue.
+ * Drains the dead letter queue and re-sends each item.
+ * @returns {Promise<number>} Number of emails replayed
+ */
+async function replayDeadLetters() {
+  if (!_deadLetterQueue) return 0;
+  var items = await _deadLetterQueue.drain();
+  for (var i = 0; i < items.length; i++) {
+    var item = items[i];
+    await sendEmail(item.to, item.subject, item.html, item.cc, item.attachments);
+  }
+  return items.length;
+}
+
+module.exports = { sendEmail, configureEmail, getDeadLetterQueue, replayDeadLetters };

package/lib/fileUploader.js

@@ -0,0 +1,135 @@
+const multer = require('multer');
+const path = require('path');
+const fs = require('fs');
+const { generateId } = require('./helpers');
+
+class FileUploader {
+  /**
+   * @param {object} options
+   * @param {function} options.auth - Auth function: receives (req), must return truthy or throw
+   * @param {string[]} [options.allowedTypes] - MIME types: ['image/png', 'image/*', '*']
+   * @param {number} [options.maxSize] - Max file size in bytes (default: 5MB)
+   * @param {string} [options.destination] - Upload directory (default: './uploads')
+   */
+  constructor(options = {}) {
+    this._auth = options.auth || null;
+    this._allowedTypes = options.allowedTypes || ['*'];
+    this._maxSize = options.maxSize || 5 * 1024 * 1024;
+    this._destination = options.destination || process.env.UPLOAD_DIR || './uploads';
+
+    if (!fs.existsSync(this._destination)) {
+      fs.mkdirSync(this._destination, { recursive: true });
+    }
+
+    this._multer = multer({
+      storage: multer.diskStorage({
+        destination: (req, file, cb) => {
+          cb(null, this._destination);
+        },
+        filename: (req, file, cb) => {
+          var ext = path.extname(file.originalname);
+          var name = generateId() + ext;
+          cb(null, name);
+        }
+      }),
+      limits: {
+        fileSize: this._maxSize
+      },
+      fileFilter: (req, file, cb) => {
+        if (this._isTypeAllowed(file.mimetype)) {
+          cb(null, true);
+        } else {
+          cb(new Error('File type not allowed: ' + file.mimetype));
+        }
+      }
+    });
+  }
+
+  _isTypeAllowed(mimetype) {
+    for (var i = 0; i < this._allowedTypes.length; i++) {
+      var allowed = this._allowedTypes[i];
+      if (allowed === '*') return true;
+      if (allowed.endsWith('/*')) {
+        var category = allowed.split('/')[0];
+        if (mimetype.startsWith(category + '/')) return true;
+      }
+      if (allowed === mimetype) return true;
+    }
+    return false;
+  }
+
+  _authGuard() {
+    var auth = this._auth;
+    return async function(req, res, next) {
+      if (!auth) return next();
+      try {
+        var result = await auth(req);
+        if (!result) {
+          res.writeHead ? _jsonResponse(res, 401, { error: 'Unauthorized' })
+            : res.status(401).json({ error: 'Unauthorized' });
+          return;
+        }
+        next();
+      } catch (err) {
+        res.writeHead ? _jsonResponse(res, 401, { error: err.message || 'Unauthorized' })
+          : res.status(401).json({ error: err.message || 'Unauthorized' });
+      }
+    };
+  }
+
+  _errorHandler() {
+    return function(err, req, res, next) {
+      if (err.code === 'LIMIT_FILE_SIZE') {
+        return res.status(413).json({ error: 'File too large' });
+      }
+      if (err.message && err.message.startsWith('File type not allowed')) {
+        return res.status(400).json({ error: err.message });
+      }
+      return res.status(500).json({ error: err.message || 'Upload failed' });
+    };
+  }
+
+  /**
+   * Accept a single file upload.
+   * @param {string} fieldName - Form field name
+   * @returns {function[]} Express middleware chain
+   */
+  single(fieldName) {
+    var guard = this._authGuard();
+    var upload = this._multer.single(fieldName);
+    var errorHandler = this._errorHandler();
+    return [guard, upload, errorHandler];
+  }
+
+  /**
+   * Accept multiple file uploads on a single field.
+   * @param {string} fieldName - Form field name
+   * @param {number} [maxCount=10] - Maximum number of files
+   * @returns {function[]} Express middleware chain
+   */
+  array(fieldName, maxCount) {
+    var guard = this._authGuard();
+    var upload = this._multer.array(fieldName, maxCount || 10);
+    var errorHandler = this._errorHandler();
+    return [guard, upload, errorHandler];
+  }
+
+  /**
+   * Accept file uploads on multiple fields.
+   * @param {Array<{name: string, maxCount: number}>} fields
+   * @returns {function[]} Express middleware chain
+   */
+  fields(fields) {
+    var guard = this._authGuard();
+    var upload = this._multer.fields(fields);
+    var errorHandler = this._errorHandler();
+    return [guard, upload, errorHandler];
+  }
+}
+
+function _jsonResponse(res, statusCode, data) {
+  res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify(data));
+}
+
+module.exports = FileUploader;

package/lib/helpers.js

@@ -0,0 +1,18 @@
+const crypto = require('crypto');
+
+/**
+ * Generate a random ID string (25 chars hex).
+ */
+function generateId() {
+  return crypto.randomBytes(12).toString('hex').substring(0, 25);
+}
+
+/**
+ * Format a Date as ISO datetime string for database storage.
+ */
+function formatDbDateTime(date) {
+  return (date || new Date()).toISOString();
+}
+
+// Keep alias for backward compat
+module.exports = { generateId, formatDbDateTime, mysqlDateTime: formatDbDateTime };

package/lib/logger.js

@@ -0,0 +1,51 @@
+let _baseUrl = null;
+
+/**
+ * Configure the logger client.
+ * @param {object} config
+ * @param {string} config.url - Logs service base URL (e.g. http://localhost:19005)
+ */
+function configureLogger(config) {
+  _baseUrl = config.url;
+}
+
+function getBaseUrl() {
+  return _baseUrl || process.env.LOGS_URL || 'http://localhost:19005';
+}
+
+async function createSession({ source, action }) {
+  var res = await fetch(getBaseUrl() + '/internal/sessions', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ source, action })
+  });
+  if (!res.ok) throw new Error('Failed to create log session: ' + res.statusText);
+  return res.json();
+}
+
+async function log(sessionId, level, message, metadata) {
+  var res = await fetch(getBaseUrl() + '/internal/logs', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ sessionId, level, message, metadata })
+  });
+  if (!res.ok) throw new Error('Failed to log: ' + res.statusText);
+  return res.json();
+}
+
+async function closeSession(sessionId) {
+  var res = await fetch(getBaseUrl() + '/internal/sessions/' + sessionId + '/close', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' }
+  });
+  if (!res.ok) throw new Error('Failed to close session: ' + res.statusText);
+  return res.json();
+}
+
+async function getSessionLogs(sessionId) {
+  var res = await fetch(getBaseUrl() + '/internal/sessions/' + sessionId);
+  if (!res.ok) throw new Error('Failed to get logs: ' + res.statusText);
+  return res.json();
+}
+
+module.exports = { configureLogger, createSession, log, closeSession, getSessionLogs };

package/lib/queue.js

@@ -0,0 +1,160 @@
+var MemoryStore = {
+  create: function() {
+    var items = [];
+    return {
+      push: function(item) { items.push(item); },
+      shift: async function() { return items.shift(); },
+      length: async function() { return items.length; },
+      list: async function() { return items.slice(); },
+      clear: async function() { items.length = 0; }
+    };
+  }
+};
+
+var RedisStore = {
+  create: function(options) {
+    var cache = require('./cache');
+    var client = cache.getClient();
+    var key = options.redisKey || 'xeplr:queue:default';
+
+    return {
+      push: function(item) {
+        client.rpush(key, JSON.stringify(item));
+      },
+      shift: async function() {
+        var raw = await client.lpop(key);
+        return raw ? JSON.parse(raw) : undefined;
+      },
+      length: async function() {
+        return await client.llen(key);
+      },
+      list: async function() {
+        var rawItems = await client.lrange(key, 0, -1);
+        return rawItems.map(function(raw) { return JSON.parse(raw); });
+      },
+      clear: async function() {
+        await client.del(key);
+      }
+    };
+  }
+};
+
+class Queue {
+  constructor(options = {}) {
+    this.action = options.action || null;
+    this.autoIntervalInSeconds = options.autoIntervalInSeconds || 0;
+    this.maxEmptyTicks = options.maxEmptyTicks || 0;
+    this._processing = false;
+    this._paused = false;
+    this._stopped = false;
+    this._emptyTicks = 0;
+
+    var storeType = options.store || 'memory';
+    if (storeType === 'redis') {
+      this._store = RedisStore.create(options);
+    } else {
+      this._store = MemoryStore.create();
+    }
+
+    if (this.autoIntervalInSeconds > 0) {
+      this._scheduleNext();
+    }
+  }
+
+  addToQueue(item) {
+    this._store.push(item);
+    if (this._paused && !this._stopped) {
+      this.resume();
+    }
+  }
+
+  async flushQueue() {
+    if (this._processing || this._paused) return;
+    var len = await this._store.length();
+    if (len === 0) return;
+    this._processing = true;
+    try {
+      while (true) {
+        if (this._paused) break;
+        var item = await this._store.shift();
+        if (item === undefined) break;
+        if (this.action) {
+          await this.action(item);
+        }
+      }
+    } finally {
+      this._processing = false;
+    }
+  }
+
+  pause() {
+    this._paused = true;
+  }
+
+  resume() {
+    if (!this._paused) return;
+    this._paused = false;
+    this._emptyTicks = 0;
+    if (this.autoIntervalInSeconds > 0 && !this._stopped) {
+      this._scheduleNext();
+    }
+  }
+
+  stop() {
+    this._stopped = true;
+    this._paused = true;
+  }
+
+  /**
+   * List all items in the queue without removing them.
+   */
+  async list() {
+    return this._store.list();
+  }
+
+  /**
+   * Clear all items from the queue.
+   */
+  async clear() {
+    return this._store.clear();
+  }
+
+  /**
+   * Drain all items from the queue and return them.
+   * Items are removed from the queue.
+   */
+  async drain() {
+    var result = [];
+    while (true) {
+      var item = await this._store.shift();
+      if (item === undefined) break;
+      result.push(item);
+    }
+    return result;
+  }
+
+  _scheduleNext() {
+    if (this._stopped || this._paused) return;
+    var self = this;
+    var timer = setTimeout(async function() {
+      var len = await self._store.length();
+      if (len === 0) {
+        self._emptyTicks++;
+        if (self.maxEmptyTicks > 0 && self._emptyTicks >= self.maxEmptyTicks) {
+          self._paused = true;
+          return;
+        }
+      } else {
+        self._emptyTicks = 0;
+        await self.flushQueue();
+      }
+      self._scheduleNext();
+    }, self.autoIntervalInSeconds * 1000);
+
+    if (timer && timer.unref) {
+      timer.unref();
+    }
+  }
+}
+
+module.exports = Queue;