hazo_notify 1.0.0

package/src/lib/emailer/__tests__/emailer.test.ts

@@ -0,0 +1,200 @@
+/**
+ * Unit tests for emailer service
+ */
+
+import { send_email, load_emailer_config } from '../emailer';
+import { SendEmailOptions, EmailerConfig } from '../types';
+
+// Mock hazo_config
+jest.mock('hazo_config', () => {
+  const mock_config_data = {
+    emailer: {
+      emailer_module: 'zeptoemail_api',
+      zeptomail_api_endpoint: 'https://api.zeptomail.com.au/v1.1/email',
+      zeptomail_api_key: 'test_api_key',
+      from_email: 'test@example.com',
+      from_name: 'Test Sender',
+    },
+    ui: {
+      enable_ui: 'false',
+    },
+  };
+
+  return {
+    HazoConfig: jest.fn().mockImplementation(() => ({
+      getSection: jest.fn((section: string) => mock_config_data[section as keyof typeof mock_config_data]),
+      get: jest.fn((section: string, key: string) => {
+        const section_data = mock_config_data[section as keyof typeof mock_config_data];
+        return section_data?.[key];
+      }),
+      getAllSections: jest.fn(() => mock_config_data),
+    })),
+  };
+});
+
+// Mock fetch
+global.fetch = jest.fn();
+
+describe('Emailer Service', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  describe('load_emailer_config', () => {
+    it('should load configuration from hazo_notify_config.ini', () => {
+      const config = load_emailer_config();
+      expect(config.emailer_module).toBe('zeptoemail_api');
+      expect(config.from_email).toBe('test@example.com');
+      expect(config.from_name).toBe('Test Sender');
+      expect(config.zeptomail_api_endpoint).toBe('https://api.zeptomail.com.au/v1.1/email');
+    });
+  });
+
+  describe('send_email', () => {
+    it('should send email successfully', async () => {
+      const mock_response = {
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+        headers: new Headers({ 'content-type': 'application/json' }),
+        json: async () => ({
+          data: {
+            message_id: 'test_message_id',
+          },
+        }),
+        text: async () => '',
+      };
+
+      (global.fetch as jest.Mock).mockResolvedValueOnce(mock_response);
+
+      const options: SendEmailOptions = {
+        to: 'recipient@example.com',
+        subject: 'Test Subject',
+        content: {
+          text: 'Test email content',
+        },
+      };
+
+      const result = await send_email(options);
+
+      expect(result.success).toBe(true);
+      expect(result.message_id).toBe('test_message_id');
+      expect(global.fetch).toHaveBeenCalledTimes(1);
+    });
+
+    it('should handle email sending failure', async () => {
+      const mock_response = {
+        ok: false,
+        status: 400,
+        statusText: 'Bad Request',
+        headers: new Headers({ 'content-type': 'application/json' }),
+        json: async () => ({
+          error: 'Invalid email address',
+        }),
+        text: async () => '',
+      };
+
+      (global.fetch as jest.Mock).mockResolvedValueOnce(mock_response);
+
+      const options: SendEmailOptions = {
+        to: 'invalid_email',
+        subject: 'Test Subject',
+        content: {
+          text: 'Test email content',
+        },
+      };
+
+      const result = await send_email(options);
+
+      expect(result.success).toBe(false);
+      expect(result.error).toBe('Invalid email address');
+    });
+
+    it('should validate required fields', async () => {
+      const options: SendEmailOptions = {
+        to: '',
+        subject: 'Test Subject',
+        content: {
+          text: 'Test email content',
+        },
+      };
+
+      const result = await send_email(options);
+
+      expect(result.success).toBe(false);
+      expect(result.error).toContain('Recipient email address');
+    });
+
+    it('should support HTML email content', async () => {
+      const mock_response = {
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+        headers: new Headers({ 'content-type': 'application/json' }),
+        json: async () => ({
+          data: {
+            message_id: 'test_message_id',
+          },
+        }),
+        text: async () => '',
+      };
+
+      (global.fetch as jest.Mock).mockResolvedValueOnce(mock_response);
+
+      const options: SendEmailOptions = {
+        to: 'recipient@example.com',
+        subject: 'Test Subject',
+        content: {
+          html: '<h1>Test HTML Email</h1>',
+        },
+      };
+
+      const result = await send_email(options);
+
+      expect(result.success).toBe(true);
+      expect(global.fetch).toHaveBeenCalledTimes(1);
+    });
+
+    it('should support multiple attachments', async () => {
+      const mock_response = {
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+        headers: new Headers({ 'content-type': 'application/json' }),
+        json: async () => ({
+          data: {
+            message_id: 'test_message_id',
+          },
+        }),
+        text: async () => '',
+      };
+
+      (global.fetch as jest.Mock).mockResolvedValueOnce(mock_response);
+
+      const options: SendEmailOptions = {
+        to: 'recipient@example.com',
+        subject: 'Test Subject',
+        content: {
+          text: 'Test email content',
+        },
+        attachments: [
+          {
+            filename: 'test1.txt',
+            content: 'dGVzdCBjb250ZW50',
+            mime_type: 'text/plain',
+          },
+          {
+            filename: 'test2.pdf',
+            content: 'dGVzdCBwZGYgY29udGVudA==',
+            mime_type: 'application/pdf',
+          },
+        ],
+      };
+
+      const result = await send_email(options);
+
+      expect(result.success).toBe(true);
+      expect(global.fetch).toHaveBeenCalledTimes(1);
+    });
+  });
+});

