hazo_notify 1.0.0

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

@@ -0,0 +1,30 @@
+/**
+ * POP3 provider implementation (placeholder)
+ * This provider is not yet implemented and will return an error
+ */
+
+import { EmailProvider, SendEmailOptions, EmailerConfig, EmailSendResponse } from '../types';
+
+export class Pop3Provider implements EmailProvider {
+  /**
+   * Send email using POP3 (not implemented)
+   * @param options - Email send options
+   * @param config - Emailer configuration
+   * @returns Promise with error response
+   */
+  async send_email(
+    options: SendEmailOptions,
+    config: EmailerConfig
+  ): Promise<EmailSendResponse> {
+    return {
+      success: false,
+      error: 'POP3 provider is not yet implemented',
+      message: 'POP3 provider is not yet implemented. Please use API method instead.',
+      raw_response: {
+        provider: 'pop3',
+        status: 'not_implemented',
+        message: 'POP3 provider is a placeholder and will be implemented in a future version',
+      },
+    };
+  }
+}

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

@@ -0,0 +1,30 @@
+/**
+ * SMTP provider implementation (placeholder)
+ * This provider is not yet implemented and will return an error
+ */
+
+import { EmailProvider, SendEmailOptions, EmailerConfig, EmailSendResponse } from '../types';
+
+export class SmtpProvider implements EmailProvider {
+  /**
+   * Send email using SMTP (not implemented)
+   * @param options - Email send options
+   * @param config - Emailer configuration
+   * @returns Promise with error response
+   */
+  async send_email(
+    options: SendEmailOptions,
+    config: EmailerConfig
+  ): Promise<EmailSendResponse> {
+    return {
+      success: false,
+      error: 'SMTP provider is not yet implemented',
+      message: 'SMTP provider is not yet implemented. Please use API method instead.',
+      raw_response: {
+        provider: 'smtp',
+        status: 'not_implemented',
+        message: 'SMTP provider is a placeholder and will be implemented in a future version',
+      },
+    };
+  }
+}

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

