cloudflare/src/resources/api-gateway/configurations.ts

The official TypeScript library for the Cloudflare API

// 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';

export class BaseConfigurations extends APIResource {
  static override readonly _key: readonly ['apiGateway', 'configurations'] = Object.freeze([
    'apiGateway',
    'configurations',
  ] as const);

  /**
   * Replaces the zone's authentication identifier characteristics used to identify
   * distinct API sessions.
   *
   * @example
   * ```ts
   * const configuration =
   *   await client.apiGateway.configurations.update({
   *     zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
   *     auth_id_characteristics: [
   *       { name: 'authorization', type: 'header' },
   *     ],
   *   });
   * ```
   */
  update(params: ConfigurationUpdateParams, options?: RequestOptions): APIPromise<Configuration> {
    const { zone_id, normalize, ...body } = params;
    return (
      this._client.put(path`/zones/${zone_id}/api_gateway/configuration`, {
        query: { normalize },
        body,
        ...options,
      }) as APIPromise<{ result: Configuration }>
    )._thenUnwrap((obj) => obj.result);
  }

  /**
   * Returns the authentication identifier characteristics configured for the zone.
   * Header, cookie, or JWT claim values identify distinct API sessions.
   *
   * @example
   * ```ts
   * const configuration =
   *   await client.apiGateway.configurations.get({
   *     zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
   *   });
   * ```
   */
  get(params: ConfigurationGetParams, options?: RequestOptions): APIPromise<Configuration> {
    const { zone_id, ...query } = params;
    return (
      this._client.get(path`/zones/${zone_id}/api_gateway/configuration`, {
        query,
        ...options,
      }) as APIPromise<{ result: Configuration }>
    )._thenUnwrap((obj) => obj.result);
  }
}
export class Configurations extends BaseConfigurations {}

export interface Configuration {
  auth_id_characteristics: Array<
    Configuration.APIShieldAuthIDCharacteristic | Configuration.APIShieldAuthIDCharacteristicJWTClaim
  >;
}

export namespace Configuration {
  /**
   * Auth ID Characteristic
   */
  export interface APIShieldAuthIDCharacteristic {
    /**
     * The name of the characteristic field, i.e., the header or cookie name.
     */
    name: string;

    /**
     * The type of characteristic.
     */
    type: 'header' | 'cookie';
  }

  /**
   * Auth ID Characteristic extracted from JWT Token Claims
   */
  export interface APIShieldAuthIDCharacteristicJWTClaim {
    /**
     * Claim location expressed as `$(token_config_id):$(json_path)`, where
     * `token_config_id` is the ID of the token configuration used in validating the
     * JWT, and `json_path` is a RFC 9535 JSONPath
     * (https://goessner.net/articles/JsonPath/,
     * https://www.rfc-editor.org/rfc/rfc9535.html). The JSONPath expression may be in
     * dot or bracket notation, may only specify literal keys or array indexes, and
     * must return a singleton value, which will be interpreted as a string.
     */
    name: string;

    /**
     * The type of characteristic.
     */
    type: 'jwt';
  }
}

export interface ConfigurationUpdateParams {
  /**
   * Path param: Identifier.
   */
  zone_id: string;

  /**
   * Body param
   */
  auth_id_characteristics: Array<
    | ConfigurationUpdateParams.APIShieldAuthIDCharacteristic
    | ConfigurationUpdateParams.APIShieldAuthIDCharacteristicJWTClaim
  >;

  /**
   * Query param: Ensures that the configuration is written or retrieved in
   * normalized fashion
   */
  normalize?: boolean;
}

export namespace ConfigurationUpdateParams {
  /**
   * Auth ID Characteristic
   */
  export interface APIShieldAuthIDCharacteristic {
    /**
     * The name of the characteristic field, i.e., the header or cookie name.
     */
    name: string;

    /**
     * The type of characteristic.
     */
    type: 'header' | 'cookie';
  }

  /**
   * Auth ID Characteristic extracted from JWT Token Claims
   */
  export interface APIShieldAuthIDCharacteristicJWTClaim {
    /**
     * Claim location expressed as `$(token_config_id):$(json_path)`, where
     * `token_config_id` is the ID of the token configuration used in validating the
     * JWT, and `json_path` is a RFC 9535 JSONPath
     * (https://goessner.net/articles/JsonPath/,
     * https://www.rfc-editor.org/rfc/rfc9535.html). The JSONPath expression may be in
     * dot or bracket notation, may only specify literal keys or array indexes, and
     * must return a singleton value, which will be interpreted as a string.
     */
    name: string;

    /**
     * The type of characteristic.
     */
    type: 'jwt';
  }
}

export interface ConfigurationGetParams {
  /**
   * Path param: Identifier.
   */
  zone_id: string;

  /**
   * Query param: Ensures that the configuration is written or retrieved in
   * normalized fashion
   */
  normalize?: boolean;
}

export declare namespace Configurations {
  export {
    type Configuration as Configuration,
    type ConfigurationUpdateParams as ConfigurationUpdateParams,
    type ConfigurationGetParams as ConfigurationGetParams,
  };
}