square.rb 45.0.1.20260122 → 45.2.0.pre.rc.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 056af038668564ff8d7f1860bcc35e44449e21f4784d91846121c139d4c139d5
-  data.tar.gz: 357823902c08c710857fe636e58f92cc223ef2269e1795b888077cea2d79114b
+  metadata.gz: 33286aa52968fd20a87e53747ec5f19b0769a955fae8be8bdb0d984d8d0e00cd
+  data.tar.gz: 1cf5fd062db619a9e1ebe949bffe6e724173526fd82d6af6bb1e07eef6d69e8d
 SHA512:
-  metadata.gz: 86385d14a820fcc51363fad79429b7f543b80329559128f3c609ced4c30cbcb06c4e5bce954b379f628ea34ffe69163e1231bedd7b41c12f3e46162f479694ec
-  data.tar.gz: e93cc124da8f72be75e60cf8e7401ad706edcde4efe464579081a684fafb86c28792dc6e46728eb2bf5531b4c02d4eac68e53ecb6204b597e15489013f4ffccd
+  metadata.gz: 8ebd02e23396a301d4cb91cdc2592d10112d419d84ba3581e69fba5d5222bbe58916c614e60d71692aeb4440079e7f8153582eba549d7f10e68d2c653cb49888
+  data.tar.gz: 7f5819b9a81bb6b683d64134b09649c698ccecc01db56b5d0e7ea58c328083da6ee669d8c5b034086d2a2a98ec4bc63ae73aac3054a3596d60b6f80fe22aa46c

data/.fern/metadata.json

@@ -1,9 +1,9 @@
 {
-  "cliVersion": "3.49.3",
+  "cliVersion": "3.98.5",
   "generatorName": "fernapi/fern-ruby-sdk",
   "generatorVersion": "1.0.0-rc84",
   "generatorConfig": {
     "enableWireTests": true
   },
-  "sdkVersion": "45.0.1.20260122"
+  "sdkVersion": "45.2.0-rc.0"
 }

data/.fern/replay.lock

@@ -0,0 +1,10 @@
+# DO NOT EDIT MANUALLY - Managed by Fern Replay
+version: "1.0"
+generations:
+  - commit_sha: f631923c98d9161665156652789a58902009b805
+    tree_hash: 872074a659baa229a5564e34250e9b648d1751fd
+    timestamp: 2026-05-19T21:18:26.039Z
+    cli_version: unknown
+    generator_versions: {}
+current_generation: f631923c98d9161665156652789a58902009b805
+patches: []

data/.fernignore

@@ -7,6 +7,10 @@ test/custom
 .github/workflows
 README.md
 lib/square/file_param.rb
+
+# Custom polling helper for the Reporting API (load_and_wait + Continue-wait
+# retry loop). Unit test lives under the already-ignored test/custom. FER-11257.
+lib/square/reporting_helper.rb
 Gemfile.custom
 custom.gemspec.rb
 
@@ -18,3 +22,6 @@ lib/square/transfer_orders/client.rb
 # Iterator does not handle nil item fields (when API returns nil instead of empty array for no items)
 # Manually added nil checks to avoid calling .shift/.empty? on nil
 lib/square/internal/iterators/item_iterator.rb
+.fern/replay.lock
+.fern/replay.yml
+.gitattributes

data/README.md

