telnyx 7.21.0 → 7.23.0

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

@@ -1,6 +1,11 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-export { Chat, type ChatCreateCompletionResponse, type ChatCreateCompletionParams } from './chat';
+export {
+  Chat,
+  type FunctionDefinition,
+  type ChatCreateCompletionResponse,
+  type ChatCreateCompletionParams,
+} from './chat';
 export {
   Embeddings,
   type EmbeddingCreateEmbeddingsResponse,

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

@@ -3,7 +3,7 @@
 import { APIResource } from '../../../core/resource';
 import * as AIAPI from '../ai';
 import * as ChatAPI from './chat';
-import { Chat, ChatCreateCompletionParams, ChatCreateCompletionResponse } from './chat';
+import { Chat, ChatCreateCompletionParams, ChatCreateCompletionResponse, FunctionDefinition } from './chat';
 import * as EmbeddingsAPI from './embeddings';
 import {
   EmbeddingCreateEmbeddingsParams,
@@ -191,6 +191,7 @@ export declare namespace OpenAI {
 
   export {
     Chat as Chat,
+    type FunctionDefinition as FunctionDefinition,
     type ChatCreateCompletionResponse as ChatCreateCompletionResponse,
     type ChatCreateCompletionParams as ChatCreateCompletionParams,
   };

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

@@ -0,0 +1,4 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export { Typesafe } from './typesafe';
+export { V1, type V1SystemoneResponse, type V1SystemoneParams } from './v1';

package/src/resources/ai/typesafe/typesafe.ts

@@ -0,0 +1,19 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../../core/resource';
+import * as V1API from './v1';
+import { V1, V1SystemoneParams, V1SystemoneResponse } from './v1';
+
+export class Typesafe extends APIResource {
+  v1: V1API.V1 = new V1API.V1(this._client);
+}
+
+Typesafe.V1 = V1;
+
+export declare namespace Typesafe {
+  export {
+    V1 as V1,
+    type V1SystemoneResponse as V1SystemoneResponse,
+    type V1SystemoneParams as V1SystemoneParams,
+  };
+}

package/src/resources/ai/typesafe/v1.ts

@@ -0,0 +1,298 @@
+// 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';
+
+/**
+ * Beta API for evaluating shared context with typed questions and structured answers. Telnyx manages model selection.
+ */
+export class V1 extends APIResource {
+  /**
+   * **Beta API.** Telnyx controls model selection.
+   *
+   * Evaluate shared context using named choice, noul (yes/no), and score questions.
+   * Returns TypeSafe System One-compatible answer shapes, an opaque compatibility
+   * identifier, and token usage. See the
+   * [decision model guide](https://developers.telnyx.com/docs/inference/decision-models)
+   * for examples and compatibility limits.
+   *
+   * The supported request subset requires instructions for every question, string
+   * descriptions for criteria (or null for choice descriptions), 1–64 questions, and
+   * 2–64 options for choice and score questions. The SDK-supplied model value is
+   * ignored and cannot select a model. Other unknown fields are rejected. The
+   * endpoint is synchronous and does not stream.
+   *
+   * Use the TypeSafe Python SDK with base_url set to
+   * https://api.telnyx.com/v2/ai/typesafe and a Telnyx API key. The SDK appends
+   * /v1/systemone. Compatibility covers this operation and the documented request
+   * subset; it does not include TypeSafe model listing. Scores describe relative
+   * preference, not calibrated correctness.
+   *
+   * @example
+   * ```ts
+   * const response = await client.ai.typesafe.v1.systemone({
+   *   questions: {
+   *     team: {
+   *       type: 'choice',
+   *       instructions:
+   *         'Choose the team that should handle this incident.',
+   *       criteria: {
+   *         billing: 'Payments and refunds',
+   *         technical_support:
+   *           'Service faults and technical problems',
+   *         sales: 'New purchases',
+   *       },
+   *     },
+   *     production_incident: {
+   *       type: 'noul',
+   *       instructions:
+   *         'Does the message describe an active production incident?',
+   *     },
+   *     urgency: {
+   *       type: 'score',
+   *       instructions: 'Rate operational urgency.',
+   *       criteria: ['Low', 'Normal', 'High', 'Critical'],
+   *     },
+   *   },
+   *   state:
+   *     'Our production calls are failing. Every customer is affected.',
+   * });
+   * ```
+   */
+  systemone(body: V1SystemoneParams, options?: RequestOptions): APIPromise<V1SystemoneResponse> {
+    return this._client.post('/ai/typesafe/v1/systemone', { body, ...options });
+  }
+}
+
+/**
+ * A complete synchronous evaluation. Answers are returned directly without a data
+ * wrapper.
+ */
+export interface V1SystemoneResponse {
+  /**
+   * Answers keyed by exactly the question IDs in the request. Each answer type
+   * matches its question.
+   */
+  answers: {
+    [key: string]:
+      | V1SystemoneResponse.DecisionModelChoiceAnswer
+      | V1SystemoneResponse.DecisionModelNoulAnswer
+      | V1SystemoneResponse.DecisionModelScoreAnswer;
+  };
+
+  /**
+   * Opaque Telnyx-controlled identifier retained for TypeSafe SDK response
+   * compatibility. It is not a selectable model name or a guarantee of a particular
+   * underlying model.
+   */
+  model: string;
+
+  /**
+   * Token usage for the completed evaluation.
+   */
+  usage: V1SystemoneResponse.Usage;
+}
+
+export namespace V1SystemoneResponse {
+  /**
+   * A selected option and the distribution across all supplied option keys.
+   */
+  export interface DecisionModelChoiceAnswer {
+    /**
+     * The option key with the highest relative score. Ties favor the first option in
+     * request order.
+     */
+    choice: string;
+
+    /**
+     * Normalized entropy confidence: 1 - H(p) / ln(N), where H(p) = -sum(p \* ln(p))
+     * and N is the number of options. Zero indicates a uniform distribution; one
+     * indicates concentration on one option. This is neither the winning probability
+     * nor calibrated correctness.
+     */
+    confidence: number;
+
+    /**
+     * Relative scores normalized across the supplied options, summing approximately
+     * to 1. These are not calibrated probabilities of correctness.
+     */
+    probabilities: { [key: string]: number };
+
+    /**
+     * Answer type.
+     */
+    type: 'choice';
+  }
+
+  /**
+   * A yes/no score with no separate confidence or probabilities fields.
+   */
+  export interface DecisionModelNoulAnswer {
+    /**
+     * Score of the positive outcome. Values near 1 favor yes; values near 0 favor no.
+     * This is a number, not a Boolean, and is not calibrated correctness.
+     */
+    noul: number;
+
+    /**
+     * Answer type.
+     */
+    type: 'noul';
+  }
+
+  /**
+   * An expected rating over the ordered criteria.
+   */
+  export interface DecisionModelScoreAnswer {
+    /**
+     * Normalized entropy confidence: 1 - H(p) / ln(N), where H(p) = -sum(p \* ln(p))
+     * and N is the number of options. Zero indicates a uniform distribution; one
+     * indicates concentration on one option. This is neither the winning probability
+     * nor calibrated correctness.
+     */
+    confidence: number;
+
+    /**
+     * Criterion descriptions keyed by stringified zero-based indices, such as "0",
+     * "1", and "2".
+     */
+    legend: { [key: string]: string };
+
+    /**
+     * Relative scores keyed by the same stringified indices as legend.
+     */
+    probabilities: { [key: string]: number };
+
+    /**
+     * Expected zero-based criterion index: sum(index \* probability). Ranges from 0 to
+     * N-1 for N criteria; fractional values are valid.
+     */
+    score: number;
+
+    /**
+     * Answer type.
+     */
+    type: 'score';
+  }
+
+  /**
+   * Token usage for the completed evaluation.
+   */
+  export interface Usage {
+    /**
+     * Input tokens processed, including shared-context preparation and question
+     * evaluation. This can exceed the token count of the unique input text.
+     */
+    input_tokens: number;
+
+    /**
+     * Output tokens used for the evaluation, including shared-context preparation.
+     */
+    output_tokens: number;
+  }
+}
+
+export interface V1SystemoneParams {
+  /**
+   * Between 1 and 64 named questions. Each key identifies the corresponding answer.
+   */
+  questions: {
+    [key: string]:
+      | V1SystemoneParams.DecisionModelChoiceQuestion
+      | V1SystemoneParams.DecisionModelNoulQuestion
+      | V1SystemoneParams.DecisionModelScoreQuestion;
+  };
+
+  /**
+   * Shared context evaluated by every question.
+   */
+  state: string | { [key: string]: unknown } | Array<unknown>;
+}
+
+export namespace V1SystemoneParams {
+  /**
+   * Select one of the supplied options.
+   */
+  export interface DecisionModelChoiceQuestion {
+    /**
+     * Between 2 and 64 option keys mapped to description strings or null. A null
+     * description uses the option key as its text.
+     */
+    criteria: { [key: string]: string | null };
+
+    /**
+     * Required instructions describing what to decide about the shared state.
+     */
+    instructions: string | { [key: string]: unknown } | Array<unknown>;
+
+    /**
+     * Question type.
+     */
+    type: 'choice';
+  }
+
+  /**
+   * Evaluate a yes/no question. Omit criteria to use Yes and No descriptions.
+   */
+  export interface DecisionModelNoulQuestion {
+    /**
+     * Required instructions describing what to decide about the shared state.
+     */
+    instructions: string | { [key: string]: unknown } | Array<unknown>;
+
+    /**
+     * Question type.
+     */
+    type: 'noul';
+
+    /**
+     * Optional descriptions for the positive and negative outcomes. Descriptions must
+     * be strings.
+     */
+    criteria?: DecisionModelNoulQuestion.Criteria;
+  }
+
+  export namespace DecisionModelNoulQuestion {
+    /**
+     * Optional descriptions for the positive and negative outcomes. Descriptions must
+     * be strings.
+     */
+    export interface Criteria {
+      /**
+       * Description of the negative outcome.
+       */
+      false?: string;
+
+      /**
+       * Description of the positive outcome.
+       */
+      true?: string;
+    }
+  }
+
+  /**
+   * Rate the state against an ordered rubric.
+   */
+  export interface DecisionModelScoreQuestion {
+    /**
+     * Between 2 and 64 description strings in ascending score order. Indices start at
+     * zero.
+     */
+    criteria: Array<string>;
+
+    /**
+     * Required instructions describing what to decide about the shared state.
+     */
+    instructions: string | { [key: string]: unknown } | Array<unknown>;
+
+    /**
+     * Question type.
+     */
+    type: 'score';
+  }
+}
+
+export declare namespace V1 {
+  export { type V1SystemoneResponse as V1SystemoneResponse, type V1SystemoneParams as V1SystemoneParams };
+}

package/src/resources/ai/typesafe.ts

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

package/src/resources/bot-challenge.ts

@@ -0,0 +1,101 @@
+// 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';
+
+/**
+ * Agentic (bot) signup for Telnyx accounts. An AI agent solves a reverse-CAPTCHA challenge designed to be easy for LLMs and hard for humans, registers an account, and signs in by consuming a magic link emailed to the account owner. All endpoints are public and unauthenticated; signup endpoints are additionally gated by the freemium feature flags and per-country availability.
+ */
+export class BotChallenge extends APIResource {
+  /**
+   * Generates a reverse-CAPTCHA challenge used to gate the bot signup flow. A random
+   * active problem is selected from the pool; math problems are returned obfuscated
+   * (case randomization, symbol injection, spacing noise) with an unobfuscated
+   * rounding instruction appended, while string and binary problems are returned
+   * as-is. The response contains a single-use nonce, the problem text, and the
+   * current terms-and-conditions and privacy-policy URLs, which must be echoed back
+   * on the signup request. Challenges expire after a short window (10 minutes by
+   * default) and can only be answered once. This endpoint is public and
+   * unauthenticated.
+   *
+   * @example
+   * ```ts
+   * const botChallenge = await client.botChallenge.create({
+   *   llm_model_name: 'claude-opus-4',
+   *   llm_parameter_count: '175B',
+   *   llm_quantization: 'int8',
+   * });
+   * ```
+   */
+  create(
+    body: BotChallengeCreateParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<BotChallengeCreateResponse> {
+    return this._client.post('/v2/bot_challenge', { body, ...options });
+  }
+}
+
+export interface BotChallengeCreateResponse {
+  data: BotChallengeCreateResponse.Data;
+}
+
+export namespace BotChallengeCreateResponse {
+  export interface Data {
+    /**
+     * Type of challenge.
+     */
+    challenge_type: 'math' | 'string' | 'binary';
+
+    /**
+     * Single-use challenge identifier. Submit it as `bot_challenge_nonce` on the
+     * signup request.
+     */
+    nonce: string;
+
+    /**
+     * Current privacy-policy URL. Echo this back on the signup request.
+     */
+    privacy_policy_url: string;
+
+    /**
+     * Problem text to solve. Math problems are obfuscated and end with an unobfuscated
+     * rounding instruction; string and binary problems are returned as-is.
+     */
+    problem: string;
+
+    /**
+     * Current terms-and-conditions URL. Echo this back on the signup request.
+     */
+    terms_and_conditions_url: string;
+
+    /**
+     * Decimal places expected in the answer. Present only for math challenges.
+     */
+    precision?: number;
+  }
+}
+
+export interface BotChallengeCreateParams {
+  /**
+   * Name of the LLM the client is using.
+   */
+  llm_model_name?: string;
+
+  /**
+   * Parameter count of the client LLM.
+   */
+  llm_parameter_count?: string;
+
+  /**
+   * Quantization of the client LLM.
+   */
+  llm_quantization?: string;
+}
+
+export declare namespace BotChallenge {
+  export {
+    type BotChallengeCreateResponse as BotChallengeCreateResponse,
+    type BotChallengeCreateParams as BotChallengeCreateParams,
+  };
+}

package/src/resources/bot-sessions.ts

@@ -0,0 +1,61 @@
+// 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';
+
+/**
+ * Agentic (bot) signup for Telnyx accounts. An AI agent solves a reverse-CAPTCHA challenge designed to be easy for LLMs and hard for humans, registers an account, and signs in by consuming a magic link emailed to the account owner. All endpoints are public and unauthenticated; signup endpoints are additionally gated by the freemium feature flags and per-country availability.
+ */
+export class BotSessions extends APIResource {
+  /**
+   * Consumes the one-time portal redirect (magic link) token emailed during bot
+   * signup and returns an API session. The token is a UUIDv7 that encodes its
+   * creation time; it expires after a configurable validity window (15 minutes by
+   * default) and is cleared on first use. Although the action creates a session, the
+   * route uses the GET verb because it is opened from an email link. On first use
+   * the account is also initialized. For bot signup (freemium) accounts the response
+   * is a minimal envelope containing only the `api_v2_token`; accounts that are
+   * permitted to use magic links but are not freemium accounts may instead receive
+   * an extended session payload when additional steps (such as two-factor
+   * authentication or identity verification) are required. This endpoint is public;
+   * the magic link token in the query string is the credential.
+   */
+  list(query: BotSessionListParams, options?: RequestOptions): APIPromise<BotSessionListResponse> {
+    return this._client.get('/v2/bot_sessions', { query, ...options });
+  }
+}
+
+export interface BotSessionListResponse {
+  data: BotSessionListResponse.Data;
+}
+
+export namespace BotSessionListResponse {
+  export interface Data {
+    /**
+     * API v2 session token for the signed-in user. Use it as a bearer token on
+     * authenticated endpoints.
+     */
+    api_v2_token: string;
+  }
+}
+
+export interface BotSessionListParams {
+  /**
+   * Email address associated with the magic link token.
+   */
+  email: string;
+
+  /**
+   * Single-use portal redirect (magic link) token, a UUIDv7 sent to the account
+   * owner's email.
+   */
+  portal_redirect_token: string;
+}
+
+export declare namespace BotSessions {
+  export {
+    type BotSessionListResponse as BotSessionListResponse,
+    type BotSessionListParams as BotSessionListParams,
+  };
+}

package/src/resources/bot-signup.ts

@@ -0,0 +1,140 @@
+// 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';
+
+/**
+ * Agentic (bot) signup for Telnyx accounts. An AI agent solves a reverse-CAPTCHA challenge designed to be easy for LLMs and hard for humans, registers an account, and signs in by consuming a magic link emailed to the account owner. All endpoints are public and unauthenticated; signup endpoints are additionally gated by the freemium feature flags and per-country availability.
+ */
+export class BotSignup extends APIResource {
+  /**
+   * Creates a freemium Telnyx account through the agentic signup flow. The request
+   * must carry a valid answer to a previously issued bot challenge
+   * (`bot_challenge_nonce` and `bot_challenge_answer`), accept the terms of service,
+   * and echo the exact terms-and-conditions and privacy-policy URLs returned by the
+   * challenge endpoint. When EU consent enforcement is enabled,
+   * `terms_of_service_eu` and `terms_and_conditions_eu_url` are also required. On
+   * success a one-time sign-in (magic) link is emailed to the address provided; if
+   * the email address belongs to an existing account, a sign-in link is sent instead
+   * of creating a duplicate account. `email` may only be omitted when
+   * placeholder-email registration is enabled server-side. This endpoint is public
+   * and unauthenticated, gated by the freemium feature flags and per-country
+   * availability, and subject to per-IP and per-domain registration limits.
+   *
+   * @example
+   * ```ts
+   * const successResponse = await client.botSignup.create({
+   *   bot_challenge_answer: '35',
+   *   bot_challenge_nonce:
+   *     'c6feda4e-6501-4db9-a21f-665e5b4ce2ba',
+   *   privacy_policy_url: 'https://telnyx.com/privacy-policy',
+   *   terms_and_conditions_url:
+   *     'https://telnyx.com/terms-and-conditions-of-service',
+   *   terms_of_service: true,
+   *   email: 'agent-owner@example.com',
+   * });
+   * ```
+   */
+  create(body: BotSignupCreateParams, options?: RequestOptions): APIPromise<SuccessResponse> {
+    return this._client.post('/v2/bot_signup', { body, ...options });
+  }
+
+  /**
+   * Resends the one-time sign-in (magic) link for an eligible bot signup account.
+   * Eligibility (account exists, was registered through bot signup, is active, and
+   * has not exceeded the resend limit or rate window) is evaluated server-side; the
+   * response is intentionally uniform and does not reveal whether the account exists
+   * or whether a link was actually sent. This endpoint is public and
+   * unauthenticated, gated by the freemium feature flags and per-country
+   * availability.
+   *
+   * @example
+   * ```ts
+   * const successResponse =
+   *   await client.botSignup.resendMagicLink({
+   *     email: 'agent-owner@example.com',
+   *   });
+   * ```
+   */
+  resendMagicLink(
+    body: BotSignupResendMagicLinkParams,
+    options?: RequestOptions,
+  ): APIPromise<SuccessResponse> {
+    return this._client.post('/v2/bot_signup/resend_magic_link', { body, ...options });
+  }
+}
+
+/**
+ * Status envelope used by the signup and magic-link flows.
+ */
+export interface SuccessResponse {
+  /**
+   * Human-readable status message.
+   */
+  message: string;
+
+  /**
+   * Whether the request was accepted.
+   */
+  success: boolean;
+}
+
+export interface BotSignupCreateParams {
+  /**
+   * Answer to the issued bot challenge.
+   */
+  bot_challenge_answer: string;
+
+  /**
+   * Nonce from a previously issued bot challenge.
+   */
+  bot_challenge_nonce: string;
+
+  /**
+   * Must exactly match the privacy-policy URL returned by the challenge endpoint.
+   */
+  privacy_policy_url: string;
+
+  /**
+   * Must exactly match the terms-and-conditions URL returned by the challenge
+   * endpoint.
+   */
+  terms_and_conditions_url: string;
+
+  /**
+   * Must be true to accept the terms of service.
+   */
+  terms_of_service: true;
+
+  /**
+   * Email address for the new account. The magic link is sent here. May only be
+   * omitted when placeholder-email registration is enabled server-side.
+   */
+  email?: string;
+
+  /**
+   * EU terms-and-conditions URL. Required when EU consent enforcement is enabled.
+   */
+  terms_and_conditions_eu_url?: string;
+
+  /**
+   * EU terms-of-service acceptance. Required when EU consent enforcement is enabled.
+   */
+  terms_of_service_eu?: true;
+}
+
+export interface BotSignupResendMagicLinkParams {
+  /**
+   * Email address of the bot signup account to resend the magic link to.
+   */
+  email: string;
+}
+
+export declare namespace BotSignup {
+  export {
+    type SuccessResponse as SuccessResponse,
+    type BotSignupCreateParams as BotSignupCreateParams,
+    type BotSignupResendMagicLinkParams as BotSignupResendMagicLinkParams,
+  };
+}