DocuSign.Util.Environment (DocuSign v2.2.3)

View Source

Utilities for automatic environment detection based on DocuSign URLs.

This module provides functions to automatically determine whether to use sandbox or production OAuth endpoints based on the API base URL patterns, similar to the Ruby DocuSign client's environment detection logic.

Environment Detection Rules

The environment is detected based on URL patterns:

  • Sandbox/Demo: URLs containing "demo", "apps-d", or pointing to demo environments
  • Production: All other URLs default to production environment

Examples

iex> DocuSign.Util.Environment.determine_hostname("https://demo.docusign.net/restapi")
"account-d.docusign.com"

iex> DocuSign.Util.Environment.determine_hostname("https://na3.docusign.net/restapi")
"account.docusign.com"

iex> DocuSign.Util.Environment.detect_environment("https://demo.docusign.net")
:sandbox

iex> DocuSign.Util.Environment.detect_environment("https://na3.docusign.net")
:production

Summary

Functions

Detects the environment type based on the API base URI.

Automatically determines the appropriate OAuth hostname based on the API base URI.

Gets the appropriate OAuth configuration based on environment detection.

Checks if the given URI indicates a sandbox/demo environment.

Validates that the hostname matches the detected environment.

Functions

detect_environment(base_uri)

@spec detect_environment(String.t()) :: :sandbox | :production

Detects the environment type based on the API base URI.

Parameters

  • base_uri - The DocuSign API base URI

Returns

  • :sandbox for sandbox/demo environments
  • :production for production environments

Examples

iex> DocuSign.Util.Environment.detect_environment("https://demo.docusign.net")
:sandbox

iex> DocuSign.Util.Environment.detect_environment("https://na3.docusign.net")
:production

determine_hostname(base_uri)

@spec determine_hostname(String.t()) :: String.t()

Automatically determines the appropriate OAuth hostname based on the API base URI.

This function analyzes the provided base URI and returns the corresponding OAuth hostname that should be used for authentication endpoints.

Parameters

Returns

  • "account-d.docusign.com" for sandbox/demo environments
  • "account.docusign.com" for production environments

Examples

# Sandbox detection
iex> DocuSign.Util.Environment.determine_hostname("https://demo.docusign.net/restapi")
"account-d.docusign.com"

iex> DocuSign.Util.Environment.determine_hostname("https://apps-d.docusign.com")
"account-d.docusign.com"

# Production detection
iex> DocuSign.Util.Environment.determine_hostname("https://na3.docusign.net/restapi")
"account.docusign.com"

iex> DocuSign.Util.Environment.determine_hostname("https://eu.docusign.net/restapi")
"account.docusign.com"

oauth_config(base_uri, opts \\ [])

@spec oauth_config(String.t(), Keyword.t()) :: Keyword.t()

Gets the appropriate OAuth configuration based on environment detection.

This function provides a convenient way to get complete OAuth configuration including hostname and other environment-specific settings.

Parameters

  • base_uri - The DocuSign API base URI
  • opts - Optional keyword list with additional configuration

Options

  • :client_id - OAuth client ID (integration key)
  • :client_secret - OAuth client secret

Returns

A keyword list with OAuth configuration:

  • :hostname - The OAuth hostname
  • :environment - :sandbox or :production
  • Plus any additional options passed in

Examples

iex> DocuSign.Util.Environment.oauth_config("https://demo.docusign.net", client_id: "abc123")
[hostname: "account-d.docusign.com", environment: :sandbox, client_id: "abc123"]

sandbox_environment?(uri)

@spec sandbox_environment?(String.t()) :: boolean()

Checks if the given URI indicates a sandbox/demo environment.

This function implements the same detection logic as the DocuSign Ruby client, checking for URL patterns that indicate sandbox usage.

Parameters

  • uri - The URI to check

Returns

  • true if the URI indicates a sandbox environment
  • false if the URI indicates a production environment

Examples

iex> DocuSign.Util.Environment.sandbox_environment?("https://demo.docusign.net")
true

iex> DocuSign.Util.Environment.sandbox_environment?("https://apps-d.docusign.com")
true

iex> DocuSign.Util.Environment.sandbox_environment?("https://na3.docusign.net")
false

validate_hostname(base_uri, hostname)

@spec validate_hostname(String.t(), String.t()) ::
  {:ok, String.t()} | {:error, atom()}

Validates that the hostname matches the detected environment.

This function can be used to verify that manually configured hostnames are consistent with the auto-detected environment.

Parameters

  • base_uri - The DocuSign API base URI
  • hostname - The manually configured hostname

Returns

  • {:ok, hostname} if the hostname matches the detected environment
  • {:error, reason} if there's a mismatch

Examples

iex> DocuSign.Util.Environment.validate_hostname("https://demo.docusign.net", "account-d.docusign.com")
{:ok, "account-d.docusign.com"}

iex> DocuSign.Util.Environment.validate_hostname("https://demo.docusign.net", "account.docusign.com")
{:error, :environment_mismatch}