guesty-client 0.1.0

data/lib/guesty/reservations/reviews/index.rb

@@ -0,0 +1,67 @@
+module Guesty
+  module Reservations
+    module Reviews
+      # startDate/endDate filter on the review's updatedAt, newest update first.
+      class Index
+        include Guesty::Operation
+
+        # @rbs (since: ::Time, ?skip: ::Integer, ?take: ::Integer) -> Dry::Monads::Result[::Array[::Hash[::Symbol, untyped]]]
+        def call(since:, skip: 0, take: 100)
+          argument! take: :invalid if take.blank? || take <= 0
+
+          response = Guesty.do_request(:get, 'reviews', query(since, skip, take))
+
+          return response unless response.success?
+
+          reviews = parse_reviews(response.value!.body[:data])
+
+          Success(reviews)
+        end
+
+        private
+
+        # @rbs (::Time since, ::Integer skip, ::Integer take) -> ::Hash[::Symbol, untyped]
+        def query(since, skip, take)
+          {
+            startDate: since.utc.iso8601,
+            skip:,
+            limit: take
+          }
+        end
+
+        # @rbs (::Array[::Hash[::Symbol, untyped]] guesty_reviews_data) -> ::Array[::Hash[::Symbol, untyped]]
+        def parse_reviews(guesty_reviews_data)
+          return [] unless guesty_reviews_data.is_a?(Array)
+
+          guesty_reviews_data.map do |review_data|
+            next unless review_data[:rawReview].is_a?(Hash)
+
+            extractor = get_extractor_for_channel(review_data[:channelId]&.downcase)
+            result = extractor.new.call(raw_review: review_data[:rawReview])
+            next unless result.success?
+
+            result.value!.merge(
+              created_at: review_data[:createdAt],
+              guesty_review_id: review_data[:_id],
+              guesty_reservation_id: review_data[:reservationId]
+            )
+          end.compact
+        end
+
+        # @rbs (::String? channel) -> untyped
+        def get_extractor_for_channel(channel)
+          case channel.to_s.downcase
+          when /airbnb/i
+            Extractors::Airbnb
+          when /booking/i
+            Extractors::BookingCom
+          when /vrbo|homeaway/i
+            Extractors::Vrbo
+          else
+            error! "Unsupported channel: #{channel}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/guesty/reservations/search.rb

@@ -0,0 +1,63 @@
+module Guesty
+  module Reservations
+    # Searches the legacy /reservations index (deprecated, switching off at the
+    # end of 2026 — new reservation calls use reservations-v3).
+    class Search
+      include Guesty::Operation
+
+      FILTER_MAPPINGS = {
+        ids: { field: '_id', operator: '$in' },
+        updated_at: { field: 'lastUpdatedAt', operator: '$gt' },
+        conversation_id: { field: 'conversationId', operator: '$eq' },
+        status: { field: 'status', operator: '$eq' },
+        confirmation_code: { field: 'confirmationCode', operator: '$eq' }
+      }.freeze
+
+      # @rbs (::Hash[::Symbol, untyped] attributes) -> ::Array[::Hash[::Symbol, untyped]]
+      def self.filters(attributes)
+        attributes.map do |key, value|
+          normalized = key == :updated_at ? value&.strftime('%Y-%m-%d') : value
+
+          FILTER_MAPPINGS.fetch(key).merge(value: normalized)
+        end
+      end
+
+      # @rbs (fields: ::Array[::String], attributes: ::Hash[::Symbol, untyped], ?skip: ::Integer, ?take: ::Integer) -> Dry::Monads::Result[::Hash[::Symbol, untyped]]
+      def call(fields:, attributes:, skip: 0, take: 100)
+        validate_arguments!(fields:, attributes:, take:)
+
+        response = Guesty.do_request(:get, 'reservations', params(fields:, attributes:, skip:, take:))
+        return response unless response.success?
+
+        body = response.value!.body
+        result = {
+          results: body[:results],
+          count: body[:count]
+        }
+
+        Success(result)
+      end
+
+      private
+
+      def validate_arguments!(fields:, attributes:, take:)
+        argument! fields: :required, fatal: true if fields.blank?
+        argument! attributes: :required if attributes.blank?
+        argument! take: :invalid if take && take <= 0
+        argument! attributes: :invalid unless attributes.keys.all? { |name| FILTER_MAPPINGS.key?(name) }
+        argument! updated_at: :required if attributes.key?(:updated_at) && attributes[:updated_at].blank?
+        argument! ids: :required if attributes.key?(:ids) && attributes[:ids].empty?
+      end
+
+      def params(fields:, attributes:, skip:, take:)
+        {
+          filters: self.class.filters(attributes).to_json,
+          sort: 'createdAt',
+          limit: take,
+          skip:,
+          fields: fields.join(' ')
+        }
+      end
+    end
+  end
+end

