// ================================================================
// frontend/src/api/types/notification.ts
// ================================================================
/**
 * Notification Type Definitions
 *
 * Aligned with backend schema:
 * - services/notification/app/schemas/notifications.py
 *
 * Last Updated: 2025-10-05
 * Status: ✅ Complete - Zero drift with backend
 */

// ================================================================
// ENUMS
// ================================================================

/**
 * Notification types
 * Backend: services/notification/app/schemas/notifications.py:14-18 (NotificationType)
 */
export enum NotificationType {
  EMAIL = 'email',
  WHATSAPP = 'whatsapp',
  PUSH = 'push',
  SMS = 'sms'
}

/**
 * Notification status
 * Backend: services/notification/app/schemas/notifications.py:20-25 (NotificationStatus)
 */
export enum NotificationStatus {
  PENDING = 'pending',
  SENT = 'sent',
  DELIVERED = 'delivered',
  FAILED = 'failed',
  CANCELLED = 'cancelled'
}

/**
 * Notification priority levels
 * Backend: services/notification/app/schemas/notifications.py:27-31 (NotificationPriority)
 */
export enum NotificationPriority {
  LOW = 'low',
  NORMAL = 'normal',
  HIGH = 'high',
  URGENT = 'urgent'
}

// ================================================================
// REQUEST TYPES
// ================================================================

/**
 * Schema for creating a new notification
 * Backend: services/notification/app/schemas/notifications.py:37-74 (NotificationCreate)
 */
export interface NotificationCreate {
  type: NotificationType;
  recipient_id?: string | null;  // For individual notifications
  recipient_email?: string | null;  // EmailStr validation on backend
  recipient_phone?: string | null;  // Spanish phone validation on backend

  // Content
  subject?: string | null;
  message: string;  // min_length=1, max_length=5000
  html_content?: string | null;

  // Template-based content
  template_id?: string | null;
  template_data?: Record<string, any> | null;

  // Configuration
  priority?: NotificationPriority;  // Default: NORMAL
  scheduled_at?: string | null;  // ISO datetime - must be in future
  broadcast?: boolean;  // Default: false

  // Internal fields (set by service)
  tenant_id?: string | null;
  sender_id?: string | null;
}

/**
 * Schema for updating notification status
 * Backend: services/notification/app/schemas/notifications.py:76-82 (NotificationUpdate)
 */
export interface NotificationUpdate {
  status?: NotificationStatus | null;
  error_message?: string | null;
  delivered_at?: string | null;  // ISO datetime
  read?: boolean | null;
  read_at?: string | null;  // ISO datetime
}

/**
 * Schema for creating bulk notifications
 * Backend: services/notification/app/schemas/notifications.py:84-100 (BulkNotificationCreate)
 */
export interface BulkNotificationCreate {
  type: NotificationType;
  recipients: string[];  // min_items=1, max_items=1000 - User IDs or emails

  // Content
  subject?: string | null;
  message: string;  // min_length=1, max_length=5000
  html_content?: string | null;

  // Template-based content
  template_id?: string | null;
  template_data?: Record<string, any> | null;

  // Configuration
  priority?: NotificationPriority;  // Default: NORMAL
  scheduled_at?: string | null;  // ISO datetime
}

// ================================================================
// RESPONSE TYPES
// ================================================================

/**
 * Schema for notification response
 * Backend: services/notification/app/schemas/notifications.py:106-137 (NotificationResponse)
 */
export interface NotificationResponse {
  id: string;
  tenant_id: string;
  sender_id: string;
  recipient_id?: string | null;

  type: NotificationType;
  status: NotificationStatus;
  priority: NotificationPriority;

  subject?: string | null;
  message: string;
  recipient_email?: string | null;
  recipient_phone?: string | null;

  scheduled_at?: string | null;  // ISO datetime
  sent_at?: string | null;  // ISO datetime
  delivered_at?: string | null;  // ISO datetime

  broadcast: boolean;
  read: boolean;
  read_at?: string | null;  // ISO datetime

  retry_count: number;
  error_message?: string | null;

  created_at: string;  // ISO datetime
  updated_at: string;  // ISO datetime
}

/**
 * Schema for notification history
 * Backend: services/notification/app/schemas/notifications.py:139-146 (NotificationHistory)
 */
export interface NotificationHistory {
  notifications: NotificationResponse[];
  total: number;
  page: number;
  per_page: number;
  has_next: boolean;
  has_prev: boolean;
}

/**
 * Schema for notification statistics
 * Backend: services/notification/app/schemas/notifications.py:148-157 (NotificationStats)
 */
