checkout-intents 0.0.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bc70fb7635edef3da40cc306e01a4e0754caee4ae66652784a95b1da116c073c
-  data.tar.gz: 560d24479d9c9d730a35f55ec5224f595983884a3d5accf419975a753d522dd8
+  metadata.gz: 6ccc0d2eeeb7a1702d337ab33d2fbb8dea3223c39aefc94a9a5460930f808293
+  data.tar.gz: 7f41dc18f595b8bfa410eda98c4f55ca377db74b28a7336469ca4660513d907c
 SHA512:
-  metadata.gz: 1c5fcfbf0a8d880d86396ef3f6c1e2040eb039b15e89be624cbd253203c87b0eb4c599e421cf2bf6b98bbae53f4ab92aa29a016327994b4dac2acaac9c6cdc02
-  data.tar.gz: b5a0f0238c5306f03bda47b7ecfad94e2137c69f53a4109c16f1615498ecab63c5a82a7118f562cceeb13429aade81855a6948b531664127b2c832db9254c296
+  metadata.gz: e2311ef4c1c2be6041830d7512449d65b8d37804ff6d6b160f53c5b82afc66eba8cce0b188cd383e6416dae43b4458785ed725c746686405e21a2f2cba2f4b77
+  data.tar.gz: 8ef1985d27314dad4a6e30c26e6b3e5e379aed5318114ebe20e2e883661c2ef5d555374853b3346aba8139904da5d6129a9db5f30220fcc0b9aba9aeeea021e0

