cloudflare
Version:
The official TypeScript library for the Cloudflare API
580 lines • 29.6 kB
JavaScript
// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
import { APIResource } from "../../core/resource.mjs";
import * as ExtensionsAPI from "./extensions.mjs";
import { BaseExtensions, Extensions, } from "./extensions.mjs";
import * as RegistrationStatusAPI from "./registration-status.mjs";
import { BaseRegistrationStatus, RegistrationStatus, } from "./registration-status.mjs";
import * as RegistrationsAPI from "./registrations.mjs";
import { BaseRegistrations, Registrations, } from "./registrations.mjs";
import * as UpdateStatusAPI from "./update-status.mjs";
import { BaseUpdateStatus, UpdateStatus, } from "./update-status.mjs";
import { path } from "../../internal/utils/path.mjs";
/**
* Use the Registrar Sandbox API to test domain search, availability checks,
* registration, and domain management flows without buying real domains.
*
* **This API is a test environment for the production Registrar API.**
*
* ## Prerequisites
*
* Before using this API, make sure you have:
*
* 1. **Cloudflare account** — the caller must have a valid Cloudflare account.
* 2. **API authentication** — create an API token with Registrar Sandbox permissions.
*
* ## How the Sandbox API differs from the production Registrar API
*
* Because the Sandbox API is intended for testing, it behaves differently from
* the production Registrar API in a few important ways:
*
* 1. **No billing** — you will not be charged real money for purchasing a domain.
* 2. **No real domains** — purchased domains are test records and will not be
* reachable on the Internet.
* 3. **No DNS zones** — purchasing a domain does not create a zone resource.
* 4. **No Registration Express Mode** — you must provide full contact data.
*
* Sandbox purchases are still persisted. If you purchase a domain in the sandbox,
* that domain will not be available for others to purchase in the sandbox.
*
* ## Terminology: domain extension
*
* Throughout this API, "extension" refers to the domain extension part of a fully
* qualified domain name — the portion after the registrable label. For example,
* in `example.co.uk`, the extension is `co.uk` (not just `uk`). This covers both
* top-level domains like `com` and multi-level extensions like `co.uk`. This is
* distinct from other uses of the word "extension" (e.g., EPP extensions).
*
* ## Supported extensions
*
* The Sandbox API currently supports programmatic registration for these
* extensions:
*
* `com`, `net`
*
* The production Registrar API supports 40+ extensions.
*
* Cloudflare Registrar supports 400+ extensions in the dashboard. Extensions
* not listed above can be registered at `https://dash.cloudflare.com/{account_id}/domains/registrations`.
*
* ## Typical workflow
*
* 1. **Search** — call `GET /domain-search?q={keyword}` to discover available domains.
* 2. **Check** — call `POST /domain-check` with candidate domains to verify real-time
* availability and pricing.
* 3. **Review the response** — if `registrable: false`, inspect `reason` to
* understand whether the domain is unavailable, the extension is not supported
* by this API, the extension is not supported by Cloudflare Registrar at all,
* or the extension's registry has frozen new registrations.
* 4. **Handle premium domains** — if `tier: premium`, premium registration is
* not currently supported by this API. The Sandbox API currently supports
* only `com` and `net`, which do not have premium registrations, but clients
* should still handle this response for consistency with the production
* Registrar API. Surface the premium pricing to the user, but do not proceed
* to `POST /registrations` for that domain.
* 5. **Observe the registration schema** — call `GET /extensions/:extension_name`
* to discover the required values for registering this extension.
* 6. **Register** — call `POST /registrations` with the chosen domain name for
* supported non-premium registrations.
* 7. **Confirm completion** — if the response is `201 Created`, registration
* completed within the default timeout and no polling is needed.
* 8. **Poll when needed** — if the response is `202 Accepted`, poll
* `links.self` from the workflow response.
* 9. **Stop for user action** — if `state: action_required`, stop polling and
* surface `context.action` to the user.
* The workflow will not resolve on its own.
* 10. **Continue when blocked** — if `state: blocked`, continue polling and
* inform the user that a third party, such as the extension registry or losing
* registrar, is delaying progress.
* 11. **Review failures before retrying** — if `state: failed`, review
* `error.code` and `error.message`, then decide whether user action or a new
* Check call is needed.
*
* ## Default behavior for mutating operations
*
* By default, mutating operations such as create and update hold the connection
* for a bounded, server-defined amount of time while the operation completes.
* In most cases, the response contains a completed workflow status and no
* polling is required.
*
* - **Completed within the synchronous wait window:** Returns `201` (create)
* or `200` (update) with a `workflow_status` where `state: succeeded` and
* `completed: true`.
* - **Still processing after the synchronous wait window:** Returns
* `202 Accepted` with a `workflow_status` where `completed: false`. Use
* the `links.self` URL to poll for completion.
*
* ## Non-blocking mode
*
* To receive an immediate `202 Accepted` response without waiting, send the
* `Prefer: respond-async` request header (RFC 7240). The server will acknowledge
* it with a `Preference-Applied: respond-async` response header.
*
* ## Polling
*
* When the response is `202`, poll the workflow status endpoint indicated by
* `links.self` in the response body until the workflow reaches a terminal
* state or requires user action.
*/
export var BaseRegistrarSandbox = /* @__PURE__ */ (() => {
/**
* Use the Registrar Sandbox API to test domain search, availability checks,
* registration, and domain management flows without buying real domains.
*
* **This API is a test environment for the production Registrar API.**
*
* ## Prerequisites
*
* Before using this API, make sure you have:
*
* 1. **Cloudflare account** — the caller must have a valid Cloudflare account.
* 2. **API authentication** — create an API token with Registrar Sandbox permissions.
*
* ## How the Sandbox API differs from the production Registrar API
*
* Because the Sandbox API is intended for testing, it behaves differently from
* the production Registrar API in a few important ways:
*
* 1. **No billing** — you will not be charged real money for purchasing a domain.
* 2. **No real domains** — purchased domains are test records and will not be
* reachable on the Internet.
* 3. **No DNS zones** — purchasing a domain does not create a zone resource.
* 4. **No Registration Express Mode** — you must provide full contact data.
*
* Sandbox purchases are still persisted. If you purchase a domain in the sandbox,
* that domain will not be available for others to purchase in the sandbox.
*
* ## Terminology: domain extension
*
* Throughout this API, "extension" refers to the domain extension part of a fully
* qualified domain name — the portion after the registrable label. For example,
* in `example.co.uk`, the extension is `co.uk` (not just `uk`). This covers both
* top-level domains like `com` and multi-level extensions like `co.uk`. This is
* distinct from other uses of the word "extension" (e.g., EPP extensions).
*
* ## Supported extensions
*
* The Sandbox API currently supports programmatic registration for these
* extensions:
*
* `com`, `net`
*
* The production Registrar API supports 40+ extensions.
*
* Cloudflare Registrar supports 400+ extensions in the dashboard. Extensions
* not listed above can be registered at `https://dash.cloudflare.com/{account_id}/domains/registrations`.
*
* ## Typical workflow
*
* 1. **Search** — call `GET /domain-search?q={keyword}` to discover available domains.
* 2. **Check** — call `POST /domain-check` with candidate domains to verify real-time
* availability and pricing.
* 3. **Review the response** — if `registrable: false`, inspect `reason` to
* understand whether the domain is unavailable, the extension is not supported
* by this API, the extension is not supported by Cloudflare Registrar at all,
* or the extension's registry has frozen new registrations.
* 4. **Handle premium domains** — if `tier: premium`, premium registration is
* not currently supported by this API. The Sandbox API currently supports
* only `com` and `net`, which do not have premium registrations, but clients
* should still handle this response for consistency with the production
* Registrar API. Surface the premium pricing to the user, but do not proceed
* to `POST /registrations` for that domain.
* 5. **Observe the registration schema** — call `GET /extensions/:extension_name`
* to discover the required values for registering this extension.
* 6. **Register** — call `POST /registrations` with the chosen domain name for
* supported non-premium registrations.
* 7. **Confirm completion** — if the response is `201 Created`, registration
* completed within the default timeout and no polling is needed.
* 8. **Poll when needed** — if the response is `202 Accepted`, poll
* `links.self` from the workflow response.
* 9. **Stop for user action** — if `state: action_required`, stop polling and
* surface `context.action` to the user.
* The workflow will not resolve on its own.
* 10. **Continue when blocked** — if `state: blocked`, continue polling and
* inform the user that a third party, such as the extension registry or losing
* registrar, is delaying progress.
* 11. **Review failures before retrying** — if `state: failed`, review
* `error.code` and `error.message`, then decide whether user action or a new
* Check call is needed.
*
* ## Default behavior for mutating operations
*
* By default, mutating operations such as create and update hold the connection
* for a bounded, server-defined amount of time while the operation completes.
* In most cases, the response contains a completed workflow status and no
* polling is required.
*
* - **Completed within the synchronous wait window:** Returns `201` (create)
* or `200` (update) with a `workflow_status` where `state: succeeded` and
* `completed: true`.
* - **Still processing after the synchronous wait window:** Returns
* `202 Accepted` with a `workflow_status` where `completed: false`. Use
* the `links.self` URL to poll for completion.
*
* ## Non-blocking mode
*
* To receive an immediate `202 Accepted` response without waiting, send the
* `Prefer: respond-async` request header (RFC 7240). The server will acknowledge
* it with a `Preference-Applied: respond-async` response header.
*
* ## Polling
*
* When the response is `202`, poll the workflow status endpoint indicated by
* `links.self` in the response body until the workflow reaches a terminal
* state or requires user action.
*/
class BaseRegistrarSandbox extends APIResource {
/**
* Performs real-time, authoritative availability checks directly against domain
* registries. Use this endpoint to verify a domain is available before attempting
* registration via `POST /registrations`.
*
* **Important:** Unlike the Search endpoint, these results are authoritative and
* reflect current registry status. Always check availability immediately before
* registration as domain status can change rapidly.
*
* **Note:** This endpoint uses POST to accept a list of domains in the request
* body. It is a read-only operation — it does not create, modify, or reserve any
* domains.
*
* ### Extension support
*
* Only domains on extensions supported for programmatic registration by this API
* can be registered. If you check a domain on an unsupported extension, the
* response will include `registrable: false` with a `reason` field explaining why:
*
* - `extension_not_supported_via_api` — Cloudflare Registrar supports this
* extension in the dashboard, but it is not yet available for programmatic
* registration via this API. Register via
* `https://dash.cloudflare.com/{account_id}/domains/registrations` instead.
* - `extension_not_supported` — This extension is not supported by Cloudflare
* Registrar.
* - `extension_disallows_registration` — The extension's registry has temporarily
* or permanently frozen new registrations. No registrar can register domains on
* this extension at this time.
* - `domain_premium` — The domain is premium priced. Premium registration is not
* currently supported by this API.
* - `domain_unavailable` — The domain is already registered, reserved, or
* otherwise not available for registration on a supported extension.
*
* The `reason` field is only present when `registrable` is `false`.
*
* ### Behavior
*
* - Maximum 20 domains per request
* - Pricing is only returned for domains where `registrable: true`
* - Results are not cached; each request queries the registry
*
* ### Workflow
*
* 1. Call this endpoint with domains the user wants to register.
* 2. For each domain where `registrable: true`, present pricing to the user.
* 3. If `tier: premium`, note that premium registration is not currently supported
* by this API and do not proceed to `POST /registrations`.
* 4. Proceed to `POST /registrations` only for supported non-premium domains.
*
* @example
* ```ts
* const response = await client.registrarSandbox.check({
* account_id: '023e105f4ecef8ad9ca31a8372d0c353',
* domains: [
* 'myawesomebrand.com',
* 'myawesomebrand.net',
* 'myawesomebrand.org',
* 'myawesomebrand.app',
* 'myawesomebrand.dev',
* ],
* });
* ```
*/
check(params, options) {
const { account_id, ...body } = params;
return this._client.post(path `/accounts/${account_id}/registrar-sandbox/domain-check`, {
body,
...options,
})._thenUnwrap((obj) => obj.result);
}
/**
* Searches for domain name suggestions based on a keyword, phrase, or partial
* domain name. Returns a list of potentially available domains with pricing
* information.
*
* **Important:** Results are non-authoritative and based on cached data. Always
* use the `/domain-check` endpoint to verify real-time availability before
* attempting registration.
*
* Suggestions are scoped to extensions supported for programmatic registration via
* this API (`POST /registrations`). Domains on unsupported extensions will not
* appear in results, even if they are available at the registry level.
*
* ### Use cases
*
* - Brand name discovery (e.g., "acme corp" → acmecorp.com, acmecorp.dev)
* - Keyword-based suggestions (e.g., "coffee shop" → coffeeshop.com,
* mycoffeeshop.net)
* - Alternative extension discovery (e.g., "example.com" → example.com,
* example.app, example.xyz)
*
* ### Workflow
*
* 1. Call this endpoint with a keyword or domain name.
* 2. Present suggestions to the user.
* 3. Call `/domain-check` with the user's chosen domains to confirm real-time
* availability and pricing.
* 4. Proceed to `POST /registrations` only for supported non-premium domains where
* the Check response returns `registrable: true`.
*
* **Note:** Searching with just a domain extension (e.g., "com" or ".app") is not
* supported. Provide a keyword or domain name.
*
* @example
* ```ts
* const response = await client.registrarSandbox.search({
* account_id: '023e105f4ecef8ad9ca31a8372d0c353',
* q: 'x',
* });
* ```
*/
search(params, options) {
const { account_id, ...query } = params;
return this._client.get(path `/accounts/${account_id}/registrar-sandbox/domain-search`, {
query,
...options,
})._thenUnwrap((obj) => obj.result);
}
}
BaseRegistrarSandbox._key = Object.freeze(['registrarSandbox']);
return BaseRegistrarSandbox;
})();
/**
* Use the Registrar Sandbox API to test domain search, availability checks,
* registration, and domain management flows without buying real domains.
*
* **This API is a test environment for the production Registrar API.**
*
* ## Prerequisites
*
* Before using this API, make sure you have:
*
* 1. **Cloudflare account** — the caller must have a valid Cloudflare account.
* 2. **API authentication** — create an API token with Registrar Sandbox permissions.
*
* ## How the Sandbox API differs from the production Registrar API
*
* Because the Sandbox API is intended for testing, it behaves differently from
* the production Registrar API in a few important ways:
*
* 1. **No billing** — you will not be charged real money for purchasing a domain.
* 2. **No real domains** — purchased domains are test records and will not be
* reachable on the Internet.
* 3. **No DNS zones** — purchasing a domain does not create a zone resource.
* 4. **No Registration Express Mode** — you must provide full contact data.
*
* Sandbox purchases are still persisted. If you purchase a domain in the sandbox,
* that domain will not be available for others to purchase in the sandbox.
*
* ## Terminology: domain extension
*
* Throughout this API, "extension" refers to the domain extension part of a fully
* qualified domain name — the portion after the registrable label. For example,
* in `example.co.uk`, the extension is `co.uk` (not just `uk`). This covers both
* top-level domains like `com` and multi-level extensions like `co.uk`. This is
* distinct from other uses of the word "extension" (e.g., EPP extensions).
*
* ## Supported extensions
*
* The Sandbox API currently supports programmatic registration for these
* extensions:
*
* `com`, `net`
*
* The production Registrar API supports 40+ extensions.
*
* Cloudflare Registrar supports 400+ extensions in the dashboard. Extensions
* not listed above can be registered at `https://dash.cloudflare.com/{account_id}/domains/registrations`.
*
* ## Typical workflow
*
* 1. **Search** — call `GET /domain-search?q={keyword}` to discover available domains.
* 2. **Check** — call `POST /domain-check` with candidate domains to verify real-time
* availability and pricing.
* 3. **Review the response** — if `registrable: false`, inspect `reason` to
* understand whether the domain is unavailable, the extension is not supported
* by this API, the extension is not supported by Cloudflare Registrar at all,
* or the extension's registry has frozen new registrations.
* 4. **Handle premium domains** — if `tier: premium`, premium registration is
* not currently supported by this API. The Sandbox API currently supports
* only `com` and `net`, which do not have premium registrations, but clients
* should still handle this response for consistency with the production
* Registrar API. Surface the premium pricing to the user, but do not proceed
* to `POST /registrations` for that domain.
* 5. **Observe the registration schema** — call `GET /extensions/:extension_name`
* to discover the required values for registering this extension.
* 6. **Register** — call `POST /registrations` with the chosen domain name for
* supported non-premium registrations.
* 7. **Confirm completion** — if the response is `201 Created`, registration
* completed within the default timeout and no polling is needed.
* 8. **Poll when needed** — if the response is `202 Accepted`, poll
* `links.self` from the workflow response.
* 9. **Stop for user action** — if `state: action_required`, stop polling and
* surface `context.action` to the user.
* The workflow will not resolve on its own.
* 10. **Continue when blocked** — if `state: blocked`, continue polling and
* inform the user that a third party, such as the extension registry or losing
* registrar, is delaying progress.
* 11. **Review failures before retrying** — if `state: failed`, review
* `error.code` and `error.message`, then decide whether user action or a new
* Check call is needed.
*
* ## Default behavior for mutating operations
*
* By default, mutating operations such as create and update hold the connection
* for a bounded, server-defined amount of time while the operation completes.
* In most cases, the response contains a completed workflow status and no
* polling is required.
*
* - **Completed within the synchronous wait window:** Returns `201` (create)
* or `200` (update) with a `workflow_status` where `state: succeeded` and
* `completed: true`.
* - **Still processing after the synchronous wait window:** Returns
* `202 Accepted` with a `workflow_status` where `completed: false`. Use
* the `links.self` URL to poll for completion.
*
* ## Non-blocking mode
*
* To receive an immediate `202 Accepted` response without waiting, send the
* `Prefer: respond-async` request header (RFC 7240). The server will acknowledge
* it with a `Preference-Applied: respond-async` response header.
*
* ## Polling
*
* When the response is `202`, poll the workflow status endpoint indicated by
* `links.self` in the response body until the workflow reaches a terminal
* state or requires user action.
*/
export var RegistrarSandbox = /* @__PURE__ */ (() => {
/**
* Use the Registrar Sandbox API to test domain search, availability checks,
* registration, and domain management flows without buying real domains.
*
* **This API is a test environment for the production Registrar API.**
*
* ## Prerequisites
*
* Before using this API, make sure you have:
*
* 1. **Cloudflare account** — the caller must have a valid Cloudflare account.
* 2. **API authentication** — create an API token with Registrar Sandbox permissions.
*
* ## How the Sandbox API differs from the production Registrar API
*
* Because the Sandbox API is intended for testing, it behaves differently from
* the production Registrar API in a few important ways:
*
* 1. **No billing** — you will not be charged real money for purchasing a domain.
* 2. **No real domains** — purchased domains are test records and will not be
* reachable on the Internet.
* 3. **No DNS zones** — purchasing a domain does not create a zone resource.
* 4. **No Registration Express Mode** — you must provide full contact data.
*
* Sandbox purchases are still persisted. If you purchase a domain in the sandbox,
* that domain will not be available for others to purchase in the sandbox.
*
* ## Terminology: domain extension
*
* Throughout this API, "extension" refers to the domain extension part of a fully
* qualified domain name — the portion after the registrable label. For example,
* in `example.co.uk`, the extension is `co.uk` (not just `uk`). This covers both
* top-level domains like `com` and multi-level extensions like `co.uk`. This is
* distinct from other uses of the word "extension" (e.g., EPP extensions).
*
* ## Supported extensions
*
* The Sandbox API currently supports programmatic registration for these
* extensions:
*
* `com`, `net`
*
* The production Registrar API supports 40+ extensions.
*
* Cloudflare Registrar supports 400+ extensions in the dashboard. Extensions
* not listed above can be registered at `https://dash.cloudflare.com/{account_id}/domains/registrations`.
*
* ## Typical workflow
*
* 1. **Search** — call `GET /domain-search?q={keyword}` to discover available domains.
* 2. **Check** — call `POST /domain-check` with candidate domains to verify real-time
* availability and pricing.
* 3. **Review the response** — if `registrable: false`, inspect `reason` to
* understand whether the domain is unavailable, the extension is not supported
* by this API, the extension is not supported by Cloudflare Registrar at all,
* or the extension's registry has frozen new registrations.
* 4. **Handle premium domains** — if `tier: premium`, premium registration is
* not currently supported by this API. The Sandbox API currently supports
* only `com` and `net`, which do not have premium registrations, but clients
* should still handle this response for consistency with the production
* Registrar API. Surface the premium pricing to the user, but do not proceed
* to `POST /registrations` for that domain.
* 5. **Observe the registration schema** — call `GET /extensions/:extension_name`
* to discover the required values for registering this extension.
* 6. **Register** — call `POST /registrations` with the chosen domain name for
* supported non-premium registrations.
* 7. **Confirm completion** — if the response is `201 Created`, registration
* completed within the default timeout and no polling is needed.
* 8. **Poll when needed** — if the response is `202 Accepted`, poll
* `links.self` from the workflow response.
* 9. **Stop for user action** — if `state: action_required`, stop polling and
* surface `context.action` to the user.
* The workflow will not resolve on its own.
* 10. **Continue when blocked** — if `state: blocked`, continue polling and
* inform the user that a third party, such as the extension registry or losing
* registrar, is delaying progress.
* 11. **Review failures before retrying** — if `state: failed`, review
* `error.code` and `error.message`, then decide whether user action or a new
* Check call is needed.
*
* ## Default behavior for mutating operations
*
* By default, mutating operations such as create and update hold the connection
* for a bounded, server-defined amount of time while the operation completes.
* In most cases, the response contains a completed workflow status and no
* polling is required.
*
* - **Completed within the synchronous wait window:** Returns `201` (create)
* or `200` (update) with a `workflow_status` where `state: succeeded` and
* `completed: true`.
* - **Still processing after the synchronous wait window:** Returns
* `202 Accepted` with a `workflow_status` where `completed: false`. Use
* the `links.self` URL to poll for completion.
*
* ## Non-blocking mode
*
* To receive an immediate `202 Accepted` response without waiting, send the
* `Prefer: respond-async` request header (RFC 7240). The server will acknowledge
* it with a `Preference-Applied: respond-async` response header.
*
* ## Polling
*
* When the response is `202`, poll the workflow status endpoint indicated by
* `links.self` in the response body until the workflow reaches a terminal
* state or requires user action.
*/
class RegistrarSandbox extends BaseRegistrarSandbox {
constructor() {
super(...arguments);
this.registrations = new RegistrationsAPI.Registrations(this._client);
this.registrationStatus = new RegistrationStatusAPI.RegistrationStatus(this._client);
this.updateStatus = new UpdateStatusAPI.UpdateStatus(this._client);
this.extensions = new ExtensionsAPI.Extensions(this._client);
}
}
RegistrarSandbox.Registrations = Registrations;
RegistrarSandbox.BaseRegistrations = BaseRegistrations;
RegistrarSandbox.RegistrationStatus = RegistrationStatus;
RegistrarSandbox.BaseRegistrationStatus = BaseRegistrationStatus;
RegistrarSandbox.UpdateStatus = UpdateStatus;
RegistrarSandbox.BaseUpdateStatus = BaseUpdateStatus;
RegistrarSandbox.Extensions = Extensions;
RegistrarSandbox.BaseExtensions = BaseExtensions;
return RegistrarSandbox;
})();
//# sourceMappingURL=registrar-sandbox.mjs.map