clicksign-ruby-sdk 0.1.1

data/lib/clicksign/resources/notarial/signature_watcher.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Clicksign
+  module Resources
+    module Notarial
+      class SignatureWatcher < Clicksign::Resource
+        self.resource_type = 'signature_watchers'
+
+        def self.retrieve(id, envelope_id:)
+          raw    = client.get("/envelopes/#{envelope_id}/signature_watchers/#{id}")
+          parsed = JsonApi::Parser.parse(raw)
+          build_instance(parsed[:data].first, parent_id: envelope_id)
+        end
+
+        def self.create(envelope_id:, **attributes)
+          raw = client.post(
+            "/envelopes/#{envelope_id}/signature_watchers",
+            body: JsonApi::Serializer.dump(type: resource_type, attributes: attributes),
+          )
+          parsed = JsonApi::Parser.parse(raw)
+          build_instance(parsed[:data].first, parent_id: envelope_id)
+        end
+
+        def base_path
+          "/envelopes/#{@_parent_id || envelope_id}/signature_watchers"
+        end
+
+        def update(**)
+          raise NotImplementedError,
+                'SignatureWatcher does not support update (route: except: [:update])'
+        end
+
+        def envelope_id
+          @_parent_id || relationships.dig('envelope', 'data', 'id')
+        end
+      end
+    end
+  end
+end

data/lib/clicksign/resources/notarial/signer.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Clicksign
+  module Resources
+    module Notarial
+      class Signer < Clicksign::Resource
+        self.resource_type = 'signers'
+
+        def self.retrieve(id, envelope_id:)
+          raw    = client.get("/envelopes/#{envelope_id}/signers/#{id}")
+          parsed = JsonApi::Parser.parse(raw)
+          build_instance(parsed[:data].first, parent_id: envelope_id)
+        end
+
+        def self.create(envelope_id:, **attributes)
+          raw = client.post(
+            "/envelopes/#{envelope_id}/signers",
+            body: JsonApi::Serializer.dump(type: resource_type, attributes: attributes),
+          )
+          parsed = JsonApi::Parser.parse(raw)
+          build_instance(parsed[:data].first, parent_id: envelope_id)
+        end
+
+        def self.notify(id, envelope_id:, message: nil, **email_customization)
+          attributes = {}
+          attributes[:message] = message if message
+          unless email_customization.empty?
+            attributes[:email_customization] =
+              email_customization
+          end
+          body = { data: { type: 'notifications', attributes: attributes } }
+          client.post("/envelopes/#{envelope_id}/signers/#{id}/notifications", body: body)
+          nil
+        end
+
+        def notify(message: nil, **email_customization)
+          self.class.notify(@id, envelope_id: envelope_id, message: message,
+                                 **email_customization)
+        end
+
+        def update(**)
+          raise NotImplementedError,
+                'Signer does not support update (route: except: [:update])'
+        end
+
+        def base_path
+          "/envelopes/#{@_parent_id || envelope_id}/signers"
+        end
+
+        def envelope_id
+          @_parent_id || relationships.dig('envelope', 'data', 'id')
+        end
+      end
+    end
+  end
+end

data/lib/clicksign/resources/template.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Clicksign
+  module Resources
+    class Template < Clicksign::Resource
+      self.resource_type = 'templates'
+
+      def self.list_template_fields(template_id)
+        nested_list(template_id, nested_type: 'template_fields', as: TemplateField)
+      end
+    end
+  end
+end

data/lib/clicksign/resources/template_field.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Clicksign
+  module Resources
+    class TemplateField < Clicksign::Resource
+      self.resource_type = 'template_fields'
+    end
+  end
+end

data/lib/clicksign/resources/user.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Clicksign
+  module Resources
+    class User < Clicksign::Resource
+      self.resource_type = 'users'
+
+      def self.me
+        raw    = client.get('/users/me')
+        parsed = JsonApi::Parser.parse(raw)
+        build_instance(parsed[:data].first)
+      end
+    end
+  end
+end