data/lib/guesty/reservations/show.rb

@@ -0,0 +1,28 @@
+module Guesty
+  module Reservations
+    class Show
+      include Guesty::Operation
+
+      # @rbs (reservation_id: ::String, fields: ::Array[::String]) -> Dry::Monads::Result[::Hash[::Symbol, untyped]]
+      def call(reservation_id:, fields: [])
+        argument! reservation_id: :required if reservation_id.blank?
+        argument! fields: :required if fields.blank?
+
+        attributes = {} #: ::Hash[::Symbol, ::String]
+        attributes[:fields] = fields.join(' ') if fields.present?
+
+        response = Guesty.do_request :get, "reservations/#{reservation_id}", attributes
+
+        Success(handle_response(response))
+      end
+
+      private
+
+      def handle_response(response)
+        raise response.failure unless response.success?
+
+        response.value!.body
+      end
+    end
+  end
+end

data/lib/guesty/reservations/status/cancel.rb

@@ -0,0 +1,34 @@
+module Guesty
+  module Reservations
+    module Status
+      class Cancel
+        include Guesty::Operation
+
+        CANCELLED_BY = {
+          guest: 'GUEST',
+          owner: 'OWNER',
+          staff: 'TEAM_MEMBER'
+        }.freeze #: ::Hash[::Symbol, ::String]
+
+        # @rbs (reservation_id: ::String, note: ::String, cancelled_by: ::Symbol) -> Dry::Monads::Result[bool]
+        def call(reservation_id:, note:, cancelled_by:)
+          argument! reservation_id: :required if reservation_id.blank?
+          argument! note: :required if note.blank?
+          argument! cancelled_by: :invalid unless CANCELLED_BY.key?(cancelled_by)
+
+          Update.new.call!(
+            reservation_id:,
+            attributes: {
+              status: CANCELLED_STATUS,
+              cancellationReason: 'No Reason Provided',
+              cancellationNote: note,
+              canceledBy: CANCELLED_BY.fetch(cancelled_by)
+            }
+          )
+
+          Success(true)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+module Guesty
+  module Reservations
+    module Status
+      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?
+
+          response = Guesty.do_request :put, "reservations-v3/#{reservation_id}/status", attributes
+
+          raise response.failure unless response.success?
+
+          Success(true)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+module Guesty
+  module Reservations
+    module Stays
+      class Update
+        include Guesty::Operation
+
+        # @rbs (reservation_id: ::String, stay: ::Hash[::Symbol, untyped]) -> Dry::Monads::Result[bool]
+        def call(reservation_id:, stay:)
+          response = Guesty.do_request(
+            :put,
+            "reservations/#{reservation_id}",
+            stay_attributes(stay)
+          )
+
+          raise response.failure if response.failure?
+
+          Success(true)
+        end
+
+        private
+
+        # @rbs (::Hash[::Symbol, untyped] stay) -> ::Hash[::Symbol, untyped]
+        def stay_attributes(stay)
+          {
+            checkInDateLocalized: stay.fetch(:start_date).iso8601,
+            checkOutDateLocalized: stay.fetch(:end_date).iso8601,
+            plannedArrival: stay.fetch(:check_in).strftime('%H:%M'),
+            plannedDeparture: stay.fetch(:check_out).strftime('%H:%M'),
+            guestsCount: stay.fetch(:num_guests),
+            numberOfGuests: {
+              numberOfAdults: stay.fetch(:adults),
+              numberOfChildren: stay.fetch(:children)
+            },
+            ignoreCalendar: stay.fetch(:ignore_calendar),
+            ignoreTerms: true,
+            listingId: stay.fetch(:listing_external_id)
+          }
+        end
+      end
+    end
+  end
+end

data/lib/guesty/reservations/update.rb

