cloudflare
Version:
The official TypeScript library for the Cloudflare API
180 lines • 8.45 kB
JavaScript
// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
import { APIResource } from "../../core/resource.mjs";
import { CursorPagination } from "../../core/pagination.mjs";
import { buildHeaders } from "../../internal/headers.mjs";
import { path } from "../../internal/utils/path.mjs";
export var BaseRegistrations = /* @__PURE__ */ (() => {
class BaseRegistrations extends APIResource {
/**
* Starts a domain registration workflow. This is a billable operation — successful
* registration charges the account's default payment method. All successful domain
* registrations are non-refundable — once the workflow completes with
* `state: succeeded`, the charge cannot be reversed.
*
* ### Prerequisites
*
* - The account must have a billing profile with a valid default payment method.
* Set this up at
* `https://dash.cloudflare.com/{account_id}/billing/payment-info`.
* - The account must not already be at the maximum supported domain limit. A
* single account may own up to 500 domains in total across registrations created
* through either the dashboard or this API.
* - The domain must be on a supported extension for programmatic registration.
* - Use `POST /domain-check` immediately before calling this endpoint to confirm
* real-time availability and pricing.
*
* ### 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`.
*
* ### Express mode
*
* The only required field is `domain_name`. If `contacts` is omitted, the system
* uses the account's default address book entry as the registrant. If no default
* exists and no contact is provided, the request fails. Set up a default address
* book entry and accept the required agreement at
* `https://dash.cloudflare.com/{account_id}/domains/registrations`.
*
* ### Defaults
*
* - `years`: defaults to the extension's minimum registration period (1 year for
* most extensions, but varies — for example, `.ai` (if supported) requires a
* minimum of 2 years).
* - `auto_renew`: defaults to `false`. Setting it to `true` is an explicit opt-in
* authorizing Cloudflare to charge the account's default payment method up to 30
* days before domain expiry to renew the registration. Renewal pricing may
* change over time based on registry pricing.
* - `privacy_mode`: defaults to `redaction`.
*
* ### Premium domains
*
* Premium domain registration is not currently supported by this API. If
* `POST /domain-check` returns `tier: premium`, do not call this endpoint for that
* domain.
*
* ### Response behavior
*
* By default, the server holds the connection for a bounded, server-defined amount
* of time while the registration completes. Most registrations finish within this
* window and return `201 Created` with a completed workflow status.
*
* If the registration is still processing after this synchronous wait window, the
* server returns `202 Accepted`. Poll the URL in `links.self` to track progress.
*
* To skip the wait and receive an immediate `202`, send `Prefer: respond-async`.
*
* @example
* ```ts
* const workflowStatus = await client.registrar.registrations.create({
* account_id: '023e105f4ecef8ad9ca31a8372d0c353',
* domain_name: 'my-brand-example.io',
* contacts: {
* administrator: { ... },
* billing: { ... },
* registrant: { ... },
* technical: { ... },
* },
* years: 1,
* });
* ```
*/
create(params, options) {
const { account_id, Prefer, ...body } = params;
return this._client.post(path `/accounts/${account_id}/registrar/registrations`, {
body,
...options,
headers: buildHeaders([{ ...(Prefer != null ? { Prefer: Prefer } : undefined) }, options?.headers]),
})._thenUnwrap((obj) => obj.result);
}
/**
* Returns a paginated list of domain registrations owned by the account.
*
* This endpoint uses cursor-based pagination. Results are ordered by registration
* date by default. To fetch the next page, pass the `cursor` value from the
* `result_info` object in the response as the `cursor` query parameter in your
* next request. An empty `cursor` string indicates there are no more pages.
*
* @example
* ```ts
* // Automatically fetches more pages as needed.
* for await (const registration of client.registrar.registrations.list(
* { account_id: '023e105f4ecef8ad9ca31a8372d0c353' },
* )) {
* // ...
* }
* ```
*/
list(params, options) {
const { account_id, ...query } = params;
return this._client.getAPIList(path `/accounts/${account_id}/registrar/registrations`, (CursorPagination), { query, ...options });
}
/**
* Updates an existing domain registration.
*
* By default, the server holds the connection for a bounded, server-defined amount
* of time while the update completes. Most updates finish within this window and
* return `200 OK` with a completed workflow status.
*
* If the update is still processing after this synchronous wait window, the server
* returns `202 Accepted`. Poll the URL in `links.self` to track progress.
*
* To skip the wait and receive an immediate `202`, send `Prefer: respond-async`.
*
* This endpoint currently supports updating `auto_renew` only.
*
* @example
* ```ts
* const workflowStatus =
* await client.registrar.registrations.edit('example.com', {
* account_id: '023e105f4ecef8ad9ca31a8372d0c353',
* });
* ```
*/
edit(domainName, params, options) {
const { account_id, Prefer, ...body } = params;
return this._client.patch(path `/accounts/${account_id}/registrar/registrations/${domainName}`, {
body,
...options,
headers: buildHeaders([
{ ...(Prefer?.toString() != null ? { Prefer: Prefer?.toString() } : undefined) },
options?.headers,
]),
})._thenUnwrap((obj) => obj.result);
}
/**
* Returns the current state of a domain registration.
*
* This is the canonical read endpoint for a domain you own. It returns the full
* registration resource including current settings and expiration. When the
* registration resource is ready, both `created_at` and `expires_at` are present
* in the response.
*
* @example
* ```ts
* const registration =
* await client.registrar.registrations.get('example.com', {
* account_id: '023e105f4ecef8ad9ca31a8372d0c353',
* });
* ```
*/
get(domainName, params, options) {
const { account_id } = params;
return this._client.get(path `/accounts/${account_id}/registrar/registrations/${domainName}`, options)._thenUnwrap((obj) => obj.result);
}
}
BaseRegistrations._key = Object.freeze([
'registrar',
'registrations',
]);
return BaseRegistrations;
})();
export class Registrations extends BaseRegistrations {
}
//# sourceMappingURL=registrations.mjs.map