desk 0.3.3 → 1.0.0

data/TRANSITION.mkd

@@ -0,0 +1,133 @@
+Desk.com API v1 to v2 transition guide
+======================================
+
+The API v2 endpoints and responses are both highly standardized and
+significantly different compared to v1 of the API. As a result the Desk.com Ruby
+gem was almost entirely rewritten to take advantage of the changes. An
+unfortunate side effect is that likely all projects upgrading from v1 to v2 will
+need to be rewritten to some extent.
+
+Below are some ideas and tips for utilizing the new features as well as
+transition guides for the original endpoints.
+
+General Pagination
+------------------
+
+Previously, to paginate through results (like all cases) you would need to do
+something similar to the following:
+
+    page = 1
+    while page > 0 do
+      results = Desk.cases(:count => 10, :page => page)
+      # Do something with results
+      if page*10 >= results.total
+        page = 0
+      else
+        page += 1
+      end
+    end
+
+Now, utilizing the new "\_links" callbacks (see the main README for more
+information), pagination can be done like:
+
+    results = Desk.list_cases
+    while results
+      # Do something with results
+      results = results.next
+    end
+
+Result objects
+--------------
+
+Previously, the raw results from the API were returned as a Hashie object. This
+required your code to dig down like:
+
+    r = Desk.cases(:count => 5)
+    r.results.each do |c|
+      theActualCaseObject = c.case
+      # Do something with theActualCaseObject
+    end
+
+    r = Desk.case(12345)
+    theActualCaseObject = r.case
+    # Do soemthing with theActualCaseObject
+
+Now, the object returned (an extended Hashie object of type Deash) gives root
+level access to the endpoint fields. This allows for:
+
+    Desk.cases(:per_page => 5).each do |theCase|
+      # Do something with theCase
+    end
+
+    theCase = Desk.case(12345)
+    # Do soemthing with theCase
+
+For more information see the specific endpoint examples below.
+
+Cases & Interaction endpoint examples
+-------------------------------------
+
+Previously cases and interactions were seperate endpoints. Additionally all
+interactions were returned with no direct access to a specific interaction, the
+original message or notes. Just to get, for example, the original interaction
+for all cases assigned to a user your code likely looked something like this:
+
+    r = Desk.cases(:assigned_user => "joe")
+    r.results.each do |c|
+      in = Desk.interactions(:case_id => c.case.case_id)
+      in.results.each do |i|
+        if( i.interaction.basis == "original" )
+          i.interaction.interactionable.each do |interaction_type, interaction|
+            case interaction_type
+            when "email"
+              puts "Message: #{interaction.body}
+            when "tweet"
+              puts "Message: #{interaction.subject}"
+            when "chat"
+              puts "Message: #{interaction.messages.first.message.text}"
+            end
+          end
+        end
+      end
+    end
+
+Now, because of standardized fields and responses along with the _links
+callbacks, the above can be simplified to:
+
+    Desk.cases(:assigned_user => "joe").each do |c|
+      puts "Message: #{c.message.body}"
+    end
+
+For more information on accessing case messages, replies, notes, attachments and
+history site the README and http://dev.desk.com/API/cases/
+
+Customer endpoint examples
+--------------------------
+
+The redundancy for customers is gone as well. Email addresses, phone numbers and
+addresses are no longer burried and are all accessible in a uniform way. So, with
+API v1, what looked like:
+
+    customers = Desk.customers(:since_created_at => 1279139906)
+    customers.results.each do |customer|
+      puts "#{customer.customer.first_name} #{customer.customer.last_name}"
+      customer.customer.addresses.each do |address|
+        puts address.address.location
+      end
+      customer.customer.phones.each do |phone|
+        # seriously, this is correct, but it feels a bit excessive
+        puts phone.phone.phone
+      end
+      customer.customer.twitters.each do |twitter|
+        puts twitter.twitter.login
+      end
+    end
+
+using the API v2 looks like:
+
+    Desk.customers(:since_created_at => 1279139906).each do |customer|
+      puts "#{customer.first_name} #{customer.last_name}"
+      customer.addresses.each { |address| puts address.value }
+      customer.phone_numbers.each { |phone| puts phone.value }
+      puts customer.twitter_user.handle
+    end

data/desk.gemspec