@@ -0,0 +1,19 @@
+module Guesty
+  module Reservations
+    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?
+
+        response = Guesty.do_request :put, "reservations/#{reservation_id}", attributes
+
+        raise response.failure unless response.success?
+
+        Success(true)
+      end
+    end
+  end
+end

data/lib/guesty/reservations.rb

@@ -0,0 +1,13 @@
+module Guesty
+  module Reservations
+    CANCELLED_STATUS = 'canceled'.freeze #: ::String
+    CLOSED_STATUSES = %w[canceled closed declined expired].freeze #: ::Array[::String]
+
+    # @rbs (untyped conversation) -> ::Array[::Hash[::Symbol, untyped]]
+    def self.from_conversation(conversation)
+      (conversation.dig(:meta, :reservations) || []).filter_map do |reservation|
+        { id: reservation[:_id], closed: CLOSED_STATUSES.include?(reservation[:status]) } if reservation[:_id]
+      end
+    end
+  end
+end

data/lib/guesty/reviews/respond.rb

@@ -0,0 +1,19 @@
+module Guesty
+  module Reviews
+    class Respond
+      include Guesty::Operation
+
+      # @rbs (review_id: ::String, text: ::String) -> Dry::Monads::Result[bool]
+      def call(review_id:, text:)
+        argument! review_id: :required if review_id.blank?
+        argument! text: :required if text.blank?
+
+        response = Guesty.do_request(:put, "reviews/#{review_id}/reply", { reviewReply: text })
+
+        raise response.failure unless response.success?
+
+        Success(true)
+      end
+    end
+  end
+end

data/lib/guesty/version.rb

@@ -0,0 +1,3 @@
+module Guesty
+  VERSION = '0.1.0'.freeze
+end

data/lib/guesty/views/create.rb

@@ -0,0 +1,19 @@
+module Guesty
+  module Views
+    class Create
+      include Guesty::Operation
+
+      # @rbs (title: ::String, section: ::String) -> Dry::Monads::Result[::Hash[::Symbol, untyped]]
+      def call(title:, section:)
+        argument! title: :required if title.blank?
+        argument! section: :required if section.blank?
+
+        response = Guesty.do_request :post, 'views', { title:, section: }
+
+        raise response.failure unless response.success?
+
+        Success(response.value!.body)
+      end
+    end
+  end
+end

data/lib/guesty/views/update.rb

@@ -0,0 +1,33 @@
+module Guesty
+  module Views
+    class Update
+      include Guesty::Operation
+
+      # @rbs (id: ::String, ?title: ::String?, ?fields: ::String?, ?filters: ::Array[::Hash[::Symbol, untyped]]?, ?sort: ::String?) -> Dry::Monads::Result[untyped]
+      def call(id:, title: nil, fields: nil, filters: nil, sort: nil)
+        argument! id: :required if id.blank?
+        argument! attributes: :invalid if [title, fields, filters, sort].all?(&:nil?)
+
+        response = Guesty.do_request :put,
+                                     "views/#{id}",
+                                     payload(
+                                       id,
+                                       title:,
+                                       fields:,
+                                       filters:,
+                                       sort:
+                                     )
+
+        raise response.failure unless response.success?
+
+        Success(response.value!.body)
+      end
+
+      private
+
+      def payload(id, title:, fields:, filters:, sort:)
+        { _id: id, title:, fields:, filters:, sort: }.compact
+      end
+    end
+  end
+end

data/lib/guesty/webhooks/create.rb

@@ -0,0 +1,21 @@
+module Guesty
+  module Webhooks
+    class Create
+      include Guesty::Operation
+
+      # @rbs (url: ::String, events: ::Array[::String]) -> Dry::Monads::Result[::Hash[::Symbol, untyped]]
+      def call(url:, events:)
+        argument! url: :required if url.blank?
+        argument! events: :required if events.blank?
+
+        response = Guesty.do_request :post, 'webhooks', { url:, events: }
+
+        if response.success?
+          Success(response.value!.body)
+        else
+          response
+        end
+      end
+    end
+  end
+end

data/lib/guesty/webhooks/index.rb

