@zintrust/core 0.4.16 → 0.4.17

package/src/tools/mail/index.ts

@@ -0,0 +1,222 @@
+import { mailConfig } from '@config/mail';
+import { ErrorFactory } from '@exceptions/ZintrustError';
+
+import type { MailAddress } from '@mail/drivers/SendGrid';
+import { SesDriver } from '@mail/drivers/Ses';
+
+import { resolveAttachments, type AttachmentInput } from '@mail/attachments';
+import { MailDriverRegistry } from '@mail/MailDriverRegistry';
+import { Storage } from '@tools/storage';
+
+export type SendMailInput = {
+  to: string | string[];
+  subject: string;
+  text: string;
+  html?: string;
+  from?: {
+    address?: string;
+    name?: string;
+  };
+  attachments?: AttachmentInput[];
+};
+
+export type SendMailResult = {
+  ok: boolean;
+  driver: 'sendgrid' | 'disabled' | 'smtp' | 'ses' | 'mailgun' | 'nodemailer';
+  messageId?: string;
+};
+
+type StorageWrapper = {
+  get: (disk: string, path: string) => Promise<Buffer>;
+  exists: (disk: string, path: string) => Promise<boolean>;
+};
+
+type StorageDiskLike = {
+  driver: {
+    get: (config: unknown, path: string) => Promise<Buffer> | Buffer;
+    exists: (config: unknown, path: string) => Promise<boolean> | boolean;
+  };
+  config: unknown;
+};
+
+const resolveFrom = (input?: SendMailInput['from']): MailAddress => {
+  const address = input?.address ?? mailConfig.from.address;
+  const name = input?.name ?? mailConfig.from.name;
+
+  if (address.trim() === '') {
+    const err = ErrorFactory.createConfigError(
+      'Mail: missing from address (set MAIL_FROM_ADDRESS or pass from.address)'
+    );
+    throw err;
+  }
+
+  return { email: address, name: name.trim() === '' ? undefined : name };
+};
+
+function assertStorageDiskLike(value: unknown): asserts value is StorageDiskLike {
+  if (typeof value !== 'object' || value === null) {
+    const err = ErrorFactory.createConfigError('Storage disk is invalid (expected object)');
+    throw err;
+  }
+
+  const v = value as Record<string, unknown>;
+  const driver = v['driver'];
+
+  if (typeof driver !== 'object' || driver === null) {
+    const err = ErrorFactory.createConfigError('Storage disk driver is invalid (expected object)');
+    throw err;
+  }
+
+  const d = driver as Record<string, unknown>;
+
+  if (typeof d['get'] !== 'function') {
+    const err = ErrorFactory.createConfigError('Storage disk driver is missing get()');
+    throw err;
+  }
+
+  if (typeof d['exists'] !== 'function') {
+    const err = ErrorFactory.createConfigError('Storage disk driver is missing exists()');
+    throw err;
+  }
+}
+
+const getDiskSafe = (disk: string): StorageDiskLike => {
+  const diskValue = Storage.getDisk(disk) as unknown;
+  assertStorageDiskLike(diskValue);
+  return diskValue;
+};
+
+const createStorageWrapper = (): StorageWrapper => ({
+  async get(disk: string, path: string) {
+    const d = getDiskSafe(disk);
+    const result = await Promise.resolve(d.driver.get(d.config, path));
+    return result;
+  },
+  async exists(disk: string, path: string) {
+    const d = getDiskSafe(disk);
+    const result = await Promise.resolve(d.driver.exists(d.config, path));
+    return Boolean(result);
+  },
+});
+
+type MailMessage = {
+  to: SendMailInput['to'];
+  from: MailAddress;
+  subject: string;
+  text: string;
+  html?: string;
+  attachments: Awaited<ReturnType<typeof resolveAttachments>>;
+};
+
+const sendWithDriver = async (
+  driver: ReturnType<typeof mailConfig.getDriver>,
+  message: MailMessage
+): Promise<SendMailResult> => {
+  if (driver.driver === 'ses') {
+    const result = await SesDriver.send({ region: driver.region }, message);
+    return { ok: result.ok, driver: 'ses', messageId: result.messageId };
+  }
+
+  // Drivers resolve via MailDriverRegistry (external packages)
+  const external = MailDriverRegistry.get(driver.driver);
+  if (external !== undefined) {
+    const result = await external(driver as unknown, message);
+    return {
+      ok: Boolean(result?.ok),
+      driver: driver.driver as SendMailResult['driver'],
+      messageId: typeof result?.messageId === 'string' ? result.messageId : undefined,
+    };
+  }
+
+  if (driver.driver === 'sendgrid' || driver.driver === 'mailgun' || driver.driver === 'smtp') {
+    throw ErrorFactory.createConfigError(
+      `Mail driver not registered: ${driver.driver} (run \`zin add mail:${driver.driver}\` / \`npm i @zintrust/mail-${driver.driver}\`)`
+    );
+  }
+
+  // Config exists for future drivers, but implementations are intentionally CLI/runtime-safe and added incrementally.
+  throw ErrorFactory.createConfigError(
+    `Mail driver not registered: ${mailConfig.default}. Available drivers: ses, sendgrid, mailgun, smtp. Run \`zin add mail:${mailConfig.default}\` to install.`
+  );
+};
+
+const createMailer = (
+  name?: string
+): Readonly<{
+  send: (input: SendMailInput) => Promise<SendMailResult>;
+}> =>
+  Object.freeze({
+    async send(input: SendMailInput): Promise<SendMailResult> {
+      const driver = mailConfig.getDriver(name);
+      if (driver.driver === 'disabled') {
+        const err = ErrorFactory.createConfigError('Mail driver is disabled (set MAIL_DRIVER)');
+        throw err;
+      }
+
+      const from = resolveFrom(input.from);
+      const storage = createStorageWrapper();
+      const attachments = await resolveAttachments(input.attachments, { storage });
+
+      return sendWithDriver(driver, {
+        to: input.to,
+        from,
+        subject: input.subject,
+        text: input.text,
+        html: input.html,
+        attachments,
+      });
+    },
+  });
+
+export interface RenderMailInput {
+  template: string; // template name (without .html) or raw HTML content
+  variables?: Record<string, unknown>;
+}
+
+const looksLikeHtml = (value: string): boolean => /<\s*html\b|<!doctype\b|<\s*body\b/i.test(value);
+
+async function renderTemplateToHtml(input: RenderMailInput): Promise<string> {
+  const { template, variables } = input;
+  // Import lazily to avoid circular deps
+  const { loadTemplate } = await import('./template-loader.js');
+  if (looksLikeHtml(template)) {
+    return loadTemplate(
+      template,
+      (variables ?? {}) as import('@mail/template-utils').TemplateVariables
+    );
+  }
+  // template-loader expects full filename
+  const fileName = template.endsWith('.html') ? template : `${template}.html`;
+  return loadTemplate(
+    fileName,
+    (variables ?? {}) as import('@mail/template-utils').TemplateVariables
+  );
+}
+
+export const Mail = Object.freeze({
+  /**
+   * Render a template with variables and return HTML (preview only).
+   */
+  async render(input: RenderMailInput): Promise<string> {
+    return renderTemplateToHtml(input);
+  },
+
+  /** Alias of render */
+  async view(input: RenderMailInput): Promise<string> {
+    return renderTemplateToHtml(input);
+  },
+  /**
+   * Select a named mailer (key from mailConfig.drivers).
+   *
+   * Example: `Mail.mailer('transactional').send(...)`
+   */
+  mailer(name: string) {
+    return createMailer(name);
+  },
+
+  async send(input: SendMailInput): Promise<SendMailResult> {
+    return createMailer().send(input);
+  },
+});
+
+export default Mail;

