export type AuthUser = {
  id: number
  name: string
  roles: Record<string, boolean>
  class_section_id?: number | null
  class_section_name?: string | null
}

export type LoginSuccess = {
  status: true
  token: string
  user: AuthUser
}

export type LoginFailure = {
  status: false
  message?: string
}

export type LoginResponse = LoginSuccess | LoginFailure

export type ApiEnvelope<T> = {
  status: boolean
  message?: string
  data?: T
}

export type DashboardPayload = {
  dashboard: {
    route: string | null
    role: string | null
    role_slug: string | null
    roles: string[]
  }
}

export type LandingPageRecord = {
  role?: string | null
  dashboard?: string | null
  summary?: Record<string, unknown> | null
}

export type LandingPagePayload = {
  landing?: LandingPageRecord
}

export type LandingPageResponse = ApiEnvelope<LandingPagePayload>

export type NavItem = {
  id: number
  menu_parent_id: number | null
  label: string
  url: string | null
  icon_class: string | null
  target: string | null
  sort_order: number
  is_enabled: number
  children: NavItem[]
}

export type NavMenuResponse = ApiEnvelope<{ items: NavItem[] }>

export type NavBuilderRoleOption = {
  id: number
  name: string
}

export type NavBuilderParentOption = {
  id: number
  label: string
}

export type NavBuilderItem = {
  id: number
  label: string
  url?: string | null
  icon_class?: string | null
  target?: string | null
  menu_parent_id?: number | null
  parent_id?: number | null
  parent_label?: string | null
  sort_order?: number
  order?: number
  is_enabled?: number | boolean
  enabled?: boolean
  depth?: number
  roles?: {
    ids?: number[]
    names?: string[]
  }
  raw?: Record<string, unknown>
}

export type NavBuilderData = {
  items: NavBuilderItem[]
  roles: NavBuilderRoleOption[]
  parentOptions: NavBuilderParentOption[]
}

export type NavBuilderDataResponse = ApiEnvelope<{ data: NavBuilderData }>
export type NavBuilderSaveResponse = ApiEnvelope<{ id: number }>
export type NavBuilderDeleteResponse = ApiEnvelope<null>

export type AdministratorDashboardMetricsResponse = {
  counts?: {
    students?: number
    teachers?: number
    teacherAssistants?: number
    admins?: number
    parents?: number
  }
  recentActivities?: Array<{
    login_time?: string | null
    email?: string | null
  }>
  meta?: {
    schoolYear?: string | null
    semester?: string | null
  }
}

export type AdministratorDashboardSearchResponse = {
  query: string
  results: {
    users?: Record<string, unknown>[]
    students?: Record<string, unknown>[]
    parents?: Record<string, unknown>[]
    staff?: Record<string, unknown>[]
    emergency_contacts?: Record<string, unknown>[]
  }
  scope_used?: string
  scope_label?: string
  total_found?: number
}

export type AdministratorAbsenceRow = {
  date?: string | null
  status?: string | null
  reason?: string | null
}

export type AdministratorAbsenceFormResponse = {
  admin_name?: string | null
  semester?: string | null
  schoolYear?: string | null
  /** Laravel may return snake_case */
  school_year?: string | null
  existing?: AdministratorAbsenceRow[]
  availableDates?: string[]
  available_dates?: string[]
  /** Optional labels for POST `reason_type` (from API or empty to use client defaults). */
  reason_types?: Record<string, string>
}

export type AdministratorAbsenceSubmitResponse = {
  message?: string
  saved?: number
  dates?: string[]
}

export type AdministratorDailyAttendanceEntry = {
  date?: string | null
  status?: string | null
  reason?: string | null
  is_reported?: string | null
  modified_by?: string | number | null
}

export type AdministratorDailyAttendanceSummary = {
  total_presence?: number
  total_late?: number
  total_absence?: number
  total_attendance?: number
}

export type AdministratorDailyAttendanceStudent = {
  id: number
  firstname?: string | null
  lastname?: string | null
  school_id?: string | null
}

export type AdministratorDailyAttendanceSection = {
  id?: number
  class_id?: number
  class_section_id?: number | string
  class_section_name?: string | null
}

export type AdministratorDailyAttendanceResponse = {
  attendance_data?: Record<string, Record<string, AdministratorDailyAttendanceEntry[]>>
  attendance_record?: Record<string, Record<string, AdministratorDailyAttendanceSummary>>
  students_by_section?: Record<string, AdministratorDailyAttendanceStudent[]>
  grades?: Record<string, AdministratorDailyAttendanceSection[]>
  dates_by_section?: Record<string, string[]>
  date_list?: string[]
  no_school_days?: Record<string, string>
  total_passed_days?: number
  semester?: string | null
  school_year?: string | null
  current_admin_name?: string | null
}

export type AdministratorAdminAttendanceRow = {
  user_id?: number
  firstname?: string | null
  lastname?: string | null
  email?: string | null
  role_name?: string | null
  role_slug?: string | null
  status?: string | null
  reason?: string | null
  date?: string | null
}

export type AdministratorAdminAttendanceResponse = {
  semester?: string | null
  school_year?: string | null
  date?: string | null
  admins_grid?: AdministratorAdminAttendanceRow[]
}

