cloudflare/src/resources/addressing/prefixes/service-bindings.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 { PagePromise, SinglePage } from '../../../core/pagination';
import { RequestOptions } from '../../../internal/request-options';
import { path } from '../../../internal/utils/path';

export class BaseServiceBindings extends APIResource {
  static override readonly _key: readonly ['addressing', 'prefixes', 'serviceBindings'] = Object.freeze([
    'addressing',
    'prefixes',
    'serviceBindings',
  ] as const);

  /**
   * Creates a new Service Binding, routing traffic to IPs within the given CIDR to a
   * service running on Cloudflare's network. **NOTE:** The first Service Binding
   * created for an IP Prefix must exactly match the IP Prefix's CIDR. Subsequent
   * Service Bindings may be created with a more-specific CIDR. Refer to the
   * [Service Bindings Documentation](https://developers.cloudflare.com/byoip/service-bindings/)
   * for compatibility details.
   *
   * @example
   * ```ts
   * const serviceBinding =
   *   await client.addressing.prefixes.serviceBindings.create(
   *     '2af39739cc4e3b5910c918468bb89828',
   *     {
   *       account_id: '258def64c72dae45f3e4c8516e2111f2',
   *       cidr: '192.0.2.0/24',
   *       service_id: '2db684ee7ca04e159946fd05b99e1bcd',
   *     },
   *   );
   * ```
   */
  create(
    prefixID: string,
    params: ServiceBindingCreateParams,
    options?: RequestOptions,
  ): APIPromise<ServiceBinding> {
    const { account_id, ...body } = params;
    return (
      this._client.post(path`/accounts/${account_id}/addressing/prefixes/${prefixID}/bindings`, {
        body,
        ...options,
      }) as APIPromise<{ result: ServiceBinding }>
    )._thenUnwrap((obj) => obj.result);
  }

  /**
   * List the Cloudflare services this prefix is currently bound to. Traffic sent to
   * an address within an IP prefix will be routed to the Cloudflare service of the
   * most-specific Service Binding matching the address. **Example:** binding
   * `192.0.2.0/24` to Cloudflare Magic Transit and `192.0.2.1/32` to the Cloudflare
   * CDN would route traffic for `192.0.2.1` to the CDN, and traffic for all other
   * IPs in the prefix to Cloudflare Magic Transit.
   *
   * @example
   * ```ts
   * // Automatically fetches more pages as needed.
   * for await (const serviceBinding of client.addressing.prefixes.serviceBindings.list(
   *   '2af39739cc4e3b5910c918468bb89828',
   *   { account_id: '258def64c72dae45f3e4c8516e2111f2' },
   * )) {
   *   // ...
   * }
   * ```
   */
  list(
    prefixID: string,
    params: ServiceBindingListParams,
    options?: RequestOptions,
  ): PagePromise<ServiceBindingsSinglePage, ServiceBinding> {
    const { account_id } = params;
    return this._client.getAPIList(
      path`/accounts/${account_id}/addressing/prefixes/${prefixID}/bindings`,
      SinglePage<ServiceBinding>,
      options,
    );
  }

  /**
   * Delete a Service Binding
   *
   * @example
   * ```ts
   * const serviceBinding =
   *   await client.addressing.prefixes.serviceBindings.delete(
   *     '0429b49b6a5155297b78e75a44b09e14',
   *     {
   *       account_id: '258def64c72dae45f3e4c8516e2111f2',
   *       prefix_id: '2af39739cc4e3b5910c918468bb89828',
   *     },
   *   );
   * ```
   */
  delete(
    bindingID: string,
    params: ServiceBindingDeleteParams,
    options?: RequestOptions,
  ): APIPromise<ServiceBindingDeleteResponse> {
    const { account_id, prefix_id } = params;
    return this._client.delete(
      path`/accounts/${account_id}/addressing/prefixes/${prefix_id}/bindings/${bindingID}`,
      options,
    );
  }

