meeting.interface.ts

// Copyright The Linux Foundation and each contributor to LFX.
// SPDX-License-Identifier: MIT

import { ArtifactVisibility, MeetingType, MeetingVisibility, RecurrenceType } from '../enums';

// ============================================================================
// V1 Legacy Summary Interfaces (still used by transformV1SummaryToV2)
// ============================================================================

/**
 * V1 Legacy summary detail item
 * @description Structure for individual summary topics in v1 format
 */
export interface V1SummaryDetail {
  /** Topic label */
  label: string;
  /** Summary content for this topic */
  summary: string;
}

/**
 * V1 Past Meeting Summary data structure
 * @description Raw V1 summary data before transformation to V2 format
 */
export interface V1PastMeetingSummary {
  id: string;
  meeting_id?: string;
  occurrence_id?: string;
  meeting_and_occurrence_id?: string;
  zoom_meeting_uuid?: string;
  zoom_meeting_topic?: string;
  zoom_meeting_host_id?: string;
  zoom_meeting_host_email?: string;
  zoom_webhook_event?: string;

  // V1 summary content structure
  summary_title?: string;
  summary_overview?: string;
  summary_details?: V1SummaryDetail[];
  next_steps?: string[];

  // V1 edited content
  edited_summary_overview?: string;
  edited_summary_details?: V1SummaryDetail[] | null;
  edited_next_steps?: string[] | null;

  // Timestamps
  summary_created_time?: string;
  summary_start_time?: string;
  summary_end_time?: string;
  summary_last_modified_time?: string;
  modified_at?: string;

  // Status
  approved?: boolean;
  requires_approval?: boolean;
  email_sent?: boolean;
  password?: string;
}

// ============================================================================
// V2 Meeting Interfaces
// ============================================================================

/**
 * Zoom-specific meeting configuration
 * @description Settings specific to Zoom platform integration
 */
export interface ZoomConfig {
  /** Zoom meeting ID (response only) */
  meeting_id?: string;
  /** Zoom meeting passcode (response only) */
  passcode?: string;
  /** Enable/disable Zoom AI companion */
  ai_companion_enabled?: boolean;
  /** Require approval for AI summaries in LFX system */
  ai_summary_require_approval?: boolean;
}

/**
 * Meeting recurrence configuration
 * @description Defines how and when a meeting repeats (compatible with Zoom API)
 */
export interface MeetingRecurrence {
  /** End date/time for the recurrence pattern (ISO string) */
  end_date_time?: string;
  /** Number of times the meeting should repeat before ending */
  end_times?: number;
  /** Day of the month for monthly recurrence (1-31) */
  monthly_day?: number;
  /** Week of the month for monthly recurrence (1-4, -1 for last week) */
  monthly_week?: number;
  /** Day of the week for monthly recurrence (1-7, Sunday=1) */
  monthly_week_day?: number;
  /** Interval between recurrences (e.g., 1=every week, 2=every other week) */
  repeat_interval: number;
  /** Type of recurrence pattern */
  type: RecurrenceType;
  /** Comma-separated days of week for weekly recurrence (1-7, Sunday=1) */
  weekly_days?: string;
}

/**
 * Important link associated with a meeting
 * @description External links relevant to the meeting (agendas, documents, etc.)
 */
export interface ImportantLink {
  /** Unique identifier for the link */
  id?: string;
  /** Display title for the link */
  title: string;
  /** URL of the external resource */
  url: string;
}

/**
 * Important link form value with attachment tracking
 * @description Form-specific interface for managing important links with attachment UIDs
 */
export interface ImportantLinkFormValue {
  /** Unique identifier for the form control */
  id: string;
  /** Display title for the link */
  title: string;
  /** URL of the external resource */
  url: string;
  /** Attachment UID (null for new links, present for existing link attachments) */
  uid: string | null;
}

/**
 * Committee associated with a meeting
 * @description Basic committee information for meeting association
 */

/**
 * Committee payload for meeting API requests
 * @description Committee structure used in create/update meeting requests
 */
