@api-buddy/sendgrid/src/types.ts

API Buddy integration for SendGrid - Email delivery service for transactional and marketing emails

import { MailDataRequired } from '@sendgrid/mail';

/**
 * Configuration options for the SendGrid client
 */
export interface SendGridConfig {
  /**
   * Your SendGrid API key
   */
  apiKey?: string;
  
  /**
   * Default "from" email address
   */
  defaultFrom?: string;
  
  /**
   * Default "reply to" email address
   */
  defaultReplyTo?: string;
  
  /**
   * Default mail settings for all emails
   */
  mailSettings?: MailSettings;
  
  /**
   * Default tracking settings for all emails
   */
  trackingSettings?: TrackingSettings;
  
  /**
   * Default ASM (Advanced Suppression Manager) settings
   */
  asm?: ASMOptions;
  
  /**
   * Default IP pool name
   */
  ipPoolName?: string;
}

/**
 * Options for sending an email
 */
export interface EmailOptions {
  /**
   * Recipient email address or array of email addresses
   */
  to: string | string[];
  
  /**
   * Sender email address
   */
  from?: string;
  
  /**
   * Email subject
   */
  subject: string;
  
  /**
   * Plain text content
   */
  text?: string;
  
  /**
   * HTML content
   */
  html?: string;
  
  /**
   * SendGrid template ID
   */
  templateId?: string;
  
  /**
   * Dynamic template data
   */
  dynamicTemplateData?: Record<string, any>;
  
  /**
   * Email attachments
   */
  attachments?: Attachment[];
  
  /**
   * Email categories for tracking
   */
  categories?: string[];
  
  /**
   * Custom arguments
   */
  customArgs?: Record<string, string>;
  
  /**
   * Custom headers
   */
  headers?: Record<string, string>;
  
  /**
   * Mail settings
   */
  mailSettings?: MailSettings;
  
  /**
   * Tracking settings
   */
  trackingSettings?: TrackingSettings;
  
  /**
   * Reply-to email address
   */
  replyTo?: string;
  
  /**
   * Send at timestamp (Unix timestamp)
   */
  sendAt?: number;
  
  /**
   * Batch ID for scheduling
   */
  batchId?: string;
  
  /**
   * ASM (Advanced Suppression Manager) settings
   */
  asm?: ASMOptions;
  
  /**
   * IP pool name
   */
  ipPoolName?: string;
}

/**
 * Email attachment
 */
export interface Attachment {
  content: string | Buffer;
  filename: string;
  type?: string;
  disposition?: string;
  contentId?: string;
}

/**
 * Personalization for sending to multiple recipients with different data
 */
export interface Personalization {
  to: { email: string; name?: string }[];
  cc?: { email: string; name?: string }[];
  bcc?: { email: string; name?: string }[];
  subject?: string;
  headers?: Record<string, string>;
  substitutions?: Record<string, string>;
  customArgs?: Record<string, string>;
  sendAt?: number;
  dynamicTemplateData?: Record<string, any>;
}

/**
 * Mail settings
 */
export interface MailSettings {
  bcc?: BCCSettings;
  bypassListManagement?: BypassListManagement;
  bypassSpamManagement?: { enable: boolean };
  bypassBounceManagement?: { enable: boolean };
  bypassUnsubscribeManagement?: { enable: boolean };
  footer?: FooterSettings;
  sandboxMode?: {
    /**
     * Whether to enable sandbox mode
     */
    enable: boolean;
  };
  spamCheck?: {
    enable: boolean;
    threshold?: number;
    post_to_url?: string;
  };
}

/**
 * BCC settings
 */
export interface BCCSettings {
  enable?: boolean;
  email?: string;
}

/**
 * Bypass list management settings
 */
export interface BypassListManagement {
  enable: boolean;
}

/**
 * Footer settings
 */
export interface FooterSettings {
  enable?: boolean;
  text?: string;
  html?: string;
}

/**
 * Tracking settings
 */
export interface TrackingSettings {
  clickTracking?: ClickTracking;
  openTracking?: OpenTracking;
  subscriptionTracking?: SubscriptionTracking;
  ganalytics?: Ganalytics;
}

/**
 * Click tracking settings
 */
export interface ClickTracking {
  enable?: boolean;
  enableText?: boolean;
}

/**
 * Open tracking settings
 */
export interface OpenTracking {
  enable?: boolean;
  substitutionTag?: string;
}

/**
 * Subscription tracking settings
 */
export interface SubscriptionTracking {
  enable?: boolean;
  text?: string;
  html?: string;
  substitutionTag?: string;
}

/**
 * Google Analytics settings
 */
export interface Ganalytics {
  enable?: boolean;
  utmSource?: string;
  utmMedium?: string;
  utmTerm?: string;
  utmContent?: string;
  utmCampaign?: string;
}

/**
 * ASM (Advanced Suppression Manager) settings
 */
export interface ASMOptions {
  groupId: number;
  groupsToDisplay?: number[];
  groupsToDisplayOnEmail?: boolean;
}

/**
 * Response from SendGrid API
 */
export interface SendGridResponse {
  success: boolean;
  statusCode: number;
  headers: Record<string, string>;
  body: any;
}

/**
 * Response for multiple emails
 */
export interface BatchSendGridResponse {
  success: boolean;
  responses: Array<{
    statusCode: number;
    headers: Record<string, string>;
    body: any;
  }>;
}

/**
 * Error response from SendGrid
 */
export interface SendGridError extends Error {
  code: number;
  response?: {
    headers: Record<string, string>;
    body: {
      errors: Array<{
        message: string;
        field?: string;
        help?: string;
      }>;
    };
  };
}