// ── SDK v2 — AgentsClient ──────────────────────────────────────────────────────
//
// Covers:
//   GET    /v2/agents
//   POST   /v2/agents
//   GET    /v2/agents/:id
//   PATCH  /v2/agents/:id
//   DELETE /v2/agents/:id
//   POST   /v2/agents/:id/retire
//   GET    /v2/agents/:id/feedback
//   POST   /v2/agents/:id/feedback
//   GET    /v2/agents/:id/feedback/:fid
//   PATCH  /v2/agents/:id/feedback/:fid
//   DELETE /v2/agents/:id/feedback/:fid
//   GET    /v2/agents/:id/supervisor-feedback
//   POST   /v2/agents/:id/supervisor-feedback
//   GET    /v2/agents/:id/supervisor-feedback/:sfid
//   PATCH  /v2/agents/:id/supervisor-feedback/:sfid
//   DELETE /v2/agents/:id/supervisor-feedback/:sfid

import type { Fetcher } from "../http/fetcher";
import type { RequestOptions } from "../http/types";
import type {
  Agent,
  AgentCreate,
  AgentUpdate,
  AgentRetireBody,
  AgentRetireResult,
  AgentFeedback,
  AgentFeedbackCreate,
  AgentFeedbackUpdate,
  SupervisorFeedback,
  SupervisorFeedbackCreate,
  SupervisorFeedbackUpdate,
  ListParams,
  Paginated,
} from "../types/index";

export class AgentsClient {
  constructor(private readonly fetcher: Fetcher) {}

  // ── Agents CRUD ───────────────────────────────────────────────────────────────

  /**
   * Lists agents with cursor pagination and optional DSL filtering.
   *
   * @example
   * ```ts
   * const page = await client.agents.list({ q: "status.eq:active" });
   * ```
   */
  list(params?: ListParams, opts?: RequestOptions): Promise<Paginated<Agent>> {
    return this.fetcher.list<Agent>("/agents", params, opts);
  }

  /**
   * Creates a new agent.
   *
   * @example
   * ```ts
   * const agent = await client.agents.create({
   *   team_id: "team-abc",
   *   name: "Baggage Agent",
   *   kind: "task",
   * });
   * ```
   */
  create(data: AgentCreate, opts?: RequestOptions): Promise<Agent> {
    return this.fetcher.post<Agent>("/agents", data, opts);
  }

  /**
   * Gets a single agent by ID.
   *
   * @throws {NotFoundError} when no agent with `id` exists.
   */
  get(id: string, opts?: RequestOptions): Promise<Agent> {
    return this.fetcher.get<Agent>(`/agents/${id}`, undefined, opts);
  }

  /**
   * Partially updates an agent. Only provided fields are changed.
   *
   * @throws {NotFoundError} when no agent with `id` exists.
   */
  update(id: string, data: AgentUpdate, opts?: RequestOptions): Promise<Agent> {
    return this.fetcher.patch<Agent>(`/agents/${id}`, data, opts);
  }

  /**
   * Permanently deletes an agent.
   *
   * @throws {NotFoundError} when no agent with `id` exists.
   */
  delete(id: string, opts?: RequestOptions): Promise<void> {
    return this.fetcher.delete(`/agents/${id}`, opts);
  }

  /**
   * Retires an agent — removes it from active boards according to the
   * specified action (`remove` or `keep`) per board.
   *
   * @example
   * ```ts
   * const result = await client.agents.retire(agentId, {
   *   boards: [
   *     { board_id: "board-1", action: "remove" },
   *     { board_id: "board-2", action: "keep" },
   *   ],
   * });
   * console.log(result.retired_from); // board IDs where agent was removed
   * ```
   */
  retire(
    id: string,
    data: AgentRetireBody,
    opts?: RequestOptions,
  ): Promise<AgentRetireResult> {
    return this.fetcher.post<AgentRetireResult>(`/agents/${id}/retire`, data, opts);
  }

  // ── Agent Feedback ────────────────────────────────────────────────────────────

  /**
   * Lists feedback entries for an agent.
   *
   * @example
   * ```ts
   * const page = await client.agents.listFeedback(agentId, {
   *   q: "evaluation.eq:positive",
   * });
   * ```
   */
  listFeedback(
    agentId: string,
    params?: ListParams,
    opts?: RequestOptions,
  ): Promise<Paginated<AgentFeedback>> {
    return this.fetcher.list<AgentFeedback>(
      `/agents/${agentId}/feedback`,
      params,
      opts,
    );
  }

