smartsheet 1.0.0 → 1.1.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 (70) hide show
  1. checksums.yaml +4 -4
  2. data/.gitignore +11 -11
  3. data/.rubocop.yml +4 -4
  4. data/.travis.yml +13 -6
  5. data/.yardopts +3 -3
  6. data/CHANGELOG.md +103 -0
  7. data/Gemfile +6 -6
  8. data/LICENSE +202 -202
  9. data/README.md +214 -141
  10. data/Rakefile +29 -23
  11. data/bin/console +14 -14
  12. data/bin/setup +8 -8
  13. data/lib/smartsheet.rb +2 -2
  14. data/lib/smartsheet/api/body_builder.rb +25 -25
  15. data/lib/smartsheet/api/endpoint_spec.rb +54 -36
  16. data/lib/smartsheet/api/faraday_adapter/faraday_net_client.rb +45 -42
  17. data/lib/smartsheet/api/faraday_adapter/faraday_response.rb +70 -70
  18. data/lib/smartsheet/api/faraday_adapter/middleware/faraday_error_translator.rb +20 -20
  19. data/lib/smartsheet/api/faraday_adapter/middleware/response_parser.rb +25 -25
  20. data/lib/smartsheet/api/file_spec.rb +31 -31
  21. data/lib/smartsheet/api/header_builder.rb +90 -84
  22. data/lib/smartsheet/api/request.rb +42 -29
  23. data/lib/smartsheet/api/request_client.rb +43 -27
  24. data/lib/smartsheet/api/request_logger.rb +182 -182
  25. data/lib/smartsheet/api/request_spec.rb +57 -44
  26. data/lib/smartsheet/api/response_net_client_decorator.rb +54 -54
  27. data/lib/smartsheet/api/retry_logic.rb +40 -40
  28. data/lib/smartsheet/api/retry_net_client_decorator.rb +37 -37
  29. data/lib/smartsheet/api/url_builder.rb +25 -25
  30. data/lib/smartsheet/client.rb +191 -185
  31. data/lib/smartsheet/constants.rb +15 -15
  32. data/lib/smartsheet/endpoints/contacts/contacts.rb +30 -30
  33. data/lib/smartsheet/endpoints/favorites/favorites.rb +159 -159
  34. data/lib/smartsheet/endpoints/folders/folders.rb +125 -125
  35. data/lib/smartsheet/endpoints/groups/groups.rb +83 -83
  36. data/lib/smartsheet/endpoints/home/home.rb +20 -20
  37. data/lib/smartsheet/endpoints/reports/reports.rb +100 -100
  38. data/lib/smartsheet/endpoints/reports/reports_share.rb +69 -69
  39. data/lib/smartsheet/endpoints/search/search.rb +30 -30
  40. data/lib/smartsheet/endpoints/server_info/server_info.rb +21 -21
  41. data/lib/smartsheet/endpoints/share/share.rb +58 -58
  42. data/lib/smartsheet/endpoints/sheets/automation_rules.rb +56 -0
  43. data/lib/smartsheet/endpoints/sheets/cells.rb +82 -82
  44. data/lib/smartsheet/endpoints/sheets/columns.rb +66 -66
  45. data/lib/smartsheet/endpoints/sheets/comments.rb +64 -64
  46. data/lib/smartsheet/endpoints/sheets/comments_attachments.rb +78 -78
  47. data/lib/smartsheet/endpoints/sheets/cross_sheet_references.rb +45 -0
  48. data/lib/smartsheet/endpoints/sheets/discussions.rb +84 -84
  49. data/lib/smartsheet/endpoints/sheets/discussions_attachments.rb +22 -22
  50. data/lib/smartsheet/endpoints/sheets/rows.rb +106 -95
  51. data/lib/smartsheet/endpoints/sheets/rows_attachments.rb +92 -92
  52. data/lib/smartsheet/endpoints/sheets/sheets.rb +326 -317
  53. data/lib/smartsheet/endpoints/sheets/sheets_attachments.rb +174 -174
  54. data/lib/smartsheet/endpoints/sheets/sheets_share.rb +69 -69
  55. data/lib/smartsheet/endpoints/sights/sights.rb +101 -101
  56. data/lib/smartsheet/endpoints/sights/sights_share.rb +69 -69
  57. data/lib/smartsheet/endpoints/templates/templates.rb +29 -29
  58. data/lib/smartsheet/endpoints/token/token.rb +65 -60
  59. data/lib/smartsheet/endpoints/update_requests/sent_update_requests.rb +44 -44
  60. data/lib/smartsheet/endpoints/update_requests/update_requests.rb +74 -74
  61. data/lib/smartsheet/endpoints/users/alternate_emails.rb +79 -79
  62. data/lib/smartsheet/endpoints/users/users.rb +77 -77
  63. data/lib/smartsheet/endpoints/webhooks/webhooks.rb +71 -71
  64. data/lib/smartsheet/endpoints/workspaces/workspaces.rb +87 -87
  65. data/lib/smartsheet/endpoints/workspaces/workspaces_share.rb +70 -70
  66. data/lib/smartsheet/error.rb +69 -69
  67. data/lib/smartsheet/general_request.rb +74 -74
  68. data/lib/smartsheet/version.rb +5 -5
  69. data/smartsheet.gemspec +54 -52
  70. metadata +34 -3
