guesty-client 0.1.0

data/lib/guesty/memory_token_store.rb

@@ -0,0 +1,33 @@
+module Guesty
+  # The default token store: keeps one token per credential slot in memory for
+  # the life of the process. Guesty mints only 5 tokens per client id per 24
+  # hours, so a multi-process host must inject a shared, persistent store, such
+  # as a database table behind a cache.
+  class MemoryTokenStore
+    Token = Struct.new(:access_token, :expires_at, keyword_init: true) do
+      def expired?
+        expires_at.nil? || expires_at < Time.now
+      end
+    end
+
+    def initialize
+      @tokens = {}
+    end
+
+    # @rbs (::String slot_key) -> Token?
+    def read(slot_key)
+      token = @tokens[slot_key]
+
+      token if token && !token.expired?
+    end
+
+    # @rbs (slot_key: ::String, access_token: ::String, expires_at: ::Time) -> Token
+    def save(slot_key:, access_token:, expires_at:)
+      @tokens[slot_key] = Token.new(access_token:, expires_at:)
+    end
+
+    def clear
+      @tokens = {}
+    end
+  end
+end

data/lib/guesty/operation.rb

@@ -0,0 +1,37 @@
+module Guesty
+  # Shared monadic contract for the client operations: #call returns a Result,
+  # #call! unwraps it and raises the underlying failure. An error raised inside
+  # #call becomes Failure(error), mirroring the host's operation base.
+  module Operation
+    def self.included(base)
+      base.include Dry::Monads[:result]
+      base.prepend(Call)
+    end
+
+    module Call
+      def call(*, **, &)
+        super
+      rescue StandardError => e
+        Failure(e)
+      end
+    end
+
+    def call!(...)
+      result = call(...)
+      raise result.failure if result.failure?
+
+      result
+    end
+
+    private
+
+    def argument!(fatal: false, **attrs)
+      key, reason = attrs.first
+      raise Guesty::ArgumentError.new("#{key}: #{reason}", fatal:)
+    end
+
+    def error!(message, fatal: false)
+      raise Guesty::Error.new(message, fatal:)
+    end
+  end
+end

data/lib/guesty/rate_limiter_middleware.rb

@@ -0,0 +1,23 @@
+module Guesty
+  # Faraday request middleware delegating throttling to the injected limiter
+  # (Guesty.config.rate_limiter), so a host can share the windows across
+  # processes. Registered as :guesty_rate_limiter.
+  class RateLimiterMiddleware < Faraday::Middleware
+    # @rbs (untyped app, ?::Hash[::Symbol, untyped] options) -> void
+    def initialize(app, options = {})
+      super
+
+      @key = options[:key]
+      @threshold = options[:threshold]
+      @interval = options[:interval]
+    end
+
+    def on_request(_env)
+      key = @key.is_a?(Proc) ? @key.call : @key
+
+      Guesty.config.rate_limiter.throttle!(key:, threshold: @threshold, interval: @interval)
+    end
+  end
+
+  Faraday::Request.register_middleware(guesty_rate_limiter: RateLimiterMiddleware)
+end

data/lib/guesty/reservations/accommodation_fare/update.rb

@@ -0,0 +1,44 @@
+module Guesty
+  module Reservations
+    module AccommodationFare
+      class Update
+        include Guesty::Operation
+
+        FARE_TYPES = %w[AF AFA AFD].freeze #: ::Array[::String]
+        ADJUSTED_TYPE = 'AF'.freeze #: ::String
+
+        # @rbs (reservation_id: ::String, amount: ::Integer | ::Float | ::BigDecimal) -> Dry::Monads::Result[::BigDecimal]
+        def call(reservation_id:, amount:)
+          argument! reservation_id: :required if reservation_id.blank?
+          argument! amount: :negative, fatal: true if amount.negative?
+
+          adjustment = amount.to_d - current_fare(reservation_id)
+          return Success(adjustment) if adjustment.zero?
+
+          response = Guesty.do_request :post, 'price-adjustments/manual-total-amount', payload(reservation_id, adjustment), retries: 0
+          return response unless response.success?
+
+          Success(adjustment)
+        end
+
+        private
+
+        # @rbs (::String reservation_id) -> ::BigDecimal
+        def current_fare(reservation_id)
+          reservation = Show.new.call!(reservation_id:, fields: %w[money.invoiceItems]).value!
+          items = reservation.dig(:money, :invoiceItems)
+
+          items.select { |item| FARE_TYPES.include?(item[:normalType]) }.sum(BigDecimal('0')) { |item| item[:amount].to_d }
+        end
+
+        # @rbs (::String reservation_id, ::BigDecimal adjustment) -> ::Hash[::Symbol, untyped]
+        def payload(reservation_id, adjustment)
+          {
+            reservationId: reservation_id,
+            priceAdjustments: [{ normalType: ADJUSTED_TYPE, amount: adjustment.to_f }]
+          }
+        end
+      end
+    end
+  end
+end

