@bernierllc/email-template-engine/src/types.ts

Email template processing engine with compilation, rendering, and text generation

/*
Copyright (c) 2025 Bernier LLC

This file is licensed to the client under a limited-use license.
The client may use and modify this code *only within the scope of the project it was delivered for*.
Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
*/

import type { HelperDelegate } from 'handlebars';

/**
 * Base template structure (header/footer)
 */
export interface BaseTemplate {
  headerHtml: string;
  footerHtml: string;
  headerCss?: string;
  footerCss?: string;
}

/**
 * Complete built template result
 */
export interface BuiltTemplate {
  html: string;
  text: string;
  variables: TemplateVariable[];
  baseTemplateId?: string;
  contentHtml: string;
  metadata: {
    buildTime: number;
    variableCount: number;
    contentLength: number;
  };
}

/**
 * Template variable information
 */
export interface TemplateVariable {
  name: string;
  path: string;
  type: 'string' | 'number' | 'boolean' | 'object' | 'array';
  firstOccurrence: number; // Character position in template
  occurrenceCount: number;
}

/**
 * Template validation result
 */
export interface TemplateValidationResult {
  isValid: boolean;
  errors: TemplateValidationError[];
  warnings: string[];
  variables: TemplateVariable[];
}

/**
 * Template validation error
 */
export interface TemplateValidationError {
  type: 'syntax' | 'variable' | 'structure';
  message: string;
  line?: number;
  column?: number;
  position?: number;
}

/**
 * Template compilation options
 */
export interface CompilationOptions {
  strict?: boolean; // Throw on undefined variables (default: false)
  noEscape?: boolean; // Disable HTML escaping (default: false)
  helpers?: Record<string, HelperDelegate>;
  partials?: Record<string, string>;
}

/**
 * Text generation options
 */
export interface TextGenerationOptions {
  wordwrap?: number; // Wrap text at N characters (default: 80)
  preserveNewlines?: boolean; // Preserve line breaks (default: true)
  uppercaseHeadings?: boolean; // Uppercase headings (default: true)
  linkBrackets?: boolean; // Wrap links in brackets (default: true)
  ignoreHref?: boolean; // Ignore href attributes (default: false)
  ignoreImage?: boolean; // Ignore images (default: false)
}

/**
 * Result pattern for error handling
 */
export interface TemplateResult<T = unknown> {
  success: boolean;
  data?: T;
  error?: string;
}

/**
 * Logger interface (optional dependency)
 */
export interface Logger {
  error(message: string, context?: Record<string, unknown>): void;
  warn(message: string, context?: Record<string, unknown>): void;
  info(message: string, context?: Record<string, unknown>): void;
  debug(message: string, context?: Record<string, unknown>): void;
}