zendesk_api 0.0.9

data/lib/zendesk_api/association.rb

@@ -0,0 +1,267 @@
+module ZendeskAPI
+  # Represents an association between two resources 
+  class Association
+    # @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 = Hashie::Mash.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 = Hashie::Mash.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.delete("ZendeskAPI")
+      has_parent = namespace.size > 1 || (options[:with_parent] && @options.parent)
+
+      if has_parent
+        parent_class = @options.parent ? @options.parent.class : ZendeskAPI.get_class(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_name
+      else
+        namespace[0] = @options.path || @options[:class].resource_name
+      end
+
+      if id = extract_id(instance, options, original_options)
+        namespace << id
+      end
+
+      namespace.join("/")
+    end
+
+    private
+
+    def build_parent_namespace(parent_class, instance, options, original_options)
+      return unless association_on_parent = parent_class.associations.detect {|a| a[:class] == @options[:class] }
+      [
+        extract_parent_id(parent_class, instance, options, original_options),
+        @options.path || association_on_parent[:name].to_s
+      ]
+    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
+
+  # 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.
+  module Associations
+    def self.included(base)
+      base.send(:extend, ClassMethods)
+    end
+
+    def wrap_resource(resource, klass, class_level_association)
+      instance_association = Association.new(class_level_association.merge(:parent => self))
+      case resource
+      when Hash
+        klass.new(@client, resource.merge(:association => instance_association))
+      when String, Fixnum
+        klass.new(@client, :id => resource, :association => instance_association)
+      else
+        resource.association = instance_association
+        resource
+      end
+    end
+
+    module ClassMethods
+      include Rescue
+
+      def associations
+        @assocations ||= []
+      end
+
+      # Represents a parent-to-child association between resources. Options to pass in are: class, path.
+      # @param [Symbol] resource_name The underlying resource name
+      # @param [Hash] opts The options to pass to the method definition.
+      def has(resource_name, class_level_options = {})
+        klass = get_class(class_level_options.delete(:class)) || get_class(resource_name)
+        class_level_association = {
+          :class => klass,
+          :name => resource_name,
+          :inline => class_level_options.delete(:inline),
+          :path => class_level_options.delete(:path)
+        }
+        associations << class_level_association
+        id_column = "#{resource_name}_id"
+
+        define_method "#{resource_name}_used?" do
+          !!instance_variable_get("@#{resource_name}")
+        end
+
+        define_method resource_name do |*args|
+          instance_options = args.last.is_a?(Hash) ? args.pop : {}
+
+          # return if cached
+          cached = instance_variable_get("@#{resource_name}")
+          return cached if cached && !instance_options[:reload]
+
+          # find and cache association
+          instance_association = Association.new(class_level_association.merge(:parent => self))
+          resource = if klass.respond_to?(:find) && resource_id = method_missing(id_column)
+            klass.find(@client, :id => resource_id, :association => instance_association)
+          elsif found = method_missing(resource_name.to_sym)
+            wrap_resource(found, klass, class_level_association)
+          elsif klass.ancestors.include?(DataResource)
+            rescue_client_error do
+              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
+          end
+
+          send("#{id_column}=", resource.id) if resource && has_key?(id_column)
+          instance_variable_set("@#{resource_name}", resource)
+        end
+
+        define_method "#{resource_name}=" do |resource|
+          resource = wrap_resource(resource, klass, class_level_association)
+          send("#{id_column}=", resource.id) if has_key?(id_column)
+          instance_variable_set("@#{resource_name}", resource)
+        end
+      end
+
+      # Represents a parent-to-children association between resources. Options to pass in are: class, path.
+      # @param [Symbol] resource The underlying resource name
+      # @param [Hash] opts The options to pass to the method definition.
+      def has_many(resource_name, class_level_opts = {})
+        klass = get_class(class_level_opts.delete(:class)) || get_class(resource_name.to_s.singular)
+        class_level_association = {
+          :class => klass,
+          :name => resource_name,
+          :inline => class_level_opts.delete(:inline),
+          :path => class_level_opts.delete(:path)
+        }
+        associations << class_level_association
+
+        id_column = "#{resource_name}_ids"
+
+        define_method "#{resource_name}_used?" do
+          !!instance_variable_get("@#{resource_name}")
+        end
+
+        define_method resource_name do |*args|
+          instance_opts = args.last.is_a?(Hash) ? args.pop : {}
+
+          # return if cached
+          cached = instance_variable_get("@#{resource_name}")
+          return cached if cached && !instance_opts[:reload]
+
+          # find and cache association
+          instance_association = Association.new(class_level_association.merge(:parent => self))
+          singular_resource_name = resource_name.to_s.singular
+
+          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(resource_name.to_sym)) && resources.any?
+            resources.map do |res|
+              klass.new(@client, res.merge(:association => instance_association))
+            end
+          else
+            ZendeskAPI::Collection.new(@client, klass, instance_opts.merge(:association => instance_association))
+          end
+
+          send("#{id_column}=", resources.map(&:id)) if resource && has_key?(id_column)
+          instance_variable_set("@#{resource_name}", resources)
+        end
+
+        define_method "#{resource_name}=" do |resources|
+          if resources.is_a?(Array)
+            resources.map! { |attr| wrap_resource(attr, klass, class_level_association) }
+            send(resource_name).replace(resources)
+          else
+            resources.association = instance_association
+            instance_variable_set("@#{resource_name}", resources)
+          end
+
+          send("#{id_column}=", resources.map(&:id)) if resources && has_key?(id_column)
+          resource
+        end
+      end
+
+      # Allows using has and has_many without having class defined yet
+      # Guesses at Resource, if it's anything else and the class is later
+      # reopened under a different superclass, an error will be thrown
+      def get_class(resource)
+        return false if resource.nil?
+        res = resource.to_s.modulize
+
+        begin
+          const_get(res)
+        rescue NameError
+          ZendeskAPI.get_class(resource)
+        end
+      end
+    end
+  end
+
+  class << self
+    # Revert Rails' overwrite of const_missing
+    if method_defined?(:const_missing_without_dependencies)
+      alias :const_missing :const_missing_without_dependencies
+    end
+
+    # Allows using has and has_many without having class defined yet
+    # Guesses at Resource, if it's anything else and the class is later
+    # reopened under a different superclass, an error will be thrown
+    def get_class(resource)
+      return false if resource.nil?
+      res = resource.to_s.modulize.split("::")
+
+      begin
+        res[1..-1].inject(ZendeskAPI.const_get(res[0])) do |iter, k|
+          begin
+            iter.const_get(k)
+          rescue
+            iter.const_set(k, Class.new(Resource))
+          end
+        end
+      rescue NameError
+        ZendeskAPI.const_set(res[0], Class.new(Resource))
+      end
+    end
+  end
+end