export interface MeetingCommittee {
  /** Unique identifier for the committee */
  uid: string;
  /** Allowed voting statuses for committee members */
  allowed_voting_statuses?: string[];
  /** Committee name */
  name?: string;
}

export interface Meeting {
  // API Response fields - not in create payload
  /** Unique identifier for the meeting */
  id: string;
  /** Timestamp when meeting was created */
  created_at: string;
  /** Timestamp when meeting was last updated */
  modified_at: string;
  /** Write access permission for current user (response only) */
  organizer?: boolean;

  // Required API fields
  /** UUID of the LF project */
  project_uid: string;
  /** Meeting start time in RFC3339 format */
  start_time: string;
  /** Meeting duration in minutes (0-600) */
  duration: number;
  /** Meeting timezone (e.g., "America/New_York") */
  timezone: string;
  /** Meeting title */
  title: string;
  /** Meeting description */
  description: string;
  // Optional API fields
  /** Currently only "Zoom" is supported */
  platform?: string;
  /** For recurring meetings */
  recurrence: MeetingRecurrence | null;
  /** Associated committees with voting statuses */
  committees: MeetingCommittee[];
  /** "Board", "Maintainers", "Technical", etc. */
  meeting_type: string | null;
  /** "public" or "private" */
  visibility: MeetingVisibility | null;
  /** Boolean for invitation-only meetings */
  restricted: boolean | null;
  /** Enable meeting recording */
  recording_enabled: boolean | null;
  /** Enable transcription */
  transcript_enabled: boolean | null;
  /** YouTube upload integration */
  youtube_upload_enabled: boolean | null;
  /** Show meeting attendees on meeting details page */
  show_meeting_attendees?: boolean | null;
  /** Who can access meeting artifacts (recordings, transcripts, AI summaries) */
  artifact_visibility: ArtifactVisibility | null;
  /** Minutes before meeting registrants can join */
  early_join_time_minutes?: number;
  /** Array of organizer usernames */
  organizers: string[];
  /** Meeting access password for private/restricted meetings */
  password: string | null;
  /** Zoom-specific settings */
  zoom_config?: ZoomConfig | null;

  /** 6-digit Zoom host key */
  host_key?: string;
  /** Zoom meeting passcode */
  passcode?: string;

  // Fields NOT in API - likely response-only
  /** Invited to meeting (response only) */
  invited: boolean;
  /** Meeting public link (join URL) */
  public_link?: string;
  /** Total registrant count from API */
  registrant_count?: number;
  /** Count fields (response only) — omitted when list endpoints skip per-meeting enrichment; callers must handle undefined. */
  individual_registrants_count?: number;
  /** Count fields (response only) — omitted when list endpoints skip per-meeting enrichment; callers must handle undefined. */
  committee_members_count?: number;
  /** Count fields (response only) — omitted when list endpoints skip per-meeting enrichment; callers must handle undefined. */
  registrants_accepted_count?: number;
  /** Count fields (response only) — omitted when list endpoints skip per-meeting enrichment; callers must handle undefined. */
  registrants_declined_count?: number;
  /** Count fields (response only) — omitted when list endpoints skip per-meeting enrichment; callers must handle undefined. */
  registrants_pending_count?: number;
  /** Participant count for past meetings (response only) */
  participant_count?: number;
  /** Attended count for past meetings (response only) */
  attended_count?: number;
  /** Meeting occurrences */
  occurrences: MeetingOccurrence[];
  /** Current user's RSVP for this meeting (null when the user hasn't responded).
   * Populated by /api/user/meetings only. Absent on other Meeting-returning endpoints. */
  my_rsvp?: MeetingRsvp | null;
  /** Project name */
  project_name: string;
  /** Project slug */
  project_slug: string;
  /** Whether the project is a foundation (top-level entity) */
  is_foundation?: boolean;
  /** Parent project UID (for subprojects under a foundation) */
  parent_project_uid?: string;
}

/**
 * Meeting occurrence entity with meeting details
 * @description Represents a specific occurrence of a recurring meeting
 */
