discourse_zendesk_api 1.0.0

data/lib/zendesk_api/association.rb

@@ -0,0 +1,195 @@
+require 'zendesk_api/helpers'
+
+module ZendeskAPI
+  # Represents an association between two resources
+  # @private
+  class Association
+    class << self
+      def namespaces
+        [ZendeskAPI] + ZendeskAPI::DataNamespace.descendants
+      end
+
+      def class_from_namespace(klass_as_string)
+        namespaces.each do |ns|
+          if module_defines_class?(ns, klass_as_string)
+            return ns.const_get(klass_as_string)
+          end
+        end
+
+        nil
+      end
+
+      # 1.9+ changed default to search ancestors, added flag to disable behavior.
+      def module_defines_class?(mod, klass_as_string)
+        if RUBY_VERSION < '1.9'
+          mod.const_defined?(klass_as_string)
+        else
+          mod.const_defined?(klass_as_string, false)
+        end
+      end
+    end
+
+    # @return [Hash] Options passed into the association
+    attr_reader :options
+
+    # Options to pass in
+    # * class - Required
+    # * parent - Parent instance
+    # * path - Optional path instead of resource name
+    def initialize(options = {})
+      @options = SilentMash.new(options)
+    end
+
+    # Generate a path to the resource.
+    # id and <parent>_id attributes will be deleted from passed in options hash if they are used in the built path.
+    # Arguments that can be passed in:
+    # An instance, any resource instance
+    # Hash Options:
+    # * with_parent - Include the parent path (false by default)
+    # * with_id - Include the instance id, if possible (true)
+    def generate_path(*args)
+      options = SilentMash.new(:with_id => true)
+      if args.last.is_a?(Hash)
+        original_options = args.pop
+        options.merge!(original_options)
+      end
+
+      instance = args.first
+
+      namespace = @options[:class].to_s.split("::")
+      namespace[-1] = @options[:class].resource_path
+
+      # Remove components without path information
+      ignorable_namespace_strings.each { |ns| namespace.delete(ns) }
+      has_parent = namespace.size > 1 || (options[:with_parent] && @options.parent)
+
+      if has_parent
+        parent_class = @options.parent ? @options.parent.class : Association.class_from_namespace(ZendeskAPI::Helpers.modulize_string(namespace[0]))
+        parent_namespace = build_parent_namespace(parent_class, instance, options, original_options)
+        namespace[1..1] = parent_namespace if parent_namespace
+        namespace[0] = parent_class.resource_path
+      else
+        namespace[0] = @options.path || @options[:class].resource_path
+      end
+
+      if id = extract_id(instance, options, original_options)
+        namespace << id
+      end
+
+      namespace.join("/")
+    end
+
+    # Tries to place side loads onto given resources.
+    def side_load(resources, side_loads)
+      key = "#{options.name}_id"
+      plural_key = "#{Inflection.singular options.name.to_s}_ids"
+
+      resources.each do |resource|
+        if resource.key?(plural_key) # Grab associations from child_ids field on resource
+          side_load_from_child_ids(resource, side_loads, plural_key)
+        elsif resource.key?(key) || options.singular
+          side_load_from_child_or_parent_id(resource, side_loads, key)
+        else # Grab associations from parent_id field from multiple child resources
+          side_load_from_parent_id(resource, side_loads, key)
+        end
+      end
+    end
+
+    private
+
+    # @return [Array<String>] ['ZendeskAPI', 'Voice', etc.. ]
+    def ignorable_namespace_strings
+      ZendeskAPI::DataNamespace.descendants.map { |klass| klass.to_s.split('::') }.flatten.uniq
+    end
+
+    def _side_load(resource, side_loads)
+      side_loads.map! do |side_load|
+        resource.send(:wrap_resource, side_load, options)
+      end
+
+      ZendeskAPI::Collection.new(resource.client, options[:class]).tap do |collection|
+        collection.replace(side_loads)
+      end
+    end
+
+    def side_load_from_parent_id(resource, side_loads, key)
+      key = "#{resource.class.singular_resource_name}_id"
+
+      resource.send("#{options.name}=", _side_load(resource, side_loads.select {|side_load|
+        side_load[key] == resource.id
+      }))
+    end
+
+    def side_load_from_child_ids(resource, side_loads, plural_key)
+      ids = resource.send(plural_key)
+
+      resource.send("#{options.name}=", _side_load(resource, side_loads.select {|side_load|
+        ids.include?(side_load[options.include_key])
+      }))
+    end
+
+    def side_load_from_child_or_parent_id(resource, side_loads, key)
+      # Either grab association from child_id field on resource or parent_id on child resource
+      if resource.key?(key)
+        id = resource.send(key)
+        include_key = options.include_key
+      else
+        id = resource.id
+        include_key = "#{resource.class.singular_resource_name}_id"
+      end
+
+      return unless id
+
+      side_load = side_loads.detect do |side_load|
+        id == side_load[include_key]
+      end
+
+      resource.send("#{options.name}=", side_load) if side_load
+    end
+
+    def build_parent_namespace(parent_class, instance, options, original_options)
+      path = @options.path
+
+      association_on_parent = parent_class.associations.detect { |a| a[:name] == @options[:name] }
+      association_on_parent ||= parent_class.associations.detect do |a|
+        !a[:inline] && a[:class] == @options[:class]
+      end
+
+      if association_on_parent
+        path ||= association_on_parent[:path]
+        path ||= association_on_parent[:name].to_s
+      end
+
+      path ||= @options[:class].resource_path
+
+      [
+        extract_parent_id(parent_class, instance, options, original_options),
+        path
+      ]
+    end
+
+    def extract_parent_id(parent_class, instance, options, original_options)
+      parent_id_column = "#{parent_class.singular_resource_name}_id"
+
+      if @options.parent
+        @options.parent.id
+      elsif instance
+        instance.send(parent_id_column)
+      elsif options[parent_id_column]
+        original_options.delete(parent_id_column) || original_options.delete(parent_id_column.to_sym)
+      else
+        raise ArgumentError.new("#{@options[:class].resource_name} requires #{parent_id_column} or parent")
+      end
+    end
+
+    def extract_id(instance, options, original_options)
+      if options[:with_id] && !@options[:class].ancestors.include?(SingularResource)
+        if instance && instance.id
+          instance.id
+        elsif options[:id]
+          original_options.delete(:id) || original_options.delete("id")
+        end
+      end
+    end
+  end
+end

