reso_api 1.7.2 → 1.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e12a31adb8cbc929ae74c0bac420887da8012d1a2b9383a4559dbf23b1bfd448
-  data.tar.gz: '09c9ef38dc896767bfd6078bab372a9f3408a5ddda293690324122c28b7abfa0'
+  metadata.gz: def7ded4fa254b441abf784360b9aa28e08b05a2816a8bcab0a080ea992ca782
+  data.tar.gz: b27d1bb6c7364617ae5e66812935fdd16baad1f3c1f8959ea126e03c4d20446d
 SHA512:
-  metadata.gz: 74c3d7f5312b9aed8f39887a4e63f40e4a8a15026d50f4571015682c1932387a0836ff49c061c50f927e445a90411c08559c31bfaa34c5c5f2d4592e73d46275
-  data.tar.gz: abf99e623fc41c01d3725c4ac5cdddc0b3ffdd3e1f81024196ea48504a3ae4281109b0227626225d85533535e865506cf77557e8b2d4056f84dafa8446288b7f
+  metadata.gz: d758d60a2503c6a61edfd6fb1768bbc39cf31551ce5e312d364f7b47403df76ef98ad6211b79f93896ce939e139bb82a3a3dcd989bd980075480961d2688b099
+  data.tar.gz: 7ec8e7ec83bfd82538fe652efbcd03ab9b725f83a0c72a3ecb65b113fcd3810cf7446d9081899ac8ed85dd582b0d43a5dca901dad69f164d04f69aa10c7fed6c

data/README.md

@@ -39,16 +39,22 @@ To set up an API client using OAuth2 authentication, you need four pieces of inf
 - Client Secret
 - Authentication URL
 - Base URL
-- Scope
 
 Often, the base URL ends with `/odata`, and the authentication URL often ends with `/token`.
 
+There are two additional pieces of information that are not required:
+
+- Scope
+- Originating System Name (OSN)
+
 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:
+Some MLS systems require Originating System Name to be included in requests.
+
+You pass these 4—6 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, scope: scope)
+client = RESO::API::Client.new(client_id: client_id, client_secret: client_secret, auth_url: auth_url, base_url: base_url, scope: scope, osn: osn)
 ```
 
 When calling API endpoints using the initialized client, it will automatically fetch and manage access and authentication tokens transparently in the background.
@@ -127,14 +133,17 @@ client.properties(filter: "StandardStatus eq 'Active' and BrokerName eq 'Doe Bro
 ```
 RESO Web API is built on the OData standard, but only requires compliant servers to support a subset of queries:
 
-| Operator   | Description            | Example                      |
-|------------|------------------------|------------------------------|
-|    `eq`    | Equals                 | `StandardStatus eq 'Active'` |
-|    `ne`    | Not equals             | `StandardStatus ne 'Active'` |
-|    `ge`    | Greater than or equals | `ListPrice ge 100000`        |
-|    `gt`    | Greater than           | `ListPrice gt 100000`        |
-|    `le`    | Less than or equals    | `ListPrice le 100000`        |
-|    `lt`    | Less than              | `ListPrice lt 100000`        |
+| Operator   | Description            | Example                                  |
+|------------|------------------------|------------------------------------------|
+|    `eq`    | Equals                 | `StandardStatus eq 'Active'`             |
+|    `ne`    | Not equals             | `StandardStatus ne 'Active'`             |
+|    `in`    | In                     | `StandardStatus in ('Active','Pending')` |
+|    `ge`    | Greater than or equals | `ListPrice ge 100000`                    |
+|    `gt`    | Greater than           | `ListPrice gt 100000`                    |
+|    `le`    | Less than or equals    | `ListPrice le 100000`                    |
+|    `lt`    | Less than              | `ListPrice lt 100000`                    |
+
+Some older MLS systems does not support `in`.
 
 #### $select
 
@@ -161,12 +170,21 @@ client.properties(orderby: "City desc")
 
 #### $expand
 
-$expand in oData is meant to join two resources together. For the Syndication API this means you can bring in photos to any property query.
+$expand in OData is for joining additional resources. For the Syndication API this means you can bring in photos to any property query.
 
 ```ruby
 client.properties(expand: "Media")
 ```
 
+Different MLS systems support different resources to be included in an `$expand` statement. You can query for which resources the system you're integrating with supports:
+
+```ruby
+expandables = client.supported_expandables
+client.properties(expand: expandables)
+```
+
+The `supported_expandables` method is a slow request, so you should store or cache the result of this method to speed up subsequent requests.
+
 #### $ignorenulls
 
 For servers that support it, `$ignorenulls` omits empty keys from the response to reduce data size.