export interface MeetingOccurrence {
  /** Unique identifier for the occurrence */
  occurrence_id: string;
  /** Meeting title */
  title?: string;
  /** Meeting description */
  description?: string;
  /** Meeting start time in RFC3339 format */
  start_time: string;
  /** Meeting duration in minutes (0-600) */
  duration: number;
  /** Occurrence status ("available" or "cancel") */
  status?: string;
  /** Total registrant count for this occurrence */
  registrant_count?: number;
}

/**
 * Meeting with occurrence information
 * @description Combines meeting details with a specific occurrence for display and sorting purposes
 */
export interface MeetingWithOccurrence {
  /** Meeting details */
  meeting: Meeting;
  /** Specific occurrence of the meeting */
  occurrence: MeetingOccurrence;
  /** Timestamp for sorting meetings chronologically (milliseconds since epoch) */
  sortTime: number;
  /** Unique tracking key combining meeting uid and occurrence id */
  trackId: string;
}

export interface CreateMeetingRequest {
  // Required API fields
  project_uid: string; // UUID of the LF project
  start_time: string; // Meeting start time in RFC3339 format
  duration: number; // Meeting duration in minutes (0-600)
  timezone: string; // Meeting timezone (e.g., "America/New_York")
  title: string; // Meeting title
  description: string; // Meeting description

  // Optional API fields
  platform?: string; // Currently only "Zoom" is supported
  recurrence?: MeetingRecurrence; // For recurring meetings
  committees?: MeetingCommittee[]; // Associated committees with voting statuses
  meeting_type?: string; // "Board", "Maintainers", "Technical", etc.
  visibility?: MeetingVisibility; // "public" or "private"
  restricted?: boolean; // Boolean for invitation-only meetings
  recording_enabled?: boolean; // Enable meeting recording
  transcript_enabled?: boolean; // Enable transcription
  youtube_upload_enabled?: boolean; // YouTube upload integration
  show_meeting_attendees?: boolean; // Show meeting attendees on meeting details page
  artifact_visibility?: ArtifactVisibility; // Who can access meeting artifacts
  early_join_time_minutes?: number; // Minutes before meeting registrants can join
  organizers?: string[]; // Array of organizer email addresses
  zoom_config?: ZoomConfig; // Zoom-specific settings
}

export interface UpdateMeetingRequest {
  // Required API fields
  project_uid: string; // UUID of the LF project
  start_time: string; // Meeting start time in RFC3339 format
  duration: number; // Meeting duration in minutes (0-600)
  timezone: string; // Meeting timezone (e.g., "America/New_York")
  title: string; // Meeting title
  description?: string; // Meeting description

  // Optional API fields
  platform?: string; // Currently only "Zoom" is supported
  recurrence?: MeetingRecurrence | null; // For recurring meetings
  committees?: MeetingCommittee[]; // Associated committees with voting statuses
  meeting_type?: string | null; // "Board", "Maintainers", "Technical", etc.
  visibility?: MeetingVisibility | null; // "public" or "private"
  restricted?: boolean | null; // Boolean for invitation-only meetings
  recording_enabled?: boolean | null; // Enable meeting recording
  transcript_enabled?: boolean | null; // Enable transcription
  youtube_upload_enabled?: boolean | null; // YouTube upload integration
  show_meeting_attendees?: boolean | null; // Show meeting attendees on meeting details page
  artifact_visibility?: ArtifactVisibility | null; // Who can access meeting artifacts
  early_join_time_minutes?: number; // Minutes before meeting registrants can join
  organizers?: string[]; // Array of organizer email addresses
  zoom_config?: ZoomConfig | null; // Zoom-specific settings
}

export interface DeleteMeetingRequest {
  deleteType?: 'single' | 'series';
}

/**
 * Meeting settings update request
 * @description Structure for updating meeting settings via PUT /meetings/{uid}/settings
 */
export interface MeetingSettingsRequest {
  /** Array of organizer usernames */
  organizers?: string[];
}

/**
 * Interface representing a meeting agenda template
 */