  /**
   * Fetch a single Service Binding
   *
   * @example
   * ```ts
   * const serviceBinding =
   *   await client.addressing.prefixes.serviceBindings.get(
   *     '0429b49b6a5155297b78e75a44b09e14',
   *     {
   *       account_id: '258def64c72dae45f3e4c8516e2111f2',
   *       prefix_id: '2af39739cc4e3b5910c918468bb89828',
   *     },
   *   );
   * ```
   */
  get(
    bindingID: string,
    params: ServiceBindingGetParams,
    options?: RequestOptions,
  ): APIPromise<ServiceBinding> {
    const { account_id, prefix_id } = params;
    return (
      this._client.get(
        path`/accounts/${account_id}/addressing/prefixes/${prefix_id}/bindings/${bindingID}`,
        options,
      ) as APIPromise<{ result: ServiceBinding }>
    )._thenUnwrap((obj) => obj.result);
  }
}
export class ServiceBindings extends BaseServiceBindings {}

export type ServiceBindingsSinglePage = SinglePage<ServiceBinding>;

export interface ServiceBinding {
  /**
   * Identifier of a Service Binding.
   */
  id?: string;

  /**
   * IP Prefix in Classless Inter-Domain Routing format.
   */
  cidr?: string;

  /**
   * Status of a Service Binding's deployment to the Cloudflare network
   */
  provisioning?: ServiceBinding.Provisioning;

  /**
   * Identifier of a Service on the Cloudflare network. Available services and their
   * IDs may be found in the **List Services** endpoint.
   */
  service_id?: string;

  /**
   * Name of a service running on the Cloudflare network
   */
  service_name?: string;
}

export namespace ServiceBinding {
  /**
   * Status of a Service Binding's deployment to the Cloudflare network
   */
  export interface Provisioning {
    /**
     * When a binding has been deployed to a majority of Cloudflare datacenters, the
     * binding will become active and can be used with its associated service.
     */
    state?: 'provisioning' | 'active' | 'magic_transit_route_missing';
  }
}

export interface ServiceBindingDeleteResponse {
  errors: Array<ServiceBindingDeleteResponse.Error>;

  messages: Array<ServiceBindingDeleteResponse.Message>;

  /**
   * Whether the API call was successful.
   */
  success: true;
}

export namespace ServiceBindingDeleteResponse {
  export interface Error {
    code: number;

    message: string;

    documentation_url?: string;

    source?: Error.Source;
  }

  export namespace Error {
    export interface Source {
      pointer?: string;
    }
  }

  export interface Message {
    code: number;

    message: string;

    documentation_url?: string;

    source?: Message.Source;
  }

  export namespace Message {
    export interface Source {
      pointer?: string;
    }
  }
}

export interface ServiceBindingCreateParams {
  /**
   * Path param: Identifier of a Cloudflare account.
   */
  account_id: string;

  /**
   * Body param: IP Prefix in Classless Inter-Domain Routing format.
   */
  cidr: string;

  /**
   * Body param: Identifier of a Service on the Cloudflare network. Available
   * services and their IDs may be found in the **List Services** endpoint.
   */
  service_id: string;
}

export interface ServiceBindingListParams {
  /**
   * Identifier of a Cloudflare account.
   */
  account_id: string;
}

export interface ServiceBindingDeleteParams {
  /**
   * Identifier of a Cloudflare account.
   */
  account_id: string;

  /**
   * Identifier of an IP Prefix.
   */
  prefix_id: string;
}

export interface ServiceBindingGetParams {
  /**
   * Identifier of a Cloudflare account.
   */
  account_id: string;

  /**
   * Identifier of an IP Prefix.
   */
  prefix_id: string;
}

export declare namespace ServiceBindings {
  export {
    type ServiceBinding as ServiceBinding,
    type ServiceBindingDeleteResponse as ServiceBindingDeleteResponse,
    type ServiceBindingsSinglePage as ServiceBindingsSinglePage,
    type ServiceBindingCreateParams as ServiceBindingCreateParams,
    type ServiceBindingListParams as ServiceBindingListParams,
    type ServiceBindingDeleteParams as ServiceBindingDeleteParams,
    type ServiceBindingGetParams as ServiceBindingGetParams,
  };
}