data/lib/zendesk_api/client.rb

@@ -0,0 +1,150 @@
+require 'faraday'
+require 'faraday_middleware'
+
+require 'zendesk_api/version'
+require 'zendesk_api/rescue'
+require 'zendesk_api/configuration'
+require 'zendesk_api/collection'
+require 'zendesk_api/lru_cache'
+require 'zendesk_api/middleware/request/etag_cache'
+require 'zendesk_api/middleware/request/retry'
+require 'zendesk_api/middleware/request/upload'
+require 'zendesk_api/middleware/response/callback'
+require 'zendesk_api/middleware/response/deflate'
+require 'zendesk_api/middleware/response/gzip'
+require 'zendesk_api/middleware/response/parse_iso_dates'
+
+module ZendeskAPI
+  class Client
+    include Rescue
+
+    # @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 : {}
+      return instance_variable_get("@#{method}") if !options.delete(:reload) && instance_variable_defined?("@#{method}")
+      instance_variable_set("@#{method}", ZendeskAPI::Collection.new(self, ZendeskAPI.get_class(method.singular), options))
+    end
+
+    # Plays a view playlist.
+    # @param [String/Number] id View id or 'incoming'
+    def play(id)
+      ZendeskAPI::Playlist.new(self, id)
+    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
+
+    def current_account(reload = false)
+      return @current_account if @current_account && !reload
+      @current_account = Hashie::Mash.new(connection.get('account/resolve').body)
+    end
+
+    rescue_client_error :current_account
+
+    # Returns the current locale
+    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
+
+      if !config.allow_http && config.url !~ /^https/
+        raise ArgumentError, "zendesk_api is ssl only; url must begin with https://"
+      end
+
+      config.retry = !!config.retry # nil -> false
+
+      if config.logger.nil? || config.logger == true
+        require 'logger'
+        config.logger = Logger.new($stderr)
+        config.logger.level = Logger::WARN
+      end
+
+      @callbacks = []
+
+      if logger = config.logger
+        insert_callback do |env|
+          if warning = env[:response_headers]["X-Zendesk-API-Warn"]
+            logger.warn "WARNING: #{warning}"
+          end
+        end
+      end
+    end
+
+    # Creates a connection if there is none, otherwise returns the existing connection.
+    #
+    # @returns [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)
+      raise "un-nest '#{name}' from the attributes" if attributes[name].is_a?(Hash)
+    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 Faraday::Request::BasicAuthentication, config.username, config.password
+        builder.use Faraday::Response::RaiseError
+        builder.use ZendeskAPI::Middleware::Response::Callback, self
+        builder.use Faraday::Response::Logger, config.logger if config.logger
+        builder.use ZendeskAPI::Middleware::Response::ParseIsoDates
+        builder.response :json, :content_type => 'application/json'
+        builder.use ZendeskAPI::Middleware::Response::Gzip
+        builder.use ZendeskAPI::Middleware::Response::Deflate
+
+        # request
+        builder.use ZendeskAPI::Middleware::Request::EtagCache, :cache => config.cache
+        builder.use ZendeskAPI::Middleware::Request::Upload
+        builder.request :multipart
+        builder.request :json
+        builder.use ZendeskAPI::Middleware::Request::Retry, :logger => config.logger if config.retry # Should always be first in the stack
+
+        builder.adapter *config.adapter || Faraday.default_adapter
+      end
+    end
+  end
+end

