guesty-client 0.1.0

data/lib/guesty/conversations/messages/reply.rb

@@ -0,0 +1,55 @@
+module Guesty
+  module Conversations
+    module Messages
+      class Reply
+        include Guesty::Operation
+
+        # Guesty module type per booking channel; direct channels go by email.
+        BOOKING_MODULE_TYPES = {
+          'airbnb' => 'airbnb2',
+          'booking_com' => 'bookingCom',
+          'guestit' => 'email',
+          'core_manual' => 'email',
+          'core_group_manual' => 'email',
+          'ago' => 'email',
+          'owner_stay' => 'email'
+        }.freeze #: ::Hash[::String, ::String]
+
+        # @rbs (::String? channel_name) -> ::String?
+        def self.module_type_for(channel_name)
+          BOOKING_MODULE_TYPES[channel_name]
+        end
+
+        # @rbs (conversation_id: String, body: String, ?module_type: String?) -> Dry::Monads::Result[Hash[Symbol, untyped]]
+        def call(conversation_id:, body:, module_type: nil)
+          argument! conversation_id: :required, fatal: true if conversation_id.blank?
+          argument! body: :required, fatal: true if body.blank?
+          argument! module_type: :invalid, fatal: true if !module_type.nil? && module_type.blank?
+
+          # On `platform` Guesty picks the booking channel, or email, and echoes the channel it used.
+          response = Guesty.do_request(
+            :post,
+            "communication/conversations/#{conversation_id}/send-message",
+            { module: { type: module_type || 'platform' }, body: },
+            retries: 0
+          )
+          return response unless response.success?
+
+          Success(normalize(response.value!.body.fetch(:data)))
+        end
+
+        private
+
+        def normalize(post)
+          {
+            message_id: post.fetch(:_id),
+            conversation_id: post.fetch(:conversationId),
+            module_type: post.dig(:module, :type),
+            body: post.fetch(:body),
+            created_at: Time.iso8601(post.fetch(:createdAt))
+          }
+        end
+      end
+    end
+  end
+end

data/lib/guesty/conversations/posts/index.rb

