cloudflare
Version:
The official TypeScript library for the Cloudflare API
413 lines • 21.7 kB
JavaScript
;
Object.defineProperty(exports, "__esModule", { value: true });
exports.Registrar = exports.BaseRegistrar = void 0;
const tslib_1 = require("../../internal/tslib.js");
// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
const resource_1 = require("../../core/resource.js");
const DomainsAPI = tslib_1.__importStar(require("./domains.js"));
const domains_1 = require("./domains.js");
const ExtensionsAPI = tslib_1.__importStar(require("./extensions.js"));
const extensions_1 = require("./extensions.js");
const RegistrationStatusAPI = tslib_1.__importStar(require("./registration-status.js"));
const registration_status_1 = require("./registration-status.js");
const RegistrationsAPI = tslib_1.__importStar(require("./registrations.js"));
const registrations_1 = require("./registrations.js");
const TransferInAPI = tslib_1.__importStar(require("./transfer-in.js"));
const transfer_in_1 = require("./transfer-in.js");
const TransferInStatusAPI = tslib_1.__importStar(require("./transfer-in-status.js"));
const transfer_in_status_1 = require("./transfer-in-status.js");
const UpdateStatusAPI = tslib_1.__importStar(require("./update-status.js"));
const update_status_1 = require("./update-status.js");
const path_1 = require("../../internal/utils/path.js");
var BaseRegistrar = /* @__PURE__ */ (() => {
/**
* Registrar API for searching, checking, registering, and managing domains through Cloudflare Registrar.
*
* ## Prerequisites
*
* Before using this API, ensure:
*
* 1. **Cloudflare account** — the caller must have a valid Cloudflare account.
* 2. **Billing profile** — the account must have a billing profile with a valid,
* current default payment method (credit card or other accepted method).
* This cannot be set up via API — the account owner must configure billing
* at `https://dash.cloudflare.com/{account_id}/billing/payment-info` before
* calling `POST /registrations`.
* 3. **API authentication** — use an API token or API key with the appropriate
* Registrar permissions for the operations you are calling.
*
* ## 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
*
* This API supports programmatic registration for all extensions supported by
* the dashboard experience, with the following exceptions:
*
* `giving`, `mom`, `inc`, `lol`, `sh`, `link`, `cc`, `new`
*
* Cloudflare Registrar supports 400+ extensions in the dashboard. Extensions
* 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. 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.
*
* **All successful domain registrations are non-refundable.** Once the registration
* workflow completes with `state: succeeded`, the charge cannot be reversed.
* Confirm pricing and domain choice with the user before calling `POST /registrations`.
*
* ## 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 BaseRegistrar extends resource_1.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.registrar.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((0, path_1.path) `/accounts/${account_id}/registrar/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.registrar.search({
* account_id: '023e105f4ecef8ad9ca31a8372d0c353',
* q: 'x',
* });
* ```
*/
search(params, options) {
const { account_id, ...query } = params;
return this._client.get((0, path_1.path) `/accounts/${account_id}/registrar/domain-search`, {
query,
...options,
})._thenUnwrap((obj) => obj.result);
}
/**
* Performs real-time, authoritative eligibility checks directly against needed
* requirements. Use this endpoint to verify a domain is available before
* attempting a transfer via `POST /registrations/:domain_name/transfer-in`.
*
* **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.
*
* ### Behavior
*
* - Maximum 10 domains per request
* - Pricing is only returned for domains where `transferable: true`
* - Results are not cached; each request queries the registry & other needed
* upstreams
*
* ## Extension Support
*
* All `.uk` extensions (`.uk`, `.co.uk`, etc) do not support auth codes. As such,
* Cloudflare will ignore the `auth_code` section of this request for `.uk`
* domains.
*
* This means that a `.uk` domain depends on public data to obtain domain
* information, so it might be a few minutes outdated.
*
* ### Workflow
*
* 1. Call this endpoint with domains the user wants to transfer.
* 2. For each domain where `transferable: true`, present pricing to the user.
* 3. For each domain where `transferable: false`, present reasons to the user
* 4. Proceed to `POST /registrations/:domain_name/transfer-in` only for the
* `transferable: true` domains.
*
* @example
* ```ts
* const response = await client.registrar.transferCheck({
* account_id: '023e105f4ecef8ad9ca31a8372d0c353',
* domains: [{ domain_name: 'example.co.uk' }],
* });
* ```
*/
transferCheck(params, options) {
const { account_id, ...body } = params;
return this._client.post((0, path_1.path) `/accounts/${account_id}/registrar/domain-transfer-check`, {
body,
...options,
})._thenUnwrap((obj) => obj.result);
}
}
BaseRegistrar._key = Object.freeze(['registrar']);
return BaseRegistrar;
})();
exports.BaseRegistrar = BaseRegistrar;
var Registrar = /* @__PURE__ */ (() => {
/**
* Registrar API for searching, checking, registering, and managing domains through Cloudflare Registrar.
*
* ## Prerequisites
*
* Before using this API, ensure:
*
* 1. **Cloudflare account** — the caller must have a valid Cloudflare account.
* 2. **Billing profile** — the account must have a billing profile with a valid,
* current default payment method (credit card or other accepted method).
* This cannot be set up via API — the account owner must configure billing
* at `https://dash.cloudflare.com/{account_id}/billing/payment-info` before
* calling `POST /registrations`.
* 3. **API authentication** — use an API token or API key with the appropriate
* Registrar permissions for the operations you are calling.
*
* ## 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
*
* This API supports programmatic registration for all extensions supported by
* the dashboard experience, with the following exceptions:
*
* `giving`, `mom`, `inc`, `lol`, `sh`, `link`, `cc`, `new`
*
* Cloudflare Registrar supports 400+ extensions in the dashboard. Extensions
* 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. 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.
*
* **All successful domain registrations are non-refundable.** Once the registration
* workflow completes with `state: succeeded`, the charge cannot be reversed.
* Confirm pricing and domain choice with the user before calling `POST /registrations`.
*
* ## 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 Registrar extends BaseRegistrar {
constructor() {
super(...arguments);
this.domains = new DomainsAPI.Domains(this._client);
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);
this.transferIn = new TransferInAPI.TransferIn(this._client);
this.transferInStatus = new TransferInStatusAPI.TransferInStatus(this._client);
}
}
Registrar.Domains = domains_1.Domains;
Registrar.BaseDomains = domains_1.BaseDomains;
Registrar.Registrations = registrations_1.Registrations;
Registrar.BaseRegistrations = registrations_1.BaseRegistrations;
Registrar.RegistrationStatus = registration_status_1.RegistrationStatus;
Registrar.BaseRegistrationStatus = registration_status_1.BaseRegistrationStatus;
Registrar.UpdateStatus = update_status_1.UpdateStatus;
Registrar.BaseUpdateStatus = update_status_1.BaseUpdateStatus;
Registrar.Extensions = extensions_1.Extensions;
Registrar.BaseExtensions = extensions_1.BaseExtensions;
Registrar.TransferIn = transfer_in_1.TransferIn;
Registrar.BaseTransferIn = transfer_in_1.BaseTransferIn;
Registrar.TransferInStatus = transfer_in_status_1.TransferInStatus;
Registrar.BaseTransferInStatus = transfer_in_status_1.BaseTransferInStatus;
return Registrar;
})();
exports.Registrar = Registrar;
//# sourceMappingURL=registrar.js.map