ruby-box-updated 1.16.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.
checksums.yaml ADDED
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA1:
3
+ metadata.gz: 314ae7c359945bf35355e3497ffa67f7ab4871c6
4
+ data.tar.gz: f946edf10b08080be31c00c90d41fb6b2d214c68
5
+ SHA512:
6
+ metadata.gz: 04f12b40f55fc76b0648e4d25482b421ea9636d2099dec5d96ae3fb2f7297d1d4c003abe20d4719952acdc803a1727c352b2f20bc11709164e8b0802a0fb6a2c
7
+ data.tar.gz: 0b16650a853982248d2c5e4e5d3e0ffaf0e613a85aa33d7a4a83609885d055b9f679840c3f37f58d79eaf59eb695ff0c8385c39dbac62a3262484598ddbea69f
data/.document ADDED
@@ -0,0 +1,5 @@
1
+ lib/**/*.rb
2
+ bin/*
3
+ -
4
+ features/**/*.feature
5
+ LICENSE.txt
data/.travis.yml ADDED
@@ -0,0 +1,6 @@
1
+ language: ruby
2
+ rvm:
3
+ - 1.9.3
4
+ before_install:
5
+ - gem install bundler --pre
6
+ script: bundle exec rake spec
data/Gemfile ADDED
@@ -0,0 +1,13 @@
1
+ source "http://rubygems.org"
2
+
3
+ gem "multipart-post"
4
+ gem "oauth2"
5
+ gem "json"
6
+ gem "addressable"
7
+
8
+ group :development do
9
+ gem "rspec"
10
+ gem "bundler"
11
+ gem "jeweler"
12
+ gem "webmock"
13
+ end
data/Gemfile.lock ADDED
@@ -0,0 +1,69 @@
1
+ GEM
2
+ remote: http://rubygems.org/
3
+ specs:
4
+ addressable (2.2.8)
5
+ builder (3.2.2)
6
+ crack (0.3.1)
7
+ diff-lcs (1.1.3)
8
+ faraday (0.8.4)
9
+ multipart-post (~> 1.1)
10
+ git (1.2.8)
11
+ github_api (0.10.1)
12
+ addressable
13
+ faraday (~> 0.8.1)
14
+ hashie (>= 1.2)
15
+ multi_json (~> 1.4)
16
+ nokogiri (~> 1.5.2)
17
+ oauth2
18
+ hashie (3.3.1)
19
+ highline (1.6.21)
20
+ httpauth (0.2.0)
21
+ jeweler (1.8.8)
22
+ builder
23
+ bundler (~> 1.0)
24
+ git (>= 1.2.5)
25
+ github_api (= 0.10.1)
26
+ highline (>= 1.6.15)
27
+ nokogiri (= 1.5.10)
28
+ rake
29
+ rdoc
30
+ json (1.7.7)
31
+ jwt (0.1.5)
32
+ multi_json (>= 1.0)
33
+ multi_json (1.6.0)
34
+ multipart-post (1.1.5)
35
+ nokogiri (1.5.10)
36
+ oauth2 (0.8.0)
37
+ faraday (~> 0.8)
38
+ httpauth (~> 0.1)
39
+ jwt (~> 0.1.4)
40
+ multi_json (~> 1.0)
41
+ rack (~> 1.2)
42
+ rack (1.4.5)
43
+ rake (10.3.2)
44
+ rdoc (4.1.2)
45
+ json (~> 1.4)
46
+ rspec (2.10.0)
47
+ rspec-core (~> 2.10.0)
48
+ rspec-expectations (~> 2.10.0)
49
+ rspec-mocks (~> 2.10.0)
50
+ rspec-core (2.10.0)
51
+ rspec-expectations (2.10.0)
52
+ diff-lcs (~> 1.1.3)
53
+ rspec-mocks (2.10.1)
54
+ webmock (1.8.7)
55
+ addressable (>= 2.2.7)
56
+ crack (>= 0.1.7)
57
+
58
+ PLATFORMS
59
+ ruby
60
+
61
+ DEPENDENCIES
62
+ addressable
63
+ bundler
64
+ jeweler
65
+ json
66
+ multipart-post
67
+ oauth2
68
+ rspec
69
+ webmock
data/LICENSE.txt ADDED
@@ -0,0 +1,20 @@
1
+ Copyright (c) 2013 Attachments.me
2
+
3
+ Permission is hereby granted, free of charge, to any person obtaining
4
+ a copy of this software and associated documentation files (the
5
+ "Software"), to deal in the Software without restriction, including
6
+ without limitation the rights to use, copy, modify, merge, publish,
7
+ distribute, sublicense, and/or sell copies of the Software, and to
8
+ permit persons to whom the Software is furnished to do so, subject to
9
+ the following conditions:
10
+
11
+ The above copyright notice and this permission notice shall be
12
+ included in all copies or substantial portions of the Software.
13
+
14
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
15
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
16
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
17
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
18
+ LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
19
+ OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
20
+ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
data/README.markdown ADDED
@@ -0,0 +1,356 @@
1
+ ruby-box
2
+ ========
3
+
4
+ Build Status: [![Build Status](https://travis-ci.org/attachmentsme/ruby-box.png)](https://travis-ci.org/attachmentsme/ruby-box)
5
+
6
+ Maintained by: [Adrien Giboire](http://adriengiboire.com)
7
+
8
+ RubyBox provides a simple, chainable, feature-rich client for [Box's 2.0 API](http://developers.box.com/docs/).
9
+
10
+ Authorization
11
+ -------------
12
+
13
+ RubyBox uses Box's OAuth2 Implementaton, Here are the steps involved in authorizing a client:
14
+
15
+ __1)__ Get the authorization url.
16
+
17
+ ```ruby
18
+ require 'ruby-box-updated'
19
+
20
+ session = RubyBox::Session.new({
21
+ client_id: 'your-client-id',
22
+ client_secret: 'your-client-secret'
23
+ })
24
+
25
+ authorize_url = session.authorize_url('https://redirect-url-in-app-settings')
26
+ ```
27
+
28
+ __2)__ After redirecting to the authorize_url, exchange the _code_ given for an _access\_token_
29
+
30
+ ```ruby
31
+ @token = session.get_access_token('code-returned-to-redirect_url')
32
+ p '@token.token' # the access token.
33
+ p '@token.refresh_token' # token that can be exchanged for a new access_token once the access_token expires.
34
+
35
+ # refreshing token.
36
+
37
+ session = RubyBox::Session.new({
38
+ client_id: 'your-client-id',
39
+ client_secret: 'your-client-secret',
40
+ access_token: 'original-access-token'
41
+ })
42
+
43
+ # you need to persist this somehow. the refresh token will change every time you use it
44
+ @token = session.refresh_token('your-refresh-token')
45
+ save_me_somehow(@token.refresh_token)
46
+ ```
47
+
48
+ __3)__ Create a client using a session initialized with the _access\_token_.
49
+
50
+ ```ruby
51
+ require 'ruby-box-updated'
52
+
53
+ session = RubyBox::Session.new({
54
+ client_id: 'your-client-id',
55
+ client_secret: 'your-client-secret',
56
+ access_token: 'access-token'
57
+ })
58
+
59
+ client = RubyBox::Client.new(session)
60
+ ```
61
+
62
+ Usage
63
+ =====
64
+
65
+ Once you've created a client, you can start interacting with the Box API. What follows are some basic examples of RubyBox's usage.
66
+
67
+ Warning
68
+ =======
69
+
70
+ Please note that using a file/folder path is extremely inefficient, as it causes the gem to traverse the directory structure recursively querying each folder in turn. Prefer the `_by_id` methods where possible for single-request access.
71
+
72
+ Items
73
+ -----
74
+
75
+ `File`s and `Folder`s are subclasses of `Item`. `Folder` contents (i.e. files and folders inside that folder) are retrieved in a `mini-format` when the `Folder` instance is loaded.
76
+
77
+ There are two caveats to this:
78
+
79
+ ### Only some fields are available
80
+
81
+ a `File` mini looks like this:
82
+
83
+ ```
84
+ {
85
+ "type": "file",
86
+ "id": "5000948880",
87
+ "sequence_id": "3",
88
+ "etag": "3",
89
+ "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc",
90
+ "name": "tigers.jpeg"
91
+ }
92
+ ```
93
+ a `Folder` mini looks like this:
94
+
95
+ ```
96
+ {
97
+ "type":"folder",
98
+ "id":"301415432",
99
+ "sequence_id":"0",
100
+ "name":"my first sub-folder"
101
+ }
102
+ ```
103
+
104
+ Requests to fields other than the above (e.g. `file.size`) will cause a one-off hit to the api, so take care when iterating over folder contents lest a single application method result in hundreds of api hits and take forever to complete.
105
+
106
+ This can be mitigated by passing a list of extra fields you want to fetch into the `.items` method:
107
+
108
+ ```ruby
109
+ folder = client.folder_by_id(@folder_id)
110
+ # retrieve size, created_at, and description for all items in this directory
111
+ detailed_items = folder.items(@item_limit, @offset, ['size', 'created_at', 'description'])
112
+ ```
113
+
114
+ Note: only the `type` and `id` fields are included in addition to whatever you specify using the above method, so you must be explicit.
115
+
116
+
117
+ Folders
118
+ -------
119
+
120
+ * Listing items in a folder:
121
+
122
+ ```ruby
123
+ files = client.folder('/image_folder').files # all files in a folder using a path.
124
+ files = client.folder(@folder_id).files # all files in a folder using an id.
125
+ folders = client.root_folder.folders # all folders in the root directory.
126
+ files_and_folders = client.folder('files').items # all files and folders in /files
127
+ ```
128
+
129
+ * Creating a folder:
130
+
131
+ ```ruby
132
+ client.folder_by_id(@folder_id).create_subfolder('subfolder') # using an id.
133
+ client.folder('image_folder').create_subfolder('subfolder') # using a path.
134
+ ```
135
+
136
+ * Setting the description on a folder:
137
+
138
+ ```ruby
139
+ folder = client.folder('image_folder') # using a path.
140
+ folder.description = 'Description on Folder'
141
+ folder.update
142
+ ```
143
+
144
+ * Listing the comments in a discussion surrounding a folder.
145
+
146
+ ```ruby
147
+ folder = client.folder('image_folder') # lookups by id are more efficient
148
+ discussion = folder.discussions.first
149
+ discussion.comments.each {|comment| p comment.message}
150
+ ```
151
+
152
+ * Creating a shared link for a folder.
153
+
154
+ ```ruby
155
+ folder = client.folder('image_folder').create_shared_link # lookups by id are more efficient
156
+ p folder.shared_link.url # https://www.box.com/s/d6de3224958c1755412
157
+ ```
158
+
159
+ * Creating an email to upload files in a folder.
160
+
161
+ ```ruby
162
+ folder = client.folder('documents_folder').create_folder_upload_email # lookups by id are more efficient
163
+ p folder.folder_upload_email.email # upload.adrien_.8kge3wck1h@u.box.com
164
+ ```
165
+
166
+ Files
167
+ -----
168
+
169
+ * Fetching a file's meta information.
170
+
171
+ ```ruby
172
+ file = client.file('/image_folder/an-image.jpg')# lookups by id are more efficient
173
+ file = client.file(@file_id)
174
+ p file.name
175
+ p file.created_at
176
+ ```
177
+
178
+ * Uploading a file to a folder.
179
+
180
+ ```ruby
181
+ file = client.upload_file('./LICENSE.txt', '/license_folder') # lookups by id are more efficient
182
+ file = client.upload_file_by_folder_id('./LICENSE.txt', @folder_id)
183
+ ```
184
+
185
+ * Downloading a file.
186
+
187
+ ```ruby
188
+ f = open('./LOCAL.txt', 'w+')
189
+ f.write( client.file('/license_folder/LICENSE.txt').download )
190
+ f.close()
191
+
192
+ # Or you can fetch by file.id, which is more efficient:
193
+ f = open('./LOCAL.txt', 'w+')
194
+ f.write( client.file_by_id(@file_id).download ) # lookups by id are more efficient
195
+ f.close()
196
+
197
+ # You can also grab the raw url with
198
+ client.file_by_id(@file_id).download_url
199
+
200
+ # Note that this URL is not persistent. Clients will need to follow the url immediately in order to
201
+ # actually download the file
202
+ ```
203
+
204
+ * Deleting a file.
205
+
206
+ ```ruby
207
+ client.file_by_id(@file_id).delete # this
208
+ client.file('/license_folder/LICENSE.txt').delete
209
+ ```
210
+
211
+ * Displaying comments on a file.
212
+
213
+ ```ruby
214
+ comments = client.file('/image_folder/an-image.jpg').comments # lookups by id are more efficient
215
+ comments = client.file_by_id(@file_id).comments
216
+
217
+ comments.each do |comment|
218
+ p comment.message
219
+ end
220
+ ```
221
+
222
+ * Creating a shared link for a file.
223
+
224
+ ```ruby
225
+ file = client.file('/image_folder/an-image.jpg').create_shared_link
226
+ file = client.file_by_id(@file_id).create_shared_link # using an id
227
+ p file.shared_link.url # https://www.box.com/s/d6de3224958c1755412
228
+ ```
229
+
230
+ * Copying a file to another folder.
231
+
232
+ ```ruby
233
+
234
+ file = client.file('/one_folder/cow_folder/an-image.jpg')
235
+ folder = client.folder('image_folder')
236
+
237
+ # lookups by id are more efficient
238
+
239
+ file = client.file_by_id(@file_id)
240
+ folder = client.folder_by_id(@folder_id)
241
+
242
+ file.copy_to(folder)
243
+ ```
244
+
245
+ * Moving a file to another folder.
246
+
247
+ ```ruby
248
+
249
+ file = client.file('/one_folder/cow_folder/an-image.jpg')
250
+ folder = client.folder('image_folder')
251
+
252
+ # lookups by id are more efficient
253
+
254
+ file = client.file_by_id(@file_id)
255
+ folder = client.folder_by_id(@folder_id)
256
+
257
+
258
+ file.move_to(folder)
259
+ ```
260
+
261
+ * Adding a comment to a file.
262
+
263
+ ```ruby
264
+ file = client.file('/image_folder/an-image.jpg') # path
265
+ file = client.file_by_id(@file_id) # id
266
+ comment = file.create_comment('Hello World!')
267
+ ```
268
+
269
+ Search
270
+ ------
271
+
272
+ You can use RubyBox's search method to return files and folders that match a given query.
273
+
274
+ ```ruby
275
+ items = client.search('image')
276
+ items.each do |item|
277
+ p "type=#{item.type} name=#{item.name}"
278
+ end
279
+ ```
280
+
281
+ Events
282
+ ------
283
+
284
+ You can use RubyBox's event_response method to return an EventResponse that can be used to process any incoming events.
285
+
286
+ ```ruby
287
+ eresp = client.event_response
288
+ eresp.chunk_size
289
+ eresp.next_stream_position
290
+ eresp.events.each do |ev|
291
+ p "type=#{ev.event_id} type=#{ev.event_type} user=#{ev.created_by.name}"
292
+ end
293
+ ```
294
+
295
+ As-User
296
+ -------
297
+
298
+ * This must be manually enabled for your account by Box Staff. Contact api@box.com for access. [ More Info ] (http://developers.box.com/docs/#users-as-user)
299
+
300
+ ```ruby
301
+ session = RubyBox::Session.new({
302
+ client_id: 'your-client-id',
303
+ client_secret: 'your-client-secret',
304
+ access_token: 'original-access-token' ,
305
+ as_user: 'your-users-box-id'
306
+ })
307
+ ```
308
+ Users
309
+ ------
310
+
311
+ Current User Info
312
+
313
+ ```ruby
314
+ me = client.me
315
+ ```
316
+
317
+ Current User's enterprise
318
+
319
+ ```ruby
320
+ me = client.me.enterprise
321
+ ```
322
+
323
+ An array of Ruby:Box users in an enterprise (Supports Filtering, Limit and Offset)
324
+
325
+ ```ruby
326
+ users = client.users
327
+ ```
328
+
329
+ * Remember the API filters "name" and "login" by the start of the string. ie: to get "sean+awesome@gmail.com" an approriate filter term would be "sean"
330
+
331
+ ```ruby
332
+ users = client.users("sean" , 10 , 1)
333
+ ```
334
+
335
+ Contributors
336
+ ============
337
+
338
+ * [full list of contributors](https://github.com/attachmentsme/ruby-box/graphs/contributors)
339
+
340
+ Contributing to ruby-box
341
+ ========================
342
+
343
+ RubyBox does not yet support all of Box's API Version 2.0 functionality, be liberal with your contributions.
344
+
345
+ * Rename account.example to account.yml and fill in your Box credentials
346
+ * Type bundle install
347
+ * Type rake.. tests should pass
348
+ * Add a failing test
349
+ * Make it pass
350
+ * Submit a pull request
351
+
352
+ Copyright
353
+ =========
354
+
355
+ Copyright (c) 2012 Attachments.me. See LICENSE.txt for
356
+ further details.