@@ -0,0 +1,121 @@
+module Guesty
+  module Conversations
+    module Posts
+      class Index
+        include Guesty::Operation
+
+        LIMIT = 500
+        LOG_SENDER = 'log'.freeze #: ::String
+        SENDERS = ['guest', 'host', LOG_SENDER].freeze #: ::Array[::String]
+        SYSTEM_MODULE_TYPES = %w[note aiSummary].freeze #: ::Array[::String]
+        INVALID_RESPONSE = 'Guesty posts response has an unexpected shape.'.freeze #: ::String
+
+        # @rbs (conversation_id: ::String, ?cursor: ::String?) -> Dry::Monads::Result[::Hash[::Symbol, untyped]]
+        def call(conversation_id:, cursor: nil)
+          argument! conversation_id: :required if conversation_id.blank?
+
+          response = Guesty.do_request(
+            :get,
+            "communication/conversations/#{conversation_id}/posts",
+            query(cursor)
+          )
+          return response unless response.success?
+
+          Success(normalize_response(response.value!.body[:data]))
+        end
+
+        private
+
+        # @rbs (untyped data) -> ::Hash[::Symbol, untyped]
+        def normalize_response(data)
+          raw_posts = data.is_a?(Hash) ? data[:posts] : nil #: ::Array[untyped]?
+          error! INVALID_RESPONSE unless raw_posts.is_a?(Array)
+
+          posts = raw_posts.filter_map { |post| normalize_post(post) }
+          { results: posts, cursor_after: data.dig(:cursor, :after).presence, oldest_created_at: oldest_created_at(raw_posts) }
+        end
+
+        # Taken before the filter. A page of only skipped post types must still tell the caller
+        # how far back it reached.
+        # @rbs (::Array[untyped] raw_posts) -> ::Time?
+        def oldest_created_at(raw_posts)
+          raw_posts.filter_map { |post| Time.iso8601(post[:createdAt]) if post[:createdAt].present? }.min
+        end
+
+        def query(cursor)
+          params = { limit: LIMIT, sort: '-createdAt' }
+          params[:cursorAfter] = cursor if cursor.present?
+          params
+        end
+
+        def normalize_attachments(attachments)
+          attachments.map { |attachment| attachment_media_type(attachment[:type]) }
+        end
+
+        # Parallel to #normalize_attachments. Index N names the same attachment in both arrays,
+        # so a missing attachmentUrl keeps its slot as an empty string.
+        def normalize_attachment_keys(attachments)
+          attachments.map { |attachment| attachment[:attachmentUrl].to_s }
+        end
+
+        def attachment_media_type(type)
+          return 'application/octet-stream' unless type.is_a?(String) && type.present?
+          return type if type.include?('/')
+
+          MiniMime.lookup_by_extension(type)&.content_type || 'application/octet-stream'
+        end
+
+        # Guesty allows a post that is only an attachment. A post with neither text nor a file
+        # carries nothing. Provider-side automation posts stay visible so the host does not answer a
+        # turn that was already answered.
+        def importable?(post, attachments)
+          return false if post[:_id].blank? || post[:createdAt].blank?
+          return false if SYSTEM_MODULE_TYPES.include?(post.dig(:module, :type))
+
+          SENDERS.include?(post[:sentBy]) && (post[:body].present? || attachments.any?)
+        end
+
+        # provider_reservation_id routes the post to its stay and author_name lands on the sync row; neither is a message column.
+        # @rbs (untyped post) -> untyped
+        def normalize_post(post)
+          raw_attachments = post.fetch(:attachments, [])
+          attachments = normalize_attachments(raw_attachments)
+          return unless importable?(post, attachments)
+
+          {
+            provider_message_id: post[:_id],
+            sender_kind: sender_kind(post),
+            body: post[:body] || '',
+            attachments:,
+            attachment_keys: normalize_attachment_keys(raw_attachments),
+            module_type: channel_type(post),
+            provider_reservation_id: post.dig(:module, :reservationId),
+            provider_occurred_at: Time.iso8601(post[:createdAt]),
+            author_name: author_name(post)
+          }
+        end
+
+        # Guesty's own scheduled posts and reservation logs are system posts. Everything else keeps the sender
+        # Guesty names.
+        # @rbs (untyped post) -> String
+        def sender_kind(post)
+          post[:isAutomatic] || post[:sentBy] == LOG_SENDER ? 'system' : post[:sentBy]
+        end
+
+        # @rbs (untyped post) -> String?
+        def channel_type(post)
+          post.dig(:module, :type) unless post[:sentBy] == LOG_SENDER
+        end
+
+        # Only a person answering from Guesty has a name worth keeping.
+        # @rbs (untyped post) -> String?
+        def author_name(post)
+          return if post[:isAutomatic] || post[:sentBy] != 'host'
+
+          name = post.dig(:from, :fullName)
+          name.presence if name.is_a?(String)
+        end
+      end
+    end
+  end
+end

data/lib/guesty/conversations/posts/since.rb

@@ -0,0 +1,37 @@
+module Guesty
+  module Conversations
+    module Posts
+      # Walks a thread newest-first until the page that reaches `since`, or to the end without one.
+      class Since
+        include Guesty::Operation
+
+        MAX_PAGES = 20
+
+        # @rbs (conversation_id: ::String, ?since: ::Time?) -> Dry::Monads::Result[::Array[untyped]]
+        def call(conversation_id:, since: nil)
+          argument! conversation_id: :required if conversation_id.blank?
+
+          posts = [] #: ::Array[untyped]
+          cursor = nil #: ::String?
+
+          MAX_PAGES.times do
+            page = Index.new.call!(conversation_id:, cursor:).value!
+            posts.concat(page.fetch(:results))
+
+            cursor = page.fetch(:cursor_after)
+            return Success(posts) if cursor.nil? || reached?(since, page.fetch(:oldest_created_at))
+          end
+
+          error! "Guesty conversation #{conversation_id} pagination exceeded #{MAX_PAGES} pages", fatal: true
+        end
+
+        private
+
+        # @rbs (::Time? since, ::Time? oldest_created_at) -> bool
+        def reached?(since, oldest_created_at)
+          since.present? && oldest_created_at.present? && oldest_created_at <= since
+        end
+      end
+    end
+  end
+end

