telnyx 7.27.0 → 7.29.0

package/src/resources/spend-limits.ts

@@ -1,6 +1,7 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 import { APIResource } from '../core/resource';
+import * as SpendLimitsAPI from './spend-limits';
 import { APIPromise } from '../core/api-promise';
 import { RequestOptions } from '../internal/request-options';
 import { path } from '../internal/utils/path';
@@ -12,6 +13,7 @@ import { path } from '../internal/utils/path';
  * - **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.
+ * - **API key limits.** For `inference`, a limit can also apply to one API key, named by `credential_id`: the key's identifier as recorded on usage, never its secret. When the key's spend goes above its own limit, only that key is blocked, with the error title `API key spend limit reached` (code `10039`); the account's other keys keep working. The API key limits of a period cannot add up to more than the total limit when the total has an amount. Only language-model requests authenticated with an API key count toward its limit.
  * - **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 {
@@ -20,7 +22,9 @@ export class SpendLimits extends APIResource {
    * 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.
+   * not paginated. Each entry also lists the API key limits of its product and
+   * period in `credential_limits`, with each key's spend and block. Each API key
+   * limit can be at most the total limit; together they may add up to more than it.
    *
    * @example
    * ```ts
@@ -36,7 +40,9 @@ export class SpendLimits extends APIResource {
    * `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.
+   * product and period; update it instead. With `credential_id`, the limit applies
+   * to that API key only: it needs an `amount`, and the period's API key limits
+   * cannot add up to more than the total limit when the total has an amount.
    *
    * @example
    * ```ts
@@ -57,7 +63,11 @@ export class SpendLimits extends APIResource {
    * 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.
+   * limit is set. With the `credential_id` query parameter, the request removes that
+   * API key's limit for the period and lifts the key's block in that period at once.
+   * A block under the key's limit in the other period stays
+   * (`evaluation.still_blocked_other_period`). Removing the total limit leaves the
+   * API key limits in place.
    *
    * @example
    * ```ts
@@ -71,8 +81,11 @@ export class SpendLimits extends APIResource {
     params: SpendLimitDeleteParams | null | undefined = {},
     options?: RequestOptions,
   ): APIPromise<SpendLimitResponse> {
-    const { period, reason } = params ?? {};
-    return this._client.delete(path`/spend_limits/${product}`, { query: { period, reason }, ...options });
+    const { credential_id, period, reason } = params ?? {};
+    return this._client.delete(path`/spend_limits/${product}`, {
+      query: { credential_id, period, reason },
+      ...options,
+    });
   }
 
   /**
@@ -81,6 +94,9 @@ export class SpendLimits extends APIResource {
    * 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.
+   * With the `credential_id` query parameter, the request changes that API key's
+   * limit; it needs an `amount`, and it can be at most the period's total limit.
+   * Lowering the total limit below the period's highest API key limit is refused.
    *
    * @example
    * ```ts
@@ -95,23 +111,30 @@ export class SpendLimits extends APIResource {
     params: SpendLimitUpdateParams,
     options?: RequestOptions,
   ): APIPromise<SpendLimitResponse> {
-    const { period, ...body } = params;
-    return this._client.patch(path`/spend_limits/${product}`, { query: { period }, body, ...options });
+    const { credential_id, period, ...body } = params;
+    return this._client.patch(path`/spend_limits/${product}`, {
+      query: { credential_id, period },
+      body,
+      ...options,
+    });
   }
 }
 
 /**
- * The spend limit, spend and block state of one product and period.
+ * The spend limit, spend and block state of one product and period. The top-level
+ * fields describe the total limit of the account; API key limits are nested in
+ * `credential_limits`.
  */
 export interface SpendLimit {
   /**
    * The active block of the period. `null` when the period is not blocked.
    */
-  block: SpendLimit.Block | null;
+  block: SpendLimitBlock | null;
 
   /**
-   * The product is blocked for this period. Always `false` in write responses; list
-   * the limits to read the block state.
+   * The product is blocked for the whole account in this period (total limit). An
+   * API key's own block appears only in `credential_limits`. Always `false` in write
+   * responses; list the limits to read the block state.
    */
   blocked: boolean;
 
@@ -167,6 +190,19 @@ export interface SpendLimit {
    */
   spend_usd: string | null;
 
+  /**
+   * In write responses, the API key the write was about; `null` for the total limit.
+   * Always `null` in list entries, which describe the total limit.
+   */
+  credential_id?: string | null;
+
+  /**
+   * List responses only. One item per API key limit of the product and period,
+   * sorted by `credential_id`, plus every API key that is still blocked. `[]` when
+   * there are none.
+   */
+  credential_limits?: Array<SpendLimit.CredentialLimit>;
+
   /**
    * What a create, update or delete did to the period at once. Only present in write
    * responses.
@@ -176,56 +212,99 @@ export interface SpendLimit {
 
 export namespace SpendLimit {
   /**
-   * The active block of the period. `null` when the period is not blocked.
+   * The limit set on the account for the product and period, whoever set it. `null`
+   * when none is set.
    */
-  export interface Block {
+  export interface Limit {
     /**
-     * Exclusive end of the block: it is lifted at 00:00 UTC on this date at the
-     * latest.
+     * Limit in USD, as a decimal string. `null` when `unlimited` is true.
      */
-    blocked_until: string;
+    amount: string | null;
 
     /**
-     * When the block started.
+     * `self_service` when a user of the account set it, `operator` when Telnyx support
+     * did.
      */
-    detected_at: string;
+    origin: 'self_service' | 'operator';
 
     /**
-     * The limit in USD that the spend went above, as a decimal string.
+     * True when the limit was set to explicitly no cap.
      */
-    limit_usd: string;
+    unlimited: boolean;
 
     /**
-     * Spend in USD when the block started, as a decimal string.
+     * When the limit was last set or changed.
      */
-    spend_usd: string;
+    updated_at: string;
   }
 
   /**
-   * The limit set on the account for the product and period, whoever set it. `null`
-   * when none is set.
+   * The limit, spend and block state of one API key in the product and period.
    */
-  export interface Limit {
+  export interface CredentialLimit {
     /**
-     * Limit in USD, as a decimal string. `null` when `unlimited` is true.
+     * The active block of the period. `null` when the period is not blocked.
      */
-    amount: string | null;
+    block: SpendLimitsAPI.SpendLimitBlock | null;
 
     /**
-     * `self_service` when a user of the account set it, `operator` when Telnyx support
-     * did.
+     * This API key is blocked for the period.
      */
-    origin: 'self_service' | 'operator';
+    blocked: boolean;
 
     /**
-     * True when the limit was set to explicitly no cap.
+     * Identifier of the API key as recorded on usage. Never the key's secret.
      */
-    unlimited: boolean;
+    credential_id: string;
 
     /**
-     * When the limit was last set or changed.
+     * The limit of one API key. It always has an amount. `null` for an API key that is
+     * still blocked after its limit was removed.
      */
-    updated_at: string;
+    limit: CredentialLimit.Limit | null;
+
+    /**
+     * Set when `spend_usd` is `null`.
+     */
+    spend_error: string | null;
+
+    /**
+     * Spend in USD in the period made with exactly this API key, as a decimal string.
+     * Usage without an API key identifier, or with another one, counts only toward the
+     * total. `null` when it could not be read.
+     */
+    spend_usd: string | null;
+
+    /**
+     * The API key's limit is above the period's total limit. Only a change by Telnyx
+     * support can cause it; the total limit still applies to the whole account. Lower
+     * the API key limit or raise the total.
+     */
+    exceeds_total?: boolean;
+  }
+
+  export namespace CredentialLimit {
+    /**
+     * The limit of one API key. It always has an amount. `null` for an API key that is
+     * still blocked after its limit was removed.
+     */
+    export interface Limit {
+      /**
+       * Limit in USD, as a decimal string.
+       */
+      amount: string;
+
+      /**
+       * `self_service` when a user of the account set it, `operator` when Telnyx support
+       * did.
+       */
+      origin: 'self_service' | 'operator';
+
+      /**
+       * When the limit was last set or changed.
+       */
+      updated_at: string;
+    }
   }
 
   /**
@@ -257,7 +336,7 @@ export namespace SpendLimit {
 
     /**
      * The other period has an active block, so the product stays blocked whatever this
-     * period's result.
+     * period's result. For an API key write, the API key's limit in the other period.
      */
     still_blocked_other_period: boolean;
 
@@ -266,6 +345,12 @@ export namespace SpendLimit {
      */
     still_over_limit: boolean;
 
+    /**
+     * API key writes only: the account itself remains blocked for the product under a
+     * total limit. Absent for total limit writes.
+     */
+    account_blocked?: boolean;
+
     /**
      * Additional information about the result, when there is any.
      */
@@ -273,6 +358,32 @@ export namespace SpendLimit {
   }
 }
 
+/**
+ * The active block of the period. `null` when the period is not blocked.
+ */
+export interface SpendLimitBlock {
+  /**
+   * 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;
+}
+
 /**
  * `daily` is the current UTC day; `monthly` is the current UTC calendar month.
  */
@@ -280,7 +391,9 @@ export type SpendLimitPeriod = 'daily' | 'monthly';
 
 export interface SpendLimitResponse {
   /**
-   * The spend limit, spend and block state of one product and period.
+   * The spend limit, spend and block state of one product and period. The top-level
+   * fields describe the total limit of the account; API key limits are nested in
+   * `credential_limits`.
    */
   data: SpendLimit;
 }
@@ -319,6 +432,14 @@ export declare namespace SpendLimitCreateParams {
      */
     product: string;
 
+    /**
+     * Optional. Identifier of one API key as recorded on usage, never the key's
+     * secret: the limit then applies to that key only. Absent or `null` sets the total
+     * limit. A blank value, or one with control characters, is refused; it never means
+     * the total limit. An API key limit always has an `amount`.
+     */
+    credential_id?: string | null;
+
     /**
      * `daily` is the current UTC day; `monthly` is the current UTC calendar month.
      */
@@ -359,6 +480,13 @@ export declare namespace SpendLimitCreateParams {
 }
 
 export interface SpendLimitDeleteParams {
+  /**
+   * Identifier of one API key as recorded on usage, never the key's secret,
+   * percent-encoded: the request is then about that key's limit. Absent means the
+   * total limit; present but blank is refused.
+   */
+  credential_id?: string;
+
   /**
    * Limit period. Defaults to `daily`; send it explicitly.
    */
@@ -381,6 +509,13 @@ export declare namespace SpendLimitUpdateParams {
      */
     amount: number;
 
+    /**
+     * Query param: Identifier of one API key as recorded on usage, never the key's
+     * secret, percent-encoded: the request is then about that key's limit. Absent
+     * means the total limit; present but blank is refused.
+     */
+    credential_id?: string;
+
     /**
      * Query param: Limit period. Defaults to `daily`; send it explicitly.
      */
@@ -403,6 +538,13 @@ export declare namespace SpendLimitUpdateParams {
      */
     unlimited: true;
 
+    /**
+     * Query param: Identifier of one API key as recorded on usage, never the key's
+     * secret, percent-encoded: the request is then about that key's limit. Absent
+     * means the total limit; present but blank is refused.
+     */
+    credential_id?: string;
+
     /**
      * Query param: Limit period. Defaults to `daily`; send it explicitly.
      */
@@ -418,6 +560,7 @@ export declare namespace SpendLimitUpdateParams {
 export declare namespace SpendLimits {
   export {
     type SpendLimit as SpendLimit,
+    type SpendLimitBlock as SpendLimitBlock,
     type SpendLimitPeriod as SpendLimitPeriod,
     type SpendLimitResponse as SpendLimitResponse,
     type SpendLimitListResponse as SpendLimitListResponse,

package/src/resources/tailscale-subnet-routers.ts

@@ -0,0 +1,303 @@
+// 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 { DefaultFlatPagination, type DefaultFlatPaginationParams, PagePromise } from '../core/pagination';
+import { RequestOptions } from '../internal/request-options';
+import { path } from '../internal/utils/path';
+
+/**
+ * Tailscale Subnet Router operations
+ */
+export class TailscaleSubnetRouters extends APIResource {
+  /**
+   * Returns a paginated list of the Tailscale Subnet Routers on the account, with
+   * support for filtering by Network.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const tailscaleSubnetRouter of client.tailscaleSubnetRouters.list()) {
+   *   // ...
+   * }
+   * ```
+   */
+  list(
+    query: TailscaleSubnetRouterListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<TailscaleSubnetRoutersDefaultFlatPagination, TailscaleSubnetRouter> {
+    return this._client.getAPIList(
+      '/tailscale_subnet_routers',
+      DefaultFlatPagination<TailscaleSubnetRouter>,
+      { query, ...options },
+    );
+  }
+
+  /**
+   * Creates a Tailscale Subnet Router on a Network and enrolls it in the user's
+   * tailnet with the auth key. The response returns the router with `status`
+   * `provisioning`. Poll `GET /tailscale_subnet_routers/{id}` until it is
+   * `provisioned`. Then approve its routes in the tailnet, unless an auto-approver
+   * covers them.
+   *
+   * @example
+   * ```ts
+   * const tailscaleSubnetRouter =
+   *   await client.tailscaleSubnetRouters.create({
+   *     advertised_routes: ['172.27.0.0/24'],
+   *     auth_key: 'tskey-auth-k1AbCdEfGh2IjKlMnOpQrStUv',
+   *     name: 'tailnet-ashburn',
+   *     network_id: '0de011ae-ee53-4df4-ba96-754728eb5aad',
+   *     region_code: 'ashburn-va',
+   *   });
+   * ```
+   */
+  create(
+    body: TailscaleSubnetRouterCreateParams,
+    options?: RequestOptions,
+  ): APIPromise<TailscaleSubnetRouterCreateResponse> {
+    return this._client.post('/tailscale_subnet_routers', { body, ...options });
+  }
+
+  /**
+   * Removes the router from the Network and logs it out of the tailnet. The response
+   * returns the router with `status` `deleting`. The record disappears once removal
+   * completes. A machine entry can remain in the tailnet's admin console until it is
+   * removed there.
+   *
+   * @example
+   * ```ts
+   * const tailscaleSubnetRouter =
+   *   await client.tailscaleSubnetRouters.delete(
+   *     '6a09cdc3-8948-47f0-aa62-74ac943d6c58',
+   *   );
+   * ```
+   */
+  delete(id: string, options?: RequestOptions): APIPromise<TailscaleSubnetRouterDeleteResponse> {
+    return this._client.delete(path`/tailscale_subnet_routers/${id}`, options);
+  }
+
+  /**
+   * Returns the details of a single Tailscale Subnet Router by its identifier,
+   * including its enrollment state.
+   *
+   * @example
+   * ```ts
+   * const tailscaleSubnetRouter =
+   *   await client.tailscaleSubnetRouters.retrieve(
+   *     '6a09cdc3-8948-47f0-aa62-74ac943d6c58',
+   *   );
+   * ```
+   */
+  retrieve(id: string, options?: RequestOptions): APIPromise<TailscaleSubnetRouterRetrieveResponse> {
+    return this._client.get(path`/tailscale_subnet_routers/${id}`, options);
+  }
+
+  /**
+   * Renames the router, changes its advertised routes, or retries a failed
+   * enrollment. Any change queues a new provisioning run and returns the router with
+   * `status` `provisioning`. The router keeps its machine identity on the tailnet.
+   * Send an empty object to retry a `failed` router with its stored auth key.
+   * Include a new `auth_key` only while the router has never enrolled. The router's
+   * Network and region cannot change: create a new router instead.
+   *
+   * @example
+   * ```ts
+   * const tailscaleSubnetRouter =
+   *   await client.tailscaleSubnetRouters.update(
+   *     '6a09cdc3-8948-47f0-aa62-74ac943d6c58',
+   *     {
+   *       advertised_routes: ['172.27.0.0/24', '172.27.1.0/24'],
+   *     },
+   *   );
+   * ```
+   */
+  update(
+    id: string,
+    body: TailscaleSubnetRouterUpdateParams,
+    options?: RequestOptions,
+  ): APIPromise<TailscaleSubnetRouterUpdateResponse> {
+    return this._client.patch(path`/tailscale_subnet_routers/${id}`, { body, ...options });
+  }
+}
+
+export type TailscaleSubnetRoutersDefaultFlatPagination = DefaultFlatPagination<TailscaleSubnetRouter>;
+
+export interface TailscaleSubnetRouter {
+  /**
+   * Identifies the resource.
+   */
+  id?: string;
+
+  /**
+   * IPv4 subnets of the Network that the router advertises to the tailnet. Each
+   * entry is a canonical CIDR that the Network routes. Default, loopback,
+   * link-local, multicast, and Tailscale (`100.64.0.0/10`) ranges are rejected. So
+   * are ranges that overlap the router's own, `172.27.254.0/24` and `198.18.0.0/20`.
+   */
+  advertised_routes?: Array<string>;
+
+  /**
+   * ISO 8601 formatted date-time indicating when the resource was created.
+   */
+  created_at?: string;
+
+  /**
+   * The router's address on the Network, from `172.27.254.0/24`. Tailnet traffic
+   * enters the Network from this address.
+   */
+  customer_address?: string;
+
+  /**
+   * The router's node id on the tailnet. Set once the router has enrolled.
+   */
+  device_id?: string | null;
+
+  /**
+   * A user specified name for the router.
+   */
+  name?: string;
+
+  /**
+   * The id of the Network the router is attached to.
+   */
+  network_id?: string;
+
+  /**
+   * Identifies the type of the resource.
+   */
+  record_type?: string;
+
+  /**
+   * The code of the region the router is created in. `GET /network_coverage` lists
+   * the regions whose `available_services` include `tailscale_subnet_router`.
+   */
+  region_code?: string;
+
+  /**
+   * `provisioning`: Telnyx is creating the router or applying a change.
+   * `provisioned`: the router is on the tailnet and advertises its routes; the
+   * tailnet still approves them. `failed`: enrollment did not complete, and `PATCH`
+   * retries it. `deleting`: the router is being removed.
+   */
+  status?: 'provisioning' | 'provisioned' | 'failed' | 'deleting';
+
+  /**
+   * The name of the tailnet the router is enrolled in. Set once the router has
+   * enrolled.
+   */
+  tailnet_name?: string | null;
+
+  /**
+   * The router's addresses on the tailnet. Empty until the router has enrolled.
+   */
+  tailscale_ips?: Array<string>;
+
+  /**
+   * ISO 8601 formatted date-time indicating when the resource was updated.
+   */
+  updated_at?: string;
+}
+
+export interface TailscaleSubnetRouterCreateResponse {
+  data?: TailscaleSubnetRouter;
+}
+
+export interface TailscaleSubnetRouterRetrieveResponse {
+  data?: TailscaleSubnetRouter;
+}
+
+export interface TailscaleSubnetRouterUpdateResponse {
+  data?: TailscaleSubnetRouter;
+}
+
+export interface TailscaleSubnetRouterDeleteResponse {
+  data?: TailscaleSubnetRouter;
+}
+
+export interface TailscaleSubnetRouterListParams extends DefaultFlatPaginationParams {
+  /**
+   * Consolidated filter parameter (deepObject style). Originally: filter[network_id]
+   */
+  filter?: TailscaleSubnetRouterListParams.Filter;
+}
+
+export namespace TailscaleSubnetRouterListParams {
+  /**
+   * Consolidated filter parameter (deepObject style). Originally: filter[network_id]
+   */
+  export interface Filter {
+    /**
+     * The id of the Network to filter on.
+     */
+    network_id?: string;
+  }
+}
+
+export interface TailscaleSubnetRouterCreateParams {
+  /**
+   * IPv4 subnets of the Network that the router advertises to the tailnet. Each
+   * entry is a canonical CIDR that the Network routes. Default, loopback,
+   * link-local, multicast, and Tailscale (`100.64.0.0/10`) ranges are rejected. So
+   * are ranges that overlap the router's own, `172.27.254.0/24` and `198.18.0.0/20`.
+   */
+  advertised_routes: Array<string>;
+
+  /**
+   * A Tailscale auth key that enrolls the router in the user's tailnet: reusable,
+   * pre-approved, tagged, and not ephemeral. Telnyx stores it encrypted until
+   * enrollment succeeds, then discards it. It is never returned.
+   */
+  auth_key: string;
+
+  /**
+   * A user specified name for the router.
+   */
+  name: string;
+
+  /**
+   * The id of the Network to attach the router to.
+   */
+  network_id: string;
+
+  /**
+   * The code of the region to create the router in. `GET /network_coverage` lists
+   * the regions whose `available_services` include `tailscale_subnet_router`.
+   */
+  region_code: string;
+}
+
+export interface TailscaleSubnetRouterUpdateParams {
+  /**
+   * IPv4 subnets of the Network that the router advertises to the tailnet. Each
+   * entry is a canonical CIDR that the Network routes. Default, loopback,
+   * link-local, multicast, and Tailscale (`100.64.0.0/10`) ranges are rejected. So
+   * are ranges that overlap the router's own, `172.27.254.0/24` and `198.18.0.0/20`.
+   */
+  advertised_routes?: Array<string>;
+
+  /**
+   * A replacement Tailscale auth key. Accepted only while the router has never
+   * enrolled, for example after a `failed` enrollment. Never returned.
+   */
+  auth_key?: string;
+
+  /**
+   * A user specified name for the router.
+   */
+  name?: string;
+}
+
+export declare namespace TailscaleSubnetRouters {
+  export {
+    type TailscaleSubnetRouter as TailscaleSubnetRouter,
+    type TailscaleSubnetRouterCreateResponse as TailscaleSubnetRouterCreateResponse,
+    type TailscaleSubnetRouterRetrieveResponse as TailscaleSubnetRouterRetrieveResponse,
+    type TailscaleSubnetRouterUpdateResponse as TailscaleSubnetRouterUpdateResponse,
+    type TailscaleSubnetRouterDeleteResponse as TailscaleSubnetRouterDeleteResponse,
+    type TailscaleSubnetRoutersDefaultFlatPagination as TailscaleSubnetRoutersDefaultFlatPagination,
+    type TailscaleSubnetRouterListParams as TailscaleSubnetRouterListParams,
+    type TailscaleSubnetRouterCreateParams as TailscaleSubnetRouterCreateParams,
+    type TailscaleSubnetRouterUpdateParams as TailscaleSubnetRouterUpdateParams,
+  };
+}