desk_api 0.6.1 → 0.6.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 418fce5029af0f83478582714488c4b29717deb2
-  data.tar.gz: 8be391f681e41a896d49ac74b64daa20878aacbc
+  metadata.gz: 7cef419cb4804c1a1d30d99063b5f3bba9e3d552
+  data.tar.gz: 67d6895e8a527ac9be61d64271bc65756e856fe1
 SHA512:
-  metadata.gz: bfd58a478541754852d65f8f66508354c51b9250fd26f77e157818905f592c4fa3ba654dcf58be463ed038e3037ffd5a244a613927e21b078d716fe5818260d8
-  data.tar.gz: 865c292b84e95f563311ba8dd3bd4dc8b73c60fca0bcc7319ffe6bd69db612b90438e4f50107227428d2ce3c7c30552e3d52a694e7918072d712e7045cfca6dc
+  metadata.gz: 81d57dd47f416ddb525e88aec774a323990dd3ac195cd825d5513ba69c35e76ddba6fdd453f7b7b9f223aea8d8acea9f04b0a9d0c8f1f9e12fc3507b30785fb0
+  data.tar.gz: 4ce97b7989cc00c14c29b4e0ae3b79a1d9d348069f6d5b336efa5ebc7eb3b78115c1405d24d6daf32cc302945b3eee58221949047a9d6b005222b31df15fee88

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2013-2014, Salesforce.com, Inc.
+Copyright (c) 2013-2016, Salesforce.com, Inc.
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without modification,

data/README.md

@@ -1,10 +1,10 @@
-# DeskApi a client for APIv2
-## An Awesomely (Un)official Desk API Client
+# DeskApi a client for API v2
+## An official Desk API Client
 
 DeskApi takes the capabilities of the Desk.com API and wraps them up in a Ruby
 client so that it's easy-as-pie to get working with your support site's API.
 
