@xeplr/utils 1.0.0

package/lib/rateLimiter.js

@@ -0,0 +1,100 @@
+var MemoryStore = {
+  create: function(windowInSeconds) {
+    var hits = {};
+
+    // cleanup expired keys periodically
+    var cleanup = setInterval(function() {
+      var now = Date.now();
+      for (var key in hits) {
+        if (hits[key].expiresAt < now) {
+          delete hits[key];
+        }
+      }
+    }, windowInSeconds * 1000);
+
+    if (cleanup && cleanup.unref) cleanup.unref();
+
+    return {
+      increment: async function(key) {
+        var now = Date.now();
+        var entry = hits[key];
+        if (!entry || entry.expiresAt < now) {
+          hits[key] = { count: 1, expiresAt: now + windowInSeconds * 1000 };
+          return { count: 1, remaining: windowInSeconds };
+        }
+        entry.count++;
+        var remaining = Math.ceil((entry.expiresAt - now) / 1000);
+        return { count: entry.count, remaining: remaining };
+      }
+    };
+  }
+};
+
+var RedisStore = {
+  create: function(windowInSeconds) {
+    var cache = require('./cache');
+    var client = cache.getClient();
+
+    return {
+      increment: async function(key) {
+        var redisKey = 'xeplr:ratelimit:' + key;
+        var count = await client.incr(redisKey);
+        if (count === 1) {
+          await client.expire(redisKey, windowInSeconds);
+        }
+        var ttl = await client.ttl(redisKey);
+        return { count: count, remaining: ttl > 0 ? ttl : windowInSeconds };
+      }
+    };
+  }
+};
+
+class RateLimiter {
+  /**
+   * @param {object} options
+   * @param {number} [options.windowInSeconds=60] - Time window in seconds
+   * @param {number} [options.max=100] - Max requests per window
+   * @param {string} [options.store='memory'] - 'memory' or 'redis'
+   * @param {function} [options.keyFn] - Function to extract key from req (default: req.ip)
+   * @param {string} [options.message] - Custom error message
+   */
+  constructor(options = {}) {
+    this._windowInSeconds = options.windowInSeconds || 60;
+    this._max = options.max || 100;
+    this._keyFn = options.keyFn || function(req) { return req.ip; };
+    this._message = options.message || 'Too many requests, please try again later';
+
+    var storeType = options.store || 'memory';
+    if (storeType === 'redis') {
+      this._store = RedisStore.create(this._windowInSeconds);
+    } else {
+      this._store = MemoryStore.create(this._windowInSeconds);
+    }
+  }
+
+  middleware() {
+    var self = this;
+    return async function(req, res, next) {
+      try {
+        var key = self._keyFn(req);
+        var result = await self._store.increment(key);
+
+        res.setHeader('X-RateLimit-Limit', self._max);
+        res.setHeader('X-RateLimit-Remaining', Math.max(0, self._max - result.count));
+        res.setHeader('X-RateLimit-Reset', result.remaining);
+
+        if (result.count > self._max) {
+          res.setHeader('Retry-After', result.remaining);
+          return res.status(429).json({ error: self._message });
+        }
+
+        next();
+      } catch (err) {
+        // if rate limiter fails, let the request through
+        next();
+      }
+    };
+  }
+}
+
+module.exports = RateLimiter;

package/lib/response.js