data/lib/zendesk_api/associations.rb

@@ -0,0 +1,212 @@
+require 'zendesk_api/helpers'
+
+module ZendeskAPI
+  # This module holds association method for resources.
+  # Associations can be loaded in three ways:
+  # * Commonly used resources are automatically side-loaded server side and sent along with their parent object.
+  # * Associated resource ids are sent and are then loaded one-by-one into the parent collection.
+  # * The association is represented with Rails' nested association urls (such as tickets/:id/groups) and are loaded that way.
+  #
+  # @private
+  module Associations
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    def wrap_resource(resource, class_level_association, options = {})
+      instance_association = Association.new(class_level_association.merge(:parent => self))
+      klass = class_level_association[:class]
+
+      case resource
+      when Hash
+        klass.new(@client, resource.merge(:association => instance_association))
+      when String, Integer
+        klass.new(@client, (options[:include_key] || :id) => resource, :association => instance_association)
+      else
+        resource.association = instance_association
+        resource
+      end
+    end
+
+    # @private
+    module ClassMethods
+      def self.extended(klass)
+        klass.extend Has
+        klass.extend HasMany
+      end
+
+      def associations
+        @associations ||= []
+      end
+
+      def associated_with(name)
+        associations.inject([]) do |associated_with, association|
+          if association[:include] == name.to_s
+            associated_with.push(Association.new(association))
+          end
+
+          associated_with
+        end
+      end
+
+      private
+
+      def build_association(klass, resource_name, options)
+        {
+          :class => klass,
+          :name => resource_name,
+          :inline => options.delete(:inline),
+          :path => options.delete(:path),
+          :include => (options.delete(:include) || klass.resource_name).to_s,
+          :include_key => (options.delete(:include_key) || :id).to_s,
+          :singular => options.delete(:singular),
+          :extensions => Array(options.delete(:extend))
+        }
+      end
+
+      def define_used(association)
+        define_method "#{association[:name]}_used?" do
+          !!instance_variable_get("@#{association[:name]}")
+        end
+      end
+
+      module Has
+        # Represents a parent-to-child association between resources. Options to pass in are: class, path.
+        # @param [Symbol] resource_name_or_class The underlying resource name or a class to get it from
+        # @param [Hash] class_level_options The options to pass to the method definition.
+        def has(resource_name_or_class, class_level_options = {})
+          if klass = class_level_options.delete(:class)
+            resource_name = resource_name_or_class
+          else
+            klass = resource_name_or_class
+            resource_name = klass.singular_resource_name
+          end
+
+          class_level_association = build_association(klass, resource_name, class_level_options)
+          class_level_association.merge!(:singular => true, :id_column => "#{resource_name}_id")
+
+          associations << class_level_association
+
+          define_used(class_level_association)
+          define_has_getter(class_level_association)
+          define_has_setter(class_level_association)
+        end
+
+        private
+
+        def define_has_getter(association)
+          klass = association[:class] # shorthand
+
+          define_method association[:name] do |*args|
+            instance_options = args.last.is_a?(Hash) ? args.pop : {}
+
+            # return if cached
+            cached = instance_variable_get("@#{association[:name]}")
+            return cached if cached && !instance_options[:reload]
+
+            # find and cache association
+            instance_association = Association.new(association.merge(:parent => self))
+            resource = if klass.respond_to?(:find) && resource_id = method_missing(association[:id_column])
+              klass.find(@client, :id => resource_id, :association => instance_association)
+            elsif found = method_missing(association[:name].to_sym)
+              wrap_resource(found, association, :include_key => association[:include_key])
+            elsif klass.superclass == DataResource && !association[:inline]
+              response = @client.connection.get(instance_association.generate_path(:with_parent => true))
+              klass.new(@client, response.body[klass.singular_resource_name].merge(:association => instance_association))
+            end
+
+            send("#{association[:id_column]}=", resource.id) if resource && has_key?(association[:id_column])
+            instance_variable_set("@#{association[:name]}", resource)
+          end
+        end
+
+        def define_has_setter(association)
+          define_method "#{association[:name]}=" do |resource|
+            resource = wrap_resource(resource, association)
+            send("#{association[:id_column]}=", resource.id) if has_key?(association[:id_column])
+            instance_variable_set("@#{association[:name]}", resource)
+          end
+        end
+      end
+
+      module HasMany
+        # Represents a parent-to-children association between resources. Options to pass in are: class, path.
+        # @param [Symbol] resource_name_or_class The underlying resource name or class to get it from
+        # @param [Hash] class_level_options The options to pass to the method definition.
+        def has_many(resource_name_or_class, class_level_options = {})
+          if klass = class_level_options.delete(:class)
+            resource_name = resource_name_or_class
+          else
+            klass = resource_name_or_class
+            resource_name = klass.resource_name
+          end
+
+          class_level_association = build_association(klass, resource_name, class_level_options)
+          class_level_association.merge!(:singular => false, :id_column => "#{resource_name}_ids")
+
+          associations << class_level_association
+
+          define_used(class_level_association)
+          define_has_many_getter(class_level_association)
+          define_has_many_setter(class_level_association)
+        end
+
+        private
+
+        def define_has_many_getter(association)
+          klass = association[:class]
+
+          define_method association[:name] do |*args|
+            instance_opts = args.last.is_a?(Hash) ? args.pop : {}
+
+            # return if cached
+            cached = instance_variable_get("@#{association[:name]}")
+            return cached if cached && !instance_opts[:reload]
+
+            # find and cache association
+            instance_association = Association.new(association.merge(:parent => self))
+            singular_resource_name = Inflection.singular(association[:name].to_s)
+
+            resources = if (ids = method_missing("#{singular_resource_name}_ids")) && ids.any?
+              ids.map do |id|
+                klass.find(@client, :id => id, :association => instance_association)
+              end.compact
+            elsif (resources = method_missing(association[:name].to_sym)) && resources.any?
+              resources.map { |res| wrap_resource(res, association) }
+            else
+              []
+            end
+
+            collection = ZendeskAPI::Collection.new(@client, klass, instance_opts.merge(:association => instance_association))
+
+            if association[:extensions].any?
+              collection.extend(*association[:extensions])
+            end
+
+            if resources.any?
+              collection.replace(resources)
+            end
+
+            send("#{association[:id_column]}=", resources.map(&:id)) if has_key?(association[:id_column])
+            instance_variable_set("@#{association[:name]}", collection)
+          end
+        end
+
+        def define_has_many_setter(association)
+          define_method "#{association[:name]}=" do |resources|
+            if resources.is_a?(Array)
+              wrapped = resources.map { |attr| wrap_resource(attr, association) }
+              send(association[:name]).replace(wrapped)
+            else
+              resources.association = Association.new(association.merge(:parent => self))
+              instance_variable_set("@#{association[:name]}", resources)
+            end
+
+            send("#{association[:id_column]}=", resources.map(&:id)) if resources && has_key?(association[:id_column])
+            resource
+          end
+        end
+      end
+    end
+  end
+end

