desk_api 0.1.3 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e26e977b6cb1ed65a5dee9ccd93a3f4617fb71e0
-  data.tar.gz: 46a9845c1399f0a4644cde8f614c9ea38bcfc1e1
+  metadata.gz: 1b2abb909d8097d68812564cb94b981e61affb4e
+  data.tar.gz: 6b00d878ab5b3086a68beafcde591faa619cc9f4
 SHA512:
-  metadata.gz: 3c2e40fa8dbff7ac13c88e43233c155123efe5d4cd4c87c173e6b4428f725d76e4da01d49481c9d7ddfc6039f2aa25ad328da34d8c3ba19a664bed74c35309d5
-  data.tar.gz: 146cccebb60d61ce7c779a9fe35fe0f26284922270ffe97efbbe4f6c927db15d1bd54fc00844187a8d7ebfad4a0647f6c44ca068c93899c736899868a9a6fa50
+  metadata.gz: 32423d4711f1b5850e3066b0fc67ec2e340933ce57f1e4b5420adefd4e2d08827c79562acf512dcffef3c0de399c8d920d03fa29c73643d0b54836ba6f140882
+  data.tar.gz: 4238fa03c918f4d3d8d2d5b550c7fcf28b246fcccd3600d4a1444fd93680010aaa426a142b50ac995a453fffc551120c2b08c2013545261dfb4d609721a0206e

data/.travis.yml

@@ -1,5 +1,4 @@
 rvm:
   - 1.9.3
   - 2.0.0
-  - jruby-19mode # JRuby in 1.9 mode
-  - rbx-19mode
+  - jruby-19mode # JRuby in 1.9 mode

data/Gemfile

@@ -4,12 +4,6 @@ group :development, :test do |variable|
   # Testing infrastructure
   gem 'guard'
   gem 'guard-rspec'
-
-  if RUBY_PLATFORM =~ /darwin/
-    # OS X integration
-    gem 'ruby_gntp'
-    gem 'rb-fsevent'
-  end
 end
 
 gemspec

data/README.md

@@ -29,7 +29,7 @@ response = client.patch '/api/v2/topics/1', name: 'Changed the Topic Name'
 response = client.delete '/api/v2/topics/1' 
 ```
 
-For ease of use and if you only create one connection to the desk.com API you can use `Desk` directly:
+For ease of use and if you only create one connection to the desk.com API you can use `DeskApi` directly:
 
 ```ruby
 DeskApi.configure do |config|
@@ -46,39 +46,45 @@ DeskApi.delete '/api/v2/topics/1'
 
 ## Working with Resources and Collections
 
-The API supports RESTful resources and so does this wrapper. Those resources are automatically discovered, meaning you can navigate around without having to worry about anything. We also support two finder methods `by_url` and `by_id`, the former works with any resource, the latter needs a collection.
+The API supports RESTful resources and so does this wrapper. These resources are automatically discovered, meaning you can navigate around without having to worry about anything. We also support two finder methods `by_url` and `find`.
 
 ### Finders
-```ruby
-# get the first user and find a case by url.
-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
-```
+The method `by_url` can be called on all `DeskApi::Resource` instances and will return a lazy loaded instance of the resource. Since the update to v0.5 of the API wrapper the `find` method can now be called on all `DeskApi::Resource` instances too. _Gotcha:_ It will rebuild the base path based on the resource/collection it is called on. So if you call it on the cases collection `DeskApi.cases.find 1` the path will look like this: `/api/v2/cases/:id`.
+
+| Method                                                      | Path                        |
+| ----------------------------------------------------------- | --------------------------- |
+| `DeskApi.cases.find(1)`                                     | `/api/v2/cases/1`           |
+| `DeskApi.cases.entries.find(1)`                             | `/api/v2/cases/1`           |
+| `DeskApi.cases.search(subject: 'Test').find(1)`             | `/api/v2/cases/1`           |
+| `DeskApi.cases.search(subject: 'Test').entries.find(1)`     | `/api/v2/cases/1`           |
+| `DeskApi.cases.entries.first.replies.find(1)`               | `/api/v2/cases/1/replies/1` |
+| `DeskApi.cases.entries.first.replies.entries.first.find(1)` | `/api/v2/cases/1/replies/1` |
 
 ### Pagination
 
