telnyx 7.28.0 → 7.30.0-beta.0

package/src/lib/login-token.ts

@@ -0,0 +1,219 @@
+/**
+ * WebRTC login tokens minted locally, with no request to Telnyx.
+ *
+ * The token has the same shape as the one
+ * `POST /v2/telephony_credentials/{id}/token` returns, so it is used the same
+ * way: pass it to the WebRTC SDK as `login_token`. Telnyx verifies it on login.
+ * It is the same computation as `TelephonyCredential#to_jwt` in telnyx-ruby.
+ *
+ * The signing material comes from the credential: `token_material` is in the
+ * response of `POST /v2/telephony_credentials` and of
+ * `GET /v2/telephony_credentials/{id}/token_material`. It is as sensitive as
+ * the SIP password, so keep it on the server; never ship it to a browser.
+ *
+ * @example
+ * const { data: credential } = await client.telephonyCredentials.create({
+ *   connection_id: '123',
+ *   include: 'token_material',   // the API returns the material only when asked
+ * });
+ * const loginToken = await client.telephonyCredentials.toJwt(credential);          // 1 hour
+ * const shortLived = await client.telephonyCredentials.toJwt(credential, { ttl: 600 });
+ *
+ * To mint later with no request at all, store these with the user the credential
+ * belongs to, server side: `id`, `user_id`, `sip_username`, `expires_at` and
+ * `token_material`. The token is built from all of them.
+ *
+ * @example From stored values, without a request at all
+ * import { createLoginToken } from 'telnyx/lib/login-token';
+ * const loginToken = await createLoginToken({
+ *   id: '...', user_id: '...', sip_username: 'gencred...', expires_at: '2027-01-01T00:00:00Z',
+ *   token_material: { kid: 'v1', tel_token: '...', signing_secret: '...' },
+ * });
+ */
+
+import { TelnyxError } from '../core/error';
+import { fromBase64, toBase64 } from '../internal/utils/base64';
+import { decodeUTF8, encodeUTF8 } from '../internal/utils/bytes';
+
+/** Token lifetime when `ttl` is not given: one hour. */
+export const LOGIN_TOKEN_DEFAULT_TTL = 3600;
+/** Longest lifetime a login token can have: one day, the same as API-minted tokens. */
+export const LOGIN_TOKEN_MAX_TTL = 86400;
+/** `cty` header of a locally minted token; voice-sdk-proxy selects the verification path by it. */
+export const LOGIN_TOKEN_CONTENT_TYPE = 'telnyx-webrtc;v=1';
+
+/**
+ * What the API returns as `token_material`. `signing_secret` is base64url
+ * (unpadded) bytes of the HS256 key; `tel_token` goes into the token as is.
+ */
+export interface TokenMaterial {
+  /** Which key the material was derived with (`v1` today). Goes in the JWT header. */
+  kid: string;
+  /** The SIP credential encrypted for the gateway, the same value `/token` puts in the `tel_token` claim. */
+  tel_token: string;
+  /** The HS256 key the token is signed with, base64url. */
+  signing_secret: string;
+}
+
+/** The fields of a telephony credential that a login token is built from. */
+export interface LoginTokenCredential {
+  /** The telephony credential `id`. */
+  id?: string | undefined;
+  /** The credential's `user_id`. */
+  user_id?: string | undefined;
+  /** The credential's `sip_username`; the token's `identity`. */
+  sip_username?: string | undefined;
+  /** The credential's `expires_at`, as the API returns it, or null. */
+  expires_at?: string | null | undefined;
+  /** `kid`, `tel_token`, `signing_secret`; present on a credential from `create`. */
+  token_material?: TokenMaterial | undefined;
+}
+
+export interface LoginTokenOptions {
+  /** Token lifetime in seconds, 1..86400. Default one hour. */
+  ttl?: number | undefined;
+  /** Signing material to use instead of `credential.token_material`. */
+  tokenMaterial?: TokenMaterial | undefined;
+  /** The token's issue time; defaults to now. */
+  now?: Date | number | undefined;
+}
+
+export class TelnyxLoginTokenError extends TelnyxError {
+  constructor(message: string) {
+    super(message);
+    this.name = 'TelnyxLoginTokenError';
+  }
+}
+
+/**
+ * Mints a login token for `credential`, valid from `now` for `ttl` seconds.
+ * Pure computation: HMAC-SHA256 over the token with `token_material.signing_secret`.
+ */
+export async function createLoginToken(
+  credential: LoginTokenCredential,
+  options: LoginTokenOptions = {},
+): Promise<string> {
+  const credentialId = required(credential.id, 'id');
+  const userId = required(credential.user_id, 'user_id');
+  const identity = required(credential.sip_username, 'sip_username');
+  const material = normalizeMaterial(options.tokenMaterial ?? credential.token_material);
+  const ttl = clampTtl(options.ttl);
+  const now = options.now === undefined ? Date.now() : Number(options.now);
+  const iat = Math.floor(now / 1000);
+
+  // Same field order as the Ruby SDK, so the two produce the same bytes.
+  const header = { alg: 'HS256', typ: 'JWT', cty: LOGIN_TOKEN_CONTENT_TYPE, kid: material.kid };
+  const payload = {
+    sub: credentialId,
+    user_id: userId,
+    identity,
+    cred_exp: credential.expires_at ?? null,
+    tel_token: material.tel_token,
+    iat,
+    nbf: iat,
+    exp: iat + ttl,
+    jti: `${credentialId}-${iat}`,
+  };
+
+  const signingInput = `${base64url(JSON.stringify(header))}.${base64url(JSON.stringify(payload))}`;
+  return `${signingInput}.${base64url(await sign(signingInput, material.signing_secret))}`;
+}
+
+/**
+ * Checks a token minted by `createLoginToken` against `signingSecret` and
+ * returns its claims. For tests and debugging: Telnyx does the real
+ * verification on login.
+ */
+export async function decodeLoginToken(jwt: string, signingSecret: string): Promise<Record<string, unknown>> {
+  const [head, body, sig, ...rest] = String(jwt).split('.');
+  if (!head || !body || sig === undefined || rest.length) {
+    throw new TelnyxLoginTokenError('not a JWT');
+  }
+  const expected = await sign(`${head}.${body}`, signingSecret);
+  const given = fromBase64url(sig);
+  if (!bytesEqual(given, expected)) {
+    throw new TelnyxLoginTokenError('Signature is invalid and does not match the payload');
+  }
+  return JSON.parse(decodeUTF8(fromBase64url(body))) as Record<string, unknown>;
+}
+
+function required(value: string | null | undefined, name: string): string {
+  if (value === undefined || value === null || String(value) === '') {
+    throw new TelnyxLoginTokenError(`${name} is required to mint a token`);
+  }
+  return String(value);
+}
+
+function normalizeMaterial(material: TokenMaterial | null | undefined): TokenMaterial {
+  if (!material || typeof material !== 'object') {
+    throw new TelnyxLoginTokenError('token_material is required to mint a token');
+  }
+  const out = {} as Record<keyof TokenMaterial, string>;
+  for (const field of ['kid', 'tel_token', 'signing_secret'] as const) {
+    const value = material[field];
+    if (value === undefined || value === null || String(value) === '') {
+      throw new TelnyxLoginTokenError(`token_material.${field} is missing`);
+    }
+    out[field] = String(value);
+  }
+  return out;
+}
+
+function clampTtl(ttl: number | undefined): number {
+  const n = ttl === undefined ? LOGIN_TOKEN_DEFAULT_TTL : Math.trunc(Number(ttl));
+  if (!Number.isFinite(n)) return LOGIN_TOKEN_DEFAULT_TTL;
+  return Math.min(LOGIN_TOKEN_MAX_TTL, Math.max(1, n));
+}
+
+function base64url(data: string | Uint8Array): string {
+  // Base64 pads with at most two '=': a bounded match keeps this linear on any input.
+  return toBase64(data)
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/={1,2}$/, '');
+}
+
+function fromBase64url(str: string): Uint8Array {
+  const b64 = str.replace(/-/g, '+').replace(/_/g, '/');
+  return fromBase64(b64 + '='.repeat((4 - (b64.length % 4)) % 4));
+}
+
+function bytesEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a[i]! ^ b[i]!;
+  return diff === 0;
+}
+
+// HMAC-SHA256 through WebCrypto, which Node, Deno, Bun, browsers and edge runtimes all provide.
+interface SubtleCryptoLike {
+  importKey(
+    format: string,
+    keyData: Uint8Array,
+    algorithm: { name: string; hash: string },
+    extractable: boolean,
+    keyUsages: string[],
+  ): Promise<unknown>;
+  sign(algorithm: string, key: unknown, data: Uint8Array): Promise<ArrayBuffer>;
+}
+
+async function getSubtle(): Promise<SubtleCryptoLike> {
+  if (typeof globalThis.crypto !== 'undefined' && globalThis.crypto.subtle) {
+    return globalThis.crypto.subtle as unknown as SubtleCryptoLike;
+  }
+  // Node.js < 19 may need webcrypto from crypto module
+  const nodeCrypto = await import('crypto');
+  return (nodeCrypto.webcrypto as unknown as { subtle: SubtleCryptoLike }).subtle;
+}
+
+async function sign(signingInput: string, signingSecret: string): Promise<Uint8Array> {
+  const subtle = await getSubtle();
+  const key = await subtle.importKey(
+    'raw',
+    fromBase64url(signingSecret),
+    { name: 'HMAC', hash: 'SHA-256' },
+    false,
+    ['sign'],
+  );
+  return new Uint8Array(await subtle.sign('HMAC', key, encodeUTF8(signingInput)));
+}

