clicksign-ruby-sdk 0.1.1

data/lib/clicksign/error_handler.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Clicksign
+  module ErrorHandler
+    ERROR_MAP = {
+      [401, 403] => AuthenticationError,
+      [404] => NotFoundError,
+      [400, 422] => ValidationError,
+      [409] => ConflictError,
+      [429] => RateLimitError,
+    }.freeze
+
+    def self.call(response)
+      return nil if (200..299).cover?(response.code.to_i)
+
+      metadata   = extract_metadata(response)
+      message    = extract_message(response)
+      error_class = error_class_for(response.code.to_i)
+      raise error_class.new(message, **metadata)
+    end
+
+    def self.error_class_for(code)
+      ERROR_MAP.each { |codes, klass| return klass if codes.include?(code) }
+      return ServerError if (500..599).cover?(code)
+
+      Error
+    end
+
+    def self.extract_metadata(response)
+      {
+        status_code: response.code.to_i,
+        request_id: response['x-request-id'],
+        response_body: response.body,
+        response_headers: response.each_header.to_h,
+      }
+    end
+
+    def self.extract_message(response)
+      return response.message if response.body.nil? || response.body.empty?
+
+      extract_from_json(response)
+    rescue JSON::ParserError
+      response.message
+    end
+
+    def self.extract_from_json(response)
+      body = JSON.parse(response.body)
+      return response.message unless body.is_a?(Hash)
+
+      errors = body['errors']
+      return response.message unless errors.is_a?(Array)
+
+      errors.filter_map { |e| e['detail'] || e['title'] }.join(', ')
+    end
+  end
+end

data/lib/clicksign/errors.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Clicksign
+  class Error < StandardError
+    attr_reader :status_code, :request_id, :response_body, :response_headers
+
+    def initialize(message = nil, status_code: nil, request_id: nil,
+                   response_body: nil, response_headers: {})
+      super(message)
+      @status_code      = status_code
+      @request_id       = request_id
+      @response_body    = response_body
+      @response_headers = response_headers || {}
+    end
+
+    def retryable?
+      false
+    end
+  end
+
+  class AuthenticationError < Error; end
+  class NotFoundError        < Error; end
+  class ValidationError      < Error; end
+  class ConflictError        < Error; end
+
+  class RateLimitError < Error
+    def retryable?
+      true
+    end
+
+    def rate_limit_remaining
+      response_headers['x-ratelimit-remaining']&.to_i
+    end
+
+    def rate_limit_reset
+      response_headers['x-ratelimit-reset']
+    end
+  end
+
+  class ServerError < Error
+    def retryable?
+      true
+    end
+  end
+
+  class TimeoutError < Error
+    def retryable?
+      true
+    end
+  end
+
+  class WebhookSignatureError < Error; end
+end

data/lib/clicksign/instrumentation.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Clicksign
+  module Instrumentation
+    EVENTS = %i[request retry error].freeze
+
+    @callbacks = Hash.new { |h, k| h[k] = [] }
+
+    class << self
+      def on(event, &block)
+        unless EVENTS.include?(event)
+          raise ArgumentError, "Unknown event: #{event}. Valid: #{EVENTS.join(', ')}"
+        end
+
+        @callbacks[event] << block
+      end
+
+      def publish(event, payload)
+        @callbacks[event].each do |cb|
+          cb.call(payload)
+        rescue StandardError
+          # Callbacks must not affect the request — errors are silently ignored.
+        end
+      end
+
+      # Removes all registered callbacks — intended for test teardown.
+      def clear
+        @callbacks = Hash.new { |h, k| h[k] = [] }
+      end
+    end
+  end
+end

