Changelog

Copy Markdown View Source

v4.1.0 (2026-10-22)

Security

  • A scheduled token refresh that failed (any transport error or non-2xx from the token endpoint) terminated DocuSign.ClientRegistry, and the GenServer crash report printed every cached OAuth2.Client, access tokens included, at error level. The refresh handler now rescues, logs the user ID and exception message only, and drops that user's cached client so the next call rebuilds it. The registry state and DocuSign.Connection redact the OAuth client on inspect, so a crash in code holding a connection does not print the bearer token or client secret either.
  • Debug logging replaced the authorization header value with [FILTERED] in the Tesla era and stopped doing so in the Req migration, while the README kept saying it did. The debug steps now apply :debug_filter_headers (default ["authorization"]) to request and response headers. debug: true alone logs method, URL, status and filtered headers; bodies are logged only with debug_body: true (application config or per request) and are logged unfiltered.
  • Generated API functions percent-encode path parameters. A value containing /, ? or # previously changed the request path or appended query parameters, all under the connection's bearer token. Every url/2 call in DocuSign.Api.* now wraps its parameters in the new DocuSign.RequestBuilder.encode_path_param/1, which encodes everything outside the RFC 3986 unreserved set and the bare . and .. values. The regeneration script applies this as post-processing until the upstream generator emits it (openapi-generator PR #25366), and a test fails if any generated URL carries a bare interpolation.
  • DocuSign.Connection.request/2 rejects absolute URLs. Req skipped the base URL for those and sent the bearer token to whatever host was given.
  • OAuth token requests for the JWT and authorization-code flows pass the verified TLS options from DocuSign.SSLOptions to httpc instead of relying on the OTP default, which only verifies peers on OTP 26 and newer.
  • Configured :ssl_options now apply to API traffic when :pool_options is not set; they were only applied through the Finch pool. Per-request ssl_options: with pooling enabled raised inside Req; that request now goes through a dynamic pool with the given transport options.
  • DocuSign.WebhookPlug accepts secret: as its documentation showed, as well as hmac_secret_key:, and raises at init without either. The HMAC length guard compares bytes rather than graphemes, so a multibyte signature header returns false instead of raising. The exception for an invalid handler return no longer embeds the webhook payload.
  • DocuSign.SSLOptions.build/1 drops :cacertfile when :cacerts is given, since OTP ignores the file in that case and logs a notice per connection.
  • config/dev.exs no longer enables oauth2 debug logging, which printed token responses.

