justrelate_sdk 1.0.0.rc1

data/lib/justrelate/account.rb

@@ -0,0 +1,17 @@
+module JustRelate
+  # A JustRelate account is an organizational entity such as a company.
+  # @api public
+  class Account < Core::BasicResource
+    include Core::Mixins::Findable
+    include Core::Mixins::Modifiable
+    include Core::Mixins::ChangeLoggable
+    include Core::Mixins::MergeAndDeletable
+    include Core::Mixins::Searchable
+    include Core::Mixins::Inspectable
+    inspectable :id, :name
+
+    # @!parse extend Core::Mixins::Findable::ClassMethods
+    # @!parse extend Core::Mixins::Modifiable::ClassMethods
+    # @!parse extend Core::Mixins::Searchable::ClassMethods
+  end
+end

data/lib/justrelate/activity.rb

@@ -0,0 +1,143 @@
+module JustRelate
+  # A JustRelate activity is a record of an action or a sequence of actions,
+  # for example a support case.
+  # It can be associated with an {Account account} or a {Contact contact}.
+  #
+  # === Comments
+  # Comments can be read be means of {#comments}.
+  # In order to add a comment, set the following write-only attributes on {.create} or {#update}:
+  # * +comment_notes+ (String) - the comment text.
+  # * +comment_contact_id+ (String) - the contact ID of the comment author (optional).
+  # * +comment_published+ (Boolean) - whether the comment should be visible
+  #   to the associated contact of this activity (+item.contact_id+).
+  #   Default: +false+.
+  # * +comment_attachments+ (Array<String, #read>) - the comment attachments (optional).
+  #   Every array element may either be an attachment ID or an object that implements +#read+
+  #   (e.g. an open file). In the latter case, the content will be
+  #   uploaded automatically. See {JustRelate::Core::AttachmentStore} for manually uploading attachments.
+  # @api public
+  class Activity < Core::BasicResource
+    include Core::Mixins::Findable
+    include Core::Mixins::Modifiable
+    include Core::Mixins::ChangeLoggable
+    include Core::Mixins::Searchable
+    include Core::Mixins::Inspectable
+    inspectable :id, :title, :type_id
+
+    # @!parse extend Core::Mixins::Findable::ClassMethods
+    # @!parse extend Core::Mixins::Modifiable::ClassMethods
+    # @!parse extend Core::Mixins::Searchable::ClassMethods
+
+    # Creates a new activity using the given +params+.
+    # See {Core::Mixins::Modifiable::ClassMethods#create Modifiable.create} for details.
+    # @return [self] the created activity.
+    # @api public
+    def self.create(attributes = {})
+      super(filter_attributes(attributes))
+    end
+
+    # Updates the attributes of this activity.
+    # See {Core::Mixins::Modifiable#update Modifiable#update} for details.
+    # @return [self] the updated activity.
+    # @api public
+    def update(attributes = {})
+      super(self.class.filter_attributes(attributes))
+    end
+
+    # +Comment+ represents a comment of an {Activity Activity},
+    # for example a single comment of a support case discussion.
+    # @api public
+    class Comment
+      include Core::Mixins::AttributeProvider
+
+      # +Attachment+ represents an attachment of an {Activity::Comment activity comment}.
+      # @api public
+      class Attachment
+        # Returns the ID of this attachment.
+        # @return [String]
+        # @api public
+        attr_reader :id
+
+        def initialize(id)
+          @id = id
+        end
+
+        # Generates a download URL for this attachment.
+        # Retrieve the attachment data by fetching this URL.
+        # This URL is only valid for a couple of minutes.
+        # Hence, it is recommended to have such URLs generated on demand.
+        # @return [String]
+        # @api public
+        def download_url
+          JustRelate::Core::AttachmentStore.generate_download_url(id)
+        end
+      end
+
+      def initialize(raw_comment)
+        comment = raw_comment.dup
+        comment['attachments'] = raw_comment['attachments'].map{ |attachment_id|
+          Attachment.new(attachment_id)
+        }
+        super(comment)
+      end
+
+      # @!attribute [r] attachments
+      #   Returns the list of comment {Attachment attachments}.
+      #   @return [Array<Attachment>]
+      #   @api public
+
+      # @!attribute [r] updated_at
+      #   Returns the timestamp of the comment.
+      #   @return [Time]
+      #   @api public
+
+      # @!attribute [r] updated_by
+      #   Returns the login of the API user who created the comment.
+      #   @return [String]
+      #   @api public
+
+      # @!attribute [r] notes
+      #   Returns the comment text.
+      #   @return [String]
+      #   @api public
+
+      # @!attribute [r] published?
+      # Returns whether the comment is published.
+      # @return [Boolean]
+      # @api public
+      def published?
+        published
+      end
+    end
+
+    # @!attribute [r] comments
+    # Returns the {Comment comments} of this activity.
+    # @return [Array<Comment>]
+    # @api public
+
+    def self.filter_attributes(attributes)
+      attachments = attributes.delete('comment_attachments') ||
+          attributes.delete(:comment_attachments)
+      if attachments
+        attributes['comment_attachments'] = attachments.map do |attachment|
+          if attachment.respond_to?(:read)
+            Core::AttachmentStore.upload(attachment)
+          else
+            attachment
+          end
+        end
+      end
+      attributes
+    end
+
+    protected
+
+    def load_attributes(raw_attributes)
+      attributes = raw_attributes.dup
+      attributes['comments'] = (attributes['comments'] || []).map do |comment_attributes|
+        Comment.new(comment_attributes)
+      end
+      super(attributes)
+    end
+  end
+end

