assinafy 1.5.0

data/lib/assinafy/client.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+module Assinafy
+  # Top-level entry point for the Assinafy Ruby SDK.
+  #
+  # A Client owns a single Faraday connection (with shared auth headers,
+  # timeouts, and User-Agent) and exposes one resource accessor per
+  # documented API surface.
+  #
+  # @example Construct from positional args
+  #   client = Assinafy::Client.create(ENV['ASSINAFY_API_KEY'], ENV['ASSINAFY_ACCOUNT_ID'])
+  #
+  # @example Construct from a config Hash (e.g. parsed YAML/JSON)
+  #   client = Assinafy::Client.from_config(api_key: '...', account_id: '...')
+  #
+  # @see https://api.assinafy.com.br/v1/docs
+  class Client
+    # @return [Resources::AuthResource]
+    attr_reader :auth
+    # @return [Resources::AccountResource]
+    attr_reader :accounts
+    # @return [Resources::UserResource]
+    attr_reader :users
+    # @return [Resources::DocumentResource]
+    attr_reader :documents
+    # @return [Resources::SignerResource]
+    attr_reader :signers
+    # @return [Resources::SignerDocumentResource]
+    attr_reader :signer_documents
+    # @return [Resources::AssignmentResource]
+    attr_reader :assignments
+    # @return [Resources::WebhookResource]
+    attr_reader :webhooks
+    # @return [Resources::TemplateResource]
+    attr_reader :templates
+    # @return [Resources::FieldResource]
+    attr_reader :fields
+    # @return [Resources::TagResource]
+    attr_reader :tags
+    # @return [Support::WebhookVerifier]
+    attr_reader :webhook_verifier
+
+    # @param api_key        [String, nil] sent as `X-Api-Key`
+    # @param token          [String, nil] legacy session token; sent as
+    #   `Authorization: Bearer ...` when no `api_key` is given
+    # @param account_id     [String, nil] default workspace ID for account-scoped
+    #   resources; those methods document their supported per-call overrides
+    # @param base_url       [String]
+    # @param webhook_secret [String, nil] secret for {Support::WebhookVerifier}
+    # @param timeout        [Integer] Faraday read/open timeout in seconds
+    # @param logger         [Logger, nil] receives info-level lifecycle messages
+    #
+    # @example Build a client and reach a resource accessor (no network call)
+    #   client = Assinafy::Client.new(api_key: 'example_api_key', account_id: 'account_example')
+    #   client.documents #=> #<Assinafy::Resources::DocumentResource ...>
+    def initialize(api_key: nil, token: nil, account_id: nil,
+                   base_url: Configuration::DEFAULT_BASE_URL,
+                   webhook_secret: nil,
+                   timeout: Configuration::DEFAULT_TIMEOUT,
+                   logger: nil)
+      config = Configuration.new(
+        api_key: api_key, token: token, account_id: account_id,
+        base_url: base_url, webhook_secret: webhook_secret,
+        timeout: timeout, logger: logger
+      )
+
+      @connection = build_connection(config)
+      @logger     = config.logger || NullLogger.new
+
+      @auth             = Resources::AuthResource.new(@connection, nil, @logger)
+      @accounts         = Resources::AccountResource.new(@connection, account_id, @logger)
+      @users            = Resources::UserResource.new(@connection, nil, @logger)
+      @documents        = Resources::DocumentResource.new(@connection, account_id, @logger)
+      @signers          = Resources::SignerResource.new(@connection, account_id, @logger)
+      @signer_documents = Resources::SignerDocumentResource.new(@connection, nil, @logger)
+      @assignments      = Resources::AssignmentResource.new(@connection, account_id, @logger)
+      @webhooks         = Resources::WebhookResource.new(@connection, account_id, @logger)
+      @templates        = Resources::TemplateResource.new(@connection, account_id, @logger)
+      @fields           = Resources::FieldResource.new(@connection, account_id, @logger)
+      @tags             = Resources::TagResource.new(@connection, account_id, @logger)
+      @webhook_verifier = Support::WebhookVerifier.new(webhook_secret)
+    end
+
+    # Convenience constructor with positional `api_key`/`account_id`.
+    #
+    # @param api_key    [String]
+    # @param account_id [String]
+    # @param options    [Hash] forwarded to {#initialize}
+    # @return [Client]
+    #
+    # @example Construct with positional credentials and an optional webhook secret
+    #   client = Assinafy::Client.create('example_api_key', 'account_example', webhook_secret: 'gateway_secret')
+    #   client #=> #<Assinafy::Client ...>
+    def self.create(api_key, account_id, **options)
+      new(api_key: api_key, account_id: account_id, **options)
+    end
+
+    # Build a Client from a Hash (string or symbol keys).
+    # Useful for credentials loaded from YAML/JSON.
+    #
+    # @param config [Hash]
+    # @return [Client]
+    #
+    # @example Build from a credentials Hash loaded from YAML/JSON (string or symbol keys both work)
+    #   creds  = YAML.load_file('config/assinafy.yml') # { 'api_key' => '...', 'account_id' => '...' }
+    #   client = Assinafy::Client.from_config(creds)
+    #   client #=> #<Assinafy::Client ...>
+    def self.from_config(config)
+      from_hash(config)
+    end
+
+    # Alias of {.from_config} for symmetry with {Configuration.from_hash}.
+    #
+    # @param config [Hash]
+    # @return [Client]
+    #
+    # @example Build from a symbol-keyed Hash
+    #   client = Assinafy::Client.from_hash(api_key: 'example_api_key', account_id: 'account_example')
+    #   client #=> #<Assinafy::Client ...>
+    def self.from_hash(config)
+      cfg = Configuration.from_hash(config)
+      new(
+        api_key:        cfg.api_key,
+        token:          cfg.token,
+        account_id:     cfg.account_id,
+        base_url:       cfg.base_url,
+        webhook_secret: cfg.webhook_secret,
+        timeout:        cfg.timeout,
+        logger:         cfg.logger
+      )
+    end
+
+    # High-level helper that bundles the most common workflow:
+    # upload PDF → (optionally wait for metadata) → create signers → create a
+    # virtual assignment for them.
+    #
+    # @param source         [String, Hash]   see {Resources::DocumentResource#upload}
+    # @param signers        [Array<Hash>]    see {Resources::SignerResource#create}
+    # @param message        [String, nil]
+    # @param wait_for_ready [Boolean]        poll until the document is metadata-ready (default true)
+    # @param expires_at     [String, nil]    ISO 8601 expiration for the assignment
+    # @param copy_receivers [Array<String>, nil] signer IDs that only receive copies
+    # @param account_id     [String, nil]    override the client default
+    # @return [Hash{Symbol=>Object}] `{ document: {Hash}, assignment: {Hash}, signer_ids: [String, ...] }`
+    #   where `document` is the (unwrapped) document payload, `assignment` is the (unwrapped) virtual
+    #   assignment, and `signer_ids` lists the IDs of the signers created during the workflow.
+    # @note This helper is not transactional. If a later API call fails, an uploaded
+    #   document or newly created signer may remain and should be cleaned up by the caller.
+    #
+    # @example Upload a PDF and request a virtual signature from one signer
+    #   result = client.upload_and_request_signatures(
+    #     source:  '/path/to/contract.pdf',
+    #     signers: [{ full_name: 'Example Signer', email: 'signer@example.com' }],
+    #     message: 'Please review and sign'
+    #   )
+    #
+    #   # Under the hood the SDK uploads the file, then POSTs this JSON body to
+    #   # POST /documents/{document_id}/assignments (nil optional fields are dropped):
+    #   #   {
+    #   #     "method": "virtual",
+    #   #     "signers": [{ "id": "19e6b92e7895332ed9708535d8c" }],
+    #   #     "message": "Please review and sign"
+    #   #   }
+    #
+    #   # Returned (unwrapped) Hash:
+    #   result
+    #   #=> {
+    #   #     document: {
+    #   #       "resource" => "document", "id" => "1032009d72b364f377ff270405cc",
+    #   #       "account_id" => "account_example", "name" => "contract.pdf",
+    #   #       "status" => "metadata_ready",
+    #   #       "artifacts" => { "original" => "https://.../download/original", "thumbnail" => "https://..." },
+    #   #       "tags" => [], "pages" => [{ "id" => "...", "number" => 1, "height" => 1651, "width" => 1275 }]
+    #   #       # ... (see docs for full shape)
+    #   #     },
+    #   #     assignment: {
+    #   #       "resource" => "assignment", "id" => "19e99aa0633e32ac13f845c08db",
+    #   #       "sender_email" => "sender@example.com", "method" => "virtual",
+    #   #       "expires_at" => nil, "message" => "Please review and sign",
+    #   #       "signers" => [{ "id" => "19e6b92e7895332ed9708535d8c", "full_name" => "Example Signer",
+    #   #                       "email" => "signer@example.com", "completed" => false, "step" => 1 }],
+    #   #       "copy_receivers" => [], "items" => [{ "id" => "103200a43e372db16f48a6f0f2d4", "completed" => false }],
+    #   #       "summary" => { "signer_count" => 1, "completed_count" => 0 },
+    #   #       "signing_urls" => [{ "signer_id" => "19e6b92e7895332ed9708535d8c", "url" => "https://.../sign/..." }]
+    #   #       # ... (see docs for full shape)
+    #   #     },
+    #   #     signer_ids: ["19e6b92e7895332ed9708535d8c"]
+    #   #   }
+    def upload_and_request_signatures(source:, signers:, message: nil,
+                                      wait_for_ready: true, expires_at: nil,
+                                      copy_receivers: nil, account_id: nil)
+      unless signers.is_a?(Array) && !signers.empty? && signers.all?(Hash)
+        raise ValidationError.new('Signers must be a non-empty Array of Hashes')
+      end
+
+      @logger.info("Starting upload and signature workflow for #{signers.length} signer(s)")
+
+      upload_opts = account_id.nil? ? {} : { account_id: account_id }
+      document = @documents.upload(source, upload_opts)
+      document = @documents.wait_until_ready(document['id']) if wait_for_ready
+
+      signer_ids = signers.map do |signer|
+        created = @signers.create(signer, account_id)
+        created['id'] || raise(ApiError.new('Signer created but the API returned no ID', 502, created))
+      end
+
+      assignment_payload = { method: 'virtual', signers: signer_ids,
+                             message: message, expires_at: expires_at,
+                             copy_receivers: copy_receivers }
+      assignment = @assignments.create(document['id'], assignment_payload)
+
+      @logger.info("Upload and signature workflow completed for document #{document['id']}")
+
+      { document: document, assignment: assignment, signer_ids: signer_ids }
+    end
+
+    # Expose the underlying Faraday connection (for advanced use cases,
+    # such as adding middleware or inspecting headers in tests).
+    #
+    # @return [Faraday::Connection]
+    #
+    # @example Inspect the auth header the SDK sends
+    #   client = Assinafy::Client.new(api_key: 'example_api_key', account_id: 'account_example')
+    #   client.faraday_connection.headers['X-Api-Key'] #=> "example_api_key"
+    def faraday_connection
+      @connection
+    end
+
+    private
+
+    def build_connection(config)
+      Faraday.new(url: config.base_url) do |f|
+        f.request :multipart
+        f.request :json
+        f.response :json, content_type: /\bjson/
+        f.options.timeout      = config.timeout
+        f.options.open_timeout = config.timeout
+        f.headers.merge!(config.auth_headers)
+        f.headers['Accept']       = 'application/json'
+        f.headers['User-Agent']   = "assinafy-ruby-sdk/#{VERSION}"
+        f.adapter Faraday.default_adapter
+      end
+    end
+  end
+end

