cloudflare
Version:
The official TypeScript library for the Cloudflare API
622 lines (559 loc) • 18.1 kB
text/typescript
// 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, V4PagePaginationArray, type V4PagePaginationArrayParams } from '../../core/pagination';
import { RequestOptions } from '../../internal/request-options';
import { path } from '../../internal/utils/path';
export class BaseOriginCloudRegions extends APIResource {
static override readonly _key: readonly ['cache', 'originCloudRegions'] = Object.freeze([
'cache',
'originCloudRegions',
] as const);
/**
* Creates a new IP-to-cloud-region mapping or replaces the existing mapping for
* the specified IP. PUT is idempotent — calling it repeatedly with the same body
* produces the same result. The IP path parameter is normalized to canonical form
* (RFC 5952 for IPv6) before storage. The vendor and region are validated against
* the list from `GET /zones/{zone_id}/origin/cloud_regions/supported_regions`.
* Returns 400 if the `origin_ip` in the body does not match the URL path
* parameter. Returns 403 (code 1164) when the zone has reached the limit of 3,500
* IP mappings.
*
* @example
* ```ts
* const originCloudRegion =
* await client.cache.originCloudRegions.update(
* '192.0.2.1',
* {
* zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
* origin_ip: '192.0.2.1',
* region: 'us-east-1',
* vendor: 'aws',
* },
* );
* ```
*/
update(
originIP: string,
params: OriginCloudRegionUpdateParams,
options?: RequestOptions,
): APIPromise<OriginCloudRegionUpdateResponse> {
const { zone_id, ...body } = params;
return (
this._client.put(path`/zones/${zone_id}/origin/cloud_regions/${originIP}`, {
body,
...options,
}) as APIPromise<{ result: OriginCloudRegionUpdateResponse }>
)._thenUnwrap((obj) => obj.result);
}
/**
* Returns all IP-to-cloud-region mappings configured for the zone with pagination
* support. Each mapping tells Cloudflare which cloud vendor and region hosts the
* origin at that IP, enabling the edge to route via the nearest Tiered Cache
* upper-tier co-located with that cloud provider. Returns an empty array when no
* mappings exist.
*
* @example
* ```ts
* // Automatically fetches more pages as needed.
* for await (const originCloudRegionListResponse of client.cache.originCloudRegions.list(
* { zone_id: '023e105f4ecef8ad9ca31a8372d0c353' },
* )) {
* // ...
* }
* ```
*/
list(
params: OriginCloudRegionListParams,
options?: RequestOptions,
): PagePromise<OriginCloudRegionListResponsesV4PagePaginationArray, OriginCloudRegionListResponse> {
const { zone_id, ...query } = params;
return this._client.getAPIList(
path`/zones/${zone_id}/origin/cloud_regions`,
V4PagePaginationArray<OriginCloudRegionListResponse>,
{ query, ...options },
);
}
/**
* Removes the cloud region mapping for a single origin IP address. The IP path
* parameter is normalized before lookup. Returns the deleted IP on success.
* Returns 404 if no mapping exists for the specified IP. When the last mapping for
* the zone is removed the underlying rule record is also deleted.
*
* @example
* ```ts
* const originCloudRegion =
* await client.cache.originCloudRegions.delete(
* '192.0.2.1',
* { zone_id: '023e105f4ecef8ad9ca31a8372d0c353' },
* );
* ```
*/
delete(
originIP: string,
params: OriginCloudRegionDeleteParams,
options?: RequestOptions,
): APIPromise<OriginCloudRegionDeleteResponse> {
const { zone_id } = params;
return (
this._client.delete(path`/zones/${zone_id}/origin/cloud_regions/${originIP}`, options) as APIPromise<{
result: OriginCloudRegionDeleteResponse;
}>
)._thenUnwrap((obj) => obj.result);
}
/**
* Removes up to 100 IP-to-cloud-region mappings in a single request. Each IP is
* validated independently — successfully deleted items are returned in the
* `succeeded` array and IPs that could not be found or are invalid are returned in
* the `failed` array.
*
* @example
* ```ts
* const response =
* await client.cache.originCloudRegions.bulkDelete({
* zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
* });
* ```
*/
bulkDelete(
params: OriginCloudRegionBulkDeleteParams,
options?: RequestOptions,
): APIPromise<OriginCloudRegionBulkDeleteResponse> {
const { zone_id } = params;
return (
this._client.delete(path`/zones/${zone_id}/origin/cloud_regions/batch`, options) as APIPromise<{
result: OriginCloudRegionBulkDeleteResponse;
}>
)._thenUnwrap((obj) => obj.result);
}
/**
* Upserts up to 100 IP-to-cloud-region mappings in a single request. Items in the
* request body are created or replaced; mappings not included in the request body
* are preserved unchanged (this is a merge operation, not a full collection
* replacement). Each item is validated independently — valid items are applied and
* invalid items are returned in the `failed` array. The vendor and region for
* every item are validated against the list from
* `GET /zones/{zone_id}/origin/cloud_regions/supported_regions`.
*
* @example
* ```ts
* const response =
* await client.cache.originCloudRegions.bulkUpdate({
* zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
* body: [
* {
* origin_ip: '192.0.2.1',
* region: 'us-east-1',
* vendor: 'aws',
* },
* {
* origin_ip: '2001:db8::1',
* region: 'us-central1',
* vendor: 'gcp',
* },
* ],
* });
* ```
*/
bulkUpdate(
params: OriginCloudRegionBulkUpdateParams,
options?: RequestOptions,
): APIPromise<OriginCloudRegionBulkUpdateResponse> {
const { zone_id, body } = params;
return (
this._client.put(path`/zones/${zone_id}/origin/cloud_regions/batch`, {
body: body,
...options,
}) as APIPromise<{ result: OriginCloudRegionBulkUpdateResponse }>
)._thenUnwrap((obj) => obj.result);
}
/**
* Returns the cloud region mapping for a single origin IP address. The IP path
* parameter is normalized before lookup (RFC 5952 for IPv6). Returns 404 if the
* zone has no mappings or if the specified IP has no mapping.
*
* @example
* ```ts
* const originCloudRegion =
* await client.cache.originCloudRegions.get('192.0.2.1', {
* zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
* });
* ```
*/
get(
originIP: string,
params: OriginCloudRegionGetParams,
options?: RequestOptions,
): APIPromise<OriginCloudRegionGetResponse> {
const { zone_id } = params;
return (
this._client.get(path`/zones/${zone_id}/origin/cloud_regions/${originIP}`, options) as APIPromise<{
result: OriginCloudRegionGetResponse;
}>
)._thenUnwrap((obj) => obj.result);
}
/**
* Returns the cloud vendors and regions that are valid values for origin cloud
* region mappings. Each region includes the Tiered Cache upper-tier colocation
* codes that will be used for cache routing when a mapping targeting that region
* is active. Requires the zone to have Tiered Cache enabled.
*
* @example
* ```ts
* const response =
* await client.cache.originCloudRegions.supportedRegions({
* zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
* });
* ```
*/
supportedRegions(
params: OriginCloudRegionSupportedRegionsParams,
options?: RequestOptions,
): APIPromise<OriginCloudRegionSupportedRegionsResponse> {
const { zone_id } = params;
return (
this._client.get(
path`/zones/${zone_id}/origin/cloud_regions/supported_regions`,
options,
) as APIPromise<{ result: OriginCloudRegionSupportedRegionsResponse }>
)._thenUnwrap((obj) => obj.result);
}
}
export class OriginCloudRegions extends BaseOriginCloudRegions {}
export type OriginCloudRegionListResponsesV4PagePaginationArray =
V4PagePaginationArray<OriginCloudRegionListResponse>;
/**
* A single origin IP-to-cloud-region mapping.
*/
export interface OriginCloudRegionUpdateResponse {
/**
* The origin IP address (IPv4 or IPv6). Normalized to canonical form (RFC 5952 for
* IPv6).
*/
origin_ip: string;
/**
* Cloud vendor region identifier.
*/
region: string;
/**
* Cloud vendor hosting the origin.
*/
vendor: 'aws' | 'azure' | 'gcp' | 'oci';
/**
* Time this mapping was last modified.
*/
modified_on?: string;
}
/**
* A single origin IP-to-cloud-region mapping.
*/
export interface OriginCloudRegionListResponse {
/**
* The origin IP address (IPv4 or IPv6). Normalized to canonical form (RFC 5952 for
* IPv6).
*/
origin_ip: string;
/**
* Cloud vendor region identifier.
*/
region: string;
/**
* Cloud vendor hosting the origin.
*/
vendor: 'aws' | 'azure' | 'gcp' | 'oci';
/**
* Time this mapping was last modified.
*/
modified_on?: string;
}
/**
* Response result for a delete operation. Identifies the deleted mapping.
*/
export interface OriginCloudRegionDeleteResponse {
/**
* The origin IP address whose mapping was deleted.
*/
origin_ip: string;
}
/**
* Response result for a batch origin cloud region operation.
*/
export interface OriginCloudRegionBulkDeleteResponse {
/**
* Items that could not be applied, with error details.
*/
failed: Array<OriginCloudRegionBulkDeleteResponse.Failed>;
/**
* Items that were successfully applied.
*/
succeeded: Array<OriginCloudRegionBulkDeleteResponse.Succeeded>;
}
export namespace OriginCloudRegionBulkDeleteResponse {
/**
* Result for a single item in a batch operation.
*/
export interface Failed {
/**
* The origin IP address for this item.
*/
origin_ip: string;
/**
* Error message explaining why the item failed. Present only on failed items.
*/
error?: string;
/**
* Cloud vendor region identifier. Present on succeeded items (the new value for
* upsert, the deleted value for delete).
*/
region?: string;
/**
* Cloud vendor identifier. Present on succeeded items (the new value for upsert,
* the deleted value for delete).
*/
vendor?: string;
}
/**
* Result for a single item in a batch operation.
*/
export interface Succeeded {
/**
* The origin IP address for this item.
*/
origin_ip: string;
/**
* Error message explaining why the item failed. Present only on failed items.
*/
error?: string;
/**
* Cloud vendor region identifier. Present on succeeded items (the new value for
* upsert, the deleted value for delete).
*/
region?: string;
/**
* Cloud vendor identifier. Present on succeeded items (the new value for upsert,
* the deleted value for delete).
*/
vendor?: string;
}
}
/**
* Response result for a batch origin cloud region operation.
*/
export interface OriginCloudRegionBulkUpdateResponse {
/**
* Items that could not be applied, with error details.
*/
failed: Array<OriginCloudRegionBulkUpdateResponse.Failed>;
/**
* Items that were successfully applied.
*/
succeeded: Array<OriginCloudRegionBulkUpdateResponse.Succeeded>;
}
export namespace OriginCloudRegionBulkUpdateResponse {
/**
* Result for a single item in a batch operation.
*/
export interface Failed {
/**
* The origin IP address for this item.
*/
origin_ip: string;
/**
* Error message explaining why the item failed. Present only on failed items.
*/
error?: string;
/**
* Cloud vendor region identifier. Present on succeeded items (the new value for
* upsert, the deleted value for delete).
*/
region?: string;
/**
* Cloud vendor identifier. Present on succeeded items (the new value for upsert,
* the deleted value for delete).
*/
vendor?: string;
}
/**
* Result for a single item in a batch operation.
*/
export interface Succeeded {
/**
* The origin IP address for this item.
*/
origin_ip: string;
/**
* Error message explaining why the item failed. Present only on failed items.
*/
error?: string;
/**
* Cloud vendor region identifier. Present on succeeded items (the new value for
* upsert, the deleted value for delete).
*/
region?: string;
/**
* Cloud vendor identifier. Present on succeeded items (the new value for upsert,
* the deleted value for delete).
*/
vendor?: string;
}
}
/**
* A single origin IP-to-cloud-region mapping.
*/
export interface OriginCloudRegionGetResponse {
/**
* The origin IP address (IPv4 or IPv6). Normalized to canonical form (RFC 5952 for
* IPv6).
*/
origin_ip: string;
/**
* Cloud vendor region identifier.
*/
region: string;
/**
* Cloud vendor hosting the origin.
*/
vendor: 'aws' | 'azure' | 'gcp' | 'oci';
/**
* Time this mapping was last modified.
*/
modified_on?: string;
}
/**
* Cloud vendors and their supported regions for origin cloud region mappings.
*/
export interface OriginCloudRegionSupportedRegionsResponse {
/**
* Whether Cloudflare airport codes (IATA colo identifiers) were successfully
* resolved for the `upper_tier_colos` field on each region. When `false`, the
* `upper_tier_colos` arrays may be empty or incomplete.
*/
obtained_codes: boolean;
/**
* Map of vendor name to list of supported regions.
*/
vendors: { [key: string]: Array<OriginCloudRegionSupportedRegionsResponse.Vendor> };
}
export namespace OriginCloudRegionSupportedRegionsResponse {
/**
* A single supported cloud region with associated Tiered Cache upper-tier
* colocations.
*/
export interface Vendor {
/**
* Cloud vendor region identifier.
*/
name: string;
/**
* Cloudflare Tiered Cache upper-tier colocation codes co-located with this cloud
* region. Requests from zones with a matching origin mapping will be routed
* through these colos.
*/
upper_tier_colos: Array<string>;
}
}
export interface OriginCloudRegionUpdateParams {
/**
* Path param: Identifier.
*/
zone_id: string;
/**
* Body param: Origin IP address (IPv4 or IPv6). For the single PUT endpoint
* (`PUT /origin/cloud_regions/{origin_ip}`), this field must match the path
* parameter or the request will be rejected with a 400 error. For the batch PUT
* endpoint, this field identifies which mapping to upsert.
*/
origin_ip: string;
/**
* Body param: Cloud vendor region identifier. Must be a valid region for the
* specified vendor as returned by the supported_regions endpoint.
*/
region: string;
/**
* Body param: Cloud vendor hosting the origin. Must be one of the supported
* vendors.
*/
vendor: 'aws' | 'azure' | 'gcp' | 'oci';
}
export interface OriginCloudRegionListParams extends V4PagePaginationArrayParams {
/**
* Path param: Identifier.
*/
zone_id: string;
}
export interface OriginCloudRegionDeleteParams {
/**
* Identifier.
*/
zone_id: string;
}
export interface OriginCloudRegionBulkDeleteParams {
/**
* Identifier.
*/
zone_id: string;
}
export interface OriginCloudRegionBulkUpdateParams {
/**
* Path param: Identifier.
*/
zone_id: string;
/**
* Body param
*/
body: Array<OriginCloudRegionBulkUpdateParams.Body>;
}
export namespace OriginCloudRegionBulkUpdateParams {
/**
* Request body for creating or replacing an origin cloud region mapping.
*/
export interface Body {
/**
* Origin IP address (IPv4 or IPv6). For the single PUT endpoint
* (`PUT /origin/cloud_regions/{origin_ip}`), this field must match the path
* parameter or the request will be rejected with a 400 error. For the batch PUT
* endpoint, this field identifies which mapping to upsert.
*/
origin_ip: string;
/**
* Cloud vendor region identifier. Must be a valid region for the specified vendor
* as returned by the supported_regions endpoint.
*/
region: string;
/**
* Cloud vendor hosting the origin. Must be one of the supported vendors.
*/
vendor: 'aws' | 'azure' | 'gcp' | 'oci';
}
}
export interface OriginCloudRegionGetParams {
/**
* Identifier.
*/
zone_id: string;
}
export interface OriginCloudRegionSupportedRegionsParams {
/**
* Identifier.
*/
zone_id: string;
}
export declare namespace OriginCloudRegions {
export {
type OriginCloudRegionUpdateResponse as OriginCloudRegionUpdateResponse,
type OriginCloudRegionListResponse as OriginCloudRegionListResponse,
type OriginCloudRegionDeleteResponse as OriginCloudRegionDeleteResponse,
type OriginCloudRegionBulkDeleteResponse as OriginCloudRegionBulkDeleteResponse,
type OriginCloudRegionBulkUpdateResponse as OriginCloudRegionBulkUpdateResponse,
type OriginCloudRegionGetResponse as OriginCloudRegionGetResponse,
type OriginCloudRegionSupportedRegionsResponse as OriginCloudRegionSupportedRegionsResponse,
type OriginCloudRegionListResponsesV4PagePaginationArray as OriginCloudRegionListResponsesV4PagePaginationArray,
type OriginCloudRegionUpdateParams as OriginCloudRegionUpdateParams,
type OriginCloudRegionListParams as OriginCloudRegionListParams,
type OriginCloudRegionDeleteParams as OriginCloudRegionDeleteParams,
type OriginCloudRegionBulkDeleteParams as OriginCloudRegionBulkDeleteParams,
type OriginCloudRegionBulkUpdateParams as OriginCloudRegionBulkUpdateParams,
type OriginCloudRegionGetParams as OriginCloudRegionGetParams,
type OriginCloudRegionSupportedRegionsParams as OriginCloudRegionSupportedRegionsParams,
};
}