@xeplr/utils 1.0.0

package/isomorphic/crypto.js

@@ -0,0 +1,123 @@
+/**
+ * AES-256-GCM encrypt/decrypt — isomorphic (browser + Node).
+ * Uses Web Crypto API (available in all modern browsers and Node 16+).
+ * Zero dependencies.
+ *
+ * Usage:
+ *   var { encrypt, decrypt } = require('@xeplr/utils/isomorphic/crypto');
+ *
+ *   var encrypted = await encrypt('hello world', 'my-secret-key');
+ *   var decrypted = await decrypt(encrypted, 'my-secret-key');
+ *   // decrypted === 'hello world'
+ */
+
+var subtle = typeof globalThis !== 'undefined' && globalThis.crypto && globalThis.crypto.subtle
+  ? globalThis.crypto.subtle
+  : null;
+
+function getSubtle() {
+  if (subtle) return subtle;
+  // Node fallback
+  var nodeCrypto = require('crypto');
+  return nodeCrypto.webcrypto.subtle;
+}
+
+function getRandomValues(buf) {
+  if (typeof globalThis !== 'undefined' && globalThis.crypto) {
+    return globalThis.crypto.getRandomValues(buf);
+  }
+  var nodeCrypto = require('crypto');
+  return nodeCrypto.webcrypto.getRandomValues(buf);
+}
+
+/**
+ * Derive a 256-bit key from a passphrase using PBKDF2.
+ */
+async function deriveKey(passphrase, salt) {
+  var s = getSubtle();
+  var enc = new TextEncoder();
+  var keyMaterial = await s.importKey('raw', enc.encode(passphrase), 'PBKDF2', false, ['deriveKey']);
+  return s.deriveKey(
+    { name: 'PBKDF2', salt: salt, iterations: 100000, hash: 'SHA-256' },
+    keyMaterial,
+    { name: 'AES-GCM', length: 256 },
+    false,
+    ['encrypt', 'decrypt']
+  );
+}
+
+function toBase64(buf) {
+  var bytes = new Uint8Array(buf);
+  if (typeof btoa === 'function') {
+    var binary = '';
+    for (var i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
+    return btoa(binary);
+  }
+  return Buffer.from(bytes).toString('base64');
+}
+
+function fromBase64(str) {
+  if (typeof atob === 'function') {
+    var binary = atob(str);
+    var bytes = new Uint8Array(binary.length);
+    for (var i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+    return bytes;
+  }
+  return new Uint8Array(Buffer.from(str, 'base64'));
+}
+
+/**
+ * Encrypt a string with a passphrase.
+ * Returns a base64 string containing salt + iv + ciphertext.
+ *
+ * @param {string} plaintext - Text to encrypt
+ * @param {string} key - Passphrase
+ * @returns {Promise<string>} Base64-encoded encrypted payload
+ */
+async function encrypt(plaintext, key) {
+  var salt = new Uint8Array(16);
+  getRandomValues(salt);
+  var iv = new Uint8Array(12);
+  getRandomValues(iv);
+
+  var cryptoKey = await deriveKey(key, salt);
+  var enc = new TextEncoder();
+  var ciphertext = await getSubtle().encrypt(
+    { name: 'AES-GCM', iv: iv },
+    cryptoKey,
+    enc.encode(plaintext)
+  );
+
+  // Pack: salt (16) + iv (12) + ciphertext
+  var packed = new Uint8Array(16 + 12 + ciphertext.byteLength);
+  packed.set(salt, 0);
+  packed.set(iv, 16);
+  packed.set(new Uint8Array(ciphertext), 28);
+
+  return toBase64(packed);
+}
+
+/**
+ * Decrypt a base64 payload with a passphrase.
+ *
+ * @param {string} encrypted - Base64-encoded encrypted payload from encrypt()
+ * @param {string} key - Passphrase (must match the one used to encrypt)
+ * @returns {Promise<string>} Decrypted plaintext
+ */
+async function decrypt(encrypted, key) {
+  var packed = fromBase64(encrypted);
+  var salt = packed.slice(0, 16);
+  var iv = packed.slice(16, 28);
+  var ciphertext = packed.slice(28);
+
+  var cryptoKey = await deriveKey(key, salt);
+  var decrypted = await getSubtle().decrypt(
+    { name: 'AES-GCM', iv: iv },
+    cryptoKey,
+    ciphertext
+  );
+
+  return new TextDecoder().decode(decrypted);
+}
+
+module.exports = { encrypt, decrypt };

package/isomorphic/emailNormalizer.js

@@ -0,0 +1,56 @@
+/**
+ * Email normalizer — strips dots and plus-aliases for known providers.
+ * Prevents vikas.bhandari@gmail.com and vikasbhandari@gmail.com from being different users.
+ *
+ * Known dot-insensitive providers:
+ *   Gmail, Google Workspace, Googlemail
+ *
+ * Also strips +alias for these providers:
+ *   vikas+test@gmail.com → vikas@gmail.com
+ */
+
+var DOT_INSENSITIVE_DOMAINS = [
+  'gmail.com',
+  'googlemail.com'
+];
+
+/**
+ * Normalize an email for duplicate detection.
+ * Returns lowercase, dot-stripped (for known providers), plus-alias stripped.
+ *
+ * @param {string} email
+ * @returns {string} Normalized email
+ */
+function normalizeEmail(email) {
+  if (!email || typeof email !== 'string') return '';
+
+  var parts = email.trim().toLowerCase().split('@');
+  if (parts.length !== 2) return email.trim().toLowerCase();
+
+  var local = parts[0];
+  var domain = parts[1];
+
+  // Strip +alias for known providers
+  if (isDotInsensitive(domain)) {
+    var plusIndex = local.indexOf('+');
+    if (plusIndex > 0) {
+      local = local.slice(0, plusIndex);
+    }
+    // Strip dots
+    local = local.replace(/\./g, '');
+  }
+
+  return local + '@' + domain;
+}
+
+/**
+ * Check if a domain ignores dots in the local part.
+ */
+function isDotInsensitive(domain) {
+  for (var i = 0; i < DOT_INSENSITIVE_DOMAINS.length; i++) {
+    if (domain === DOT_INSENSITIVE_DOMAINS[i]) return true;
+  }
+  return false;
+}
+
+module.exports = { normalizeEmail, isDotInsensitive };

package/isomorphic/helpers.js

@@ -0,0 +1,52 @@
+/**
+ * Pure JS helpers — safe for both browser and Node.
+ * No Node-specific APIs (crypto, fs, etc.).
+ */
+
+/**
+ * Format a Date as ISO datetime string for database storage.
+ */
+function formatDbDateTime(date) {
+  return (date || new Date()).toISOString();
+}
+
+/**
+ * Format a Date for display (e.g. "15 Mar 2026").
+ */
+function formatDate(date, locale = 'en-GB') {
+  return (date || new Date()).toLocaleDateString(locale, {
+    day: 'numeric', month: 'short', year: 'numeric'
+  });
+}
+
+/**
+ * Format a Date for display with time (e.g. "15 Mar 2026, 14:30").
+ */
+function formatDateTime(date, locale = 'en-GB') {
+  return (date || new Date()).toLocaleDateString(locale, {
+    day: 'numeric', month: 'short', year: 'numeric',
+    hour: '2-digit', minute: '2-digit'
+  });
+}
+
+/**
+ * Simple deep-clone using structured clone (works in modern browsers + Node 17+).
+ * Falls back to JSON parse/stringify.
+ */
+function deepClone(obj) {
+  if (typeof structuredClone === 'function') return structuredClone(obj);
+  return JSON.parse(JSON.stringify(obj));
+}
+
+/**
+ * Check if a value is empty (null, undefined, '', [], {}).
+ */
+function isEmpty(value) {
+  if (value == null) return true;
+  if (typeof value === 'string') return value.trim() === '';
+  if (Array.isArray(value)) return value.length === 0;
+  if (typeof value === 'object') return Object.keys(value).length === 0;
+  return false;
+}
+
+module.exports = { formatDbDateTime, mysqlDateTime: formatDbDateTime, formatDate, formatDateTime, deepClone, isEmpty };

package/isomorphic/index.js

@@ -0,0 +1,93 @@
+/**
+ * xeplr-utils/isomorphic — runs everywhere (browser + Node).
+ * Zero Node-specific dependencies.
+ *
+ * Usage:
+ *   // Backend (CJS)
+ *   const { HTTP, STATUS, MESSAGES, msg } = require('@xeplr/utils/isomorphic');
+ *
+ *   // UI (ESM via Vite)
+ *   import { HTTP, STATUS, MESSAGES, msg } from 'xeplr-utils/isomorphic';
+ */
+
+const { HTTP, STATUS } = require('./codes');
+const { MESSAGES } = require('./messages');
+const { readResponse } = require('./responseReader');
+const helpers = require('./helpers');
+const { encrypt, decrypt } = require('./crypto');
+const { normalizeEmail, isDotInsensitive } = require('./emailNormalizer');
+const { COUNTRIES } = require('./countries');
+const { STATES, STATES_IN } = require('./states');
+
+// --- Language resolution ---
+
+let _lang = null;
+
+/**
+ * Set the active language explicitly.
+ *   configureLang('fr');
+ */
+function configureLang(lang) {
+  _lang = lang;
+}
+
+/**
+ * Get current language.
+ * Priority: configureLang() > APP_LANG env var > 'en'
+ */
+function getLang() {
+  if (_lang) return _lang;
+
+  if (typeof process !== 'undefined' && process.env && process.env.APP_LANG) {
+    return process.env.APP_LANG;
+  }
+
+  if (typeof window !== 'undefined' && window.__APP_LANG__) {
+    return window.__APP_LANG__;
+  }
+
+  return 'en';
+}
+
+/**
+ * Get the i18n message string for a message key.
+ *   msg('success')        → 'Success'
+ *   msg('success', 'fr')  → 'Succès'
+ */
+function msg(messageKey, lang) {
+  const l = lang || getLang();
+  const m = MESSAGES[messageKey];
+  if (!m) return messageKey;
+  return m[l] || m.en;
+}
+
+module.exports = {
+  // Language
+  configureLang,
+  getLang,
+  msg,
+
+  // Constants
+  HTTP,
+  STATUS,
+  MESSAGES,
+
+  // Response reader
+  readResponse,
+
+  // Helpers
+  ...helpers,
+
+  // Crypto
+  encrypt,
+  decrypt,
+
+  // Email normalization
+  normalizeEmail,
+  isDotInsensitive,
+
+  // Static lookups
+  COUNTRIES,
+  STATES,
+  STATES_IN
+};

package/isomorphic/messages.js

@@ -0,0 +1,36 @@
+/**
+ * i18n message dictionary.
+ * Reusable strings keyed by a readable name.
+ * CODES reference these by message key.
+ *
+ * Add new languages by adding a key to each entry.
+ * Add new messages as needed — not limited to response codes.
+ */
+
+const MESSAGES = {
+  success:                { en: 'Success',                           fr: 'Succès' },
+  created:                { en: 'Created successfully',              fr: 'Créé avec succès' },
+  updated:                { en: 'Updated successfully',              fr: 'Mis à jour avec succès' },
+  deleted:                { en: 'Deleted successfully',              fr: 'Supprimé avec succès' },
+
+  bad_request:            { en: 'Bad request',                       fr: 'Requête invalide' },
+  unauthorized:           { en: 'Unauthorized',                      fr: 'Non autorisé' },
+  access_denied:          { en: 'Access denied',                     fr: 'Accès refusé' },
+  not_found:              { en: 'Not found',                         fr: 'Non trouvé' },
+  already_exists:         { en: 'Already exists',                    fr: 'Existe déjà' },
+  validation_failed:      { en: 'Validation failed',                 fr: 'Échec de validation' },
+  too_many_requests:      { en: 'Too many requests',                 fr: 'Trop de requêtes' },
+
+  server_error:           { en: 'Internal server error',             fr: 'Erreur interne du serveur' },
+  service_unavailable:    { en: 'Service temporarily unavailable',   fr: 'Service temporairement indisponible' },
+
+  login_success:          { en: 'Logged in successfully',            fr: 'Connexion réussie' },
+  login_failed:           { en: 'Invalid email or password',         fr: 'Email ou mot de passe invalide' },
+  logout_success:         { en: 'Logged out successfully',           fr: 'Déconnexion réussie' },
+  account_not_active:     { en: 'Account is not activated',          fr: 'Le compte n\'est pas activé' },
+  password_reset_sent:    { en: 'Password reset link sent',          fr: 'Lien de réinitialisation envoyé' },
+  password_reset_success: { en: 'Password reset successfully',       fr: 'Mot de passe réinitialisé avec succès' },
+  invalid_token:          { en: 'Invalid or expired token',          fr: 'Jeton invalide ou expiré' },
+};
+
+module.exports = { MESSAGES };

package/isomorphic/responseReader.js

@@ -0,0 +1,57 @@
+/**
+ * Response reader — parses the standard API response format.
+ * Isomorphic — works in browser and Node.
+ *
+ * Usage:
+ *   import { readResponse } from 'xeplr-utils/isomorphic';
+ *
+ *   const result = readResponse(apiResponse);
+ *   if (result.ok) {
+ *     renderTable(result.dataArray);
+ *   } else {
+ *     showToast(result.message);
+ *     console.log(result.error);
+ *   }
+ */
+
+/**
+ * @param {object} response - The API response body
+ * @returns {object} Parsed response with convenience getters
+ */
+function readResponse(response) {
+  const code       = response.code       || '';
+  const message    = response.message    || '';
+  const error      = response.error      || null;
+  const dataArray  = response.dataArray  || [];
+  const updatedIds = response.updatedIds || [];
+
+  return {
+    code,
+    message,
+    error,
+    dataArray,
+    updatedIds,
+
+    /** true if no error object present */
+    ok: error === null,
+
+    /** true if error object present */
+    hasError: error !== null,
+
+    /** true if dataArray has items */
+    hasData: dataArray.length > 0,
+
+    /** true if updatedIds has items */
+    hasUpdates: updatedIds.length > 0,
+
+    /** First item from dataArray, or null */
+    first: dataArray.length > 0 ? dataArray[0] : null,
+
+    /** Check if response code matches a specific STATUS */
+    is(statusCode) {
+      return code === statusCode;
+    },
+  };
+}
+
+module.exports = { readResponse };

package/isomorphic/states.js

@@ -0,0 +1,44 @@
+var STATES_IN = [
+  { code: 'AN', name: 'Andaman and Nicobar Islands' },
+  { code: 'AP', name: 'Andhra Pradesh' },
+  { code: 'AR', name: 'Arunachal Pradesh' },
+  { code: 'AS', name: 'Assam' },
+  { code: 'BR', name: 'Bihar' },
+  { code: 'CH', name: 'Chandigarh' },
+  { code: 'CT', name: 'Chhattisgarh' },
+  { code: 'DN', name: 'Dadra and Nagar Haveli and Daman and Diu' },
+  { code: 'DL', name: 'Delhi' },
+  { code: 'GA', name: 'Goa' },
+  { code: 'GJ', name: 'Gujarat' },
+  { code: 'HR', name: 'Haryana' },
+  { code: 'HP', name: 'Himachal Pradesh' },
+  { code: 'JK', name: 'Jammu and Kashmir' },
+  { code: 'JH', name: 'Jharkhand' },
+  { code: 'KA', name: 'Karnataka' },
+  { code: 'KL', name: 'Kerala' },
+  { code: 'LA', name: 'Ladakh' },
+  { code: 'LD', name: 'Lakshadweep' },
+  { code: 'MP', name: 'Madhya Pradesh' },
+  { code: 'MH', name: 'Maharashtra' },
+  { code: 'MN', name: 'Manipur' },
+  { code: 'ML', name: 'Meghalaya' },
+  { code: 'MZ', name: 'Mizoram' },
+  { code: 'NL', name: 'Nagaland' },
+  { code: 'OR', name: 'Odisha' },
+  { code: 'PY', name: 'Puducherry' },
+  { code: 'PB', name: 'Punjab' },
+  { code: 'RJ', name: 'Rajasthan' },
+  { code: 'SK', name: 'Sikkim' },
+  { code: 'TN', name: 'Tamil Nadu' },
+  { code: 'TG', name: 'Telangana' },
+  { code: 'TR', name: 'Tripura' },
+  { code: 'UP', name: 'Uttar Pradesh' },
+  { code: 'UT', name: 'Uttarakhand' },
+  { code: 'WB', name: 'West Bengal' },
+];
+
+var STATES = {
+  IN: STATES_IN,
+};
+
+module.exports = { STATES, STATES_IN };