/** Staff teacher daily grid — `GET /api/v1/attendance/staff/teachers` */
export type TeacherStaffAttendanceRow = {
  teacher_id?: number
  firstname?: string | null
  lastname?: string | null
  position?: string | null
  status?: string | null
  reason?: string | null
}

export type TeacherStaffAttendanceResponse = {
  semester?: string | null
  school_year?: string | null
  date?: string | null
  class_section_id?: number | null
  locked?: boolean
  /** Section id → label */
  sections?: Record<string, string>
  grid?: TeacherStaffAttendanceRow[]
}

/** Monthly admin/teacher grid payload — `GET /api/v1/attendance/staff/month-overview` */
export type StaffMonthlyCell = { status?: string | null }
export type StaffMonthlyTeacherRow = {
  user_id?: number
  teacher_id?: number
  name?: string | null
  position?: string | null
  cells?: Record<string, StaffMonthlyCell>
  totals?: { p?: number; a?: number; l?: number }
}
export type StaffMonthlySection = {
  section_code?: string
  label?: string
  teachers?: StaffMonthlyTeacherRow[]
}
export type StaffMonthlyAdminRow = {
  user_id?: number
  name?: string | null
  role?: string | null
  cells?: Record<string, StaffMonthlyCell>
  totals?: { p?: number; a?: number; l?: number }
}
export type StaffMonthlyOverviewPayload = {
  filters?: {
    semester?: string
    school_year?: string
    range_label?: string
    month_label?: string
    range_start?: string
    range_end?: string
  }
  sundays?: string[]
  noSchoolDays?: string[]
  no_school_days?: string[]
  sections?: StaffMonthlySection[]
  admins?: StaffMonthlyAdminRow[]
  missingYear?: boolean
  schoolYears?: Array<{ school_year?: string } | string>
  isCurrentYear?: boolean
}

export type AttendanceViolationStudentRow = Record<string, unknown>
export type AttendanceViolationsResponse = {
  students?: AttendanceViolationStudentRow[]
  school_year?: string
  semester?: string
  debug?: Record<string, unknown>
}

export type ParentAttendanceAdminReportRow = Record<string, unknown>

export type EarlyDismissalGroup = Record<string, Array<Record<string, unknown>>>
export type EarlyDismissalsResponse = {
  groups?: EarlyDismissalGroup
  schoolYear?: string
  semester?: string
  signatureByDate?: Record<string, { filename?: string; original_name?: string }>
}

export type AttendanceCommentTemplate = {
  id?: number
  min_score?: number
  max_score?: number
  template_text?: string
  is_active?: boolean
}

export type AttendanceCommentTemplatesResponse = {
  templates?: AttendanceCommentTemplate[]
}

export type ParentAttendanceRow = {
  firstname: string
  lastname: string
  date: string
  status: string
  reason: string | null
}

export type ParentAttendanceResponse = {
  ok: true
  attendance: ParentAttendanceRow[]
  schoolYears: { school_year: string }[]
  selectedYear: string | null
}

/** Laravel `User::toArray()` for the logged-in parent (password hidden server-side). */
export type ParentProfileRecord = {
  id?: number
  firstname?: string | null
  lastname?: string | null
  email?: string | null
  cellphone?: string | null
  city?: string | null
  state?: string | null
  zip?: string | null
  address_street?: string | null
}

export type ParentProfileResponse = {
  ok: true
  profile: ParentProfileRecord | null
}

export type ParentInvoiceRow = {
  id: number
  invoice_number?: string | null
  balance?: number
  status?: string | null
  due_date?: string | null
}

export type ParentInvoicesResponse = {
  ok: true
  invoices: ParentInvoiceRow[]
}

export type ParentEnrollmentStudent = {
  id: number
  firstname: string
  lastname: string
  dob?: string | null
  gender?: string | null
  registration_grade?: string | null
  class_section?: string | null
  enrollment_status?: string | null
  admission_status?: string | null
  disable_enroll?: boolean
}

export type ParentEnrollmentsResponse = {
  ok: true
  students: ParentEnrollmentStudent[]
  schoolYears: { school_year: string }[]
  selectedYear: string | null
}

export type ContactSubmitResponse = {
  status: boolean
  message?: string
}

export type BroadcastEmailParentOption = {
  id: number
  firstname?: string | null
  lastname?: string | null
  email?: string | null
  school_id?: string | null
}

export type BroadcastEmailSenderOption = {
  key: string
  label: string
}

export type BroadcastEmailOptionsResponse = {
  ok: true
  parents: BroadcastEmailParentOption[]
  fromOptions: BroadcastEmailSenderOption[]
}

export type BroadcastEmailSendResponse = {
  ok: boolean
  message?: string
  stats?: {
    mode?: string
    sent?: number
    attempted?: number
    failed?: number
  }
}

export type SchoolCalendarDetailRow = {
  id: number
  title: string
  description?: string
  event_type?: string | null
  date: string
  notify_parent?: number
  notify_teacher?: number
  notify_admin?: number
  no_school?: number
  semester?: string
  school_year?: string
  created_at?: string | null
  updated_at?: string | null
}

export type SchoolCalendarOptionsResponse = ApiEnvelope<{
  event_types: string[]
  defaults: {
    school_year?: string | null
    semester?: string | null
  }
}>

