hellosign-ruby-sdk 3.0.0

data/lib/hello_sign/api/team.rb

@@ -0,0 +1,88 @@
+module HelloSign
+  module Api
+
+    #
+    # Contains all the api calls for the Team resource.
+    # Take a look at our {https://www.hellosign.com/api/reference#Team team api document}
+    # for more information about this.
+    #
+    # @author [hellosign]
+    #
+    module Team
+
+      #
+      # Returns information about your Team as well as a list of its members.
+      # If you do not belong to a Team, HelloSign::Error::NotFound will be raised
+      #
+      # @return [HelloSign::Resource::Team] your current Team
+      #
+      # @example
+      #   team = @client.get_team
+      def get_team
+        HelloSign::Resource::Team.new get("/team")
+      end
+
+      #
+      # Creates a new Team and makes you a member. You must not currently belong to a Team to invoke.
+      # @option opts [String] name The name of your Team
+      #
+      # @return [HelloSign::Resource::Team] new created Team
+      #
+      # @example
+      #   team = @client.create_team :name => 'Team America World Police'
+      def create_team opts
+        HelloSign::Resource::Team.new post("/team/create", :body => opts)
+      end
+
+      #
+      # Updates the name of your Team.
+      # @option opts [String] name The name of your Team
+      #
+      # @return [HelloSign::Resource::Team] a Team object
+      #
+      # @example
+      #   team = @client.update_team :name => 'New Team Name'
+      def update_team opts
+        HelloSign::Resource::Team.new post("/team", :body => opts)
+      end
+
+      #
+      # Deletes your Team. Can only be invoked when you have a Team with only one member (yourself).
+      #
+      # @example
+      #   team = @client.destroy_team
+      def destroy_team
+        post("/team/destroy")
+      end
+
+      #
+      # Adds or invites a user (specified using the email_address parameter) to your Team.
+      # If the user does not currently have a HelloSign Account, a new one will be created for them.
+      # If the user currently has a paid subscription, they will not automatically join the Team but instead will be sent an invitation to join.
+      # If a user is already a part of another Team, a "team_invite_failed" error will be returned.
+      # @option opts [String] account_id The id of the Account of the user to invite to your Team. The account id prevails if both email_address and acccount_id are provided.
+      # @option opts [String] email_address The email address of the Account of the user to invite to your Team. The account id prevails if both email_address and acccount_id are provided.
+      #
+      # @return [HelloSign::Resource::Team] updated Team object
+      #
+      # @example
+      #   team = @client.add_member_to_team :email_address => 'george@example.com'
+      def add_member_to_team opts
+        HelloSign::Resource::Team.new post("/team/add_member", :body => opts)
+      end
+
+
+      #
+      # Removes a user from your Team. If the user had an outstanding invitation to your Team the invitation will be expired.
+      # @option opts [String] account_id The id of the Account of the user to invite to your Team. The account id prevails if both email_address and acccount_id are provided.
+      # @option opts [String] email_address The email address of the Account of the user to invite to your Team. The account id prevails if both email_address and acccount_id are provided.
+      #
+      # @return [HelloSign::Resource::Team] updated Team object
+      # @example
+      #   team = @client.remove_member_from_team :email_address => 'george@example.com'
+      def remove_member_from_team opts
+        HelloSign::Resource::Team.new post("/team/remove_member", :body => opts)
+      end
+    end
+  end
+end

data/lib/hello_sign/api/template.rb

