stripe 12.5.0 → 15.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0769dc1b2a67c8d52fd3a68fcf23d81ebbe66f172d5e32967419935bc2d8069b'
-  data.tar.gz: 812292719086f586103b3ac2a48a7d1203e3dd67916cedf77c136e834d45252a
+  metadata.gz: 9ac9a4371f393b1650cd2b5198d4e2ceed046c9676183b0d339fd985c4b8b815
+  data.tar.gz: 3fc59d72c6450657a7797088c39f5c85d9b8bba505992cfc3fdbdc7a8d27fb7d
 SHA512:
-  metadata.gz: b5f9326aa0c29bf3ef6cee7c36ca82f3f70e33b60d0813d35707bc27c533b3e6af1de89a8dc7864b6b130a419bc05be97258754a7099ee95681303679df36885
-  data.tar.gz: 10b2f9759e1d3ac6b5e1e5dec555b6b819f2f82f466d504e9b44c3772e09dbe2bdb2986a63051f7e7850ade6eace7caeacfb8042c5cd6ca67f510c1413284041
+  metadata.gz: 4f156649ca332eff3a2837ec1f038ebcc8ab9f5c35194d031e2610b45ef6b74cb0b651b3402d0afa98375a7ac293f0e54761e191dd6237e58e372b42b2cba681
+  data.tar.gz: 1cb72620268bf94d44b0ddd6090b41404efc0b25606759907c2a3d6821577b45b488738bdfdac34b6ba3a6e9fb769d9646ad1b184580d84fac3df6451a0fd172

data/CHANGELOG.md

@@ -1,4 +1,192 @@
 # Changelog
