smartmail/ts/smartmail.wire.ts

import type { ISmartmailJson } from './smartmail.classes.smartmail.js';

// ==========================================
// Base Message Structure
// ==========================================

/**
 * Base interface for all wire messages
 */
export interface IWireMessage {
  type: string;
  messageId: string;
  timestamp: string;
}

// ==========================================
// Mail Send Operations
// ==========================================

/**
 * Request to send an email
 */
export interface IMailSendRequest extends IWireMessage {
  type: 'mail.send';
  email: ISmartmailJson;
  options?: {
    validateBeforeSend?: boolean;
    templateVariables?: Record<string, unknown>;
  };
}

/**
 * Response after sending an email
 */
export interface IMailSendResponse extends IWireMessage {
  type: 'mail.send.response';
  success: boolean;
  error?: string;
  deliveryId?: string;
}

// ==========================================
// Mailbox Operations
// ==========================================

/**
 * Request to list emails in a mailbox
 */
export interface IMailboxListRequest extends IWireMessage {
  type: 'mailbox.list';
  mailbox: string;
  limit?: number;
  offset?: number;
}

/**
 * Response with mailbox email list
 */
export interface IMailboxListResponse extends IWireMessage {
  type: 'mailbox.list.response';
  mailbox: string;
  emails: ISmartmailJson[];
  total: number;
}

// ==========================================
// Mail Fetch Operations
// ==========================================

/**
 * Request to fetch a specific email
 */
export interface IMailFetchRequest extends IWireMessage {
  type: 'mail.fetch';
  mailbox: string;
  emailId: string;
}

/**
 * Response with fetched email
 */
export interface IMailFetchResponse extends IWireMessage {
  type: 'mail.fetch.response';
  email: ISmartmailJson | null;
}

// ==========================================
// Mail Status Operations
// ==========================================

/**
 * Request to check delivery status
 */
export interface IMailStatusRequest extends IWireMessage {
  type: 'mail.status';
  deliveryId: string;
}

/**
 * Response with delivery status
 */
export interface IMailStatusResponse extends IWireMessage {
  type: 'mail.status.response';
  deliveryId: string;
  status: 'queued' | 'sending' | 'sent' | 'failed';
  error?: string;
}

// ==========================================
// Settings Operations (Extensible)
// ==========================================

/**
 * SMTP server configuration
 */
export interface ISmtpSettings {
  host: string;
  port: number;
  secure: boolean;
  username?: string;
  password?: string;
}

/**
 * Wire settings - extensible with arbitrary key-value pairs
 */
export interface IWireSettings {
  smtp?: ISmtpSettings;
  defaultFrom?: string;
  defaultReplyTo?: string;
  [key: string]: unknown;
}

/**
 * Request to update settings
 */
export interface ISettingsUpdateRequest extends IWireMessage {
  type: 'settings.update';
  settings: IWireSettings;
}

/**
 * Response after updating settings
 */
export interface ISettingsUpdateResponse extends IWireMessage {
  type: 'settings.update.response';
  success: boolean;
  error?: string;
}

// ==========================================
// Union Type for Type Discrimination
// ==========================================

/**
 * Union of all wire message types for type discrimination
 */
export type TWireMessage =
  | IMailSendRequest
  | IMailSendResponse
  | IMailboxListRequest
  | IMailboxListResponse
  | IMailFetchRequest
  | IMailFetchResponse
  | IMailStatusRequest
  | IMailStatusResponse
  | ISettingsUpdateRequest
  | ISettingsUpdateResponse;

// ==========================================
// Helper Functions
// ==========================================

/**
 * Creates a unique message ID
 * @returns UUID string
 */
export function createMessageId(): string {
  return crypto.randomUUID();
}

/**
 * Creates an ISO timestamp
 * @returns ISO 8601 timestamp string
 */
export function createTimestamp(): string {
  return new Date().toISOString();
}