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

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

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

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

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

/**
 * SendGrid Error Types
 */
export type SendGridErrorType = 
  | 'Unauthorized'
  | 'Forbidden'
  | 'BadRequest'
  | 'NotFound'
  | 'TooManyRequests'
  | 'InternalServerError'
  | 'ServiceUnavailable'
  | 'GatewayTimeout'
  | 'InvalidEmail'
  | 'InvalidSender'
  | 'InvalidRecipient'
  | 'InvalidTemplate'
  | 'InvalidAttachment'
  | 'RateLimitExceeded'
  | 'QuotaExceeded'
  | 'NetworkError'
  | 'TimeoutError';

/**
 * SendGrid Error Types Array
 */
export const SENDGRID_ERROR_TYPES: SendGridErrorType[] = [
  'Unauthorized',
  'Forbidden',
  'BadRequest',
  'NotFound',
  'TooManyRequests',
  'InternalServerError',
  'ServiceUnavailable',
  'GatewayTimeout',
  'InvalidEmail',
  'InvalidSender',
  'InvalidRecipient',
  'InvalidTemplate',
  'InvalidAttachment',
  'RateLimitExceeded',
  'QuotaExceeded',
  'NetworkError',
  'TimeoutError',
];

/**
 * SendGrid Metrics Interface
 */
export interface SendGridMetrics {
  quotaUsage: number;
  deliveryRate: number;
  bounceRate: number;
  spamReportRate: number;
  lastQuotaCheck?: string;
}

/**
 * SendGrid Quota Data Interface
 */
export interface SendGridQuotaData {
  dailyQuota: number;
  dailyUsed: number;
  monthlyQuota: number;
  monthlyUsed: number;
  remainingQuota: number;
}

/**
 * SendGrid Statistics Data Interface
 */
export interface SendGridStatisticsData {
  delivered: number;
  bounces: number;
  spamReports: number;
  opens: number;
  clicks: number;
  unsubscribes: number;
}

/**
 * SendGrid Email Event Interface
 */
export interface SendGridEmailEvent {
  id: string;
  timestamp: string;
  type: 'email_sent' | 'email_failed';
  provider: 'sendgrid';
  recipient?: string;
  subject?: string;
  messageId?: string;
  duration?: number;
  error?: {
    message: string;
    code: SendGridErrorType;
    details?: {
      sendgridErrorType: SendGridErrorType;
      originalError: any;
      statusCode?: number;
    };
  };
  metadata?: Record<string, any>;
}

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

/**
 * SendGrid Quota Event Interface
 */
export interface SendGridQuotaEvent {
  id: string;
  timestamp: string;
  type: 'connection_verified';
  provider: 'sendgrid';
  metadata: {
    quotaUsage: number;
    dailyQuota: number;
    dailyUsed: number;
    monthlyQuota: number;
    monthlyUsed: number;
    remainingQuota: number;
  };
}

/**
 * SendGrid Statistics Event Interface
 */
export interface SendGridStatisticsEvent {
  id: string;
  timestamp: string;
  type: 'connection_verified';
  provider: 'sendgrid';
  metadata: {
    deliveryRate: number;
    bounceRate: number;
    spamReportRate: number;
    openRate: number;
    clickRate: number;
    unsubscribeRate: number;
    delivered: number;
    bounces: number;
    spamReports: number;
    opens: number;
    clicks: number;
    unsubscribes: number;
  };
}

/**
 * SendGrid Error Event Interface
 */
export interface SendGridErrorEvent {
  id: string;
  timestamp: string;
  type: 'email_failed';
  provider: 'sendgrid';
  duration: number;
  error: {
    message: string;
    code: SendGridErrorType;
    details: {
      sendgridErrorType: SendGridErrorType;
      originalError: any;
      statusCode?: number;
    };
  };
  metadata: {
    errorType: SendGridErrorType;
    duration: number;
    statusCode?: number;
  };
}

/**
 * SendGrid Error Codes
 */
export const SENDGRID_ERROR_CODES = {
  UNAUTHORIZED: 'Unauthorized',
  FORBIDDEN: 'Forbidden',
  BAD_REQUEST: 'BadRequest',
  NOT_FOUND: 'NotFound',
  TOO_MANY_REQUESTS: 'TooManyRequests',
  INTERNAL_SERVER_ERROR: 'InternalServerError',
  SERVICE_UNAVAILABLE: 'ServiceUnavailable',
  GATEWAY_TIMEOUT: 'GatewayTimeout',
  INVALID_EMAIL: 'InvalidEmail',
  INVALID_SENDER: 'InvalidSender',
  INVALID_RECIPIENT: 'InvalidRecipient',
  INVALID_TEMPLATE: 'InvalidTemplate',
  INVALID_ATTACHMENT: 'InvalidAttachment',
  RATE_LIMIT_EXCEEDED: 'RateLimitExceeded',
  QUOTA_EXCEEDED: 'QuotaExceeded',
  NETWORK_ERROR: 'NetworkError',
  TIMEOUT_ERROR: 'TimeoutError',
} as const;

/**
 * SendGrid Default Configuration
 */
export const SENDGRID_DEFAULT_CONFIG: SendGridConfig = {
  apiKey: 'SG.your-api-key-here',
};

/**
 * SendGrid API Response Interface
 */
export interface SendGridApiResponse {
  messageId: string;
  statusCode: number;
  headers: Record<string, string>;
  body?: any;
}

/**
 * SendGrid Email Content Interface
 */
export interface SendGridEmailContent {
  type: 'text/plain' | 'text/html';
  value: string;
}

/**
 * SendGrid Personalization Interface
 */
export interface SendGridPersonalization {
  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;
}

/**
 * SendGrid Mail Settings Interface
 */
export interface SendGridMailSettings {
  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;
  };
}

/**
 * SendGrid Tracking Settings Interface
 */
export interface SendGridTrackingSettings {
  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;
  };
}