Internal

  • Regeneration runs against OpenAPI Generator 7.26.0 again. The upstream Elixir generator cannot fall back to its embedded templates when a custom template directory is given (openapi-generator PR #25365), and its merged Req templates (PRs #24840 and #24841) produce code that differs from this library's and fails eight tests. scripts/regen/custom_templates therefore vendors the full template set: the pre-upstream Req templates this code was generated from, upstream's supporting files, and three local deviations (model.mustache omitting nil fields, a version-less licenseInfo.mustache, and encode_path_param/1 in the request builder). The script requires 7.26.0 or newer, runs the generator from a temporary directory so it leaves no openapitools.json behind, and reproduces the committed code byte for byte. Moving to upstream's templates is a separate change; see scripts/regen/README.md.

Improvements

  • Pooled connections pass the Finch pool as finch: [name: DocuSign.Finch]. Req 0.7 deprecates the bare name form and printed a warning on every pooled request.
  • Fix the generated DocuSign.Deserializer.deserialize/4 typespec, which declared its fourth argument as a function while every generated model passes a module. Dialyzer now analyses the 605 generated model modules cleanly, so the blanket .dialyzer_ignore.exs entry for lib/docusign/model has been removed along with the file itself. mix dialyzer reports zero errors with nothing suppressed.

v4.0.0 (2026-09-01)

Breaking Changes

  • Require Elixir 1.18 or newer.
  • Require Req in the ~> 0.7 series.
  • Replace Jason with Elixir's built-in JSON module for encoding and decoding. Generated models now implement JSON.Encoder and continue to omit nil fields from encoded request bodies.
  • Jason is no longer a direct dependency. Applications that use Jason directly must declare it themselves.

Improvements

  • Rewrite retry handling to use Req's retry-callback style. Retries now cover HTTP 408, 429, 500, 502, 503, and 504 responses plus timeout, connection-refused, and closed transport errors. Retry-After values are validated, retain millisecond precision, and are capped by max_delay; malformed values fall back to exponential backoff. Rate-limit telemetry now fires exactly once for each 429 response, including 429 responses without a usable Retry-After header.
  • Fix three mangled MDN links in generated API documentation.
  • Make the generator templates portable by using the configured module name and passing invokerPackage to the generator.
  • Make the regeneration script use the tracked specification by default, always clean and regenerate generated output, support Linux-compatible post-processing, and remove the obsolete Poison fallback.

v3.5.1 (2026-06-29)

Dependencies

  • Remove direct cowlib dependency. The package was not used directly, and the exact pin leaked an unnecessary version constraint to downstream applications.
  • Replace Bypass test servers with a local Bandit-backed test helper, removing the test-only Cowboy dependency stack.

v3.5.0 (2026-06-27)

API Updates

  • Regenerate API from latest DocuSign OpenAPI specification (June 24, 2026).
  • Replace the stale tracked regeneration spec payload with the real upstream OpenAPI JSON.
  • Add envelope share APIs for retrieving, creating/updating, and deleting individual or bulk envelope shares, plus shared envelope listing.
  • Add Connect HMAC secret APIs for creating, retrieving, and deleting Connect secrets.
  • Add new generated models including AdditionalSetting, AuthorizedSignatory, BulkSendingCopyPrefillTab, EnvelopesShareRequest, EnvelopesSharePermissionRequest, EnvelopesShareResponse, GroupUserInfo, GroupUsersResponse, SenderCompletionInfo, TemplateCompletionInfo, TemplateCompletionRateResponse, and UserCompletionRateResponse.
  • Update envelope share request/response models to use the new singular share item models from the upstream spec.
  • Add newly generated account settings, recipient, tab, completion-rate, and group user fields.
  • Remove the generated Accounts.recipient_names_get_recipient_names/3 endpoint because it is no longer present in the upstream spec.

Dependencies

  • Add Elixir 1.20 / OTP 29 support.
  • Update dependency lockfile, including Req 0.6.2, Finch 0.23.0, Plug 1.20.1, Cowboy 2.16.1, Credo 1.7.19, Quokka 2.13.1, and ExDoc 0.40.3.

CI/Testing

  • Add an Elixir 1.20.1 / OTP 29.0 CI lane.
  • Update GitHub Actions to actions/checkout@v4 and actions/cache@v4.
  • Fix the test step so failing tests fail CI.
  • Run Credo, docs generation, and package build checks on the primary CI lane.
  • Add a mix precommit alias for local format, compile, Credo, and test checks.

v3.4.0 (2026-03-26)

API Updates

  • Regenerate API from latest DocuSign OpenAPI specification (March 13, 2026)
    • Add new Envelope Shares API endpoint (/envelopes/{envelopeId}/shares)
    • Add new models: EnvelopeShares, docGenFormat, envelopesSharesRequest, envelopesSharesRequestItem, envelopesSharesResponse, envelopesSharesResponseItem
    • Add signingGroupType property to all recipient types (agent, carbonCopy, certifiedDelivery, editor, inPersonSigner, intermediary, notaryRecipient, notaryWitness, participant, signer, witness)
    • Add format, hidden, readOnly properties to docGenFormField
    • Add BYOIDV and FedRAMP IDV settings to accountSettingsInformation
    • Add Navigator hierarchy AI settings to accountSettingsInformation
    • Remove deprecated settings: dss_SCOREFDN_196_Rebrand_DocuSignIsNotAVerb, enableSigningAIFeaturesSetting

Bug Fixes

Dependencies

  • Update castore to 1.0.18
  • Update credo to 1.7.17

v3.3.0 (TBD)

Release

  • Bump library minor version to 3.3.0.

Features

  • Add support for custom headers in API requests via :headers option parameter. Useful for DocuSign-specific headers like X-DocuSign-Edit required for locked envelope operations.

API Updates

  • Regenerate API from latest DocuSign OpenAPI specification (January 27, 2026)
    • Add new AI-related settings (enableAISuggestedFields, enableAISuggestedFieldsAutoPlace)
    • Add Navigator API configuration options (enableNavigatorAPIDataIn, enableNavigatorAPIDataOut, enableNavigatorAPIUtilities)
    • Add CFR rapid signing embedded auth settings
    • Add Connect envelope reminder sent event UI option
    • Add legacy KBA disable settings
    • Add new model: BrandLogoIds
    • Add new models: AccountManagementGranular, NotaryWitness
    • Add notary witness recipient lists to envelope/template recipient models
    • Add envelope get query support for user_id
    • Update custom headers support in regeneration template for future regenerations

Bug Fixes

  • Fix custom opts in API requests - change :query to :params to match Req API requirements

Dependencies

  • Update Erlang to 28.3 and Elixir to 1.19.4
  • Update castore to 1.0.17
  • Update cowboy to 2.14.2
  • Update cowlib to 2.16.0
  • Update credo to 1.7.16
  • Update dialyxir to 1.4.7
  • Update ex_doc to 0.40.1
  • Update finch to 0.21.0
  • Update jose to 1.11.12
  • Update mix_test_watch to 1.4.0
  • Update plug to 1.19.1
  • Update plug_cowboy to 2.7.5
  • Update quokka to 2.12.1
  • Update req to 0.5.17
  • Relax dependency version constraints to allow latest patch versions automatically
  • Drop Elixir 1.16 support (now requires 1.17+)

CI/Testing

  • Update CI test matrix: drop 1.16, test 1.17-1.19 with OTP 27-28
  • Update .tool-versions to Erlang 28.3 and Elixir 1.19.4

v3.1.1 (2025-09-04)

Documentation

  • Add reference to ueberauth_docusign package for Überauth integration
  • Update README to guide Phoenix developers to the appropriate OAuth solution

v3.1.0 (2025-09-01)

Improvements

  • Connection Pooling: Add optimized connection pooling for high-throughput applications

    • Configurable pool size and count for concurrent request handling
    • Connection reuse to reduce HTTPS handshake overhead
    • Automatic cleanup of idle connections with configurable timeout
    • Health monitoring through DocuSign.ConnectionPool.health()
    • Seamless integration with existing Connection module
    • Custom Finch supervisor when pooling is enabled
    • Full SSL/TLS support with pooled connections

  • Retry Logic: Add configurable retry logic with exponential backoff

    • Automatic retry on transient failures (5xx errors, network issues)
    • Rate limit handling with Retry-After header support
    • Configurable max retries, backoff factor, and max delay
    • Exponential backoff with jitter to prevent thundering herd
    • Can be disabled by setting retry_options: [enabled: false]

  • Telemetry Integration: Add comprehensive telemetry events for monitoring and observability

    • DocuSign-specific events for API operations (start, stop, exception)
    • Rate limit tracking with dedicated telemetry events
    • Integration with Finch telemetry for low-level HTTP metrics
    • Support for Telemetry.Metrics and production monitoring tools
    • Automatic operation name extraction from API paths
    • Detailed metadata including account ID, operation, status codes

  • SDK Version Management: Add proper SDK identification and version reporting

    • User-Agent header includes SDK version, API version, and runtime info
    • Format: docusign-elixir/3.0.0 (Elixir/1.18.4; OTP/28; API/v2.1)
    • SDK metadata included in all telemetry events
    • Support for custom User-Agent suffix for app identification
    • Matches Ruby SDK pattern for version reporting

Bug Fixes

  • Test Stability: Fix flaky async tests caused by Mock library
    • Replace Mock-based tests with Bypass integration tests
    • Fix OAuth test log assertions to handle concurrent test execution
    • All tests now pass consistently with async: true

Internal Changes

  • Documentation: Add CLAUDE.md with critical CI requirements
  • Regeneration Script: Update to handle correct OpenAPI Generator output paths
  • Removed Files: Remove unused RecipientViewUrl model (API uses EnvelopeViews instead)
  • Dependencies: Update ex_doc from 0.38.2 to 0.38.3

v3.0.0 (2025-09-01)

Breaking Changes

  • HTTP Client Migration: Replace Tesla with Req HTTP client
    • Error responses now return {:error, Req.Response} instead of {:error, Tesla.Env}
    • Connection module internally uses Req instead of Tesla
    • Removed Tesla middleware system in favor of Req's request/response steps
    • Debug module's middleware functions are deprecated (use sdk_headers() directly)
    • Any code directly accessing error response structures will need updates

Major Improvements

  • Removed Internal Workarounds:

    • Eliminated ModelCleaner hack - Req properly handles nil values in request bodies
    • No more INVALID_REQUEST_BODY errors from nil values
    • Cleaner codebase without internal workarounds

  • OpenAPI Generator Integration: Implement custom Mustache templates for OpenAPI Generator

    • Custom templates for api, model, request_builder, and deserializer modules
    • Correct type specifications that pass Dialyzer without warnings
    • Jason encoder/decoder integration replacing Poison
    • Generated code now requires minimal post-processing

  • API Updates: Regenerate entire API from latest DocuSign OpenAPI specification (August 22, 2025)

    • Uses the most recent spec available from DocuSign's official repository
    • Added new models: ConnectedData, ConnectedObjectDetails, ConnectionInstance, ExtensionData
    • Added new template view models: TemplateViewRecipientSettings, TemplateViewSettings
    • Added recipient preview for template editing
    • Updated all existing API endpoints to latest specifications

Improvements

  • File Download: Add DocuSign.FileDownloader module for robust file downloads

    • Support for documents, attachments, and any downloadable resources
    • Multiple download strategies: memory, temp file, or specific path
    • Automatic filename extraction from Content-Disposition headers
    • Configurable temp file options with automatic cleanup
    • Content-Type validation and size limits
    • Convenient Connection.download_file/3 helper function

  • Configuration: Add auto-detection of OAuth hostname based on base URI

    • determine_hostname/1 function automatically detects sandbox vs production
    • detect_environment/1 function identifies environment from base URI
    • from_oauth_client_with_detection/2 for automatic hostname configuration
    • Eliminates manual hostname configuration in most cases

  • Error Handling: Add structured error support (opt-in)

    • Set config :docusign, :structured_errors, true to enable
    • Provides DocuSign.Error struct with detailed error information
    • Backward compatible - defaults to tuple errors

Bug Fixes

  • Fixed OAuth2 client integration to work with Req
  • Fixed SSLOptions module to properly configure Finch transport options
  • Fixed retry logic initialization when retries are disabled
  • Fixed User module warning about is_binary guard
  • Updated all API calls to handle Req.Response instead of Tesla.Env

Internal Changes

  • Migrated from Tesla to Req for HTTP client
  • Replaced Poison with Jason for JSON handling
  • Updated all dependencies to latest versions
  • Added comprehensive test coverage for new features
  • Improved documentation with more examples

v2.0.0 (2021-11-11)

Breaking Changes

  • The private_key parameter for JWT impersonation has been renamed to private_key_file. The value is expected to be a file path now.
  • Introduced a new private_key_contents parameter for JWT impersonation which expects a string with the contents of the private key.

Improvements

  • Allow a private_key_contents parameter for JWT impersonation, useful for applications where the private key is stored in environment variables.
  • Introduce ClientRegistry which allows using multiple DocuSign accounts in the same application.
  • Increased the timeout for Accounts.refresh_access_token to account for real-world latencies
  • Allow passing in :ssl_options per-request to configure SSL with custom CA certificates
  • Add example error in docstrings for endpoints that use composite templates
  • Added types, docs, specs, and fixed unused variable warnings

Bug Fixes

  • Fixed an issue with newer OAuth library versions where JWT grant parameters were incorrectly encoded, causing authentication failures
  • Fixed missing alias for CompositeTemplate in Envelopes module
  • Fixed broken refresh token flow that was using wrong token type
  • Clarified error messages when OAuth configurations are missing or conflicting

Internal Changes

  • Added dialyzer and resolved all warnings
  • Upgraded dependencies to latest versions
  • Fixed test async mode for more reliable test runs
  • General code cleanup and maintenance

v1.2.0 (2021-03-25)

Added

  • "JWT Flow for API impersonation added
  • Enhanced Test Coverage

v1.1.0 (2019-09-17)

Improvements

  • Ability to pass options to Tesla per request was added

v1.0.1 (2019-09-06)

Improvements

  • Add support for resending an envelope

v1.0.0 (2019-07-23)

  • Initial public release