desk_api 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 6b7e54656d496540b4dca275b4288ee34341b3c6
+  data.tar.gz: fadb4549ca2e30c77e92fa0f74aece67f9176ce6
+SHA512:
+  metadata.gz: a14e59d2749dab344223176662a5d20b262d12e010247a76dd04e1a4964dd311fb58e419b1d358eeb5386dd0e11a163df1c5874f84b97591c0a6e2f9fe65ff42
+  data.tar.gz: 2be5d5583bfc5735e010444a06e4b1d220dc12da470c498240a29c0ac9ed8ffeeec64cc249f06227787d53e9fdaff8ad02a01193569d54f0414ca707ecc3030b

data/.coveralls.yml

@@ -0,0 +1 @@
+service_name: travis-ci

data/.rspec

@@ -0,0 +1 @@
+--color --order rand --format documentation

data/.travis.yml

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

data/.yardopts

@@ -0,0 +1,3 @@
+--readme          README.md
+--title           "desk.rb Documentation"
+--no-private

data/Gemfile

@@ -0,0 +1,15 @@
+source 'https://rubygems.org'
+
+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/Guardfile

@@ -0,0 +1,5 @@
+guard 'rspec', :version => 2 do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+end

data/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2013 Thomas Stachl <tom@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:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,185 @@
+# desk.com APIv2 [![Build Status](https://secure.travis-ci.org/tstachl/desk.png)](http://travis-ci.org/tstachl/desk) [![Coverage Status](https://coveralls.io/repos/tstachl/desk/badge.png)](https://coveralls.io/r/tstachl/desk) [![Dependency Status](https://gemnasium.com/tstachl/desk.png)](https://gemnasium.com/tstachl/desk)
+
+desk.com has released v2 of their REST API a few months ago and provides a lot more functionality. You should read up on the current progress of the [API](http://dev.desk.com/API/changelog). This library wraps all of it into an easy to use ruby module. We'll try to keep up with the changes of the API but things might still break unexpectedly.
+
+## Example
+This example shows you how to create a new client and establish a connection to the API. It shows the four request methods supported by the desk.com API (`GET`, `POST`, `PATCH` and `DELETE`).
+
+```ruby
+client = Desk::Client.new username: 'thomas@example.com', password: 'somepassword', subdomain: 'devel'
+
+response = client.get '/api/v2/topics'
+response = client.post '/api/v2/topics', name: 'My new Topic', allow_questions: true
+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:
+
+```ruby
+Desk.configure do |config|
+  config.username = 'thomas@example.com'
+  config.password = 'somepassword'
+  config.subdomain = 'devel'
+end
+
+Desk.get '/api/v2/topics'
+Desk.post '/api/v2/topics', name: 'My new Topic', allow_questions: true
+Desk.patch '/api/v2/topics/1', name: 'Changed the Topic Name'
+Desk.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.
+
+### Finders
+```ruby
+# get the first user and find a case by url.
+found_case = Desk.users.first.by_url '/api/v2/cases/1'
+
+# find a case by case number
+found_case = Desk.cases.by_id 1
+```
+
+### Pagination
+
+As mentioned above you can also navigate between resources and mainly pages of collections.
+
+```ruby
+cases = Desk.cases
+cases.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|
+  # do something with the case
+end
+# go back to the previous page
+previous_page = next_page.previous_page
+# or go to the last page
+last_page = previous_page.last_page
+# or go to the first page
+first_page = last_page.first_page
+```
+
+### Links
+
+Pagination is pretty obvious but the cool part about pagination or rather resources is the auto-linking. As soon as the resource has a link defined, it'll be navigatable:
+
+```ruby
+# get the customer of the first case of the first page
+customer = Desk.cases.first.customer
+# who sent the first outbound reply of the first email
+user_name = Desk.cases.select{ |my_case| 
+              my_case.type == 'email'
+            }.first.replies.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 `Desk.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).
+
+```ruby
+Desk.cases.page(10).per_page(50).each do |my_case|
+  # in this method chain `.each' is the first method that acutally sends a request
+end
+
+# however if you request the current page numer and the resource is not loaded
+# it'll send a request
+Desk.cases.page == 1
+```
+
+### 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 `Desk::Error::MethodNotSupported` error. The specific method won't be defined on the resource either `Desk.cases.first.respond_to?(:delete) == false`.
+
+```ruby
+# let's create an article
+new_article = Desk.articles.create({
+                subject: 'Some Subject',
+                body: 'Some Body',
+                _links: {
+                  topic: Desk.topics.first.get_self
+                }
+              })
+
+# as you can see here a `Resource' always includes a method `.get_self'
+# which will return the link object to build relationships
+
+# updating the article
+updated_article = new_article.update subject: 'Updated Subject'
+
+# deleting the article
+if updated_article.delete == true
+  # article has been deleted
+end
+
+# ATTENTION: Cases can not be deleted!
+begin
+  Desk.cases.first.delete
+rescue Desk::Error::MethodNotSupported => 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.
+
+```ruby
+customer = Desk.customers.by_id(1)
+
+puts customer.first_name
+puts customer.last_name
+puts customer.title
+
+# for updates you can either use the setter or a hash
+
+customer.first_name = 'John'
+customer.last_name = 'Doe'
+
+updated_customer = customer.update title: 'Master of the Universe'
+
+# users are not updatable
+begin
+  user = Desk.users.first
+  user.name = 'Not updateable'
+rescue Desk::Error::MethodNotSupported
+  # too bad
+end
+```
+
+### API Errors
+
+Sometimes the API is going to return errors, eg. Validation Error. In these cases we wrap the API error into a `Desk::Error`. Here are the common errors:
+
+```ruby
+Desk::Error::BadRequest             #=> 400 Status
+Desk::Error::Unauthorized           #=> 401 Status
+Desk::Error::Forbidden              #=> 403 Status
+Desk::Error::NotFound               #=> 404 Status
+Desk::Error::MethodNotAllowed       #=> 405 Status
+Desk::Error::NotAcceptable          #=> 406 Status
+Desk::Error::Conflict               #=> 409 Status
+Desk::Error::UnsupportedMediaType   #=> 415 Status
+Desk::Error::UnprocessableEntity    #=> 422 Status
+Desk::Error::TooManyRequests        #=> 429 Status
+```
+
+Please also have a look at all [desk.com API errors](http://dev.desk.com/API/using-the-api/#status-codes) and their respective meanings.
+
+## License
+
+(The MIT License)
+
+Copyright (c) 2013 Thomas Stachl <tom@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:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,15 @@
+require 'rake'
+
+begin
+  require 'bundler/setup'
+  Bundler::GemHelper.install_tasks
+rescue
+  puts 'although not required, bundler is recommened for running the tests'
+end
+
+task default: :spec
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new do |t|
+  t.rspec_opts = ["--color", '--format doc']
+end

data/config.rb

@@ -0,0 +1,7 @@
+module Desk
+  CONFIG = {
+    username: 'tstachl@salesforce.com',
+    password: '253e6745',
+    subdomain: 'devel'
+  }
+end

data/desk_api.gemspec

@@ -0,0 +1,36 @@
+# -*- encoding: utf-8 -*-
+$LOAD_PATH.unshift File.expand_path("../lib", __FILE__)
+require 'desk/version'
+
+Gem::Specification.new do |gem|
+  gem.name              = 'desk_api'
+  gem.summary           = 'A lightweight, flexible wrapper for the desk.com REST API.'
+  gem.description       = 'This is a lightweight, flexible ruby gem to interact with the desk.com REST API. It allows to create, read and delete resources available through the API endpoints. It can be used either with OAuth or HTTP Basic Authentication.'
+  gem.homepage          = 'http://github.com/tstachl/desk.rb'
+  gem.version           = Desk::VERSION
+
+  gem.authors           = ['Thomas Stachl']
+  gem.email             = 'tom@desk.com'
+
+  gem.require_paths     = ['lib']
+  gem.files             = `git ls-files`.split("\n")
+  gem.test_files        = `git ls-files -- {test,spec,features}/*`.split("\n")
+  gem.executables       = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+
+  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('typhoeus')
+  gem.add_runtime_dependency('addressable')
+  gem.add_runtime_dependency('activesupport')
+  gem.add_runtime_dependency('hashie')
+
+  gem.add_development_dependency('rspec')
+  gem.add_development_dependency('rake')
+  gem.add_development_dependency('vcr')
+  gem.add_development_dependency('simplecov')
+  gem.add_development_dependency('coveralls')
+end

data/lib/desk/action/create.rb

@@ -0,0 +1,15 @@
+module Desk
+  module Action
+    module Create
+      module ClassMethods
+        def create(client, path, params)
+          self.new(client, client.post(path, params).body)
+        end
+      end
+
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+    end
+  end
+end

data/lib/desk/action/delete.rb

@@ -0,0 +1,9 @@
+module Desk
+  module Action
+    module Delete
+      def delete
+        client.delete(@_links.self.href).status === 204
+      end
+    end
+  end
+end

data/lib/desk/action/embedded.rb

@@ -0,0 +1,12 @@
+module Desk
+  module Action
+    module Embedded
+    protected
+      def setup_embedded(entries)
+        @records = entries.map do |record|
+          resource(record._links.self['class']).new(client, record, true)
+        end
+      end
+    end
+  end
+end

data/lib/desk/action/field.rb

@@ -0,0 +1,33 @@
+module Desk
+  module Action
+    module Field
+    protected
+      # Handles the _links part of the HAL response and sets up the associations.
+      # It is used by the client to setup the initial resources like `users`, `cases` and
+      # so on, as well as by the resource object itself for sub resources (`cases.replies`).
+      #
+      # @api private
+      def setup_fields(definition)
+        definition.each_pair do |key, value|
+          next if key[0] == '_'
+          # set the instance variable
+          instance_variable_set(:"@#{key}", value)
+          # create getter
+          (class << self; self; end).send(:define_method, "#{key}") do
+            return @_changed[key] if kind_of?(Desk::Action::Update) and @_changed[key]
+            instance_variable_get(:"@#{key}")
+          end
+          # create setter
+          if kind_of?(Desk::Action::Update)
+            (class << self; self; end).send(:define_method, "#{key}=") do |value|
+              if instance_variable_get(:"@#{key}") != value
+                @_changed[key] = value
+              end
+              self
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/desk/action/link.rb

@@ -0,0 +1,29 @@
+module Desk
+  module Action
+    module Link
+    protected
+      attr_accessor :_links
+      # Handles the _links part of the HAL response and sets up the associations.
+      # It is used by the client to setup the initial resources like `users`, `cases` and
+      # so on, as well as by the resource object itself for sub resources (`cases.replies`).
+      #
+      # @api private
+      def setup_links(links)
+        @_links = links
+        @_links.each_pair do |method, definition|
+          (class << self; self; end).send(:define_method, ['first', 'last', 'next', 'previous'].include?(method) ? "#{method}_page" : method) do
+            return nil unless definition
+            # return the stored resource if we already loaded it
+            return @_links[method]['resource'] if @_links[method].key?('resource')
+            # this is a really ugly hack but necessary for sub resources which aren't declared consistently
+            definition['class'] = 'page' if method.pluralize == method
+            # get the client
+            client = self.instance_of?(Desk::Client) ? self : self.client
+            # create the new resource
+            @_links[method]['resource'] = resource(definition['class']).new client, Hashie::Mash.new({ _links: { self: definition } })
+          end
+        end
+      end
+    end
+  end
+end

data/lib/desk/action/resource.rb

@@ -0,0 +1,14 @@
+module Desk
+  module Action
+    module Resource
+    protected
+      def resource(name)
+        require "desk/resource/#{name}"
+        "Desk::Resource::#{name.classify}".constantize
+      rescue NameError
+      rescue LoadError
+        Desk::Resource
+      end
+    end
+  end
+end

data/lib/desk/action/search.rb

@@ -0,0 +1,15 @@
+module Desk
+  module Action
+    module Search
+      module ClassMethods
+        def search(client, path)
+          client.send(:resource, 'page').new(client, Hashie::Mash.new({ _links: { self: { href: path }}}))
+        end
+      end
+
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+    end
+  end
+end

data/lib/desk/action/update.rb

@@ -0,0 +1,12 @@
+module Desk
+  module Action
+    module Update
+      def update(params)
+        params.each_pair do |key, value|
+          send("#{key}=", value) if respond_to?("#{key}=")
+        end
+        setup(client.patch(@_links.self.href, @_changed).body)
+      end
+    end
+  end
+end

data/lib/desk/client.rb

@@ -0,0 +1,67 @@
+require 'faraday'
+
+require 'desk/configuration'
+require 'desk/action/link'
+require 'desk/action/resource'
+require 'desk/error/client_error'
+require 'desk/error/parse_error'
+
+require 'desk/resource'
+
+module Desk
+  class Client
+    include Desk::Configuration
+    include Desk::Action::Link
+    include Desk::Action::Resource
+
+    # Initializes a new Client object
+    #
+    # @param options [Hash]
+    # @return [Desk::Client]
+    def initialize(options = {})
+      Desk::Configuration.keys.each do |key|
+        instance_variable_set(:"@#{key}", options[key] || Desk.instance_variable_get(:"@#{key}"))
+      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 DELETE request
+    def delete(path, params = {})
+      request(:delete, path, params)
+    end
+
+    # Perform an HTTP GET request
+    def get(path, params = {})
+      request(:get, path, params)
+    end
+
+    # Perform an HTTP POST request
+    def post(path, params = {})
+      request(:post, path, params)
+    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 Desk::Error::ClientError
+    rescue JSON::ParserError
+      raise Desk::Error::ParserError
+    end
+
+    def connection
+      @connection ||= Faraday.new endpoint, connection_options, &middleware
+    end
+  end
+end

data/lib/desk/configuration.rb

@@ -0,0 +1,132 @@
+require 'faraday'
+require 'faraday_middleware'
+
+require 'typhoeus'
+require 'typhoeus/adapters/faraday'
+
+require 'desk/default'
+require 'desk/request/retry'
+require 'desk/response/raise_error'
+require 'desk/error/configuration_error'
+require 'desk/error/client_error'
+require 'desk/error/server_error'
+
+module Desk
+  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
+    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 :basic_auth, @username, @password if basic_auth.values.all?
+        builder.request :oauth, oauth if oauth.values.all?
+        builder.request :json
+        builder.request :retry
+
+        builder.response :mashify
+        builder.response :dates
+        builder.response :raise_error, Desk::Error::ClientError
+        builder.response :raise_error, Desk::Error::ServerError
+        builder.response :json, content_type: /application\/json/
+
+        builder.adapter :typhoeus
+      end
+    end
+
+    def configure
+      yield self
+      validate_credentials!
+      validate_endpoint!
+      self
+    end
+
+    def reset!
+      Desk::Configuration.keys.each do |key|
+        send("#{key}=", Desk::Default.options[key])
+      end
+      self
+    end
+    alias setup reset!
+
+    def credentials?
+      oauth.values.all? || basic_auth.values.all?
+    end
+
+  private
+    # @return [Hash]
+    def options
+      Hash[Desk::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 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
+
+      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
+        end
+      end
+
+      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
+        end
+      end
+    end
+
+    def validate_endpoint!
+      unless endpoint =~ /^#{URI::regexp}$/
+        raise(Error::ConfigurationError, "Invalid endpoint specified: `#{endpoint}` must be a valid url.")
+      end
+    end
+  end
+end