@@ -19,7 +19,7 @@ Gem::Specification.new do |s|
   s.add_runtime_dependency('multi_json', '~> 1.6')
   s.add_runtime_dependency('multi_xml', '~> 0.5')
   s.add_runtime_dependency('rash', '~> 0.3.1')
-  s.add_runtime_dependency('simple_oauth', '~> 0.1.4')
+  s.add_runtime_dependency('simple_oauth', '~> 0.2.0')
   s.add_runtime_dependency('pony', '~> 1.1')
   s.authors = ["Chris Warren"]
   s.description = %q{A Ruby wrapper for the Desk.com REST API}

data/lib/desk.rb

@@ -11,7 +11,7 @@ module Desk
 
   class << self
     attr_accessor :counter, :minute
-    
+
     # Alias for Desk::Client.new
     #
     # @return [Desk::Client]

data/lib/desk/api.rb

@@ -18,7 +18,11 @@ module Desk
     end
 
     def endpoint
-      "https://#{self.subdomain}.desk.com/api/#{self.version}/"
+      "https://#{self.subdomain}.desk.com"+api_path
+    end
+
+    def api_path
+      "/api/#{self.version}/"
     end
 
     include Connection

data/lib/desk/client.rb

@@ -7,24 +7,198 @@ module Desk
     # 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/group'
-    require 'desk/client/interaction'
+    require 'desk/client/article'
+    require 'desk/client/brand'
     require 'desk/client/case'
+    require 'desk/client/company'
+    require 'desk/client/custom_field'
     require 'desk/client/customer'
-    require 'desk/client/topic'
-    require 'desk/client/article'
+    require 'desk/client/facebook_user'
+    require 'desk/client/filter'
+    require 'desk/client/group'
+    require 'desk/client/insight'
+    require 'desk/client/integration_url'
+    require 'desk/client/job'
+    require 'desk/client/label'
     require 'desk/client/macro'
+    require 'desk/client/mailbox'
+    require 'desk/client/rule'
+    require 'desk/client/site_setting'
+    require 'desk/client/system_message'
+    require 'desk/client/topic'
+    require 'desk/client/twitter_account'
+    require 'desk/client/twitter_user'
+    require 'desk/client/user'
 
     alias :api_endpoint :endpoint
 
-    include Desk::Client::User
-    include Desk::Client::Group
-    include Desk::Client::Interaction
+    include Desk::Client::Article
+    include Desk::Client::Brand
     include Desk::Client::Case
+    include Desk::Client::Company
+    include Desk::Client::CustomField
     include Desk::Client::Customer
-    include Desk::Client::Topic
-    include Desk::Client::Article
+    include Desk::Client::FacebookUser
+    include Desk::Client::Filter
+    include Desk::Client::Group
+    include Desk::Client::Insight
+    include Desk::Client::IntegrationUrl
+    include Desk::Client::Job
+    include Desk::Client::Label
     include Desk::Client::Macro
