dodopayments 1.16.1 → 1.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4412aafd8f47732a2f61ea33c4b6a29422536d903dcbb5c11eec1cf8b2af528d
-  data.tar.gz: 4fa6a909d5e0000db80a5de978f471f1ac5a85708d711cdc65ec90249b203fce
+  metadata.gz: b7d6a141291675cb8c695b5b88364058399a4f477d2f43eb851a80b4c81706f5
+  data.tar.gz: 57e2af01863ba772f020b0fb9a43b5941c04be6b138fcd5f1a78024d8bb19747
 SHA512:
-  metadata.gz: 30d7a6062eacf0b4e55439a23be00ad373f1c9bc7728fae66220585691f7eba62adf676f90301d44f6469a25dcc20690fca7fe56832f058c64b5e09d6d7a719c
-  data.tar.gz: 8d55446d2edc906fbdb18fad0e5122143e9180a13d1aa34e060b4e96b470dc4c82bb265fe439cbe91e8e2686eb579aca601381904e262b6a0bb7943b3a490990
+  metadata.gz: acd5317d471d998c14ada88e83e99d6078bead9ba90108a6055b57040ba905381163339b03341207361aa289f08b4fb282bd5adca29eb7f4964eb3ee78370252
+  data.tar.gz: 633947d1f1d0bfa26a5658f69171ef894120e538e7066e37631a283db8b333d77f7c3ccf24606bc261dd93f6fa208ffa448d258ec6ee5b15ef4f37edfb35b0da

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 1.17.0 (2025-04-22)
+
+Full Changelog: [v1.16.1...v1.17.0](https://github.com/dodopayments/dodopayments-ruby/compare/v1.16.1...v1.17.0)
+
+### Features
+
+* **api:** manual updates ([62a87c3](https://github.com/dodopayments/dodopayments-ruby/commit/62a87c3f8cdcfc59f5b93dc3dae02d0bb3712108))
+* implement `#hash` for data containers ([34c3553](https://github.com/dodopayments/dodopayments-ruby/commit/34c35538d611b8b829f6e058531bf9f9c16a08d4))
+
+
+### Chores
+
+* documentation improvements ([71c417b](https://github.com/dodopayments/dodopayments-ruby/commit/71c417bc885d00ab6e31067378e4a10ca1449aea))
+* explicitly mark apis public under `Internal` module ([b5c432b](https://github.com/dodopayments/dodopayments-ruby/commit/b5c432b32debc84016858af1c7f2ec88899410ab))
+* **internal:** minor type annotation improvements ([0356338](https://github.com/dodopayments/dodopayments-ruby/commit/0356338332f349cf9aaea6c7c309254af6bc96cc))
+* make sorbet enums easier to read ([2fb5092](https://github.com/dodopayments/dodopayments-ruby/commit/2fb509272af690159ad22df97abd1854b617af7f))
+* simplify yard annotations by removing most `@!parse` directives ([d54d094](https://github.com/dodopayments/dodopayments-ruby/commit/d54d094c00557b2730477cf86c9d835f2c256aee))
+* update README with recommended editor plugins ([b5f54c9](https://github.com/dodopayments/dodopayments-ruby/commit/b5f54c9799d10e1e8b6126bb9c91182f0e4db59d))
+* use `@!method` instead of `@!parse` for virtual method type definitions ([d890ce6](https://github.com/dodopayments/dodopayments-ruby/commit/d890ce641419ae2b7eaf32bf15e1b9a8990da53b))
+
 ## 1.16.1 (2025-04-18)
 
 Full Changelog: [v1.14.0...v1.16.1](https://github.com/dodopayments/dodopayments-ruby/compare/v1.14.0...v1.16.1)

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 "dodopayments", "~> 1.16.1"
+gem "dodopayments", "~> 1.17.0"
 ```
 
 <!-- x-release-please-end -->
@@ -38,6 +38,16 @@ payment = dodo_payments.payments.create
 puts(payment.payment_id)
 ```
 
+## Sorbet
+
+This library is written with [Sorbet type definitions](https://sorbet.org/docs/rbi). However, there is no runtime dependency on the `sorbet-runtime`.
+
+When using sorbet, it is recommended to use model classes as below. This provides stronger type checking and tooling integration.
+
+```ruby
+dodo_payments.payments.create
+```
+
 ### Pagination
 
 List methods in the Dodo Payments API are paginated.
@@ -121,61 +131,32 @@ dodo_payments = Dodopayments::Client.new(
 dodo_payments.payments.create(request_options: {timeout: 5})
 ```
 
-## LSP Support
-
-### Solargraph
-
-This library includes [Solargraph](https://solargraph.org) support for both auto completion and go to definition.
-
-```ruby
-gem "solargraph", group: :development
-```
-
-After Solargraph is installed, **you must populate its index** either via the provided editor command, or by running the following in your terminal:
-
-```sh
-bundle exec solargraph gems
-```
-
-Note: if you had installed the gem either using a `git:` or `github:` URL, or had vendored the gem using bundler, you will need to set up your [`.solargraph.yml`](https://solargraph.org/guides/configuration) to include the path to the gem's `lib` directory.
-
-```yaml
-include:
-  - 'vendor/bundle/ruby/*/gems/dodopayments-*/lib/**/*.rb'
-```
-
-Otherwise Solargraph will not be able to provide type information or auto-completion for any non-indexed libraries.
-
-### Sorbet
-
-This library is written with [Sorbet type definitions](https://sorbet.org/docs/rbi). However, there is no runtime dependency on the `sorbet-runtime`.
+## Model DSL
 
-What this means is that while you can use Sorbet to type check your code statically, and benefit from the [Sorbet Language Server](https://sorbet.org/docs/lsp) in your editor, there is no runtime type checking and execution overhead from Sorbet itself.
+This library uses a simple DSL to represent request parameters and response shapes in `lib/dodopayments/models`.
 
-Due to limitations with the Sorbet type system, where a method otherwise can take an instance of `Dodopayments::BaseModel` class, you will need to use the `**` splat operator to pass the arguments:
+With the right [editor plugins](https://shopify.github.io/ruby-lsp), you can ctrl-click on elements of the DSL to navigate around and explore the library.
 
-Please follow Sorbet's [setup guides](https://sorbet.org/docs/adopting) for best experience.
+In all places where a `BaseModel` type is specified, vanilla Ruby `Hash` can also be used. For example, the following are interchangeable as arguments:
 
 ```ruby
+# This has tooling readability, for auto-completion, static analysis, and goto definition with supported language services
 params = Dodopayments::Models::PaymentCreateParams.new
 
-dodo_payments.payments.create(**params)
-```
+# This also works
+params = {
 
-Note: **This library emits an intentional warning under the [`tapioca` toolchain](https://github.com/Shopify/tapioca)**. This is normal, and does not impact functionality.
+}
+```
 
-### Ruby LSP
+## Editor support
 
-The Ruby LSP has [best effort support](https://shopify.github.io/ruby-lsp/#guessed-types) for inferring type information from Ruby code, and as such it may not always be able to provide accurate type information.
+A combination of [Shopify LSP](https://shopify.github.io/ruby-lsp) and [Solargraph](https://solargraph.org/) is recommended for non-[Sorbet](https://sorbet.org) users. The former is especially good at go to definition, while the latter has much better auto-completion support.
 
-## Advanced
+## Advanced concepts
 
 ### Making custom/undocumented requests
 
-This library is typed for convenient access to the documented API.
-
-If you need to access undocumented endpoints, params, or response properties, the library can still be used.
-
 #### Undocumented request params
 
 If you want to explicitly send an extra param, you can do so with the `extra_query`, `extra_body`, and `extra_headers` under the `request_options:` parameter when making a requests as seen in examples above.
@@ -186,15 +167,15 @@ To make requests to undocumented endpoints, you can make requests using `client.
 
 ```ruby
 response = client.request(
-    method: :post,
-    path: '/undocumented/endpoint',
-    query: {"dog": "woof"},
-    headers: {"useful-header": "interesting-value"},
-    body: {"he": "llo"},
-  )
+  method: :post,
+  path: '/undocumented/endpoint',
+  query: {"dog": "woof"},
+  headers: {"useful-header": "interesting-value"},
+  body: {"he": "llo"},
+)
 ```
 
-### Concurrency & Connection Pooling
+### Concurrency & connection pooling
 
 The `Dodopayments::Client` instances are thread-safe, and should be re-used across multiple threads. By default, each `Client` have their own HTTP connection pool, with a maximum number of connections equal to thread count.
 
@@ -204,6 +185,30 @@ Unless otherwise specified, other classes in the SDK do not have locks protectin
 
 Currently, `Dodopayments::Client` instances are only fork-safe if there are no in-flight HTTP requests.
 
+### Sorbet
+
+#### Enums
+
+Sorbet's typed enums require sub-classing of the [`T::Enum` class](https://sorbet.org/docs/tenum) from the `sorbet-runtime` gem.
+
+Since this library does not depend on `sorbet-runtime`, it uses a [`T.all` intersection type](https://sorbet.org/docs/intersection-types) with a ruby primitive type to construct a "tagged alias" instead.
+
+```ruby
+module Dodopayments::Models::IntentStatus
+  # This alias aids language service driven navigation.
+  TaggedSymbol = T.type_alias { T.all(Symbol, Dodopayments::Models::IntentStatus) }
+end
+```
+
+#### Argument passing trick
+
+It is possible to pass a compatible model / parameter class to a method that expects keyword arguments by using the `**` splat operator.
+
+```ruby
+params = Dodopayments::Models::PaymentCreateParams.new
+dodo_payments.payments.create(**params)
+```
+
 ## Versioning
 
 This package follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions. As the library is in initial development and has a major version of `0`, APIs may change at any time.
@@ -213,3 +218,7 @@ This package considers improvements to the (non-runtime) `*.rbi` and `*.rbs` typ
 ## Requirements
 
 Ruby 3.1.0 or higher.
+
+## Contributing
+
+See [the contributing documentation](https://github.com/dodopayments/dodopayments-ruby/tree/main/CONTRIBUTING.md).

data/lib/dodopayments/client.rb

@@ -100,10 +100,10 @@ module Dodopayments
       bearer_token: ENV["DODO_PAYMENTS_API_KEY"],
       environment: nil,
       base_url: ENV["DODO_PAYMENTS_BASE_URL"],
-      max_retries: DEFAULT_MAX_RETRIES,
-      timeout: DEFAULT_TIMEOUT_IN_SECONDS,
-      initial_retry_delay: DEFAULT_INITIAL_RETRY_DELAY,
-      max_retry_delay: DEFAULT_MAX_RETRY_DELAY
+      max_retries: Dodopayments::Client::DEFAULT_MAX_RETRIES,
+      timeout: Dodopayments::Client::DEFAULT_TIMEOUT_IN_SECONDS,
+      initial_retry_delay: Dodopayments::Client::DEFAULT_INITIAL_RETRY_DELAY,
+      max_retry_delay: Dodopayments::Client::DEFAULT_MAX_RETRY_DELAY
     )
       base_url ||= Dodopayments::Client::ENVIRONMENTS.fetch(environment&.to_sym || :production) do
         message = "environment must be one of #{Dodopayments::Client::ENVIRONMENTS.keys}, got #{environment}"

data/lib/dodopayments/internal/default_page_number_pagination.rb

@@ -25,7 +25,7 @@ module Dodopayments
       end
 
       # @raise [Dodopayments::HTTP::Error]
-      # @return [Dodopayments::Internal::DefaultPageNumberPagination]
+      # @return [self]
       def next_page
         unless next_page?
           message = "No more pages available. Please check #next_page? before calling ##{__method__}"

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

@@ -216,9 +216,9 @@ module Dodopayments
         #
         #   @option req [Symbol, nil] :unwrap
         #
-        #   @option req [Class, nil] :page
+        #   @option req [Class<Dodopayments::Internal::Type::BasePage>, nil] :page
         #
-        #   @option req [Class, nil] :stream
+        #   @option req [Class<Dodopayments::Internal::Type::BaseStream>, nil] :stream
         #
         #   @option req [Dodopayments::Internal::Type::Converter, Class, nil] :model
         #
@@ -420,9 +420,9 @@ module Dodopayments
         #
         # @param unwrap [Symbol, nil]
         #
-        # @param page [Class, nil]
+        # @param page [Class<Dodopayments::Internal::Type::BasePage>, nil]
         #
-        # @param stream [Class, nil]
+        # @param stream [Class<Dodopayments::Internal::Type::BaseStream>, nil]
         #
         # @param model [Dodopayments::Internal::Type::Converter, Class, nil]
         #

data/lib/dodopayments/internal/transport/pooled_net_requester.rb

@@ -57,15 +57,11 @@ module Dodopayments
           # @return [Array(Net::HTTPGenericRequest, Proc)]
           def build_request(request, &blk)
             method, url, headers, body = request.fetch_values(:method, :url, :headers, :body)
-
-            # ensure we construct a URI class of the right scheme
-            url = URI(url.to_s)
-
             req = Net::HTTPGenericRequest.new(
               method.to_s.upcase,
               !body.nil?,
               method != :head,
-              url
+              URI(url.to_s) # ensure we construct a URI class of the right scheme
             )
 
             headers.each { req[_1] = _2 }

data/lib/dodopayments/internal/type/array_of.rb

@@ -28,13 +28,19 @@ module Dodopayments
         #   @option spec [Proc] :union
         #
         #   @option spec [Boolean] :"nil?"
+        #
+        # @return [Dodopayments::Internal::Type::ArrayOf]
         def self.[](...) = new(...)
 
+        # @api public
+        #
         # @param other [Object]
         #
         # @return [Boolean]
         def ===(other) = other.is_a?(Array) && other.all?(item_type)
 
+        # @api public
+        #
         # @param other [Object]
         #
         # @return [Boolean]
@@ -44,6 +50,11 @@ module Dodopayments
           # rubocop:enable Layout/LineLength
         end
 
+        # @api public
+        #
+        # @return [Integer]
+        def hash = [self.class, item_type].hash
+
         # @api private
         #
         # @param value [Array<Object>, Object]

data/lib/dodopayments/internal/type/base_model.rb

@@ -4,12 +4,6 @@ module Dodopayments
   module Internal
     module Type
       # @abstract
-      #
-      # @example
-      #   # `attach_existing_customer` is a `Dodopayments::Models::AttachExistingCustomer`
-      #   attach_existing_customer => {
-      #     customer_id: customer_id
-      #   }
       class BaseModel
         extend Dodopayments::Internal::Type::Converter
 
@@ -96,11 +90,13 @@ module Dodopayments
                   target, value, state: state
                 )
               end
-            rescue StandardError
+            rescue StandardError => e
               cls = self.class.name.split("::").last
-              # rubocop:disable Layout/LineLength
-              message = "Failed to parse #{cls}.#{__method__} from #{value.class} to #{target.inspect}. To get the unparsed API response, use #{cls}[:#{__method__}]."
-              # rubocop:enable Layout/LineLength
+              message = [
+                "Failed to parse #{cls}.#{__method__} from #{value.class} to #{target.inspect}.",
+                "To get the unparsed API response, use #{cls}[#{__method__.inspect}].",
+                "Cause: #{e.message}"
+              ].join(" ")
               raise Dodopayments::Errors::ConversionError.new(message)
             end
           end
@@ -168,19 +164,33 @@ module Dodopayments
             @mode = nil
           end
 
+          # @api public
+          #
           # @param other [Object]
           #
           # @return [Boolean]
           def ==(other)
             other.is_a?(Class) && other <= Dodopayments::Internal::Type::BaseModel && other.fields == fields
           end
+
+          # @api public
+          #
+          # @return [Integer]
+          def hash = fields.hash
         end
 
+        # @api public
+        #
         # @param other [Object]
         #
         # @return [Boolean]
         def ==(other) = self.class == other.class && @data == other.to_h
 
+        # @api public
+        #
+        # @return [Integer]
+        def hash = [self.class, @data].hash
+
         class << self
           # @api private
           #
@@ -294,6 +304,8 @@ module Dodopayments
           end
         end
 
+        # @api public
+        #
         # Returns the raw value associated with the given key, if found. Otherwise, nil is
         # returned.
         #
@@ -312,6 +324,8 @@ module Dodopayments
           @data[key]
         end
 
+        # @api public
+        #
         # Returns a Hash of the data underlying this object. O(1)
         #
         # Keys are Symbols and values are the raw values from the response. The return
@@ -342,6 +356,8 @@ module Dodopayments
         end
 
         class << self
+          # @api private
+          #
           # @param model [Dodopayments::Internal::Type::BaseModel]
           #
           # @return [Hash{Symbol=>Object}]
@@ -362,11 +378,15 @@ module Dodopayments
           end
         end
 
+        # @api public
+        #
         # @param a [Object]
         #
         # @return [String]
         def to_json(*a) = Dodopayments::Internal::Type::Converter.dump(self.class, self).to_json(*a)
 
+        # @api public
+        #
         # @param a [Object]
         #
         # @return [String]
@@ -374,7 +394,7 @@ module Dodopayments
 
         # Create a new instance of a model.
         #
-        # @param data [Hash{Symbol=>Object}, Dodopayments::Internal::Type::BaseModel]
+        # @param data [Hash{Symbol=>Object}, self]
         def initialize(data = {})
           case Dodopayments::Internal::Util.coerce_hash(data)
           in Hash => coerced
@@ -408,7 +428,7 @@ module Dodopayments
           end
         end
 
-        # @api private
+        # @api public
         #
         # @return [String]
         def to_s = self.class.walk(@data).to_s

data/lib/dodopayments/internal/type/base_page.rb

@@ -3,19 +3,27 @@
 module Dodopayments
   module Internal
     module Type
+      # @api private
+      #
       # @generic Elem
       #
       # This module provides a base implementation for paginated responses in the SDK.
       module BasePage
         # rubocop:disable Lint/UnusedMethodArgument
 
+        # @api public
+        #
         # @return [Boolean]
         def next_page? = (raise NotImplementedError)
 
+        # @api public
+        #
         # @raise [Dodopayments::Errors::APIError]
-        # @return [Dodopayments::Internal::Type::BasePage]
+        # @return [self]
         def next_page = (raise NotImplementedError)
 
+        # @api public
+        #
         # @param blk [Proc]
         #
         # @yieldparam [generic<Elem>]

data/lib/dodopayments/internal/type/boolean.rb

@@ -13,11 +13,15 @@ module Dodopayments
 
         private_class_method :new
 
+        # @api public
+        #
         # @param other [Object]
         #
         # @return [Boolean]
         def self.===(other) = other == true || other == false
 
+        # @api public
+        #
         # @param other [Object]
         #
         # @return [Boolean]

data/lib/dodopayments/internal/type/enum.rb

@@ -46,18 +46,17 @@ module Dodopayments
         # All of the valid Symbol values for this enum.
         #
         # @return [Array<NilClass, Boolean, Integer, Float, Symbol>]
-        def values = (@values ||= constants.map { const_get(_1) })
+        def values = constants.map { const_get(_1) }
 
-        # @api private
+        # @api public
         #
-        # Guard against thread safety issues by instantiating `@values`.
-        private def finalize! = values
-
         # @param other [Object]
         #
         # @return [Boolean]
         def ===(other) = values.include?(other)
 
+        # @api public
+        #
         # @param other [Object]
         #
         # @return [Boolean]
@@ -67,6 +66,11 @@ module Dodopayments
           # rubocop:enable Style/CaseEquality
         end
 
+        # @api public
+        #
+        # @return [Integer]
+        def hash = values.to_set.hash
+
         # @api private
         #
         # Unlike with primitives, `Enum` additionally validates that the value is a member

data/lib/dodopayments/internal/type/hash_of.rb

@@ -28,8 +28,12 @@ module Dodopayments
         #   @option spec [Proc] :union
         #
         #   @option spec [Boolean] :"nil?"
+        #
+        # @return [Dodopayments::Internal::Type::HashOf]
         def self.[](...) = new(...)
 
+        # @api public
+        #
         # @param other [Object]
         #
         # @return [Boolean]
@@ -50,6 +54,8 @@ module Dodopayments
           end
         end
 
+        # @api public
+        #
         # @param other [Object]
         #
         # @return [Boolean]
@@ -59,6 +65,11 @@ module Dodopayments
           # rubocop:enable Layout/LineLength
         end
 
+        # @api public
+        #
+        # @return [Integer]
+        def hash = [self.class, item_type].hash
+
         # @api private
         #
         # @param value [Hash{Object=>Object}, Object]

data/lib/dodopayments/internal/type/io_like.rb

@@ -13,6 +13,8 @@ module Dodopayments
 
         private_class_method :new
 
+        # @api public
+        #
         # @param other [Object]
         #
         # @return [Boolean]
@@ -25,6 +27,8 @@ module Dodopayments
           end
         end
 
+        # @api public
+        #
         # @param other [Object]
         #
         # @return [Boolean]

data/lib/dodopayments/internal/type/request_parameters.rb

@@ -12,9 +12,8 @@ module Dodopayments
 
         # @param mod [Module]
         def self.included(mod)
-          return unless mod <= Dodopayments::Internal::Type::BaseModel
+          raise ArgumentError.new(mod) unless mod <= Dodopayments::Internal::Type::BaseModel
 
-          mod.extend(Dodopayments::Internal::Type::RequestParameters::Converter)
           mod.optional(:request_options, Dodopayments::RequestOptions)
         end
 

data/lib/dodopayments/internal/type/union.rb

@@ -39,7 +39,7 @@ module Dodopayments
         #
         # @return [Array<Array(Symbol, Object)>]
         protected def derefed_variants
-          @known_variants.map { |key, variant_fn| [key, variant_fn.call] }
+          known_variants.map { |key, variant_fn| [key, variant_fn.call] }
         end
 
         # All of the specified variants for this union.
@@ -108,6 +108,8 @@ module Dodopayments
         # rubocop:disable Style/HashEachMethods
         # rubocop:disable Style/CaseEquality
 
+        # @api public
+        #
         # @param other [Object]
         #
         # @return [Boolean]
@@ -117,6 +119,8 @@ module Dodopayments
           end
         end
 
+        # @api public
+        #
         # @param other [Object]
         #
         # @return [Boolean]
@@ -124,6 +128,11 @@ module Dodopayments
           Dodopayments::Internal::Type::Union === other && other.derefed_variants == derefed_variants
         end
 
+        # @api public
+        #
+        # @return [Integer]
+        def hash = variants.hash
+
         # @api private
         #
         # @param value [Object]

data/lib/dodopayments/internal/type/unknown.rb

@@ -15,11 +15,15 @@ module Dodopayments
 
         private_class_method :new
 
+        # @api public
+        #
         # @param other [Object]
         #
         # @return [Boolean]
         def self.===(other) = true
 
+        # @api public
+        #
         # @param other [Object]
         #
         # @return [Boolean]

data/lib/dodopayments/internal.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 module Dodopayments
-  # @api private
   module Internal
     OMIT =
       Object.new.tap do

data/lib/dodopayments/models/attach_existing_customer.rb

@@ -8,12 +8,8 @@ module Dodopayments
       #   @return [String]
       required :customer_id, String
 
-      # @!parse
-      #   # @param customer_id [String]
-      #   #
-      #   def initialize(customer_id:, **) = super
-
-      # def initialize: (Hash | Dodopayments::Internal::Type::BaseModel) -> void
+      # @!method initialize(customer_id:)
+      #   @param customer_id [String]
     end
   end
 end