-As mentioned above you can also navigate between resources and mainly pages of collections.
+As mentioned above you can also navigate between resources and pages of collections. _Please Notice:_ `DeskApi.cases` doesn't behave like an `Array` any longer, it's just a `DeskApi::Resource` so links like `next`, `previous`, `first` and `last` can be called directly. However you'll have to request the `entries` before you can loop through all the records on the page.
 
 ```ruby
 cases = DeskApi.cases
-cases.each do |my_case|
+cases.entries.each do |my_case|
   # do something with the case
 end
+
 # now move on to the next page
-next_page = cases.next_page
-next_page.each do |my_case|
+next_page = cases.next
+next_page.entries.each do |my_case|
   # do something with the case
 end
+
 # go back to the previous page
-previous_page = next_page.previous_page
+previous_page = next_page.previous
+
 # or go to the last page
-last_page = previous_page.last_page
+last_page = previous_page.last
+
 # or go to the first page
-first_page = last_page.first_page
+first_page = last_page.first
 ```
 
 ### Links
@@ -87,22 +93,23 @@ Pagination is pretty obvious but the cool part about pagination or rather resour
 
 ```ruby
 # get the customer of the first case of the first page
-customer = DeskApi.cases.first.customer
+customer = DeskApi.cases.entries.first.customer
+
 # who sent the first outbound reply of the first email
-user_name = DeskApi.cases.select{ |my_case| 
+user_name = DeskApi.cases.entries.select{ |my_case| 
               my_case.type == 'email'
-            }.first.replies.select{ |reply|
+            }.first.replies.entries.select{ |reply|
               reply.direction == 'out'
             }.first.sent_by.name
 ```
 
 ### Lazy loading
 
-Collections and resources in general are lazily loaded, meaning if you request the cases `DeskApi.cases` no actual request will be set off until you actually request data. This makes sure only necessary requests are fired and which keeps the overall requests low and spares the [desk.com rate limit](http://dev.desk.com/API/using-the-api/#rate-limits).
+Collections and resources in general are lazily loaded, meaning if you request the cases `DeskApi.cases` no actual request will be set off until you actually request data. Meaning only necessary requests are sent which will keep the request count low - [desk.com rate limit](http://dev.desk.com/API/using-the-api/#rate-limits).
 
 ```ruby
-DeskApi.cases.page(10).per_page(50).each do |my_case|
-  # in this method chain `.each' is the first method that acutally sends a request
+DeskApi.cases.page(10).per_page(50).entries.each do |my_case|
+  # in this method chain `.entries' is the first method that acutally sends a request
 end
 
 # however if you request the current page numer and the resource is not loaded
@@ -112,7 +119,7 @@ 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!!!!).
+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:
 
@@ -124,7 +131,7 @@ 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])
+my_case = DeskApi.cases.find(1, embed: [:customer, :assigned_user, :assigned_group, :message])
 
 customer = my_case.customer
 assigned_user = my_case.assigned_user
@@ -133,7 +140,7 @@ 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`.
+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::MethodNotAllowed` error. For ease of use and because we wanted to build as less business logic into the wrapper as possible, all of the methods are defined on each `DeskApi::Resource` and will be sent to desk.com. However the API might respond with an error if you do things that aren't supported.
 
 ```ruby
 # let's create an article
@@ -159,17 +166,17 @@ end
 # ATTENTION: Cases can not be deleted!
 begin
   DeskApi.cases.first.delete
-rescue DeskApi::Error::MethodNotSupported => e
+rescue DeskApi::Error::MethodNotAllowed => e
   # too bad
 end
 ```
 
 ### Getters & Setters
 