data/lib/guesty/conversations/search.rb

@@ -0,0 +1,31 @@
+module Guesty
+  module Conversations
+    class Search
+      include Guesty::Operation
+
+      FIELDS = '_id meta.reservations._id meta.reservations.status'.freeze #: ::String
+
+      # @rbs (external_id: ::String) -> Dry::Monads::Result[::Hash[::Symbol, untyped]?]
+      def call(external_id:)
+        argument! external_id: :required if external_id.blank?
+
+        response = Guesty.do_request(:get, 'communication/conversations', query(external_id))
+        return response unless response.success?
+
+        conversation = response.value!.body[:data][:conversations].first
+
+        Success(conversation && { id: conversation.fetch(:_id), reservations: Guesty::Reservations.from_conversation(conversation) })
+      end
+
+      private
+
+      def query(external_id)
+        {
+          fields: FIELDS,
+          filters: [{ field: 'reservation._id', operator: '$eq', value: external_id }].to_json,
+          limit: 1
+        }
+      end
+    end
+  end
+end

data/lib/guesty/conversations/show.rb

@@ -0,0 +1,25 @@
+module Guesty
+  module Conversations
+    class Show
+      include Guesty::Operation
+
+      FIELDS = Search::FIELDS #: ::String
+
+      # @rbs (conversation_id: ::String) -> Dry::Monads::Result[::Hash[::Symbol, untyped]]
+      def call(conversation_id:)
+        argument! conversation_id: :required if conversation_id.blank?
+
+        response = Guesty.do_request(
+          :get,
+          "communication/conversations/#{conversation_id}",
+          { fields: FIELDS }
+        )
+        return response unless response.success?
+
+        conversation = response.value!.body[:data]
+
+        Success({ id: conversation.fetch(:_id), reservations: Guesty::Reservations.from_conversation(conversation) })
+      end
+    end
+  end
+end

data/lib/guesty/conversations.rb

@@ -0,0 +1,15 @@
+module Guesty
+  module Conversations
+    # Neutral channel names for Guesty's versioned module types.
+    CHANNELS = {
+      'airbnb2' => 'airbnb',
+      'bookingCom' => 'booking_com'
+    }.freeze #: ::Hash[::String, ::String]
+    VERSION_SUFFIX = /\d+\z/ #: ::Regexp
+
+    # @rbs (::String module_type) -> ::String
+    def self.channel(module_type)
+      CHANNELS.fetch(module_type) { module_type.sub(VERSION_SUFFIX, '') }
+    end
+  end
+end

data/lib/guesty/error.rb

@@ -0,0 +1,32 @@
+module Guesty
+  class Error < StandardError
+    attr_reader :fatal
+
+    # @rbs (?::String message, ?fatal: bool) -> void
+    def initialize(message = nil, fatal: false)
+      @fatal = fatal
+
+      super(message)
+    end
+  end
+
+  # Raised by operations before any network call when the arguments are unusable.
+  # fatal: true marks a refusal no retry can fix; the host decides what to do with it.
+  class ArgumentError < Error; end
+
+  # Raised by the rate limiter middleware when the injected limiter refuses the
+  # request: the call never left the process, so no write landed upstream.
+  class ThrottledError < Error
+    attr_reader :key, :threshold, :interval, :retry_after
+
+    # @rbs (key: ::Symbol, threshold: ::Integer, interval: untyped, retry_after: untyped) -> void
+    def initialize(key:, threshold:, interval:, retry_after:)
+      @key = key
+      @threshold = threshold
+      @interval = interval
+      @retry_after = retry_after
+
+      super("Rate limit exceeded for #{key}")
+    end
+  end
+end

data/lib/guesty/guest_folio/invoice_items/index.rb