data/README.md CHANGED
@@ -1,141 +1,214 @@
1
- # Smartsheet Ruby SDK [![Build Status](https://travis-ci.org/smartsheet-platform/smartsheet-ruby-sdk.svg?branch=master)](https://travis-ci.org/smartsheet-platform/smartsheet-ruby-sdk) [![Coverage Status](https://coveralls.io/repos/github/smartsheet-platform/smartsheet-ruby-sdk/badge.svg?branch=master)](https://coveralls.io/github/smartsheet-platform/smartsheet-ruby-sdk?branch=master) [![Gem Version](https://badge.fury.io/rb/smartsheet.svg)](https://badge.fury.io/rb/smartsheet)
2
-
3
- This is an SDK to simplify connecting to the [Smartsheet API](http://www.smartsheet.com/developers/api-documentation) from Ruby applications.
4
-
5
- ## System Requirements
6
-
7
- The SDK supports Ruby versions 2.2 or later.
8
-
9
- ## Installation
10
-
11
- Add this line to your application's Gemfile:
12
-
13
- ```ruby
14
- gem 'smartsheet', '>= 1.0.0'
15
- ```
16
-
17
- And then execute:
18
-
19
- $ bundle
20
-
21
- Or install it yourself as:
22
-
23
- $ gem install smartsheet --pre
24
-
25
- ## Documentation
26
-
27
- The Smartsheet API documentation with corresponding SDK example code can be found [here](http://www.smartsheet.com/developers/api-documentation).
28
-
29
- ## Example Usage
30
-
31
- To call the API, you must have an access token, which looks something like this example: ll352u9jujauoqz4gstvsae05. You can find the access token in the UI at Account > Personal Settings > API Access.
32
-
33
- The following is a brief sample that shows you how to:
34
-
35
- * Initialize the client
36
- * List all sheets
37
- * Load one sheet
38
-
39
- ```ruby
40
- require 'smartsheet'
41
-
42
- # Initialize the client
43
- smartsheet_client = Smartsheet::Client.new(token: 'll352u9jujauoqz4gstvsae05')
44
-
45
- # The `smartsheet_client` variable now contains access to all of the APIs
46
-
47
- begin
48
- # List all sheets
49
- sheets = smartsheet_client.sheets.list
50
-
51
- # Default to first sheet
52
- sheet_id = sheets[:data][0][:id]
53
-
54
- # Load the entire sheet
55
- puts smartsheet_client.sheets.get(sheet_id: sheet_id)
56
- rescue Smartsheet::ApiError => e
57
- puts "Error Code: #{e.error_code}"
58
- puts "Message: #{e.message}"
59
- puts "Ref Id: #{e.ref_id}"
60
- end
61
- ```
62
-
63
- See the [read-write-sheet](https://github.com/smartsheet-samples/ruby-read-write-sheet) example to see a more robust use case in action.
64
-
65
- ## Basic Configuration
66
-
67
- When creating the client object, pass an object with any of the following properties to tune its behavior.
68
-
69
- * `max_retry_time` - The maximum time in seconds to retry intermittent errors. (Defaults to 15 seconds.)
70
-
71
- ## Advanced Configuration Options
72
- ### Logging Configuration
73
-
74
- Smartsheet expects a standard Ruby logger. For example, to enable console logging of warnings and above, make a call such as the following:
75
-
76
- ```ruby
77
- logger = Logger.new(STDOUT)
78
- logger.level = Logger::WARN
79
- smartsheet = Smartsheet::Client.new(logger: logger)
80
- ```
81
-
82
- Supported log levels are as follows:
83
-
84
- |Level |What is logged |
85
- |---------------|---------------------------------|
86
- |`Logger::ERROR`|Failures only |
87
- |`Logger::WARN` |Failures and retries |
88
- |`Logger::INFO` |Each call's URL and response code|
89
- |`Logger::DEBUG`|Full headers and payloads |
90
-
91
- By default, payloads are truncated to 1024 characters. To display full payloads, pass the `log_full_body` named flag to the `Smartsheet::Client` with the value true:
92
-
93
- ```ruby
94
- smartsheet = Smartsheet::Client.new(logger: logger, log_full_body: true)
95
- ```
96
-
97
- ### Retry Configuration
98
-
99
- For additional customization, you can specify a `backoff_method` function. This function is called with two arguments:
100
-
101
- * The first accepts the index of the retry being attempted (0 for the first retry, 1 for the second, etc.)
102
- * The second accepts the Error Object that caused the retry.
103
-
104
- The function must return the number of seconds to wait before making the subsequent retry call, or the symbol `:stop` if no more retries should be made.
105
-
106
- The default implementation performs exponential backoff with jitter.
107
-
108
- ### JSON Output
109
-
110
- * `json_output` - A flag indicating if data should be returned as a JSON string. Defaults to Hash output when not specified.
111
-
112
- ### Assume User
113
-
114
- * `assume_user` - Allows an admin to act on behalf of, or impersonate, the user to make API calls. The email address should NOT be URI encoded.
115
-
116
- ## Development
117
-
118
- After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests, with code coverage provided automatically by the Coveralls gem. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
119
-
120
- To install this gem onto your local machine, run `bundle exec rake install`.
121
-
122
- ## Contributing
123
-
124
- If you would like to contribute a change to the SDK, please fork a branch and then submit a pull request.
125
- [More info here.](https://help.github.com/articles/using-pull-requests)
126
-
127
- ## Support
128
-
129
- If you have any questions or issues with this SDK please post on [Stack Overflow using the tag "smartsheet-api"](http://stackoverflow.com/questions/tagged/smartsheet-api) or contact us directly at api@smartsheet.com.
130
-
131
- ## Release Notes
132
-
133
- Each specific release is available for download via [GitHub](https://github.com/smartsheet-platform/smartsheet-ruby-sdk/tags).
134
-
135
- **v1.0.0 (Nov 2017)**
136
- Full release
137
-
138
- **v1.0.0.beta (October 2017)**
139
- Beta release of the Smartsheet SDK for Ruby
140
-
141
- *Note*: Minor changes that result in a patch version increment in RubyGems (such as updates to the README) will not be tagged as a Release in GitHub.
1
+ # Smartsheet Ruby SDK [![Build Status](https://travis-ci.org/smartsheet-platform/smartsheet-ruby-sdk.svg?branch=master)](https://travis-ci.org/smartsheet-platform/smartsheet-ruby-sdk) [![Coverage Status](https://coveralls.io/repos/github/smartsheet-platform/smartsheet-ruby-sdk/badge.svg?branch=master)](https://coveralls.io/github/smartsheet-platform/smartsheet-ruby-sdk?branch=master) [![Gem Version](https://badge.fury.io/rb/smartsheet.svg)](https://badge.fury.io/rb/smartsheet)
2
+
3
+ This is an SDK to simplify connecting to the [Smartsheet API](http://www.smartsheet.com/developers/api-documentation) from Ruby applications.
4
+
5
+ ## System Requirements
6
+
7
+ The SDK supports Ruby versions 2.2 or later.
8
+
9
+ ## Installation
10
+
11
+ Add this line to your application's Gemfile:
12
+
13
+ ```ruby
14
+ gem 'smartsheet', '>= 1.0.0'
15
+ ```
16
+
17
+ And then execute:
18
+
19
+ $ bundle
20
+
21
+ Or install it yourself as:
22
+
23
+ $ gem install smartsheet
24
+
25
+ ## Documentation
26
+
27
+ The Smartsheet API documentation with corresponding SDK example code can be found [here](http://www.smartsheet.com/developers/api-documentation).
28
+
29
+ The generated SDK RubyDoc is available [here](http://www.rubydoc.info/gems/smartsheet/Smartsheet).
30
+
31
+ ## Example Usage
32
+
33
+ To call the API, you must have an access token, which looks something like this example: `ll352u9jujauoqz4gstvsae05`. You can find the access token in the UI at Account > Personal Settings > API Access.
34
+
35
+ The following is a brief sample that shows you how to:
36
+
37
+ * Initialize the client
38
+ * List all sheets
39
+ * Load one sheet
40
+
41
+ ```ruby
42
+ require 'smartsheet'
43
+
44
+ # Initialize the client - use your access token here
45
+ smartsheet_client = Smartsheet::Client.new(token: 'll352u9jujauoqz4gstvsae05')
46
+ # The `smartsheet_client` variable now contains access to all of the APIs
47
+
48
+ begin
49
+ # List all sheets
50
+ sheets = smartsheet_client.sheets.list
51
+
52
+ # Select first sheet
53
+ sheet_id = sheets[:data][0][:id]
54
+
55
+ # Load the entire sheet
56
+ puts "Loading sheet id #{sheet_id}"
57
+ sheet = smartsheet_client.sheets.get(sheet_id: sheet_id)
58
+ puts "Loaded #{sheet[:total_row_count]} rows from sheet '#{sheet[:name]}'"
59
+
60
+ rescue Smartsheet::ApiError => e
61
+ puts "Error Code: #{e.error_code}"
62
+ puts "Message: #{e.message}"
63
+ puts "Ref Id: #{e.ref_id}"
64
+ end
65
+ ```
66
+
67
+ See the [read-write-sheet](https://github.com/smartsheet-samples/ruby-read-write-sheet) example to see a more robust use case in action.
68
+
69
+ ## Basic Configuration
70
+
71
+ When creating the client object, pass an object with any of the following properties to tune its behavior.
72
+
73
+ * `token` - Your smartsheet API access token. If you omit this property (or pass an empty string) then the access token will be read from the system environment variable `SMARTSHEET_ACCESS_TOKEN`.
74
+
75
+ * `max_retry_time` - The maximum time in seconds to retry intermittent errors. (Defaults to 15 seconds.)
76
+
77
+ * `base_url` - By default, the SDK connects to the production API URL. Provide a custom base URL to connect to other environments.
78
+
79
+ ## Advanced Configuration Options
80
+ ### Logging Configuration
81
+
82
+ Smartsheet expects a standard Ruby logger. For example, to enable console logging of warnings and above, make a call such as the following:
83
+
84
+ ```ruby
85
+ logger = Logger.new(STDOUT)
86
+ logger.level = Logger::INFO
87
+ smartsheet = Smartsheet::Client.new(logger: logger)
88
+ ```
89
+
90
+ Supported log levels are as follows:
91
+
92
+ |Level |What is logged |
93
+ |---------------|---------------------------------|
94
+ |`Logger::ERROR`|Failures only |
95
+ |`Logger::WARN` |Failures and retries |
96
+ |`Logger::INFO` |Each call's URL and response code|
97
+ |`Logger::DEBUG`|Full headers and payloads |
98
+
99
+ By default, payloads are truncated to 1024 characters. To display full payloads, pass the `log_full_body` named flag to the `Smartsheet::Client` with the value true:
100
+
101
+ ```ruby
102
+ smartsheet = Smartsheet::Client.new(logger: logger, log_full_body: true)
103
+ ```
104
+
105
+ ### Retry Configuration
106
+
107
+ For additional customization, you can specify a `backoff_method` function. This function is called with two arguments:
108
+
109
+ * The first accepts the index of the retry being attempted (0 for the first retry, 1 for the second, etc.)
110
+ * The second accepts the Error Object that caused the retry.
111
+
112
+ The function must return the number of seconds to wait before making the subsequent retry call, or the symbol `:stop` if no more retries should be made.
113
+
114
+ The default implementation performs exponential backoff with jitter.
115
+
116
+ ### JSON Input and Output
117
+ * `json_output` - A flag indicating if data should be returned as a JSON string.
118
+
119
+ By default, the Ruby SDK converts the raw JSON API response (with camelCase properties) to a Ruby hash with snake_case properties. If you prefer to receive results as the original JSON string, initialize the client with `json_output: true`.
120
+
121
+ Regardless of this setting, the SDK will accept `body` parameters as a hash or JSON, and in either camelCase or snake_case.
122
+
123
+ ### Assume User
124
+
125
+ * `assume_user` - Allows an admin to act on behalf of, or impersonate, the user to make API calls. The email address should NOT be URI encoded.
126
+
127
+ ### User Agent
128
+
129
+ * `user_agent` - A custom app name to add to the user agent header; this helps Smartsheet diagnose any issues you may have while using the SDK.
130
+
131
+ ## Development
132
+
133
+ After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
134
+
135
+ To install this gem onto your local machine, run `bundle exec rake install`.
136
+
137
+ ### Running the Tests
138
+ #### All
139
+ 1. Run `rake test`. Note, the mock API tests will fail unless the mock server is running. See [Mock API Tests](#mock-api-tests)
140
+
141
+ #### Unit Tests
142
+ 1. Run `rake test:units`
143
+
144
+ #### Mock API Tests
145
+ 1. Clone the [Smartsheet SDK tests](https://github.com/smartsheet-platform/smartsheet-sdk-tests) repo and follow the instructions from the README to start the mock server
146
+ 2. Run `rake test:mock_api`
147
+
148
+ ## Passthrough Option
149
+
150
+ If there is an API Feature that is not yet supported by the Ruby SDK, there is a passthrough option that allows you to call arbitrary API endpoints.
151
+
152
+ To invoke the passthrough, your code can call one of the following three methods:
153
+
154
+ `response = smartsheet.request(method:, url_path:, body:, params:, header_overrides:)`
155
+
156
+ `response = smartsheet.request_with_file(method:, url_path:, file:, file_length:, filename:, content_type:, params:, header_overrides:)`
157
+
158
+ `response = smartsheet.request_with_file_from_path(method:, url_path:, path:, filename:, content_type:, params:, header_overrides:)`
159
+
160
+ * `method`: The method to invoke, one of `:get`, `:post`, `:put`, or `:delete`
161
+ * `url_path`: The specific API endpoint you wish to invoke. The client object base URL gets prepended to the caller’s endpoint URL argument. For example, passing a `url_path` of `sheets/1` to a standard client would give a URL like `https://api.smartsheet.com/2.0/sheets/1`
162
+ * `body`: An optional hash of data to be passed as a JSON request body
163
+ * `file`: An opened `File` object to read as the request body, generally for file attachment endpoints
164
+ * `path`: The path of a file to be read as the request body, generally for file attachment endpoints
165
+ * `file_length`: The length of a file body in octets
166
+ * `filename`: The name of a file body
167
+ * `content_type`: The MIME type of a file body
168
+ * `params`: An optional hash of query parameters
169
+ * `header_overrides`: An optional hash of HTTP header overrides
170
+
171
+ All calls to passthrough methods return a JSON result, converted to a hash using symbol keys, in the same manner as the rest of the SDK. For example, after a `PUT` operation, the API's result message could be contained in `response[:message]`. If you prefer raw JSON instead of a hash, create a client with `json_output` configured; see client documentation above for more info.
172
+
173
+ ### Passthrough Example
174
+
175
+ The following example shows how to POST data to `https://api.smartsheet.com/2.0/sheets` using the passthrough method and a hash:
176
+
177
+ ```ruby
178
+ payload = {
179
+ name: 'my new sheet',
180
+ columns: [
181
+ {
182
+ title: 'Favorite',
183
+ type: 'CHECKBOX',
184
+ symbol: 'STAR'
185
+ },
186
+ {
187
+ title: 'Primary Column',
188
+ primary: true,
189
+ type: 'TEXT_NUMBER'
190
+ }
191
+ ]
192
+ }
193
+
194
+ response = smartsheet.request(
195
+ method: :post,
196
+ url_path: 'sheets',
197
+ body: payload
198
+ )
199
+ ```
200
+
201
+ ## Contributing
202
+
203
+ If you would like to contribute a change to the SDK, please fork a branch and then submit a pull request.
204
+ [More info here.](https://help.github.com/articles/using-pull-requests)
205
+
206
+ ## Support
207
+
208
+ If you have any questions or issues with this SDK please post on [Stack Overflow using the tag "smartsheet-api"](http://stackoverflow.com/questions/tagged/smartsheet-api) or contact us directly at api@smartsheet.com.
209
+
210
+ ## Release Notes
211
+
212
+ Each specific release is available for download via [GitHub](https://github.com/smartsheet-platform/smartsheet-ruby-sdk/tags). Detailed release notes are available in [CHANGELOG.md].
213
+
214
+ *Note*: Minor changes that result in a patch version increment in RubyGems (such as updates to the README) will not be tagged as a Release in GitHub.
data/Rakefile CHANGED
@@ -1,23 +1,29 @@
1
- require 'bundler/gem_tasks'
2
- require 'rake/testtask'
3
- require 'rubycritic/rake_task'
4
-
5
-
6
- Rake::TestTask.new do |t|
7
- t.libs << 'test'
8
- t.libs << 'lib'
9
- t.test_files = FileList['test/**/*_test.rb']
10
- end
11
-
12
- namespace :test do
13
- Rake::TestTask.new(:units) do |t|
14
- t.libs << 'test'
15
- t.pattern = 'test/unit/**/*_test.rb'
16
- t.verbose = true
17
- end
18
- end
19
-
20
-
21
- RubyCritic::RakeTask.new
22
-
23
- task default: :test
1
+ require 'bundler/gem_tasks'
2
+ require 'rake/testtask'
3
+ require 'rubycritic/rake_task'
4
+
5
+
6
+ Rake::TestTask.new do |t|
7
+ t.libs << 'test'
8
+ t.libs << 'lib'
9
+ t.test_files = FileList['test/**/*_test.rb']
10
+ end
11
+
12
+ namespace :test do
13
+ Rake::TestTask.new(:units) do |t|
14
+ t.libs << 'test'
15
+ t.pattern = 'test/unit/**/*_test.rb'
16
+ t.verbose = true
17
+ end
18
+
19
+ Rake::TestTask.new(:mock_api) do |t|
20
+ t.libs << 'test'
21
+ t.pattern = 'test/mock_api/**/*_test.rb'
22
+ t.verbose = true
23
+ end
24
+ end
25
+
26
+
27
+ RubyCritic::RakeTask.new
28
+
29
+ task default: :'test:units'
@@ -1,14 +1,14 @@
1
- #!/usr/bin/env ruby
2
-
3
- require 'bundler/setup'
4
- require 'smartsheet/client'
5
-
6
- # You can add fixtures and/or initialization code here to make experimenting
7
- # with your gem easier. You can also use a different console, if you like.
8
-
9
- # (If you use this, don't forget to add pry to your Gemfile!)
10
- # require "pry"
11
- # Pry.start
12
-
13
- require 'irb'
14
- IRB.start(__FILE__)
1
+ #!/usr/bin/env ruby
2
+
3
+ require 'bundler/setup'
4
+ require 'smartsheet/client'
5
+
6
+ # You can add fixtures and/or initialization code here to make experimenting
7
+ # with your gem easier. You can also use a different console, if you like.
8
+
9
+ # (If you use this, don't forget to add pry to your Gemfile!)
10
+ # require "pry"
11
+ # Pry.start
12
+
13
+ require 'irb'
14
+ IRB.start(__FILE__)
data/bin/setup CHANGED
@@ -1,8 +1,8 @@
1
- #!/usr/bin/env bash
2
- set -euo pipefail
3
- IFS=$'\n\t'
4
- set -vx
5
-
6
- bundle install
7
-
8
- # Do any other automated setup that you need to do here
1
+ #!/usr/bin/env bash
2
+ set -euo pipefail
3
+ IFS=$'\n\t'
4
+ set -vx
5
+
6
+ bundle install
7
+
8
+ # Do any other automated setup that you need to do here