@@ -258,6 +276,7 @@ This gem should work with any RESO Web API compliant service, but these are thos
 - [Constellation1](https://constellation1.com)
 - [CoreLogic Trestle](https://trestle.corelogic.com)
 - [ListHub](https://www.listhub.com)
+- [Spark API](https://www.sparkapi.io)
 
 If you use this gem to connect to another service or MLS, please submit a pull request with that service added in alphabetical order in this list.
 

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

@@ -7,10 +7,10 @@ module RESO
       require 'json'
       require 'tmpdir'
 
-      attr_accessor :access_token, :client_id, :client_secret, :auth_url, :base_url, :scope
+      attr_accessor :access_token, :client_id, :client_secret, :auth_url, :base_url, :scope, :osn
 
       def initialize(**opts)
-        @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)
+        @access_token, @client_id, @client_secret, @auth_url, @base_url, @scope, @osn = opts.values_at(:access_token, :client_id, :client_secret, :auth_url, :base_url, :scope, :osn)
         validate!
       end
 
@@ -159,15 +159,17 @@ module RESO
         return URI(endpoint).host ? URI(endpoint) : URI([base_url, endpoint].join)
       end
 
-      def perform_call(endpoint, params)
+      def perform_call(endpoint, params, max_retries = 5, debug = false)
         uri = uri_for_endpoint(endpoint)
+        params = params.presence || {}
         retries = 0
-        if params.present?
-          query = params.present? ? URI.encode_www_form(params).gsub("+", " ") : ""
-          uri.query && uri.query.length > 0 ? uri.query += '&' + query : uri.query = query
-          return URI::decode(uri.request_uri) if params.dig(:$debug).present?
-        end
-        begin
+
+        params['$filter'] = "OriginatingSystemName eq '#{osn}'" if osn.present?
+        query = params.present? ? URI.encode_www_form(params).gsub("+", " ") : ""
+        uri.query && uri.query.length > 0 ? uri.query += '&' + query : uri.query = query
+        return URI::decode(uri.request_uri) if params.dig(:$debug).present?
+
+          begin
           req = Net::HTTP::Get.new(uri.request_uri)
           req['Authorization'] = "Bearer #{auth_token}"
           res = Net::HTTP.start(uri.host, uri.port, :use_ssl => uri.scheme == 'https') do |http|
@@ -175,23 +177,23 @@ module RESO
           end
           response = JSON(res.body) rescue res.body
           if response.is_a?(String) && response.include?('Bad Gateway')
-            puts "Error: Bad Gateway."
+            puts "Error: Bad Gateway." if debug
             raise StandardError
           elsif response.is_a?(String) && response.include?('Unauthorized')
-            puts "Error: Unauthorized."
+            puts "Error: Unauthorized." if debug
             fresh_oauth2_payload
             raise StandardError
           elsif response.is_a?(Hash) && response.has_key?("error")
-            puts "Error: #{response.inspect}"
+            puts "Error: #{response.inspect}" if debug
             raise StandardError
           elsif response.is_a?(Hash) && response.has_key?("retry-after")
-            puts "Error: Retrying in #{response["retry-after"].to_i}} seconds."
+            puts "Error: Retrying in #{response["retry-after"].to_i}} seconds." if debug
             sleep response["retry-after"].to_i
             raise StandardError
           end
         rescue Net::ReadTimeout, StandardError
-          if (retries += 1) <= 5
-            sleep 10
+          if (retries += 1) <= max_retries
+            sleep 5
             retry
           else
             raise
@@ -200,6 +202,33 @@ module RESO
         return response
       end
 
+      def entity_names
+        doc = Nokogiri::XML(metadata)
+        namespace = { 'edm' => 'http://docs.oasis-open.org/odata/ns/edm' }
+        doc.xpath('//edm:EntityType', namespace).map { |node| node['Name'] }
+      end
+
+      def supported_expandables
+        expandables_arr = []
+
+        entity_names.each do |entity_name|
+          success = try_expand(entity_name)
+          expandables_arr << entity_name if success
+        end
+
+        expandables_arr.join(',').presence
+      end
+
+      def try_expand(entity_name)
+        endpoint = '/Property'
+        params = { '$expand' => entity_name }
+        params['$filter'] = "OriginatingSystemName eq '#{osn}'" if osn.present?
+
+        response = perform_call(endpoint, params, max_retries = 0)
+        (!response.is_a?(Hash) || !response.key?('error')) && response['statusCode'].blank?
+      rescue StandardError
+        false
+      end
     end
   end
 end

data/lib/reso_api/version.rb

@@ -1,3 +1,3 @@
 module ResoApi
-  VERSION = "1.7.2"
+  VERSION = "1.8.1"
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: reso_api
 version: !ruby/object:Gem::Version
-  version: 1.7.2
+  version: 1.8.1
 platform: ruby
 authors:
 - Michael Edlund
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-04-24 00:00:00.000000000 Z
+date: 2025-03-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -108,7 +107,6 @@ files:
 homepage: https://github.com/arcticleo/reso_api
 licenses: []
 metadata: {}
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -123,8 +121,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.9
-signing_key:
+rubygems_version: 3.6.2
 specification_version: 4
 summary: RESO Web API Wrapper
 test_files: []