-As you have seen in prior examples for each field on the resource we create a getter and setter. Be careful if a resource is not updatable it won't have a setter specified.
+As you have seen in prior examples for each field on the resource we create a getter and setter.
 
 ```ruby
-customer = DeskApi.customers.by_id(1)
+customer = DeskApi.customers.find(1)
 
 puts customer.first_name
 puts customer.last_name
@@ -185,8 +192,8 @@ updated_customer = customer.update title: 'Master of the Universe'
 # users are not updatable
 begin
   user = DeskApi.users.first
-  user.name = 'Not updateable'
-rescue DeskApi::Error::MethodNotSupported
+  user.update name: 'Not updateable'
+rescue DeskApi::Error::MethodNotAllowed
   # too bad
 end
 ```

data/desk_api.gemspec

@@ -10,7 +10,7 @@ Gem::Specification.new do |gem|
   gem.version           = DeskApi::VERSION
 
   gem.authors           = ['Thomas Stachl']
-  gem.email             = 'tom@desk.com'
+  gem.email             = 'thomas@desk.com'
 
   gem.require_paths     = ['lib']
   gem.files             = `git ls-files`.split("\n")
@@ -20,13 +20,10 @@ Gem::Specification.new do |gem|
   gem.extra_rdoc_files  = ['README.md']
   gem.rdoc_options      = ['--line-numbers', '--inline--source', '--title', 'desk.rb']
 
-  gem.add_runtime_dependency('multi_json')
   gem.add_runtime_dependency('faraday')
   gem.add_runtime_dependency('faraday_middleware')
   gem.add_runtime_dependency('simple_oauth')
-  gem.add_runtime_dependency('typhoeus')
   gem.add_runtime_dependency('addressable')
-  gem.add_runtime_dependency('activesupport')
   gem.add_runtime_dependency('hashie')
 
   gem.add_development_dependency('rspec')

data/lib/desk_api.rb

@@ -3,14 +3,11 @@ require 'json'
 require 'forwardable'
 require 'addressable/uri'
 
-require 'hashie/mash'
-require 'active_support/inflector'
-
-require 'desk_api/configuration'
-require 'desk_api/client'
-require 'desk_api/version'
-
 module DeskApi
+  require 'desk_api/version'
+  require 'desk_api/configuration'
+  require 'desk_api/client'
+
   class << self
     include DeskApi::Configuration
 
@@ -31,5 +28,6 @@ module DeskApi
       client.respond_to?(method_name, include_private)
     end
   end
+
   setup
 end

data/lib/desk_api/client.rb

@@ -1,67 +1,54 @@
-require 'faraday'
-
-require 'desk_api/configuration'
-require 'desk_api/action/link'
-require 'desk_api/action/resource'
-require 'desk_api/error/client_error'
-require 'desk_api/error/parse_error'
-
 require 'desk_api/resource'
+require 'desk_api/error/parser_error'
+
+class DeskApi::Client
+  include DeskApi::Configuration
+
+  # Initializes a new Client object
+  #
+  # @param options [Hash]
+  # @return [DeskApi::Client]
+  def initialize(options = {})
+    DeskApi::Configuration.keys.each do |key|
+      instance_variable_set(:"@#{key}", options[key] || DeskApi.instance_variable_get(:"@#{key}"))
+    end
+  end
 
-module DeskApi
-  class Client
-    include DeskApi::Configuration
-    include DeskApi::Action::Link
-    include DeskApi::Action::Resource
-
-    # Initializes a new Client object
-    #
-    # @param options [Hash]
-    # @return [DeskApi::Client]
-    def initialize(options = {})
-      DeskApi::Configuration.keys.each do |key|
-        instance_variable_set(:"@#{key}", options[key] || DeskApi.instance_variable_get(:"@#{key}"))
-      end
+  # Perform an HTTP DELETE request
+  def delete(path, params = {})
+    request(:delete, path, params)
+  end
 
-      # load the initial resources (should actually be a call to /api/v2 but not yet)
-      resources = File.open(File.expand_path('resources.json', File.dirname(__FILE__))).read
-      definition = Hashie::Mash.new(JSON.parse(resources))
-      # on the client we only have links
-      setup_links(definition._links)
-    end
+  # Perform an HTTP GET request
+  def get(path, params = {})
+    request(:get, path, params)
+  end
 
-    # Perform an HTTP DELETE request
-    def delete(path, params = {})
-      request(:delete, path, params)
-    end
+  # Perform an HTTP POST request
+  def post(path, params = {})
+    request(:post, path, params)
+  end
 
