/**
 * The scan- and attendance-permission list rows, and the user payload they
 * carry.
 *
 * These two endpoints do not answer with a single Resource. Each row is
 * `CustomUserResource` **spread flat**, with three keys merged on top of it by
 * the controller:
 *
 * ```php
 * $userData = (new CustomUserResource($scan->user))->resolve();
 * $userData['volunteer_profile'] = (new VolunteerProfileWithUserResource(…))->resolve();
 * $userData['is_allowed'] = $scan->is_allowed;
 * $userData['scan_permission_id'] = $scan->id;
 * ```
 *
 * So `id` on a row is the **user's** id, and the permission's own id is
 * `scan_permission_id`. `volunteer_profile` is present only when the user has
 * a volunteer profile — it is assigned inside an `if`, so the key is *absent*,
 * not null, for anyone else.
 */

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

/**
 * `Auth\CustomUserResource` — the user block these tables are built from.
 *
 * Unlike `VolunteerPickerResource`, this one **does** emit `is_public`, so a
 * row from these two endpoints can choose the right profile route. It also
 * carries the volunteer's real name, which the picker withholds.
 */
export interface CustomUserRecord {
  /** The user's id. */
  id: number;
  username: string | null;
  email: string | null;
  user_type: string | null;
  first_name: string | null;
  last_name: string | null;
  /** `fullName()` — `''` rather than null when there is no name. */
  full_name: string;
  profile_pic: string | null;
  country_code: string | null;
  phone_number: string | null;
  nationality: string | null;
  receive_reminder_emails: boolean;
  /** `Y-m-d`. */
  dob: string | null;
  birth_year: number | null;
  instagram_link: string | null;
  whatsapp_link: string | null;
  linkedin_link: string | null;
  facebook_link: string | null;
  twitter_link: string | null;
  gender_display: MasterChoiceDisplay | null;
  /** Present here, unlike `VolunteerPickerResource`. */
  is_public: boolean;
  /**
   * `"{country_code}-{phone_number}"` — **hyphen-separated**.
   *
   * Worth pinning, because `LearnServeOpportunityRegistrationResource` builds
   * a field of the same name by plain concatenation
   * (`$country_code.$phone_number`), with no separator. The two endpoints
   * genuinely format it differently, so anything parsing this back apart has
   * to know which one it came from.
   */
  user_contact_number: string | null;
  /** The volunteer's nickname, or an organization's full name. Null for neither. */
  nickname: string | null;
  emergency_contact_name: string | null;
  emergency_contact_phone: string | null;
  emergency_contact_country_code: string | null;
  emergency_contact_civil_id: string | null;
  emergency_contact_relationship: number | null;
  emergency_contact_relationship_display: MasterChoiceDisplay | null;
}

/**
 * One row of `GET /scan-permissions/list/` or `/attendance-permissions/list/`.
 *
 * The nested `volunteer_profile` comes from
 * `VolunteerProfileWithUserResource`, which extends `VolunteerProfileResource`
 * and overrides one method: its `user` key is a **nested user object** rather
 * than the bare `user_id` integer the plain profile resource emits. Same
 * resource family, two different shapes for the same key name.
 */
export interface PermissionListRow extends CustomUserRecord {
  /** Whether the permission is currently granted. */
  is_allowed: boolean;
  /**
   * The permission row's own id. `permissionUserRow($permission, $idKey)`
   * names it per endpoint: `scan_permission_id` on the retired scan list,
   * `attendance_permission_id` on `/attendance-permissions/list/`.
   */
  scan_permission_id?: number;
  attendance_permission_id?: number;
  /** Absent, not null, when the user has no volunteer profile. */
  volunteer_profile?: {
    id: number;
    nickname: string | null;
    is_public: boolean;
    is_verified: boolean;
    /** The nested user object — not a bare id. */
    user: CustomUserRecord | null;
    [key: string]: unknown;
  };
}

/**
 * `Opportunity\OpportunityFeedbackResource` — `GET /opportunity-feedbacks/`.
 */
export interface OpportunityFeedbackRecord {
  id: number;
  learn_serve_opportunity_id: number;
  user_id: number;
  /** `fullName()` — `''` rather than null when the author has no name. */
  user_name: string;
  profile_pic?: string | null;
  nickname?: string | null;
  gender_display?: MasterChoiceDisplay | null;
  rating: number | null;
  comment_en: string | null;
  comment_ar: string | null;
  primary_language: string | null;
  /** Counted across all users, so never locale-formatted. */
  likes_count: number;
  /** `false` for an anonymous reader, not null. */
  is_liked_by_me: boolean;
  created_at: string | null;
}

/**
 * `Opportunity\LearnServeOpportunityRegistrationResource` —
 * `GET /learn-serve-opportunities/{id}/registrations/`.
 */
export interface LearnServeRegistrationRecord {
  id: number;
  opportunity_id: number;
  user_id: number;
  /** `user_name` and `full_name` are the **same value** — both `fullName()`. */
  user_name: string;
  full_name: string;
  user_email: string | null;
  civil_id: string | null;
  passport_number: string | null;
  phone_number: string | null;
  /**
   * `country_code . phone_number` — **no separator**, unlike
   * `CustomUserRecord.user_contact_number`, which hyphenates. Null when the
   * user has no phone number.
   */
  user_contact_number: string | null;
  profile_pic: string | null;
  gender_display: MasterChoiceDisplay | null;
  /** Emitted here, so this table can route to the right profile. */
  is_public: boolean;
  registration_date: string | null;
  status: string | null;
  is_attended: boolean | null;
  is_certified: boolean | null;
  certificate_name: string | null;
  certificate_image: string | null;
  /** Null unless the registration is assigned to a specific slot. */
  time_slot: {
    id: number;
    date: string | null;
    start_time: string | null;
    end_time: string | null;
  } | null;
}

/**
 * `GET /check-license-requirement/` — built inline by
 * `BaseController::checkLicenseRequirement()`.
 *
 * `user_role_display` is an **English label** (`"Volunteer"`,
 * `"Association"`, `"Governmental"`, …) taken from the choice row's
 * `value_en`, not a translated string — so it is an identifier for the
 * frontend to branch on rather than copy to show the reader. It falls back to
 * the user's own `user_type` (or `"admin"`) for an account that is neither a
 * volunteer nor an organization.
 */
export interface LicenseRequirement {
  license_required: boolean;
  user_role_display: string;
}

/** `GET /volunteer-profile/qr-code/`. */
export interface VolunteerQrCode {
  /** The volunteer **profile** id. */
  volunteer_id: number;
  qr_code_url: string;
  name: string;
}
