/**
 * Field-level validation errors, as `ApiResponse::normalizeErrors()` emits them.
 *
 * It is a **map keyed by field name**, each value a list of already-localized
 * messages: `{ civil_id: ["The civil id is invalid."] }`. The messages are
 * localized server-side from the `x-lang` header, and a legacy `{ en, ar }`
 * pair is collapsed to the request locale before it leaves PHP — so there is
 * nothing to pick per language here.
 *
 * The one wrinkle: when there are no errors, `normalizeErrors()` returns PHP's
 * `[]`, which serializes as a JSON **array**, not `{}`. Typing this as a map
 * anyway is deliberate and safe — every reader goes through `Object.entries`
 * or `Object.values`, which behave identically on `[]`. The previous
 * `unknown[]` described *only* that empty case and so described away the
 * populated one, which is why reading a field error needed a cast.
 *
 * Use `getApiFieldErrors` (`lib/api/errors.ts`) rather than indexing this
 * directly; it also handles the older `errors: { field: { en, ar } }` shape
 * that some endpoints still return.
 */
export type ApiValidationErrors = Record<string, string[]>;

export interface ApiResponseStatus {
  error: boolean;
  validation_errors: ApiValidationErrors;
}

export interface ApiPagination {
  page: number;
  limit: number;
  total: number;
  total_pages: number;
}

export interface ApiResponse<T> {
  key: string;
  msg: string;
  code: number;
  response_status: ApiResponseStatus;
  data: T;
  meta?: {
    pagination?: ApiPagination;
    timestamp?: string;
  };
}

/**
 * The envelope `GET /list-all-opportunities/` and the profile listing
 * endpoints answer with.
 *
 * `VolunteerOpportunityController::listAllOpportunities()` builds the normal
 * envelope and then assigns `$data['counts']` onto it, so `counts` sits at the
 * **top level beside `data`**, not inside `meta` — the same placement as
 * `unread_count` on the notifications endpoint. Reading it off `meta` yields
 * `undefined`.
 */
export interface CountedApiResponse<T> extends ApiResponse<T> {
  counts?: {
    all?: number;
    volunteer?: number;
    development?: number;
  };
}

/**
 * Registration download endpoints answer `download=true` with the standard
 * API envelope whose `data` contains a pre-signed `downloadUrl`. Services
 * unwrap that envelope before returning this shape to components.
 */
export interface RegistrationsDownload {
  downloadUrl: string;
}

/**
 * Volunteer downloads additionally report the outcome of the optional
 * `mark_attendance` side effect requested in the same call.
 */
export interface VolunteerRegistrationsDownload extends RegistrationsDownload {
  file_format?: string;
  registrations_count?: number;
  attendance_marked_count?: number;
  attendance_already_marked_count?: number;
}

export interface FaqItem {
  id: number;
  question_en: string;
  question_ar: string;
  answer_en: string;
  answer_ar: string;
  created_at: string;
  updated_at: string;
  is_deleted: boolean;
  deleted_at: string | null;
}

/**
 * A value that can go in a query string.
 *
 * Axios serializes `params` into the URL, so only primitives and arrays of
 * primitives make it through intact — an object would be stringified as
 * `[object Object]`. The list endpoints all took `params?: any`, which hid
 * exactly that mistake.
 */
export type QueryParamValue = string | number | boolean | null | undefined;

/** The `params` object of a list request. */
export type QueryParams = Record<
  string,
  QueryParamValue | readonly QueryParamValue[]
>;

/*
 * `ApiWriteBody = FormData | Record<string, unknown>` used to live here: the
 * placeholder for a write body whose accepted keys had not been transcribed
 * from the endpoint's validation yet.
 *
 * It is gone because there are none left. Every write wrapper in
 * `features/*\/services/` now takes either a named per-endpoint interface or a
 * bare `FormData` for the multipart ones, with the field contract typed at the
 * builder's input instead. The placeholder is not re-added for a new endpoint —
 * the point of removing it is that `Record<string, unknown>` has an index
 * signature, and an index signature satisfies *any* required-key check, which
 * is how `POST /opportunity-feedbacks/` shipped with the wrong id key for the
 * life of the feature.
 */