-    # Perform an HTTP GET request
-    def get(path, params = {})
-      request(:get, path, params)
-    end
+  # Perform an HTTP PATCH request
+  def patch(path, params = {})
+    request(:patch, path, params)
+  end
 
-    # Perform an HTTP POST request
-    def post(path, params = {})
-      request(:post, path, params)
-    end
+private
+  # If the method is missing create a resource
+  def method_missing(method, *args, &block)
+    DeskApi::Resource.new(self, DeskApi::Resource.build_self_link("/api/v2/#{method}"))
+  end
 
-    # Perform an HTTP PATCH request
-    def patch(path, params = {})
-      request(:patch, path, params)
-    end
-  
-  private
-    
-    def request(method, path, params = {})
-      connection.send(method, path, params)
-    rescue Faraday::Error::ClientError
-      raise DeskApi::Error::ClientError
-    rescue JSON::ParserError
-      raise DeskApi::Error::ParserError
-    end
+  def request(method, path, params = {})
+    connection.send(method, path, params)
+  rescue Faraday::Error::ClientError
+    raise DeskApi::Error::ClientError
+  rescue JSON::ParserError
+    raise DeskApi::Error::ParserError
+  end
 
-    def connection
-      @connection ||= Faraday.new endpoint, connection_options, &middleware
-    end
+  def connection
+    @connection ||= Faraday.new endpoint, connection_options, &middleware
   end
 end

data/lib/desk_api/configuration.rb

@@ -1,9 +1,6 @@
 require 'faraday'
 require 'faraday_middleware'
 
-require 'typhoeus'
-require 'typhoeus/adapters/faraday'
-
 require 'desk_api/default'
 require 'desk_api/request/retry'
 require 'desk_api/response/raise_error'
@@ -11,122 +8,119 @@ require 'desk_api/error/configuration_error'
 require 'desk_api/error/client_error'
 require 'desk_api/error/server_error'
 
-module DeskApi
-  module Configuration
-    extend Forwardable
-    attr_writer :consumer_secret, :token, :token_secret, :password
-    attr_accessor :consumer_key, :username, :endpoint, :subdomain, :connection_options, :middleware
-    def_delegator :options, :hash
-
-    class << self
-      def keys
-        @keys ||= [
-          :consumer_key,
-          :consumer_secret,
-          :token,
-          :token_secret,
-          :username,
-          :password,
-          :subdomain,
-          :endpoint,
-          :connection_options
-        ]
-      end
+module DeskApi::Configuration
+  extend Forwardable
+  attr_writer :consumer_secret, :token, :token_secret, :password
+  attr_accessor :consumer_key, :username, :endpoint, :subdomain, :connection_options, :middleware
+  def_delegator :options, :hash
+
+  class << self
+    def keys
+      @keys ||= [
+        :consumer_key,
+        :consumer_secret,
+        :token,
+        :token_secret,
+        :username,
+        :password,
+        :subdomain,
+        :endpoint,
+        :connection_options
+      ]
     end
+  end
 
-    # if subdomain is set make sure endpoint is correct
-    def endpoint
-      @endpoint ||= "https://#{@subdomain}.desk.com"
-    end
+  # if subdomain is set make sure endpoint is correct
+  def endpoint
+    @endpoint ||= "https://#{@subdomain}.desk.com"
+  end
 
-    def middleware
-      @middleware ||= Proc.new do |builder|
-        builder.request :json
-        builder.request :basic_auth, @username, @password if basic_auth.values.all?
-        builder.request :oauth, oauth if oauth.values.all?
-        builder.request :retry
+  def middleware
+    @middleware ||= Proc.new do |builder|
+      builder.request :json
+      builder.request :basic_auth, @username, @password if basic_auth.values.all?
+      builder.request :oauth, oauth if oauth.values.all?
+      builder.request :retry
 
