webspresso 0.0.100 → 0.0.102

package/core/forms/flash.js

@@ -0,0 +1,234 @@
+/**
+ * Webspresso - Flash Messages & Old Input Manager (AdonisJS & Django-inspired)
+ * Provides session-backed or cookie-backed one-time flash storage across redirects
+ * @module core/forms/flash
+ */
+
+const FLASH_SESSION_KEY = '__ws_flash';
+const FLASH_COOKIE_NAME = '__ws_flash';
+
+/**
+ * Format and normalize errors into a standard `{ fieldName: string[] }` shape
+ * Supports ZodError, plain object, array, or string error.
+ * @param {any} errors
+ * @returns {Record<string, string[]>}
+ */
+function normalizeErrors(errors) {
+  if (!errors) return {};
+
+  // 1. ZodError with format() or flatten() or issues
+  if (errors.issues && Array.isArray(errors.issues)) {
+    const result = {};
+    for (const issue of errors.issues) {
+      const field = issue.path && issue.path.length > 0 ? issue.path.join('.') : '_form';
+      if (!result[field]) result[field] = [];
+      result[field].push(issue.message || 'Invalid value');
+    }
+    return result;
+  }
+
+  if (typeof errors.flatten === 'function') {
+    const flat = errors.flatten();
+    const result = { ...(flat.fieldErrors || {}) };
+    if (flat.formErrors && flat.formErrors.length > 0) {
+      result._form = flat.formErrors;
+    }
+    return result;
+  }
+
+  // 2. Simple string error
+  if (typeof errors === 'string') {
+    return { _form: [errors] };
+  }
+
+  // 3. Array of strings or objects
+  if (Array.isArray(errors)) {
+    return {
+      _form: errors.map((e) => (typeof e === 'string' ? e : e.message || String(e))),
+    };
+  }
+
+  // 4. Plain object `{ field: string | string[] }`
+  if (typeof errors === 'object') {
+    const result = {};
+    for (const [key, val] of Object.entries(errors)) {
+      if (Array.isArray(val)) {
+        result[key] = val.map((v) => (typeof v === 'string' ? v : v.message || String(v)));
+      } else if (typeof val === 'string') {
+        result[key] = [val];
+      } else if (val && typeof val === 'object' && val.message) {
+        result[key] = [String(val.message)];
+      } else if (val !== null && val !== undefined) {
+        result[key] = [String(val)];
+      }
+    }
+    return result;
+  }
+
+  return { _form: [String(errors)] };
+}
+
+/**
+ * Encode flash data for cookie transport (base64url JSON)
+ * @param {Object} data
+ * @returns {string}
+ */
+function encodeFlashCookie(data) {
+  try {
+    return Buffer.from(JSON.stringify(data), 'utf8').toString('base64url');
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Decode flash data from cookie
+ * @param {string} raw
+ * @returns {Object|null}
+ */
+function decodeFlashCookie(raw) {
+  if (!raw || typeof raw !== 'string') return null;
+  try {
+    const json = Buffer.from(raw, 'base64url').toString('utf8');
+    return JSON.parse(json);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Flash and Old Input Express Middleware
+ * @param {Object} [options={}]
+ * @returns {import('express').RequestHandler}
+ */
+function createFlashMiddleware(options = {}) {
+  const cookieName = options.cookieName || FLASH_COOKIE_NAME;
+
+  return function flashMiddleware(req, res, next) {
+    // 1. Load incoming flash messages from session or cookie
+    let incomingFlash = {};
+
+    if (req.session && req.session[FLASH_SESSION_KEY]) {
+      incomingFlash = req.session[FLASH_SESSION_KEY] || {};
+      // Delete from session for next request (consume)
+      delete req.session[FLASH_SESSION_KEY];
+    } else if (req.cookies && req.cookies[cookieName]) {
+      incomingFlash = decodeFlashCookie(req.cookies[cookieName]) || {};
+      // Clear cookie immediately
+      res.clearCookie(cookieName, { path: '/' });
+    }
+
+    // Outgoing flash state to be persisted for the NEXT request
+    const outgoingFlash = {};
+
+    /**
+     * Set or get a flash message
+     * @param {string} [key]
+     * @param {any} [value]
+     * @returns {any}
+     */
+    req.flash = function (key, value) {
+      if (arguments.length === 0) {
+        return incomingFlash;
+      }
+      if (arguments.length === 1) {
+        return incomingFlash[key];
+      }
+      outgoingFlash[key] = value;
+      saveOutgoingFlash();
+      return value;
+    };
+
+    /**
+     * Get old input value from previous request
+     * @param {string} [name]
+     * @param {any} [defaultValue=null]
+     * @returns {any}
+     */
+    req.old = function (name, defaultValue = null) {
+      const oldInputs = incomingFlash.old || {};
+      if (!name) return oldInputs;
+      return oldInputs[name] !== undefined ? oldInputs[name] : defaultValue;
+    };
+
+    /**
+     * Flash current request body / input for the next request
+     * @param {Object} [customInput]
+     * @returns {res}
+     */
+    res.withInput = function (customInput) {
+      const input = customInput || req.body || {};
+      // Exclude sensitive fields by default
+      const sanitized = { ...input };
+      delete sanitized.password;
+      delete sanitized.password_confirmation;
+      delete sanitized.confirmPassword;
+      delete sanitized._csrf;
+
+      outgoingFlash.old = sanitized;
+      saveOutgoingFlash();
+      return res;
+    };
+
+    /**
+     * Flash validation errors for the next request
+     * @param {any} errors - ZodError, object, array, or string
+     * @returns {res}
+     */
+    res.withErrors = function (errors) {
+      outgoingFlash.errors = normalizeErrors(errors);
+      saveOutgoingFlash();
+      return res;
+    };
+
+    /**
+     * Flash a key-value message for the next request
+     * @param {string} key - e.g. 'success', 'warning', 'info'
+     * @param {any} message
+     * @returns {res}
+     */
+    res.withFlash = function (key, message) {
+      outgoingFlash[key] = message;
+      saveOutgoingFlash();
+      return res;
+    };
+
+    function saveOutgoingFlash() {
+      if (req.session) {
+        req.session[FLASH_SESSION_KEY] = outgoingFlash;
+      } else {
+        // Remove any previously set cookie with the same name from response headers
+        const existing = res.getHeader('Set-Cookie');
+        if (existing) {
+          const arr = Array.isArray(existing) ? existing : [existing];
+          const filtered = arr.filter((c) => !c.startsWith(`${cookieName}=`));
+          if (filtered.length > 0) {
+            res.setHeader('Set-Cookie', filtered);
+          } else {
+            res.removeHeader('Set-Cookie');
+          }
+        }
+        const encoded = encodeFlashCookie(outgoingFlash);
+        res.cookie(cookieName, encoded, {
+          path: '/',
+          httpOnly: true,
+          sameSite: 'lax',
+          maxAge: 300000, // 5 minutes
+        });
+      }
+    }
+
+    // Attach to request context for Nunjucks helpers
+    req.__flash = incomingFlash;
+    req.__outgoingFlash = outgoingFlash;
+
+    next();
+  };
+}
+
+module.exports = {
+  createFlashMiddleware,
+  normalizeErrors,
+  FLASH_SESSION_KEY,
+  FLASH_COOKIE_NAME,
+};

package/core/forms/form-builder.js

@@ -0,0 +1,214 @@
+/**
+ * Webspresso - Form Builder & HTML Generator (Django ModelForm-inspired)
+ * Generates accessible HTML form inputs, field wrappers, and auto-forms from ORM models
+ * @module core/forms/form-builder
+ */
+
+function escapeHtml(str) {
+  if (str === null || str === undefined) return '';
+  return String(str)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#039;');
+}
+
+/**
+ * Render a single form field with label, input, and validation error message
+ * @param {string} name - Field name
+ * @param {Object} [options={}] - Field configuration options
+ * @param {Object} [ctx={}] - Request / helpers context
+ * @returns {string} HTML string
+ */
+function renderField(name, options = {}, ctx = {}) {
+  const {
+    label = humanize(name),
+    type = 'text',
+    placeholder = '',
+    required = false,
+    disabled = false,
+    readonly = false,
+    className = 'form-control',
+    wrapperClass = 'form-group mb-3',
+    errorClass = 'is-invalid',
+    showError = true,
+    rows = 4,
+    selectOptions = [],
+    helpText = '',
+    attributes = {},
+  } = options;
+
+  // Resolve old value or default
+  const req = ctx.req;
+  const oldVal = req && typeof req.old === 'function' ? req.old(name) : undefined;
+  const value = oldVal !== undefined ? oldVal : (options.value !== undefined ? options.value : (options.default ?? ''));
+
+  // Check error state
+  const errors = req?.__flash?.errors || {};
+  const fieldErrors = errors[name] || [];
+  const hasError = fieldErrors.length > 0;
+  const inputClass = `${className}${hasError ? ` ${errorClass}` : ''}`.trim();
+
+  const extraAttrs = Object.entries(attributes)
+    .map(([k, v]) => `${escapeHtml(k)}="${escapeHtml(v)}"`)
+    .join(' ');
+
+  let inputHtml = '';
+
+  if (type === 'textarea') {
+    inputHtml = `<textarea id="field_${escapeHtml(name)}" name="${escapeHtml(name)}" class="${escapeHtml(inputClass)}" placeholder="${escapeHtml(placeholder)}"${required ? ' required' : ''}${disabled ? ' disabled' : ''}${readonly ? ' readonly' : ''} rows="${rows}"${extraAttrs ? ' ' + extraAttrs : ''}>${escapeHtml(value)}</textarea>`;
+  } else if (type === 'select') {
+    const optsHtml = selectOptions
+      .map((opt) => {
+        const optVal = typeof opt === 'object' && opt !== null ? opt.value : opt;
+        const optLabel = typeof opt === 'object' && opt !== null ? opt.label : opt;
+        const isSelected = String(optVal) === String(value);
+        return `<option value="${escapeHtml(optVal)}"${isSelected ? ' selected' : ''}>${escapeHtml(optLabel)}</option>`;
+      })
+      .join('\n      ');
+    inputHtml = `<select id="field_${escapeHtml(name)}" name="${escapeHtml(name)}" class="${escapeHtml(inputClass)}"${required ? ' required' : ''}${disabled ? ' disabled' : ''}${extraAttrs ? ' ' + extraAttrs : ''}>\n      ${optsHtml}\n    </select>`;
+  } else if (type === 'checkbox') {
+    const isChecked = Boolean(value) && value !== '0' && value !== 'false';
+    inputHtml = `<div class="form-check">
+      <input type="checkbox" id="field_${escapeHtml(name)}" name="${escapeHtml(name)}" value="true" class="form-check-input${hasError ? ` ${errorClass}` : ''}"${isChecked ? ' checked' : ''}${disabled ? ' disabled' : ''}${extraAttrs ? ' ' + extraAttrs : ''}>
+      <label class="form-check-label" for="field_${escapeHtml(name)}">${escapeHtml(label)}</label>
+    </div>`;
+  } else {
+    // Standard input (text, email, password, number, date, file, etc.)
+    inputHtml = `<input type="${escapeHtml(type)}" id="field_${escapeHtml(name)}" name="${escapeHtml(name)}" value="${escapeHtml(value)}" class="${escapeHtml(inputClass)}" placeholder="${escapeHtml(placeholder)}"${required ? ' required' : ''}${disabled ? ' disabled' : ''}${readonly ? ' readonly' : ''}${extraAttrs ? ' ' + extraAttrs : ''}>`;
+  }
+
+  const labelHtml =
+    type !== 'checkbox' && label
+      ? `<label for="field_${escapeHtml(name)}" class="form-label">${escapeHtml(label)}${required ? ' <span class="text-danger">*</span>' : ''}</label>`
+      : '';
+
+  const helpHtml = helpText ? `<div class="form-text text-muted">${escapeHtml(helpText)}</div>` : '';
+
+  const errorHtml =
+    showError && hasError
+      ? `<div class="invalid-feedback d-block text-danger mt-1">${escapeHtml(fieldErrors[0])}</div>`
+      : '';
+
+  return `<div class="${escapeHtml(wrapperClass)}">
+    ${labelHtml ? labelHtml + '\n    ' : ''}${inputHtml}
+    ${helpHtml ? helpHtml + '\n    ' : ''}${errorHtml}
+  </div>`.trim();
+}
+
+/**
+ * Generate a complete HTML form from an ORM model definition (Django ModelForm-inspired)
+ * @param {Object} modelOrRepo - ORM model or repository
+ * @param {Object} [options={}] - Form options (action, method, exclude, include, submitLabel)
+ * @param {Object} [ctx={}] - Request / helpers context
+ * @returns {string} HTML string
+ */
+function renderFormFor(modelOrRepo, options = {}, ctx = {}) {
+  const model = modelOrRepo.model || modelOrRepo;
+  if (!model || !model.columns) {
+    throw new Error('renderFormFor requires an ORM model or repository with column definitions');
+  }
+
+  const {
+    action = '',
+    method = 'POST',
+    exclude = ['id', 'created_at', 'updated_at', 'deleted_at'],
+    include = null,
+    submitLabel = 'Save',
+    csrf = true,
+    formClass = 'webspresso-form',
+  } = options;
+
+  const excludeSet = new Set(exclude);
+  const includeSet = include ? new Set(include) : null;
+
+  const fieldsHtml = [];
+
+  for (const [colName, meta] of model.columns.entries()) {
+    if (excludeSet.has(colName)) continue;
+    if (includeSet && !includeSet.has(colName)) continue;
+
+    const fieldConfig = inferFieldConfig(colName, meta);
+    fieldsHtml.push(renderField(colName, fieldConfig, ctx));
+  }
+
+  let csrfHtml = '';
+  if (csrf && ctx.req) {
+    const token = ctx.req.csrfToken ? ctx.req.csrfToken() : ctx.req.session?._csrf || '';
+    if (token) {
+      csrfHtml = `  <input type="hidden" name="_csrf" value="${escapeHtml(token)}">\n`;
+    }
+  }
+
+  const submitHtml = submitLabel
+    ? `  <div class="form-actions mt-4">\n    <button type="submit" class="btn btn-primary">${escapeHtml(submitLabel)}</button>\n  </div>`
+    : '';
+
+  return `<form action="${escapeHtml(action)}" method="${escapeHtml(method)}" class="${escapeHtml(formClass)}">
+${csrfHtml}  ${fieldsHtml.join('\n  ')}
+${submitHtml}
+</form>`;
+}
+
+function inferFieldConfig(name, meta) {
+  const config = {
+    label: humanize(name),
+    required: !meta.nullable && meta.default === undefined && !meta.auto,
+  };
+
+  switch (meta.type) {
+    case 'text':
+      config.type = 'textarea';
+      break;
+    case 'boolean':
+      config.type = 'checkbox';
+      break;
+    case 'integer':
+    case 'bigint':
+    case 'float':
+    case 'decimal':
+      config.type = 'number';
+      break;
+    case 'date':
+      config.type = 'date';
+      break;
+    case 'datetime':
+    case 'timestamp':
+      config.type = 'datetime-local';
+      break;
+    case 'file':
+    case 'files':
+      config.type = 'file';
+      break;
+    case 'enum':
+      config.type = 'select';
+      config.selectOptions = (meta.enumValues || []).map((v) => ({ label: humanize(v), value: v }));
+      break;
+    default:
+      if (name.includes('email')) {
+        config.type = 'email';
+      } else if (name.includes('password')) {
+        config.type = 'password';
+      } else {
+        config.type = 'text';
+      }
+  }
+
+  return config;
+}
+
+function humanize(str) {
+  if (!str) return '';
+  return str
+    .replace(/[_-]+/g, ' ')
+    .replace(/([a-z\d])([A-Z])/g, '$1 $2')
+    .replace(/^./, (m) => m.toUpperCase());
+}
+
+module.exports = {
+  renderField,
+  renderFormFor,
+  humanize,
+  escapeHtml,
+};

package/core/forms/index.js

@@ -0,0 +1,16 @@
+/**
+ * Webspresso Forms & Flash Subsystem (AdonisJS & Django-inspired)
+ * @module core/forms
+ */
+
+const { createFlashMiddleware, normalizeErrors } = require('./flash');
+const { renderField, renderFormFor, humanize, escapeHtml } = require('./form-builder');
+
+module.exports = {
+  createFlashMiddleware,
+  normalizeErrors,
+  renderField,
+  renderFormFor,
+  humanize,
+  escapeHtml,
+};

package/core/mail/index.js

@@ -0,0 +1,23 @@
+/**
+ * Core Mail Module
+ * @module core/mail
+ */
+
+const { Mailable } = require('./mailable');
+const { Mailer, createMailer } = require('./mailer');
+const {
+  MemoryTransport,
+  ConsoleTransport,
+  FileTransport,
+  resolveTransport,
+} = require('./transports');
+
+module.exports = {
+  Mailable,
+  Mailer,
+  createMailer,
+  MemoryTransport,
+  ConsoleTransport,
+  FileTransport,
+  resolveTransport,
+};