geotrigger 0.0.4 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1eab33595fb526ab1fd3bd9b5ce817efec4645d4
-  data.tar.gz: 2d130461adf416f37c4a4bc4ae2244f663d09339
+  metadata.gz: b80b540534f9cbb0793eca389c041ac27eea153c
+  data.tar.gz: 1100a93307a68ab21ff168fad392c21a64191820
 SHA512:
-  metadata.gz: f5f6c4e88f34f686f28b1954f9dce23aa692fdabeae8dae54ee99c1f27897f5545da557a0405f600622ba9b4a4f966d49111a531620485540f79860c38ec98f9
-  data.tar.gz: 4f87a58f91f31f10a23636b452e1210b4a90945e0e7e65f68ce224a2f9347d22f0d9008eb51a09f7e3fcb5c09e5c32e4fcb78437988a434894bb478e9c27021f
+  metadata.gz: b80200b1e85cdd48327cecfc7fc684523a9190466f299f76f0a471290417696eca695e24e41b9b4564a7c9d4255551c45ddd6472f6771bcabd8a6865dfd7306a
+  data.tar.gz: 8939b512abcb68f664115143aef14d35b2b9a35dabce8605d5fea0f77fe5a1f813fd667b2b03c43de1f687635829837fbd910f2606a7d79b25c6c1425b9f3f19

data/.gitignore

@@ -1,3 +1,4 @@
 Gemfile.lock
 config.yml
 geotrigger-0.0.1.gem