data/lib/assinafy/configuration.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require_relative 'errors'
+
+module Assinafy
+  # SDK configuration values. {Client} snapshots these values when it builds
+  # its connection; construct a new client after changing a configuration.
+  #
+  # @example Build from a YAML-style hash (e.g. loaded from config/assinafy.yml)
+  #   raw = YAML.load_file('config/assinafy.yml') # => string-keyed Hash
+  #   # raw => {
+  #   #   "api_key"        => "example_api_key",
+  #   #   "account_id"     => "account_example",
+  #   #   "base_url"       => "https://api.assinafy.com.br/v1",
+  #   #   "webhook_secret" => "gateway_secret",
+  #   #   "timeout"        => 30
+  #   # }
+  #   config = Assinafy::Configuration.from_hash(raw)
+  #   config.api_key      # => "example_api_key"
+  #   config.account_id   # => "account_example"
+  #   config.auth_headers # => { "X-Api-Key" => "example_api_key" }
+  class Configuration
+    # Default base URL (production v1 API).
+    DEFAULT_BASE_URL = 'https://api.assinafy.com.br/v1'
+    # Default Faraday open/read timeout, in seconds.
+    DEFAULT_TIMEOUT  = 30
+
+    # @!attribute [rw] api_key
+    #   @return [String, nil] sent as `X-Api-Key`
+    # @!attribute [rw] token
+    #   @return [String, nil] legacy bearer token (used when `api_key` is nil)
+    # @!attribute [rw] account_id
+    #   @return [String, nil] default workspace ID
+    # @!attribute [rw] base_url
+    #   @return [String] API base URL (trailing slash stripped)
+    # @!attribute [rw] webhook_secret
+    #   @return [String, nil] secret for {Support::WebhookVerifier}
+    # @!attribute [rw] timeout
+    #   @return [Integer] Faraday timeout in seconds
+    # @!attribute [rw] logger
+    #   @return [Logger, nil]
+    attr_accessor :api_key, :token, :account_id, :base_url, :webhook_secret, :timeout, :logger
+
+    # Build a configuration directly from keyword arguments. Prefer passing
+    # `api_key` (the documented `X-Api-Key` mechanism); `token` is the legacy
+    # bearer fallback. `base_url` has its trailing slash stripped on assignment.
+    #
+    # @param api_key [String, nil] sent as the `X-Api-Key` header
+    # @param token [String, nil] legacy bearer token (used only when `api_key` is nil)
+    # @param account_id [String, nil] default workspace account ID
+    # @param base_url [String] API base URL (trailing slash is stripped)
+    # @param webhook_secret [String, nil] secret for {Support::WebhookVerifier}
+    # @param timeout [Integer] Faraday open/read timeout in seconds
+    # @param logger [Logger, nil] optional logger for Faraday
+    #
+    # @example Construct with an API key (omits the default base_url)
+    #   config = Assinafy::Configuration.new(
+    #     api_key:    'example_api_key',
+    #     account_id: 'account_example'
+    #   )
+    #   config.base_url     # => "https://api.assinafy.com.br/v1"
+    #   config.timeout      # => 30
+    #   config.auth_headers # => { "X-Api-Key" => "example_api_key" }
+    #
+    # @example Trailing slash on base_url is stripped
+    #   Assinafy::Configuration.new(base_url: 'https://api.assinafy.com.br/v1/').base_url
+    #   # => "https://api.assinafy.com.br/v1"
+    def initialize(api_key: nil, token: nil, account_id: nil,
+                   base_url: DEFAULT_BASE_URL, webhook_secret: nil,
+                   timeout: DEFAULT_TIMEOUT, logger: nil)
+      @api_key        = api_key
+      @token          = token
+      @account_id     = account_id
+      raise ValidationError.new('Base URL is required') unless base_url.is_a?(String)
+
+      @base_url = base_url.strip.sub(%r{/+\z}, '')
+      raise ValidationError.new('Base URL is required') if @base_url.empty?
+
+      @webhook_secret = webhook_secret
+      @timeout        = normalize_timeout(timeout)
+      @logger         = logger
+    end
+
+    # Build a {Configuration} from a Hash with string or symbol keys.
+    # Accepts both `'token'` and `'access_token'` for backwards compatibility.
+    # Missing keys fall back to defaults (`base_url` => {DEFAULT_BASE_URL},
+    # `timeout` => {DEFAULT_TIMEOUT}); numeric strings are accepted, while
+    # invalid and non-positive values raise {ValidationError}.
+    #
+    # @param hash [Hash{String,Symbol=>Object}]
+    # @return [Configuration]
+    #
+    # @example Symbol-keyed hash with the legacy access_token alias
+    #   config = Assinafy::Configuration.from_hash(
+    #     access_token: 'legacy-bearer-abc123',
+    #     account_id:   'account_example',
+    #     timeout:      '45'
+    #   )
+    #   config.token        # => "legacy-bearer-abc123"
+    #   config.api_key      # => nil
+    #   config.timeout      # => 45
+    #   config.base_url     # => "https://api.assinafy.com.br/v1"
+    #   config.auth_headers # => { "Authorization" => "Bearer legacy-bearer-abc123" }
+    def self.from_hash(hash)
+      raise ValidationError.new('Configuration must be a Hash') unless hash.is_a?(Hash)
+
+      h = hash.transform_keys(&:to_s)
+      new(
+        api_key:        h['api_key'],
+        token:          h['token'] || h['access_token'],
+        account_id:     h['account_id'],
+        base_url:       h.key?('base_url') ? h['base_url'] : DEFAULT_BASE_URL,
+        webhook_secret: h['webhook_secret'],
+        timeout:        h.key?('timeout') ? h['timeout'] : DEFAULT_TIMEOUT,
+        logger:         h['logger']
+      )
+    end
+
+    # Return the HTTP headers used to authenticate requests, preferring
+    # `X-Api-Key` (the documented mechanism) over a bearer token. When `api_key`
+    # is set it wins; otherwise a non-nil `token` produces an `Authorization:
+    # Bearer` header; with neither credential set an empty Hash is returned.
+    #
+    # @return [Hash{String=>String}] one of `{ "X-Api-Key" => ... }`,
+    #   `{ "Authorization" => "Bearer ..." }`, or `{}`
+    #
+    # @example api_key takes precedence over token
+    #   Assinafy::Configuration.new(api_key: 'k', token: 't').auth_headers
+    #   # => { "X-Api-Key" => "k" }
+    #
+    # @example Bearer fallback when only a token is present
+    #   Assinafy::Configuration.new(token: 't').auth_headers
+    #   # => { "Authorization" => "Bearer t" }
+    #
+    # @example No credentials configured
+    #   Assinafy::Configuration.new.auth_headers
+    #   # => {}
+    def auth_headers
+      key = api_key.to_s.strip
+      bearer = token.to_s.strip
+      return { 'X-Api-Key' => key } unless key.empty?
+      return { 'Authorization' => "Bearer #{bearer}" } unless bearer.empty?
+
+      {}
+    end
+
+    private
+
+    def normalize_timeout(value)
+      raw = value.nil? ? DEFAULT_TIMEOUT : value
+      seconds = Integer(raw, exception: false) if raw.is_a?(Integer) || raw.is_a?(String)
+      return seconds if seconds&.positive?
+
+      raise ValidationError.new('Timeout must be a positive integer')
+    end
+  end
+end

