reso_api 1.5.13 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c60f3b7a93a8fdff58458cb3ceedc48021d007bf88c65fc81455fde74002da9e
-  data.tar.gz: 97509b32ddd67a2d5ee5857d25fb322e55f3d1e3cb4246c451c0b02f1865fd36
+  metadata.gz: 152e24a12afdb9af2c9385a365335df67b58704676b313c886a1833417ae8763
+  data.tar.gz: 88ca57e2199877808138e07f96999376541c40a138b90a920bf56940e786d212
 SHA512:
-  metadata.gz: eaa3ebf09faee81c40d59063d77468e716f14377a6ae3fd5bb8b59423831b7c3008b0d968cf91962948d828150680caadb7c4fc5f3a2997fa7710527dae9e2b3
-  data.tar.gz: 196d66437d0ceb577aa3521fb2bee7ae7fb996c2a3b46520ee5ea7268d2cda33751744c314939f57c1676db8657942a52d12f1711ace54e55c7010cef318fcc2
+  metadata.gz: 0e5c6750cddd94f0dc296e64baf3d008157754360c58c2350feb5df96fa4301f272ad4c1b81a3f20b809523bd16858fc018e38e0a190f71eb2b10f6b2b0552d5
+  data.tar.gz: 1a21eb60cd03e7e39a6cd33123f7635dd194f1cd4bb2e03d326788fecdc187316e9bfc79469f60847fe7d013d286611ef8e4dee49d0524a37d5b2bd3e1814912

data/README.md

@@ -26,23 +26,47 @@ Or install it yourself as:
 
 ### Authentication and Access
 
-To set up an API client and access a service, you need three pieces of information:
+This gem supports two types of authentication:
+
+- OAuth2
+- Access Token
+
+#### OAuth2
+
+To set up an API client using OAuth2 authentication, you need four pieces of information:
 
 - Client ID
 - Client Secret
-- Base API endpoint
 - Authentication URL
+- Base URL
+- Scope
 
-You'll recognize the base API endpoint by it ending with /odata, and the authentication URL by it likely ending with /token.
+Often, the base URL ends with `/odata`, and the authentication URL often ends with `/token`.
+
+Scope defaults to "api" and only needs to be included if it is "OData" or something else.
 
 You pass these four pieces of information to create an instance of an API client:
 
 ```ruby
-client = RESO::API::Client.new(client_id: client_id, client_secret: client_secret, auth_url: auth_url, base_url: base_url)
+client = RESO::API::Client.new(client_id: client_id, client_secret: client_secret, auth_url: auth_url, base_url: base_url, scope: scope)
 ```
 
 When calling API endpoints using the initialized client, it will automatically fetch and manage access and authentication tokens transparently in the background.
 
+#### Access Token
+
+Some systems, like MLSGRID and Spark/Flexmls provides a persistent Access Token. In these cases, you need these two pieces of information to set up an API client:
+
+- Access Token
+- Base API endpoint
+
+You pass these two pieces of information to create an instance of an API client:
+
+```ruby
+client = RESO::API::Client.new(access_token: access_token, base_url: base_url)
+```
+
+
 ### Resources
 
 #### Supported Resources

data/lib/reso_api/app/models/reso/api/client.rb

@@ -7,18 +7,22 @@ module RESO
       require 'json'
       require 'tmpdir'
 
-      attr_accessor :client_id, :client_secret, :auth_url, :base_url
+      attr_accessor :access_token, :client_id, :client_secret, :auth_url, :base_url, :scope
 
       def initialize(**opts)
-        @client_id, @client_secret, @auth_url, @base_url = opts.values_at(:client_id, :client_secret, :auth_url, :base_url)
+        @access_token, @client_id, @client_secret, @auth_url, @base_url, @scope = opts.values_at(:access_token, :client_id, :client_secret, :auth_url, :base_url, :scope)
         validate!
       end
 
       def validate!
-        raise 'Missing Client ID `client_id`' if client_id.nil?
-        raise 'Missing Client Secret `client_secret`' if client_secret.nil?
-        raise 'Missing Authentication URL `auth_url`' if auth_url.nil?
-        raise 'Missing API Base URL `base_url`' if base_url.nil?
+        if access_token.nil?
+          raise 'Missing Client ID `client_id`' if client_id.nil?
+          raise 'Missing Client Secret `client_secret`' if client_secret.nil?
+          raise 'Missing Authentication URL `auth_url`' if auth_url.nil?
+          raise 'Missing API Base URL `base_url`' if base_url.nil?
+        else
+          raise 'Missing API Base URL `base_url`' if base_url.nil?
+        end
       end
 
       RESOURCE_KEYS = {
@@ -96,12 +100,16 @@ module RESO
         end
       end
 
+      def auth_token
+        access_token.presence ? access_token : oauth2_token
+      end
+
       def oauth2_client
         OAuth2::Client.new(
           client_id,
           client_secret,
           token_url: auth_url,
-          scope: "api",
+          scope: scope.presence || "api",
           grant_type: "client_credentials"
         )
       end
@@ -120,7 +128,7 @@ module RESO
       end
 
       def fresh_oauth2_payload
-        @oauth2_payload = oauth2_client.client_credentials.get_token('client_id' => client_id, 'client_secret' => client_secret)
+        @oauth2_payload = oauth2_client.client_credentials.get_token('client_id' => client_id, 'client_secret' => client_secret, 'scope' => scope || "api")
         File.write(oauth2_token_path, @oauth2_payload.to_hash.to_json)
         return @oauth2_payload
       end
@@ -138,7 +146,7 @@ module RESO
           persisted = File.read(oauth2_token_path)
           payload = OAuth2::AccessToken.from_hash(oauth2_client, JSON.parse(persisted))
         else
-          payload = oauth2_client.client_credentials.get_token('client_id' => client_id, 'client_secret' => client_secret)
+          payload = oauth2_client.client_credentials.get_token('client_id' => client_id, 'client_secret' => client_secret, 'scope' => scope || "api")
           File.write(oauth2_token_path, payload.to_hash.to_json)
         end
         return payload
@@ -158,7 +166,7 @@ module RESO
         end
         begin
           req = Net::HTTP::Get.new(uri.request_uri)
-          req['Authorization'] = "Bearer #{oauth2_token}"
+          req['Authorization'] = "Bearer #{auth_token}"
           res = Net::HTTP.start(uri.host, uri.port, :use_ssl => uri.scheme == 'https') do |http|
             http.request(req)
           end
@@ -171,7 +179,7 @@ module RESO
             fresh_oauth2_payload
             raise StandardError
           elsif response.is_a?(Hash) && response.has_key?("error")
-            puts "Error."
+            puts "Error: #{response.inspect}"
             raise StandardError
           elsif response.is_a?(Hash) && response.has_key?("retry-after")
             puts "Error: Retrying in #{response["retry-after"].to_i}} seconds."

data/lib/reso_api/version.rb

@@ -1,3 +1,3 @@
 module ResoApi
-  VERSION = "1.5.13"
+  VERSION = "1.7.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: reso_api
 version: !ruby/object:Gem::Version
-  version: 1.5.13
+  version: 1.7.0
 platform: ruby
 authors:
 - Michael Edlund
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-07-17 00:00:00.000000000 Z
+date: 2024-04-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -123,7 +123,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.16
+rubygems_version: 3.5.9
 signing_key:
 specification_version: 4
 summary: RESO Web API Wrapper