package/src/resources/addresses/actions.ts

@@ -78,10 +78,7 @@ export interface ActionValidateResponse {
 
 export namespace ActionValidateResponse {
   export interface Data {
-    /**
-     * Indicates whether an address is valid or invalid.
-     */
-    result: 'valid' | 'invalid';
+    result: 'valid';
 
     /**
      * Provides normalized address when available.
@@ -107,6 +104,12 @@ export namespace ActionValidateResponse {
        */
       administrative_area?: string;
 
+      /**
+       * The borough of the address. This field is not used for addresses in the US but
+       * is used for some international addresses.
+       */
+      borough?: string;
+
       /**
        * The two-character (ISO 3166-1 alpha-2) country code of the address.
        */
@@ -118,12 +121,28 @@ export namespace ActionValidateResponse {
        */
       extended_address?: string;
 
+      /**
+       * Latitude of the suggested address, when available.
+       */
+      latitude?: number | null;
+
       /**
        * The locality of the address. For US addresses, this corresponds to the city of
        * the address.
        */
       locality?: string;
 
+      /**
+       * Longitude of the suggested address, when available.
+       */
+      longitude?: number | null;
+
+      /**
+       * The neighborhood of the address. This field is not used for addresses in the US
+       * but is used for some international addresses.
+       */
+      neighborhood?: string;
+
       /**
        * The postal code of the address.
        */

package/src/resources/ai/ai.ts

@@ -193,6 +193,8 @@ import {
 } from './missions/missions';
 import * as OpenAIAPI from './openai/openai';
 import { OpenAI, OpenAICreateResponseParams, OpenAICreateResponseResponse } from './openai/openai';
+import * as TestsAPI from './tests/tests';
+import { Tests } from './tests/tests';
 import * as TypesafeAPI from './typesafe/typesafe';
 import { Typesafe } from './typesafe/typesafe';
 import { APIPromise } from '../../core/api-promise';
@@ -219,6 +221,7 @@ export class AI extends APIResource {
   typesafe: TypesafeAPI.Typesafe = new TypesafeAPI.Typesafe(this._client);
   memory: MemoryAPI.Memory = new MemoryAPI.Memory(this._client);
   avatars: AvatarsAPI.Avatars = new AvatarsAPI.Avatars(this._client);
+  tests: TestsAPI.Tests = new TestsAPI.Tests(this._client);
 
   /**
    * Generate a summary of a file's contents.
@@ -674,6 +677,7 @@ AI.Knowledge = Knowledge;
 AI.Typesafe = Typesafe;
 AI.Memory = Memory;
 AI.Avatars = Avatars;
+AI.Tests = Tests;
 
 export declare namespace AI {
   export {
@@ -887,4 +891,6 @@ export declare namespace AI {
     type AvatarCreateParams as AvatarCreateParams,
     type AvatarUpdateParams as AvatarUpdateParams,
   };
+
+  export { Tests as Tests };
 }

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

@@ -3804,9 +3804,10 @@ export interface TranscriptionSettings {
    *   auto-detect; set `language` from Speechmatics' Realtime language list
    *   (defaults to `en`).
    * - `azure/fast` is a multilingual Azure transcription model.
-   * - `assemblyai/universal-3-5-pro` is a multilingual streaming model with
-   *   configurable turn detection. The legacy alias `assemblyai/universal-streaming`
-   *   is still accepted and resolves to the same model.
+   * - `assemblyai/universal-3-6-pro` (AssemblyAI Universal-3.6 Pro) is a
+   *   multilingual streaming model with configurable turn detection. The legacy
+   *   aliases `assemblyai/universal-3-5-pro` and `assemblyai/universal-streaming`
+   *   are still accepted and run the same model.
    * - `xai/grok-stt` is a multilingual Grok STT model.
    * - `soniox/stt-rt-v4` and `soniox/stt-rt-v5` are multilingual streaming models
    *   with automatic language detection, configurable endpointing, term biasing
@@ -3829,6 +3830,7 @@ export interface TranscriptionSettings {
     | 'speechmatics/standard'
     | 'speechmatics/linden-1'
     | 'azure/fast'
+    | 'assemblyai/universal-3-6-pro'
     | 'assemblyai/universal-3-5-pro'
     | 'assemblyai/universal-streaming'
     | 'xai/grok-stt'
@@ -3861,11 +3863,11 @@ export namespace TranscriptionSettings {
     /**
      * The language booster's model. It must be the same kind of model as
      * `transcription.model`: both streaming (`deepgram/flux`, `deepgram/nova-3`,
-     * `deepgram/nova-2`, `assemblyai/universal-3-5-pro` or its legacy alias
-     * `assemblyai/universal-streaming`, `xai/grok-stt`, `soniox/stt-rt-v4`,
-     * `soniox/stt-rt-v5`, `humain/realtime`, `reson8/turns`) or both non-streaming
-     * (`azure/fast`, `nvidia/parakeet-v3`, `omi-health/omi-med-stt-v1`,
-     * `cohere/ar-stt`, `distil-whisper/distil-large-v2`,
+     * `deepgram/nova-2`, `assemblyai/universal-3-6-pro` or its legacy aliases
+     * `assemblyai/universal-3-5-pro` and `assemblyai/universal-streaming`,
+     * `xai/grok-stt`, `soniox/stt-rt-v4`, `soniox/stt-rt-v5`, `humain/realtime`,
+     * `reson8/turns`) or both non-streaming (`azure/fast`, `nvidia/parakeet-v3`,
+     * `omi-health/omi-med-stt-v1`, `cohere/ar-stt`, `distil-whisper/distil-large-v2`,
      * `openai/whisper-large-v3-turbo`, `telnyx/basira`). It can be the same model as
      * `transcription.model` on a different `language`.
      */
@@ -3874,6 +3876,7 @@ export namespace TranscriptionSettings {
       | 'deepgram/nova-3'
       | 'deepgram/nova-2'
       | 'azure/fast'
+      | 'assemblyai/universal-3-6-pro'
       | 'assemblyai/universal-3-5-pro'
       | 'assemblyai/universal-streaming'
       | 'xai/grok-stt'
@@ -3936,14 +3939,16 @@ export namespace TranscriptionSettings {
     /**
      * The fallback model. It must be a streaming model other than
      * `transcription.model` and the other fallbacks: `deepgram/flux`,
-     * `deepgram/nova-3`, `deepgram/nova-2`, `assemblyai/universal-3-5-pro` (or its
-     * legacy alias `assemblyai/universal-streaming`), `xai/grok-stt`,
-     * `soniox/stt-rt-v4`, `soniox/stt-rt-v5`, `humain/realtime`, or `reson8/turns`.
+     * `deepgram/nova-3`, `deepgram/nova-2`, `assemblyai/universal-3-6-pro` (or its
+     * legacy aliases `assemblyai/universal-3-5-pro` and
+     * `assemblyai/universal-streaming`), `xai/grok-stt`, `soniox/stt-rt-v4`,
+     * `soniox/stt-rt-v5`, `humain/realtime`, or `reson8/turns`.
      */
     model:
       | 'deepgram/flux'
       | 'deepgram/nova-3'
       | 'deepgram/nova-2'
+      | 'assemblyai/universal-3-6-pro'
       | 'assemblyai/universal-3-5-pro'
       | 'assemblyai/universal-streaming'
       | 'xai/grok-stt'
@@ -4026,9 +4031,9 @@ export interface TranscriptionSettingsConfig {
    * transcription, used by Deepgram, Reson8, Speechmatics Linden 1 and AssemblyAI
    * models. Helps improve accuracy for domain-specific terminology, proper nouns, or
    * uncommon words. At most 1000 characters in total. For
-   * assemblyai/universal-3-5-pro (and its legacy alias
-   * assemblyai/universal-streaming), also at most 100 terms of up to 50 characters
-   * each. This field may be templated with
+   * assemblyai/universal-3-6-pro (and its legacy aliases
+   * assemblyai/universal-3-5-pro and assemblyai/universal-streaming), also at most
+   * 100 terms of up to 50 characters each. This field may be templated with
    * [dynamic variables](https://developers.telnyx.com/docs/inference/ai-assistants/dynamic-variables)
    * using mustache syntax (e.g. `Telnyx,{{customer_name}},VoIP`). Variables are
    * resolved at call time before the value is sent to the speech-to-text engine.
@@ -4050,26 +4055,28 @@ export interface TranscriptionSettingsConfig {
   max_endpoint_delay_ms?: number;
 
   /**
-   * Available only for assemblyai/universal-3-5-pro (and its legacy alias
-   * assemblyai/universal-streaming). Maximum duration of silence in milliseconds
-   * before forcing an end of turn.
+   * Available only for assemblyai/universal-3-6-pro (and its legacy aliases
+   * assemblyai/universal-3-5-pro and assemblyai/universal-streaming). Maximum
+   * duration of silence in milliseconds before forcing an end of turn.
    */
   max_turn_silence?: number;
 
   /**
-   * Available only for assemblyai/universal-3-5-pro (and its legacy alias
-   * assemblyai/universal-streaming). Minimum duration of silence in milliseconds
-   * before a turn can end. Must be less than or equal to max_turn_silence.
+   * Available only for assemblyai/universal-3-6-pro (and its legacy aliases
+   * assemblyai/universal-3-5-pro and assemblyai/universal-streaming). Minimum
+   * duration of silence in milliseconds before a turn can end. Must be less than or
+   * equal to max_turn_silence.
    */
   min_turn_silence?: number;
 
   numerals?: boolean;
 
   /**
-   * Available only for assemblyai/universal-3-5-pro (and its legacy alias
-   * assemblyai/universal-streaming). Context about the conversation (domain, names,
-   * terms) to improve transcription; describe the content, do not give instructions.
-   * Leave empty unless needed. At most 1750 characters.
+   * Available only for assemblyai/universal-3-6-pro (and its legacy aliases
+   * assemblyai/universal-3-5-pro and assemblyai/universal-streaming). Context about
+   * the conversation (domain, names, terms) to improve transcription; describe the
+   * content, do not give instructions. Leave empty unless needed. At most 1750
+   * characters.
    */
   prompt?: string;
 

package/src/resources/ai/avatars.ts

@@ -44,15 +44,15 @@ export class Avatars extends APIResource {
    * is stored independently from the rendering model and background, which are
    * selected where the avatar is consumed. Supported image types are JPEG, PNG, and
    * WebP. Images may be up to 10 MiB, must be between 256 and 8192 pixels on each
-   * side, and may contain at most 40 megapixels. Each organization may have up to 20
-   * custom avatars. For best results, use a 16:9 landscape image, preferably 1920 by
-   * 1080 pixels and at least 1280 by 720 pixels. Show one centered, front-facing
-   * person from the shoulders up, keep the full head and hair visible with space
-   * around it, and use a sharp, evenly lit image with unobstructed eyes and mouth.
-   * Use a transparent PNG or WebP when the avatar will be combined with a selectable
-   * background. These composition recommendations are not enforced in the first
-   * release; the first release does not validate the number of faces, pose, or image
-   * content.
+   * side, and may contain at most 40 megapixels. A per-organization custom-avatar
+   * quota applies; the create request returns an error when the quota is reached.
+   * For best results, use a 16:9 landscape image, preferably 1920 by 1080 pixels and
+   * at least 1280 by 720 pixels. Show one centered, front-facing person from the
+   * shoulders up, keep the full head and hair visible with space around it, and use
+   * a sharp, evenly lit image with unobstructed eyes and mouth. Use a transparent
+   * PNG or WebP when the avatar will be combined with a selectable background. These
+   * composition recommendations are not enforced in the first release; the first
+   * release does not validate the number of faces, pose, or image content.
    *
    * @example
    * ```ts

package/src/resources/ai/index.ts

@@ -174,6 +174,7 @@ export {
   type MissionDataDefaultFlatPagination,
 } from './missions/index';
 export { OpenAI, type OpenAICreateResponseResponse, type OpenAICreateResponseParams } from './openai/index';
+export { Tests } from './tests/index';
 export {
   Tools,
   type PayToolParams,

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

@@ -0,0 +1,5 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export { Schedules } from './schedules/index';
+export { TestFramework } from './test-framework/index';
+export { Tests } from './tests';

package/src/resources/ai/tests/schedules/index.ts

@@ -0,0 +1,4 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export { Schedules } from './schedules';
+export { V1 } from './v1/index';

package/src/resources/ai/tests/schedules/schedules.ts

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