checkout-intents 0.0.2 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bc70fb7635edef3da40cc306e01a4e0754caee4ae66652784a95b1da116c073c
-  data.tar.gz: 560d24479d9c9d730a35f55ec5224f595983884a3d5accf419975a753d522dd8
+  metadata.gz: 8cf5e6cd633f4f7ee6338c4bea928549742449f2866fa6bbd2ae92b6421ef31c
+  data.tar.gz: 852728890666c85d7d1a0e8adeda2d59a5b2ce29c3cee5e3799044f740f9e543
 SHA512:
-  metadata.gz: 1c5fcfbf0a8d880d86396ef3f6c1e2040eb039b15e89be624cbd253203c87b0eb4c599e421cf2bf6b98bbae53f4ab92aa29a016327994b4dac2acaac9c6cdc02
-  data.tar.gz: b5a0f0238c5306f03bda47b7ecfad94e2137c69f53a4109c16f1615498ecab63c5a82a7118f562cceeb13429aade81855a6948b531664127b2c832db9254c296
+  metadata.gz: 0034c8b0230278a365e8d1193ba49d1cd32e9fc03a69794436e2ef407dcd73b6b7637e40587951695621099bc0e71a619725f896e91d0b1e335bef346cbae651
+  data.tar.gz: 2f2dfb10980745a1f0f3b127a4e31faac529af16e3091c753d7f53e9341e29ac558c3308ca68cfcd33a1033cab7299fc47f05e78e1ba7a85938fc472384596df

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.1.0 (2026-01-12)
+
+Full Changelog: [v0.0.2...v0.1.0](https://github.com/rye-com/checkout-intents-ruby/compare/v0.0.2...v0.1.0)
+
+### Features
+
+* **api:** add polling helpers ([5209a5f](https://github.com/rye-com/checkout-intents-ruby/commit/5209a5fcb449acf6e4ab52e1711b5c95a5acfa63))
+* **api:** auto infer environment value ([d666fbb](https://github.com/rye-com/checkout-intents-ruby/commit/d666fbb211955c2c02c9fb5c88de0dea6240adf1))
+
+
+### Chores
+
+* **internal:** add request_with_headers method ([89dc817](https://github.com/rye-com/checkout-intents-ruby/commit/89dc817a36404e5231e65ab7f05ebe1e5766c61f))
+* move `cgi` into dependencies for ruby 4 ([7674f56](https://github.com/rye-com/checkout-intents-ruby/commit/7674f56727d3e5d940c110eb173d91148224c21b))
+
+
+### Documentation
+
+* **api:** polling helpers ([465f0a0](https://github.com/rye-com/checkout-intents-ruby/commit/465f0a06848b014fd4e3526ff5c2a01b68f3b7ec))
+
 ## 0.0.2 (2026-01-07)
 
 Full Changelog: [v0.0.1...v0.0.2](https://github.com/rye-com/checkout-intents-ruby/compare/v0.0.1...v0.0.2)
@@ -13,4 +33,5 @@ Full Changelog: [v0.0.1...v0.0.2](https://github.com/rye-com/checkout-intents-ru
 ### Chores
 
 * configure new SDK language ([ee73dec](https://github.com/rye-com/checkout-intents-ruby/commit/ee73dec601f3c6286045a97a8c900ade97e9099f))
+* sync repo ([c2a3795](https://github.com/rye-com/checkout-intents-ruby/commit/c2a379536364e5dbdfc5aabfaf20383817a1e2b1))
 * update SDK settings ([a11c510](https://github.com/rye-com/checkout-intents-ruby/commit/a11c51015c6bcdbbc51353813a10b4421f9ebf44))

data/README.md

@@ -17,7 +17,7 @@ To use this gem, install via Bundler by adding the following to your application
 <!-- x-release-please-start-version -->
 
 ```ruby
-gem "checkout-intents", "~> 0.0.2"
+gem "checkout-intents", "~> 0.1.0"
 ```
 
 <!-- x-release-please-end -->
@@ -81,6 +81,63 @@ if page.next_page?
 end
 ```
 
+### Polling Helpers
+
+This SDK includes helper methods for the asynchronous checkout flow. The recommended pattern follows Rye's two-phase checkout:
+
+```ruby
+# Phase 1: Create and wait for offer
+intent = checkout_intents.checkout_intents.create_and_poll(
+  buyer: {
+    address1: "123 Main St",
+    city: "New York",
+    country: "US",
+    email: "john.doe@example.com",
+    firstName: "John",
+    lastName: "Doe",
+    phone: "5555555555",
+    postalCode: "10001",
+    province: "NY"
+  },
+  product_url: "https://example.com/product",
+  quantity: 1
+)
+
+# Handle failure during offer retrieval
+if intent.state == CheckoutIntents::CheckoutIntent::FailedCheckoutIntent::State::FAILED
+  puts "Failed: #{intent.failure_reason.message}"
+else
+  # Review pricing with user
+  puts "Total: #{intent.offer.cost.total}"
+
+  # Phase 2: Confirm and wait for completion
+  completed = checkout_intents.checkout_intents.confirm_and_poll(
+    intent.id,
+    payment_method: { type: :stripe_token, stripeToken: "tok_visa" }
+  )
+
+  puts "Status: #{completed.state}"
+end
+```
+
+Available polling methods:
+
+- `create_and_poll` - Create and poll until offer is ready (awaiting_confirmation or failed)
+- `confirm_and_poll` - Confirm and poll until completion (completed or failed)
+- `poll_until_completed` - Poll until completed or failed
+- `poll_until_awaiting_confirmation` - Poll until offer is ready or failed
+
+All polling methods support customizable timeouts:
+
+```ruby
+# Configure polling behavior
+intent = checkout_intents.checkout_intents.poll_until_completed(
+  intent_id,
+  poll_interval: 5.0,  # Poll every 5 seconds (default)
+  max_attempts: 120    # Try up to 120 times, ~10 minutes (default)
+)
+```
+
 ### Handling errors
 
 When the library is unable to connect to the API, or if the API returns a non-success status code (i.e., 4xx or 5xx response), a subclass of `CheckoutIntents::Errors::APIError` will be thrown:
@@ -128,6 +185,28 @@ Error codes are as follows:
 | Other HTTP error | `APIStatusError`           |
 | Timeout          | `APITimeoutError`          |
 | Network error    | `APIConnectionError`       |
+| Polling timeout  | `PollTimeoutError`         |
+
+### Polling Timeout Errors
+
+When using polling helper methods, if the operation exceeds the configured `max_attempts`, a `PollTimeoutError` is raised with helpful context:
+
+```ruby
+begin
+  intent = checkout_intents.checkout_intents.poll_until_completed(
+    "intent_id",
+    poll_interval: 5.0,
+    max_attempts: 60
+  )
+rescue CheckoutIntents::Errors::PollTimeoutError => e
+  puts "Polling timed out for intent: #{e.intent_id}"
+  puts "Attempted #{e.attempts} times over #{e.attempts * e.poll_interval}s"
+
+  # You can retrieve the current state manually
+  current_intent = checkout_intents.checkout_intents.retrieve(e.intent_id)
+  puts "Current state: #{current_intent.state}"
+end
+```
 
 ### Retries
 

data/lib/checkout_intents/client.rb

@@ -42,6 +42,19 @@ module CheckoutIntents
       {"authorization" => "Bearer #{@api_key}"}
     end
 
+    # Extracts the environment from a Rye API key.
+    # API keys follow the format: RYE/{environment}-{key}
+    #
+    # @api private
+    #
+    # @param api_key [String] The API key to parse
+    #
+    # @return [Symbol, nil] The extracted environment (:staging or :production), or nil if format doesn't match
+    private_class_method def self.extract_environment_from_api_key(api_key)
+      match = api_key.match(%r{\ARYE/(staging|production)-})
+      match ? match[1].to_sym : nil
+    end
+
     # Creates and returns a new client for interacting with the API.
     #
     # @param api_key [String, nil] Rye API key. Format: `RYE/{environment}-abcdef` Defaults to
@@ -73,17 +86,33 @@ module CheckoutIntents
       initial_retry_delay: self.class::DEFAULT_INITIAL_RETRY_DELAY,
       max_retry_delay: self.class::DEFAULT_MAX_RETRY_DELAY
     )
-      base_url ||= CheckoutIntents::Client::ENVIRONMENTS.fetch(environment&.to_sym || :production) do
-        message = "environment must be one of #{CheckoutIntents::Client::ENVIRONMENTS.keys}, got #{environment}"
-        raise ArgumentError.new(message)
-      end
-
       if api_key.nil?
         raise ArgumentError.new("api_key is required, and can be set via environ: \"CHECKOUT_INTENTS_API_KEY\"")
       end
 
       @api_key = api_key.to_s
 
+      # Auto-infer environment from API key
+      inferred_environment = self.class.send(:extract_environment_from_api_key, @api_key)
+
+      # Validate environment option matches API key (if both provided)
+      if environment && inferred_environment && environment.to_sym != inferred_environment
+        raise ArgumentError.new(
+          "Environment mismatch: API key is for '#{inferred_environment}' environment " \
+          "but 'environment' option is set to '#{environment}'. Please use an API key that " \
+          "matches your desired environment or omit the 'environment' option to auto-detect " \
+          "from the API key (only auto-detectable with the RYE/{environment}-abcdef api key format)."
+        )
+      end
+
+      # Resolve environment: explicit > inferred > default (staging)
+      resolved_environment = environment&.to_sym || inferred_environment || :staging
+
+      base_url ||= CheckoutIntents::Client::ENVIRONMENTS.fetch(resolved_environment) do
+        message = "environment must be one of #{CheckoutIntents::Client::ENVIRONMENTS.keys}, got #{resolved_environment}"
+        raise ArgumentError.new(message)
+      end
+
       super(
         base_url: base_url,
         timeout: timeout,

data/lib/checkout_intents/errors.rb

@@ -224,5 +224,38 @@ module CheckoutIntents
     class InternalServerError < CheckoutIntents::Errors::APIStatusError
       HTTP_STATUS = (500..)
     end
+
+    class PollTimeoutError < CheckoutIntents::Errors::Error
+      # @return [String]
+      attr_reader :intent_id
+
+      # @return [Integer]
+      attr_reader :attempts
+
+      # @return [Float]
+      attr_reader :poll_interval
+
+      # @return [Integer]
+      attr_reader :max_attempts
+
+      # @api private
+      #
+      # @param intent_id [String]
+      # @param attempts [Integer]
+      # @param poll_interval [Float]
+      # @param max_attempts [Integer]
+      # @param message [String, nil]
+      def initialize(intent_id:, attempts:, poll_interval:, max_attempts:, message: nil)
+        @intent_id = intent_id
+        @attempts = attempts
+        @poll_interval = poll_interval
+        @max_attempts = max_attempts
+
+        message ||= "Polling timeout for checkout intent '#{intent_id}': " \
+                    "condition not met after #{attempts} attempts (#{(max_attempts * poll_interval).round(1)}s). " \
+                    "Consider increasing max_attempts or poll_interval."
+        super(message)
+      end
+    end
   end
 end

data/lib/checkout_intents/internal/transport/base_client.rb

@@ -518,6 +518,39 @@ module CheckoutIntents
           end
         end
 
+        # @api private
+        #
+        # Like `request`, but returns both the parsed model and response headers.
+        # Used internally for polling helpers that need to inspect headers.
+        #
+        # @param req [Hash{Symbol=>Object}]
+        #
+        # @raise [CheckoutIntents::Errors::APIError]
+        # @return [Hash{Symbol=>Object}] Hash with :data and :headers keys
+        def request_with_headers(req)
+          self.class.validate!(req)
+          model = req.fetch(:model) { CheckoutIntents::Internal::Type::Unknown }
+          opts = req[:options].to_h
+          unwrap = req[:unwrap]
+          CheckoutIntents::RequestOptions.validate!(opts)
+          request = build_request(req.except(:options), opts)
+
+          send_retry_header = request.fetch(:headers)["x-stainless-retry-count"] == "0"
+          _status, response, stream = send_request(
+            request,
+            redirect_count: 0,
+            retry_count: 0,
+            send_retry_header: send_retry_header
+          )
+
+          headers = CheckoutIntents::Internal::Util.normalized_headers(response.each_header.to_h)
+          decoded = CheckoutIntents::Internal::Util.decode_content(headers, stream: stream)
+          unwrapped = CheckoutIntents::Internal::Util.dig(decoded, unwrap)
+          data = CheckoutIntents::Internal::Type::Converter.coerce(model, unwrapped)
+
+          {data: data, headers: headers}
+        end
+
         # @api private
         #
         # @return [String]

data/lib/checkout_intents/resources/checkout_intents.rb

@@ -3,6 +3,11 @@
 module CheckoutIntents
   module Resources
     class CheckoutIntents
+      # Default polling interval in seconds
+      DEFAULT_POLL_INTERVAL = 5.0
+
+      # Default maximum polling attempts
+      DEFAULT_MAX_ATTEMPTS = 120
       # Create a checkout intent with the given request body.
       #
       # @overload create(buyer:, product_url:, quantity:, constraints: nil, promo_codes: nil, variant_selections: nil, request_options: {})
@@ -162,12 +167,229 @@ module CheckoutIntents
         )
       end
 
+      # Poll a checkout intent until it reaches a completed state (completed or failed).
+      #
+      # @param id [String] The checkout intent ID to poll
+      # @param poll_interval [Float] Seconds between polling attempts (default: 5.0)
+      # @param max_attempts [Integer] Maximum polling attempts before timeout (default: 120)
+      # @param request_options [::CheckoutIntents::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [::CheckoutIntents::Models::CheckoutIntent::CompletedCheckoutIntent, ::CheckoutIntents::Models::CheckoutIntent::FailedCheckoutIntent]
+      #
+      # @raise [::CheckoutIntents::Errors::PollTimeoutError] If max attempts reached without reaching terminal state
+      #
+      # @example
+      #   intent = client.checkout_intents.poll_until_completed("ci_123")
+      #   if intent.state == :completed
+      #     puts "Order placed successfully!"
+      #   else
+      #     puts "Order failed: #{intent.failure_reason.message}"
+      #   end
+      def poll_until_completed(
+        id,
+        poll_interval: DEFAULT_POLL_INTERVAL,
+        max_attempts: DEFAULT_MAX_ATTEMPTS,
+        request_options: {}
+      )
+        poll_until(
+          id,
+          ->(intent) { [:completed, :failed].include?(intent.state) },
+          poll_interval: poll_interval,
+          max_attempts: max_attempts,
+          request_options: request_options
+        )
+      end
+
+      # Poll a checkout intent until it's ready for confirmation (awaiting_confirmation or failed).
+      #
+      # This is typically used after creating a checkout intent to wait for the offer
+      # to be retrieved from the merchant. The intent can reach awaiting_confirmation
+      # (success - ready to confirm) or failed (offer retrieval failed).
+      #
+      # @param id [String] The checkout intent ID to poll
+      # @param poll_interval [Float] Seconds between polling attempts (default: 5.0)
+      # @param max_attempts [Integer] Maximum polling attempts before timeout (default: 120)
+      # @param request_options [::CheckoutIntents::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [::CheckoutIntents::Models::CheckoutIntent::AwaitingConfirmationCheckoutIntent, ::CheckoutIntents::Models::CheckoutIntent::FailedCheckoutIntent]
+      #
+      # @raise [::CheckoutIntents::Errors::PollTimeoutError] If max attempts reached without reaching target state
+      #
+      # @example
+      #   intent = client.checkout_intents.poll_until_awaiting_confirmation("ci_123")
+      #   if intent.state == :awaiting_confirmation
+      #     puts "Total: #{intent.offer.cost.total}"
+      #   else
+      #     puts "Failed: #{intent.failure_reason.message}"
+      #   end
+      def poll_until_awaiting_confirmation(
+        id,
+        poll_interval: DEFAULT_POLL_INTERVAL,
+        max_attempts: DEFAULT_MAX_ATTEMPTS,
+        request_options: {}
+      )
+        poll_until(
+          id,
+          ->(intent) { [:awaiting_confirmation, :failed].include?(intent.state) },
+          poll_interval: poll_interval,
+          max_attempts: max_attempts,
+          request_options: request_options
+        )
+      end
+
+      # Create a checkout intent and poll until it's ready for confirmation.
+      #
+      # This follows the Rye documented flow: create -> poll until awaiting_confirmation.
+      # After this method completes, you should review the offer (pricing, shipping, taxes)
+      # with the user before calling confirm().
+      #
+      # @overload create_and_poll(buyer:, product_url:, quantity:, constraints: nil, promo_codes: nil, variant_selections: nil, poll_interval: 5.0, max_attempts: 120, request_options: {})
+      #
+      # @param buyer [::CheckoutIntents::Models::Buyer]
+      # @param product_url [String]
+      # @param quantity [Float]
+      # @param constraints [::CheckoutIntents::Models::CheckoutIntentCreateParams::Constraints]
+      # @param promo_codes [Array<String>]
+      # @param variant_selections [Array<::CheckoutIntents::Models::VariantSelection>]
+      # @param poll_interval [Float] Seconds between polling attempts (default: 5.0)
+      # @param max_attempts [Integer] Maximum polling attempts before timeout (default: 120)
+      # @param request_options [::CheckoutIntents::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [::CheckoutIntents::Models::CheckoutIntent::AwaitingConfirmationCheckoutIntent, ::CheckoutIntents::Models::CheckoutIntent::FailedCheckoutIntent]
+      #
+      # @raise [::CheckoutIntents::Errors::PollTimeoutError] If max attempts reached without reaching target state
+      #
+      # @example
+      #   intent = client.checkout_intents.create_and_poll(
+      #     buyer: { address1: "123 Main St", city: "New York", ... },
+      #     product_url: "https://example.com/product",
+      #     quantity: 1
+      #   )
+      #   puts "Total: #{intent.offer.cost.total}"
+      def create_and_poll(
+        params,
+        poll_interval: DEFAULT_POLL_INTERVAL,
+        max_attempts: DEFAULT_MAX_ATTEMPTS
+      )
+        intent = create(params)
+        poll_until_awaiting_confirmation(
+          intent.id,
+          poll_interval: poll_interval,
+          max_attempts: max_attempts,
+          request_options: params[:request_options] || {}
+        )
+      end
+
+      # Confirm a checkout intent and poll until it reaches a completed state (completed or failed).
+      #
+      # @overload confirm_and_poll(id, payment_method:, poll_interval: 5.0, max_attempts: 120, request_options: {})
+      #
+      # @param id [String] The id of the checkout intent to confirm
+      # @param payment_method [::CheckoutIntents::Models::PaymentMethod::StripeTokenPaymentMethod, ::CheckoutIntents::Models::PaymentMethod::BasisTheoryPaymentMethod, ::CheckoutIntents::Models::PaymentMethod::NekudaPaymentMethod]
+      # @param poll_interval [Float] Seconds between polling attempts (default: 5.0)
+      # @param max_attempts [Integer] Maximum polling attempts before timeout (default: 120)
+      # @param request_options [::CheckoutIntents::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [::CheckoutIntents::Models::CheckoutIntent::CompletedCheckoutIntent, ::CheckoutIntents::Models::CheckoutIntent::FailedCheckoutIntent]
+      #
+      # @raise [::CheckoutIntents::Errors::PollTimeoutError] If max attempts reached without reaching terminal state
+      #
+      # @example
+      #   intent = client.checkout_intents.confirm_and_poll(
+      #     "ci_123",
+      #     payment_method: { type: "stripe_token", stripe_token: "tok_visa" }
+      #   )
+      #   if intent.state == :completed
+      #     puts "Order placed successfully!"
+      #   else
+      #     puts "Order failed: #{intent.failure_reason.message}"
+      #   end
+      def confirm_and_poll(
+        id,
+        params,
+        poll_interval: DEFAULT_POLL_INTERVAL,
+        max_attempts: DEFAULT_MAX_ATTEMPTS
+      )
+        intent = confirm(id, params)
+        poll_until_completed(
+          intent.id,
+          poll_interval: poll_interval,
+          max_attempts: max_attempts,
+          request_options: params[:request_options] || {}
+        )
+      end
+
       # @api private
       #
       # @param client [::CheckoutIntents::Client]
       def initialize(client:)
         @client = client
       end
+
+      private
+
+      # Core polling implementation.
+      #
+      # @param id [String] The checkout intent ID
+      # @param condition [Proc] Returns true when polling should stop
+      # @param poll_interval [Float] Seconds between polls
+      # @param max_attempts [Integer] Maximum attempts
+      # @param request_options [Hash] Additional request options
+      #
+      # @return [::CheckoutIntents::Models::CheckoutIntent]
+      def poll_until(id, condition, poll_interval:, max_attempts:, request_options:)
+        if max_attempts < 1
+          warn(
+            "[Checkout Intents SDK] Invalid max_attempts value: #{max_attempts}. " \
+            "max_attempts must be >= 1. Defaulting to 1."
+          )
+          max_attempts = 1
+        end
+
+        attempts = 0
+        poll_headers = {
+          "x-stainless-poll-helper" => "true",
+          "x-stainless-custom-poll-interval" => (poll_interval * 1000).to_i.to_s
+        }
+
+        merged_options = (request_options || {}).merge(
+          extra_headers: ((request_options || {})[:extra_headers] || {}).merge(poll_headers)
+        )
+
+        while attempts < max_attempts
+          result = @client.request_with_headers(
+            method: :get,
+            path: ["api/v1/checkout-intents/%1$s", id],
+            model: ::CheckoutIntents::CheckoutIntent,
+            options: merged_options
+          )
+
+          intent = result[:data]
+          headers = result[:headers]
+
+          return intent if condition.call(intent)
+
+          attempts += 1
+
+          if attempts >= max_attempts
+            raise ::CheckoutIntents::Errors::PollTimeoutError.new(
+              intent_id: id,
+              attempts: attempts,
+              poll_interval: poll_interval,
+              max_attempts: max_attempts
+            )
+          end
+
+          # Check for server-suggested polling interval
+          sleep_interval = poll_interval
+          if (header_interval = headers["retry-after-ms"])
+            header_interval_ms = Integer(header_interval, exception: false)
+            sleep_interval = header_interval_ms / 1000.0 if header_interval_ms
+          end
+
+          sleep(sleep_interval)
+        end
+      end
     end
   end
 end

data/lib/checkout_intents/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module CheckoutIntents
-  VERSION = "0.0.2"
+  VERSION = "0.1.0"
 end

data/rbi/checkout_intents/errors.rbi

@@ -201,5 +201,38 @@ module CheckoutIntents
     class InternalServerError < CheckoutIntents::Errors::APIStatusError
       HTTP_STATUS = T.let((500..), T::Range[Integer])
     end
+
+    class PollTimeoutError < CheckoutIntents::Errors::Error
+      sig { returns(String) }
+      attr_reader :intent_id
+
+      sig { returns(Integer) }
+      attr_reader :attempts
+
+      sig { returns(Float) }
+      attr_reader :poll_interval
+
+      sig { returns(Integer) }
+      attr_reader :max_attempts
+
+      # @api private
+      sig do
+        params(
+          intent_id: String,
+          attempts: Integer,
+          poll_interval: Float,
+          max_attempts: Integer,
+          message: T.nilable(String)
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        intent_id:,
+        attempts:,
+        poll_interval:,
+        max_attempts:,
+        message: nil
+      )
+      end
+    end
   end
 end

data/rbi/checkout_intents/internal/transport/base_client.rbi

@@ -299,6 +299,18 @@ module CheckoutIntents
         )
         end
 
+        # @api private
+        #
+        # Like `request`, but returns both the parsed model and response headers.
+        # Used internally for polling helpers that need to inspect headers.
+        sig do
+          params(
+            req: CheckoutIntents::Internal::Transport::BaseClient::RequestComponents
+          ).returns({ data: T.anything, headers: T::Hash[String, String] })
+        end
+        def request_with_headers(req)
+        end
+
         # @api private
         sig { returns(String) }
         def inspect

data/rbi/checkout_intents/resources/checkout_intents.rbi

@@ -156,6 +156,98 @@ module CheckoutIntents
       )
       end
 
+      # Default polling interval in seconds
+      DEFAULT_POLL_INTERVAL = T.let(5.0, Float)
+
+      # Default maximum polling attempts
+      DEFAULT_MAX_ATTEMPTS = T.let(120, Integer)
+
+      # Poll a checkout intent until it reaches a completed state (completed or failed).
+      sig do
+        params(
+          id: String,
+          poll_interval: Float,
+          max_attempts: Integer,
+          request_options: ::CheckoutIntents::RequestOptions::OrHash
+        ).returns(
+          T.any(
+            ::CheckoutIntents::CheckoutIntent::CompletedCheckoutIntent,
+            ::CheckoutIntents::CheckoutIntent::FailedCheckoutIntent
+          )
+        )
+      end
+      def poll_until_completed(
+        id,
+        poll_interval: DEFAULT_POLL_INTERVAL,
+        max_attempts: DEFAULT_MAX_ATTEMPTS,
+        request_options: {}
+      )
+      end
+
+      # Poll a checkout intent until it's ready for confirmation (awaiting_confirmation or failed).
+      sig do
+        params(
+          id: String,
+          poll_interval: Float,
+          max_attempts: Integer,
+          request_options: ::CheckoutIntents::RequestOptions::OrHash
+        ).returns(
+          T.any(
+            ::CheckoutIntents::CheckoutIntent::AwaitingConfirmationCheckoutIntent,
+            ::CheckoutIntents::CheckoutIntent::FailedCheckoutIntent
+          )
+        )
+      end
+      def poll_until_awaiting_confirmation(
+        id,
+        poll_interval: DEFAULT_POLL_INTERVAL,
+        max_attempts: DEFAULT_MAX_ATTEMPTS,
+        request_options: {}
+      )
+      end
+
+      # Create a checkout intent and poll until it's ready for confirmation.
+      sig do
+        params(
+          params: T::Hash[Symbol, T.anything],
+          poll_interval: Float,
+          max_attempts: Integer
+        ).returns(
+          T.any(
+            ::CheckoutIntents::CheckoutIntent::AwaitingConfirmationCheckoutIntent,
+            ::CheckoutIntents::CheckoutIntent::FailedCheckoutIntent
+          )
+        )
+      end
+      def create_and_poll(
+        params,
+        poll_interval: DEFAULT_POLL_INTERVAL,
+        max_attempts: DEFAULT_MAX_ATTEMPTS
+      )
+      end
+
+      # Confirm a checkout intent and poll until it reaches a completed state.
+      sig do
+        params(
+          id: String,
+          params: T::Hash[Symbol, T.anything],
+          poll_interval: Float,
+          max_attempts: Integer
+        ).returns(
+          T.any(
+            ::CheckoutIntents::CheckoutIntent::CompletedCheckoutIntent,
+            ::CheckoutIntents::CheckoutIntent::FailedCheckoutIntent
+          )
+        )
+      end
+      def confirm_and_poll(
+        id,
+        params,
+        poll_interval: DEFAULT_POLL_INTERVAL,
+        max_attempts: DEFAULT_MAX_ATTEMPTS
+      )
+      end
+
       # @api private
       sig { params(client: ::CheckoutIntents::Client).returns(T.attached_class) }
       def self.new(client:)

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: checkout-intents
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.1.0
 platform: ruby
 authors:
 - Checkout Intents
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-01-07 00:00:00.000000000 Z
+date: 2026-01-12 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: cgi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: connection_pool
   requirement: !ruby/object:Gem::Requirement