export interface IAgentAnalyticsTrend {
  delta_pct: number;
}

export interface IAgentOverview {
  total_conversations: number;
  unique_visitors: number;
  real_conversion_rate: number;
  satisfaction_rate: number;
  product_clicks: number;
  add_to_cart_count: number;
  avg_messages_per_conversation: number;
  avg_duration_minutes: number;
  high_intent_conversations: number;
  high_intent_rate: number;
  returning_rate: number;
  returning_visitors: number;
}

export interface IAgentOverviewTrends {
  total_conversations?: IAgentAnalyticsTrend;
  unique_visitors?: IAgentAnalyticsTrend;
  real_conversion_rate?: IAgentAnalyticsTrend;
  satisfaction_rate?: IAgentAnalyticsTrend;
  product_clicks?: IAgentAnalyticsTrend;
  add_to_cart_count?: IAgentAnalyticsTrend;
}

export interface IAgentProductFunnel {
  products_shown: number;
  products_clicked: number;
  products_carted: number;
}

export interface IAgentFunnel {
  total_conversations: number;
  reached_discovery: number;
  reached_consideration: number;
  reached_ready: number;
  product_funnel: IAgentProductFunnel;
}

export interface IDailyConversation {
  date: string;
  count: number;
}

export interface IAgentEngagementPatterns {
  daily_conversations: IDailyConversation[];
  peak_hours: Record<string, number>;
  language_distribution: Record<string, number>;
  avg_user_message_length: number;
  avg_ai_response_length: number;
  conversations_with_products: number;
  product_engagement_rate: number;
}

export interface ITopProduct {
  name: string;
  sku: string;
  price: number;
  times_recommended: number;
  times_clicked: number;
  times_carted: number;
  click_rate: number;
  cart_rate: number;
}

export interface IMissingProduct {
  name: string;
  times_requested: number;
}

export interface IAgentProductPerformance {
  top_products: ITopProduct[];
  missing_products: IMissingProduct[];
  category_distribution: Record<string, number>;
}

export interface ISentimentTrendPoint {
  date: string;
  positive: number;
  neutral: number;
  negative: number;
}

export interface IAgentIntentSentiment {
  intent_distribution: Record<string, number>;
  sentiment_breakdown: {
    positive: number;
    neutral: number;
    negative: number;
  };
  outcome_distribution: Record<string, number>;
  sentiment_trend: ISentimentTrendPoint[];
}

export interface ISatisfactionTrendPoint {
  date: string;
  rate: number;
}

export interface ICommonQuestion {
  question: string;
  count: number;
}

export interface IPainPoint {
  issue: string;
  count: number;
}

export interface IAgentChatbotPerformance {
  satisfaction_trend: ISatisfactionTrendPoint[];
  common_questions: ICommonQuestion[];
  common_pain_points: IPainPoint[];
}

export interface ICompetitor {
  name: string;
  mention_count: number;
  contexts: string[];
}

export interface IAgentCompetitiveIntel {
  total_mentions: number;
  competitors: ICompetitor[];
}

export interface IAgentDashboardData {
  overview: IAgentOverview;
  overview_trends: IAgentOverviewTrends;
  funnel: IAgentFunnel;
  engagement_patterns: IAgentEngagementPatterns;
  product_performance: IAgentProductPerformance;
  intent_sentiment: IAgentIntentSentiment;
  chatbot_performance: IAgentChatbotPerformance;
  competitive_intel: IAgentCompetitiveIntel;
}

export interface IJourneyClickedProduct {
  sku: string;
  name: string;
  image_url?: string;
  product_url?: string;
}

export interface IJourneyListItem {
  fingerprint: string;
  first_message_at: string;
  duration_minutes: number;
  message_count: number;
  outcome: string;
  sentiment: string;
  purchase_intent_score: number;
  product_clicks: number;
  add_to_cart_count: number;
  clicked_products: IJourneyClickedProduct[];
  carted_products: IJourneyClickedProduct[];
  liked_messages_count: number;
  disliked_messages_count: number;
  last_stage: string;
}

export interface IJourneyProduct {
  name?: string;
  sku?: string;
  image_url?: string;
  product_url?: string;
}

export interface IJourneyMessage {
  user_message: string;
  ai_response: string;
  products_shown: IJourneyProduct[];
  conversation_stage: string;
}

export interface IJourneyProductStep {
  product?: string;
  name?: string;
  sku?: string;
  image_url?: string;
  product_url?: string;
  recommended: boolean;
  clicked: boolean;
  carted: boolean;
}

export interface IJourneyDetail {
  duration_minutes: number;
  language: string;
  outcome: string;
  purchase_intent_score: number;
  summary: string;
  messages: IJourneyMessage[];
  product_journey: IJourneyProductStep[];
  stage_progression: string[];
  sentiment_progression: (string | { sentiment: string })[];
  product_clicks: number;
  add_to_cart_count: number;
  clicked_products: IJourneyClickedProduct[];
  carted_products: IJourneyClickedProduct[];
  liked_messages_count: number;
  disliked_messages_count: number;
}

export interface IAgentDateRange {
  start: string;
  end: string;
}

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

