/**
 * One row of `GET /notifications/`.
 *
 * Transcribed from `UserNotificationResource`. The shape is two levels because
 * the per-user row (read state, delivery time) and the notification itself
 * (the localized copy, shared by every recipient) are different records:
 * `is_read` and `created_at` belong to `user_notifications`, the titles and
 * messages to `notifications`.
 *
 * `notification` is `whenLoaded('notification')`, so it is **absent** rather
 * than null if the relation was not eager-loaded. `NotificationController::index`
 * always calls `->with('notification')`, so in practice it is present — but a
 * reader must still tolerate its absence, which is why every field access in
 * `useNotifications` is optional-chained and defaulted to `""`.
 */

import type { ApiResponseStatus } from "@/lib/api/types";
export interface UserNotificationRecord {
  /** The `user_notifications` row id — the id the read/delete endpoints take. */
  id: number;
  is_read: boolean;
  /**
   * ISO 8601, or null — the resource emits `$this->created_at?->toIso8601String()`,
   * so a row with no timestamp yields null rather than an empty string.
   * `formatDate` turns it into the displayed `date`.
   */
  created_at: string | null;
  notification?: {
    /** The shared `notifications` row id, **not** the id to act on. */
    id: number;
    title_en: string | null;
    title_ar: string | null;
    message_en: string | null;
    message_ar: string | null;
    /** What the notice points at; `null` for a plain notice. Never a URL. */
    action_type?: NotificationActionType | null;
    entity_id?: number | null;
  };
}

export type NotificationActionType = "volunteer_opportunity" | "learn_serve_opportunity" | "event";

/** `POST /notifications/{id}/open/`: marks it read; `available` false = the item was deleted, null = plain notice. */
export interface NotificationOpenResult {
  id: number;
  is_read: boolean;
  action_type: NotificationActionType | null;
  entity_id: number | null;
  available: boolean | null;
}

/**
 * The envelope `index()` answers with.
 *
 * `unread_count` sits at the **top level**, beside `data` — not under `meta`,
 * which is where this project's other counts live. Worth stating because the
 * unpaginated branch hand-builds the envelope rather than going through
 * `ApiResponse::success`, and `meta` is absent entirely on that branch.
 */
export interface NotificationsEnvelope {
  key: string;
  msg: string;
  code: number;
  response_status: ApiResponseStatus;
  data: UserNotificationRecord[];
  unread_count: number;
}