data/lib/clicksign/resources/webhook.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Clicksign
+  module Resources
+    class Webhook < Clicksign::Resource
+      self.resource_type = 'webhooks'
+    end
+  end
+end

data/lib/clicksign/services.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Clicksign
+  class Services
+    def initialize(api_key:, environment: :production, base_url: nil,
+                   open_timeout: 2, read_timeout: 10, write_timeout: 10, max_retries: 0)
+      resolved_url = base_url || resolve_environment(environment)
+      @client = Client.new(
+        api_key: api_key,
+        base_url: resolved_url,
+        open_timeout: open_timeout,
+        read_timeout: read_timeout,
+        write_timeout: write_timeout,
+        max_retries: max_retries,
+      )
+    end
+
+    def use
+      previous = Thread.current[:clicksign_client]
+      Thread.current[:clicksign_client] = @client
+      yield
+    ensure
+      Thread.current[:clicksign_client] = previous
+    end
+
+    private
+
+    def resolve_environment(env)
+      Configuration::ENVIRONMENTS.fetch(env.to_sym) do
+        valid = Configuration::ENVIRONMENTS.keys.join(', ')
+        raise ArgumentError, "Unknown environment: #{env}. Valid: #{valid}"
+      end
+    end
+  end
+end

data/lib/clicksign/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Clicksign
+  VERSION = '0.1.1'
+end

data/lib/clicksign/webhook.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'openssl'
+
+module Clicksign
+  module Webhook
+    DIGEST = 'sha256'
+
+    # Raises WebhookSignatureError if the Content-HMAC header does not match.
+    def self.verify_signature!(payload, signature, secret:)
+      expected = compute_signature(payload, secret: secret)
+      raise WebhookSignatureError, 'Webhook signature mismatch' unless secure_compare?(
+        expected, signature
+      )
+
+      true
+    end
+
+    # Returns true/false instead of raising.
+    def self.verify_signature(payload, signature, secret:)
+      verify_signature!(payload, signature, secret: secret)
+    rescue WebhookSignatureError
+      false
+    end
+
+    # Computes the expected Content-HMAC value for a given payload and secret.
+    def self.compute_signature(payload, secret:)
+      "#{DIGEST}=#{OpenSSL::HMAC.hexdigest(DIGEST, secret, payload)}"
+    end
+
+    # Constant-time comparison to prevent timing attacks.
+    def self.secure_compare?(expected, actual)
+      digest_a = OpenSSL::Digest::SHA256.hexdigest(expected)
+      digest_b = OpenSSL::Digest::SHA256.hexdigest(actual)
+      result = 0
+      digest_a.bytes.zip(digest_b.bytes) { |x, y| result |= x ^ y }
+      result.zero?
+    end
+    private_class_method :secure_compare?
+  end
+end

