entrata 1.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2316690e03ac91b2580dbaab63c56ac93afc70eaef268c787d206aba024a484f
+  data.tar.gz: 574ed8030e63871b2cb1a59afd3e5ea25a57a995b790ba5a2a6c606aa3965db3
+SHA512:
+  metadata.gz: 678ea4ce2d8dbf797263d707df80c21351f26085c6e690d5024a23a346c52a272695f049e23c3a74cf536ff96257156878c9ba019ee050d62046f42ace087fe2
+  data.tar.gz: e92102c9060201f39c692dbac217f27b77b60d131ac5ff12d33b639453225d728fd02c6b1548bad0423b12a04be91820e495d5e4736bd76498ec1ddf4b4d7c64

data/.ci

@@ -0,0 +1,144 @@
+#!/usr/bin/env groovy
+
+// https://github.com/apartmentlist/ci-shared-library
+@Library('ci-shared-library')_
+
+// Log Rotation
+properties([
+  buildDiscarder(
+    logRotator(
+      artifactDaysToKeepStr: '',
+      artifactNumToKeepStr: '',
+      daysToKeepStr: '30',
+      numToKeepStr: '100'
+    )
+  )
+]) //properties
+
+// Generate unique slave labels
+def k8s_label = "${UUID.randomUUID().toString()}"
+
+pipeline {
+  environment {
+    APP_NAME = 'entrata'
+    APT_KEY_DONT_WARN_ON_DANGEROUS_USAGE = 'true'
+    CI = 'true'
+    CLOUDSDK_CORE_DISABLE_PROMPTS = '1'
+    GIT_COMMIT_SHORT = sh(script: "git rev-parse --short ${GIT_COMMIT}", returnStdout: true).trim()
+    GIT_MESSAGE = sh(script: "git log --format=%B -n 1 ${GIT_COMMIT}", returnStdout: true).trim()
+    GIT_USER = sh(script: "git log -1 --pretty=format:'%ae'", returnStdout: true).trim()
+    GITHUB_URL = "https://github.com"
+    LANG = "en_US.UTF-8"
+    LANGUAGE = "en_US:en"
+    LC_ALL = "en_US.UTF-8"
+    PRODUCTION_DEPLOY="false"
+    SLACK_SUCCESS_CHANNEL = "#staging-releases"
+    SLACK_FAILURE_CHANNEL = "#supply_log_info"
+  } // environment
+
+  agent {
+    kubernetes {
+      label k8s_label
+      defaultContainer 'jnlp'
+      yaml """
+---
+apiVersion: v1
+kind: Pod
+metadata:
+  name: test
+spec:
+  restartPolicy: Never
+  containers:
+  - name: ruby
+    image: gcr.io/alist-development/ruby:2.7.6
+    imagePullPolicy: Always
+    resources:
+      requests:
+        memory: "1024Mi"
+        cpu: "1"
+      requests:
+        memory: "1024Mi"
+        cpu: "1"
+    command:
+    - "tail"
+    - "-f"
+    - "/dev/null"
+"""
+    } // kubernetes
+  } // agent
+
+  options {
+    timestamps()
+    timeout(time: 10, unit: 'MINUTES')
+    ansiColor('xterm')
+  } // options
+
+  stages {
+    stage('Preparation') {
+      parallel {
+        stage('Slack') {
+          steps {
+            slackPreparation()
+          } // steps
+        } // stage - Slack
+        stage('Build Description') {
+          steps {
+            buildDescription()
+          }
+        }
+        stage('Bundle') {
+          steps {
+            container('ruby') {
+              sh 'gem install bundler:2.2.6 --no-post-install-message --no-document'
+              sh 'bundle install -j 12'
+            } // container
+          } // steps
+        } // stage - Bundle
+      } //parallel
+    } //stage - Preparation
+
+    stage('Testing') {
+      when {
+        allOf {
+          changeRequest target: 'main'
+        }
+      }
+
+      parallel {
+        stage('Run RSpec') {
+          steps {
+            container('ruby') {
+              sh label: 'RSpec', script: 'bundle exec rake'
+            } // container
+          } // steps
+        } // stage
+      } //parallel
+    } //stage
+
+    stage("Publish") {
+      when {
+        allOf {
+          branch "main"
+          not { changeRequest() }
+        }
+      } // when
+      parallel {
+        stage("to Github packages") {
+          steps {
+            publishRubyGemToGHP("ruby")
+          }
+        } // stage - to Github packages
+      } // parallel
+    } // stage - Publish
+  } // stages
+
+  post {
+    success {
+      success('alist-production')
+    } // success
+    aborted {
+      aborted('alist-production')
+    } // aborted
+  } // post
+
+} // pipeline

