telnyx 7.13.0 → 7.14.0

package/src/resources/ai/collections/settings.ts

@@ -0,0 +1,124 @@
+// 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 { RequestOptions } from '../../../internal/request-options';
+import { path } from '../../../internal/utils/path';
+
+/**
+ * Create and manage logical collections of your Telnyx data, tune retrieval settings, manage sources, and run collection-scoped semantic search.
+ */
+export class Settings extends APIResource {
+  /**
+   * Returns the retrieval settings for a collection.
+   *
+   * @example
+   * ```ts
+   * const settingsEnvelope =
+   *   await client.ai.collections.settings.list(
+   *     '6a09ccbd-8f9b-4c3a-9b0e-2f1d3c4b5a6e',
+   *   );
+   * ```
+   */
+  list(uuid: string, options?: RequestOptions): APIPromise<SettingsEnvelope> {
+    return this._client.get(path`/ai/collections/${uuid}/settings`, options);
+  }
+
+  /**
+   * Partially updates the collection's retrieval settings.
+   *
+   * @example
+   * ```ts
+   * const settingsEnvelope =
+   *   await client.ai.collections.settings.patchAll(
+   *     '6a09ccbd-8f9b-4c3a-9b0e-2f1d3c4b5a6e',
+   *   );
+   * ```
+   */
+  patchAll(
+    uuid: string,
+    body: SettingPatchAllParams,
+    options?: RequestOptions,
+  ): APIPromise<SettingsEnvelope> {
+    return this._client.patch(path`/ai/collections/${uuid}/settings`, { body, ...options });
+  }
+
+  /**
+   * Replaces the collection's retrieval settings.
+   *
+   * @example
+   * ```ts
+   * const settingsEnvelope =
+   *   await client.ai.collections.settings.create(
+   *     '6a09ccbd-8f9b-4c3a-9b0e-2f1d3c4b5a6e',
+   *   );
+   * ```
+   */
+  create(uuid: string, body: SettingCreateParams, options?: RequestOptions): APIPromise<SettingsEnvelope> {
+    return this._client.put(path`/ai/collections/${uuid}/settings`, { body, ...options });
+  }
+}
+
+/**
+ * How documents are retrieved when searching the collection.
+ */
+export interface RetrievalSettings {
+  /**
+   * Retrieval strategy. `vector` runs semantic similarity search; `hybrid` combines
+   * vector similarity with keyword matching; `keyword` runs lexical (BM25) matching.
+   */
+  retrieval_type?: 'vector' | 'hybrid' | 'keyword';
+
+  /**
+   * Number of top results to retrieve (1–50).
+   */
+  top_k?: number;
+}
+
+export interface RetrievalSettingsWrapper {
+  /**
+   * Identifies the record type. Always `ai_collection_settings`.
+   */
+  record_type?: string;
+
+  /**
+   * How documents are retrieved when searching the collection.
+   */
+  retrieval?: RetrievalSettings;
+}
+
+export interface SettingsEnvelope {
+  data?: RetrievalSettingsWrapper;
+}
+
+export interface SettingsRequest {
+  /**
+   * How documents are retrieved when searching the collection.
+   */
+  retrieval?: RetrievalSettings;
+}
+
+export interface SettingPatchAllParams {
+  /**
+   * How documents are retrieved when searching the collection.
+   */
+  retrieval?: RetrievalSettings;
+}
+
+export interface SettingCreateParams {
+  /**
+   * How documents are retrieved when searching the collection.
+   */
+  retrieval?: RetrievalSettings;
+}
+
+export declare namespace Settings {
+  export {
+    type RetrievalSettings as RetrievalSettings,
+    type RetrievalSettingsWrapper as RetrievalSettingsWrapper,
+    type SettingsEnvelope as SettingsEnvelope,
+    type SettingsRequest as SettingsRequest,
+    type SettingPatchAllParams as SettingPatchAllParams,
+    type SettingCreateParams as SettingCreateParams,
+  };
+}

package/src/resources/ai/collections/sources.ts

