telnyx 6.47.0 → 6.49.0

package/src/resources/ai/assistants/canary-deploys.ts

@@ -21,11 +21,6 @@ export class CanaryDeploys extends APIResource {
    * const canaryDeployResponse =
    *   await client.ai.assistants.canaryDeploys.create(
    *     'assistant_id',
-   *     {
-   *       versions: [
-   *         { percentage: 1, version_id: 'version_id' },
-   *       ],
-   *     },
    *   );
    * ```
    */
@@ -67,11 +62,6 @@ export class CanaryDeploys extends APIResource {
    * const canaryDeployResponse =
    *   await client.ai.assistants.canaryDeploys.update(
    *     'assistant_id',
-   *     {
-   *       versions: [
-   *         { percentage: 1, version_id: 'version_id' },
-   *       ],
-   *     },
    *   );
    * ```
    */
@@ -104,62 +94,321 @@ export class CanaryDeploys extends APIResource {
 }
 
 /**
- * Request model for creating or updating canary deploys.
+ * Create/update request body. Accepts:
+ *
+ * - `rules` — canonical ordered list of routing rules
  */
 export interface CanaryDeploy {
+  rules?: Array<CanaryDeploy.Rule>;
+}
+
+export namespace CanaryDeploy {
   /**
-   * List of version configurations
+   * A targeting rule: `match` clauses (AND) gate `serve`.
+   *
+   * An empty `match` is a catch-all (always fires).
    */
-  versions: Array<VersionConfig>;
+  export interface Rule {
+    /**
+     * What a rule serves when matched.
+     *
+     * Exactly one of:
+     *
+     * - `version_id` — serve a specific version
+     * - `rollout` — weighted random across versions; weights must sum to less than
+     *   100, with the leftover routing to the main version
+     */
+    serve: Rule.Serve;
+
+    match?: Array<Rule.Match>;
+  }
+
+  export namespace Rule {
+    /**
+     * What a rule serves when matched.
+     *
+     * Exactly one of:
+     *
+     * - `version_id` — serve a specific version
+     * - `rollout` — weighted random across versions; weights must sum to less than
+     *   100, with the leftover routing to the main version
+     */
+    export interface Serve {
+      rollout?: Array<Serve.Rollout>;
+
+      version_id?: string;
+    }
+
+    export namespace Serve {
+      /**
+       * One slot in a percentage rollout.
+       */
+      export interface Rollout {
+        version_id: string;
+
+        weight: number;
+      }
+    }
+
+    /**
+     * A single attribute/operator/values check.
+     *
+     * A clause matches when the routing context's value for `attribute` satisfies
+     * `operator` against any of `values`.
+     */
+    export interface Match {
+      /**
+       * Attribute name from the routing context
+       */
+      attribute: string;
+
+      /**
+       * Match operator
+       */
+      operator: 'in' | 'not_in' | 'starts_with';
+
+      values: Array<string>;
+    }
+  }
 }
 
 /**
- * Response model for canary deploy operations.
+ * Response shape.
+ *
+ * Always carries `rules` (canonical).
  */
 export interface CanaryDeployResponse {
   assistant_id: string;
 
   created_at: string;
 
-  updated_at: string;
+  rules: Array<CanaryDeployResponse.Rule>;
 
-  versions: Array<VersionConfig>;
+  updated_at: string;
 }
 
-/**
- * Configuration for a single version in canary deploy.
- */
-export interface VersionConfig {
+export namespace CanaryDeployResponse {
   /**
-   * Percentage of traffic for this version [1-99]
+   * A targeting rule: `match` clauses (AND) gate `serve`.
+   *
+   * An empty `match` is a catch-all (always fires).
    */
-  percentage: number;
+  export interface Rule {
+    /**
+     * What a rule serves when matched.
+     *
+     * Exactly one of:
+     *
+     * - `version_id` — serve a specific version
+     * - `rollout` — weighted random across versions; weights must sum to less than
+     *   100, with the leftover routing to the main version
+     */
+    serve: Rule.Serve;
 
-  /**
-   * Version ID string that references assistant_versions.version_id
-   */
-  version_id: string;
+    match?: Array<Rule.Match>;
+  }
+
+  export namespace Rule {
+    /**
+     * What a rule serves when matched.
+     *
+     * Exactly one of:
+     *
+     * - `version_id` — serve a specific version
+     * - `rollout` — weighted random across versions; weights must sum to less than
+     *   100, with the leftover routing to the main version
+     */
+    export interface Serve {
+      rollout?: Array<Serve.Rollout>;
+
+      version_id?: string;
+    }
+
+    export namespace Serve {
+      /**
+       * One slot in a percentage rollout.
+       */
+      export interface Rollout {
+        version_id: string;
+
+        weight: number;
+      }
+    }
+
+    /**
+     * A single attribute/operator/values check.
+     *
+     * A clause matches when the routing context's value for `attribute` satisfies
+     * `operator` against any of `values`.
+     */
+    export interface Match {
+      /**
+       * Attribute name from the routing context
+       */
+      attribute: string;
+
+      /**
+       * Match operator
+       */
+      operator: 'in' | 'not_in' | 'starts_with';
+
+      values: Array<string>;
+    }
+  }
 }
 
 export interface CanaryDeployCreateParams {
+  rules?: Array<CanaryDeployCreateParams.Rule>;
+}
+
+export namespace CanaryDeployCreateParams {
   /**
-   * List of version configurations
+   * A targeting rule: `match` clauses (AND) gate `serve`.
+   *
+   * An empty `match` is a catch-all (always fires).
    */
-  versions: Array<VersionConfig>;
+  export interface Rule {
+    /**
+     * What a rule serves when matched.
+     *
+     * Exactly one of:
+     *
+     * - `version_id` — serve a specific version
+     * - `rollout` — weighted random across versions; weights must sum to less than
+     *   100, with the leftover routing to the main version
+     */
+    serve: Rule.Serve;
+
+    match?: Array<Rule.Match>;
+  }
+
+  export namespace Rule {
+    /**
+     * What a rule serves when matched.
+     *
+     * Exactly one of:
+     *
+     * - `version_id` — serve a specific version
+     * - `rollout` — weighted random across versions; weights must sum to less than
+     *   100, with the leftover routing to the main version
+     */
+    export interface Serve {
+      rollout?: Array<Serve.Rollout>;
+
+      version_id?: string;
+    }
+
+    export namespace Serve {
+      /**
+       * One slot in a percentage rollout.
+       */
+      export interface Rollout {
+        version_id: string;
+
+        weight: number;
+      }
+    }
+
+    /**
+     * A single attribute/operator/values check.
+     *
+     * A clause matches when the routing context's value for `attribute` satisfies
+     * `operator` against any of `values`.
+     */
+    export interface Match {
+      /**
+       * Attribute name from the routing context
+       */
+      attribute: string;
+
+      /**
+       * Match operator
+       */
+      operator: 'in' | 'not_in' | 'starts_with';
+
+      values: Array<string>;
+    }
+  }
 }
 
 export interface CanaryDeployUpdateParams {
+  rules?: Array<CanaryDeployUpdateParams.Rule>;
+}
+
+export namespace CanaryDeployUpdateParams {
   /**
-   * List of version configurations
+   * A targeting rule: `match` clauses (AND) gate `serve`.
+   *
+   * An empty `match` is a catch-all (always fires).
    */
-  versions: Array<VersionConfig>;
+  export interface Rule {
+    /**
+     * What a rule serves when matched.
+     *
+     * Exactly one of:
+     *
+     * - `version_id` — serve a specific version
+     * - `rollout` — weighted random across versions; weights must sum to less than
+     *   100, with the leftover routing to the main version
+     */
+    serve: Rule.Serve;
+
+    match?: Array<Rule.Match>;
+  }
+
+  export namespace Rule {
+    /**
+     * What a rule serves when matched.
+     *
+     * Exactly one of:
+     *
+     * - `version_id` — serve a specific version
+     * - `rollout` — weighted random across versions; weights must sum to less than
+     *   100, with the leftover routing to the main version
+     */
+    export interface Serve {
+      rollout?: Array<Serve.Rollout>;
+
+      version_id?: string;
+    }
+
+    export namespace Serve {
+      /**
+       * One slot in a percentage rollout.
+       */
+      export interface Rollout {
+        version_id: string;
+
+        weight: number;
+      }
+    }
+
+    /**
+     * A single attribute/operator/values check.
+     *
+     * A clause matches when the routing context's value for `attribute` satisfies
+     * `operator` against any of `values`.
+     */
+    export interface Match {
+      /**
+       * Attribute name from the routing context
+       */
+      attribute: string;
+
+      /**
+       * Match operator
+       */
+      operator: 'in' | 'not_in' | 'starts_with';
+
+      values: Array<string>;
+    }
+  }
 }
 
 export declare namespace CanaryDeploys {
   export {
     type CanaryDeploy as CanaryDeploy,
     type CanaryDeployResponse as CanaryDeployResponse,
-    type VersionConfig as VersionConfig,
     type CanaryDeployCreateParams as CanaryDeployCreateParams,
     type CanaryDeployUpdateParams as CanaryDeployUpdateParams,
   };

package/src/resources/ai/assistants/index.ts

@@ -7,6 +7,10 @@ export {
   type AssistantsList,
   type AudioVisualizerConfig,
   type EnabledFeatures,
+  type ExternalLlm,
+  type ExternalLlmReq,
+  type FallbackConfig,
+  type FallbackConfigReq,
   type HangupTool,
   type HangupToolParams,
   type ImportMetadata,
@@ -16,6 +20,8 @@ export {
   type MessagingSettings,
   type Observability,
   type ObservabilityReq,
+  type PostConversationSettings,
+  type PostConversationSettingsReq,
   type PrivacySettings,
   type RetrievalTool,
   type TelephonySettings,
@@ -40,7 +46,6 @@ export {
   CanaryDeploys,
   type CanaryDeploy,
   type CanaryDeployResponse,
-  type VersionConfig,
   type CanaryDeployCreateParams,
   type CanaryDeployUpdateParams,
 } from './canary-deploys';

package/src/resources/ai/assistants/versions.ts

@@ -146,9 +146,9 @@ export interface UpdateAssistant {
 
   enabled_features?: Array<AssistantsAPI.EnabledFeatures>;
 
-  external_llm?: UpdateAssistant.ExternalLlm;
+  external_llm?: AssistantsAPI.ExternalLlmReq;
 
-  fallback_config?: UpdateAssistant.FallbackConfig;
+  fallback_config?: AssistantsAPI.FallbackConfigReq;
 
   /**
    * Text that the assistant will use to start the conversation. This may be
@@ -225,7 +225,7 @@ export interface UpdateAssistant {
    * Telephony-control tools (e.g. hangup, transfer) are unavailable
    * post-conversation. Beta feature.
    */
-  post_conversation_settings?: UpdateAssistant.PostConversationSettings;
+  post_conversation_settings?: AssistantsAPI.PostConversationSettingsReq;
 
   privacy_settings?: AssistantsAPI.PrivacySettings;
 
@@ -266,111 +266,6 @@ export interface UpdateAssistant {
 }
 
 export namespace UpdateAssistant {
-  export interface ExternalLlm {
-    /**
-     * Base URL for the external LLM endpoint.
-     */
-    base_url: string;
-
-    /**
-     * Model identifier to use with the external LLM endpoint.
-     */
-    model: string;
-
-    /**
-     * Authentication method used when connecting to the external LLM endpoint.
-     */
-    authentication_method?: 'token' | 'certificate';
-
-    /**
-     * Integration secret identifier for the client certificate used with certificate
-     * authentication.
-     */
-    certificate_ref?: string;
-
-    /**
-     * When `true`, Telnyx forwards the assistant's dynamic variables to the external
-     * LLM endpoint as a top-level `extra_metadata` object on the chat completion
-     * request body. Defaults to `false`. Example payload sent to the external
-     * endpoint:
-     * `{"extra_metadata": {"customer_name": "Jane", "account_id": "acct_789", "telnyx_agent_target": "+13125550100", "telnyx_end_user_target": "+13125550123"}}`.
-     * Distinct from OpenAI's native `metadata` field, which has its own size and type
-     * limits.
-     */
-    forward_metadata?: boolean;
-
-    /**
-     * Integration secret identifier for the external LLM API key.
-     */
-    llm_api_key_ref?: string;
-
-    /**
-     * URL used to retrieve an access token when certificate authentication is enabled.
-     */
-    token_retrieval_url?: string;
-  }
-
-  export interface FallbackConfig {
-    external_llm?: FallbackConfig.ExternalLlm;
-
-    /**
-     * Integration secret identifier for the fallback model API key.
-     */
-    llm_api_key_ref?: string;
-
-    /**
-     * Fallback Telnyx-hosted model to use when the primary LLM provider is
-     * unavailable.
-     */
-    model?: string;
-  }
-
-  export namespace FallbackConfig {
-    export interface ExternalLlm {
-      /**
-       * Base URL for the external LLM endpoint.
-       */
-      base_url: string;
-
-      /**
-       * Model identifier to use with the external LLM endpoint.
-       */
-      model: string;
-
-      /**
-       * Authentication method used when connecting to the external LLM endpoint.
-       */
-      authentication_method?: 'token' | 'certificate';
-
-      /**
-       * Integration secret identifier for the client certificate used with certificate
-       * authentication.
-       */
-      certificate_ref?: string;
-
-      /**
-       * When `true`, Telnyx forwards the assistant's dynamic variables to the external
-       * LLM endpoint as a top-level `extra_metadata` object on the chat completion
-       * request body. Defaults to `false`. Example payload sent to the external
-       * endpoint:
-       * `{"extra_metadata": {"customer_name": "Jane", "account_id": "acct_789", "telnyx_agent_target": "+13125550100", "telnyx_end_user_target": "+13125550123"}}`.
-       * Distinct from OpenAI's native `metadata` field, which has its own size and type
-       * limits.
-       */
-      forward_metadata?: boolean;
-
-      /**
-       * Integration secret identifier for the external LLM API key.
-       */
-      llm_api_key_ref?: string;
-
-      /**
-       * URL used to retrieve an access token when certificate authentication is enabled.
-       */
-      token_retrieval_url?: string;
-    }
-  }
-
   /**
    * Reference to a connected integration attached to an assistant. Discover
    * available integrations with `/ai/integrations` and connected integrations with
@@ -482,23 +377,6 @@ export namespace UpdateAssistant {
      */
     allowed_tools?: Array<string>;
   }
-
-  /**
-   * Configuration for post-conversation processing. When enabled, the assistant
-   * receives one additional LLM turn after the conversation ends, allowing it to
-   * execute tool calls such as logging to a CRM or sending a summary. The assistant
-   * can execute multiple parallel or sequential tools during this phase.
-   * Telephony-control tools (e.g. hangup, transfer) are unavailable
-   * post-conversation. Beta feature.
-   */
-  export interface PostConversationSettings {
-    /**
-     * Whether post-conversation processing is enabled. When true, the assistant will
-     * be invoked after the conversation ends to perform any final tool calls. Defaults
-     * to false.
-     */
-    enabled?: boolean;
-  }
 }
 
 export interface VersionRetrieveParams {
@@ -557,12 +435,12 @@ export interface VersionUpdateParams {
   /**
    * Body param
    */
-  external_llm?: VersionUpdateParams.ExternalLlm;
+  external_llm?: AssistantsAPI.ExternalLlmReq;
 
   /**
    * Body param
    */
-  fallback_config?: VersionUpdateParams.FallbackConfig;
+  fallback_config?: AssistantsAPI.FallbackConfigReq;
 
   /**
    * Body param: Text that the assistant will use to start the conversation. This may
@@ -652,7 +530,7 @@ export interface VersionUpdateParams {
    * Telephony-control tools (e.g. hangup, transfer) are unavailable
    * post-conversation. Beta feature.
    */
-  post_conversation_settings?: VersionUpdateParams.PostConversationSettings;
+  post_conversation_settings?: AssistantsAPI.PostConversationSettingsReq;
 
   /**
    * Body param
@@ -705,111 +583,6 @@ export interface VersionUpdateParams {
 }
 
 export namespace VersionUpdateParams {
-  export interface ExternalLlm {
-    /**
-     * Base URL for the external LLM endpoint.
-     */
-    base_url: string;
-
-    /**
-     * Model identifier to use with the external LLM endpoint.
-     */
-    model: string;
-
-    /**
-     * Authentication method used when connecting to the external LLM endpoint.
-     */
-    authentication_method?: 'token' | 'certificate';
-
-    /**
-     * Integration secret identifier for the client certificate used with certificate
-     * authentication.
-     */
-    certificate_ref?: string;
-
-    /**
-     * When `true`, Telnyx forwards the assistant's dynamic variables to the external
-     * LLM endpoint as a top-level `extra_metadata` object on the chat completion
-     * request body. Defaults to `false`. Example payload sent to the external
-     * endpoint:
-     * `{"extra_metadata": {"customer_name": "Jane", "account_id": "acct_789", "telnyx_agent_target": "+13125550100", "telnyx_end_user_target": "+13125550123"}}`.
-     * Distinct from OpenAI's native `metadata` field, which has its own size and type
-     * limits.
-     */
-    forward_metadata?: boolean;
-
-    /**
-     * Integration secret identifier for the external LLM API key.
-     */
-    llm_api_key_ref?: string;
-
-    /**
-     * URL used to retrieve an access token when certificate authentication is enabled.
-     */
-    token_retrieval_url?: string;
-  }
-
-  export interface FallbackConfig {
-    external_llm?: FallbackConfig.ExternalLlm;
-
-    /**
-     * Integration secret identifier for the fallback model API key.
-     */
-    llm_api_key_ref?: string;
-
-    /**
-     * Fallback Telnyx-hosted model to use when the primary LLM provider is
-     * unavailable.
-     */
-    model?: string;
-  }
-
-  export namespace FallbackConfig {
-    export interface ExternalLlm {
-      /**
-       * Base URL for the external LLM endpoint.
-       */
-      base_url: string;
-
-      /**
-       * Model identifier to use with the external LLM endpoint.
-       */
-      model: string;
-
-      /**
-       * Authentication method used when connecting to the external LLM endpoint.
-       */
-      authentication_method?: 'token' | 'certificate';
-
-      /**
-       * Integration secret identifier for the client certificate used with certificate
-       * authentication.
-       */
-      certificate_ref?: string;
-
-      /**
-       * When `true`, Telnyx forwards the assistant's dynamic variables to the external
-       * LLM endpoint as a top-level `extra_metadata` object on the chat completion
-       * request body. Defaults to `false`. Example payload sent to the external
-       * endpoint:
-       * `{"extra_metadata": {"customer_name": "Jane", "account_id": "acct_789", "telnyx_agent_target": "+13125550100", "telnyx_end_user_target": "+13125550123"}}`.
-       * Distinct from OpenAI's native `metadata` field, which has its own size and type
-       * limits.
-       */
-      forward_metadata?: boolean;
-
-      /**
-       * Integration secret identifier for the external LLM API key.
-       */
-      llm_api_key_ref?: string;
-
-      /**
-       * URL used to retrieve an access token when certificate authentication is enabled.
-       */
-      token_retrieval_url?: string;
-    }
-  }
-
   /**
    * Reference to a connected integration attached to an assistant. Discover
    * available integrations with `/ai/integrations` and connected integrations with
@@ -921,23 +694,6 @@ export namespace VersionUpdateParams {
      */
     allowed_tools?: Array<string>;
   }
-
-  /**
-   * Configuration for post-conversation processing. When enabled, the assistant
-   * receives one additional LLM turn after the conversation ends, allowing it to
-   * execute tool calls such as logging to a CRM or sending a summary. The assistant
-   * can execute multiple parallel or sequential tools during this phase.
-   * Telephony-control tools (e.g. hangup, transfer) are unavailable
-   * post-conversation. Beta feature.
-   */
-  export interface PostConversationSettings {
-    /**
-     * Whether post-conversation processing is enabled. When true, the assistant will
-     * be invoked after the conversation ends to perform any final tool calls. Defaults
-     * to false.
-     */
-    enabled?: boolean;
-  }
 }
 
 export interface VersionDeleteParams {