my_john_deere_api 2.3.3 → 2.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e82399b62eca7ecbf5c1e1f9d7f0de2391c909bed4426ccafbc19a3b555a2df2
-  data.tar.gz: e38342e0db2b4adc5cc6a9a6bba54b91c7aeb2e56e819a25696fc3c0cde75447
+  metadata.gz: 75b86b9b093f4aa0cc586ce56fb961654b1b91577947acf48392d8d2294c85b9
+  data.tar.gz: b5879b20c85891180747ba42657ffa399da981596820c813a7049d680240dd39
 SHA512:
-  metadata.gz: 2e80cfb7dbd6f7fb209403d5d92405e1beacf5282612747f449d245dffea7b182e2dc913a57acbe478a9f986e8b6b421add72e525c9d34def8ffbfe22967dd15
-  data.tar.gz: 743a9373b0646e76ace34001ae95937555c1aa00eea2c9bbcc4b6d6896f4784d67d1ecd07b4e7116182de60066c01d5ab4468c595f2f68f0a9ad401baf727a69
+  metadata.gz: 6a8c729311baa853f8ae1039573f673cb01cc084d0fc9b662ce592dd1b907a85b153f04d07ebd6bf346558efb708242f5c13f3464f3c4c5b03a4c21a2479c2d9
+  data.tar.gz: cf5dd0b1e590baeb06ead7ffeffb4a7501de17b8b56596a297797186f1bc85aa33b196f58f19162f6027e40a27b023f9ad18ad3aa25e07b61fcd383612c0bbaa

data/README.md