export interface MeetingTemplate {
  /** Unique identifier for the template */
  id: string;
  /** Template title displayed to users */
  title: string;
  /** Structured markdown content for the agenda */
  content: string;
  /** Meeting type this template is designed for */
  meetingType: MeetingType;
  /** Estimated duration in minutes */
  estimatedDuration: number;
}

/**
 * Interface representing a group of templates for a specific meeting type
 */
export interface MeetingTemplateGroup {
  /** Meeting type for this group */
  meetingType: MeetingType;
  /** Array of templates for this meeting type */
  templates: MeetingTemplate[];
}

/**
 * Meeting registrant information from microproxy service
 * @description Individual registrant/guest for a meeting
 */
export interface MeetingRegistrant {
  /** Unique identifier for the registrant (auto-generated) */
  uid: string;
  /** Meeting UUID this registrant belongs to */
  meeting_id: string;
  /** Registrant's email address */
  email: string;
  /** Registrant's first name */
  first_name: string;
  /** Registrant's last name */
  last_name: string;
  /** Whether this registrant has host access */
  host: boolean;
  /** Registrant's job title */
  job_title: string | null;
  /** Registrant's organization name */
  org_name: string | null;
  /** Specific occurrence ID to invite to */
  occurrence_id: string | null;
  /** LF membership status (read-only) */
  org_is_member: boolean;
  /** Project membership status (read-only) */
  org_is_project_member: boolean;
  /** Registrant's avatar URL */
  avatar_url: string | null;
  /** Registrant's LFID username */
  username: string | null;
  /** Registrant's LinkedIn profile URL */
  linkedin_profile: string | null;
  /** Creation timestamp */
  created_at: string;
  /** Last update timestamp */
  updated_at: string;

  // Fields NOT in API - likely response-only
  /** Registrant's type */
  type: 'direct' | 'committee';
  /** Registrant Committee UID (if type is committee) */
  committee_uid?: string | null;
  /** Committee name (resolved from committee_uid) - response only */
  committee_name?: string | null;
  /** Committee role (e.g., "Member", "Chair", "Co-chair") - response only */
  committee_role?: string | null;
  /** Committee category (e.g., "Technical", "Board", "Marketing") - response only */
  committee_category?: string | null;
  /** Committee member voting status - response only */
  committee_voting_status?: string | null;
  /** Committee member appointed by - response only */
  committee_appointed_by?: string | null;
  /** Registrant's invite accepted status */
  invite_accepted: boolean | null;
  /** Registrant's attended status */
  attended: boolean | null;
  /** Registrant's RSVP (only included when include_rsvp=true) */
  rsvp?: MeetingRsvp | null;
}

/**
 * Request payload for creating a meeting registrant
 * @description Data required to add a new registrant to a meeting
 */
export interface CreateMeetingRegistrantRequest {
  /** UUID of the meeting */
  meeting_id: string;
  /** User's email address */
  email: string;
  /** User's first name */
  first_name: string;
  /** User's last name */
  last_name: string;
  /** Whether user should have host access */
  host?: boolean;
  /** User's job title */
  job_title?: string | null;
  /** User's organization */
  org_name?: string | null;
  /** Specific occurrence ID to invite to (blank = all occurrences) */
  occurrence_id?: string | null;
  /** User's avatar URL */
  avatar_url?: string | null;
  /** User's LFID */
  username?: string | null;
}

/**
 * Request payload for updating a meeting registrant
 * @description Data required for PUT request to update an existing registrant
 */
export interface UpdateMeetingRegistrantRequest {
  /** UUID of the meeting (required) */
  meeting_id: string;
  /** User's email address (required) */
  email: string;
  /** User's first name (required) */
  first_name: string;
  /** User's last name (required) */
  last_name: string;
  /** Whether user should have host access */
  host?: boolean;
  /** User's job title */
  job_title?: string | null;
  /** User's organization */
  org_name?: string | null;
  /** Specific occurrence ID to invite to */
  occurrence_id?: string | null;
  /** User's avatar URL */
  avatar_url?: string | null;
  /** User's LFID */
  username?: string | null;
  /** User's LinkedIn profile URL */
  linkedin_profile?: string | null;
}

