desk_api 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: bd267e380566167aae73f9d0b26d8d84e72b1749
-  data.tar.gz: deaee7be024ea5238866cb2e8fab1e8e579cbe25
+  metadata.gz: e26e977b6cb1ed65a5dee9ccd93a3f4617fb71e0
+  data.tar.gz: 46a9845c1399f0a4644cde8f614c9ea38bcfc1e1
 SHA512:
-  metadata.gz: 0319000b143117a540561e855ee3f03adcb46a85db1ff87567d0702dd0cc9a7ac9978bca858a642e677ca39f22d8d60dc513f7c452b8a3b4788725db431f7a09
-  data.tar.gz: abde08faf56067f3fbea77028ef954dd04cf8f6dbcab698d6deb07fe13711570f0742f07dfa9d60a716d611bf0a7bd040e84f1ad973f3fe98db6e6f38bfc8821
+  metadata.gz: 3c2e40fa8dbff7ac13c88e43233c155123efe5d4cd4c87c173e6b4428f725d76e4da01d49481c9d7ddfc6039f2aa25ad328da34d8c3ba19a664bed74c35309d5
+  data.tar.gz: 146cccebb60d61ce7c779a9fe35fe0f26284922270ffe97efbbe4f6c927db15d1bd54fc00844187a8d7ebfad4a0647f6c44ca068c93899c736899868a9a6fa50

data/README.md

@@ -54,6 +54,8 @@ The API supports RESTful resources and so does this wrapper. Those resources are
 found_case = DeskApi.users.first.by_url '/api/v2/cases/1'
 
 # find a case by case number
+found_case = DeskApi.cases.find 1
+# the old #by_id still works
 found_case = DeskApi.cases.by_id 1
 ```
 
@@ -108,6 +110,27 @@ end
 DeskApi.cases.page == 1
 ```
 
+### Side loading
+
+APIv2 has a lot of great new features but the one I'm most excited about is side loading or embedding resources. You basically request one resource and tell the API to embed sub resources, eg. you need cases but also want to have the `assigned_user` - instead of requesting all cases and the `assigned_user` for each of those cases (30 cases = 31 API requests) you can now embed `assigned_user` into your cases list view (1 API REQUEST!!!!).
+
+Of course we had to bring this awesomeness into the API wrapper as soon as possible, so here you go:
+
+```ruby
+# fetch cases with their respective customers
+cases = DeskApi.cases.embed(:customer)
+customer = cases.first.customer
+
+# you can use this feature in finders too
+my_case = DeskApi.cases.find(1, embed: :customer)
+# OR
+my_case = DeskApi.cases.find(1, embed: [:customer, :assigned_user, :assigned_group])
+
+customer = my_case.customer
+assigned_user = my_case.assigned_user
+assigned_group = my_case.assigned_group
+```
+
 ### Create, Update and Delete
 
 Of course we support creating, updating and deleting resources but not all resources can be deleted or updated or created, if that's the case for the resource you're trying to update, it'll throw a `DeskApi::Error::MethodNotSupported` error. The specific method won't be defined on the resource either `DeskApi.cases.first.respond_to?(:delete) == false`.
