desk 0.3.0

data/lib/desk/client/macro.rb

@@ -0,0 +1,142 @@
+module Desk
+  class Client
+    # Defines methods related to macros
+    module Macro
+      # Returns extended information of macros
+      #
+      #   @option options [Boolean, String, Integer]
+      #   @example Return extended information for 12345
+      #     Desk.macros
+      #     Desk.macros(:count => 5)
+      #     Desk.macros(:count => 5, :page => 3)
+      # @format :json
+      # @authenticated true
+      # @see http://dev.desk.com/docs/api/macros
+      def macros(*args)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        response = get("macros",options)
+        response
+      end
+
+      # Returns extended information on a single macro
+      #
+      #   @param id [Integer] a macro ID
+      #   @option options [Hash]
+      #   @example Return extended information for 12345
+      #     Desk.macro(12345)
+      # @format :json
+      # @authenticated true
+      # @see http://dev.desk.com/docs/api/macros/show
+      def macro(id)
+        response = get("macros/#{id}")
+        response.macro
+      end
+
+      # Creates a new macro
+      #
+      #   @param name [String] A macro name
+      #   @option options [Hash]
+      #   @example Creates a new macro
+      #     Desk.create_macro("name")
+      #     Desk.create_macro("name")
+      # @format :json
+      # @authenticated true
+      # @see http://dev.desk.com/docs/api/macros/create
+      def create_macro(name, *args)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        response = post("macros",options)
+        if response['success']
+          return response['results']['macro']
+        else
+          return response
+        end
+      end
+
+      # Updates a single macro
+      #
+      #   @param id [Integer] a macro ID
+      #   @option options [String]
+      #   @example Updates information for macro 12345
+      #     Desk.update_macro(12345, :subject => "New Subject")
+      # @format :json
+      # @authenticated true
+      # @see http://dev.desk.com/docs/api/macros/update
+      def update_macro(id, *args)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        response = put("macros/#{id}",options)
+        if response['success']
+          return response['results']['macro']
+        else
+          return response
+        end
+      end
+
+      # Deletes a single macro
+      #
+      #   @param id [Integer] a macro ID
+      #   @example Deletes macro 12345
+      #     Desk.update_macro(12345, :subject => "New Subject")
+      # @format :json
+      # @authenticated true
+      # @see http://dev.desk.com/docs/api/macros/update
+      def delete_macro(id)
+        response = delete("macros/#{id}")
+        response
+      end
+
+      ##########
+      # Macro Actions
+      ##########
+
+      # Returns extended information of macros
+      #
+      #   @option options [Boolean, String, Integer]
+      #   @example Return extended information for 12345
+      #     Desk.macro_actions(1)
+      #     Desk.macro_actions(1, :count => 5)
+      #     Desk.macro_actions(1, :count => 5, :page => 3)
+      # @format :json
+      # @authenticated true
+      # @see http://dev.desk.com/docs/api/macros/actions
+      def macro_actions(id, *args)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        response = get("macros/#{id}/actions",options)
+        response['results']
+      end
+
+      # Returns extended information on a single macro
+      #
+      #   @param id [Integer] a macro ID
+      #   @option options [Hash]
+      #   @example Return extended information for 12345
+      #     Desk.macro_action(12345, "set-case-description")
+      # @format :json
+      # @authenticated true
+      # @see http://dev.desk.com/docs/api/macros/actions/show
+      def macro_action(id, slug)
+        response = get("macros/#{id}/actions/#{slug}")
+        response['action']
+      end
+
+      # Updates a single macro action
+      #
+      #   @param id [Integer] a macro ID
+      #   @option options [String]
+      #   @example Updates information for macro 12345
+      #     Desk.update_macro_action(12345, "set-case-description", :value => "New Subject")
+      # @format :json
+      # @authenticated true
+      # @see http://dev.desk.com/docs/api/macros/actions/update
+      def update_macro_action(id, slug, *args)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        response = put("macros/#{id}/actions/#{slug}",options)
+        if response['success']
+          return response['results']['action']
+        else
+          return response
+        end
+      end
+
+    end
+  end
+end

data/lib/desk/client/topic.rb