/**
 * State types for tracking registrant changes
 */
export type RegistrantState = 'existing' | 'new' | 'modified' | 'deleted';

/**
 * Enhanced meeting registrant with state tracking
 * @description Extends MeetingRegistrant with metadata for local state management
 */
export interface MeetingRegistrantWithState extends MeetingRegistrant {
  /** Current state of this registrant */
  state: RegistrantState;
  /** Original data from API (for existing registrants) */
  originalData?: MeetingRegistrant;
  /** Temporary ID for new registrants (starts with 'temp_') */
  tempId?: string;
  /** RSVP response status for this registrant */
  rsvpStatus?: RsvpResponse;
}

/**
 * Batch update request for meeting registrants
 * @description Request payload for updating multiple registrants at once
 */
export interface BatchUpdateMeetingRegistrantsRequest {
  /** Array of registrants to update with their UIDs and change data */
  registrants: { uid: string; changes: UpdateMeetingRegistrantRequest }[];
}

/**
 * Batch delete request for meeting registrants
 * @description Request payload for deleting multiple registrants at once
 */
export interface BatchDeleteMeetingRegistrantsRequest {
  /** Array of registrant UIDs to delete */
  registrantUids: string[];
}

/**
 * Pending changes summary for registrants
 */
export interface RegistrantPendingChanges {
  /** Registrants to be created via API */
  toAdd: CreateMeetingRegistrantRequest[];
  /** Registrants to be updated via API */
  toUpdate: { uid: string; changes: UpdateMeetingRegistrantRequest }[];
  /** Registrant UIDs to be deleted via API */
  toDelete: string[];
}

/**
 * Individual operation result for batch operations
 */
export interface RegistrantOperationResult<T = unknown> {
  /** Success indicator */
  success: boolean;
  /** Result data if successful */
  data?: T;
  /** Error information if failed */
  error?: {
    message: string;
    code?: string;
    details?: unknown;
  };
  /** Original input data for context */
  input?: unknown;
}

/**
 * Batch operation response for registrant operations
 */
export interface BatchRegistrantOperationResponse<T = unknown> {
  /** Array of successful results */
  successes: T[];
  /** Array of failed operations with error details */
  failures: Array<{
    input: unknown;
    error: {
      message: string;
      code?: string;
      details?: unknown;
    };
  }>;
  /** Summary counts */
  summary: {
    total: number;
    successful: number;
    failed: number;
  };
}

/**
 * Response for meeting join URL endpoint
 * @description Contains the join URL for a specific meeting
 */
export interface MeetingJoinURL {
  /** Meeting join URL */
  link: string;
}

/**
 * Extended recurrence pattern for UI form handling
 * @description Extends MeetingRecurrence with UI-specific fields for custom pattern configuration
 */
export interface CustomRecurrencePattern extends MeetingRecurrence {
  /** UI helper: Type of recurrence pattern for form display */
  patternType?: 'daily' | 'weekly' | 'monthly';
  /** UI helper: Selected days for weekly patterns (0=Sunday, 1=Monday, etc.) - converted to/from weekly_days */
  weeklyDaysArray?: number[];
  /** UI helper: Monthly recurrence type for form display */
  monthlyType?: 'dayOfMonth' | 'dayOfWeek';
  /** UI helper: When the recurrence should end for form display */
  endType?: 'never' | 'date' | 'occurrences';
}

/**
 * Recurrence summary for display purposes
 * @description Human-readable description of the recurrence pattern
 */
export interface RecurrenceSummary {
  /** Main description (e.g., "Every 2 weeks on Monday, Wednesday") */
  description: string;
  /** End description (e.g., "Until December 31, 2024" or "For 10 occurrences") */
  endDescription: string;
  /** Full summary combining both */
  fullSummary: string;
}

/**
 * Meeting session information
 * @description Individual session within a meeting (typically for past meetings)
 */