@@ -0,0 +1,77 @@
+module HelloSign
+  module Api
+
+    #
+    # Contains all the api calls for the Template resource.
+    # Take a look at our {https://www.hellosign.com/api/templatesAndApiWalkthrough template form api document}
+    # for more information about this.
+    #
+    # @author [hellosign]
+    #
+    module Template
+
+      #
+      # Retrieves the Template specified by the id parameter.
+      # @option opts [String] template_id The id of the Template to retrieve.
+      #
+      # @return [HelloSign::Resource::Template] a Template object
+      #
+      # @example
+      #   template = @client.get_template :template_id => 'f57db65d3f933b5316d398057a36176831451a35'
+      #
+      def get_template opts
+        HelloSign::Resource::Template.new get("/template/#{opts[:template_id]}")
+      end
+
+      #
+      # Retrieves the Templates for the current user account.
+      #
+      # @option opts [Integer] page (1) Which page number of the Template List to return.
+      #
+      # @return [HelloSign::Resource::ResourceArray] a ResourceArray object
+      # @example
+      #   templates = @client.get_templates :page => 1
+      #
+      def get_templates opts={}
+        path = '/template/list'
+        path += opts[:page] ? "?page=#{opts[:page]}" : ""
+        HelloSign::Resource::ResourceArray.new get(path, opts), "templates", HelloSign::Resource::Template
+      end
+
+
+      #
+      # Gives the specified Account on your team access to a Template
+      #
+      # @option opts [String] template_id The id of the Template to give access to.
+      # @option opts [String] account_id The id of the Account to get access. The account_id prevails if account_id and email_address are both provided.
+      # @option opts [String] email_address The email address of the Account to give access to the Template. The account_id prevails if account_id and email_address are both provided.
+      #
+      # @return [Template] a Template object
+      # @example
+      #   templates = @client.add_user_to_template :template_id => 'f57db65d3f933b5316d398057a36176831451a35', :email_address => 'george@example.com'
+      #
+      def add_user_to_template opts
+        path = "/template/add_user/#{opts[:template_id]}"
+        opts.delete(:template_id)
+        HelloSign::Resource::Template.new post(path, :body => opts)
+      end
+
+      #
+      # Removes the specified Account's access to the specified Template.
+      # The user can be designated using their account ID or email address.
+      # @option opts [String] template_id The id of the Template to remove the Account access to.
+      # @option opts [String] account_id The id of the Account to remove access to the Template. The account_id prevails if account_id and email_address are both provided.
+      # @option opts [String] email_address The email address of the Account to remove access to the Template. The account_id prevails if account_id and email_address are both provided.
+      #
+      # @return [Template] a Template object
+      # @example
+      #   templates = @client.remove_user_from_template :template_id => 'f57db65d3f933b5316d398057a36176831451a35', :email_address => 'george@example.com'
+      #
+      def remove_user_from_template opts
+        path = "/template/remove_user/#{opts[:template_id]}"
+        opts.delete(:template_id)
+        HelloSign::Resource::Template.new post(path, :body => opts)
+      end
+    end
+  end
+end

data/lib/hello_sign/api/unclaimed_draft.rb