data/lib/clicksign/json_api/atomic_results_parser.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Clicksign
+  module JsonApi
+    module AtomicResultsParser
+      module_function
+
+      def parse(raw, envelope_id:, operations:)
+        raw ||= {}
+        raise ValidationError, format_errors(raw['errors']) if envelope_errors?(raw)
+
+        Array(raw['atomic:results']).each_with_index.map do |slot, index|
+          build_operation_result(
+            slot: slot,
+            index: index,
+            op: operations.dig(index, 'op'),
+            envelope_id: envelope_id,
+          )
+        end
+      end
+
+      def envelope_errors?(raw)
+        raw.key?('errors') && !raw.key?('atomic:results')
+      end
+
+      def build_operation_result(slot:, index:, op:, envelope_id:)
+        errors = slot['errors']
+        requirement = build_requirement(slot['data'], envelope_id: envelope_id)
+
+        Resources::Notarial::BulkRequirement::OperationResult.new(
+          index: index,
+          op: op,
+          requirement: requirement,
+          errors: errors,
+          raw: slot,
+        )
+      end
+
+      def build_requirement(data, envelope_id:)
+        return nil if data.nil? || data.empty?
+
+        Resources::Notarial::Requirement.send(
+          :build_instance,
+          {
+            'id' => data['id'],
+            'type' => data['type'],
+            'attributes' => data.fetch('attributes', {}),
+            'relationships' => data.fetch('relationships', {}),
+          },
+          parent_id: envelope_id,
+        )
+      end
+
+      def format_errors(errors)
+        return 'Validation failed' unless errors.is_a?(Array)
+
+        errors.filter_map { |e| e['detail'] || e['title'] }.join(', ')
+      end
+    end
+  end
+end

data/lib/clicksign/json_api/bulk_operations_client.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+require 'json'
+
+module Clicksign
+  module JsonApi
+    class BulkOperationsClient
+      HEADERS = {
+        'Content-Type' => 'application/vnd.api+json',
+        'Accept' => 'application/vnd.api+json',
+      }.freeze
+
+      def initialize(api_key:, base_url:, open_timeout: 2, read_timeout: 10,
+                     write_timeout: 10, max_retries: 0)
+        @api_key       = api_key
+        @base_url      = base_url
+        @open_timeout  = open_timeout
+        @read_timeout  = read_timeout
+        @write_timeout = write_timeout
+        @max_retries   = max_retries
+      end
+
+      def post(path, body:)
+        response = perform_post(path, body)
+        parsed = parse_response_body(response) || {}
+
+        return parsed if parsed.key?('atomic:results')
+
+        ErrorHandler.call(response)
+        parsed
+      end
+
+      private
+
+      def perform_post(path, body)
+        uri     = build_uri(path)
+        request = build_request(uri, body)
+        execute_with_retry(request, uri)
+      end
+
+      def build_request(uri, body)
+        request = Net::HTTP::Post.new(uri, headers)
+        request.body = body.to_json
+        request
+      end
+
+      def execute_with_retry(request, uri)
+        attempts = 0
+        begin
+          attempts += 1
+          safe_http_post(request, uri)
+        rescue Clicksign::TimeoutError => e
+          raise unless e.retryable? && attempts <= @max_retries
+
+          sleep([0.5 * (2**(attempts - 1)), 30].min)
+          retry
+        end
+      end
+
+      def safe_http_post(request, uri)
+        http_post(request, uri)
+      rescue Net::OpenTimeout, Net::ReadTimeout, Errno::ECONNREFUSED => e
+        raise TimeoutError, e.message, e.backtrace
+      end
+
+      def http_post(request, uri)
+        Net::HTTP.start(uri.host, uri.port,
+                        use_ssl: uri.scheme == 'https',
+                        open_timeout: @open_timeout,
+                        read_timeout: @read_timeout,
+                        write_timeout: @write_timeout) do |http|
+          http.request(request)
+        end
+      end
+
+      def headers
+        HEADERS.merge('Authorization' => @api_key)
+      end
+
+      def build_uri(path)
+        URI.parse("#{@base_url}#{path}")
+      end
+
+      def parse_response_body(response)
+        return nil if response.body.nil? || response.body.empty?
+
+        JSON.parse(response.body)
+      rescue JSON::ParserError
+        nil
+      end
+    end
+  end
+end

