@454creative/easy-email/src/types/global.d.ts

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

/**
 * Global TypeScript declarations for the easy-email library
 */

declare module 'easy-email' {
  // Core exports
  export { default as EmailService } from './services/email.service';
  export { ObservabilityService } from './services/observability.service';
  export { SesService } from './services/ses.service';
  
  // Type exports
  export type {
    EmailOptions,
    EmailResponse,
    EmailRecipient,
    EmailAttachment,
    SmtpConfig,
    SendGridConfig,
    SesConfig,
    EmailProviderConfig,
    EmailProviderType,
  } from './interfaces/email-options.interface';
  
  export type {
    EmailRequest,
    EmailRequestAttachment,
    EmailRequestResponse,
    EmailValidationResult,
  } from './interfaces/email-request.interface';
  
  export type {
    ObservabilityConfig,
    EmailMetrics,
    EmailEvent,
    AuditLog,
  } from './interfaces/observability.interface';
  
  export type {
    SesErrorType,
    SesMetrics,
    SesQuotaData,
    SesStatisticsData,
    SesEmailEvent,
    SesConnectionEvent,
    SesQuotaEvent,
    SesStatisticsEvent,
    SesErrorEvent,
  } from './types/ses.types';
  
  export type {
    SendGridErrorType,
    SendGridMetrics,
    SendGridQuotaData,
    SendGridStatisticsData,
    SendGridEmailEvent,
    SendGridConnectionEvent,
    SendGridQuotaEvent,
    SendGridStatisticsEvent,
    SendGridErrorEvent,
    SendGridApiResponse,
    SendGridEmailContent,
    SendGridPersonalization,
    SendGridMailSettings,
    SendGridTrackingSettings,
  } from './types/sendgrid.types';
  
  // Error exports
  export {
    EmailServiceError,
    ConfigurationError,
    ProviderError,
    ValidationError,
    TemplateError,
    RetryError,
    TimeoutError,
    RateLimitError,
    AuthenticationError,
    NetworkError,
    InvalidEmailError,
    MissingRequiredFieldError,
    InvalidTemplateError,
    TemplateNotFoundError,
    ConnectionError,
    QuotaExceededError,
    SpamDetectionError,
  } from './errors';
  
  // Utility exports
  export { PerformanceMonitor, trackPerformance } from './utils/performance';
  export { validateEmail, validateEmailRequest } from './utils/email-validator';
  export { renderString, templateExists } from './utils/template-engine';
  
  // Configuration exports
  export { EmailConfigBuilder } from './config/default-config';
  export { ProviderFactory } from './config/provider-factory';
  export { ConfigValidator } from './config/validator';
  
  // Constants exports
  export { EMAIL_CONSTANTS, OBSERVABILITY_CONSTANTS } from './config/constants';
  export { SES_ERROR_TYPES, SES_ERROR_CODES, SES_DEFAULT_CONFIG } from './types/ses.types';
  export { SENDGRID_ERROR_TYPES, SENDGRID_ERROR_CODES, SENDGRID_DEFAULT_CONFIG } from './types/sendgrid.types';
  
  // Version exports
  export { VERSION, LIBRARY_INFO, getLibraryInfo, isVersionCompatible } from './config/version';
  
  // Default export
  export { default } from './services/email.service';
}

// Module augmentation for better type inference
declare module '@aws-sdk/client-ses' {
  export class SESClient {
    constructor(config: any);
    send<T>(command: T): Promise<any>;
    destroy(): void;
  }
  
  export interface SendEmailCommandInput {
    Source: string;
    Destination: {
      ToAddresses?: string[];
      CcAddresses?: string[];
      BccAddresses?: string[];
    };
    Message: {
      Subject: {
        Data: string;
        Charset?: string;
      };
      Body: {
        Text?: {
          Data: string;
          Charset?: string;
        };
        Html?: {
          Data: string;
          Charset?: string;
        };
      };
    };
    ReplyToAddresses?: string[];
    ReturnPath?: string;
    SourceArn?: string;
    ReturnPathArn?: string;
    Tags?: Array<{
      Name: string;
      Value: string;
    }>;
    ConfigurationSetName?: string;
  }
  