data/lib/zendesk_api/collection.rb

@@ -0,0 +1,233 @@
+require 'zendesk_api/resource'
+require 'zendesk_api/resources/misc'
+require 'zendesk_api/resources/ticket'
+require 'zendesk_api/resources/user'
+require 'zendesk_api/resources/playlist'
+
+module ZendeskAPI
+  # Represents a collection of resources. Lazily loaded, resources aren't
+  # actually fetched until explicitly needed (e.g. #each, {#fetch}).
+  class Collection
+    SPECIALLY_JOINED_PARAMS = [:include, :ids, :only]
+
+    include Rescue
+
+    # @return [ZendeskAPI::Association] The class association
+    attr_reader :association
+
+    # Creates a new Collection instance. Does not fetch resources.
+    # Additional options are: verb (default: GET), path (default: resource param), page, per_page.
+    # @param [Client] client The {Client} to use.
+    # @param [String] resource The resource being collected.
+    # @param [Hash] options Any additional options to be passed in.
+    def initialize(client, resource, options = {})
+      @client, @resource = client, resource.resource_name
+      @options = Hashie::Mash.new(options)
+
+      @verb = @options.delete(:verb)
+      @collection_path = @options.delete(:collection_path)
+
+      association_options = { :path => @options.delete(:path) }
+      association_options[:path] ||= @collection_path.join("/") if @collection_path
+      @association = @options.delete(:association) || Association.new(association_options.merge(:class => resource))
+
+      # some params use comma-joined strings instead of query-based arrays for multiple values
+      @options.each do |k, v|
+        if SPECIALLY_JOINED_PARAMS.include?(k.to_sym) && v.is_a?(Array)
+          @options[k] = v.join(',')
+        end
+      end
+
+      @collection_path ||= [@resource]
+      @resource_class = resource
+      @fetchable = true
+
+      # Used for Attachments, TicketComment
+      if @resource_class.superclass == ZendeskAPI::Data
+        @resources = []
+        @fetchable = false
+      end
+    end
+
+    # Passes arguments and the proper path to the resource class method.
+    # @param [Hash] attributes Attributes to pass to Create#create
+    def create(attributes = {})
+      attributes.merge!(:association => @association)
+      @resource_class.create(@client, @options.merge(attributes))
+    end
+
+    # (see #create)
+    def find(opts = {})
+      opts.merge!(:association => @association)
+      @resource_class.find(@client, @options.merge(opts))
+    end
+
+    # (see #create)
+    def update(opts = {})
+      opts.merge!(:association => @association)
+      @resource_class.update(@client, @options.merge(opts))
+    end
+
+    # (see #create)
+    def destroy(opts = {})
+      opts.merge!(:association => association)
+      @resource_class.destroy(@client, @options.merge(opts))
+    end
+
+    # @return [Number] The total number of resources server-side (disregarding pagination).
+    def count
+      fetch
+      @count
+    end
+
+    # Changes the per_page option. Returns self, so it can be chained. No execution.
+    # @return [Collection] self
+    def per_page(count)
+      @options["per_page"] = count
+      self
+    end
+
+    # Changes the page option. Returns self, so it can be chained. No execution.
+    # @return [Collection] self
+    def page(number)
+      @options["page"] = number
+      self
+    end
+
+    # Saves all newly created resources stored in this collection.
+    # @return [Collection] self
+    def save
+      if @resources
+        @resources.map! do |item|
+          unless !item.respond_to?(:save) || item.changes.empty?
+            item.save
+          end
+
+          item
+        end
+      end
+
+      self
+    end
+
+    def <<(item)
+      fetch
+      if item.is_a?(Resource)
+        if item.is_a?(@resource_class)
+          @resources << item
+        else
+          raise "this collection is for #{@resource_class}"
+        end
+      else
+        item.merge!(:association => @association) if item.is_a?(Hash)
+        @resources << @resource_class.new(@client, item)
+      end
+    end
+
+    def path
+      @association.generate_path(:with_parent => true)
+    end
+
+    # Executes actual GET from API and loads resources into proper class.
+    # @param [Boolean] reload Whether to disregard cache
+    def fetch(reload = false)
+      return @resources if @resources && (!@fetchable || !reload)
+      if association && association.options.parent && association.options.parent.new_record?
+        return @resources = []
+      end
+
+      if @query
+        path = @query
+        @query = nil
+      else
+        path = self.path
+      end
+
+      response = @client.connection.send(@verb || "get", path) do |req|
+        req.params.merge!(@options.delete_if {|k, v| v.nil?})
+      end
+
+      results = response.body[@resource_class.model_key] || response.body["results"]
+      @resources = results.map { |res| @resource_class.new(@client, res) }
+
+      @count = (response.body["count"] || @resources.size).to_i
+      @next_page, @prev_page = response.body["next_page"], response.body["previous_page"]
+
+      @resources
+    end
+
+    rescue_client_error :fetch, :with => lambda { Array.new }
+
+    # Alias for fetch(false)
+    def to_a
+      fetch
+    end
+
+    def replace(collection)
+      raise "this collection is for #{@resource_class}" if collection.any?{|r| !r.is_a?(@resource_class) }
+      @resources = collection
+    end
+
+    # Find the next page. Does one of three things: 
+    # * If there is already a page number in the options hash, it increases it and invalidates the cache, returning the new page number.
+    # * If there is a next_page url cached, it executes a fetch on that url and returns the results.
+    # * Otherwise, returns an empty array.
+    def next
+      if @options["page"]
+        clear_cache
+        @options["page"] += 1
+      elsif @next_page
+        @query = @next_page
+        fetch(true)
+      else
+        []
+      end
+    end
+
+    # Find the previous page. Does one of three things: 
+    # * If there is already a page number in the options hash, it increases it and invalidates the cache, returning the new page number.
+    # * If there is a prev_page url cached, it executes a fetch on that url and returns the results.
+    # * Otherwise, returns an empty array.
+    def prev
+      if @options["page"] && @options["page"] > 1 
+        clear_cache
+        @options["page"] -= 1
+      elsif @prev_page
+        @query = @prev_page
+        fetch(true)
+      else
+        []
+      end
+    end
+
+    # Clears all cached resources and associated values.
+    def clear_cache
+      @resources = nil
+      @count = nil
+      @next_page = nil
+      @prev_page = nil
+    end
+
+    def to_ary; nil; end
+
+    # Sends methods to underlying array of resources.
+    def method_missing(name, *args, &block)
+      if Array.new.respond_to?(name)
+        to_a.send(name, *args, &block)
+      else
+        opts = args.last.is_a?(Hash) ? args.last : {}
+        opts.merge!(:collection_path => @collection_path.dup.push(name))
+        self.class.new(@client, @resource_class, @options.merge(opts))
+      end
+    end
+
+    alias :orig_to_s :to_s
+    def to_s
+      if @resources
+        @resources.inspect
+      else
+        orig_to_s
+      end
+    end
+  end
+end