export type SchoolCalendarListResponse = ApiEnvelope<{
  events: SchoolCalendarEventRow[]
}>

export type SchoolCalendarShowResponse = ApiEnvelope<{
  event: SchoolCalendarDetailRow
}>

export type ClassSectionRow = {
  id: number
  class_id?: number | null
  class_section_id?: number | null
  class_section_name?: string | null
  class_name?: string | null
  semester?: string | null
  school_year?: string | null
  created_at?: string | null
  updated_at?: string | null
}

export type ClassSectionsResponse = ApiEnvelope<{
  sections: ClassSectionRow[]
  meta?: {
    current_page?: number
    per_page?: number
    total?: number
    last_page?: number
  }
}>

export type ClassSectionShowResponse = ApiEnvelope<{
  section: ClassSectionRow
}>

export type StudentAssignmentRow = {
  student_id: number
  name: string
  age?: number | string | null
  email?: string | null
  phone?: string | null
  registration_grade?: string | null
  class_section_name?: string | null
  class_section_names?: string[]
  class_section_ids?: number[]
  new_student?: string | null
  registration_date?: string | null
  school_year?: string | null
  semester?: string | null
}

export type StudentAssignmentOption = {
  id: number
  class_section_id: number
  class_section_name: string
  school_year?: string | null
}

export type StudentAssignmentsResponse = {
  ok: true
  students: StudentAssignmentRow[]
  classes: StudentAssignmentOption[]
  schoolYears: string[]
  selectedYear?: string | null
  currentYear?: string | null
  isCurrentYear?: boolean
}

export type ExamDraftRow = {
  id: number
  teacher_id: number
  class_section_id: number
  class_section_name?: string | null
  semester?: string | null
  school_year?: string | null
  exam_type?: string | null
  draft_title?: string | null
  description?: string | null
  teacher_file?: string | null
  teacher_filename?: string | null
  status?: string | null
  admin_id?: number | null
  admin_comments?: string | null
  reviewed_at?: string | null
  final_file?: string | null
  final_filename?: string | null
  final_pdf_file?: string | null
  version?: number | null
  previous_draft_id?: number | null
  is_legacy?: boolean | number | null
  teacher_first?: string | null
  teacher_last?: string | null
  admin_first?: string | null
  admin_last?: string | null
}

export type ExamDraftAdminResponse = {
  ok: true
  drafts: ExamDraftRow[]
  class_sections: Array<{ class_section_id: number; class_section_name: string }>
  legacy_by_class: Record<
    string,
    {
      class_section_id: number
      class_section_name: string
      items: ExamDraftRow[]
    }
  >
  exam_types: string[]
  status_options: string[]
  school_year?: string | null
  semester?: string | null
  allowed_extensions?: string[]
  max_upload_bytes?: number
}

export type GradingOverviewStudentRow = {
  id: number
  school_id?: string | null
  firstname?: string | null
  lastname?: string | null
  class_id?: number
  ptap?: number | string | null
  semester_score?: number | string | null
  attendance?: number | string | null
  homework_avg?: number | string | null
  project_avg?: number | string | null
  quiz_avg?: number | string | null
  participation?: number | string | null
  midterm_exam?: number | string | null
  final_exam?: number | string | null
  matched_biz_csid?: number | null
  matched_pk_csid?: number | null
  placement_level?: string | null
}

export type GradingOverviewResponse = {
  ok: true
  grades: Record<string, Array<{ class_section_id: number; class_section_name: string }>>
  students_by_section: Record<string, GradingOverviewStudentRow[]>
  semester?: string | null
  school_year?: string | null
  requested_class_id?: number | null
  semester_options?: string[]
  scores_released?: boolean
  scores_released_fall?: boolean
  scores_released_spring?: boolean
  score_locks?: Record<string, boolean>
}

export type IpBanRow = {
  id: number
  ip_address?: string | null
  attempts?: number
  last_attempt_at?: string | null
  blocked_until?: string | null
  is_active?: boolean
  created_at?: string | null
  updated_at?: string | null
}

export type IpBansResponse = ApiEnvelope<{
  bans: IpBanRow[]
  meta?: {
    current_page?: number
    per_page?: number
    total?: number
    last_page?: number
  }
}>

export type LateSlipLogRow = {
  id: number
  school_year?: string | null
  semester?: string | null
  student_name?: string | null
  slip_date?: string | null
  time_in?: string | null
  grade?: string | null
  reason?: string | null
  admin_name?: string | null
  printed_by?: string | null
  printed_at?: string | null
  created_at?: string | null
  updated_at?: string | null
}

export type LateSlipLogsResponse = ApiEnvelope<{
  logs: LateSlipLogRow[]
  meta?: {
    current_page?: number
    per_page?: number
    total?: number
    last_page?: number
  }
}>

export type UserListRow = {
  user?: {
    id?: number
    firstname?: string | null
    lastname?: string | null
    email?: string | null
    school_id?: string | number | null
    status?: string | null
    cellphone?: string | null
    gender?: string | null
    address_street?: string | null
    city?: string | null
    state?: string | null
    zip?: string | null
    school_year?: string | null
    semester?: string | null
    [key: string]: unknown
  } | null
  roles?: Array<string | { id?: number; name?: string | null; slug?: string | null }>
  role_ids?: number[]
  parent_type?: string
  second_from_parents?: string
}