@@ -191,7 +214,7 @@ Please also have a look at all [desk.com API errors](http://dev.desk.com/API/usi
 
 (The MIT License)
 
-Copyright (c) 2013 Thomas Stachl <tom@desk.com>
+Copyright (c) 2013 Thomas Stachl <thomas@desk.com>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

data/lib/desk_api/action/embeddable.rb

@@ -0,0 +1,47 @@
+require 'desk_api/error/not_embeddable'
+
+module DeskApi
+  module Action
+    module Embeddable
+      attr_reader :embedded
+
+      def embed(*embedds)
+        # make sure we don't try to embed anything that's not defined
+        # add it to the query
+        self.query_params = { embed: embedds.each{ |embed|
+          unless self.base_class.embeddable?(embed)
+            raise DeskApi::Error::NotEmbeddable.new("`#{embed.to_s}' can not be embedded.")
+          end
+        }.join(',') }
+        # return self
+        self
+      end
+
+      def setup_embedded(embedds)
+        if embedds.entries?
+          @records = embedds['entries'].map do |record|
+            resource(record._links.self['class']).new(client, record, true)
+          end 
+        else
+          embedds.each_pair do |key, definition|
+            @_links[key]['resource'] = resource(definition['class']).new @client, definition, true
+          end
+        end
+      end
+
+      module ClassMethods
+        def embeddable(*embeddables)
+          @embeddables = embeddables
+        end
+
+        def embeddable?(key)
+          (@embeddables || []).include?(key.to_sym)
+        end
+      end
+
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+    end
+  end
+end

data/lib/desk_api/action/update.rb

@@ -2,9 +2,14 @@ module DeskApi
   module Action
     module Update
       def update(params = {})
+        if kind_of?(resource('case')) and status == 'closed'
+          raise DeskApi::Error::NotUpdateable
+        end
+
         params.each_pair do |key, value|
           send("#{key}=", value) if respond_to?("#{key}=")
         end
+        
         setup(client.patch(@_links.self.href, @_changed).body)
       end
     end

data/lib/desk_api/error/not_embeddable.rb

@@ -0,0 +1,8 @@
+require 'desk_api/error'
+
+module DeskApi
+  class Error
+    class NotEmbeddable < DeskApi::Error
+    end
+  end
+end

data/lib/desk_api/error/not_updateable.rb

@@ -0,0 +1,10 @@
+require 'desk_api/error'
+
+module DeskApi
+  class Error
+    # Raised when an updateable resources becomes non-updateable
+    # and you try to update it
+    class NotUpdateable < DeskApi::Error
+    end
+  end
+end

data/lib/desk_api/error/unprocessable_entity.rb

@@ -5,6 +5,7 @@ module DeskApi
     # Raised when desk.com returns the HTTP status code 422
     class UnprocessableEntity < DeskApi::Error::ClientError
       HTTP_STATUS_CODE = 422
+      attr_reader :errors
     end
   end
 end

data/lib/desk_api/error.rb

@@ -11,10 +11,9 @@ module DeskApi
     # @param response_headers [Hash]
     # @param code [Integer]
     # @return [DeskApi::Error]
-    def initialize(exception=$!, response_headers={}, code = nil)
+    def initialize(exception=$!, response_headers={}, code = nil, err_hash = nil)
       @rate_limit = DeskApi::RateLimit.new(response_headers)
-      @wrapped_exception = exception
-      @code = code
+      @wrapped_exception, @code, @errors = exception, code, err_hash
       exception.respond_to?(:backtrace) ? super(exception.message) : super(exception.to_s)
     end
 
@@ -28,8 +27,8 @@ module DeskApi
       # @param response [Hash]
       # @return [DeskApi::Error]
       def from_response(response = {})
-        error, code = parse_error(response[:body]), response[:status]
-        new(error, response[:response_headers], code)
+        err_hash, error, code = parse_body(response[:body]).push(response[:status])
+        new(error, response[:response_headers], code, err_hash)
       end
 
       # @return [Hash]
@@ -51,11 +50,10 @@ module DeskApi
 
     private
 
-      def parse_error(body)
-        if body['message']
-          body['message']
-        end
+      def parse_body(body = {})
+        [body['errors'] || nil, body['message'] || nil]
       end
+
     end
   end
 end

data/lib/desk_api/resource/case.rb

@@ -4,6 +4,8 @@ module DeskApi
       include DeskApi::Action::Create
       include DeskApi::Action::Update
       include DeskApi::Action::Search
+
+      embeddable :customer, :assigned_user, :assigned_group, :locked_by
     end
   end
 end

data/lib/desk_api/resource/filter.rb

@@ -0,0 +1,7 @@
+module DeskApi
+  class Resource
+    class Filter < DeskApi::Resource
+      embeddable :user, :group
+    end
+  end
+end

data/lib/desk_api/resource/inbound_mailbox.rb

@@ -0,0 +1,7 @@
+module DeskApi
+  class Resource
+    class InboundMailbox < DeskApi::Resource
+      embeddable :default_group
+    end
+  end
+end

data/lib/desk_api/resource/job.rb

@@ -2,6 +2,8 @@ module DeskApi
   class Resource
     class Job < DeskApi::Resource
       include DeskApi::Action::Create
+      
+      embeddable :user
     end
   end
 end

data/lib/desk_api/resource/page.rb

@@ -2,7 +2,6 @@ module DeskApi
   class Resource
     class Page < DeskApi::Resource
       include Enumerable
-      include DeskApi::Action::Embedded
 
       [
         :all?, :any?,
@@ -31,44 +30,28 @@ module DeskApi
       [:page, :per_page].each do |method|
         define_method(method) do |value = nil|
           if not value
-            self.exec! if self.query_params(method.to_s) == nil
-            return self.query_params(method.to_s).to_i
+            self.exec! if self.query_params_include?(method.to_s) == nil
+            return self.query_params_include?(method.to_s).to_i
           end
           self.query_params = Hash[method.to_s, value.to_s]
           self
         end
       end
 
-      def by_id(id)
-        by_url("#{clean_base_url}/#{id}")
+      def find(id, options = {})
+        res = base_class.new(client, Hashie::Mash.new({ _links: { self: { href: "#{clean_base_url}/#{id}" }}}))
+        if options[:embed]
+          options[:embed] = [options[:embed]] unless options[:embed].kind_of?(Array)
+          res.embed(*options[:embed])
+        end
+        res.exec!
       end
+      alias_method :by_id, :find
 
     protected
     
       attr_reader :records
 
-      def setup(definition)
-        setup_embedded(definition._embedded['entries']) if definition._embedded?
-        super(definition)
-      end
-
-      def query_params(param)
-        params = Addressable::URI.parse(@_links.self.href).query_values || {}
-        params.include?(param) ? params[param] : nil
-      end
-
-      def query_params=(params = {})
-        return @_links.self.href if params.empty?
-
-        uri = Addressable::URI.parse(@_links.self.href)
-        params = (uri.query_values || {}).merge(params)
-
-        @loaded = false unless params == uri.query_values
-
-        uri.query_values = params
-        @_links.self.href = uri.to_s
-      end
-
       def clean_base_url
         Addressable::URI.parse(@_links.self.href).path.gsub(/\/search$/, '') 
       end

data/lib/desk_api/resource/reply.rb

@@ -3,6 +3,8 @@ module DeskApi
     class Reply < DeskApi::Resource
       include DeskApi::Action::Create
       include DeskApi::Action::Update
+
+      embeddable :case, :sent_by, :entered_by
     end
   end
 end

data/lib/desk_api/resource.rb

@@ -1,6 +1,6 @@
 require 'desk_api/action/create'
 require 'desk_api/action/delete'
-require 'desk_api/action/embedded'
+require 'desk_api/action/embeddable'
 require 'desk_api/action/field'
 require 'desk_api/action/link'
 require 'desk_api/action/resource'
@@ -14,6 +14,7 @@ module DeskApi
     include DeskApi::Action::Resource
     include DeskApi::Action::Link
     include DeskApi::Action::Field
+    include DeskApi::Action::Embeddable
 
     def initialize(client, definition = {}, loaded = false)
       @client, @loaded, @_changed = client, loaded, {}
@@ -37,16 +38,41 @@ module DeskApi
 
     def exec!(reload = false)
       return self if loaded and !reload
-      definition, @loaded = client.get(@_links.self.href).body, true
+      definition, @loaded = client.get(get_href).body, true
       setup(definition)
     end
 
+    def query_params
+      Addressable::URI.parse(@_links.self.href).query_values || {}
+    end
+
+    def query_params_include?(param)
+      query_params.include?(param) ? query_params[param] : nil
+    end
+
+    def query_params=(params = {})
+      return @_links.self.href if params.empty?
+
+      uri = Addressable::URI.parse(@_links.self.href)
+      params = (uri.query_values || {}).merge(params)
+
+      @loaded = false unless params == uri.query_values
+
+      uri.query_values = params
+      @_links.self.href = uri.to_s
+    end
+
+    def base_class
+      self.class
+    end
+
   private
     
     attr_accessor :client, :loaded, :_changed
 
     def setup(definition)
       setup_links(definition._links) if definition._links?
+      setup_embedded(definition._embedded) if definition._embedded?
       setup_fields(definition)
       self
     end
@@ -56,6 +82,5 @@ module DeskApi
       raise DeskApi::Error::MethodNotSupported unless self.respond_to?(method.to_sym)
       self.send(method, *args, &block) 
     end
-
   end
 end

data/lib/desk_api/version.rb

@@ -1,3 +1,3 @@
 module DeskApi
-  VERSION = '0.1.2'
+  VERSION = '0.1.3'
 end

data/spec/cassettes/DeskApi_Error/on_validation_error/allows_access_to_error_hash.yml

@@ -0,0 +1,54 @@
+---
+http_interactions:
+- request:
+    method: post
+    uri: https://devel.desk.com/api/v2/articles
+    body:
+      encoding: UTF-8
+      string: '{"subject":"Testing","body":"Testing"}'
+    headers:
+      Accept:
+      - application/json
+      User-Agent:
+      - desk.com Ruby Gem v0.1.2
+      Content-Type:
+      - application/json
+  response:
+    status:
+      code: 422
+      message: 
+    headers:
+      Accept-Ranges:
+      - bytes
+      Cache-Control:
+      - no-cache
+      Content-Type:
+      - application/json; charset=utf-8
+      Date:
+      - Wed, 04 Sep 2013 23:57:05 GMT
+      Status:
+      - 422 Unprocessable Entity
+      Vary:
+      - X-AppVersion
+      X-AppVersion:
+      - '9.7'
+      X-Frame-Options:
+      - SAMEORIGIN
+      X-Rate-Limit-Limit:
+      - '60'
+      X-Rate-Limit-Remaining:
+      - '59'
+      X-Rate-Limit-Reset:
+      - '55'
+      X-Request-Id:
+      - a902613e4a179503f1a94b35421449ec
+      Content-Length:
+      - '71'
+      Connection:
+      - keep-alive
+    body:
+      encoding: UTF-8
+      string: '{"message":"Validation Failed","errors":{"_links":{"topic":["blank"]}}}'
+    http_version: 
+  recorded_at: Wed, 04 Sep 2013 23:57:05 GMT
+recorded_with: VCR 2.5.0