justrelate_sdk 1.0.0.rc1

data/lib/justrelate/core/rest_api.rb

@@ -0,0 +1,148 @@
+require 'multi_json'
+require 'addressable/uri'
+
+module JustRelate; module Core
+  class RestApi
+    METHOD_TO_NET_HTTP_CLASS = {
+      :get => Net::HTTP::Get,
+      :put => Net::HTTP::Put,
+      :post => Net::HTTP::Post,
+      :delete => Net::HTTP::Delete,
+    }.freeze
+
+    def self.instance=(instance)
+      @instance = instance
+    end
+
+    def self.instance
+      if @instance
+        @instance
+      else
+        raise "Please run JustRelate.configure first"
+      end
+    end
+
+    def initialize(uri, login, api_key)
+      @uri = uri
+      @login = login
+      @api_key = api_key
+      @connection_manager = ConnectionManager.new(uri)
+    end
+
+    def get(resource_path, payload = nil)
+      response_for_request(:get, resource_path, payload, {})
+    end
+
+    def put(resource_path, payload, headers = {})
+      response_for_request(:put, resource_path, payload, headers)
+    end
+
+    def post(resource_path, payload)
+      response_for_request(:post, resource_path, payload, {})
+    end
+
+    def delete(resource_path, payload = nil, headers = {})
+      response_for_request(:delete, resource_path, payload, headers)
+    end
+
+    def resolve_uri(url)
+      input_uri = Addressable::URI.parse(url)
+      input_uri.path = Addressable::URI.escape(input_uri.path)
+      @uri + input_uri.to_s
+    end
+
+    private
+
+    def response_for_request(method, resource_path, payload, headers)
+      path = resolve_uri(resource_path).path
+      request = method_to_net_http_class(method).new(path)
+      set_headers(request, headers)
+      request.body = MultiJson.encode(payload) if payload.present?
+
+      response = nil
+      retried = false
+      begin
+        ActiveSupport::Notifications.instrument("request.justrelate") do |msg|
+          msg[:method] = method
+          msg[:resource_path] = "#{resource_path}"
+          msg[:request_payload] = payload
+        end
+        response = ActiveSupport::Notifications.instrument("response.justrelate") do |msg|
+          # lower timeout back to DEFAULT_TIMEOUT once the backend has been fixed
+          msg[:response] = @connection_manager.request(request, 25)
+        end
+      rescue Errors::NetworkError => e
+        if method == :post || retried
+          raise e
+        else
+          retried = true
+          retry
+        end
+      end
+
+      handle_response(response)
+    end
+
+    def parse_payload(payload)
+      MultiJson.load(payload)
+    rescue MultiJson::DecodeError
+      raise Errors::ServerError.new("Server returned invalid json: #{payload}")
+    end
+
+    def handle_response(response)
+      body = parse_payload(response.body)
+      if response.code.start_with?('2')
+        body
+      else
+        message = body['message']
+
+        case body['id']
+        when 'unauthorized'
+          raise Errors::UnauthorizedAccess.new(message)
+        when 'authentication_failed'
+          raise Errors::AuthenticationFailed.new(message)
+        when 'forbidden'
+          raise Errors::ForbiddenAccess.new(message)
+        when 'not_found'
+          raise Errors::ResourceNotFound.new(message, body['missing_ids'])
+        when 'item_state_precondition_failed'
+          raise Errors::ItemStatePreconditionFailed.new(message, body['unmet_preconditions'])
+        when 'conflict'
+          raise Errors::ResourceConflict.new(message)
+        when 'invalid_keys'
+          raise Errors::InvalidKeys.new(message, body['validation_errors'])
+        when 'invalid_values'
+          raise Errors::InvalidValues.new(message, body['validation_errors'])
+        # leaving out 'params_parse_error', since the client should always send valid json.
+        when 'rate_limit'
+          raise Errors::RateLimitExceeded.new(message)
+        when 'internal_server_error'
+          raise Errors::ServerError.new(message)
+        when 'too_many_params'
+          raise Errors::TooManyParams.new(message)
+        else
+          if response.code == '404'
+            raise Errors::ResourceNotFound.new('Not Found.')
+          elsif response.code.start_with?('4')
+            raise Errors::ClientError.new("HTTP Code #{response.code}: #{body}")
+          else
+            raise Errors::ServerError.new("HTTP Code #{response.code}: #{body}")
+          end
+        end
+      end
+    end
+
+    def set_headers(request, additional_headers)
+      request.basic_auth(@login, @api_key)
+      request['Content-Type'] = 'application/json'
+      request['Accept'] = 'application/json'
+      additional_headers.each do |key, value|
+        request[key] = value
+      end
+    end
+
+    def method_to_net_http_class(method)
+      METHOD_TO_NET_HTTP_CLASS.fetch(method)
+    end
+  end
+end; end