export type UsersResponse = {
  ok: true
  users: UserListRow[]
}

export type NotificationAdminRow = {
  id: number
  firstname?: string | null
  lastname?: string | null
  email?: string | null
}

export type NotificationAlertsResponse = {
  admins: NotificationAdminRow[]
  subjects: Record<string, string>
  assignedSubjects: Record<string, Record<string, boolean>>
  tableReady: boolean
}

export type PrintNotificationRecipientsResponse = {
  admins: NotificationAdminRow[]
  assigned: Record<string, boolean>
  tableReady: boolean
}

export type FamilyGuardianRow = {
  user_id?: number
  firstname?: string | null
  lastname?: string | null
  email?: string | null
  cellphone?: string | null
  relation?: string | null
  is_primary?: boolean
  receive_emails?: boolean
  receive_sms?: boolean
  address_street?: string | null
  city?: string | null
  state?: string | null
  zip?: string | null
}

export type FamilyStudentRow = {
  id?: number
  firstname?: string | null
  lastname?: string | null
  school_id?: string | null
  class_section_name?: string | null
  [key: string]: unknown
}

export type FamilyRow = {
  id: number
  family_code?: string
  household_name?: string
  address_line1?: string
  address_line2?: string
  city?: string
  state?: string
  postal_code?: string
  country?: string
  primary_phone?: string
  preferred_lang?: string
  preferred_contact_method?: string
  is_active?: boolean
  is_primary_home?: boolean
  guardians?: FamilyGuardianRow[]
  students?: FamilyStudentRow[]
  [key: string]: unknown
}

export type FamilyAdminIndexResponse = ApiEnvelope<{
  student?: { id?: number; firstname?: string | null; lastname?: string | null } | null
  families: FamilyRow[]
  guardians: Record<string, unknown>[]
  students: Record<string, unknown>[]
  searchStudents: Record<string, unknown>[]
  searchGuardians: NotificationAdminRow[]
  resolved_student_id?: number | null
}>

export type FamilySearchSuggestionItem = {
  type: 'student' | 'guardian'
  id: number
  label: string
  sub?: string
}

export type FamilySearchResponse = {
  items: FamilySearchSuggestionItem[]
}

/** GET `/api/v1/families/import-legacy` — metadata for the legacy import UI (optional; SPA uses defaults if unavailable). */
export type FamilyLegacyImportMetaResponse = {
  instructions?: string | null
  instructions_html?: string | null
  accepted_extensions?: string[]
  accepted_mime_types?: string[]
  max_file_bytes?: number | null
  template_url?: string | null
  template_download_url?: string | null
  columns?: string[]
  dry_run_supported?: boolean
}

export type FamilyLegacyImportRowError = {
  row?: number
  line?: number
  message?: string
  error?: string
}

/** POST `/api/v1/families/import-legacy` (multipart) response */
export type FamilyLegacyImportResult = {
  ok?: boolean
  message?: string
  imported?: number
  imported_count?: number
  skipped?: number
  skipped_count?: number
  failed?: number
  errors?: FamilyLegacyImportRowError[]
  validation_errors?: FamilyLegacyImportRowError[]
}

export type PaypalTransactionRow = {
  id: number
  transaction_id?: string | null
  order_id?: string | null
  parent_school_id?: string | null
  payer_email?: string | null
  amount?: number
  net_amount?: number
  currency?: string | null
  status?: string | null
  event_type?: string | null
  created_at?: string | null
}

export type PaypalTransactionsResponse = {
  ok: true
  transactions: PaypalTransactionRow[]
  pagination?: {
    current_page?: number
    per_page?: number
    total?: number
    last_page?: number
  }
}

export type RemovedStudentRow = {
  id: number
  school_id?: string | null
  firstname?: string | null
  lastname?: string | null
  gender?: string | null
  age?: number | string | null
  class_sections?: string[]
  class_section_name?: string | null
}

export type RemovedStudentsResponse = {
  ok: true
  active_students: RemovedStudentRow[]
  removed_students: RemovedStudentRow[]
  school_year?: string | null
}

export type StudentPromotionTotalsRow = {
  class_id?: number | null
  class_section_id?: number | null
  class_section_name?: string | null
  total?: number
}

export type StudentPromotionTotalsResponse = {
  ok: true
  year?: string | null
  rows: StudentPromotionTotalsRow[]
}

export type StudentDirectoryRow = {
  id: number
  school_id?: string | null
  firstname?: string | null
  lastname?: string | null
  dob?: string | null
  age?: number | null
  gender?: string | null
  is_active?: boolean | number | null
  registration_grade?: string | null
  is_new?: boolean | number | null
  photo_consent?: boolean | number | null
  parent_id?: number | null
  registration_date?: string | null
  tuition_paid?: boolean | number | null
  semester?: string | null
  year_of_registration?: string | number | null
  school_year?: string | null
  medical_conditions?: string | null
  allergies?: string | null
}

export type StudentDirectoryResponse = {
  ok: true
  students: StudentDirectoryRow[]
  school_year?: string | null
  current_year?: string | null
}