export interface ISuggestedCampaign {
  name: string;
  goal: 'awareness' | 'conversion' | 'upsell' | 'clearance';
  target_categories: string[];
  tone_of_voice: string;
  priority: 'soft' | 'balanced' | 'strong';
  description: string;
}

export interface IInsight {
  id: string;
  title: string;
  subtitle: string;
  type: string;
  priority: 'high' | 'medium' | 'low';
  metrics: IInsightMetric[];
  dismissed: boolean;
  suggested_campaign: ISuggestedCampaign;
}

export interface IInsightReport {
  report_id: string;
  created_at: string | null;
  period_start: string | null;
  period_end: string | null;
  summary: string;
  insights: IInsight[];
  status: string;
}

/**
 * Wire shape of ``GET /analytics/ai-insights``. The agent wraps the
 * report so the UI can show "report is stale, regenerating..." without
 * a second round-trip.
 */
export interface IInsightsResponse {
  report: IInsightReport | null;
  is_stale: boolean;
  regen_dispatched: boolean;
}

export type AgentGapCategory =
  | 'info_missing'
  | 'feature_missing'
  | 'cannot_guide'
  | 'out_of_scope';

export interface IAgentGapSample {
  fingerprint: string;
  message_index: number;
  occurred_at: string | null;
}

/**
 * Statuses that surface in the Gaps tab UI (one tab each).
 * ``deleted`` is intentionally NOT in this union - it is a one-way hard
 * remove that no tab exposes; see {@link AgentGapMutation} for the
 * write-only value the state-flip endpoint accepts.
 */
export type AgentGapStatus = 'active' | 'completed' | 'dismissed';

/**
 * Values the merchant can flip a gap into. Mirrors ``AGENT_GAP_STATUSES``
 * in recomaze-agent and includes ``'deleted'`` for the irreversible
 * trash action; the list endpoint never returns a gap whose state has
 * been set to ``deleted``.
 */
export type AgentGapMutation = AgentGapStatus | 'deleted';

export interface IAgentGap {
  target: string;
  category: AgentGapCategory;
  count: number;
  samples: IAgentGapSample[];
  status?: AgentGapStatus;
}

export type AgentGapFixActionKind =
  | 'kb_article'
  | 'ai_visibility_article'
  | 'product_rewrite'
  | 'policy_update'
  | 'manual';

export interface IAgentGapFixAction {
  kind: AgentGapFixActionKind;
  label: string;
  description: string;
  payload: Record<string, unknown>;
}

export interface IAgentGapFixSuggestion {
  target: string;
  category: AgentGapCategory | string;
  explanation: string;
  actions: IAgentGapFixAction[];
}

export interface IAgentGapFixRequest {
  target: string;
  category: AgentGapCategory;
  sample_fingerprint?: string | null;
  sample_message_index?: number | null;
  language?: string | null;
}

export interface IAgentGapStateUpdateRequest {
  target: string;
  category: AgentGapCategory;
  status: AgentGapMutation;
}

export interface IAgentGapStateUpdateResponse {
  gap_key: string;
  target: string;
  category: AgentGapCategory;
  status: AgentGapMutation;
}

export interface IAgentGapsResponse {
  gaps: IAgentGap[];
  count: number;
  total: number;
  total_all_categories: number;
  category_counts: Record<AgentGapCategory, number>;
  next_cursor: string | null;
}

/** Body for ``POST /analytics/gaps/prepare-kb-draft``. */
export interface IAgentGapKbDraftRequest {
  target: string;
  category: AgentGapCategory;
  sample_fingerprint?: string | null;
  sample_message_index?: number | null;
  /**
   * Optional "suggest more" hint typed by the merchant when they want a
   * regenerated draft from inside the publish modal (e.g. "make it
   * shorter", "include the 30-day return window", "more formal").
   */
  extra_prompt?: string | null;
}

/**
 * Response payload for ``POST /analytics/gaps/prepare-kb-draft``. The FE
 * pre-fills a modal with these values and posts the edited result through
 * ``createTextEntry``.
 */
export interface IAgentGapKbDraft {
  title: string;
  body: string;
  language: string;
}

/** Body for ``POST /analytics/gaps/product-suggestion``. */
export interface IAgentGapProductSuggestionRequest {
  target: string;
  category: AgentGapCategory;
  sample_fingerprint?: string | null;
  sample_message_index?: number | null;
  /**
   * Optional "suggest more" hint typed by the merchant when they want a
   * regenerated snippet from inside the suggestion modal.
   */
  extra_prompt?: string | null;
}

/** Resolved product context returned to the FE for display. */
export interface IAgentGapProductSuggestionProduct {
  title: string;
  sku: string;
  current_description: string;
}

/** Response payload for ``POST /analytics/gaps/product-suggestion``. */
export interface IAgentGapProductSuggestionResponse {
  language: string;
  product: IAgentGapProductSuggestionProduct;
  customer_query: string;
  problem: string;
  /** "faq" → paste into the FAQ section; "description" → paste into the
   *  product description per ``placement_hint``. */
  suggestion_type: 'faq' | 'description';
  suggested_text: string;
  placement_hint: string;
}