justrelate_sdk 1.0.0.rc1

data/lib/justrelate/core/item_enumerator.rb

@@ -0,0 +1,61 @@
+module JustRelate; module Core
+  # +ItemEnumerator+ provides methods for accessing items identified by their ID.
+  # It implements {#each} and includes the
+  # {http://ruby-doc.org/core/Enumerable.html Enumerable} mixin,
+  # which provides methods such as +#map+, +#select+ or +#take+.
+  # @api public
+  class ItemEnumerator
+    include Enumerable
+    include Core::Mixins::Inspectable
+    inspectable :length, :total
+
+    # Returns the IDs of the items to enumerate.
+    # @return [Array<String>]
+    # @api public
+    attr_reader :ids
+
+    # If the ItemEnumerator is the result of a search, it returns the total number of search hits.
+    # Otherwise, it returns {#length}.
+    # @return [Fixnum]
+    # @api public
+    attr_reader :total
+
+    def initialize(ids, total: nil)
+      @ids = ids
+      @total = total || ids.length
+    end
+
+    # Iterates over the {#ids} and fetches the corresponding items on demand.
+    # @overload each
+    #   Calls the block once for each item, passing this item as a parameter.
+    #   @yieldparam item [BasicResource]
+    #   @return [void]
+    # @overload each
+    #   If no block is given, an {http://ruby-doc.org/core/Enumerator.html enumerator}
+    #   is returned instead.
+    #   @return [Enumerator<BasicResource>]
+    # @raise [Errors::ResourceNotFound] if at least one of the IDs could not be found.
+    # @api public
+    def each(&block)
+      return enum_for(:each) unless block_given?
+
+      server_limit = 1_000
+      @ids.each_slice(server_limit) do |sliced_ids|
+        RestApi.instance.get('mget', {'ids' => sliced_ids}).map do |item|
+          block.call "JustRelate::#{item['base_type']}".constantize.new(item)
+        end
+      end
+    end
+
+    # Returns the number of items.
+    # Prefer this method over +Enumerable#count+
+    # because +#length+ doesn't fetch the items and therefore is faster than +Enumerable#count+.
+    # @return [Fixnum]
+    # @api public
+    def length
+      @ids.length
+    end
+
+    alias_method :size, :length
+  end
+end; end

data/lib/justrelate/core/log_subscriber.rb

@@ -0,0 +1,41 @@
+require 'action_dispatch'
+
+module JustRelate; module Core
+  class LogSubscriber < ActiveSupport::LogSubscriber
+    def logger
+      self.class.logger.presence or super
+    end
+
+    def request(event)
+      info { "#{event.payload[:method].to_s.upcase} #{event.payload[:resource_path]}" }
+      request_payload = event.payload[:request_payload]
+      if request_payload.present?
+        debug { "  request body: #{parameter_filter.filter(request_payload)}" }
+      end
+    end
+
+    def response(event)
+      r = event.payload[:response]
+      info {
+        "  #{r.code} #{r.message} #{r.body.to_s.length} (total: #{event.duration.round(1)}ms)"
+      }
+      debug {
+        response_payload = MultiJson.load(r.body)
+        "  response body: #{parameter_filter.filter(response_payload)}"
+      }
+    end
+
+    def establish_connection(event)
+      debug {
+        attempt = event.payload[:attempt]
+        "  Establishing connection on attempt #{attempt} (#{event.duration.round(1)}ms)"
+      }
+    end
+
+    private
+
+    def parameter_filter
+      @parameter_filter ||= ::ActionDispatch::Http::ParameterFilter.new(['password'])
+    end
+  end
+end; end

data/lib/justrelate/core/mixins/attribute_provider.rb