@@ -0,0 +1,127 @@
+module HelloSign
+  module Api
+
+    #
+    # Contains all the api calls for the UnclaimedDraft resource.
+    # Take a look at our {https://www.hellosign.com/api/reference#UnclaimedDraft unclaimed draft document}
+    # for more information about this.
+    #
+    # @author [hellosign]
+    #
+    module UnclaimedDraft
+
+      #
+      # Creates a new Draft that can be claimed using the claim URL.
+      # The first authenticated user to access the URL will claim the Draft and will be shown either the "Sign and send" or the "Request signature" page with the Draft loaded.
+      # Subsequent access to the claim URL will result in a 404 not found.
+      # If the type is "send_document" then only the file parameter is required.
+      # If the type is "request_signature", then the identities of the signers and optionally
+      # the location of signing elements on the page are also required.
+      # @option opts [Integer] test_mode (0) Whether this is a test, the signature request will not be legally binding if set to 1.
+      # @option opts [Array<String>] files Use files to indicate the uploaded file(s) to send for signature. Currently we only support use of either the files parameter or file_urls parameter, not both.
+      # @option opts [Array<String>] file_urls Use file_urls to have HelloSign download the file(s) to send for signature. Currently we only support use of either the files parameter or file_urls parameter, not both.
+      # @option opts [String] type The type of unclaimed draft to create. Use "send_document" to create a claimable file, and "request_signature" for a claimable signature request. If the type is "request_signature" then signers name and email_address are not optional.
+      # @option opts [String] subject The subject in the email that will be sent to the signers.
+      # @option opts [String] message The custom message in the email that will be sent to the signers.
+      # @option opts [String] signing_redirect_url The URL you want the signer redirected to after they successfully sign. (optional)
+      #
+      # @option opts [Array<Hash>] signers List of signers, each item is a Hash with these keys:
+      #   * :name (String) Sender' name
+      #   * :email_address (String) Sender's email address
+      #   * :order (Integer) The order the signer is required to sign in (optional)
+      #   * :pin (Integer) The 4-digit code that will secure this signer's signature page. You must have a business plan to use this feature. (optional)
+      # @option opts [Array<String>] cc_email_addresses The email addresses that should be CCed.
+      # @option opts [String] form_fields_per_document
+      #
+      # @return [HelloSign::Resource::UnclaimedDraft] a UnclaimedDraft object
+      #
+      # @example send_document
+      #   unclaimed_draft = @client.create_unclaimed_draft(
+      #     :test_mode => 1,
+      #     :files => ['NDA.pdf', 'AppendixA.pdf']
+      #   )
+      # @example request_signature
+      #   unclaimed_draft = @client.create_unclaimed_draft(
+      #     :test_mode => 1,
+      #     :type => 'request_signature',
+      #     :subject => 'The NDA we talked about',
+      #     :message => 'Please sign this NDA and then we can discuss more. Let me know if you have any questions.',
+      #     :signers => [{
+      #         :email_address => 'jack@example.com',
+      #         :name => 'Jack',
+      #         :order => 0
+      #       },{
+      #         :email_address => 'jill@example.com',
+      #         :name => 'Jill',
+      #         :order => 1
+      #       }
+      #     ],
+      #     :cc_email_addresses => ['lawyer@example.com', 'lawyer@example2.com'],
+      #     :files => ['NDA.pdf', 'AppendixA.pdf']
+      #   )
+      #
+      def create_unclaimed_draft opts
+        prepare_files opts
+        if opts[:type] == 'request_signature'
+          prepare_signers opts
+        end
+
+        HelloSign::Resource::UnclaimedDraft.new post('/unclaimed_draft/create', :body => opts)
+      end
+
+
+      #
+      # Creates a new embedded unclaimed draft object that can be launched in an iframe using the claim URL.
+      # @option opts [Integer] test_mode (0) Whether this is a test, the signature request will not be legally binding if set to 1.
+      # @option opts [Integer] is_for_embedded_signing set this to 1 to to mix embedded requesting and embedded signing.
+      # @option opts [Array<String>] files Use files to indicate the uploaded file(s) to send for signature. Currently we only support use of either the files parameter or file_urls parameter, not both.
+      # @option opts [Array<String>] file_urls Use file_urls to have HelloSign download the file(s) to send for signature. Currently we only support use of either the files parameter or file_urls parameter, not both.
+      # @option opts [String] type The type of unclaimed draft to create. Should be "request_signature" for a claimable signature request. If the type is "request_signature" then signers name and email_address are not optional.
+      # @option opts [String] subject The subject in the email that will be sent to the signers.
+      # @option opts [String] requester_email_address The email address of the requester.
+      # @option opts [String] message The custom message in the email that will be sent to the signers.
+      # @option opts [String] signing_redirect_url The URL you want the signer redirected to after they successfully sign. (optional)
+      #
+      # @option opts [Array<Hash>] signers List of signers, each item is a Hash with these keys:
+      #   * :name (String) Sender' name
+      #   * :email_address (String) Sender's email address
+      #   * :order (Integer) The order the signer is required to sign in (optional)
+      #   * :pin (Integer) The 4-digit code that will secure this signer's signature page. You must have a business plan to use this feature. (optional)
+      # @option opts [Array<String>] cc_email_addresses The email addresses that should be CCed.
+      #
+      # @return [HelloSign::Resource::UnclaimedDraft] a UnclaimedDraft object
+
+      # @example request_signature
+      #   unclaimed_draft = @client.create_embedded_unclaimed_draft(
+      #     :test_mode => 1,
+      #     :type => 'request_signature',
+      #     :subject => 'The NDA we talked about',
+      #     :requester_email_address => requester@example.com",
+      #     :message => 'Please sign this NDA and then we can discuss more. Let me know if you have any questions.',
+      #     :signers => [{
+      #         :email_address => 'jack@example.com',
+      #         :name => 'Jack',
+      #         :order => 0
+      #       },{
+      #         :email_address => 'jill@example.com',
+      #         :name => 'Jill',
+      #         :order => 1
+      #       }
+      #     ],
+      #     :cc_email_addresses => ['lawyer@example.com', 'lawyer@example2.com'],
+      #     :files => ['NDA.pdf', 'AppendixA.pdf']
+      #   )
+      #
+      def create_embedded_unclaimed_draft opts
+        opts[:client_id] ||= self.client_id
+        prepare_files opts
+        if opts[:type] == 'request_signature'
+          prepare_signers opts
+        end
+
+        HelloSign::Resource::UnclaimedDraft.new post('/unclaimed_draft/create_embedded', :body => opts)
+      end
+
+    end
+  end
+end

data/lib/hello_sign/client.rb

