dcrouter/ts_interfaces/requests/email-domains.ts

import * as plugins from '../plugins.js';
import type * as authInterfaces from '../data/auth.js';
import type { IEmailDomain, IEmailDnsRecord } from '../data/email-domain.js';

// ============================================================================
// Email Domain Endpoints
// ============================================================================

/**
 * List all email domains.
 */
export interface IReq_GetEmailDomains extends plugins.typedrequestInterfaces.implementsTR<
  plugins.typedrequestInterfaces.ITypedRequest,
  IReq_GetEmailDomains
> {
  method: 'getEmailDomains';
  request: {
    identity?: authInterfaces.IIdentity;
    apiToken?: string;
  };
  response: {
    domains: IEmailDomain[];
  };
}

/**
 * Get a single email domain by id.
 */
export interface IReq_GetEmailDomain extends plugins.typedrequestInterfaces.implementsTR<
  plugins.typedrequestInterfaces.ITypedRequest,
  IReq_GetEmailDomain
> {
  method: 'getEmailDomain';
  request: {
    identity?: authInterfaces.IIdentity;
    apiToken?: string;
    id: string;
  };
  response: {
    domain: IEmailDomain | null;
  };
}

/**
 * Create an email domain. Links to an existing dcrouter DNS domain.
 * Generates DKIM keys and computes the required DNS records.
 */
export interface IReq_CreateEmailDomain extends plugins.typedrequestInterfaces.implementsTR<
  plugins.typedrequestInterfaces.ITypedRequest,
  IReq_CreateEmailDomain
> {
  method: 'createEmailDomain';
  request: {
    identity?: authInterfaces.IIdentity;
    apiToken?: string;
    /** ID of the existing dcrouter DNS domain to link to. */
    linkedDomainId: string;
    /** DKIM selector (default: 'default'). */
    dkimSelector?: string;
    /** RSA key size (default: 2048). */
    dkimKeySize?: number;
    /** Enable automatic key rotation (default: false). */
    rotateKeys?: boolean;
    /** Days between rotations (default: 90). */
    rotationIntervalDays?: number;
  };
  response: {
    success: boolean;
    domain?: IEmailDomain;
    message?: string;
  };
}

/**
 * Update an email domain's configuration.
 */
export interface IReq_UpdateEmailDomain extends plugins.typedrequestInterfaces.implementsTR<
  plugins.typedrequestInterfaces.ITypedRequest,
  IReq_UpdateEmailDomain
> {
  method: 'updateEmailDomain';
  request: {
    identity?: authInterfaces.IIdentity;
    apiToken?: string;
    id: string;
    rotateKeys?: boolean;
    rotationIntervalDays?: number;
    rateLimits?: IEmailDomain['rateLimits'];
  };
  response: {
    success: boolean;
    message?: string;
  };
}

/**
 * Delete an email domain.
 */
export interface IReq_DeleteEmailDomain extends plugins.typedrequestInterfaces.implementsTR<
  plugins.typedrequestInterfaces.ITypedRequest,
  IReq_DeleteEmailDomain
> {
  method: 'deleteEmailDomain';
  request: {
    identity?: authInterfaces.IIdentity;
    apiToken?: string;
    id: string;
  };
  response: {
    success: boolean;
    message?: string;
  };
}

/**
 * Trigger DNS validation for an email domain.
 * Performs live lookups for MX, SPF, DKIM, and DMARC records.
 */
export interface IReq_ValidateEmailDomain extends plugins.typedrequestInterfaces.implementsTR<
  plugins.typedrequestInterfaces.ITypedRequest,
  IReq_ValidateEmailDomain
> {
  method: 'validateEmailDomain';
  request: {
    identity?: authInterfaces.IIdentity;
    apiToken?: string;
    id: string;
  };
  response: {
    success: boolean;
    domain?: IEmailDomain;
    records?: IEmailDnsRecord[];
    message?: string;
  };
}

/**
 * Get the required DNS records for an email domain (for display / copy-paste).
 */
export interface IReq_GetEmailDomainDnsRecords extends plugins.typedrequestInterfaces.implementsTR<
  plugins.typedrequestInterfaces.ITypedRequest,
  IReq_GetEmailDomainDnsRecords
> {
  method: 'getEmailDomainDnsRecords';
  request: {
    identity?: authInterfaces.IIdentity;
    apiToken?: string;
    id: string;
  };
  response: {
    records: IEmailDnsRecord[];
  };
}

/**
 * Auto-provision DNS records for an email domain.
 * Creates any missing MX, SPF, DKIM, and DMARC records via the linked
 * domain's DNS path (dcrouter zone or provider API).
 */
export interface IReq_ProvisionEmailDomainDns extends plugins.typedrequestInterfaces.implementsTR<
  plugins.typedrequestInterfaces.ITypedRequest,
  IReq_ProvisionEmailDomainDns
> {
  method: 'provisionEmailDomainDns';
  request: {
    identity?: authInterfaces.IIdentity;
    apiToken?: string;
    id: string;
  };
  response: {
    success: boolean;
    /** Number of records created. */
    provisioned?: number;
    message?: string;
  };
}