package/src/lib/emailer/emailer.ts

@@ -0,0 +1,263 @@
+/**
+ * Emailer service implementation
+ * Reads configuration from hazo_notify_config.ini via hazo_config package
+ * and sends emails using the configured provider
+ */
+
+import { EmailerConfig, SendEmailOptions, EmailSendResponse, EmailerModule } from './types';
+import { get_email_provider } from './providers';
+import { HazoConfig } from 'hazo_config';
+import { join } from 'path';
+import { VALID_EMAILER_MODULES, DEFAULT_RATE_LIMIT_REQUESTS, DEFAULT_RATE_LIMIT_WINDOW, DEFAULT_MAX_ATTACHMENT_SIZE, DEFAULT_MAX_ATTACHMENTS, DEFAULT_REQUEST_TIMEOUT, MAX_SUBJECT_LENGTH, MAX_BODY_LENGTH } from './utils/constants';
+import { log_error, create_log_entry } from './utils/logger';
+import { validate_email_address, validate_subject_length, validate_body_length, validate_attachment_size } from './utils/validation';
+
+/**
+ * Load emailer configuration from hazo_notify_config.ini
+ * @returns Emailer configuration
+ */
+export function load_emailer_config(): EmailerConfig {
+  const filename = 'emailer.ts';
+  const function_name = 'load_emailer_config';
+
+  try {
+    // Read configuration from hazo_notify_config.ini using hazo_config
+    const config_file_path = join(process.cwd(), 'hazo_notify_config.ini');
+    const hazo_config = new HazoConfig({ filePath: config_file_path });
+    const emailer_section = hazo_config.getSection('emailer') || {};
+    const emailer_module_raw = emailer_section?.emailer_module || 'zeptoemail_api';
+    
+    // Validate emailer_module
+    if (!VALID_EMAILER_MODULES.includes(emailer_module_raw as EmailerModule)) {
+      throw new Error(`Invalid emailer_module: ${emailer_module_raw}. Must be one of: ${VALID_EMAILER_MODULES.join(', ')}`);
+    }
+    
+    const emailer_module = emailer_module_raw as EmailerModule;
+
+    // Build configuration object
+    const config: EmailerConfig = {
+      emailer_module: emailer_module,
+      from_email: emailer_section?.from_email || '',
+      from_name: emailer_section?.from_name || 'Hazo Notify',
+      // Rate limiting
+      rate_limit_requests: parseInt(emailer_section?.rate_limit_requests || String(DEFAULT_RATE_LIMIT_REQUESTS), 10),
+      rate_limit_window: parseInt(emailer_section?.rate_limit_window || String(DEFAULT_RATE_LIMIT_WINDOW), 10),
+      // Attachment limits
+      max_attachment_size: parseInt(emailer_section?.max_attachment_size || String(DEFAULT_MAX_ATTACHMENT_SIZE), 10),
+      max_attachments: parseInt(emailer_section?.max_attachments || String(DEFAULT_MAX_ATTACHMENTS), 10),
+      // Request timeout
+      request_timeout: parseInt(emailer_section?.request_timeout || String(DEFAULT_REQUEST_TIMEOUT), 10),
+      // Input length limits
+      max_subject_length: parseInt(emailer_section?.max_subject_length || String(MAX_SUBJECT_LENGTH), 10),
+      max_body_length: parseInt(emailer_section?.max_body_length || String(MAX_BODY_LENGTH), 10),
+      // CORS
+      cors_allowed_origins: emailer_section?.cors_allowed_origins || '',
+    };
+
+    // Load Zeptomail API configuration if emailer_module is 'zeptoemail_api'
+    if (emailer_module === 'zeptoemail_api') {
+      config.zeptomail_api_endpoint = emailer_section?.zeptomail_api_endpoint || 'https://api.zeptomail.com.au/v1.1/email';
+      // Prioritize environment variables over config file for security
+      // Check .env.local first (Next.js convention), then .env, then config file
+      config.zeptomail_api_key = process.env.ZEPTOMAIL_API_KEY || emailer_section?.zeptomail_api_key || '';
+    }
+
+    // Load optional configuration
+    if (emailer_section?.reply_to_email) {
+      config.reply_to_email = emailer_section.reply_to_email;
+    }
+    if (emailer_section?.bounce_email) {
+      config.bounce_email = emailer_section.bounce_email;
+    }
+    if (emailer_section?.return_path_email) {
+      config.return_path_email = emailer_section.return_path_email;
+    }
+
+    // Load SMTP configuration if emailer_module is 'smtp' (placeholder)
+    if (emailer_module === 'smtp') {
+      config.smtp_host = emailer_section?.smtp_host || '';
+      config.smtp_port = parseInt(emailer_section?.smtp_port || '587', 10);
+      const smtp_secure_value: unknown = emailer_section?.smtp_secure;
+      config.smtp_secure = smtp_secure_value === 'true' || smtp_secure_value === true;
+      config.smtp_auth_user = emailer_section?.smtp_auth_user || '';
+      config.smtp_auth_pass = emailer_section?.smtp_auth_pass || '';
+      config.smtp_timeout = parseInt(emailer_section?.smtp_timeout || '5000', 10);
+      const smtp_pool_value: unknown = emailer_section?.smtp_pool;
+      config.smtp_pool = smtp_pool_value === 'true' || smtp_pool_value === true;
+    }
+
+    // Load POP3 configuration if emailer_module is 'pop3' (placeholder)
+    if (emailer_module === 'pop3') {
+      config.pop3_host = emailer_section?.pop3_host || '';
+      config.pop3_port = parseInt(emailer_section?.pop3_port || '995', 10);
+      const pop3_secure_value: unknown = emailer_section?.pop3_secure;
+      config.pop3_secure = pop3_secure_value === 'true' || pop3_secure_value === true;
+      config.pop3_auth_user = emailer_section?.pop3_auth_user || '';
+      config.pop3_auth_pass = emailer_section?.pop3_auth_pass || '';
+      config.pop3_timeout = parseInt(emailer_section?.pop3_timeout || '5000', 10);
+    }
+
+    // Validate required configuration
+    if (!config.from_email) {
+      throw new Error('from_email is required in hazo_notify_config.ini');
+    }
+    if (!config.from_name) {
+      throw new Error('from_name is required in hazo_notify_config.ini');
+    }
+    
+    // Validate emailer_module specific configuration
+    if (emailer_module === 'zeptoemail_api') {
+      if (!config.zeptomail_api_endpoint) {
+        throw new Error('zeptomail_api_endpoint is required when emailer_module=zeptoemail_api');
+      }
+      if (!config.zeptomail_api_key) {
+        throw new Error('Zeptomail API key is required. Set ZEPTOMAIL_API_KEY in .env.local or zeptomail_api_key in config file');
+      }
+    }
+
+    return config;
+  } catch (error: unknown) {
+    const error_message = error instanceof Error ? error.message : 'Failed to load emailer configuration';
+    const error_string = error instanceof Error ? error.toString() : String(error);
+    const stack = error instanceof Error ? error.stack : undefined;
+    
+    log_error(create_log_entry(
+      filename,
+      function_name,
+      error_message,
+      {
+        line_number: stack || 'unknown',
+        error: error_string,
+      }
+    ));
+
+    throw new Error(`Failed to load emailer configuration: ${error_message}`);
+  }
+}
+
+/**
+ * Send email using the configured provider
+ * @param options - Email send options
+ * @param config - Optional emailer configuration (if not provided, loads from config file)
+ * @returns Promise with email send response
+ */
+export async function send_email(
+  options: SendEmailOptions,
+  config?: EmailerConfig
+): Promise<EmailSendResponse> {
+  const filename = 'emailer.ts';
+  const function_name = 'send_email';
+
+  try {
+    // Load configuration if not provided
+    const emailer_config = config || load_emailer_config();
+
+    // Validate email options
+    if (!options.to || (Array.isArray(options.to) && options.to.length === 0)) {
+      throw new Error('Recipient email address(es) are required');
+    }
+    
+    // Validate email addresses
+    const to_emails = Array.isArray(options.to) ? options.to : [options.to];
+    for (const email of to_emails) {
+      if (!validate_email_address(email)) {
+        throw new Error(`Invalid recipient email address: ${email}`);
+      }
+    }
+    
+    if (!options.subject) {
+      throw new Error('Email subject is required');
+    }
+    
+    // Validate subject length
+    if (!validate_subject_length(options.subject)) {
+      throw new Error(`Email subject exceeds maximum length of ${emailer_config.max_subject_length || MAX_SUBJECT_LENGTH} characters`);
+    }
+    
+    if (!options.content.text && !options.content.html) {
+      throw new Error('Email content (text or html) is required');
+    }
+    
+    // Validate body length
+    if (options.content.text && !validate_body_length(options.content.text)) {
+      throw new Error(`Email text body exceeds maximum size of ${emailer_config.max_body_length || MAX_BODY_LENGTH} bytes`);
+    }
+    if (options.content.html && !validate_body_length(options.content.html)) {
+      throw new Error(`Email HTML body exceeds maximum size of ${emailer_config.max_body_length || MAX_BODY_LENGTH} bytes`);
+    }
+    
+    // Validate attachments
+    if (options.attachments) {
+      const max_attachments = emailer_config.max_attachments || DEFAULT_MAX_ATTACHMENTS;
+      if (options.attachments.length > max_attachments) {
+        throw new Error(`Maximum ${max_attachments} attachments allowed`);
+      }
+      
+      const max_size = emailer_config.max_attachment_size || DEFAULT_MAX_ATTACHMENT_SIZE;
+      for (const attachment of options.attachments) {
+        if (!validate_attachment_size(attachment.content, max_size)) {
+          throw new Error(`Attachment "${attachment.filename}" exceeds maximum size of ${max_size} bytes`);
+        }
+      }
+    }
+
+    // Get appropriate provider
+    const provider = get_email_provider(emailer_config);
+
+    // Send email
+    const response = await provider.send_email(options, emailer_config);
+
+    // Log error if email sending failed
+    if (!response.success) {
+      log_error(create_log_entry(
+        filename,
+        function_name,
+        response.error || 'Failed to send email',
+        {
+          options: {
+            to: options.to,
+            subject: options.subject,
+            has_text: !!options.content.text,
+            has_html: !!options.content.html,
+            attachments_count: options.attachments?.length || 0,
+          },
+          response: response.raw_response,
+        }
+      ));
+    }
+
+    return response;
+  } catch (error: unknown) {
+    const error_message = error instanceof Error ? error.message : 'Failed to send email';
+    const error_string = error instanceof Error ? error.toString() : String(error);
+    const stack = error instanceof Error ? error.stack : undefined;
+    const is_production = process.env.NODE_ENV === 'production';
+    
+    log_error(create_log_entry(
+      filename,
+      function_name,
+      error_message,
+      {
+        line_number: stack || 'unknown',
+        error: error_string,
+        options: {
+          to: options.to,
+          subject: options.subject,
+          has_text: !!options.content.text,
+          has_html: !!options.content.html,
+          attachments_count: options.attachments?.length || 0,
+        },
+      }
+    ));
+
+    return {
+      success: false,
+      error: error_message,
+      message: error_message,
+      raw_response: is_production ? undefined : {
+        error: error_string,
+        stack: stack,
+      },
+    };
+  }
+}

