telnyx 7.24.0 → 7.26.0

package/src/resources/sip-registration-status.ts

@@ -0,0 +1,188 @@
+// 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';
+
+/**
+ * UAC connection operations
+ */
+export class SipRegistrationStatus extends APIResource {
+  /**
+   * Returns the live SIP registration status for a Telnyx endpoint: whether it is
+   * currently registered, when the current registration expires, and the last
+   * response Telnyx received from the registrar.
+   *
+   * The endpoint supports three credential types, selected with the
+   * `credential_type` query parameter. Each type is keyed by a different identifier:
+   *
+   * | `credential_type`           | Keyed by        | Use case                                                                   |
+   * | --------------------------- | --------------- | -------------------------------------------------------------------------- |
+   * | `uac_external_credential`   | `connection_id` | A UAC (SIP attach) connection that registers to an external PBX.           |
+   * | `telephony_credential`      | `username`      | An ephemeral, one-time-use telephony credential.                           |
+   * | `sip_credential_connection` | `username`      | A traditional SIP credential connection that registers directly to Telnyx. |
+   *
+   * The authenticated account is taken from your API key; you can only read the
+   * registration status of connections and credentials your account owns.
+   */
+  list(
+    query: SipRegistrationStatusListParams,
+    options?: RequestOptions,
+  ): APIPromise<SipRegistrationStatusListResponse> {
+    return this._client.get('/sip_registration_status', { query, ...options });
+  }
+}
+
+export interface SipRegistrationStatusListResponse {
+  /**
+   * Identifier of the connection associated with the credential.
+   */
+  connection_id?: string;
+
+  /**
+   * Human-readable connection name.
+   */
+  connection_name?: string;
+
+  /**
+   * The credential type that was looked up.
+   */
+  credential_type?: 'uac_external_credential' | 'telephony_credential' | 'sip_credential_connection';
+
+  /**
+   * SIP username used for the registration.
+   */
+  credential_username?: string;
+
+  /**
+   * SIP response from the last registration attempt.
+   */
+  last_registration_response?: string | null;
+
+  /**
+   * True if the endpoint is currently registered.
+   */
+  registered?: boolean;
+
+  /**
+   * Detailed registration information reported by the registrar. The populated
+   * fields depend on `credential_type`: UAC external credentials report
+   * `auth_retries`, `uptime`, `next_action_at`, `failures`, and `sip_uri_user_host`;
+   * telephony credentials and SIP credential connections report `ua_ip`, `ua_port`,
+   * `transport`, and `last_modified`. All types report `expires`, but its unit
+   * differs by `credential_type` — see that field.
+   */
+  sip_registration_details?: SipRegistrationStatusListResponse.SipRegistrationDetails;
+
+  /**
+   * Human-readable registration status derived from the registrar state.
+   */
+  sip_registration_status?:
+    | 'unregistering'
+    | 'connection_disabled'
+    | 'standby'
+    | 'failed'
+    | 'trying'
+    | 'registered'
+    | 'unknown';
+}
+
+export namespace SipRegistrationStatusListResponse {
+  /**
+   * Detailed registration information reported by the registrar. The populated
+   * fields depend on `credential_type`: UAC external credentials report
+   * `auth_retries`, `uptime`, `next_action_at`, `failures`, and `sip_uri_user_host`;
+   * telephony credentials and SIP credential connections report `ua_ip`, `ua_port`,
+   * `transport`, and `last_modified`. All types report `expires`, but its unit
+   * differs by `credential_type` — see that field.
+   */
+  export interface SipRegistrationDetails {
+    /**
+     * Number of authentication retries on the last attempt (uac_external_credential).
+     */
+    auth_retries?: number;
+
+    /**
+     * When the current registration expires. The unit depends on `credential_type`:
+     * for `uac_external_credential` this is a Unix timestamp (seconds since epoch) of
+     * the next scheduled re-registration; for `telephony_credential` and
+     * `sip_credential_connection` this is the registration lifetime in seconds as
+     * negotiated with the registrar (the `Expires` value, defaulting to 3600 when the
+     * endpoint sends none).
+     */
+    expires?: number;
+
+    /**
+     * Count of consecutive registration failures (uac_external_credential).
+     */
+    failures?: number;
+
+    /**
+     * Timestamp when the registration was last modified (telephony_credential and
+     * sip_credential_connection).
+     */
+    last_modified?: string;
+
+    /**
+     * Unix timestamp of the next scheduled registration action
+     * (uac_external_credential).
+     */
+    next_action_at?: number;
+
+    /**
+     * SIP URI user@host of the registered contact (uac_external_credential).
+     */
+    sip_uri_user_host?: string;
+
+    /**
+     * Transport used for the registration, e.g. UDP/TCP/TLS (telephony_credential and
+     * sip_credential_connection).
+     */
+    transport?: string;
+
+    /**
+     * IP address of the registered user agent (telephony_credential and
+     * sip_credential_connection).
+     */
+    ua_ip?: string;
+
+    /**
+     * Port of the registered user agent (telephony_credential and
+     * sip_credential_connection).
+     */
+    ua_port?: number;
+
+    /**
+     * Registration uptime reported by the registrar (uac_external_credential).
+     */
+    uptime?: number;
+  }
+}
+
+export interface SipRegistrationStatusListParams {
+  /**
+   * The kind of credential to look up. `uac_external_credential` is keyed by
+   * `connection_id`; `telephony_credential` and `sip_credential_connection` are
+   * keyed by `username`.
+   */
+  credential_type: 'uac_external_credential' | 'telephony_credential' | 'sip_credential_connection';
+
+  /**
+   * Identifier of the UAC connection to look up. Required when `credential_type` is
+   * `uac_external_credential`.
+   */
+  connection_id?: string;
+
+  /**
+   * SIP username to look up. Required when `credential_type` is
+   * `telephony_credential` or `sip_credential_connection`.
+   */
+  username?: string;
+}
+
+export declare namespace SipRegistrationStatus {
+  export {
+    type SipRegistrationStatusListResponse as SipRegistrationStatusListResponse,
+    type SipRegistrationStatusListParams as SipRegistrationStatusListParams,
+  };
+}