data/lib/justrelate/core/search_configurator.rb

@@ -0,0 +1,207 @@
+module JustRelate; module Core
+  # +SearchConfigurator+ provides methods to incrementally configure a search request
+  # using chainable methods and to {#perform_search perform} this search.
+  # @example
+  #   search_config = JustRelate::Contact.
+  #     where('last_name', 'equals', 'Johnson').
+  #     and('locality', 'equals', 'New York').
+  #     and_not('language', 'equals', 'en').
+  #     sort_by('first_name').
+  #     sort_order('desc').
+  #     offset(1).
+  #     limit(3)
+  #   # => JustRelate::Core::SearchConfigurator
+  #
+  #   results = search_config.perform_search
+  #   # => JustRelate::Core::ItemEnumerator
+  #
+  #   results.length # => 3
+  #   results.total # => 17
+  #   results.map(&:first_name) # => ['Tim', 'Joe', 'Ann']
+  #
+  # @example Unlimited search results
+  #   search_config = JustRelate::Contact.
+  #     where('last_name', 'equals', 'Johnson').
+  #     unlimited
+  #   # => JustRelate::Core::SearchConfigurator
+  #
+  #   results = search_config.perform_search
+  #   # => JustRelate::Core::ItemEnumerator
+  #
+  #   results.length # => 85
+  #   results.total # => 85
+  #   results.map(&:first_name) # => an array of 85 first names
+  # @api public
+  class SearchConfigurator
+    include Enumerable
+
+    def initialize(settings = {})
+      @settings = {
+        filters: [],
+      }.merge(settings)
+    end
+
+    # Executes the search request based on this configuration.
+    # @return [ItemEnumerator] the search result.
+    # @api public
+    def perform_search
+      @perform_search ||= JustRelate.search(
+        filters: @settings[:filters],
+        query: @settings[:query],
+        limit: @settings[:limit],
+        offset: @settings[:offset],
+        sort_by: @settings[:sort_by],
+        sort_order: @settings[:sort_order],
+        include_deleted: @settings[:include_deleted]
+      )
+    end
+
+    # @!group Chainable methods
+
+    # Returns a new {SearchConfigurator} constructed by combining
+    # this configuration and the new filter.
+    #
+    # Supported conditions:
+    # * +contains_word_prefixes+ - +field+ contains words starting with +value+.
+    # * +contains_words+ - +field+ contains the words given by +value+.
+    # * +equals+ - +field+ exactly corresponds to +value+ (case insensitive).
+    # * +is_blank+ - +field+ is blank (omit +value+).
+    # * +is_earlier_than+ - date time +field+ is earlier than +value+.
+    # * +is_later_than+ - date time +field+ is later than +value+.
+    # * +is_true+ - +field+ is true (omit +value+).
+    # @param field [Symbol, String] the attribute name.
+    # @param condition [Symbol, String] the condition, e.g. +:equals+.
+    # @param value [Symbol, String, Array<Symbol, String>, nil] the value.
+    # @return [SearchConfigurator]
+    # @api public
+    def add_filter(field, condition, value = nil)
+      new_filter = Array(@settings[:filters]) + [{field: field, condition: condition, value: value}]
+      SearchConfigurator.new(@settings.merge(filters: new_filter))
+    end
+    alias and add_filter
+
+    # Returns a new {SearchConfigurator} constructed by combining
+    # this configuration and the new negated filter.
+    #
+    # All filters (and their conditions) passed to {#add_filter} can be negated.
+    # @param field [Symbol, String] the attribute name.
+    # @param condition [Symbol, String] the condition, e.g. +:equals+.
+    # @param value [Symbol, String, Array<Symbol, String>, nil] the value.
+    # @return [SearchConfigurator]
+    # @api public
+    def add_negated_filter(field, condition, value = nil)
+      negated_condition = "not_#{condition}"
+      add_filter(field, negated_condition, value)
+    end
+    alias and_not add_negated_filter
+
+    # Returns a new {SearchConfigurator} constructed by combining this configuration
+    # with the given query.
+    # @param new_query [String] the new query.
+    # @return [SearchConfigurator]
+    # @api public
+    def query(new_query)
+      SearchConfigurator.new(@settings.merge(query: new_query))
+    end
+
+    # Returns a new {SearchConfigurator} constructed by combining this configuration
+    # with the given limit.
+    # @param new_limit [Fixnum] the new limit.
+    # @return [SearchConfigurator]
+    # @api public
+    def limit(new_limit)
+      SearchConfigurator.new(@settings.merge(limit: new_limit))
+    end
+
+    # Returns a new {SearchConfigurator} constructed by combining this configuration
+    # without limiting the number of search results.
+    # @return [SearchConfigurator]
+    # @api public
+    def unlimited
+      limit(:none)
+    end
+
+    # Returns a new {SearchConfigurator} constructed by combining this configuration
+    # with the given offset.
+    # @param new_offset [Fixnum] the new offset.
+    # @return [SearchConfigurator]
+    # @api public
+    def offset(new_offset)
+      SearchConfigurator.new(@settings.merge(offset: new_offset))
+    end
+
+    # Returns a new {SearchConfigurator} constructed by combining this configuration
+    # with the given sort criterion.
+    # @param new_sort_by [String]
+    #   See {JustRelate.search} for the list of supported +sort_by+ values.
+    # @return [SearchConfigurator]
+    # @api public
+    def sort_by(new_sort_by)
+      SearchConfigurator.new(@settings.merge(sort_by: new_sort_by))
+    end
+
+    # Returns a new {SearchConfigurator} constructed by combining this configuration
+    # with the given sort order.
+    # @param new_sort_order [String]
+    #   See {JustRelate.search} for the list of supported +sort_order+ values.
+    # @return [SearchConfigurator]
+    # @api public
+    def sort_order(new_sort_order)
+      SearchConfigurator.new(@settings.merge(sort_order: new_sort_order))
+    end
+
+    # Returns a new {SearchConfigurator} constructed by combining this configuration
+    # with the ascending sort order.
+    # @return [SearchConfigurator]
+    # @api public
+    def asc
+      sort_order('asc')
+    end
+
+    # Returns a new {SearchConfigurator} constructed by combining this configuration
+    # with the descending sort order.
+    # @return [SearchConfigurator]
+    # @api public
+    def desc
+      sort_order('desc')
+    end
+
+    # Returns a new {SearchConfigurator} constructed by combining this configuration
+    # with the given +include_deleted+ flag.
+    # @param new_include_deleted [Boolean] whether to include deleted items in the results.
+    # @return [SearchConfigurator]
+    # @api public
+    def include_deleted(new_include_deleted = true)
+      SearchConfigurator.new(@settings.merge(include_deleted: new_include_deleted))
+    end
+
+    # Returns a new {SearchConfigurator} constructed by combining this configuration
+    # and excluding deleted items.
+    # @return [SearchConfigurator]
+    # @api public
+    def exclude_deleted
+      include_deleted(false)
+    end
+
+    # @!endgroup
+
+    # Iterates over the search results.
+    # Implicitly triggers {#perform_search} and caches its result.
+    # See {ItemEnumerator#each} for details.
+    # @api public
+    def each(&block)
+      return enum_for(:each) unless block_given?
+
+      perform_search.each(&block)
+    end
+
+    # Returns the total number of items that match this search configuration.
+    # It can be greater than +limit+.
+    # Implicitly triggers {#perform_search} and caches its result.
+    # @return [Fixnum] the total.
+    # @api public
+    def total
+      perform_search.total
+    end
+  end
+end; end