@@ -0,0 +1,18 @@
+module Guesty
+  module Webhooks
+    class Index
+      include Guesty::Operation
+
+      # @rbs () -> Dry::Monads::Result[::Array[untyped]]
+      def call
+        response = Guesty.do_request :get, 'webhooks'
+
+        if response.success?
+          Success(response.value!.body)
+        else
+          response
+        end
+      end
+    end
+  end
+end

data/lib/guesty/webhooks/signatures/verify.rb

@@ -0,0 +1,76 @@
+require 'base64'
+require 'openssl'
+
+module Guesty
+  module Webhooks
+    # Guesty delivers webhooks through Svix, which signs every request. The secret is the
+    # base64 after the optional whsec_ prefix of the account signing key, the signed content is
+    # "<svix-id>.<svix-timestamp>.<raw body>", and svix-signature lists space-separated
+    # "version,base64-HMAC-SHA256" entries, one per active key.
+    module Signatures
+      class Verify
+        include Guesty::Operation
+
+        SECRET_PREFIX = 'whsec_'.freeze
+        SIGNATURE_VERSION = 'v1'.freeze
+        TOLERANCE = 5.minutes.freeze #: ActiveSupport::Duration
+
+        # @rbs (payload: ::String, headers: untyped) -> Dry::Monads::Result[bool]
+        def call(payload:, headers:)
+          argument! payload: :required if payload.nil?
+          argument! headers: :required if headers.nil?
+
+          id = headers['svix-id']
+          timestamp = headers['svix-timestamp']
+          signatures = headers['svix-signature']
+
+          error! 'Missing Svix headers' if id.blank? || timestamp.blank? || signatures.blank?
+
+          verify_timestamp!(timestamp)
+          error! 'No matching Svix signature' unless signed?(signatures, sign(id, timestamp, payload))
+
+          Success(true)
+        end
+
+        private
+
+        # A timestamp outside the tolerance fails even with a valid signature, so a captured
+        # delivery cannot be replayed later.
+        # @rbs (untyped header) -> void
+        def verify_timestamp!(header)
+          timestamp = Integer(header, exception: false)
+          error! 'Invalid Svix timestamp' if timestamp.nil?
+          error! 'Svix timestamp is outside the tolerance' unless timestamp.between?(TOLERANCE.ago.to_i, TOLERANCE.from_now.to_i)
+        end
+
+        # @rbs (::String id, ::String timestamp, ::String payload) -> ::String
+        def sign(id, timestamp, payload)
+          Base64.strict_encode64(
+            OpenSSL::HMAC.digest(
+              'sha256',
+              secret,
+              "#{id}.#{timestamp}.#{payload}"
+            )
+          )
+        end
+
+        # @rbs (::String header, ::String expected) -> bool
+        def signed?(header, expected)
+          header.split.any? do |versioned_signature|
+            version, signature = versioned_signature.split(',', 2)
+
+            version == SIGNATURE_VERSION && signature && ActiveSupport::SecurityUtils.secure_compare(signature, expected)
+          end
+        end
+
+        # @rbs () -> ::String
+        def secret
+          decoded = Base64.decode64(Guesty.webhook_key.to_s.delete_prefix(SECRET_PREFIX))
+          error! 'Guesty webhook signing key is not configured' if decoded.empty?
+
+          decoded
+        end
+      end
+    end
+  end
+end

data/lib/guesty/webhooks/sync.rb

@@ -0,0 +1,36 @@
+module Guesty
+  module Webhooks
+    # Subscribes the urls to the events: creates the missing, updates the
+    # drifted, leaves the rest. Returns the urls grouped by :created, :updated,
+    # :unchanged.
+    class Sync
+      include Guesty::Operation
+
+      # @rbs (urls: ::Array[::String], events: ::Array[::String]) -> Dry::Monads::Result[::Hash[::Symbol, ::Array[::String]]]
+      def call(urls:, events:)
+        argument! urls: :required if urls.blank?
+        argument! events: :required if events.blank?
+
+        webhooks = Index.new.call!.value!
+        existing = webhooks.index_by { |webhook| webhook[:url].strip }
+
+        Success(urls.group_by { |url| reconcile(url, events, existing[url]) })
+      end
+
+      private
+
+      # @rbs (::String url, ::Array[::String] events, ::Hash[::Symbol, untyped]? current) -> ::Symbol
+      def reconcile(url, events, current)
+        if current.nil?
+          Create.new.call!(url:, events:)
+          :created
+        elsif current[:events].to_set != events.to_set
+          Update.new.call!(id: current[:_id], url:, events:)
+          :updated
+        else
+          :unchanged
+        end
+      end
+    end
+  end
+end