export interface MeetingSession {
  /** Session unique identifier */
  uid: string;
  /** Session start time */
  start_time: string;
  /** Session end time */
  end_time: string;
}

/**
 * Past meeting interface
 * @description Extended meeting interface with additional fields specific to past meetings
 */
export interface PastMeeting extends Meeting {
  /** Scheduled start time for past meetings */
  scheduled_start_time: string;
  /** Scheduled end time for past meetings */
  scheduled_end_time: string;
  /** Original meeting UID (different from uid which is the past meeting occurrence UID) */
  meeting_id: string;
  /** The specific occurrence ID for recurring meetings */
  occurrence_id: string;
  /** Composite meeting and occurrence ID (e.g., "99152950841-1630560600000"); used as the canonical id downstream */
  meeting_and_occurrence_id?: string;
  /** Platform-specific meeting ID (e.g., Zoom meeting ID) */
  platform_meeting_id: string;
  /** Array of session objects with start/end times */
  sessions: MeetingSession[];
  /** Whether the requesting user attended this meeting — populated by /api/user/past-meetings only */
  user_attended?: boolean;
}

/**
 * Past meeting participant information
 * @description Individual participant who was invited/attended a past meeting
 */
export interface PastMeetingParticipant {
  /** Unique identifier for the participant */
  uid: string;
  /** Original meeting UUID this participant belongs to */
  meeting_id: string;
  /** Composite meeting and occurrence ID (e.g., "99152950841-1630560600000") */
  meeting_and_occurrence_id: string;
  /** Past meeting UUID for the specific occurrence */
  past_meeting_id: string;
  /** Participant's email address */
  email: string;
  /** Participant's first name */
  first_name: string;
  /** Participant's last name */
  last_name: string;
  /** Whether participant has host access */
  host: boolean;
  /** Participant's job title */
  job_title?: string;
  /** Participant's organization name */
  org_name?: string;
  /** Whether participant actually attended the meeting */
  is_attended: boolean;
  /** Whether participant was invited to the meeting */
  is_invited: boolean;
  /** LF membership status */
  org_is_member: boolean;
  /** Project membership status */
  org_is_project_member: boolean;
  /** Participant's avatar URL */
  avatar_url?: string;
  /** Participant's username */
  username?: string;
  /** Creation timestamp */
  created_at: string;
  /** Last update timestamp */
  updated_at: string;
}

/**
 * Past meeting participant enriched with committee membership data from meeting registrants
 */
export interface EnrichedPastMeetingParticipant extends PastMeetingParticipant {
  /** Committee name (from committee member data) */
  committee_name?: string | null;
  /** Role within the committee (from committee member data) */
  committee_role?: string | null;
  /** Voting status within the committee (from committee member data) */
  committee_voting_status?: string | null;
  /** Committee category (from committee member data) */
  committee_category?: string | null;
}

/**
 * Result of canceling a meeting occurrence
 * @description Contains the result of canceling a meeting occurrence
 */
export interface MeetingCancelOccurrenceResult {
  confirmed: boolean;
  error?: string;
}

/**
 * Recording session information
 * @description Individual session within a past meeting recording
 */
export interface RecordingSession {
  /** Session start time */
  start_time: string;
  /** Shareable URL for the recording */
  share_url: string;
  /** Total size of the session in bytes */
  total_size: number;
  /** Session UUID */
  uuid: string;
}

/**
 * Recording file information
 * @description Individual recording file from a meeting session
 */
export interface RecordingFile {
  /** Unique identifier for the recording file */
  id: string;
  /** Download URL for the recording file */
  download_url: string;
  /** Play URL for the recording file */
  play_url: string;
  /** File size in bytes */
  file_size: number;
  /** File type (e.g., MP4, M4A, CHAT, TRANSCRIPT) */
  file_type: string;
  /** Recording type (e.g., shared_screen_with_speaker_view, audio_only) */
  recording_type: string;
  /** Recording start time */
  recording_start: string;
  /** Recording end time */
  recording_end: string;
  /** Recording status */
  status: string;
  /** Platform-specific meeting ID */
  platform_meeting_id: string;
}

