artemis_api 0.2.0 → 0.7.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 32db9ba97ad1d05952feab8c6bd9b4ee8de457ba
-  data.tar.gz: 51c060027ec42f376727b5306458757050fefbec
+SHA256:
+  metadata.gz: '028bbc37f004d68e6513d33cd96c577933d05a0690de059cb737f26a19d8405c'
+  data.tar.gz: 5d403657733f1e76b2dd4f3416126f9f06484c402ec3fc544e33725d935200ea
 SHA512:
-  metadata.gz: 68232ded4b5b706fd7ddcc3be017a7d054063df9af3090447449833d5eb16177da445c863eeac10153cc7b98d168fdbb7c9a23877eaf73c4cee222f38c2a8039
-  data.tar.gz: cc72bb823a05f33d8cbda6e231464aee7ed1f3555016c60952fcaeaeb9fc8c956e0d18b840a1b79fd057be6f0884002a71be9c61dc0391dc007c90de0a0f16ae
+  metadata.gz: f6cb7bbf6da754d24ab0b9e5cbc3bd83391d4cdb13268a99c81c9c244ba2671dc82b7fa3bf62b91cf97c05a8b3a1f4cf5045be2854463f9e52587915e2c2f063
+  data.tar.gz: ba63182e17d76c7d90224a0d87a6073b8314203cbffc7422ecde68937eb11084fcd8cfb8d56058d71143c852d3d8cf6f34a0d6ac704144f4956bcaf1b002e8f8

data/.ruby-version

@@ -0,0 +1 @@
+2.6.0

data/Gemfile.lock

@@ -1,48 +1,56 @@
 PATH
   remote: .
   specs:
-    artemis_api (0.1.0)
+    artemis_api (0.7.4)
+      oauth2
 
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (5.2.3)
+    activesupport (6.0.3.1)
       concurrent-ruby (~> 1.0, >= 1.0.2)
       i18n (>= 0.7, < 2)
       minitest (~> 5.1)
       tzinfo (~> 1.1)
+      zeitwerk (~> 2.2, >= 2.2.2)
     addressable (2.6.0)
       public_suffix (>= 2.0.2, < 4.0)
-    concurrent-ruby (1.1.5)
+    coderay (1.1.2)
+    concurrent-ruby (1.1.6)
     crack (0.4.3)
       safe_yaml (~> 1.0.0)
-    faraday (0.15.4)
+    faraday (1.0.1)
       multipart-post (>= 1.2, < 3)
     hashdiff (0.4.0)
-    i18n (1.6.0)
+    i18n (1.8.2)
       concurrent-ruby (~> 1.0)
     jwt (2.2.1)
+    method_source (1.0.0)
     minitest (5.11.3)
-    multi_json (1.13.1)
+    multi_json (1.14.1)
     multi_xml (0.6.0)
     multipart-post (2.1.1)
-    oauth2 (1.4.1)
-      faraday (>= 0.8, < 0.16.0)
+    oauth2 (1.4.4)
+      faraday (>= 0.8, < 2.0)
       jwt (>= 1.0, < 3.0)
       multi_json (~> 1.3)
       multi_xml (~> 0.5)
       rack (>= 1.2, < 3)
+    pry (0.13.1)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
     public_suffix (3.1.1)
-    rack (2.0.7)
-    rake (10.5.0)
+    rack (2.2.3)
+    rake (13.0.1)
     safe_yaml (1.0.5)
     thread_safe (0.3.6)
-    tzinfo (1.2.5)
+    tzinfo (1.2.7)
       thread_safe (~> 0.1)
     webmock (3.6.0)
       addressable (>= 2.3.6)
       crack (>= 0.3.2)
       hashdiff (>= 0.4.0, < 2.0.0)
+    zeitwerk (2.3.0)
 
 PLATFORMS
   ruby
@@ -52,9 +60,9 @@ DEPENDENCIES
   artemis_api!
   bundler (~> 1.16)
   minitest (~> 5.0)