data/lib/justrelate/collection.rb

@@ -0,0 +1,41 @@
+module JustRelate
+  # A JustRelate collection is a saved search. To execute such a saved search, call {#compute}.
+  # The results are persisted and can be accessed by means of {#output_items}.
+  # Output items can be {Account accounts}, {Contact contacts}, {Activity activities},
+  # and {Event events}.
+  # @api public
+  class Collection < Core::BasicResource
+    include Core::Mixins::Findable
+    include Core::Mixins::Modifiable
+    include Core::Mixins::ChangeLoggable
+    include Core::Mixins::Searchable
+    include Core::Mixins::Inspectable
+    inspectable :id, :title
+
+    # @!parse extend Core::Mixins::Findable::ClassMethods
+    # @!parse extend Core::Mixins::Modifiable::ClassMethods
+    # @!parse extend Core::Mixins::Searchable::ClassMethods
+
+    # Computes this collection.
+    # @return [self]
+    # @api public
+    def compute
+      load_attributes(Core::RestApi.instance.put("#{path}/compute", {}))
+    end
+
+    # Returns the IDs resulting from the computation.
+    # @return [Array<String>]
+    # @api public
+    def output_ids
+      Core::RestApi.instance.get("#{path}/output_ids")
+    end
+
+    # Returns an {Core::ItemEnumerator ItemEnumerator}
+    # that provides access to the items of {#output_ids}.
+    # @return [Core::ItemEnumerator]
+    # @api public
+    def output_items
+      Core::ItemEnumerator.new(output_ids)
+    end
+  end
+end

data/lib/justrelate/contact.rb

