groupdocs 0.3.11 → 1.0.0

data/lib/groupdocs/signature/shared/field_methods.rb

@@ -0,0 +1,282 @@
+module GroupDocs
+  class Signature
+    #
+    # Envelope and template entities share the same set of field methods.
+    #
+    # @see GroupDocs::Signature::Envelope
+    # @see GroupDocs::Signature::Template
+    #
+    module FieldMethods
+
+      #
+      # Returns an array of fields for document and recipient.
+      #
+      # @example Get fields from template
+      #   template = GroupDocs::Signature::Template.get!("g94h5g84hj9g4gf23i40j")
+      #   document = template.documents!.first
+      #   recipient = template.recipients!.first
+      #   template.fields! document, recipient
+      #
+      # @example Get fields from envelope
+      #   envelope = GroupDocs::Signature::Envelope.get!("g94h5g84hj9g4gf23i40j")
+      #   document = envelope.documents!.first
+      #   recipient = envelope.recipients!.first
+      #   envelope.fields! document, recipient
+      #
+      # @param [GroupDocs::Document] document
+      # @param [GroupDocs::Signature::Recipient] recipient
+      # @param [Hash] access Access credentials
+      # @option access [String] :client_id
+      # @option access [String] :private_key
+      # @raise [ArgumentError] if document is not GroupDocs::Document
+      # @raise [ArgumentError] if recipient is not GroupDocs::Signature::Recipient
+      #
+      def fields!(document, recipient, access = {})
+        document.is_a?(GroupDocs::Document) or raise ArgumentError,
+          "Document should be GroupDocs::Document object, received: #{document.inspect}"
+        recipient.is_a?(GroupDocs::Signature::Recipient) or raise ArgumentError,
+          "Recipient should be GroupDocs::Signature::Recipient object, received: #{recipient.inspect}"
+
+        api = Api::Request.new do |request|
+          request[:access] = access
+          request[:method] = :GET
+          request[:path] = "/signature/{{client_id}}/#{pluralized_class_name}/#{id}/fields"
+        end
+        api.add_params(document: document.file.guid, recipient: recipient.id)
+        json = api.execute!
+
+        json[:fields].map do |field|
+          Signature::Field.new(field)
+        end
+      end
+
+      #
+      # Adds field for document and recipient.
+      #
+      # @example Add field to template
+      #   template = GroupDocs::Signature::Template.get!("g94h5g84hj9g4gf23i40j")
+      #   field = GroupDocs::Signature::Field.get!.detect { |f| f.name == "Signature" }
+      #   field.location = { location_x: 0.1, location_y: 0.1, page: 1 }
+      #   document = template.documents!.first
+      #   recipient = template.recipients!.first
+      #   template.add_field! field, document, recipient
+      #
+      # @example Add field to envelope
+      #   envelope = GroupDocs::Signature::Envelope.get!("g94h5g84hj9g4gf23i40j")
+      #   field = GroupDocs::Signature::Field.get!.detect { |f| f.name == "Signature" }
+      #   field.location = { location_x: 0.1, location_y: 0.1, page: 1 }
+      #   document = envelope.documents!.first
+      #   recipient = envelope.recipients!.first
+      #   envelope.add_field! field, document, recipient
+      #
+      # @param [GroupDocs::Signature::Field] field
+      # @param [GroupDocs::Document] document
+      # @param [GroupDocs::Signature::Recipient] recipient
+      # @param [Hash] access Access credentials
+      # @option access [String] :client_id
+      # @option access [String] :private_key
+      # @raise [ArgumentError] if field is not GroupDocs::Signature::Field
+      # @raise [ArgumentError] if document is not GroupDocs::Document
+      # @raise [ArgumentError] if recipient is not GroupDocs::Signature::Recipient
+      # @raise [ArgumentError] if field does not specify location
+      #
+      def add_field!(field, document, recipient, access = {})
+        field.is_a?(GroupDocs::Signature::Field) or raise ArgumentError,
+          "Field should be GroupDocs::Signature::Field object, received: #{field.inspect}"
+        document.is_a?(GroupDocs::Document) or raise ArgumentError,
+          "Document should be GroupDocs::Document object, received: #{document.inspect}"
+        recipient.is_a?(GroupDocs::Signature::Recipient) or raise ArgumentError,
+          "Recipient should be GroupDocs::Signature::Recipient object, received: #{recipient.inspect}"
+        field.location or raise ArgumentError,
+          "You have to specify field location, received: #{field.location.inspect}"
+
+        payload = field.to_hash # field itself
+        payload.merge!(field.location.to_hash) # location should added in plain view (i.e. not "location": {...})
+        payload.merge!(forceNewField: true) # create new field flag
+
+        Api::Request.new do |request|
+          request[:access] = access
+          request[:method] = :POST
+          request[:path] = "/signature/{{client_id}}/#{pluralized_class_name}/#{id}/documents/#{document.file.guid}/recipient/#{recipient.id}/field/#{field.id}"
+          request[:request_body] = payload
+        end.execute!
+      end
+
+      #
+      # Modifies document field.
+      #
+      # @example Modify template field
+      #   template = GroupDocs::Signature::Template.get!("g94h5g84hj9g4gf23i40j")
+      #   document = template.documents!.first
+      #   recipient = template.recipients!.first
+      #   field = template.fields!(document, recipient).first
+      #   field.name = "Field"
+      #   template.modify_field! field, document
+      #
+      # @example Modify envelope field
+      #   envelope = GroupDocs::Signature::Envelope.get!("g94h5g84hj9g4gf23i40j")
+      #   document = envelope.documents!.first
+      #   recipient = envelope.recipients!.first
+      #   field = envelope.fields!(document, recipient).first
+      #   field.name = "Field"
+      #   envelope.modify_field! field, document
+      #
+      # @param [GroupDocs::Signature::Field] field
+      # @param [GroupDocs::Document] document
+      # @param [Hash] access Access credentials
+      # @option access [String] :client_id
+      # @option access [String] :private_key
+      # @raise [ArgumentError] if field is not GroupDocs::Signature::Field
+      # @raise [ArgumentError] if document is not GroupDocs::Document
+      #
+      def modify_field!(field, document, access = {})
+        field.is_a?(GroupDocs::Signature::Field) or raise ArgumentError,
+          "Field should be GroupDocs::Signature::Field object, received: #{field.inspect}"
+        document.is_a?(GroupDocs::Document) or raise ArgumentError,
+          "Document should be GroupDocs::Document object, received: #{document.inspect}"
+
+        # prepare payload
+        payload = field.to_hash # field itself
+        payload.delete(:locations) # remove locations array
+        payload.merge!(field.locations.first.to_hash) # location should added in plain view (i.e. not "locations": [{...}])
+
+        Api::Request.new do |request|
+          request[:access] = access
+          request[:method] = :PUT
+          request[:path] = "/signature/{{client_id}}/#{pluralized_class_name}/#{id}/documents/#{document.file.guid}/field/#{field.id}"
+          request[:request_body] = payload
+        end.execute!
+      end
+
+      #
+      # Deletes field.
+      #
+      # @example Delete field from template
+      #   template = GroupDocs::Signature::Template.get!("g94h5g84hj9g4gf23i40j")
+      #   document = template.documents!.first
+      #   recipient = template.recipients!.first
+      #   field = template.fields!(document, recipient).first
+      #   template.delete_field! field
+      #
+      # @example Delete field from envelope
+      #   envelope = GroupDocs::Signature::Envelope.get!("g94h5g84hj9g4gf23i40j")
+      #   document = envelope.documents!.first
+      #   recipient = envelope.recipients!.first
+      #   field = envelope.fields!(document, recipient).first
+      #   envelope.delete_field! field
+      #
+      # @param [GroupDocs::Signature::Field] field
+      # @param [Hash] access Access credentials
+      # @option access [String] :client_id
+      # @option access [String] :private_key
+      # @raise [ArgumentError] if field is not GroupDocs::Signature::Field
+      #
+      def delete_field!(field, access = {})
+        field.is_a?(GroupDocs::Signature::Field) or raise ArgumentError,
+          "Field should be GroupDocs::Signature::Field object, received: #{field.inspect}"
+
+        Api::Request.new do |request|
+          request[:access] = access
+          request[:method] = :DELETE
+          request[:path] = "/signature/{{client_id}}/#{pluralized_class_name}/#{id}/fields/#{field.id}"
+        end.execute!
+      end
+
+      #
+      # Modifies field location.
+      #
+      # @example Modify field location in template
+      #   template = GroupDocs::Signature::Template.get!("g94h5g84hj9g4gf23i40j")
+      #   document = template.documents!.first
+      #   recipient = template.recipients!.first
+      #   field = template.fields!(document, recipient).first
+      #   location = field.locations.first
+      #   location.x = 0.123
+      #   location.y = 0.123
+      #   location.page = 2
+      #   template.modify_field_location! location, field, document, recipient
+      #
+      # @example Modify field location in envelope
+      #   envelope = GroupDocs::Signature::Envelope.get!("g94h5g84hj9g4gf23i40j")
+      #   document = envelope.documents!.first
+      #   recipient = envelope.recipients!.first
+      #   field = envelope.fields!(document, recipient).first
+      #   location = field.locations.first
+      #   location.x = 0.123
+      #   location.y = 0.123
+      #   location.page = 2
+      #   envelope.modify_field_location! location, field, document, recipient
+      #
+      # @param [GroupDocs::Signature::Field::Location] location
+      # @param [GroupDocs::Signature::Field] field
+      # @param [GroupDocs::Document] document
+      # @param [GroupDocs::Signature::Recipient] recipient
+      # @param [Hash] access Access credentials
+      # @option access [String] :client_id
+      # @option access [String] :private_key
+      # @raise [ArgumentError] if location is not GroupDocs::Signature::Field::Location
+      # @raise [ArgumentError] if field is not GroupDocs::Signature::Field
+      # @raise [ArgumentError] if document is not GroupDocs::Document
+      # @raise [ArgumentError] if recipient is not GroupDocs::Signature::Recipient
+      #
+      def modify_field_location!(location, field, document, recipient, access = {})
+        location.is_a?(GroupDocs::Signature::Field::Location) or raise ArgumentError,
+          "Location should be GroupDocs::Signature::Field::Location object, received: #{location.inspect}"
+        field.is_a?(GroupDocs::Signature::Field) or raise ArgumentError,
+          "Field should be GroupDocs::Signature::Field object, received: #{field.inspect}"
+        document.is_a?(GroupDocs::Document) or raise ArgumentError,
+          "Document should be GroupDocs::Document object, received: #{document.inspect}"
+        recipient.is_a?(GroupDocs::Signature::Recipient) or raise ArgumentError,
+          "Recipient should be GroupDocs::Signature::Recipient object, received: #{recipient.inspect}"
+
+        Api::Request.new do |request|
+          request[:access] = access
+          request[:method] = :PUT
+          request[:path] = "/signature/{{client_id}}/#{pluralized_class_name}/#{id}/documents/#{document.file.guid}/recipient/#{recipient.id}/fields/#{field.id}/locations/#{location.id}"
+          request[:request_body] = location.to_hash
+        end.execute!
+      end
+
+      #
+      # Deletes field location.
+      #
+      # @example Delete field location in template
+      #   template = GroupDocs::Signature::Template.get!("g94h5g84hj9g4gf23i40j")
+      #   document = template.documents!.first
+      #   recipient = template.recipients!.first
+      #   field = template.fields!(document, recipient).first
+      #   location = field.locations.first
+      #   template.delete_field_location! location, field
+      #
+      # @example Delete field location in envelope
+      #   envelope = GroupDocs::Signature::Envelop.get!("g94h5g84hj9g4gf23i40j")
+      #   document = envelope.documents!.first
+      #   recipient = envelope.recipients!.first
+      #   field = envelope.fields!(document, recipient).first
+      #   location = field.locations.first
+      #   envelope.delete_field_location! location, field
+      #
+      # @param [GroupDocs::Signature::Field::Location] location
+      # @param [GroupDocs::Signature::Field] field
+      # @param [Hash] access Access credentials
+      # @option access [String] :client_id
+      # @option access [String] :private_key
+      # @raise [ArgumentError] if location is not GroupDocs::Signature::Field::Location
+      # @raise [ArgumentError] if field is not GroupDocs::Signature::Field
+      #
+      def delete_field_location!(location, field, access = {})
+        location.is_a?(GroupDocs::Signature::Field::Location) or raise ArgumentError,
+          "Location should be GroupDocs::Signature::Field::Location object, received: #{location.inspect}"
+        field.is_a?(GroupDocs::Signature::Field) or raise ArgumentError,
+          "Field should be GroupDocs::Signature::Field object, received: #{field.inspect}"
+
+        Api::Request.new do |request|
+          request[:access] = access
+          request[:method] = :DELETE
+          request[:path] = "/signature/{{client_id}}/#{pluralized_class_name}/#{id}/fields/#{field.id}/locations/#{location.id}"
+        end.execute!
+      end
+
+    end # FieldMethods
+  end # Signature
+end # GroupDocs