-        builder.response :mashify
-        builder.response :dates
-        builder.response :raise_error, DeskApi::Error::ClientError
-        builder.response :raise_error, DeskApi::Error::ServerError
-        builder.response :json, content_type: /application\/json/
+      builder.response :dates
+      builder.response :raise_error, DeskApi::Error::ClientError
+      builder.response :raise_error, DeskApi::Error::ServerError
+      builder.response :json, content_type: /application\/json/
 
-        builder.adapter :typhoeus
-      end
+      builder.adapter Faraday.default_adapter
     end
+  end
 
-    def configure
-      yield self
-      validate_credentials!
-      validate_endpoint!
-      self
-    end
+  def configure
+    yield self
+    validate_credentials!
+    validate_endpoint!
+    self
+  end
 
-    def reset!
-      DeskApi::Configuration.keys.each do |key|
-        send("#{key}=", DeskApi::Default.options[key])
-      end
-      self
+  def reset!
+    DeskApi::Configuration.keys.each do |key|
+      send("#{key}=", DeskApi::Default.options[key])
     end
-    alias setup reset!
+    self
+  end
+  alias setup reset!
 
-    def credentials?
-      oauth.values.all? || basic_auth.values.all?
-    end
+  def credentials?
+    oauth.values.all? || basic_auth.values.all?
+  end
 
-  private
-    # @return [Hash]
-    def options
-      Hash[DeskApi::Configuration.keys.map{|key| [key, instance_variable_get(:"@#{key}")]}]
-    end
+private
+  # @return [Hash]
+  def options
+    Hash[DeskApi::Configuration.keys.map{|key| [key, instance_variable_get(:"@#{key}")]}]
+  end
 
-    def oauth
-      {
-        consumer_key: @consumer_key,
-        consumer_secret: @consumer_secret,
-        token: @token,
-        token_secret: @token_secret
-      }
-    end
+  def oauth
+    {
+      consumer_key: @consumer_key,
+      consumer_secret: @consumer_secret,
+      token: @token,
+      token_secret: @token_secret
+    }
+  end
 
-    def basic_auth
-      {
-        username: @username,
-        password: @password
-      }
-    end
+  def basic_auth
+    {
+      username: @username,
+      password: @password
+    }
+  end
 
-    def validate_credentials!
-      unless credentials?
-        raise(Error::ConfigurationError, "Invalid credentials: Either username/password or OAuth credentials must be specified.")
-      end
+  def validate_credentials!
+    unless credentials?
+      raise(DeskApi::Error::ConfigurationError, "Invalid credentials: Either username/password or OAuth credentials must be specified.")
+    end
 
-      if oauth.values.all?
-        oauth.each do |credential, value|
-          next if value.nil?
+    if oauth.values.all?
+      oauth.each do |credential, value|
+        next if value.nil?
 
-          unless value.is_a?(String) || value.is_a?(Symbol)
-            raise(Error::ConfigurationError, "Invalid #{credential} specified: #{value} must be a string or symbol.")
-          end
+        unless value.is_a?(String) || value.is_a?(Symbol)
+          raise(DeskApi::Error::ConfigurationError, "Invalid #{credential} specified: #{value} must be a string or symbol.")
         end
       end
+    end
 
-      if basic_auth.values.all?
-        basic_auth.each do |credential, value|
-          next if value.nil?
+    if basic_auth.values.all?
+      basic_auth.each do |credential, value|
+        next if value.nil?
 
-          unless value.is_a?(String) || value.is_a?(Symbol)
-            raise(Error::ConfigurationError, "Invalid #{credential} specified: #{value} must be a string or symbol.")
-          end
+        unless value.is_a?(String) || value.is_a?(Symbol)
+          raise(DeskApi::Error::ConfigurationError, "Invalid #{credential} specified: #{value} must be a string or symbol.")
         end
       end
     end
+  end
 
-    def validate_endpoint!
-      unless endpoint =~ /^#{URI::regexp}$/
-        raise(Error::ConfigurationError, "Invalid endpoint specified: `#{endpoint}` must be a valid url.")
-      end
+  def validate_endpoint!
+    unless endpoint =~ /^#{URI::regexp}$/
+      raise(DeskApi::Error::ConfigurationError, "Invalid endpoint specified: `#{endpoint}` must be a valid url.")
     end
   end
 end