@@ -0,0 +1,121 @@
+module JustRelate
+  # A JustRelate contact represents contact information about a person.
+  # It can be associated with an {Account account}.
+  # @api public
+  class Contact < Core::BasicResource
+    include Core::Mixins::Findable
+    include Core::Mixins::Modifiable
+    include Core::Mixins::ChangeLoggable
+    include Core::Mixins::MergeAndDeletable
+    include Core::Mixins::Searchable
+    include Core::Mixins::Inspectable
+    inspectable :id, :last_name, :first_name, :email
+
+    # @!parse extend Core::Mixins::Findable::ClassMethods
+    # @!parse extend Core::Mixins::Modifiable::ClassMethods
+    # @!parse extend Core::Mixins::Searchable::ClassMethods
+
+    # @!group Authentication and password management
+
+    # Authenticates a contact using their +login+ and +password+.
+    # @example
+    #   contact = JustRelate::Contact.authenticate!('jane@example.org', 'correct')
+    #   # => JustRelate::Contact
+    #
+    #   contact.login
+    #   # => 'jane@example.org'
+    #
+    #   JustRelate::Contact.authenticate!('jane@example.org', 'wrong')
+    #   # => raises AuthenticationFailed
+    # @param login [String] the login of the contact.
+    # @param password [String] the password of the contact.
+    # @return [Contact] the authenticated contact.
+    # @raise [Errors::AuthenticationFailed] if the +login+/+password+ combination is wrong.
+    # @api public
+    def self.authenticate!(login, password)
+      new(Core::RestApi.instance.put("#{path}/authenticate",
+          {'login' => login, 'password' => password}))
+    end
+
+    # Authenticates a contact using their +login+ and +password+.
+    # @example
+    #   contact = JustRelate::Contact.authenticate('jane@example.org', 'correct')
+    #   # => JustRelate::Contact
+    #
+    #   contact.login
+    #   # => 'jane@example.org'
+    #
+    #   JustRelate::Contact.authenticate('jane@example.org', 'wrong')
+    #   # => nil
+    # @param login [String] the login of the contact.
+    # @param password [String] the password of the contact.
+    # @return [Contact, nil] the authenticated contact. +nil+ if authentication failed.
+    # @api public
+    def self.authenticate(login, password)
+      authenticate!(login, password)
+    rescue Errors::AuthenticationFailed
+      nil
+    end
+
+    # Sets the new password.
+    # @param new_password [String] the new password.
+    # @return [self] the updated contact.
+    # @api public
+    def set_password(new_password)
+      load_attributes(Core::RestApi.instance.put("#{path}/set_password",
+          {'password' => new_password}))
+    end
+
+    # Generates a password token.
+    #
+    # Use case: A project sends an e-mail to the contact. The e-mail contains a link to
+    # the project web app. The link contains the param +?token=...+.
+    # The web app retrieves and parses the token
+    # and passes it to {Contact.set_password_by_token}.
+    # @return [String] the generated token.
+    # @api public
+    def generate_password_token
+      Core::RestApi.instance.post("#{path}/generate_password_token", {})['token']
+    end
+
+    # Sets a contact's new password by means of the token. Generate a token by calling
+    # {#send_password_token_email} or {#generate_password_token}.
+    #
+    # Use case: A contact clicks a link (that includes a token) in an e-mail
+    # to get to a password change page.
+    # @param new_password [String] the new password.
+    # @param token [String] the given token.
+    # @return [Contact] the updated contact.
+    # @raise [Errors::ResourceNotFound] if +token+ is invalid.
+    # @api public
+    def self.set_password_by_token(new_password, token)
+      new(Core::RestApi.instance.put("#{path}/set_password_by_token", {
+        'password' => new_password,
+        'token' => token,
+      }))
+    end
+
+    # Clears the contact's password.
+    # @return [self] the updated contact.
+    # @api public
+    def clear_password
+      load_attributes(Core::RestApi.instance.put("#{path}/clear_password", {}))
+    end
+
+    # Sends a password token by e-mail to this contact.
+    #
+    # Put a link to the project web app into the +password_request_email_body+ template.
+    # The link should contain the +?token=...+ parameter, e.g.:
+    #
+    # <tt>https://example.com/user/set_password?token={{password_request_token}}</tt>
+    #
+    # The web app can then pass the token to {Contact.set_password_by_token}.
+    # @return [void]
+    # @api public
+    def send_password_token_email
+      Core::RestApi.instance.post("#{path}/send_password_token_email", {})
+    end
+
+    # @!endgroup
+  end
+end

data/lib/justrelate/core/attachment_store.rb

@@ -0,0 +1,122 @@
+module JustRelate; module Core
+  # +AttachmentStore+ represents an attachment of an {Activity::Comment activity comment}.
+  #
+  # To upload a file as an attachment, add it to +comment_attachments+. The SDK will automatically
+  # upload the content of the file.
+  #
+  # Note that this method of uploading an attachment using a browser will upload the file twice.
+  # It is first uploaded to the ruby application (e.g. Rails) which then uploads it to AWS S3.
+  #
+  # To upload the attachment directly to AWS S3 (i.e. bypassing the ruby application),
+  # please proceed as follows:
+  #
+  # 1. Request an upload permission
+  #    ({JustRelate::Core::AttachmentStore.generate_upload_permission AttachmentStore.generate_upload_permission}).
+  #    The response grants the client permission to upload a file to a given key on AWS S3.
+  #    This permission is valid for one hour.
+  # 2. Upload the file to the URL (+permission.url+ or
+  #    +permission.uri+), together with the fields (+permission.fields+) as parameters.
+  #    AWS S3 itself then verifies the signature of these parameters prior to accepting the upload.
+  # 3. Attach the upload to a new activity comment by setting its +comment_attachments+ attribute
+  #    to an array of upload IDs. The client may append filenames to the upload IDs for producing
+  #    download URLs with proper filenames later on.
+  #
+  #    The format of +comment_attachments+ is
+  #    <tt>["upload_id/filename.ext", ...]</tt>,
+  #    e.g. <tt>["e13f0d960feeb2b2903bd/screenshot.jpg"]</tt>.
+  #    JustRelate in turn translates these upload IDs to attachment IDs.
+  #    Syntactically they look the same. Upload IDs, however, are only temporary,
+  #    whereas attachment IDs are permanent. If the client appended a filename to the upload ID,
+  #    the attachment ID will contain this filename, too. Otherwise, the attachment ID ends
+  #    with <tt>"/file"</tt>. Please note that JustRelate replaces filename characters other
+  #    than <tt>a-zA-Z0-9.+-</tt> with a dash. Multiple dashes will be joined into a single dash.
+  # 4. Later, when downloading the attachment, pass the attachment ID to
+  #    {JustRelate::Core::AttachmentStore.generate_download_url}.
+  #    JustRelate returns a signed AWS S3 URL that remains valid for 5 minutes.
+  # @api public
+  class AttachmentStore
+    # +Permission+ holds all the pieces of information required to upload an {AttachmentStore attachment}.
+    # Generate a permission by calling {AttachmentStore.generate_upload_permission}.
+    # @api public
+    class Permission
+      # Returns the {http://www.ruby-doc.org/stdlib/libdoc/uri/rdoc/URI.html URI}
+      # for uploading the new attachment data.
+      # @return [URI]
+      # @api public
+      attr_reader :uri
+
+      # Returns the URL for uploading the new attachment data.
+      # @return [String]
+      # @api public
+      attr_reader :url
+
+      # Returns a hash of additional request parameters to be sent to the {#url}.
+      # @return [Hash{String => String}]
+      # @api public
+      attr_reader :fields
+
+      # Returns a temporary ID associated with this upload.
+      # Use this ID when setting the +comment_attachments+ attribute of an activity.
+      # @return [String]
+      # @api public
+      attr_reader :upload_id
+
+      def initialize(uri, url, fields, upload_id)
+        @uri, @url, @fields, @upload_id = uri, url, fields, upload_id
+      end
+    end
+
+    class << self
+
+      # Obtains the permission to upload a file manually.
+      # The permission is valid for a couple of minutes.
+      # Hence, it is recommended to have such permissions generated on demand.
+      # @return [Permission]
+      # @api public
+      def generate_upload_permission
+        perm = Core::RestApi.instance.post("attachment_store/generate_upload_permission", {})
+        uri = resolve_uri(perm["url"])
+        Permission.new(uri, uri.to_s, perm["fields"], perm["upload_id"])
+      end
+
+      # Generates a download URL for the given attachment.
+      # The URL is valid for a couple of minutes.
+      # Hence, it is recommended to have such URLs generated on demand.
+      # @param attachment_id [String] the ID of an attachment.
+      # @return [String]
+      # @api public
+      def generate_download_url(attachment_id)
+        response = Core::RestApi.instance.post("attachment_store/generate_download_url",
+            {'attachment_id' => attachment_id})
+        resolve_uri(response["url"]).to_s
+      end
+
+      # Uploads a file to S3.
+      # @param file [File] the file to be uploaded.
+      # @return [String] the upload ID. Add this ID to the +comment_attachments+ attribute
+      #   of an activity.
+      def upload(file)
+        permission = generate_upload_permission
+
+        file_name = File.basename(file.path)
+        upload_io = UploadIO.new(file, 'application/octet-stream', file_name)
+        params = permission.fields.merge(file: upload_io)
+        request = Net::HTTP::Post::Multipart.new(permission.uri, params)
+
+        response = Core::ConnectionManager.new(permission.uri).request(request)
+
+        if response.code.starts_with?('2')
+          [permission.upload_id, file_name].compact.join('/')
+        else
+          raise Errors::ServerError, "File upload failed with code #{response.code}"
+        end
+      end
+
+      private
+
+      def resolve_uri(url)
+        Core::RestApi.instance.resolve_uri(url)
+      end
+    end
+  end
+end; end