package/src/tools/mail/template-loader.ts

@@ -0,0 +1,336 @@
+import { ErrorFactory } from '@exceptions/ZintrustError';
+import { readFile } from '@node-singletons/fs';
+import { dirname, join } from '@node-singletons/path';
+import { fileURLToPath, pathToFileURL } from '@node-singletons/url';
+
+import { Env } from '@config/env';
+import type { TemplateVariables } from '@mail/template-utils';
+import { interpolate } from '@mail/template-utils';
+
+const looksLikeHtml = (value: string): boolean => /<\s*html\b|<!doctype\b|<\s*body\b/i.test(value);
+
+const builtinTemplateLoaders = Object.freeze({
+  'auth-password-reset': async () => import('./templates/auth-password-reset.js'),
+  'auth-welcome': async () => import('./templates/auth-welcome.js'),
+  general: async () => import('./templates/general.js'),
+  'job-completed': async () => import('./templates/job-completed.js'),
+  'notifications-new-comment': async () => import('./templates/notifications-new-comment.js'),
+  'password-reset': async () => import('./templates/password-reset.js'),
+  'performance-report': async () => import('./templates/performance-report.js'),
+  welcome: async () => import('./templates/welcome.js'),
+  'worker-alert': async () => import('./templates/worker-alert.js'),
+});
+
+const getSafeCwd = (): string => {
+  try {
+    if (typeof process !== 'undefined' && typeof process.cwd === 'function') {
+      const cwd = process.cwd();
+      if (typeof cwd === 'string' && cwd.trim() !== '') return cwd;
+    }
+  } catch {
+    return '';
+  }
+  return '';
+};
+
+/**
+ * Get the base directory for templates.
+ * In Cloudflare Workers, import.meta.url may be undefined, so we handle that case.
+ */
+function getBaseDir(): string {
+  try {
+    // Check if import.meta.url is available (Node.js, Deno, modern bundlers)
+    if (typeof import.meta.url === 'string' && import.meta.url.trim() !== '') {
+      return dirname(fileURLToPath(import.meta.url));
+    }
+  } catch {
+    // Fallback for environments where fileURLToPath fails
+  }
+
+  // Fallback: use cwd if available
+  const cwd = getSafeCwd();
+  if (cwd.trim() !== '') {
+    return join(cwd, 'src', 'tools', 'mail');
+  }
+
+  // Last resort: return a relative path that might work
+  return './src/tools/mail';
+}
+
+function resolveTemplatePath(templateName: string): string {
+  const baseDir = getBaseDir();
+  const isPath = templateName.includes('/') || templateName.endsWith('.html');
+
+  if (!isPath) {
+    return join(baseDir, 'templates', `${templateName}.html`);
+  }
+
+  if (templateName.startsWith('/')) {
+    return templateName;
+  }
+
+  const cwd = getSafeCwd();
+  return cwd.trim() === '' ? join(baseDir, templateName) : join(cwd, templateName);
+}
+
+function normalizeTemplateName(templateName: string): {
+  normalizedTemplate: string;
+  normalizedModuleName: string;
+} {
+  return {
+    normalizedTemplate: templateName.endsWith('.html') ? templateName : `${templateName}.html`,
+    normalizedModuleName: templateName.endsWith('.html') ? templateName.slice(0, -5) : templateName,
+  };
+}
+
+async function tryBuiltinLoader(normalizedModuleName: string): Promise<string | null> {
+  const builtinLoader =
+    builtinTemplateLoaders[normalizedModuleName as keyof typeof builtinTemplateLoaders];
+
+  if (builtinLoader === undefined) {
+    return null;
+  }
+
+  try {
+    const imported = (await builtinLoader()) as { default?: unknown };
+    if (typeof imported.default === 'string' && imported.default.trim() !== '') {
+      return imported.default;
+    }
+  } catch {
+    // Fall through to filesystem/module path probes.
+  }
+
+  return null;
+}
+
+function getFileCandidates(templatePath: string, normalizedTemplate: string): string[] {
+  const cwd = getSafeCwd();
+  const baseDir = getBaseDir();
+
+  return [
+    templatePath,
+    join(baseDir, 'templates', normalizedTemplate),
+    join(cwd, 'dist', 'src', 'tools', 'mail', 'templates', normalizedTemplate),
+    join(cwd, 'src', 'tools', 'mail', 'templates', normalizedTemplate),
+  ].filter((path, index, arr) => path.trim() !== '' && arr.indexOf(path) === index);
+}
+
+function getModuleCandidates(normalizedModuleName: string): string[] {
+  const cwd = getSafeCwd();
+  const baseDir = getBaseDir();
+
+  return [
+    join(cwd, 'dist', 'src', 'tools', 'mail', 'templates', `${normalizedModuleName}.js`),
+    join(cwd, 'src', 'tools', 'mail', 'templates', `${normalizedModuleName}.ts`),
+    join(baseDir, 'templates', `${normalizedModuleName}.js`),
+    join(baseDir, 'templates', `${normalizedModuleName}.ts`),
+  ].filter((path, index, arr) => path.trim() !== '' && arr.indexOf(path) === index);
+}
+
+async function tryReadFromCandidates(
+  candidates: string[]
+): Promise<{ content?: string; error?: unknown }> {
+  let lastError: unknown;
+
+  for (const candidate of candidates) {
+    try {
+      // eslint-disable-next-line no-await-in-loop
+      const content = await readFile(candidate, 'utf-8');
+      return { content };
+    } catch (error) {
+      lastError = error;
+    }
+  }
+
+  return { error: lastError };
+}
+
+async function tryImportFromCandidates(
+  moduleCandidates: string[]
+): Promise<{ content?: string; error?: unknown }> {
+  let lastError: unknown;
+
+  for (const modulePath of moduleCandidates) {
+    try {
+      // eslint-disable-next-line no-await-in-loop
+      const imported = (await import(pathToFileURL(modulePath).href)) as { default?: unknown };
+      if (typeof imported.default === 'string' && imported.default.trim() !== '') {
+        return { content: imported.default };
+      }
+    } catch (error) {
+      lastError = error;
+    }
+  }
+
+  return { error: lastError };
+}
+
+async function loadTemplateContent(templateName: string): Promise<string> {
+  const templatePath = resolveTemplatePath(templateName);
+  const { normalizedTemplate, normalizedModuleName } = normalizeTemplateName(templateName);
+
+  // Try builtin loader first
+  const builtinResult = await tryBuiltinLoader(normalizedModuleName);
+  if (builtinResult !== null && typeof builtinResult === 'string') {
+    return builtinResult;
+  }
+
+  // Try file system candidates
+  const fileCandidates = getFileCandidates(templatePath, normalizedTemplate);
+  const fileResult = await tryReadFromCandidates(fileCandidates);
+
+  if (fileResult.content !== undefined) {
+    return fileResult.content;
+  }
+
+  // Try module candidates
+  const moduleCandidates = getModuleCandidates(normalizedModuleName);
+  const moduleResult = await tryImportFromCandidates(moduleCandidates);
+
+  if (moduleResult.content !== undefined) {
+    return moduleResult.content;
+  }
+
+  // Extract last error from failed attempts
+  const lastError = fileResult.error ?? moduleResult.error;
+
+  throw ErrorFactory.createConfigError(
+    `Failed to load template from known paths: ${[...fileCandidates, ...moduleCandidates].join(', ')}` +
+      (lastError === undefined ? '' : `. Last error: ${String(lastError)}`)
+  );
+}
+
+/**
+ * Load and render email template with variable substitution
+ */
+export async function loadTemplate(
+  templateName: string,
+  variables: TemplateVariables = {}
+): Promise<string> {
+  try {
+    const template = looksLikeHtml(templateName)
+      ? templateName
+      : await loadTemplateContent(templateName);
+
+    // Replace variables using shared interpolate util
+    const mergedVars: TemplateVariables = {
+      year: new Date().getFullYear().toString(),
+      APP_NAME: Env.APP_NAME ?? 'ZinTrust',
+      ...variables,
+    };
+    let rendered = interpolate(template, mergedVars);
+
+    // Handle conditional blocks {{#if_condition}}...{{/if_condition}}
+    rendered = renderConditionals(rendered, variables);
+
+    // Handle loops {{#each_array}}...{{/each_array}}
+    rendered = renderLoops(rendered, variables);
+
+    return rendered;
+  } catch (error) {
+    throw ErrorFactory.createConfigError(`Failed to load template ${templateName}: ${error}`);
+  }
+}
+
+/**
+ * Render conditional blocks {{#if_condition}}...{{/if_condition}}
+ */
+function renderConditionals(template: string, variables: TemplateVariables): string {
+  return renderBlockTags(template, 'if', (condition: string, content: string): string => {
+    const value = variables[condition];
+    return value === true || value === 'true' ? content : '';
+  });
+}
+
+/**
+ * Render loop blocks {{#each_array}}...{{/each_array}}
+ */
+function renderLoops(template: string, variables: TemplateVariables): string {
+  return renderBlockTags(template, 'each', (arrayName: string, content: string): string => {
+    const array = variables[arrayName] as unknown[] | undefined;
+
+    if (!Array.isArray(array)) {
+      return '';
+    }
+
+    return array
+      .map((item): string => {
+        let rendered = content;
+
+        if (typeof item === 'object' && item !== null) {
+          for (const [key, value] of Object.entries(item as Record<string, unknown>)) {
+            const regex = new RegExp(`{{${key}}}`, 'g');
+            rendered = rendered.replaceAll(regex, String(value ?? ''));
+          }
+        }
+
+        return rendered;
+      })
+      .join('');
+  });
+}
+
+const isSafeBlockName = (value: string): boolean => /^\w+$/.test(value);
+
+const renderBlockTags = (
+  template: string,
+  tagPrefix: 'if' | 'each',
+  resolver: (name: string, content: string) => string
+): string => {
+  const openPrefix = `{{#${tagPrefix}_`;
+  let cursor = 0;
+  let output = '';
+
+  while (cursor < template.length) {
+    const openIndex = template.indexOf(openPrefix, cursor);
+    if (openIndex < 0) {
+      output += template.slice(cursor);
+      break;
+    }
+
+    output += template.slice(cursor, openIndex);
+
+    const nameStart = openIndex + openPrefix.length;
+    const openEnd = template.indexOf('}}', nameStart);
+    if (openEnd < 0) {
+      output += template.slice(openIndex);
+      break;
+    }
+
+    const name = template.slice(nameStart, openEnd);
+    if (!isSafeBlockName(name)) {
+      output += template.slice(openIndex, openEnd + 2);
+      cursor = openEnd + 2;
+      continue;
+    }
+
+    const closeToken = `{{/${tagPrefix}_${name}}}`;
+    const contentStart = openEnd + 2;
+    const closeIndex = template.indexOf(closeToken, contentStart);
+
+    if (closeIndex < 0) {
+      output += template.slice(openIndex);
+      break;
+    }
+
+    const content = template.slice(contentStart, closeIndex);
+    output += resolver(name, content);
+    cursor = closeIndex + closeToken.length;
+  }
+
+  return output;
+};
+
+/**
+ * Get list of available templates
+ */
+export function getAvailableTemplates(): string[] {
+  return [
+    'welcome.html',
+    'password-reset.html',
+    'job-completed.html',
+    'worker-alert.html',
+    'performance-report.html',
+    'general.html',
+  ];
+}

package/src/tools/mail/template-utils.ts

@@ -0,0 +1,19 @@
+/**
+ * Template utilities shared by mail modules.
+ */
+
+export type TemplateVariables = Record<string, unknown>;
+
+/**
+ * Simple handlebars‐style interpolation: replaces all occurrences of
+ * `{{ key }}` (whitespace optional) with String(value).
+ */
+export function interpolate(template: string, data: TemplateVariables): string {
+  let out = template;
+  for (const [key, value] of Object.entries(data)) {
+    const replacement = value === null || value === undefined ? '' : String(value);
+    const regex = new RegExp(String.raw`{{\s*${key}\s*}}`, 'g');
+    out = out.replace(regex, replacement);
+  }
+  return out;
+}