@@ -0,0 +1,61 @@
+module Guesty
+  module GuestFolio
+    module InvoiceItems
+      # Closed Airbnb Resolution Center items: negative amounts are refunds and
+      # positive amounts are guest charges.
+      class Index
+        include Guesty::Operation
+
+        FIELDS = %w[normalType totalPrice logs.createdAt].freeze #: ::Array[::String]
+        INVALID_RESPONSE = 'Guesty invoice items response has an unexpected shape.'.freeze #: ::String
+
+        # @rbs (reservation_id: ::String) -> Dry::Monads::Result[::Array[untyped]]
+        def call(reservation_id:)
+          argument! reservation_id: :required if reservation_id.blank?
+
+          response = Guesty.do_request(:get, 'guest-folio/invoice-items', query(reservation_id))
+          return response unless response.success?
+
+          Success(normalize_response(response.value!.body, reservation_id))
+        end
+
+        private
+
+        # @rbs (::String reservation_id) -> ::Hash[::Symbol, ::String]
+        def query(reservation_id)
+          {
+            reservationIds: reservation_id,
+            fields: FIELDS.join(',')
+          }
+        end
+
+        # @rbs (untyped body, ::String reservation_id) -> ::Array[untyped]
+        def normalize_response(body, reservation_id)
+          results = body[:results] if body.is_a?(Hash)
+          error! INVALID_RESPONSE unless results.is_a?(Array)
+
+          result = results.find { |row| row[:reservationId] == reservation_id }
+          return [] if result.nil?
+
+          items = result[:invoiceItems]
+          error! INVALID_RESPONSE unless items.is_a?(Array) && result[:currency].present?
+
+          items.map { |item| normalize_item(item, result.fetch(:currency)) }
+        end
+
+        # @rbs (untyped item, ::String currency) -> untyped
+        def normalize_item(item, currency)
+          created_at = item.dig(:logs, :createdAt)
+
+          {
+            external_id: item.fetch(:id),
+            normal_type: item[:normalType],
+            amount: item[:totalPrice]&.to_d,
+            currency:,
+            occurred_at: (Time.iso8601(created_at) if created_at.present?)
+          }
+        end
+      end
+    end
+  end
+end

data/lib/guesty/guests/profiles/create.rb

@@ -0,0 +1,25 @@
+module Guesty
+  module Guests
+    module Profiles
+      class Create
+        include Guesty::Operation
+
+        REQUIRED_ATTRIBUTES = %i[firstName lastName].freeze #: ::Array[::Symbol]
+
+        # @rbs (attributes: ::Hash[::Symbol, untyped]) -> Dry::Monads::Result[::Hash[::Symbol, untyped]]
+        def call(attributes:)
+          argument! attributes: :required, fatal: true if attributes.blank?
+
+          missing = REQUIRED_ATTRIBUTES.find { |attribute| attributes[attribute].blank? }
+          argument! missing => :required if missing
+
+          response = Guesty.do_request :post, 'guests-crud', attributes, retries: 0
+
+          raise response.failure unless response.success?
+
+          Success(response.value!.body)
+        end
+      end
+    end
+  end
+end

data/lib/guesty/guests/profiles/show.rb

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

data/lib/guesty/guests/profiles/update.rb

@@ -0,0 +1,36 @@
+module Guesty
+  module Guests
+    module Profiles
+      class Update
+        include Guesty::Operation
+
+        # @rbs (guest_id: ::String, attributes: ::Hash[::Symbol, untyped]) -> Dry::Monads::Result[::Hash[::Symbol, untyped]]
+        def call(guest_id:, attributes:)
+          argument! guest_id: :required if guest_id.blank?
+          argument! attributes: :required, fatal: true if attributes.blank?
+
+          response = Guesty.do_request :put, "guests-crud/#{guest_id}", prepare_tags(guest_id, attributes)
+
+          raise response.failure unless response.success?
+
+          Success(response.value!.body)
+        end
+
+        private
+
+        # Actions on a single tag are not supported by Guesty.
+        # Instead, we fetch all tags and upload a modified array.
+        def prepare_tags(guest_id, attributes)
+          tags_to_add = attributes[:addTags] || []
+          tags_to_remove = attributes[:removeTags] || []
+          payload = attributes.except(:addTags, :removeTags)
+
+          return payload if tags_to_add.blank? && tags_to_remove.blank?
+
+          current_profile = Show.new.call!(guest_id:, fields: ['tags']).value!
+          payload.merge(tags: (current_profile[:tags] | tags_to_add) - tags_to_remove)
+        end
+      end
+    end
+  end
+end

