boldsign 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9fc2965681164f6e721c5d7a18b9370d1ddfd7570916cde257078b29d3be34d5
-  data.tar.gz: 9210a75137622829403d8b6ae47dfa1f51e3f71462313b12ef076e6b240391a9
+  metadata.gz: 9fc744443078d2ffab4156204b7921ef617c3788d373253956a0fe9f3455a14a
+  data.tar.gz: 133c334403bb3a2655f61ab7c14f8d9d75c9e3adf5212f9bdf7e69811a2cda2a
 SHA512:
-  metadata.gz: 00ab26917b2ad3ab3af835ec58842b1fa75ba19d61254447466a5eee7b5db388f9c5800ec7807806fd737526772516f43277520ba1005d18539a8e54356f0ee8
-  data.tar.gz: '038338c9aca83500340f85e0d6d2e6247466701739ff3606ae8bf59905f930541514e9e3130ac5296b9ee658085993c601126d84ee5e6527451b4ba1d75df1ab'
+  metadata.gz: 96e5622f76bf23b2df6be9663542fb0db5da070f40480e6649960da33d336c14afcafc36c308b5dad867fa4ce90ab3faf574c3c956011c330c7599713cf3afe2
+  data.tar.gz: 640539d3b260f4b50de92bddca66ed45a794c0c54c722d32d807134eee505d06f737542d077403ab71f5699f23e106567d1bf19dfb4954420398904e9cd756e2

data/CHANGELOG.md