  export interface SendEmailCommandOutput {
    MessageId: string;
    $metadata: {
      httpStatusCode: number;
      requestId: string;
      cfId?: string;
      extendedRequestId?: string;
    };
  }
  
  export class SendEmailCommand {
    constructor(input: SendEmailCommandInput);
  }
  
  export interface GetSendQuotaCommandInput {}
  
  export interface GetSendQuotaCommandOutput {
    Max24HourSend: number;
    SentLast24Hours: number;
    MaxSendRate: number;
  }
  
  export class GetSendQuotaCommand {
    constructor(input: GetSendQuotaCommandInput);
  }
  
  export interface GetSendStatisticsCommandInput {}
  
  export interface GetSendStatisticsCommandOutput {
    SendDataPoints: Array<{
      Timestamp: Date;
      DeliveryAttempts: number;
      Bounces: number;
      Complaints: number;
      Rejects: number;
    }>;
  }
  
  export class GetSendStatisticsCommand {
    constructor(input: GetSendStatisticsCommandInput);
  }
}

// Module augmentation for SendGrid
declare module '@sendgrid/mail' {
  export interface MailDataRequired {
    to: string | string[] | { email: string; name?: string }[];
    from: string | { email: string; name?: string };
    subject: string;
    text?: string;
    html?: string;
  }
  
  export interface MailDataOptional {
    cc?: string | string[] | { email: string; name?: string }[];
    bcc?: string | string[] | { email: string; name?: string }[];
    replyTo?: string | { email: string; name?: string };
    attachments?: Array<{
      content: string | Buffer;
      filename: string;
      type?: string;
      disposition?: string;
      contentId?: string;
    }>;
    templateId?: string;
    dynamicTemplateData?: Record<string, any>;
    personalizations?: Array<{
      to: Array<{ email: string; name?: string }>;
      cc?: Array<{ email: string; name?: string }>;
      bcc?: Array<{ email: string; name?: string }>;
      subject?: string;
      headers?: Record<string, string>;
      substitutions?: Record<string, string>;
      dynamicTemplateData?: Record<string, any>;
      customArgs?: Record<string, string>;
      sendAt?: number;
    }>;
    mailSettings?: {
      bypassListManagement?: boolean;
      bypassSpamManagement?: boolean;
      bypassBounceManagement?: boolean;
      bypassUnsubscribeManagement?: boolean;
      footer?: {
        enable?: boolean;
        text?: string;
        html?: string;
      };
      sandboxMode?: {
        enable?: boolean;
      };
      spamCheck?: {
        enable?: boolean;
        threshold?: number;
        postToUrl?: string;
      };
    };
    trackingSettings?: {
      clickTracking?: {
        enable?: boolean;
        enableText?: boolean;
      };
      openTracking?: {
        enable?: boolean;
        substitutionTag?: string;
      };
      subscriptionTracking?: {
        enable?: boolean;
        text?: string;
        html?: string;
        substitutionTag?: string;
      };
      ganalytics?: {
        enable?: boolean;
        utmSource?: string;
        utmMedium?: string;
        utmTerm?: string;
        utmContent?: string;
        utmCampaign?: string;
      };
    };
  }
  
  export type MailData = MailDataRequired & MailDataOptional;
  
  export interface ResponseError {
    message: string;
    code: number;
    response: {
      headers: Record<string, string>;
      body: any;
    };
  }
  
  export interface Response {
    statusCode: number;
    headers: Record<string, string>;
    body: any;
  }
  
  export interface MailService {
    send(data: MailData): Promise<[Response, {}]>;
    sendMultiple(data: MailData): Promise<[Response, {}]>;
    setApiKey(apiKey: string): void;
    setSubstitutionWrappers(left: string, right: string): void;
    setDefaultHeader(key: string, value: string): void;
    setDefaultHeaders(headers: Record<string, string>): void;
    addHeader(key: string, value: string): void;
    addHeaders(headers: Record<string, string>): void;
    addFilter(filter: string, setting: string, value: string | number | boolean): void;
    addFilters(filters: Record<string, Record<string, string | number | boolean>>): void;
    addSection(section: string, value: string): void;
    addSections(sections: Record<string, string>): void;
    addCategory(category: string): void;
  }
  
  const mail: MailService;
  export default mail;
}