data/lib/guesty/reservations/approve.rb

@@ -0,0 +1,23 @@
+module Guesty
+  module Reservations
+    # Approves a request to book (a reservation in status `reserved`). Runs
+    # asynchronously on Guesty's side; a repeat answers 400 DUPLICATE.
+    class Approve
+      include Guesty::Operation
+
+      # @rbs (reservation_id: ::String) -> Dry::Monads::Result[bool]
+      def call(reservation_id:)
+        argument! reservation_id: :required if reservation_id.blank?
+
+        response = Guesty.do_request(
+          :post,
+          "reservations-v3/#{reservation_id}/approve",
+          retries: 0
+        )
+        return response unless response.success?
+
+        Success(true)
+      end
+    end
+  end
+end

data/lib/guesty/reservations/create.rb

@@ -0,0 +1,50 @@
+module Guesty
+  module Reservations
+    class Create
+      include Guesty::Operation
+
+      REQUIRED_ATTRIBUTE_KEYS = %i[
+        guestId
+        listingId
+        source
+        status
+        ignoreCalendar
+        ignoreTerms
+        checkInDateLocalized
+        checkOutDateLocalized
+      ].freeze #: ::Array[::Symbol]
+      GUEST_COUNT_KEYS = %i[numberOfAdults numberOfChildren].freeze #: ::Array[::Symbol]
+
+      # @rbs (attributes: ::Hash[::Symbol, untyped]) -> Dry::Monads::Result[::String]
+      def call(attributes:)
+        validate_attributes!(attributes)
+
+        response = Guesty.do_request :post, 'reservations-v3', attributes, retries: 0, timeout: 60
+        Success(handle_response(response))
+      end
+
+      private
+
+      def validate_attributes!(attributes)
+        argument! attributes: :required if attributes.blank?
+
+        REQUIRED_ATTRIBUTE_KEYS.each do |key|
+          argument! key => :required if attributes[key].nil?
+        end
+
+        guests = attributes[:numberOfGuests]
+        return unless guests
+
+        GUEST_COUNT_KEYS.each do |key|
+          argument! key => :required if guests[key].blank?
+        end
+      end
+
+      def handle_response(response)
+        raise response.failure unless response.success?
+
+        response.value!.body.fetch(:reservationId)
+      end
+    end
+  end
+end

data/lib/guesty/reservations/custom_fields/update.rb

@@ -0,0 +1,26 @@
+module Guesty
+  module Reservations
+    module CustomFields
+      class Update
+        include Guesty::Operation
+
+        # @rbs (reservation_id: ::String, custom_fields: ::Array[::Hash[::Symbol, untyped]]) -> Dry::Monads::Result[::Hash[::Symbol, untyped]]
+        def call(reservation_id:, custom_fields:)
+          argument! reservation_id: :required if reservation_id.blank?
+          argument! custom_fields: :required if custom_fields.blank?
+
+          response = Guesty.do_request :put, "reservations-v3/#{reservation_id}/custom-fields", { customFields: custom_fields }
+          Success(handle_response(response))
+        end
+
+        private
+
+        def handle_response(response)
+          raise response.failure unless response.success?
+
+          response.value!.body
+        end
+      end
+    end
+  end
+end

data/lib/guesty/reservations/dates/update.rb