package/src/lib/emailer/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Emailer service exports
+ * Main entry point for the emailer library
+ */
+
+export { send_email, load_emailer_config } from './emailer';
+export * from './types';
+export { get_email_provider } from './providers';
+export { ZeptomailProvider } from './providers/zeptomail_provider';
+export { SmtpProvider } from './providers/smtp_provider';
+export { Pop3Provider } from './providers/pop3_provider';

package/src/lib/emailer/providers/__tests__/zeptomail_provider.test.ts

@@ -0,0 +1,196 @@
+/**
+ * Unit tests for Zeptomail provider
+ */
+
+import { ZeptomailProvider } from '../zeptomail_provider';
+import { SendEmailOptions, EmailerConfig } from '../../types';
+
+// Mock fetch
+global.fetch = jest.fn();
+
+describe('ZeptomailProvider', () => {
+  let provider: ZeptomailProvider;
+  let config: EmailerConfig;
+
+  beforeEach(() => {
+    provider = new ZeptomailProvider();
+    config = {
+      emailer_module: 'zeptoemail_api',
+      zeptomail_api_endpoint: 'https://api.zeptomail.com.au/v1.1/email',
+      zeptomail_api_key: 'test_api_key',
+      from_email: 'test@example.com',
+      from_name: 'Test Sender',
+    };
+    jest.clearAllMocks();
+  });
+
+  describe('send_email', () => {
+    it('should send email successfully', async () => {
+      const mock_response = {
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+        headers: new Headers({ 'content-type': 'application/json' }),
+        json: async () => ({
+          data: {
+            message_id: 'test_message_id',
+          },
+        }),
+        text: async () => '',
+      };
+
+      (global.fetch as jest.Mock).mockResolvedValueOnce(mock_response);
+
+      const options: SendEmailOptions = {
+        to: 'recipient@example.com',
+        subject: 'Test Subject',
+        content: {
+          text: 'Test email content',
+        },
+      };
+
+      const result = await provider.send_email(options, config);
+
+      expect(result.success).toBe(true);
+      expect(result.message_id).toBe('test_message_id');
+      expect(global.fetch).toHaveBeenCalledTimes(1);
+      expect(global.fetch).toHaveBeenCalledWith(
+        config.zeptomail_api_endpoint,
+        expect.objectContaining({
+          method: 'POST',
+          headers: expect.objectContaining({
+            'Content-Type': 'application/json',
+            'Authorization': expect.stringContaining('Zoho-enczapikey'),
+          }),
+        })
+      );
+    });
+
+    it('should handle API errors', async () => {
+      const mock_response = {
+        ok: false,
+        status: 400,
+        statusText: 'Bad Request',
+        headers: new Headers({ 'content-type': 'application/json' }),
+        json: async () => ({
+          error: 'Invalid email address',
+        }),
+        text: async () => '',
+      };
+
+      (global.fetch as jest.Mock).mockResolvedValueOnce(mock_response);
+
+      const options: SendEmailOptions = {
+        to: 'invalid_email',
+        subject: 'Test Subject',
+        content: {
+          text: 'Test email content',
+        },
+      };
+
+      const result = await provider.send_email(options, config);
+
+      expect(result.success).toBe(false);
+      expect(result.error).toBe('Invalid email address');
+    });
+
+    it('should validate required configuration', async () => {
+      const invalid_config: EmailerConfig = {
+        emailer_module: 'zeptoemail_api',
+        from_email: 'test@example.com',
+        from_name: 'Test Sender',
+      };
+
+      const options: SendEmailOptions = {
+        to: 'recipient@example.com',
+        subject: 'Test Subject',
+        content: {
+          text: 'Test email content',
+        },
+      };
+
+      const result = await provider.send_email(options, invalid_config);
+
+      expect(result.success).toBe(false);
+      expect(result.error).toContain('required');
+    });
+
+    it('should support HTML email content', async () => {
+      const mock_response = {
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+        headers: new Headers({ 'content-type': 'application/json' }),
+        json: async () => ({
+          data: {
+            message_id: 'test_message_id',
+          },
+        }),
+        text: async () => '',
+      };
+
+      (global.fetch as jest.Mock).mockResolvedValueOnce(mock_response);
+
+      const options: SendEmailOptions = {
+        to: 'recipient@example.com',
+        subject: 'Test Subject',
+        content: {
+          html: '<h1>Test HTML Email</h1>',
+        },
+      };
+
+      const result = await provider.send_email(options, config);
+
+      expect(result.success).toBe(true);
+      const call_args = (global.fetch as jest.Mock).mock.calls[0];
+      const request_body = JSON.parse(call_args[1].body);
+      expect(request_body.htmlbody).toBe('<h1>Test HTML Email</h1>');
+    });
+
+    it('should support multiple attachments', async () => {
+      const mock_response = {
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+        headers: new Headers({ 'content-type': 'application/json' }),
+        json: async () => ({
+          data: {
+            message_id: 'test_message_id',
+          },
+        }),
+        text: async () => '',
+      };
+
+      (global.fetch as jest.Mock).mockResolvedValueOnce(mock_response);
+
+      const options: SendEmailOptions = {
+        to: 'recipient@example.com',
+        subject: 'Test Subject',
+        content: {
+          text: 'Test email content',
+        },
+        attachments: [
+          {
+            filename: 'test1.txt',
+            content: 'dGVzdCBjb250ZW50',
+            mime_type: 'text/plain',
+          },
+          {
+            filename: 'test2.pdf',
+            content: 'dGVzdCBwZGYgY29udGVudA==',
+            mime_type: 'application/pdf',
+          },
+        ],
+      };
+
+      const result = await provider.send_email(options, config);
+
+      expect(result.success).toBe(true);
+      const call_args = (global.fetch as jest.Mock).mock.calls[0];
+      const request_body = JSON.parse(call_args[1].body);
+      expect(request_body.attachments).toHaveLength(2);
+      expect(request_body.attachments[0].name).toBe('test1.txt');
+      expect(request_body.attachments[1].name).toBe('test2.pdf');
+    });
+  });
+});

package/src/lib/emailer/providers/index.ts

@@ -0,0 +1,33 @@
+/**
+ * Provider factory for email providers
+ * Selects and returns the appropriate provider based on configuration
+ */
+
+import { EmailProvider, EmailerConfig, EmailerModule } from '../types';
+import { ZeptomailProvider } from './zeptomail_provider';
+import { SmtpProvider } from './smtp_provider';
+import { Pop3Provider } from './pop3_provider';
+
+/**
+ * Get email provider based on configuration module
+ * @param config - Emailer configuration
+ * @returns Email provider instance
+ */
+export function get_email_provider(config: EmailerConfig): EmailProvider {
+  const emailer_module: EmailerModule = config.emailer_module || 'zeptoemail_api';
+
+  switch (emailer_module) {
+    case 'zeptoemail_api':
+      return new ZeptomailProvider();
+    case 'smtp':
+      return new SmtpProvider();
+    case 'pop3':
+      return new Pop3Provider();
+    default:
+      throw new Error(`Unsupported emailer module: ${emailer_module}`);
+  }
+}
+
+export { ZeptomailProvider } from './zeptomail_provider';
+export { SmtpProvider } from './smtp_provider';
+export { Pop3Provider } from './pop3_provider';