homeaway-api 1.0.0

data/lib/homeaway/api/domain/submit_review.rb

@@ -0,0 +1,57 @@
+# Copyright (c) 2015 HomeAway.com, Inc.
+# All rights reserved.  http://www.homeaway.com
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module HomeAway
+  module API
+    module Domain
+      module SubmitReview
+
+        # Creates a review for the given listing and unit. The review submitted must go through the standard HomeAway
+        # review process and may not appear immediately within the list of reviews for the listing. It is recommended
+        # that the link to submitting a review be placed off of the details page of the listing and unit in question.
+        #
+        # analogous to calling a POST on API url /public/submitReview
+        #
+        # @note user must be logged in via 3 legged oauth to call this function without error
+        #
+        # @param headline	[String] A short summary about the stay.
+        # @param body	[String] The body of the review.
+        # @param locale [String] The locale that the review was written in.
+        # @param arrival_date [String, DateTime] The date of arrival for the stay. Can either be a date-parsable string or a DateTime object
+        # @param rating [Integer] An overall rating for the stay between 1 and 5.
+        # @param listing_id [String] A listing id as supplied by this public API.
+        # @param unit_id [String] The unit id within the listing that the review is for.
+        # @return [Boolean] true if the review was successfully posted to the moderation queue
+        def submit_review(headline, body, locale, arrival_date, rating, listing_id, unit_id, opts={})
+          body = {
+              'headline' => headline.to_s,
+              'body' => body.to_s,
+              'locale' => locale.to_s,
+              'arrivalDate' => HomeAway::API::Util::Validators.date(arrival_date),
+              'rating' => HomeAway::API::Util::Validators.integer(rating, 0, 6),
+              'listingId' => listing_id.to_s,
+              'unitId' => unit_id.to_s
+          }.merge(HomeAway::API::Util::Validators.query_keys(opts))
+          begin
+            post '/public/submitReview', body
+            true
+          rescue => e
+            raise e
+          end
+        end
+      end
+    end
+  end
+end

data/lib/homeaway/api/errors/ha_api_errors.rb

@@ -0,0 +1,144 @@
+# Copyright (c) 2015 HomeAway.com, Inc.
+# All rights reserved.  http://www.homeaway.com
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module HomeAway
+  module API
+    # a collection of error classes corresponding to various errors that might be raised by the HomeAway API
+    module Errors
+
+      # @private
+      class HomeAwayAPIError < StandardError
+
+        attr_reader :response
+
+        # @private
+        def initialize(response=nil)
+          @response = response
+        end
+
+        # @private
+        def to_s
+          begin
+            buf = "#{self.class.name} #{@response._metadata.status_code} "
+            @response.violations.each do |violation|
+              buf << "#{violation.description} | "
+            end
+            buf = buf[0..-3] unless @response.violations.empty?
+            return buf
+          rescue
+            if @response.nil?
+              super
+            else
+              @response.to_s
+            end
+          end
+        end
+
+        # @private
+        def self.method_missing(name, *args, &block)
+          if @response.respond_to? name
+            @response.send name
+          else
+            super
+          end
+        end
+      end
+
+      # raised when the token a client is using has become expired
+      class TokenExpiredError < StandardError
+      end
+
+      # @private
+      class ClientError < HomeAwayAPIError
+      end
+
+      # represents a HTTP 400
+      class BadRequestError < ClientError
+        CODE = 400
+      end
+
+      # represents a HTTP 500
+      class InternalServerError < HomeAwayAPIError
+        CODE = 500
+      end
+
+      # represents a HTTP 404
+      class ResourceNotFoundError < ClientError
+        CODE = 404
+      end
+
+      # represents a HTTP 401
+      class UnauthorizedError < ClientError
+        CODE = 401
+      end
+
+      # represents a HTTP 403
+      class ForbiddenError < ClientError
+        CODE = 403
+      end
+
+      # represents a HTTP 405
+      class MethodNotAllowedError < ClientError
+        CODE = 405
+      end
+
+      # represents a HTTP 416
+      class RequestedRangeNotSatisfiableError < ClientError
+        CODE = 416
+      end
+
+      # represents a HTTP 429. This will be raised when a client exceeds their rate limit
+      class TooManyRequestsError < ClientError
+        CODE = 429
+      end
+
+      # represents a HTTP 503
+      class APINotAvailableError < HomeAwayAPIError
+        CODE = 503
+      end
+
+      # represents a HTTP 406
+      class NotAcceptableError < ClientError
+        CODE = 406
+      end
+
+      # represents a HTTP 409
+      class ConflictError < ClientError
+        CODE = 409
+      end
+
+      # @private
+      class ImATeapotError < ClientError
+        #hopefully this is never ever used
+        CODE = 418
+      end
+
+      # @private
+      def self.for_http_code(status_code)
+        begin
+          self.const_get(self.constants.select do |c|
+            const = self.const_get c
+            Class === const &&
+                const.const_defined?(:CODE) &&
+                const.const_get(:CODE) == status_code.to_i
+          end.first)
+        rescue => _
+          HomeAwayAPIError
+        end
+      end
+
+    end
+  end
+end

data/lib/homeaway/api/paginator.rb