/**
 * Past meeting recording information
 * @description Recording data for a completed past meeting
 */
export interface PastMeetingRecording {
  /** Unique identifier for the recording */
  uid: string;
  /** Past meeting UID this recording belongs to */
  past_meeting_id: string;
  /** Platform (e.g., Zoom) */
  platform: string;
  /** Platform-specific meeting ID */
  platform_meeting_id: string;
  /** Number of recording files */
  recording_count: number;
  /** Array of recording files */
  recording_files: RecordingFile[];
  /** Array of recording sessions */
  sessions: RecordingSession[];
  /** Total size of all recordings in bytes */
  total_size: number;
  /** Creation timestamp */
  created_at: string;
  /** Last update timestamp */
  updated_at: string;
}

/**
 * Summary data for a past meeting
 * @description Contains the AI-generated summary content and metadata
 */
export interface SummaryData {
  /** Summary title */
  title: string;
  /** AI-generated summary content in markdown format */
  content: string;
  /** User-edited summary content (can be empty) */
  edited_content: string;
  /** Zoom document URL for the summary */
  doc_url: string;
  /** Summary generation start time */
  start_time: string;
  /** Summary generation end time */
  end_time: string;
}

/**
 * Zoom configuration for meeting summary
 * @description Platform-specific configuration for Zoom summaries
 */
export interface ZoomSummaryConfig {
  /** Zoom meeting ID */
  meeting_id: string;
  /** Zoom meeting UUID */
  meeting_uuid: string;
}

/**
 * Past meeting summary information
 * @description AI-generated summary data for a completed past meeting
 */
export interface PastMeetingSummary {
  /** Unique identifier for the summary */
  uid: string;
  /** Original meeting UID */
  meeting_id: string;
  /** Past meeting UID this summary belongs to */
  past_meeting_id: string;
  /** Platform (e.g., Zoom) */
  platform: string;
  /** Whether the summary has been approved */
  approved: boolean;
  /** Whether the summary requires approval before viewing */
  requires_approval: boolean;
  /** Whether notification email was sent */
  email_sent: boolean;
  /** Access password for the summary */
  password: string;
  /** Summary content and metadata */
  summary_data: SummaryData;
  /** Zoom-specific configuration (optional) */
  zoom_config?: ZoomSummaryConfig;
  /** Creation timestamp */
  created_at: string;
  /** Last update timestamp */
  updated_at: string;
}

/**
 * Update past meeting summary request
 * @description Request payload for updating a past meeting summary's edited content and approval status
 */
export interface UpdatePastMeetingSummaryRequest {
  /** Updated summary content (HTML/text) - optional when only approving */
  edited_content?: string;
  /** Approval status - optional when only editing content */
  approved?: boolean;
}

/**
 * RSVP response type
 * @description User's response to a meeting invitation
 */
export type RsvpResponse = 'accepted' | 'maybe' | 'declined';

/**
 * RSVP scope type
 * @description Defines which occurrences of a recurring meeting the RSVP applies to
 */
export type RsvpScope = 'single' | 'all' | 'this_and_following';

/**
 * RSVP counts by response type
 * @description Aggregated counts of RSVPs grouped by response
 */
export interface RsvpCounts {
  /** Number of accepted RSVPs */
  accepted: number;
  /** Number of declined RSVPs */
  declined: number;
  /** Number of maybe RSVPs */
  maybe: number;
  /** Total number of RSVPs */
  total: number;
}

/**
 * Meeting RSVP information
 * @description User's RSVP response for a meeting
 */