@@ -7,6 +7,52 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] — 2026-06-02
+
+### Added
+- OAuth 2.0 authentication via the **client credentials** grant. Configure
+  `client_id` / `client_secret` (on `Boldsign.configure` or `Client.new`) and
+  the client fetches a bearer token from the region's account host
+  (`https://account.boldsign.com/connect/token` for `:us`), caches it until
+  shortly before `expires_in` lapses, and sends `Authorization: Bearer …`
+  instead of `X-API-KEY`. Token fetches are mutex-guarded for shared clients.
+- `scope:` (defaults to `BoldSign.Documents.All`) and `token_url:` options to
+  override the requested scope and token endpoint.
+- `access_token:` option to supply a pre-obtained bearer token that is used
+  as-is (not refreshed).
+- `Boldsign::AccessToken` encapsulating the client-credentials token lifecycle.
+- `TOKEN_REGIONS` / `DEFAULT_TOKEN_BASE_URL` constants and `Client#auth_mode`.
+
+### Changed
+- `Client.new` no longer requires an API key. It accepts any one of
+  `client_id`/`client_secret`, `access_token`, or `api_key`, and raises
+  `ConfigurationError` only when none is provided. The API-key path is
+  unchanged, so existing `api_key:` callers keep working.
+
+## [0.4.0] — 2026-05-22
+
+### Changed
+- Request body hash keys are now recursively converted to **camelCase** (not
+  PascalCase). This matches the casing used by the BoldSign OpenAPI/Swagger
+  schema for all request body DTOs, including nested objects like
+  `DocumentSigner` and `FormField`. Callers pass idiomatic snake_case (or
+  camelCase / PascalCase) Ruby keys and the gem emits the casing BoldSign
+  validates against. **Breaking** for callers that relied on the 0.3.0
+  PascalCase output.
+- Multipart file uploads are still keyed `Files` (capital F) for the
+  document send endpoint; only request body field names are camelCased.
+- Multipart `send_document`: single-element arrays for both `signers:` and
+  `files:` are now unwrapped before encoding. BoldSign's POST
+  `/v1/document/send` rejects `signers=[{...}]` (JSON-array string) and
+  `Files[]=…` (Faraday's automatic array-bracket form). The gem now emits
+  `signers={...}` (single JSON object) and `Files=<file>` (single FilePart)
+  for the one-signer/one-file case. Multi-signer / multi-file uploads are
+  not yet supported via this helper and raise `NotImplementedError`.
+
+### Removed
+- `Boldsign::CaseConvert.pascalize` / `.pascalize_key`. Replaced by
+  `.camelize` / `.camelize_key`.
+
 ## [0.3.0] — 2026-05-22
 
 ### Changed
@@ -44,5 +90,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 100% line and branch test coverage enforced via SimpleCov.
 - GitHub Actions CI on Ruby 3.4 and 4.0.
 
-[Unreleased]: https://github.com/kleinjm/boldsign-ruby/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/kleinjm/boldsign-ruby/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/kleinjm/boldsign-ruby/compare/v0.4.0...v0.5.0
 [0.1.0]: https://github.com/kleinjm/boldsign-ruby/releases/tag/v0.1.0

data/README.md

@@ -17,6 +17,32 @@ gem "boldsign"
 
 ## Configuration
 
+The client authenticates with either an API key or OAuth 2.0.
+
+### OAuth 2.0 (client credentials)
+
+Register an OAuth app in the BoldSign dashboard (API → OAuth Apps) and configure
+its `client_id` / `client_secret`. The client fetches a bearer token from the
+region's account host, caches it until shortly before it expires, and refreshes
+automatically — no token plumbing on your side.
+
+```ruby
+Boldsign.configure do |c|
+  c.client_id     = ENV["BOLDSIGN_CLIENT_ID"]
+  c.client_secret = ENV["BOLDSIGN_CLIENT_SECRET"]
+  c.region        = :us   # :us, :eu, :ca, :au
+  # c.scope       = "BoldSign.Documents.All"  # optional; empty grants all the app allows
+end
+```
+
+You can also pass a token you obtained yourself (used as-is, not refreshed):
+
+```ruby
+Boldsign::Client.new(access_token: "…", region: :us)
+```
+
+### API key
+
 ```ruby
 Boldsign.configure do |c|
   c.api_key = ENV["BOLDSIGN_API_KEY"]
@@ -30,14 +56,17 @@ Or instantiate a client directly:
 client = Boldsign::Client.new(api_key: "…", region: :us)
 ```
 
-Region base URLs:
+Region hosts:
+
+| Region | API base URL | OAuth account host |
+| ------ | ------------ | ------------------ |
+| `:us`  | `https://api.boldsign.com` | `https://account.boldsign.com` |
+| `:eu`  | `https://api-eu.boldsign.com` | `https://account-eu.boldsign.com` |
+| `:ca`  | `https://api-ca.boldsign.com` | `https://account-ca.boldsign.com` |
+| `:au`  | `https://api-au.boldsign.com` | `https://account-au.boldsign.com` |
 
-| Region | URL |
-| ------ | --- |
-| `:us`  | `https://api.boldsign.com` |
-| `:eu`  | `https://api-eu.boldsign.com` |
-| `:ca`  | `https://api-ca.boldsign.com` |
-| `:au`  | `https://api-au.boldsign.com` |
+The token endpoint is the account host + `/connect/token`; override the full URL
+with `token_url:` if a region differs.
 
 ## Usage
 

data/lib/boldsign/access_token.rb

@@ -0,0 +1,95 @@
+module Boldsign
+  # Fetches and caches an OAuth 2.0 access token using the client credentials
+  # grant (server-to-server; no user interaction).
+  #
+  # A single instance is shared by a {Client} and may be hit from multiple
+  # threads, so token reads/refreshes are guarded by a mutex. The token is
+  # cached until shortly before it expires ({EXPIRY_LEEWAY_SECONDS}), then a new
+  # one is requested on the next call. The client credentials grant does not
+  # issue refresh tokens — expiry is handled by re-requesting.
+  #
+  # @see https://developers.boldsign.com/authentication/oauth-2-0/
+  class AccessToken
+    # Token endpoint path, appended to the region's account host.
+    TOKEN_PATH = "/connect/token".freeze
+
+    # Default scope requested for the access token. Covers the document /
+    # signature endpoints this gem is primarily used for. Pass a different
+    # `scope:` to request others (an empty scope grants all the app is allowed).
+    DEFAULT_SCOPE = "BoldSign.Documents.All".freeze
+
+    # Refresh this many seconds before the token actually expires, so an
+    # in-flight request never carries a token that lapses server-side mid-call.
+    EXPIRY_LEEWAY_SECONDS = 60
+
+    # Fallback lifetime (seconds) when the token response omits `expires_in`.
+    DEFAULT_EXPIRES_IN = 3600
+
+    # @param client_id [String] OAuth app client ID.
+    # @param client_secret [String] OAuth app client secret.
+    # @param token_url [String] Full token endpoint URL (host + {TOKEN_PATH}).
+    # @param scope [String] OAuth scope to request.
+    # @param adapter [Symbol] Faraday adapter.
+    def initialize(client_id:, client_secret:, token_url:, scope: DEFAULT_SCOPE,
+                   adapter: Faraday.default_adapter)
+      @client_id = client_id
+      @client_secret = client_secret
+      @token_url = token_url
+      @scope = scope
+      @adapter = adapter
+      @mutex = Mutex.new
+    end
+
+    # @return [String] a currently-valid bearer token, fetching or refreshing
+    #   one if the cached token is missing or near expiry.
+    def value
+      @mutex.synchronize do
+        refresh! if expired?
+        @token
+      end
+    end
+
+    private
+
+    def expired?
+      @token.nil? || Time.now >= @expires_at
+    end
+
+    def refresh!
+      response = connection.post(@token_url) do |req|
+        req.headers["Content-Type"] = "application/x-www-form-urlencoded"
+        req.body = URI.encode_www_form(
+          grant_type: "client_credentials",
+          client_id: @client_id,
+          client_secret: @client_secret,
+          scope: @scope
+        )
+      end
+      raise_token_error(response) unless response.success?
+
+      body = JSON.parse(response.body)
+      @token = body["access_token"]
+      expires_in = (body["expires_in"] || DEFAULT_EXPIRES_IN).to_i
+      @expires_at = Time.now + expires_in - EXPIRY_LEEWAY_SECONDS
+    end
+
+    def connection
+      Faraday.new do |f|
+        f.adapter @adapter
+      end
+    end
+
+    def raise_token_error(response)
+      body = begin
+        JSON.parse(response.body)
+      rescue StandardError
+        response.body
+      end
+      message = body.is_a?(Hash) ? (body["error_description"] || body["error"] || body.to_s) : body.to_s
+      raise AuthenticationError.new(
+        "BoldSign OAuth token request failed (#{response.status}): #{message}",
+        status: response.status, body: body, response: response
+      )
+    end
+  end
+end

data/lib/boldsign/case_convert.rb

@@ -1,36 +1,39 @@
 module Boldsign
-  # Converts arbitrary Ruby hash keys (snake_case or camelCase, Symbol or
-  # String) to PascalCase string keys recursively, matching the casing the
-  # BoldSign REST API expects in request bodies. Non-Hash and non-Array values
-  # — including binary IO objects, FilePart instances, scalars, dates, etc. —
-  # pass through untouched.
+  # Converts arbitrary Ruby hash keys (snake_case, camelCase, or PascalCase;
+  # Symbol or String) to camelCase string keys recursively, matching the
+  # casing the BoldSign REST API expects in request bodies. Non-Hash and
+  # non-Array values — including binary IO objects, FilePart instances,
+  # scalars, dates, etc. — pass through untouched.
   module CaseConvert
     module_function
 
-    # Recursively PascalCase every Hash key reachable from `obj`.
+    # Recursively camelCase every Hash key reachable from `obj`.
     # @param obj [Object]
-    # @return [Object] new object with the same shape and PascalCase keys
-    def pascalize(obj)
+    # @return [Object] new object with the same shape and camelCase keys
+    def camelize(obj)
       case obj
       when Hash
-        obj.each_with_object({}) { |(k, v), acc| acc[pascalize_key(k)] = pascalize(v) }
+        obj.each_with_object({}) { |(k, v), acc| acc[camelize_key(k)] = camelize(v) }
       when Array
-        obj.map { |v| pascalize(v) }
+        obj.map { |v| camelize(v) }
       else
         obj
       end
     end
 
     # @param key [String, Symbol]
-    # @return [String] PascalCase string
-    def pascalize_key(key)
+    # @return [String] camelCase string
+    def camelize_key(key)
       str = key.to_s
       return str if str.empty?
 
       if str.include?("_")
-        str.split("_").map { |part| capitalize_word(part) }.join
+        parts = str.split("_").reject(&:empty?)
+        return str if parts.empty?
+
+        ([parts.first.downcase] + parts.drop(1).map { |part| capitalize_word(part) }).join
       else
-        capitalize_word(str)
+        lowercase_first(str)
       end
     end
 
@@ -39,5 +42,11 @@ module Boldsign
 
       str[0].upcase + str[1..]
     end
+
+    def lowercase_first(str)
+      return str if str.empty?
+
+      str[0].downcase + str[1..]
+    end
   end
 end

data/lib/boldsign/client.rb

@@ -8,9 +8,21 @@ module Boldsign
   # Low-level verb methods ({#get}, {#post}, {#put}, {#patch}, {#delete},
   # {#download}) are also available for hitting any endpoint directly.
   #
-  # @example
+  # Authenticates with either an API key (`X-API-KEY`) or OAuth 2.0
+  # (`Authorization: Bearer`). For OAuth, pass `client_id`/`client_secret` and
+  # the client fetches + caches a token via the client credentials grant; or
+  # pass a `access_token` you obtained yourself.
+  #
+  # @example API key
   #   client = Boldsign::Client.new(api_key: ENV["BOLDSIGN_API_KEY"], region: :us)
   #   client.documents.send_document(title: "NDA", signers: [...])
+  #
+  # @example OAuth client credentials
+  #   client = Boldsign::Client.new(
+  #     client_id: ENV["BOLDSIGN_CLIENT_ID"],
+  #     client_secret: ENV["BOLDSIGN_CLIENT_SECRET"],
+  #     region: :us
+  #   )
   class Client
     # Default region (US).
     DEFAULT_BASE_URL = "https://api.boldsign.com".freeze
@@ -18,25 +30,50 @@ module Boldsign
     # User-Agent header value sent on every request.
     USER_AGENT = "boldsign-ruby/#{Boldsign::VERSION}".freeze
 
-    # @return [String] the API key in use.
+    # @return [String, nil] the API key in use, when authenticating via API key.
     attr_reader :api_key
 
+    # @return [Symbol] the resolved auth mode (`:api_key`, `:oauth`, or `:bearer`).
+    attr_reader :auth_mode
+
     # @return [String] the resolved base URL (region or explicit override).
     attr_reader :base_url
 
     # @param api_key [String, nil] BoldSign API key. Falls back to `ENV["BOLDSIGN_API_KEY"]`.
-    # @param region [Symbol, nil] One of `:us`, `:eu`, `:ca`, `:au`. Ignored if `base_url` is given.
-    # @param base_url [String, nil] Explicit base URL override.
+    # @param client_id [String, nil] OAuth app client ID (enables the client credentials grant).
+    # @param client_secret [String, nil] OAuth app client secret (required with `client_id`).
+    # @param access_token [String, nil] A pre-obtained OAuth bearer token (used as-is, not refreshed).
+    # @param scope [String, nil] OAuth scope to request (defaults to {AccessToken::DEFAULT_SCOPE}).
+    # @param token_url [String, nil] Override for the full OAuth token endpoint URL.
+    # @param region [Symbol, nil] One of `:us`, `:eu`, `:ca`, `:au`. Ignored if `base_url`/`token_url` is given.
+    # @param base_url [String, nil] Explicit API base URL override.
     # @param adapter [Symbol] Faraday adapter (defaults to `Faraday.default_adapter`).
     # @param logger [Logger, nil] Optional logger; when present, Faraday's logger middleware is enabled.
-    # @raise [ConfigurationError] when no API key is available.
-    def initialize(api_key: nil, region: nil, base_url: nil, adapter: Faraday.default_adapter, logger: nil)
+    # @raise [ConfigurationError] when no usable credentials are provided.
+    def initialize(api_key: nil, client_id: nil, client_secret: nil, access_token: nil,
+                   scope: nil, token_url: nil, region: nil, base_url: nil,
+                   adapter: Faraday.default_adapter, logger: nil)
       @api_key = api_key || ENV["BOLDSIGN_API_KEY"]
-      raise ConfigurationError, "Missing BoldSign API key" if @api_key.nil? || @api_key.empty?
-
+      @static_access_token = access_token
       @base_url = base_url || Boldsign::REGIONS[region&.to_sym] || DEFAULT_BASE_URL
       @adapter = adapter
       @logger = logger
+
+      if present?(client_id) && present?(client_secret)
+        @auth_mode = :oauth
+        @access_token = AccessToken.new(
+          client_id: client_id, client_secret: client_secret,
+          token_url: token_url || default_token_url(region),
+          scope: scope || AccessToken::DEFAULT_SCOPE, adapter: adapter
+        )
+      elsif present?(@static_access_token)
+        @auth_mode = :bearer
+      elsif present?(@api_key)
+        @auth_mode = :api_key
+      else
+        raise ConfigurationError,
+              "Missing BoldSign credentials: provide client_id/client_secret, access_token, or api_key"
+      end
     end
 
     # @return [Resources::Brand]
@@ -125,7 +162,7 @@ module Boldsign
             req.body = body
           else
             req.headers["Content-Type"] = "application/json"
-            req.body = body.is_a?(String) ? body : JSON.generate(CaseConvert.pascalize(body))
+            req.body = body.is_a?(String) ? body : JSON.generate(CaseConvert.camelize(body))
           end
         end
       end
@@ -137,7 +174,7 @@ module Boldsign
       Faraday.new(url: @base_url) do |f|
         f.request :multipart if multipart
         f.request :url_encoded
-        f.headers["X-API-KEY"] = @api_key
+        apply_auth(f.headers)
         f.headers["Accept"] = "application/json"
         f.headers["User-Agent"] = USER_AGENT
         f.response :logger, @logger if @logger
@@ -145,6 +182,27 @@ module Boldsign
       end
     end
 
+    def apply_auth(headers)
+      if @auth_mode == :api_key
+        headers["X-API-KEY"] = @api_key
+      else
+        headers["Authorization"] = "Bearer #{bearer_token}"
+      end
+    end
+
+    def bearer_token
+      @auth_mode == :oauth ? @access_token.value : @static_access_token
+    end
+
+    def present?(value)
+      !value.nil? && !value.empty?
+    end
+
+    def default_token_url(region)
+      base = Boldsign::TOKEN_REGIONS[region&.to_sym] || Boldsign::DEFAULT_TOKEN_BASE_URL
+      "#{base}#{AccessToken::TOKEN_PATH}"
+    end
+
     def parse_body(response)
       return nil if response.body.nil? || response.body.empty?
       content_type = response.headers["content-type"].to_s

data/lib/boldsign/resources/document.rb

@@ -73,21 +73,36 @@ module Boldsign
 
       private
 
+      # BoldSign's POST /v1/document/send multipart endpoint is fussy about
+      # repeated/array-valued parts. Single signers must be sent as one
+      # multipart part whose value is the signer JSON OBJECT (not a JSON array
+      # containing one object). Files must be sent as a single FilePart value
+      # for one upload; Faraday's automatic `Files[]` bracketing breaks the
+      # request. For the single-signer, single-file flow (the common case) we
+      # unwrap one-element arrays here. Multi-signer / multi-file is not yet
+      # supported via this helper and will raise.
       def multipart_send_body(body, files)
         parts = body.each_with_object({}) do |(key, value), acc|
           next if value.nil?
 
-          pascal_key = Boldsign::CaseConvert.pascalize_key(key)
-          acc[pascal_key] = if scalar?(value)
-                              value.to_s
-                            else
-                              JSON.generate(Boldsign::CaseConvert.pascalize(value))
-                            end
+          camel_key = Boldsign::CaseConvert.camelize_key(key)
+          acc[camel_key] = encode_multipart_value(value)
         end
-        parts["Files"] = Array(files).map { |f| file_part(f) }
+        files_array = Array(files)
+        raise NotImplementedError, "multi-file uploads are not supported yet" if files_array.size > 1
+
+        parts["Files"] = file_part(files_array.first)
         parts
       end
 
+      def encode_multipart_value(value)
+        return value.to_s if scalar?(value)
+        return JSON.generate(Boldsign::CaseConvert.camelize(value)) unless value.is_a?(Array)
+        raise NotImplementedError, "multi-element arrays are not supported in multipart bodies yet" if value.size > 1
+
+        JSON.generate(Boldsign::CaseConvert.camelize(value.first))
+      end
+
       def file_part(file)
         return file if file.is_a?(Faraday::Multipart::FilePart)
 

data/lib/boldsign/version.rb

@@ -1,3 +1,3 @@
 module Boldsign
-  VERSION = "0.3.0"
+  VERSION = "0.5.0"
 end

data/lib/boldsign.rb

@@ -1,10 +1,12 @@
 require "faraday"
 require "faraday/multipart"
 require "json"
+require "uri"
 
 require_relative "boldsign/version"
 require_relative "boldsign/error"
 require_relative "boldsign/case_convert"
+require_relative "boldsign/access_token"
 require_relative "boldsign/client"
 require_relative "boldsign/resource"
 require_relative "boldsign/resources/brand"
@@ -24,10 +26,11 @@ require_relative "boldsign/resources/user"
 # Configure once at boot and access a shared {Client} via {Boldsign.client}, or
 # instantiate {Client} directly when you need multiple credentials/regions.
 #
-# @example Configure and use the shared client
+# @example Configure with OAuth and use the shared client
 #   Boldsign.configure do |c|
-#     c.api_key = ENV["BOLDSIGN_API_KEY"]
-#     c.region  = :us
+#     c.client_id     = ENV["BOLDSIGN_CLIENT_ID"]
+#     c.client_secret = ENV["BOLDSIGN_CLIENT_SECRET"]
+#     c.region        = :us
 #   end
 #   Boldsign.client.documents.list
 module Boldsign
@@ -39,10 +42,37 @@ module Boldsign
     au: "https://api-au.boldsign.com"
   }.freeze
 