data/lib/guesty/guests.rb

@@ -0,0 +1,5 @@
+module Guesty
+  module Guests
+    OTA_LINK_TYPES = { airbnb: 'airbnb' }.freeze
+  end
+end

data/lib/guesty/homes/calendars/show.rb

@@ -0,0 +1,134 @@
+module Guesty
+  module Homes
+    module Calendars
+      class Show
+        include Guesty::Operation
+
+        BLOCK_TYPE_MAPPING = {
+          m: :manual_block,
+          r: :reserved_date,
+          b: :booked_reservation,
+          bd: :blocked_by_default,
+          sr: :smart_calendar_rule,
+          abl: :annual_booking_limit,
+          a: :allotment_block,
+          bw: :booking_window,
+          o: :owner_reservation,
+          pt: :preparation_time,
+          ic: :ical_import,
+          an: :advance_notice,
+          cio: :check_in_out
+        }.freeze
+
+        # @rbs (home_id: ::String, start_date: ::Date, end_date: ::Date) -> Dry::Monads::Result[::Hash[::Symbol, untyped]]
+        def call(home_id:, start_date:, end_date:)
+          argument! home_id: :required if home_id.blank?
+          argument! end_date: :invalid if end_date <= start_date
+
+          response = fetch_calendar_data(home_id, start_date, end_date)
+
+          raise response.failure if response.failure?
+
+          Success(normalize_calendar(response.value!.body))
+        end
+
+        private
+
+        def fetch_calendar_data(home_id, start_date, end_date)
+          params = {
+            startDate: start_date,
+            endDate: end_date,
+            view: 'full'
+          }
+
+          Guesty.do_request :get, "availability-pricing/api/calendar/listings/minified/#{home_id}", params
+        end
+
+        def normalize_calendar(body)
+          calendar = body.dig(:data, :days) || {}
+          @blocks = calendar[:blocks] || {}
+          @days = calendar[:calendar] || []
+          available, unavailable = @days.partition { |day| available_day?(day) }
+
+          validate_currency(calendar[:currency], @days)
+
+          {
+            available: attrs_for_available(available),
+            unavailable: attrs_for_unavailable(unavailable),
+            blocks: attrs_for_blocks
+          }
+        end
+
+        # The host prices in one currency; a listing in another would silently
+        # misprice. Skipped when the host has not configured one.
+        # @rbs (::String? currency, ::Array[::Hash[::Symbol, untyped]] days) -> void
+        def validate_currency(currency, days)
+          return nil if days.empty? || Guesty.config.default_currency.nil?
+          return nil if currency.to_s.upcase == Guesty.config.default_currency
+
+          error! "unsupported currency #{currency}"
+        end
+
+        # @rbs (::Hash[::Symbol, untyped] day) -> bool
+        def available_day?(day)
+          day[:blocks].empty? || day_is_available_for_checkout?(day)
+        end
+
+        # @rbs (::Hash[::Symbol, untyped] day) -> bool
+        def day_is_available_for_checkout?(day)
+          return false if day[:blocks].except(:b).any?
+          return false if previous_night_blocked?(day)
+
+          day[:blockIds].any? { |id| @blocks.dig(id.to_sym, :reservation, :checkInDateLocalized) == day[:date] }
+        end
+
+        # @rbs (::Hash[::Symbol, untyped] day) -> bool
+        def previous_night_blocked?(day)
+          blocked_dates.include?(day[:date].to_date.prev_day.iso8601)
+        end
+
+        # @rbs () -> ::Set[::String]
+        def blocked_dates
+          @blocked_dates ||= @days.reject { |day| day[:blocks].empty? }.to_set { |day| day[:date] }
+        end
+
+        # @rbs (::Array[::Hash[::Symbol, untyped]] days) -> ::Array[::Hash[::Symbol, untyped]]
+        def attrs_for_available(days)
+          days.map do |day|
+            {
+              date: day[:date],
+              price: day[:price],
+              min_nights: day[:minNights],
+              check_in: day[:blocks].empty?
+            }
+          end
+        end
+
+        # @rbs (::Array[::Hash[::Symbol, untyped]] days) -> ::Array[::Hash[::Symbol, untyped]]
+        def attrs_for_unavailable(days)
+          days.map do |day|
+            {
+              date: day[:date],
+              price: day[:price],
+              min_nights: day[:minNights],
+              check_in: false,
+              blocked_as: day[:blocks].keys.filter_map { |key| BLOCK_TYPE_MAPPING[key] }
+            }
+          end
+        end
+
+        # @rbs () -> ::Array[::Hash[::Symbol, untyped]]
+        def attrs_for_blocks
+          @blocks.values.map do |block|
+            {
+              kind: BLOCK_TYPE_MAPPING[block[:type].to_sym],
+              start_date: block[:startDate].to_date,
+              end_date: block[:endDate].to_date,
+              comment: block[:note].presence
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/guesty/homes/search.rb

@@ -0,0 +1,46 @@
+module Guesty
+  module Homes
+    # `active` is a filter, so all listings take two passes. Tags come back as
+    # ids on the listing; tag names live on GET listings/tags.
+    class Search
+      include Guesty::Operation
+
+      # @example
+      #   attributes: {
+      #     params: { ids: 'guestyID', available: { checkIn: "YYYY-MM-DD", checkOut: "YYYY-MM-DD", minOccupancy: 3 }.to_json }
+      #     filters: [{ operator: '$eq', field: 'type', value: 'MTL_CHILD' }],
+      #     response_keys: %w[
+      #       _id
+      #       nickname
+      #       type
+      #     ]
+      #   }
+
+      # @rbs (attributes: ::Hash[::Symbol, untyped], ?skip: ::Integer, ?take: ::Integer) -> Dry::Monads::Result[::Hash[::Symbol, untyped]]
+      def call(attributes:, skip: 0, take: 100)
+        argument! take: :invalid if take.blank? || take <= 0
+
+        response = Guesty.do_request :get, 'listings', query(attributes, skip, take)
+
+        raise response.failure unless response.success?
+
+        body = response.value!.body
+
+        Success(body.slice(:results, :count))
+      end
+
+      private
+
+      def query(attributes, skip, take)
+        {
+          active: true,
+          fields: (attributes[:response_keys] || []).join(' '),
+          limit: take,
+          skip:,
+          **(attributes[:filters].present? ? { filters: attributes[:filters].to_json } : {}),
+          **(attributes[:params] || {})
+        }.compact_blank
+      end
+    end
+  end
+end

data/lib/guesty/memory_rate_limiter.rb

@@ -0,0 +1,28 @@
+module Guesty
+  # The default rate limiter: in-memory fixed windows per key. Per-process only;
+  # a host running several processes injects a shared backend, such as Redis,
+  # via Guesty.config.rate_limiter.
+  class MemoryRateLimiter
+    def initialize
+      @windows = {}
+    end
+
+    # @rbs (key: ::Symbol, threshold: ::Integer, interval: untyped) -> void
+    def throttle!(key:, threshold:, interval:)
+      now = Time.now
+      window_start, count = @windows.fetch(key, [now, 0])
+
+      if now >= window_start + interval
+        window_start = now
+        count = 0
+      end
+
+      count += 1
+      @windows[key] = [window_start, count]
+
+      return if count <= threshold
+
+      raise ThrottledError.new(key:, threshold:, interval:, retry_after: (window_start + interval) - now)
+    end
+  end
+end