data/lib/groupdocs/signature/shared/recipient_methods.rb

@@ -0,0 +1,63 @@
+module GroupDocs
+  class Signature
+    #
+    # Envelope and template entities share the same set of recipient methods.
+    #
+    # @see GroupDocs::Signature::Envelope
+    # @see GroupDocs::Signature::Template
+    #
+    module RecipientMethods
+
+      #
+      # Returns recipients array.
+      #
+      # @param [Hash] access Access credentials
+      # @option access [String] :client_id
+      # @option access [String] :private_key
+      # @return [Array<GroupDocs::Signature::Recipient>]
+      #
+      def recipients!(access = {})
+        json = Api::Request.new do |request|
+          request[:access] = access
+          request[:method] = :GET
+          request[:path] = "/signature/{{client_id}}/#{pluralized_class_name}/#{id}/recipients"
+        end.execute!
+
+        json[:recipients].map do |recipient|
+          Signature::Recipient.new(recipient)
+        end
+      end
+
+      #
+      # Removes recipient.
+      #
+      # @example
+      #   template = GroupDocs::Signature::Template.get!("g94h5g84hj9g4gf23i40j")
+      #   recipient = template.recipients!.first
+      #   template.remove_recipient! recipient
+      #
+      # @example
+      #   envelope = GroupDocs::Signature::Envelope.get!("g94h5g84hj9g4gf23i40j")
+      #   recipient = envelope.recipients!.first
+      #   envelope.remove_recipient! recipient
+      #
+      # @param [GroupDocs::Signature::Recipient] recipient
+      # @param [Hash] access Access credentials
+      # @option access [String] :client_id
+      # @option access [String] :private_key
+      # @raise [ArgumentError] if recipient is not GroupDocs::Signature::Recipient
+      #
+      def remove_recipient!(recipient, access = {})
+        recipient.is_a?(GroupDocs::Signature::Recipient) or raise ArgumentError,
+          "Recipient should be GroupDocs::Signature::Recipient object, received: #{recipient.inspect}"
+
+        Api::Request.new do |request|
+          request[:access] = access
+          request[:method] = :DELETE
+          request[:path] = "/signature/{{client_id}}/#{pluralized_class_name}/#{id}/recipients/#{recipient.id}"
+        end.execute!
+      end
+
+    end # RecipientMethods
+  end # Signature
+end # GroupDocs

