reso_transport 1.5.2 → 1.5.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f1ae4fd99eee1b55b80dd22982d070081a49be756e7495e49536bd887fc231c2
-  data.tar.gz: c711e2c0c848fd96b3837d4dbdf1629e6d05a5bd49192f815a1c917c4b72dda4
+  metadata.gz: 91e46c54493b29b1afd7cf10e4193209a6f91692494f5d5f9b35c48e176f0e50
+  data.tar.gz: 5778db15cafacd613b1262c88434c4f484e508da600d62d7ef960ea3a4e6e1c5
 SHA512:
-  metadata.gz: c745d382e1cfa925562d318736b8c154e81db511ec4456360e57358230edd118e46a421b249f7404087b4557fd7935371870e78aeb49b3731661fa6be57793a4
-  data.tar.gz: c9affa40ce40bd80f90f3f2aed2128687ce4eb0b3b3092d6ad69aa569293f6afd8a64d7aaaebc70257de83b7d4452ad3ac7e52f35ce1fc1d819a1a270d30cbbe
+  metadata.gz: 140b63e766d92ec632abf864803dd7a6beffde76069b5f9cec4b7f37f0c659b437a15b3b47bbde9692cf84070276e5d189520fbb45c35c7edc8af7396ed86ff6
+  data.tar.gz: 17525cbd4fb045a43b5c14082fd076f7798ff7d3abede002e36efecb85a526d5ab4b245d77c2cd08dc191942b7cf0b572979339c51bdda518061c209f889155a

data/.gitignore

@@ -13,5 +13,7 @@
 /log/**
 /test/vcr_cassettes/**
 md_cache/**
+ds_cache/**
 .byebug_history
 secrets.yml
+/.history/

data/.gitpod.yml

@@ -0,0 +1,2 @@
+tasks:
+  - init: bundle install

data/.rubocop.yml

@@ -0,0 +1,33 @@
+AllCops:
+  TargetRubyVersion: 2.6
+
+Layout/FirstHashElementIndentation:
+  Enabled: false
+
+Layout/MultilineMethodCallIndentation:
+  Enabled: false
+
+Metrics/AbcSize:
+  Max: 20
+
+Metrics/BlockLength:
+  Exclude:
+    - test/**/*
+
+Metrics/ClassLength:
+  Max: 150
+
+Metrics/MethodLength:
+  Max: 15
+
+Metrics/ModuleLength:
+  Max: 150
+
+Style/ColonMethodCall:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Style/FrozenStringLiteralComment:
+  Enabled: false

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    reso_transport (1.5.1)
+    reso_transport (1.5.5)
       faraday (~> 1.0.1)
 
 GEM

data/README.md

