desk 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (74) hide show
  1. data/.gemtest +0 -0
  2. data/.gitignore +11 -0
  3. data/.rspec +3 -0
  4. data/.yardopts +9 -0
  5. data/Gemfile +12 -0
  6. data/HISTORY.mkd +44 -0
  7. data/LICENSE.mkd +20 -0
  8. data/README.mkd +267 -0
  9. data/Rakefile +23 -0
  10. data/desk.gemspec +44 -0
  11. data/lib/desk.rb +26 -0
  12. data/lib/desk/api.rb +28 -0
  13. data/lib/desk/authentication.rb +25 -0
  14. data/lib/desk/client.rb +28 -0
  15. data/lib/desk/client/article.rb +92 -0
  16. data/lib/desk/client/case.rb +55 -0
  17. data/lib/desk/client/customer.rb +146 -0
  18. data/lib/desk/client/interaction.rb +75 -0
  19. data/lib/desk/client/macro.rb +142 -0
  20. data/lib/desk/client/topic.rb +90 -0
  21. data/lib/desk/client/user.rb +38 -0
  22. data/lib/desk/configuration.rb +98 -0
  23. data/lib/desk/connection.rb +39 -0
  24. data/lib/desk/error.rb +67 -0
  25. data/lib/desk/request.rb +44 -0
  26. data/lib/desk/version.rb +4 -0
  27. data/lib/faraday/request/multipart_with_file.rb +30 -0
  28. data/lib/faraday/request/oauth.rb +23 -0
  29. data/lib/faraday/response/raise_http_4xx.rb +45 -0
  30. data/lib/faraday/response/raise_http_5xx.rb +24 -0
  31. data/spec/desk/api_spec.rb +70 -0
  32. data/spec/desk/client/article_spec.rb +134 -0
  33. data/spec/desk/client/case_spec.rb +99 -0
  34. data/spec/desk/client/customer_spec.rb +158 -0
  35. data/spec/desk/client/interaction_spec.rb +191 -0
  36. data/spec/desk/client/macro_spec.rb +204 -0
  37. data/spec/desk/client/topic_spec.rb +135 -0
  38. data/spec/desk/client/user_spec.rb +58 -0
  39. data/spec/desk/client_spec.rb +10 -0
  40. data/spec/desk_spec.rb +127 -0
  41. data/spec/faraday/response_spec.rb +34 -0
  42. data/spec/fixtures/article.json +50 -0
  43. data/spec/fixtures/article_create.json +54 -0
  44. data/spec/fixtures/article_destroy.json +3 -0
  45. data/spec/fixtures/article_update.json +54 -0
  46. data/spec/fixtures/articles.json +58 -0
  47. data/spec/fixtures/case.json +59 -0
  48. data/spec/fixtures/case_update.json +59 -0
  49. data/spec/fixtures/cases.json +182 -0
  50. data/spec/fixtures/customer.json +58 -0
  51. data/spec/fixtures/customer_create.json +56 -0
  52. data/spec/fixtures/customer_create_email.json +15 -0
  53. data/spec/fixtures/customer_update.json +47 -0
  54. data/spec/fixtures/customer_update_email.json +15 -0
  55. data/spec/fixtures/customers.json +98 -0
  56. data/spec/fixtures/interaction_create.json +126 -0
  57. data/spec/fixtures/interactions.json +139 -0
  58. data/spec/fixtures/macro.json +8 -0
  59. data/spec/fixtures/macro_action.json +9 -0
  60. data/spec/fixtures/macro_action_update.json +12 -0
  61. data/spec/fixtures/macro_actions.json +69 -0
  62. data/spec/fixtures/macro_create.json +13 -0
  63. data/spec/fixtures/macro_destroy.json +3 -0
  64. data/spec/fixtures/macro_update.json +13 -0
  65. data/spec/fixtures/macros.json +24 -0
  66. data/spec/fixtures/topic.json +9 -0
  67. data/spec/fixtures/topic_create.json +14 -0
  68. data/spec/fixtures/topic_destroy.json +3 -0
  69. data/spec/fixtures/topic_update.json +14 -0
  70. data/spec/fixtures/topics.json +35 -0
  71. data/spec/fixtures/user.json +15 -0
  72. data/spec/fixtures/users.json +24 -0
  73. data/spec/helper.rb +55 -0
  74. metadata +464 -0