data/.gitignore

@@ -0,0 +1,2 @@
+/Gemfile.lock
+entrata-*.gem

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require 'spec_helper'

data/CODEOWNERS

@@ -0,0 +1 @@
+* @apartmentlist/integrations

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in entrata.gemspec
+gemspec

data/README.md

@@ -0,0 +1,110 @@
+[![CircleCI](https://circleci.com/gh/apartmentlist/entrata.svg?style=svg&circle-token=838474bf01ba4796ffc9f2b59038523b3b6a2b90)](https://circleci.com/gh/apartmentlist/entrata)
+
+# Entrata
+
+Ruby client for Entrata API
+
+## Versions
+* 0.1.0 Initial Release
+* 0.1.1 Extend request timeout to 10 minutes for all requests
+* 0.1.2 Request GetIlsPropertiesData via `curl` to avoid errors on large responses
+* 0.2.0 Add buildingName to fixture file for getIlsPropertiesData success response
+* 0.2.1 Make paths in StaticFileFetcher relative
+* 0.2.2 Add buildingName to unit C606 in fixture file for successful getIlsPropertiesData
+* 0.3.0 Raise a Request::Error when the response is not valid JSON and update Travis Ruby version
+* 0.3.2 Expose lead request body for troubleshooting when sending leads
+* 1.0.0 Allow us to pass renter min and max price range in
+* 1.0.4 Make entrata gem compatible with Ruby 3 syntax updates
+* 1.0.5 No functional changes. Updating build pipeline to publish to GitHub Packages.
+* 1.1.0 Adding services to manage lea lite inactive and reactive guestcard requests.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'entrata'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install entrata
+
+## Usage
+
+### Configuration
+
+No gem configuration, but getting an access token (via `Entrata::Client.get_access_token`) requires `client_id` and `client_secret` in addition to `auth_code` provided by Entrata on property activation.
+
+### API Resources
+
+All API access is performed via the `Entrata::Client` class.
+
+There are two usage patterns:
+1. Gathering client credential and PMC subdomain
+2. Making authenticated requests to API resources using saved credential and PMC subdomain
+
+#### Gathering client credential and PMC subdomain
+Class methods are available for convenience of this one-time call sequence per PMC
+```
+auth_code = 'received from activation endpoint'
+client_id = ENV['ENTRATA_CLIENT_ID'] # Apartmentlist assigned client_id
+client_secret = ENV['ENTRATA_CLIENT_SECRET'] # Apartmentlist current client_secret
+
+token_hash = Entrata::Client.get_access_token(auth_code: auth_code,
+                                         client_id: client_id,
+                                         client_secret: client_secret)
+
+client_info = Entrata::Client.get_client_subdomain(token_hash['token'])
+subdomain = client_info['subdomain']
+
+# create or update Entrata credential with token and subdomain
+```
+
+#### Making authenticated requests to API resources
+An instance of the `Entrata::Client` may be created per PMC to request authenticated resources available under its subdomain.
+
+```
+credential = #find by PMC or iterate all entrata credentials
+token = credential.fields['access_token']
+subdomain = credential.fields['subdomain']
+
+client = Entrata::Client.new(subdomain: subdomain, token: token)
+
+remote_property_id = #get from activation
+
+client.process_property_activation(remote_property_id) #defaults to 'approve'-ing the activation
+property_hash = client.get_property_info(remote_property_id)
+multiple_property_hash = client.get_ils_properties_data([remote_property_id])
+```
+
+## Testing
+
+A test client is available for integration testing in your consuming application.
+
+`Entrata::TestClient` behaves like `Entrata::Client`, but returns static responses or raises errors just like the real client would.  It never makes any real HTTP requests.
+
+`Entrata::TestClient` defaults to providing successful (static) responses collected from the real API.
+
+You may force failure by providing specific ("fail") input values.  See below for specific trigger parameters:
+```
+# Providing "fail" to specific parameters will raise `Entrata::Request::Error` just like the real client would.
+Entrata::TestClient.get_access_token(auth_code: 'fail', client_id: 'anything', client_secret: 'anything') #BOOM!
+Entrata::TestClient.get_client_info('fail') #BOOM!
+
+test_client = Entrata::TestClient.new(subdomain: 'anything', token: 'anything')
+test_client.get_property_info('fail') #BOOM!
+test_client.process_property_activation('fail') #BOOM!
+test_client.get_ils_properties_data(['at', 'least', 'one', 'fail']) #BOOM!
+
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).

data/Rakefile

@@ -0,0 +1,7 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+Rake.add_rakelib('./lib/tasks')
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'pry'
+require 'entrata'
+
+# 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.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require 'pry'
+# Pry.start
+
+require 'irb'
+IRB.start

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/entrata.gemspec

@@ -0,0 +1,27 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'entrata/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'entrata'
+  spec.version       = Entrata::VERSION
+  spec.authors       = ['Justin Richard']
+  spec.email         = ['justin@apartmentlist.com']
+
+  spec.summary       = 'Ruby client of Entrata API'
+  spec.homepage      = 'https://github.com/apartmentlist/entrata'
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_runtime_dependency 'activesupport', '~> 5.2'
+  spec.add_runtime_dependency 'faraday', '< 1.0'
+
+  spec.add_development_dependency 'bundler'
+  spec.add_development_dependency 'pry-byebug', '~> 3.3'
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'webmock', '~> 1.21'
+end

data/lib/entrata/client.rb

@@ -0,0 +1,152 @@
+require 'faraday'
+require 'uri'
+require 'entrata/request/get_access_token'
+require 'entrata/request/get_client_info'
+require 'entrata/request/get_ils_properties_data'
+require 'entrata/request/get_property_info'
+require 'entrata/request/process_property_activation'
+require 'entrata/request/send_lead_details'
+require 'entrata/request/send_inactive_leads'
+require 'entrata/request/send_reactivate_leads'
+
+# Client to access all API resources through
+module Entrata
+  class Client
+    def initialize(subdomain:, token:)
+      @subdomain = subdomain
+      @token = token
+    end
+
+    class << self
+      def get_access_token(auth_code:, client_id:, client_secret:,
+                           conn: Faraday.new('https://sync.entrata.com'))
+        Request::GetAccessToken.new(
+          conn: conn,
+          auth_code: auth_code,
+          client_id: client_id,
+          client_secret: client_secret
+        ).perform
+      end
+
+      # requires token directly; typical use is to #get_access_token, then
+      # #get_client_info immediately with the same client
+      def get_client_info(token, conn: Faraday.new('https://sync.entrata.com'))
+        conn.authorization :Bearer, token
+
+        Request::GetClientInfo.new(conn: conn).perform
+      end
+    end
+
+    def get_property_info(property_id)
+      Request::GetPropertyInfo.new(
+        conn: conn,
+        property_id: property_id
+      ).perform
+    end
+
+    def process_property_activation(property_id, activation_status: 'approve')
+      Request::ProcessPropertyActivation.new(
+        conn: conn,
+        property_id: property_id,
+        activation_status: activation_status
+      ).perform
+    end
+
+    def get_ils_properties_data(property_ids)
+      Request::GetIlsPropertiesData.new(
+        conn: conn,
+        property_ids: property_ids
+      ).perform_with_curl
+    end
+
+    def send_lead_details(customer:, property_id:, preferences: nil)
+      Request::SendLeadDetails.new(
+        conn: conn,
+        customer: customer,
+        preferences: preferences,
+        property_id: property_id
+      ).perform
+    end
+
+    def send_inactive_leads(customer:, lead_source_id:, leasing_agent_id:, preferences:, property_id:)
+      Request::SendInactiveLeads.new(
+        conn: basic_auth_conn,
+        customer: customer,
+        lead_source_id: lead_source_id,
+        leasing_agent_id: leasing_agent_id,
+        preferences: preferences,
+        property_id: property_id
+      ).perform
+    end
+
+    def send_reactivate_leads(applicant_id:, application_id:, customer:, preferences:, property_id:)
+      Request::SendReactivateLeads.new(
+        conn: basic_auth_conn,
+        applicant_id: applicant_id,
+        application_id: application_id,
+        customer: customer,
+        preferences: preferences,
+        property_id: property_id
+      ).perform
+    end
+
+    def lead_details_request_body(customer:, property_id:, preferences: nil)
+      Request::SendLeadDetails.new(
+        conn: conn,
+        customer: customer,
+        preferences: preferences,
+        property_id: property_id
+      ).body
+    end
+
+    def inactive_lead_request_body(customer:, lead_source_id:, leasing_agent_id:, preferences:, property_id:)
+      Request::SendInactiveLeads.new(
+        conn: basic_auth_conn,
+        customer: customer,
+        lead_source_id: lead_source_id,
+        leasing_agent_id: leasing_agent_id,
+        preferences: preferences,
+        property_id: property_id
+      ).body
+    end
+
+    def reactivate_lead_request_body(applicant_id:, application_id:, customer:, preferences:, property_id:)
+      Request::SendReactivateLeads.new(
+        conn: basic_auth_conn,
+        applicant_id: applicant_id,
+        application_id: application_id,
+        customer: customer,
+        preferences: preferences,
+        property_id: property_id
+      ).body
+    end
+
+    private
+
+    def url
+      URI::HTTPS.build(host: "#{subdomain}.entrata.com").to_s
+    end
+
+    def conn
+      @conn_with_auth ||= Faraday.new(url) do |request|
+        # MUST specify adapter when configuring with block! Otherwise no adapter
+        #   will be set: https://github.com/lostisland/faraday/issues/121
+        request.adapter Faraday.default_adapter
+        request.authorization :Bearer, token
+        request.options[:timeout] = 600 # 10 minutes
+      end
+    end
+
+    def basic_auth_conn
+      @basic_auth_conn ||= Faraday.new(url) do |request|
+        # MUST specify adapter when configuring with block! Otherwise no adapter
+        #   will be set: https://github.com/lostisland/faraday/issues/121
+        request.adapter Faraday.default_adapter
+        request.authorization :Basic, token
+        request.options[:timeout] = 600 # 10 minutes
+      end
+    end
+
+    attr_reader :token, :subdomain
+  end
+end

data/lib/entrata/parameter/customer.rb

@@ -0,0 +1,20 @@
+module Entrata
+  module Parameter
+    # Wraps the user-related data that we pass to Entrata. All of the Customer
+    # attributes are required when inserting a lead.
+    class Customer
+      attr_reader :email, :first_name, :last_name, :phone
+
+      # @param email [String] Renter email
+      # @param first_name [String] Renter first name
+      # @param last_name [String] Renter last name
+      # @param phone [Integer] Renter phone number, digits only
+      def initialize(email:, first_name:, last_name:, phone:)
+        @email = email
+        @first_name = first_name
+        @last_name = last_name
+        @phone = phone
+      end
+    end
+  end
+end

data/lib/entrata/parameter/customer_preferences.rb

@@ -0,0 +1,61 @@
+module Entrata
+  module Parameter
+    # Wraps the customer preference data that we pass to Entrata. All of the
+    # preference attributes are optional when inserting a lead.
+    class CustomerPreferences
+      attr_reader :beds,
+                  :baths,
+                  :comments,
+                  :lease_terms,
+                  :move_in_date,
+                  :number_of_pets,
+                  :preferred_floorplan_id,
+                  :preferred_unit_id,
+                  :min_price,
+                  :max_price
+
+      # @param beds [Integer] Number of beds the renter is interested in
+      # @param baths [Float] Number of baths the renter is interested in
+      # @param comments [String] Notes about the renter's preferences plus any
+      #   information about a tour if there is one, plus the renter's message
+      #   for the property. Entrata only gives us one key for comments, so we
+      #   need to put everything there.
+      # @param lease_terms [String] Length of preferred lease term,
+      #   e.g. '12 months'
+      # @param move_in_date [Date] Renter move in date
+      # @param number_of_pets [String] The number of pets the renter has
+      # @param preferred_floorplan_id [Integer] Entrata's ID for the floorplan
+      #   the renter is interested in. They do not verify that this ID matches
+      #   any real floorplan on the property in their system.
+      # @param preferred_unit_id [Integer] Entrata's ID for the unit the renter
+      #   is interested in. They do not verify that this ID matches any real
+      #   unit on the property in their system.
+      # @param min_price [Float] Renter's minimum budget
+      # @param max_price [Float] Renter's maximum budget
+      def initialize(
+        beds: nil,
+        baths: nil,
+        comments: nil,
+        lease_terms: nil,
+        move_in_date: nil,
+        number_of_pets: nil,
+        preferred_floorplan_id: nil,
+        preferred_unit_id: nil,
+        min_price: nil,
+        max_price: nil
+      )
+
+        @beds = beds
+        @baths = baths
+        @comments = comments
+        @lease_terms = lease_terms
+        @move_in_date = move_in_date
+        @number_of_pets = number_of_pets
+        @preferred_floorplan_id = preferred_floorplan_id
+        @preferred_unit_id = preferred_unit_id
+        @min_price = min_price
+        @max_price = max_price
+      end
+    end
+  end
+end

data/lib/entrata/request/base.rb

@@ -0,0 +1,117 @@
+require 'faraday'
+require 'json'
+require 'entrata/request/error'
+require 'open3'
+
+module Entrata
+  module Request
+    class Base
+      def initialize(conn:, **other_args)
+        @conn = conn
+        set_content_header!
+
+        after_initialize(**other_args)
+      end
+
+      # Initialization call back for subclasses init parameter access
+      def after_initialize(**params)
+        # No-op, this method is a call back for subclasses
+      end
+
+      def resource_name
+        raise NotImplementedError, 'implement with exact case of resource'
+      end
+
+      def resource_path
+        '/api/ils/internetlisting'
+      end
+
+      def resource_auth
+        { type: 'oauth' }
+      end
+
+      def resource_params
+        {}
+      end
+
+      def perform
+        response = conn.post(resource_path) do |request|
+          request.body = body
+        end
+
+        result_hash = try_parsing_body(response.body)
+
+        if response.success? && result_hash
+          result_hash
+        else
+          error = create_response_error(response.body)
+          raise error
+        end
+      end
+
+      def perform_with_curl
+        stdout, _stderr, status = Open3.capture3(curl_command,)
+        result_hash = try_parsing_body(stdout)
+
+        if status == 0 && result_hash
+          result_hash
+        else
+          error = create_response_error(stdout)
+          raise error
+        end
+      end
+
+      def body
+        {
+          auth: resource_auth,
+          method: {
+            name: resource_name,
+            params: resource_params
+          }
+        }.to_json
+      end
+
+      private
+
+      def try_parsing_body(raw_body)
+        @parsed_body = JSON.parse(raw_body)
+        @parsed_body.fetch('response', {}).fetch('result', nil)
+      rescue JSON::ParserError
+        nil
+      end
+
+      def create_response_error(message)
+        error_hash = try_parsing_error_hash(message)
+        if error_hash
+          Entrata::Request::Error.new(error_hash['message'], error_hash['code'])
+        else
+          Entrata::Request::Error.new(message)
+        end
+      end
+
+      def try_parsing_error_hash(error)
+        parsed_error = JSON.parse(error)
+        parsed_error.fetch('response', {}).fetch('error', nil)
+      rescue JSON::ParserError
+        nil
+      end
+
+      def set_content_header!
+        conn.headers['Content-Type'] = 'application/json'
+      end
+
+      def curl_command
+        full_url =
+          URI::HTTPS.build(host: conn.url_prefix.host, path: resource_path)
+
+        <<-CURL_COMMAND.gsub!(/\s+/, ' ').strip
+          curl #{full_url.to_s} -X POST -H 'Content-Type: application/json'
+           -H 'Authorization: #{conn.headers['Authorization']}'
+           --data '#{body}'
+        CURL_COMMAND
+      end
+
+      attr_reader :conn, :hostname, :parsed_body
+    end
+  end
+end