data/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 0.2.0 (2026-01-12)
+
+Full Changelog: [v0.1.0...v0.2.0](https://github.com/rye-com/checkout-intents-ruby/compare/v0.1.0...v0.2.0)
+
+### Features
+
+* **api:** convert polling helpers to flat keyword args ([0b0893e](https://github.com/rye-com/checkout-intents-ruby/commit/0b0893e255447c6ef35a81196c7481242f7eab8b))
+
+
+### Chores
+
+* **api:** coerce `quantity` to an `Integer` ([e32b3fc](https://github.com/rye-com/checkout-intents-ruby/commit/e32b3fc5848bfd455cba755cceddfd94f5d40da0))
+
+## 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 +46,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.2.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/models/base_checkout_intent.rb

@@ -25,8 +25,8 @@ module CheckoutIntents
 
       # @!attribute quantity
       #
-      #   @return [Float]
-      required :quantity, Float
+      #   @return [Integer]
+      required :quantity, Integer
 
       # @!attribute constraints
       #
@@ -50,7 +50,7 @@ module CheckoutIntents
       #   @param buyer [CheckoutIntents::Models::Buyer]
       #   @param created_at [Time]
       #   @param product_url [String]
-      #   @param quantity [Float]
+      #   @param quantity [Integer]
       #   @param constraints [CheckoutIntents::Models::BaseCheckoutIntent::Constraints]
       #   @param promo_codes [Array<String>]
       #   @param variant_selections [Array<CheckoutIntents::Models::VariantSelection>]

data/lib/checkout_intents/models/betas/checkout_session_create_params.rb

@@ -15,8 +15,8 @@ module CheckoutIntents
 
         # @!attribute quantity
         #
-        #   @return [Float]
-        required :quantity, Float
+        #   @return [Integer]
+        required :quantity, Integer
 
         # @!attribute buyer
         #   Optional buyer information, used to pre-fill the checkout form with the buyer's
@@ -48,7 +48,7 @@ module CheckoutIntents
         #
         #   @param product_url [String]
         #
-        #   @param quantity [Float]
+        #   @param quantity [Integer]
         #
         #   @param buyer [CheckoutIntents::Models::Betas::CheckoutSessionCreateParams::Buyer] Optional buyer information, used to pre-fill the checkout form with the buyer's
         #

data/lib/checkout_intents/models/checkout_intent_create_params.rb

@@ -19,8 +19,8 @@ module CheckoutIntents
 
       # @!attribute quantity
       #
-      #   @return [Float]
-      required :quantity, Float
+      #   @return [Integer]
+      required :quantity, Integer
 
       # @!attribute constraints
       #
@@ -42,7 +42,7 @@ module CheckoutIntents
       # @!method initialize(buyer:, product_url:, quantity:, constraints: nil, promo_codes: nil, variant_selections: nil, request_options: {})
       #   @param buyer [CheckoutIntents::Models::Buyer]
       #   @param product_url [String]
-      #   @param quantity [Float]
+      #   @param quantity [Integer]
       #   @param constraints [CheckoutIntents::Models::CheckoutIntentCreateParams::Constraints]
       #   @param promo_codes [Array<String>]
       #   @param variant_selections [Array<CheckoutIntents::Models::VariantSelection>]

data/lib/checkout_intents/models/checkout_intent_purchase_params.rb

@@ -24,8 +24,8 @@ module CheckoutIntents
 
       # @!attribute quantity
       #
-      #   @return [Float]
-      required :quantity, Float
+      #   @return [Integer]
+      required :quantity, Integer
 
       # @!attribute constraints
       #
@@ -48,7 +48,7 @@ module CheckoutIntents
       #   @param buyer [CheckoutIntents::Models::Buyer]
       #   @param payment_method [CheckoutIntents::Models::PaymentMethod::StripeTokenPaymentMethod, CheckoutIntents::Models::PaymentMethod::BasisTheoryPaymentMethod, CheckoutIntents::Models::PaymentMethod::NekudaPaymentMethod]
       #   @param product_url [String]
-      #   @param quantity [Float]
+      #   @param quantity [Integer]
       #   @param constraints [CheckoutIntents::Models::CheckoutIntentPurchaseParams::Constraints]
       #   @param promo_codes [Array<String>]
       #   @param variant_selections [Array<CheckoutIntents::Models::VariantSelection>]

data/lib/checkout_intents/resources/betas/checkout_sessions.rb

@@ -16,7 +16,7 @@ module CheckoutIntents
         #
         # @param product_url [String]
         #
-        # @param quantity [Float]
+        # @param quantity [Integer]
         #
         # @param buyer [::CheckoutIntents::Models::Betas::CheckoutSessionCreateParams::Buyer] Optional buyer information, used to pre-fill the checkout form with the buyer's
         #

data/lib/checkout_intents/resources/checkout_intents.rb

@@ -3,13 +3,18 @@
 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: {})
       #
       # @param buyer [::CheckoutIntents::Models::Buyer]
       # @param product_url [String]
-      # @param quantity [Float]
+      # @param quantity [Integer]
       # @param constraints [::CheckoutIntents::Models::CheckoutIntentCreateParams::Constraints]
       # @param promo_codes [Array<String>]
       # @param variant_selections [Array<::CheckoutIntents::Models::VariantSelection>]
@@ -142,7 +147,7 @@ module CheckoutIntents
       # @param buyer [::CheckoutIntents::Models::Buyer]
       # @param payment_method [::CheckoutIntents::Models::PaymentMethod::StripeTokenPaymentMethod, ::CheckoutIntents::Models::PaymentMethod::BasisTheoryPaymentMethod, ::CheckoutIntents::Models::PaymentMethod::NekudaPaymentMethod]
       # @param product_url [String]
-      # @param quantity [Float]
+      # @param quantity [Integer]
       # @param constraints [::CheckoutIntents::Models::CheckoutIntentPurchaseParams::Constraints]
       # @param promo_codes [Array<String>]
       # @param variant_selections [Array<::CheckoutIntents::Models::VariantSelection>]
@@ -162,12 +167,244 @@ 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 [Integer]
+      # @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(
+        buyer:,
+        product_url:,
+        quantity:,
+        constraints: nil,
+        promo_codes: nil,
+        variant_selections: nil,
+        poll_interval: DEFAULT_POLL_INTERVAL,
+        max_attempts: DEFAULT_MAX_ATTEMPTS,
+        request_options: {}
+      )
+        intent = create(
+          buyer: buyer,
+          product_url: product_url,
+          quantity: quantity,
+          constraints: constraints,
+          promo_codes: promo_codes,
+          variant_selections: variant_selections,
+          request_options: request_options
+        )
+        poll_until_awaiting_confirmation(
+          intent.id,
+          poll_interval: poll_interval,
+          max_attempts: max_attempts,
+          request_options: 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,
+        payment_method:,
+        poll_interval: DEFAULT_POLL_INTERVAL,
+        max_attempts: DEFAULT_MAX_ATTEMPTS,
+        request_options: {}
+      )
+        intent = confirm(id, payment_method: payment_method, request_options: request_options)
+        poll_until_completed(
+          intent.id,
+          poll_interval: poll_interval,
+          max_attempts: max_attempts,
+          request_options: 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.2.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/models/base_checkout_intent.rbi

@@ -64,7 +64,7 @@ module CheckoutIntents
           buyer: CheckoutIntents::Buyer::OrHash,
           created_at: Time,
           product_url: String,
-          quantity: Float,
+          quantity: Integer,
           constraints: CheckoutIntents::BaseCheckoutIntent::Constraints::OrHash,
           promo_codes: T::Array[String],
           variant_selections:
@@ -90,7 +90,7 @@ module CheckoutIntents
             buyer: CheckoutIntents::Buyer,
             created_at: Time,
             product_url: String,
-            quantity: Float,
+            quantity: Integer,
             constraints: CheckoutIntents::BaseCheckoutIntent::Constraints,
             promo_codes: T::Array[String],
             variant_selections: T::Array[CheckoutIntents::VariantSelection]

data/rbi/checkout_intents/models/betas/checkout_session_create_params.rbi

@@ -77,7 +77,7 @@ module CheckoutIntents
         sig do
           params(
             product_url: String,
-            quantity: Float,
+            quantity: Integer,
             buyer:
               CheckoutIntents::Betas::CheckoutSessionCreateParams::Buyer::OrHash,
             constraints:
@@ -105,7 +105,7 @@ module CheckoutIntents
           override.returns(
             {
               product_url: String,
-              quantity: Float,
+              quantity: Integer,
               buyer: CheckoutIntents::Betas::CheckoutSessionCreateParams::Buyer,
               constraints:
                 CheckoutIntents::Betas::CheckoutSessionCreateParams::Constraints,

data/rbi/checkout_intents/models/checkout_intent_create_params.rbi

@@ -62,7 +62,7 @@ module CheckoutIntents
         params(
           buyer: CheckoutIntents::Buyer::OrHash,
           product_url: String,
-          quantity: Float,
+          quantity: Integer,
           constraints:
             CheckoutIntents::CheckoutIntentCreateParams::Constraints::OrHash,
           promo_codes: T::Array[String],
@@ -87,7 +87,7 @@ module CheckoutIntents
           {
             buyer: CheckoutIntents::Buyer,
             product_url: String,
-            quantity: Float,
+            quantity: Integer,
             constraints:
               CheckoutIntents::CheckoutIntentCreateParams::Constraints,
             promo_codes: T::Array[String],

data/rbi/checkout_intents/models/checkout_intent_purchase_params.rbi

@@ -79,7 +79,7 @@ module CheckoutIntents
               CheckoutIntents::PaymentMethod::NekudaPaymentMethod::OrHash
             ),
           product_url: String,
-          quantity: Float,
+          quantity: Integer,
           constraints:
             CheckoutIntents::CheckoutIntentPurchaseParams::Constraints::OrHash,
           promo_codes: T::Array[String],
@@ -111,7 +111,7 @@ module CheckoutIntents
                 CheckoutIntents::PaymentMethod::NekudaPaymentMethod
               ),
             product_url: String,
-            quantity: Float,
+            quantity: Integer,
             constraints:
               CheckoutIntents::CheckoutIntentPurchaseParams::Constraints,
             promo_codes: T::Array[String],

data/rbi/checkout_intents/resources/betas/checkout_sessions.rbi

@@ -11,7 +11,7 @@ module CheckoutIntents
         sig do
           params(
             product_url: String,
-            quantity: Float,
+            quantity: Integer,
             buyer:
               ::CheckoutIntents::Betas::CheckoutSessionCreateParams::Buyer::OrHash,
             constraints:

data/rbi/checkout_intents/resources/checkout_intents.rbi

@@ -8,7 +8,7 @@ module CheckoutIntents
         params(
           buyer: ::CheckoutIntents::Buyer::OrHash,
           product_url: String,
-          quantity: Float,
+          quantity: Integer,
           constraints:
             ::CheckoutIntents::CheckoutIntentCreateParams::Constraints::OrHash,
           promo_codes: T::Array[String],
@@ -135,7 +135,7 @@ module CheckoutIntents
               ::CheckoutIntents::PaymentMethod::NekudaPaymentMethod::OrHash
             ),
           product_url: String,
-          quantity: Float,
+          quantity: Integer,
           constraints:
             ::CheckoutIntents::CheckoutIntentPurchaseParams::Constraints::OrHash,
           promo_codes: T::Array[String],
@@ -156,6 +156,119 @@ 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(
+          buyer: ::CheckoutIntents::Buyer::OrHash,
+          product_url: String,
+          quantity: Integer,
+          constraints:
+            ::CheckoutIntents::CheckoutIntentCreateParams::Constraints::OrHash,
+          promo_codes: T::Array[String],
+          variant_selections:
+            T::Array[::CheckoutIntents::VariantSelection::OrHash],
+          poll_interval: Float,
+          max_attempts: Integer,
+          request_options: ::CheckoutIntents::RequestOptions::OrHash
+        ).returns(
+          T.any(
+            ::CheckoutIntents::CheckoutIntent::AwaitingConfirmationCheckoutIntent,
+            ::CheckoutIntents::CheckoutIntent::FailedCheckoutIntent
+          )
+        )
+      end
+      def create_and_poll(
+        buyer:,
+        product_url:,
+        quantity:,
+        constraints: nil,
+        promo_codes: nil,
+        variant_selections: nil,
+        poll_interval: DEFAULT_POLL_INTERVAL,
+        max_attempts: DEFAULT_MAX_ATTEMPTS,
+        request_options: {}
+      )
+      end
+
+      # Confirm a checkout intent and poll until it reaches a completed state.
+      sig do
+        params(
+          id: String,
+          payment_method:
+            T.any(
+              ::CheckoutIntents::PaymentMethod::StripeTokenPaymentMethod::OrHash,
+              ::CheckoutIntents::PaymentMethod::BasisTheoryPaymentMethod::OrHash,
+              ::CheckoutIntents::PaymentMethod::NekudaPaymentMethod::OrHash
+            ),
+          poll_interval: Float,
+          max_attempts: Integer,
+          request_options: ::CheckoutIntents::RequestOptions::OrHash
+        ).returns(
+          T.any(
+            ::CheckoutIntents::CheckoutIntent::CompletedCheckoutIntent,
+            ::CheckoutIntents::CheckoutIntent::FailedCheckoutIntent
+          )
+        )
+      end
+      def confirm_and_poll(
+        id,
+        payment_method:,
+        poll_interval: DEFAULT_POLL_INTERVAL,
+        max_attempts: DEFAULT_MAX_ATTEMPTS,
+        request_options: {}
+      )
+      end
+
       # @api private
       sig { params(client: ::CheckoutIntents::Client).returns(T.attached_class) }
       def self.new(client:)

data/sig/checkout_intents/models/base_checkout_intent.rbs

@@ -6,7 +6,7 @@ module CheckoutIntents
         buyer: CheckoutIntents::Buyer,
         created_at: Time,
         product_url: String,
-        quantity: Float,
+        quantity: Integer,
         constraints: CheckoutIntents::BaseCheckoutIntent::Constraints,
         promo_codes: ::Array[String],
         variant_selections: ::Array[CheckoutIntents::VariantSelection]
@@ -21,7 +21,7 @@ module CheckoutIntents
 
       attr_accessor product_url: String
 
-      attr_accessor quantity: Float
+      attr_accessor quantity: Integer
 
       attr_reader constraints: CheckoutIntents::BaseCheckoutIntent::Constraints?
 
@@ -44,7 +44,7 @@ module CheckoutIntents
         buyer: CheckoutIntents::Buyer,
         created_at: Time,
         product_url: String,
-        quantity: Float,
+        quantity: Integer,
         ?constraints: CheckoutIntents::BaseCheckoutIntent::Constraints,
         ?promo_codes: ::Array[String],
         ?variant_selections: ::Array[CheckoutIntents::VariantSelection]
@@ -55,7 +55,7 @@ module CheckoutIntents
         buyer: CheckoutIntents::Buyer,
         created_at: Time,
         product_url: String,
-        quantity: Float,
+        quantity: Integer,
         constraints: CheckoutIntents::BaseCheckoutIntent::Constraints,
         promo_codes: ::Array[String],
         variant_selections: ::Array[CheckoutIntents::VariantSelection]

data/sig/checkout_intents/models/betas/checkout_session_create_params.rbs

@@ -4,7 +4,7 @@ module CheckoutIntents
       type checkout_session_create_params =
         {
           product_url: String,
-          quantity: Float,
+          quantity: Integer,
           buyer: CheckoutIntents::Betas::CheckoutSessionCreateParams::Buyer,
           constraints: CheckoutIntents::Betas::CheckoutSessionCreateParams::Constraints,
           promo_codes: ::Array[String],
@@ -18,7 +18,7 @@ module CheckoutIntents
 
         attr_accessor product_url: String
 
-        attr_accessor quantity: Float
+        attr_accessor quantity: Integer
 
         attr_reader buyer: CheckoutIntents::Betas::CheckoutSessionCreateParams::Buyer?
 
@@ -44,7 +44,7 @@ module CheckoutIntents
 
         def initialize: (
           product_url: String,
-          quantity: Float,
+          quantity: Integer,
           ?buyer: CheckoutIntents::Betas::CheckoutSessionCreateParams::Buyer,
           ?constraints: CheckoutIntents::Betas::CheckoutSessionCreateParams::Constraints,
           ?promo_codes: ::Array[String],
@@ -54,7 +54,7 @@ module CheckoutIntents
 
         def to_hash: -> {
           product_url: String,
-          quantity: Float,
+          quantity: Integer,
           buyer: CheckoutIntents::Betas::CheckoutSessionCreateParams::Buyer,
           constraints: CheckoutIntents::Betas::CheckoutSessionCreateParams::Constraints,
           promo_codes: ::Array[String],

data/sig/checkout_intents/models/checkout_intent_create_params.rbs

@@ -4,7 +4,7 @@ module CheckoutIntents
       {
         buyer: CheckoutIntents::Buyer,
         product_url: String,
-        quantity: Float,
+        quantity: Integer,
         constraints: CheckoutIntents::CheckoutIntentCreateParams::Constraints,
         promo_codes: ::Array[String],
         variant_selections: ::Array[CheckoutIntents::VariantSelection]
@@ -19,7 +19,7 @@ module CheckoutIntents
 
       attr_accessor product_url: String
 
-      attr_accessor quantity: Float
+      attr_accessor quantity: Integer
 
       attr_reader constraints: CheckoutIntents::CheckoutIntentCreateParams::Constraints?
 
@@ -40,7 +40,7 @@ module CheckoutIntents
       def initialize: (
         buyer: CheckoutIntents::Buyer,
         product_url: String,
-        quantity: Float,
+        quantity: Integer,
         ?constraints: CheckoutIntents::CheckoutIntentCreateParams::Constraints,
         ?promo_codes: ::Array[String],
         ?variant_selections: ::Array[CheckoutIntents::VariantSelection],
@@ -50,7 +50,7 @@ module CheckoutIntents
       def to_hash: -> {
         buyer: CheckoutIntents::Buyer,
         product_url: String,
-        quantity: Float,
+        quantity: Integer,
         constraints: CheckoutIntents::CheckoutIntentCreateParams::Constraints,
         promo_codes: ::Array[String],
         variant_selections: ::Array[CheckoutIntents::VariantSelection],

data/sig/checkout_intents/models/checkout_intent_purchase_params.rbs

@@ -5,7 +5,7 @@ module CheckoutIntents
         buyer: CheckoutIntents::Buyer,
         payment_method: CheckoutIntents::Models::payment_method,
         product_url: String,
-        quantity: Float,
+        quantity: Integer,
         constraints: CheckoutIntents::CheckoutIntentPurchaseParams::Constraints,
         promo_codes: ::Array[String],
         variant_selections: ::Array[CheckoutIntents::VariantSelection]
@@ -22,7 +22,7 @@ module CheckoutIntents
 
       attr_accessor product_url: String
 
-      attr_accessor quantity: Float
+      attr_accessor quantity: Integer
 
       attr_reader constraints: CheckoutIntents::CheckoutIntentPurchaseParams::Constraints?
 
@@ -44,7 +44,7 @@ module CheckoutIntents
         buyer: CheckoutIntents::Buyer,
         payment_method: CheckoutIntents::Models::payment_method,
         product_url: String,
-        quantity: Float,
+        quantity: Integer,
         ?constraints: CheckoutIntents::CheckoutIntentPurchaseParams::Constraints,
         ?promo_codes: ::Array[String],
         ?variant_selections: ::Array[CheckoutIntents::VariantSelection],
@@ -55,7 +55,7 @@ module CheckoutIntents
         buyer: CheckoutIntents::Buyer,
         payment_method: CheckoutIntents::Models::payment_method,
         product_url: String,
-        quantity: Float,
+        quantity: Integer,
         constraints: CheckoutIntents::CheckoutIntentPurchaseParams::Constraints,
         promo_codes: ::Array[String],
         variant_selections: ::Array[CheckoutIntents::VariantSelection],

data/sig/checkout_intents/resources/betas/checkout_sessions.rbs

@@ -4,7 +4,7 @@ module CheckoutIntents
       class CheckoutSessions
         def create: (
           product_url: String,
-          quantity: Float,
+          quantity: Integer,
           ?buyer: CheckoutIntents::Betas::CheckoutSessionCreateParams::Buyer,
           ?constraints: CheckoutIntents::Betas::CheckoutSessionCreateParams::Constraints,
           ?promo_codes: ::Array[String],

data/sig/checkout_intents/resources/checkout_intents.rbs

@@ -4,7 +4,7 @@ module CheckoutIntents
       def create: (
         buyer: CheckoutIntents::Buyer,
         product_url: String,
-        quantity: Float,
+        quantity: Integer,
         ?constraints: CheckoutIntents::CheckoutIntentCreateParams::Constraints,
         ?promo_codes: ::Array[String],
         ?variant_selections: ::Array[CheckoutIntents::VariantSelection],
@@ -41,13 +41,47 @@ module CheckoutIntents
         buyer: CheckoutIntents::Buyer,
         payment_method: CheckoutIntents::Models::payment_method,
         product_url: String,
-        quantity: Float,
+        quantity: Integer,
         ?constraints: CheckoutIntents::CheckoutIntentPurchaseParams::Constraints,
         ?promo_codes: ::Array[String],
         ?variant_selections: ::Array[CheckoutIntents::VariantSelection],
         ?request_options: CheckoutIntents::request_opts
       ) -> CheckoutIntents::Models::checkout_intent
 
+      def poll_until_completed: (
+        String id,
+        ?poll_interval: Float,
+        ?max_attempts: Integer,
+        ?request_options: CheckoutIntents::request_opts
+      ) -> (CheckoutIntents::CheckoutIntent::CompletedCheckoutIntent | CheckoutIntents::CheckoutIntent::FailedCheckoutIntent)
+
+      def poll_until_awaiting_confirmation: (
+        String id,
+        ?poll_interval: Float,
+        ?max_attempts: Integer,
+        ?request_options: CheckoutIntents::request_opts
+      ) -> (CheckoutIntents::CheckoutIntent::AwaitingConfirmationCheckoutIntent | CheckoutIntents::CheckoutIntent::FailedCheckoutIntent)
+
+      def create_and_poll: (
+        buyer: CheckoutIntents::Buyer,
+        product_url: String,
+        quantity: Integer,
+        ?constraints: CheckoutIntents::CheckoutIntentCreateParams::Constraints,
+        ?promo_codes: ::Array[String],
+        ?variant_selections: ::Array[CheckoutIntents::VariantSelection],
+        ?poll_interval: Float,
+        ?max_attempts: Integer,
+        ?request_options: CheckoutIntents::request_opts
+      ) -> (CheckoutIntents::CheckoutIntent::AwaitingConfirmationCheckoutIntent | CheckoutIntents::CheckoutIntent::FailedCheckoutIntent)
+
+      def confirm_and_poll: (
+        String id,
+        payment_method: CheckoutIntents::Models::payment_method,
+        ?poll_interval: Float,
+        ?max_attempts: Integer,
+        ?request_options: CheckoutIntents::request_opts
+      ) -> (CheckoutIntents::CheckoutIntent::CompletedCheckoutIntent | CheckoutIntents::CheckoutIntent::FailedCheckoutIntent)
+
       def initialize: (client: CheckoutIntents::Client) -> void
     end
   end

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: checkout-intents
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.2.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