package/src/resources/spend-limits.ts

@@ -0,0 +1,428 @@
+// 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';
+
+/**
+ * Daily and monthly spend limits per product. A limit applies to the organization of the authenticated user, or to the user's own account when they belong to no organization; every user of the organization sees and changes the same limits.
+ *
+ * - **Periods.** `daily` covers the current UTC day and `monthly` the current UTC calendar month. The two limits are independent: you can set either, both or neither.
+ * - **Blocking.** When spend in a period goes above the limit (strictly greater), the product is blocked until the period ends: 00:00 UTC the next day for `daily`, 00:00 UTC on the 1st of the next month for `monthly`. A block appears within about 2 minutes (daily) or 10 minutes (monthly) of the spend being recorded.
+ * - **Changes apply immediately.** Creating, updating or deleting a limit checks the period's spend in the same request: raising the limit above the spend, or removing it, lifts that period's block, and lowering it below the spend blocks the product at once. The `evaluation` object in the response says what happened.
+ * - **Supported products.** Today only `inference` supports spend limits. A blocked account gets HTTP 403 with the error title `Inference spend limit reached` (code `10039`) on new billable chat completions, Responses, Anthropic Messages and classification requests; requests already running finish normally. Take the list of products from the list operation.
+ * - **Limits set by Telnyx.** Telnyx support can also set a limit on your account. It is listed with `origin: operator` and you can update or delete it like your own.
+ */
+export class SpendLimits extends APIResource {
+  /**
+   * Returns one entry per product and period you can set a limit on, with the limit,
+   * the spend so far in the period and whether the product is blocked. An entry
+   * without a limit is still listed (`limit: null`). When the spend cannot be read,
+   * the entry is returned with `spend_usd: null` and `spend_error` set. The list is
+   * not paginated.
+   *
+   * @example
+   * ```ts
+   * const spendLimits = await client.spendLimits.list();
+   * ```
+   */
+  list(options?: RequestOptions): APIPromise<SpendLimitListResponse> {
+    return this._client.get('/spend_limits', options);
+  }
+
+  /**
+   * Sets a limit for a product and period that has none. Send exactly one of
+   * `amount` and `unlimited: true`. The period's spend is checked at once: if it is
+   * already above the new limit, the product is blocked immediately
+   * (`evaluation.blocked_now`). Returns 409 when a limit already exists for the
+   * product and period; update it instead.
+   *
+   * @example
+   * ```ts
+   * const spendLimitResponse = await client.spendLimits.create({
+   *   amount: 100,
+   *   product: 'inference',
+   *   period: 'daily',
+   *   reason: 'Team budget',
+   * });
+   * ```
+   */
+  create(body: SpendLimitCreateParams, options?: RequestOptions): APIPromise<SpendLimitResponse> {
+    return this._client.post('/spend_limits', { body, ...options });
+  }
+
+  /**
+   * Removes the limit for the product and period. For `inference`, which has no
+   * default limit, the product becomes unlimited for the period and the period's
+   * block is lifted (`evaluation.released`). The response carries `limit: null` and
+   * the `effective_limit_usd` that applies after the removal. Returns 404 when no
+   * limit is set.
+   *
+   * @example
+   * ```ts
+   * const spendLimitResponse = await client.spendLimits.delete(
+   *   'inference',
+   * );
+   * ```
+   */
+  delete(
+    product: string,
+    params: SpendLimitDeleteParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<SpendLimitResponse> {
+    const { period, reason } = params ?? {};
+    return this._client.delete(path`/spend_limits/${product}`, { query: { period, reason }, ...options });
+  }
+
+  /**
+   * Replaces the value of the existing limit for the product and period. Send
+   * exactly one of `amount` and `unlimited: true`. The period's spend is checked at
+   * once: raising the limit above the spend lifts the period's block
+   * (`evaluation.released`), and lowering it below the spend blocks the product
+   * (`evaluation.blocked_now`). Returns 404 when no limit is set; create it instead.
+   *
+   * @example
+   * ```ts
+   * const spendLimitResponse = await client.spendLimits.update(
+   *   'inference',
+   *   { amount: 250 },
+   * );
+   * ```
+   */
+  update(
+    product: string,
+    params: SpendLimitUpdateParams,
+    options?: RequestOptions,
+  ): APIPromise<SpendLimitResponse> {
+    const { period, ...body } = params;
+    return this._client.patch(path`/spend_limits/${product}`, { query: { period }, body, ...options });
+  }
+}
+
+/**
+ * The spend limit, spend and block state of one product and period.
+ */
+export interface SpendLimit {
+  /**
+   * The active block of the period. `null` when the period is not blocked.
+   */
+  block: SpendLimit.Block | null;
+
+  /**
+   * The product is blocked for this period. Always `false` in write responses; list
+   * the limits to read the block state.
+   */
+  blocked: boolean;
+
+  /**
+   * The limit in USD that is enforced, as a decimal string. `null` means unlimited.
+   */
+  effective_limit_usd: string | null;
+
+  /**
+   * The limit set on the account for the product and period, whoever set it. `null`
+   * when none is set.
+   */
+  limit: SpendLimit.Limit | null;
+
+  /**
+   * `daily` is the current UTC day; `monthly` is the current UTC calendar month.
+   */
+  period: SpendLimitPeriod;
+
+  /**
+   * Exclusive end of the current period, a UTC date.
+   */
+  period_end: string;
+
+  /**
+   * First UTC day of the current period.
+   */
+  period_start: string;
+
+  /**
+   * Product the entry applies to.
+   */
+  product: string;
+
+  /**
+   * Display name of the product.
+   */
+  product_name: string;
+
+  /**
+   * Identifies the type of the resource.
+   */
+  record_type: string;
+
+  /**
+   * Set when `spend_usd` is `null`.
+   */
+  spend_error: string | null;
+
+  /**
+   * Spend in USD so far in the period, as a decimal string. It can lag actual usage
+   * by about a minute. `null` when it could not be read.
+   */
+  spend_usd: string | null;
+
+  /**
+   * What a create, update or delete did to the period at once. Only present in write
+   * responses.
+   */
+  evaluation?: SpendLimit.Evaluation;
+}
+
+export namespace SpendLimit {
+  /**
+   * The active block of the period. `null` when the period is not blocked.
+   */
+  export interface Block {
+    /**
+     * Exclusive end of the block: it is lifted at 00:00 UTC on this date at the
+     * latest.
+     */
+    blocked_until: string;
+
+    /**
+     * When the block started.
+     */
+    detected_at: string;
+
+    /**
+     * The limit in USD that the spend went above, as a decimal string.
+     */
+    limit_usd: string;
+
+    /**
+     * Spend in USD when the block started, as a decimal string.
+     */
+    spend_usd: string;
+  }
+
+  /**
+   * The limit set on the account for the product and period, whoever set it. `null`
+   * when none is set.
+   */
+  export interface Limit {
+    /**
+     * Limit in USD, as a decimal string. `null` when `unlimited` is true.
+     */
+    amount: string | null;
+
+    /**
+     * `self_service` when a user of the account set it, `operator` when Telnyx support
+     * did.
+     */
+    origin: 'self_service' | 'operator';
+
+    /**
+     * True when the limit was set to explicitly no cap.
+     */
+    unlimited: boolean;
+
+    /**
+     * When the limit was last set or changed.
+     */
+    updated_at: string;
+  }
+
+  /**
+   * What a create, update or delete did to the period at once. Only present in write
+   * responses.
+   */
+  export interface Evaluation {
+    /**
+     * The change blocked the product: the spend was already above the new limit.
+     */
+    blocked_now: boolean;
+
+    /**
+     * The spend could not be checked now. The change is saved and applied within a few
+     * minutes.
+     */
+    evaluation_deferred: boolean;
+
+    /**
+     * The change lifted a block of this period.
+     */
+    released: boolean;
+
+    /**
+     * Spend in USD used for the check, as a decimal string. `null` when the spend was
+     * not checked.
+     */
+    spend_usd: string | null;
+
+    /**
+     * The other period has an active block, so the product stays blocked whatever this
+     * period's result.
+     */
+    still_blocked_other_period: boolean;
+
+    /**
+     * A block of this period remains because the spend is still above the new limit.
+     */
+    still_over_limit: boolean;
+
+    /**
+     * Additional information about the result, when there is any.
+     */
+    note?: string;
+  }
+}
+
+/**
+ * `daily` is the current UTC day; `monthly` is the current UTC calendar month.
+ */
+export type SpendLimitPeriod = 'daily' | 'monthly';
+
+export interface SpendLimitResponse {
+  /**
+   * The spend limit, spend and block state of one product and period.
+   */
+  data: SpendLimit;
+}
+
+export interface SpendLimitListResponse {
+  data: Array<SpendLimit>;
+
+  meta?: SpendLimitListResponse.Meta;
+}
+
+export namespace SpendLimitListResponse {
+  export interface Meta {
+    page_number?: number;
+
+    page_size?: number;
+
+    total_pages?: number;
+
+    total_results?: number;
+  }
+}
+
+export type SpendLimitCreateParams =
+  | SpendLimitCreateParams.CreateSpendLimitWithAmount
+  | SpendLimitCreateParams.CreateSpendLimitUnlimited;
+
+export declare namespace SpendLimitCreateParams {
+  export interface CreateSpendLimitWithAmount {
+    /**
+     * Limit in USD. `0` blocks at the first cent of spend.
+     */
+    amount: number;
+
+    /**
+     * Product to limit, as returned in `product` by the list operation.
+     */
+    product: string;
+
+    /**
+     * `daily` is the current UTC day; `monthly` is the current UTC calendar month.
+     */
+    period?: SpendLimitPeriod;
+
+    /**
+     * Why the limit is set or changed, kept for audit.
+     */
+    reason?: string;
+
+    /**
+     * Optional; only `false` is allowed together with `amount`.
+     */
+    unlimited?: false;
+  }
+
+  export interface CreateSpendLimitUnlimited {
+    /**
+     * Product to limit, as returned in `product` by the list operation.
+     */
+    product: string;
+
+    /**
+     * `true`: explicitly no cap.
+     */
+    unlimited: true;
+
+    /**
+     * `daily` is the current UTC day; `monthly` is the current UTC calendar month.
+     */
+    period?: SpendLimitPeriod;
+
+    /**
+     * Why the limit is set or changed, kept for audit.
+     */
+    reason?: string;
+  }
+}
+
+export interface SpendLimitDeleteParams {
+  /**
+   * Limit period. Defaults to `daily`; send it explicitly.
+   */
+  period?: SpendLimitPeriod;
+
+  /**
+   * Why the limit is removed, kept for audit. At most 500 characters.
+   */
+  reason?: string;
+}
+
+export type SpendLimitUpdateParams =
+  | SpendLimitUpdateParams.UpdateSpendLimitWithAmount
+  | SpendLimitUpdateParams.UpdateSpendLimitUnlimited;
+
+export declare namespace SpendLimitUpdateParams {
+  export interface UpdateSpendLimitWithAmount {
+    /**
+     * Body param: Limit in USD. `0` blocks at the first cent of spend.
+     */
+    amount: number;
+
+    /**
+     * Query param: Limit period. Defaults to `daily`; send it explicitly.
+     */
+    period?: SpendLimitPeriod;
+
+    /**
+     * Body param: Why the limit is set or changed, kept for audit.
+     */
+    reason?: string;
+
+    /**
+     * Body param: Optional; only `false` is allowed together with `amount`.
+     */
+    unlimited?: false;
+  }
+
+  export interface UpdateSpendLimitUnlimited {
+    /**
+     * Body param: `true`: explicitly no cap.
+     */
+    unlimited: true;
+
+    /**
+     * Query param: Limit period. Defaults to `daily`; send it explicitly.
+     */
+    period?: SpendLimitPeriod;
+
+    /**
+     * Body param: Why the limit is set or changed, kept for audit.
+     */
+    reason?: string;
+  }
+}
+
+export declare namespace SpendLimits {
+  export {
+    type SpendLimit as SpendLimit,
+    type SpendLimitPeriod as SpendLimitPeriod,
+    type SpendLimitResponse as SpendLimitResponse,
+    type SpendLimitListResponse as SpendLimitListResponse,
+    type SpendLimitCreateParams as SpendLimitCreateParams,
+    type SpendLimitDeleteParams as SpendLimitDeleteParams,
+    type SpendLimitUpdateParams as SpendLimitUpdateParams,
+  };
+}

package/src/resources/terms-of-service/agreements.ts

@@ -49,10 +49,19 @@ export type TosAgreementsDefaultFlatPagination = DefaultFlatPagination<TosAgreem
  * their own identity.
  */
 export interface TosAgreement {
+  /**
+   * The unique identifier of this recorded agreement.
+   */
   id?: string;
 
+  /**
+   * When you accepted this version of the terms.
+   */
   agreed_at?: string;
 
+  /**
+   * When this agreement record was created.
+   */
   created_at?: string;
 
   /**
@@ -60,6 +69,9 @@ export interface TosAgreement {
    */
   product_type?: TosProductType;
 
+  /**
+   * The version of the terms you accepted.
+   */
   terms_version?: string;
 
   /**

package/src/resources/terms-of-service/terms-of-service.ts

@@ -61,10 +61,19 @@ export interface TermsOfServiceRetrieveInfoResponse {
 
 export namespace TermsOfServiceRetrieveInfoResponse {
   export interface Agreement {
+    /**
+     * The latest published version of these terms.
+     */
     current_version?: string;
 
+    /**
+     * A short summary of the product these terms cover.
+     */
     description?: string;
 
+    /**
+     * The date this version took effect.
+     */
     effective_date?: string;
 
     /**
@@ -72,6 +81,9 @@ export namespace TermsOfServiceRetrieveInfoResponse {
      */
     product_type?: AgreementsAPI.TosProductType;
 
+    /**
+     * A link to the full terms text.
+     */
     terms_url?: string;
   }
 }
