dcrouter/ts_interfaces/requests/email-ops.ts

import * as plugins from '../plugins.js';
import * as authInterfaces from '../data/auth.js';

// ============================================================================
// Email Queue Item Interface (matches backend IQueueItem)
// ============================================================================
export type TEmailQueueStatus = 'pending' | 'processing' | 'delivered' | 'failed' | 'deferred';

export interface IEmailQueueItem {
  id: string;
  processingMode: 'forward' | 'mta' | 'process';
  status: TEmailQueueStatus;
  attempts: number;
  nextAttempt: number; // timestamp
  lastError?: string;
  createdAt: number; // timestamp
  updatedAt: number; // timestamp
  deliveredAt?: number; // timestamp
  // Email details extracted from processingResult
  from?: string;
  to?: string[];
  subject?: string;
}

// ============================================================================
// Bounce Record Interface (matches backend BounceRecord)
// ============================================================================
export type TBounceType =
  | 'invalid_recipient'
  | 'domain_not_found'
  | 'mailbox_full'
  | 'mailbox_inactive'
  | 'blocked'
  | 'spam_related'
  | 'policy_related'
  | 'server_unavailable'
  | 'temporary_failure'
  | 'quota_exceeded'
  | 'network_error'
  | 'timeout'
  | 'auto_response'
  | 'challenge_response'
  | 'unknown';

export type TBounceCategory = 'hard' | 'soft' | 'auto_response' | 'unknown';

export interface IBounceRecord {
  id: string;
  originalEmailId?: string;
  recipient: string;
  sender: string;
  domain: string;
  subject?: string;
  bounceType: TBounceType;
  bounceCategory: TBounceCategory;
  timestamp: number;
  smtpResponse?: string;
  diagnosticCode?: string;
  statusCode?: string;
  processed: boolean;
  retryCount?: number;
  nextRetryTime?: number;
}

// ============================================================================
// Security Incident Interface (matches backend ISecurityEvent)
// ============================================================================
export type TSecurityLogLevel = 'info' | 'warn' | 'error' | 'critical';

export type TSecurityEventType =
  | 'authentication'
  | 'access_control'
  | 'email_validation'
  | 'email_processing'
  | 'email_forwarding'
  | 'email_delivery'
  | 'dkim'
  | 'spf'
  | 'dmarc'
  | 'rate_limit'
  | 'rate_limiting'
  | 'spam'
  | 'malware'
  | 'connection'
  | 'data_exposure'
  | 'configuration'
  | 'ip_reputation'
  | 'rejected_connection';

export interface ISecurityIncident {
  timestamp: number;
  level: TSecurityLogLevel;
  type: TSecurityEventType;
  message: string;
  details?: any;
  ipAddress?: string;
  userId?: string;
  sessionId?: string;
  emailId?: string;
  domain?: string;
  action?: string;
  result?: string;
  success?: boolean;
}

// ============================================================================
// Get Queued Emails Request
// ============================================================================
export interface IReq_GetQueuedEmails extends plugins.typedrequestInterfaces.implementsTR<
  plugins.typedrequestInterfaces.ITypedRequest,
  IReq_GetQueuedEmails
> {
  method: 'getQueuedEmails';
  request: {
    identity?: authInterfaces.IIdentity;
    status?: TEmailQueueStatus;
    limit?: number;
    offset?: number;
  };
  response: {
    items: IEmailQueueItem[];
    total: number;
  };
}

// ============================================================================
// Get Sent Emails Request
// ============================================================================
export interface IReq_GetSentEmails extends plugins.typedrequestInterfaces.implementsTR<
  plugins.typedrequestInterfaces.ITypedRequest,
  IReq_GetSentEmails
> {
  method: 'getSentEmails';
  request: {
    identity?: authInterfaces.IIdentity;
    limit?: number;
    offset?: number;
  };
  response: {
    items: IEmailQueueItem[];
    total: number;
  };
}

// ============================================================================
// Get Failed Emails Request
// ============================================================================
export interface IReq_GetFailedEmails extends plugins.typedrequestInterfaces.implementsTR<
  plugins.typedrequestInterfaces.ITypedRequest,
  IReq_GetFailedEmails
> {
  method: 'getFailedEmails';
  request: {
    identity?: authInterfaces.IIdentity;
    limit?: number;
    offset?: number;
  };
  response: {
    items: IEmailQueueItem[];
    total: number;
  };
}

// ============================================================================
// Resend Failed Email Request
// ============================================================================
export interface IReq_ResendEmail extends plugins.typedrequestInterfaces.implementsTR<
  plugins.typedrequestInterfaces.ITypedRequest,
  IReq_ResendEmail
> {
  method: 'resendEmail';
  request: {
    identity?: authInterfaces.IIdentity;
    emailId: string;
  };
  response: {
    success: boolean;
    newQueueId?: string;
    error?: string;
  };
}

// ============================================================================
// Get Security Incidents Request
// ============================================================================
export interface IReq_GetSecurityIncidents extends plugins.typedrequestInterfaces.implementsTR<
  plugins.typedrequestInterfaces.ITypedRequest,
  IReq_GetSecurityIncidents
> {
  method: 'getSecurityIncidents';
  request: {
    identity?: authInterfaces.IIdentity;
    type?: TSecurityEventType;
    level?: TSecurityLogLevel;
    limit?: number;
  };
  response: {
    incidents: ISecurityIncident[];
    total: number;
  };
}

// ============================================================================
// Get Bounce Records Request
// ============================================================================
export interface IReq_GetBounceRecords extends plugins.typedrequestInterfaces.implementsTR<
  plugins.typedrequestInterfaces.ITypedRequest,
  IReq_GetBounceRecords
> {
  method: 'getBounceRecords';
  request: {
    identity?: authInterfaces.IIdentity;
    limit?: number;
    offset?: number;
  };
  response: {
    records: IBounceRecord[];
    suppressionList: string[];
    total: number;
  };
}

// ============================================================================
// Remove from Suppression List Request
// ============================================================================
export interface IReq_RemoveFromSuppressionList extends plugins.typedrequestInterfaces.implementsTR<
  plugins.typedrequestInterfaces.ITypedRequest,
  IReq_RemoveFromSuppressionList
> {
  method: 'removeFromSuppressionList';
  request: {
    identity?: authInterfaces.IIdentity;
    email: string;
  };
  response: {
    success: boolean;
    error?: string;
  };
}