@@ -0,0 +1,135 @@
+module JustRelate; module Core; module Mixins
+  # +AttributeProvider+ provides multiple ways to access the attributes of an item.
+  # All attributes are available using {#[]}, {#attributes}
+  # or a method named like the attribute.
+  # @example
+  #   contact
+  #   # => JustRelate::Contact
+  #
+  #   contact.first_name
+  #   # => "John"
+  #
+  #   contact['first_name']
+  #   # => "John"
+  #
+  #   contact[:first_name]
+  #   # => "John"
+  #
+  #   contact.unknown_attribute
+  #   # => raises NoMethodError
+  #
+  #   contact['unknown_attribute']
+  #   # => nil
+  #
+  #   contact.attributes
+  #   # => {
+  #   #  ...
+  #   #  'first_name' => 'John',
+  #   #  ...
+  #   # }
+  # @api public
+  module AttributeProvider
+    def initialize(attributes = nil)
+      load_attributes(attributes || {})
+
+      super()
+    end
+
+    # Makes all attributes accessible as methods.
+    def method_missing(method_name, *args)
+      return self[method_name] if has_attribute?(method_name)
+      [
+        "#{method_name}_id",
+        "#{method_name.to_s.singularize}_ids",
+      ].each do |id_name|
+        return JustRelate.find(self[id_name]) if has_attribute?(id_name)
+      end
+
+      super
+    end
+
+    # Motivation see http://blog.marc-andre.ca/2010/11/15/methodmissing-politely/
+    def respond_to_missing?(method_name, *)
+      return true if has_attribute?(method_name)
+      return true if has_attribute?("#{method_name}_id")
+      return true if has_attribute?("#{method_name.to_s.singularize}_ids")
+
+      super
+    end
+
+    def methods(*args)
+      super | @extra_methods
+    end
+
+    # Returns the value associated with +attribute_name+.
+    # Returns +nil+ if not found.
+    # @example
+    #   contact['first_name']
+    #   # => "John"
+    #
+    #   contact[:first_name]
+    #   # => "John"
+    #
+    #   contact['nonexistent']
+    #   # => nil
+    # @param attribute_name [String, Symbol]
+    # @return [Object, nil]
+    # @api public
+    def [](attribute_name)
+      @attrs[attribute_name.to_s]
+    end
+
+    # Returns the hash of all attribute names and their values.
+    # @return [HashWithIndifferentAccess]
+    # @api public
+    def attributes
+      @attrs
+    end
+
+    # Returns the value before type cast.
+    # Returns +nil+ if attribute_name not found.
+    # @example
+    #   contact[:created_at]
+    #   # => 2012-05-07 17:15:00 +0200
+    #
+    #   contact.raw(:created_at)
+    #   # => "2012-05-07T15:15:00+00:00"
+    # @return [Object, nil]
+    # @api public
+    def raw(attribute_name)
+      @raw_attrs[attribute_name] || @attrs[attribute_name]
+    end
+
+    protected
+
+    def load_attributes(attributes)
+      @raw_attrs = HashWithIndifferentAccess.new
+      @attrs = attributes.each_with_object(HashWithIndifferentAccess.new) do |(key, value), hash|
+        if key.ends_with?('_at')
+          @raw_attrs[key] = value
+          value = begin
+            Time.parse(value.to_s).in_time_zone
+          rescue ArgumentError
+            nil
+          end
+        end
+        hash[key] = value
+      end
+      @extra_methods = []
+      @attrs.keys.each do |key|
+        key = key.to_s
+        @extra_methods << key.to_sym
+        @extra_methods << key.gsub(/_id$/, '').to_sym if key.ends_with?('_id')
+        @extra_methods << key.gsub(/_ids$/, '').pluralize.to_sym if key.ends_with?('_ids')
+      end
+      @attrs.freeze
+      self
+    end
+
+    private
+
+    def has_attribute?(attribute_name)
+      @attrs.has_key?(attribute_name.to_s)
+    end
+  end
+end; end; end

data/lib/justrelate/core/mixins/change_loggable.rb