@@ -0,0 +1,86 @@
+/**
+ * Response helper — sends a fixed-format JSON response.
+ *
+ * Format:
+ *   {
+ *     code:       'SUC_LOGIN' | 'ERR_INVALID_FILE' | STATUS.SUCCESS | ...,
+ *     message:    'Human-readable message (i18n aware)',
+ *     error:      null | { name, message, ...details },
+ *     dataArray:  [],
+ *     updatedIds: []
+ *   }
+ *
+ * Usage:
+ *   const { respond } = require('@xeplr/utils');
+ *   const { HTTP, STATUS } = require('@xeplr/utils/isomorphic');
+ *
+ *   // Success
+ *   respond(res, HTTP.OK, STATUS.SUCCESS, 'success', { dataArray: orders });
+ *
+ *   // Error
+ *   respond(res, HTTP.BAD_REQUEST, STATUS.BAD_REQUEST, 'bad_request', { error: err });
+ *
+ *   // With updatedIds
+ *   respond(res, HTTP.OK, STATUS.UPDATED, 'updated', { updatedIds: [1, 2, 3] });
+ *
+ *   // Minimal
+ *   respond(res, HTTP.OK, STATUS.SUCCESS, 'success');
+ */
+
+const { msg } = require('../isomorphic');
+
+/**
+ * Sanitize an error object for serialization (strips stack trace).
+ */
+function sanitizeError(err) {
+  if (!err) return null;
+
+  const clean = {
+    name: err.name || 'Error',
+    message: err.message || String(err),
+  };
+
+  // Preserve any extra properties (e.g. err.code, err.field, err.details)
+  // but skip stack, __proto__, constructor
+  const skip = new Set(['name', 'message', 'stack']);
+  for (const key of Object.keys(err)) {
+    if (!skip.has(key)) {
+      clean[key] = err[key];
+    }
+  }
+
+  return clean;
+}
+
+/**
+ * Send a standardized response.
+ *
+ * @param {object} res         - Express response object
+ * @param {number} httpCode    - HTTP status code (from HTTP constants)
+ * @param {string} statusCode  - Application status code (from STATUS constants)
+ * @param {string} messageKey  - Key in MESSAGES for i18n lookup
+ * @param {object} [options]   - Optional overrides
+ * @param {Array}  [options.dataArray]   - Response data (default: [])
+ * @param {Array}  [options.updatedIds]  - IDs affected by the operation (default: [])
+ * @param {Error}  [options.error]       - Error object, sanitized before sending (default: null)
+ * @param {string} [options.message]     - Override the i18n message with a custom string
+ * @param {object} [options.pagination]  - { page, limit, total, totalPages }
+ */
+function respond(res, httpCode, statusCode, messageKey, options = {}) {
+  const body = {
+    code:       statusCode,
+    message:    options.message || msg(messageKey),
+    error:      sanitizeError(options.error),
+    dataArray:  options.dataArray || [],
+    updatedIds: options.updatedIds || [],
+    sessionId:  res.req && res.req.sessionId || null,
+  };
+
+  if (options.pagination) {
+    body.pagination = options.pagination;
+  }
+
+  return res.status(httpCode).send(body);
+}
+
+module.exports = { respond, sanitizeError };

package/lib/sms.js