+  # Region → account host map for the OAuth token endpoint. Non-US hosts follow
+  # BoldSign's regional naming; override with `token_url:` if a region differs.
+  TOKEN_REGIONS = {
+    us: "https://account.boldsign.com",
+    eu: "https://account-eu.boldsign.com",
+    ca: "https://account-ca.boldsign.com",
+    au: "https://account-au.boldsign.com"
+  }.freeze
+
+  # Default account host (US) for the OAuth token endpoint.
+  DEFAULT_TOKEN_BASE_URL = "https://account.boldsign.com".freeze
+
   class << self
     # @return [String, nil] API key used by the shared {client}.
     attr_accessor :api_key
 
+    # @return [String, nil] OAuth app client ID used by the shared {client}.
+    attr_accessor :client_id
+
+    # @return [String, nil] OAuth app client secret used by the shared {client}.
+    attr_accessor :client_secret
+
+    # @return [String, nil] Pre-obtained OAuth bearer token (used as-is, not refreshed).
+    attr_accessor :access_token
+
+    # @return [String, nil] OAuth scope to request (defaults to {AccessToken::DEFAULT_SCOPE}).
+    attr_accessor :scope
+
+    # @return [String, nil] Override for the full OAuth token endpoint URL.
+    attr_accessor :token_url
+
     # @return [Symbol, nil] Region key (`:us`, `:eu`, `:ca`, `:au`).
     attr_accessor :region
 
@@ -58,7 +88,11 @@ module Boldsign
 
     # @return [Client] memoized shared client built from module-level config.
     def client
-      @client ||= Client.new(api_key: api_key, region: region, base_url: base_url)
+      @client ||= Client.new(
+        api_key: api_key, client_id: client_id, client_secret: client_secret,
+        access_token: access_token, scope: scope, token_url: token_url,
+        region: region, base_url: base_url
+      )
     end
 
     # Clears the memoized shared client so the next call to {client} rebuilds it.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: boldsign
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - James Klein
@@ -92,6 +92,7 @@ files:
 - README.md
 - boldsign.gemspec
 - lib/boldsign.rb
+- lib/boldsign/access_token.rb
 - lib/boldsign/case_convert.rb
 - lib/boldsign/client.rb
 - lib/boldsign/error.rb