/**
 * Type Definitions for Staff Dashboard Demo Bookings
 *
 * This module contains all TypeScript type definitions for the demo bookings feature.
 * It provides type safety for database operations and API responses.
 *
 * @module lib/staff-dashboard/demo-bookings/types
 */

/**
 * Demo booking database record
 *
 * Uses snake_case naming convention as per database standards.
 */
export type DemoBookingRecord = {
  /** Unique identifier (VARCHAR 255, matches CUID format) */
  id: string;

  // Customer Information
  /** Customer's full name (supports Arabic and English) */
  full_name: string;
  /** Customer's email address (validated) */
  email: string;
  /** Customer's telephone number (international format) */
  telephone: string;

  // Appointment Details
  /** Appointment date (TIMESTAMPTZ, stored in UTC) */
  appointment_date: string;
  /** Appointment time (human-readable, e.g., "10:00 AM") */
  appointment_time: string;
  /** Duration of appointment (e.g., "30 minutes", "1 hour") */
  duration: string;
  /** Optional special requirements or notes from customer */
  special_requirements: string | null;

  // Metadata
  /** Language preference: Arabic or English */
  language: 'ar' | 'en';
  /** Booking status: pending (new), confirmed (approved), cancelled (rejected) */
  status: 'pending' | 'confirmed' | 'cancelled';

  // Webhook Integration (n8n)
  /** Webhook delivery status */
  webhook_status: 'pending' | 'sent' | 'failed';
  /** Number of times webhook delivery was attempted */
  webhook_retry_count: number;
  /** Timestamp of last webhook attempt */
  webhook_last_attempt: string | null;
  /** Response body from webhook endpoint */
  webhook_response: string | null;

  // Staff Management Fields (added in migration 20251116)
  /** Video meeting link (Zoom, Google Meet, Teams, etc.) - added by staff */
  meeting_link: string | null;
  /** Private notes for internal staff use only - never shown to customer */
  internal_notes: string | null;
  /** Timestamp when staff member contacted the customer */
  contacted_at: string | null;
  /** User ID of staff member who contacted the customer */
  contacted_by: string | null;

  // Timestamps
  /** Record creation timestamp */
  created_at: string;
  /** Record last update timestamp */
  updated_at: string;
};

/**
 * Demo booking data for frontend/API responses
 *
 * This type uses camelCase naming convention for JavaScript/TypeScript compatibility.
 * It's the transformed version of DemoBookingRecord used in API responses.
 *
 * Maps from snake_case (database) to camelCase (frontend)
 */
export type DemoBooking = {
  id: string;
  fullName: string;
  email: string;
  telephone: string;
  appointmentDate: string;
  appointmentTime: string;
  duration: string;
  specialRequirements: string | null;
  language: 'ar' | 'en';
  status: 'pending' | 'confirmed' | 'cancelled';
  webhookStatus: 'pending' | 'sent' | 'failed';
  webhookRetryCount: number;
  webhookLastAttempt: string | null;
  webhookResponse: string | null;
  meetingLink: string | null;
  internalNotes: string | null;
  contactedAt: string | null;
  contactedBy: string | null;
  createdAt: string;
  updatedAt: string;
};

/**
 * Input type for creating new demo bookings (public form submission)
 *
 * Used when customers submit the demo booking form.
 * Only includes fields that the customer provides.
 *
 * @example
 * const booking: DemoBookingInput = {
 *   full_name: "John Doe",
 *   email: "john@example.com",
 *   telephone: "+966501234567",
 *   appointment_date: "2025-12-01T10:00:00Z",
 *   appointment_time: "10:00 AM",
 *   duration: "30 minutes",
 *   language: "en"
 * };
 */
export type DemoBookingInput = {
  full_name: string;
  email: string;
  telephone: string;
  appointment_date: string;
  appointment_time: string;
  duration: string;
  special_requirements?: string;
  language: 'ar' | 'en';
};

/**
 * Update data for modifying existing bookings (staff actions)
 *
 * Used when staff members update booking status, add meeting links, or add notes.
 * All fields are optional - only provided fields will be updated.
 *
 * @example
 * const update: DemoBookingUpdate = {
 *   status: "confirmed",
 *   meeting_link: "https://zoom.us/j/123456",
 *   contacted_at: new Date().toISOString(),
 *   contacted_by: "staff-user-id"
 * };
 */
export type DemoBookingUpdate = {
  status?: 'pending' | 'confirmed' | 'cancelled';
  meeting_link?: string;
  internal_notes?: string;
  contacted_at?: string;
  contacted_by?: string;
  updated_at?: string;
};

/**
 * Filter parameters for querying demo bookings
 *
 * Used by the GET API endpoint to filter and search bookings.
 * All filters are optional and can be combined.
 *
 * @example
 * const filters: DemoBookingFilters = {
 *   status: "pending",
 *   search: "john",
 *   dateRange: "week"
 * };
 */
export type DemoBookingFilters = {
  /** Filter by booking status (omit for all statuses) */
  status?: 'all' | 'pending' | 'confirmed' | 'cancelled';
  /** Search term (searches name, email, and phone) */
  search?: string;
  /** Date range filter */
  dateRange?: 'all' | 'today' | 'week' | 'month';
};

/**
 * API request body for updating bookings
 *
 * Used by the UPDATE API endpoint. Uses camelCase naming.
 *
 * @example
 * const requestBody: DemoBookingUpdateRequest = {
 *   bookingId: "booking-123",
 *   status: "confirmed",
 *   meetingLink: "https://zoom.us/j/123"
 * };
 */
export type DemoBookingUpdateRequest = {
  /** ID of the booking to update */
  bookingId: string;
  /** New status (optional) */
  status?: 'pending' | 'confirmed' | 'cancelled';
  /** Meeting link to add (optional) */
  meetingLink?: string;
  /** Internal notes to add/update (optional) */
  internalNotes?: string;
};

/**
 * API response for GET /api/staff/dashboard/demos
 *
 * @example
 * const response: DemoBookingsResponse = {
 *   bookings: [...],
 *   total: 10
 * };
 */
export type DemoBookingsResponse = {
  /** Array of demo bookings (camelCase format) */
  bookings: DemoBooking[];
  /** Total count (optional, for pagination) */
  total?: number;
};

/**
 * API response for POST /api/staff/dashboard/demos/update
 *
 * @example
 * const response: DemoBookingUpdateResponse = {
 *   success: true,
 *   booking: {...}
 * };
 */
export type DemoBookingUpdateResponse = {
  /** Whether update was successful */
  success: boolean;
  /** Updated booking record (snake_case from database) */
  booking?: DemoBookingRecord;
  /** Error message if update failed */
  error?: string;
};

/**
 * Staff user information (for audit trail)
 *
 * Minimal user info needed for tracking who made changes.
 */
export type StaffUser = {
  id: string;
  email: string;
  name: string;
  role: string;
};

/**
 * Enum values for type-safe status updates
 *
 * @example
 * if (status === BookingStatus.CONFIRMED) { ... }
 */
export enum BookingStatus {
  PENDING = 'pending',
  CONFIRMED = 'confirmed',
  CANCELLED = 'cancelled',
}

/**
 * Enum values for webhook status
 */
export enum WebhookStatus {
  PENDING = 'pending',
  SENT = 'sent',
  FAILED = 'failed',
}

/**
 * Language options
 */
export enum Language {
  ARABIC = 'ar',
  ENGLISH = 'en',
}

/**
 * Date range filter options
 */
export enum DateRange {
  ALL = 'all',
  TODAY = 'today',
  WEEK = 'week',
  MONTH = 'month',
}
