@xeplr/utils 1.0.0 → 1.0.1

package/index.js

@@ -1,4 +1,4 @@
-const { sendEmail, configureEmail } = require('./lib/email');
+const { sendEmail, configureEmail, emailConfigFromEnv, configureFromEnv } = require('./lib/email');
 const { configureLogger, createSession, log, closeSession, getSessionLogs } = require('./lib/logger');
 const { generateId, formatDbDateTime, mysqlDateTime } = require('./lib/helpers');
 const { respond, sanitizeError } = require('./lib/response');
@@ -7,11 +7,14 @@ const Queue = require('./lib/queue');
 const FileUploader = require('./lib/fileUploader');
 const RateLimiter = require('./lib/rateLimiter');
 const sms = require('./lib/sms');
+const otp = require('./lib/otp');
 
 module.exports = {
   // Email
   sendEmail,
   configureEmail,
+  emailConfigFromEnv,
+  configureFromEnv,
 
   // Logger client
   configureLogger,
@@ -42,5 +45,8 @@ module.exports = {
   RateLimiter,
 
   // SMS
-  sms
+  sms,
+
+  // OTP (uses sms above for delivery)
+  otp
 };

package/isomorphic/crypto.js

@@ -120,4 +120,63 @@ async function decrypt(encrypted, key) {
   return new TextDecoder().decode(decrypted);
 }
 
-module.exports = { encrypt, decrypt };
+/**
+ * Same as encrypt(), but returns the salt separately instead of packing it
+ * into the payload — for callers that store salt in its own column/field
+ * (e.g. to keep the ciphertext opaque even to something inspecting schema,
+ * or to swap in a different encryption backend later that takes salt as an
+ * explicit input rather than embedding it).
+ *
+ * @param {string} plaintext
+ * @param {string} key - Passphrase
+ * @param {string} [salt] - Base64 salt to reuse (e.g. rotating the ciphertext
+ *   without rotating the salt). Omit to generate a new one.
+ * @returns {Promise<{salt: string, ciphertext: string}>} both base64
+ */
+async function encryptSplit(plaintext, key, salt) {
+  var saltBytes = salt ? fromBase64(salt) : new Uint8Array(16);
+  if (!salt) getRandomValues(saltBytes);
+  var iv = new Uint8Array(12);
+  getRandomValues(iv);
+
+  var cryptoKey = await deriveKey(key, saltBytes);
+  var enc = new TextEncoder();
+  var ciphertext = await getSubtle().encrypt(
+    { name: 'AES-GCM', iv: iv },
+    cryptoKey,
+    enc.encode(plaintext)
+  );
+
+  // Pack: iv (12) + ciphertext — salt travels separately.
+  var packed = new Uint8Array(12 + ciphertext.byteLength);
+  packed.set(iv, 0);
+  packed.set(new Uint8Array(ciphertext), 12);
+
+  return { salt: toBase64(saltBytes), ciphertext: toBase64(packed) };
+}
+
+/**
+ * Counterpart to encryptSplit() — salt passed in explicitly rather than read
+ * from the payload.
+ *
+ * @param {string} ciphertext - Base64 payload from encryptSplit()
+ * @param {string} key - Passphrase
+ * @param {string} salt - Base64 salt from encryptSplit()
+ * @returns {Promise<string>} Decrypted plaintext
+ */
+async function decryptSplit(ciphertext, key, salt) {
+  var packed = fromBase64(ciphertext);
+  var iv = packed.slice(0, 12);
+  var data = packed.slice(12);
+
+  var cryptoKey = await deriveKey(key, fromBase64(salt));
+  var decrypted = await getSubtle().decrypt(
+    { name: 'AES-GCM', iv: iv },
+    cryptoKey,
+    data
+  );
+
+  return new TextDecoder().decode(decrypted);
+}
+
+module.exports = { encrypt, decrypt, encryptSplit, decryptSplit };

package/lib/cache.js

@@ -1,4 +1,23 @@
-const Redis = require('ioredis');
+// `ioredis` is an OPTIONAL peer dependency — nothing in xeplr-utils
+// requires Redis unless you actually use the cache. We lazy-require it so
+// projects that never touch cache/queue/sessions never have to install it.
+// If they DO reach for cache without installing ioredis, throw a message
+// that names the fix, not a raw "Cannot find module" from deep in node.
+let Redis = null;
+function loadRedis() {
+  if (Redis) return Redis;
+  try { Redis = require('ioredis'); return Redis; }
+  catch (e) {
+    var err = new Error(
+      "@xeplr/utils/lib/cache: 'ioredis' is not installed. Run `npm install ioredis` " +
+      "in your project. It's an optional peer dependency — only required if you use " +
+      "the cache, queue, or any session-backed feature (xeplr-auth sessions, SSE " +
+      "tickets, email queue)."
+    );
+    err.cause = e;
+    throw err;
+  }
+}
 
 let _client = null;
 let _config = {};
@@ -38,6 +57,7 @@ function configureCache(config = {}) {
 
 function getClient() {
   if (_client) return _client;
+  const RedisCtor = loadRedis();
 
   const opts = {
     host: _config.host || process.env.REDIS_HOST || '127.0.0.1',
@@ -64,7 +84,7 @@ function getClient() {
     // For extreme throughput, use Cluster mode instead.
   };
 
-  _client = new Redis(opts);
+  _client = new RedisCtor(opts);
 
   _client.on('error', (err) => {
     // Silently handle — don't crash the server if Redis is down

package/lib/email.js

@@ -1,4 +1,19 @@
-const nodemailer = require('nodemailer');
+// `nodemailer` is an optional peer dep — lazy-loaded so projects that
+// don't send email don't have to install it (or its transitive deps).
+let _nodemailer = null;
+function loadNodemailer() {
+  if (_nodemailer) return _nodemailer;
+  try { _nodemailer = require('nodemailer'); return _nodemailer; }
+  catch (e) {
+    var err = new Error(
+      "@xeplr/utils/lib/email: 'nodemailer' is not installed. Run `npm install nodemailer` " +
+      "in your project. It's an optional peer dependency — only required if you send email."
+    );
+    err.cause = e;
+    throw err;
+  }
+}
+
 const fs = require('fs');
 const path = require('path');
 
@@ -102,7 +117,7 @@ function buildAttachments(attachments) {
 
 async function sendViaSMTP(to, subject, html, cc, attachments) {
   var cfg = getConfig().smtp;
-  var transporter = nodemailer.createTransport({
+  var transporter = loadNodemailer().createTransport({
     host: cfg.host,
     port: cfg.port,
     secure: false,
@@ -122,7 +137,7 @@ async function sendViaAWS(to, subject, html, cc, attachments) {
   // 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 transporter = loadNodemailer().createTransport({ streamTransport: true });
 
     var mailOptions = { from: cfg.from, to, subject, html };
     if (cc && cc.length) mailOptions.cc = cc;
@@ -300,4 +315,35 @@ async function replayDeadLetters() {
   return items.length;
 }
 
-module.exports = { sendEmail, configureEmail, getDeadLetterQueue, replayDeadLetters };
+// Build an email config from env (EMAIL_PROVIDER + provider vars). Pure — returns
+// the config or null if no provider is set. The single source for env→email config.
+function emailConfigFromEnv() {
+  var provider = process.env.EMAIL_PROVIDER;
+  if (!provider) return null;
+
+  var config = { provider: provider };
+  if (provider === 'brevo') {
+    config.brevo = {
+      apiKey: process.env.BREVO_API_KEY,
+      fromEmail: process.env.BREVO_FROM_EMAIL,
+      fromName: process.env.BREVO_FROM_NAME
+    };
+  } else if (provider === 'smtp') {
+    config.smtp = {
+      host: process.env.SMTP_HOST, port: process.env.SMTP_PORT,
+      user: process.env.SMTP_USER, pass: process.env.SMTP_PASS, from: process.env.SMTP_FROM
+    };
+  }
+  // aws / azure read their own vars here when those providers are used.
+  return config;
+}
+
+// Configure the email sender straight from env. Returns true if a provider was set.
+function configureFromEnv() {
+  var config = emailConfigFromEnv();
+  if (!config) return false;
+  configureEmail(config);
+  return true;
+}
+
+module.exports = { sendEmail, configureEmail, emailConfigFromEnv, configureFromEnv, getDeadLetterQueue, replayDeadLetters };

package/lib/fileUploader.js

@@ -1,4 +1,19 @@
-const multer = require('multer');
+// `multer` is an optional peer dep — lazy-loaded so projects that
+// don't handle multipart uploads don't have to install it.
+let _multer = null;
+function loadMulter() {
+  if (_multer) return _multer;
+  try { _multer = require('multer'); return _multer; }
+  catch (e) {
+    var err = new Error(
+      "@xeplr/utils/lib/fileUploader: 'multer' is not installed. Run `npm install multer` " +
+      "in your project. It's an optional peer dependency — only required if you handle file uploads."
+    );
+    err.cause = e;
+    throw err;
+  }
+}
+
 const path = require('path');
 const fs = require('fs');
 const { generateId } = require('./helpers');
@@ -21,6 +36,7 @@ class FileUploader {
       fs.mkdirSync(this._destination, { recursive: true });
     }
 
+    var multer = loadMulter();
     this._multer = multer({
       storage: multer.diskStorage({
         destination: (req, file, cb) => {

package/lib/otp.js

@@ -0,0 +1,111 @@
+/**
+ * OTP (one-time password) — generate, deliver, and verify short-lived codes.
+ * Delivery goes through THIS package's own sms module (see lib/sms.js: register
+ * a provider there, then otp.js sends through it) — no separate provider
+ * registration here, one registry to keep in sync.
+ *
+ * Codes live in Redis (lib/cache.js) — no DB table, no cleanup job. Expiry is
+ * just the Redis key's TTL.
+ *
+ * Usage:
+ *   var otp = require('@xeplr/utils').otp;
+ *   otp.configureOtp({ provider: 'twilio' });   // optional — see defaults below
+ *
+ *   await otp.requestOtp('+91...');              // generates + sends a code
+ *   await otp.verifyOtp('+91...', '482913');     // { success: true } or { success:false, reason }
+ */
+const crypto = require('crypto');
+const cache = require('./cache');
+const sms = require('./sms');
+
+var _config = {
+  codeLength: 6,
+  ttlSeconds: 300,     // 5 minutes
+  maxAttempts: 5,
+  keyPrefix: 'otp:',
+  provider: null,       // sms provider name (see lib/sms.js register()); falls back to sms.setDefault()
+  message: function(code) { return 'Your verification code is ' + code; }
+};
+
+/**
+ * Configure OTP policy. All optional — defaults above apply otherwise.
+ * @param {object} config
+ * @param {number} [config.codeLength=6]
+ * @param {number} [config.ttlSeconds=300]
+ * @param {number} [config.maxAttempts=5]
+ * @param {string} [config.provider] - sms provider name registered via sms.register()
+ * @param {function} [config.message] - (code) => string, the SMS body
+ */
+function configureOtp(config) {
+  Object.assign(_config, config || {});
+}
+
+function generateCode() {
+  var max = Math.pow(10, _config.codeLength);
+  var code = crypto.randomInt(0, max);
+  return String(code).padStart(_config.codeLength, '0');
+}
+
+function otpKey(identifier) {
+  return _config.keyPrefix + identifier;
+}
+
+/**
+ * Generate a code, store it, and send it via the configured SMS provider.
+ * @param {string} identifier - phone number (or any unique key) the code is tied to
+ * @returns {Promise<{ sent: boolean }>}
+ */
+async function requestOtp(identifier) {
+  var code = generateCode();
+  await cache.set(otpKey(identifier), { code: code, attempts: 0 }, _config.ttlSeconds);
+
+  var message = _config.message(code);
+  var result = _config.provider
+    ? await sms.send(_config.provider, { to: identifier, message: message })
+    : await sms.send({ to: identifier, message: message });
+
+  if (!result.success) {
+    await cache.del(otpKey(identifier));
+    throw new Error('Failed to send OTP: ' + (result.error || 'unknown error'));
+  }
+  return { sent: true };
+}
+
+/**
+ * Verify a submitted code against the stored one. Single-use — deleted on
+ * success. maxAttempts is the real security bound (not TTL precision): a
+ * wrong guess re-arms the same TTL window rather than tracking remaining
+ * time, so repeated wrong guesses can extend the window, but never the
+ * attempt count past maxAttempts.
+ * @param {string} identifier
+ * @param {string} code
+ * @returns {Promise<{ success: boolean, reason?: 'expired'|'invalid'|'too_many_attempts' }>}
+ */
+async function verifyOtp(identifier, code) {
+  var key = otpKey(identifier);
+  var record = await cache.get(key);
+
+  if (!record) {
+    return { success: false, reason: 'expired' };
+  }
+
+  if (record.attempts >= _config.maxAttempts) {
+    await cache.del(key);
+    return { success: false, reason: 'too_many_attempts' };
+  }
+
+  if (String(code) !== record.code) {
+    record.attempts += 1;
+    if (record.attempts >= _config.maxAttempts) {
+      await cache.del(key);
+      return { success: false, reason: 'too_many_attempts' };
+    }
+    await cache.set(key, record, _config.ttlSeconds);
+    return { success: false, reason: 'invalid' };
+  }
+
+  await cache.del(key);
+  return { success: true };
+}
+
+module.exports = { configureOtp, requestOtp, verifyOtp };

package/lib/queue.js

@@ -157,4 +157,326 @@ class Queue {
   }
 }
 
+// ─────────────────────────────────────────────────────────────────────────
+// SqlQueue — in-memory concurrent worker pool for SQL execution.
+//
+// Movement-scoped: every item carries a `movementId`. Rollback is by
+// movementId. Aborting drops all queued items for one movement without
+// affecting others.
+//
+// Retry / bisect / drop / abort behavior:
+//   - Up to `maxAttempts` per item (default 3); errorExecutor decides
+//     what to do on each failure ('retry' | 'bisect' | 'error-table' |
+//     'drop' | 'fatal').
+//   - 'bisect' splits `item.meta.rows` in half, regenerates two child
+//     SQL statements via `item.meta.rowsToSql(rows)`, and re-enqueues both.
+//   - 'error-table' calls `onErrorTable({item, error, rowNum})` and counts
+//     as a drop.
+//   - `maxConsecutiveDrops` (default 5) drops within the same movement
+//     → auto-abort that movement.
+//   - 'fatal' → auto-abort that movement immediately.
+//
+// Backpressure: total serialized item bytes ≤ `maxMemoryMB * 1024 * 1024`
+// (default 200MB high water). `addToQueue` returns a promise that awaits
+// when over the ceiling, resumes at 75% low water.
+//
+// Encrypted connections: `connections: { name: encryptedString | plainConfig }`
+// + `encryptionKey`. String values are decrypted via
+// `@xeplr/utils/isomorphic/crypto` on first use and cached.
+class SqlQueue {
+  constructor(options) {
+    options = options || {};
+    if (typeof options.executor !== 'function') {
+      throw new Error('SqlQueue: options.executor is required (async (item, resolvedConn) => void)');
+    }
+    this.executor           = options.executor;
+    this.errorExecutor      = options.errorExecutor      || defaultErrorExecutor;
+    this.onErrorTable       = options.onErrorTable       || function() {};
+    this.onMovementAbort    = options.onMovementAbort    || function() {};
+    this.concurrency        = options.concurrency        || 4;
+    this.maxAttempts        = options.maxAttempts        || 3;
+    this.maxConsecutiveDrops= options.maxConsecutiveDrops|| 5;
+    this.maxMemoryBytes     = (options.maxMemoryMB       || 200) * 1024 * 1024;
+    this.lowMemoryBytes     = Math.floor(this.maxMemoryBytes * 0.75);
+    this.retryDelaysMs      = options.retryDelaysMs      || [5000, 15000, 45000];
+    this.connections        = options.connections        || {};
+    this.encryptionKey      = options.encryptionKey      || null;
+
+    this._items       = [];
+    this._itemId      = 0;
+    this._byteTotal   = 0;
+    this._inFlight    = 0;
+    this._pendingRetries = 0;               // items awaiting their retry setTimeout
+    this._stopped     = false;
+    this._paused      = false;
+    this._pressureWaiters = [];
+    this._idleWaiters = [];
+    this._resolved    = {};                 // decrypted connection cache
+    this._movements   = new Map();          // movementId → state
+
+    this._workers = [];
+    for (var i = 0; i < this.concurrency; i++) {
+      this._workers.push(this._workerLoop());
+    }
+  }
+
+  // Enqueue an item. Awaits when the queue is over its memory ceiling.
+  // Item shape:
+  //   { movementId, connection, sql?, meta: { rows?, rowsToSql?, errorTable?, ... }, attempt? }
+  // `sql` is generated from `meta.rowsToSql(meta.rows)` if not supplied.
+  async addToQueue(item) {
+    if (this._stopped) throw new Error('SqlQueue is stopped');
+    if (!item || !item.movementId) throw new Error('addToQueue: item.movementId is required');
+    if (!item.sql && item.meta && typeof item.meta.rowsToSql === 'function' && Array.isArray(item.meta.rows)) {
+      var builtA = item.meta.rowsToSql(item.meta.rows);
+      if (typeof builtA === 'string') { item.sql = builtA; }
+      else if (builtA && builtA.sql)  { item.sql = builtA.sql; if (builtA.params != null) item.params = builtA.params; }
+    }
+    if (!item.sql) throw new Error('addToQueue: item.sql is required (or provide meta.rowsToSql + meta.rows)');
+
+    while (this._byteTotal >= this.maxMemoryBytes) {
+      await new Promise(function(res) { this._pressureWaiters.push(res); }.bind(this));
+    }
+
+    item.id      = ++this._itemId;
+    item.attempt = item.attempt || 0;
+    item.bytes   = approximateBytes(item);
+    this._byteTotal += item.bytes;
+    this._items.push(item);
+
+    var state = this._stateFor(item.movementId);
+    state.queued++;
+  }
+
+  // Abort a movement. Drops queued items for that movement and prevents
+  // in-flight retries. Emits onMovementAbort. In-flight SQLs are allowed
+  // to settle — caller runs uploader.rollback() to clean the DB.
+  abort(movementId, reason) {
+    var state = this._stateFor(movementId);
+    if (state.aborted) return;
+    state.aborted = true;
+    state.abortReason = reason || 'aborted';
+
+    var kept = [];
+    for (var i = 0; i < this._items.length; i++) {
+      var it = this._items[i];
+      if (it.movementId === movementId) {
+        this._byteTotal -= it.bytes;
+        state.queued--;
+        state.dropped++;
+      } else {
+        kept.push(it);
+      }
+    }
+    this._items = kept;
+    this._releaseBackpressure();
+
+    try { this.onMovementAbort({ movementId: movementId, reason: state.abortReason }); }
+    catch (e) { /* swallow — never let a hook block */ }
+  }
+
+  // Stats: per-movement if id passed, else global.
+  stats(movementId) {
+    if (movementId) {
+      var s = this._movements.get(movementId);
+      return s ? Object.assign({}, s) : null;
+    }
+    var total = { queued: this._items.length, inFlight: this._inFlight, bytes: this._byteTotal, movements: this._movements.size };
+    return total;
+  }
+
+  // Resolve when the queue drains AND no items are in flight AND no
+  // retry is pending. Useful after a spool ends and before checking
+  // final counts.
+  async drain() {
+    while (this._items.length > 0 || this._inFlight > 0 || this._pendingRetries > 0) {
+      await new Promise(function(res) { this._idleWaiters.push(res); }.bind(this));
+    }
+  }
+
+  pause()   { this._paused = true; }
+  resume()  { if (this._paused) { this._paused = false; this._kick(); } }
+  stop()    { this._stopped = true; this._paused = true; this._releaseBackpressure(); }
+
+  // ─── internal ─────────────────────────────────────────────────────────
+  _stateFor(movementId) {
+    var s = this._movements.get(movementId);
+    if (!s) {
+      s = { movementId: movementId, queued: 0, inFlight: 0, completed: 0, dropped: 0, aborted: false, abortReason: null, consecutiveDrops: 0 };
+      this._movements.set(movementId, s);
+    }
+    return s;
+  }
+
+  async _workerLoop() {
+    while (!this._stopped) {
+      if (this._paused || this._items.length === 0 || this._byteTotal === 0) {
+        await sleep(25);
+        this._maybeSignalIdle();
+        continue;
+      }
+      // Pick the first item whose movement isn't aborted.
+      var idx = -1;
+      for (var i = 0; i < this._items.length; i++) {
+        var m = this._items[i].movementId;
+        if (!this._stateFor(m).aborted) { idx = i; break; }
+      }
+      if (idx < 0) { await sleep(25); continue; }
+
+      var item = this._items.splice(idx, 1)[0];
+      this._byteTotal -= item.bytes;
+      this._releaseBackpressure();
+
+      var state = this._stateFor(item.movementId);
+      state.queued--;
+      state.inFlight++;
+      this._inFlight++;
+
+      try { await this._processItem(item, state); }
+      catch (e) { /* processItem never throws — belt and braces */ }
+      finally { state.inFlight--; this._inFlight--; this._maybeSignalIdle(); }
+    }
+  }
+
+  async _processItem(item, state) {
+    if (state.aborted) return;
+
+    var conn;
+    try { conn = await this._resolveConnection(item.connection); }
+    catch (err) {
+      // Connection resolution failure = fatal for the movement.
+      state.dropped++;
+      this.abort(item.movementId, 'connection_resolve_failed: ' + err.message);
+      return;
+    }
+
+    item.attempt++;
+    try {
+      await this.executor(item, conn);
+      state.completed++;
+      state.consecutiveDrops = 0;
+      return;
+    } catch (err) {
+      var attemptedFinal = item.attempt >= this.maxAttempts;
+      var decision = await this.errorExecutor({ item: item, error: err, attempt: item.attempt, isFinal: attemptedFinal });
+      decision = decision || {};
+
+      if (decision.decision === 'retry' && !attemptedFinal && !state.aborted) {
+        // Delays indexed by "which retry": 1st retry uses [0], 2nd uses [1], etc.
+        var delayIdx = Math.min(item.attempt - 1, this.retryDelaysMs.length - 1);
+        var delay = decision.delayMs != null ? decision.delayMs : this.retryDelaysMs[delayIdx];
+        this._pendingRetries++;
+        setTimeout(function() {
+          this._pendingRetries--;
+          if (!state.aborted && !this._stopped) {
+            item.bytes = approximateBytes(item);
+            this._byteTotal += item.bytes;
+            this._items.push(item);
+            state.queued++;
+          }
+          this._maybeSignalIdle();
+        }.bind(this), delay);
+        return;
+      }
+
+      if (decision.decision === 'bisect' && item.meta && Array.isArray(item.meta.rows) && item.meta.rows.length > 1) {
+        var mid = Math.floor(item.meta.rows.length / 2);
+        var left = cloneItemWithRows(item, item.meta.rows.slice(0, mid));
+        var right = cloneItemWithRows(item, item.meta.rows.slice(mid));
+        await this.addToQueue(left);
+        await this.addToQueue(right);
+        return;
+      }
+
+      if (decision.decision === 'fatal') {
+        this.abort(item.movementId, 'fatal: ' + (decision.reason || err.message));
+        return;
+      }
+
+      // 'error-table' | 'drop' | anything else past max attempts → drop
+      state.dropped++;
+      state.consecutiveDrops++;
+      try {
+        this.onErrorTable({
+          item: item,
+          error: err,
+          rowNum: item.meta && item.meta.rowNum,
+          reason: decision.reason || err.message
+        });
+      } catch (_) { /* swallow */ }
+      if (state.consecutiveDrops >= this.maxConsecutiveDrops) {
+        this.abort(item.movementId, 'consecutive_drops_exceeded');
+      }
+    }
+  }
+
+  async _resolveConnection(name) {
+    if (this._resolved[name]) return this._resolved[name];
+    var raw = this.connections[name];
+    if (raw === undefined) throw new Error('SqlQueue: unknown connection "' + name + '"');
+    if (typeof raw === 'object') { this._resolved[name] = raw; return raw; }
+    if (typeof raw !== 'string')  throw new Error('SqlQueue: connection "' + name + '" must be encrypted string or plain object');
+    if (!this.encryptionKey)      throw new Error('SqlQueue: encryptionKey required to decrypt connection "' + name + '"');
+    var { decrypt } = require('../isomorphic/crypto');
+    var decrypted = await decrypt(raw, this.encryptionKey);
+    var config = JSON.parse(decrypted);
+    this._resolved[name] = config;
+    return config;
+  }
+
+  _releaseBackpressure() {
+    if (this._byteTotal <= this.lowMemoryBytes && this._pressureWaiters.length) {
+      var waiters = this._pressureWaiters;
+      this._pressureWaiters = [];
+      for (var i = 0; i < waiters.length; i++) waiters[i]();
+    }
+  }
+
+  _maybeSignalIdle() {
+    if (this._items.length === 0 && this._inFlight === 0 && this._pendingRetries === 0 && this._idleWaiters.length) {
+      var waiters = this._idleWaiters;
+      this._idleWaiters = [];
+      for (var i = 0; i < waiters.length; i++) waiters[i]();
+    }
+  }
+
+  _kick() { /* worker loops poll — nothing to do */ }
+}
+
+function defaultErrorExecutor(ctx) {
+  // Default: retry until final attempt, then route the row (or the whole
+  // batch if not bisectable) to the error table.
+  if (!ctx.isFinal) return { decision: 'retry' };
+  if (ctx.item.meta && Array.isArray(ctx.item.meta.rows) && ctx.item.meta.rows.length > 1) {
+    return { decision: 'bisect' };
+  }
+  return { decision: 'error-table', reason: ctx.error && ctx.error.message };
+}
+
+function cloneItemWithRows(item, rows) {
+  var clonedMeta = Object.assign({}, item.meta, { rows: rows, rowCount: rows.length });
+  var next = {
+    movementId: item.movementId,
+    connection: item.connection,
+    meta:       clonedMeta,
+    attempt:    0
+  };
+  if (typeof clonedMeta.rowsToSql === 'function') {
+    var built = clonedMeta.rowsToSql(rows);
+    if (typeof built === 'string') { next.sql = built; next.params = item.params; }
+    else if (built && built.sql)   { next.sql = built.sql; next.params = built.params; }
+  } else {
+    next.sql = item.sql; next.params = item.params;
+  }
+  return next;
+}
+
+function approximateBytes(item) {
+  try { return JSON.stringify(item).length; } catch (_) { return 128; }
+}
+
+function sleep(ms) { return new Promise(function(res) { setTimeout(res, ms); }); }
+
 module.exports = Queue;
+module.exports.Queue = Queue;
+module.exports.SqlQueue = SqlQueue;

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@xeplr/utils",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Utility functions: email (SMTP, AWS SES, Azure, Brevo), cache, queue, logging client, and helpers",
   "main": "index.js",
-  "files": ["index.js", "lib/", "isomorphic/"],
+  "files": [
+    "index.js",
+    "lib/",
+    "isomorphic/"
+  ],
   "exports": {
     ".": "./index.js",
     "./isomorphic": "./isomorphic/index.js",
@@ -15,26 +19,55 @@
     "./lib/fileUploader": "./lib/fileUploader.js",
     "./lib/helpers": "./lib/helpers.js",
     "./lib/logger": "./lib/logger.js",
+    "./lib/otp": "./lib/otp.js",
     "./lib/queue": "./lib/queue.js",
     "./lib/rateLimiter": "./lib/rateLimiter.js",
-    "./lib/response": "./lib/response.js"
+    "./lib/response": "./lib/response.js",
+    "./lib/sms": "./lib/sms.js"
   },
-  "keywords": ["email", "brevo", "ses", "smtp", "cache", "redis", "queue", "logger", "utilities"],
+  "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"
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Xeplr/xeplr-utils"
+  },
+  "publishConfig": {
+    "access": "public"
   },
+  "dependencies": {},
   "peerDependencies": {
     "@aws-sdk/client-ses": "^3.0.0",
-    "@azure/communication-email": "^1.0.0"
+    "@azure/communication-email": "^1.0.0",
+    "ioredis": "^5.6.1",
+    "multer": "^1.4.5-lts.1",
+    "nodemailer": "^8.0.2"
   },
   "peerDependenciesMeta": {
-    "@aws-sdk/client-ses": { "optional": true },
-    "@azure/communication-email": { "optional": true }
+    "@aws-sdk/client-ses": {
+      "optional": true
+    },
+    "@azure/communication-email": {
+      "optional": true
+    },
+    "ioredis": {
+      "optional": true
+    },
+    "multer": {
+      "optional": true
+    },
+    "nodemailer": {
+      "optional": true
+    }
   }
 }