-Desk publishes a changelog monthly, which you can keep up with at
+Desk.com publishes a change log monthly, which you can keep up with at
 [dev.desk.com/API/changelog](http://dev.desk.com/API/changelog).
 
 We do our best to keep DeskApi, but please don't hesitate to open an
@@ -25,7 +25,7 @@ gem install desk_api
 
 #### Authentication Mechanism
 
-The desk.com API allows you to access data using two authentication mechanisms:
+The Desk.com API allows you to access data using two authentication mechanisms:
 
 ##### Basic Authentication
 
@@ -185,7 +185,7 @@ updated_customer = customer.update title: 'Master of the Universe'
 # users are not updatable
 begin
   user = DeskApi.users.first
-  user.update name: 'Not updateable'
+  user.update name: 'Not updatable'
 rescue DeskApi::Error::MethodNotAllowed
   # too bad
 end
@@ -193,7 +193,7 @@ end
 
 ### Find
 
-The method `by_url` can be called on the client, for backwards compatability we
+The method `by_url` can be called on the client, for backwards compatibility we
 haven't yet removed it from the `DeskApi::Resource` but it will be removed once
 we release v1 of this client. `by_url` will return a lazy loaded instance of the
 resource.
@@ -345,7 +345,7 @@ DeskApi.cases.page(10).per_page(50).entries.each do |my_case|
   # in this method chain, no HTTP request is fired until `.entries'
 end
 
-# however if you request the current page numer and the resource is not loaded
+# however if you request the current page number and the resource is not loaded
 # it'll send a request
 DeskApi.cases.page == 1
 ```
@@ -394,6 +394,24 @@ assigned_user = my_case.assigned_user
 assigned_group = my_case.assigned_group
 ```
 
+### Downloading Attachments
+
+Attachment resources can be downloaded directly, a `Tempfile` is returned that can either be read or moved to the final location.
+
+```ruby
+ticket     = DeskApi.cases.find(123)
+attachment = ticket.attachments.entries.first
+file       = attachment.download
+
+# Read the file
+content    = file.read
+
+# Save the file
+File.open('/path/to/my/storage', 'w') do |f|
+  f.write(content)
+end
+```
+
 ### API Errors
 
 Sometimes the API is going to return errors, eg. Validation Error. In these
@@ -418,7 +436,7 @@ their respective meanings.
 
 ## License
 
-Copyright (c) 2013-2014, Salesforce.com, Inc.
+Copyright (c) 2013-2016, Salesforce.com, Inc.
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without modification,

data/lib/desk.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2013-2014, Salesforce.com, Inc.
+# Copyright (c) 2013-2016, Salesforce.com, Inc.
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without modification,

data/lib/desk_api.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2013-2014, Salesforce.com, Inc.
+# Copyright (c) 2013-2016, Salesforce.com, Inc.
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without modification,
@@ -29,7 +29,6 @@
 require 'uri'
 require 'faraday'
 require 'forwardable'
-require 'addressable/uri'
 
 # {DeskApi} allows for easy interaction with Desk.com's API.
 # It is the top level namespace and delegates all missing
@@ -38,7 +37,7 @@ require 'addressable/uri'
 # if you have to connect to multiple Desk.com sites.
 #
 # @author    Thomas Stachl <tstachl@salesforce.com>
-# @copyright Copyright (c) 2013-2014 Salesforce.com
+# @copyright Copyright (c) 2013-2016 Salesforce.com
 # @license   BSD 3-Clause License
 #
 # @example configure the {DeskApi} client

data/lib/desk_api/client.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2013-2014, Salesforce.com, Inc.
+# Copyright (c) 2013-2016, Salesforce.com, Inc.
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without modification,
@@ -36,7 +36,7 @@ module DeskApi
   # the configuration module.
   #
   # @author    Thomas Stachl <tstachl@salesforce.com>
-  # @copyright Copyright (c) 2013-2014 Salesforce.com
+  # @copyright Copyright (c) 2013-2016 Salesforce.com
   # @license   BSD 3-Clause License
   class Client
     include DeskApi::Configuration
@@ -103,10 +103,10 @@ module DeskApi
     # @raises [DeskApi::Error::ParserError]
     def request(method, path, params = {}, &block)
       connection.send(method, path, params, &block)
-    rescue Faraday::Error::ClientError
-      raise DeskApi::Error::ClientError
-    rescue JSON::ParserError
-      raise DeskApi::Error::ParserError
+    rescue Faraday::Error::ClientError => err
+      raise DeskApi::Error::ClientError.new(err)
+    rescue JSON::ParserError => err
+      raise DeskApi::Error::ParserError.new(err)
     end
 
     # Builds and/or returns the Faraday client.

data/lib/desk_api/configuration.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2013-2014, Salesforce.com, Inc.
+# Copyright (c) 2013-2016, Salesforce.com, Inc.
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without modification,
@@ -32,6 +32,7 @@ require 'desk_api/default'
 require 'desk_api/request/retry'
 require 'desk_api/request/oauth'
 require 'desk_api/request/encode_json'
+require 'desk_api/request/encode_dates'
 require 'desk_api/response/parse_dates'
 require 'desk_api/response/parse_json'
 require 'desk_api/response/raise_error'
@@ -46,7 +47,7 @@ module DeskApi
   # makes sure secrets are only readable by the client.
   #
   # @author    Thomas Stachl <tstachl@salesforce.com>
-  # @copyright Copyright (c) 2013-2014 Salesforce.com
+  # @copyright Copyright (c) 2013-2016 Salesforce.com
   # @license   BSD 3-Clause License
   module Configuration
     extend Forwardable
@@ -84,6 +85,7 @@ module DeskApi
 
       # Registers the middleware when the module is included.
       def included(_base)
+        register_middleware :request, :desk_encode_dates, :EncodeDates
         register_middleware :request, :desk_encode_json, :EncodeJson
         register_middleware :request, :desk_oauth, :OAuth
         register_middleware :request, :desk_retry, :Retry
@@ -106,6 +108,7 @@ module DeskApi
     # @return [Proc]
     def middleware
       @middleware ||= proc do |builder|
+        builder.request(:desk_encode_dates)
         builder.request(:desk_encode_json)
         builder.request(*authorize_request)
         builder.request(:desk_retry)

data/lib/desk_api/default.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2013-2014, Salesforce.com, Inc.
+# Copyright (c) 2013-2016, Salesforce.com, Inc.
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without modification,
@@ -31,7 +31,7 @@ module DeskApi
   # {DeskApi::Client}.
   #
   # @author    Thomas Stachl <tstachl@salesforce.com>
-  # @copyright Copyright (c) 2013-2014 Salesforce.com
+  # @copyright Copyright (c) 2013-2016 Salesforce.com
   # @license   BSD 3-Clause License
   module Default
     CONNECTION_OPTIONS = {

data/lib/desk_api/error.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2013-2014, Salesforce.com, Inc.
+# Copyright (c) 2013-2016, Salesforce.com, Inc.
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without modification,
@@ -32,7 +32,7 @@ module DeskApi
   # {DeskApi::Error} is the base error for all {DeskApi} errors.
   #
   # @author    Thomas Stachl <tstachl@salesforce.com>
-  # @copyright Copyright (c) 2013-2014 Salesforce.com
+  # @copyright Copyright (c) 2013-2016 Salesforce.com
   # @license   BSD 3-Clause License
   class Error < StandardError
     attr_reader :rate_limit

data/lib/desk_api/error/bad_gateway.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2013-2014, Salesforce.com, Inc.
+# Copyright (c) 2013-2016, Salesforce.com, Inc.
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without modification,

data/lib/desk_api/error/bad_request.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2013-2014, Salesforce.com, Inc.
+# Copyright (c) 2013-2016, Salesforce.com, Inc.
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without modification,

data/lib/desk_api/error/client_error.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2013-2014, Salesforce.com, Inc.
+# Copyright (c) 2013-2016, Salesforce.com, Inc.
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without modification,

data/lib/desk_api/error/configuration_error.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2013-2014, Salesforce.com, Inc.
+# Copyright (c) 2013-2016, Salesforce.com, Inc.
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without modification,

data/lib/desk_api/error/conflict.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2013-2014, Salesforce.com, Inc.
+# Copyright (c) 2013-2016, Salesforce.com, Inc.
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without modification,

data/lib/desk_api/error/follow_redirect_error.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2013-2014, Salesforce.com, Inc.
+# Copyright (c) 2013-2016, Salesforce.com, Inc.
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without modification,

data/lib/desk_api/error/forbidden.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2013-2014, Salesforce.com, Inc.
+# Copyright (c) 2013-2016, Salesforce.com, Inc.
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without modification,

data/lib/desk_api/error/gateway_timeout.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2013-2014, Salesforce.com, Inc.
+# Copyright (c) 2013-2016, Salesforce.com, Inc.
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without modification,

data/lib/desk_api/error/internal_server_error.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2013-2014, Salesforce.com, Inc.
+# Copyright (c) 2013-2016, Salesforce.com, Inc.
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without modification,

data/lib/desk_api/error/method_not_allowed.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2013-2014, Salesforce.com, Inc.
+# Copyright (c) 2013-2016, Salesforce.com, Inc.
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without modification,

data/lib/desk_api/error/not_acceptable.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2013-2014, Salesforce.com, Inc.
+# Copyright (c) 2013-2016, Salesforce.com, Inc.
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without modification,

data/lib/desk_api/error/not_found.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2013-2014, Salesforce.com, Inc.
+# Copyright (c) 2013-2016, Salesforce.com, Inc.
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without modification,

data/lib/desk_api/error/parser_error.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2013-2014, Salesforce.com, Inc.
+# Copyright (c) 2013-2016, Salesforce.com, Inc.
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without modification,

data/lib/desk_api/error/server_error.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2013-2014, Salesforce.com, Inc.
+# Copyright (c) 2013-2016, Salesforce.com, Inc.
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without modification,

data/lib/desk_api/error/service_unavailable.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2013-2014, Salesforce.com, Inc.
+# Copyright (c) 2013-2016, Salesforce.com, Inc.
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without modification,

data/lib/desk_api/error/too_many_requests.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2013-2014, Salesforce.com, Inc.
+# Copyright (c) 2013-2016, Salesforce.com, Inc.
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without modification,

data/lib/desk_api/error/unauthorized.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2013-2014, Salesforce.com, Inc.
+# Copyright (c) 2013-2016, Salesforce.com, Inc.
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without modification,

data/lib/desk_api/error/unprocessable_entity.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2013-2014, Salesforce.com, Inc.
+# Copyright (c) 2013-2016, Salesforce.com, Inc.
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without modification,

data/lib/desk_api/error/unsupported_media_type.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2013-2014, Salesforce.com, Inc.
+# Copyright (c) 2013-2016, Salesforce.com, Inc.
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without modification,

data/lib/desk_api/rate_limit.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2013-2014, Salesforce.com, Inc.
+# Copyright (c) 2013-2016, Salesforce.com, Inc.
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without modification,
@@ -31,7 +31,7 @@ module DeskApi
   # responses from desk.com API.
   #
   # @author    Thomas Stachl <tstachl@salesforce.com>
-  # @copyright Copyright (c) 2013-2014 Salesforce.com
+  # @copyright Copyright (c) 2013-2016 Salesforce.com
   # @license   BSD 3-Clause License
   class RateLimit
     def initialize(attrs = {})

data/lib/desk_api/request/encode_dates.rb

@@ -0,0 +1,73 @@
+# Copyright (c) 2013-2016, Salesforce.com, Inc.
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without modification,
+# are permitted provided that the following conditions are met:
+#
+#   * Redistributions of source code must retain the above copyright notice, this
+#     list of conditions and the following disclaimer.
+#
+#   * Redistributions in binary form must reproduce the above copyright notice,
+#     this list of conditions and the following disclaimer in the documentation
+#     and/or other materials provided with the distribution.
+#
+#   * Neither the name of Salesforce.com nor the names of its contributors may be
+#     used to endorse or promote products derived from this software without
+#     specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+# ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+# ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+module DeskApi
+  module Request
+    # {DeskApi::Request::EncodeJson} is the Faraday middleware
+    # that dumps a json string from whatever is specified in
+    # the request body. It also sets the "Content-Type" header.
+    #
+    # @author    Thomas Stachl <tstachl@salesforce.com>
+    # @copyright Copyright (c) 2013-2016 Salesforce.com
+    # @license   BSD 3-Clause License
+    class EncodeDates < Faraday::Middleware
+      # Changes the request before it gets sent
+      #
+      # @param env [Hash] the request hash
+      def call(env)
+        if env[:body] && !env[:body].to_s.empty?
+          env[:body] = encode_dates(env[:body])
+        end
+        @app.call env
+      end
+
+      private
+
+      # Encodes all {Date}, {DateTime} and {Time} values
+      # to iso8601
+      #
+      # @param value [Mixed] the current body
+      def encode_dates(value)
+        case value
+        when Hash
+          value.each_pair do |key, element|
+            value[key] = encode_dates element
+          end
+        when Array
+          value.each_with_index do |element, index|
+            value[index] = encode_dates element
+          end
+        when DateTime, Date, Time
+          value.to_time.utc.iso8601
+        else
+          value
+        end
+      end
+    end
+  end
+end