DomainConnect.Async (DomainConnect v0.5.0)

The asynchronous (OAuth) Domain Connect flow, for Service Providers that apply templates programmatically rather than by redirecting the owner to a one-shot sync UX.

The round trip:

consent_url/2 — build the URL the owner visits to grant consent. The provider redirects back to your redirect_uri with a code.
get_token/2 — exchange that code for a DomainConnect.Token.
apply/3 — apply your template(s) using the token. Re-runnable; on a record conflict it returns {:error, :conflict} unless force: true.
refresh/2 — exchange a refresh token for a fresh access token.

Every request that this library makes server-side (get_token/2, apply/3, refresh/2) hits the provider's urlAPI, which is taken from the discovered settings and is therefore DNS-influenced — so its host is SSRF-guarded (DomainConnect.HostGuard), redirects are disabled, and timeouts are tight. consent_url/2 is a pure builder (the owner's browser makes that request).

Summary

Functions

apply(config, token, opts)

Applies a template using an access token.

consent_url(config, opts)

Builds the OAuth consent URL to redirect the domain owner to.

get_token(config, opts)

Exchanges an authorization code for a DomainConnect.Token.

refresh(config, opts)

Refreshes an access token.

Functions

apply(config, token, opts)

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

Applies a template using an access token.

Required options

:provider_id, :service_id.

Optional options

:params (string-keyed map; reserved keys rejected), :group_ids (string or list), :force (boolean — override a record conflict).

Returns :ok, {:error, :conflict} (records already present; retry with force: true), or {:error, reason}.

consent_url(config, opts)

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

Builds the OAuth consent URL to redirect the domain owner to.

Required options

:provider_id — your template's providerId.
:service_ids — the template service id(s) to request, as a string or a list of strings (joined into the OAuth scope).
:redirect_uri — where the provider returns the owner with the code.

Optional options

:client_id — OAuth client id (defaults to :provider_id).
:params — template variable values (string-keyed map; reserved keys rejected).
:state — opaque value echoed back to :redirect_uri.

Returns {:error, :async_not_supported} if the provider advertised no async UX.

get_token(config, opts)

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

Exchanges an authorization code for a DomainConnect.Token.

Required options

:code, :client_id, :client_secret, :redirect_uri.

Returns {:ok, %DomainConnect.Token{}} or {:error, reason}.

refresh(config, opts)

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

Refreshes an access token.

Required options

:refresh_token, :client_id, :client_secret.