Extract V2TypeCoercion module for bidirectional field encoding (#1926)

* Extract V2TypeCoercion module for bidirectional field encoding

Consolidates request-side (encode: native → wire) and response-side
(decode: wire → native) type coercion into a shared module that handles
all V2 encoding kinds: int64_string, decimal_string, object, array,
nullable, and discriminated_union.

Previously, request_params.rb had its own coercion implementation and
stripe_object.rb only handled decimal_string with a flat equality check.
This left int64_string fields uncoerced on the response side (returning
String instead of Integer) and didn't support nested schemas like
{kind: :nullable, inner: :decimal_string}.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Committed-By-Agent: claude

* Scope module to existing encoding kinds only

Remove nullable and discriminated_union cases — those belong in the
DU coercion branch, not this base extraction. The module should only
contain what already exists on master: int64_string, decimal_string,
object, array.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Committed-By-Agent: claude

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: jar-stripe

lib/stripe.rb

@@ -34,6 +34,7 @@
 require "stripe/object_types"
 require "stripe/event_types"
 require "stripe/request_options"
+require "stripe/v2_type_coercion"
 require "stripe/request_params"
 require "stripe/stripe_context"
 require "stripe/util"

lib/stripe/request_params.rb

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
 # typed: true
 
-require "bigdecimal"
-
 module Stripe
   # For internal use only. Does not provide a stable API and may be broken
   # with future non-major changes.
@@ -64,61 +62,8 @@ def self.field_encodings
       @field_encodings ||= {}
     end
 
-    # Recursively coerce a value based on its field encoding schema.
-    # Handles :int64_string leaves, { kind: :object, fields: ... } nesting,
-    # and { kind: :array, element: ... } for arrays.
     def self.coerce_value(value, encoding)
-      return value if value.nil?
-
-      case encoding
-      when :int64_string
-        coerce_int64_string(value)
-      when :decimal_string
-        coerce_decimal_string(value)
-      when Hash
-        coerce_composite(value, encoding)
-      else
-        value
-      end
-    end
-
-    private_class_method def self.coerce_int64_string(value)
-      case value
-      when Integer then value.to_s
-      when Array then value.map { |v| v.is_a?(Integer) ? v.to_s : v }
-      else value
-      end
-    end
-
-    private_class_method def self.coerce_decimal_string(value)
-      case value
-      when BigDecimal then value.to_s("F")
-      when Integer, Float then value.to_s
-      when Array then value.map { |v| coerce_decimal_string(v) }
-      else value
-      end
-    end
-
-    private_class_method def self.coerce_composite(value, encoding)
-      case encoding[:kind]
-      when :object
-        coerce_object(value, encoding[:fields] || {})
-      when :array
-        return value unless value.is_a?(Array)
-
-        value.map { |v| coerce_value(v, encoding[:element]) }
-      else
-        value
-      end
-    end
-
-    private_class_method def self.coerce_object(value, fields_schema)
-      return value unless value.is_a?(Hash)
-
-      value.each_with_object({}) do |(k, v), result|
-        field_encoding = fields_schema[k.to_sym]
-        result[k] = field_encoding ? coerce_value(v, field_encoding) : v
-      end
+      V2TypeCoercion.coerce_value(value, encoding, direction: :encode)
     end
 
     # Coerce a plain Hash using this class's field_encodings.

lib/stripe/stripe_object.rb

@@ -157,9 +157,8 @@ def update_attributes(values, opts = {}, dirty: true)
       values.each do |k, v|
         add_accessors([k], values) unless metaclass.method_defined?(k.to_sym)
         @values[k] = convert_value_with_inner_types(k, v, opts)
-        if self.class.field_encodings[k.to_sym] == :decimal_string && @values[k].is_a?(String)
-          @values[k] = BigDecimal(@values[k])
-        end
+        encoding = self.class.field_encodings[k.to_sym]
+        @values[k] = V2TypeCoercion.coerce_value(@values[k], encoding, direction: :decode) if encoding
         dirty_value!(@values[k]) if dirty
         @unsaved_values.add(k)
       end

lib/stripe/v2_type_coercion.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+# typed: true
+
+require "bigdecimal"
+
+module Stripe
+  # Shared V2 type coercion logic for encoding/decoding values between
+  # native Ruby types and their wire representations.
+  #
+  # Used by RequestParams (encode: native → wire) and StripeObject (decode: wire → native).
+  module V2TypeCoercion
+    # Coerce a single value based on its field encoding schema.
+    # direction: :encode (request: native → wire) or :decode (response: wire → native)
+    module_function def coerce_value(value, encoding, direction:)
+      return value if value.nil?
+
+      case encoding
+      when :int64_string
+        coerce_int64_string(value, direction)
+      when :decimal_string
+        coerce_decimal_string(value, direction)
+      when Hash
+        coerce_composite(value, encoding, direction)
+      else
+        value
+      end
+    end
+
+    # Coerce all fields in a hash according to a schema map.
+    module_function def coerce_fields(hash, schema, direction:)
+      return hash unless hash.is_a?(Hash)
+      return hash if schema.nil? || schema.empty?
+
+      hash.each_with_object({}) do |(k, v), result|
+        field_encoding = schema[k.to_sym]
+        result[k] = field_encoding ? coerce_value(v, field_encoding, direction: direction) : v
+      end
+    end
+
+    # --- leaf coercions ---
+
+    module_function def coerce_int64_string(value, direction)
+      case direction
+      when :encode
+        case value
+        when Integer then value.to_s
+        when Array then value.map { |v| v.is_a?(Integer) ? v.to_s : v }
+        else value
+        end
+      when :decode
+        case value
+        when String then Kernel.Integer(value)
+        when Array then value.map { |v| v.is_a?(String) ? Kernel.Integer(v) : v }
+        else value
+        end
+      else
+        Kernel.raise ArgumentError, "unknown direction: #{direction.inspect}"
+      end
+    end
+
+    module_function def coerce_decimal_string(value, direction)
+      case direction
+      when :encode
+        case value
+        when BigDecimal then value.to_s("F")
+        when Integer, Float then value.to_s
+        when Array then value.map { |v| coerce_decimal_string(v, direction) }
+        else value
+        end
+      when :decode
+        case value
+        when String then Kernel.BigDecimal(value)
+        when Array then value.map { |v| coerce_decimal_string(v, direction) }
+        else value
+        end
+      else
+        Kernel.raise ArgumentError, "unknown direction: #{direction.inspect}"
+      end
+    end
+
+    # --- composite coercions ---
+
+    module_function def coerce_composite(value, encoding, direction)
+      case encoding[:kind]
+      when :object
+        coerce_object(value, encoding[:fields] || {}, direction)
+      when :array
+        return value unless value.is_a?(Array)
+
+        value.map { |v| coerce_value(v, encoding[:element], direction: direction) }
+      else
+        value
+      end
+    end
+
+    module_function def coerce_object(value, fields_schema, direction)
+      return value unless value.is_a?(Hash)
+
+      coerce_fields(value, fields_schema, direction: direction)
+    end
+  end
+end

test/stripe/stripe_object_int64_test.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require File.expand_path("../test_helper", __dir__)
+
+module Stripe
+  class StripeObjectInt64Test < Test::Unit::TestCase
+    # A test resource with an int64_string-encoded field.
+    class Int64Resource < Stripe::StripeObject
+      def self.field_encodings
+        { amount: :int64_string }
+      end
+    end
+
+    # A nested inner class that has its own field_encodings.
+    class InnerDetail < Stripe::StripeObject
+      def self.field_encodings
+        { quantity: :int64_string }
+      end
+    end
+
+    # A parent resource referencing the inner class via inner_class_types.
+    # This demonstrates that nested coercion works through each StripeObject
+    # applying its own field_encodings during update_attributes (not through
+    # V2TypeCoercion recursing into StripeObjects).
+    class ParentResource < Stripe::StripeObject
+      def self.field_encodings
+        { total: :int64_string }
+      end
+
+      def self.inner_class_types
+        { detail: InnerDetail }
+      end
+    end
+
+    context "response-side int64_string coercion via construct_from" do
+      should "deserialize a string field to Integer" do
+        obj = Int64Resource.construct_from(id: "obj_1", amount: "42")
+        assert_equal 42, obj.amount
+        assert_instance_of Integer, obj.amount
+      end
+
+      should "handle large int64 values" do
+        obj = Int64Resource.construct_from(id: "obj_2", amount: "9223372036854775807")
+        assert_equal 9_223_372_036_854_775_807, obj.amount
+      end
+
+      should "preserve negative values" do
+        obj = Int64Resource.construct_from(id: "obj_3", amount: "-100")
+        assert_equal(-100, obj.amount)
+      end
+
+      should "preserve zero" do
+        obj = Int64Resource.construct_from(id: "obj_4", amount: "0")
+        assert_equal 0, obj.amount
+        assert_instance_of Integer, obj.amount
+      end
+
+      should "pass through nil without error" do
+        obj = Int64Resource.construct_from(id: "obj_5", amount: nil)
+        assert_nil obj.amount
+      end
+
+      should "leave non-encoded fields unaffected" do
+        obj = Int64Resource.construct_from(id: "obj_6", amount: "10", name: "test")
+        assert_equal "test", obj.name
+      end
+    end
+
+    context "nested resource coercion (each layer applies its own field_encodings)" do
+      should "coerce both parent and nested inner-class fields" do
+        obj = ParentResource.construct_from(
+          id: "parent_1",
+          total: "500",
+          detail: { quantity: "25", label: "items" }
+        )
+
+        assert_equal 500, obj.total
+        assert_instance_of Integer, obj.total
+
+        assert_equal 25, obj.detail.quantity
+        assert_instance_of Integer, obj.detail.quantity
+
+        assert_equal "items", obj.detail.label
+      end
+
+      should "handle nil nested object" do
+        obj = ParentResource.construct_from(id: "parent_2", total: "100", detail: nil)
+        assert_equal 100, obj.total
+        assert_nil obj.detail
+      end
+    end
+  end
+end