@@ -0,0 +1,299 @@
+/**
+ * Zeptomail API provider implementation
+ * Sends emails using the Zeptomail API
+ */
+
+import { EmailProvider, SendEmailOptions, EmailerConfig, EmailSendResponse, ZeptomailEmailData } from '../types';
+import { sanitize_email_header } from '../utils/validation';
+import { log_error, log_info, create_log_entry } from '../utils/logger';
+import DOMPurify from 'isomorphic-dompurify';
+import { DEFAULT_REQUEST_TIMEOUT } from '../utils/constants';
+
+export class ZeptomailProvider implements EmailProvider {
+  /**
+   * Send email using Zeptomail API
+   * @param options - Email send options
+   * @param config - Emailer configuration
+   * @returns Promise with email send response
+   */
+  async send_email(
+    options: SendEmailOptions,
+    config: EmailerConfig
+  ): Promise<EmailSendResponse> {
+    const filename = 'zeptomail_provider.ts';
+    const function_name = 'send_email';
+
+    try {
+      // Validate required configuration
+      if (!config.zeptomail_api_endpoint) {
+        throw new Error('Zeptomail API endpoint is required');
+      }
+      if (!config.zeptomail_api_key) {
+        throw new Error('Zeptomail API key is required');
+      }
+
+      // Prepare recipient array
+      const to_emails = Array.isArray(options.to) ? options.to : [options.to];
+      const cc_emails = options.cc ? (Array.isArray(options.cc) ? options.cc : [options.cc]) : [];
+      const bcc_emails = options.bcc ? (Array.isArray(options.bcc) ? options.bcc : [options.bcc]) : [];
+
+      // Prepare email data according to Zeptomail API format
+      const email_data: ZeptomailEmailData = {
+        from: {
+          address: options.from || config.from_email,
+          name: sanitize_email_header(options.from_name || config.from_name || 'Hazo Notify'),
+        },
+        to: to_emails.map((email) => ({
+          email_address: {
+            address: email,
+          },
+        })),
+        subject: sanitize_email_header(options.subject),
+      };
+
+      // Add content (text and/or html)
+      if (options.content.text) {
+        email_data.textbody = options.content.text;
+      }
+      if (options.content.html) {
+        // Sanitize HTML content to prevent XSS attacks
+        email_data.htmlbody = DOMPurify.sanitize(options.content.html);
+      }
+
+      // Add reply-to if specified
+      if (options.reply_to || config.reply_to_email) {
+        email_data.reply_to = [
+          {
+            address: sanitize_email_header(options.reply_to || config.reply_to_email || ''),
+          },
+        ];
+      }
+
+      // Add CC if specified
+      if (cc_emails.length > 0) {
+        email_data.cc = cc_emails.map((email) => ({
+          email_address: {
+            address: email,
+          },
+        }));
+      }
+
+      // Add BCC if specified
+      if (bcc_emails.length > 0) {
+        email_data.bcc = bcc_emails.map((email) => ({
+          email_address: {
+            address: email,
+          },
+        }));
+      }
+
+      // Add attachments if specified
+      if (options.attachments && options.attachments.length > 0) {
+        email_data.attachments = options.attachments.map((attachment) => ({
+          name: attachment.filename,
+          content: attachment.content,
+          mime_type: attachment.mime_type,
+        }));
+      }
+
+      // Prepare request headers
+      // Handle API key - it may already include the "Zoho-enczapikey" prefix or just be the key
+      const api_key = config.zeptomail_api_key.trim();
+      const auth_header = api_key.startsWith('Zoho-enczapikey')
+        ? api_key
+        : `Zoho-enczapikey ${api_key}`;
+
+      const headers: Record<string, string> = {
+        'Accept': 'application/json',
+        'Content-Type': 'application/json',
+        'Authorization': auth_header,
+      };
+
+      // Log request for debugging (mask API key in logs)
+      log_info(create_log_entry(
+        filename,
+        function_name,
+        'Sending email via Zeptomail API',
+        {
+          endpoint: config.zeptomail_api_endpoint,
+          method: 'POST',
+          headers: {
+            ...headers,
+            Authorization: headers.Authorization ? 'Zoho-enczapikey ***' : undefined, // Mask API key
+          },
+          body: {
+            from: email_data.from,
+            to_count: email_data.to.length,
+            subject: email_data.subject,
+            has_text: !!email_data.textbody,
+            has_html: !!email_data.htmlbody,
+            attachments_count: email_data.attachments?.length || 0,
+          },
+        }
+      ));
+
+      // Set up request timeout
+      const timeout = config.request_timeout || DEFAULT_REQUEST_TIMEOUT;
+      const controller = new AbortController();
+      const timeout_id = setTimeout(() => controller.abort(), timeout);
+
+      try {
+        // Make API request
+        const response = await fetch(config.zeptomail_api_endpoint, {
+          method: 'POST',
+          headers: headers,
+          body: JSON.stringify(email_data),
+          signal: controller.signal,
+        });
+        
+        clearTimeout(timeout_id);
+
+        // Parse response (handle both JSON and text responses)
+        let response_data: Record<string, unknown> | string;
+        const content_type = response.headers.get('content-type') || '';
+        
+        // Get response text first for better error handling
+        const response_text = await response.text();
+        
+        if (content_type.includes('application/json')) {
+          try {
+            response_data = JSON.parse(response_text) as Record<string, unknown>;
+          } catch (e) {
+            response_data = { error: 'Failed to parse JSON response', raw: response_text };
+          }
+        } else {
+          // For HTML/text responses, try to extract error information
+          response_data = { 
+            text: response_text,
+            error: response_text.trim() || 'Unknown error from server'
+          };
+          
+          // Log the full response for debugging
+          log_error(create_log_entry(
+            filename,
+            function_name,
+            'Zeptomail API returned non-JSON response',
+            {
+              status: response.status,
+              statusText: response.statusText,
+              contentType: content_type,
+              body: response_text,
+              headers: Object.fromEntries(response.headers.entries()),
+            }
+          ));
+        }
+
+        const raw_response: Record<string, unknown> = {
+          status: response.status,
+          status_text: response.statusText,
+          headers: Object.fromEntries(response.headers.entries()),
+          body: response_data,
+        };
+
+        // Check if request was successful
+        if (!response.ok) {
+          const response_obj = typeof response_data === 'object' ? response_data : {};
+          const error_message = (response_obj.message as string) || 
+                                (response_obj.error as string) || 
+                                (typeof response_data === 'string' ? response_data : '') ||
+                                `HTTP ${response.status}: ${response.statusText}`;
+          
+          // Enhanced error logging
+          log_error(create_log_entry(
+            filename,
+            function_name,
+            'Zeptomail API error',
+            {
+              status: response.status,
+              error_message,
+              response_body: response_data,
+            }
+          ));
+          
+          const is_production = process.env.NODE_ENV === 'production';
+          
+          return {
+            success: false,
+            error: error_message,
+            raw_response: is_production ? { status: response.status, status_text: response.statusText } : raw_response,
+            message: error_message,
+          };
+        }
+
+        // Return successful response
+        const response_obj = typeof response_data === 'object' ? response_data : {};
+        const data = response_obj.data as Record<string, unknown> | undefined;
+        
+        return {
+          success: true,
+          message_id: (data?.message_id as string) || (response_obj.message_id as string) || undefined,
+          message: 'Email sent successfully',
+          raw_response: raw_response,
+        };
+      } catch (fetch_error: unknown) {
+        clearTimeout(timeout_id);
+        
+        // Handle timeout errors
+        if (fetch_error instanceof Error && fetch_error.name === 'AbortError') {
+          const timeout_error = `Request timeout after ${timeout}ms`;
+          log_error(create_log_entry(
+            filename,
+            function_name,
+            timeout_error,
+            {
+              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: timeout_error,
+            message: timeout_error,
+            raw_response: undefined,
+          };
+        }
+        
+        // Re-throw to be caught by outer catch
+        throw fetch_error;
+      }
+    } catch (error: unknown) {
+      const error_message = error instanceof Error ? error.message : 'Unknown error occurred';
+      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/types.ts

@@ -0,0 +1,119 @@
+/**
+ * Type definitions for the emailer service
+ */
+
+// Emailer module types
+export type EmailerModule = 'zeptoemail_api' | 'smtp' | 'pop3';
+
+// Email content types
+export interface EmailContent {
+  text?: string;
+  html?: string;
+}
+
+// Attachment interface
+export interface EmailAttachment {
+  filename: string;
+  content: string; // Base64 encoded content
+  mime_type: string; // e.g., 'text/plain', 'application/pdf', 'image/png'
+}
+
+// Email send options
+export interface SendEmailOptions {
+  to: string | string[]; // Recipient email address(es)
+  subject: string; // Email subject
+  content: EmailContent; // Email content (text, html, or both)
+  attachments?: EmailAttachment[]; // Optional attachments
+  from?: string; // Override default from email
+  from_name?: string; // Override default from name
+  reply_to?: string; // Reply-to email address
+  cc?: string | string[]; // CC recipient(s)
+  bcc?: string | string[]; // BCC recipient(s)
+}
+
+// Email configuration interface
+export interface EmailerConfig {
+  emailer_module: EmailerModule;
+  // Zeptomail API configuration
+  zeptomail_api_endpoint?: string;
+  zeptomail_api_key?: string;
+  // Common configuration
+  from_email: string;
+  from_name: string;
+  reply_to_email?: string;
+  bounce_email?: string;
+  return_path_email?: string;
+  // Rate limiting configuration
+  rate_limit_requests?: number;
+  rate_limit_window?: number;
+  // Attachment limits
+  max_attachment_size?: number;
+  max_attachments?: number;
+  // Request timeout
+  request_timeout?: number;
+  // Input length limits
+  max_subject_length?: number;
+  max_body_length?: number;
+  // CORS configuration
+  cors_allowed_origins?: string;
+  // SMTP configuration (placeholder)
+  smtp_host?: string;
+  smtp_port?: number;
+  smtp_secure?: boolean;
+  smtp_auth_user?: string;
+  smtp_auth_pass?: string;
+  smtp_timeout?: number;
+  smtp_pool?: boolean;
+  // POP3 configuration (placeholder)
+  pop3_host?: string;
+  pop3_port?: number;
+  pop3_secure?: boolean;
+  pop3_auth_user?: string;
+  pop3_auth_pass?: string;
+  pop3_timeout?: number;
+}
+
+// Email send response
+export interface EmailSendResponse {
+  success: boolean;
+  message_id?: string;
+  message?: string;
+  raw_response?: Record<string, unknown> | string;
+  error?: string;
+}
+
+// Zeptomail API request data structure
+export interface ZeptomailEmailAddress {
+  address: string;
+  name?: string;
+}
+
+export interface ZeptomailEmailAddressObject {
+  email_address: ZeptomailEmailAddress;
+}
+
+export interface ZeptomailAttachment {
+  name: string;
+  content: string;
+  mime_type: string;
+}
+
+export interface ZeptomailEmailData {
+  from: {
+    address: string;
+    name: string;
+  };
+  to: ZeptomailEmailAddressObject[];
+  subject: string;
+  textbody?: string;
+  htmlbody?: string;
+  reply_to?: Array<{ address: string }>;
+  cc?: ZeptomailEmailAddressObject[];
+  bcc?: ZeptomailEmailAddressObject[];
+  attachments?: ZeptomailAttachment[];
+}
+
+// Provider interface
+export interface EmailProvider {
+  send_email(options: SendEmailOptions, config: EmailerConfig): Promise<EmailSendResponse>;
+}

package/src/lib/emailer/utils/constants.ts

@@ -0,0 +1,24 @@
+/**
+ * Constants for emailer service
+ * Centralized constants to avoid magic numbers and strings
+ */
+
+// Rate limiting constants
+export const DEFAULT_RATE_LIMIT_REQUESTS = 10; // requests per minute
+export const DEFAULT_RATE_LIMIT_WINDOW = 60; // seconds
+
+// Attachment limits
+export const DEFAULT_MAX_ATTACHMENT_SIZE = 10 * 1024 * 1024; // 10MB in bytes
+export const DEFAULT_MAX_ATTACHMENTS = 10;
+
+// Request timeout
+export const DEFAULT_REQUEST_TIMEOUT = 30000; // 30 seconds in milliseconds
+
+// Input length limits
+export const MAX_SUBJECT_LENGTH = 255; // characters
+export const MAX_BODY_LENGTH = 1024 * 1024; // 1MB in bytes
+export const MAX_EMAIL_LENGTH = 254; // characters (RFC 5321)
+
+// Valid emailer modules
+export const VALID_EMAILER_MODULES = ['zeptoemail_api', 'smtp', 'pop3'] as const;
+

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

@@ -0,0 +1,9 @@
+/**
+ * Utility functions for emailer service
+ * Centralized exports for validation, logging, and constants
+ */
+
+export * from './constants';
+export * from './validation';
+export * from './logger';
+

package/src/lib/emailer/utils/logger.ts

@@ -0,0 +1,71 @@
+/**
+ * Centralized logging utility for emailer service
+ * Provides consistent JSON logging format across all components
+ */
+
+interface LogEntry {
+  filename: string;
+  function_name: string;
+  line_number?: string | number;
+  message: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Log an error message
+ * @param entry - Log entry object
+ */
+export function log_error(entry: LogEntry): void {
+  console.error(JSON.stringify({
+    level: 'error',
+    timestamp: new Date().toISOString(),
+    ...entry,
+  }));
+}
+
+/**
+ * Log an info message
+ * @param entry - Log entry object
+ */
+export function log_info(entry: LogEntry): void {
+  console.log(JSON.stringify({
+    level: 'info',
+    timestamp: new Date().toISOString(),
+    ...entry,
+  }));
+}
+
+/**
+ * Log a warning message
+ * @param entry - Log entry object
+ */
+export function log_warning(entry: LogEntry): void {
+  console.warn(JSON.stringify({
+    level: 'warning',
+    timestamp: new Date().toISOString(),
+    ...entry,
+  }));
+}
+
+/**
+ * Create a log entry with standard fields
+ * @param filename - Name of the file
+ * @param function_name - Name of the function
+ * @param message - Log message
+ * @param additional_data - Additional data to include
+ * @returns Log entry object
+ */
+export function create_log_entry(
+  filename: string,
+  function_name: string,
+  message: string,
+  additional_data?: Record<string, unknown>
+): LogEntry {
+  return {
+    filename,
+    function_name,
+    message,
+    ...(additional_data || {}),
+  };
+}
+

package/src/lib/emailer/utils/validation.ts

@@ -0,0 +1,84 @@
+/**
+ * Validation utilities for emailer service
+ * Provides email validation, sanitization, and input validation functions
+ */
+
+import { MAX_SUBJECT_LENGTH, MAX_BODY_LENGTH, MAX_EMAIL_LENGTH } from './constants';
+
+/**
+ * Validate email address format
+ * @param email - Email address to validate
+ * @returns boolean indicating if email is valid
+ */
+export function validate_email_address(email: string): boolean {
+  if (!email || typeof email !== 'string') {
+    return false;
+  }
+
+  // RFC 5322 compliant regex (simplified)
+  const email_regex = /^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/;
+  
+  return email_regex.test(email) && email.length <= MAX_EMAIL_LENGTH;
+}
+
+/**
+ * Sanitize email header to prevent injection attacks
+ * Removes newlines, carriage returns, and other control characters
+ * @param value - Header value to sanitize
+ * @returns Sanitized header value
+ */
+export function sanitize_email_header(value: string): string {
+  if (!value || typeof value !== 'string') {
+    return '';
+  }
+  
+  // Remove newlines, carriage returns, and other control characters
+  return value.replace(/[\r\n\t\0\x08\x0B\x0C\x1F]/g, '').trim();
+}
+
+/**
+ * Validate subject length
+ * @param subject - Email subject to validate
+ * @returns boolean indicating if subject is valid
+ */
+export function validate_subject_length(subject: string): boolean {
+  if (!subject || typeof subject !== 'string') {
+    return false;
+  }
+  return subject.length <= MAX_SUBJECT_LENGTH;
+}
+
+/**
+ * Validate body length
+ * @param body - Email body to validate
+ * @returns boolean indicating if body is valid
+ */
+export function validate_body_length(body: string): boolean {
+  if (!body || typeof body !== 'string') {
+    return false;
+  }
+  
+  // Calculate byte length (UTF-8 encoding)
+  const byte_length = Buffer.from(body, 'utf8').length;
+  return byte_length <= MAX_BODY_LENGTH;
+}
+
+/**
+ * Validate attachment size
+ * @param content - Base64 encoded attachment content
+ * @param max_size - Maximum size in bytes
+ * @returns boolean indicating if attachment size is valid
+ */
+export function validate_attachment_size(content: string, max_size: number): boolean {
+  if (!content || typeof content !== 'string') {
+    return false;
+  }
+  
+  try {
+    const size = Buffer.from(content, 'base64').length;
+    return size <= max_size;
+  } catch (error) {
+    return false;
+  }
+}
+

package/src/lib/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Main library exports
+ * Entry point for the hazo_notify library
+ */
+
+export * from './emailer';

package/src/lib/utils.ts

@@ -0,0 +1,6 @@
+import { type ClassValue, clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}