/**
 * Feature announcements ("Nouveautés") — what the product team writes in the admin and Fleet
 * shows to its users: a "new" badge, a menu spotlight, a banner, a modal, a step card or a
 * guided tour. Field names are snake_case to match /api/admin/announcements/* exactly.
 * See docs/announcements/SPEC.md.
 */

export type AnnouncementFormat =
  | "badge"
  | "sidebar_spotlight"
  | "banner"
  | "modal"
  | "page_widget"
  | "tour";

/** Stored status. "Programmée / En ligne / Terminée" are derived from the dates. */
export type AnnouncementStatus = "draft" | "published" | "archived";

export type AnnouncementDisplayState = "draft" | "scheduled" | "live" | "ended" | "archived";

export type AnnouncementPlacement = "auto" | "top" | "right" | "bottom" | "left";

export type AnnouncementWidgetCorner = "bottom_right" | "bottom_left";

export type AnnouncementLanguage = "fr" | "en";

/** A text in both languages; FR is required, EN falls back to FR in Fleet. */
export interface LocalizedText {
  fr: string;
  en: string;
}

export interface AnnouncementStep {
  /** Client-side id until saved; the backend id afterwards. */
  id: string;
  title: LocalizedText;
  subtitle: LocalizedText;
  body: LocalizedText;
  icon: string | null;
  media_url: string | null;
  media_alt: LocalizedText;
  anchor_key: string | null;
  placement: AnnouncementPlacement;
  cta_label: LocalizedText;
  cta_path: string | null;
}

export interface AnnouncementAudience {
  /** Empty = every plan. */
  plans: string[];
  capabilities_required: string[];
  /** Upsell: users whose plan lacks these capabilities. */
  capabilities_missing: string[];
  permissions: string[];
  roles: string[];
  companies_include: number[];
  companies_exclude: number[];
  /** Empty = both languages. */
  languages: AnnouncementLanguage[];
  new_users_only: boolean;
  /** Explicit confirmation that an empty audience means everybody. */
  everyone_confirmed: boolean;
}

export interface AnnouncementRules {
  dismissible: boolean;
  max_impressions: number;
  hide_after_page_visit: boolean;
  account_age_min_days: number | null;
  account_age_max_days: number | null;
}

export interface AnnouncementReminder {
  enabled: boolean;
  after_days: number;
  format: "badge" | "banner";
  max_reminders: number;
}

export interface AnnouncementNotify {
  enabled: boolean;
  channels: ("in_app" | "email")[];
  message: LocalizedText;
}

export interface AnnouncementCounts {
  eligible: number;
  seen: number;
  clicked: number;
  dismissed: number;
  completed: number;
}

export interface Announcement {
  id: number;
  key: string;
  format: AnnouncementFormat;
  status: AnnouncementStatus;
  title: LocalizedText;
  body: LocalizedText;
  badge_text: LocalizedText;
  category: string | null;
  icon: string | null;
  media_url: string | null;
  media_alt: LocalizedText;
  cta_label: LocalizedText;
  cta_path: string | null;
  page_key: string | null;
  target_sidebar_path: string | null;
  anchor_key: string | null;
  placement: AnnouncementPlacement;
  widget_corner: AnnouncementWidgetCorner;
  steps: AnnouncementStep[];
  audience: AnnouncementAudience;
  starts_at: string | null;
  ends_at: string | null;
  priority: number;
  rules: AnnouncementRules;
  success_event: string | null;
  reminder: AnnouncementReminder;
  notify: AnnouncementNotify;
  /** Exposure cycle: 1 at the first publish, +1 at each reset. */
  round: number;
  /** Set once published at least once: key, format and step count are locked from then. */
  first_published_at: string | null;
  counts: AnnouncementCounts;
  created_by: string;
  updated_at: string;
  created_at: string;
}

/** What the editor sends on create / save. */
export type AnnouncementInput = Omit<
  Announcement,
  "id" | "status" | "round" | "first_published_at" | "counts" | "created_by" | "updated_at" | "created_at"
>;

// ── Catalogs (pickers) ───────────────────────────────────────────────────────