export type StudentParentResponse = {
  ok: true
  student_id: number
  parent?: {
    id?: number
    firstname?: string | null
    lastname?: string | null
    email?: string | null
    cellphone?: string | null
  } | null
}

export type StudentEmergencyContactResponse = {
  ok: true
  student_id: number
  rows: Array<Record<string, unknown>>
}

export type TeacherClassAssignmentRow = {
  teacher_id: number
  firstname?: string | null
  lastname?: string | null
  name?: string | null
  email?: string | null
  cellphone?: string | null
  role?: string | null
  school_year?: string | null
  main_assignments?: Array<{
    section_id?: number
    class_section_name?: string | null
    role?: string | null
    semester?: string | null
    school_year?: string | null
  }>
  ta_assignments?: Array<{
    section_id?: number
    class_section_name?: string | null
    role?: string | null
    semester?: string | null
    school_year?: string | null
  }>
}

export type TeacherClassOption = {
  class_section_id: number
  class_section_name: string
  class_id?: number | null
  class_name?: string | null
  teacher_role?: string | null
  school_year?: string | null
  semester?: string | null
}

export type TeacherClassAssignmentsResponse = {
  ok: true
  school_year?: string | null
  teachers: TeacherClassAssignmentRow[]
  classes: TeacherClassOption[]
}

export type TeacherSubmissionTeacherRow = {
  id: number
  label: string
  role_key?: string | null
}

export type TeacherSubmissionStatus = {
  label?: string | null
  badge?: string | null
  detail?: string | null
  completed?: boolean
}

export type TeacherSubmissionReportRow = {
  class_section?: string | null
  class_section_id?: number
  teachers?: TeacherSubmissionTeacherRow[]
  midterm_score_status?: TeacherSubmissionStatus | null
  midterm_comment_status?: TeacherSubmissionStatus | null
  participation_status?: TeacherSubmissionStatus | null
  ptap_comment_status?: TeacherSubmissionStatus | null
  attendance_status?: TeacherSubmissionStatus | null
  missing_items?: string[]
  student_count?: number
}

export type TeacherSubmissionsResponse = {
  rows: TeacherSubmissionReportRow[]
  semester?: string | null
  schoolYear?: string | null
  notificationHistory?: Record<string, unknown>
  summary?: {
    total_items?: number
    missing_items?: number
    submitted_items?: number
    submission_percentage?: number
  }
}

export type SubjectCurriculumClassRow = {
  id: number
  class_name: string
  school_year?: string | null
}

export type SubjectCurriculumEntryRow = {
  id: number
  class_id: number
  class_name?: string | null
  subject: string
  unit_number?: number | string | null
  unit_title?: string | null
  chapter_name: string
  school_year?: string | null
}

export type SubjectCurriculumResponse = {
  ok: true
  classes: SubjectCurriculumClassRow[]
  entries: SubjectCurriculumEntryRow[]
  subject_labels: Record<string, string>
  school_year?: string | null
  school_years?: string[]
}

export type PublicCompetitionRow = {
  id: number
  title?: string | null
  class_section_id?: number | null
  semester?: string | null
  school_year?: string | null
  is_published?: boolean | number | null
  is_locked?: boolean | number | null
  published_at?: string | null
  [key: string]: unknown
}

export type PublicCompetitionIndexResponse = {
  status: boolean
  data?: {
    competitions: PublicCompetitionRow[]
  }
  message?: string
}

export type PublicCompetitionWinnerRow = {
  student_id?: number
  class_section_id?: number
  rank?: number
  score?: number | string | null
  prize_amount?: number | string | null
  firstname?: string | null
  lastname?: string | null
  class_section_name?: string | null
  name?: string | null
  [key: string]: unknown
}

export type PublicCompetitionShowResponse = {
  status: boolean
  data?: {
    competition: PublicCompetitionRow
    winners_by_class: Record<string, PublicCompetitionWinnerRow[]>
    section_map: Record<string, string>
    question_counts: Record<string, number>
  }
  message?: string
}

export type CompetitionScoresIndexCompetitionRow = {
  id: number
  title?: string | null
  class_section_id?: number | null
  is_locked?: boolean | number | null
  is_published?: boolean | number | null
  [key: string]: unknown
}

export type CompetitionScoresIndexResponse = {
  ok: true
  competitions: CompetitionScoresIndexCompetitionRow[]
  activeClassId?: number
  activeClassName?: string | null
  questionCounts?: Record<string, number>
  scoreCounts?: Record<string, number>
  studentTotal?: number
  sectionMap?: Record<string, string>
  schoolYear?: string | null
  semester?: string | null
  hasClasses?: boolean
}

export type CompetitionWinnerAdminCompetitionRow = CompetitionScoresIndexCompetitionRow & {
  semester?: string | null
  school_year?: string | null
  start_date?: string | null
  end_date?: string | null
  published_at?: string | null
  locked_at?: string | null
}

export type CompetitionWinnerAdminIndexResponse = {
  ok: boolean
  competitions?: CompetitionWinnerAdminCompetitionRow[]
  sectionMap?: Record<string, string>
  message?: string
}

export type CompetitionWinnerAdminClassSectionRow = {
  class_section_id?: number
  class_section_name?: string | null
}

export type CompetitionWinnerAdminClassRow = {
  class_section_id: number
  class_section_name: string
  student_count: number
  auto_winners: number
  override_winners?: number | null
  final_winners: number
  question_count?: number | null
  prize_1?: number | null
  prize_2?: number | null
  prize_3?: number | null
  prize_4?: number | null
  prize_5?: number | null
  prize_6?: number | null
}

export type CompetitionWinnerAdminFormResponse = {
  ok: boolean
  mode?: 'create' | 'edit'
  competition?: PublicCompetitionRow | null
  classSections?: CompetitionWinnerAdminClassSectionRow[]
  classRows?: CompetitionWinnerAdminClassRow[]
  defaultSemester?: string | null
  defaultSchoolYear?: string | null
  message?: string
}

export type CompetitionWinnerAdminActionResponse = {
  ok: boolean
  id?: number
  message?: string
}

export type CompetitionWinnerAdminScoresResponse = {
  ok: boolean
  competition?: PublicCompetitionRow
  students?: CompetitionScoreStudentRow[]
  scoreMap?: Record<string, number | string>
  classSections?: CompetitionWinnerAdminClassSectionRow[]
  activeClassSectionId?: number
  classSectionName?: string | null
  classSelectionLocked?: boolean
  classStudentCount?: number
  classAutoWinners?: number
  classOverrideWinners?: number | null
  classFinalWinners?: number
  classQuestionCount?: number | null
  classPrizeMap?: Record<string, number | null>
  message?: string
}

export type CompetitionWinnerPreviewStudentRow = {
  student_id?: number
  name?: string | null
  score?: number | string | null
  rank?: number
  prize_amount?: number | string | null
}

export type CompetitionWinnerAdminPreviewResponse = {
  ok: boolean
  competition?: PublicCompetitionRow
  classMap?: Record<string, string>
  classCounts?: Record<string, number>
  overrideMap?: Record<string, number>
  questionCounts?: Record<string, number>
  prizeMap?: Record<string, Record<string, number | null>>
  winnersCountByClass?: Record<string, number>
  rankedByClass?: Record<string, CompetitionWinnerPreviewStudentRow[]>
  topByClass?: Record<string, CompetitionWinnerPreviewStudentRow[]>
  message?: string
}

export type CompetitionWinnerAdminWinnerRow = PublicCompetitionWinnerRow & {
  school_id?: string | null
  photo_consent?: number | boolean | null
}

export type CompetitionWinnerAdminWinnersResponse = {
  ok: boolean
  competition?: PublicCompetitionRow
  rows?: CompetitionWinnerAdminWinnerRow[]
  sectionMap?: Record<string, string>
  message?: string
}

export type CompetitionWinnerExportQuizResponse = {
  ok: boolean
  message?: string
  quizIndexes?: Record<string, number>
}

export type CompetitionScoreStudentRow = {
  id?: number
  student_id?: number
  school_id?: string | null
  firstname?: string | null
  lastname?: string | null
}

export type CompetitionScoresEditResponse = {
  ok: boolean
  competition?: PublicCompetitionRow
  students?: CompetitionScoreStudentRow[]
  scoreMap?: Record<string, number | string>
  classSectionId?: number
  classSectionName?: string | null
  classStudentCount?: number
  questionCount?: number | null
  classSelectionLocked?: boolean
  isLocked?: boolean
  schoolYear?: string | null
  semester?: string | null
  message?: string
}

/** Loose JSON payloads for complex parent dashboards (events, registration, attendance report form). */
export type ParentEventsResponse = Record<string, unknown>
export type ParentRegistrationResponse = Record<string, unknown>
export type ParentAttendanceReportFormResponse = {
  ok: true
  students?: ParentEnrollmentStudent[]
  today?: string
  sundays?: string[]
  defaultDate?: string
  myReports?: Record<string, unknown>[]
  cutoffThreshold?: string | null
}

export type ParentEmergencyContactRow = {
  id: number
  name?: string
  cellphone?: string
  email?: string | null
  relation?: string | null
}

export type ParentEmergencyContactsResponse = {
  ok: true
  contacts: ParentEmergencyContactRow[]
}

export type ParentAttendanceReportsListResponse = {
  ok: true
  reports: Record<string, unknown>[]
}

/** `GET /api/v1/parents/authorized-users` — envelope from BaseApiController. */
export type ParentAuthorizedUserRow = {
  id?: number
  user_id?: number
  email?: string | null
  created_at?: string | null
  updated_at?: string | null
  [key: string]: unknown
}

export type ParentAuthorizedUsersApiResponse = ApiEnvelope<ParentAuthorizedUserRow[]>

export type ParentMessageRow = {
  id?: number | null
  message_number?: string | number | null
  sender_name?: string | null
  recipient_name?: string | null
  subject?: string | null
  message?: string | null
  sent_datetime?: string | null
  read_status?: boolean
  priority?: string | null
}

export type ParentMessagesResponse = ApiEnvelope<{
  messages: ParentMessageRow[]
  meta?: Record<string, unknown> | null
}>

export type SchoolCalendarEventRow = {
  id?: number | null
  title: string
  start: string
  description?: string
  backgroundColor?: string | null
  extendedProps?: {
    event_type?: string
    backgroundColor?: string
    color?: string
    no_school?: number | boolean
    notify_parent?: number | boolean
    notify_teacher?: number | boolean
    notify_admin?: number | boolean
    [key: string]: unknown
  }
}

