reso_web_api 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4476a6c7c91ca11a6ee826b17173fb7f05875f9a
-  data.tar.gz: b926a43a312ee862f0139729cac0893bfbba53ac
+  metadata.gz: 67631df91f672fae2f93f55775fe0428cd9499c2
+  data.tar.gz: ff3124a85d13350d727091124f6b1a26505192ff
 SHA512:
-  metadata.gz: f97635ef226ae6e694a5dacf135fac8c43b78b87af4b3c05659b07c2380e991a3866fe9b90b30c72ab9782f584da007052e8070751a5cc9f84aa26fd27e821a2
-  data.tar.gz: 944f6747aebf0ec3862548c919f79bf15b826a714d71451e12402bd1ed9205a783ca7c2ba07f7b5660f60c393623e3ca99362990108a6b5f39127c4c1e75344e
+  metadata.gz: 0ec818165bb57a2aaa96f7648d8926d4d2970f9b44fc7e0f4fb08104507cd42946291e968eb1503c4d06bf9d86ddc46561dba9d37b38cf372c99ae92e53e055c
+  data.tar.gz: 42b196b79c5e818acea12e690a664fc35e51d922c4447d6264b083ddd53f18d9ec20821664cef9476b4c8e13ea94a1eaf4f0b1e91114290087f3a03cd59d99a6

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # CHANGELOG
 
+## 0.2.1
+
+* Added `SimpleTokenAuth` strategy for using basic non-expiring, non-refreshable tokens
+* Share logger with OData service
+* Allow passing options to OData service
+
 ## 0.2.0
 
 * Refactored code and simplified design

data/README.md