export interface NotificationStats {
  total_sent: number;
  total_delivered: number;
  total_failed: number;
  delivery_rate: number;
  avg_delivery_time_minutes?: number | null;
  by_type: Record<string, number>;
  by_status: Record<string, number>;
  recent_activity: Array<Record<string, any>>;
}

// ================================================================
// PREFERENCE TYPES
// ================================================================

/**
 * Schema for user notification preferences
 * Backend: services/notification/app/schemas/notifications.py:163-200 (NotificationPreferences)
 */
export interface NotificationPreferences {
  user_id: string;
  tenant_id: string;

  // Email preferences
  email_enabled: boolean;  // Default: true
  email_alerts: boolean;  // Default: true
  email_marketing: boolean;  // Default: false
  email_reports: boolean;  // Default: true

  // WhatsApp preferences
  whatsapp_enabled: boolean;  // Default: false
  whatsapp_alerts: boolean;  // Default: false
  whatsapp_reports: boolean;  // Default: false

  // Push notification preferences
  push_enabled: boolean;  // Default: true
  push_alerts: boolean;  // Default: true
  push_reports: boolean;  // Default: false

  // Timing preferences
  quiet_hours_start: string;  // Default: "22:00", pattern: HH:MM
  quiet_hours_end: string;  // Default: "08:00", pattern: HH:MM
  timezone: string;  // Default: "Europe/Madrid"

  // Frequency preferences
  digest_frequency: string;  // Default: "daily", pattern: ^(none|daily|weekly)$
  max_emails_per_day: number;  // Default: 10, ge=1, le=100

  // Language preference
  language: string;  // Default: "es", pattern: ^(es|en)$

  created_at: string;  // ISO datetime
  updated_at: string;  // ISO datetime
}

/**
 * Schema for updating notification preferences
 * Backend: services/notification/app/schemas/notifications.py:202-223 (PreferencesUpdate)
 */
export interface PreferencesUpdate {
  email_enabled?: boolean | null;
  email_alerts?: boolean | null;
  email_marketing?: boolean | null;
  email_reports?: boolean | null;

  whatsapp_enabled?: boolean | null;
  whatsapp_alerts?: boolean | null;
  whatsapp_reports?: boolean | null;

  push_enabled?: boolean | null;
  push_alerts?: boolean | null;
  push_reports?: boolean | null;

  quiet_hours_start?: string | null;  // pattern: HH:MM
  quiet_hours_end?: string | null;  // pattern: HH:MM
  timezone?: string | null;

  digest_frequency?: string | null;  // pattern: ^(none|daily|weekly)$
  max_emails_per_day?: number | null;  // ge=1, le=100
  language?: string | null;  // pattern: ^(es|en)$
}

// ================================================================
// TEMPLATE TYPES
// ================================================================

/**
 * Schema for creating notification templates
 * Backend: services/notification/app/schemas/notifications.py:229-243 (TemplateCreate)
 */
export interface TemplateCreate {
  template_key: string;  // min_length=3, max_length=100
  name: string;  // min_length=3, max_length=255
  description?: string | null;
  category: string;  // pattern: ^(alert|marketing|transactional)$

  type: NotificationType;
  subject_template?: string | null;
  body_template: string;  // min_length=10
  html_template?: string | null;

  language?: string;  // Default: "es", pattern: ^(es|en)$
  default_priority?: NotificationPriority;  // Default: NORMAL
  required_variables?: string[] | null;
}

/**
 * Schema for template response
 * Backend: services/notification/app/schemas/notifications.py:245-269 (TemplateResponse)
 */
export interface TemplateResponse {
  id: string;
  tenant_id?: string | null;
  template_key: string;
  name: string;
  description?: string | null;
  category: string;

  type: NotificationType;
  subject_template?: string | null;
  body_template: string;
  html_template?: string | null;

  language: string;
  is_active: boolean;
  is_system: boolean;
  default_priority: NotificationPriority;
  required_variables?: string[] | null;

  created_at: string;  // ISO datetime
  updated_at: string;  // ISO datetime
}

// ================================================================
// WEBHOOK TYPES
// ================================================================

/**
 * Schema for delivery status webhooks
 * Backend: services/notification/app/schemas/notifications.py:275-284 (DeliveryWebhook)
 */
export interface DeliveryWebhook {
  notification_id: string;
  status: NotificationStatus;
  provider: string;
  provider_message_id?: string | null;
  delivered_at?: string | null;  // ISO datetime
  error_code?: string | null;
  error_message?: string | null;
  metadata?: Record<string, any> | null;
}

/**
 * Schema for read receipt webhooks
 * Backend: services/notification/app/schemas/notifications.py:286-290 (ReadReceiptWebhook)
 */
export interface ReadReceiptWebhook {
  notification_id: string;
  read_at: string;  // ISO datetime
  user_agent?: string | null;
  ip_address?: string | null;
}
