desk 0.3.0

data/lib/desk.rb

@@ -0,0 +1,26 @@
+require 'desk/error'
+require 'desk/configuration'
+require 'desk/api'
+require 'desk/client'
+require 'pony'
+
+module Desk
+  extend Configuration
+
+  # Alias for Desk::Client.new
+  #
+  # @return [Desk::Client]
+  def self.client(options={})
+    Desk::Client.new(options)
+  end
+
+  # Delegate to Desk::Client
+  def self.method_missing(method, *args, &block)
+    return super unless client.respond_to?(method)
+    client.send(method, *args, &block)
+  end
+
+  def self.respond_to?(method)
+    client.respond_to?(method) || super
+  end
+end

data/lib/desk/api.rb

@@ -0,0 +1,28 @@
+require 'desk/connection'
+require 'desk/request'
+require 'desk/authentication'
+
+module Desk
+  # @private
+  class API
+    # @private
+    attr_accessor *Configuration::VALID_OPTIONS_KEYS
+
+    # Creates a new API
+    def initialize(options={})
+      options = Desk.options.merge(options)
+
+      Configuration::VALID_OPTIONS_KEYS.each do |key|
+        send("#{key}=", options[key])
+      end
+    end
+
+    def endpoint
+      "https://#{self.subdomain}.desk.com/api/#{self.version}/"
+    end
+
+    include Connection
+    include Request
+    include Authentication
+  end
+end

data/lib/desk/authentication.rb

@@ -0,0 +1,25 @@
+module Desk
+  # @private
+  module Authentication
+    private
+
+    # Authentication hash
+    #
+    # @return [Hash]
+    def authentication
+      {
+        :consumer_key => consumer_key,
+        :consumer_secret => consumer_secret,
+        :token => oauth_token,
+        :token_secret => oauth_token_secret
+      }
+    end
+
+    # Check whether user is authenticated
+    #
+    # @return [Boolean]
+    def authenticated?
+      authentication.values.all?
+    end
+  end
+end

data/lib/desk/client.rb

@@ -0,0 +1,28 @@
+module Desk
+  # Wrapper for the Desk.com REST API
+  #
+  # @note All methods have been separated into modules and follow the same grouping used in {http://dev.desk.com/doc the Desk.com API Documentation}.
+  # @see http://dev.desk.com/pages/every_developer
+  class Client < API
+    # Require client method modules after initializing the Client class in
+    # order to avoid a superclass mismatch error, allowing those modules to be
+    # Client-namespaced.
+    require 'desk/client/user'
+    require 'desk/client/interaction'
+    require 'desk/client/case'
+    require 'desk/client/customer'
+    require 'desk/client/topic'
+    require 'desk/client/article'
+    require 'desk/client/macro'
+
+    alias :api_endpoint :endpoint
+
+    include Desk::Client::User
+    include Desk::Client::Interaction
+    include Desk::Client::Case
+    include Desk::Client::Customer
+    include Desk::Client::Topic
+    include Desk::Client::Article
+    include Desk::Client::Macro
+  end
+end

data/lib/desk/client/article.rb

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

data/lib/desk/client/case.rb

@@ -0,0 +1,55 @@
+module Desk
+  class Client
+    # Defines methods related to cases
+    module Case
+      # Returns extended information of cases
+      #
+      #   @option options [Boolean, String, Integer]
+      #   @example Return extended information for 12345
+      #     Desk.cases(:case_id => 12345)
+      #     Desk.cases(:email => "customer@example.com", :count => 5)
+      #     Desk.cases(:since_id => 12345)
+      # @format :json
+      # @authenticated true
+      # @see http://dev.desk.com/docs/api/cases/show
+      def cases(*args)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        response = get("cases",options)
+        response
+      end
+
+      # Returns extended information on a single case
+      #
+      #   @option options [String]
+      #   @example Return extended information for 12345
+      #     Desk.case(12345)
+      #     Desk.case(12345, :by => "external_id")
+      # @format :json
+      # @authenticated true
+      # @see http://dev.desk.com/docs/api/cases/show
+      def case(id, *args)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        response = get("cases/#{id}",options)
+        response.case
+      end
+
+      # Updates a single case
+      #
+      #   @option options [String]
+      #   @example Return extended information for 12345
+      #     Desk.update_case(12345, :subject => "New Subject")
+      # @format :json
+      # @authenticated true
+      # @see http://dev.desk.com/docs/api/cases/update
+      def update_case(id, *args)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        response = put("cases/#{id}",options)
+        response.case
+      end
+
+      def case_url(id)
+        "https://#{subdomain}.desk.com/agent/case/#{id}"
+      end
+    end
+  end
+end

data/lib/desk/client/customer.rb

