boxr 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 701cf0b13487355be79ee76e2a1e3c14f6b469e2
-  data.tar.gz: 4be68b9d0ea475e149e15dbda0698651a6de8deb
+  metadata.gz: 313b4d35a06c5975bcc0486d8d0099cb74288d53
+  data.tar.gz: b691b2075b1bb74992222aeb945c9e0665ab8378
 SHA512:
-  metadata.gz: a2a8c7de20cf50e9b1908663af64e438de58b23c6e1414e55ead210aa6b331f77160512760a72a50c89817e9433913c2cda99092ef32e21c102b4fa9d2547dce
-  data.tar.gz: 9fa79592811db54ff842378f90c5801f3303bda768456f5297557cf5b23288f6fb7330a48850f4225ce0c87de761ba1eca64cf525c42e59513145374423934d6
+  metadata.gz: 007e990c0b663e9b1cfd26bc387f4352d75764a462cbbed1ecf5bc41028982189c7507ff1fb87e7ca7d8d58112d45b06a611dd0d2c429cb818bd8fc17a9cc94c
+  data.tar.gz: 39f0c09f87141e9a62780401979c0a76391e4f1109d99f0653b9e81e50a3a968651c09c47b54cc4fcfca229c6d7b1977cedd203b40b6740255ea9bd0fe684c58

data/README.md

@@ -1,9 +1,11 @@
 # Boxr
+Boxr is a Ruby client library for the Box V2 Content API that covers 100% of the underlying REST API.  Box employees affectionately refer to one another as Boxers, hence the name of this gem.  
 
