Execution Reports

// ============================================
// EFFECTIVE STATUS
// ============================================

/**
 * Effective status includes computed pause window state.
 * - DB stores: 'scheduled' | 'running' | 'paused' | 'paused_no_credits' | 'paused_threshold' | 'completed' | 'stopped' | 'cancelled'
 * - API adds: 'paused_manual' (user paused) vs 'paused_window' (in pause window)
 */
type EffectiveStatus =
  | 'scheduled'
  | 'running'
  | 'paused_manual'      // User explicitly paused
  | 'paused_window'      // Currently in a pause window (computed at query time)
  | 'paused_no_credits'  // Auto-paused due to insufficient credits
  | 'paused_threshold'   // Auto-paused due to counter threshold reached
  | 'completed'
  | 'stopped'
  | 'cancelled';

// ============================================
// CONTACT METRICS
// ============================================

/**
 * Metrics aggregated from execution_contacts by status.
 * Represents unique contacts, not call attempts.
 */
interface ContactMetrics {
  totalContacts: number;

  // By execution_contacts.status
  pending: number;
  queued: number;
  calling: number;
  pendingRetry: number;
  completed: number;
  failed: number;
  skipped: number;

  // Derived - most important campaign metric
  reachRate: number;  // completed / totalContacts * 100
}

// ============================================
// CALL METRICS
// ============================================

/**
 * Metrics aggregated from calls by outcome.
 * Can exceed totalContacts due to retries.
 */
interface CallMetrics {
  totalCalls: number;

  // By calls.outcome
  connected: number;   // answered + voicemail (any pickup — line connected)
  answered: number;    // human answered (calls.outcome = 'completed')
  voicemail: number;
  noAnswer: number;
  busy: number;
  rejected: number;
  failed: number;

  // By calls.flowOutcome
  completed: number;       // flow ran to normal end (calls.flowOutcome = 'completed')

  // Derived
  connectionRate: number;  // connected / totalCalls * 100
  answerRate: number;      // answered / totalCalls * 100
}

// ============================================
// BILLING METRICS
// ============================================

/**
 * Billing metrics for program execution.
 */
interface BillingMetrics {
  totalCreditsUsed: number;       // Sum of all call costs
  billableCallsCount: number;     // Calls with cost > 0
  averageCostPerCall: number;     // totalCreditsUsed / billableCallsCount
}

// ============================================
// PROGRAM REPORT (Main Report)
// ============================================

interface ProgramReport {
  executionId: string;
  programId: string;
  organizationId: string;

  // Status
  status: string;                  // DB status
  effectiveStatus: EffectiveStatus;
  isInPauseWindow: boolean;

  // Timing
  scheduledStartAt: string;        // ISO date
  scheduledStopAt?: string;        // ISO date
  actualStartAt?: string;          // ISO date
  actualEndAt?: string;            // ISO date
  durationMs?: number;             // Computed: endTime - startTime

  // Metadata
  metadata: {
    flowId: string;
    flowName: string;
    audienceId: string;
    didPool: string[];
    retryStrategy: RetryStrategy;
    pauseWindows?: PauseWindows;
  };

  // Metrics
  contactMetrics: ContactMetrics;
  callMetrics: CallMetrics;
  billingMetrics: BillingMetrics;
}

// ============================================
// CALL HISTORY ITEM
// ============================================

type CallHistoryStatus = 'ongoing' | 'completed' | 'no_answer' | 'voicemail' | 'busy' | 'rejected' | 'failed';

interface CallHistoryItem {
  callId: string;
  contactId: string | null;

  // Call details
  from: string;
  to: string;
  direction: 'inbound' | 'outbound';
  attempt: number;

  // Status
  status: CallHistoryStatus;
  outcome: string | null;

  // Timing
  startedAt: string;          // ISO date
  endedAt?: string;           // ISO date
  durationMs?: number;

  // Billing
  totalCost?: number;         // Total cost for this call
}

// ============================================
// ATTEMPT BREAKDOWN
// ============================================

interface AttemptBreakdown {
  attemptNumber: number;       // 1, 2, 3... or 0 for total

  // Counts
  callsAttempted: number;
  callsConnected: number;     // answered + voicemail (any pickup)
  callsAnswered: number;      // human answered
  callsVoicemail: number;
  callsNoAnswer: number;
  callsFailed: number;
  callsCompleted: number;     // flow ran to normal end

  // Percentages (relative to callsAttempted for this attempt)
  connectedPercentage: number;
  answeredPercentage: number;
  voicemailPercentage: number;
  noAnswerPercentage: number;
  completedPercentage: number;

  // Metrics
  averageDurationMs: number;
}

interface EventBreakdownResponse {
  perAttempt: AttemptBreakdown[];
  total: AttemptBreakdown;
}

// ============================================
// NODE EXECUTION STATS
// ============================================

/**
 * Execution statistics for a single node.
 *
 * NOTE: This is NOT a funnel because call flows are directed graphs
 * with branches (DTMF/condition) and cycles (loops back to previous nodes).
 * We report unique calls per node and total executions, not drop-off rates.
 */
interface NodeExecutionStat {
  nodeId: string;
  nodeType: string;
  nodeLabel?: string;

  // Unique calls that executed this node (at least once)
  uniqueCalls: number;

  // Total executions including loops/retries (uniqueCalls <= totalExecutions)
  totalExecutions: number;

  // % of calls that reached this node: uniqueCalls / totalCalls * 100
  percentage: number;

  // DTMF-specific (only for nodeType === 'dtmf')
  dtmfBreakdown?: Record<string, number>;      // e.g., { "1": 50, "2": 30 }
  dtmfPercentages?: Record<string, number>;    // e.g., { "1": 62.5, "2": 37.5 }
}

interface NodeExecutionStatsResponse {
  nodes: NodeExecutionStat[];

  // Summary
  totalCalls: number;
  completedCalls: number;      // flow_outcome = 'completed'
  completionRate: number;      // completedCalls / totalCalls * 100
}

// ============================================
// PROGRAM BILLING REPORT
// ============================================

/**
 * Cost breakdown by node type (e.g., all DIAL nodes, all RECORD nodes)
 */
interface NodeTypeCostBreakdown {
  nodeType: string;           // 'dial' | 'record' | etc.
  totalCost: number;          // Total cost for all nodes of this type
  executionCount: number;     // Number of executions
  totalDurationMs: number | null;
}

/**
 * Top costly call entry
 */
interface TopCostlyCall {
  callId: string;
  contactId: string | null;
  totalCost: number;
  durationMs: number | null;
}

/**
 * Detailed billing report for a program execution
 */
interface ProgramBillingReport {
  executionId: string;

  summary: {
    totalCreditsUsed: number;
    billableCallsCount: number;
    averageCostPerCall: number;
  };

  // Cost breakdown by node type
  byNodeType: NodeTypeCostBreakdown[];

  // Top 10 most expensive calls
  topCostlyCalls: TopCostlyCall[];
}

// ============================================
// PAGINATION
// ============================================

interface PaginationMeta {
  page: number;
  limit: number;
  total: number;
  totalPages: number;
}

interface PaginatedResponse<T> {
  data: T[];
  meta: PaginationMeta;
}