@@ -0,0 +1,98 @@
+module JustRelate; module Core; module Mixins
+  # +ChangeLoggable+ provides access to the change log of a resource.
+  # A {ChangeLoggable::Change change log entry} contains the +before+ and +after+ values
+  # of all attributes that were changed by an update.
+  # It also includes the author (+changed_by+) and the timestamp (+changed_at+) of the change.
+  # @example
+  #   contact
+  #   # => JustRelate::Contact
+  #
+  #   changes = contact.changes
+  #   # => Array<ChangeLoggable::Change>
+  #
+  #   change = changes.first
+  #   # => ChangeLoggable::Change
+  #
+  #   change.changed_by
+  #   # => 'john_smith'
+  #
+  #   change.changed_at
+  #   # => Time
+  #
+  #   change.details.keys
+  #   # => ['email', 'locality']
+  #
+  #   detail = change.details[:email]
+  #   # => ChangeLoggable::Change::Detail
+  #
+  #   detail.before
+  #   # => old@example.com
+  #
+  #   detail.after
+  #   # => new@example.com
+  # @api public
+  module ChangeLoggable
+    # +Change+ represents a single change log entry contained in
+    # {ChangeLoggable#changes item.changes}.
+    # See {JustRelate::Core::Mixins::ChangeLoggable ChangeLoggable} for details.
+    # @api public
+    class Change
+      include Core::Mixins::AttributeProvider
+
+      def initialize(raw_change)
+        change = raw_change.dup
+        change['details'] = change['details'].each_with_object({}) do |(attr_name, detail), hash|
+          hash[attr_name] = Detail.new(detail)
+        end
+        super(change)
+      end
+
+      # @!attribute [r] changed_at
+      #   Returns the timestamp of the change to the item.
+      #   @return [Time]
+      #   @api public
+
+      # @!attribute [r] changed_by
+      #   Returns the login of the API user who made the change.
+      #   @return [String]
+      #   @api public
+
+      # @!attribute [r] details
+      #   Returns the details of the change
+      #   (i.e. +before+ and +after+ of every changed attribute)
+      #   @return [Array<Detail>]
+      #   @api public
+
+      # +Detail+ represents a single detail of a
+      # {JustRelate::Core::Mixins::ChangeLoggable::Change change},
+      # which can be accessed by means of {Change#details change.details}.
+      # See {JustRelate::Core::Mixins::ChangeLoggable ChangeLoggable} for details.
+      # @api public
+      class Detail
+        # @!attribute [r] before
+        #   Returns the value before the change.
+        #   @return [Object]
+        #   @api public
+
+        # @!attribute [r] after
+        #   Returns the value after the change.
+        #   @return [Object]
+        #   @api public
+
+        # flush yardoc!!!!
+        include Core::Mixins::AttributeProvider
+      end
+    end
+
+    # Returns the most recent changes made to this item.
+    # @param limit [Fixnum] the number of changes to return at most.
+    #   Maximum: +100+. Default: +10+.
+    # @return [Array<Change>]
+    # @api public
+    def changes(limit: 10)
+      RestApi.instance.get("#{path}/changes", {"limit" => limit})['results'].map do |change|
+        Change.new(change)
+      end
+    end
+  end
+end; end; end

data/lib/justrelate/core/mixins/findable.rb

@@ -0,0 +1,24 @@
+module JustRelate; module Core; module Mixins
+  # +Findable+ lets you fetch an item using {ClassMethods#find .find}.
+  # @example
+  #   JustRelate::Contact.find('e70a7123f499c5e0e9972ab4dbfb8fe3')
+  #   # => JustRelate::Contact
+  # @api public
+  module Findable
+    extend ActiveSupport::Concern
+
+    # @api public
+    module ClassMethods
+      # Returns the requested item.
+      # @param id [String] the ID of the item.
+      # @return [BasicResource]
+      # @raise [Errors::ResourceNotFound]
+      #   if the ID could not be found or the base type did not match.
+      # @api public
+      def find(id)
+        new({'id' => id}).reload
+      end
+    end
+    # @!parse extend ClassMethods
+  end
+end; end; end

data/lib/justrelate/core/mixins/inspectable.rb