@@ -0,0 +1,146 @@
+module Desk
+  class Client
+    # Defines methods related to customers
+    module Customer
+      # Returns extended information of customers
+      #
+      #   @option options [Boolean, String, Integer]
+      #   @example Return extended information for customers
+      #     Desk.customers
+      #     Desk.customers(:since_id => 12345, :count => 5)
+      # @format :json
+      # @authenticated true
+      # @see http://dev.desk.com/docs/api/customers
+      def customers(*args)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        response = get("customers",options)
+        response
+      end
+
+      # Returns extended information on a single customer
+      #
+      #   @option options [String]
+      #   @example Return extended information for customer 12345
+      #     Desk.customer(12345)
+      # @format :json
+      # @authenticated true
+      # @see http://dev.desk.com/docs/api/customers/show
+      def customer(id)
+        response = get("customers/#{id}")
+        response.customer
+      end
+
+      # Create a new customer
+      #
+      #   @option options [String]
+      #   @example Return extended information for 12345
+      #     Desk.create_customer(:name => "Chris Warren", :twitter => "cdwarren")
+      # @format :json
+      # @authenticated true
+      # @see http://dev.desk.com/docs/api/customers/create
+      def create_customer(*args)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        response = post("customers",options)
+        if response['success']
+          return response['results']['customer']
+        else
+          return response
+        end
+      end
+
+      # Update a customer
+      #
+      #   @option options [String]
+      #   @example Return extended information for 12345
+      #     Desk.update_customer(12345, :name => "Christopher Warren")
+      # @format :json
+      # @authenticated true
+      # @see http://dev.desk.com/docs/api/customers/update
+      def update_customer(id, *args)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        response = put("customers/#{id}",options)
+        if response['success']
+          return response['results']['customer']
+        else
+          return response
+        end
+      end
+
+      # Create a new customer email
+      #
+      #   @option options [String]
+      #   @example Return extended information for 12345
+      #     Desk.create_customer_email(12345, "foo@example.com")
+      # @format :json
+      # @authenticated true
+      # @see http://dev.desk.com/docs/api/customers/emails/create
+      def create_customer_email(id, email, *args)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        options.merge!({:email => email})
+        response = post("customers/#{id}/emails",options)
+        if response['success']
+          return response['results']['email']
+        else
+          return response
+        end
+      end
+
+      # Update a customer's email
+      #
+      #   @option options [String]
+      #   @example Return extended information for 12345
+      #     Desk.update_customer_email(12345, 12345, :email => "foo@example.com")
+      #     Desk.update_customer_email(12345, 12345, :customer_contact_type => "work")
+      # @format :json
+      # @authenticated true
+      # @see http://dev.desk.com/docs/api/customers/emails/update
+      def update_customer_email(id, email_id, *args)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        response = put("customers/#{id}/emails/#{email_id}",options)
+        if response['success']
+          return response['results']['email']
+        else
+          return response
+        end
+      end
+
+      # Create a new customer phone number
+      #
+      #   @option options [String]
+      #   @example Return extended information for 12345
+      #     Desk.create_customer_phone(12345, "555-368-7147")
+      # @format :json
+      # @authenticated true
+      # @see http://dev.desk.com/docs/api/customers/phones/create
+      def create_customer_phone(id, phone, *args)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        options.merge!({:phone => phone})
+        response = post("customers/#{id}/phones",options)
+        if response['success']
+          return response['results']['phone']
+        else
+          return response
+        end
+      end
+
+      # Update a customer's phone number
+      #
+      #   @option options [String]
+      #   @example Return extended information for 12345
+      #     Desk.update_customer_phone(12345, 12345, :phone => "555-368-7147")
+      #     Desk.update_customer_phone(12345, 12345, :customer_contact_type => "work")
+      # @format :json
+      # @authenticated true
+      # @see http://dev.desk.com/docs/api/customers/phones/update
+      def update_customer_phone(id, phone_id, *args)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        response = put("customers/#{id}/phones/#{phone_id}",options)
+        if response['success']
+          return response['results']['phone']
+        else
+          return response
+        end
+      end
+    end
+  end
+end

data/lib/desk/client/interaction.rb

@@ -0,0 +1,75 @@
+module Desk
+  class Client
+    # Defines methods related to interactions
+    module Interaction
+
+      # Returns extended information of up to 100 interactions
+      #
+      #   @option options [Boolean, String, Integer]
+      #   @example Return extended information for 12345
+      #     Desk.interactions(:since_id => 12345)
+      #     Desk.interactions(:since_id => 12345, :count => 5)
+      # @format :json
+      # @authenticated true
+      # @see http://dev.desk.com/docs/api/interactions
+      def interactions(*args)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        response = get("interactions",options)
+        response
+      end
+
+      def create_interaction(*args)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        if options[:direction].to_s == "outbound"
+          options.delete(:direction)
+          to      = options.delete(:customer_email)
+          subject = options.delete(:interaction_subject)
+          body    = options.delete(:interaction_body)
+
+          create_outbound_interaction(to, subject, body, options)
+        else
+          create_inbound_interaction(options)
+        end
+      end
+
+      # Creates an interaction from a customer
+      #
+      # @format :json
+      # @authenticated true
+      # @rate_limited true
+      # @return [Array] The requested users.
+      # @see http://dev.desk.com/docs/api/interactions/create
+      # @example Create a new interaction
+      #   Desk.create_interaction(:interaction_subject => "this is an api test", :customer_email => "foo@example.com")
+      def create_inbound_interaction(*args)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        response = post('interactions', options)
+        if response['success']
+          return response['results']
+        else
+          return response
+        end
+      end
+
+      # Create an interaction from an agent
+      #
+      # Desk's API doesn't support creating a new case/interaction initiated by an agent
+      # so we'll use send an email to the customer directly that is BCC'd to the support email address
+      # which will create the ticket
+      #
+      # @see http://support.desk.com/customer/portal/articles/4180
+      # @see http://support.desk.com/customer/portal/articles/6728
+      def create_outbound_interaction(to, subject, body, *args)
+        raise Desk::SupportEmailNotSet if support_email.blank?
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        options.merge!(:to => to, :subject => subject, :body => body, :from => support_email, :bcc => support_email)
+        headers = { "x-assistly-customer-email" => to,
+                    "x-assistly-interaction-direction" => "out",
+                    "x-assistly-case-status" => options[:status]||"open"}
+        headers.merge!(options[:headers]) if options[:headers]
+        options.merge!(:headers => headers)
+        Pony.mail(options)
+      end
+    end
+  end
+end