+doc/*

data/README.md

@@ -2,3 +2,172 @@ geotrigger-ruby
 ===============
 
 a small ruby client for https://developers.arcgis.com/en/geotrigger-service/.
+
+# Install
+
+`gem install geotrigger`
+
+# Usage
+
+## Session
+
+`Geotrigger::Session` is the main interface to the Geotrigger API. Once
+created, it serves as the underlying support to all the Model subclasses.
+Its main features are:
+
+  * wrapping communication with the Geotrigger API
+  * handling all `access_token` negotiation with ArcGIS Online
+
+See also [API Doc](http://www.rubydoc.info/gems/geotrigger/Geotrigger/Session)
+
+To create a `Session`, call `#new` with a optional Hash:
+
+```ruby
+# specify client_id and client_secret
+#
+session = Geotrigger::Session.new client_id: 'abcde', client_secret: '12345'
+#=> <Geotrigger::Session ... >
+
+# specify client_id and :device type
+# (registers as a new device)
+#
+session = Geotrigger::Session.new client_id: 'abcde', type: :device
+#=> <Geotrigger::Session ... >
+
+# specify client_id, refresh_token, and :device type
+# (gets access_tokens for an existing device)
+#
+session = Geotrigger::Session.new client_id: 'abcde', refresh_token: 'qwert', type: :device
+#=> <Geotrigger::Session ... >
+
+# reads config from ~/.geotrigger YAML
+#
+session = Geotrigger::Session.new
+#=> <Geotrigger::Session ... >
+
+# reads config from ~/.geotrigger YAML :dev key
+#
+session = Geotrigger::Session.new config: :dev
+#=> <Geotrigger::Session ... >
+```
+
+You can then POST to any route in the API, without worring about managing
+`access_token` lifecycles, with a normal Ruby `Hash` for both request
+parameters and additional headers. The return value will be a normal Ruby
+`Hash` parsed from the JSON response of the API. A `GeotriggerError` may be
+raised if there was a problem with your request parameters or soemthing else.
+
+```ruby
+session.post 'trigger/list'
+#=> { "triggers" => [] }
+
+session.post 'device/update', deviceIds: ['abcd1234'], addTags: ['foo']
+#=> { "devices" => [ { "deviceId" => "abcd1234", tags: ["foo", "device:abcd1234", ...] } ] }
+
+begin
+  session.post 'device/update', bad_param: false
+rescue Geotrigger::GeotriggerError => ge
+
+  ge.parameters
+  #=> {"bad_param"=>[{"type"=>"invalid", "message"=>"Not a valid parameter for this request."}]}
+
+end
+```
+
+You can do all of what you need to through this interface, but there are some
+more lightweight utility classes for those that prefer a more OO approach.
+
+## Models
+
+These classes provide a ORM-ish interface to the Geotrigger API objects
+Application, Trigger, Tag, and Device.
+
+### Application
+
+Application objects offer top-level access to various other model objects,
+as well as updating of [Application](https://developers.arcgis.com/geotrigger-service/api-reference/application/) specific settings.
+
+See also [API Doc](http://www.rubydoc.info/gems/geotrigger/Geotrigger/Application)
+
+```
+a = Geotrigger::Application.new client_id: 'abcde', client_secret: '12345'
+#=> <Geotrigger::Application ... >
+
+d = a.devices(tags: ['foo']).first
+#=> <Geotrigger::Device ... >
+
+geojson = JSON.parse File.load 'something.geojson'
+t = a.triggers(geo: {geojson: geosjon}).first
+#=> <Geotrigger::Trigger ... >
+
+tag = a.tags.first
+#=> <Geotrigger::Tag ... >
+```
+
+### Trigger
+
+Trigger objects offer access to all attributes of a [Trigger](https://developers.arcgis.com/geotrigger-service/api-reference/trigger/).
+
+See also [API Doc](http://www.rubydoc.info/gems/geotrigger/Geotrigger/Trigger)
+
+```ruby
+trigger.add_tags 'foo'
+trigger.save
+
+trigger.remove_tags 'bar'
+trigger.properties = { foo: 'bar', baz: true, bat: 123 }
+trigger.save
+```
+
+### Device
+
+Device objects offer access to all attributes of a [Device](https://developers.arcgis.com/geotrigger-service/api-reference/device/).
+
+See also [API Doc](http://www.rubydoc.info/gems/geotrigger/Geotrigger/Device)
+
+```ruby
+device.add_tags 'foo'
+device.save
+
+device.remove_tags 'bar'
+device.properties = { foo: 'bar', baz: true, bat: 123 }
+device.save
+
+device.session.post 'location/update', locations: [{
+  longitude: -122,
+  latitude: 45,
+  accuracy: 10,
+  timestamp: DateTime.now.iso8601,
+  trackingProfile: 'adaptive'
+}]
+```
+
+### Tag
+
+Tag objects offer access to all attributes of a [Tag](https://developers.arcgis.com/geotrigger-service/api-reference/tag/).
+
+See also [API Doc](http://www.rubydoc.info/gems/geotrigger/Geotrigger/Tag)
+
+```ruby
+# create a new tag without applying it to any other objects
+#
+s = Geotrigger::Session.new
+tag = Geotrigger::Tag.create s, name: 'foo', deviceTagging: false
+#=> <Geotrigger::Tag ... >
+```
+
+Note that Tags are automatically created by the API, if needed, when added to a
+Trigger or Device. This offers a way to create the Tag before applying it to
+anything.
+
+```ruby
+a = Geotrigger::Application.new client_id: 'abcde', client_secret: '12345'
+#=> <Geotrigger::Application ... >
+
+tag = a.tags(tags: 'foo').first
+#=> <Geotrigger::Tag ... >
+
+tag.device_tagging = false
+tag.trigger_list = false
+tag.save
+```

data/lib/ext/string.rb

@@ -1,10 +1,11 @@
-class String
+# basic string extensions
+#
+# these are pretty much ripped from:
+#
+# https://github.com/rails/rails/blob/master/activesupport/lib/active_support/inflector/methods.rb
 
-  alias_method :blank?, :empty?
+class String
 
-  # these are pretty much ripped from:
-  # https://github.com/rails/rails/blob/master/activesupport/lib/active_support/inflector/methods.rb
-  #
   def camelcase
     string = self.sub(/^(?:(?=\b|[A-Z_])|\w)/) { $&.downcase }
     string.gsub!(/(?:_|(\/))([a-z\d]*)/i) { "#{$1}#{$2.capitalize}" }

data/lib/geotrigger.rb

@@ -1,12 +1,39 @@
+# Geotrigger - A small Ruby client for the Esri Geotrigger Service.
+# Copyright 2014 Esri; Nakamura, Kenichi (knakamura@esri.com)
+#
+# https://developers.arcgis.com/geotrigger-service/
+# http://www.esri.com/
+#
+# [author] Kenichi Nakamura (knakamura@esri.com)
+# [license] http://www.apache.org/licenses/LICENSE-2.0.txt
+
 require 'forwardable'
-require 'httpclient'; class HTTPClient; def inspect; to_s; end; end
+require 'httpclient'
 require 'json'
 
+# HTTPClient's normal #inspect is quite large, ungainly in irb sessions
+#
+if $0 == 'irb'
+  class HTTPClient
+    alias_method :real_inspect, :inspect
+    def inspect; self.to_s; end
+  end
+end
+
+# The Geotrigger module is the main namespace for all things in this library.
+#
 module Geotrigger
+
+  # raised by AGOSession on error from ArcGIS Online API
+  #
   class AGOError < StandardError; end
+
+  # raised by Session on error from Geotrigger API
+  #
   class GeotriggerError < StandardError
-    attr_accessor :code, :headers, :message, :params
+    attr_accessor :code, :headers, :message, :parameters
   end
+
 end
 
 lib = File.expand_path '../..', __FILE__
@@ -21,3 +48,5 @@ require 'geotrigger/application'
 require 'geotrigger/device'
 require 'geotrigger/tag'
 require 'geotrigger/trigger'
+
+require 'geotrigger/version'

data/lib/geotrigger/ago/session.rb

@@ -1,13 +1,46 @@
 module Geotrigger
+
+  # namespace for interacting with the ArcGIS Online API.
+  #
   module AGO
+
+    # AGO::Session is responsible for talking to the ArcGIS Online API.
+    #
+    # * retrieves a valid OAuth +access_token+, handling expiration
+    #   * Application, via +client_credentials+
+    #   * Device, via registration or +refresh_token+
+    # * registers a new Device given a +client_id+
+    #
+    # Generally, one interacts with only the +Session+, which retains an
+    # instance of this to deal with tokens.
+    #
     class Session
+
       extend ::Forwardable
       def_delegators :@impl, :access_token, :access_token=, :ago_data, :device_data, :refresh_token
 
+      # Read the base URL for ArcGIS Online API from the environment,
+      # or use the default.
+      #
+      # If you have a different OAuth portal, you can:
+      #
+      #   $ AGO_BASE_URL=http://example.com/path/ irb -rgeotrigger
+      #
+      # to have the client use that base URL.
+      #
       AGO_BASE_URL = (ENV.key?('AGO_BASE_URL') ?
                       (ENV['AGO_BASE_URL'] + '%s') :
                       'https://www.arcgis.com/sharing/%s').freeze
 
+      # Determines underlying implementation type, and creates an HTTPClient
+      # instance.
+      #
+      # [opts] +Hash+ options for construction:
+      #   [:client_id]     +String+ OAuth client id
+      #   [:client_secret] +String+ OAuth client secret
+      #   [:refresh_token] +String+ OAuth refresh token
+      #   [:type]          +Symbol+ +:application+ (default) or +:device+
+      #
       def initialize opts = {}
         @hc = HTTPClient.new
         @impl = case opts[:type] || :application
@@ -20,6 +53,8 @@ module Geotrigger
                 end
       end
 
+      # Type of implementation as a symbol.
+      #
       def type
         case @impl
         when Application
@@ -29,8 +64,12 @@ module Geotrigger
         end
       end
 
-      # http the specified method to the specified path with the given params.
-      # json parse the response body or raise errors.
+      # HTTP the specified method to the specified path with the given params.
+      # JSON parse the response body or raise errors.
+      #
+      # [meth]   +Symbol+ of the method to HTTP (:get,:post...)
+      # [path]   +String+ path of the request ('/example/index.html')
+      # [params] +Hash+ parameters for the request
       #
       def hc meth, path, params
         r = @hc.__send__ meth, AGO_BASE_URL % path, params.merge(f: 'json')
@@ -40,10 +79,17 @@ module Geotrigger
         h
       end
 
+      # Mixin for the AGO::Session underlying implementation.
+      #
       module ExpirySet
 
+        # Number of seconds before expiration to refresh tokens.
+        #
         TOKEN_EXPIRY_BUFFER = 10
 
+        # Sets a buffered +:expires_at+ for refreshing tokens. Generates this
+        # value from +Time.now+ and the supplied +expires_in+ value (seconds).
+        #
         def wrap_token_retrieval &block
           yield
           expires_at = Time.now.to_i + @ago_data['expires_in']
@@ -53,6 +99,8 @@ module Geotrigger
 
       end
 
+      # AGO::Session implementation for Applications
+      #
       class Application
         include ExpirySet
         extend ::Forwardable
@@ -60,11 +108,15 @@ module Geotrigger
 
         attr_reader :ago_data
 
+        # Accepts the abstract +AGO::Session+ and a +client_credentials+ Hash.
+        #
         def initialize session, opts = {}
           @session, @client_id, @client_secret =
             session, opts[:client_id], opts[:client_secret]
         end
 
+        # Returns a valid +access_token+. Gets a new one if +nil+ or expired.
+        #
         def access_token
           fetch_access_token if @ago_data.nil? or
                                 (not @ago_data[:expires_at].nil? and
@@ -74,6 +126,8 @@ module Geotrigger
 
         private
 
+        # Gets a new +access_token+.
+        #
         def fetch_access_token
           wrap_token_retrieval do
             @ago_data = hc :post, 'oauth2/token',
@@ -85,6 +139,8 @@ module Geotrigger
 
       end
 
+      # AGO::Session implementation for Devices
+      #
       class Device
         include ExpirySet
         extend Forwardable
@@ -93,11 +149,17 @@ module Geotrigger
         attr_accessor :refresh_token
         attr_reader :ago_data
 
+        # Accepts the abstract +AGO::Session+ and a Hash with +:client_id+
+        # and +:refresh_token+ keys.
+        #
         def initialize session, opts = {}
           @session, @client_id, @refresh_token =
             session, opts[:client_id], opts[:refresh_token]
         end
 
+        # Returns a valid +access_token+. Registers a new Device with AGO if
+        # needed.
+        #
         def access_token
           if @ago_data.nil?
             if @refresh_token.nil?
@@ -111,12 +173,16 @@ module Geotrigger
           @ago_data['access_token']
         end
 
+        # Fetches data from AGO about the device specified by this :access_token+.
+        #
         def device_data
           @device_data ||= hc(:get, 'portals/self', token: access_token)['deviceInfo']
         end
 
         private
 
+        # Registers as a new Device with AGO.
+        #
         def register
           wrap_token_retrieval do
             data = hc :post, 'oauth2/registerDevice', client_id: @client_id, expiration: -1
@@ -129,6 +195,8 @@ module Geotrigger
           end
         end
 
+        # Gets a new +access_token+.
+        #
         def refresh_access_token
           wrap_token_retrieval do
             @ago_data = hc :post, 'oauth2/token',

data/lib/geotrigger/application.rb

@@ -1,23 +1,82 @@
 module Geotrigger
 
+  # Application objects offer top-level, ORM-ish access to various other model
+  # objects, as well as updating of application specific settings.
+  #
+  #   a = Geotrigger::Application.new client_id: 'abcde', client_secret: '12345'
+  #   #=> <Geotrigger::Application ...>
+  #
+  #   # or
+  #
+  #   s = Geotrigger::Session.new client_id: 'abcde', client_secret: '12345'
+  #   a = Geotrigger::Application.new session: s
+  #   #=> <Geotrigger::Application ...>
+  #
   class Application < Model
 
+    # Return this application's default tag permissions as a +Hash+.
+    #
+    #   a.permissions
+    #   #=> {"deviceTagging"=>true, "deviceLocation"=>false, ... }
+    #
     def permissions
       post 'application/permissions'
     end
 
+    # Update this application's default tag permissions with a +Hash+.
+    #
+    #   a.permissions = { deviceTagging: false }
+    #   #=> {:deviceTagging => false }
+    #
+    #   a.permissions
+    #   #=> {"deviceTagging"=>false, "deviceLocation"=>false, ... }
+    #
     def permissions= perms
       post 'application/permissions/update', perms
     end
 
+    # Return an +Array+ of +Device+ model objects that belong to this
+    # application.
+    #
+    # [params] +Hash+ optional parameters to send with the request
+    #
+    #   a.devices tags: 'foo'
+    #   #=> [<Geotrigger::Device ...>, ...] # (devices that have the tag 'foo' on them)
+    #
+    #   a.devices geo: { geojson: { type: "Feature", properties: nil, geometry: {
+    #     type:"Polygon",coordinates:[[[-122.669085113593,45.4999973537201], ... ,[-122.669085113593,45.4999973537201]]]
+    #   }}}
+    #   #=> [<Geotrigger::Device ...>, ...] # (devices whose last location was inside the given polygon)
+    #
     def devices params = {}
       post_list 'devices', params
     end
 
+    # Return an +Array+ of +Tag+ model objects that belong to this
+    # application.
+    #
+    # [params] +Hash+ optional parameters to send with the request
+    #
+    #   a.tags
+    #   #=> [<Geotrigger::Tag...>, ...]
+    #
     def tags params = {}
       post_list 'tags', params
     end
 
+    # Return an +Array+ of +Trigger+ model objects that belong to this
+    # application.
+    #
+    # [params] +Hash+ optional parameters to send with the request
+    #
+    #   a.triggers tags: 'foo'
+    #   #=> [<Geotrigger::Trigger ...>, ...] # (triggers that have the tag 'foo' on them)
+    #
+    #   a.triggers geo: { geojson: { type: "Feature", properties: nil, geometry: {
+    #     type:"Polygon",coordinates:[[[-122.669085113593,45.4999973537201], ... ,[-122.669085113593,45.4999973537201]]]
+    #   }}}
+    #   #=> [<Geotrigger::Trigger ...>, ...] # (triggers whose condition polygon is inside the given polygon)
+    #
     def triggers params = {}
       post_list 'triggers', params
     end

data/lib/geotrigger/device.rb

@@ -1,8 +1,23 @@
 module Geotrigger
 
+  # +Device+ objects offer ORM-ish access to all attributes of a Device.
+  #
+  #   device.add_tags 'foo'
+  #   device.save
+  #
+  #   device.remove_tags 'bar'
+  #   device.properties = { foo: 'bar', baz: true, bat: 123 }
+  #   device.save
+  #
   class Device < Model
     include Taggable
 
+    # Create a new +Device+ instance and load +@data+ from the API given a
+    # +Hash+ with options:
+    #
+    # [device_id] +String+ id of the device
+    # [tags] +Array+ name(s) of tag(s) to filter devices by
+    #
     def initialize opts = {}
       super opts
       case session.type
@@ -17,10 +32,15 @@ module Geotrigger
       end
     end
 
+    # Return the +String+ of this device's default tag.
+    #
     def default_tag
       'device:%s' % deviceId
     end
 
+    # POST the device's +@data+ to the API via 'device/update', and return
+    # the same object with the new +@data+ returned from API call.
+    #
     def post_update
       post_data = @data.dup
       case @session.type
@@ -37,6 +57,12 @@ module Geotrigger
     end
     alias_method :save, :post_update
 
+    # Reads the data specific to this +Device+ from the API response and sets
+    # it in +@data+.
+    #
+    # [data] +Hash+ the API response
+    # [id] +String+ the id of the Device to pull out (first if nil)
+    #
     def grok_self_from data, id = nil
       if id == :first
         @data = data['devices'].first

data/lib/geotrigger/model.rb

@@ -1,5 +1,11 @@
 module Geotrigger
 
+  # Superclass for Geotrigger "objects" - +Application+, +Trigger+, +Device+,
+  # +Tag+.
+  #
+  # Contains the base logic for interacting with the Geotrigger API in an
+  # ORM-like fashion. Never instantiated directly by the user.
+  #
   class Model
 
     class StateError < StandardError; end
@@ -7,19 +13,39 @@ module Geotrigger
     extend Forwardable
     def_delegator :@session, :post
 
+    # The data behind the model object.
+    #
     attr_accessor :data
+
+    # The +Session+ the model object uses to talk to the API.
+    #
     attr_reader :session
 
+    # Create an instance of the subclassed model object from data retrieved
+    # from the API.
+    #
     def self.from_api data, session
       i = self.new session: session
       i.data = data
       return i
     end
 
+    # Create an instance and from given options +Hash+.
+    #
+    # [:session] +Session+ underlying session to use when talking to the API
+    #
     def initialize opts = {}
       @session = opts[:session] || Session.new(opts)
     end
 
+    # POST a request to this model's /list route, passing parameters. Returns
+    # a new instance of the model object with populated data via
+    # +Model.from_api+.
+    #
+    # [models] +String+ name of the model to request listed data for
+    # [params] +Hash+ parameters to send with the request
+    # [default_params] +Hash+ default parameters to merge +params+ into
+    #
     def post_list models, params = {}, default_params = {}
       model = models.sub /s$/, ''
       params = default_params.merge params
@@ -28,6 +54,15 @@ module Geotrigger
       end
     end
 
+    # Allows snake_case accessor to top-level data values keyed by their
+    # camelCase counterparts. An attempt to be moar Rubyish.
+    #
+    #   device.tracking_profile
+    #   #=> 'adaptive'
+    #
+    #   device.trackingProfile
+    #   #=> 'adaptive'
+    #
     def method_missing meth, *args
       meth_s = meth.to_s
       if meth_s =~ /=$/ and args.length == 1
@@ -47,6 +82,8 @@ module Geotrigger
       end
     end
 
+    # Compares underlying data for equality.
+    #
     def == obj
       if Model === obj
         self.data == obj.data
@@ -55,22 +92,45 @@ module Geotrigger
       end
     end
 
+    # Mixin for +Trigger+ and +Device+ to add tag functionality.
+    #
     module Taggable
 
+      # Returns this model's tags as an +Array+ of +Tag+ objects.
+      #
       def tags params = {}
         post_list 'tags', params, tags: @data['tags']
       end
 
+      # Sets 'addTags' in this model's +@data+ for POSTing to the API via
+      # +Model#save+.
+      #
+      #   device.add_tags 'foo', 'bar'
+      #   device.save
+      #
       def add_tags *names
         @data['addTags'] = names.flatten
       end
 
+      # Sets 'removeTags' in this model's +@data+ for POSTing to the API via
+      # +Model#save+.
+      #
+      #   trigger.remove_tags 'foo', 'bar'
+      #   trigger.save
+      #
       def remove_tags *names
         names = names.flatten
         raise ArgumentError.new "default tag prohibited" if names.include? default_tag
         @data['removeTags'] = names
       end
 
+
+      # Sets 'setTags' in this model's +@data+ for POSTing to the API via
+      # +Model#save+.
+      #
+      #   trigger.tags = ['foo', 'bar']
+      #   trigger.save
+      #
       def tags= *names
         names = names.flatten
         raise ArgumentError.new "default tag required" unless names.include? default_tag

data/lib/geotrigger/session.rb

@@ -1,9 +1,67 @@
+# Geotrigger - A small Ruby client for the Esri Geotrigger Service.
+# Copyright 2014 Esri; Nakamura, Kenichi (knakamura@esri.com)
+#
+# https://developers.arcgis.com/geotrigger-service/
+# http://www.esri.com/
+#
+# [author] Kenichi Nakamura (knakamura@esri.com)
+# [license] http://www.apache.org/licenses/LICENSE-2.0.txt
+
 module Geotrigger
 
+  # +Session+ is the main interface to the Geotrigger API.
+  #
+  # Instances of it POST to the API and return the values using normal Ruby
+  # Hashes. Used by objects subclassed from +Model+.
+  #
+  # Example:
+  #
+  #   session = Geotrigger::Session.new client_id: 'abcde', client_secret: '12345'
+  #   session.post 'trigger/list'
+  #   #=> { "triggers" => [ ... ] }
+  #
+  #   device_session = Geotrigger::Session.new client_id: 'abcde', type: :device
+  #   device_session.post 'device/update', addTags: ['foo']
+  #   #=> { "devices" => [{ "deviceId" => '0987qwer', tags: ["device:0987qwer", "foo"], ... }] }
+  #
+  #   device_session = Geotrigger::Session.new client_id: 'abcde', refresh_token: 'zxcvb', type: :device
+  #   device_session.post 'device/list'
+  #   #=> { "devices" => [{ "deviceId" => '1234zxcv', tags: ["device:1234zxcv"], ... }] }
+  #
+  # It can also read default values for the constructor options from
+  # +ENV['HOME']/.geotrigger+, which is YAML formatted like:
+  #
+  #   :production:
+  #     :client_id: abcde
+  #     :client_secret: 12345
+  #   :test:
+  #     :client_id: qwert
+  #     :client_secret: 67890
+  #   :test_device:
+  #     :client_id: qwert
+  #     :refresh_token: 45678lmnop
+  #     :type: :device
+  #
+  # It will load the first Hash it finds with value for key +:client_id+, or
+  # one specified with the +:config+ option like:
+  #
+  #   # default to :production in the example
+  #   s = Geotrigger::Session.new
+  #
+  #   # specify the :test_device config
+  #   s = Geotrigger::Session.new config: :test_device
+  #
   class Session
     extend Forwardable
     def_delegator :@ago, :type
 
+    # Read the base URL for Geotrigger API from the environment, or use the
+    # default.
+    #
+    #   $ GT_BASE_URL=http://example.com/path/ irb -rgeotrigger
+    #
+    # to have the client use that base URL.
+    #
     BASE_URL = (ENV.key?('GT_BASE_URL') ?
                (ENV['GT_BASE_URL'] + '%s') :
                'https://geotrigger.arcgis.com/%s').freeze
@@ -12,6 +70,14 @@ module Geotrigger
 
     attr_writer :access_token
 
+    # Creates a Geotrigger::Session instance. Valid key/values for +opts+ are:
+    #
+    # [:client_id]     +String+ OAuth client id
+    # [:client_secret] +String+ OAuth client secret
+    # [:refresh_token] +String+ OAuth refresh token (used for +:device+ type)
+    # [:type]          +Symbol+ +:application+ (default) or +:device+
+    # [:config]        +Symbol+ key of options defaults in ~/.geotrigger
+    #
     def initialize opts = {}
       if opts[:config] or opts.empty?
         if File.exist? USER_CONFIG
@@ -31,17 +97,31 @@ module Geotrigger
       @hc = HTTPClient.new
     end
 
+    # Returns a valid +access_token+. Gets a new one if +nil+ or expired.
+    #
     def access_token
       @access_token || @ago.access_token
     end
 
+    # Returns default request headers optionally merged with specified others.
+    #
+    # [others] +Hash+ other headers to include
+    #
     def headers others = {}
       {
         'Content-Type' => 'application/json',
-        'Authorization' => "Bearer #{access_token}"
+        'Authorization' => "Bearer #{access_token}",
+        'X-GT-Client-Name' => 'geotrigger-ruby',
+        'X-GT-Client-Version' => Geotrigger::VERSION
       }.merge others
     end
 
+    # POST an API request to the given path, with optional params and
+    # headers. Returns a normal Ruby +Hash+ of the response data.
+    #
+    # [params]        +Hash+ parameters to include in the request (will be converted to JSON)
+    # [other_headers] +Hash+ headers to include in the request in addition to the defaults.
+    #
     def post path, params = {}, other_headers = {}
       r = @hc.post BASE_URL % path, params.to_json, headers(other_headers)
       raise GeotriggerError.new r.body unless r.status == 200
@@ -50,20 +130,26 @@ module Geotrigger
       h
     end
 
+    # Creates and raises a +GeotriggerError+ from an API error response.
+    #
     def raise_error error
       ge = GeotriggerError.new error['message']
       ge.code = error['code']
       ge.headers = error['headers']
       ge.message = error['message']
-      ge.params = error['params']
+      ge.parameters = error['parameters']
       jj error
       raise ge
     end
 
+    # True if Session is for a Device.
+    #
     def device?
       type == :device
     end
 
+    # True if Session is for an Application.
+    #
     def application?
       type == :application
     end

data/lib/geotrigger/tag.rb

@@ -1,7 +1,18 @@
 module Geotrigger
 
+  # +Tag+ objects offer ORM-ish access to all attributes of a Tag.
+  #
   class Tag < Model
 
+    # Create a Tag with the given +Session+ and options. Note that Tags are
+    # automatically created by the API, if needed, when added to a Trigger
+    # or Device. This offers a way to create the Tag before applying it to
+    # anything.
+    #
+    #   s = Geotrigger::Session.new
+    #   tag = Geotrigger::Tag.create s, name: 'foo', deviceTagging: false
+    #   #=> <Geotrigger::Tag ... >
+    #
     def self.create session, opts
       t = ::Geotrigger::Tag.new session: session
       t.data = opts
@@ -9,6 +20,11 @@ module Geotrigger
       t.post_create
     end
 
+    # Create a new +Tag+ instance and load +@data+ from the API given a +Hash+
+    # with options:
+    #
+    # [name] +String+ name of the tag
+    #
     def initialize opts = {}
       super opts
       if opts[:name] and @data.nil?
@@ -16,20 +32,35 @@ module Geotrigger
       end
     end
 
+    # Return an +Array+ of +Trigger+ objects in this Application that have this
+    # tag applied to them.
+    #
+    # [params] +Hash+ any additional parameters to include in the request (trigger/list)
+    #
     def triggers params = {}
       post_list 'triggers', params, tags: name
     end
 
+    # Return an +Array+ of +Device+ objects in this Application that have this
+    # tag applied to them.
+    #
+    # [params] +Hash+ any additional parameters to include in the request (device/list)
+    #
     def devices params = {}
       post_list 'devices', params, tags: name
     end
 
+    # Creates a tag by POSTing to tag/permissions/update with +@data+.
+    #
     def post_create
       post_data = @data.dup
       grok_self_from post('tag/permissions/update', post_data), @data[:tags]
       self
     end
 
+    # POST the tag's +@data+ to the API via 'tag/permissions/update', and return
+    # the same object with the new +@data+ returned from API call.
+    #
     def post_update
       raise StateError.new 'device access_token prohibited' if @session.device?
       post_data = @data.dup
@@ -39,6 +70,12 @@ module Geotrigger
     end
     alias_method :save, :post_update
 
+    # Reads the data specific to this +Tag+ from the API response and sets
+    # it in +@data+.
+    #
+    # [data] +Hash+ the API response
+    # [name] +String+ the name of the Tag to pull out
+    #
     def grok_self_from data, name = nil
       @data = data['tags'].select {|t| t['name'] == (name || @data['name'])}.first
     end

data/lib/geotrigger/trigger.rb

@@ -1,16 +1,36 @@
 module Geotrigger
 
+  # +Trigger+ objects offer ORM-ish access to all attributes of a Trigger.
+  #
+  #   trigger.add_tags 'foo'
+  #   trigger.save
+  #
+  #   trigger.remove_tags 'bar'
+  #   trigger.properties = { foo: 'bar', baz: true, bat: 123 }
+  #   trigger.save
+  #
   class Trigger < Model
     include Taggable
 
     CIRCLE_KEYS = %w[latitude longitude distance]
 
+    # Create a Trigger with the given +Session+ and options.
+    #
+    #   s = Geotrigger::Session.new
+    #   t = Geotrigger::Trigger.create s, condition: { ... }, action: { ... }, tags: ['foo']
+    #   #=> <Geotrigger::Trigger ... >
+    #
     def self.create session, opts
       t = Trigger.new session: session
       t.data = opts
       t.post_create
     end
 
+    # Create a new +Trigger+ instance and load +@data+ from the API given a
+    # +Hash+ with options:
+    #
+    # [tags] +Array+ name(s) of tag(s)
+    #
     def initialize opts = {}
       super opts
       if opts[:trigger_id] and @data.nil?
@@ -18,16 +38,23 @@ module Geotrigger
       end
     end
 
+    # Return the +String+ of this trigger's default tag.
+    #
     def default_tag
       'trigger:%s' % triggerId
     end
 
+    # Creates a trigger by POSTing to trigger/create with +@data+.
+    #
     def post_create
       post_data = @data.dup
       @data = post 'trigger/create', post_data
       self
     end
 
+    # POST the trigger's +@data+ to the API via 'trigger/update', and return
+    # the same object with the new +@data+ returned from API call.
+    #
     def post_update opts = {}
       post_data = @data.dup
       post_data['triggerIds'] = post_data.delete 'triggerId'
@@ -43,10 +70,19 @@ module Geotrigger
     end
     alias_method :save, :post_update
 
+    # Reads the data specific to this +Trigger+ from the API response and sets
+    # it in +@data+.
+    #
+    # [data] +Hash+ the API response
+    # [triggerId] +String+ the id of the trigger to pull out (first if nil)
+    #
     def grok_self_from data, id = nil
       @data = data['triggers'].select {|t| t['triggerId'] == (id || @data['triggerId'])}.first
     end
 
+    # True if trigger is a "circle" type, meaning it has a point(longitude,latitude) and
+    # radius(distance) in its condition, rather than only a geojson or esrijson geometry.
+    #
     def circle?
       not CIRCLE_KEYS.map {|k| @data['condition']['geo'].keys.include? k}.select {|e| e}.empty?
     end

data/lib/geotrigger/version.rb

@@ -1,3 +1,3 @@
 module Geotrigger
-  VERSION = '0.0.4'
+  VERSION = '0.0.6'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: geotrigger
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.6
 platform: ruby
 authors:
 - Kenichi Nakamura
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-02-18 00:00:00.000000000 Z
+date: 2014-02-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httpclient