@@ -0,0 +1,27 @@
+module JustRelate; module Core; module Mixins
+  module Inspectable
+    extend ActiveSupport::Concern
+
+    def inspect
+      field_values = self.class.inspectable_fields.map do |field|
+        value = self.send(field).inspect
+
+        "#{field}=#{value}"
+      end
+
+      "#<#{self.class.name} #{field_values.join(', ')}>"
+    end
+
+    included do
+      cattr_accessor :inspectable_fields
+
+      self.inspectable_fields = []
+    end
+
+    module ClassMethods
+      def inspectable(*fields)
+        self.inspectable_fields = *fields
+      end
+    end
+  end
+end; end; end

data/lib/justrelate/core/mixins/merge_and_deletable.rb

@@ -0,0 +1,17 @@
+module JustRelate; module Core; module Mixins
+  # +MergeAndDeletable+ provides the common {#merge_and_delete} method
+  # for {Account accounts} and {Contact contacts}.
+  # @api public
+  module MergeAndDeletable
+    # Assigns the items associated with this item to the account or contact
+    # whose ID is +merge_into_id+. Afterwards, the current item is deleted.
+    # @param merge_into_id [String]
+    #   the ID of the account or contact to which the associated items are assigned.
+    # @return [self] the deleted item.
+    # @api public
+    def merge_and_delete(merge_into_id)
+      load_attributes(
+          RestApi.instance.post("#{path}/merge_and_delete", {"merge_into_id" => merge_into_id}))
+    end
+  end
+end; end; end

data/lib/justrelate/core/mixins/modifiable.rb

@@ -0,0 +1,102 @@
+require "active_support/concern"
+
+module JustRelate; module Core; module Mixins
+  # +Modifiable+ is a collection of methods that are used to {ClassMethods#create .create},
+  # {#update}, {#delete}, and {#undelete} a JustRelate item.
+  # @api public
+  module Modifiable
+    extend ActiveSupport::Concern
+
+    # @api public
+    module ClassMethods
+      # Creates a new item using the given +attributes+.
+      # @example
+      #   JustRelate::Contact.create({
+      #     language: 'en',
+      #     last_name: 'Smith',
+      #   })
+      #   # => JustRelate::Contact
+      # @param attributes [Hash{String, Symbol => String}] the attributes of the new item.
+      # @return [BasicResource] the created item.
+      # @raise [Errors::InvalidKeys] if +attributes+ contains unknown attribute names.
+      # @raise [Errors::InvalidValues] if +attributes+ contains incorrect values.
+      # @api public
+      def create(attributes = {})
+        new(RestApi.instance.post(path, attributes))
+      end
+    end
+    # @!parse extend ClassMethods
+
+    # Updates the attributes of this item.
+    # @example
+    #   contact.last_name
+    #   # => 'Smith'
+    #
+    #   contact.locality
+    #   # => 'New York'
+    #
+    #   contact.update({locality: 'Boston'})
+    #   # => JustRelate::Contact
+    #
+    #   contact.last_name
+    #   # => 'Smith'
+    #
+    #   contact.locality
+    #   # => 'Boston'
+    # @param attributes [Hash{String, Symbol => String}] the new attributes.
+    # @return [self] the updated item.
+    # @raise [Errors::InvalidKeys] if +attributes+ contains unknown attribute names.
+    # @raise [Errors::InvalidValues] if +attributes+ contains incorrect values.
+    # @raise [Errors::ResourceConflict] if the item has been changed concurrently.
+    #   {Core::BasicResource#reload Reload} it, review the changes and retry.
+    # @api public
+    def update(attributes = {})
+      load_attributes(RestApi.instance.put(path, attributes, if_match_header))
+    end
+
+    # Soft-deletes this item (i.e. marks it as deleted).
+    #
+    # The deleted item can be {#undelete undeleted}.
+    # @example
+    #   contact.deleted?
+    #   # => false
+    #
+    #   contact.delete
+    #   # => JustRelate::Contact
+    #
+    #   contact.deleted?
+    #   # => true
+    # @return [self] the deleted item.
+    # @raise [Errors::ResourceConflict] if the item has been changed concurrently.
+    #   {Core::BasicResource#reload Reload} it, review the changes and retry.
+    # @api public
+    def delete
+      load_attributes(RestApi.instance.delete(path, nil, if_match_header))
+    end
+
+    # Undeletes this deleted item.
+    # @example
+    #   contact.deleted?
+    #   # => true
+    #
+    #   contact.undelete
+    #   # => JustRelate::Contact
+    #
+    #   contact.deleted?
+    #   # => false
+    # @return [self] the undeleted item.
+    # @api public
+    def undelete
+      load_attributes(RestApi.instance.put("#{path}/undelete", {}))
+    end
+
+    # Returns +true+ if the item was deleted (i.e. +item.deleted_at+ is not empty).
+    # @return [Boolean]
+    # @api public
+    def deleted?
+      self['deleted_at'].present?
+    end
+
+    alias_method :destroy, :delete
+  end
+end; end; end