data/lib/clicksign.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+require 'uri'
+
+require_relative 'clicksign/version'
+require_relative 'clicksign/configuration'
+require_relative 'clicksign/errors'
+require_relative 'clicksign/error_handler'
+require_relative 'clicksign/instrumentation'
+require_relative 'clicksign/webhook'
+require_relative 'clicksign/json_api/query_builder'
+require_relative 'clicksign/json_api/serializer'
+require_relative 'clicksign/json_api/parser'
+require_relative 'clicksign/json_api/operations'
+require_relative 'clicksign/json_api/operations/bulk_requirement'
+require_relative 'clicksign/json_api/atomic_results_parser'
+require_relative 'clicksign/client'
+require_relative 'clicksign/json_api/bulk_operations_client'
+require_relative 'clicksign/resource'
+require_relative 'clicksign/services'
+
+Dir[File.join(__dir__, 'clicksign', 'resources', '**', '*.rb')].each do |file|
+  require file
+end
+
+module Clicksign
+  class << self
+    # Must be called once at application startup, before any threads are spawned.
+    # Module-level memoisation (@client, @configuration) is not thread-safe for
+    # concurrent first-access; subsequent calls are safe once initialised.
+    def configure
+      yield configuration
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def client
+      @client ||= Client.new(
+        api_key: configuration.api_key,
+        base_url: configuration.base_url,
+        open_timeout: configuration.open_timeout,
+        read_timeout: configuration.read_timeout,
+        write_timeout: configuration.write_timeout,
+        max_retries: configuration.max_retries,
+      )
+    end
+
+    def bulk_operations_client
+      @bulk_operations_client ||= JsonApi::BulkOperationsClient.new(
+        api_key: configuration.api_key,
+        base_url: configuration.base_url,
+        open_timeout: configuration.open_timeout,
+        read_timeout: configuration.read_timeout,
+        write_timeout: configuration.write_timeout,
+        max_retries: configuration.max_retries,
+      )
+    end
+
+    def on_request(&block) = Instrumentation.on(:request, &block)
+    def on_retry(&block)   = Instrumentation.on(:retry, &block)
+    def on_error(&block)   = Instrumentation.on(:error, &block)
+
+    def reset!
+      @configuration          = nil
+      @client                 = nil
+      @bulk_operations_client = nil
+    end
+  end
+end

metadata

@@ -0,0 +1,81 @@
+--- !ruby/object:Gem::Specification
+name: clicksign-ruby-sdk
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Clicksign
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Official Ruby SDK for the Clicksign e-signature API (v3). Supports envelope
+  management, signing workflows and webhooks. JSON:API compliant, no runtime dependencies
+  beyond the Ruby stdlib.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/clicksign.rb
+- lib/clicksign/client.rb
+- lib/clicksign/configuration.rb
+- lib/clicksign/error_handler.rb
+- lib/clicksign/errors.rb
+- lib/clicksign/instrumentation.rb
+- lib/clicksign/json_api/atomic_results_parser.rb
+- lib/clicksign/json_api/bulk_operations_client.rb
+- lib/clicksign/json_api/operations.rb
+- lib/clicksign/json_api/operations/bulk_requirement.rb
+- lib/clicksign/json_api/parser.rb
+- lib/clicksign/json_api/query_builder.rb
+- lib/clicksign/json_api/serializer.rb
+- lib/clicksign/resource.rb
+- lib/clicksign/resources/acceptance_term/whatsapp.rb
+- lib/clicksign/resources/access_control_list.rb
+- lib/clicksign/resources/auto_signature/term.rb
+- lib/clicksign/resources/envelope_bulk_creation.rb
+- lib/clicksign/resources/folder.rb
+- lib/clicksign/resources/group.rb
+- lib/clicksign/resources/membership.rb
+- lib/clicksign/resources/notarial/bulk_requirement.rb
+- lib/clicksign/resources/notarial/document.rb
+- lib/clicksign/resources/notarial/envelope.rb
+- lib/clicksign/resources/notarial/event.rb
+- lib/clicksign/resources/notarial/requirement.rb
+- lib/clicksign/resources/notarial/signature_watcher.rb
+- lib/clicksign/resources/notarial/signer.rb
+- lib/clicksign/resources/template.rb
+- lib/clicksign/resources/template_field.rb
+- lib/clicksign/resources/user.rb
+- lib/clicksign/resources/webhook.rb
+- lib/clicksign/services.rb
+- lib/clicksign/version.rb
+- lib/clicksign/webhook.rb
+homepage: https://github.com/djosino/clicksign-ruby-sdk
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/djosino/clicksign-ruby-sdk
+  changelog_uri: https://github.com/djosino/clicksign-ruby-sdk/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/djosino/clicksign-ruby-sdk/issues
+  documentation_uri: https://github.com/djosino/clicksign-ruby-sdk
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.11
+specification_version: 4
+summary: Ruby SDK for the Clicksign API
+test_files: []