telnyx 7.24.0 → 7.26.0

package/src/resources/llm-token-gateway/usage.ts

@@ -0,0 +1,460 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as UsageAPI from './usage';
+import { APIPromise } from '../../core/api-promise';
+import { RequestOptions } from '../../internal/request-options';
+
+/**
+ * Manage and report AI Gateway usage.
+ */
+export class Usage extends APIResource {
+  /**
+   * Gateway reference/enforcement usage, not invoice truth or BYOK provider charges.
+   * Requires the dedicated llm_token_gateway.usage.read V2 action for combined spend
+   * and guardrail reporting; existing spend.read and guardrail_events.read grants do
+   * not grant this endpoint. All totals, UTC daily buckets, models and latest 20
+   * guardrail events share one database snapshot. UTC half-open dates, at most 31
+   * days. Zero-filled days; at most 1000 models (503 rather than truncation on
+   * overflow/timeout). Known tokens sum independently known categories across latest
+   * attempt evidence, including corrections; unknown spend is excluded and
+   * unknown_requests/reserved_spend remain explicit. Guardrail counts count events,
+   * not distinct requests. No raw spend events, prompts or secrets. This read-only
+   * report creates no pagination snapshot and accepts no pagination parameters.
+   *
+   * @example
+   * ```ts
+   * const response =
+   *   await client.llmTokenGateway.usage.retrieveSummary({
+   *     end_date: '2019-12-27',
+   *     start_date: '2019-12-27',
+   *     token_group_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   *   });
+   * ```
+   */
+  retrieveSummary(
+    query: UsageRetrieveSummaryParams,
+    options?: RequestOptions,
+  ): APIPromise<UsageRetrieveSummaryResponse> {
+    return this._client.get('/llm_token_gateway/usage/summary', { query, ...options });
+  }
+
+  /**
+   * Durable, replayable, content-free usage export for customer pipelines. Requires
+   * the dedicated llm_token_gateway.usage_export.read V2 action; spend.read and
+   * usage.read do not grant it. Records are inference.request (one per immutable
+   * ledger revision; a correction adds a new id with supersedes, keep the highest
+   * revision per request_id) and guardrail.evaluation (one per guardrail event,
+   * including blocked prompts with no inference record; correlate on request_id).
+   * Delivery is at least once in commit order: deduplicate on id. Records appear
+   * after settlement and after every older database transaction has finished
+   * (meta.horizon_lag_seconds); keep polling with next_cursor, which is always
+   * returned and is reusable after has_more is false. After a logical database
+   * restore, restart from start_time and deduplicate on id; a cursor from before it
+   * may return 409 cursor_expired (no Retry-After). Retention promise 30 days. No
+   * prompts, responses, provider credentials, supplier or customer rates. Gateway
+   * reference/enforcement usage, not invoice truth or BYOK provider charges.
+   *
+   * @example
+   * ```ts
+   * const response =
+   *   await client.llmTokenGateway.usage.retrieveExport();
+   * ```
+   */
+  retrieveExport(
+    query: UsageRetrieveExportParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<UsageRetrieveExportResponse> {
+    return this._client.get('/llm_token_gateway/usage/export', { query, ...options });
+  }
+}
+
+export interface GuardrailFinding {
+  action: 'flag' | 'block';
+
+  code: string;
+
+  count: number;
+
+  detector: 'secrets' | 'dlp' | 'safety';
+}
+
+export interface UsageRetrieveExportResponse {
+  data: Array<
+    | UsageRetrieveExportResponse.UsageExportInferenceRequest
+    | UsageRetrieveExportResponse.UsageExportGuardrailEvaluation
+  >;
+
+  meta: UsageRetrieveExportResponse.Meta;
+}
+
+export namespace UsageRetrieveExportResponse {
+  export interface UsageExportInferenceRequest {
+    /**
+     * Deterministic: req\_{request_id}\_r{revision}. Deduplicate on id.
+     */
+    id: string;
+
+    attempts: number;
+
+    biller: 'telnyx' | 'provider' | 'none';
+
+    cache_hit: boolean;
+
+    configuration_version: number;
+
+    /**
+     * USD decimal string with exactly 6 places, 0 to 1000000000.000000 (the Money
+     * bound); enforcement basis, not invoice truth.
+     */
+    cost: string | null;
+
+    end_user_id: string | null;
+
+    input_tokens: number | null;
+
+    /**
+     * Customer request tags captured at admission; {} when untagged.
+     */
+    metadata: { [key: string]: string | number | boolean };
+
+    model: string;
+
+    output_tokens: number | null;
+
+    protocol: 'openai' | 'anthropic';
+
+    provider: string;
+
+    provider_key_id: string | null;
+
+    provider_model: string;
+
+    rate_version: string;
+
+    request_id: string;
+
+    revision: number;
+
+    route_mode: 'managed' | 'byok' | 'cache';
+
+    schema_version: 1;
+
+    status: 'succeeded' | 'failed' | 'partial' | 'unknown';
+
+    stream: boolean;
+
+    /**
+     * Previous revision id; keep the highest revision per request_id.
+     */
+    supersedes: string | null;
+
+    timings: UsageExportInferenceRequest.Timings;
+
+    token_group_id: string;
+
+    token_key_id: string;
+
+    token_user_id: string | null;
+
+    type: 'inference.request';
+
+    usage_source: 'provider' | 'gateway_tokenizer' | 'operator' | null;
+
+    usage_status: 'known' | 'unknown' | 'reconciled';
+  }
+
+  export namespace UsageExportInferenceRequest {
+    export interface Timings {
+      admitted_at: string;
+
+      completed_at: string | null;
+
+      first_attempt_at: string | null;
+
+      /**
+       * completed_at - admitted_at as recorded by the ledger; not time to first token.
+       */
+      gateway_duration_ms: number | null;
+
+      settled_at: string;
+    }
+  }
+
+  export interface UsageExportGuardrailEvaluation {
+    id: string;
+
+    created_at: string;
+
+    end_user_id: string | null;
+
+    evaluation_input_tokens: number | null;
+
+    evaluation_output_tokens: number | null;
+
+    findings: Array<UsageAPI.GuardrailFinding>;
+
+    /**
+     * Customer request tags from the x-ltg-metadata header: up to 5 entries. Keys are
+     * case-sensitive; keys starting with ltg*, telnyx*, litellm* or cf* (any case) are
+     * reserved. Values are strings (1-256 characters, no control or format
+     * characters), integers within +/-9007199254740991, or booleans; floats, null,
+     * objects and arrays are rejected. Values that look like credentials are rejected.
+     * Tags are attribution only: never forwarded upstream, never part of the response
+     * cache key, never used for budgets or routing. An untagged request reports {}.
+     */
+    metadata: { [key: string]: string | number | boolean };
+
+    model: string;
+
+    outcome: 'evaluated' | 'flagged' | 'blocked' | 'unevaluated';
+
+    request_id: string;
+
+    schema_version: 1;
+
+    stage: 'prompt' | 'response';
+
+    token_group_id: string;
+
+    token_key_id: string;
+
+    token_user_id: string | null;
+
+    type: 'guardrail.evaluation';
+  }
+
+  export interface Meta {
+    has_more: boolean;
+
+    horizon_lag_seconds: number;
+
+    next_cursor: string;
+  }
+}
+
+export interface UsageRetrieveSummaryResponse {
+  data: UsageRetrieveSummaryResponse.Data;
+
+  meta: UsageRetrieveSummaryResponse.Meta;
+}
+
+export namespace UsageRetrieveSummaryResponse {
+  export interface Data {
+    by_day: Array<Data.ByDay>;
+
+    by_model: Array<Data.ByModel>;
+
+    guardrails: Data.Guardrails;
+
+    totals: Data.Totals;
+  }
+
+  export namespace Data {
+    export interface ByDay {
+      cache_hits: number;
+
+      date: string;
+
+      failed_requests: number;
+
+      input_tokens: number;
+
+      output_tokens: number;
+
+      partial_requests: number;
+
+      requests: number;
+
+      /**
+       * USD, decimal precision at most 6 places; parse exactly to integer micro-USD,
+       * never binary float accounting.
+       */
+      reserved_spend: number;
+
+      /**
+       * USD, decimal precision at most 6 places; parse exactly to integer micro-USD,
+       * never binary float accounting.
+       */
+      spend: number;
+
+      succeeded_requests: number;
+
+      unknown_requests: number;
+    }
+
+    export interface ByModel {
+      cache_hits: number;
+
+      failed_requests: number;
+
+      input_tokens: number;
+
+      model: string;
+
+      output_tokens: number;
+
+      partial_requests: number;
+
+      requests: number;
+
+      /**
+       * USD, decimal precision at most 6 places; parse exactly to integer micro-USD,
+       * never binary float accounting.
+       */
+      reserved_spend: number;
+
+      /**
+       * USD, decimal precision at most 6 places; parse exactly to integer micro-USD,
+       * never binary float accounting.
+       */
+      spend: number;
+
+      succeeded_requests: number;
+
+      unknown_requests: number;
+    }
+
+    export interface Guardrails {
+      blocked_events: number;
+
+      flagged_events: number;
+
+      recent_events: Array<Guardrails.RecentEvent>;
+    }
+
+    export namespace Guardrails {
+      export interface RecentEvent {
+        id: string;
+
+        created_at: string;
+
+        end_user_id: string | null;
+
+        evaluation_input_tokens: number | null;
+
+        evaluation_output_tokens: number | null;
+
+        findings: Array<UsageAPI.GuardrailFinding>;
+
+        /**
+         * Customer request tags from the x-ltg-metadata header: up to 5 entries. Keys are
+         * case-sensitive; keys starting with ltg*, telnyx*, litellm* or cf* (any case) are
+         * reserved. Values are strings (1-256 characters, no control or format
+         * characters), integers within +/-9007199254740991, or booleans; floats, null,
+         * objects and arrays are rejected. Values that look like credentials are rejected.
+         * Tags are attribution only: never forwarded upstream, never part of the response
+         * cache key, never used for budgets or routing. An untagged request reports {}.
+         */
+        metadata: { [key: string]: string | number | boolean };
+
+        model: string;
+
+        outcome: 'evaluated' | 'flagged' | 'blocked' | 'unevaluated';
+
+        record_type: 'guardrail_event';
+
+        request_id: string;
+
+        stage: 'prompt' | 'response';
+
+        token_group_id: string;
+
+        token_key_id: string;
+
+        token_user_id: string | null;
+      }
+    }
+
+    export interface Totals {
+      cache_hits: number;
+
+      failed_requests: number;
+
+      input_tokens: number;
+
+      output_tokens: number;
+
+      partial_requests: number;
+
+      requests: number;
+
+      /**
+       * USD, decimal precision at most 6 places; parse exactly to integer micro-USD,
+       * never binary float accounting.
+       */
+      reserved_spend: number;
+
+      /**
+       * USD, decimal precision at most 6 places; parse exactly to integer micro-USD,
+       * never binary float accounting.
+       */
+      spend: number;
+
+      succeeded_requests: number;
+
+      unknown_requests: number;
+    }
+  }
+
+  export interface Meta {
+    end_date: string;
+
+    /**
+     * The metadata[<key>] filters applied to every section; {} when unfiltered.
+     */
+    metadata: { [key: string]: string };
+
+    start_date: string;
+
+    token_group_id: string;
+  }
+}
+
+export interface UsageRetrieveSummaryParams {
+  end_date: string;
+
+  start_date: string;
+
+  token_group_id: string;
+
+  /**
+   * Request tag filters as metadata[<key>]=<value>, at most 5, combined with AND. A
+   * value matches the tag's text form exactly (booleans as true/false, integers in
+   * decimal), so metadata[flag]=true matches both boolean true and the string
+   * "true". Keys are case-sensitive; reserved-prefix keys are rejected. Unindexed:
+   * bounded by the account, the date range and the report timeout.
+   */
+  metadata?: { [key: string]: string };
+}
+
+export interface UsageRetrieveExportParams {
+  /**
+   * Opaque next_cursor from a previous page; not combinable with start_time. Bound
+   * to the requested types; the account always comes from the credential.
+   */
+  cursor?: string;
+
+  limit?: number;
+
+  /**
+   * First page only: RFC 3339 with offset, at most 30 days ago and not in the
+   * future; default now - 24h.
+   */
+  start_time?: string;
+
+  /**
+   * Comma-separated subset of inference.request,guardrail.evaluation; default both.
+   */
+  types?: string;
+}
+
+export declare namespace Usage {
+  export {
+    type GuardrailFinding as GuardrailFinding,
+    type UsageRetrieveExportResponse as UsageRetrieveExportResponse,
+    type UsageRetrieveSummaryResponse as UsageRetrieveSummaryResponse,
+    type UsageRetrieveSummaryParams as UsageRetrieveSummaryParams,
+    type UsageRetrieveExportParams as UsageRetrieveExportParams,
+  };
+}

package/src/resources/llm-token-gateway.ts

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

package/src/resources/meeting-sessions/meeting-sessions.ts

@@ -139,12 +139,12 @@ export class MeetingSessions extends APIResource {
   }
 
   /**
-   * Irreversibly requests deletion of provider-hosted aggregate recording media
-   * under the provider contract. The operation retains the Telnyx-local Meeting
-   * session, transcript segments, events, artifacts, and usage records. It is
-   * separate from `DELETE /meeting_sessions/{id}`, which stops or cancels
-   * participation without deleting the persisted session. A missing/foreign session
-   * returns 404; provider deletion failures return 502.
+   * Irreversibly requests deletion of the aggregate recording media for the session.
+   * The operation retains the Telnyx-local Meeting session, transcript segments,
+   * events, artifacts, and usage records. It is separate from
+   * `DELETE /meeting_sessions/{id}`, which stops or cancels participation without
+   * deleting the persisted session. A missing/foreign session returns 404; provider
+   * deletion failures return 502.
    *
    * @example
    * ```ts
@@ -438,7 +438,7 @@ export namespace MeetingSessionDeleteRecordingMediaResponse {
      */
     meeting_session_id: string;
 
-    provider: 'recall';
+    provider: 'telnyx';
 
     scope: 'provider_recording_media';
   }