data/lib/guesty/webhooks/update.rb

@@ -0,0 +1,22 @@
+module Guesty
+  module Webhooks
+    class Update
+      include Guesty::Operation
+
+      # @rbs (id: ::String, url: ::String, events: ::Array[::String]) -> Dry::Monads::Result[::Hash[::Symbol, untyped]]
+      def call(id:, url:, events:)
+        argument! id: :required if id.blank?
+        argument! url: :required if url.blank?
+        argument! events: :required if events.blank?
+
+        response = Guesty.do_request :put, "webhooks/#{id}", { url:, events: }
+
+        if response.success?
+          Success(response.value!.body)
+        else
+          response
+        end
+      end
+    end
+  end
+end

data/lib/guesty-client.rb

@@ -0,0 +1 @@
+require_relative 'guesty'

data/lib/guesty.rb

@@ -0,0 +1,78 @@
+require 'active_support'
+require 'active_support/core_ext'
+require 'active_support/security_utils'
+require 'dry/monads'
+require 'faraday'
+require 'faraday/retry'
+require 'mini_mime'
+require 'oj'
+
+require_relative 'guesty/version'
+require_relative 'guesty/error'
+require_relative 'guesty/memory_token_store'
+require_relative 'guesty/memory_rate_limiter'
+require_relative 'guesty/config'
+require_relative 'guesty/operation'
+require_relative 'guesty/rate_limiter_middleware'
+require_relative 'guesty/api_error'
+require_relative 'guesty/client'
+require_relative 'guesty/access_tokens/upsert'
+require_relative 'guesty/conversations'
+require_relative 'guesty/conversations/attachments/index'
+require_relative 'guesty/conversations/index'
+require_relative 'guesty/conversations/messages/reply'
+require_relative 'guesty/conversations/posts/index'
+require_relative 'guesty/conversations/posts/since'
+require_relative 'guesty/conversations/search'
+require_relative 'guesty/conversations/show'
+require_relative 'guesty/guest_folio/invoice_items/index'
+require_relative 'guesty/guests'
+require_relative 'guesty/guests/profiles/create'
+require_relative 'guesty/guests/profiles/show'
+require_relative 'guesty/guests/profiles/update'
+require_relative 'guesty/homes/calendars/show'
+require_relative 'guesty/homes/search'
+require_relative 'guesty/reservations'
+require_relative 'guesty/reservations/accommodation_fare/update'
+require_relative 'guesty/reservations/approve'
+require_relative 'guesty/reservations/create'
+require_relative 'guesty/reservations/custom_fields/update'
+require_relative 'guesty/reservations/dates/update'
+require_relative 'guesty/reservations/decline'
+require_relative 'guesty/reservations/flags/update'
+require_relative 'guesty/reservations/payments/create'
+require_relative 'guesty/reservations/pre_approve'
+require_relative 'guesty/reservations/recover'
+require_relative 'guesty/reservations/reviews/extractors/base'
+require_relative 'guesty/reservations/reviews/extractors/airbnb'
+require_relative 'guesty/reservations/reviews/extractors/booking_com'
+require_relative 'guesty/reservations/reviews/extractors/vrbo'
+require_relative 'guesty/reservations/reviews/index'
+require_relative 'guesty/reservations/search'
+require_relative 'guesty/reservations/show'
+require_relative 'guesty/reservations/status/cancel'
+require_relative 'guesty/reservations/status/update'
+require_relative 'guesty/reservations/stays/update'
+require_relative 'guesty/reservations/update'
+require_relative 'guesty/reviews/respond'
+require_relative 'guesty/views/create'
+require_relative 'guesty/views/update'
+require_relative 'guesty/webhooks/create'
+require_relative 'guesty/webhooks/index'
+require_relative 'guesty/webhooks/signatures/verify'
+require_relative 'guesty/webhooks/sync'
+require_relative 'guesty/webhooks/update'
+
+module Guesty
+  class << self
+    # @rbs () { (Config) -> void } -> void
+    def configure
+      yield(config)
+    end
+
+    # @rbs () -> Config
+    def config
+      @config ||= Config.new
+    end
+  end
+end