fulcrum 0.1.6 → 0.2.0

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    ZWY2MDkwMWM5ZWI3NjUxNzExMTQxNzRhYTNmMjg0OGJjNDdkNDhmNA==
+    NWFhOTc0Yzc4YzEzODQ2ZjE5MWVmMDI3NDc5MmU1Yjg1MDA3NzY1NQ==
   data.tar.gz: !binary |-
-    YzU0ZWNhZmE4ODc1MmViYjVlMTI1NjVjM2M0Y2QxMDBjYTgxNWYyZg==
+    NDIyNjg1Yzg0MzMwNDFmNThiMTgyNjM1MWNkNzkyMmZhZjkxYWQwNw==
 SHA512:
   metadata.gz: !binary |-
-    NjA2NjdiM2JkNDViMGEzODQ5OWU1N2MzMzc3NmI0YzNhNDlhYzBhNDY4NDhm
-    N2RiNGM4NjM1ZjNkMjAxNzZmZjgwNDdiNWQ1ZDBmZTMzYTJjYzA2MDA2N2M3
-    ZTg2NmIwMTc0OTJjZjM1ZTdlNDZiNzhmNzAwNzU0OTFlYjIwNzE=
+    OGYxYjYxYWEzMWMwNWNhYTJhMWZiZjUyMTZhYzZlZjlhZGE2MjY3MGZlYTE2
+    MmY3ZjNiYjgzM2FmYTVmMGIzODliMzhmMzM0Yzg3NGY1MTIzYjA0YjIzZTdj
+    MWNkNGE5NzE1MDhhZGZmZTIzNjFhMzc1MTNjYWIzYzRhOGY3Y2I=
   data.tar.gz: !binary |-
-    MTRkOTIwNzQwNDI5YjFiZTE4ZTc0YzkyZWU0ZWEyMThlMDRkNjRkYzA4YzUx
-    MzAwZTkyOGRiMmRlMjM2N2M3MDgzYjVlNDhjZjExMGIxYjJmYWZiNTZmMWYx
-    ZTU0MTNjYjE5MjBhODExNjliZmZlNTliNzRlYjc2NDFmYjhkMTU=
+    ZWYzNGE3NGUyZWNiMjBlMzY1MGJmMzE2MGZmYjVkZGYwN2YxODhjMjk5MWI3
+    OTk0NWQyMzNiNzcyMjQwOWNmYzkzMmMyNTI2Mzk4MjAzNGIyMTBmZTdjNzVj
+    NDg4NzMzNDU3YzBkYmQ5ZGY2NjE1M2NhMTE2YjAyMTdlMDRjNzM=

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2012 Chris Hall
+Copyright (c) 2014 Spatial Networks
 
 MIT License
 
@@ -19,4 +19,4 @@ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
 LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
 OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -5,7 +5,7 @@ Fulcrum API Gem
 ## Requirements
 
 * Ruby 1.9