data/lib/justrelate/core/basic_resource.rb

@@ -0,0 +1,68 @@
+module JustRelate; module Core
+  # +BasicResource+ is the base class of all JustRelate resources.
+  # @api public
+  class BasicResource
+    include Mixins::AttributeProvider
+
+    def self.base_type
+      name.split(/::/).last
+    end
+
+    def self.resource_name
+      base_type.underscore
+    end
+
+    def self.path
+      resource_name.pluralize
+    end
+
+    # Returns the ID of this item.
+    # @return [String]
+    # @api public
+    def id
+      self['id']
+    end
+
+    def path
+      [self.class.path, id].compact.join('/')
+    end
+
+    # Returns the type object of this item.
+    # @return [JustRelate::Type]
+    # @api public
+    def type
+      ::JustRelate::Type.find(type_id)
+    end
+
+    # Reloads the attributes of this item from the remote web service.
+    # @example
+    #   contact.locality
+    #   # => 'Bergen'
+    #
+    #   # Assume this contact has been modified concurrently.
+    #
+    #   contact.reload
+    #   # => JustRelate::Contact
+    #
+    #   contact.locality
+    #   # => 'Oslo'
+    # @return [self] the reloaded item.
+    # @api public
+    def reload
+      load_attributes(RestApi.instance.get(path))
+    end
+
+    def eql?(other)
+      other.equal?(self) || other.instance_of?(self.class) && other.id == id
+    end
+
+    alias_method :==, :eql?
+    delegate :hash, to: :id
+
+    private
+
+    def if_match_header
+      {'If-Match' => self['version']}
+    end
+  end
+end; end

data/lib/justrelate/core/configuration.rb

