/**
 * What the auth write endpoints answer with.
 *
 * The request payloads next door in `services/authApi.ts` were transcribed
 * from the validation rules in an earlier pass; these are the other half — the
 * **responses**, which four screens read and one of them feeds straight into
 * `authStore.setUser()`.
 *
 * Three things about this family are easy to get wrong, and all three are
 * encoded below:
 *
 * 1. **The token's key name differs by endpoint.** `POST /login/` and
 *    `POST /social-auth/` merge **`auth_token`** onto the payload
 *    (`AuthController.php:136` and `:614`); `POST /verify_otp_or_token/`
 *    answers with **`token`**. The axios interceptor reads
 *    `authStore.user.auth_token`, so only the first two can sign a user in.
 * 2. **`auth_token` is not part of any Resource.** `WebsiteLoginUserResource`
 *    does not emit it — the controller assigns it onto the resolved array. So
 *    the login payload is "that resource, plus one key", which is why it is
 *    modelled as an intersection here rather than being looked for in the
 *    resource.
 * 3. **`organization` / `volunteer` are conditional keys.** They are assigned
 *    inside an `if`, so they are **absent** — not null — for an account of the
 *    other kind.
 */

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

/** The development kinds a trainer can be approved for. Enforced on write. */
export type TrainerType = "course" | "workshop" | "consultation";

/** The `organization` block, present only for an organization account. */
export interface AuthOrganizationBlock {
  id: number;
  /**
   * `pending | approved | rejected`.
   *
   * Worth noting what this does *not* do: `CLAUDE.md` says it "gates org-only
   * actions independently of the login state", and nothing in `src` reads it
   * for that purpose — a pending organization completes a whole publish form
   * before the 403 tells it otherwise. Recorded in the review checklist.
   */
  organization_status: "pending" | "approved" | "rejected" | (string & {});
}

/** The `volunteer` block, present only for a volunteer account on social auth. */
export interface AuthVolunteerBlock {
  id: number;
  organization_id: number | null;
  is_verified: boolean;
  is_public: boolean;
}

/**
 * `Website\WebsiteLoginUserResource` — the user half of a sign-in response.
 *
 * `user_type` is the backend's `UserType` enum: `volunteer | organization |
 * admin`. There is **no `individual`** case, although `authStore`'s own `User`
 * interface lists one — see the note there.
 */
export interface LoginUserRecord {
  id: number;
  first_name: string | null;
  last_name: string | null;
  company_name?: string | null;
  nickname?: string | null;
  email: string | null;
  profile_pic: string | null;
  social_media_id: string | null;
  /** `SocialMediaProvider` has exactly these two cases. */
  social_media_provider: "google" | "linkedin" | null;
  /** `UserType` — `volunteer | organization | admin`, with no `individual`. */
  user_type: "volunteer" | "organization" | "admin";
  manual_id: string | null;
  /** True only on the response that created the account. */
  is_new_user: boolean;
  is_verified: boolean | null;
  is_banned: boolean;
  receive_reminder_emails: boolean;
  do_not_disturb: boolean;
  is_trainer: boolean;
  trainer_status: string | null;
  /**
   * `[]` rather than null when the volunteer has none.
   *
   * The three values are enforced on write — `RegisterRequest` validates
   * `trainer_types.*` with `Rule::in(['course', 'workshop',
   * 'consultation'])` — so the read side can only contain them.
   */
  trainer_types: TrainerType[];
  show_real_name: boolean;
  /** Absent for a volunteer. */
  organization?: AuthOrganizationBlock;
}

/**
 * The body of `POST /login/` and `POST /social-auth/`: the resource plus the
 * controller-merged token.
 */
export type LoginResponseRecord = LoginUserRecord & {
  /** The Sanctum plain-text token the axios interceptor sends as `Authorization`. */
  auth_token: string;
};

/**
 * `Website\WebsiteRegisterUserResource` — the body of `POST /register/`.
 *
 * Five keys and **no token**: registering does not sign the account in, which
 * is why the flow goes on to OTP verification and then to login.
 */
export interface RegisterUserRecord {
  id: number;
  email: string | null;
  first_name: string | null;
  last_name: string | null;
  user_type: string | null;
}

/**
 * The body of `POST /verify_otp_or_token/`, for both `type` values.
 *
 * **The two `token`s are different kinds of thing**, under the same key:
 *
 * - `type: "register"` returns a Sanctum `plainTextToken` — a credential;
 * - `type: "password"` returns a `password_reset_tokens` row's token — a
 *   one-shot authorisation to set a new password, which is what
 *   `/reset-password?token=` carries.
 *
 * Neither is stored by `authStore`, and neither should be: treating the reset
 * token as a credential, or logging the register token into the URL the way
 * the reset one is, would both be wrong.
 */
export interface VerifyOtpRecord {
  token: string;
  user_id: number;
}

/**
 * `Auth\SocialAuthUserResource`.
 *
 * Returned by the *profile* half of the social flow rather than by
 * `/social-auth/` itself, which answers with `LoginResponseRecord`. It is the
 * widest of the auth payloads because the registration screens pre-fill from
 * it, and it carries the `volunteer` **xor** `organization` block.
 */
export interface SocialAuthUserRecord {
  id: number;
  first_name: string | null;
  last_name: string | null;
  email: string | null;
  social_profile_pic_url: string | null;
  social_media_id: string | null;
  social_media_provider: string | null;
  user_type: string | null;
  manual_id: string | null;
  is_new_user: boolean;
  /** The volunteer's nickname, else the organization's. */
  nickname: string | null;
  gender_display: MasterChoiceDisplay | null;
  /** `Y-m-d`. */
  dob: string | null;
  birth_year: number | null;
  phone_number: string | null;
  country_code: string | null;
  organizer_type_display: MasterChoiceDisplay | null;
  registration_number: string | null;
  license_number: string | null;
  /** Null for an admin — neither branch of the check runs. */
  is_verified: boolean | null;
  is_banned: boolean;
  latitude: string | number | null;
  longitude: string | number | null;
  nationality: string | null;
  preferred_language: string | null;
  company_name: string | null;
  civil_id: 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;
  profile_pic: string | null;
  is_trainer: boolean;
  trainer_status: string | null;
  trainer_types: TrainerType[];
  show_real_name: boolean;
  /** Absent unless the account is a volunteer. */
  volunteer?: AuthVolunteerBlock;
  /** Absent unless the account is an organization. */
  organization?: AuthOrganizationBlock;
}