@@ -0,0 +1,142 @@
1
+ module Desk
2
+ class Client
3
+ # Defines methods related to macros
4
+ module Macro
5
+ # Returns extended information of macros
6
+ #
7
+ # @option options [Boolean, String, Integer]
8
+ # @example Return extended information for 12345
9
+ # Desk.macros
10
+ # Desk.macros(:count => 5)
11
+ # Desk.macros(:count => 5, :page => 3)
12
+ # @format :json
13
+ # @authenticated true
14
+ # @see http://dev.desk.com/docs/api/macros
15
+ def macros(*args)
16
+ options = args.last.is_a?(Hash) ? args.pop : {}
17
+ response = get("macros",options)
18
+ response
19
+ end
20
+
21
+ # Returns extended information on a single macro
22
+ #
23
+ # @param id [Integer] a macro ID
24
+ # @option options [Hash]
25
+ # @example Return extended information for 12345
26
+ # Desk.macro(12345)
27
+ # @format :json
28
+ # @authenticated true
29
+ # @see http://dev.desk.com/docs/api/macros/show
30
+ def macro(id)
31
+ response = get("macros/#{id}")
32
+ response.macro
33
+ end
34
+
35
+ # Creates a new macro
36
+ #
37
+ # @param name [String] A macro name
38
+ # @option options [Hash]
39
+ # @example Creates a new macro
40
+ # Desk.create_macro("name")
41
+ # Desk.create_macro("name")
42
+ # @format :json
43
+ # @authenticated true
44
+ # @see http://dev.desk.com/docs/api/macros/create
45
+ def create_macro(name, *args)
46
+ options = args.last.is_a?(Hash) ? args.pop : {}
47
+ response = post("macros",options)
48
+ if response['success']
49
+ return response['results']['macro']
50
+ else
51
+ return response
52
+ end
53
+ end
54
+
55
+ # Updates a single macro
56
+ #
57
+ # @param id [Integer] a macro ID
58
+ # @option options [String]
59
+ # @example Updates information for macro 12345
60
+ # Desk.update_macro(12345, :subject => "New Subject")
61
+ # @format :json
62
+ # @authenticated true
63
+ # @see http://dev.desk.com/docs/api/macros/update
64
+ def update_macro(id, *args)
65
+ options = args.last.is_a?(Hash) ? args.pop : {}
66
+ response = put("macros/#{id}",options)
67
+ if response['success']
68
+ return response['results']['macro']
69
+ else
70
+ return response
71
+ end
72
+ end
73
+
74
+ # Deletes a single macro
75
+ #
76
+ # @param id [Integer] a macro ID
77
+ # @example Deletes macro 12345
78
+ # Desk.update_macro(12345, :subject => "New Subject")
79
+ # @format :json
80
+ # @authenticated true
81
+ # @see http://dev.desk.com/docs/api/macros/update
82
+ def delete_macro(id)
83
+ response = delete("macros/#{id}")
84
+ response
85
+ end
86
+
87
+ ##########
88
+ # Macro Actions
89
+ ##########
90
+
91
+ # Returns extended information of macros
92
+ #
93
+ # @option options [Boolean, String, Integer]
94
+ # @example Return extended information for 12345
95
+ # Desk.macro_actions(1)
96
+ # Desk.macro_actions(1, :count => 5)
97
+ # Desk.macro_actions(1, :count => 5, :page => 3)
98
+ # @format :json
99
+ # @authenticated true
100
+ # @see http://dev.desk.com/docs/api/macros/actions
101
+ def macro_actions(id, *args)
102
+ options = args.last.is_a?(Hash) ? args.pop : {}
103
+ response = get("macros/#{id}/actions",options)
104
+ response['results']
105
+ end
106
+
107
+ # Returns extended information on a single macro
108
+ #
109
+ # @param id [Integer] a macro ID
110
+ # @option options [Hash]
111
+ # @example Return extended information for 12345
112
+ # Desk.macro_action(12345, "set-case-description")
113
+ # @format :json
114
+ # @authenticated true
115
+ # @see http://dev.desk.com/docs/api/macros/actions/show
116
+ def macro_action(id, slug)
117
+ response = get("macros/#{id}/actions/#{slug}")
118
+ response['action']
119
+ end
120
+
121
+ # Updates a single macro action
122
+ #
123
+ # @param id [Integer] a macro ID
124
+ # @option options [String]
125
+ # @example Updates information for macro 12345
126
+ # Desk.update_macro_action(12345, "set-case-description", :value => "New Subject")
127
+ # @format :json
128
+ # @authenticated true
129
+ # @see http://dev.desk.com/docs/api/macros/actions/update
130
+ def update_macro_action(id, slug, *args)
131
+ options = args.last.is_a?(Hash) ? args.pop : {}
132
+ response = put("macros/#{id}/actions/#{slug}",options)
133
+ if response['success']
134
+ return response['results']['action']
135
+ else
136
+ return response
137
+ end
138
+ end
139
+
140
+ end
141
+ end
142
+ end
@@ -0,0 +1,90 @@
1
+ module Desk
2
+ class Client
3
+ # Defines methods related to topics
4
+ module Topic
5
+ # Returns extended information of topics
6
+ #
7
+ # @option options [Boolean, String, Integer]
8
+ # @example Return extended information for 12345
9
+ # Desk.topics
10
+ # Desk.topics(:count => 5)
11
+ # Desk.topics(:count => 5, :page => 3)
12
+ # @format :json
13
+ # @authenticated true
14
+ # @see http://dev.desk.com/docs/api/topics/show
15
+ def topics(*args)
16
+ options = args.last.is_a?(Hash) ? args.pop : {}
17
+ response = get("topics",options)
18
+ response
19
+ end
20
+
21
+ # Returns extended information on a single topic
22
+ #
23
+ # @param id [Integer] a topic ID
24
+ # @option options [Hash]
25
+ # @example Return extended information for 12345
26
+ # Desk.topic(12345)
27
+ # Desk.topic(12345, :by => "external_id")
28
+ # @format :json
29
+ # @authenticated true
30
+ # @see http://dev.desk.com/docs/api/topics/show
31
+ def topic(id, *args)
32
+ options = args.last.is_a?(Hash) ? args.pop : {}
33
+ response = get("topics/#{id}",options)
34
+ response.topic
35
+ end
36
+
37
+ # Creates a new topic
38
+ #
39
+ # @param name [String] A topic name
40
+ # @option options [Hash]
41
+ # @example Creates a new topic
42
+ # Desk.create_topic("name")
43
+ # Desk.create_topic("name", :description => "description")
44
+ # @format :json
45
+ # @authenticated true
46
+ # @see http://dev.desk.com/docs/api/topics/create
47
+ def create_topic(name, *args)
48
+ options = args.last.is_a?(Hash) ? args.pop : {}
49
+ response = post("topics",options)
50
+ if response['success']
51
+ return response['results']['topic']
52
+ else
53
+ return response
54
+ end
55
+ end
56
+
57
+ # Updates a single topic
58
+ #
59
+ # @param id [Integer] a topic ID
60
+ # @option options [String]
61
+ # @example Updates information for topic 12345
62
+ # Desk.update_topic(12345, :subject => "New Subject")
63
+ # @format :json
64
+ # @authenticated true
65
+ # @see http://dev.desk.com/docs/api/topics/update
66
+ def update_topic(id, *args)
67
+ options = args.last.is_a?(Hash) ? args.pop : {}
68
+ response = put("topics/#{id}",options)
69
+ if response['success']
70
+ return response['results']['topic']
71
+ else
72
+ return response
73
+ end
74
+ end
75
+
76
+ # Deletes a single topic
77
+ #
78
+ # @param id [Integer] a topic ID
79
+ # @example Deletes topic 12345
80
+ # Desk.update_topic(12345, :subject => "New Subject")
81
+ # @format :json
82
+ # @authenticated true
83
+ # @see http://dev.desk.com/docs/api/topics/update
84
+ def delete_topic(id)
85
+ response = delete("topics/#{id}")
86
+ response
87
+ end
88
+ end
89
+ end
90
+ end
@@ -0,0 +1,38 @@
1
+ module Desk
2
+ class Client
3
+ # Defines methods related to users
4
+ module User
5
+ # Returns extended information of a given user
6
+ #
7
+ # @overload user(user, options={})
8
+ # @param user [Integer] An Assitely user ID
9
+ # @option options [Boolean, String, Integer] :include_entities Include {http://dev.twitter.com/pages/tweet_entities Tweet Entities} when set to true, 't' or 1.
10
+ # @return [Hashie::Mash] The requested user.
11
+ # @example Return extended information for 12345
12
+ # Desk.user(12345)
13
+ # @format :json, :xml
14
+ # @authenticated true
15
+ # @see http://dev.desk.com/docs/api/users/show
16
+ def user(id,*args)
17
+ options = args.last.is_a?(Hash) ? args.pop : {}
18
+ response = get("users/#{id}",options)
19
+ response.user
20
+ end
21
+
22
+ # Returns extended information for up to 100 users
23
+ #
24
+ # @format :json, :xml
25
+ # @authenticated true
26
+ # @rate_limited true
27
+ # @return [Array] The requested users.
28
+ # @see http://dev.desk.com/docs/api/users
29
+ # @example Return extended information account users
30
+ # Desk.users
31
+ def users(*args)
32
+ options = args.last.is_a?(Hash) ? args.pop : {}
33
+ response = get('users', options)
34
+ response
35
+ end
36
+ end
37
+ end
38
+ end
@@ -0,0 +1,98 @@
1
+ require 'faraday'
2
+ require 'desk/version'
3
+
4
+ module Desk
5
+ # Defines constants and methods related to configuration
6
+ module Configuration
7
+ # An array of valid keys in the options hash when configuring a {Twitter::API}
8
+ VALID_OPTIONS_KEYS = [
9
+ :adapter,
10
+ :consumer_key,
11
+ :consumer_secret,
12
+ :format,
13
+ :oauth_token,
14
+ :oauth_token_secret,
15
+ :proxy,
16
+ :subdomain,
17
+ :support_email,
18
+ :user_agent,
19
+ :version].freeze
20
+
21
+ # An array of valid request/response formats
22
+ #
23
+ # @note Not all methods support the XML format.
24
+ VALID_FORMATS = [
25
+ :json].freeze
26
+
27
+ # The adapter that will be used to connect if none is set
28
+ #
29
+ # @note The default faraday adapter is Net::HTTP.
30
+ DEFAULT_ADAPTER = Faraday.default_adapter
31
+
32
+ # By default, don't set an application key
33
+ DEFAULT_CONSUMER_KEY = nil
34
+
35
+ # By default, don't set an application secret
36
+ DEFAULT_CONSUMER_SECRET = nil
37
+
38
+ # The response format appended to the path and sent in the 'Accept' header if none is set
39
+ #
40
+ # @note JSON is preferred over XML because it is more concise and faster to parse.
41
+ DEFAULT_FORMAT = :json
42
+
43
+ # By default, don't set a user oauth token
44
+ DEFAULT_OAUTH_TOKEN = nil
45
+
46
+ # By default, don't set a user oauth secret
47
+ DEFAULT_OAUTH_TOKEN_SECRET = nil
48
+
49
+ # By default, don't use a proxy server
50
+ DEFAULT_PROXY = nil
51
+
52
+ # By default use example
53
+ DEFAULT_SUBDOMAIN = "example"
54
+
55
+ # The user agent that will be sent to the API endpoint if none is set
56
+ DEFAULT_USER_AGENT = "Desk.com Ruby Gem #{Desk::VERSION}".freeze
57
+
58
+ # The user agent that will be sent to the API endpoint if none is set
59
+ DEFAULT_VERSION = "v1".freeze
60
+
61
+ # By default, don't set a support email address
62
+ DEFAULT_SUPPORT_EMAIL = nil
63
+
64
+ # @private
65
+ attr_accessor *VALID_OPTIONS_KEYS
66
+
67
+ # When this module is extended, set all configuration options to their default values
68
+ def self.extended(base)
69
+ base.reset
70
+ end
71
+
72
+ # Convenience method to allow configuration options to be set in a block
73
+ def configure
74
+ yield self
75
+ end
76
+
77
+ # Create a hash of options and their values
78
+ def options
79
+ Hash[VALID_OPTIONS_KEYS.map {|key| [key, send(key)] }]
80
+ end
81
+
82
+ # Reset all configuration options to defaults
83
+ def reset
84
+ self.adapter = DEFAULT_ADAPTER
85
+ self.consumer_key = DEFAULT_CONSUMER_KEY
86
+ self.consumer_secret = DEFAULT_CONSUMER_SECRET
87
+ self.format = DEFAULT_FORMAT
88
+ self.oauth_token = DEFAULT_OAUTH_TOKEN
89
+ self.oauth_token_secret = DEFAULT_OAUTH_TOKEN_SECRET
90
+ self.proxy = DEFAULT_PROXY
91
+ self.subdomain = DEFAULT_SUBDOMAIN
92
+ self.support_email = DEFAULT_SUPPORT_EMAIL
93
+ self.user_agent = DEFAULT_USER_AGENT
94
+ self.version = DEFAULT_VERSION
95
+ self
96
+ end
97
+ end
98
+ end
@@ -0,0 +1,39 @@
1
+ require 'faraday_middleware'
2
+ require 'faraday/request/multipart_with_file'
3
+ require 'faraday/response/raise_http_4xx'
4
+ require 'faraday/response/raise_http_5xx'
5
+
6
+ module Desk
7
+ # @private
8
+ module Connection
9
+ private
10
+
11
+ def connection(raw=false)
12
+ options = {
13
+ :headers => {'Accept' => "application/#{format}", 'User-Agent' => user_agent},
14
+ :proxy => proxy,
15
+ :ssl => {:verify => false},
16
+ :url => api_endpoint,
17
+ }
18
+
19
+ Faraday.new(options) do |builder|
20
+ builder.use Faraday::Request::MultipartWithFile
21
+ builder.use Faraday::Request::OAuth, authentication if authenticated?
22
+ builder.use Faraday::Request::Multipart
23
+ builder.use Faraday::Request::UrlEncoded
24
+ builder.use Faraday::Response::RaiseHttp4xx
25
+ builder.use Faraday::Response::Rashify unless raw
26
+ unless raw
27
+ case format.to_s.downcase
28
+ when 'json'
29
+ builder.use Faraday::Response::ParseJson
30
+ when 'xml'
31
+ builder.use Faraday::Response::ParseXml
32
+ end
33
+ end
34
+ builder.use Faraday::Response::RaiseHttp5xx
35
+ builder.adapter(adapter)
36
+ end
37
+ end
38
+ end
39
+ end
data/lib/desk/error.rb ADDED
@@ -0,0 +1,67 @@
1
+ module Desk
2
+ # Custom error class for rescuing from all Desk.com errors
3
+ class Error < StandardError
4
+ attr_reader :http_headers
5
+
6
+ def initialize(message, http_headers)
7
+ http_headers ||= {}
8
+ @http_headers = Hash[http_headers]
9
+ super message
10
+ end
11
+
12
+ def ratelimit_reset
13
+ Time.at(@http_headers.values_at('x-ratelimit-reset', 'X-RateLimit-Reset').detect {|value| value }.to_i)
14
+ end
15
+
16
+ def ratelimit_limit
17
+ @http_headers.values_at('x-ratelimit-limit', 'X-RateLimit-Limit').detect {|value| value }.to_i
18
+ end
19
+
20
+ def ratelimit_remaining
21
+ @http_headers.values_at('x-ratelimit-limit', 'X-RateLimit-Limit').detect {|value| value }.to_i
22
+ end
23
+
24
+ def retry_after
25
+ [(ratelimit_reset - Time.now).ceil, 0].max
26
+ end
27
+ end
28
+
29
+ # Raised when Desk returns the HTTP status code 400
30
+ class BadRequest < Error; end
31
+
32
+ # Raised when Desk returns the HTTP status code 401
33
+ class Unauthorized < Error; end
34
+
35
+ # Raised when Desk returns the HTTP status code 403
36
+ class Forbidden < Error; end
37
+
38
+ # Raised when Desk returns the HTTP status code 404
39
+ class NotFound < Error; end
40
+
41
+ # Raised when Desk returns the HTTP status code 406
42
+ class NotAcceptable < Error; end
43
+
44
+ # Raised when Desk returns the HTTP status code 420
45
+ class EnhanceYourCalm < Error
46
+ # The number of seconds your application should wait before requesting date from the Search API again
47
+ #
48
+ # @see http://dev.desk.com/pages/rate-limiting
49
+ def retry_after
50
+ @http_headers.values_at('retry-after', 'Retry-After').detect {|value| value }.to_i
51
+ end
52
+ end
53
+
54
+ # Raised when Desk returns the HTTP status code 500
55
+ class InternalServerError < Error; end
56
+
57
+ # Raised when Desk returns the HTTP status code 502
58
+ class BadGateway < Error; end
59
+
60
+ # Raised when Desk returns the HTTP status code 503
61
+ class ServiceUnavailable < Error; end
62
+
63
+ # Gem Specific Errors
64
+ class DeskError < StandardError; end
65
+
66
+ class SupportEmailNotSet < DeskError; end
67
+ end