@@ -4,6 +4,12 @@ A Ruby library to connects to MLS servers conforming to the [RESO Web API][reso-
 
 [reso-web-api]: https://www.reso.org/reso-web-api/
 
+[![Gem Version](https://badge.fury.io/rb/reso_web_api.svg)](https://badge.fury.io/rb/reso_web_api)
+[![Build Status](https://app.codeship.com/projects/c9f88f50-3a07-0136-6878-6eab29180a68/status?branch=master)](https://app.codeship.com/projects/290070)
+[![Test Coverage](https://api.codeclimate.com/v1/badges/6e707a367bfdd609fc76/test_coverage)](https://codeclimate.com/github/wrstudios/reso_web_api/test_coverage)
+[![Maintainability](https://api.codeclimate.com/v1/badges/6e707a367bfdd609fc76/maintainability)](https://codeclimate.com/github/wrstudios/reso_web_api/maintainability)
+[![Documentation](http://inch-ci.org/github/wrstudios/reso_web_api.png?branch=master)](http://www.rubydoc.info/github/wrstudios/reso_web_api/master)
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -22,14 +28,23 @@ Or install it yourself as:
 
 ## Usage
 
-### Authentication
+### Quickstart
 
 Instantiating an API client requires two things: an endpoint (i.e. service URL) and an authentication strategy.
-You may either instantiate the auth strategy directly and pass it to the client constructor (in the `:auth` parameter), or you may choose to pass a nested hash with options for configuring the strategy instead, as below:
 
 ```ruby
 require 'reso_web_api'
 
+client = ResoWebApi::Client.new(endpoint: '<Service URL>', auth: auth)
+```
+
+The `:endpoint` option should need no further explanation, for `:auth`, read on below.
+
+### Authentication
+
+You may either instantiate the auth strategy directly and pass it to the client constructor (in the `:auth` parameter), or you may choose to pass a nested hash with options for configuring the strategy instead, as below:
+
+```ruby
 client = ResoWebApi::Client.new(
   endpoint: 'https://api.my-mls.org/RESO/OData/',
   auth: {
@@ -45,6 +60,18 @@ end
 Note that if you choose this option, you _may_ specify the strategy implementation by passing its _class_ as the `:strategy` option.
 If you omit the `:strategy` parameter, it will default to `ResoWebApi::Authentication::TokenAuth`.
 
+For a list of available authentication strategies and usage examples, please [see below](#authentication-strategies).
+
+### Advanced Configuration
+
+The client is designed to work out-of-the-box and require as little configuration as possible (only endpoint and auth by default).
+However, if you need more control, there are several additional settings that can be configured using the constructor.
+
+- `:user_agent`: Sets the `User-Agent` header sent to the service (defaults to `Reso Web API Ruby Gem $VERSION`)
+- `:adapter`: Sets the Faraday adapter used for the connection (defaults to `Net::HTTP`)
+- `:logger`: You may pass your own logger to a client instance. By default, each instance will use the global logger defined on the `ResoWebApi` module, which logs to STDOUT. You can also change the logger on the module itself, which will then be used for all new client instances you create.
+- `:odata`: If you need to pass any special options to the OData service, you may do so here.
+
 ### Accessing Data
 
 #### Standard Resources
@@ -70,7 +97,63 @@ The following methods are provided:
 Other resources may be access using the `#resources` method on the client, which may be accessed as a hash like this:
 
 ```ruby
-client.resources['OpenHouse'].first # Access the 'OpenHouse' collectionh
+client.resources['OpenHouse'].first # Access the 'OpenHouse' collection
+```
+
+## Authentication Strategies
+
+Since the details of authentication may vary from vendor to vendor, this gem attempts to stay flexible by providing a modular authentication system.
+
+### Available Strategies
+
+Currently, we provide the following authentication strategies:
+
+#### `SimpleTokenAuth`
+
+A simple strategy that works with a static access token. Often used for development access, where security is not a major concern.
+
+##### Configuration
+
+- `access_token`: The access token value (`String`).
+- `token_type`: The token type (`String`, optional). Defaults to `Bearer`.
+
+##### Example
+
+```ruby
+client = ResoWebApi::Client.new(
+  endpoint: 'https://api.my-mls.org/RESO/OData/',
+  auth: {
+    strategy: ResoWebApi::Authentication::SimpleTokenAuth,
+    access_token: 'abcdefg01234567890'
+  }
+)
+```
+
+#### `TokenAuth`
+
+A basic OAuth-based token strategy, where a Client ID/Secret pair is sent to a server in exchange for a temporary access token. Frequently used in production systems for its increased security over the static token strategy.
+
+##### Configuration
+
+- `endpoint`: The URL of the token server (`String`).
+- `client_id`: The Client ID (`String`).
+- `client_secret`: The Client Secret (`String`).
+- `scope`: The scope for the token (`String`).
+- `grant_type`: The grant type (`String`, optional). Defaults to `client_credentials`.
+
+##### Example
+
+```ruby
+client = ResoWebApi::Client.new(
+  endpoint: 'https://api.my-mls.org/RESO/OData/',
+  auth: {
+    strategy:      ResoWebApi::Authentication::TokenAuth,
+    endpoint:      'https://oauth.my-mls.org/connect/token',
+    client_id:     'deadbeef',
+    client_secret: 'T0pS3cr3t',
+    scope:         'odata'
+  }
+end
 ```
 
 ## Development

data/lib/reso_web_api/authentication.rb

@@ -1,4 +1,5 @@
 require_relative 'authentication/access'
 require_relative 'authentication/auth_strategy'
 require_relative 'authentication/middleware'
+require_relative 'authentication/simple_token_auth'
 require_relative 'authentication/token_auth'

data/lib/reso_web_api/authentication/simple_token_auth.rb

@@ -0,0 +1,23 @@
+module ResoWebApi
+  module Authentication
+    # A simple auth strategy that uses a static, non-expiring token.
+    class SimpleTokenAuth < AuthStrategy
+      # The access token (String)
+      option :access_token
+      # The token type (String, defaults to `Bearer`)
+      option :token_type, default: proc { 'Bearer' }
+      # This strategy does not require an endpoint
+      option :endpoint, optional: true
+
+      # Simply returns a static, never expiring access token
+      # @return [Access] The access token object
+      def authenticate
+        Access.new(
+          'access_token' => access_token,
+          'token_type'   => token_type,
+          'expires_in'   => 1 << (1.size * 8 - 2) - 1 # Max int value
+        )
+      end
+    end
+  end
+end

data/lib/reso_web_api/client.rb

@@ -7,7 +7,10 @@ module ResoWebApi
   class Client < BaseClient
     include Resources
 
+    # Auth strategy (class instance or Hash)
     option :auth
+    # Options for OData service
+    option :odata, optional: true
 
     def initialize(options = {})
       super(options)
@@ -34,7 +37,14 @@ module ResoWebApi
     # authenticated and authorized connection
     # @return [OData4::Service] The service instance.
     def service
-      @service ||= OData4::Service.new(connection)
+      # puts odata, service_options
+      @service ||= OData4::Service.new(connection, service_options)
+    end
+
+    # Returns the default options used by the by the OData service
+    # @return [Hash] The options hash
+    def service_options
+      @service_options ||= { logger: logger }.merge(odata || {})
     end
 
     private

data/lib/reso_web_api/version.rb

@@ -1,3 +1,3 @@
 module ResoWebApi
-  VERSION = "0.2.0"
+  VERSION = "0.2.1"
 end

data/reso_web_api.gemspec

@@ -28,4 +28,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "bundler", "~> 1.16"
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "simplecov", "~> 0.15"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: reso_web_api
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Christoph Wagner
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-05-15 00:00:00.000000000 Z
+date: 2018-05-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -94,6 +94,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.15'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.15'
 description: Allows communication with MLS systems conforming to the RESO Web API
   standard
 email:
@@ -118,6 +132,7 @@ files:
 - lib/reso_web_api/authentication/access.rb
 - lib/reso_web_api/authentication/auth_strategy.rb
 - lib/reso_web_api/authentication/middleware.rb
+- lib/reso_web_api/authentication/simple_token_auth.rb
 - lib/reso_web_api/authentication/token_auth.rb
 - lib/reso_web_api/base_client.rb
 - lib/reso_web_api/client.rb