data/lib/justrelate/core.rb

@@ -0,0 +1,6 @@
+module JustRelate
+  # @api public
+  module Core
+    JustRelate.autoload_module(self, File.expand_path(__FILE__))
+  end
+end

data/lib/justrelate/errors.rb

@@ -0,0 +1,169 @@
+module JustRelate
+  # @api public
+  module Errors
+    # +BaseError+ is the superclass of all JustRelate errors.
+    # @api public
+    class BaseError < StandardError
+    end
+
+    # +ServerError+ is raised if an internal error occurs in the API server.
+    # @api public
+    class ServerError < BaseError
+    end
+
+    # +ClientError+ is the superclass of all errors that are a result of client-supplied input.
+    # @api public
+    class ClientError < BaseError
+    end
+
+    # +UnauthorizedAccess+ is raised if the API user credentials are invalid.
+    # Set the correct API user credentials using {JustRelate.configure}.
+    # @api public
+    class UnauthorizedAccess < ClientError
+    end
+
+    # +AuthenticationFailed+ is raised if the credentials used with
+    # {JustRelate::Contact.authenticate!} are invalid.
+    # @api public
+    class AuthenticationFailed < ClientError
+    end
+
+    # +ForbiddenAccess+ is raised if the API user is not permitted to access the resource.
+    # @api public
+    class ForbiddenAccess < ClientError
+    end
+
+    # +TooManyParams+ is raised if more than 1000 keys are passed as parameters to
+    # {Core::Mixins::Modifiable::ClassMethods#create Modifiable.create} or
+    # {Core::Mixins::Modifiable#update Modifiable#update}.
+    # @api public
+    class TooManyParams < ClientError
+    end
+
+    # +ResourceNotFound+ is raised if the requested IDs could not be found.
+    # @api public
+    class ResourceNotFound < ClientError
+      # Returns the IDs that could not be found.
+      # @return [Array<String>]
+      # @example
+      #   ["9762b2b4382f6bf34adbdeb21ce588aa"]
+      # @api public
+      attr_reader :missing_ids
+
+      def initialize(message = nil, missing_ids = [])
+        super("#{message} Missing IDs: #{missing_ids.to_sentence}")
+
+        @missing_ids = missing_ids
+      end
+    end
+
+    # +ItemStatePreconditionFailed+ is raised if one or more preconditions
+    # for the attempted action were not satisfied. For example, a deleted item cannot be updated.
+    # It must be undeleted first.
+    # @api public
+    class ItemStatePreconditionFailed < ClientError
+      # Returns the unmet preconditions.
+      # The items in the list are hashes consisting of a +code+ (the name of the precondition),
+      # and an English translation (+message+).
+      # @return [Array<Hash{String => String}>]
+      # @example
+      #   [
+      #     {
+      #       "code" => "is_internal_mailing",
+      #       "message" => "The mailing is not an internal mailing.",
+      #     },
+      #   ]
+      # @api public
+      attr_reader :unmet_preconditions
+
+      def initialize(message = nil, unmet_preconditions)
+        precondition_messages = unmet_preconditions.map{ |p| p['message'] }
+        new_message = ([message] + precondition_messages).join(' ')
+        super(new_message)
+
+        @unmet_preconditions = unmet_preconditions
+      end
+    end
+
+    # +ResourceConflict+ is raised if the item has been changed concurrently.
+    # {Core::BasicResource#reload Reload} the item, review the changes and retry.
+    # @api public
+    class ResourceConflict < ClientError
+    end
+
+    # +InvalidKeys+ is raised if a create or update request contains unknown attributes.
+    # @api public
+    class InvalidKeys < ClientError
+      # Returns the list of validation errors.
+      # The items in the list are hashes consisting of a +code+ (always +unknown+),
+      # the invalid +attribute+ name and an English translation (+message+).
+      # @return [Array<Hash{String => String}>]
+      # @example
+      #   [
+      #     {
+      #       "attribute" => "foo",
+      #       "code" => "unknown",
+      #       "message" => "foo is unknown",
+      #     },
+      #   ]
+      # @api public
+      attr_reader :validation_errors
+
+      def initialize(message = nil, validation_errors = {})
+        super("#{message} #{validation_errors.map{ |h| h['message'] }.to_sentence}.")
+
+        @validation_errors = validation_errors
+      end
+    end
+
+    # +InvalidValues+ is raised if the keys of a create or update request are recognized
+    # but include incorrect values.
+    # @api public
+    class InvalidValues < ClientError
+      # Returns the list of validation errors.
+      # The items in the list are hashes consisting of a +code+ (the name of the validation error,
+      # i.e. one of the rails validation error codes),
+      # an +attribute+ name and an English translation (+message+).
+      # You may use +code+ to translate the message into other languages.
+      # @example
+      #   [
+      #     {
+      #       "code" => "blank",
+      #       "attribute" => "name",
+      #       "message" => "name is blank",
+      #     },
+      #   ]
+      # @return [Array<Hash{String => String}>]
+      # @api public
+      attr_reader :validation_errors
+
+      def initialize(message = nil, validation_errors = {})
+        super("#{message} #{validation_errors.map{ |h| h['message'] }.to_sentence}.")
+
+        @validation_errors = validation_errors
+      end
+    end
+
+    # +RateLimitExceeded+ is raised if too many requests were issued within a given time frame.
+    # @api public
+    class RateLimitExceeded < ClientError
+    end
+
+    # +NetworkError+ is raised if a non-recoverable network-related error occurred
+    # (e.g. connection timeout).
+    # @api public
+    class NetworkError < BaseError
+      # Returns the underlying network error.
+      # E.g. {http://www.ruby-doc.org/stdlib/libdoc/timeout/rdoc/Timeout/Error.html Timeout::Error}
+      # @return [Exception]
+      # @api public
+      attr_reader :cause
+
+      def initialize(message = nil, cause = nil)
+        super(message)
+
+        @cause = cause
+      end
+    end
+  end
+end