@@ -0,0 +1,90 @@
+module Desk
+  class Client
+    # Defines methods related to topics
+    module Topic
+      # Returns extended information of topics
+      #
+      #   @option options [Boolean, String, Integer]
+      #   @example Return extended information for 12345
+      #     Desk.topics
+      #     Desk.topics(:count => 5)
+      #     Desk.topics(:count => 5, :page => 3)
+      # @format :json
+      # @authenticated true
+      # @see http://dev.desk.com/docs/api/topics/show
+      def topics(*args)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        response = get("topics",options)
+        response
+      end
+
+      # Returns extended information on a single topic
+      #
+      #   @param id [Integer] a topic ID
+      #   @option options [Hash]
+      #   @example Return extended information for 12345
+      #     Desk.topic(12345)
+      #     Desk.topic(12345, :by => "external_id")
+      # @format :json
+      # @authenticated true
+      # @see http://dev.desk.com/docs/api/topics/show
+      def topic(id, *args)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        response = get("topics/#{id}",options)
+        response.topic
+      end
+
+      # Creates a new topic
+      #
+      #   @param name [String] A topic name
+      #   @option options [Hash]
+      #   @example Creates a new topic
+      #     Desk.create_topic("name")
+      #     Desk.create_topic("name", :description => "description")
+      # @format :json
+      # @authenticated true
+      # @see http://dev.desk.com/docs/api/topics/create
+      def create_topic(name, *args)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        response = post("topics",options)
+        if response['success']
+          return response['results']['topic']
+        else
+          return response
+        end
+      end
+
+      # Updates a single topic
+      #
+      #   @param id [Integer] a topic ID
+      #   @option options [String]
+      #   @example Updates information for topic 12345
+      #     Desk.update_topic(12345, :subject => "New Subject")
+      # @format :json
+      # @authenticated true
+      # @see http://dev.desk.com/docs/api/topics/update
+      def update_topic(id, *args)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        response = put("topics/#{id}",options)
+        if response['success']
+          return response['results']['topic']
+        else
+          return response
+        end
+      end
+
+      # Deletes a single topic
+      #
+      #   @param id [Integer] a topic ID
+      #   @example Deletes topic 12345
+      #     Desk.update_topic(12345, :subject => "New Subject")
+      # @format :json
+      # @authenticated true
+      # @see http://dev.desk.com/docs/api/topics/update
+      def delete_topic(id)
+        response = delete("topics/#{id}")
+        response
+      end
+    end
+  end
+end

data/lib/desk/client/user.rb

@@ -0,0 +1,38 @@
+module Desk
+  class Client
+    # Defines methods related to users
+    module User
+      # Returns extended information of a given user
+      #
+      # @overload user(user, options={})
+      #   @param user [Integer] An Assitely user ID
+      #   @option options [Boolean, String, Integer] :include_entities Include {http://dev.twitter.com/pages/tweet_entities Tweet Entities} when set to true, 't' or 1.
+      #   @return [Hashie::Mash] The requested user.
+      #   @example Return extended information for 12345
+      #     Desk.user(12345)
+      # @format :json, :xml
+      # @authenticated true
+      # @see http://dev.desk.com/docs/api/users/show
+      def user(id,*args)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        response = get("users/#{id}",options)
+        response.user
+      end
+
+      # Returns extended information for up to 100 users
+      #
+      # @format :json, :xml
+      # @authenticated true
+      # @rate_limited true
+      # @return [Array] The requested users.
+      # @see http://dev.desk.com/docs/api/users
+      # @example Return extended information account users
+      #   Desk.users
+      def users(*args)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        response = get('users', options)
+        response
+      end
+    end
+  end
+end

data/lib/desk/configuration.rb

@@ -0,0 +1,98 @@
+require 'faraday'
+require 'desk/version'
+
+module Desk
+  # Defines constants and methods related to configuration
+  module Configuration
+    # An array of valid keys in the options hash when configuring a {Twitter::API}
+    VALID_OPTIONS_KEYS = [
+      :adapter,
+      :consumer_key,
+      :consumer_secret,
+      :format,
+      :oauth_token,
+      :oauth_token_secret,
+      :proxy,
+      :subdomain,
+      :support_email,
+      :user_agent,
+      :version].freeze
+
+    # An array of valid request/response formats
+    #
+    # @note Not all methods support the XML format.
+    VALID_FORMATS = [
+      :json].freeze
+
+    # The adapter that will be used to connect if none is set
+    #
+    # @note The default faraday adapter is Net::HTTP.
+    DEFAULT_ADAPTER = Faraday.default_adapter
+
+    # By default, don't set an application key
+    DEFAULT_CONSUMER_KEY = nil
+
+    # By default, don't set an application secret
+    DEFAULT_CONSUMER_SECRET = nil
+
+    # The response format appended to the path and sent in the 'Accept' header if none is set
+    #
+    # @note JSON is preferred over XML because it is more concise and faster to parse.
+    DEFAULT_FORMAT = :json
+
+    # By default, don't set a user oauth token
+    DEFAULT_OAUTH_TOKEN = nil
+
+    # By default, don't set a user oauth secret
+    DEFAULT_OAUTH_TOKEN_SECRET = nil
+
+    # By default, don't use a proxy server
+    DEFAULT_PROXY = nil
+
+    # By default use example
+    DEFAULT_SUBDOMAIN = "example"
+
+    # The user agent that will be sent to the API endpoint if none is set
+    DEFAULT_USER_AGENT = "Desk.com Ruby Gem #{Desk::VERSION}".freeze
+
+    # The user agent that will be sent to the API endpoint if none is set
+    DEFAULT_VERSION = "v1".freeze
+
+    # By default, don't set a support email address
+    DEFAULT_SUPPORT_EMAIL = nil
+
+    # @private
+    attr_accessor *VALID_OPTIONS_KEYS
+
+    # When this module is extended, set all configuration options to their default values
+    def self.extended(base)
+      base.reset
+    end
+
+    # Convenience method to allow configuration options to be set in a block
+    def configure
+      yield self
+    end
+
+    # Create a hash of options and their values
+    def options
+      Hash[VALID_OPTIONS_KEYS.map {|key| [key, send(key)] }]
+    end
+
+    # Reset all configuration options to defaults
+    def reset
+      self.adapter            = DEFAULT_ADAPTER
+      self.consumer_key       = DEFAULT_CONSUMER_KEY
+      self.consumer_secret    = DEFAULT_CONSUMER_SECRET
+      self.format             = DEFAULT_FORMAT
+      self.oauth_token        = DEFAULT_OAUTH_TOKEN
+      self.oauth_token_secret = DEFAULT_OAUTH_TOKEN_SECRET
+      self.proxy              = DEFAULT_PROXY
+      self.subdomain          = DEFAULT_SUBDOMAIN
+      self.support_email      = DEFAULT_SUPPORT_EMAIL
+      self.user_agent         = DEFAULT_USER_AGENT
+      self.version            = DEFAULT_VERSION
+      self
+    end
+  end
+end