-* [Fulcrum user account](https://web.fulcrumapp.com)
+* [Fulcrum account](https://web.fulcrumapp.com)
 
 ## Installation
 
@@ -23,118 +23,237 @@ Or install it yourself as:
 
     gem install fulcrum
 
-## Configuration
+## Using the gem
 
-```ruby
-Fulcrum::Api.configure do |config|
-  config.uri = 'https://api.fulcrumapp.com/api/v2'
-  config.key = 'your_api_key'
-end
-```
+## Client
 
-## Projects
+All interaction with the API is done through a client object. Below is a simple example of how to instantiate a client object.
 
 ```ruby
-Fulcrum::Project.all(opts)
-# opts = { 'page' => page_number,
-#          'updated_since' => date_time }
+client = Fulcrum::Client.new(your_api_key)
 ```
 
-## Forms
 
-```ruby
-Fulcrum::Form.all(opts)
-# opts = { 'page' => page_number,
-#          'schema' => true_or_false }
+## Basics
 
-Fulcrum::Form.find(id, opts)
-# opts = { 'include_foreign_elements' => true_or_false }
+In general, this API is intended to be a low level wrapper around the Fulcrum API. All of the filtering and query parameters are passed directly through to the HTTP request. It's best to read the [API documentation](http://fulcrumapp.com/developers/api/) to get a sense of the parameters available for each resource. Resource instances are returned from the API as simple hashes.
 
-Fulcrum::Form.create(form)
-# form = { 'form' => { ... } }
+When using the `create` or `update` methods on resources, the object passed to the method should be in the same format as a result from calling `find` on that resource. For example, you can call `client.records.find(id)` and the result can be used as the parameter for `client.records.update(id, record)`.
 
-Fulcrum::Form.update(id, form)
-# form = { 'form' => { ... } }
+Each of the API resources has an `all` method that can be used to fetch a list of resources. The `all` methods accept some basic pagination parameters (`per_page` and `page`) you can use to iterate over the pages. Because the index API's are paginated, the result of `all` is not the objects themselves. The `all` methods return a `Page` object that has some basic attributes to inspect the pagination extents. The `objects` attribute returns the actual array of objects. Below is a simple example that fetches the first page of records from the API.
+```ruby
 
-Fulcrum::Form.delete(id)
+client = Fulcrum::Client.new(your_api_key)
+
+result = client.records.all(form_id: my_form_id, page: 1, per_page: 100)
+
+puts result.class         # Fulcrum::Page
+puts result.per_page      # => 100
+puts result.current_page  # => 1
+puts result.total_pages   # => 2
+puts result.total_count   # => 137
+puts result.objects.count # => 100
+puts result.objects       # [ ... the records ... ]
 ```
 
 ## Records
 
+### client.records.all(params = {})
+
+Retrieve records with optional parameters. For a full list of the available parameters, see the [API documentation](http://fulcrumapp.com/developers/api/records/).
+
 ```ruby
-Fulcrum::Record.all(opts)
-# opts = { 'page' => page_number,
-#          'form_id' => form_id,
-#          'bounding_box' => 'lat_bottom,lng_left,lat_top,lng_right',
-#          'updated_since' => date_since_epoch_in_seconds }
+client.records.all(page: 1, per_page: 100, form_id: some_form_id, updated_since: timestamp)
+```
 
-Fulcrum::Record.find(id)
-Fulcrum::Record.create(record)
-# record = { 'record' => { ... } }
+### client.records.find(id)
 
-Fulcrum::Record.update(id, record)
-# record = { 'record' => { ... } }
+Find a single record by its `id` and return a `Hash` of the record attributes.
 
-Fulcrum::Record.delete(id)
-```
+### client.records.create(record)
 
-## Photos
+Create a new record from a `Hash` of attributes. The format of the attributes is identical to the format returned from `find`. The [record API documentation](http://fulcrumapp.com/developers/api/records) has more information on the format. **Note:** although the raw API uses a hash wrapped in a `record` attribute, this is not necessary for the ruby API. Instead of `{ "record" => record_attributes }`, you simply pass `record_attributes` directly to this method.
 
-```ruby
-Fulcrum::Photo.find(access_key, opts)
-# opts = { 'format' => 'json|jpg' }, defaults to 'json'
+### client.records.update(id, record)
 
-Fulcrum::Photo.thumbnail(access_key, opts)
-# opts = { 'format' => 'json|jpg' }, defaults to 'json'
+Update an existing record by its `id` using a `Hash` of attributes. The format of the attributes is identical to the format returned from `find`. The [record API documentation](http://fulcrumapp.com/developers/api/records) has more information on the format. **Note:** although the raw API uses a hash wrapped in a `record` attribute, this is not necessary for the ruby API. Instead of `{ "record" => record_attributes }`, you simply pass `record_attributes` directly to this method.
+
+### client.records.delete(id)
+
+Delete a record by its `id`.
+
+
+
+## Forms
+
+### client.forms.all(params = {})
+
+### client.forms.find(id)
+
+### client.forms.create(form)
+
+### client.forms.update(id, form)
+
+### client.forms.delete(id)
 
-Fulcrum::Photo.create(photo, content_type, unique_id, label)
 
-Fulcrum::Photo.delete(access_key)
-```
 
 ## Choice Lists
 
-```ruby
-Fulcrum::ChoiceList.all(opts)
-# opts = { 'page' => page_number }
+### client.choice_lists.all(params = {})
 
-Fulcrum::ChoiceList.find(id)
+### client.choice_lists.find(id)
 
-Fulcrum::ChoiceList.create(choice_list)
-# choice_list = { 'choice_list' => { ... } }
+### client.choice_lists.create(choice_list)
+
+### client.choice_lists.update(id, choice_list)
+
+### client.choice_lists.delete(id)
 
-Fulcrum::ChoiceList.update(id, choice_list)
-# choice_list = { 'choice_list' => { ... } }
 
-Fulcrum::ChoiceList.delete(id)
-```
 
 ## Classification Sets
 
-```ruby
-Fulcrum::ClassificationSet.all(opts)
-# opts = { 'page' => page_number }
+### client.classification_sets.all(params = {})
 
-Fulcrum::ClassificationSet.find(id)
+### client.classification_sets.find(id)
 
-Fulcrum::ClassificationSet.create(classification_set)
-# classification_set = { 'classification_set' => { ... } }
+### client.classification_sets.create(classification_set)
 
-Fulcrum::ClassificationSet.update(id, classification_set)
-# classification_set = { 'classification_set' => { ... } }
+### client.classification_sets.update(id, classification_set)
 
-Fulcrum::ClassificationSet.delete(id)
-```
+### client.classification_sets.delete(id)
 
-## Members
 
-```ruby
-Fulcrum::Member.all(opts)
-# opts = { 'page' => page_number }
 
-Fulcrum::Member.find(id)
+## Projects
+
+### client.projects.all(params = {})
+
+### client.projects.find(id)
+
+
+
+## Layers
+
+### client.layers.all(params = {})
+
+### client.layers.find(id)
+
+
+
+## Photos
+
+### client.photos.all(params = {})
+
+### client.photos.find(id)
+
+### client.photos.create(file_or_path, content_type = 'image/jpeg', attributes = {})
+
+Create a new photo from a file or a file path. `attributes` must be a `Hash` and currently only accepts 1 attribute, `access_key`.
+If you specify an `access_key`, it must be a UUID. If you don't specify an `access_key`, one will be automatically generated and returned in the response.
+
+### client.photos.delete(id)
+
+### client.photos.original(id) {|io| block }
+
+Downloads the original version and yields an IO object to the block. The block is passed an IO object that you can call `#read` on. For example, to download a photo to a file:
+
+```ruby
+client.photos.original(id) do |input|
+  File.open('output.jpg', 'wb') do |output|
+    output.write(input.read)
+  end
+end
 ```
 
+### client.photos.thumbnail(id) {|io| block }
+
+Downloads the thumbnail version and yields an IO object to the block.
+
+### client.photos.large(id) {|io| block }
+
+Downloads the large version and yields an IO object to the block.
+
+
+
+## Signatures
+
+### client.signatures.all(params = {})
+
+### client.signatures.find(id)
+
+### client.signatures.create(file_or_path, content_type = 'image/png', attributes = {})
+
+Create a new signature from a file or a file path. `attributes` must be a `Hash` and currently only accepts 1 attribute, `access_key`.
+If you specify an `access_key`, it must be a UUID. If you don't specify an `access_key`, one will be automatically generated and returned in the response.
+
+### client.signatures.delete(id)
+
+### client.signatures.original(id) {|io| block }
+
+Downloads the original version and yields an IO object to the block.
+
+### client.signatures.thumbnail(id) {|io| block }
+
+Downloads the thumbnail version and yields an IO object to the block.
+
+### client.signatures.large(id) {|io| block }
+
+Downloads the large version and yields an IO object to the block.
+
+
+
+## Videos
+
+### client.videos.all(params = {})
+
+### client.videos.find(id)
+
+### client.videos.create(file_or_path, content_type = 'video/mp4', attributes = {})
+
+Create a new video from a file or a file path. `attributes` must be a `Hash` and currently only accepts 2 attributes, `access_key` and `track`.
+If you specify an `access_key`, it must be a UUID. If you don't specify an `access_key`, one will be automatically generated and returned in the response.
+
+### client.videos.delete(id)
+
+### client.videos.original(id) {|io| block }
+
+Downloads the original version and yields an IO object to the block.
+
+### client.videos.small(id) {|io| block }
+
+Downloads the small version and yields an IO object to the block.
+
+### client.videos.medium(id) {|io| block }
+
+Downloads the medium version and yields an IO object to the block.
+
+### client.videos.track(id)
+
+Fetches the GPS track for the specified video.
+
+
+
+## Memberships
+
+### client.memberships.all(params = {})
+
+
+
+## Changesets
+
+### client.changesets.all(params = {})
+
+### client.changesets.find(id)
+
+### client.changesets.create(changeset)
+
+### client.changesets.update(id, changeset)
+
+### client.changesets.close(id, changeset = {})
+
+
 ## Extra Reading
 
 * [Fulcrum API documentation](http://fulcrumapp.com/developers/api/)

data/Rakefile

@@ -6,3 +6,8 @@ RSpec::Core::RakeTask.new
 
 task :default => :spec
 task :test => :spec
+
+desc "Open an irb session preloaded with this library"
+task :console do
+  sh "irb -rubygems -I lib -r fulcrum.rb"
+end

data/fulcrum.gemspec

@@ -5,7 +5,7 @@ Gem::Specification.new do |gem|
   gem.authors       = ["Spatial Networks"]
   gem.email         = ["sniadmin@spatialnetworks.com"]
   gem.description   = %q{Fulcrum API}
-  gem.summary       = %q{Fulcrum API}
+  gem.summary       = %q{Fulcrum API client for ruby}
   gem.homepage      = "http://github.com/spatialnetworks/fulcrum-ruby"
 
   gem.files         = `git ls-files`.split($\)
@@ -21,7 +21,6 @@ Gem::Specification.new do |gem|
   gem.add_development_dependency 'debugger'
 
   gem.add_dependency 'activesupport'
-  gem.add_dependency 'faraday', '~> 0.8.8'
-  gem.add_dependency 'hashie'
+  gem.add_dependency 'faraday', '~> 0.9.0'
   gem.add_dependency 'faraday_middleware'
 end

data/lib/fulcrum.rb

@@ -1,14 +1,22 @@
-require "fulcrum/version"
-require "fulcrum/api"
-require "fulcrum/form"
-require "fulcrum/record"
-require "fulcrum/project"
-require "fulcrum/choice_list"
-require "fulcrum/classification_set"
-require "fulcrum/member"
-require "fulcrum/photo"
-require "fulcrum/validators/base_validator"
-require "fulcrum/validators/form_validator"
-require "fulcrum/validators/record_validator"
-require "fulcrum/validators/choice_list_validator"
-require "fulcrum/validators/classification_set_validator"
+require 'active_support/all'
+require 'fulcrum/version'
+require 'fulcrum/resource'
+require 'fulcrum/actions/list'
+require 'fulcrum/actions/find'
+require 'fulcrum/actions/create'
+require 'fulcrum/actions/update'
+require 'fulcrum/actions/delete'
+require 'fulcrum/media_resource'
+require 'fulcrum/page'
+require 'fulcrum/choice_list'
+require 'fulcrum/classification_set'
+require 'fulcrum/form'
+require 'fulcrum/membership'
+require 'fulcrum/photo'
+require 'fulcrum/video'
+require 'fulcrum/signature'
+require 'fulcrum/project'
+require 'fulcrum/record'
+require 'fulcrum/layer'
+require 'fulcrum/changeset'
+require 'fulcrum/client'

data/lib/fulcrum/actions/create.rb

@@ -0,0 +1,15 @@
+module Fulcrum
+  module Actions
+    module Create
+      extend ActiveSupport::Concern
+
+      def create_action
+        collection
+      end
+
+      def create(object)
+        call(:post, create_action, attributes_for_object(object))[resource_name]
+      end
+    end
+  end
+end

data/lib/fulcrum/actions/delete.rb

@@ -0,0 +1,12 @@
+module Fulcrum
+  module Actions
+    module Delete
+      extend ActiveSupport::Concern
+
+      def delete(id)
+        call(:delete, member(id))
+      end
+    end
+  end
+end
+