import type { MasterChoiceDisplay } from "@/features/shared/apiPrimitives";

/**
 * One row of `GET /volunteer-opportunity-registrations/`.
 *
 * Transcribed from `Opportunity\VolunteerOpportunityRegistrationResource`,
 * which is a **single** resource of twenty-four keys — so the row the
 * registrations table renders is enumerable after all. The alias it replaces
 * (`UntypedRow = any`) carried a note saying narrowing it "would mean
 * transcribing six resources and reconciling them"; that was wrong, and the
 * note is what kept the last meaningful `any` in the app alive.
 *
 * Four things the key names do not say:
 *
 *  - **`user` is a nested block *and* `user_id` is flat.** Both are
 *    deliberate (BE-67.1): the nested object exists because `user.*` reads had
 *    been orphaned when it was a bare id, and the flat id stays because the
 *    unregister call keys on it. The block is `null` when the user row is
 *    gone, which is why every field on it is read optionally.
 *  - **`opportunity` is a bare integer**, not an object — the same naming trap
 *    as `LearnServeTimeSlotRecord`, where the write side calls it
 *    `opportunity_id`.
 *  - **`user_contact_number` is `country_code . phone_number` with no
 *    separator** (`($user->country_code ?? '').$user->phone_number`), and is
 *    `null` when the volunteer has no number at all. The event resource
 *    hyphenates the same pair; this one does not.
 *  - **`is_attended` means "today"**, not "ever": it is an `exists()` query
 *    against `now()->toDateString()`. The per-day history is
 *    `date_wise_attended`, and `attendances` carries the editable records.
 */
export interface VolunteerRegistrationRow {
  can_exclude?: boolean;
  exclusion_closes_at?: string | null;
  id: number;
  /** The opportunity's id — a bare integer under a singular key. */
  opportunity: number;
  /** Null when the user row is gone; `user_id` survives either way. */
  user: {
    id: number;
    emergency_contact_name: string | null;
    emergency_contact_phone: string | null;
    emergency_contact_civil_id: string | null;
    emergency_contact_relationship_display: MasterChoiceDisplay | null;
  } | null;
  user_id: number;
  /** ISO 8601 — a timestamp, not a day. The same-day attendance rule compares
      its *time* against the session end. */
  registration_date: string | null;
  /** `ApprovalStatus` — `pending | approved | rejected`. */
  status: string | null;
  /** `first_name last_name`, trimmed; null when there is no user. */
  full_name: string | null;
  user_email: string | null;
  team: { id: number; name_en: string | null; name_ar: string | null } | null;
  role: { id: number; name_en: string | null; name_ar: string | null } | null;
  /** Dial code and number concatenated, unseparated. */
  user_contact_number: string | null;
  /** `getimg()` of the volunteer profile's QR, or null. */
  qr_code_url: string | null;
  /** The id the bulk-attendance endpoint takes; null without a volunteer profile. */
  volunteer_uuid: string | null;
  /** Attended **today** — not ever. */
  is_attended: boolean;
  /** `Y-m-d` strings, every day already marked present. */
  date_wise_attended: string[];
  /**
   * The attendance records themselves, which the edit-hours and undo actions
   * key on (BE-67.2 — the id used not to be returned at all, so those actions
   * only worked for check-ins made in the current browser session).
   */
  attendances: Array<{
    id: number;
    attended_date: string | null;
    /** The column is cast `float`, and this resource does not use `ar_num()`. */
    total_hours: number | null;
    /** When the attendance was recorded — scan or manual. */
    checked_in_at: string | null;
    /** The session's creditable cap for this day; the hours editor's max. */
    max_hours?: number | null;
    /** Set once the organizer corrected the hours by hand. */
    hours_set_manually_at?: string | null;
    /** BE-101 — organizer-only; null unless the scan was location-checked. */
    check_in_latitude?: number | null;
    check_in_longitude?: number | null;
    check_in_distance_m?: number | null;
  }>;
  /** BE-121 — attended days counted toward the certificate. */
  attended_count?: number;
  created_at: string | null;
  phone_number: string | null;
  civil_id: string | null;
  passport_number: string | null;
}