@@ -0,0 +1,41 @@
+module Guesty
+  module Reservations
+    module Dates
+      class Update
+        include Guesty::Operation
+
+        # @rbs (reservation_id: ::String, attributes: ::Hash[::Symbol, untyped]) -> Dry::Monads::Result[bool]
+        def call(reservation_id:, attributes:)
+          argument! reservation_id: :required if reservation_id.blank?
+          argument! attributes: :required if attributes.blank?
+
+          payload = date_attributes(attributes)
+          response = Guesty.do_request(
+            :put,
+            "reservations-v3/#{reservation_id}/dates",
+            payload
+          )
+
+          raise response.failure if response.failure?
+
+          Success(true)
+        end
+
+        private
+
+        # @rbs (::Hash[::Symbol, untyped] attributes) -> ::Hash[::Symbol, untyped]
+        def date_attributes(attributes)
+          {
+            checkInDateLocalized: attributes[:start_date]&.iso8601,
+            checkOutDateLocalized: attributes[:end_date]&.iso8601,
+            plannedArrival: attributes[:check_in]&.strftime('%H:%M'),
+            plannedDeparture: attributes[:check_out]&.strftime('%H:%M'),
+            ignoreCalendar: attributes[:ignore_calendar],
+            ignoreTerms: attributes[:ignore_terms],
+            applyRecalculation: false
+          }.compact
+        end
+      end
+    end
+  end
+end

data/lib/guesty/reservations/decline.rb

@@ -0,0 +1,30 @@
+module Guesty
+  module Reservations
+    # Declines a request to book. Airbnb answers 422 without a reason; Guesty
+    # documents only `dates_not_available`.
+    class Decline
+      include Guesty::Operation
+
+      # @rbs (reservation_id: ::String, reason: ::String, message: ::String) -> Dry::Monads::Result[bool]
+      def call(reservation_id:, reason:, message:)
+        argument! reservation_id: :required if reservation_id.blank?
+        argument! reason: :required if reason.blank?
+        argument! message: :required if message.blank?
+
+        body = {
+          reason:,
+          messageToGuest: message
+        }
+        response = Guesty.do_request(
+          :post,
+          "reservations-v3/#{reservation_id}/decline",
+          body,
+          retries: 0
+        )
+        return response unless response.success?
+
+        Success(true)
+      end
+    end
+  end
+end

data/lib/guesty/reservations/flags/update.rb

@@ -0,0 +1,33 @@
+module Guesty
+  module Reservations
+    module Flags
+      # Sets account custom fields on a reservation. The field ids are
+      # account-specific, so the host injects them (Guesty.config.custom_fields,
+      # keyed by flag name: blacklisted, grants_created, grants_partial).
+      class Update
+        include Guesty::Operation
+
+        # @rbs (reservation_id: ::String, flags: ::Hash[::Symbol, bool]) -> Dry::Monads::Result[bool]
+        def call(reservation_id:, flags:)
+          custom_fields = flags.map { |name, value| { fieldId: field_ids.fetch(name), value: value.to_s } }
+          body = { customFields: custom_fields }
+          response = Guesty.do_request(
+            :put,
+            "reservations-v3/#{reservation_id}/custom-fields",
+            body
+          )
+
+          raise response.failure if response.failure?
+
+          Success(true)
+        end
+
+        private
+
+        def field_ids
+          Guesty.config.custom_fields
+        end
+      end
+    end
+  end
+end

data/lib/guesty/reservations/payments/create.rb

@@ -0,0 +1,72 @@
+module Guesty
+  module Reservations
+    module Payments
+      # Records a payment taken outside Guesty. Idempotent per payment intent:
+      # a reservation already fully paid, or with a payment noting the intent,
+      # is returned without a post.
+      class Create
+        include Guesty::Operation
+
+        PAYMENT_METHOD_NAME = 'RECORDED_CASH'.freeze #: ::String
+        HISTORY_UNAVAILABLE = 'Guesty has not returned the payment history yet. Try again later.'.freeze #: ::String
+
+        # @rbs (reservation_id: ::String, attributes: ::Hash[::Symbol, untyped]) -> Dry::Monads::Result[::Hash[::Symbol, untyped]]
+        def call(reservation_id:, attributes:)
+          validate_arguments!(reservation_id:, attributes:)
+
+          @reservation_id = reservation_id
+
+          return Success(reservation) if fully_paid? || recorded?(attributes)
+
+          response = Guesty.do_request :post, "reservations/#{reservation_id}/payments", payload(attributes), retries: 0
+          return response unless response.success?
+
+          Success(response.value!.body)
+        end
+
+        private
+
+        def validate_arguments!(reservation_id:, attributes:)
+          argument! reservation_id: :required if reservation_id.blank?
+          argument! attributes: :required if attributes.blank?
+          argument! amount: :required if attributes[:amount].blank?
+          argument! amount: :must_be_positive if attributes[:amount].present? && attributes[:amount] <= 0
+          argument! paid_at: :required if attributes[:paid_at].blank?
+          argument! payment_intent_id: :required if attributes[:payment_intent_id].blank?
+        end
+
+        # @rbs () -> ::Hash[::Symbol, untyped]
+        def reservation
+          @reservation ||= Show.new.call!(reservation_id: @reservation_id, fields: %w[money.isFullyPaid money.payments money.totalPaid]).value!
+        end
+
+        # @rbs () -> bool
+        def fully_paid?
+          reservation[:money][:isFullyPaid]
+        end
+
+        # @rbs (::Hash[::Symbol, untyped] attributes) -> bool
+        def recorded?(attributes)
+          payments = reservation[:money][:payments]
+
+          return payments.any? { |payment| payment[:note]&.include?(attributes[:payment_intent_id]) } if payments
+          return false if reservation[:money][:totalPaid]&.zero?
+
+          error! HISTORY_UNAVAILABLE
+        end
+
+        # @rbs (::Hash[::Symbol, untyped] attributes) -> ::Hash[::Symbol, untyped]
+        def payload(attributes)
+          {
+            paymentMethod: {
+              method: PAYMENT_METHOD_NAME
+            },
+            amount: attributes[:amount],
+            paidAt: attributes[:paid_at].strftime('%Y-%m-%d'),
+            note: "Payment recorded in Guestit.se / Stripe #{attributes[:payment_intent_id]}"
+          }
+        end
+      end
+    end
+  end
+end