data/lib/justrelate/core/mixins/searchable.rb

@@ -0,0 +1,88 @@
+module JustRelate; module Core; module Mixins
+  # +Searchable+ provides several methods related to searching.
+  # @api public
+  module Searchable
+    extend ActiveSupport::Concern
+
+    # @api public
+    module ClassMethods
+      # Returns the item of this base type that was created first.
+      # @return [BasicResource]
+      # @api public
+      def first
+        search_configurator.
+            sort_by('created_at').
+            limit(1).
+            perform_search.
+            first
+      end
+
+      # Returns an {JustRelate::Core::ItemEnumerator enumerator} for iterating over all items
+      # of this base type. The items are sorted by +created_at+.
+      # @param include_deleted [Boolean] whether to include deleted items. Default: +false+.
+      # @return [ItemEnumerator]
+      # @api public
+      def all(include_deleted: false)
+        search_configurator.
+            sort_by('created_at').
+            unlimited.
+            include_deleted(include_deleted).
+            perform_search
+      end
+
+      # Returns a new {JustRelate::Core::SearchConfigurator SearchConfigurator} set to the given
+      # filter (+field+, +condition+, +value+). Additionally, it is limited
+      # to this base type and can be further refined using chainable methods.
+      # This method is equivalent to +search_configurator.and(field, condition, value)+.
+      # See {SearchConfigurator#and} for parameters and examples.
+      # @return [SearchConfigurator]
+      # @api public
+      def where(field, condition, value = nil)
+        search_configurator.and(field, condition, value)
+      end
+
+      # Returns a new {JustRelate::Core::SearchConfigurator SearchConfigurator} set to the given
+      # negated filter (+field+, +condition+, +value+). Additionally, it is limited
+      # to this base type and can be further refined using chainable methods.
+      # This method is equivalent to +search_configurator.and_not(field, condition, value)+.
+      # See {SearchConfigurator#and_not} for parameters and examples.
+      # @return [SearchConfigurator]
+      # @api public
+      def where_not(field, condition, value = nil)
+        search_configurator.and_not(field, condition, value)
+      end
+
+      # Returns a new {JustRelate::Core::SearchConfigurator SearchConfigurator} set to the given
+      # +query+. Additionally, it is limited
+      # to this base type and can be further refined using chainable methods.
+      # This method is equivalent to +search_configurator.query(query)+.
+      # See {SearchConfigurator#query} for examples.
+      # @return [SearchConfigurator]
+      # @api public
+      def query(query)
+        search_configurator.query(query)
+      end
+
+      # Returns a new {JustRelate::Core::SearchConfigurator SearchConfigurator} limited
+      # to this base type. It can be further refined using chainable methods.
+      # @return [SearchConfigurator]
+      # @api public
+      def search_configurator
+        SearchConfigurator.new({
+          filters: filters_for_base_type,
+        })
+      end
+
+      private
+
+      def filters_for_base_type
+        [{
+          field: 'base_type',
+          condition: 'equals',
+          value: base_type,
+        }]
+      end
+    end
+    # @!parse extend ClassMethods
+  end
+end; end; end

data/lib/justrelate/core/mixins.rb

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