export type SchoolCalendarEventsResponse = ApiEnvelope<{
  events: SchoolCalendarEventRow[]
}>

export type StudentScoreRow = {
  id?: number
  student_id?: number
  school_year?: string | null
  semester?: string | null
  class_section_id?: number | null
  homework_score?: number | string | null
  project_score?: number | string | null
  participation_score?: number | string | null
  quiz_score?: number | string | null
  attendance_score?: number | string | null
  ptap_score?: number | string | null
  midterm_exam_score?: number | string | null
  final_exam_score?: number | string | null
  semester_score?: number | string | null
  [key: string]: unknown
}

export type StudentScoresResponse = {
  ok: true
  student_id: number
  rows: StudentScoreRow[]
}

export type StudentScoreCardStudent = {
  id: number
  firstname?: string | null
  lastname?: string | null
  school_id?: string | null
}

export type StudentScoreCardRow = {
  school_year?: string | null
  semester?: string | null
  homework_avg?: number | string | null
  project_avg?: number | string | null
  participation_score?: number | string | null
  quiz_avg?: number | string | null
  test_avg?: number | string | null
  attendance_score?: number | string | null
  ptap_score?: number | string | null
  midterm_exam_score?: number | string | null
  semester_score?: number | string | null
  class_section_name?: string | null
  comments?: Record<string, string>
  year_score?: number | string | null
}

export type StudentScoreCardResponse = {
  ok: true
  student: StudentScoreCardStudent
  rows: StudentScoreCardRow[]
}

export type ReportCardStudentMetaRow = {
  id: number
  firstname: string
  lastname: string
  class_section_name: string
}

export type ReportCardMetaResponse = ApiEnvelope<{
  schoolYears: string[]
  selectedYear: string | null
  semesters: string[]
  selectedSemester: string | null
  students: ReportCardStudentMetaRow[]
}>

export type ReportCardAcknowledgementRow = {
  student_id: number
  school_year: string
  semester: string
  viewed_at?: string | null
  signed_at?: string | null
  signed_name?: string | null
}

export type ReportCardAcknowledgementResponse = ApiEnvelope<ReportCardAcknowledgementRow>

export type ClassProgressReportRow = {
  id: number
  teacher_name?: string | null
  class_section_name?: string | null
  class_section_id?: number | null
  subject?: string | null
  unit_title?: string | null
  status?: string | null
  status_label?: string | null
  covered?: string | null
  homework?: string | null
  materials?: string | null
  support_needed?: string | null
  flags?: string[]
  week_start?: string | null
  week_end?: string | null
  created_at?: string | null
  updated_at?: string | null
  attachments?: {
    id?: number
    name?: string | null
    file_path?: string | null
    download_url?: string | null
    legacy?: boolean | number | null
  }[]
}

export type ClassProgressGroupRow = {
  week_start?: string | null
  week_end?: string | null
  class_section_id?: number | null
  class_section_name?: string | null
  reports?: Record<string, ClassProgressReportRow>
}

export type ClassProgressGroupsResponse = ApiEnvelope<{
  items: ClassProgressGroupRow[]
  pagination?: Record<string, unknown>
}>

export type ClassProgressShowResponse = ApiEnvelope<{
  report?: ClassProgressReportRow
  weekly_reports?: ClassProgressReportRow[]
  status_options?: Record<string, string>
}>

export type ClassProgressMetaResponse = ApiEnvelope<{
  subject_sections?: Record<string, { label?: string; db_subject?: string }>
  status_options?: Record<string, string>
  sunday_options?: string[]
  curriculum?: Record<string, Array<Record<string, unknown>>>
}>

export type EmergencyContactGroupRow = {
  parent_id: number
  parent_name?: string | null
  parent_phones?: string[]
  students?: Array<{
    id?: number
    student_id?: number
    firstname?: string | null
    lastname?: string | null
  }>
  contacts?: Array<{
    id: number
    parent_id?: number
    name?: string | null
    cellphone?: string | null
    email?: string | null
    relation?: string | null
    semester?: string | null
    school_year?: string | null
  }>
}

export type EmergencyContactGroupsResponse = {
  ok: true
  groups: EmergencyContactGroupRow[]
}

export type EmergencyContactShowResponse = {
  ok: true
  contact: {
    id: number
    parent_id: number
    name?: string | null
    cellphone?: string | null
    email?: string | null
    relation?: string | null
    semester?: string | null
    school_year?: string | null
  }
}

export type ParentRegistrationOverviewResponse = {
  ok: true
  parent: ParentProfileRecord | null
  existingKids: ParentEnrollmentStudent[]
  emergencies: ParentEmergencyContactRow[]
  maxChilds?: number
  maxEmergency?: number
  lastDayOfRegistration?: string | null
  registrationAgeDeadline?: string | null
}

export type ParentEventRow = {
  id?: number
  title?: string | null
  event_name?: string | null
  event_date?: string | null
  start_date?: string | null
  description?: string | null
  [key: string]: unknown
}

export type ParentEventsOverviewResponse = {
  ok: true
  activeEvents?: ParentEventRow[]
  charges?: Record<string, unknown>[]
  yourStudents?: ParentEnrollmentStudent[]
}

