/**
 * The two public statistics payloads.
 *
 * Both are built inline by `VolunteerStatisticsController` rather than through
 * a Resource, so there is no class to point at — these are transcribed from
 * `statistics()` and `topVolunteers()` directly.
 */

/** One year's hours on the platform-wide chart. */
export interface YearlyHours {
  year: number;
  total_hours: number;
}

/**
 * `GET /statistics/` — the platform's headline figures.
 *
 * Several keys are **deliberate aliases of each other**, kept so an older
 * client keeps working while the wording changes:
 * `learn_serve_opportunities_completed` / `development_opportunities_completed`
 * are the same count, and so are `relief_trips` / `outside_kuwait_trips`.
 *
 * One oddity worth knowing when reading the chart: `yearly_hours` spans
 * `range(currentYear, currentYear + 6)` — the current year and the next **six**,
 * not the previous ones. Every future year is therefore `0`, which is what the
 * chart's long flat tail is.
 */
export interface PlatformStatistics {
  yearly_hours: YearlyHours[];
  grand_total_hours: number;
  volunteer_opportunities_completed: number;
  learn_serve_opportunities_completed: number;
  /** Alias of `learn_serve_opportunities_completed`. */
  development_opportunities_completed: number;
  relief_trips: number;
  /** Alias of `relief_trips`. */
  outside_kuwait_trips: number;
  economic_impact_kwd: number;
  /** The configured KWD-per-hour rate, defaulting to 11. */
  economic_impact_rate_kwd: number;
  beneficiaries_count: number;
  development_beneficiaries_count: number;
  beneficiaries_breakdown: {
    volunteer_opportunities: number;
    course_learners: number;
  };
  counter_visibility: Record<string, boolean>;
}

/** The badge block the leaderboard rows carry. Null when the account has none. */
export interface LeaderboardBadge {
  id: number;
  name: string;
}

/** One individual on the leaderboard. */
export interface TopIndividual {
  /** Competition rank — ties share a number. */
  rank?: number;
  /** The **user** id, not a profile id. */
  user_id: number;
  /** `first_name + last_name`, trimmed — `''` when the account has neither. */
  name: string;
  nickname: string | null;
  volunteer_hours: number;
  organizing_hours: number;
  profile_pic: string | null;
  total_hours: number;
  /** `total_hours` as H:MM (`HoursFormat::fromHours`). */
  total_hours_display?: string;
  gender_display: { value_en?: string; value_ar?: string } | null;
  /** Present here, unlike `VolunteerPickerResource` — so routing can be correct. */
  is_public: boolean;
  /** Defaults to `"volunteer"` when the user row is missing. */
  user_type: string;
  badge_info: LeaderboardBadge | null;
}

/** One organization or volunteer team on the leaderboard. */
export interface TopOrganization {
  /** Competition rank — ties share a number. */
  rank?: number;
  /** The organization's **user** id — `$team->user_id`, not the profile id. */
  organization_id: number;
  /** `company_name`, falling back to the user's first + last name. */
  organization_name: string;
  profile_pic: string | null;
  user_type: string;
  badge_info: LeaderboardBadge | null;
  /** Volunteer teams and companies are ranked by executed opportunities. */
  executed_opportunities?: number;
  /** Companies only: their sponsorships, one half of `total_score`. */
  sponsored_count?: number;
  /** Companies only: completed opportunities + sponsorships — the ranking score. */
  total_score?: number;
}

/**
 * `GET /statistics/top/` — the three leaderboards plus the cycle they cover.
 *
 * The cycle fields describe *which* window the three lists were computed over,
 * so a caller can label the board ("this month", "this year") rather than
 * guessing.
 */
export interface TopStatistics {
  top_individuals: TopIndividual[];
  top_volunteer_teams: TopOrganization[];
  top_companies_and_government: TopOrganization[];
  cycle_type: string;
  /** `current` unless the admin configured otherwise. */
  cycle_scope: string;
  /** `Y-m-d`. */
  start_date: string;
  end_date: string;
}

/**
 * `GET /verify/{uuid}/` — `Volunteer\VolunteerVerificationResource`.
 *
 * The public check behind a report's QR code. Deliberately thin: it proves a
 * volunteer's totals without exposing their name, civil id or contact details
 * — the only identity it carries is the nickname and the email.
 *
 * Note that these counters are **not** the `number | string` union
 * `/volunteer-detail/` has: this resource casts the hours with `(float)` and
 * defaults the rest with `?? 0`, so every one of them is a real number.
 */
export interface VolunteerVerificationRecord {
  /** The volunteer **profile** id. */
  id: number;
  uuid: string;
  email: string | null;
  nickname: string | null;
  is_verified: boolean;
  is_public: boolean;
  total_volunteer_hours: number;
  total_opportunities: number;
  total_certificates: number;
  opportunities_organized: number;
  current_rank: number | null;
  current_year_hours: number;
  /** The badge's id, as a bare integer — not a nested badge object. */
  current_badge: number | null;
}
