guesty-client 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 83257fa001c6c49e93fc8e82a589f7021c5924e79aa37c4aba1ac39016190b91
+  data.tar.gz: 47f958e92a9567eaea516c9e65e1842fbf801e0f2bf298156f043e90ace89abc
+SHA512:
+  metadata.gz: b7d52343654868afa7b48544b81f088214c7201c89f408ea24104ad8c9fb7642466b53aab13be87e4d56cba4dada62578871c322dddc778255df010023b0b79b
+  data.tar.gz: faec56e53c7a5477e98a7db05c5d4156ed0e096764793a5a23ccd68ba93d50a0da102ad9cb7ce16c699e2cb30b9ae272a53c7960582d47474d7e9a453192fdaf

data/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-08
+
+First release as `guesty-client`, extracted from the Guesty integration Guestit runs in production. The specs are
+that integration's provider specs, ported with their recorded VCR cassettes.
+
+### Added
+
+- `Guesty.configure` for credentials per priority lane, the token store, the rate limiter, the slot picker, custom
+  field ids and the default currency. No Rails dependency.
+- Wire API on the `Guesty` module: `connection`, `do_request` with retries of known Guesty glitches, `with_priority`
+  lanes, credential slots (`token_slots`, `pick_slot`), the error helpers `retryable_read?`, `unapplied?` and
+  `delivery_unknown?`, and `webhook_key`.
+- Rate limits of 10 requests a second, 120 a minute and 5,000 an hour per credential slot.
+- `sig/guesty.rbs` declaring the public API.
+- Operations, each returning a dry-monads `Result`:
+  - `AccessTokens::Upsert`: OAuth client-credentials token, one stored token per slot.
+  - Reservations: `Search`, `Show`, `Create`, `Update`, `Recover`, `Approve`, `Decline`, `PreApprove`,
+    `Status::Update`, `Status::Cancel`, `Dates::Update`, `Stays::Update`, `Flags::Update`,
+    `AccommodationFare::Update`, `CustomFields::Update`, `Payments::Create`.
+  - Conversations: `Index`, `Show`, `Search`, `Posts::Index`, `Posts::Since`, `Messages::Reply`,
+    `Attachments::Index`, and the `Conversations.channel` and `Reservations.from_conversation` helpers.
+  - Reviews: `Reviews::Respond` and `Reservations::Reviews::Index` with extractors for Airbnb, Booking.com and Vrbo.
+  - Guests: `Profiles::Create`, `Profiles::Show`, `Profiles::Update`.
+  - Homes: `Search`, `Calendars::Show`.
+  - `GuestFolio::InvoiceItems::Index` for Airbnb Resolution Center items.
+  - Webhooks: `Index`, `Create`, `Update`, `Sync`, `Signatures::Verify` for Svix signatures.
+  - Views: `Create`, `Update`.
+
+[Unreleased]: https://github.com/guestitab/guesty-client/compare/v0.1.0...staging
+[0.1.0]: https://github.com/guestitab/guesty-client/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Guestit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,178 @@
+# guesty-client
+
+A Ruby client for the [Guesty Open API](https://open-api-docs.guesty.com/). Each endpoint is one operation class that
+returns a [dry-monads](https://dry-rb.org/gems/dry-monads/) `Result`. The gem handles OAuth tokens, rate limits,
+retries and webhook signatures. It does not depend on Rails, only on ActiveSupport and Faraday. Your app supplies the
+credentials, the token storage and the rate limiter.
+
+[Guestit](https://guestit.se) built it and runs it in production.
+
+Requires Ruby 4.0 or later.
+
+## Installation
+
+```ruby
+# Gemfile
+gem 'guesty-client'
+```
+
+Bundler loads it for you. Outside Bundler, `require 'guesty'`.
+
+## Configuration
+
+```ruby
+Guesty.configure do |config|
+  config.credentials = {
+    default: [
+      { client_id: ENV.fetch('GUESTY_CLIENT_ID'), secret: ENV.fetch('GUESTY_CLIENT_SECRET') }
+    ],
+    high: [
+      { client_id: ENV.fetch('GUESTY_HIGH_CLIENT_ID'), secret: ENV.fetch('GUESTY_HIGH_CLIENT_SECRET') }
+    ],
+    webhook_key: ENV.fetch('GUESTY_WEBHOOK_KEY')
+  }
+  config.token_store = MyTokenStore.new
+  config.rate_limiter = MyRateLimiter.new
+end
+```
+
+| Setting | Default | What it does |
+| --- | --- | --- |
+| `credentials` | `{}` | Client credentials per priority lane, plus the webhook signing key. |
+| `token_store` | `Guesty::MemoryTokenStore` | Holds one access token per credential slot. |
+| `rate_limiter` | `Guesty::MemoryRateLimiter` | Counts requests per slot and window. |
+| `slot_picker` | first slot | `->(slots, priority) { slot }`, called when a lane has several credentials. |
+| `custom_fields` | `{}` | Account custom field ids by flag name, read by `Reservations::Flags::Update`. |
+| `default_currency` | `nil` | When set, `Homes::Calendars::Show` refuses a calendar priced in another currency. |
+| `base_url` | `https://open-api.guesty.com/v1/` | API root. |
+
+### Access tokens
+
+Guesty mints 5 access tokens per client id per 24 hours and answers 429 to every request after that. The default
+memory store loses its tokens when the process exits, so it suits a console or a single long-running process. Once
+you run more than one process, or restart often, inject a shared store that keeps each token until it expires:
+
+```ruby
+class MyTokenStore
+  # Returns an object that responds to #access_token, or nil when no live token is stored.
+  def read(slot_key); end
+
+  # Persists the token and returns an object that responds to #access_token.
+  def save(slot_key:, access_token:, expires_at:); end
+end
+```
+
+### Rate limits
+
+Every request passes three windows per credential slot: 10 a second, 120 a minute and 5,000 an hour. The limiter
+raises `Guesty::ThrottledError` when a window is full, and the request is never sent. The memory limiter counts per
+process. With several processes, inject one backed by Redis or your cache:
+
+```ruby
+class MyRateLimiter
+  # Raises Guesty::ThrottledError.new(key:, threshold:, interval:, retry_after:) once
+  # more than threshold calls arrive for key within interval.
+  def throttle!(key:, threshold:, interval:); end
+end
+```
+
+### Priority lanes and slots
+
+Each key in `credentials` other than `webhook_key` is a lane. Requests run on `:default` unless wrapped:
+
+```ruby
+Guesty.with_priority(:high) do
+  Guesty::Reservations::Approve.new.call(reservation_id:)
+end
+```
+
+A lane with several credentials gets one slot per credential. Each slot has its own token and rate limit windows, and
+`slot_picker` chooses the slot for each request.
+
+## Usage
+
+Operations live under `Guesty::<Resource>::<Action>`. Build a fresh instance for every call:
+
+```ruby
+result = Guesty::Reservations::Show.new.call(reservation_id: '67ebc9c7c5904c0010502f89', fields: %w[status money])
+
+if result.success?
+  result.value!   # => { _id: '67ebc9c7c5904c0010502f89', status: 'confirmed', money: { ... } }
+else
+  result.failure  # => a Guesty::Error or a Faraday::Error
+end
+```
+
+`call` never raises. It returns `Success(value)` or `Failure(error)`. `call!` returns the `Success` and raises the
+error where `call` would return a `Failure`. Response bodies come back as hashes with symbol keys.
+
+The gem covers reservations (search, create, update, approve, decline, cancel, payments, custom fields, reviews),
+conversations and messages, guest profiles, listings and calendars, guest folio items, review responses, webhooks and
+saved views. [CHANGELOG.md](CHANGELOG.md) lists every operation.
+
+### Errors
+
+| Class | Raised when |
+| --- | --- |
+| `Guesty::ArgumentError` | The arguments are unusable. Raised before any request. |
+| `Guesty::ApiError` | Guesty answered with an error, including one tunnelled through an HTTP 200. `#status` and `#raw_body` hold the details. |
+| `Guesty::ThrottledError` | The rate limiter refused the request. Nothing was sent. |
+| `Guesty::Error` | The parent of the three above, also raised for refusals inside an operation. |
+
+`error.fatal` is true for a refusal that no retry can fix.
+
+### Retries
+
+The client retries a 429 and network failures with backoff on every method but POST. Reads also retry the known Guesty
+errors that a second attempt fixes; operations that must not write twice send once. After a failed write, these
+helpers tell you what happened:
+
+```ruby
+Guesty.unapplied?(error)        # the write certainly did not take, so a retry is safe
+Guesty.delivery_unknown?(error) # it may have taken, so read back before retrying
+Guesty.retryable_read?(error)   # a read failed for a reason a retry can fix
+```
+
+### Webhooks
+
+Guesty sends webhooks through Svix. Verify each delivery against the raw body and its headers before trusting it:
+
+```ruby
+Guesty::Webhooks::Signatures::Verify.new.call(payload: request.raw_post, headers: request.headers)
+# => Success(true), or a Failure when no signature matches or the timestamp is more than 5 minutes off
+```
+
+`Guesty::Webhooks::Sync.new.call(urls:, events:)` subscribes each url to the events. It creates missing webhooks,
+updates drifted ones and returns the urls grouped by `:created`, `:updated` and `:unchanged`.
+
+## Type signatures
+
+The gem ships RBS for its public API in `sig/guesty.rbs`. `rbs collection install` picks it up from your
+`Gemfile.lock`, so Steep sees it with no extra setup.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake        # specs and RuboCop
+bundle exec rspec       # specs only
+bundle exec rubocop -A  # autocorrect; review every change
+```
+
+The specs run offline against recorded VCR cassettes in `spec/fixtures/cassettes`. Recording a new cassette needs
+live credentials for a Guesty account. Scrub tokens, guest names and contact details from the cassette before you
+commit it.
+
+## Releasing
+
+1. Bump `Guesty::VERSION` in `lib/guesty/version.rb` and move the `Unreleased` notes in `CHANGELOG.md` under the new
+   version.
+2. Commit on `staging` and run `bundle exec rake`.
+3. Run `gem signin` once per machine. The gem requires MFA, so every push asks for a one-time code.
+4. Run `bundle exec rake release`. It builds `pkg/guesty-client-<version>.gem`, tags `v<version>`, pushes the branch
+   and the tag, and pushes the gem to RubyGems.
+5. Fast-forward `production` to the release tag.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

data/lib/guesty/access_tokens/upsert.rb

@@ -0,0 +1,61 @@
+module Guesty
+  module AccessTokens
+    # Ensures a live access token for the current credential slot: reuse the
+    # stored one, else mint one. Persistence, caching and expiry policy live in
+    # the injected token store (Guesty.config.token_store).
+    #
+    # Guesty mints only 5 access tokens per client id within 24 hours and
+    # answers 429 to everything after, so a token must never be discarded.
+    class Upsert
+      include Guesty::Operation
+
+      OAUTH_ENDPOINT = 'https://open-api.guesty.com/oauth2/token'.freeze #: ::String
+
+      # @rbs () -> Dry::Monads::Result[untyped]
+      def call
+        if (token = store.read(Guesty.current_slot[:key]))
+          return Success(token)
+        end
+
+        response = request_access_token
+        raise ApiError, response unless Guesty.successful_response?(response)
+
+        Success(save_token(response))
+      end
+
+      private
+
+      def store
+        Guesty.config.token_store
+      end
+
+      def client_id
+        Guesty.current_slot[:client_id]
+      end
+
+      def client_secret
+        Guesty.current_slot[:secret]
+      end
+
+      def request_access_token
+        Guesty.connection(url: OAUTH_ENDPOINT, skip_auth: true).post do |req|
+          req.headers['Content-Type'] = 'application/x-www-form-urlencoded'
+          req.body = {
+            grant_type: 'client_credentials',
+            scope: 'open-api',
+            client_secret:,
+            client_id:
+          }
+        end
+      end
+
+      def save_token(response)
+        store.save(
+          slot_key: Guesty.current_slot[:key],
+          access_token: response.body[:access_token],
+          expires_at: response.body[:expires_in].seconds.from_now
+        )
+      end
+    end
+  end
+end

data/lib/guesty/api_error.rb

@@ -0,0 +1,73 @@
+module Guesty
+  # A rejected Guesty response. Carries the response and its parsed body, and
+  # classifies transience so callers can tell a retryable glitch from a write
+  # that never landed (see Guesty.unapplied? and Guesty.delivery_unknown?).
+  class ApiError < Error
+    GLITCH_MESSAGES = [
+      /An invalid response was received from the upstream server/,
+      /Forbidden err/,
+      /Reservation Meta not found/,
+      /Write conflict during plan execution/,
+      /You don't have permission to access, please contact Guesty support/
+    ].freeze
+
+    RETRYABLE_NON_DELIVERY_STATUSES = [401, 403, 429].freeze #: ::Array[::Integer]
+    PERMANENT_REJECTION_STATUSES = [400, 404, 405, 409, 410, 415, 422].freeze #: ::Array[::Integer]
+    UPSTREAM_STATUS = /\ARequest failed with status code (\d{3})\z/ #: ::Regexp
+
+    attr_reader :raw_body, :response
+
+    # @rbs (Faraday::Response response) -> void
+    def initialize(response)
+      @response = response
+      @raw_body = response.body
+
+      super(error_message.to_s.presence || response.status.to_s)
+    end
+
+    # @rbs () -> Integer
+    def status
+      body_status = @raw_body[:status] if @raw_body.is_a?(Hash)
+      parsed_status = Integer(body_status, exception: false) || Integer(error_message.to_s[UPSTREAM_STATUS, 1], exception: false)
+
+      parsed_status && parsed_status >= 300 ? parsed_status : @response.status
+    end
+
+    def guesty_glitch?
+      GLITCH_MESSAGES.any? do |message|
+        error_message.to_s =~ message
+      end
+    end
+
+    # @rbs () -> bool
+    def retryable_non_delivery?
+      RETRYABLE_NON_DELIVERY_STATUSES.include?(status)
+    end
+
+    # @rbs () -> bool
+    def permanent_rejection?
+      PERMANENT_REJECTION_STATUSES.include?(status)
+    end
+
+    # @rbs () -> bool
+    def transient?
+      retryable_non_delivery? || guesty_glitch? || status == 408 || status >= 500
+    end
+
+    private
+
+    # @rbs () -> untyped
+    def error_message
+      return @raw_body unless @raw_body.respond_to?(:dig)
+
+      error_paths = [%i[error data], %i[error message], :message, :data, :error, :code]
+
+      error_message = error_paths.find do |path|
+        value = path.is_a?(Array) ? @raw_body.dig(*path) : @raw_body[path]
+        break value if value.present?
+      end
+
+      error_message.is_a?(Array) ? error_message.join(', ') : error_message || @raw_body
+    end
+  end
+end

data/lib/guesty/client.rb

@@ -0,0 +1,138 @@
+module Guesty
+  extend Dry::Monads::Result::Mixin
+
+  BASE_URL = 'https://open-api.guesty.com/v1/'.freeze #: ::String
+  TIMEOUT = 20 #: ::Integer
+
+  RETRY_OPTIONS = {
+    max: 50,
+    interval: 1.0,
+    interval_randomness: 0.5,
+    backoff_factor: 1,
+    retry_statuses: [429],
+    exceptions: [*Faraday::Retry::Middleware::DEFAULT_EXCEPTIONS, Faraday::ConnectionFailed],
+    methods: [*Faraday::Retry::Middleware::IDEMPOTENT_METHODS, :patch]
+  }.freeze #: ::Hash[::Symbol, untyped]
+
+  # @rbs (?url: ::String, ?skip_auth: bool, ?timeout: ::Integer) -> Faraday::Connection
+  def self.connection(url: config.base_url, skip_auth: false, timeout: TIMEOUT)
+    Faraday.new(url:) do |builder|
+      builder.request :authorization, 'Bearer', -> { auth_token } unless skip_auth
+
+      builder.request :json
+      builder.request :retry, RETRY_OPTIONS
+
+      builder.request :guesty_rate_limiter, threshold: 10, interval: 1.second, key: -> { rate_limit_key(:second) }
+      builder.request :guesty_rate_limiter, threshold: 120, interval: 1.minute, key: -> { rate_limit_key(:minute) }
+      builder.request :guesty_rate_limiter, threshold: 5000, interval: 1.hour, key: -> { rate_limit_key(:hour) }
+
+      builder.request :url_encoded
+      builder.response :json, parser_options: { symbolize_names: true, mode: :rails, decoder: [Oj, :load] }
+      builder.options[:timeout] = timeout
+    end
+  end
+
+  # @rbs (::Symbol | ::String request_method, ::String path, ?::Hash[::Symbol, untyped] params, ?retries: ::Integer, ?timeout: ::Integer) -> untyped
+  def self.do_request(request_method, path, params = {}, retries: 3, timeout: TIMEOUT)
+    Fiber[:guesty__slot] = pick_slot(current_priority)
+
+    http = connection(timeout:)
+    response = params.present? ? http.send(request_method, path, params) : http.send(request_method, path)
+    result = successful_response?(response) ? Success(response) : Failure(ApiError.new(response))
+
+    if retries.positive? && result.failure? && result.failure.guesty_glitch?
+      sleep(1.0)
+      result = do_request(request_method, path, params, retries: (retries - 1), timeout:)
+    end
+
+    result
+  end
+
+  # @rbs (::Symbol priority) { (?) -> untyped } -> untyped
+  def self.with_priority(priority, &block)
+    previous_priority = current_priority
+    Fiber[:guesty__priority] = priority
+    block.call
+  ensure
+    Fiber[:guesty__priority] = previous_priority
+  end
+
+  # @rbs () -> ::Symbol
+  def self.current_priority
+    Fiber[:guesty__priority] || :default
+  end
+
+  # @rbs () -> slot
+  def self.current_slot
+    Fiber[:guesty__slot] || token_slots(current_priority).first
+  end
+
+  # @rbs (::Symbol window) -> ::Symbol
+  def self.rate_limit_key(window)
+    :"guesty_http_limit_#{window}_#{current_slot[:key]}"
+  end
+
+  # @rbs (?::Symbol priority) -> ::Array[slot]
+  def self.token_slots(priority = current_priority)
+    creds = Array.wrap(config.credentials[priority])
+
+    creds.each_with_index.map do |cred, index|
+      key = creds.one? ? priority.to_s : "#{priority}_#{index}"
+
+      {
+        key:,
+        client_id: cred[:client_id],
+        secret: cred[:secret]
+      }
+    end
+  end
+
+  # @rbs () -> ::String?
+  def self.webhook_key
+    config.credentials[:webhook_key]
+  end
+
+  # @rbs () -> bool
+  def self.sync_guest_and_reservation_changes?
+    !!config.sync_guest_and_reservation_changes
+  end
+
+  # @rbs (::Symbol priority) -> slot
+  def self.pick_slot(priority)
+    slots = token_slots(priority)
+    return slots.fetch(0) if slots.one?
+
+    config.slot_picker.call(slots, priority)
+  end
+
+  # @rbs (Faraday::Response response) -> bool
+  def self.successful_response?(response)
+    return false unless response.success?
+
+    !response.body.is_a?(Hash) || response.body[:status].blank? || response.body[:status].to_i < 300
+  end
+
+  # @rbs (::StandardError error) -> bool
+  def self.retryable_read?(error)
+    return true if error.is_a?(Faraday::TimeoutError) || error.is_a?(Faraday::ConnectionFailed)
+
+    error.is_a?(ApiError) && error.transient?
+  end
+
+  # @rbs (::StandardError error) -> bool
+  def self.unapplied?(error)
+    return true if error.is_a?(Guesty::ThrottledError)
+
+    error.is_a?(ApiError) && (error.retryable_non_delivery? || error.permanent_rejection?)
+  end
+
+  # @rbs (::StandardError error) -> bool
+  def self.delivery_unknown?(error)
+    (error.is_a?(ApiError) || error.is_a?(Faraday::Error)) && !unapplied?(error)
+  end
+
+  # @rbs () -> ::String
+  def self.auth_token
+    AccessTokens::Upsert.new.call!.value!.access_token
+  end
+end

data/lib/guesty/config.rb

@@ -0,0 +1,29 @@
+module Guesty
+  # Injected by the host app (see the Guesty.configure initializer): the API
+  # credentials per priority lane, the webhook signing key, a token store, a
+  # rate limiter and a slot picker. Keeping these out of the gem is what makes
+  # it host-agnostic.
+  #
+  # credentials maps each priority to its client credentials, plus webhook_key:
+  #
+  #   {
+  #     default: [{ client_id: '...', secret: '...' }, ...],
+  #     high:    [{ client_id: '...', secret: '...' }],
+  #     webhook_key: 'whsec_...'
+  #   }
+  class Config
+    attr_accessor :credentials, :token_store, :rate_limiter, :slot_picker, :base_url, :sync_guest_and_reservation_changes, :custom_fields,
+                  :default_currency
+
+    def initialize
+      @base_url = BASE_URL
+      @credentials = {}
+      @custom_fields = {}
+      @default_currency = nil
+      @token_store = MemoryTokenStore.new
+      @rate_limiter = MemoryRateLimiter.new
+      @slot_picker = ->(slots, _priority) { slots.first }
+      @sync_guest_and_reservation_changes = false
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+module Guesty
+  module Conversations
+    module Attachments
+      # Trades attachment storage keys for signed URLs (they expire after about
+      # an hour). Keys that are already links pass through unchanged.
+      class Index
+        include Guesty::Operation
+
+        BATCH_SIZE = 20
+        INVALID_RESPONSE = 'Guesty attachments response has an unexpected shape.'.freeze #: ::String
+
+        # @rbs (keys: ::Array[::String]) -> Dry::Monads::Result[::Hash[::String, ::String]]
+        def call(keys:)
+          argument! keys: :required, fatal: true if keys.blank?
+          argument! keys: :invalid unless keys.all?(&:present?)
+
+          links, storage_keys = keys.uniq.partition { |key| key.start_with?('http://', 'https://') }
+          urls = links.index_with(&:itself)
+
+          storage_keys.each_slice(BATCH_SIZE) do |batch|
+            response = Guesty.do_request :get, 'communication/conversations/get-attachments', { keys: batch }
+            return response unless response.success?
+
+            urls.merge!(normalize_response(batch, response.value!.body))
+          end
+
+          Success(urls)
+        end
+
+        private
+
+        # @rbs (::Array[::String] batch, untyped body) -> ::Hash[::String, ::String]
+        def normalize_response(batch, body)
+          links = body[:data] if body.is_a?(Hash)
+          error! INVALID_RESPONSE unless links.is_a?(Array) && links.size == batch.size && links.all? { |link| link.is_a?(String) && link.present? }
+
+          batch.zip(links).to_h
+        end
+      end
+    end
+  end
+end

data/lib/guesty/conversations/index.rb

@@ -0,0 +1,58 @@
+module Guesty
+  module Conversations
+    class Index
+      include Guesty::Operation
+
+      FIELDS = 'updatedAt meta.reservations._id meta.reservations.status'.freeze #: ::String
+      LIMIT = 100
+      MAX_PAGES = 20
+
+      # @rbs (since: ::Time) -> Dry::Monads::Result[::Array[::Hash[::Symbol, untyped]]]
+      def call(since:)
+        results = collect_updated(since)
+
+        Success(results)
+      end
+
+      private
+
+      def collect_updated(since)
+        results = [] #: ::Array[untyped]
+        cursor_after = nil
+
+        MAX_PAGES.times do
+          data = fetch_page(cursor_after)
+          page = data[:conversations].map { |conversation| normalize(conversation) }
+          results.concat(page.select { |conversation| conversation[:updated_at] >= since })
+
+          cursor_after = data.dig(:cursor, :after)
+          return without_timestamps(results) if page.empty? || cursor_after.blank? || page.last[:updated_at] < since
+        end
+
+        error! "Guesty conversations pagination exceeded #{MAX_PAGES} pages since #{since.iso8601}"
+      end
+
+      def without_timestamps(conversations)
+        conversations.map { |conversation| conversation.except(:updated_at) }
+      end
+
+      def fetch_page(cursor_after)
+        params = { fields: FIELDS, sort: '-updatedAt', limit: LIMIT }
+        params[:cursorAfter] = cursor_after if cursor_after.present?
+
+        response = Guesty.do_request(:get, 'communication/conversations', params)
+        error! response.failure.message unless response.success?
+
+        response.value!.body[:data]
+      end
+
+      def normalize(conversation)
+        {
+          id: conversation.fetch(:_id),
+          updated_at: Time.iso8601(conversation.fetch(:updatedAt)),
+          reservations: Guesty::Reservations.from_conversation(conversation)
+        }
+      end
+    end
+  end
+end