/**
 * AI Overview Click Recovery — shared TypeScript types.
 *
 * Matches the `aio_recovery` prop contract defined in
 * docs/implementation-waves-ai-overview-click-recovery.md § Shared Contracts.
 *
 * W4-B additions: recommendation_id, status, roi_snapshot.
 */

/**
 * Measured ROI delta from RecommendationRoiSnapshot (W4-B).
 * Populated after CalculateRecommendationRoiJob runs post-publish.
 * clicks_delta: absolute change (positive = recovery).
 * Copy must say "observed change," never "caused by us" (plan §14.3).
 *
 * W5-G P1: is_seasonal_peak — true when the measurement window overlapped a
 * known seasonal traffic peak. The UI must show a caveat chip/note when true
 * so users are not misled into attributing seasonal uplift to the fix.
 */
export interface AioRoiSnapshot {
  clicks_delta: number;
  days_tracked: number;
  /**
   * W5-G P1: measurement was during a seasonal traffic peak — show caveat.
   * Optional for backward compatibility with older roi_snapshot records that
   * predate this field; the UI treats absent/undefined as false (no caveat shown).
   */
  is_seasonal_peak?: boolean;
}

export interface AioRecoveryItem {
  /** public_id (ULID) — serialized as `id` by the backend; never the integer PK. */
  id: string;
  page_url: string;
  position_recent: number;
  ctr_recent: number;
  ctr_baseline: number;
  /** Relative change, e.g. -22.5 means 22.5% drop. */
  ctr_delta_pct: number;
  est_clicks_lost: number;
  est_clicks_recoverable: number;
  recoverability: 'high' | 'medium' | 'low';
  serp_confirmed: boolean;
  snoozed_until: string | null;
  /**
   * W4-B: integer PK of the linked Recommendation — used as the
   * `recommendation_ids` param for batch-ai.estimate and batch-ai.store.
   * This is NOT the public_id; it is the internal FK. Null when no
   * recommendation has been linked yet (pre-W3-A items or deleted recs).
   */
  recommendation_id: number | null;
  /**
   * W4-B: item status string — 'open' | 'snoozed' | 'applied' | 'tracking'
   * Used to gate the "winning" strip display.
   */
  status: string;
  /**
   * W4-B: measured ROI delta from latestRoiSnapshot.
   * Null until CalculateRecommendationRoiJob has run at least once post-publish.
   * Positive clicks_delta = measured recovery (observed, not causally proven).
   */
  roi_snapshot: AioRoiSnapshot | null;
}

export interface AioRecoverySummary {
  pages: number;
  clicks_at_risk: number;
  est_recoverable: number;
  /**
   * BHUNT-FLOW-01: true when the site had fewer than min_history_days of GSC data,
   * meaning AioRecoveryDetector could not run a valid comparison. The frontend must
   * show a "Still gathering data" / early-signal state instead of the all-clear copy
   * when warming_up===true and items.length===0. Always false for runs with sufficient
   * history or when no completed run exists.
   *
   * Optional for backward compatibility with code paths that build AioRecoverySummary
   * inline (e.g., test factories, storybook fixtures). The backend always sends it.
   * Consumers must use `?? false` as the default.
   */
  warming_up?: boolean;
}

export interface AioRecoveryProp {
  enabled: boolean;
  summary: AioRecoverySummary;
  items: AioRecoveryItem[];
  /**
   * W4-B: integer PK of the latest completed AioRecoveryRun.
   * Required by aio-recovery.batch-estimate and aio-recovery.batch-dispatch
   * to resolve eligible recommendations server-side.
   * Null when no completed run exists (enabled=false path never reaches here).
   */
  run_id: number | null;
}