+    include Desk::Client::Mailbox
+    include Desk::Client::Rule
+    include Desk::Client::SiteSetting
+    include Desk::Client::SystemMessage
+    include Desk::Client::Topic
+    include Desk::Client::TwitterAccount
+    include Desk::Client::TwitterUser
+    include Desk::Client::User
+
+
+    def initialize(options={})
+      if !self.respond_to? :endpoints_setup
+        self.class.included_modules.each do |m|
+          if r = m.name.match(/Desk::Client::([a-zA-z]+)/)
+            base = r[1].gsub(/(.)([A-Z])/, '\1_\2').downcase
+            if self.respond_to? "#{base}_endpoints"
+              endpoints_list = send("#{base}_endpoints")
+              setup_functions(base, endpoints_list)
+            end
+          end
+        end
+        self.class.send(:define_method, :endpoints_setup) {}
+      end
+      super(options)
+    end
+
+    def plural(singular)
+      if singular[-1, 1] == "y"
+        singular[0..-2]+"ies"
+      elsif singular[-1, 1] == "x"
+        singular+"es"
+      else
+        singular+"s"
+      end
+    end
+
+    def create_link(type, class_or_hash, id = nil, sub_class = nil, sub_id = nil)
+      if class_or_hash.class == Hashie::Deash
+        {type.to_sym => {
+          :class => class_or_hash._links.self['class'],
+          :href => class_or_hash._links.self['href']
+        }}
+      elsif class_or_hash.class == String
+        href = Desk.api_path+plural(class_or_hash)+"/#{id}"
+        href += "/"+plural(sub_class)+"/#{sub_id}" if sub_class != nil
+        {type.to_sym => { :class => class_or_hash, :href => href }}
+      else
+        nil
+      end
+    end
+
+    private
+
+    def setup_functions(base, endpoints_list)
+      endpoints_list.each do |endpoint|
+        eps = endpoint.to_s.split("_")
+        endpoint = eps[0]
+        bases = plural(base)
+        sub_ep = eps[1]
+        sub_eps = plural(sub_ep) if sub_ep
+
+        case endpoint
+        when "list"
+          if sub_ep
+            method_name = "list_#{base}_#{sub_ep}"
+            alias_names = ["#{base}_#{sub_ep}"]
+            block = lambda{ |id, *args|
+              options = args.last.is_a?(Hash) ? args.pop : {}
+              get("#{bases}/#{id}/#{sub_ep}", options)
+            }
+          else
+            method_name = "list_#{bases}"
+            alias_names = [bases]
+            block = lambda{ |*args|
+              options = args.last.is_a?(Hash) ? args.pop : {}
+              searchOptions = options.keys - [:page, :per_page]
+              if (!self.respond_to? "search_#{bases}") || searchOptions.empty?
+                get(bases, options)
+              else
+                send("search_#{bases}", options)
+              end
+            }
+          end
+        when "search"
+          method_name = "search_#{bases}"
+          alias_names = []
+          block = lambda{ |*args|
+            options = args.last.is_a?(Hash) ? args.pop : {}
+            get("#{bases}/search", options)
+          }
+        when "show"
+          if sub_ep
+            method_name = "show_#{base}_#{sub_ep}"
+            alias_names = ["#{base}_#{sub_ep}"]
+            block = lambda{ |id, sub_id|
+              get("#{bases}/#{id}/#{sub_eps}/#{sub_id}")
+            }
+          else
+            method_name = "show_#{base}"
+            alias_names = [base]
+            block = lambda{ |id| get("#{bases}/#{id}") }
+          end
+        when "create"
+          if sub_ep
+            method_name = "create_#{base}_#{sub_ep}"
+            alias_names = []
+            block = lambda{ |id, *args|
+              options = args.last.is_a?(Hash) ? args.pop : {}
+              post("#{bases}/#{id}/#{sub_eps}", options)
+            }
+          else
+            method_name = "create_#{base}"
+            alias_names = []
+            block = lambda{ |*args|
+              options = args.last.is_a?(Hash) ? args.pop : {}
+              post("#{bases}", options)
+            }
+          end
+        when "update"
+          if sub_ep
+            method_name = "update_#{base}_#{sub_ep}"
+            alias_names = []
+            block = lambda{ |id, sub_id, *args|
+              options = args.last.is_a?(Hash) ? args.pop : {}
+              patch("#{bases}/#{id}/#{sub_eps}/#{sub_id}", options)
+            }
+          else
+            method_name = "update_#{base}"
+            alias_names = []
+            block = lambda{ |id, *args|
+              options = args.last.is_a?(Hash) ? args.pop : {}
+              patch("#{bases}/#{id}", options)
+            }
+          end
+        when "delete"
+          if sub_ep
+            method_name = "delete_#{base}_#{sub_ep}"
+            alias_names = []
+            block = lambda{ |id, sub_id|
+              delete("#{bases}/#{id}/#{sub_eps}/#{sub_id}")
+            }
+          else
+            method_name = "delete_#{base}"
+            alias_names = []
+            block = lambda{ |id| delete("#{bases}/#{id}") }
+          end
+        end
+        self.class.send(:define_method, method_name, block)
+        alias_names.each do |alias_name|
+          self.class.send(:alias_method, alias_name, method_name)
+        end
+      end
+    end
+
   end
 end

data/lib/desk/client/article.rb

@@ -1,92 +1,13 @@
 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
+      def article_endpoints
+        [ :list, :show, :create, :update, :delete, :search,
+          :list_translations, :show_translation, :create_translation,
+          :update_translation, :delete_translation ]
       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