/**
 * The public profiles directory payloads.
 *
 * All four endpoints answer with `Website\WebsiteProfileListItemResource`,
 * which is **two different shapes behind one class**: it takes a `$type` of
 * `'volunteer'` or `'organization'` and returns a different `user_details`
 * block for each. Nothing in the payload says which one you got — the caller
 * knows from the endpoint it called, which is why these are separate types
 * rather than a union with a discriminator.
 *
 * | Endpoint | `$type` passed | Shape |
 * |---|---|---|
 * | `GET /profiles/volunteers/` | `volunteer` | `VolunteerDirectoryItem` |
 * | `GET /profiles/organizations/` | `organization` | `OrganizationDirectoryItem` |
 * | `GET /profiles/volunteer-teams/` | **`organization`** | `OrganizationDirectoryItem` |
 * | `GET /all-profiles/` | both | `AllProfilesPayload` (three keyed buckets) |
 *
 * A volunteer team is served with the *organization* shape, not the volunteer
 * one — it is an `organization_profiles` row with a volunteer-team type.
 */

import type { WebsiteChoiceDisplay } from "@/features/shared/apiPrimitives";
import type { ApiPagination } from "@/lib/api/types";

/**
 * `user_details` on a **volunteer** row.
 *
 * It carries **no `first_name` / `last_name`** — the organization branch does,
 * this one does not, and reading either off a volunteer row is `undefined`.
 * That is a deliberate privacy line, not an oversight: the volunteer list is
 * also searched with `matchRealName: false`, so a volunteer is findable and
 * displayable only by nickname.
 */
export interface VolunteerDirectoryUser {
  id: number;
  /** `profilePicUrl()` — the upload, else the social avatar, else null. */
  profile_pic: string | null;
  gender_display: WebsiteChoiceDisplay | null;
  user_type: string | null;
}

/** One row of `GET /profiles/volunteers/`. */
export interface VolunteerDirectoryItem {
  /** The **profile** id, not the user id — `volunteer_profiles.id`. */
  id: number;
  nickname: string | null;
  /** BE-169: the real name when the volunteer shows it, else `null`. */
  full_name?: string | null;
  /** BE-169: what others may see — real name or nickname (fallback «متطوع»). */
  display_name?: string | null;
  /** Always `true` since BE-168 (kept by the API for older clients). */
  is_public: boolean;
  user_details: VolunteerDirectoryUser;
}

/** `user_details` on an **organization** (or volunteer-team) row. */
export interface OrganizationDirectoryUser {
  id: number;
  first_name: string | null;
  last_name: string | null;
  profile_pic: string | null;
  /** Always `null` on this branch — organizations have no gender choice. */
  gender_display: null;
  user_type: string | null;
}

/** One row of `GET /profiles/organizations/` or `/profiles/volunteer-teams/`. */
export interface OrganizationDirectoryItem {
  /** `organization_profiles.id`. */
  id: number;
  nickname: string | null;
  /** BE-294: the registered organization / team name (`organization_profiles.company_name`). */
  company_name?: string | null;
  /** BE-294: `company_name`, else the nickname — what the tile should show. */
  display_name?: string | null;
  /** **Hard-coded `true`** on this branch — an organization is always public. */
  is_public: true;
  user_details: OrganizationDirectoryUser;
}

/** Either directory row. */
export type ProfileDirectoryItem =
  | VolunteerDirectoryItem
  | OrganizationDirectoryItem;

/**
 * The body of `GET /all-profiles/` — a **three-bucket preview**, each bucket
 * capped at `limit`, for the directory overview.
 *
 * Two things about this payload are unlike every other list in the API:
 *
 * - `data` is an **object**, not an array.
 * - **`meta` is nested inside `data`**, and its `pagination` is keyed by
 *   bucket rather than being a single `{page, limit, total, total_pages}`.
 *   `allProfiles()` builds this by hand and passes it to
 *   `ApiResponse::success`, so the envelope's own `meta` is absent. Reading
 *   `response.meta.pagination` here yields `undefined`; the pagination lives
 *   at `response.data.meta.pagination.volunteer` and its two siblings.
 *
 * For one bucket's full list, use the dedicated endpoint instead — those do
 * answer with a flat array and the standard envelope `meta.pagination`.
 */
export interface AllProfilesPayload {
  volunteer: VolunteerDirectoryItem[];
  organization: OrganizationDirectoryItem[];
  /** Served with the organization shape — see the table above. */
  volunteer_team: OrganizationDirectoryItem[];
  meta: {
    pagination: {
      volunteer: ApiPagination;
      organization: ApiPagination;
      volunteer_team: ApiPagination;
    };
  };
}
