xpeditis2.0/apps/backend/src/domain/ports/out/email.port.ts

/**
 * Email Port
 *
 * Defines the interface for email sending operations.
 * This is a secondary port (output port) in hexagonal architecture.
 */

export const EMAIL_PORT = 'EmailPort';

export interface EmailAttachment {
  filename: string;
  content: Buffer | string;
  contentType?: string;
}

export interface EmailOptions {
  to: string | string[];
  from?: string;
  cc?: string | string[];
  bcc?: string | string[];
  replyTo?: string;
  subject: string;
  html?: string;
  text?: string;
  attachments?: EmailAttachment[];
}

/** Message du formulaire de contact, adressé à l'équipe. */
export interface ContactMessageEmail {
  firstName: string;
  lastName: string;
  email: string;
  company?: string;
  phone?: string;
  /** Libellé lisible du sujet choisi. */
  subjectLabel: string;
  message: string;
}

/** Virement déclaré par un client, à valider par un administrateur. */
export interface BankTransferToValidateEmail {
  bookingNumber: string;
  carrierName: string;
  routeDescription: string;
  /** Montant déjà formaté (ex. « 150,00 € »). */
  commissionAmount: string;
}

export interface EmailPort {
  /**
   * Send the contact form message to the team (reply-to = sender)
   */
  sendContactMessage(to: string, data: ContactMessageEmail): Promise<void>;

  /**
   * Alert admins that a declared bank transfer awaits validation
   */
  sendBankTransferToValidate(to: string[], data: BankTransferToValidateEmail): Promise<void>;

  /**
   * Send the SMTP diagnostic email from the admin panel
   */
  sendSmtpTest(to: string, requestedBy: string): Promise<void>;

  /**
   * Send an email
   */
  send(options: EmailOptions): Promise<void>;

  /**
   * Send booking confirmation email
   */
  sendBookingConfirmation(
    email: string,
    bookingNumber: string,
    bookingDetails: any,
    pdfAttachment?: Buffer
  ): Promise<void>;

  /**
   * Send email verification email
   */
  sendVerificationEmail(email: string, token: string): Promise<void>;

  /**
   * Send password reset email
   */
  sendPasswordResetEmail(email: string, token: string): Promise<void>;

  /**
   * Send welcome email
   */
  sendWelcomeEmail(email: string, firstName: string): Promise<void>;

  /**
   * Send user invitation email (legacy - with temp password)
   */
  sendUserInvitation(
    email: string,
    organizationName: string,
    inviterName: string,
    tempPassword: string
  ): Promise<void>;

  /**
   * Send invitation email with registration link (token-based)
   */
  sendInvitationWithToken(
    email: string,
    firstName: string,
    lastName: string,
    organizationName: string,
    inviterName: string,
    invitationLink: string,
    expiresAt: Date
  ): Promise<void>;

  /**
   * Send CSV booking request email to carrier
   */
  sendCsvBookingRequest(
    carrierEmail: string,
    bookingDetails: {
      bookingId: string;
      bookingNumber?: string;
      documentPassword?: string;
      origin: string;
      destination: string;
      volumeCBM: number;
      weightKG: number;
      palletCount: number;
      priceUSD: number;
      priceEUR: number;
      primaryCurrency: string;
      transitDays: number;
      containerType: string;
      documents: Array<{
        type: string;
        fileName: string;
      }>;
      confirmationToken: string;
      notes?: string;
    }
  ): Promise<void>;

  /**
   * Send carrier account creation email with temporary password
   */
  sendCarrierAccountCreated(
    email: string,
    carrierName: string,
    temporaryPassword: string
  ): Promise<void>;

  /**
   * Send carrier password reset email with temporary password
   */
  sendCarrierPasswordReset(
    email: string,
    carrierName: string,
    temporaryPassword: string
  ): Promise<void>;

  /**
   * Send document access email to carrier after booking acceptance
   */
  sendDocumentAccessEmail(
    carrierEmail: string,
    data: {
      carrierName: string;
      bookingId: string;
      bookingNumber?: string;
      documentPassword?: string;
      origin: string;
      destination: string;
      volumeCBM: number;
      weightKG: number;
      documentCount: number;
      confirmationToken: string;
    }
  ): Promise<void>;

  /**
   * Send notification to carrier when new documents are added
   */
  sendNewDocumentsNotification(
    carrierEmail: string,
    data: {
      carrierName: string;
      bookingId: string;
      origin: string;
      destination: string;
      newDocumentsCount: number;
      totalDocumentsCount: number;
      confirmationToken: string;
    }
  ): Promise<void>;
}