@spec apply_url(
  DomainConnect.Config.t(),
  keyword()
) :: {:ok, String.t()} | {:error, term()}

Builds the synchronous apply URL to redirect the domain owner to.

On arrival the DNS provider shows a consent screen for your template and, on approval, writes the records. Resolves to:

<url_sync_ux>/v2/domainTemplates/providers/<provider_id>/services/<service_id>/apply?...

Required options

• :provider_id — your template's providerId (e.g. "exampleservice.com").
• :service_id — your template's serviceId (e.g. "hosting").

Optional options

• :params — a map of template variable values (string keys), merged into the query (e.g. %{"target" => "portal.unitops.app", "ttl" => "3600"}). Must not contain the reserved keys domain, host, redirect_uri, state, or groupId.
• :redirect_uri — where the provider returns the owner after applying.
• :state — opaque value echoed back to :redirect_uri.
• :group_ids — record group ids for partial templates; a list of strings or a comma-separated string.

Returns {:error, :sync_not_supported} if the provider advertised no sync UX, {:error, {:missing, key}} if a required id is absent, or {:error, {:reserved_params, keys}} if :params collides with a reserved key.

Signed templates

For templates that require a signed request, pass :private_key (an unencrypted RSA private-key PEM) and :key_id (the TXT record name where the matching public key is published). The query is signed (RSA-SHA256) and sig /key are appended. Without both, an unsigned URL is built.

@spec async_apply(DomainConnect.Config.t(), DomainConnect.Token.t(), keyword()) ::
  :ok | {:error, term()}

Asynchronous flow: apply a template using a token. See DomainConnect.Async.apply/3.

@spec async_consent_url(
  DomainConnect.Config.t(),
  keyword()
) :: {:ok, String.t()} | {:error, term()}

Asynchronous (OAuth) flow: build the consent URL to redirect the owner to. See DomainConnect.Async.consent_url/2.

@spec async_refresh(
  DomainConnect.Config.t(),
  keyword()
) :: {:ok, DomainConnect.Token.t()} | {:error, term()}

Asynchronous flow: refresh an access token. See DomainConnect.Async.refresh/2.

@spec async_token(
  DomainConnect.Config.t(),
  keyword()
) :: {:ok, DomainConnect.Token.t()} | {:error, term()}

Asynchronous flow: exchange an authorization code for a token. See DomainConnect.Async.get_token/2.

@spec discover(
  String.t(),
  keyword()
) :: {:ok, DomainConnect.Config.t()} | {:error, :not_supported | term()}

Discovers the Domain Connect configuration for domain. See DomainConnect.Discovery.discover/2 for options.

@spec supported?(
  String.t(),
  keyword()
) :: boolean()

Convenience: true if domain's provider supports the synchronous apply flow.

Swallows discovery errors into false. Accepts the same options as discover/2.

@spec zone_and_host(String.t()) ::
  {:ok, String.t(), String.t() | nil} | {:error, :invalid_domain}

Splits a domain into its registrable zone and sub-host via the Public Suffix List, without any DNS lookup.

iex> DomainConnect.zone_and_host("rent.theirplace.co.uk")
{:ok, "theirplace.co.uk", "rent"}

Useful for showing the owner exactly what you'll configure ("we'll set up rent on theirplace.co.uk") before discovery.