clicksign-ruby-sdk 0.1.1

data/lib/clicksign/resource.rb

@@ -0,0 +1,263 @@
+# frozen_string_literal: true
+
+module Clicksign
+  class Resource
+    class QueryProxy
+      include Enumerable
+
+      def initialize(resource_class, builder)
+        @resource_class = resource_class
+        @builder        = builder
+      end
+
+      def filter(**params)
+        @builder.filter(**params)
+        self
+      end
+
+      def include(*types)
+        @builder.include(*types)
+        self
+      end
+
+      def order(field)
+        @builder.order(field)
+        self
+      end
+
+      def page(number)
+        @builder.page(number)
+        self
+      end
+
+      def per(size)
+        @builder.per(size)
+        self
+      end
+
+      def fields(**types)
+        @builder.fields(**types)
+        self
+      end
+
+      def to_a
+        @resource_class.send(:fetch_list, @builder.to_params)
+      end
+
+      def first
+        to_a.first
+      end
+
+      def last
+        to_a.last
+      end
+
+      def count
+        to_a.size
+      end
+
+      def each(&block)
+        to_a.each(&block)
+      end
+
+      def auto_paging_each(&block)
+        return enum_for(:auto_paging_each) unless block_given?
+
+        @resource_class.send(:fetch_auto_pages, @builder.to_params) do |page|
+          page.each(&block)
+        end
+      end
+
+      def each_page(&block)
+        return enum_for(:each_page) unless block_given?
+
+        @resource_class.send(:fetch_auto_pages, @builder.to_params, &block)
+      end
+
+      def auto_paging
+        enum_for(:auto_paging_each)
+      end
+    end
+
+    class << self
+      attr_writer :resource_type, :endpoint
+
+      def resource_type
+        @resource_type || infer_resource_type
+      end
+
+      def endpoint
+        @endpoint || "/#{resource_type}"
+      end
+
+      def list(**filters)
+        return fetch_list({}) if filters.empty?
+
+        filter(**filters).to_a
+      end
+
+      def retrieve(id)
+        raw    = client.get("#{endpoint}/#{id}")
+        parsed = JsonApi::Parser.parse(raw)
+        build_instance(parsed[:data].first)
+      end
+
+      def create(**attributes)
+        relationships = attributes.delete(:relationships) || {}
+        raw = client.post(
+          endpoint,
+          body: JsonApi::Serializer.dump(
+            type: resource_type, attributes: attributes, relationships: relationships,
+          ),
+        )
+        parsed = JsonApi::Parser.parse(raw)
+        build_instance(parsed[:data].first)
+      end
+
+      def filter(**params)
+        QueryProxy.new(self, JsonApi::QueryBuilder.new.filter(**params))
+      end
+
+      def include(*types)
+        QueryProxy.new(self, JsonApi::QueryBuilder.new.include(*types))
+      end
+
+      def order(field)
+        QueryProxy.new(self, JsonApi::QueryBuilder.new.order(field))
+      end
+
+      def page(number)
+        QueryProxy.new(self, JsonApi::QueryBuilder.new.page(number))
+      end
+
+      def per(size)
+        QueryProxy.new(self, JsonApi::QueryBuilder.new.per(size))
+      end
+
+      def fields(**types)
+        QueryProxy.new(self, JsonApi::QueryBuilder.new.fields(**types))
+      end
+
+      def nested_list(parent_id, nested_type:, as: self, params: {})
+        raw    = client.get("#{endpoint}/#{parent_id}/#{nested_type}", params: params)
+        parsed = JsonApi::Parser.parse(raw)
+        parsed[:data].map { |item| as.send(:build_instance, item, parent_id: parent_id) }
+      end
+
+      def filter_params(**filters)
+        filters.empty? ? {} : JsonApi::QueryBuilder.new.filter(**filters).to_params
+      end
+
+      def auto_paging_each(&block)
+        return enum_for(:auto_paging_each) unless block_given?
+
+        fetch_auto_pages({}) { |page| page.each(&block) }
+      end
+
+      def each_page(&block)
+        return enum_for(:each_page) unless block_given?
+
+        fetch_auto_pages({}, &block)
+      end
+
+      def client
+        Thread.current[:clicksign_client] || Clicksign.client
+      end
+
+      private
+
+      def fetch_list(params)
+        raw    = client.get(endpoint, params: params)
+        parsed = JsonApi::Parser.parse(raw)
+        parsed[:data].map { |item| build_instance(item) }
+      end
+
+      def fetch_auto_pages(params)
+        per  = (params['page[size]'] || 20).to_i
+        base = params.except('page[number]')
+        page = 1
+
+        loop do
+          raw   = client.get(endpoint,
+                             params: base.merge('page[number]' => page,
+                                                'page[size]' => per))
+          items = JsonApi::Parser.parse(raw)[:data].map { |item| build_instance(item) }
+          yield items
+          break if items.size < per
+
+          page += 1
+        end
+      end
+
+      def build_instance(data, parent_id: nil)
+        instance = allocate
+        instance.send(:load_data, data, parent_id: parent_id)
+        instance
+      end
+
+      def infer_resource_type
+        "#{name.split('::').last
+              .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+              .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+              .downcase}s"
+      end
+    end
+
+    attr_reader :id, :relationships
+
+    def update(**attributes)
+      raw = self.class.client.patch(
+        "#{base_path}/#{@id}",
+        body: JsonApi::Serializer.dump(
+          type: self.class.resource_type, id: @id, attributes: attributes,
+        ),
+      )
+      parsed = JsonApi::Parser.parse(raw)
+      load_data(parsed[:data].first, parent_id: @_parent_id)
+      self
+    end
+
+    def delete
+      self.class.client.delete("#{base_path}/#{@id}")
+      nil
+    end
+
+    def reload
+      raw    = self.class.client.get("#{base_path}/#{@id}")
+      parsed = JsonApi::Parser.parse(raw)
+      load_data(parsed[:data].first, parent_id: @_parent_id)
+      self
+    end
+
+    def base_path
+      self.class.endpoint
+    end
+
+    def [](key)
+      @_attributes&.[](key.to_s)
+    end
+
+    def method_missing(name, *args, &block)
+      key = name.to_s.delete_suffix('=')
+      if @_attributes&.key?(key)
+        name.to_s.end_with?('=') ? @_attributes[key] = args.first : @_attributes[key]
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      key = name.to_s.delete_suffix('=')
+      @_attributes&.key?(key) || super
+    end
+
+    private
+
+    def load_data(data, parent_id: nil)
+      @id            = data['id']
+      @relationships = data['relationships'] || {}
+      @_attributes   = data['attributes'] || {}
+      @_parent_id    = parent_id
+    end
+  end
+end

