In stripe-ruby v14.0.0, we added explicit field attributes on resources and request parameters for methods. We also added static inline RBI annotations, available in the rbi/ directory. These annotations describe the shape of the Stripe API much more precisely than previously available in the Ruby SDK.

This is a non-breaking change for users who want to take advantage of these types.

• There are explicit field attributes for resources. Example from the CustomerSession resource:

  # =========checkout_session.rb=========
  
  # The client secret of this Customer Session. Used on the client to set up secure access to the given `customer`.
  #
  # The client secret can be used to provide access to `customer` from your frontend. It should not be stored, logged, or exposed to anyone other than the relevant customer. Make sure that you have TLS enabled on any page that includes the client secret.
  attr_reader :client_secret
  # Configuration for the components supported by this Customer Session.
  attr_reader :components

  • The RBIs provide type annotations as well:

    # =========checkout_session.rb=========
    
    # The client secret of this Customer Session. Used on the client to set up secure access to the given `customer`.
    #
    # The client secret can be used to provide access to `customer` from your frontend. It should not be stored, logged, or exposed to anyone other than the relevant customer. Make sure that you have TLS enabled on any page that includes the client secret.
    sig { returns(String) }
    attr_reader :client_secret
    # Configuration for the components supported by this Customer Session.
    sig { returns(Components) }
    attr_reader :components

• There are now explicit param classes with attributes defined for each param, available both in resources and services. With the Sorbet annotation, example from CustomerSession::CreateParams:

  class CreateParams < Stripe::RequestParams
    class Components < Stripe::RequestParams
    ...
    end
  
    # Configuration for buy button.
    sig { returns(T.nilable(::Stripe::CustomerSession::CreateParams::Components::BuyButton)) }
    attr_accessor :buy_button
  end

• If you use an editor that has Sorbet support set up, you can see better type hints and errors when using stripe-ruby.
  • The types will warn you if you attempt to send or access a field that does not exist in GA version of the API.
  • Autocomplete will allow you to explore what API methods are available, and what data appears on the responses.
  • When you upgrade Stripe, type errors will notify you if a field has been removed or deprecated in the latest version.
• Field and param-level docstrings have been added, so you can discover the meaning of your favorite API fields from the comfort of your IDE.

• There aren't any required changes to take advantage of the attributes present in resources.
• Sorbet will not raise issues if you continue to use hashes as your params types. A migration from params hashes to classes IS required to take advantage of the Sorbet types. The migration can be done one call at a time, so does not require a huge lift to begin experimenting.

client = StripeClient.new("sk_test_123")
# using params hashes
client.v1.customers.create(
  {name: "John Doe", email: "[email protected]"}
)

# using params class
client.v1.customers.create(
  # This will have per-param type checking
  CustomerService::CreateParams.new(name: "John Doe", email: "[email protected]")
)

We release type changes in minor releases. While stripe-ruby follows semantic versioning, our semantic versions describe the runtime behavior of the library alone. Our type annotations are not reflected in the semantic version. That is, upgrading to a new minor version of stripe-ruby might result in your type checker producing a type error that it didn't before. You can use ~> x.x or x.x.x constrain the version of stripe-ruby in your Gemfile to a certain version or range of stripe-ruby.

This is similar to the versioning policy we established for our Typescript types, and we are very open to feedback. Please open a Github issue if you have thoughts!