data/lib/groupdocs/signature/shared/resource_methods.rb

@@ -0,0 +1,65 @@
+module GroupDocs
+  class Signature
+    #
+    # Envelope and template entities share the same set of resource methods.
+    #
+    # @see GroupDocs::Signature::Form
+    # @see GroupDocs::Signature::Envelope
+    # @see GroupDocs::Signature::Template
+    #
+    module ResourceMethods
+
+      #
+      # Returns a list of resources.
+      #
+      # @example
+      #   resources = GroupDocs::Signature::Envelope.resources!
+      #   resources[:documents]
+      #   #=> [#<GroupDocs::Document>]
+      #   resources[:recipients]
+      #   #=> [#<GroupDocs::Signature::Recipient>]
+      #   resources[:dates]
+      #   #=> ["2012-09-25T00:00:00.0000000"]
+      #
+      # @param [Hash] options Hash of options
+      # @option options [Array<Integer>] :status_ids List of status identifiers to filter. Doesn't work for template
+      # @param [Hash] access Access credentials
+      # @option access [String] :client_id
+      # @option access [String] :private_key
+      # @return [Hash]
+      #
+      def resources!(options = {}, access = {})
+        class_name = self.name.split('::').last.downcase
+
+        # filter doesn't work for template
+        unless class_name == 'template'
+          ids = options.delete(:status_ids)
+          options[:statusIds] = ids.join(?,) if ids
+        end
+
+        api = Api::Request.new do |request|
+          request[:access] = access
+          request[:method] = :GET
+          request[:path] = "/signature/{{client_id}}/#{class_name}s/resources"
+        end
+        api.add_params(options)
+        json = api.execute!
+
+        resources = {}
+        json.each do |key, value|
+          resources[key] = case key
+                           when :documents
+                             value.map { |doc| Document.new(file: Storage::File.new(doc)) }
+                           when :recipients
+                             value.map { |recipient| Signature::Recipient.new(recipient) }
+                           else
+                             value
+                           end
+        end
+
+        resources
+      end
+
+    end # ResourceMethods
+  end # Signature
+end # GroupDocs

