@sixthsummit/ship-api 0.0.0-stage → 4.1.1

package/lib/libraries/email/TemplateRegistry.ts

@@ -0,0 +1,148 @@
+import type { EmailTemplate } from "./types/index.js";
+
+/**
+ * TemplateRegistry - Registry for managing email templates
+ *
+ * Provides centralized storage and retrieval of email templates.
+ * Templates can be registered at application startup and retrieved by ID.
+ *
+ * @example
+ * ```typescript
+ * const registry = new TemplateRegistry();
+ *
+ * // Register a template
+ * registry.register({
+ *   id: 'welcome',
+ *   name: 'Welcome Email',
+ *   subject: 'Welcome to {{appName}}!',
+ *   html: '<h1>Hello {{firstName}}!</h1>',
+ *   text: 'Hello {{firstName}}!'
+ * });
+ *
+ * // Get a template
+ * const template = registry.get('welcome');
+ *
+ * // List all templates
+ * const templates = registry.list();
+ * ```
+ */
+export default class TemplateRegistry {
+  private templates: Map<string, EmailTemplate<any>>;
+
+  constructor() {
+    this.templates = new Map();
+  }
+
+  /**
+   * Register a new email template
+   * @param template - Template to register
+   * @throws Error if template with same ID already exists
+   */
+  register<T = Record<string, any>>(template: EmailTemplate<T>): void {
+    if (this.templates.has(template.id)) {
+      throw new Error(`Template with ID '${template.id}' already exists`);
+    }
+
+    // Validate template has at least subject and one body type
+    if (!template.subject) {
+      throw new Error(`Template '${template.id}' must have a subject`);
+    }
+
+    if (!template.html && !template.text) {
+      throw new Error(`Template '${template.id}' must have either html or text content`);
+    }
+
+    this.templates.set(template.id, template as EmailTemplate<any>);
+  }
+
+  /**
+   * Register multiple templates at once
+   * @param templates - Array of templates to register
+   */
+  registerMany(templates: EmailTemplate<any>[]): void {
+    for (const template of templates) {
+      this.register(template);
+    }
+  }
+
+  /**
+   * Get a template by ID
+   * @param id - Template ID
+   * @returns Template or undefined if not found
+   */
+  get(id: string): EmailTemplate<any> | undefined {
+    return this.templates.get(id);
+  }
+
+  /**
+   * Get a template by ID or throw error if not found
+   * @param id - Template ID
+   * @returns Template
+   * @throws Error if template not found
+   */
+  getOrThrow(id: string): EmailTemplate<any> {
+    const template = this.templates.get(id);
+    if (!template) {
+      throw new Error(`Template with ID '${id}' not found`);
+    }
+    return template;
+  }
+
+  /**
+   * Check if a template exists
+   * @param id - Template ID
+   * @returns True if template exists
+   */
+  has(id: string): boolean {
+    return this.templates.has(id);
+  }
+
+  /**
+   * Remove a template from the registry
+   * @param id - Template ID
+   * @returns True if template was removed
+   */
+  unregister(id: string): boolean {
+    return this.templates.delete(id);
+  }
+
+  /**
+   * Clear all templates from the registry
+   */
+  clear(): void {
+    this.templates.clear();
+  }
+
+  /**
+   * List all registered templates
+   * @returns Array of all templates
+   */
+  list(): EmailTemplate<any>[] {
+    return Array.from(this.templates.values());
+  }
+
+  /**
+   * Get all template IDs
+   * @returns Array of template IDs
+   */
+  listIds(): string[] {
+    return Array.from(this.templates.keys());
+  }
+
+  /**
+   * Get count of registered templates
+   * @returns Number of templates
+   */
+  count(): number {
+    return this.templates.size;
+  }
+
+  /**
+   * Find templates by tag
+   * @param tag - Tag to search for
+   * @returns Array of templates with the specified tag
+   */
+  findByTag(tag: string): EmailTemplate[] {
+    return Array.from(this.templates.values()).filter((template) => template.tags?.includes(tag));
+  }
+}

package/lib/libraries/email/TemplateRenderer.ts

