// 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 { CursorIDPage, type CursorIDPageParams, PagePromise } from '../../core/pagination';
import { buildHeaders } from '../../internal/headers';
import { RequestOptions } from '../../internal/request-options';
import { path } from '../../internal/utils/path';

export class Calls extends APIResource {
  /**
   * Get Call
   */
  retrieve(callID: string, options?: RequestOptions): APIPromise<AgentCall> {
    return this._client.get(path`/agents/calls/${callID}`, options);
  }

  /**
   * Lists calls sorted by start time in descending order for a specific agent.
   * `agent_id` is required and if you want to include `transcript` in the response,
   * add `expand=transcript` to the request. This endpoint is paginated.
   */
  list(query: CallListParams, options?: RequestOptions): PagePromise<AgentCallsCursorIDPage, AgentCall> {
    return this._client.getAPIList('/agents/calls', CursorIDPage<AgentCall>, { query, ...options });
  }

  /**
   * The downloaded audio file is in .wav format. This endpoint streams the audio
   * file content (WAV format) to the client.
   */
  downloadAudio(callID: string, options?: RequestOptions): APIPromise<void> {
    return this._client.get(path`/agents/calls/${callID}/audio`, {
      ...options,
      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
    });
  }
}

export type AgentCallsCursorIDPage = CursorIDPage<AgentCall>;

export interface AgentCall {
  /**
   * The unique identifier for the agent call.
   */
  id: string;

  /**
   * The identifier of the agent associated with the call.
   */
  agent_id: string;

  /**
   * The status of the agent call.
   */
  status: 'active' | 'completed' | 'failed' | 'cancelled';

  /**
   * The deployment identifier associated with the call.
   */
  deployment_id?: string | null;

  /**
   * The end time of the agent call.
   */
  end_time?: string | null;

  /**
   * The error message, if any, associated with the call.
   */
  error_message?: string | null;

  /**
   * The start time of the agent call.
   */
  start_time?: string | null;

  /**
   * A summary of the agent call. This is a brief summary of the call that is
   * generated by Cartesia.
   */
  summary?: string | null;

  /**
   * The telephony parameters associated with the call when the call is made via
   * phone.
   */
  telephony_params?: AgentCall.TelephonyParams | null;

  /**
   * The transcript of the agent call.
   */
  transcript?: Array<AgentTranscript> | null;
}

export namespace AgentCall {
  /**
   * The telephony parameters associated with the call when the call is made via
   * phone.
   */
  export interface TelephonyParams {
    /**
     * The phone number of the agent.
     */
    from: string;

    /**
     * The phone number of the caller.
     */
    to: string;
  }
}

export interface AgentTranscript {
  /**
   * The end timestamp in seconds relative to the start of the call.
   */
  end_timestamp: number;

  /**
   * The role of the participant in the conversation. Roles are `user`, `assistant`,
   * or `system`. `assistant` is the agent. `system` is used to indicate logs during
   * the conversation such as `log_event` or `log_metric`.
   */
  role: string;

  /**
   * The start timestamp in seconds relative to the start of the call.
   */
  start_timestamp: number;

  /**
   * The reason for why the assistant turn ended. This could be `call_ended`,
   * `interrupted`, or `tts_completed`.
   */
  end_reason?: string | null;

  /**
   * The log event from user code.
   */
  log_event?: AgentTranscript.LogEvent | null;

  /**
   * The log metric from user code.
   */
  log_metric?: AgentTranscript.LogMetric | null;

  /**
   * The text content of the transcript. This is the text that was spoken by the user
   * or the agent.
   */
  text?: string | null;

  /**
   * The chunks of text at a more granular level in the transcript with timestamps
   * relative to the start of the call.
   */
  text_chunks?: Array<AgentTranscript.TextChunk> | null;

  /**
   * The tool calls made during the turn.
   */
  tool_calls?: Array<AgentTranscript.ToolCall> | null;

  /**
   * The time to first byte in seconds from the agent for text-to-speech.
   */
  tts_ttfb?: number | null;

  /**
   * The VAD buffer time in milliseconds.
   */
  vad_buffer_ms?: number | null;
}

export namespace AgentTranscript {
  /**
   * The log event from user code.
   */
  export interface LogEvent {
    /**
     * The event name.
     */
    event: string;

    /**
     * Additional metadata associated with the event.
     */
    metadata: { [key: string]: string };

    /**
     * The timestamp when the event was received relative to the start of the call.
     */
    timestamp: number;
  }

  /**
   * The log metric from user code.
   */
  export interface LogMetric {
    /**
     * The name of the metric.
     */
    name: string;

    /**
     * The timestamp when the metric was received relative to the start of the call.
     */
    timestamp: number;

    /**
     * The value of the metric.
     */
    value: number;
  }

  export interface TextChunk {
    /**
     * The starting timestamp of the text chunk in seconds relative to the start of the
     * call.
     */
    start_timestamp: number;

    /**
     * The text content of the chunk.
     */
    text: string;
  }

  export interface ToolCall {
    /**
     * The unique identifier for the tool call.
     */
    id: string;

    /**
     * The arguments passed to the tool.
     */
    arguments: { [key: string]: string };

    /**
     * The name of the tool that was called.
     */
    name: string;
  }
}

export interface CallListParams extends CursorIDPageParams {
  /**
   * The ID of the agent.
   */
  agent_id: string;

  /**
   * The fields to expand in the response. Currently, the only supported value is
   * `transcript`.
   */
  expand?: string | null;

  /**
   * (Pagination option) The number of calls to return per page, ranging between 1
   * and 100.
   */
  limit?: number | null;
}

export declare namespace Calls {
  export {
    type AgentCall as AgentCall,
    type AgentTranscript as AgentTranscript,
    type AgentCallsCursorIDPage as AgentCallsCursorIDPage,
    type CallListParams as CallListParams,
  };
}