@@ -0,0 +1,278 @@
+/**
+ * SMS Service — generic wrapper for any SMS provider.
+ *
+ * Each provider is an HTTP API definition with multiple actions.
+ * Register providers once, then send via provider + action name.
+ *
+ * Usage:
+ *
+ *   var sms = require('@xeplr/utils').sms;
+ *
+ *   // Simple provider — single action (default)
+ *   sms.register('twilio', {
+ *     actions: {
+ *       send: {
+ *         url: 'https://api.twilio.com/2010-04-01/Accounts/{{accountSid}}/Messages.json',
+ *         method: 'POST',
+ *         auth: { user: '{{accountSid}}', password: '{{authToken}}' },
+ *         contentType: 'form',
+ *         body: { From: '{{from}}', To: '{{to}}', Body: '{{message}}' }
+ *       }
+ *     },
+ *     params: { accountSid: 'AC...', authToken: '...', from: '+1234567890' }
+ *   });
+ *
+ *   // Provider with multiple actions + chained auth
+ *   sms.register('kaleyra', {
+ *     actions: {
+ *       auth: {
+ *         url: 'https://api.kaleyra.io/v1/{{sid}}/auth/token',
+ *         method: 'POST',
+ *         contentType: 'json',
+ *         body: { api_key: '{{apiKey}}' },
+ *         extract: { token: 'data.token' }   // extract token from response into params
+ *       },
+ *       otp: {
+ *         url: 'https://api.kaleyra.io/v1/{{sid}}/messages',
+ *         method: 'POST',
+ *         headers: { Authorization: 'Bearer {{token}}' },
+ *         contentType: 'json',
+ *         body: { to: '{{to}}', type: 'OTP', body: '{{message}}' },
+ *         before: ['auth']   // run auth action first, merge extracted params
+ *       },
+ *       promo: {
+ *         url: 'https://api.kaleyra.io/v1/{{sid}}/messages',
+ *         method: 'POST',
+ *         headers: { Authorization: 'Bearer {{token}}' },
+ *         contentType: 'json',
+ *         body: { to: '{{to}}', type: 'PROMO', body: '{{message}}' },
+ *         before: ['auth']
+ *       }
+ *     },
+ *     params: { sid: '...', apiKey: '...' }
+ *   });
+ *
+ *   // Send
+ *   await sms.send('twilio', { to: '+91...', message: 'Hello!' });
+ *   await sms.send('kaleyra', 'otp', { to: '+91...', message: 'OTP: 1234' });
+ *   await sms.send('kaleyra', 'promo', { to: '+91...', message: 'Sale!' });
+ */
+
+var _providers = {};
+var _defaultProvider = null;
+
+/**
+ * Register an SMS provider.
+ *
+ * @param {string} name - Provider name
+ * @param {object} config
+ * @param {object} config.actions - Named actions { actionName: { url, method, headers, auth, contentType, body, before, extract } }
+ * @param {object} [config.params] - Default params shared across all actions
+ * @param {function} [config.parseResponse] - Custom response parser for all actions
+ */
+function register(name, config) {
+  _providers[name] = config;
+}
+
+/**
+ * Set the default provider.
+ */
+function setDefault(name) {
+  _defaultProvider = name;
+}
+
+function _resolvePlaceholders(str, params) {
+  if (typeof str !== 'string') return str;
+  return str.replace(/\{\{(\w+)\}\}/g, function(match, key) {
+    return params[key] !== undefined ? String(params[key]) : match;
+  });
+}
+
+function _resolveObject(obj, params) {
+  if (typeof obj === 'string') return _resolvePlaceholders(obj, params);
+  if (Array.isArray(obj)) return obj.map(function(v) { return _resolveObject(v, params); });
+  if (obj && typeof obj === 'object') {
+    var resolved = {};
+    var keys = Object.keys(obj);
+    for (var i = 0; i < keys.length; i++) {
+      resolved[keys[i]] = _resolveObject(obj[keys[i]], params);
+    }
+    return resolved;
+  }
+  return obj;
+}
+
+/**
+ * Extract a nested value from an object using dot notation.
+ * e.g. _extractPath({ data: { token: 'abc' } }, 'data.token') => 'abc'
+ */
+function _extractPath(obj, path) {
+  var parts = path.split('.');
+  var val = obj;
+  for (var i = 0; i < parts.length; i++) {
+    if (val == null) return undefined;
+    val = val[parts[i]];
+  }
+  return val;
+}
+
+/**
+ * Execute a single action against a provider.
+ */
+async function _executeAction(action, params) {
+  var url = _resolvePlaceholders(action.url, params);
+  var method = (action.method || 'POST').toUpperCase();
+
+  var headers = {};
+  if (action.headers) {
+    headers = _resolveObject(action.headers, params);
+  }
+
+  var fetchOptions = { method: method, headers: {} };
+
+  // Basic auth
+  if (action.auth) {
+    var user = _resolvePlaceholders(action.auth.user, params);
+    var password = _resolvePlaceholders(action.auth.password, params);
+    fetchOptions.headers['Authorization'] = 'Basic ' + Buffer.from(user + ':' + password).toString('base64');
+  }
+
+  Object.assign(fetchOptions.headers, headers);
+
+  // Body
+  if (action.body) {
+    var body = _resolveObject(action.body, params);
+    var contentType = action.contentType || 'json';
+
+    if (contentType === 'form') {
+      fetchOptions.headers['Content-Type'] = 'application/x-www-form-urlencoded';
+      var parts = [];
+      var bodyKeys = Object.keys(body);
+      for (var i = 0; i < bodyKeys.length; i++) {
+        parts.push(encodeURIComponent(bodyKeys[i]) + '=' + encodeURIComponent(body[bodyKeys[i]]));
+      }
+      fetchOptions.body = parts.join('&');
+    } else {
+      fetchOptions.headers['Content-Type'] = 'application/json';
+      fetchOptions.body = JSON.stringify(body);
+    }
+  }
+
+  var res = await fetch(url, fetchOptions);
+  var raw;
+  try {
+    raw = await res.json();
+  } catch (e) {
+    raw = null;
+  }
+
+  return { ok: res.ok, status: res.status, raw: raw };
+}
+
+/**
+ * Send an SMS.
+ *
+ * Signatures:
+ *   send('twilio', { to, message })              — uses 'send' action
+ *   send('kaleyra', 'otp', { to, message })      — uses named action
+ *   send({ to, message })                         — uses default provider + 'send' action
+ *
+ * @returns {Promise<{ success, messageId?, raw?, error? }>}
+ */
+async function send(providerName, actionOrParams, sendParams) {
+  // Resolve arguments
+  var actionName, params;
+
+  if (typeof providerName === 'object') {
+    // send({ to, message }) — default provider, 'send' action
+    params = providerName;
+    providerName = _defaultProvider;
+    actionName = 'send';
+  } else if (typeof actionOrParams === 'string') {
+    // send('provider', 'action', { to, message })
+    actionName = actionOrParams;
+    params = sendParams || {};
+  } else {
+    // send('provider', { to, message }) — 'send' action
+    actionName = 'send';
+    params = actionOrParams || {};
+  }
+
+  if (!providerName) {
+    throw new Error('SMS provider name required. Call sms.setDefault() or pass provider name.');
+  }
+
+  var config = _providers[providerName];
+  if (!config) {
+    throw new Error('SMS provider "' + providerName + '" not registered.');
+  }
+
+  var action = config.actions[actionName];
+  if (!action) {
+    throw new Error('Action "' + actionName + '" not found on provider "' + providerName + '".');
+  }
+
+  // Merge default params with send-time params
+  var mergedParams = Object.assign({}, config.params || {}, params);
+
+  // Run prerequisite actions (e.g. auth)
+  if (action.before && action.before.length) {
+    for (var i = 0; i < action.before.length; i++) {
+      var beforeName = action.before[i];
+      var beforeAction = config.actions[beforeName];
+      if (!beforeAction) {
+        throw new Error('Before-action "' + beforeName + '" not found on provider "' + providerName + '".');
+      }
+
+      var beforeResult = await _executeAction(beforeAction, mergedParams);
+      if (!beforeResult.ok) {
+        return {
+          success: false,
+          error: 'Pre-action "' + beforeName + '" failed with status ' + beforeResult.status,
+          raw: beforeResult.raw
+        };
+      }
+
+      // Extract values from response into params
+      if (beforeAction.extract && beforeResult.raw) {
+        var extractKeys = Object.keys(beforeAction.extract);
+        for (var j = 0; j < extractKeys.length; j++) {
+          var paramKey = extractKeys[j];
+          var responsePath = beforeAction.extract[paramKey];
+          mergedParams[paramKey] = _extractPath(beforeResult.raw, responsePath);
+        }
+      }
+    }
+  }
+
+  // Execute main action
+  var result = await _executeAction(action, mergedParams);
+
+  // Custom response parser
+  if (config.parseResponse) {
+    return config.parseResponse(result.raw, result);
+  }
+
+  if (!result.ok) {
+    return {
+      success: false,
+      error: (result.raw && (result.raw.message || result.raw.error || result.raw.error_message)) || 'SMS failed with status ' + result.status,
+      raw: result.raw
+    };
+  }
+
+  return {
+    success: true,
+    messageId: result.raw && (result.raw.sid || result.raw.messageId || result.raw.message_id || result.raw.id) || null,
+    raw: result.raw
+  };
+}
+
+/**
+ * Get list of registered provider names.
+ */
+function getProviders() {
+  return Object.keys(_providers);
+}
+
+module.exports = { register, setDefault, send, getProviders };

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@xeplr/utils",
+  "version": "1.0.0",
+  "description": "Utility functions: email (SMTP, AWS SES, Azure, Brevo), cache, queue, logging client, and helpers",
+  "main": "index.js",
+  "files": ["index.js", "lib/", "isomorphic/"],
+  "exports": {
+    ".": "./index.js",
+    "./isomorphic": "./isomorphic/index.js",
+    "./isomorphic/crypto": "./isomorphic/crypto.js",
+    "./isomorphic/countries": "./isomorphic/countries.js",
+    "./isomorphic/states": "./isomorphic/states.js",
+    "./lib/cache": "./lib/cache.js",
+    "./lib/email": "./lib/email.js",
+    "./lib/fileUploader": "./lib/fileUploader.js",
+    "./lib/helpers": "./lib/helpers.js",
+    "./lib/logger": "./lib/logger.js",
+    "./lib/queue": "./lib/queue.js",
+    "./lib/rateLimiter": "./lib/rateLimiter.js",
+    "./lib/response": "./lib/response.js"
+  },
+  "keywords": ["email", "brevo", "ses", "smtp", "cache", "redis", "queue", "logger", "utilities"],
+  "author": "xeplr",
+  "license": "MIT",
+  "repository": { "type": "git", "url": "https://github.com/Xeplr/xeplr-utils" },
+  "publishConfig": { "access": "public" },
+  "dependencies": {
+    "ioredis": "^5.6.1",
+    "multer": "^1.4.5-lts.1",
+    "nodemailer": "^8.0.2"
+  },
+  "peerDependencies": {
+    "@aws-sdk/client-ses": "^3.0.0",
+    "@azure/communication-email": "^1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@aws-sdk/client-ses": { "optional": true },
+    "@azure/communication-email": { "optional": true }
+  }
+}