data/lib/zendesk_api/client.rb

@@ -0,0 +1,243 @@
+require 'faraday'
+
+require 'zendesk_api/version'
+require 'zendesk_api/sideloading'
+require 'zendesk_api/configuration'
+require 'zendesk_api/collection'
+require 'zendesk_api/lru_cache'
+require 'zendesk_api/silent_mash'
+require 'zendesk_api/middleware/request/etag_cache'
+require 'zendesk_api/middleware/request/retry'
+require 'zendesk_api/middleware/request/raise_rate_limited'
+require 'zendesk_api/middleware/request/upload'
+require 'zendesk_api/middleware/request/encode_json'
+require 'zendesk_api/middleware/request/url_based_access_token'
+require 'zendesk_api/middleware/response/callback'
+require 'zendesk_api/middleware/response/deflate'
+require 'zendesk_api/middleware/response/gzip'
+require 'zendesk_api/middleware/response/sanitize_response'
+require 'zendesk_api/middleware/response/parse_iso_dates'
+require 'zendesk_api/middleware/response/parse_json'
+require 'zendesk_api/middleware/response/raise_error'
+require 'zendesk_api/middleware/response/logger'
+require 'zendesk_api/delegator'
+
+module ZendeskAPI
+  # The top-level class that handles configuration and connection to the Zendesk API.
+  # Can also be used as an accessor to resource collections.
+  class Client
+    GZIP_EXCEPTIONS = [:em_http, :httpclient]
+
+    # @return [Configuration] Config instance
+    attr_reader :config
+    # @return [Array] Custom response callbacks
+    attr_reader :callbacks
+
+    # Handles resources such as 'tickets'. Any options are passed to the underlying collection, except reload which disregards
+    # memoization and creates a new Collection instance.
+    # @return [Collection] Collection instance for resource
+    def method_missing(method, *args, &block)
+      method = method.to_s
+      options = args.last.is_a?(Hash) ? args.pop : {}
+
+      unless config.use_resource_cache
+        raise "Resource for #{method} does not exist" unless method_as_class(method)
+        return ZendeskAPI::Collection.new(self, method_as_class(method), options)
+      end
+
+      @resource_cache[method] ||= { :class => nil, :cache => ZendeskAPI::LRUCache.new }
+      if !options.delete(:reload) && (cached = @resource_cache[method][:cache].read(options.hash))
+        cached
+      else
+        @resource_cache[method][:class] ||= method_as_class(method)
+        raise "Resource for #{method} does not exist" unless @resource_cache[method][:class]
+        @resource_cache[method][:cache].write(options.hash, ZendeskAPI::Collection.new(self, @resource_cache[method][:class], options))
+      end
+    end
+
+    def respond_to?(method, *args)
+      ((cache = @resource_cache[method]) && cache[:class]) || !method_as_class(method).nil? || super
+    end
+
+    # Returns the current user (aka me)
+    # @return [ZendeskAPI::User] Current user or nil
+    def current_user(reload = false)
+      return @current_user if @current_user && !reload
+      @current_user = users.find(:id => 'me')
+    end
+
+    # Returns the current account
+    # @return [Hash] The attributes of the current account or nil
+    def current_account(reload = false)
+      return @current_account if @current_account && !reload
+      @current_account = SilentMash.new(connection.get('account/resolve').body)
+    end
+
+    # Returns the current locale
+    # @return [ZendeskAPI::Locale] Current locale or nil
+    def current_locale(reload = false)
+      return @locale if @locale && !reload
+      @locale = locales.find(:id => 'current')
+    end
+
+    # Creates a new {Client} instance and yields {#config}.
+    #
+    # Requires a block to be given.
+    #
+    # Does basic configuration constraints:
+    # * {Configuration#url} must be https unless {Configuration#allow_http} is set.
+    def initialize
+      raise ArgumentError, "block not given" unless block_given?
+
+      @config = ZendeskAPI::Configuration.new
+      yield config
+
+      @callbacks = []
+      @resource_cache = {}
+
+      check_url
+
+      config.retry = !!config.retry # nil -> false
+
+      set_raise_error_when_rated_limited
+
+      set_token_auth
+
+      set_default_logger
+      add_warning_callback
+    end
+
+    # Creates a connection if there is none, otherwise returns the existing connection.
+    #
+    # @return [Faraday::Connection] Faraday connection for the client
+    def connection
+      @connection ||= build_connection
+      return @connection
+    end
+
+    # Pushes a callback onto the stack. Callbacks are executed on responses, last in the Faraday middleware stack.
+    # @param [Proc] block The block to execute. Takes one parameter, env.
+    def insert_callback(&block)
+      @callbacks << block
+    end
+
+    # show a nice warning for people using the old style api
+    def self.check_deprecated_namespace_usage(attributes, name)
+      if attributes[name].is_a?(Hash)
+        raise "un-nest '#{name}' from the attributes"
+      end
+    end
+
+    ZendeskAPI::DataNamespace.descendants.each do |namespace|
+      delegator = ZendeskAPI::Helpers.snakecase_string(namespace.to_s.split("::").last)
+      define_method delegator do |*| # takes arguments, but doesn't do anything with them
+        Delegator.new(self)
+      end
+    end
+
+    protected
+
+    # Called by {#connection} to build a connection. Can be overwritten in a
+    # subclass to add additional middleware and make other configuration
+    # changes.
+    #
+    # Uses middleware according to configuration options.
+    #
+    # Request logger if logger is not nil
+    #
+    # Retry middleware if retry is true
+    def build_connection
+      Faraday.new(config.options) do |builder|
+        # response
+        builder.use ZendeskAPI::Middleware::Response::RaiseError
+        builder.use ZendeskAPI::Middleware::Response::Callback, self
+        builder.use ZendeskAPI::Middleware::Response::Logger, config.logger if config.logger
+        builder.use ZendeskAPI::Middleware::Response::ParseIsoDates
+        builder.use ZendeskAPI::Middleware::Response::ParseJson
+        builder.use ZendeskAPI::Middleware::Response::SanitizeResponse
+
+        adapter = config.adapter || Faraday.default_adapter
+
+        unless GZIP_EXCEPTIONS.include?(adapter)
+          builder.use ZendeskAPI::Middleware::Response::Gzip
+          builder.use ZendeskAPI::Middleware::Response::Deflate
+        end
+
+        # request
+        if config.access_token && !config.url_based_access_token
+          builder.authorization("Bearer", config.access_token)
+        elsif config.access_token
+          builder.use ZendeskAPI::Middleware::Request::UrlBasedAccessToken, config.access_token
+        else
+          builder.use Faraday::Request::BasicAuthentication, config.username, config.password
+        end
+
+        if config.cache
+          builder.use ZendeskAPI::Middleware::Request::EtagCache, :cache => config.cache
+        end
+
+        builder.use ZendeskAPI::Middleware::Request::Upload
+        builder.request :multipart
+        builder.use ZendeskAPI::Middleware::Request::EncodeJson
+
+        # Should always be first in the stack
+        builder.use ZendeskAPI::Middleware::Request::Retry, :logger => config.logger, :retry_codes => config.retry_codes, :retry_on_exception => config.retry_on_exception if config.retry
+        if config.raise_error_when_rate_limited
+          builder.use ZendeskAPI::Middleware::Request::RaiseRateLimited, :logger => config.logger
+        end
+
+        builder.adapter(*adapter)
+      end
+    end
+
+    private
+
+    def method_as_class(method)
+      klass_as_string = ZendeskAPI::Helpers.modulize_string(Inflection.singular(method.to_s.gsub(/\W/, '')))
+      ZendeskAPI::Association.class_from_namespace(klass_as_string)
+    end
+
+    def check_url
+      if !config.allow_http && config.url !~ /^https/
+        raise ArgumentError, "zendesk_api is ssl only; url must begin with https://"
+      end
+    end
+
+    def set_raise_error_when_rated_limited
+      config.raise_error_when_rate_limited = if config.retry
+        false
+      else
+        !!config.raise_error_when_rate_limited
+      end
+    end
+
+    def set_token_auth
+      return if config.password || config.token.nil?
+
+      if config.username.nil?
+        raise ArgumentError, "you need to provide a username when using API token auth"
+      else
+        config.password = config.token
+        config.username += "/token" unless config.username.end_with?("/token")
+      end
+    end
+
+    def set_default_logger
+      if config.logger.nil? || config.logger == true
+        require 'logger'
+        config.logger = Logger.new($stderr)
+        config.logger.level = Logger::WARN
+      end
+    end
+
+    def add_warning_callback
+      return unless logger = config.logger
+
+      insert_callback do |env|
+        if warning = env[:response_headers]["X-Zendesk-API-Warn"]
+          logger.warn "WARNING: #{warning}"
+        end
+      end
+    end
+  end
+end