-PLEASE NOTE: I need to complete this README with much more detailed instructions.  However, feel free to try it out. The integration test suite is achieving 95% code coverage. Thanks!
+The purpose of this gem is to provide a clear, efficient, and intentional method of interacting with the Box Content API. As with any SDK that wraps a REST API, it is important to fully understand the Box Content API at the REST endpoint level.  You are strongly encouraged to read through the Box documentation located [here](https://developers.box.com/docs/).
 
-## Installation
+The full RubyDocs for Boxr can be found [here](http://www.rubydoc.info/gems/boxr).  You are also encouraged to rely heavily on the source code found in the [lib/boxr](https://github.com/cburnette/boxr/tree/master/lib/boxr) directory of this gem, as well as on the integration test found [here](https://github.com/cburnette/boxr/blob/master/spec/boxr_spec.rb).
 
+## Installation
 Add this line to your application's Gemfile:
 
 ```ruby
@@ -19,10 +21,9 @@ Or install it yourself as:
     $ gem install boxr
 
 ## Usage
+Super-fast instructions:
 
-Super-fast instructions for now (much more to come):
-
-1. go to https://developers.box.com
+1. go to http://developers.box.com
 2. find or create your Box Content API app for testing
 3. click 'Edit Application'
 4. check the boxes for 'Read and write all files and folders' and 'Manage an enterprise'
@@ -32,11 +33,62 @@ Super-fast instructions for now (much more to come):
 ```ruby
 require 'boxr'
 
-client = Boxr::Client.new({BOX_DEVELOPER_TOKEN})
+client = Boxr::Client.new('{BOX_DEVELOPER_TOKEN}')
 items = client.folder_items(Boxr::ROOT)
 items.each {|i| puts i.name}
 ```
 
+### Creating a client
+There are a few different ways to create a Boxr client.  The simplest is to use a Box Developer Token (you generate these from your Box app's General Information page).  They last for 60 minutes and you don't have to go through OAuth2.
+```ruby
+client = Boxr::Client.new('yPDWOvnumUFaKIMrNBg6PGJpWXC0oaFW')
+
+# Alternatively, you can set an environment variable called BOX_DEVELOPER_TOKEN to 
+# the value of your current token. By default, Boxr will look for that.
+
+client = Boxr::Client.new  #uses ENV['BOX_DEVELOPER_TOKEN']
+```
+
+The next way is to use an access token retrieved after going through the OAuth2 process.  If your application is going to handle refreshing the tokens in a scheduled way (more on this later) then this is the way to go.
+```ruby
+client = Boxr::Client.new('v2eAXqhZ28WIEpIWeAJcmyamLLt77icP')  #a valid OAuth2 access token
+
+# Boxr will raise an error if this token becomes invalid. It is up to your application to generate
+# a new pair of access and refresh tokens in a timely manner.
+```
+
+If you want Boxr to automatically refresh the tokens once the access token becomes invalid you can supply a refresh token, along with your client_id and client_secret, and a block that will get invoked when the refresh occurs.
+```ruby
+token_refresh_callback = lambda {|access, refresh, identifier| some_method_that_saves_them(access, refresh)}
+client = Boxr::Client.new('zX3UjFwNerOy5PSWc2WI8aJgMHtAjs8T', 
+                          refresh_token: 'dvfzfCQoIcRi7r4Yeuar7mZnaghGWexXlX89sBaRy1hS9e5wFroVVOEM6bs0DwPQ',
+                          client_id: 'kplh54vfeagt6jmi4kddg4xdswwvrw8y',
+                          client_secret: 'sOsm9ZZ8L8svwrn9FsdulLQVwDizKueU',
+                          &token_refresh_callback)
+                           
+# By default Boxr will look for client_id and client_secret in your environment variables as
+# BOX_CLIENT_ID and BOX_CLIENT_SECRET, respectively.  You can omit the two optional parameters above
+# if those are present.
+
+# Additionally, you can provide one other parameter called identifier. This can be used, for example, to
+# hold the id of the user associated with this Boxr client.  When the callback is invoked this value 
+# will be provided.
+```
+  
+### A quick example
+Before diving into detailed documentation, let's take a look at how to accomplish a simple task with Boxr.  This script will find a specific folder given its path, upload a file to that folder, and create an open shared link to that file.
+```ruby
+require 'boxr'
+
+client = Boxr::Client.new  #using ENV['BOX_DEVELOPER_TOKEN']
+
+folder = client.folder_from_path('/some/directory/structure')
+file = client.upload_file('test.txt', folder.id)
+file = client.create_shared_link_for_file(file.id, access: :open)
+puts "Shared Link: #{file.shared_link.url}"
+```
+
+
 ## Contributing
 
 1. Fork it ( https://github.com/cburnette/boxr/fork )

data/lib/boxr/files.rb

@@ -1,7 +1,7 @@
 module Boxr
   class Client
 
-    def file_id(path)
+    def file_from_path(path)
       if(path.start_with?('/'))
         path = path.slice(1..-1)
       end
@@ -9,15 +9,12 @@ module Boxr
       path_items = path.split('/')
       file_name = path_items.slice!(-1)
 
-      folder_id = folder_id(path_items.join('/'))
+      folder = folder_from_path(path_items.join('/'))
 
-      files = folder_items(folder_id, fields: [:id, :name])
-
-      begin
-        files.select{|f| f.name == file_name}.first.id
-      rescue
-        raise BoxrException.new(boxr_message: "File not found: '#{file_name}'")
-      end
+      files = folder_items(folder.id, fields: [:id, :name]).files
+      file = files.select{|f| f.name == file_name}.first
+      raise BoxrException.new(boxr_message: "File not found: '#{file_name}'") if file.nil?
+      file
     end
 
     def file(file_id, fields: [])

data/lib/boxr/folders.rb

@@ -1,21 +1,19 @@
 module Boxr
   class Client
 
-    def folder_id(path)
+    def folder_from_path(path)
       if(path.start_with?('/'))
         path = path.slice(1..-1)
       end
 
       path_folders = path.split('/')
 
-      folder_id = path_folders.inject(Boxr::ROOT) do |parent_id, folder_name|
-        folders = folder_items(parent_id, fields: [:id, :name]).folders
-
-        begin
-          folders.select{|f| f.name == folder_name}.first.id
-        rescue
-          raise BoxrException.new(boxr_message: "Folder not found: '#{folder_name}'")
-        end
+      root_folder = Hashie::Mash.new({id: Boxr::ROOT})
+      folder = path_folders.inject(root_folder) do |parent_folder, folder_name|
+        folders = folder_items(parent_folder.id, fields: [:id, :name]).folders
+        folder = folders.select{|f| f.name == folder_name}.first
+        raise BoxrException.new(boxr_message: "Folder not found: '#{folder_name}'") if folder.nil?
+        folder
       end
     end
 

data/lib/boxr/version.rb

@@ -1,3 +1,3 @@
 module Boxr
-  VERSION = "0.1.1"
+  VERSION = "0.2.0"
 end

data/spec/boxr_spec.rb

@@ -29,7 +29,7 @@ describe Boxr::Client do
   COMMENT_MESSAGE = 'this is a comment'
   REPLY_MESSAGE = 'this is a comment reply'
   CHANGED_COMMENT_MESSAGE = 'this comment has been changed'
-  TEST_USER_LOGIN = "test-boxr-user@example.com"
+  TEST_USER_LOGIN = "test-boxr-user@#{('a'..'z').to_a.shuffle[0,10].join}.com" #needs to be unique across anyone running this test
   TEST_USER_NAME = "Test Boxr User"
   TEST_GROUP_NAME= "Test Boxr Group"
   TEST_TASK_MESSAGE = "Please review"
@@ -46,7 +46,7 @@ describe Boxr::Client do
     @test_folder_id = new_folder.id
 
     all_users = BOX_CLIENT.all_users
-    test_user = all_users.find{|u| u.login == TEST_USER_LOGIN}
+    test_user = all_users.find{|u| u.name == TEST_USER_NAME}
     if(test_user)
       BOX_CLIENT.delete_user(test_user.id, force: true)
     end
@@ -62,9 +62,9 @@ describe Boxr::Client do
   end
 
   it 'invokes folder operations' do
-    puts "get folder id using path"
-    folder_id = BOX_CLIENT.folder_id(TEST_FOLDER_NAME)
-    expect(folder_id).to eq(@test_folder_id)
+    puts "get folder using path"
+    folder = BOX_CLIENT.folder_from_path(TEST_FOLDER_NAME)
+    expect(folder.id).to eq(@test_folder_id)
 
     puts "get folder info"
     folder = BOX_CLIENT.folder(@test_folder_id)
@@ -125,9 +125,9 @@ describe Boxr::Client do
     expect(new_file.name).to eq(TEST_FILE_NAME)
     test_file_id = new_file.id
 
-    puts "get file id using path"
-    file_id = BOX_CLIENT.file_id("/#{TEST_FOLDER_NAME}/#{TEST_FILE_NAME}")
-    expect(file_id).to eq(test_file_id)
+    puts "get file using path"
+    file = BOX_CLIENT.file_from_path("/#{TEST_FOLDER_NAME}/#{TEST_FILE_NAME}")
+    expect(file.id).to eq(test_file_id)
 
     puts "get file download url"
     download_url = BOX_CLIENT.download_url(test_file_id)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: boxr
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Chad Burnette
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-01-14 00:00:00.000000000 Z
+date: 2015-01-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler