@454creative/easy-email/src/types/ses.types.ts

A framework-agnostic email service library for Node.js with observability and monitoring

/**
 * SES-specific TypeScript types and constants
 */

import { SesConfig } from '../interfaces/email-options.interface';

// Re-export SesConfig to avoid circular dependencies
export type { SesConfig };

/**
 * SES Error Types
 */
export type SesErrorType = 
  | 'MessageRejected'
  | 'MailFromDomainNotVerified'
  | 'ConfigurationSetDoesNotExist'
  | 'TemplateDoesNotExist'
  | 'AccountSendingPaused'
  | 'SendingPaused'
  | 'MessageTooLarge'
  | 'InvalidParameterValue'
  | 'ValidationError'
  | 'ThrottlingException'
  | 'ServiceUnavailable'
  | 'InternalError'
  | 'NetworkError'
  | 'TimeoutError';

/**
 * SES Error Types Array
 */
export const SES_ERROR_TYPES: SesErrorType[] = [
  'MessageRejected',
  'MailFromDomainNotVerified',
  'ConfigurationSetDoesNotExist',
  'TemplateDoesNotExist',
  'AccountSendingPaused',
  'SendingPaused',
  'MessageTooLarge',
  'InvalidParameterValue',
  'ValidationError',
  'ThrottlingException',
  'ServiceUnavailable',
  'InternalError',
  'NetworkError',
  'TimeoutError',
];

/**
 * SES Metrics Interface
 */
export interface SesMetrics {
  quotaUsage: number;
  bounceRate: number;
  complaintRate: number;
  deliveryRate: number;
  lastQuotaCheck?: string;
}

/**
 * SES Quota Data Interface
 */
export interface SesQuotaData {
  max24HourSend: number;
  sentLast24Hours: number;
  maxSendRate: number;
}

/**
 * SES Statistics Data Interface
 */
export interface SesStatisticsData {
  deliveryAttempts: number;
  bounces: number;
  complaints: number;
  rejects: number;
}

/**
 * SES Email Event Interface
 */
export interface SesEmailEvent {
  id: string;
  timestamp: string;
  type: 'email_sent' | 'email_failed';
  provider: 'ses';
  recipient?: string;
  subject?: string;
  messageId?: string;
  duration?: number;
  error?: {
    message: string;
    code: SesErrorType;
    details?: {
      sesErrorType: SesErrorType;
      originalError: any;
    };
  };
  metadata?: Record<string, any>;
}

/**
 * SES Connection Event Interface
 */
export interface SesConnectionEvent {
  id: string;
  timestamp: string;
  type: 'connection_verified' | 'connection_failed';
  provider: 'ses';
  duration?: number;
  error?: {
    message: string;
    code: string;
  };
}

/**
 * SES Quota Event Interface
 */
export interface SesQuotaEvent {
  id: string;
  timestamp: string;
  type: 'connection_verified';
  provider: 'ses';
  metadata: {
    quotaUsage: number;
    max24HourSend: number;
    sentLast24Hours: number;
    maxSendRate: number;
  };
}

/**
 * SES Statistics Event Interface
 */
export interface SesStatisticsEvent {
  id: string;
  timestamp: string;
  type: 'connection_verified';
  provider: 'ses';
  metadata: {
    deliveryRate: number;
    bounceRate: number;
    complaintRate: number;
    deliveryAttempts: number;
    bounces: number;
    complaints: number;
    rejects: number;
  };
}

/**
 * SES Error Event Interface
 */
export interface SesErrorEvent {
  id: string;
  timestamp: string;
  type: 'email_failed';
  provider: 'ses';
  duration: number;
  error: {
    message: string;
    code: SesErrorType;
    details: {
      sesErrorType: SesErrorType;
      originalError: any;
    };
  };
  metadata: {
    errorType: SesErrorType;
    duration: number;
  };
}

/**
 * SES Error Codes
 */
export const SES_ERROR_CODES = {
  MESSAGE_REJECTED: 'MessageRejected',
  MAIL_FROM_DOMAIN_NOT_VERIFIED: 'MailFromDomainNotVerified',
  CONFIGURATION_SET_DOES_NOT_EXIST: 'ConfigurationSetDoesNotExist',
  TEMPLATE_DOES_NOT_EXIST: 'TemplateDoesNotExist',
  ACCOUNT_SENDING_PAUSED: 'AccountSendingPaused',
  SENDING_PAUSED: 'SendingPaused',
  MESSAGE_TOO_LARGE: 'MessageTooLarge',
  INVALID_PARAMETER_VALUE: 'InvalidParameterValue',
  VALIDATION_ERROR: 'ValidationError',
  THROTTLING_EXCEPTION: 'ThrottlingException',
  SERVICE_UNAVAILABLE: 'ServiceUnavailable',
  INTERNAL_ERROR: 'InternalError',
  NETWORK_ERROR: 'NetworkError',
  TIMEOUT_ERROR: 'TimeoutError',
} as const;

/**
 * SES Default Configuration
 */
export const SES_DEFAULT_CONFIG: SesConfig = {
  region: 'us-west-2',
  apiVersion: '2010-12-01',
  maxRetries: 3,
  httpOptions: {
    timeout: 10000,
    connectTimeout: 5000,
  },
};