@@ -111,6 +123,9 @@ export namespace TermsOfServiceRetrieveStatusResponse {
      */
     product_type: AgreementsAPI.TosProductType;
 
+    /**
+     * When you accepted the terms, or null if you have not.
+     */
     agreed_at?: string | null;
 
     /**

package/src/resources/texml/texml.ts

@@ -43,8 +43,10 @@ export class Texml extends APIResource {
   }
 
   /**
-   * Initiate an outbound AI call with warm-up support. Validates parameters, builds
-   * an internal TeXML with an AI Assistant configuration, encodes instructions into
+   * Initiate an outbound AI call with warm-up support: Telnyx attempts to warm up
+   * the assistant identified by `AIAssistantId` before placing the call and starts
+   * it automatically when the called party answers. Validates parameters, builds an
+   * internal TeXML with an AI Assistant configuration, encodes instructions into
    * client state, and calls the dial API. The Twiml, Texml, and Url parameters are
    * not allowed and will result in a 422 error.
    *
@@ -121,7 +123,9 @@ export interface TexmlSecretsParams {
 
 export interface TexmlInitiateAICallParams {
   /**
-   * The ID of the AI assistant to use for the call.
+   * The ID of the AI assistant to use for the call. Telnyx attempts to warm up this
+   * assistant before the call is placed and starts it automatically when the called
+   * party answers.
    */
   AIAssistantId: string;