@@ -0,0 +1,202 @@
+// 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 { buildHeaders } from '../../../internal/headers';
+import { RequestOptions } from '../../../internal/request-options';
+import { path } from '../../../internal/utils/path';
+
+/**
+ * Create and manage logical collections of your Telnyx data, tune retrieval settings, manage sources, and run collection-scoped semantic search.
+ */
+export class Sources extends APIResource {
+  /**
+   * Returns the sources attached to a collection.
+   *
+   * @example
+   * ```ts
+   * const sources = await client.ai.collections.sources.list(
+   *   '6a09ccbd-8f9b-4c3a-9b0e-2f1d3c4b5a6e',
+   * );
+   * ```
+   */
+  list(uuid: string, options?: RequestOptions): APIPromise<SourceListResponse> {
+    return this._client.get(path`/ai/collections/${uuid}/sources`, options);
+  }
+
+  /**
+   * Attaches a new source to a collection.
+   *
+   * @example
+   * ```ts
+   * const source = await client.ai.collections.sources.create(
+   *   '6a09ccbd-8f9b-4c3a-9b0e-2f1d3c4b5a6e',
+   *   { source_type: 'voice' },
+   * );
+   * ```
+   */
+  create(uuid: string, body: SourceCreateParams, options?: RequestOptions): APIPromise<SourceCreateResponse> {
+    return this._client.post(path`/ai/collections/${uuid}/sources`, { body, ...options });
+  }
+
+  /**
+   * Replaces the collection's entire source set. The response `meta` reports which
+   * sources were added, retained, and removed.
+   *
+   * @example
+   * ```ts
+   * const response =
+   *   await client.ai.collections.sources.replace(
+   *     '6a09ccbd-8f9b-4c3a-9b0e-2f1d3c4b5a6e',
+   *     { sources: [{ source_type: 'voice' }] },
+   *   );
+   * ```
+   */
+  replace(
+    uuid: string,
+    body: SourceReplaceParams,
+    options?: RequestOptions,
+  ): APIPromise<SourceReplaceResponse> {
+    return this._client.put(path`/ai/collections/${uuid}/sources`, { body, ...options });
+  }
+
+  /**
+   * Removes a single source from a collection.
+   *
+   * @example
+   * ```ts
+   * await client.ai.collections.sources.delete('42', {
+   *   uuid: '6a09ccbd-8f9b-4c3a-9b0e-2f1d3c4b5a6e',
+   * });
+   * ```
+   */
+  delete(sourceID: string, params: SourceDeleteParams, options?: RequestOptions): APIPromise<void> {
+    const { uuid } = params;
+    return this._client.delete(path`/ai/collections/${uuid}/sources/${sourceID}`, {
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+}
+
+export interface Source {
+  id?: string;
+
+  /**
+   * The Telnyx Storage bucket name. Present only for `bucket` sources.
+   */
+  bucket_id?: string;
+
+  collection_id?: string;
+
+  /**
+   * Identifies the record type. Always `ai_collection_source`.
+   */
+  record_type?: string;
+
+  /**
+   * The type of Telnyx data attached as a source. `bucket` requires an additional
+   * `bucket_id`. Only `voice` is searchable today; `meeting_bot`, `message`, and
+   * `bucket` attach but are not yet searchable (Coming soon).
+   */
+  source_type?: SourceType;
+
+  status?: string;
+}
+
+export interface SourceRequest {
+  /**
+   * The type of Telnyx data attached as a source. `bucket` requires an additional
+   * `bucket_id`. Only `voice` is searchable today; `meeting_bot`, `message`, and
+   * `bucket` attach but are not yet searchable (Coming soon).
+   */
+  source_type: SourceType;
+
+  /**
+   * The Telnyx Storage bucket name. Required when `source_type` is `bucket`; ignored
+   * otherwise.
+   */
+  bucket_id?: string;
+}
+
+/**
+ * The type of Telnyx data attached as a source. `bucket` requires an additional
+ * `bucket_id`. Only `voice` is searchable today; `meeting_bot`, `message`, and
+ * `bucket` attach but are not yet searchable (Coming soon).
+ */
+export type SourceType = 'voice' | 'meeting_bot' | 'message' | 'bucket';
+
+/**
+ * Envelope containing a single collection source.
+ */
+export interface SourceCreateResponse {
+  data?: Source;
+}
+
+export interface SourceListResponse {
+  data?: Array<Source>;
+}
+
+export interface SourceReplaceResponse {
+  data?: Array<Source>;
+
+  /**
+   * Reports which source IDs were added, retained, and removed by a replace
+   * operation.
+   */
+  meta?: SourceReplaceResponse.Meta;
+}
+
+export namespace SourceReplaceResponse {
+  /**
+   * Reports which source IDs were added, retained, and removed by a replace
+   * operation.
+   */
+  export interface Meta {
+    added?: Array<string>;
+
+    removed?: Array<string>;
+
+    retained?: Array<string>;
+  }
+}
+
+export interface SourceCreateParams {
+  /**
+   * The type of Telnyx data attached as a source. `bucket` requires an additional
+   * `bucket_id`. Only `voice` is searchable today; `meeting_bot`, `message`, and
+   * `bucket` attach but are not yet searchable (Coming soon).
+   */
+  source_type: SourceType;
+
+  /**
+   * The Telnyx Storage bucket name. Required when `source_type` is `bucket`; ignored
+   * otherwise.
+   */
+  bucket_id?: string;
+}
+
+export interface SourceReplaceParams {
+  sources: Array<SourceRequest>;
+}
+
+export interface SourceDeleteParams {
+  /**
+   * The collection's unique identifier.
+   */
+  uuid: string;
+}
+
+export declare namespace Sources {
+  export {
+    type Source as Source,
+    type SourceRequest as SourceRequest,
+    type SourceType as SourceType,
+    type SourceCreateResponse as SourceCreateResponse,
+    type SourceListResponse as SourceListResponse,
+    type SourceReplaceResponse as SourceReplaceResponse,
+    type SourceCreateParams as SourceCreateParams,
+    type SourceReplaceParams as SourceReplaceParams,
+    type SourceDeleteParams as SourceDeleteParams,
+  };
+}

package/src/resources/ai/collections.ts

@@ -0,0 +1,3 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export * from './collections/index';

package/src/resources/ai/conversations/conversations.ts

@@ -74,7 +74,9 @@ export class Conversations extends APIResource {
    *
    * @example
    * ```ts
-   * const conversation = await client.ai.conversations.create();
+   * const conversation = await client.ai.conversations.create({
+   *   name: 'string',
+   * });
    * ```
    */
   create(body: ConversationCreateParams, options?: RequestOptions): APIPromise<Conversation> {
@@ -117,6 +119,7 @@ export class Conversations extends APIResource {
    * ```ts
    * const conversation = await client.ai.conversations.update(
    *   'conversation_id',
+   *   { metadata: { ai_disabled: 'true' } },
    * );
    * ```
    */
@@ -154,7 +157,14 @@ export class Conversations extends APIResource {
    * ```ts
    * await client.ai.conversations.addMessage(
    *   '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
-   *   { role: 'role' },
+   *   {
+   *     role: 'Role',
+   *     name: 'Name',
+   *     sent_at: '2024-01-23T18:10:02.574Z',
+   *     tool_call_id: 'Tool Call Id',
+   *     tool_calls: [],
+   *     tool_choice: 'string',
+   *   },
    * );
    * ```
    */

package/src/resources/ai/conversations/insight-groups/insight-groups.ts

@@ -49,7 +49,7 @@ export class InsightGroups extends APIResource {
    * ```ts
    * const insightTemplateGroupDetail =
    *   await client.ai.conversations.insightGroups.insightGroups(
-   *     { name: 'name' },
+   *     { name: 'Name', description: 'Description' },
    *   );
    * ```
    */
@@ -100,6 +100,11 @@ export class InsightGroups extends APIResource {
    * const insightTemplateGroupDetail =
    *   await client.ai.conversations.insightGroups.update(
    *     '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   *     {
+   *       description: 'Description',
+   *       name: 'Name',
+   *       webhook: 'Webhook',
+   *     },
    *   );
    * ```
    */

package/src/resources/ai/conversations/insights.ts

@@ -43,8 +43,9 @@ export class Insights extends APIResource {
    * ```ts
    * const insightTemplateDetail =
    *   await client.ai.conversations.insights.create({
-   *     instructions: 'instructions',
-   *     name: 'name',
+   *     instructions: 'Instructions',
+   *     name: 'Name',
+   *     json_schema: 'string',
    *   });
    * ```
    */
@@ -92,6 +93,12 @@ export class Insights extends APIResource {
    * const insightTemplateDetail =
    *   await client.ai.conversations.insights.update(
    *     '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   *     {
+   *       instructions: 'Instructions',
+   *       json_schema: 'string',
+   *       name: 'Name',
+   *       webhook: 'Webhook',
+   *     },
    *   );
    * ```
    */

package/src/resources/ai/embeddings/embeddings.ts

@@ -65,7 +65,13 @@ export class Embeddings extends APIResource {
    * @example
    * ```ts
    * const embeddingResponse = await client.ai.embeddings.create(
-   *   { bucket_name: 'bucket_name' },
+   *   {
+   *     bucket_name: 'Bucket Name',
+   *     document_chunk_overlap_size: 512,
+   *     document_chunk_size: 1024,
+   *     embedding_model: 'thenlper/gte-large',
+   *     loader: 'default',
+   *   },
    * );
    * ```
    */
@@ -92,8 +98,9 @@ export class Embeddings extends APIResource {
    * ```ts
    * const response =
    *   await client.ai.embeddings.similaritySearch({
-   *     bucket_name: 'bucket_name',
-   *     query: 'query',
+   *     bucket_name: 'Bucket Name',
+   *     query: 'Query',
+   *     num_of_docs: 3,
    *   });
    * ```
    */
@@ -116,8 +123,8 @@ export class Embeddings extends APIResource {
    * @example
    * ```ts
    * const embeddingResponse = await client.ai.embeddings.url({
-   *   bucket_name: 'bucket_name',
-   *   url: 'url',
+   *   bucket_name: 'Bucket Name',
+   *   url: 'URL',
    * });
    * ```
    */

package/src/resources/ai/fine-tuning/jobs.ts

@@ -28,8 +28,10 @@ export class Jobs extends APIResource {
    * ```ts
    * const fineTuningJob =
    *   await client.ai.fineTuning.jobs.create({
-   *     model: 'model',
-   *     training_file: 'training_file',
+   *     model: 'string',
+   *     training_file: 'string',
+   *     hyperparameters: { n_epochs: 3 },
+   *     suffix: 'string',
    *   });
    * ```
    */

package/src/resources/ai/index.ts

@@ -81,6 +81,17 @@ export {
   type ClusterFetchGraphParams,
   type ClusterListResponsesDefaultFlatPagination,
 } from './clusters';
+export {
+  Collections,
+  type Collection,
+  type CollectionEnvelope,
+  type CollectionRetrieveDocumentsResponse,
+  type CollectionListParams,
+  type CollectionCreateParams,
+  type CollectionRetrieveDocumentsParams,
+  type CollectionUpdateParams,
+  type CollectionsDefaultFlatPagination,
+} from './collections/index';
 export {
   Conversations,
   type Conversation,
@@ -133,6 +144,7 @@ export {
   Tools,
   type PayToolParams,
   type SharedToolResponse,
+  type UpdateDynamicVariablesToolParams,
   type ToolDeleteResponse,
   type ToolListParams,
   type ToolCreateParams,

package/src/resources/ai/mcp-servers.ts

@@ -39,9 +39,9 @@ export class McpServers extends APIResource {
    * @example
    * ```ts
    * const mcpServer = await client.ai.mcpServers.create({
-   *   name: 'name',
-   *   type: 'type',
-   *   url: 'url',
+   *   name: 'Name',
+   *   type: 'Type',
+   *   url: 'Url',
    * });
    * ```
    */
@@ -85,6 +85,13 @@ export class McpServers extends APIResource {
    * ```ts
    * const mcpServer = await client.ai.mcpServers.update(
    *   'mcp_server_id',
+   *   {
+   *     id: 'Id',
+   *     created_at: '2024-01-23T18:10:02.574Z',
+   *     name: 'Name',
+   *     type: 'Type',
+   *     url: 'Url',
+   *   },
    * );
    * ```
    */

package/src/resources/ai/missions/missions.ts

@@ -94,7 +94,11 @@ export class Missions extends APIResource {
    * @example
    * ```ts
    * const missionResponse = await client.ai.missions.create({
-   *   name: 'name',
+   *   name: 'Name',
+   *   description: 'Description',
+   *   execution_mode: 'external',
+   *   instructions: 'Instructions',
+   *   model: 'Model',
    * });
    * ```
    */
@@ -162,6 +166,13 @@ export class Missions extends APIResource {
    * const missionResponse =
    *   await client.ai.missions.updateMission(
    *     '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   *     {
+   *       description: 'Description',
+   *       execution_mode: 'external',
+   *       instructions: 'Instructions',
+   *       model: 'Model',
+   *       name: 'Name',
+   *     },
    *   );
    * ```
    */

package/src/resources/ai/missions/runs/events.ts

@@ -48,8 +48,11 @@ export class Events extends APIResource {
    *     '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
    *     {
    *       mission_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
-   *       summary: 'summary',
+   *       summary: 'Summary',
    *       type: 'status_change',
+   *       agent_id: 'Agent Id',
+   *       idempotency_key: 'Idempotency Key',
+   *       step_id: 'Step Id',
    *     },
    *   );
    * ```

package/src/resources/ai/missions/runs/plan.ts

@@ -38,9 +38,10 @@ export class Plan extends APIResource {
    *       mission_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
    *       steps: [
    *         {
-   *           description: 'description',
+   *           step_id: 'Step Id',
+   *           description: 'Description',
    *           sequence: 0,
-   *           step_id: 'step_id',
+   *           parent_step_id: 'Parent Step Id',
    *         },
    *       ],
    *     },
@@ -65,6 +66,7 @@ export class Plan extends APIResource {
    *   await client.ai.missions.runs.plan.updateStep('step_id', {
    *     mission_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
    *     run_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   *     status: 'pending',
    *   });
    * ```
    */
@@ -92,9 +94,10 @@ export class Plan extends APIResource {
    *       mission_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
    *       steps: [
    *         {
-   *           description: 'description',
+   *           step_id: 'Step Id',
+   *           description: 'Description',
    *           sequence: 0,
-   *           step_id: 'step_id',
+   *           parent_step_id: 'Parent Step Id',
    *         },
    *       ],
    *     },

package/src/resources/ai/missions/runs/runs.ts

@@ -85,6 +85,13 @@ export class Runs extends APIResource {
    * const missionRunResponse =
    *   await client.ai.missions.runs.create(
    *     '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   *     {
+   *       input: {
+   *         objective:
+   *           "Summarize yesterday's failed call attempts",
+   *       },
+   *       metadata: { requested_by: 'docs-example' },
+   *     },
    *   );
    * ```
    */
@@ -125,7 +132,12 @@ export class Runs extends APIResource {
    * const missionRunResponse =
    *   await client.ai.missions.runs.update(
    *     '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
-   *     { mission_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e' },
+   *     {
+   *       mission_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   *       result_summary:
+   *         'Processed 24 customer records successfully.',
+   *       status: 'succeeded',
+   *     },
    *   );
    * ```
    */

package/src/resources/ai/missions/runs/telnyx-agents.ts

@@ -38,7 +38,7 @@ export class TelnyxAgents extends APIResource {
    *     '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
    *     {
    *       mission_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
-   *       telnyx_agent_id: 'telnyx_agent_id',
+   *       telnyx_agent_id: 'Telnyx Agent Id',
    *     },
    *   );
    * ```

package/src/resources/ai/openai/openai.ts

@@ -87,7 +87,6 @@ export class OpenAI extends APIResource {
    *   },
    *   instructions: 'You are a friendly chatbot.',
    *   model: 'zai-org/GLM-5.1-FP8',
-   *   stream: true,
    * });
    * ```
    */