@omnizap-system/omnizap 2.6.0 → 2.6.2

package/server/routes/indexRouter.js

@@ -9,6 +9,7 @@ import { getStickerSiteRouterConfig, maybeHandleStickerSiteRequest, shouldHandle
 import { getStickerDataRouterConfig, maybeHandleStickerDataRequest, shouldHandleStickerDataPath } from './sticker/stickerDataRouter.js';
 import { getStickerApiRouterConfig, maybeHandleStickerApiRequest, shouldHandleStickerApiPath } from './sticker/stickerApiRouter.js';
 import { maybeHandleStaticPageRequest, shouldHandleStaticPagePath } from './static/staticPageRouter.js';
+import { getGrafanaProxyRouterConfig, maybeHandleGrafanaProxyRequest, shouldHandleGrafanaProxyPath } from './observability/grafanaProxyRouter.js';
 
 const startsWithPath = (pathname, prefix) => {
   if (!pathname || !prefix) return false;
@@ -112,12 +113,27 @@ const loadStickerApiConfigSafe = async () => {
   }
 };
 
+const loadGrafanaProxyConfigSafe = async () => {
+  try {
+    return getGrafanaProxyRouterConfig();
+  } catch {
+    return {
+      enabled: false,
+      basePath: '/api/grafana',
+      legacyBasePath: '/grafana',
+      timeoutMs: 15000,
+      target: null,
+    };
+  }
+};
+
 export const getIndexRouteConfigs = async () => {
   if (!indexRouteConfigsPromise) {
-    indexRouteConfigsPromise = Promise.all([loadUserConfigSafe(), loadSystemAdminConfigSafe(), loadEmailAutomationConfigSafe(), loadStickerSiteConfigSafe(), loadStickerDataConfigSafe(), loadStickerApiConfigSafe()]).then(([userConfig, systemAdminConfig, emailAutomationConfig, stickerSiteConfig, stickerDataConfig, stickerApiConfig]) => ({
+    indexRouteConfigsPromise = Promise.all([loadUserConfigSafe(), loadSystemAdminConfigSafe(), loadEmailAutomationConfigSafe(), loadStickerSiteConfigSafe(), loadStickerDataConfigSafe(), loadStickerApiConfigSafe(), loadGrafanaProxyConfigSafe()]).then(([userConfig, systemAdminConfig, emailAutomationConfig, stickerSiteConfig, stickerDataConfig, stickerApiConfig, grafanaProxyConfig]) => ({
       userConfig,
       systemAdminConfig,
       emailAutomationConfig,
+      grafanaProxyConfig,
       stickerConfig: {
         ...stickerSiteConfig,
         ...stickerDataConfig,
@@ -140,6 +156,7 @@ export const routeRequest = async (req, res, { pathname, url, metricsPath = '/me
   const userConfig = resolvedConfigs?.userConfig || null;
   const systemAdminConfig = resolvedConfigs?.systemAdminConfig || null;
   const emailAutomationConfig = resolvedConfigs?.emailAutomationConfig || null;
+  const grafanaProxyConfig = resolvedConfigs?.grafanaProxyConfig || null;
   const stickerConfig = resolvedConfigs?.stickerConfig || null;
 
   // 1) Metrics
@@ -163,7 +180,14 @@ export const routeRequest = async (req, res, { pathname, url, metricsPath = '/me
     return sendNotFound(req, res);
   }
 
-  // 4) User
+  // 4) Grafana proxy (/api/grafana e alias /grafana)
+  if (shouldHandleGrafanaProxyPath(pathname, grafanaProxyConfig)) {
+    const handled = await maybeHandleGrafanaProxyRequest(req, res, { pathname, url, config: grafanaProxyConfig });
+    if (handled) return true;
+    return sendNotFound(req, res);
+  }
+
+  // 5) User
   const systemAdminCandidate = shouldHandleSystemAdminStep(pathname, systemAdminConfig);
   if (shouldHandleUserStep(pathname, userConfig)) {
     const handled = await maybeHandleUserRequest(req, res, { pathname, url });
@@ -173,14 +197,14 @@ export const routeRequest = async (req, res, { pathname, url, metricsPath = '/me
     if (!systemAdminCandidate) return sendNotFound(req, res);
   }
 
-  // 5) System admin + legacy /stickers/admin
+  // 6) System admin + legacy /stickers/admin
   if (systemAdminCandidate) {
     const handled = await maybeHandleSystemAdminRequest(req, res, { pathname, url });
     if (handled) return true;
     return sendNotFound(req, res);
   }
 
-  // 6) Sticker catalog apenas nos prefixes permitidos
+  // 7) Sticker catalog apenas nos prefixes permitidos
   if (shouldHandleStickerSitePath(pathname, stickerConfig)) {
     const handled = await maybeHandleStickerSiteRequest(req, res, { pathname, url });
     if (handled) return true;
@@ -212,14 +236,14 @@ export const routeRequest = async (req, res, { pathname, url, metricsPath = '/me
     return sendNotFound(req, res);
   }
 
-  // 7) Paginas estaticas (templates em public/pages)
+  // 8) Paginas estaticas (templates em public/pages)
   if (shouldHandleStaticPagePath(pathname)) {
     const handled = await maybeHandleStaticPageRequest(req, res, { pathname });
     if (handled) return true;
     return sendNotFound(req, res);
   }
 
-  // 8) 404 global
+  // 9) 404 global
   return sendNotFound(req, res);
 };
 

package/server/routes/observability/grafanaProxyRouter.js

@@ -0,0 +1,254 @@
+import http from 'node:http';
+import https from 'node:https';
+import { URL } from 'node:url';
+
+import logger from '#logger';
+
+const HOP_BY_HOP_HEADERS = new Set(['connection', 'keep-alive', 'proxy-authenticate', 'proxy-authorization', 'te', 'trailer', 'transfer-encoding', 'upgrade']);
+
+const DEFAULT_GRAFANA_PROXY_BASE_PATH = '/api/grafana';
+const DEFAULT_GRAFANA_PROXY_LEGACY_BASE_PATH = '/grafana';
+const DEFAULT_GRAFANA_PROXY_TIMEOUT_MS = 15000;
+
+const normalizeBasePath = (value, fallback) => {
+  const raw = String(value || '').trim() || fallback;
+  const withLeadingSlash = raw.startsWith('/') ? raw : `/${raw}`;
+  const withoutTrailingSlash = withLeadingSlash.length > 1 && withLeadingSlash.endsWith('/') ? withLeadingSlash.slice(0, -1) : withLeadingSlash;
+  return withoutTrailingSlash || fallback;
+};
+
+const startsWithPath = (pathname, prefix) => {
+  if (!pathname || !prefix) return false;
+  if (pathname === prefix) return true;
+  return pathname.startsWith(`${prefix}/`);
+};
+
+const parseEnvBool = (value, fallback = true) => {
+  if (value === undefined || value === null || value === '') return fallback;
+  const normalized = String(value).trim().toLowerCase();
+  if (['1', 'true', 'yes', 'y', 'on'].includes(normalized)) return true;
+  if (['0', 'false', 'no', 'n', 'off'].includes(normalized)) return false;
+  return fallback;
+};
+
+const parseEnvNumber = (value, fallback) => {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed > 0 ? Math.round(parsed) : fallback;
+};
+
+const normalizeTargetUrl = (rawUrl) => {
+  const raw = String(rawUrl || '').trim();
+  if (!raw) return null;
+  try {
+    const parsed = new URL(raw);
+    if (!['http:', 'https:'].includes(parsed.protocol)) return null;
+    parsed.search = '';
+    parsed.hash = '';
+    parsed.pathname = String(parsed.pathname || '/').replace(/\/+$/, '') || '/';
+    return parsed;
+  } catch {
+    return null;
+  }
+};
+
+const normalizeHeaderValue = (value) => {
+  if (Array.isArray(value))
+    return value
+      .map((item) => String(item || '').trim())
+      .filter(Boolean)
+      .join(', ');
+  return String(value || '').trim();
+};
+
+const getDefaultTargetUrl = () => {
+  const port = parseEnvNumber(process.env.GRAFANA_PORT, 3003);
+  return `http://127.0.0.1:${port}`;
+};
+
+const joinUrlPath = (leftPath, rightPath) => {
+  const left = String(leftPath || '').replace(/\/+$/, '');
+  const right = String(rightPath || '').replace(/^\/+/, '');
+  if (!left) return `/${right}`.replace(/\/{2,}/g, '/');
+  if (!right) return left.startsWith('/') ? left : `/${left}`;
+  const joined = `${left}/${right}`.replace(/\/{2,}/g, '/');
+  return joined.startsWith('/') ? joined : `/${joined}`;
+};
+
+const buildUpstreamPath = ({ pathname, search = '', matchedBasePath, upstreamBasePath, canonicalBasePath }) => {
+  const suffix = pathname === matchedBasePath ? '' : pathname.slice(matchedBasePath.length);
+  const normalizedSuffix = suffix ? (suffix.startsWith('/') ? suffix : `/${suffix}`) : '';
+  const canonicalPath = `${canonicalBasePath}${normalizedSuffix}` || canonicalBasePath;
+  const path = joinUrlPath(upstreamBasePath === '/' ? '' : upstreamBasePath, canonicalPath);
+  return `${path}${search || ''}`;
+};
+
+const getMatchedBasePath = (pathname, config) => {
+  if (!config?.enabled) return null;
+  if (startsWithPath(pathname, config.basePath)) return config.basePath;
+  if (config.legacyBasePath && startsWithPath(pathname, config.legacyBasePath)) return config.legacyBasePath;
+  return null;
+};
+
+const copyResponseHeaders = (res, upstreamHeaders = {}) => {
+  for (const [name, value] of Object.entries(upstreamHeaders)) {
+    if (value === undefined) continue;
+    const lower = String(name || '').toLowerCase();
+    if (!lower || HOP_BY_HOP_HEADERS.has(lower)) continue;
+    res.setHeader(name, value);
+  }
+};
+
+const buildUpstreamHeaders = (req, { matchedBasePath, target }) => {
+  const headers = {};
+  for (const [name, value] of Object.entries(req.headers || {})) {
+    if (value === undefined) continue;
+    const lower = String(name || '').toLowerCase();
+    if (!lower || lower === 'host' || HOP_BY_HOP_HEADERS.has(lower)) continue;
+    headers[lower] = value;
+  }
+
+  const incomingForwardedFor = normalizeHeaderValue(req.headers?.['x-forwarded-for']);
+  const remoteAddress = String(req.socket?.remoteAddress || '').trim();
+  const forwardedFor = [incomingForwardedFor, remoteAddress].filter(Boolean).join(', ');
+  if (forwardedFor) headers['x-forwarded-for'] = forwardedFor;
+
+  const forwardedProto = normalizeHeaderValue(req.headers?.['x-forwarded-proto']) || (req.socket?.encrypted ? 'https' : 'http');
+  headers['x-forwarded-proto'] = forwardedProto;
+
+  const incomingHost = normalizeHeaderValue(req.headers?.host);
+  const forwardedHost = normalizeHeaderValue(req.headers?.['x-forwarded-host']) || incomingHost;
+  if (forwardedHost) headers['x-forwarded-host'] = forwardedHost;
+
+  headers['x-forwarded-prefix'] = matchedBasePath;
+  headers.host = incomingHost || target.host;
+  return headers;
+};
+
+const pipeToUpstream = ({ req, res, target, targetPathWithQuery, timeoutMs, headers }) =>
+  new Promise((resolve, reject) => {
+    let settled = false;
+    const finalize = (error = null) => {
+      if (settled) return;
+      settled = true;
+      if (error) reject(error);
+      else resolve();
+    };
+
+    const transport = target.protocol === 'https:' ? https : http;
+    const upstreamReq = transport.request(
+      {
+        protocol: target.protocol,
+        hostname: target.hostname,
+        port: target.port || (target.protocol === 'https:' ? 443 : 80),
+        method: req.method,
+        path: targetPathWithQuery,
+        headers,
+      },
+      (upstreamRes) => {
+        res.statusCode = Number(upstreamRes.statusCode) || 502;
+        if (upstreamRes.statusMessage) res.statusMessage = upstreamRes.statusMessage;
+        copyResponseHeaders(res, upstreamRes.headers);
+
+        if (String(req.method || '').toUpperCase() === 'HEAD') {
+          upstreamRes.resume();
+          upstreamRes.once('end', () => {
+            if (!res.writableEnded) res.end();
+            finalize();
+          });
+          upstreamRes.once('error', finalize);
+          return;
+        }
+
+        upstreamRes.once('error', finalize);
+        res.once('error', finalize);
+        upstreamRes.pipe(res);
+        upstreamRes.once('end', finalize);
+      },
+    );
+
+    upstreamReq.setTimeout(timeoutMs, () => {
+      upstreamReq.destroy(new Error(`Grafana proxy timeout (${timeoutMs}ms)`));
+    });
+
+    upstreamReq.once('error', finalize);
+    req.once('error', (error) => upstreamReq.destroy(error));
+    req.once('aborted', () => upstreamReq.destroy(new Error('Client aborted request')));
+
+    if (['GET', 'HEAD'].includes(String(req.method || '').toUpperCase())) {
+      upstreamReq.end();
+      return;
+    }
+
+    req.pipe(upstreamReq);
+  });
+
+export const getGrafanaProxyRouterConfig = () => {
+  const enabled = parseEnvBool(process.env.GRAFANA_PROXY_ENABLED, true);
+  const basePath = normalizeBasePath(process.env.GRAFANA_PROXY_BASE_PATH, DEFAULT_GRAFANA_PROXY_BASE_PATH);
+  const legacyBasePath = normalizeBasePath(process.env.GRAFANA_PROXY_LEGACY_BASE_PATH, DEFAULT_GRAFANA_PROXY_LEGACY_BASE_PATH);
+  const timeoutMs = parseEnvNumber(process.env.GRAFANA_PROXY_TIMEOUT_MS, DEFAULT_GRAFANA_PROXY_TIMEOUT_MS);
+  const target = normalizeTargetUrl(process.env.GRAFANA_PROXY_TARGET_URL || getDefaultTargetUrl());
+
+  return {
+    enabled: Boolean(enabled && target),
+    basePath,
+    legacyBasePath,
+    timeoutMs,
+    target,
+  };
+};
+
+export const shouldHandleGrafanaProxyPath = (pathname, config = null) => Boolean(getMatchedBasePath(pathname, config || getGrafanaProxyRouterConfig()));
+
+const sendProxyError = (req, res, message) => {
+  if (res.writableEnded) return;
+  res.statusCode = 502;
+  res.setHeader('Content-Type', 'application/json; charset=utf-8');
+  if (req.method === 'HEAD') {
+    res.end();
+    return;
+  }
+  res.end(JSON.stringify({ error: message }));
+};
+
+export const maybeHandleGrafanaProxyRequest = async (req, res, { pathname, url, config = null } = {}) => {
+  const resolvedConfig = config || getGrafanaProxyRouterConfig();
+  const matchedBasePath = getMatchedBasePath(pathname, resolvedConfig);
+  if (!matchedBasePath) return false;
+
+  if (!resolvedConfig?.target) {
+    sendProxyError(req, res, 'Grafana proxy indisponivel.');
+    return true;
+  }
+
+  const targetPathWithQuery = buildUpstreamPath({
+    pathname,
+    search: url?.search || '',
+    matchedBasePath,
+    upstreamBasePath: resolvedConfig.target.pathname || '/',
+    canonicalBasePath: resolvedConfig.basePath,
+  });
+
+  try {
+    const headers = buildUpstreamHeaders(req, { matchedBasePath, target: resolvedConfig.target });
+    await pipeToUpstream({
+      req,
+      res,
+      target: resolvedConfig.target,
+      targetPathWithQuery,
+      timeoutMs: resolvedConfig.timeoutMs,
+      headers,
+    });
+  } catch (error) {
+    logger.warn('Falha ao encaminhar request para o Grafana.', {
+      action: 'grafana_proxy_failed',
+      path: pathname,
+      method: req.method,
+      target_path: targetPathWithQuery,
+      error: error?.message,
+    });
+    sendProxyError(req, res, 'Grafana indisponivel no momento.');
+  }
+
+  return true;
+};

package/server/routes/static/staticPageRouter.js

@@ -2,6 +2,7 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 
 import logger from '#logger';
+import { buildWhatsappUrl, formatWhatsappDisplay, resolvePublicWhatsappNumber } from '../../utils/publicContact.js';
 
 const normalizeBasePath = (value, fallback) => {
   const raw = String(value || '').trim() || fallback;
@@ -21,6 +22,11 @@ const PUBLIC_PAGES_DIR = path.join(process.cwd(), 'public', 'pages');
 const SEO_ROUTE_PREFIX = '/seo/';
 const SEO_SLUG_REGEX = /^[a-z0-9-]+$/;
 const INDEX_FILE_SUFFIX = '/index.html';
+const LGPD_DEFAULT_TEXT = 'Olá, gostaria de exercer meus direitos de titular de dados (LGPD).';
+const SUPPORT_WHATSAPP_NUMBER = resolvePublicWhatsappNumber();
+const SUPPORT_WHATSAPP_URL = buildWhatsappUrl(SUPPORT_WHATSAPP_NUMBER);
+const SUPPORT_WHATSAPP_URL_LGPD = buildWhatsappUrl(SUPPORT_WHATSAPP_NUMBER, process.env.WHATSAPP_SUPPORT_LGPD_TEXT || LGPD_DEFAULT_TEXT);
+const SUPPORT_WHATSAPP_DISPLAY = formatWhatsappDisplay(SUPPORT_WHATSAPP_NUMBER);
 
 const STATIC_PAGE_ROUTE_TO_FILE = new Map(
   [
@@ -89,6 +95,26 @@ const sendJson = (req, res, statusCode, payload) => {
   res.end(body);
 };
 
+const injectStaticTemplateTokens = (html) => {
+  let rendered = String(html || '');
+  const replacements = {
+    __WHATSAPP_SUPPORT_NUMBER__: SUPPORT_WHATSAPP_NUMBER,
+    __WHATSAPP_SUPPORT_URL__: SUPPORT_WHATSAPP_URL,
+    __WHATSAPP_SUPPORT_URL_LGPD__: SUPPORT_WHATSAPP_URL_LGPD,
+    __WHATSAPP_SUPPORT_DISPLAY__: SUPPORT_WHATSAPP_DISPLAY,
+    __WHATSAPP_PUBLIC_CONTACT_NUMBER__: SUPPORT_WHATSAPP_NUMBER,
+    __WHATSAPP_PUBLIC_CONTACT_URL__: SUPPORT_WHATSAPP_URL,
+    __WHATSAPP_PUBLIC_CONTACT_URL_LGPD__: SUPPORT_WHATSAPP_URL_LGPD,
+    __WHATSAPP_PUBLIC_CONTACT_DISPLAY__: SUPPORT_WHATSAPP_DISPLAY,
+  };
+
+  for (const [token, value] of Object.entries(replacements)) {
+    rendered = rendered.replaceAll(token, String(value || ''));
+  }
+
+  return rendered;
+};
+
 export const shouldHandleStaticPagePath = (pathname) => Boolean(resolveStaticTemplateName(pathname));
 
 export const maybeHandleStaticPageRequest = async (req, res, { pathname } = {}) => {
@@ -116,7 +142,7 @@ export const maybeHandleStaticPageRequest = async (req, res, { pathname } = {})
   const templatePath = path.join(PUBLIC_PAGES_DIR, templateName);
   try {
     const html = await fs.readFile(templatePath, 'utf8');
-    sendHtml(req, res, html);
+    sendHtml(req, res, injectStaticTemplateTokens(html));
   } catch (error) {
     if (error?.code === 'ENOENT') {
       sendJson(req, res, 404, { error: 'Template da pagina nao encontrado.' });

package/server/utils/publicContact.js

@@ -0,0 +1,31 @@
+import { isLikelyWhatsAppPhone, normalizePhoneDigits, resolveSupportPhoneFromEnv } from '../../utils/whatsapp/contactEnv.js';
+
+const FALLBACK_WHATSAPP_SUPPORT_NUMBER = '5511999999999';
+
+export { normalizePhoneDigits };
+
+export const resolvePublicWhatsappNumber = ({ fallback = FALLBACK_WHATSAPP_SUPPORT_NUMBER } = {}) => resolveSupportPhoneFromEnv({ fallback });
+
+export const formatWhatsappDisplay = (value) => {
+  const digits = normalizePhoneDigits(value || '');
+  if (!isLikelyWhatsAppPhone(digits)) return '';
+
+  if (digits.startsWith('55') && digits.length === 12) {
+    return `+55 ${digits.slice(2, 4)} ${digits.slice(4, 8)}-${digits.slice(8)}`;
+  }
+
+  if (digits.startsWith('55') && digits.length === 13) {
+    return `+55 ${digits.slice(2, 4)} ${digits.slice(4, 9)}-${digits.slice(9)}`;
+  }
+
+  return `+${digits}`;
+};
+
+export const buildWhatsappUrl = (value, text = '') => {
+  const digits = normalizePhoneDigits(value || '');
+  if (!isLikelyWhatsAppPhone(digits)) return '';
+
+  const normalizedText = String(text || '').trim();
+  if (!normalizedText) return `https://wa.me/${digits}`;
+  return `https://wa.me/${digits}?text=${encodeURIComponent(normalizedText)}`;
+};

package/utils/time/timeModule.js

@@ -0,0 +1,135 @@
+import { DateTime, Duration } from 'luxon';
+
+function resolveTimeZone(timeZone = 'UTC') {
+  if (typeof timeZone !== 'string' || timeZone.trim().length === 0) {
+    return 'UTC';
+  }
+
+  return timeZone;
+}
+
+function normalizeDateTime(dateInput = new Date(), { locale = 'pt-BR', timeZone = 'UTC' } = {}) {
+  const zone = resolveTimeZone(timeZone);
+  let dateTime = null;
+
+  if (DateTime.isDateTime(dateInput)) {
+    dateTime = dateInput.setZone(zone);
+  } else if (dateInput instanceof Date) {
+    dateTime = DateTime.fromJSDate(dateInput, { zone });
+  } else if (typeof dateInput === 'number') {
+    dateTime = DateTime.fromMillis(dateInput, { zone });
+  } else if (typeof dateInput === 'string') {
+    dateTime = DateTime.fromISO(dateInput, { zone });
+
+    if (!dateTime.isValid) {
+      const parsedDate = new Date(dateInput);
+      if (!Number.isNaN(parsedDate.getTime())) {
+        dateTime = DateTime.fromJSDate(parsedDate, { zone });
+      }
+    }
+  } else {
+    dateTime = DateTime.fromJSDate(new Date(dateInput), { zone });
+  }
+
+  if (!dateTime || !dateTime.isValid) {
+    dateTime = DateTime.now().setZone(zone);
+  }
+
+  return dateTime.setLocale(locale);
+}
+
+export function now() {
+  return new Date();
+}
+
+export function nowIso() {
+  return DateTime.utc().toISO();
+}
+
+export function toUnixMs(dateInput = new Date()) {
+  return normalizeDateTime(dateInput, { locale: 'en-US', timeZone: 'UTC' }).toMillis();
+}
+
+export function toUnixSeconds(dateInput = new Date()) {
+  return Math.floor(toUnixMs(dateInput) / 1000);
+}
+
+export function elapsedMs(startDateInput, endDateInput = new Date()) {
+  return toUnixMs(endDateInput) - toUnixMs(startDateInput);
+}
+
+export function formatInTimeZone(dateInput = new Date(), { locale = 'pt-BR', timeZone = 'UTC', options = {} } = {}) {
+  return normalizeDateTime(dateInput, { locale, timeZone }).toLocaleString(options);
+}
+
+export function formatTimeAmPm(dateInput = new Date(), { locale = 'en-US', timeZone = 'UTC', includeSeconds = false } = {}) {
+  return normalizeDateTime(dateInput, { locale, timeZone }).toFormat(includeSeconds ? 'hh:mm:ss a' : 'hh:mm a');
+}
+
+export function formatDateTimeExtenso(dateInput = new Date(), { locale = 'pt-BR', timeZone = 'UTC', includeWeekday = true } = {}) {
+  return normalizeDateTime(dateInput, { locale, timeZone }).toLocaleString({
+    ...(includeWeekday ? { weekday: 'long' } : {}),
+    day: 'numeric',
+    month: 'long',
+    year: 'numeric',
+    hour: '2-digit',
+    minute: '2-digit',
+  });
+}
+
+export function formatTimeExtenso(dateInput = new Date(), { locale = 'pt-BR', timeZone = 'UTC', includeSeconds = false } = {}) {
+  const dateTime = normalizeDateTime(dateInput, { locale, timeZone });
+  const duration = Duration.fromObject(
+    {
+      hours: dateTime.hour,
+      minutes: dateTime.minute,
+      ...(includeSeconds ? { seconds: dateTime.second } : {}),
+    },
+    { locale },
+  );
+
+  return duration.toHuman({
+    unitDisplay: 'long',
+    listStyle: 'long',
+  });
+}
+
+export function buildTimeFormats(dateInput = new Date(), { locale = 'pt-BR', timeZone = 'UTC' } = {}) {
+  const iso = normalizeDateTime(dateInput, { locale: 'en-US', timeZone: 'UTC' }).toUTC().toISO();
+
+  return {
+    iso,
+    unixMs: toUnixMs(dateInput),
+    unixSeconds: toUnixSeconds(dateInput),
+    amPm: formatTimeAmPm(dateInput, {
+      locale: 'en-US',
+      timeZone,
+      includeSeconds: false,
+    }),
+    extenso: formatDateTimeExtenso(dateInput, {
+      locale,
+      timeZone,
+      includeWeekday: true,
+    }),
+    horaExtenso: formatTimeExtenso(dateInput, {
+      locale,
+      timeZone,
+      includeSeconds: false,
+    }),
+  };
+}
+
+const timeModule = {
+  now,
+  nowIso,
+  toUnixMs,
+  toUnixSeconds,
+  elapsedMs,
+  formatInTimeZone,
+  formatTimeAmPm,
+  formatDateTimeExtenso,
+  formatTimeExtenso,
+  buildTimeFormats,
+};
+
+export default timeModule;

package/utils/time/timeModule.test.js

@@ -0,0 +1,65 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { buildTimeFormats, elapsedMs, formatDateTimeExtenso, formatTimeAmPm, formatTimeExtenso, now, nowIso, toUnixMs, toUnixSeconds } from './timeModule.js';
+
+const FIXED_ISO = '2026-03-16T15:45:30.000Z';
+
+test('now e nowIso retornam valores válidos de data/hora', () => {
+  const nowValue = now();
+  const nowIsoValue = nowIso();
+
+  assert.ok(nowValue instanceof Date);
+  assert.ok(Number.isFinite(nowValue.getTime()));
+  assert.ok(Number.isFinite(Date.parse(nowIsoValue)));
+});
+
+test('conversão unix e elapsedMs funcionam conforme esperado', () => {
+  assert.equal(toUnixMs(FIXED_ISO), 1773675930000);
+  assert.equal(toUnixSeconds(FIXED_ISO), 1773675930);
+  assert.equal(elapsedMs('2026-03-16T15:45:00.000Z', FIXED_ISO), 30000);
+});
+
+test('formatTimeAmPm gera horário em AM/PM', () => {
+  const result = formatTimeAmPm(FIXED_ISO, {
+    locale: 'en-US',
+    timeZone: 'UTC',
+  });
+
+  assert.equal(result, '03:45 PM');
+});
+
+test('formatDateTimeExtenso gera data/hora por extenso em pt-BR', () => {
+  const result = formatDateTimeExtenso(FIXED_ISO, {
+    locale: 'pt-BR',
+    timeZone: 'America/Sao_Paulo',
+  });
+
+  assert.match(result, /16 de março de 2026/i);
+  assert.match(result, /12:45/);
+});
+
+test('formatTimeExtenso gera hora por extenso em pt-BR', () => {
+  const result = formatTimeExtenso(FIXED_ISO, {
+    locale: 'pt-BR',
+    timeZone: 'America/Sao_Paulo',
+  });
+
+  assert.equal(result, '12 horas e 45 minutos');
+});
+
+test('buildTimeFormats retorna pacote completo de formatos', () => {
+  const result = buildTimeFormats(FIXED_ISO, {
+    locale: 'pt-BR',
+    timeZone: 'America/Sao_Paulo',
+  });
+
+  assert.deepEqual(result, {
+    iso: '2026-03-16T15:45:30.000Z',
+    unixMs: 1773675930000,
+    unixSeconds: 1773675930,
+    amPm: '12:45 PM',
+    extenso: 'segunda-feira, 16 de março de 2026 às 12:45',
+    horaExtenso: '12 horas e 45 minutos',
+  });
+});

package/utils/whatsapp/contactEnv.js

@@ -0,0 +1,39 @@
+const MAX_PHONE_DIGITS = 20;
+const DEFAULT_FALLBACK_NUMBER = '5511999999999';
+
+const BOT_PHONE_ENV_KEYS = ['WHATSAPP_BOT_NUMBER', 'WHATSAPP_SUPPORT_NUMBER', 'BOT_NUMBER', 'BOT_PHONE_NUMBER', 'PHONE_NUMBER'];
+const SUPPORT_PHONE_ENV_KEYS = ['WHATSAPP_SUPPORT_NUMBER', 'WHATSAPP_ADMIN_NUMBER', 'WHATSAPP_PUBLIC_CONTACT_NUMBER', 'EMAIL_BRAND_SUPPORT_PHONE', 'OWNER_NUMBER'];
+const ADMIN_PHONE_ENV_KEYS = ['WHATSAPP_ADMIN_NUMBER', 'WHATSAPP_ADMIN_JID', 'USER_ADMIN', 'OWNER_NUMBER', 'WHATSAPP_SUPPORT_NUMBER', 'WHATSAPP_PUBLIC_CONTACT_NUMBER'];
+const ADMIN_IDENTITY_ENV_KEYS = ['WHATSAPP_ADMIN_JID', 'USER_ADMIN', 'WHATSAPP_ADMIN_NUMBER'];
+
+export const normalizePhoneDigits = (value, maxLength = MAX_PHONE_DIGITS) =>
+  String(value || '')
+    .replace(/\D+/g, '')
+    .slice(0, Math.max(1, Number(maxLength) || MAX_PHONE_DIGITS));
+
+export const isLikelyWhatsAppPhone = (value) => /^\d{10,15}$/.test(normalizePhoneDigits(value, 20));
+
+const resolvePhoneFromEnvKeys = (keys, { fallback = '' } = {}) => {
+  for (const envKey of keys) {
+    const digits = normalizePhoneDigits(process.env[envKey] || '');
+    if (isLikelyWhatsAppPhone(digits)) return digits;
+  }
+
+  const fallbackDigits = normalizePhoneDigits(fallback || '');
+  if (isLikelyWhatsAppPhone(fallbackDigits)) return fallbackDigits;
+  return '';
+};
+
+export const resolveBotPhoneFromEnv = ({ fallback = DEFAULT_FALLBACK_NUMBER } = {}) => resolvePhoneFromEnvKeys(BOT_PHONE_ENV_KEYS, { fallback });
+
+export const resolveSupportPhoneFromEnv = ({ fallback = DEFAULT_FALLBACK_NUMBER } = {}) => resolvePhoneFromEnvKeys(SUPPORT_PHONE_ENV_KEYS, { fallback });
+
+export const resolveAdminPhoneFromEnv = ({ fallback = DEFAULT_FALLBACK_NUMBER } = {}) => resolvePhoneFromEnvKeys(ADMIN_PHONE_ENV_KEYS, { fallback });
+
+export const resolveAdminIdentityRawFromEnv = ({ fallback = '' } = {}) => {
+  for (const envKey of ADMIN_IDENTITY_ENV_KEYS) {
+    const value = String(process.env[envKey] || '').trim();
+    if (value) return value;
+  }
+  return String(fallback || '').trim();
+};