data/lib/guesty/reservations/pre_approve.rb

@@ -0,0 +1,23 @@
+module Guesty
+  module Reservations
+    # Pre-approves an inquiry (Airbnb only, asynchronous). An inquiry cannot be
+    # declined through the API.
+    class PreApprove
+      include Guesty::Operation
+
+      # @rbs (reservation_id: ::String) -> Dry::Monads::Result[bool]
+      def call(reservation_id:)
+        argument! reservation_id: :required if reservation_id.blank?
+
+        response = Guesty.do_request(
+          :post,
+          "reservations-v3/#{reservation_id}/pre-approve",
+          retries: 0
+        )
+        return response unless response.success?
+
+        Success(true)
+      end
+    end
+  end
+end

data/lib/guesty/reservations/recover.rb

@@ -0,0 +1,27 @@
+module Guesty
+  module Reservations
+    # Finds the Guesty reservation matching a confirmation code and stay window,
+    # skipping canceled ones. Returns nil when none matches.
+    class Recover
+      include Guesty::Operation
+
+      # @rbs (confirmation_code: ::String, start_date: ::Date, end_date: ::Date) -> Dry::Monads::Result[::String?]
+      def call(confirmation_code:, start_date:, end_date:)
+        fields = %w[_id listingId checkInDateLocalized checkOutDateLocalized status confirmationCode]
+        attributes = { confirmation_code: }
+        result = Guesty::Reservations::Search.new.call!(
+          fields:,
+          attributes:,
+          take: 2
+        ).value!
+        candidate = result.fetch(:results).find do |reservation|
+          reservation[:status] != CANCELLED_STATUS &&
+            reservation[:checkInDateLocalized] == start_date.iso8601 &&
+            reservation[:checkOutDateLocalized] == end_date.iso8601
+        end
+
+        Success(candidate&.dig(:_id))
+      end
+    end
+  end
+end

data/lib/guesty/reservations/reviews/extractors/airbnb.rb

@@ -0,0 +1,66 @@
+module Guesty
+  module Reservations
+    module Reviews
+      module Extractors
+        # Airbnb raw reviews carry category_ratings[].review_category_tags.
+        class Airbnb < Base
+          POSITIVE_TAG = 'GUEST_REVIEW_HOST_POSITIVE_'.freeze #: ::String
+          NEGATIVE_TAG = 'GUEST_REVIEW_HOST_NEGATIVE_'.freeze #: ::String
+
+          private
+
+          # @rbs (::Hash[::Symbol, untyped] raw_review) -> ::Hash[::Symbol, untyped]
+          def extract(raw_review)
+            codes = tag_codes(raw_review)
+
+            {
+              **super,
+              positive_tags: tags(codes, POSITIVE_TAG),
+              negative_tags: tags(codes, NEGATIVE_TAG),
+              other_tags: codes.reject { it.start_with?(POSITIVE_TAG, NEGATIVE_TAG) }.map(&:downcase)
+            }
+          end
+
+          def extract_text(raw_review)
+            {
+              public: raw_review[:public_review],
+              private: raw_review[:private_feedback]
+            }.compact_blank
+          end
+
+          def extract_scores(raw_review)
+            scores = { rating: raw_review[:overall_rating]&.to_f }
+
+            category_ratings = raw_review[:category_ratings]
+            return unless category_ratings.is_a?(Array)
+
+            category_ratings.each do |rating_entry|
+              next unless rating_entry.is_a?(Hash)
+
+              category = rating_entry[:category].downcase.to_sym
+              rating = rating_entry[:rating]
+
+              scores[category] = rating.to_f if category.present? && rating.present?
+            end
+
+            scores.compact
+          end
+
+          # @rbs (::Hash[::Symbol, untyped] raw_review) -> ::Array[::String]
+          def tag_codes(raw_review)
+            category_ratings = raw_review[:category_ratings]
+
+            return [] unless category_ratings.is_a?(Array)
+
+            category_ratings.flat_map { it[:review_category_tags] }
+          end
+
+          # @rbs (::Array[::String] codes, ::String prefix) -> ::Array[::String]
+          def tags(codes, prefix)
+            codes.select { it.start_with?(prefix) }.map { it.delete_prefix(prefix).downcase }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/guesty/reservations/reviews/extractors/base.rb