@@ -1,3 +1,6 @@
+[![Gitpod ready-to-code](https://img.shields.io/badge/Gitpod-ready--to--code-blue?logo=gitpod)](https://gitpod.io/#https://github.com/wrstudios/reso_transport)
+[![Gem Version](https://badge.fury.io/rb/reso_transport.svg)](https://badge.fury.io/rb/reso_transport)
+
 # ResoTransport
 
 A Ruby gem for connecting to and interacting with RESO WebAPI services.  Learn more about what that is by checking out the [RESO WebAPI](https://www.reso.org/reso-web-api/) Documentation.
@@ -51,7 +54,7 @@ Or you can set a logger for each specific instance of a client which can be usef
 
 ### Getting Connected
 
-There are 2 strategies for authentication. 
+There are 2 strategies for authentication.
 
 **Bearer Token**
 
@@ -60,7 +63,8 @@ It's simple to use a static access token if your token never expires:
 ```ruby
   @client = ResoTransport::Client.new({
     md_file: METADATA_CACHE,
-    endpoint: ENDPOINT_URL
+    endpoint: ENDPOINT_URL,
+    use_replication_endpoint: false # this is the default and can be ommitted
     authentication: {
       access_token: TOKEN,
       token_type: "Bearer" # this is the default and can be ommitted
@@ -82,13 +86,72 @@ If the connection requires requesting a new token periodically, it's easy to pro
       client_id: CLIENT_ID,
       client_secret: CLIENT_SECRET,
       grant_type: "client_credentials", # these are the default and can be ommitted
-      scope: "api"                      # 
+      scope: "api"
     }
   })
 ```
 
 This will pre-fetch a token from the provided endpoint when the current token is either non-existent or has expired.
 
+The `use_replication_endpoint` flag will append `/replication` to all resource queries if set to `true`. This is required
+by some data sources to query resources beyond 10,000 records.
+
+### Caching Metadata
+
+The metadata file itself is large and parsing it is slow, so ResoTransport has built in support for caching the metadata to your file system. In the example above
+you would replace `METADATA_CACHE` with a path to a file to store the metadata.
+
+```
+  md_file: "reso_md_cache/#{@mls.name}",
+```
+
+This will store the metadata to a file with `@mls.name` in a folder named `reso_md_cache` in the relative root of your app.
+
+**Customize your cache**
+
+If you don't have access to the file system, like on Heroku, or you just don't want to store the metadata on the file system, you can provide your down metadata cache class.
+
+```ruby
+class MyCacheStore < ResoTransport::MetadataCache
+
+  def read
+    # read `name` from somewhere
+  end
+
+  def write(data)
+    # write `name` with `data` somewhere
+    # return an IO instance
+  end
+
+end
+```
+
+The metadata parser expects to recieve an IO instance so just make sure your `read` and `write` methods return one.
+
+And you can instruct the client to use that cache store like so:
+
+```
+  md_file: "reso_md_cache/#{@mls.name}",
+  md_cache: MyCacheStore
+```
+
+
+**Skip cache altogether**
+
+Caching the metadata is not actually required, just be aware that it will be much slower. To skip caching just omit the related keys
+when instantiating a new Client.
+
+```ruby
+  @client = ResoTransport::Client.new({
+    endpoint: ENDPOINT_URL
+    authentication: {
+      endpoint: AUTH_ENDPOINT,
+      client_id: CLIENT_ID,
+      client_secret: CLIENT_SECRET,
+    }
+  })
+```
+
 
 ### Resources
 
@@ -100,12 +163,25 @@ Once you have a successful connection you can explore what resources are availab
   #=> {"Property"=>#<ResoTransport::Resource entity_set="Property", schema="ODataService">, "Office"=>#<ResoTransport::Resource entity_set="Office", schema="ODataService">, "Member"=>#<ResoTransport::Resource entity_set="Member", schema="ODataService">}
 
   @client.resources["Property"]
-  #=> #<ResoTransport::Resource entity_set="Property", schema="ODataService"> 
+  #=> #<ResoTransport::Resource entity_set="Property", schema="ODataService">
 
   @client.resources["Property"].query.limit(1).results
   #=> Results Array
 ```
 
+If the resource contains localizations you can access those as well.
+
+```ruby
+@client.resources["Property"].localizations
+#=> {"CommercialSale"=>{"Name"=>"CommercialSale", "ResourcePath"=>"/Property?Class=CommercialSale", "Description"=>"Contains data for Commercial searches.", "DateTimeStamp"=>"2021-05-03T18:13:20.643-07:00"}, "Residential"=>{"Name"=>"Residential", "ResourcePath"=>"/Property?Class=Residential", "Description"=>"Contains data for Residential searches.", "DateTimeStamp"=>"2021-05-03T18:13:20.643-07:00"}}
+```
+
+If a resource contains localizations you must select one by name, before querying, like so:
+
+```ruby
+@client.resources["Property"].localization('Residential').query.limit(1).results
+```
+
 #### Querying
 
 ResoTransport provides powerful querying capabilities:
@@ -138,7 +214,7 @@ To see what child records can be expanded look at `expandable`:
 
 ```ruby
   @resource.expandable
-  #=> [#<struct ResoTransport::Property name="Media", data_type="Collection(RESO.Media)", attrs={"Name"=>"Media", "Type"=>"Collection(RESO.Media)"}, multi=true, enum=nil, complex_type=nil, entity_type=#<struct ResoTransport::EntityType name="Media", base_type=nil, primary_key="MediaKey", schema="CoreLogic.DataStandard.RESO.DD">> ...] 
+  #=> [#<struct ResoTransport::Property name="Media", data_type="Collection(RESO.Media)", attrs={"Name"=>"Media", "Type"=>"Collection(RESO.Media)"}, multi=true, enum=nil, complex_type=nil, entity_type=#<struct ResoTransport::EntityType name="Media", base_type=nil, primary_key="MediaKey", schema="CoreLogic.DataStandard.RESO.DD">> ...]
 ```
 
 Use `expand` to expand child records with the top level results.
@@ -152,7 +228,7 @@ You have several options to expand multiple child record sets. Each of these wil
 
 ```ruby
   @resource.query.expand("Media", "Office").limit(10).results
-  
+
   @resource.query.expand(["Media", "Office"]).limit(10).results
 
   @resource.query.expand("Media").expand("Office").limit(10).results
@@ -199,9 +275,22 @@ When querying for an enumeration value, you can provide either the system name,
 
 ```ruby
   @resource.query.eq(StandardStatus: "Active Under Contract").limit(1).compile_params
-  #=> {"$top"=>1, "$filter"=>"StandardStatus eq 'ActiveUnderContract'"} 
+  #=> {"$top"=>1, "$filter"=>"StandardStatus eq 'ActiveUnderContract'"}
 ```
 
+### Troubleshooting
+
+In the event there are connection issues, the following errors are raised:
+
+* `ResoTransport::NoResponse` - The server did not respond to the request
+* `ResoTransport::RequestError` - The server responded with a status code outside the 200 range
+* `ResoTransport::ResponseError` - The server responded with errors in the body
+* `ResoTransport::AccessDenied` - Check your authentication details
+* `ResoTransport::LocalizationRequired` - Provide one of the required localizations through the `localization` method
+* `ResoTransport::EncodeError` - No match was found for one or more of the properties
+
+The Faraday Request hash is attached to the error for `NoResponse`, `RequestError`, `ResponseError`, and `AccessDenied`.  A Faraday Response is attached on `RequestError`, `ResponseError`, and `AccessDenied`.
+
 ## 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/bin/console

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 
-require "bundler/setup"
-require "reso_transport"
+require 'bundler/setup'
+require 'reso_transport'
 
 # 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.
@@ -12,19 +12,19 @@ require "reso_transport"
 #
 
 ResoTransport.configure do |c|
-  c.logger = Logger.new("log/console.log")
+  c.logger = Logger.new('log/console.log')
 end
 
-
-require "irb"
+require 'irb'
 require 'yaml'
 require 'byebug'
 
-SECRETS = YAML.load_file("secrets.yml")
+SECRETS = YAML.load_file('secrets.yml')
 
-@trestle = ResoTransport::Client.new(SECRETS[:trestle].merge(logger: Logger.new($stdout)))
-@bridge = ResoTransport::Client.new(SECRETS[:bridge].merge(logger: Logger.new($stdout)))
-# @spark = ResoTransport::Client.new(SECRETS[:spark])
-@crmls = ResoTransport::Client.new(SECRETS[:crmls])
+SECRETS.each do |name, data|
+  data[:logger] = Logger.new($stdout)
+  client = ResoTransport::Client.new(data)
+  instance_variable_set("@#{name}", client)
+end
 
 IRB.start(__FILE__)

data/bin/rake

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rake' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path("../bundle", __FILE__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("rake", "rake")

data/lib/reso_transport.rb

@@ -5,40 +5,28 @@ require 'faraday'
 require 'json'
 require 'time'
 
-require "reso_transport/version"
-require "reso_transport/configuration"
-require "reso_transport/authentication"
-require "reso_transport/client"
-require "reso_transport/resource"
-require "reso_transport/metadata"
-require "reso_transport/metadata_parser"
-require "reso_transport/schema"
-require "reso_transport/entity_set"
-require "reso_transport/entity_type"
-require "reso_transport/enum"
-require "reso_transport/property"
-require "reso_transport/query"
-
-
-
-# module Faraday
-#   module Utils
-
-#     def escape(str)
-#       str.to_s.gsub(ESCAPE_RE) do |match|
-#         '%' + match.unpack('H2' * match.bytesize).join('%').upcase
-#       end.gsub(" ","%20")
-
-#     end
-#   end
-# end
-
-Faraday::Utils.default_space_encoding = "%20"
+require 'reso_transport/version'
+require 'reso_transport/configuration'
+require 'reso_transport/authentication'
+require 'reso_transport/client'
+require 'reso_transport/resource'
+require 'reso_transport/metadata'
+require 'reso_transport/metadata_cache'
+require 'reso_transport/metadata_parser'
+require 'reso_transport/datasystem'
+require 'reso_transport/datasystem_parser'
+require 'reso_transport/schema'
+require 'reso_transport/entity_set'
+require 'reso_transport/entity_type'
+require 'reso_transport/enum'
+require 'reso_transport/property'
+require 'reso_transport/query'
+require 'reso_transport/errors'
+
+Faraday::Utils.default_space_encoding = '%20'
 
 module ResoTransport
-  class Error < StandardError; end
-  class AccessDenied < StandardError; end
-  ODATA_TIME_FORMAT = "%Y-%m-%dT%H:%M:%S%Z"
+  ODATA_TIME_FORMAT = '%Y-%m-%dT%H:%M:%SZ'.freeze
 
   class << self
     attr_writer :configuration
@@ -52,8 +40,7 @@ module ResoTransport
     yield(configuration)
   end
 
-  def self.split_schema_and_class_name(s)
-    s.partition(/(\w+)$/).first(2).map {|s| s.sub(/\.$/, '') }
+  def self.split_schema_and_class_name(text)
+    text.to_s.partition(/(\w+)$/).first(2).map { |s| s.sub(/\.$/, '') }
   end
-
 end

data/lib/reso_transport/authentication/fetch_token_auth.rb

@@ -1,48 +1,71 @@
 module ResoTransport
   module Authentication
     class FetchTokenAuth < AuthStrategy
-      attr_reader :connection, :endpoint, :client_id, :client_secret, :grant_type, :scope
-      
+      attr_reader :endpoint,
+                  :client_id,
+                  :client_secret,
+                  :grant_type,
+                  :scope,
+                  :username,
+                  :password
+
       def initialize(options)
-        @grant_type    = options.fetch(:grant_type, "client_credentials")
-        @scope         = options.fetch(:scope, "api")
+        super()
+
+        @grant_type    = options.fetch(:grant_type, 'client_credentials')
+        @scope         = options.fetch(:scope, 'api')
         @client_id     = options.fetch(:client_id)
         @client_secret = options.fetch(:client_secret)
         @endpoint      = options.fetch(:endpoint)
+        @username      = options.fetch(:username, nil)
+        @password      = options.fetch(:password, nil)
+        @request       = nil
+      end
 
-        @connection = Faraday.new(@endpoint) do |faraday|
+      def connection
+        @connection ||= Faraday.new(@endpoint) do |faraday|
           faraday.request  :url_encoded
           faraday.response :logger, ResoTransport.configuration.logger if ResoTransport.configuration.logger
           faraday.adapter Faraday.default_adapter
-          faraday.basic_auth @client_id, @client_secret
+          faraday.basic_auth client_id, client_secret
         end
       end
 
       def authenticate
-        response = connection.post nil, auth_params
+        response = connection.post(nil, auth_params { |req| @request = req })
         json = JSON.parse response.body
 
-        unless response.success?
-          message = "#{response.reason_phrase}: #{json['error'] || response.body}"
-          raise ResoTransport::AccessDenied, response: response, message: message
-        end
+        raise AccessDenied.new(request, response, 'token') unless response.success?
 
         Access.new({
           access_token: json.fetch('access_token'),
           expires_in: json.fetch('expires_in', 1 << (1.size * 8 - 2) - 1),
-          token_type: json.fetch('token_type', "Bearer")
+          token_type: json.fetch('token_type', 'Bearer')
         })
       end
 
+      def request
+        return @request.to_h if @request.respond_to? :to_h
+
+        {}
+      end
+
       private
 
       def auth_params
-        {
-          client_id:     client_id,
+        params = {
+          client_id: client_id,
           client_secret: client_secret,
-          grant_type:    grant_type,
-          scope:         scope
+          grant_type: grant_type,
+          scope: scope
         }
+
+        if grant_type == 'password'
+          params[:username] = username
+          params[:password] = password
+        end
+
+        params
       end
     end
   end