-  oauth2
-  rake (~> 10.0)
+  pry
+  rake (~> 13.0)
   webmock
 
 BUNDLED WITH
-   1.17.2
+   1.17.3

data/History.txt

@@ -1,5 +1,23 @@
 # coding: UTF-8
 
+=== 0.4.0 / 2019-11-14
+
+* Added pagination functionality to Batch queries
+* Cleaned up filtering and added tests
+* Documentation updates
+
+=== 0.3.0 / 2019-11-04
+
+* Added an alternative OAuth flow that can accept an authorization code
+  directly and handle the creation of the OAuth client and token
+
+=== 0.2.1 / 2019-10-28
+
+* Minor updates to documentation
+* Fix errors with gem installation
+* Don't try to delete a record if it doesn't exist
+* Using URI module to generate API urls
+
 === 0.2.0 / 2019-10-24
 
 * Added the ability to delete Subscriptions

data/README.md

@@ -6,6 +6,12 @@ This is a simple API wrapper for the [Artemis](https://artemisag.com/) API.
 
 Add this line to your application's Gemfile:
 
+```ruby
+gem 'artemis_api'
+```
+
+If you want to ensure the most up to date version, you can also use the gem straight from the repository:
+
 ```ruby
 gem 'artemis_api', :git => 'https://github.com/artemis-ag/artemis_api'
 ```
@@ -20,13 +26,15 @@ Or install it yourself as:
 
 ## Usage
 
+#### Instantiating your Client
+
 In order to use this gem, you will need to be set up as a developer in the Artemis Portal. If you're not, please contact Artemis CS in order to get that settled.
 
 Once you have developer access, go to Settings and choose "OAuth 2.0 Applications" at the bottom of the sidebar to set up an application by entering the name and redirect URI you wish to use. You will then be provided with an application ID and a secret ID, which you will need in order to authenticate with Artemis.
 
-(Please note that this gem doesn't currently handle OAuth. You will need to do that on your own in order to generate your access token and refresh token. We recommend using the [OAuth2 gem](https://github.com/oauth-xx/oauth2). You'll also need to pass in the `expires_at` for when your token will exipire.)
+The first step to actually using this gem is to instantiate an instance of `ArtemisApi::Client` and there are two different ways to do so depending on if you're handling OAuth in your own app or not.
 
-Once you have all this info, the first step to actually using this gem is to instantiate an instance of `ArtemisApi::Client` - which requires an access token, a refresh token,
+If you intend to do a full OAuth flow, we recommend using the [OAuth2 gem](https://github.com/oauth-xx/oauth2). After authenticating with OAuth and generating your access token and refresh token, you can use them to instantiate your Client instance. You'll also need to pass in the `expires_at` for when your token will expire. That looks like this:
 
 ```ruby
 options = {app_id: 'your_artemis_application_id',
@@ -39,7 +47,7 @@ client = ArtemisApi::Client.new(access_token: 'your_access_token',
                                 options: options)
 ```
 
-Alternatively, instead of passing in options, you can set those values as ENV variables called `ENV['ARTEMIS_OAUTH_APP_ID']`, `ENV['ARTEMIS_OAUTH_APP_SECRET']` and `ENV['ARTEMIS_BASE_URI']`
+Instead of passing in options, you can set those values as ENV variables called `ENV['ARTEMIS_OAUTH_APP_ID']`, `ENV['ARTEMIS_OAUTH_APP_SECRET']` and `ENV['ARTEMIS_BASE_URI']`
 
 They will be automatically detected and then you don't have to pass in any options:
 ```ruby
@@ -48,6 +56,20 @@ client = ArtemisApi::Client.new(access_token: 'your_access_token',
                                 expires_at: token_expires_at)
 ```
 
+Alternatively, if you're working on a command line tool or otherwise not intending to implement a full OAuth flow, you can generate an authorization code directly and use this code to obtain an access token and a refresh token.
+Do this by creating an OAuth application in your Artemis settings with `urn:ietf:wg:oauth:2.0:oob` as the callback url. Then, clicking the Authorize button directly on Artemis Portal beside it on your application show page will
+provide you directly with an authorization code. Pass it into the Client instantiator like this. (The same rules apply about either passing in options or setting your ENV variables.)
+
+```ruby
+client = ArtemisApi::Client.new(auth_code: 'your_generated_authorization_code')
+```
+
+This authorization code is only valid for one use. If you want to keep connecting using the same authorization grant, you
+need to save the values of `client.access_token`, `client.refresh_token` and `client.expires_at` and use them when
+reinstantiating `client` in the future.
+
+#### Requesting data from Artemis
+
 Once you have a client instance, you can use it to request information from Artemis.
 
 To get user information about the Artemis User that is associated with your application ID:
@@ -146,8 +168,10 @@ ArtemisApi::Batch.find(id: 22, facility_id: 2, client: client, include: "complet
 We also support filtering on several models: Batch, Completion, Discard, Harvest, Zone, Item. It is another optional param and it expects a hash. Here's what that should look like.
 
 ```ruby
-ArtemisApi::Batch.find_all(facility_id: 2, client: client, filters: {view: 'all_batches', search: 'genovese basil'})
+ArtemisApi::Batch.find_all(facility_id: 2, client: client, filters: {search: 'genovese basil'})
 ArtemisApi::Batch.find_all(facility_id: 2, client: client, filters: {ids: [2, 4, 6, 11]})
+ArtemisApi::Batch.find_all(facility_id: 2, client: client, filters: {date_type: 'seeded_at', date_window: "2019-10-31 17:06:42 -0400,2019-11-15 17:06:42 -0500"})
+
 ArtemisApi::Completion.find_all(facility_id: 2, client: client, filters: {crop_batch_ids: [5]})
 ArtemisApi::Harvest.find_all(facility_id: 2, client: client, filters: {crop_batch_ids: [5, 7]})
 ArtemisApi::Discard.find_all(facility_id: 2, client: client, filters: {crop_batch_ids: [6, 7, 9]})
@@ -157,6 +181,12 @@ ArtemisApi::Item.find_all(facility_id: 2, batch_id: 22, client: client, filters:
 
 Note that when you filter by ids or crop_batch_ids, you must pass in an array even if it only has one element.
 
+Pagination is also supported on batches, and is also an optional param that expects a hash. We use the limit/offset method of pagination.
+
+```ruby
+ArtemisApi::Batch.find_all(facility_id: 2, client: client, page: {limit: 10, offset: 60})
+```
+
 The Artemis API is currently mainly read only, but we do support the creation of Subscriptions. These are used to set up webhooks that will make a callback to you whenever a Completion or Batch gets created or updated in the given facility. They require a `subject`, which can currently be either `completions` or `batches`, and a `destination`, which is the url that you want the callback to hit. There are two ways to make that call:
 
 ```ruby
@@ -168,6 +198,12 @@ ArtemisApi::Subscription.create(facility_id: 2,
 facility.create_subscription(subject: 'completions', destination: 'https://test-app-url.artemisag.io/v1/webhook')
 ```
 
+You can also delete one of your own Subscriptions. Trying to delete a Subscription that isn't associated with your user account will fail.
+
+```ruby
+ArtemisApi::Subscription.delete(id: 1, facility_id: 2, client: client)
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/artemis_api.gemspec

@@ -1,4 +1,3 @@
-
 lib = File.expand_path("../lib", __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require "artemis_api/version"
@@ -6,24 +5,27 @@ require "artemis_api/version"
 Gem::Specification.new do |spec|
   spec.name          = "artemis_api"
   spec.version       = ArtemisApi::VERSION
-  spec.authors       = ["Jamey Hampton"]
-  spec.email         = ["jhampton@artemisag.com"]
+  spec.authors       = ["Jamey Hampton", "Carlos Betancourt Carrero"]
+  spec.email         = ["jhampton@artemisag.com", "cbetancourt@artemisag.com"]
 
-  spec.summary       = %q{An API wrapper for the ArtemisAg API}
+  spec.summary       = "An API wrapper for the ArtemisAg API"
   spec.homepage      = "https://github.com/artemis-ag/artemis_api/"
   spec.license       = "MIT"
 
   spec.files         = `git ls-files -z`.split("\x0").reject do |f|
     f.match(%r{^(test|spec|features)/})
+    f.match(/\.gem$/)
   end
   spec.bindir        = "exe"
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
+  spec.add_dependency "oauth2"
+
+  spec.add_development_dependency "activesupport"
   spec.add_development_dependency "bundler", "~> 1.16"
-  spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "minitest", "~> 5.0"
-  spec.add_development_dependency "oauth2"
+  spec.add_development_dependency "pry"
+  spec.add_development_dependency "rake", "~> 13.0"
   spec.add_development_dependency "webmock"
-  spec.add_development_dependency "activesupport"
 end

data/bin/console

@@ -6,9 +6,5 @@ require "artemis_api"
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.
 
-# (If you use this, don't forget to add pry to your Gemfile!)
-# require "pry"
-# Pry.start
-
-require "irb"
-IRB.start(__FILE__)
+require 'pry'
+Pry.start

data/lib/artemis_api.rb

@@ -11,8 +11,14 @@ require 'artemis_api/discard'
 require 'artemis_api/harvest'
 require 'artemis_api/seeding_unit'
 require 'artemis_api/harvest_unit'
+require 'artemis_api/resource_unit'
+require 'artemis_api/crop_variety'
 require 'artemis_api/item'
 require 'artemis_api/subscription'
+require 'artemis_api/stage'
+require 'artemis_api/sub_stage'
+require 'artemis_api/custom_fields'
+require 'artemis_api/custom_data'
 
 module ArtemisApi
   # Your code goes here...

data/lib/artemis_api/batch.rb

@@ -4,20 +4,22 @@ module ArtemisApi
     related_to_one :zone
     related_to_one :seeding_unit
     related_to_one :harvest_unit
+    related_to_many :custom_data
+    related_to_many :custom_fields
 
     def self.find(id:, client:, facility_id:, include: nil, force: false)
       client.find_one(self.json_type, id, facility_id: facility_id, include: include, force: force)
     end
 
-    def self.find_all(client:, facility_id:, include: nil, filters: nil)
-      client.find_all(self.json_type, facility_id: facility_id, include: include, filters: filters)
+    def self.find_all(client:, facility_id:, include: nil, filters: nil, page: nil)
+      client.find_all(self.json_type, facility_id: facility_id, include: include, filters: filters, page: page)
     end
 
-    def completions(include: nil)
+    def completions(include: nil, filters: {})
       ArtemisApi::Completion.find_all(facility_id: facility_id,
                                       client: client,
                                       include: include,
-                                      filters: {crop_batch_ids: [id]})
+                                      filters: {crop_batch_ids: [id]}.with_indifferent_access.merge(filters))
     end
 
     def completion(completion_id, include: nil)

data/lib/artemis_api/client.rb

@@ -1,38 +1,82 @@
 module ArtemisApi
   class Client
     require 'oauth2'
-    attr_reader :options, :objects, :access_token, :refresh_token, :oauth_client,
-                :oauth_token, :expires_at
+    attr_reader :options, :objects,
+                :oauth_client, :oauth_token,
+                :access_token, :refresh_token, :expires_at,
+                :on_token_refreshed, :on_token_failed
+
+    def initialize(
+      access_token: nil,
+      refresh_token: nil,
+      expires_at: nil,
+      auth_code: nil,
+      redirect_uri: nil,
+      on_token_refreshed: nil,
+      on_token_failed: nil,
+      options: {}
+    )
+      unless (access_token && refresh_token && expires_at) || auth_code
+        raise ArgumentError.new('You must either provide your access token, refresh token & expires at time, or an authorization code.')
+      end
 
-    def initialize(access_token:, refresh_token:, expires_at:, options: {})
       options[:app_id] ||= ENV['ARTEMIS_OAUTH_APP_ID']
       options[:app_secret] ||= ENV['ARTEMIS_OAUTH_APP_SECRET']
       options[:base_uri] ||= ENV['ARTEMIS_BASE_URI']
       @options = options
-      @access_token = access_token
-      @refresh_token = refresh_token
-      @expires_at = expires_at
+      @objects = {}
+
+      @on_token_refreshed = on_token_refreshed
+      @on_token_failed = on_token_failed
 
       @oauth_client = OAuth2::Client.new(@options[:app_id], @options[:app_secret], site: @options[:base_uri])
-      @oauth_token = OAuth2::AccessToken.from_hash(
-                      oauth_client,
-                      {access_token: @access_token,
-                       refresh_token: @refresh_token,
-                       expires_at: @expires_at})
-      @objects = {}
+
+      if auth_code
+        redirect_uri ||= 'urn:ietf:wg:oauth:2.0:oob'
+
+        @oauth_token = @oauth_client.auth_code.get_token(auth_code, redirect_uri: redirect_uri)
+
+        @access_token = @oauth_token.token
+        @refresh_token = @oauth_token.refresh_token
+        @expires_at = @oauth_token.expires_at
+      else
+        set_oauth_token_from_parts(
+          access_token: access_token,
+          refresh_token: refresh_token,
+          expires_at: expires_at
+        )
+      end
+    end
+
+    def set_oauth_token_from_parts(access_token:, refresh_token:, expires_at:)
+      if access_token && refresh_token && expires_at
+        @access_token = access_token
+        @refresh_token = refresh_token
+        @expires_at = expires_at.to_i
+
+        @oauth_token = OAuth2::AccessToken.from_hash(
+                        oauth_client,
+                        {access_token: @access_token,
+                        refresh_token: @refresh_token,
+                        expires_at: @expires_at})
+      end
     end
 
     def find_one(type, id, facility_id: nil, include: nil, force: false)
       obj = get_record(type, id)
       if !obj || force
-        refresh if @oauth_token.expired?
+        auto_refresh!
+
+        path = if facility_id
+                 "/api/v3/facilities/#{facility_id}/#{type}/#{id}"
+               else
+                 "/api/v3/#{type}/#{id}"
+               end
 
-        url = if facility_id
-                "#{@options[:base_uri]}/api/v3/facilities/#{facility_id}/#{type}/#{id}"
-              else
-                "#{@options[:base_uri]}/api/v3/#{type}/#{id}"
-              end
-        url = "#{url}?include=#{include}" if include
+        query = {}
+        query[:include] = include if include
+
+        url = build_url(path: path, query: URI.encode_www_form(query))
 
         response = @oauth_token.get(url)
         obj = process_response(response, type) if response.status == 200
@@ -40,23 +84,24 @@ module ArtemisApi
       obj
     end
 
-    def find_all(type, facility_id: nil, batch_id: nil, include: nil, filters: nil)
+    def find_all(type, facility_id: nil, batch_id: nil, include: nil, filters: nil, page: nil)
       records = []
-      refresh if @oauth_token.expired?
-
-      url = if facility_id && batch_id
-              "#{@options[:base_uri]}/api/v3/facilities/#{facility_id}/batches/#{batch_id}/#{type}"
-            elsif facility_id && batch_id.nil?
-              "#{@options[:base_uri]}/api/v3/facilities/#{facility_id}/#{type}"
-            else
-              "#{@options[:base_uri]}/api/v3/#{type}"
-            end
-
-      url = "#{url}?include=#{include}" if include
-      if filters
-        formatted_filters = format_filters(filters)
-        url = (include) ? "#{url}&#{formatted_filters}" : "#{url}?#{formatted_filters}"
-      end
+      auto_refresh!
+
+      path = if facility_id && batch_id
+               "/api/v3/facilities/#{facility_id}/batches/#{batch_id}/#{type}"
+             elsif facility_id && batch_id.nil?
+               "/api/v3/facilities/#{facility_id}/#{type}"
+             else
+               "/api/v3/#{type}"
+             end
+
+      query = {}
+      query[:include] = include if include
+      format_filters(filters, query) if filters
+      format_pagination(page, query) if page
+
+      url = build_url(path: path, query: URI.encode_www_form(query))
 
       response = @oauth_token.get(url)
       if response.status == 200
@@ -65,21 +110,44 @@ module ArtemisApi
       records
     end
 
-    def store_record(type, id, data)
+    def build_url(path:, query: nil)
+      uri = URI::Generic.build(path: path, query: query)
+      @options[:base_uri] + uri.to_s
+    end
+
+    def store_record(type, id, data, included = nil)
       @objects[type] ||= {}
-      @objects[type][id.to_i] = ArtemisApi::Model.instance_for(type, data, self)
+      @objects[type][id.to_i] = ArtemisApi::Model.instance_for(type, data, included, self)
     end
 
     def get_record(type, id)
-      @objects[type]&.[](id.to_i)
+      @objects.dig(type, id.to_i)
     end
 
     def remove_record(type, id)
-      @objects[type].delete(id.to_i)
+      @objects[type]&.delete(id.to_i)
+    end
+
+    def auto_refresh!
+      refresh! if @oauth_token.expired?
     end
 
-    def refresh
+    def refresh!
+      old_refresh_token = @oauth_token.refresh_token
+
       @oauth_token = @oauth_token.refresh!
+
+      if old_refresh_token != @oauth_token.refresh_token
+        on_token_refreshed && on_token_refreshed.call(self, @oauth_token, old_refresh_token)
+      end
+      @oauth_token
+    rescue OAuth2::Error => err
+      if on_token_failed
+        on_token_failed.call(self, @oauth_token, err)
+        @oauth_token
+      else
+        raise err
+      end
     end
 
     def facilities(include: nil)
@@ -104,8 +172,8 @@ module ArtemisApi
 
     def process_response(response, type)
       json = JSON.parse(response.body)
-      obj = store_record(type, json['data']['id'].to_i, json['data'])
-      process_included_objects(json['included']) if json['included']
+      included = process_included_objects(json['included']) if json['included']
+      obj = store_record(type, json['data']['id'].to_i, json['data'], included)
 
       obj
     end
@@ -118,29 +186,41 @@ module ArtemisApi
         record = store_record(type, obj['id'], obj)
         records << record
       end
+
       process_included_objects(json['included']) if json['included']
 
       records
     end
 
     def process_included_objects(included_array)
+      included = {}
       included_array.each do |included_obj|
-        store_record(included_obj['type'], included_obj['id'], included_obj)
+        type = included_obj['type']
+        obj = store_record(type, included_obj['id'], included_obj)
+
+        next unless obj
+
+        included[type.to_sym] = [] unless included.key?(type.to_sym)
+        included[type.to_sym].push(obj)
       end
+
+      included
     end
 
-    def format_filters(filter_hash)
-      filter_string = ''
+    def format_filters(filter_hash, query_hash)
       filter_hash.each do |k, v|
-        if v.kind_of?(Array)
-          v.each do |item|
-            filter_string += "filter[#{k}][]=#{item}&"
-          end
+        if v.is_a?(Array)
+          query_hash[:"filter[#{k}][]"] = v
         else
-          filter_string += "filter[#{k}]=#{v}&"
+          query_hash[:"filter[#{k}]"] = v
         end
       end
-      filter_string
+    end
+
+    def format_pagination(page_hash, query_hash)
+      page_hash.each do |k, v|
+        query_hash[:"page[#{k}]"] = v
+      end
     end
   end
 end