data/lib/justrelate/event.rb

@@ -0,0 +1,17 @@
+module JustRelate
+  # A JustRelate event contains all data associated with an event such
+  # as a conference or a trade show. An event has participants ({EventContact}).
+  # @api public
+  class Event < 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
+  end
+end

data/lib/justrelate/event_contact.rb

@@ -0,0 +1,16 @@
+module JustRelate
+  # A JustRelate event contact is a participant or a potential participant of an {Event}.
+  # @api public
+  class EventContact < Core::BasicResource
+    include Core::Mixins::Findable
+    include Core::Mixins::Modifiable
+    include Core::Mixins::ChangeLoggable
+    include Core::Mixins::Searchable
+    include Core::Mixins::Inspectable
+    inspectable :id
+
+    # @!parse extend Core::Mixins::Findable::ClassMethods
+    # @!parse extend Core::Mixins::Modifiable::ClassMethods
+    # @!parse extend Core::Mixins::Searchable::ClassMethods
+  end
+end

data/lib/justrelate/mailing.rb

@@ -0,0 +1,111 @@
+module JustRelate
+  # The purpose of a JustRelate mailing is to send an e-mail, e.g. a newsletter,
+  # to several recipients.
+  # The e-mails will be sent to the members of the contact collection associated with the mailing
+  # (+mailing.collection_id+).
+  #
+  # JustRelate uses the {http://liquidmarkup.org/ Liquid template engine} for evaluating
+  # mailing content.
+  # @api public
+  class Mailing < 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
+
+    # Renders a preview of the e-mail for the given contact.
+    # @example
+    #   mailing.html_body
+    #   # => "<h1>Welcome {{contact.first_name}} {{contact.last_name}}</h1>"
+    #
+    #   contact.email
+    #   # => "john.doe@example.com"
+    #
+    #   mailing.render_preview(contact)
+    #   # => {
+    #   #  "email_from" => "Marketing <marketing@example.org>",
+    #   #  "email_reply_to" => "marketing-replyto@example.com",
+    #   #  "email_subject" => "Invitation to exhibition",
+    #   #  "email_to" => "john.doe@example.com",
+    #   #  "text_body" => "Welcome John Doe",
+    #   #  "html_body" => "<h1>Welcome John Doe</h1>"
+    #   # }
+    # @param render_for_contact_or_id [String, Contact]
+    #   the contact for which the e-mail preview is rendered.
+    # @return [Hash{String => String}] the values of the mailing fields evaluated
+    #   in the context of the contact.
+    # @api public
+    def render_preview(render_for_contact_or_id)
+      Core::RestApi.instance.post("#{path}/render_preview", {
+        'render_for_contact_id' => extract_id(render_for_contact_or_id)
+      })
+    end
+
+    # Sends a proof e-mail (personalized for a contact) to the current user (the API user).
+    # @example
+    #   mailing.send_me_a_proof_email(contact)
+    #   # => {
+    #   #   "message" => "e-mail sent to api_user@example.com"
+    #   # }
+    # @param render_for_contact_or_id [String, Contact]
+    #   the contact for which the proof e-mail is rendered.
+    # @return [Hash{String => String}] a status report.
+    # @api public
+    def send_me_a_proof_email(render_for_contact_or_id)
+      Core::RestApi.instance.post("#{path}/send_me_a_proof_email", {
+        'render_for_contact_id' => extract_id(render_for_contact_or_id)
+      })
+    end
+
+    # Sends this mailing to a single contact.
+    #
+    # Use case: If someone registers for a newsletter, you can send them the most recent issue
+    # that has already been released.
+    # @example
+    #   contact.email
+    #   # => "john.doe@example.org"
+    #
+    #   mailing.released_at
+    #   # => 2014-12-01 12:48:00 +0100
+    #
+    #   mailing.send_single_email(contact)
+    #   # => {
+    #   #   "message" => "e-mail sent to john.doe@example.org"
+    #   # }
+    # @param recipient_contact_or_id [String, Contact]
+    #   the contact to send a single e-mail to.
+    # @return [Hash{String => String}] a status report.
+    # @api public
+    def send_single_email(recipient_contact_or_id)
+      Core::RestApi.instance.post("#{path}/send_single_email", {
+        'recipient_contact_id' => extract_id(recipient_contact_or_id)
+      })
+    end
+
+    # Releases this mailing.
+    #
+    # Sends the mailing to all recipients, marks the mailing as
+    # released (+released_at+, +released_by+), and also sets +planned_release_at+ to now.
+    # @return [self] the updated mailing.
+    # @api public
+    def release
+      load_attributes(Core::RestApi.instance.post("#{path}/release", {}))
+    end
+
+    private
+
+    def extract_id(contact_or_id)
+      if contact_or_id.respond_to?(:id)
+        contact_or_id.id
+      else
+        contact_or_id
+      end
+    end
+  end
+end