reso_transport 1.5.1 → 1.5.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3d0f1d48b90a3fac473d2fc548626f619a1389814fe476db23bb0e12113ee84d
-  data.tar.gz: 0a61cdc9750832111812de93441beafe29bef47059841e7ea41105589c673373
+  metadata.gz: 49293478c0827ccb4bdca1bb6c9974900f8c0c16853b247487120a0ed3bb79df
+  data.tar.gz: c9d8c93979377ed18d22a179bae44175961b44e8641eb091930f99542d1e610f
 SHA512:
-  metadata.gz: 96b56e7e821e978b4ff48f9023d82901c4449eb820f3b0ab82e9faa187b8c7e547dbef679a396c6385202f713aeaf8c446e2d1338b46e2c09f32632ab6e04d6a
-  data.tar.gz: c054fa510a18b072a4e98505d48d73fb9bde7c06e3294aaafe9fcf7c28b94cd0ffb0e51019ea5b6b6630783584bcbde5e49a4abfa0d9fecebb45567bcab79308
+  metadata.gz: 4464fe0a9aa0006f25c5eab29dab8422401ac2ebf435b712e65d5727e43606bb0df4fdf895e5a1d6a1e3e44d4937d19c42389577d28568351832ccae64d55ebb
+  data.tar.gz: 729d643455ddd8e7a827ddc6aea2a8512f93bc65a3e469993da5d2cd5085ecdc5eed4befee4f376cd9986f51a81d363fdeb042a1f8f51e2e51d7230f265c2d7a

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,7 +275,7 @@ 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'"}
 ```
 
 ## Development

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,30 @@ 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'
+
+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 +42,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,20 +1,32 @@
 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)
+      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
 
@@ -30,19 +42,26 @@ module ResoTransport
         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
 
       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

data/lib/reso_transport/base_metadata.rb

@@ -0,0 +1,61 @@
+module ResoTransport
+  class BaseMetadata
+    MIME_TYPES = {
+      xml: 'application/xml',
+      json: 'application/json'
+    }.freeze
+
+    attr_reader :client
+
+    def initialize(client)
+      @client = client
+      @prefix = nil
+      @classname = nil
+    end
+
+    def prefix
+      raise 'prefix not set' unless @prefix
+
+      @prefix
+    end
+
+    def classname
+      raise 'classname not set' unless @classname
+
+      @classname
+    end
+
+    def parser
+      @parser ||= Object::const_get("#{classname}Parser").new.parse(data)
+    end
+
+    def data
+      if cache_file
+        cache.read || cache.write(raw)
+      else
+        raw
+      end
+    end
+
+    def cache
+      @cache ||= client.send("#{prefix}_cache").new(cache_file)
+    end
+
+    def cache_file
+      @cache_file ||= client.send "#{prefix}_file"
+    end
+
+    def raw
+      if response.success?
+        response.body
+      else
+        puts response.body
+        raise "Error getting #{classname}!"
+      end
+    end
+
+    def response
+      raise 'Must implement response method'
+    end
+  end
+end