data/lib/groupdocs/signature/template.rb

@@ -0,0 +1,104 @@
+module GroupDocs
+  class Signature::Template < Api::Entity
+
+    include Signature::DocumentMethods
+    include Signature::EntityFields
+    include Signature::EntityMethods
+    include Signature::FieldMethods
+    include Signature::RecipientMethods
+    extend  Signature::ResourceMethods
+
+    #
+    # Returns a list of all templates.
+    #
+    # @param [Hash] options Hash of options
+    # @option options [Integer] :page Page to start with
+    # @option options [Integer] :records How many items to list
+    # @param [Hash] access Access credentials
+    # @option access [String] :client_id
+    # @option access [String] :private_key
+    # @return [Array<GroupDocs::Signature::Template>]
+    #
+    def self.all!(options = {}, access = {})
+      api = Api::Request.new do |request|
+        request[:access] = access
+        request[:method] = :GET
+        request[:path] = '/signature/{{client_id}}/templates'
+      end
+      api.add_params(options)
+      json = api.execute!
+
+      json[:templates].map do |template|
+        new(template)
+      end
+    end
+
+    # @attr [Integer] templateExpireTime
+    attr_accessor :templateExpireTime
+
+    # Human-readable accessors
+    alias_method :template_expire_time,  :templateExpireTime
+    alias_method :template_expire_time=, :templateExpireTime=
+
+    #
+    # Adds recipient to template.
+    #
+    # @example
+    #   roles = GroupDocs::Signature::Role.get!
+    #   template = GroupDocs::Signature::Template.get!("g94h5g84hj9g4gf23i40j")
+    #   recipient = GroupDocs::Signature::Recipient.new
+    #   recipient.nickname = 'John Smith'
+    #   recipient.role_id = roles.detect { |role| role.name == "Signer" }.id
+    #   template.add_recipient! recipient
+    #
+    # @param [GroupDocs::Signature::Recipient] recipient
+    # @param [Hash] access Access credentials
+    # @option access [String] :client_id
+    # @option access [String] :private_key
+    # @raise [ArgumentError] if recipient is not GroupDocs::Signature::Recipient
+    #
+    def add_recipient!(recipient, access = {})
+      recipient.is_a?(GroupDocs::Signature::Recipient) or raise ArgumentError,
+        "Recipient should be GroupDocs::Signature::Recipient object, received: #{recipient.inspect}"
+
+      api = Api::Request.new do |request|
+        request[:access] = access
+        request[:method] = :POST
+        request[:path] = "/signature/{{client_id}}/templates/#{id}/recipient"
+      end
+      api.add_params(nickname: recipient.nickname,
+                     role:     recipient.role_id,
+                     order:    recipient.order)
+      api.execute!
+    end
+
+    #
+    # Modify recipient of template.
+    #
+    # @example
+    #   template = GroupDocs::Signature::Template.get!("g94h5g84hj9g4gf23i40j")
+    #   recipient = template.recipients!.first
+    #   recipient.nickname = 'John Smith'
+    #   template.modify_recipient! recipient
+    #
+    # @param [GroupDocs::Signature::Recipient] recipient
+    # @param [Hash] access Access credentials
+    # @option access [String] :client_id
+    # @option access [String] :private_key
+    # @raise [ArgumentError] if recipient is not GroupDocs::Signature::Recipient
+    #
+    def modify_recipient!(recipient, access = {})
+      recipient.is_a?(GroupDocs::Signature::Recipient) or raise ArgumentError,
+        "Recipient should be GroupDocs::Signature::Recipient object, received: #{recipient.inspect}"
+
+      api = Api::Request.new do |request|
+        request[:access] = access
+        request[:method] = :PUT
+        request[:path] = "/signature/{{client_id}}/templates/#{id}/recipient/#{recipient.id}"
+      end
+      api.add_params(nickname: recipient.nickname, role: recipient.role_id, order: recipient.order)
+      api.execute!
+    end
+
+  end # Signature::Template
+end # GroupDocs