data/lib/clicksign/json_api/operations/bulk_requirement.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Clicksign
+  module JsonApi
+    class Operations
+      class BulkRequirement < Operations
+        VALID_KINDS = %w[initials manuscript].freeze
+
+        def add_agree(signer_id:, document_id:, role:)
+          validate_ids!(signer_id, document_id)
+          raise ArgumentError, 'role is required' if role.to_s.empty?
+
+          add(
+            data: build_add_data(
+              signer_id: signer_id,
+              document_id: document_id,
+              attributes: { action: 'agree', role: role },
+            ),
+          )
+        end
+
+        def add_provide_evidence(signer_id:, document_id:, auth:)
+          validate_ids!(signer_id, document_id)
+          raise ArgumentError, 'auth is required' if auth.to_s.empty?
+
+          add(
+            data: build_add_data(
+              signer_id: signer_id,
+              document_id: document_id,
+              attributes: { action: 'provide_evidence', auth: auth },
+            ),
+          )
+        end
+
+        def add_rubricate(signer_id:, document_id:, pages: nil, rubric_field: nil,
+                          kind: nil)
+          validate_ids!(signer_id, document_id)
+          if pages.nil? && rubric_field.nil?
+            raise ArgumentError, 'pages or rubric_field is required'
+          end
+          if kind && !VALID_KINDS.include?(kind.to_s)
+            raise ArgumentError, "kind must be one of: #{VALID_KINDS.join(', ')}"
+          end
+
+          add(
+            data: build_add_data(
+              signer_id: signer_id,
+              document_id: document_id,
+              attributes: { action: 'rubricate', pages: pages,
+                            rubric_field: rubric_field, kind: kind },
+            ),
+          )
+        end
+
+        def remove(requirement_id:)
+          raise ArgumentError, 'requirement_id is required' if requirement_id.to_s.empty?
+
+          super(ref: { type: 'requirements', id: requirement_id })
+        end
+
+        private
+
+        def validate_ids!(signer_id, document_id)
+          raise ArgumentError, 'signer_id is required' if signer_id.to_s.empty?
+          raise ArgumentError, 'document_id is required' if document_id.to_s.empty?
+        end
+
+        def build_add_data(signer_id:, document_id:, attributes:)
+          {
+            type: 'requirements',
+            attributes: compact_attributes(attributes),
+            relationships: {
+              signer: { data: { type: 'signers', id: signer_id.to_s } },
+              document: { data: { type: 'documents', id: document_id.to_s } },
+            },
+          }
+        end
+
+        def compact_attributes(attrs)
+          attrs.each_with_object({}) do |(key, value), result|
+            next if value.nil?
+
+            result[key.to_s] = value.is_a?(Symbol) ? value.to_s : value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/clicksign/json_api/operations.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Clicksign
+  module JsonApi
+    class Operations
+      def initialize
+        @entries = []
+      end
+
+      def add(data:)
+        @entries << { 'op' => 'add', 'data' => stringify(data) }
+        self
+      end
+
+      def remove(ref:)
+        @entries << { 'op' => 'remove', 'ref' => stringify(ref) }
+        self
+      end
+
+      def to_h
+        { 'atomic:operations' => @entries }
+      end
+
+      attr_reader :entries
+
+      private
+
+      def stringify(value)
+        case value
+        when Hash then value.transform_keys(&:to_s).transform_values { |v| stringify(v) }
+        when Array then value.map { |v| stringify(v) }
+        when Symbol then value.to_s
+        else value
+        end
+      end
+    end
+  end
+end

data/lib/clicksign/json_api/parser.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Clicksign
+  module JsonApi
+    module Parser
+      def self.parse(raw)
+        raw_data = raw['data']
+        data = case raw_data
+               when Array then raw_data.map { |item| build(item) }
+               when Hash  then [build(raw_data)]
+               else            []
+               end
+
+        included = Array(raw['included'])
+                   .select { |item| item.is_a?(Hash) && item['type'] }
+                   .map { |item| build(item) }
+
+        { data: data, included: included }
+      end
+
+      def self.build(item)
+        {
+          'id' => item['id'],
+          'type' => item['type'],
+          'attributes' => item.fetch('attributes', {}),
+          'relationships' => item.fetch('relationships', {}),
+        }
+      end
+    end
+  end
+end

data/lib/clicksign/json_api/query_builder.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Clicksign
+  module JsonApi
+    class QueryBuilder
+      def initialize
+        @params = {}
+      end
+
+      def filter(**filters)
+        filters.each { |k, v| @params["filter[#{k}]"] = v }
+        self
+      end
+
+      def include(*types)
+        @params['include'] = types.join(',')
+        self
+      end
+
+      def order(field)
+        @params['sort'] = field.to_s
+        self
+      end
+
+      def page(number)
+        @params['page[number]'] = number
+        self
+      end
+
+      def per(size)
+        @params['page[size]'] = size
+        self
+      end
+
+      def fields(**types)
+        types.each { |type, list| @params["fields[#{type}]"] = Array(list).join(',') }
+        self
+      end
+
+      def to_params
+        @params.dup
+      end
+    end
+  end
+end

data/lib/clicksign/json_api/serializer.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Clicksign
+  module JsonApi
+    module Serializer
+      def self.dump(type:, attributes:, id: nil, relationships: {})
+        data = { type: type, attributes: attributes }
+        data[:id] = id if id
+        data[:relationships] = relationships unless relationships.empty?
+        { data: data }
+      end
+    end
+  end
+end