data/lib/desk/connection.rb

@@ -0,0 +1,39 @@
+require 'faraday_middleware'
+require 'faraday/request/multipart_with_file'
+require 'faraday/response/raise_http_4xx'
+require 'faraday/response/raise_http_5xx'
+
+module Desk
+  # @private
+  module Connection
+    private
+
+    def connection(raw=false)
+      options = {
+        :headers => {'Accept' => "application/#{format}", 'User-Agent' => user_agent},
+        :proxy => proxy,
+        :ssl => {:verify => false},
+        :url => api_endpoint,
+      }
+
+      Faraday.new(options) do |builder|
+        builder.use Faraday::Request::MultipartWithFile
+        builder.use Faraday::Request::OAuth, authentication if authenticated?
+        builder.use Faraday::Request::Multipart
+        builder.use Faraday::Request::UrlEncoded
+        builder.use Faraday::Response::RaiseHttp4xx
+        builder.use Faraday::Response::Rashify unless raw
+        unless raw
+          case format.to_s.downcase
+          when 'json'
+            builder.use Faraday::Response::ParseJson
+          when 'xml'
+            builder.use Faraday::Response::ParseXml
+          end
+        end
+        builder.use Faraday::Response::RaiseHttp5xx
+        builder.adapter(adapter)
+      end
+    end
+  end
+end

data/lib/desk/error.rb

@@ -0,0 +1,67 @@
+module Desk
+  # Custom error class for rescuing from all Desk.com errors
+  class Error < StandardError
+    attr_reader :http_headers
+
+    def initialize(message, http_headers)
+      http_headers ||= {}
+      @http_headers = Hash[http_headers]
+      super message
+    end
+
+    def ratelimit_reset
+      Time.at(@http_headers.values_at('x-ratelimit-reset', 'X-RateLimit-Reset').detect {|value| value }.to_i)
+    end
+
+    def ratelimit_limit
+      @http_headers.values_at('x-ratelimit-limit', 'X-RateLimit-Limit').detect {|value| value }.to_i
+    end
+
+    def ratelimit_remaining
+      @http_headers.values_at('x-ratelimit-limit', 'X-RateLimit-Limit').detect {|value| value }.to_i
+    end
+
+    def retry_after
+      [(ratelimit_reset - Time.now).ceil, 0].max
+    end
+  end
+
+  # Raised when Desk returns the HTTP status code 400
+  class BadRequest < Error; end
+
+  # Raised when Desk returns the HTTP status code 401
+  class Unauthorized < Error; end
+
+  # Raised when Desk returns the HTTP status code 403
+  class Forbidden < Error; end
+
+  # Raised when Desk returns the HTTP status code 404
+  class NotFound < Error; end
+
+  # Raised when Desk returns the HTTP status code 406
+  class NotAcceptable < Error; end
+
+  # Raised when Desk returns the HTTP status code 420
+  class EnhanceYourCalm < Error
+    # The number of seconds your application should wait before requesting date from the Search API again
+    #
+    # @see http://dev.desk.com/pages/rate-limiting
+    def retry_after
+      @http_headers.values_at('retry-after', 'Retry-After').detect {|value| value }.to_i
+    end
+  end
+
+  # Raised when Desk returns the HTTP status code 500
+  class InternalServerError < Error; end
+
+  # Raised when Desk returns the HTTP status code 502
+  class BadGateway < Error; end
+
+  # Raised when Desk returns the HTTP status code 503
+  class ServiceUnavailable < Error; end
+
+  # Gem Specific Errors
+  class DeskError < StandardError; end
+
+  class SupportEmailNotSet < DeskError; end
+end