@@ -0,0 +1,140 @@
+# Copyright (c) 2015 HomeAway.com, Inc.
+# All rights reserved.  http://www.homeaway.com
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module HomeAway
+  module API
+    class Paginator
+      include Enumerable
+
+      # @private
+      def initialize(client, hashie, auto_pagination=false)
+        @hashie = hashie
+        @client = client
+        @auto_pagination = auto_pagination
+      end
+
+      # supply a block that expects a single parameter to iterate through this paginator
+      def each(&block)
+        if @auto_pagination
+          first_hashie = @hashie.clone
+          while true
+            cur_hits = entries.clone
+            cur_hits.each do |entity|
+              if block_given?
+                block.call entity
+              else
+                yield entity
+              end
+            end
+            if @hashie.nextPage && @hashie.page < 300
+              begin
+                next_page!
+              rescue HomeAway::API::Errors::RequestedRangeNotSatisfiableError
+                # we have a max page limit
+                # reset me to the first so that I can be iterated over again
+                @hashie = first_hashie
+                break
+              end
+            else
+              # reset me to the first so that I can be iterated over again
+              @hashie = first_hashie
+              break
+            end
+          end
+        else
+          entries.each do |entity|
+            if block_given?
+              block.call entity
+            else
+              yield entity
+            end
+          end
+        end
+      end
+
+      # @return [Integer] the size of this paginator
+      def size
+        return @hashie['size'] if @hashie.has_key? 'size'
+        0
+      end
+
+      alias_method :length, :size
+
+      # @return [HomeAway::API::Paginator] a paginator object that has the next page of results
+      def next_page
+        return nil unless next_page?
+        next_hashie = @client.get(*parse_url(nextPage))
+        self.class.new(@client, next_hashie, @auto_pagination)
+      end
+
+      # updates this paginator to have the next page of results in place
+      # @return [Boolean] true if successful
+      def next_page!
+        return false unless next_page?
+        @hashie = @client.get(*parse_url(nextPage))
+        true
+      end
+
+      # @return [Boolean] does this paginator have another page?
+      def next_page?
+        @hashie.has_key? 'nextPage'
+      end
+
+      # @return [HomeAway::API::Paginator] a paginator object that has the previous page of results
+      def previous_page
+        return nil unless previous_page?
+        prev_hashie = @client.get(*parse_url(prevPage))
+        self.class.new(@client, prev_hashie, @auto_pagination)
+      end
+
+      # updates this paginator to have the previous page of results in place
+      # @return [Boolean] true if successful
+      def previous_page!
+        return false unless previous_page?
+        @hashie = @client.get(*parse_url(prevPage))
+        true
+      end
+
+      # @return [Boolean] does this paginator have previous page?
+      def previous_page?
+        @hashie.has_key? 'prevPage'
+      end
+
+      # @private
+      def method_missing(name, *args, &block)
+        if @hashie.respond_to? name
+          @hashie.send name, *args, &block
+        else
+          super
+        end
+      end
+
+      # @return [Array] the current page of results as an array of entities
+      def entries
+        entries = @hashie['entries'] ||= nil
+        entries.map { |entry| HomeAway::API::Response.new(entry) }
+      end
+
+      alias_method :hits, :entries
+
+      private
+
+      def parse_url(input)
+        uri = URI.parse(input)
+        return uri.path, CGI.parse(uri.query)
+      end
+    end
+  end
+end

data/lib/homeaway/api/response.rb

@@ -0,0 +1,49 @@
+# Copyright (c) 2015 HomeAway.com, Inc.
+# All rights reserved.  http://www.homeaway.com
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module HomeAway
+  module API
+    # A container around the response that the HomeAway API returns.
+    # This object extends Hashie::Mash and can be accessed in an identical method
+    class Response < Hashie::Mash
+
+      # @private
+      def convert_key(key) #:nodoc:
+        HomeAway::API::Util::Validators.camel_case(key)
+      end
+
+      # a helper method to determine if this response has
+      # any particular fields in its payload, potentially
+      # nested
+      #
+      # @param attrs [Symbol] one or more symbols to search into this response with
+      def has?(*attrs)
+        entity = self
+        attrs.each do |attr|
+          return false unless entity.has_key?(attr.to_sym)
+          entity = entity.send(attr.to_sym)
+        end
+        true
+      end
+
+      # Returns information about the request that was just made. This includes
+      # things such as connection headers and status code
+      # @return [HomeAway::API::Response] information about the request that was made
+      def _metadata
+        @metadata ||= HomeAway::API::Response.new
+      end
+    end
+  end
+end

data/lib/homeaway/api/util/defaults.rb

@@ -0,0 +1,92 @@
+# Copyright (c) 2015 HomeAway.com, Inc.
+# All rights reserved.  http://www.homeaway.com
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'singleton'
+
+module HomeAway
+  module API
+    module Util
+      # @private
+      class Defaults
+        include Singleton
+
+        def site
+          'https://ws.homeaway.com'
+        end
+
+        def port
+          '443'
+        end
+
+        def auth_url
+          '/oauth/authenticate?clientId='
+        end
+
+        def token_url
+          '/oauth/token?credentials='
+        end
+
+        def logger
+          default_logger = Logger.new(STDOUT)
+          default_logger.level = Logger::WARN
+          default_logger
+        end
+
+        def cache_control
+          'max-age: 0, must-revalidate'
+        end
+
+        def auto_pagination
+          true
+        end
+
+        def page_size
+          10
+        end
+
+        def connection_opts
+          {}
+        end
+
+        def adapter
+          :faraday
+        end
+
+        def auto_reauth
+          true
+        end
+
+        def manual_token_supplied
+          false
+        end
+
+        def test_mode
+          false
+        end
+
+        def to_hash
+          keys = self.class.instance_methods(false)
+          keys.delete(:to_hash)
+          hash = {}
+          keys.each do |key|
+            hash[key] = send key
+          end
+          hash
+        end
+      end.freeze
+      Defaults.instance.freeze
+    end
+  end
+end