data/lib/assinafy/errors.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Assinafy
+  # Base class for all errors raised by the SDK. Carries an optional context
+  # Hash that may contain useful debugging details (e.g. response data, IDs).
+  class Error < StandardError
+    # @return [Hash] arbitrary metadata about the error
+    attr_reader :context
+
+    def initialize(message = nil, context = {})
+      super(message)
+      @context = context || {}
+    end
+  end
+
+  # Raised when the API responds with a non-2xx status, or with a 2xx
+  # response envelope whose embedded status code indicates failure.
+  #
+  # The Assinafy v1 API returns two distinct error-body shapes, both handled
+  # here:
+  #
+  # - Framework errors: `{"name":"Not Found","message":"Página não encontrada.","code":0,"status":404}`
+  # - Application envelopes: `{"status":404,"data":null,"message":"Template não encontrado."}`
+  #
+  # @example Rescue an API error
+  #   begin
+  #     client.documents.details('missing-id')
+  #   rescue Assinafy::ApiError => e
+  #     e.status_code   # => 404
+  #     e.message       # => "Documento não encontrado."
+  #     e.error_name    # => "Not Found" (nil when the body omits it)
+  #     e.error_code    # => 0          (nil when the body omits it)
+  #     e.response_data # => the raw parsed body Hash
+  #   end
+  class ApiError < Error
+    # @return [Integer] HTTP-style status code reported by the API
+    attr_reader :status_code
+    # @return [Hash, String, nil] raw response body
+    attr_reader :response_data
+    # @return [String, nil] the API's `name` field (framework errors only)
+    attr_reader :error_name
+    # @return [Integer, String, nil] the API's `code` field, when present
+    attr_reader :error_code
+
+    def initialize(message, status_code, response_data = nil)
+      super(message, { status_code: status_code, response_data: response_data })
+      @status_code   = status_code
+      @response_data = response_data
+      return unless response_data.is_a?(Hash)
+
+      @error_name = response_data['name']
+      @error_code = response_data['code']
+    end
+
+    # Build an {ApiError} from an HTTP status and parsed body. Reads the human
+    # message from `message`, `error`, or `name` (in that order).
+    #
+    # @param status_code   [Integer]
+    # @param response_data [Hash, Object]
+    # @return [ApiError]
+    def self.from_response(status_code, response_data)
+      data = response_data.is_a?(Hash) ? response_data : {}
+      message = data['message'] || data['error'] || data['name'] || 'API request failed'
+      new(message.to_s, status_code, response_data)
+    end
+  end
+
+  # Raised before a network request is made when the caller's input is
+  # invalid (missing IDs, wrong shape, etc.).
+  class ValidationError < Error
+    # @return [Hash] field-keyed validation details
+    attr_reader :errors
+
+    def initialize(message = 'Validation failed', errors = {})
+      super(message, { errors: errors })
+      @errors = errors || {}
+    end
+  end
+
+  # Raised when Faraday reports a connection, timeout, or TLS error. The
+  # original exception's message is included.
+  class NetworkError < Error; end
+end

data/lib/assinafy/null_logger.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Assinafy
+  class NullLogger
+    %i[debug info warn error fatal unknown].each do |level|
+      define_method(level) { |*, **| nil }
+    end
+  end
+end