@@ -467,8 +467,7 @@ export interface MeetingSessionRetrieveRecordingsResponse {
 export namespace MeetingSessionRetrieveRecordingsResponse {
   export interface Data {
     /**
-     * Expiry timestamp when supplied by the provider, or null. The current adapter
-     * returns null.
+     * Expiry timestamp when available, or null. Currently returns null.
      */
     expires_at: string | null;
 

package/src/resources/phone-numbers/jobs.ts

@@ -15,9 +15,10 @@ import { path } from '../../internal/utils/path';
 export class Jobs extends APIResource {
   /**
    * Returns background jobs that operate on phone numbers. Filter by job type,
-   * target phone numbers, or job status, and sort by creation time. Multiple
-   * phone-number or status values use OR semantics within that filter; different
-   * filter categories use AND semantics. Results include pagination metadata.
+   * target phone numbers, job status, or creation-time customer reference, and sort
+   * by creation time. Multiple phone-number or status values use OR semantics within
+   * that filter; different filter categories use AND semantics. Results include
+   * pagination metadata.
    *
    * @example
    * ```ts
@@ -242,7 +243,8 @@ export interface JobUpdateEmergencySettingsBatchResponse {
 export interface JobListParams extends DefaultFlatPaginationParams {
   /**
    * Consolidated filter parameter (deepObject style). Originally: filter[type],
-   * filter[phone_number], filter[phone_number][], filter[status][]
+   * filter[phone_number], filter[phone_number][], filter[status][],
+   * filter[customer_reference]
    */
   filter?: JobListParams.Filter;
 
@@ -256,9 +258,20 @@ export interface JobListParams extends DefaultFlatPaginationParams {
 export namespace JobListParams {
   /**
    * Consolidated filter parameter (deepObject style). Originally: filter[type],
-   * filter[phone_number], filter[phone_number][], filter[status][]
+   * filter[phone_number], filter[phone_number][], filter[status][],
+   * filter[customer_reference]
    */
   export interface Filter {
+    /**
+     * Returns jobs whose creation-time customer reference exactly matches the supplied
+     * value, not the current reference on a phone number. Only jobs within the lookup
+     * window (90 days by default) are returned. Supply a single non-blank string of up
+     * to 250 characters, without null characters, using
+     * `filter[customer_reference]=yourcustomerrefhere`. An invalid filter value
+     * returns HTTP 422.
+     */
+    customer_reference?: string;
+
     /**
      * Returns jobs that targeted any of the supplied account-owned phone numbers.
      * Values beginning with `+` must contain 1 to 20 digits after the plus sign. The

package/src/resources/porting-orders/phone-number-blocks.ts

@@ -130,7 +130,15 @@ export interface PortingPhoneNumberBlock {
   /**
    * Specifies the phone number type for this porting phone number block.
    */
-  phone_number_type?: 'landline' | 'local' | 'mobile' | 'national' | 'shared_cost' | 'toll_free';
+  phone_number_type?:
+    | 'landline'
+    | 'local'
+    | 'mobile'
+    | 'multipurpose'
+    | 'national'
+    | 'other'
+    | 'shared_cost'
+    | 'toll_free';
 
   /**
    * Identifies the type of the resource.

package/src/resources/porting-orders/porting-orders.ts

@@ -417,7 +417,15 @@ export interface PortingOrder {
   /**
    * The type of the phone number
    */
-  phone_number_type?: 'landline' | 'local' | 'mobile' | 'national' | 'shared_cost' | 'toll_free';
+  phone_number_type?:
+    | 'landline'
+    | 'local'
+    | 'mobile'
+    | 'multipurpose'
+    | 'national'
+    | 'other'
+    | 'shared_cost'
+    | 'toll_free';
 
   /**
    * List of phone numbers associated with this porting order

package/src/resources/porting-phone-numbers.ts

@@ -56,7 +56,15 @@ export interface PortingPhoneNumber {
   /**
    * The type of the phone number
    */
-  phone_number_type?: 'landline' | 'local' | 'mobile' | 'national' | 'shared_cost' | 'toll_free';
+  phone_number_type?:
+    | 'landline'
+    | 'local'
+    | 'mobile'
+    | 'multipurpose'
+    | 'national'
+    | 'other'
+    | 'shared_cost'
+    | 'toll_free';
 
   /**
    * Specifies whether Telnyx is able to confirm portability this number in the

package/src/resources/reputation/numbers.ts

@@ -59,6 +59,13 @@ export interface NumberListParams extends DefaultFlatPaginationParams {
    */
   'filter[enterprise_id]'?: string;
 
+  /**
+   * Only numbers with this ownership status. `removed` lists the numbers that were
+   * removed, each with its `removal_reason` and `removed_at`; removed numbers are
+   * not returned otherwise.
+   */
+  'filter[ownership_status]'?: ReputationNumbersAPI.ReputationOwnershipStatus;
+
   /**
    * Partial match on phone number. Must contain at least 5 digits.
    */
@@ -68,6 +75,11 @@ export interface NumberListParams extends DefaultFlatPaginationParams {
    * Exact phone-number match (E.164).
    */
   'filter[phone_number][eq]'?: string;
+
+  /**
+   * Only numbers with this source.
+   */
+  'filter[source]'?: ReputationNumbersAPI.ReputationNumberSource;
 }
 
 export interface NumberRetrieveParams {

package/src/resources/requirements.ts

@@ -97,7 +97,7 @@ export interface DocReqsRequirement {
    * Indicates the phone_number_type this requirement applies to. Leave blank if this
    * requirement applies to all number_types.
    */
-  phone_number_type?: 'local' | 'national' | 'toll_free';
+  phone_number_type?: 'local' | 'mobile' | 'multipurpose' | 'national' | 'shared_cost' | 'toll_free';
 
   /**
    * Identifies the type of the resource.
@@ -173,7 +173,7 @@ export namespace RequirementListParams {
     /**
      * Filters results to those applying to a specific phone_number_type
      */
-    phone_number_type?: 'local' | 'national' | 'toll_free';
+    phone_number_type?: 'local' | 'mobile' | 'multipurpose' | 'national' | 'shared_cost' | 'toll_free';
   }
 }