// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

import { APIResource } from '../core/resource';
import { APIPromise } from '../core/api-promise';
import { Cursor, type CursorParams, PagePromise } from '../core/pagination';
import { buildHeaders } from '../internal/headers';
import { RequestOptions } from '../internal/request-options';
import { path } from '../internal/utils/path';

export class Conversations extends APIResource {
  /**
   * Get details of a specific conversation including all messages.
   */
  retrieve(id: string, options?: RequestOptions): APIPromise<ConversationRetrieveResponse> {
    return this._client.get(path`/conversations/${id}`, options);
  }

  /**
   * List conversations for the project with optional filtering.
   *
   * Conversations store chat history between users and agents. Use filters to narrow
   * down results by agent name or identity fields.
   *
   * **Filters:**
   *
   * - `agent_name`: Filter by agent name
   * - `identity.*`: Filter by identity fields (e.g., identity.user_id=user_123)
   */
  list(
    query: ConversationListParams | null | undefined = {},
    options?: RequestOptions,
  ): PagePromise<ConversationsCursor, Conversation> {
    return this._client.getAPIList('/conversations', Cursor<Conversation>, { query, ...options });
  }

  /**
   * Delete a conversation and all its messages. This action cannot be undone.
   */
  delete(id: string, options?: RequestOptions): APIPromise<void> {
    return this._client.delete(path`/conversations/${id}`, {
      ...options,
      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
    });
  }
}

export type ConversationsCursor = Cursor<Conversation>;

export interface Conversation {
  /**
   * Unique conversation ID
   */
  id: string;

  /**
   * Agent name
   */
  agentName: string;

  /**
   * When the conversation was created
   */
  createdAt: string;

  /**
   * Identity fields for conversation scoping
   */
  identity: { [key: string]: unknown };

  /**
   * Project ID
   */
  projectId: string;

  /**
   * When the conversation was last updated
   */
  updatedAt: string;
}

export interface ConversationRetrieveResponse extends Conversation {
  /**
   * Conversation messages
   */
  messages: Array<ConversationRetrieveResponse.Message>;
}

export namespace ConversationRetrieveResponse {
  export interface Message {
    /**
     * Unique message ID
     */
    id: string;

    /**
     * Message content
     */
    content: string | Array<unknown> | null;

    /**
     * Conversation ID
     */
    conversationId: string;

    /**
     * When the message was created
     */
    createdAt: string;

    /**
     * Tool name (for tool messages)
     */
    name: string | null;

    /**
     * Message role
     */
    role: 'system' | 'user' | 'assistant' | 'tool' | 'developer';

    /**
     * Tool call ID (for tool messages)
     */
    toolCallId: string | null;

    /**
     * Tool calls (for assistant messages)
     */
    toolCalls?: unknown;
  }
}

export interface ConversationListParams extends CursorParams {
  /**
   * Filter by agent name
   */
  agent_name?: string;
}

export declare namespace Conversations {
  export {
    type Conversation as Conversation,
    type ConversationRetrieveResponse as ConversationRetrieveResponse,
    type ConversationsCursor as ConversationsCursor,
    type ConversationListParams as ConversationListParams,
  };
}