@@ -0,0 +1,36 @@
+module Guesty
+  module Reservations
+    module Reviews
+      module Extractors
+        class Base
+          include Guesty::Operation
+
+          # @rbs (raw_review: ::Hash[::Symbol, untyped]) -> Dry::Monads::Result[::Hash[::Symbol, untyped]]
+          def call(raw_review:)
+            argument! raw_review: :required, fatal: true if raw_review.blank?
+
+            Success(extract(raw_review))
+          end
+
+          private
+
+          # @rbs (::Hash[::Symbol, untyped] raw_review) -> ::Hash[::Symbol, untyped]
+          def extract(raw_review)
+            {
+              text: extract_text(raw_review),
+              scores: extract_scores(raw_review)
+            }
+          end
+
+          def extract_text(raw_review)
+            raise NotImplementedError, "#{self.class} must implement #extract_text"
+          end
+
+          def extract_scores(raw_review)
+            raise NotImplementedError, "#{self.class} must implement #extract_scores"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/guesty/reservations/reviews/extractors/booking_com.rb

@@ -0,0 +1,35 @@
+module Guesty
+  module Reservations
+    module Reviews
+      module Extractors
+        class BookingCom < Base
+          private
+
+          def extract_text(raw_review)
+            {
+              public: [
+                raw_review.dig(:content, :headline),
+                raw_review.dig(:content, :positive),
+                raw_review.dig(:content, :negative)
+              ].compact_blank.join(' ').presence
+            }
+          end
+
+          def extract_scores(raw_review)
+            scores = {} #: ::Hash[::Symbol, untyped]
+            category_ratings = raw_review[:scoring]
+            return unless category_ratings.is_a?(Hash)
+
+            category_ratings.each do |category, rating|
+              scores[category.to_sym] = (rating.to_f / 2).round(2) # Booking.com gives 1-10, we want 0-5
+            end
+
+            scores[:rating] = scores[:review_score]
+            scores[:cleanliness] = scores[:clean]
+            scores.except(:clean, :review_score).compact
+          end
+        end
+      end
+    end
+  end
+end

data/lib/guesty/reservations/reviews/extractors/vrbo.rb

@@ -0,0 +1,46 @@
+module Guesty
+  module Reservations
+    module Reviews
+      module Extractors
+        class Vrbo < Base
+          private
+
+          def extract_text(raw_review)
+            {
+              public: [
+                raw_review.dig(:title, :value),
+                raw_review.dig(:body, :value)
+              ].compact.reject(&:empty?).join(' ').presence
+            }
+          end
+
+          def extract_scores(raw_review)
+            scores = { rating: raw_review[:starRatingOverall].to_f }
+
+            raw_ratings = raw_review[:starRatings]
+            return unless raw_ratings.is_a?(Array)
+
+            raw_ratings.each do |rating|
+              next unless rating.is_a?(Hash)
+
+              category_key = normalize_category(rating[:category].downcase.to_sym)
+              scores[category_key] ||= rating[:value].to_f
+            end
+
+            scores.compact
+          end
+
+          def normalize_category(category)
+            case category
+            when :roomcleanliness then :cleanliness
+            when :onlinelisting then :accuracy
+            when :overall then :rating
+            else
+              category
+            end
+          end
+        end
+      end
+    end
+  end
+end