+## 15.0.0 - 2025-04-09
+
+### Breaking change
+* [#1574](https://github.com/stripe/stripe-ruby/pull/1574) Rename `object_id` in V2::Core::EventService::ListParams to `object_id_`
+  * ⚠️ Change name of parameter from `object_id` to `object_id_` on `Stripe::V2::Core::EventService::ListParams` to avoid conflict with Ruby native attribute, as found in https://github.com/stripe/stripe-ruby/issues/1567
+  * This is a no-op unless you are using this specific parameter that was introduced in `v14.0.0`
+
+* [#1576](https://github.com/stripe/stripe-ruby/pull/1576) Explicitly pass through custom headers in retrieve
+  * Fix custom options passing for resource-based retrieve
+* [#1571](https://github.com/stripe/stripe-ruby/pull/1571) Validate all instance variable keys returned from the API
+  * Validate all keys returned from the API, including custom response fields, to make sure they can be set in an instance variable, as brought up in https://github.com/stripe/stripe-ruby/issues/1564
+    * We do not set instance variables for invalid field names (as defined by the [Ruby spec](https://ruby-doc.org/docs/ruby-doc-bundle/Manual/man-1.4/syntax.html#ident)). We recommend for custom hash map response fields, use the `[]` accessor.
+       ```ruby
+       c = client.v1.customers.retrieve("cus_123")
+       c.metadata["invalid-variable-name!"]
+       c.metadata["valid_key_name_works_too"]
+      ```
+* [#1575](https://github.com/stripe/stripe-ruby/pull/1575) Remove unused youtube playlist link
+* [#1573](https://github.com/stripe/stripe-ruby/pull/1573) Remove link for stale youtube video playlist
+
+## 14.0.0 - 2025-04-01
+* [#1559](https://github.com/stripe/stripe-ruby/pull/1559) Add RBI annotations for fields and params
+  * Adds explicit field types for resources and parameters for methods, and add RBI static annotations for all resources and services
+  ![image](https://github.com/user-attachments/assets/1b6cd994-d3ea-4f47-8487-f5c7b9ebf885)
+  * See [the wiki](https://github.com/stripe/stripe-ruby/wiki/Static-Type-Annotations) for more details
+  
+* [#1543](https://github.com/stripe/stripe-ruby/pull/1543) Support for APIs in the new API version 2025-03-31.basil
+
+  This release changes the pinned API version to `2025-03-31.basil`.
+  
+  ### ⚠️ Breaking changes  due to changes in the Stripe API
+
+  Please review details for the breaking changes and alternatives in the [Stripe API changelog](https://docs.stripe.com/changelog/basil) before upgrading.
+  
+  * Remove support for resources `SubscriptionItemUsageRecordSummary` and `SubscriptionItemUsageRecord`
+  * Remove support for `create` method on resource `SubscriptionItemUsageRecord`
+  * Remove support for `list` method on resource `SubscriptionItemUsageRecordSummary`
+  * Remove support for `upcomingLines` and `upcoming` methods on resource `Invoice`
+
+  ### ⚠️ Other breaking changes in the SDK
+  * [#1553](https://github.com/stripe/stripe-ruby/pull/1553) Remove public idempotent_replayed? method
+    * ⚠️ Remove the `idempotent_replayed?` method on `StripeError`
+      * The information is accessible indirectly via the raw response headers, `StripeResponse.http_headers`. For example, use `resource.last_response.http_headers['Idempotent-Replayed']`
+  
+  ### Additions to the Stripe API
+  
+  * Add support for new resource `InvoicePayment`
+  * Add support for `list` and `retrieve` methods on resource `InvoicePayment`
+  
+
+## 13.5.0 - 2025-02-24
+* [#1534](https://github.com/stripe/stripe-ruby/pull/1534) Update generated code
+  * Fixed `Stripe::InvoiceLineItem.update` method. 
+* [#1536](https://github.com/stripe/stripe-ruby/pull/1536) Fix InvoiceLineItem parent class
+  * Fix bug where `Stripe::InvoiceLineItem` had the incorrect parent class, making it error when `update` was called
+* [#1533](https://github.com/stripe/stripe-ruby/pull/1533) add codeowners file
+
+## 13.4.1 - 2025-01-28
+* [#1528](https://github.com/stripe/stripe-ruby/pull/1528) Update generated code
+  * ⚠️ Bugfix: `invoice` and `line_item_id` can be passed to `update` method in `InvoiceLineItem`.
+
+## 13.4.0 - 2025-01-27
+* [#1510](https://github.com/stripe/stripe-ruby/pull/1510) Update generated code
+  * Add support for `close` method on resource `Treasury.FinancialAccount`
+* [#1521](https://github.com/stripe/stripe-ruby/pull/1521) pipe rubocop output to devnull
+* [#1519](https://github.com/stripe/stripe-ruby/pull/1519) Fixed typos in CONTRIBUTING.MD
+* [#1513](https://github.com/stripe/stripe-ruby/pull/1513) add justfile
+* [#1515](https://github.com/stripe/stripe-ruby/pull/1515) Added CONTRIBUTING.md file
+
+## 13.3.1 - 2025-01-13
+* [#1512](https://github.com/stripe/stripe-ruby/pull/1512) Import global configuration for options not available on StripeClient options
+  * Fixes bug where `StripeClient` was not falling back to global options for options that are not available to be set per-client
+* [#1516](https://github.com/stripe/stripe-ruby/pull/1516) ThinEvent reason and livemode
+  - Add `livemode` and optional `reason` fields to ThinEvent
+* [#1518](https://github.com/stripe/stripe-ruby/pull/1518) Pin ubuntu version in Test action
+* [#1508](https://github.com/stripe/stripe-ruby/pull/1508) Added pull request template
+
+## 13.3.0 - 2024-12-18
+* [#1500](https://github.com/stripe/stripe-ruby/pull/1500) This release changes the pinned API version to `2024-12-18.acacia`.
+
+* [#1507](https://github.com/stripe/stripe-ruby/pull/1507) Pass requestor to all deserialized objects including lists
+  
+  * Fixes bug where `StripeObject` retrieved from lists could not be used to make requests, such as `refresh`
+
+## 13.2.0 - 2024-11-20
+* [#1486](https://github.com/stripe/stripe-ruby/pull/1486) This release changes the pinned API version to `2024-11-20.acacia`.
+  * Add support for `respond` test helper method on resource `Issuing.Authorization`
+
+## 13.1.2 - 2024-11-15
+* [#1488](https://github.com/stripe/stripe-ruby/pull/1488) Fix incorrect key in param encoding
+
+## 13.1.1 - 2024-11-06
+* [#1483](https://github.com/stripe/stripe-ruby/pull/1483) Fix APIResource#retrieve not sending `stripe_version`
+
+## 13.1.0 - 2024-10-29
+* [#1472](https://github.com/stripe/stripe-ruby/pull/1472) This release changes the pinned API version to `2024-10-28.acacia`.
+  * Add support for `submit_card` test helper method on resource `Issuing.Card`
+  * Add support for new resource `V2.EventDestinations`
+  * Add support for `create`, `retrieve`, `update`, `list`, `delete`, `disable`, `enable` and `ping` methods on resource `V2.EventDestinations`
+* [#1476](https://github.com/stripe/stripe-ruby/pull/1476) Fix APIResource#retrieve bug not returning instance of custom resources
+  * Fix bug in APIResource#refresh and APIResource#retrieve where they returned an instance of `StripeObject` for custom resources. They should now return the instance of the custom resource.
+
+## 13.0.2 - 2024-10-23
+* [#1473](https://github.com/stripe/stripe-ruby/pull/1473) Always return the result of APIResource#refresh in APIResource.retrieve
+  
+  * Fix bug where we would not return the mutated `self` object when calling `APIResource.retrieve`
+
+## 13.0.1 - 2024-10-18
+* [#1471](https://github.com/stripe/stripe-ruby/pull/1471) update object tags for meter-related classes
+  
+  - fixes a bug where the `object` property of the `MeterEvent`, `MeterEventAdjustment`, and `MeterEventSession` didn't match the server.
+* [#1470](https://github.com/stripe/stripe-ruby/pull/1470) Cleaned up examples and added documentation
+
+## 13.0.0 - 2024-10-01
+* [#1458](https://github.com/stripe/stripe-ruby/pull/1458) Support for APIs in the new API version 2024-09-30.acacia
+  
+  This release changes the pinned API version to `2024-09-30.acacia`. Please read the [API Upgrade Guide](https://stripe.com/docs/upgrades#2024-09-30.acacia) and carefully review the API changes before upgrading.
+  
+  ### ⚠️ Breaking changes 
+  
+  Please refer to our [migration guide for v13](https://github.com/stripe/stripe-ruby/wiki/Migration-guide-for-v13) for more information about the backwards incompatible changes.
+  
+  #### ❗ `StripeClient` and related changes
+  * Move `StripeClient` and requestor logic to `APIRequestor`.
+    * `StripeClient#request` is still available, but is deprecated and will be removed. We encourage `StripeClient#raw_request` as a replacement (see other breaking changes for more detail).
+  * Repurpose and introduce `StripeClient` as the the entry-point to the service-based pattern, a new interface for calling the Stripe API with many benefits over the existing resource-based paradigm. Services are available under the `v1` and `v2` accessors.
+      * No global config: you can simultaneously use multiple clients with different configuration options (such as API keys)
+      * No extra API calls. All API endpoints can be accessed with a single method call. You don't have to call `retrieve` before doing an `update`.
+      * No static methods. Much easier mocking.
+  
+  #### Other breaking changes
+  
+  * Adjust default values around retries for HTTP requests. You can use the old defaults by setting them explicitly. New values are:
+    - max retries: `0` -> `2`
+    - max retry delay (seconds) `2` -> `5`
+  * Remove `StripeClient#connection_manager`. This was a legacy method from years ago.
+  * Singleton `retrieve` method now requires `params` to be passed as the first argument. Existing calls to singleton `retrieve` method with only `opts` argument will have to be updated to account for the addition of `params` argument. 
+      ```ruby
+      params = { expand: ["available"] }
+      opts = { stripe_account: "acct_123" }
+  
+      # ❌ No longer works
+      Stripe::Balance.retrieve(opts)
+  
+      # ✅ Correct way to call retrieve method
+      Stripe::Balance.retrieve(params, opts)
+      ```
+  * Moved the `Stripe.raw_request()` method that was recently added to `StripeClient`. This will use the configuration set on the StripeClient instead of the global configuration used before.
+  * Remove `APIResource.request`. Instead, use `StripeClient#raw_request` now.
+      ```ruby
+      # Instead of
+      Stripe::APIResource.request(:get, "/v1/endpoint", params, opts)
+  
+      # do
+      client = Stripe::StripeClient.new(...)
+      resp = client.raw_request(:get, "/v1/endpoint", params: params, opts: opts)
+      ```
+  * Add an additional parameter to `APIResource.execute_resource_request`. However, we discourage use of this in favor of `StripeClient#raw_request`.
+      ```ruby
+      APIResource.execute_resource_request(method, url, params = {}, opts = {}, usage = [])
+      # is now, with base_address being one of [:api, :files, :connect, :meter_events]
+      APIResource.execute_resource_request(method, url, base_address = :api, params = {}, opts = {}, usage = [])
+      ```
+  * Change parameters to `APIRequestor.execute_request` (previously `StripeClient.execute_request`). It now returns all request options from our internal request framework as the second value in the returned tuple, instead of only the API key used:
+    ```ruby
+    # Before
+    obj, api_key = StripeClient.execute_request(method, path, api_base: nil,
+                                                api_key: nil, headers: {}, params: {}, usage: [])
+  
+    # is now, with base_address being one of [:api, :files, :connect, :meter_events]
+  
+    obj, opts = APIRequestor.execute_request(method, path, base_address,
+                                            params: {}, opts: {}, usage: [])
+    puts(opts) # will output {api_key: "sk_test_123", stripe_account: "acct_123"}
+    ```
+  
+   
+  ### Additions
+  * Add support for new Usage Billing APIs `Billing.MeterEvent`, `Billing.MeterEventAdjustments`, `Billing.MeterEventSession`, `Billing.MeterEventStream` and the new Events API `Core.Events` in the [v2 namespace ](https://docs.corp.stripe.com/api-v2-overview)
+  * Add method `parse_thin_event()` on the `StripeClient` class to parse [thin events](https://docs.corp.stripe.com/event-destinations#events-overview). 
+
+
+## 12.6.0 - 2024-09-12
+* [#1442](https://github.com/stripe/stripe-ruby/pull/1442) Update generated code
+  * Add support for new resource `InvoiceRenderingTemplate`
+  * Add support for `archive`, `list`, `retrieve`, and `unarchive` methods on resource `InvoiceRenderingTemplate`
+* [#1443](https://github.com/stripe/stripe-ruby/pull/1443) Removed v1/files override
+
 ## 12.5.0 - 2024-08-08
 * [#1440](https://github.com/stripe/stripe-ruby/pull/1440) Update generated code
   * Add support for new resources `Billing.AlertTriggered` and `Billing.Alert`
@@ -18,21 +206,21 @@
 
 * [#1433](https://github.com/stripe/stripe-ruby/pull/1433) Add usage to raw_request call
 * [#1431](https://github.com/stripe/stripe-ruby/pull/1431) Add `raw_request`
-  
+  
   - Adds the ability to make raw requests to the Stripe API, by providing an HTTP method and url. This is an alternative to using `Stripe::APIResource.request(...)` to make custom requests, which is discouraged and will be broken in a future major version.
 
 ## 12.1.0 - 2024-07-05
 * [#1425](https://github.com/stripe/stripe-ruby/pull/1425) Update generated code
   * Add support for `add_lines`, `remove_lines`, and `update_lines` methods on resource `Invoice`
 * [#1420](https://github.com/stripe/stripe-ruby/pull/1420) Update static methods for delete/list on BankAccount/Card to throw NotImplementedError
-  * The below methods have been throwing `InvalidRequestError` because the urls used to make the requests have been buggy. Updating them to throw `NotImplementedError` instead just like their counterparts for update & retrieve because they cannot be implemented without the parent id. 
-  
-  Methods affected | Use these instead in the context of payment method | Use these in the context of external accounts
-  ------ | ------ | ----
-  Stripe:: BankAccount.delete | Stripe::Customer.delete_source | Stripe::Account.delete_external_account
-  Stripe:: BankAccount.list | Stripe::Customer.list_sources | Stripe::Customer.list_external_accounts
-  Stripe:: Card.delete | Stripe::Customer.delete_source | Stripe::Account.delete_external_account
-  Stripe:: Card.list | Stripe::Customer.list_sources | Stripe::Customer.list_external_accounts
+  * The below methods have been throwing `InvalidRequestError` because the urls used to make the requests have been buggy. Updating them to throw `NotImplementedError` instead just like their counterparts for update & retrieve because they cannot be implemented without the parent id. 
+  
+  Methods affected | Use these instead in the context of payment method | Use these in the context of external accounts
+  ------ | ------ | ----
+  Stripe:: BankAccount.delete | Stripe::Customer.delete_source | Stripe::Account.delete_external_account
+  Stripe:: BankAccount.list | Stripe::Customer.list_sources | Stripe::Customer.list_external_accounts
+  Stripe:: Card.delete | Stripe::Customer.delete_source | Stripe::Account.delete_external_account
+  Stripe:: Card.list | Stripe::Customer.list_sources | Stripe::Customer.list_external_accounts
 * [#1427](https://github.com/stripe/stripe-ruby/pull/1427) Regenerate rbis
 * [#1426](https://github.com/stripe/stripe-ruby/pull/1426) Remove coveralls and re-added JRuby
 

data/Gemfile

@@ -34,4 +34,8 @@ group :development do
     gem "pry"
     gem "pry-byebug"
   end
+
+  platforms :jruby do
+    gem "rbi", "0.2.4" # jruby does not support rbs, a new dependency in 0.3.0
+  end
 end

data/Makefile

@@ -1,3 +1,5 @@
+# NOTE: this file is deprecated and slated for deletion; prefer using the equivalent `just` commands.
+
 .PHONY: update-version codegen-format test ci-test
 update-version:
 	@echo "$(VERSION)" > VERSION

data/OPENAPI_VERSION

@@ -1 +1 @@
-v1187
+v1642

data/README.md

@@ -20,8 +20,6 @@ The library also provides other features. For example:
 
 See the [Ruby API docs](https://stripe.com/docs/api?lang=ruby).
 
-See [video demonstrations][youtube-playlist] covering how to use the library.
-
 ## Installation
 
 You don't need this source code unless you want to modify the gem. If you just
@@ -158,6 +156,9 @@ print(customer.last_response.http_status) # to retrieve status code
 print(customer.last_response.http_headers) # to retrieve headers
 ```
 
+If you are accessing a response field with custom hashes provided by you, such as `Customer.metadata`,
+please access your fields with the `[]` accessor.
+
 ### Configuring a proxy
 
 A proxy can be configured with `Stripe.proxy`:
@@ -317,6 +318,35 @@ You can disable this behavior if you prefer:
 Stripe.enable_telemetry = false
 ```
 
+### Types
+
+In [v14.0.0](https://github.com/stripe/stripe-python/releases/tag/v7.1.0) and newer, the library provides RBI
+static type annotations. See [the wiki](https://github.com/stripe/stripe-ruby/wiki/Static-Type-Annotations)
+for an detailed guide.
+
+Please note that these types are available only for static analysis and we only support RBIs at the moment.
+Please [report an issue](https://github.com/stripe/stripe-ruby/issues/new/choose)
+if you find discrepancies or have issues using types.
+
+The RBIs can be found in the `rbi/stripe/` directory, and to decrease `Tapioca` loading time we pack the gem with the
+combined RBI at `rbi/stripe.rbi`.
+
+#### Types and the Versioning Policy
+
+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`.
+
+#### Types and API Versions
+
+The types describe the [Stripe API version](https://stripe.com/docs/api/versioning)
+that was the latest at the time of release. This is the version that your library sends
+by default. If you are overriding `Stripe.api_version` / `stripe_version` on the StripeClient,
+or using a webhook endpoint tied to an older version, be aware that the data
+you see at runtime may not match the types.
+
 ### Beta SDKs
 
 Stripe has features in the beta phase that can be accessed via the beta version of this package.
@@ -346,13 +376,14 @@ If you:
 - prefer to bypass the method definitions in the library and specify your request details directly,
 - used the method `Stripe::APIResource.request(...)` to specify your own requests, which will soon be broken
 
-you can now use the `raw_request` method on `Stripe`.
+you can now use the `raw_request` method on `StripeClient`.
 
 ```ruby
-resp = Stripe.raw_request(:post, "/v1/beta_endpoint", {param: 123}, {stripe_version: "2022-11-15; feature_beta=v3"})
+client = Stripe::StripeClient.new(...)
+resp = client.raw_request(:post, "/v1/beta_endpoint", {param: 123}, {stripe_version: "2022-11-15; feature_beta=v3"})
 
 # (Optional) resp is a StripeResponse. You can use `Stripe.deserialize` to get a StripeObject.
-deserialized_resp = Stripe.deserialize(resp.http_body)
+deserialized_resp = client.deserialize(resp.http_body)
 ```
 
 ## Support
@@ -361,19 +392,22 @@ New features and bug fixes are released on the latest major version of the Strip
 
 ## Development
 
-The test suite depends on [stripe-mock], so make sure to fetch and run it from a
-background terminal ([stripe-mock's README][stripe-mock] also contains
-instructions for installing via Homebrew and other methods):
+[Contribution guidelines for this project](CONTRIBUTING.md)
+
+The test suite depends on [stripe-mock], so make sure to fetch and run it from a background terminal ([stripe-mock's README][stripe-mock] also contains instructions for installing via Homebrew and other methods):
 
 ```sh
-go get -u github.com/stripe/stripe-mock
+go install github.com/stripe/stripe-mock@latest
 stripe-mock
 ```
 
+We use [just](https://github.com/casey/just) for common development tasks. You can install it or run the underlying commands directly (by copying them from the `justfile`). Common tasks include:
+
 Run all tests:
 
 ```sh
-bundle exec rake test
+just test
+# or: bundle exec rake test
 ```
 
 Run a single test suite:
@@ -391,13 +425,15 @@ bundle exec ruby -Ilib/ test/stripe/util_test.rb -n /should.convert.names.to.sym
 Run the linter:
 
 ```sh
-bundle exec rake rubocop
+just lint
+# or: bundle exec rubocop
 ```
 
 Update bundled CA certificates from the [Mozilla cURL release][curl]:
 
 ```sh
-bundle exec rake update_certs
+just update-certs
+# or: bundle exec rake update_certs
 ```
 
 Update the bundled [stripe-mock] by editing the version number found in
@@ -409,7 +445,6 @@ Update the bundled [stripe-mock] by editing the version number found in
 [idempotency-keys]: https://stripe.com/docs/api/idempotent_requests?lang=ruby
 [stripe-mock]: https://github.com/stripe/stripe-mock
 [versioning]: https://stripe.com/docs/api/versioning?lang=ruby
-[youtube-playlist]: https://www.youtube.com/playlist?list=PLy1nL-pvL2M50RmP6ie-gdcSnfOuQCRYk
 
 <!--
 # vim: set tw=79:

data/Rakefile

@@ -8,11 +8,6 @@ Rake::TestTask.new do |t|
   t.pattern = "./test/**/*_test.rb"
 end
 
-if RUBY_VERSION >= "2.7.0"
-  require "rubocop/rake_task"
-  RuboCop::RakeTask.new
-end
-
 desc "Update bundled certs"
 task :update_certs do
   require "net/http"

data/VERSION

@@ -1 +1 @@
-12.5.0
+15.0.0

data/examples/README.md

@@ -0,0 +1,16 @@
+## Running an example
+
+From the examples folder, run:
+`RUBYLIB=../lib ruby your_example.rb`
+
+e.g.
+
+`RUBYLIB=../lib ruby thinevent_webhook_handler.rb`
+
+## Adding a new example
+
+1. Clone new_example.rb
+2. Implement your example
+3. Fill out the file comment. Include a description and key steps that are being demonstrated.
+4. Run it (as per above)
+5. 👍

data/examples/example_template.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+# example_template.py - This is a template for defining new examples.  It is not intended to be used directly.
+#
+# <describe what this example does>
+#
+# In this example, we:
+#   - <key step 1>
+#   - <key step 2
+#   - ...
+#
+# <describe assumptions about the user's stripe account, environment, or configuration;
+# or things to watch out for when running>
+
+require "stripe"
+require "date"
+
+class ExampleTemplate
+  attr_accessor :api_key
+
+  def initialize(api_key)
+    @api_key = api_key
+  end
+
+  def do_something_great
+    puts "Hello World"
+    # client = Stripe::StripeClient.new(api_key)
+    # client.v1
+  end
+end
+
+# Send meter events
+api_key = "{{API_KEY}}"
+
+example = ExampleTemplate.new(api_key)
+example.do_something_great

data/examples/meter_event_stream.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+# meter_event_stream.py - use the high-throughput meter event stream to report create billing meter events.
+#
+# In this example, we:
+#   - create a meter event session and store the session's authentication token
+#   - define an event with a payload
+#   - use the meter_event_stream service accessor in StripeClient to create an event stream that reports this event
+#
+# This example expects a billing meter with an event_name of 'alpaca_ai_tokens'.  If you have
+# a different meter event name, you can change it before running this example.
+
+require "stripe"
+require "date"
+
+class MeterEventManager
+  attr_accessor :api_key, :meter_event_session
+
+  def initialize(api_key)
+    @api_key = api_key
+    @meter_event_session = nil
+  end
+
+  def refresh_meter_event_session
+    return unless @meter_event_session.nil? || DateTime.parse(@meter_event_session.expires_at) <= DateTime.now
+
+    # Create a new meter event session in case the existing session expired
+    client = Stripe::StripeClient.new(api_key)
+    @meter_event_session = client.v2.billing.meter_event_session.create
+  end
+
+  def send_meter_event(meter_event)
+    # Refresh the meter event session if necessary
+    refresh_meter_event_session
+
+    # Create a meter event with the current session's authentication token
+    client = Stripe::StripeClient.new(meter_event_session.authentication_token)
+    client.v2.billing.meter_event_stream.create(
+      events: [meter_event]
+    )
+  end
+end
+
+# Send meter events
+api_key = "{{API_KEY}}"
+customer_id = "{{CUSTOMER_ID}}"
+
+manager = MeterEventManager.new(api_key)
+manager.send_meter_event(
+  {
+    event_name: "alpaca_ai_tokens",
+    payload: {
+      "stripe_customer_id" => customer_id,
+      "value" => "25",
+    },
+  }
+)

data/examples/thinevent_webhook_handler.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+# typed: false
+
+# thinevent_webhook_handler.rb - receive and process thin events like the
+# v1.billing.meter.error_report_triggered event.
+#
+# In this example, we:
+#     - create a StripeClient called client
+#     - use client.parse_thin_event to parse the received thin event webhook body
+#     - call client.v2.core.events.retrieve to retrieve the full event object
+#     - if it is a V1BillingMeterErrorReportTriggeredEvent event type, call
+#       event.fetchRelatedObject to retrieve the Billing Meter object associated
+#       with the event.
+
+require "stripe"
+require "sinatra"
+
+api_key = ENV.fetch("STRIPE_API_KEY", nil)
+# Retrieve the webhook secret from the environment variable
+webhook_secret = ENV.fetch("WEBHOOK_SECRET", nil)
+
+client = Stripe::StripeClient.new(api_key)
+
+post "/webhook" do
+  webhook_body = request.body.read
+  sig_header = request.env["HTTP_STRIPE_SIGNATURE"]
+  thin_event = client.parse_thin_event(webhook_body, sig_header, webhook_secret)
+
+  # Fetch the event data to understand the failure
+  event = client.v2.core.events.retrieve(thin_event.id)
+  if event.instance_of? Stripe::V1BillingMeterErrorReportTriggeredEvent
+    meter = event.fetch_related_object
+    meter_id = meter.id
+    puts "Success!", meter_id
+  end
+
+  # Record the failures and alert your team
+  status 200
+end

data/justfile

@@ -0,0 +1,43 @@
+set quiet
+
+import? '../sdk-codegen/utils.just'
+
+_default:
+    just --list --unsorted
+
+install *args:
+    bundle install {{ if is_dependency() == "true" {"--quiet"} else {""} }} {{ args }}
+
+# ⭐ run all unit tests
+test: install
+    bundle exec rake test
+
+# check linting / formatting status of files
+format-check *args: install
+    bundle exec rubocop {{ args }}
+alias lint-check := format-check
+
+# ⭐ check style & formatting for all files, fixing what we can
+lint: (format-check "--autocorrect")
+
+# NOTE: "-o /dev/null" is vital - rubocop has super noisy output and codegen will crash when formatting ruby if everything gets printed
+# so, we send all its output to the void
+# copy of `lint` with less output
+format: (format-check "-o /dev/null --autocorrect")
+
+update-certs: install
+    bundle exec rake update_certs
+
+# run sorbet to check type definitions
+typecheck: install
+    {{ if semver_matches(`ruby -e "puts RUBY_VERSION"`, ">=2.7") == "true" { \
+        "bundle exec srb tc" \
+    } else { \
+        "echo \"Ruby version < 2.7, skipping srb tc\"" \
+    } }}
+
+# called by tooling
+[private]
+update-version version:
+    echo "{{ version }}" > VERSION
+    perl -pi -e 's|VERSION = "[.\-\w\d]+"|VERSION = "{{ version }}"|' lib/stripe/version.rb

data/lib/stripe/api_operations/nested_resource.rb

@@ -35,7 +35,6 @@ module Stripe
         end
       end
 
-      # rubocop:disable Metrics/MethodLength
       private def define_operation(
         resource,
         operation,
@@ -54,26 +53,8 @@ module Stripe
             )
           end
         when :retrieve
-          # TODO: (Major) Split params_or_opts to params and opts and get rid of the complicated way to add params
           define_singleton_method(:"retrieve_#{resource}") \
-              do |id, nested_id, params_or_opts = {}, definitely_opts = nil|
-            opts = nil
-            params = nil
-            if definitely_opts.nil?
-              unrecognized_key = params_or_opts.keys.find { |k| !Util::OPTS_USER_SPECIFIED.include?(k) }
-              if unrecognized_key
-                raise ArgumentError,
-                      "Unrecognized request option: #{unrecognized_key}. Did you mean to specify this as " \
-                      "retrieve params? " \
-                      "If so, you must explicitly pass an opts hash as a fourth argument. " \
-                      "For example: .retrieve(#{id}, #{nested_id}, {#{unrecognized_key}: 'foo'}, {})"
-              end
-
-              opts = params_or_opts
-            else
-              opts = definitely_opts
-              params = params_or_opts
-            end
+              do |id, nested_id, params = {}, opts = {}|
             request_stripe_object(
               method: :get,
               path: send(resource_url_method, id, nested_id),
@@ -115,7 +96,6 @@ module Stripe
           raise ArgumentError, "Unknown operation: #{operation.inspect}"
         end
       end
-      # rubocop:enable Metrics/MethodLength
     end
   end
 end