@@ -0,0 +1,273 @@
+import type { EmailTemplate, RenderedTemplate } from "./types/index.js";
+
+/**
+ * TemplateRenderer - Renders email templates with variable substitution
+ *
+ * Supports:
+ * - Variable substitution using {{variableName}} syntax
+ * - Nested object access using dot notation: {{user.firstName}}
+ * - Array indexing: {{items.0.name}}
+ * - Conditional rendering: {{#if condition}}...{{/if}}
+ * - Loops: {{#each items}}...{{/each}}
+ * - Helper functions: {{formatDate date}}
+ *
+ * @example
+ * ```typescript
+ * const renderer = new TemplateRenderer();
+ * const result = renderer.render(template, {
+ *   firstName: 'John',
+ *   lastName: 'Doe',
+ *   importCount: 100
+ * });
+ * ```
+ */
+export default class TemplateRenderer {
+  /**
+   * Render a template with the provided variables
+   * @param template - Template to render
+   * @param variables - Variables to substitute in the template
+   * @returns Rendered template
+   */
+  render<T extends Record<string, any> = Record<string, any>>(
+    template: EmailTemplate<T>,
+    variables: T,
+  ): RenderedTemplate {
+    // Render subject
+    const subject = this.renderString(template.subject, variables as Record<string, any>);
+
+    // Render HTML body (if present)
+    const html = template.html
+      ? this.renderString(template.html, variables as Record<string, any>)
+      : undefined;
+
+    // Render text body (if present)
+    const text = template.text
+      ? this.renderString(template.text, variables as Record<string, any>)
+      : undefined;
+
+    // Process tags
+    const tags = template.tags?.map((tag) => ({
+      name: tag,
+      value: this.renderString(tag, variables as Record<string, any>),
+    }));
+
+    return {
+      templateId: template.id,
+      subject,
+      html,
+      text,
+      from: template.from,
+      replyTo: template.replyTo,
+      tags,
+    };
+  }
+
+  /**
+   * Render a string with variable substitution
+   * @param content - String content with {{variable}} placeholders
+   * @param variables - Variables to substitute
+   * @returns Rendered string
+   */
+  private renderString(content: string, variables: Record<string, any>): string {
+    let result = content;
+
+    // Handle loops FIRST {{#each items}}...{{/each}}
+    // Loops need to be processed before conditionals because they create context variables like @first, @last
+    result = this.renderLoops(result, variables);
+
+    // Handle conditional blocks {{#if condition}}...{{/if}}
+    result = this.renderConditionals(result, variables);
+
+    // Handle helper functions {{helperName arg1 arg2}} - BEFORE simple variables
+    result = this.renderHelpers(result, variables);
+
+    // Handle simple variable substitution {{variableName}}
+    result = this.renderVariables(result, variables);
+
+    return result;
+  }
+
+  /**
+   * Render simple variable substitutions
+   * Supports:
+   * - {{variableName}}
+   * - {{user.firstName}} (nested objects)
+   * - {{items.0.name}} (array indexing)
+   */
+  private renderVariables(content: string, variables: Record<string, any>): string {
+    return content.replace(/\{\{([^#/}]+)\}\}/g, (match, variablePath) => {
+      const trimmedPath = variablePath.trim();
+      const value = this.getNestedValue(variables, trimmedPath);
+
+      if (value === undefined || value === null) {
+        return "";
+      }
+
+      return String(value);
+    });
+  }
+
+  /**
+   * Render conditional blocks
+   * Syntax: {{#if variableName}}content{{/if}}
+   */
+  private renderConditionals(content: string, variables: Record<string, any>): string {
+    const conditionalRegex = /\{\{#if\s+([^}]+)\}\}([\s\S]*?)\{\{\/if\}\}/g;
+
+    return content.replace(conditionalRegex, (match, condition, innerContent) => {
+      const trimmedCondition = condition.trim();
+
+      // Direct property access for variables starting with @
+      const value = trimmedCondition.startsWith("@")
+        ? variables[trimmedCondition]
+        : this.getNestedValue(variables, trimmedCondition);
+
+      // Evaluate truthiness
+      const isTruthy = this.isTruthy(value);
+
+      return isTruthy ? innerContent : "";
+    });
+  }
+
+  /**
+   * Render loop blocks
+   * Syntax: {{#each items}}{{this.name}}{{/each}}
+   */
+  private renderLoops(content: string, variables: Record<string, any>): string {
+    const loopRegex = /\{\{#each\s+([^}]+)\}\}([\s\S]*?)\{\{\/each\}\}/g;
+
+    return content.replace(loopRegex, (match, arrayPath, innerContent) => {
+      const trimmedPath = arrayPath.trim();
+      const array = this.getNestedValue(variables, trimmedPath);
+
+      if (!Array.isArray(array)) {
+        return "";
+      }
+
+      return array
+        .map((item, index) => {
+          // Create context with 'this' pointing to current item
+          const itemContext = {
+            ...variables,
+            this: item,
+            "@index": index,
+            "@first": index === 0,
+            "@last": index === array.length - 1,
+          };
+
+          // Render inner content with full processing (conditionals, helpers, and variables)
+          let renderedContent = innerContent;
+          renderedContent = this.renderConditionals(renderedContent, itemContext);
+          renderedContent = this.renderHelpers(renderedContent, itemContext);
+          renderedContent = this.renderVariables(renderedContent, itemContext);
+          return renderedContent;
+        })
+        .join("");
+    });
+  }
+
+  /**
+   * Render helper functions
+   * Supports:
+   * - {{formatNumber value}} - Format number with commas
+   * - {{formatDate date}} - Format date
+   * - {{pluralize count singular plural}} - Pluralize based on count
+   */
+  private renderHelpers(content: string, variables: Record<string, any>): string {
+    // Match helper functions that don't use # or /
+    const helperRegex = /\{\{(?!#|\/)(formatNumber|formatDate|pluralize)\s+([^}]+)\}\}/g;
+
+    return content.replace(helperRegex, (match, helperName, args) => {
+      const argsList = args.split(/\s+/).map((arg: string) => {
+        // Check if it's a variable reference or a literal
+        if (arg.startsWith("'") || arg.startsWith('"')) {
+          return arg.slice(1, -1); // Remove quotes
+        }
+        return this.getNestedValue(variables, arg);
+      });
+
+      switch (helperName) {
+        case "formatNumber":
+          return this.formatNumber(argsList[0]);
+        case "formatDate":
+          return this.formatDate(argsList[0]);
+        case "pluralize":
+          return this.pluralize(argsList[0], argsList[1], argsList[2]);
+        default:
+          return match; // Return original if helper not found
+      }
+    });
+  }
+
+  /**
+   * Get nested value from object using dot notation
+   * @param obj - Object to traverse
+   * @param path - Dot-notation path (e.g., "user.firstName" or "items.0.name")
+   * @returns Value at path or undefined
+   */
+  private getNestedValue(obj: any, path: string): any {
+    const parts = path.split(".");
+    let current = obj;
+
+    for (const part of parts) {
+      if (current === undefined || current === null) {
+        return undefined;
+      }
+
+      // Handle array indexing
+      const arrayIndex = parseInt(part, 10);
+      if (!Number.isNaN(arrayIndex)) {
+        current = current[arrayIndex];
+      } else {
+        current = current[part];
+      }
+    }
+
+    return current;
+  }
+
+  /**
+   * Check if a value is truthy
+   */
+  private isTruthy(value: any): boolean {
+    if (value === undefined || value === null) return false;
+    if (typeof value === "boolean") return value;
+    if (typeof value === "number") return value !== 0;
+    if (typeof value === "string") return value.length > 0;
+    if (Array.isArray(value)) return value.length > 0;
+    return true;
+  }
+
+  /**
+   * Format a number with comma separators
+   */
+  private formatNumber(value: any): string {
+    const num = Number(value);
+    if (Number.isNaN(num)) return String(value);
+    return num.toLocaleString();
+  }
+
+  /**
+   * Format a date
+   */
+  private formatDate(value: any): string {
+    if (!value) return "";
+
+    const date = value instanceof Date ? value : new Date(value);
+    if (Number.isNaN(date.getTime())) return String(value);
+
+    return date.toLocaleDateString("en-US", {
+      year: "numeric",
+      month: "long",
+      day: "numeric",
+    });
+  }
+
+  /**
+   * Pluralize based on count
+   */
+  private pluralize(count: any, singular: string, plural: string): string {
+    const num = Number(count);
+    return num === 1 ? singular : plural;
+  }
+}

package/lib/libraries/email/index.ts

@@ -0,0 +1,4 @@
+export { default as EmailService } from "./EmailService.js";
+export { default as TemplateRegistry } from "./TemplateRegistry.js";
+export { default as TemplateRenderer } from "./TemplateRenderer.js";
+export * from "./types/index.js";

package/lib/libraries/email/initializeEmailService.ts

@@ -0,0 +1,60 @@
+import Logger from "../app/utils/Logger.js";
+import EmailService from "./EmailService.js";
+
+/**
+ * Singleton EmailService instance with registered templates
+ * Available globally after initialization
+ */
+let emailServiceInstance: EmailService | null = null;
+
+/**
+ * Initialize the singleton EmailService instance and register all email templates
+ * This function can be called from scripts or tests that need email functionality
+ *
+ * @returns The initialized EmailService instance
+ * @throws Error if initialization fails
+ */
+export async function initializeEmailService(): Promise<EmailService> {
+  // Return existing instance if already initialized
+  if (emailServiceInstance) {
+    return emailServiceInstance;
+  }
+
+  Logger.log("Initializing email templates...");
+
+  try {
+    // Create singleton EmailService instance
+    // Uses RESEND_API_KEY and RESEND_DEFAULT_FROM environment variables
+    emailServiceInstance = new EmailService();
+
+    // Register templates from all modules
+    //emailServiceInstance.registerTemplates(...);
+
+    Logger.log(`Registered ${emailServiceInstance.listTemplates().length} email templates:`, {
+      templateIds: emailServiceInstance.listTemplates().map((t) => t.id),
+    });
+
+    Logger.log("Email templates initialized successfully");
+
+    return emailServiceInstance;
+  } catch (error) {
+    Logger.error("Error initializing email templates:", error);
+    throw error;
+  }
+}
+
+/**
+ * Get the singleton EmailService instance
+ *
+ * @returns EmailService instance with all templates registered
+ * @throws Error if called before initialization
+ */
+export function getEmailService(): EmailService {
+  if (!emailServiceInstance) {
+    throw new Error(
+      "EmailService not initialized. Call initializeEmailService() first or ensure InitEmailTemplates bootstrapper has run.",
+    );
+  }
+
+  return emailServiceInstance;
+}

package/lib/libraries/email/library.json

@@ -0,0 +1,12 @@
+{
+  "name": "email",
+  "description": "Email sending utilities with template support",
+  "version": "1.0.0",
+  "dependencies": [],
+  "npmDependencies": {
+    "resend": "^6.7.0"
+  },
+  "requiredEnvVars": ["RESEND_API_KEY", "RESEND_DEFAULT_FROM"],
+  "optionalEnvVars": [],
+  "postInstall": ["Configure Resend API key and default from address in .env"]
+}

package/lib/libraries/email/types/EmailAddress.ts

@@ -0,0 +1,4 @@
+/**
+ * Email address can be a string or an object with name and email
+ */
+export type EmailAddress = string | { name: string; email: string };

package/lib/libraries/email/types/EmailAttachment.ts

@@ -0,0 +1,11 @@
+/**
+ * Email attachment
+ */
+export interface EmailAttachment {
+  /** Attachment filename */
+  filename: string;
+  /** Attachment content (Buffer or base64 string) */
+  content: Buffer | string;
+  /** Content type (MIME type) */
+  contentType?: string;
+}

package/lib/libraries/email/types/EmailTag.ts

@@ -0,0 +1,9 @@
+/**
+ * Email tag for tracking and organization
+ */
+export interface EmailTag {
+  /** Tag name */
+  name: string;
+  /** Tag value */
+  value: string;
+}

package/lib/libraries/email/types/EmailTemplate.ts

@@ -0,0 +1,124 @@
+/**
+ * Email template definition
+ */
+export interface EmailTemplate<T = Record<string, any>> {
+  /**
+   * Unique identifier for the template
+   */
+  id: string;
+
+  /**
+   * Human-readable name for the template
+   */
+  name: string;
+
+  /**
+   * Description of the template purpose
+   */
+  description?: string;
+
+  /**
+   * Email subject line (supports variable substitution)
+   */
+  subject: string;
+
+  /**
+   * HTML email body (supports variable substitution)
+   */
+  html?: string;
+
+  /**
+   * Plain text email body (supports variable substitution)
+   */
+  text?: string;
+
+  /**
+   * Optional default "from" address for this template
+   */
+  from?: string;
+
+  /**
+   * Optional reply-to address for this template
+   */
+  replyTo?: string;
+
+  /**
+   * Template variables schema (for validation)
+   */
+  variables?: (keyof T)[];
+
+  /**
+   * Optional tags for the template
+   */
+  tags?: string[];
+}
+
+/**
+ * Options for rendering a template
+ */
+export interface RenderTemplateOptions<T = Record<string, any>> {
+  /**
+   * Template ID to render
+   */
+  templateId: string;
+
+  /**
+   * Variables to substitute in the template
+   */
+  variables: T;
+
+  /**
+   * Optional: Override the default "from" address
+   */
+  from?: string;
+
+  /**
+   * Optional: Override the default "reply-to" address
+   */
+  replyTo?: string;
+
+  /**
+   * Optional: Additional tags to add
+   */
+  tags?: string[];
+}
+
+/**
+ * Result of rendering a template
+ */
+export interface RenderedTemplate {
+  /**
+   * Template ID that was rendered
+   */
+  templateId: string;
+
+  /**
+   * Rendered subject line
+   */
+  subject: string;
+
+  /**
+   * Rendered HTML body (if template has HTML)
+   */
+  html?: string;
+
+  /**
+   * Rendered plain text body (if template has text)
+   */
+  text?: string;
+
+  /**
+   * From address
+   */
+  from?: string;
+
+  /**
+   * Reply-to address
+   */
+  replyTo?: string;
+
+  /**
+   * Tags for the email
+   */
+  tags?: Array<{ name: string; value: string }>;
+}

package/lib/libraries/email/types/SendBatchEmailsOptions.ts

@@ -0,0 +1,9 @@
+import type { SendEmailOptions } from "./SendEmailOptions.js";
+
+/**
+ * Options for sending multiple emails in a batch
+ */
+export interface SendBatchEmailsOptions {
+  /** Array of emails to send (max 100) */
+  emails: SendEmailOptions[];
+}

package/lib/libraries/email/types/SendBatchEmailsResult.ts

@@ -0,0 +1,9 @@
+/**
+ * Result of a batch email operation
+ */
+export interface SendBatchEmailsResult {
+  /** Array of email IDs (if successful) */
+  data?: Array<{ id: string }>;
+  /** Error (if failed) */
+  error?: Error;
+}

package/lib/libraries/email/types/SendEmailOptions.ts

@@ -0,0 +1,33 @@
+import type { EmailAddress } from "./EmailAddress.js";
+import type { EmailAttachment } from "./EmailAttachment.js";
+import type { EmailTag } from "./EmailTag.js";
+
+/**
+ * Options for sending a single email
+ */
+export interface SendEmailOptions {
+  /** Sender email address */
+  from?: string;
+  /** Recipient email address(es) */
+  to: EmailAddress | EmailAddress[];
+  /** Email subject */
+  subject: string;
+  /** Plain text content */
+  text?: string;
+  /** HTML content */
+  html?: string;
+  /** CC recipients */
+  cc?: EmailAddress | EmailAddress[];
+  /** BCC recipients */
+  bcc?: EmailAddress | EmailAddress[];
+  /** Reply-to address(es) */
+  replyTo?: EmailAddress | EmailAddress[];
+  /** Email attachments */
+  attachments?: EmailAttachment[];
+  /** Email tags for tracking */
+  tags?: EmailTag[];
+  /** Custom headers */
+  headers?: Record<string, string>;
+  /** Schedule email to be sent at a specific time (ISO 8601 format) */
+  scheduledAt?: string;
+}