/** Class preparation (inventory vs sections) — Laravel `GET /api/v1/class-prep` */
export type ClassPrepSectionRow = {
  class_section_id: number | string
  class_section: string
  needs_print?: boolean
  last_printed_at?: string | null
  student_count: number
  prep_items: Record<string, number>
  adjustments: Record<string, number>
}

export type ClassPrepIndexResponse = {
  school_year: string
  semester?: string | null
  prep_results: ClassPrepSectionRow[]
  total_needed: Record<string, number>
  available: Record<string, number>
  shortages?: Record<string, number>
}

export type ClassPrepPrintResponse = {
  class_section?: string | null
  prep_items: Record<string, number>
}

export type CommunicationsStudentOption = {
  id: number
  firstname?: string | null
  lastname?: string | null
}

export type CommunicationsTemplateOption = {
  template_key: string
  name?: string | null
}

export type CommunicationsComposeResponse = {
  students: CommunicationsStudentOption[]
  templates: CommunicationsTemplateOption[]
  display_name?: string | null
}

export type CommunicationsPreviewResponse = {
  subject?: string | null
  html?: string | null
}

export type FamilyListItem = {
  id: number
  household_name?: string | null
  is_primary_home?: boolean
}

export type GuardianListItem = {
  email?: string | null
  receive_emails?: boolean
}

export type ConfigurationRow = {
  id: number | string
  config_key: string
  config_value: string
}

export type ConfigurationListResponse = {
  configs: ConfigurationRow[]
}

export type DiscountVoucherRow = {
  id: number | string
  code: string
  discount_type: 'percent' | 'fixed' | string
  discount_value: number | string
  max_uses?: number | string | null
  times_used?: number | string | null
  valid_from?: string | null
  valid_until?: string | null
  is_active?: boolean
}

export type DiscountsListResponse = {
  vouchers: DiscountVoucherRow[]
  school_year?: string | null
  semester?: string | null
  school_years?: string[]
}

export type DiscountApplyParentRow = {
  id: number | string
  school_id?: string | null
  firstname?: string | null
  lastname?: string | null
  email?: string | null
  has_discount?: boolean
  total_discount?: number | string | null
}

export type DiscountApplyContextResponse = {
  vouchers: DiscountVoucherRow[]
  parents: DiscountApplyParentRow[]
}

/** Admin: enroll_withdraw / new-students list */
export type RegisteredNewStudentRow = {
  id: number
  firstname?: string | null
  lastname?: string | null
  new_student?: string | null
  class_section?: string | null
  enrollment_status?: string | null
  age?: string | number | null
  registration_date?: string | null
  parent_firstname?: string | null
  parent_lastname?: string | null
  parent_phone?: string | null
  parent_email?: string | null
  emergency_name?: string | null
  emergency_relationship?: string | null
  emergency_phone?: string | null
}

export type RegisteredNewStudentsResponse = {
  new_students: RegisteredNewStudentRow[]
  total_new?: number
  school_year?: string | null
  semester?: string | null
  school_years?: string[]
}

export type EnrollmentWithdrawalClassOption = {
  id?: number | string
  class_section_id?: number | string
  name?: string | null
  class_section_name?: string | null
}

export type EnrollmentWithdrawalStudentRow = {
  student_id?: number
  id?: number
  parent_id?: number | null
  guardian_id?: number | null
  firstname?: string | null
  lastname?: string | null
  parent_label?: string | null
  new_student?: string | null
  removed_previous_year?: string | null
  class_section?: string | null
  enrollment_status?: string | null
  registration_date?: string | null
}

export type EnrollmentWithdrawalPageResponse = {
  students: EnrollmentWithdrawalStudentRow[]
  classes: EnrollmentWithdrawalClassOption[]
  school_years?: string[]
  schoolYears?: string[]
  selected_year?: string | null
  selectedYear?: string | null
  current_year?: string | null
  currentYear?: string | null
  semester?: string | null
  missing_year?: boolean
  missingYear?: boolean
  is_current_year?: boolean
  isCurrentYear?: boolean
}

/** Admin expenses (`Views/expenses/*`) */
export type ExpenseUserOption = {
  id: number
  firstname?: string | null
  lastname?: string | null
}

export type ExpenseRow = {
  id: number
  category: string
  amount: number | string
  retailor?: string | null
  retailer?: string | null
  description?: string | null
  status: string
  receipt_path?: string | null
  /** Full URL if API provides it */
  receipt_url?: string | null
  purchaser_firstname?: string | null
  purchaser_lastname?: string | null
  approver_firstname?: string | null
  approver_lastname?: string | null
  created_at?: string | null
  date_of_purchase?: string | null
  purchase_date?: string | null
  purchased_at?: string | null
  date_purchased?: string | null
}

export type ExpensesListResponse = {
  expenses: ExpenseRow[]
  school_year?: string | null
  semester?: string | null
  school_years?: string[]
}

export type ExpenseCreateFormResponse = {
  retailors: string[]
  users: ExpenseUserOption[]
}

export type ExpenseDetail = ExpenseRow & {
  purchased_by?: number | string | null
}

export type ExpenseEditFormResponse = {
  expense: ExpenseDetail
  retailors: string[]
  users: ExpenseUserOption[]
  receipt_url?: string | null
}