@@ -0,0 +1,65 @@
+module JustRelate; module Core
+  # +Configuration+ is yielded by {JustRelate.configure}.
+  # It lets you set the credentials for accessing the API.
+  # The +tenant+, +login+, and +api_key+ attributes must be provided.
+  # @api public
+  class Configuration
+    attr_reader :api_key
+    attr_reader :login
+    attr_reader :tenant
+
+    attr_accessor :endpoint
+
+    # @param value [String]
+    # @return [void]
+    # @api public
+    attr_writer :api_key
+
+    # @param value [String]
+    # @return [void]
+    # @api public
+    attr_writer :login
+
+    # @param value [String]
+    # @return [void]
+    # @api public
+    attr_writer :tenant
+
+    def endpoint_uri
+      if endpoint.present?
+        url = endpoint
+        url = "https://#{url}" unless url.match(/^http/)
+        url += '/' unless url.end_with?('/')
+        URI.parse(url)
+      else
+        URI.parse("https://#{tenant}.crm.infopark.net/api2/")
+      end
+    end
+
+    def logger
+      JustRelate::Core::LogSubscriber.logger
+    end
+
+    # The {http://www.ruby-doc.org/stdlib/libdoc/logger/rdoc/Logger.html logger} of the
+    # JustRelate SDK. It logs request URLs according to the +:info+ level.
+    # Additionally, it logs request and response payloads according to the +:debug+ level.
+    # Password fields are filtered out.
+    # In a Rails environment, the logger defaults to +Rails.logger+. Otherwise, no logger is set.
+    # @param value [Logger]
+    # @return [void]
+    # @api public
+    # @!parse attr_writer :logger
+
+    def logger=(logger)
+      JustRelate::Core::LogSubscriber.logger = logger
+    end
+
+    def validate!
+      raise "Missing required configuration key: api_key" if api_key.blank?
+      raise "Missing required configuration key: login" if login.blank?
+      if tenant.blank? && endpoint.blank?
+        raise "Missing required configuration key: tenant"
+      end
+    end
+  end
+end; end

data/lib/justrelate/core/connection_manager.rb

@@ -0,0 +1,98 @@
+module JustRelate; module Core
+  class ConnectionManager
+    SOCKET_ERRORS = [
+      EOFError,
+      Errno::ECONNABORTED,
+      Errno::ECONNREFUSED,
+      Errno::ECONNRESET,
+      Errno::EINVAL,
+      Errno::EPIPE,
+      Errno::ETIMEDOUT,
+      IOError,
+      SocketError,
+      Timeout::Error,
+    ].freeze
+
+    DEFAULT_TIMEOUT = 10.freeze
+
+    attr_reader :uri
+    attr_reader :ca_file
+    attr_reader :cert_store
+
+    def initialize(uri)
+      @uri = uri
+      @ca_file = File.expand_path('../../../../config/ca-bundle.crt', __FILE__)
+      @cert_store = OpenSSL::X509::Store.new.tap do |store|
+        store.set_default_paths
+        store.add_file(@ca_file)
+      end
+      @connection = nil
+    end
+
+    def request(request, timeout=DEFAULT_TIMEOUT)
+      request['User-Agent'] = user_agent
+      ensure_started(timeout)
+
+      begin
+        @connection.request(request)
+      rescue *SOCKET_ERRORS => e
+        ensure_finished
+        raise Errors::NetworkError.new(e.message, e)
+      end
+    end
+
+    private
+
+    def ensure_started(timeout)
+      if @connection && @connection.started?
+        configure_timeout(@connection, timeout)
+      else
+        conn = Net::HTTP.new(uri.host, uri.port)
+        if uri.scheme == 'https'
+          conn.use_ssl = true
+          conn.verify_mode = OpenSSL::SSL::VERIFY_PEER
+          conn.cert_store = @cert_store
+        end
+        configure_timeout(conn, timeout)
+        retry_twice_on_socket_error do |attempt|
+          ActiveSupport::Notifications.instrument("establish_connection.justrelate") do |msg|
+            msg[:attempt] = attempt
+            conn.start
+          end
+        end
+        @connection = conn
+      end
+    end
+
+    def ensure_finished
+      @connection.finish if @connection && @connection.started?
+      @connection = nil
+    end
+
+    def retry_twice_on_socket_error
+      attempt = 1
+      begin
+        yield attempt
+      rescue *SOCKET_ERRORS => e
+        raise Errors::NetworkError.new(e.message, e) if attempt > 2
+        attempt += 1
+        retry
+      end
+    end
+
+    def configure_timeout(connection, timeout)
+      connection.open_timeout = timeout
+      connection.read_timeout = timeout
+      connection.ssl_timeout = timeout
+    end
+
+    def user_agent
+      @user_agent ||= (
+        gem_info = Gem.loaded_specs["justrelate_sdk"]
+        if gem_info
+          "#{gem_info.name}-#{gem_info.version}"
+        end
+      )
+    end
+  end
+end; end