@@ -255,6 +255,60 @@ response = client.payments.create(..., {
 })
 ```
 
+## Reporting API
+
+The [Reporting API](https://developer.squareup.com/docs/reporting-api/overview) exposes two
+polling endpoints under `client.reporting`:
+
+- `get_metadata` — describes the data you can query (cubes, measures, dimensions, segments).
+  Call it first to discover the schema.
+- `load` — runs a reporting query and returns the aggregated result rows in `data`.
+
+`load` is asynchronous: while a query is still being computed it returns an HTTP 200 whose body
+is `{ "error": "Continue wait" }` rather than the results. Callers are expected to re-send the
+identical request, with backoff, until real results arrive.
+
+The SDK ships a `.fernignore`-protected helper that owns that retry loop. Require it explicitly
+to add `load_and_wait` to `client.reporting`:
+
+```ruby
+require "square"
+require "square/reporting_helper"
+
+client = Square::Client.new(token: ENV.fetch("SQUARE_TOKEN"))
+
+# 1. Discover the schema.
+metadata = client.reporting.get_metadata
+
+# 2. Run a query and transparently poll until it resolves.
+response = client.reporting.load_and_wait(
+  query: {
+    measures: ["orders.count"],
+    time_dimensions: [{ dimension: "orders.created_at", granularity: "day" }]
+  }
+)
+
+response.data.each { |row| puts row }
+```
+
+`load_and_wait` accepts optional polling parameters (defaults shown): `max_attempts: 20`,
+`initial_delay: 2.0`, `max_delay: 20.0`, `backoff_factor: 2.0` (seconds). It raises
+`Square::Reporting::ContinueWaitTimeoutError` if the query has not resolved within
+`max_attempts`. Pass a `should_cancel` predicate to abort the loop early (the Ruby idiom for an
+abort signal); it raises `Square::Reporting::PollingCancelledError` when the predicate returns a
+truthy value:
+
+```ruby
+deadline = Time.now + 60
+response = client.reporting.load_and_wait(
+  query: { measures: ["orders.count"] },
+  should_cancel: -> { Time.now > deadline }
+)
+```
+
+> **Note:** The Reporting API is production-only — sandbox requests return 404, and a sandbox
+> token against production returns 401. Use a production, reporting-provisioned token.
+
 ## Contributing
 
 While we value open-source contributions to this SDK, this library is generated programmatically. Additions made directly to this library would have to be moved over to our generation code, otherwise they would be overwritten upon the next generated release. Feel free to open a PR as a proof of concept, but know that we will not be able to merge it as-is. We suggest opening an issue first to discuss with us!

data/lib/square/client.rb

@@ -10,7 +10,7 @@ module Square
       @raw_client = Square::Internal::Http::RawClient.new(
         base_url: base_url || Square::Environment::PRODUCTION,
         headers: {
-          "User-Agent" => "square.rb/45.0.1.20260122",
+          "User-Agent" => "square.rb/45.2.0-rc.0",
           "X-Fern-Language" => "Ruby",
           Authorization: "Bearer #{token}"
         }
@@ -182,6 +182,11 @@ module Square
       @vendors ||= Square::Vendors::Client.new(client: @raw_client)
     end
 
+    # @return [Square::Reporting::Client]
+    def reporting
+      @reporting ||= Square::Reporting::Client.new(client: @raw_client)
+    end
+
     # @return [Square::CashDrawers::Client]
     def cash_drawers
       @cash_drawers ||= Square::CashDrawers::Client.new(client: @raw_client)

data/lib/square/inventory/client.rb

@@ -14,9 +14,10 @@ module Square
       # @return [Square::Types::GetInventoryAdjustmentResponse]
       def deprecated_get_adjustment(request_options: {}, **params)
         _request = Square::Internal::JSON::Request.new(
-          base_url: request_options[:base_url] || Square::Environment::PRODUCTION,
+          base_url: request_options[:base_url],
           method: "GET",
-          path: "v2/inventory/adjustment/#{params[:adjustment_id]}"
+          path: "v2/inventory/adjustment/#{params[:adjustment_id]}",
+          request_options: request_options
         )
         begin
           _response = @client.send(_request)
@@ -38,9 +39,10 @@ module Square
       # @return [Square::Types::GetInventoryAdjustmentResponse]
       def get_adjustment(request_options: {}, **params)
         _request = Square::Internal::JSON::Request.new(
-          base_url: request_options[:base_url] || Square::Environment::PRODUCTION,
+          base_url: request_options[:base_url],
           method: "GET",
-          path: "v2/inventory/adjustments/#{params[:adjustment_id]}"
+          path: "v2/inventory/adjustments/#{params[:adjustment_id]}",
+          request_options: request_options
         )
         begin
           _response = @client.send(_request)
@@ -62,10 +64,11 @@ module Square
       # @return [Square::Types::BatchChangeInventoryResponse]
       def deprecated_batch_change(request_options: {}, **params)
         _request = Square::Internal::JSON::Request.new(
-          base_url: request_options[:base_url] || Square::Environment::PRODUCTION,
+          base_url: request_options[:base_url],
           method: "POST",
           path: "v2/inventory/batch-change",
-          body: Square::Types::BatchChangeInventoryRequest.new(params).to_h
+          body: Square::Types::BatchChangeInventoryRequest.new(params).to_h,
+          request_options: request_options
         )
         begin
           _response = @client.send(_request)
@@ -87,10 +90,11 @@ module Square
       # @return [Square::Types::BatchGetInventoryChangesResponse]
       def deprecated_batch_get_changes(request_options: {}, **params)
         _request = Square::Internal::JSON::Request.new(
-          base_url: request_options[:base_url] || Square::Environment::PRODUCTION,
+          base_url: request_options[:base_url],
           method: "POST",
           path: "v2/inventory/batch-retrieve-changes",
-          body: Square::Types::BatchRetrieveInventoryChangesRequest.new(params).to_h
+          body: Square::Types::BatchRetrieveInventoryChangesRequest.new(params).to_h,
+          request_options: request_options
         )
         begin
           _response = @client.send(_request)
@@ -112,10 +116,11 @@ module Square
       # @return [Square::Types::BatchGetInventoryCountsResponse]
       def deprecated_batch_get_counts(request_options: {}, **params)
         _request = Square::Internal::JSON::Request.new(
-          base_url: request_options[:base_url] || Square::Environment::PRODUCTION,
+          base_url: request_options[:base_url],
           method: "POST",
           path: "v2/inventory/batch-retrieve-counts",
-          body: Square::Types::BatchGetInventoryCountsRequest.new(params).to_h
+          body: Square::Types::BatchGetInventoryCountsRequest.new(params).to_h,
+          request_options: request_options
         )
         begin
           _response = @client.send(_request)
@@ -140,10 +145,11 @@ module Square
       # @return [Square::Types::BatchChangeInventoryResponse]
       def batch_create_changes(request_options: {}, **params)
         _request = Square::Internal::JSON::Request.new(
-          base_url: request_options[:base_url] || Square::Environment::PRODUCTION,
+          base_url: request_options[:base_url],
           method: "POST",
           path: "v2/inventory/changes/batch-create",
-          body: Square::Types::BatchChangeInventoryRequest.new(params).to_h
+          body: Square::Types::BatchChangeInventoryRequest.new(params).to_h,
+          request_options: request_options
         )
         begin
           _response = @client.send(_request)
@@ -177,10 +183,11 @@ module Square
         ) do |next_cursor|
           params[:cursor] = next_cursor
           _request = Square::Internal::JSON::Request.new(
-            base_url: request_options[:base_url] || Square::Environment::PRODUCTION,
+            base_url: request_options[:base_url],
             method: "POST",
             path: "v2/inventory/changes/batch-retrieve",
-            body: Square::Types::BatchRetrieveInventoryChangesRequest.new(params).to_h
+            body: Square::Types::BatchRetrieveInventoryChangesRequest.new(params).to_h,
+            request_options: request_options
           )
           begin
             _response = @client.send(_request)
@@ -218,10 +225,11 @@ module Square
         ) do |next_cursor|
           params[:cursor] = next_cursor
           _request = Square::Internal::JSON::Request.new(
-            base_url: request_options[:base_url] || Square::Environment::PRODUCTION,
+            base_url: request_options[:base_url],
             method: "POST",
             path: "v2/inventory/counts/batch-retrieve",
-            body: Square::Types::BatchGetInventoryCountsRequest.new(params).to_h
+            body: Square::Types::BatchGetInventoryCountsRequest.new(params).to_h,
+            request_options: request_options
           )
           begin
             _response = @client.send(_request)
@@ -244,9 +252,10 @@ module Square
       # @return [Square::Types::GetInventoryPhysicalCountResponse]
       def deprecated_get_physical_count(request_options: {}, **params)
         _request = Square::Internal::JSON::Request.new(
-          base_url: request_options[:base_url] || Square::Environment::PRODUCTION,
+          base_url: request_options[:base_url],
           method: "GET",
-          path: "v2/inventory/physical-count/#{params[:physical_count_id]}"
+          path: "v2/inventory/physical-count/#{params[:physical_count_id]}",
+          request_options: request_options
         )
         begin
           _response = @client.send(_request)
@@ -268,9 +277,10 @@ module Square
       # @return [Square::Types::GetInventoryPhysicalCountResponse]
       def get_physical_count(request_options: {}, **params)
         _request = Square::Internal::JSON::Request.new(
-          base_url: request_options[:base_url] || Square::Environment::PRODUCTION,
+          base_url: request_options[:base_url],
           method: "GET",
-          path: "v2/inventory/physical-counts/#{params[:physical_count_id]}"
+          path: "v2/inventory/physical-counts/#{params[:physical_count_id]}",
+          request_options: request_options
         )
         begin
           _response = @client.send(_request)
@@ -292,9 +302,10 @@ module Square
       # @return [Square::Types::GetInventoryTransferResponse]
       def get_transfer(request_options: {}, **params)
         _request = Square::Internal::JSON::Request.new(
-          base_url: request_options[:base_url] || Square::Environment::PRODUCTION,
+          base_url: request_options[:base_url],
           method: "GET",
-          path: "v2/inventory/transfers/#{params[:transfer_id]}"
+          path: "v2/inventory/transfers/#{params[:transfer_id]}",
+          request_options: request_options
         )
         begin
           _response = @client.send(_request)
@@ -329,10 +340,11 @@ module Square
         ) do |next_cursor|
           _query[:cursor] = next_cursor
           _request = Square::Internal::JSON::Request.new(
-            base_url: request_options[:base_url] || Square::Environment::PRODUCTION,
+            base_url: request_options[:base_url],
             method: "GET",
             path: "v2/inventory/#{params[:catalog_object_id]}",
-            query: _query
+            query: _query,
+            request_options: request_options
           )
           begin
             _response = @client.send(_request)
@@ -377,10 +389,11 @@ module Square
         ) do |next_cursor|
           _query[:cursor] = next_cursor
           _request = Square::Internal::JSON::Request.new(
-            base_url: request_options[:base_url] || Square::Environment::PRODUCTION,
+            base_url: request_options[:base_url],
             method: "GET",
             path: "v2/inventory/#{params[:catalog_object_id]}/changes",
-            query: _query
+            query: _query,
+            request_options: request_options
           )
           begin
             _response = @client.send(_request)

data/lib/square/payments/types/create_payment_request.rb

@@ -9,6 +9,7 @@ module Square
         field :amount_money, -> { Square::Types::Money }, optional: true, nullable: false
         field :tip_money, -> { Square::Types::Money }, optional: true, nullable: false
         field :app_fee_money, -> { Square::Types::Money }, optional: true, nullable: false
+        field :app_fee_allocations, -> { Internal::Types::Array[Object] }, optional: true, nullable: false
         field :delay_duration, -> { String }, optional: true, nullable: false
         field :delay_action, -> { String }, optional: true, nullable: false
         field :autocomplete, -> { Internal::Types::Boolean }, optional: true, nullable: false

data/lib/square/refunds/types/refund_payment_request.rb

@@ -7,6 +7,7 @@ module Square
         field :idempotency_key, -> { String }, optional: false, nullable: false
         field :amount_money, -> { Square::Types::Money }, optional: false, nullable: false
         field :app_fee_money, -> { Square::Types::Money }, optional: true, nullable: false
+        field :app_fee_allocations, -> { Internal::Types::Array[Object] }, optional: true, nullable: false
         field :payment_id, -> { String }, optional: true, nullable: false
         field :destination_id, -> { String }, optional: true, nullable: false
         field :unlinked, -> { Internal::Types::Boolean }, optional: true, nullable: false

data/lib/square/reporting/client.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Square
+  module Reporting
+    class Client
+      # @param client [Square::Internal::Http::RawClient]
+      #
+      # @return [void]
+      def initialize(client:)
+        @client = client
+      end
+
+      # Describes the data available to query: the cubes, views, measures, dimensions, and segments you can reference in
+      # a reporting query. Call this first to discover the schema, then pass the members you need to `load`.
+      #
+      # @param request_options [Hash]
+      # @param params [Hash]
+      # @option request_options [String] :base_url
+      # @option request_options [Hash{String => Object}] :additional_headers
+      # @option request_options [Hash{String => Object}] :additional_query_parameters
+      # @option request_options [Hash{String => Object}] :additional_body_parameters
+      # @option request_options [Integer] :timeout_in_seconds
+      #
+      # @return [Square::Types::MetadataResponse]
+      def get_metadata(request_options: {}, **params)
+        Square::Internal::Types::Utils.normalize_keys(params)
+        request = Square::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
+          method: "GET",
+          path: "reporting/v1/meta",
+          request_options: request_options
+        )
+        begin
+          response = @client.send(request)
+        rescue Net::HTTPRequestTimeout
+          raise Square::Errors::TimeoutError
+        end
+        code = response.code.to_i
+        if code.between?(200, 299)
+          Square::Types::MetadataResponse.load(response.body)
+        else
+          error_class = Square::Errors::ResponseError.subclass_for_code(code)
+          raise error_class.new(response.body, code: code)
+        end
+      end
+
+      # Runs a reporting query against the discovered schema and returns the aggregated results. Long-running queries
+      # may return a "Continue wait" response while processing — retry the same request until results are ready.
+      #
+      # @param request_options [Hash]
+      # @param params [Square::Reporting::Types::LoadRequest]
+      # @option request_options [String] :base_url
+      # @option request_options [Hash{String => Object}] :additional_headers
+      # @option request_options [Hash{String => Object}] :additional_query_parameters
+      # @option request_options [Hash{String => Object}] :additional_body_parameters
+      # @option request_options [Integer] :timeout_in_seconds
+      #
+      # @return [Square::Types::LoadResponse]
+      def load(request_options: {}, **params)
+        params = Square::Internal::Types::Utils.normalize_keys(params)
+        request = Square::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
+          method: "POST",
+          path: "reporting/v1/load",
+          body: Square::Reporting::Types::LoadRequest.new(params).to_h,
+          request_options: request_options
+        )
+        begin
+          response = @client.send(request)
+        rescue Net::HTTPRequestTimeout
+          raise Square::Errors::TimeoutError
+        end
+        code = response.code.to_i
+        if code.between?(200, 299)
+          Square::Types::LoadResponse.load(response.body)
+        else
+          error_class = Square::Errors::ResponseError.subclass_for_code(code)
+          raise error_class.new(response.body, code: code)
+        end
+      end
+    end
+  end
+end

data/lib/square/reporting/types/load_request.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Square
+  module Reporting
+    module Types
+      class LoadRequest < Internal::Types::Model
+        field :query_type, -> { String }, optional: true, nullable: false, api_name: "queryType"
+        field :cache, -> { Square::Types::CacheMode }, optional: true, nullable: false
+        field :query, -> { Square::Types::Query }, optional: true, nullable: false
+      end
+    end
+  end
+end

data/lib/square/reporting_helper.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require_relative "../square"
+
+module Square
+  module Reporting
+    # Raised by {Client#load_and_wait} when a reporting query has not finished
+    # after the configured maximum number of attempts.
+    class ContinueWaitTimeoutError < StandardError; end
+
+    # Raised by {Client#load_and_wait} when the caller-supplied +should_cancel+
+    # predicate returns a truthy value, aborting the polling loop.
+    class PollingCancelledError < StandardError; end
+
+    # Custom, +.fernignore+-protected polling helper for the Reporting API.
+    #
+    # The +/reporting/v1/load+ endpoint is asynchronous: a query that is still
+    # being computed comes back as an HTTP 200 whose body is
+    # +{ "error": "Continue wait" }+ rather than the results. Callers are expected
+    # to re-send the identical request, with backoff, until real results arrive.
+    # This file reopens the generated {Square::Reporting::Client} to add
+    # +load_and_wait+, which owns that retry loop.
+    #
+    # @example
+    #   require "square"
+    #   require "square/reporting_helper"
+    #
+    #   client = Square::Client.new(token: ENV.fetch("SQUARE_TOKEN"))
+    #   response = client.reporting.load_and_wait(query: { ... })
+    class Client
+      # The value of the +error+ field the Reporting API returns on an HTTP 200
+      # while a +/reporting/v1/load+ query is still processing. It is NOT a
+      # failure — the identical request should be re-sent until real results
+      # arrive. See https://developer.squareup.com/docs/reporting-api/overview.
+      CONTINUE_WAIT_SENTINEL = "Continue wait"
+
+      # Default polling parameters for {#load_and_wait}.
+      DEFAULT_MAX_ATTEMPTS = 20
+      DEFAULT_INITIAL_DELAY = 2.0
+      DEFAULT_MAX_DELAY = 20.0
+      DEFAULT_BACKOFF_FACTOR = 2.0
+
+      # Granularity (seconds) at which a backoff wait checks +should_cancel+, so
+      # cancellation stays responsive even during a long delay.
+      POLL_TICK = 0.1
+
+      # Runs a reporting query and transparently polls until it resolves,
+      # returning the final {Square::Types::LoadResponse}.
+      #
+      # A query that is still being computed comes back as an HTTP 200 whose body
+      # is +{ "error": "Continue wait" }+. That body deserializes into a
+      # +LoadResponse+ whose +error+ key lands in the model's extra fields (it is
+      # not a declared field) while +results+ stays +nil+; that is the signal to
+      # retry. +load_and_wait+ re-sends the identical request with exponential
+      # backoff until real results arrive.
+      #
+      # @param request_options [Hash] forwarded verbatim to each underlying
+      #   {#load} call.
+      # @param max_attempts [Integer] maximum number of +load+ calls before
+      #   giving up. Defaults to {DEFAULT_MAX_ATTEMPTS}.
+      # @param initial_delay [Numeric] delay (seconds) before the first retry.
+      #   Defaults to {DEFAULT_INITIAL_DELAY}.
+      # @param max_delay [Numeric] upper bound (seconds) on the backoff delay.
+      #   Defaults to {DEFAULT_MAX_DELAY}.
+      # @param backoff_factor [Numeric] multiplier applied to the delay after each
+      #   attempt. Defaults to {DEFAULT_BACKOFF_FACTOR}.
+      # @param should_cancel [#call, nil] optional predicate checked before each
+      #   attempt and during each backoff wait; when it returns a truthy value the
+      #   loop aborts with {PollingCancelledError}. This is the Ruby idiom for
+      #   TypeScript's +AbortSignal+ / Go's +context.Context+.
+      # @param params [Hash] the reporting query, forwarded verbatim to {#load}
+      #   (same keyword arguments as a direct +load+ call).
+      #
+      # @return [Square::Types::LoadResponse] the resolved response.
+      #
+      # @raise [ContinueWaitTimeoutError] if the query has not resolved within
+      #   +max_attempts+ attempts.
+      # @raise [PollingCancelledError] if +should_cancel+ returns a truthy value.
+      def load_and_wait(
+        request_options: {},
+        max_attempts: DEFAULT_MAX_ATTEMPTS,
+        initial_delay: DEFAULT_INITIAL_DELAY,
+        max_delay: DEFAULT_MAX_DELAY,
+        backoff_factor: DEFAULT_BACKOFF_FACTOR,
+        should_cancel: nil,
+        **params
+      )
+        delay = initial_delay
+        attempt = 1
+
+        loop do
+          raise PollingCancelledError if should_cancel&.call
+
+          response = load(request_options: request_options, **params)
+          return response unless continue_wait?(response)
+
+          break if attempt >= max_attempts
+
+          cancellable_sleep(delay, should_cancel)
+
+          attempt += 1
+          delay = [delay * backoff_factor, max_delay].min
+        end
+
+        raise ContinueWaitTimeoutError,
+              "Reporting query did not complete after #{max_attempts} attempts " \
+              "(#{CONTINUE_WAIT_SENTINEL.inspect})"
+      end
+
+      private
+
+      # @param response [Square::Types::LoadResponse]
+      # @return [Boolean] whether +response+ is the "still processing" sentinel
+      #   rather than a real result.
+      def continue_wait?(response)
+        return false if response.nil?
+
+        response.to_h["error"] == CONTINUE_WAIT_SENTINEL
+      end
+
+      # Sleeps for +seconds+, waking every {POLL_TICK} to honor +should_cancel+.
+      #
+      # @param seconds [Numeric]
+      # @param should_cancel [#call, nil]
+      # @return [void]
+      # @raise [PollingCancelledError] if +should_cancel+ becomes truthy.
+      def cancellable_sleep(seconds, should_cancel)
+        return if seconds <= 0
+
+        deadline = monotonic_now + seconds
+        loop do
+          raise PollingCancelledError if should_cancel&.call
+
+          remaining = deadline - monotonic_now
+          break if remaining <= 0
+
+          sleep([remaining, POLL_TICK].min)
+        end
+      end
+
+      # @return [Float] a monotonic clock reading in seconds.
+      def monotonic_now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end