telnyx 7.16.0 → 7.17.0

package/src/resources/ai/ai.ts

@@ -47,6 +47,7 @@ import {
   Assistant,
   AssistantChatParams,
   AssistantChatResponse,
+  AssistantCloneParams,
   AssistantCreateParams,
   AssistantDeleteResponse,
   AssistantGetTexmlResponse,
@@ -64,6 +65,7 @@ import {
   AuthenticationMethod,
   BooleanOpExpression,
   ComparisonExpression,
+  ConversationFlow,
   ConversationFlowReq,
   EnabledFeatures,
   Expression,
@@ -72,6 +74,8 @@ import {
   FallbackConfig,
   FallbackConfigReq,
   FlowEdge,
+  FlowNode,
+  FlowNodeReq,
   HangupTool,
   HangupToolParams,
   ImportMetadata,
@@ -89,8 +93,12 @@ import {
   PrivacySettings,
   PromptSyncStatus,
   RetrievalTool,
+  SpeakNode,
+  SpeakNodeReq,
   StartSpeakingPlan,
   TelephonySettings,
+  ToolNode,
+  ToolNodeReq,
   TranscriptionEndpointingPlan,
   TranscriptionSettings,
   TranscriptionSettingsConfig,
@@ -107,6 +115,7 @@ import {
   CollectionListParams,
   CollectionRetrieveDocumentsParams,
   CollectionRetrieveDocumentsResponse,
+  CollectionRetrieveDocumentsResponsesDefaultFlatPagination,
   CollectionUpdateParams,
   Collections,
   CollectionsDefaultFlatPagination,
@@ -158,6 +167,8 @@ import {
 import * as OpenAIAPI from './openai/openai';
 import { OpenAI, OpenAICreateResponseParams, OpenAICreateResponseResponse } from './openai/openai';
 import { APIPromise } from '../../core/api-promise';
+import { DefaultFlatPagination, type DefaultFlatPaginationParams, PagePromise } from '../../core/pagination';
+import { buildHeaders } from '../../internal/headers';
 import { RequestOptions } from '../../internal/request-options';
 
 export class AI extends APIResource {
@@ -198,8 +209,16 @@ export class AI extends APIResource {
    * });
    * ```
    */
-  summarize(body: AISummarizeParams, options?: RequestOptions): APIPromise<AISummarizeResponse> {
-    return this._client.post('/ai/summarize', { body, ...options });
+  summarize(params: AISummarizeParams, options?: RequestOptions): APIPromise<AISummarizeResponse> {
+    const { 'Idempotency-Key': idempotencyKey, ...body } = params;
+    return this._client.post('/ai/summarize', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        { ...(idempotencyKey != null ? { 'Idempotency-Key': idempotencyKey } : undefined) },
+        options?.headers,
+      ]),
+    });
   }
 
   /**
@@ -255,20 +274,32 @@ export class AI extends APIResource {
    *
    * @example
    * ```ts
-   * const response =
-   *   await client.ai.retrieveConversationHistories({
-   *     q: 'customer called about billing issue',
-   *   });
+   * // Automatically fetches more pages as needed.
+   * for await (const aiRetrieveConversationHistoriesResponse of client.ai.retrieveConversationHistories(
+   *   { q: 'customer called about billing issue' },
+   * )) {
+   *   // ...
+   * }
    * ```
    */
   retrieveConversationHistories(
     query: AIRetrieveConversationHistoriesParams,
     options?: RequestOptions,
-  ): APIPromise<AIRetrieveConversationHistoriesResponse> {
-    return this._client.get('/ai/conversation_histories', { query, ...options });
+  ): PagePromise<
+    AIRetrieveConversationHistoriesResponsesDefaultFlatPagination,
+    AIRetrieveConversationHistoriesResponse
+  > {
+    return this._client.getAPIList(
+      '/ai/conversation_histories',
+      DefaultFlatPagination<AIRetrieveConversationHistoriesResponse>,
+      { query, ...options },
+    );
   }
 }
 
+export type AIRetrieveConversationHistoriesResponsesDefaultFlatPagination =
+  DefaultFlatPagination<AIRetrieveConversationHistoriesResponse>;
+
 /**
  * Metadata for a model available on Telnyx Inference. Returned by
  * `GET /v2/ai/openai/models` (and the deprecated `GET /v2/ai/models`). Open-source
@@ -411,116 +442,73 @@ export interface ModelsResponse {
 }
 
 /**
- * Search response following the standard Telnyx V2 API format.
+ * A single search result representing one chunk of a conversation history record.
+ * Records are split into chunks of up to 480 tokens with 64-token overlap at
+ * ingestion time.
  */
 export interface AIRetrieveConversationHistoriesResponse {
   /**
-   * Ranked list of matching text chunks, sorted by cosine similarity score
-   * descending.
+   * Unique chunk identifier.
    */
-  data: Array<AIRetrieveConversationHistoriesResponse.Data>;
+  id: string;
 
   /**
-   * Pagination metadata following the standard Telnyx V2 API format.
+   * Zero-based index of this chunk within the parent record.
    */
-  meta: AIRetrieveConversationHistoriesResponse.Meta;
-}
+  chunk_index: number;
 
-export namespace AIRetrieveConversationHistoriesResponse {
   /**
-   * A single search result representing one chunk of a conversation history record.
-   * Records are split into chunks of up to 480 tokens with 64-token overlap at
-   * ingestion time.
+   * Total number of chunks the parent record was split into.
    */
-  export interface Data {
-    /**
-     * Unique chunk identifier.
-     */
-    id: string;
-
-    /**
-     * Zero-based index of this chunk within the parent record.
-     */
-    chunk_index: number;
-
-    /**
-     * Total number of chunks the parent record was split into.
-     */
-    chunk_total: number;
-
-    /**
-     * When the record was chunked, embedded, and indexed (ISO 8601).
-     */
-    ingested_at: string;
-
-    /**
-     * Identifier of the organization that owns this record.
-     */
-    organization_id: string;
-
-    /**
-     * When the original record was created (ISO 8601).
-     */
-    record_created_at: string;
-
-    /**
-     * Identifier of the parent record. Multiple chunks from the same record share this
-     * ID.
-     */
-    record_id: string;
-
-    /**
-     * The region where this record is stored.
-     */
-    region: 'USA' | 'DEU' | 'AUS' | 'UAE';
-
-    /**
-     * Cosine similarity score between the query vector and this chunk's vector. Higher
-     * values indicate greater semantic relevance.
-     */
-    score: number;
-
-    /**
-     * The text content of this chunk (up to 480 tokens).
-     */
-    text: string;
-
-    /**
-     * Identifier of the user who owns this record.
-     */
-    user_id: string;
-
-    /**
-     * Arbitrary metadata attached to the record at ingestion time. Filterable via
-     * filter[field]=value query parameters.
-     */
-    metadata?: { [key: string]: unknown };
-  }
+  chunk_total: number;
+
+  /**
+   * When the record was chunked, embedded, and indexed (ISO 8601).
+   */
+  ingested_at: string;
+
+  /**
+   * Identifier of the organization that owns this record.
+   */
+  organization_id: string;
 
   /**
-   * Pagination metadata following the standard Telnyx V2 API format.
+   * When the original record was created (ISO 8601).
    */
-  export interface Meta {
-    /**
-     * Current page number (1-based), matching the requested page[number].
-     */
-    page_number: number;
+  record_created_at: string;
 
-    /**
-     * Number of results per page, matching the requested page[size].
-     */
-    page_size: number;
+  /**
+   * Identifier of the parent record. Multiple chunks from the same record share this
+   * ID.
+   */
+  record_id: string;
 
-    /**
-     * Total number of pages.
-     */
-    total_pages: number;
+  /**
+   * The region where this record is stored.
+   */
+  region: 'USA' | 'DEU' | 'AUS' | 'UAE';
 
-    /**
-     * Total number of matching results across all queried regions.
-     */
-    total_results: number;
-  }
+  /**
+   * Cosine similarity score between the query vector and this chunk's vector. Higher
+   * values indicate greater semantic relevance.
+   */
+  score: number;
+
+  /**
+   * The text content of this chunk (up to 480 tokens).
+   */
+  text: string;
+
+  /**
+   * Identifier of the user who owns this record.
+   */
+  user_id: string;
+
+  /**
+   * Arbitrary metadata attached to the record at ingestion time. Filterable via
+   * filter[field]=value query parameters.
+   */
+  metadata?: { [key: string]: unknown };
 }
 
 export interface AISummarizeResponse {
@@ -535,22 +523,34 @@ export namespace AISummarizeResponse {
 
 export interface AISummarizeParams {
   /**
-   * The name of the bucket that contains the file to be summarized.
+   * Body param: The name of the bucket that contains the file to be summarized.
    */
   bucket: string;
 
   /**
-   * The name of the file to be summarized.
+   * Body param: The name of the file to be summarized.
    */
   filename: string;
 
   /**
-   * A system prompt to guide the summary generation.
+   * Body param: A system prompt to guide the summary generation.
    */
   system_prompt?: string;
+
+  /**
+   * Header param: Optional opaque, unquoted key for safely retrying the same logical
+   * request. Keys must contain 1 to 255 letters, numbers, hyphens, or underscores.
+   * Generate a unique UUID v4 for each operation and reuse it only when retrying
+   * that operation with the same request. Invalid headers—including duplicate,
+   * empty, malformed, or overlong values—return 400 with error code 10015. A request
+   * already in progress with the same key returns 409; reusing the key with a
+   * different request returns 422. Only successful responses are replayed, for up to
+   * 24 hours. Do not include sensitive data in the key.
+   */
+  'Idempotency-Key'?: string;
 }
 
-export interface AIRetrieveConversationHistoriesParams {
+export interface AIRetrieveConversationHistoriesParams extends DefaultFlatPaginationParams {
   /**
    * Natural language search query. The text is embedded into a 1024-dimensional
    * vector and compared against indexed record chunks using semantic similarity.
@@ -610,16 +610,6 @@ export interface AIRetrieveConversationHistoriesParams {
    */
   min_score?: number;
 
-  /**
-   * Page number to return (1-based). Defaults to 1.
-   */
-  'page[number]'?: number;
-
-  /**
-   * Number of results per page. Defaults to 20, maximum 100.
-   */
-  'page[size]'?: number;
-
   /**
    * Restrict search to a specific region. When omitted, all regions are queried in
    * parallel (fan-out) and results are merged by similarity score.
@@ -648,6 +638,7 @@ export declare namespace AI {
     type ModelsResponse as ModelsResponse,
     type AIRetrieveConversationHistoriesResponse as AIRetrieveConversationHistoriesResponse,
     type AISummarizeResponse as AISummarizeResponse,
+    type AIRetrieveConversationHistoriesResponsesDefaultFlatPagination as AIRetrieveConversationHistoriesResponsesDefaultFlatPagination,
     type AISummarizeParams as AISummarizeParams,
     type AIRetrieveConversationHistoriesParams as AIRetrieveConversationHistoriesParams,
   };
@@ -664,6 +655,7 @@ export declare namespace AI {
     type AuthenticationMethod as AuthenticationMethod,
     type BooleanOpExpression as BooleanOpExpression,
     type ComparisonExpression as ComparisonExpression,
+    type ConversationFlow as ConversationFlow,
     type ConversationFlowReq as ConversationFlowReq,
     type EnabledFeatures as EnabledFeatures,
     type Expression as Expression,
@@ -672,6 +664,8 @@ export declare namespace AI {
     type FallbackConfig as FallbackConfig,
     type FallbackConfigReq as FallbackConfigReq,
     type FlowEdge as FlowEdge,
+    type FlowNode as FlowNode,
+    type FlowNodeReq as FlowNodeReq,
     type HangupTool as HangupTool,
     type HangupToolParams as HangupToolParams,
     type ImportMetadata as ImportMetadata,
@@ -689,8 +683,12 @@ export declare namespace AI {
     type PrivacySettings as PrivacySettings,
     type PromptSyncStatus as PromptSyncStatus,
     type RetrievalTool as RetrievalTool,
+    type SpeakNode as SpeakNode,
+    type SpeakNodeReq as SpeakNodeReq,
     type StartSpeakingPlan as StartSpeakingPlan,
     type TelephonySettings as TelephonySettings,
+    type ToolNode as ToolNode,
+    type ToolNodeReq as ToolNodeReq,
     type TranscriptionEndpointingPlan as TranscriptionEndpointingPlan,
     type TranscriptionSettings as TranscriptionSettings,
     type TranscriptionSettingsConfig as TranscriptionSettingsConfig,
@@ -707,6 +705,7 @@ export declare namespace AI {
     type AssistantRetrieveParams as AssistantRetrieveParams,
     type AssistantUpdateParams as AssistantUpdateParams,
     type AssistantChatParams as AssistantChatParams,
+    type AssistantCloneParams as AssistantCloneParams,
     type AssistantSendSMSParams as AssistantSendSMSParams,
   };
 
@@ -737,6 +736,7 @@ export declare namespace AI {
     type CollectionEnvelope as CollectionEnvelope,
     type CollectionRetrieveDocumentsResponse as CollectionRetrieveDocumentsResponse,
     type CollectionsDefaultFlatPagination as CollectionsDefaultFlatPagination,
+    type CollectionRetrieveDocumentsResponsesDefaultFlatPagination as CollectionRetrieveDocumentsResponsesDefaultFlatPagination,
     type CollectionListParams as CollectionListParams,
     type CollectionCreateParams as CollectionCreateParams,
     type CollectionRetrieveDocumentsParams as CollectionRetrieveDocumentsParams,