groupdocs 1.0.0 → 1.1.0

data/CHANGELOG.md

@@ -1,3 +1,25 @@
+## v1.1
+
+**New**
+
+* Added `Annotation::Reviewer` class
+* Added `Reviewer.all!`
+* Added `Reviewer.set!`
+* Added `Job#delete!`
+* Added `Document#shared_link_access_rights!`
+* Added `Document#set_shared_link_access_rights!`
+* Added `Document#set_reviewers!`
+* Added `Document#add_collaborotor!`
+* More attributes for `User` class
+* Added `Annotation#move_marker!`
+* Added new `Job` action - `:compare`
+
+**Changes**
+
+* Moved `Annotation#collaborators!` and `Annotation#set_collaborators!` to `Document` class as it makes more sense
+* `Document#set_collaborators!` now accepts options `version` parameter (default to `1`)
+
+
 ## v1.0
 
 **New**

data/README.md

@@ -23,7 +23,7 @@ Installing from source
 
 All "bang" methods (ending with exclamation sign) imply interaction with API server.
 
-Other methods (with expect to some methods - see documentation) do not operate with API Server
+Other methods (with expect to some, see documentation) do not operate with API Server
 
 ### Configuration
 
@@ -53,7 +53,9 @@ GroupDocs::Storage::Folder.create!('/folder', client_id: 'your_client_id', priva
 
 ### Documentation
 
-Reference to [this page](http://rubydoc.info/gems/groupdocs) for docs
+Reference to [this page](http://rubydoc.info/gems/groupdocs) for docs and examples.
+
+There are also some examples in [repository](https://github.com/groupdocs/groupdocs-ruby/tree/master/examples) and on [wiki](https://github.com/groupdocs/groupdocs-ruby/wiki)
 
 ### Entities
 

data/lib/groupdocs/api/helpers/access_rights_helper.rb

@@ -0,0 +1,54 @@
+module GroupDocs
+  module Api
+    module Helpers
+      module AccessRights
+
+        include Api::Helpers::ByteFlag
+
+        ACCESS_RIGHTS = {
+          export:   1,
+          download: 2,
+          proof:    4,
+          view:     8,
+        }
+
+        private
+
+        #
+        # Converts shared link access rights array to byte flag.
+        #
+        # @param [Array<String, Symbol>] rights
+        # @return [Integer]
+        # @raise [ArgumentError] if rights is not an array
+        # @raise [ArgumentError] if right is unknown
+        # @api private
+        #
+        def convert_access_rights_to_byte(rights)
+          rights.is_a?(Array) or raise ArgumentError, "Rights should be an array, received: #{rights.inspect}"
+          rights = rights.map(&:to_sym)
+
+          possible_rights = ACCESS_RIGHTS.map { |hash| hash.first }
+          rights.each do |right|
+            possible_rights.include?(right) or raise ArgumentError, "Unknown access right: #{rights.inspect}"
+          end
+
+          byte_from_array(rights, ACCESS_RIGHTS)
+        end
+
+        #
+        # Converts byte flag to shared link access rights array.
+        #
+        # @param [Integer] rights
+        # @return [Array<Symbol>]
+        # @raise [ArgumentError] if rights is not integer
+        # @api private
+        #
+        def convert_byte_to_access_rights(rights)
+          rights.is_a?(Integer) or raise ArgumentError, "Rights should be an integer, received: #{rights.inspect}"
+          array_from_byte(rights, ACCESS_RIGHTS)
+        end
+
+      end # AccessRights
+    end # Helpers
+  end # Api
+end # GroupDocs

data/lib/groupdocs/api/helpers/byte_flag_helper.rb

@@ -0,0 +1,49 @@
+module GroupDocs
+  module Api
+    module Helpers
+      module ByteFlag
+
+        #
+        # Converts array of values to byte flag using hash of value => byte.
+        #
+        # @param [Array<String, Symbol>] values
+        # @param [Hash] value_byte_hash
+        # @return [Integer]
+        # @raise [ArgumentError] if values is not an array
+        # @api private
+        #
+        def byte_from_array(values, value_byte_hash)
+          flag = 0
+          values.each do |value|
+            flag += value_byte_hash[value]
+          end
+
+          flag
+        end
+
+        #
+        # Converts byte flag to array of values using hash of value => byte.
+        #
+        # @param [Integer] byte
+        # @param [Hash] value_byte_hash
+        # @return [Integer]
+        # @api private
+        #
+        def array_from_byte(byte, value_byte_hash)
+          values = []
+
+          value_byte_hash.reverse_each do |value, flag|
+            decreased_byte = byte - flag
+            if decreased_byte >= 0
+              values << value
+              byte = decreased_byte
+            end
+          end
+
+          values
+        end
+
+      end # ByteFlag
+    end # Helpers
+  end # Api
+end # GroupDocs

data/lib/groupdocs/api/helpers.rb

@@ -1,5 +1,6 @@
+require 'groupdocs/api/helpers/byte_flag_helper'
 require 'groupdocs/api/helpers/access_mode_helper'
-require 'groupdocs/api/helpers/actions_helper'
+require 'groupdocs/api/helpers/access_rights_helper'
 require 'groupdocs/api/helpers/credentials_helper'
 require 'groupdocs/api/helpers/path_helper'
 require 'groupdocs/api/helpers/rest_helper'

data/lib/groupdocs/document/annotation/reviewer.rb

@@ -0,0 +1,60 @@
+module GroupDocs
+  class Document::Annotation::Reviewer < Api::Entity
+
+    #
+    # Returns all reviewer contacts.
+    #
+    # @param [Hash] access Access credentials
+    # @option access [String] :client_id
+    # @option access [String] :private_key
+    # @return [Array<GroupDocs::Document::Annotation::Reviewer>]
+    #
+    def self.all!(access = {})
+      json = Api::Request.new do |request|
+        request[:access] = access
+        request[:method] = :GET
+        request[:path] = '/ant/{{client_id}}/contacts'
+      end.execute!
+
+      json[:reviewerContacts].map do |reviewer|
+        new(reviewer)
+      end
+    end
+
+    #
+    # Sets reviewer contacts to passed array.
+    #
+    # Please, note that it removes existing reviewer contacts.
+    #
+    # @example Add new reviewer contact
+    #   reviewers = GroupDocs::Document::Annotation::Reviewer.all!
+    #   reviewers << GroupDocs::Document::Annotation::Reviewer.new(full_name: 'John Smith', email_address: 'john@smith.com')
+    #   GroupDocs::Document::Annotation::Reviewer.set! reviewers
+    #
+    # @param [Array<GroupDocs::Document::Annotation::Reviewer>] reviewers
+    # @param [Hash] access Access credentials
+    # @option access [String] :client_id
+    # @option access [String] :private_key
+    #
+    def self.set!(reviewers, access = {})
+      Api::Request.new do |request|
+        request[:access] = access
+        request[:method] = :PUT
+        request[:path] = '/ant/{{client_id}}/reviewerContacts'
+        request[:request_body] = reviewers.each.map(&:to_hash)
+      end.execute!
+    end
+
+    # @attr [String] emailAddress
+    attr_accessor :emailAddress
+    # @attr [String] FullName
+    attr_accessor :FullName
+
+    # Human-readable accessors
+    alias_method :email_address,         :emailAddress
+    alias_method :email_address=,        :emailAddress=
+    alias_method :full_name,             :FullName
+    alias_method :full_name=,            :FullName=
+
+  end # Document::Annotation::Reviewer
+end # GroupDocs

data/lib/groupdocs/document/annotation.rb

@@ -2,6 +2,7 @@ module GroupDocs
   class Document::Annotation < Api::Entity
 
     require 'groupdocs/document/annotation/reply'
+    require 'groupdocs/document/annotation/reviewer'
 
     include Api::Helpers::AccessMode
 
@@ -181,50 +182,6 @@ module GroupDocs
       end
     end
 
-    #
-    # Returns annotation collaborators.
-    #
-    # @param [Hash] access Access credentials
-    # @option access [String] :client_id
-    # @option access [String] :private_key
-    # @return [Array<GroupDocs::User>]
-    #
-    def collaborators!(access = {})
-      json = Api::Request.new do |request|
-        request[:access] = access
-        request[:method] = :GET
-        request[:path] = "/ant/{{client_id}}/files/#{document.file.guid}/collaborators"
-      end.execute!
-
-      json[:collaborators].map do |collaborator|
-        User.new(collaborator)
-      end
-    end
-
-    #
-    # Sets annotation collaborators to given emails.
-    #
-    # @param [Array] emails List of collaborators' email addresses
-    # @param [Hash] access Access credentials
-    # @option access [String] :client_id
-    # @option access [String] :private_key
-    # @return [Array<GroupDocs::User>]
-    #
-    def collaborators_set!(emails, access = {})
-      json = Api::Request.new do |request|
-        request[:access] = access
-        request[:method] = :PUT
-        request[:path] = "/ant/{{client_id}}/files/#{document.file.guid}/collaborators"
-        request[:request_body] = emails
-      end.execute!
-
-      json[:collaborators].map do |collaborator|
-        User.new(collaborator)
-      end
-    end
-    # note that aliased version cannot accept access credentials hash
-    alias_method :collaborators=, :collaborators_set!
-
     #
     # Removes annotation.
     #
@@ -276,6 +233,24 @@ module GroupDocs
       self.annotation_position = { x: x, y: y }
     end
 
+    #
+    # Moves annotation marker to given coordinates.
+    #
+    # @param [Integer, Float] x
+    # @param [Integer, Float] y
+    # @param [Hash] access Access credentials
+    # @option access [String] :client_id
+    # @option access [String] :private_key
+    #
+    def move_marker!(x, y, access = {})
+      Api::Request.new do |request|
+        request[:access] = access
+        request[:method] = :PUT
+        request[:path] = "/ant/{{client_id}}/annotations/#{guid}/markerPosition"
+        request[:request_body] = { x: x, y: y }
+      end.execute!
+    end
+
     #
     # Sets access mode.
     #

data/lib/groupdocs/document.rb

@@ -16,6 +16,7 @@ module GroupDocs
     }
 
     include Api::Helpers::AccessMode
+    include Api::Helpers::AccessRights
     include Api::Helpers::Status
 
     #
@@ -535,6 +536,134 @@ module GroupDocs
       end
     end
 
+    #
+    # Returns document annotations collaborators.
+    #
+    # @param [Hash] access Access credentials
+    # @option access [String] :client_id
+    # @option access [String] :private_key
+    # @return [Array<GroupDocs::User>]
+    #
+    def collaborators!(access = {})
+      json = Api::Request.new do |request|
+        request[:access] = access
+        request[:method] = :GET
+        request[:path] = "/ant/{{client_id}}/files/#{file.guid}/collaborators"
+      end.execute!
+
+      json[:collaborators].map do |collaborator|
+        User.new(collaborator)
+      end
+    end
+
+    #
+    # Sets document annotations collaborators to given emails.
+    #
+    # @param [Array<String>] emails List of collaborators' email addresses
+    # @param [Integer] version Annotation version
+    # @param [Hash] access Access credentials
+    # @option access [String] :client_id
+    # @option access [String] :private_key
+    # @return [Array<GroupDocs::User>]
+    #
+    def set_collaborators!(emails, version = 1, access = {})
+      json = Api::Request.new do |request|
+        request[:access] = access
+        request[:method] = :PUT
+        request[:path] = "/ant/{{client_id}}/files/#{file.guid}/version/#{version}/collaborators"
+        request[:request_body] = emails
+      end.execute!
+
+      json[:collaborators].map do |collaborator|
+        User.new(collaborator)
+      end
+    end
+
+    #
+    # Adds document annotations collaborator.
+    #
+    # @param [GroupDocs::User] collaborator
+    # @param [Hash] access Access credentials
+    # @option access [String] :client_id
+    # @option access [String] :private_key
+    #
+    def add_collaborator!(collaborator, access = {})
+      collaborator.is_a?(GroupDocs::User) or raise ArgumentError,
+        "Collaborator should be GroupDocs::User object, received: #{collaborator.inspect}"
+
+      Api::Request.new do |request|
+        request[:access] = access
+        request[:method] = :POST
+        request[:path] = "/ant/{{client_id}}/files/#{file.guid}/collaborators"
+        request[:request_body] = collaborator.to_hash
+      end.execute!
+    end
+
+    #
+    # Sets reviewers for document.
+    #
+    # @example Change reviewer rights
+    #   reviewers = document.collaborators!
+    #   reviewers.each do |reviewer|
+    #     reviewer.access_rights = %w(view)
+    #   end
+    #   document.set_reviewers! reviewers
+    #
+    # @param [Array<GroupDocs::User>] reviewers
+    # @param [Hash] access Access credentials
+    # @option access [String] :client_id
+    # @option access [String] :private_key
+    # @return [Array<Symbol>]
+    #
+    def set_reviewers!(reviewers, access = {})
+      Api::Request.new do |request|
+        request[:access] = access
+        request[:method] = :PUT
+        request[:path] = "/ant/{{client_id}}/files/#{file.guid}/reviewerRights"
+        request[:request_body] = reviewers.map(&:to_hash)
+      end.execute!
+    end
+
+    #
+    # Returns an array of access rights for shared link.
+    #
+    # @param [Hash] access Access credentials
+    # @option access [String] :client_id
+    # @option access [String] :private_key
+    # @return [Array<Symbol>]
+    #
+    def shared_link_access_rights!(access = {})
+      json = Api::Request.new do |request|
+        request[:access] = access
+        request[:method] = :GET
+        request[:path] = "/ant/{{client_id}}/files/#{file.guid}/sharedLinkAccessRights"
+      end.execute!
+
+      if json[:accessRights]
+        convert_byte_to_access_rights json[:accessRights]
+      else
+        []
+      end
+    end
+
+    #
+    # Sets access rights for shared link.
+    #
+    # @param [Array<Symbol>] rights
+    # @param [Hash] access Access credentials
+    # @option access [String] :client_id
+    # @option access [String] :private_key
+    # @return [Array<Symbol>]
+    #
+    def set_shared_link_access_rights!(rights, access = {})
+      json = Api::Request.new do |request|
+        request[:access] = access
+        request[:method] = :PUT
+        request[:path] = "/ant/{{client_id}}/files/#{file.guid}/sharedLinkAccessRights"
+        request[:request_body] = convert_access_rights_to_byte(rights)
+      end.execute!
+    end
+
     #
     # Pass all unknown methods to file.
     #

data/lib/groupdocs/job.rb

@@ -1,7 +1,21 @@
 module GroupDocs
   class Job < Api::Entity
 
-    extend Api::Helpers::Actions
+    ACTIONS = {
+      none:                 0,
+      convert:              1,
+      combine:              2,
+      compress_zip:         4,
+      compress_rar:         8,
+      trace:               16,
+      convert_body:        32,
+      bind_data:           64,
+      print:              128,
+      compare:            256,
+      import_annotations: 512,
+    }
+
+    extend Api::Helpers::ByteFlag
     include Api::Helpers::Status
 
     #
@@ -280,5 +294,43 @@ module GroupDocs
       end.execute!
     end
 
+    #
+    # Deletes draft job.
+    #
+    # @param [Hash] access Access credentials
+    # @option access [String] :client_id
+    # @option access [String] :private_key
+    #
+    def delete!(access = {})
+      Api::Request.new do |request|
+        request[:access] = access
+        request[:method] = :DELETE
+        request[:path] = "/async/{{client_id}}/jobs/#{id}"
+      end.execute!
+    end
+
+    private
+
+    #
+    # Converts actions array to byte flag.
+    #
+    # @param [Array<String, Symbol>] actions
+    # @return [Integer]
+    # @raise [ArgumentError] if actions is not an array
+    # @raise [ArgumentError] if action is unknown
+    # @api private
+    #
+    def self.convert_actions_to_byte(actions)
+      actions.is_a?(Array) or raise ArgumentError, "Actions should be an array, received: #{actions.inspect}"
+      actions = actions.map(&:to_sym)
+
+      possible_actions = ACTIONS.map { |hash| hash.first }
+      actions.each do |action|
+        possible_actions.include?(action) or raise ArgumentError, "Unknown action: #{action.inspect}"
+      end
+
+      byte_from_array(actions, ACTIONS)
+    end
+
   end # Job
 end # GroupDocs