data/lib/clicksign/resources/acceptance_term/whatsapp.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Clicksign
+  module Resources
+    module AcceptanceTerm
+      class Whatsapp < Clicksign::Resource
+        self.resource_type = 'acceptance_term_whatsapps'
+        self.endpoint      = '/acceptance_term/whatsapps'
+      end
+    end
+  end
+end

data/lib/clicksign/resources/access_control_list.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Clicksign
+  module Resources
+    class AccessControlList < Clicksign::Resource
+      self.resource_type = 'access_control_lists'
+
+      def self.create(folder_id:, group_id:)
+        super(
+          relationships: acl_relationships(folder_id: folder_id, group_id: group_id)
+        )
+      end
+
+      def self.destroy(folder_id:, group_id:)
+        client.delete(
+          endpoint,
+          body: JsonApi::Serializer.dump(
+            type: resource_type,
+            attributes: {},
+            relationships: acl_relationships(folder_id: folder_id, group_id: group_id),
+          ),
+        )
+        nil
+      end
+
+      def self.acl_relationships(folder_id:, group_id:)
+        {
+          folder: { data: { type: 'folders', id: folder_id } },
+          group: { data: { type: 'groups', id: group_id } },
+        }
+      end
+      private_class_method :acl_relationships
+    end
+  end
+end

data/lib/clicksign/resources/auto_signature/term.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Clicksign
+  module Resources
+    module AutoSignature
+      class Term < Clicksign::Resource
+        self.resource_type = 'auto_signature_terms'
+        self.endpoint      = '/auto_signature/terms'
+      end
+    end
+  end
+end

data/lib/clicksign/resources/envelope_bulk_creation.rb

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