export interface MeetingRsvp {
  /** Unique identifier for the RSVP */
  id: string;
  /** Meeting UUID this RSVP belongs to */
  meeting_id: string;
  /** Combined meeting and occurrence identifier (e.g., "95156357074" or "95156357074_1707321600000") */
  meeting_and_occurrence_id?: string;
  /** User's registrant ID */
  registrant_id: string;
  /** User's username */
  username: string;
  /** User's display name */
  name?: string;
  /** User's email address */
  email: string;
  /** User's RSVP response */
  response_type: RsvpResponse;
  /** Scope of the RSVP (which occurrences it applies to) */
  scope: RsvpScope;
  /** Occurrence ID (empty string when no specific occurrence) */
  occurrence_id?: string;
  /** Creation timestamp */
  created_at: string;
  /** Last modification timestamp (API field name) */
  modified_at?: string;
  /** Last update timestamp (alias for modified_at) */
  updated_at?: string;
  /** Timestamp of the RSVP response */
  response_date?: string;
}

/**
 * Request payload for creating a meeting RSVP
 * @description Data required to create or update a meeting RSVP
 */
export interface CreateMeetingRsvpRequest {
  /** User's registrant ID (optional - backend derives from username if not provided) */
  registrant_id?: string;
  /** User's username (optional - backend derives from authenticated user if not provided) */
  username?: string;
  /** User's email (optional - backend derives from authenticated user if not provided) */
  email?: string;
  /** The specific occurrence ID to RSVP for (optional) */
  occurrence_id?: string;
  /** Scope of the RSVP */
  scope: RsvpScope;
  /** User's RSVP response */
  response: RsvpResponse;
}

// ============================================================================
// ITX Meeting Response Interfaces (Goa endpoint shape)
// ============================================================================

/**
 * Request payload sent to the ITX meeting response endpoint
 * @description POST /itx/meetings/{meeting_id}/responses
 */
export interface ITXCreateMeetingResponseRequest {
  /** User's RSVP response */
  response: RsvpResponse;
  /** Scope of the RSVP */
  scope: RsvpScope;
  /** User's registrant ID */
  registrant_id: string;
  /** Occurrence ID for recurring meetings; the upstream meeting-service concatenates it with the meeting ID when calling ITX */
  occurrence_id?: string;
}

/**
 * Response shape from the ITX meeting response endpoint
 * @description Result returned by POST /itx/meetings/{meeting_id}/responses
 */
export interface ITXMeetingResponseResult {
  /** Unique identifier for the response */
  id: string;
  /** Meeting ID this response belongs to */
  meeting_id: string;
  /** User's registrant ID */
  registrant_id: string;
  /** User's username */
  username: string;
  /** User's email address */
  email: string;
  /** User's RSVP response */
  response: RsvpResponse;
  /** Scope of the RSVP */
  scope: RsvpScope;
  /** Occurrence ID (for recurring meetings) */
  occurrence_id?: string;
  /** Creation timestamp */
  created_at: string;
  /** Last update timestamp */
  updated_at: string;
}

// ============================================================================
// URL Metadata Interfaces (for resource link resolution)
// ============================================================================

/** Single URL metadata result */
export interface UrlMetadata {
  /** The original URL */
  url: string;
  /** Extracted page title, or null if unavailable */
  title: string | null;
  /** Domain name (without www prefix) */
  domain: string;
}

/** Request body for POST /api/url-metadata */
export interface UrlMetadataRequest {
  urls: string[];
}

/** Response body for POST /api/url-metadata */
export interface UrlMetadataResponse {
  results: UrlMetadata[];
}

/**
 * Response from public past meeting endpoint
 * @description Returns meeting details with tiered access — full_access indicates whether
 * the user has permission to view enrichment data (summary, recording, attachments)
 * via the existing authenticated endpoints
 */
export interface PublicPastMeetingResponse {
  meeting: PastMeeting;
  project: { name: string; slug: string; logo_url: string; uid: string; parent_uid: string };
  full_access: boolean;
}

/**
 * Parsed section from an AI-generated meeting summary
 * @description Represents a structured section extracted from markdown `##` headings
 * in meeting summaries, with visual styling metadata for display
 */
export interface SummarySection {
  /** Section heading text (from ## heading) */
  heading: string;
  /** Section body content (markdown between headings) */
  content: string;
  /** Font Awesome icon class for the section */
  icon: string;
  /** Tailwind border-left color class */
  borderColor: string;
  /** Tailwind text color class for the icon */
  iconColor: string;
}