@@ -0,0 +1,211 @@
+require 'faraday'
+require 'multi_json'
+require 'hello_sign/error'
+require 'hello_sign/configuration'
+require 'hello_sign/resource'
+require 'hello_sign/api'
+require 'logger'
+
+module HelloSign
+
+  #
+  # You'll need the HelloSign::Client to do just about everything, from creating
+  # signatures to updating account information.
+  #
+  # @example
+  #   client = HelloSign::Client.new :email_address => "me@hellosign.com", :password => "mypassword"
+  #
+  # @author [hellosign]
+  class Client
+    include Api::Account
+    include Api::SignatureRequest
+    include Api::Template
+    include Api::Team
+    include Api::UnclaimedDraft
+    include Api::Embedded
+    include Api::OAuth
+
+    attr_accessor :end_point, :oauth_end_point, :api_version, :user_agent, :client_id, :client_secret, :email_address, :password, :api_key, :auth_token, :logging, :log_level
+
+    ERRORS = {
+      400 => Error::BadRequest,
+      401 => Error::Unauthorized,
+      403 => Error::Forbidden,
+      404 => Error::NotFound,
+      405 => Error::MethodNotAllowed,
+      409 => Error::Conflict,
+      410 => Error::Gone,
+      500 => Error::InternalServerError,
+      502 => Error::BadGateway,
+      503 => Error::ServiceUnavailable
+    }
+
+    #
+    # Creates a new HelloSign Client
+
+    # @option opts [String] email_address email address
+    # @option opts [String] password password
+    # @option opts [String] api_key Api key
+    # @return [HelloSign::Client] a new HelloSign::Client
+    def initialize(opts={})
+      options = HelloSign.options.merge(opts)
+      HelloSign::Configuration::VALID_OPTIONS_KEYS.each do |key|
+        self.send("#{key}=", options[key])
+      end
+    end
+
+    #
+    # Make a http get request
+    # @param  path [String] relative path of the request
+    # @option options [Hash] params params of the url
+    #
+    def get(path, options={})
+      response = request(path, :get, options)
+      validate response
+      parse response
+    end
+
+    #
+    # Make a http post request
+    # @param  path [String] relative path of the request
+    # @option options [Hash] params params of the url
+    # @option options [Hash] body request body
+    #
+    def post(path, options={})
+      response = request(path, :post, options)
+      validate response
+      parse response
+    end
+
+    #
+    # Make a http put request
+    # @param  path [String] relative path of the request
+    # @option options [Hash] params params of the url
+    # @option options [Hash] body request body
+    #
+    def put(path, options={})
+      response = request(path, :put, options)
+      validate response
+      parse response
+    end
+
+    #
+    # Make a http delete request
+    # @param  path [String] relative path of the request
+    # @option options [Hash] params params of the url
+    #
+    def delete(path, options={})
+      response = request(path, :delete, options)
+      validate response
+      parse response
+    end
+
+    private
+
+    def request(path, method, options={})
+      make_connection(options).send method do |request|
+        if options[:oauth_request]
+          request.url "#{path}", options[:params]
+        else
+          request.url "#{api_version}#{path}", options[:params]
+        end
+        request.body = options[:body]
+      end
+    end
+
+    def make_connection options
+      url = options[:oauth_request] ? oauth_end_point : end_point
+
+      if @logging
+        logger = Logger.new(STDOUT)
+        logger.level = @log_level
+      end
+
+      connection = Faraday.new(:url => url, :headers => {user_agent: user_agent}) do |faraday|
+        faraday.request  :multipart
+        faraday.request  :url_encoded
+        faraday.response :logger, logger if @logging
+        faraday.adapter  :net_http
+      end
+      if options[:no_auth]
+      elsif auth_token
+        connection.authorization :Bearer, auth_token
+      elsif api_key
+        connection.basic_auth api_key, ''
+      elsif email_address
+        connection.basic_auth email_address, password
+      else
+      end
+      connection
+    end
+
+    def validate(response)
+      if response.status >= 400
+        raise ERRORS[response.status].new error_message(response)
+      end
+    end
+
+    def parse(response)
+      if response["content-type"] == "application/pdf"
+        response.body
+      elsif response.body.strip.empty?
+        {}
+      else
+        MultiJson.load response.body
+      end
+    end
+
+    def error_message(response)
+      "Server responded with code #{response.status}\n" \
+      "Request URI: #{response.to_hash[:url].to_s}\n"\
+      "Message: #{response.body}"
+    end
+
+    def prepare_files opts
+      if opts[:files]
+        opts[:files].each_with_index do |file, index|
+          if file.is_a? String
+            opts[:"file[#{index}]"] = Faraday::UploadIO.new(file, 'application/pdf')
+          elsif defined? ActionDispatch::Http::UploadedFile
+            if file.is_a? ActionDispatch::Http::UploadedFile
+              opts[:"file[#{index}]"] = UploadIO.new(file.tempfile, 'application/pdf')
+            end
+          else
+            raise HelloSign::Error::NotSupportedType.new "#{file.class} is not a supported. Must be a string or ActionDispatch::Http::UploadedFile"
+          end
+        end
+        opts.delete(:files)
+      elsif opts[:file_urls]
+        opts[:file_urls].each_with_index do |file, index|
+          opts[:"file_url[#{index}]"] = file
+        end
+        opts.delete(:file_urls)
+      end
+    end
+
+    def prepare_signers opts
+      prepare opts, :signers
+    end
+
+    def prepare_ccs opts
+      prepare opts, :ccs
+    end
+
+    def prepare opts, key
+      return unless opts[key]
+      opts[key].each_with_index do |value, index|
+        if value.is_a? String
+          opts[:"#{key}[#{index}]"] = value
+        else
+          if value[:role]
+            opts[:"#{key}[#{value[:role]}]"] = value
+            value.delete(:role)
+          else
+            opts[:"#{key}[#{index}]"] = value
+          end
+        end
+      end
+      opts.delete(key)
+    end
+  end
+end