  /**
   * Creates a feedback entry for an agent.
   *
   * @example
   * ```ts
   * const feedback = await client.agents.createFeedback(agentId, {
   *   type: "human",
   *   evaluation: "positive",
   *   comment: "Handled the baggage claim perfectly.",
   *   card_id: "card-123",
   * });
   * ```
   */
  createFeedback(
    agentId: string,
    data: AgentFeedbackCreate,
    opts?: RequestOptions,
  ): Promise<AgentFeedback> {
    return this.fetcher.post<AgentFeedback>(
      `/agents/${agentId}/feedback`,
      data,
      opts,
    );
  }

  /**
   * Gets a single feedback entry by ID.
   *
   * @throws {NotFoundError} when the feedback entry doesn't exist.
   */
  getFeedback(
    agentId: string,
    feedbackId: string,
    opts?: RequestOptions,
  ): Promise<AgentFeedback> {
    return this.fetcher.get<AgentFeedback>(
      `/agents/${agentId}/feedback/${feedbackId}`,
      undefined,
      opts,
    );
  }

  /**
   * Updates a feedback entry.
   *
   * @throws {NotFoundError} when the feedback entry doesn't exist.
   */
  updateFeedback(
    agentId: string,
    feedbackId: string,
    data: AgentFeedbackUpdate,
    opts?: RequestOptions,
  ): Promise<AgentFeedback> {
    return this.fetcher.patch<AgentFeedback>(
      `/agents/${agentId}/feedback/${feedbackId}`,
      data,
      opts,
    );
  }

  /**
   * Deletes a feedback entry.
   *
   * @throws {NotFoundError} when the feedback entry doesn't exist.
   */
  deleteFeedback(
    agentId: string,
    feedbackId: string,
    opts?: RequestOptions,
  ): Promise<void> {
    return this.fetcher.delete(
      `/agents/${agentId}/feedback/${feedbackId}`,
      opts,
    );
  }

  // ── Supervisor Feedback ───────────────────────────────────────────────────────

  /**
   * Lists supervisor feedback entries for an agent.
   *
   * @example
   * ```ts
   * const page = await client.agents.listSupervisorFeedback(agentId);
   * ```
   */
  listSupervisorFeedback(
    agentId: string,
    params?: ListParams,
    opts?: RequestOptions,
  ): Promise<Paginated<SupervisorFeedback>> {
    return this.fetcher.list<SupervisorFeedback>(
      `/agents/${agentId}/supervisor-feedback`,
      params,
      opts,
    );
  }

  /**
   * Creates a supervisor feedback entry for an agent.
   *
   * @example
   * ```ts
   * const sf = await client.agents.createSupervisorFeedback(agentId, {
   *   comment: "Needs improvement on edge cases.",
   *   card_id: "card-456",
   * });
   * ```
   */
  createSupervisorFeedback(
    agentId: string,
    data: SupervisorFeedbackCreate,
    opts?: RequestOptions,
  ): Promise<SupervisorFeedback> {
    return this.fetcher.post<SupervisorFeedback>(
      `/agents/${agentId}/supervisor-feedback`,
      data,
      opts,
    );
  }

  /**
   * Gets a single supervisor feedback entry by ID.
   *
   * @throws {NotFoundError} when the entry doesn't exist.
   */
  getSupervisorFeedback(
    agentId: string,
    supervisorFeedbackId: string,
    opts?: RequestOptions,
  ): Promise<SupervisorFeedback> {
    return this.fetcher.get<SupervisorFeedback>(
      `/agents/${agentId}/supervisor-feedback/${supervisorFeedbackId}`,
      undefined,
      opts,
    );
  }

  /**
   * Updates a supervisor feedback entry.
   *
   * @throws {NotFoundError} when the entry doesn't exist.
   */
  updateSupervisorFeedback(
    agentId: string,
    supervisorFeedbackId: string,
    data: SupervisorFeedbackUpdate,
    opts?: RequestOptions,
  ): Promise<SupervisorFeedback> {
    return this.fetcher.patch<SupervisorFeedback>(
      `/agents/${agentId}/supervisor-feedback/${supervisorFeedbackId}`,
      data,
      opts,
    );
  }

  /**
   * Deletes a supervisor feedback entry.
   *
   * @throws {NotFoundError} when the entry doesn't exist.
   */
  deleteSupervisorFeedback(
    agentId: string,
    supervisorFeedbackId: string,
    opts?: RequestOptions,
  ): Promise<void> {
    return this.fetcher.delete(
      `/agents/${agentId}/supervisor-feedback/${supervisorFeedbackId}`,
      opts,
    );
  }
}