@@ -3,7 +3,7 @@
 [![CircleCI](https://circleci.com/gh/Intellifarm/my_john_deere_api.svg?style=svg)](https://circleci.com/gh/Intellifarm/my_john_deere_api)
 
 This client allows you to connect the [MyJohnDeere API](https://developer.deere.com/#!documentation)
-without having to code your own oauth process, API requests, and pagination.
+without having to code your own oAuth process, API requests, and pagination.
 
 * Works with Rails, but does not require it
 * Supports both sandbox and live mode
@@ -23,6 +23,8 @@ without having to code your own oauth process, API requests, and pagination.
   * [Contribution Definitions](#contribution-definitions)
   * [Organizations](#organizations)
   * [Assets](#assets)
+  * [Asset Locations](#asset-locations)
+  * [Fields](#fields)
 * [Direct API Requests](#direct-api-requests)
   * [GET](#get)
   * [POST](#post)
@@ -345,7 +347,7 @@ organization.links
 # =>  {
 #       'self' => 'https://sandboxapi.deere.com/platform/organizations/1234',
 #       'machines' => 'https://sandboxapi.deere.com/platform/organizations/1234/machines',
-#       'wdtCapableMachines' => 'ttps://sandboxapi.deere.com/platform/organizations/1234/machines?capability=wdt'   
+#       'wdtCapableMachines' => 'https://sandboxapi.deere.com/platform/organizations/1234/machines?capability=wdt'   
 #     }
 
 organization.assets
@@ -435,6 +437,237 @@ asset.save
 ```
 
 
+### [Asset Locations](https://developer.deere.com/#!documentation&doc=.%2Fmyjohndeere%2Fassets.htm)
+
+Handles an asset's locations. Asset Location collections support the following methods:
+
+* create(attributes)
+* all
+* count
+* first
+
+An individual location supports the following methods:
+
+* timestamp
+* geometry
+* measurement\_data
+
+```ruby
+asset = organizations.assets.first
+# => the first asset returned by the organization
+
+asset.locations
+# => collection of locations belonging to this asset
+
+location = asset.locations.first
+# => the first location returned by the asset. Note that locations do not have their own id's
+#    in the JD platform, and therefore cannot be requested individually via a "find" method.
+
+location.timestamp
+# => "2019-11-11T23:00:00.000Z"
+#    John Deere includes 3 decimal places in the format, but does not actually
+#    store fractions of a second, so it will always end in ".000". This is
+#    important, because timestamps must be unique.
+
+location.geometry
+# =>  a GeoJSON formatted hash, for example:
+#     {
+#       "type"=>"Feature",
+#       "geometry"=>{
+#         "geometries"=>[
+#             {
+#               "coordinates"=>[-95.123456, 40.123456], 
+#               "type"=>"Point"
+#             }
+#           ],
+#         "type"=>"GeometryCollection"
+#       }
+#     }
+
+location.measurement_data
+# =>  the status details of this location, for example:
+#     [
+#       {
+#         "@type"=>"BasicMeasurement",
+#         "name"=>"[Soil Temperature](http://example.com/current_temperature)", 
+#         "value"=>"21.0", 
+#         "unit"=>"°C"
+#       }
+#     ]
+```
+
+The `create` method creates the location in the John Deere platform, and returns the newly created
+object from John Deere. However, there will be no new information since there is no unique ID
+generated. The timestamp submitted (which defaults to "now") will be rounded
+to the nearest second.
+
+```ruby
+locaton = asset.locatons.create(
+  # You can pass fractional seconds, but they will be truncated by JD.
+  timestamp: "2019-11-11T23:00:00.123Z",
+
+  # JD requires more complicated JSON geometry, but this client will convert a simple
+  # set of lat/long coordinates into the larger format automatically.
+  geometry: [-95.123456, 40.123456],
+
+  # This is a list of "measurements"
+  measurement_data: [
+    {
+      name: 'Temperature',
+      value: '68.0',
+      unit: 'F'
+    }
+  ]
+)
+
+location.timestamp
+# =>  "2019-11-11T23:00:00.000Z"
+#     Note that the timestamp's fractional second is truncated by John Deere, though they
+#     still return the record with three digits of precision.
+
+location.geometry
+# =>  a GeoJSON formatted hash in its larger format
+#     {
+#       "type"=>"Feature",
+#       "geometry"=>{
+#         "geometries"=>[
+#             {
+#               "coordinates"=>[-95.123456, 40.123456], 
+#               "type"=>"Point"
+#             }
+#           ],
+#         "type"=>"GeometryCollection"
+#       }
+#     }
+
+location.measurement_data
+#     [
+#       {
+#         "@type"=>"BasicMeasurement",
+#         "name"=>"Temperature", 
+#         "value"=>"68.0", 
+#         "unit"=>"F"
+#       }
+#     ]
+
+```
+
+There is no updating or deleting of a location. The newest location record always acts as the status
+for the given asset, and is what appears on the map view.
+
+Note that locations are called "Asset Locations" in John Deere, but we call the association "locations", as in
+`asset.locations`, for brevity.
+
+
+### [Fields](https://developer.deere.com/#!documentation&doc=myjohndeere%2FfieldsADS.htm)
+
+Handles an organization's fields. Field collections support the following methods:
+
+* all
+* count
+* first
+* find(field\_id)
+
+An individual field supports the following methods and associations:
+
+* id
+* name
+* archived?
+* links
+* flags (collection of this field's flags)
+
+The `count` method only requires loading the first page of results, so it's a relatively cheap call. On the other hand,
+`all` forces the entire collection to be loaded from John Deere's API, so use with caution. Fields can be
+created via the API, but there is no `create` method on this collection yet.
+
+```ruby
+organization.fields
+# => collection of fields under this organization
+
+organization.fields.count
+# => 15
+
+organization.fields.first
+# => an individual field object
+
+field = organization.fields.find(1234)
+# => an individual field object, fetched by ID
+
+field.name
+# => 'Smith Field'
+
+field.archived?
+# => false
+
+field.links
+# => a hash of API urls related to this field
+
+field.flags
+# => collection of flags belonging to this field
+```
+
+
+### [Flags](https://developer.deere.com/#!documentation&doc=.%2Fmyjohndeere%2Fflags.htm)
+
+Handles a field's flags. Flag collections support the following methods. Note, John Deere does not provide an endpoint to retrieve a specific flag by id:
+
+* all
+* count
+* first
+
+An individual flag supports the following methods and associations:
+
+* id
+* notes
+* geometry
+* archived?
+* proximity\_alert\_enabled?
+* links
+
+The `count` method only requires loading the first page of results, so it's a relatively cheap call. On the other hand,
+`all` forces the entire collection to be loaded from John Deere's API, so use with caution. Flags can be
+created via the API, but there is no `create` method on this collection yet.
+
+```ruby
+field.flags
+# => collection of flags under this field
+
+field.flags.count
+# => 15
+
+flag = field.flags.first
+# => an individual flag object
+
+flag.notes
+# => 'A big rock on the left after entering the field'
+
+flag.geometry
+# =>  a GeoJSON formatted hash, for example:
+#     {
+#       "type"=>"Feature",
+#       "geometry"=>{
+#         "geometries"=>[
+#             {
+#               "coordinates"=>[-95.123456, 40.123456], 
+#               "type"=>"Point"
+#             }
+#           ],
+#         "type"=>"GeometryCollection"
+#       }
+#     }
+
+
+field.archived?
+# => false
+
+field.proximity_alert_enabled?
+# => true
+
+field.links
+# => a hash of API urls related to this flag
+```
+
+
 ## Direct API Requests
 
 While the goal of the client is to eliminate the need to make/interpret calls to the John Deere API, it's important
@@ -544,7 +777,7 @@ Custom errors help clearly identify problems when using the client:
 * **InvalidRecordError** is raised when bad input has been given, in an attempt to create or update
   a record on the John Deere platform.
 * **MissingContributionDefinitionIdError** is raised when the optional contribution\_definition\_id
-  has not been set in the client, but an operation has been attempted that requires it - like 
+  has not been set in the client, but an operation has been attempted that requires it - like
   creating an asset in the John Deere platform.
 * **TypeMismatchError** is raised when a model is instantiated, typically when a record is received
   from John Deere and is being converted into a Ruby object. Model instantiation is normally handled

data/lib/my_john_deere_api.rb

@@ -13,4 +13,5 @@ module MyJohnDeereApi
   autoload :Validators,     'my_john_deere_api/validators'
 
   require 'my_john_deere_api/errors'
+  require 'my_john_deere_api/net_http_retry'
 end

data/lib/my_john_deere_api/client.rb

@@ -4,10 +4,11 @@ module MyJohnDeereApi
     include Helpers::CaseConversion
 
     attr_accessor :contribution_definition_id
-    attr_reader :api_key, :api_secret, :access_token, :access_secret
+    attr_reader :api_key, :api_secret, :access_token, :access_secret, :http_retry_options
 
     DEFAULTS = {
-      environment: :live
+      environment: :live,
+      http_retry: {}
     }
 
     ##
@@ -37,6 +38,7 @@ module MyJohnDeereApi
 
       self.environment = options[:environment]
       @contribution_definition_id = options[:contribution_definition_id]
+      @http_retry_options = options[:http_retry]
     end
 
     ##
@@ -45,7 +47,15 @@ module MyJohnDeereApi
 
     def accessor
       return @accessor if defined?(@accessor)
-      @accessor = OAuth::AccessToken.new(consumer.user_get, access_token, access_secret)
+
+      @accessor = NetHttpRetry::Decorator.new(
+        OAuth::AccessToken.new(
+          consumer.user_get,
+          access_token,
+          access_secret
+        ),
+        http_retry_options
+      )
     end
 
     ##

data/lib/my_john_deere_api/net_http_retry.rb

@@ -0,0 +1,2 @@
+require 'my_john_deere_api/net_http_retry/decorator'
+require 'my_john_deere_api/net_http_retry/max_retries_exceeded_error'

data/lib/my_john_deere_api/net_http_retry/decorator.rb

@@ -0,0 +1,53 @@
+module MyJohnDeereApi
+  module NetHttpRetry
+    class Decorator
+      attr_reader :object, :request_methods, :retry_delay_exponent, :max_retries, :response_codes
+
+      DEFAULTS = {
+        request_methods:      [:get, :post, :put, :delete],
+        retry_delay_exponent: 2,
+        max_retries: 12,
+        response_codes: ['429', '503']
+      }
+
+      def initialize(object, options={})
+        @object = object
+
+        [:request_methods, :retry_delay_exponent, :max_retries].each do |option|
+          instance_variable_set(:"@#{option}", options[option] || DEFAULTS[option])
+        end
+
+        @response_codes = (options[:response_codes] || DEFAULTS[:response_codes]).map(&:to_s)
+      end
+
+      def request(method_name, *args)
+        retries = 0
+        result = object.send(method_name, *args)
+
+        while response_codes.include?(result.code)
+          if retries >= max_retries
+            raise MaxRetriesExceededError.new(method_name, "#{result.code} #{result.message}")
+          end
+
+          delay = [result['retry-after'].to_i, retry_delay_exponent ** retries].max
+          sleep(delay)
+
+          result = object.send(method_name, *args)
+          retries += 1
+        end
+
+        result
+      end
+
+      private
+
+      def method_missing(method_name, *args, &block)
+        if request_methods.include?(method_name)
+          request(method_name, *args)
+        else
+          object.send(method_name, *args, &block)
+        end
+      end
+    end
+  end
+end

data/lib/my_john_deere_api/net_http_retry/max_retries_exceeded_error.rb

@@ -0,0 +1,20 @@
+module MyJohnDeereApi
+  module NetHttpRetry
+    ##
+    # This error is used when a single request has exceeded
+    # the number of retries allowed by NetHttpRetry::Decorator::MAX_RETRIES.
+
+    class MaxRetriesExceededError < StandardError
+
+      ##
+      # argument is a string which describes the attempted request
+
+      def initialize(request_method, response_message)
+        message = "Max retries exceeded for #{request_method.to_s.upcase} " +
+                  "request: #{response_message}"
+
+        super(message)
+      end
+    end
+  end
+end

data/lib/my_john_deere_api/version.rb

@@ -1,3 +1,3 @@
 module MyJohnDeereApi
-  VERSION='2.3.3'
+  VERSION='2.4.1'
 end

data/test/lib/my_john_deere_api/client_test.rb

@@ -6,7 +6,7 @@ describe 'MyJohnDeereApi::Client' do
     assert_equal 'thisIsATest', client.send(:camelize, :this_is_a_test)
   end
 
-  describe '#initialize(api_key, api_secret)' do
+  describe '#initialize(api_key, api_secret, options={})' do
     it 'sets the api key/secret' do
       client = JD::Client.new(api_key, api_secret)
 
@@ -35,6 +35,23 @@ describe 'MyJohnDeereApi::Client' do
       client = JD::Client.new(api_key, api_secret, contribution_definition_id: contribution_definition_id)
       assert_equal contribution_definition_id, client.contribution_definition_id
     end
+
+    it 'accepts a list of parameters for NetHttpRetry' do
+      custom_retries = JD::NetHttpRetry::Decorator::DEFAULTS[:max_retries] + 10
+
+      VCR.use_cassette('catalog') do
+        new_client = JD::Client.new(
+          api_key,
+          api_secret,
+          contribution_definition_id: contribution_definition_id,
+          environment: :sandbox,
+          access: [access_token, access_secret],
+          http_retry: {max_retries: custom_retries}
+        )
+
+        assert_equal custom_retries, new_client.accessor.max_retries
+      end
+    end
   end
 
   describe '#contribution_definition_id' do
@@ -130,7 +147,7 @@ describe 'MyJohnDeereApi::Client' do
 
     it 'sends the request' do
       response = VCR.use_cassette('put_asset') { client.put("/assets/#{asset_id}", attributes) }
-      puts "HASH!! #{response.inspect}" if response.is_a?(Hash)
+
       assert_equal '204', response.code
       assert_equal 'No Content', response.message
     end
@@ -199,7 +216,7 @@ describe 'MyJohnDeereApi::Client' do
 
   describe '#accessor' do
     it 'returns an object that can make user-specific requests' do
-      assert_kind_of OAuth::AccessToken, accessor
+      assert_kind_of JD::NetHttpRetry::Decorator, accessor
       assert_kind_of OAuth::Consumer, accessor.consumer
       assert_equal access_token, accessor.token
       assert_equal access_secret, accessor.secret