data/lib/clicksign/resources/folder.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Clicksign
+  module Resources
+    class Folder < Clicksign::Resource
+      self.resource_type = 'folders'
+
+      def self.create(name:, folder_id: nil)
+        rels = folder_id ? { folder: { data: { type: 'folders', id: folder_id } } } : {}
+        super(name: name, relationships: rels)
+      end
+
+      def folder_id
+        relationships.dig('folder', 'data', 'id')
+      end
+
+      def child_folder_ids
+        Array(relationships.dig('folders', 'data')).filter_map { |d| d['id'] }
+      end
+    end
+  end
+end

data/lib/clicksign/resources/group.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Clicksign
+  module Resources
+    class Group < Clicksign::Resource
+      self.resource_type = 'groups'
+
+      def self.add_users(group_id, user_ids)
+        data = Array(user_ids).map { |id| { type: 'users', id: id } }
+        client.post("/groups/#{group_id}/relationships/users", body: { data: data })
+        nil
+      end
+
+      def self.remove_users(group_id, user_ids)
+        data = Array(user_ids).map { |id| { type: 'users', id: id } }
+        client.delete("/groups/#{group_id}/relationships/users", body: { data: data })
+        nil
+      end
+    end
+  end
+end

data/lib/clicksign/resources/membership.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Clicksign
+  module Resources
+    class Membership < Clicksign::Resource
+      self.resource_type = 'memberships'
+
+      def self.create(role:, user_id:, **attributes)
+        super(
+          **attributes,
+          role: role,
+          relationships: { user: { data: { type: 'users', id: user_id } } }
+        )
+      end
+
+      def user_id
+        relationships.dig('user', 'data', 'id')
+      end
+    end
+  end
+end

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

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Clicksign
+  module Resources
+    module Notarial
+      class BulkRequirement
+        class OperationResult
+          attr_reader :index, :op, :requirement, :errors, :raw
+
+          def initialize(index:, op:, requirement:, errors:, raw:)
+            @index = index
+            @op = op
+            @requirement = requirement
+            @errors = errors
+            @raw = raw
+          end
+
+          def success?
+            errors.nil? || (errors.is_a?(Array) && errors.empty?)
+          end
+        end
+
+        class Response
+          attr_reader :envelope_id, :results
+
+          def initialize(envelope_id:, results:)
+            @envelope_id = envelope_id
+            @results = results
+          end
+
+          def success?
+            results.all?(&:success?)
+          end
+
+          def requirements
+            results.filter_map(&:requirement)
+          end
+
+          def failures
+            results.reject(&:success?)
+          end
+        end
+
+        def self.create(envelope_id:, &block)
+          raise ArgumentError, 'block is required' unless block
+
+          ops = JsonApi::Operations::BulkRequirement.new
+          yield ops
+
+          raw = Clicksign.bulk_operations_client.post(
+            "/envelopes/#{envelope_id}/bulk_requirements",
+            body: ops.to_h,
+          )
+
+          Response.new(
+            envelope_id: envelope_id,
+            results: JsonApi::AtomicResultsParser.parse(
+              raw,
+              envelope_id: envelope_id,
+              operations: ops.entries,
+            ),
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Clicksign
+  module Resources
+    module Notarial
+      class Document < Clicksign::Resource
+        self.resource_type = 'documents'
+
+        def self.retrieve(id, envelope_id:)
+          raw    = client.get("/envelopes/#{envelope_id}/documents/#{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}/documents",
+            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.list_events(document_id, envelope_id:)
+          raw    = client.get("/envelopes/#{envelope_id}/documents/#{document_id}/events")
+          parsed = JsonApi::Parser.parse(raw)
+          parsed[:data].map { |item| Event.send(:build_instance, item) }
+        end
+
+        def base_path
+          "/envelopes/#{@_parent_id || envelope_id}/documents"
+        end
+
+        def envelope_id
+          @_parent_id || relationships.dig('envelope', 'data', 'id')
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Clicksign
+  module Resources
+    module Notarial
+      class Envelope < Clicksign::Resource
+        self.resource_type = 'envelopes'
+
+        def self.create(folder_id: nil, **attributes)
+          relationships = if folder_id
+                            { folder: { data: { type: 'folders',
+                                                id: folder_id } } }
+                          else
+                            {}
+                          end
+          super(**attributes, relationships: relationships)
+        end
+
+        # POST /envelopes/:id/activate — rota disponível mas prefira
+        # envelope.update(status: 'running') via PATCH, que é o caminho
+        # recomendado e suportado por todos os ambientes.
+        def self.activate(id)
+          raw    = client.post("#{endpoint}/#{id}/activate", body: {})
+          parsed = JsonApi::Parser.parse(raw)
+          build_instance(parsed[:data].first)
+        end
+
+        def self.list_events(envelope_id, **filters)
+          nested_list(envelope_id, nested_type: 'events', as: Event,
+                                   params: filter_params(**filters))
+        end
+
+        def self.list_documents(envelope_id, **filters)
+          nested_list(envelope_id, nested_type: 'documents', as: Document,
+                                   params: filter_params(**filters))
+        end
+
+        def self.list_signers(envelope_id, **filters)
+          nested_list(envelope_id, nested_type: 'signers', as: Signer,
+                                   params: filter_params(**filters))
+        end
+
+        def self.list_signature_watchers(envelope_id, **filters)
+          nested_list(envelope_id, nested_type: 'signature_watchers',
+                                   as: SignatureWatcher,
+                                   params: filter_params(**filters))
+        end
+
+        def self.list_requirements(envelope_id, **filters)
+          nested_list(
+            envelope_id,
+            nested_type: 'requirements',
+            as: Requirement,
+            params: filter_params(**filters),
+          )
+        end
+
+        def self.notify(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("#{endpoint}/#{id}/notifications", body: body)
+          nil
+        end
+
+        def notify(message: nil, **email_customization)
+          self.class.notify(@id, message: message, **email_customization)
+        end
+
+        def folder_id
+          relationships.dig('folder', 'data', 'id')
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Clicksign
+  module Resources
+    module Notarial
+      class Event < Clicksign::Resource
+        self.resource_type = 'events'
+
+        def self.create_for_document(envelope_id:, document_id:, **attributes)
+          raw = client.post(
+            "/envelopes/#{envelope_id}/documents/#{document_id}/events",
+            body: JsonApi::Serializer.dump(type: resource_type, attributes: attributes),
+          )
+          parsed = JsonApi::Parser.parse(raw)
+          build_instance(parsed[:data].first)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Clicksign
+  module Resources
+    module Notarial
+      class Requirement < Clicksign::Resource
+        self.resource_type = 'requirements'
+
+        def self.retrieve(id, envelope_id:)
+          raw    = client.get("/envelopes/#{envelope_id}/requirements/#{id}")
+          parsed = JsonApi::Parser.parse(raw)
+          build_instance(parsed[:data].first, parent_id: envelope_id)
+        end
+
+        def self.create(envelope_id:, **attributes)
+          relationships = attributes.delete(:relationships) || {}
+          raw = client.post(
+            "/envelopes/#{envelope_id}/requirements",
+            body: JsonApi::Serializer.dump(
+              type: resource_type, attributes: attributes, relationships: relationships,
+            ),
+          )
+          parsed = JsonApi::Parser.parse(raw)
+          build_instance(parsed[:data].first, parent_id: envelope_id)
+        end
+
+        def self.list_for_document(document_id, **filters)
+          list_related('documents', document_id, **filters)
+        end
+
+        def self.list_for_signer(signer_id, **filters)
+          list_related('signers', signer_id, **filters)
+        end
+
+        def self.list_related(resource_type, resource_id, **filters)
+          raw = client.get(
+            "/#{resource_type}/#{resource_id}/relationships/requirements",
+            params: filter_params(**filters),
+          )
+          parsed = JsonApi::Parser.parse(raw)
+          parsed[:data].map { |item| build_instance(item) }
+        end
+        private_class_method :list_related
+
+        def base_path
+          "/envelopes/#{@_parent_id || envelope_id}/requirements"
+        end
+
+        def envelope_id
+          @_parent_id || relationships.dig('envelope', 'data', 'id')
+        end
+
+        def document_id
+          relationships.dig('document', 'data', 'id')
+        end
+
+        def signer_id
+          relationships.dig('signer', 'data', 'id')
+        end
+      end
+    end
+  end
+end