export interface AnnouncementPage {
  key: string;
  /** The French label of Fleet's menu. */
  label: string;
  /** Its English label, when it differs (helps tell two entries apart). */
  hint?: string | null;
  /** Fleet path the preview opens; ":id" is replaced by an example (every record of that kind). */
  path: string;
  /** The page needs an id (e.g. "Fiche véhicule"): the preview asks for an example vehicle. */
  needs_vehicle: boolean;
  /** The kind of record behind ":id" (vehicle, employee, contract…): the API picks the example. */
  example?: string | null;
}

export interface AnnouncementAnchor {
  key: string;
  label: string;
  /** The English label of a menu entry, when it differs. */
  hint?: string | null;
  /** null = a menu entry ("sidebar.<page>") or group ("sidebar-group.<id>"), available on every page. */
  page_key: string | null;
}

export interface AnnouncementSidebarPath {
  path: string;
  label: string;
  hint?: string | null;
  anchor_key: string;
}

export interface CatalogOption {
  value: string;
  label: string;
}

export interface AnnouncementExampleVehicle {
  id: number;
  numberplate: string;
  make_model: string;
}

export interface AnnouncementCatalogs {
  pages: AnnouncementPage[];
  anchors: AnnouncementAnchor[];
  sidebar_paths: AnnouncementSidebarPath[];
  plans: CatalogOption[];
  capabilities: CatalogOption[];
  permissions: CatalogOption[];
  roles: CatalogOption[];
  usage_events: CatalogOption[];
  /** companies.id + name (the existing GET /companies/options). */
  companies: { value: number; label: string }[];
}

// ── Read models ──────────────────────────────────────────────────────────────

export interface AudienceCount {
  count: number;
  /** Total Fleet users, to tell "everybody" apart. */
  total: number;
}

export interface EligibilityResult {
  eligible: boolean;
  /** Users of the company in the audience, out of its users. */
  matching_users: number;
  /** Of those, the users Fleet would show it to now (a saved announcement: what they already did
   * with it, the day's modal); equal to matching_users otherwise. */
  visible_users?: number;
  company_users: number;
  /** Why the others (or the whole company) are left out, in plain words. */
  reasons: string[];
}

export interface AnnouncementStepStats {
  step_id: string;
  title: string;
  seen: number;
  completed: number;
  anchor_missing: number;
}

export interface AnnouncementStats {
  round: number;
  rounds: number[];
  counts: AnnouncementCounts;
  dismiss_rate: number;
  steps: AnnouncementStepStats[];
  anchor_missing: number;
  adoption: {
    event: string | null;
    adopted_after_seen: number;
    adopted_not_seen: number;
    rate_seen: number;
    rate_not_seen: number;
    /** Daily adoption rate (seen users), oldest first. */
    series: { date: string; rate_seen: number; rate_not_seen: number }[];
  };
  reminder_targets: number;
  posthog_url: string | null;
}

export type AnnouncementHistoryAction =
  | "created"
  | "updated"
  | "published"
  | "unpublished"
  | "reset"
  | "archived"
  | "duplicated";

export interface AnnouncementHistoryEntry {
  id: number;
  action: AnnouncementHistoryAction;
  by: string;
  at: string;
  /** Changed fields for "updated", the reason for "reset". */
  detail: string | null;
}

export interface AnnouncementPreviewToken {
  token: string;
  preview_url: string;
  expires_at: string;
}

// ── Menu labels (« Étiquettes du menu », SCRUM-443) ─────────────────────────────

/** A Fleet menu entry's status label: drawn while `shown`, its words `text` (« Beta » when empty). */
export interface MenuLabelEntry {
  id: number;
  /** Fleet's French menu label. */
  label: string;
  /** Its English label, when it differs. */
  hint: string | null;
  path: string;
  shown: boolean;
  text: string | null;
}

/** A menu section; with one entry, Fleet draws that entry at the top level. */
export interface MenuLabelSection {
  id: number;
  label: string;
  hint: string | null;
  items: MenuLabelEntry[];
}

/** 422 body: field errors keyed by the field path (e.g. "title.fr", "steps.0.anchor_key"). */
export interface AnnouncementFieldErrors {
  [field: string]: string[];
}
