/** A single step in the copilot's tool/thinking trace. */
export interface ICopilotStep {
  /** Stable identifier used to update the step's state. */
  id: string;
  /** Title, e.g. "Checking your AI Visibility". */
  label: string;
  /** Optional one-line description shown under the title. */
  detail?: string;
  /** Whether the step is in progress or finished. */
  state: 'running' | 'done';
}

/** A one-tap quick-action button the copilot attaches under a reply. */
export interface ICopilotAction {
  /** Short button label (1-3 words). */
  label: string;
  /** Visual weight: filled "primary" or outline "secondary". */
  kind: 'primary' | 'secondary';
  /** What clicking does. */
  action: 'navigate' | 'prompt' | 'dismiss';
  /** Target dashboard path, for "navigate". */
  route?: string;
  /** Follow-up message to send, for "prompt". */
  prompt?: string;
}

/**
 * One turn in the copilot conversation.
 */
export interface ICopilotMessage {
  /** Who produced the message. */
  role: 'user' | 'assistant';
  /** Markdown content of the message. */
  content: string;
  /** Tool/thinking steps that produced this assistant message. */
  steps?: ICopilotStep[];
  /** Quick-action buttons attached to this assistant message. */
  actions?: ICopilotAction[];
  /** What this turn kicked off: an article, or an emailed product-content job. */
  generationKind?: 'article' | 'content';
  /**
   * Article id of a generation this turn kicked off, so the in-chat card can
   * poll it. Set once the agent reports the started generation.
   */
  generationArticleId?: string;
  /** Content-generator job id to poll, for an emailed product-content job. */
  generationJobId?: string;
  /** Latest polled status of the tracked generation, when known. */
  generationStatus?: 'generating' | 'ready';
}

/**
 * Snapshot of what the merchant is currently looking at, sent for grounding.
 */
export interface ICopilotContext {
  /** Current dashboard route, e.g. "/ai-visibility". */
  route?: string;
  /** Latest AI Readiness score, when known. */
  readiness_score?: number;
  /** Merchant platform (CUSTOM, SHOPIFY, ...), for platform-specific guidance. */
  platform?: string;
  /** Canonical names of setup steps not yet completed (from dashboard-api). */
  pending_steps?: string[];
}

/**
 * Request payload sent to the copilot proxy.
 */
export interface ICopilotStreamRequest {
  /** The merchant's latest message. */
  message: string;
  /** Prior turns, oldest first. */
  history: ICopilotMessage[];
  /** Optional page/account context. */
  context?: ICopilotContext;
  /** Optional language override; defaults to mirroring the message language. */
  language?: string;
  /**
   * A logo the merchant attached in chat, as an http(s) url or a
   * data:image/...;base64 URI. The backend reads brand colors off it.
   */
  logo_image?: string;
}

/**
 * Callbacks invoked while consuming the copilot SSE stream.
 */
/** A single daily improvement quest. */
export interface ICopilotQuest {
  /** Stable id. */
  quest_id: string;
  /** Quest type (article/catalog/gap/analytics). */
  type: string;
  /** Short title. */
  title: string;
  /** What to do and why. */
  description: string;
  /** "open" or "resolved". */
  status: string;
  /** Points awarded on resolution. */
  points: number;
  /** ISO timestamp when resolved, if resolved. */
  resolved_at?: string | null;
}

/** One onboarding step with its completion state. */
export interface ICopilotSetupStep {
  /** Canonical step name (e.g. "import_products"). */
  name: string;
  /** Whether the merchant has completed it. */
  completed: boolean;
}

/** A merchant's quest overview: open quests, points, history, and setup state. */
export interface ICopilotQuestOverview {
  /** Currently open quests. */
  open: ICopilotQuest[];
  /** Number of quests resolved all-time. */
  resolved_count: number;
  /** Total points earned. */
  earned_points: number;
  /** The Quests pillar score (capped). */
  quest_pillar_score: number;
  /** Recent quests, newest first. */
  history: ICopilotQuest[];
  /** Merchant platform (CUSTOM, SHOPIFY, ...). */
  platform: string;
  /** Incomplete onboarding steps, in order (from Postgres). */
  pending_steps: string[];
  /** All onboarding steps with completion state, in order. */
  setup_steps: ICopilotSetupStep[];
  /** True when no onboarding step is complete yet. */
  is_new_merchant: boolean;
  /** The single most impactful open quest to proactively nudge, or null. */
  nudge?: ICopilotQuest | null;
  /** Quests resolved in the last two days, for the one-time points toast. */
  recently_resolved?: ICopilotQuest[];
}

/** A UI directive the front-end executes: navigate, or attach quick actions. */
export type ICopilotDirective =
  | {
      /** Move the merchant to a page/section. */
      directive: 'navigate';
      /** Target dashboard path, optionally with a query string. */
      path: string;
    }
  | {
      /** Attach one-tap buttons under the current reply. */
      directive: 'actions';
      /** The quick-action buttons to show. */
      actions: ICopilotAction[];
    }
  | {
      /** A generation just started; the card can poll it to completion. */
      directive: 'generation';
      /** Article generation, or an emailed product-content job. */
      kind: 'article' | 'content';
      /** The article id to poll to "ready", for an article generation. */
      articleId?: string;
      /** The content-generator job id to poll, for a content generation. */
      jobId?: string;
    }
  | {
      /** A knowledge-base draft is ready; open it in the review modal. */
      directive: 'kb_document';
      /** The draft's stored file name on the Knowledge Base page. */
      fileName: string;
    }
  | {
      /** A popup-customization proposal; pre-fill the Popup Settings form. */
      directive: 'customize';
      /** The proposed colors, messages, placeholders, and quick actions. */
      suggestion: ICopilotPopupCustomization;
    }
  | {
      /** Generated quick-action icons; set them on the Popup Settings form. */
      directive: 'quick_action_icons';
      /** Generated icons in slot order. */
      icons: ICopilotQuickActionIcon[];
    };

/** One proposed quick-action chip: a short label and the query it runs. */
export interface ICopilotPopupQuickAction {
  label: string;
  query: string;
}

/** A generated quick-action icon: its label and the stored image URL. */
export interface ICopilotQuickActionIcon {
  label: string;
  icon_url: string;
}

/** A copilot popup-customization proposal for the live gradient widget. */
export interface ICopilotPopupCustomization {
  text_color: string;
  button_color: string;
  cart_icon_color: string;
  gradient_left: string;
  gradient_right: string;
  header_message: string;
  expanded_message: string;
  search_placeholders: string[];
  quick_actions: ICopilotPopupQuickAction[];
  rationale: string;
}

export interface ICopilotStreamHandlers {
  /** Called when a tool/thinking step starts or finishes. */
  onStep: (step: ICopilotStep) => void;
  /** Called when the agent asks the UI to act (e.g. navigate). */
  onDirective: (directive: ICopilotDirective) => void;
  /** Called with each streamed text fragment. */
  onToken: (text: string) => void;
  /** Called once when the stream completes successfully. */
  onDone: () => void;
  /** Called with a human-readable message when the stream fails. */
  onError: (message: string) => void;
}