stripe 12.7.0.pre.beta.2 → 13.1.0.pre.beta.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: baccff36bc3c05653ea6db905dbb388ab87127e4bf722930051e170ebe38b8e3
-  data.tar.gz: 1a6e9187f2e9283d35313223dbf71c54637445af5153d26532bb8cc2b547e52b
+  metadata.gz: bb3814708d697a6e7d081dfeec39b1d54b4e32abc163a83c5e2b5d4e9934d623
+  data.tar.gz: ba8c9d94f78eab694cf55148e04de09ad390bc039537093df7a1c31d4c11234b
 SHA512:
-  metadata.gz: 7f1d75169b9c872a3bfa3bcc81e01e3b311e37a0cb458e237e5dee15f9ed7c268c2d211d8c2302371b3570965cdab0a69205bc2fa842eed29323987c6ca079ee
-  data.tar.gz: fa91a27ac219a9236ee2fa7443ac467b7e82640ea55fa90ad63ba9f8d965accf007aef216e1d2025e06176d109284e623c0f9889ede83ced264bef494c9df974
+  metadata.gz: 1f135698dc89345728ec5d73991ea0de8d2507632a2ad94a7b3cbbef206bf7b7f51b9c067d548d930a4ff6c904e91b0a3d4024c168fed9edbb539005ec7b477a
+  data.tar.gz: fc3e2a7bf5f31f9ab9d7d2415099bd913f0b7f37067a13a8cf3720a4f572f388bb507ac7dd99cbed392d68bb98e6cff6ac53ff25c7899c479cdc25b1c701ecee

data/CHANGELOG.md

@@ -1,5 +1,92 @@
 # Changelog
 
+## 13.1.0-beta.2 - 2024-10-08
+* [#1468](https://github.com/stripe/stripe-ruby/pull/1468) Update generated code for beta
+  * Add support for `submit_card` test helper method on resource `Issuing.Card`
+
+## 13.1.0-beta.1 - 2024-10-03
+* [#1465](https://github.com/stripe/stripe-ruby/pull/1465) Updates to the `Preview` class 
+  * Remove `Stripe::Preview`. Use `StripeClient#raw_request` instead (see below).
+  * Marked `Stripe.raw_request` and `Stripe.deserialize` as deprecated. Use `StripeClient#raw_request` and `StripeClient#deserialize` instead. In StripeClient, the params and opts parameters are passed as keyword arguments:
+    ```ruby
+    # Before
+    resp = Stripe.raw_request(:post, "v1/charges", , {p1: "p1"}, {stripe_account: "acct_123"})
+    charge = Stripe.deserialize(resp.data)
+  
+    # After
+    client = StripeClient.new("sk_test_123") 
+    resp = client.raw_request(:post, "/v1/charges", params: {p1: "p1"}, opts: {stripe_account: "acct_123"})
+    charge = client.deserialize(resp.data)
+    ```
+
+## 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.7.0-beta.2 - 2024-09-18
 * [#1449](https://github.com/stripe/stripe-ruby/pull/1449) Update generated code for beta
   * Remove support for resource `QuotePhase`
@@ -52,7 +139,7 @@
 
 * [#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.2.0-beta.1 - 2024-07-05
@@ -65,14 +152,14 @@
 * [#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/OPENAPI_VERSION

@@ -1 +1 @@
-v1267
+v1273

data/README.md

@@ -346,13 +346,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

data/VERSION

@@ -1 +1 @@
-12.7.0-beta.2
+13.1.0-beta.2

data/examples/README.md

@@ -0,0 +1,11 @@
+## Running an example
+
+From the examples folder, run:
+`RUBYLIB=../lib ruby your_example.rb`
+
+## Adding a new example
+
+1. Clone new_example.rb
+2. Implement your example
+3. Run it (as per above)
+4. 👍

data/examples/meter_event_stream.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+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/new_example.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "stripe"
+require "date"
+
+class NewExample
+  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 = NewExample.new(api_key)
+example.do_something_great

data/examples/stripe_webhook_handler.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+# typed: false
+
+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/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

data/lib/stripe/api_operations/request.rb

@@ -4,20 +4,21 @@ module Stripe
   module APIOperations
     module Request
       module ClassMethods
-        def execute_resource_request(method, url,
+        def execute_resource_request(method, url, base_address = :api,
                                      params = {}, opts = {}, usage = [])
           execute_resource_request_internal(
-            :execute_request, method, url, params, opts, usage
+            :execute_request, method, url, base_address, params, opts, usage
           )
         end
 
-        def execute_resource_request_stream(method, url,
+        def execute_resource_request_stream(method, url, base_address = :api,
                                             params = {}, opts = {}, usage = [],
                                             &read_body_chunk_block)
           execute_resource_request_internal(
             :execute_request_stream,
             method,
             url,
+            base_address,
             params,
             opts,
             usage,
@@ -25,13 +26,12 @@ module Stripe
           )
         end
 
-        private def request_stripe_object(method:, path:, params:, opts: {}, usage: [])
-          resp, opts = execute_resource_request(method, path, params, opts, usage)
-          Util.convert_to_stripe_object_with_params(resp.data, params, opts, resp)
+        private def request_stripe_object(method:, path:, base_address: :api, params: {}, opts: {}, usage: [])
+          execute_resource_request(method, path, base_address, params, opts, usage)
         end
 
         private def execute_resource_request_internal(client_request_method_sym,
-                                                      method, url,
+                                                      method, url, base_address,
                                                       params, opts, usage,
                                                       &read_body_chunk_block)
           params ||= {}
@@ -40,60 +40,15 @@ module Stripe
           warn_on_opts_in_params(params)
 
           opts = Util.normalize_opts(opts)
-          error_on_non_string_user_opts(opts)
+          req_opts = RequestOptions.extract_opts_from_hash(opts)
 
-          opts[:client] ||= StripeClient.active_client
-
-          headers = opts.clone
-          api_key = headers.delete(:api_key)
-          api_base = headers.delete(:api_base)
-          client = headers.delete(:client)
-          api_mode = headers.delete(:api_mode)
-          # Assume all remaining opts must be headers
-
-          resp, opts[:api_key] = client.send(
+          APIRequestor.active_requestor.send(
             client_request_method_sym,
             method, url,
-            api_base: api_base, api_key: api_key,
-            headers: headers, params: params, usage: usage, api_mode: api_mode,
+            base_address,
+            params: params, opts: req_opts, usage: usage,
             &read_body_chunk_block
           )
-
-          # Hash#select returns an array before 1.9
-          opts_to_persist = {}
-          opts.each do |k, v|
-            opts_to_persist[k] = v if Util::OPTS_PERSISTABLE.include?(k)
-          end
-
-          [resp, opts_to_persist]
-        end
-
-        # TODO: (major)
-        # This method used to be called `request`, but it's such a short name
-        # that it eventually conflicted with the name of a field on an API
-        # resource (specifically, `Event#request`), so it was renamed to
-        # something more unique.
-        #
-        # The former name had been around for just about forever though, and
-        # although all internal uses have been renamed, I've left this alias in
-        # place for backwards compatibility. Consider removing it on the next
-        # major.
-        alias request execute_resource_request
-        extend Gem::Deprecate
-        deprecate :request, "Stripe.raw_request", 2024, 7
-
-        private def error_on_non_string_user_opts(opts)
-          Util::OPTS_USER_SPECIFIED.each do |opt|
-            next unless opts.key?(opt)
-
-            val = opts[opt]
-            next if val.nil?
-            next if val.is_a?(String)
-
-            raise ArgumentError,
-                  "request option '#{opt}' should be a string value " \
-                  "(was a #{val.class})"
-          end
         end
 
         private def error_on_invalid_params(params)
@@ -105,7 +60,7 @@ module Stripe
         end
 
         private def warn_on_opts_in_params(params)
-          Util::OPTS_USER_SPECIFIED.each do |opt|
+          RequestOptions::OPTS_USER_SPECIFIED.each do |opt|
             warn("WARNING: '#{opt}' should be in opts instead of params.") if params.key?(opt)
           end
         end
@@ -115,30 +70,24 @@ module Stripe
         base.extend(ClassMethods)
       end
 
-      protected def execute_resource_request(method, url,
+      protected def execute_resource_request(method, url, base_address = :api,
                                              params = {}, opts = {}, usage = [])
         opts = @opts.merge(Util.normalize_opts(opts))
-        self.class.execute_resource_request(method, url, params, opts, usage)
+        self.class.execute_resource_request(method, url, base_address, params, opts, usage)
       end
 
-      protected def execute_resource_request_stream(method, url,
-                                                    params = {}, opts = {},
+      protected def execute_resource_request_stream(method, url, base_address = :api,
+                                                    params = {}, opts = {}, usage = [],
                                                     &read_body_chunk_block)
         opts = @opts.merge(Util.normalize_opts(opts))
         self.class.execute_resource_request_stream(
-          method, url, params, opts, &read_body_chunk_block
+          method, url, base_address, params, opts, usage, &read_body_chunk_block
         )
       end
 
-      private def request_stripe_object(method:, path:, params:, opts: {}, usage: [])
-        resp, opts = execute_resource_request(method, path, params, opts, usage)
-        Util.convert_to_stripe_object_with_params(resp.data, params, opts, resp)
+      private def request_stripe_object(method:, path:, params:, base_address: :api, opts: {}, usage: [])
+        execute_resource_request(method, path, base_address, params, opts, usage)
       end
-
-      # See notes on `alias` above.
-      alias request execute_resource_request
-      extend Gem::Deprecate
-      deprecate :request, "Stripe.raw_request", 2024, 7
     end
   end
 end

data/lib/stripe/api_operations/save.rb

@@ -65,9 +65,10 @@ module Stripe
         # Please note that id gets removed here our call to #url above has already
         # generated a uri for this object with an identifier baked in
         values.delete(:id)
-
-        resp, opts = execute_resource_request(:post, save_url, values, opts, ["save"])
-        initialize_from(resp.data, opts, resp)
+        opts = Util.normalize_opts(opts)
+        APIRequestor.active_requestor.execute_request_initialize_from(:post, save_url, :api, self,
+                                                                      params: values, opts: opts,
+                                                                      usage: ["save"])
       end
       extend Gem::Deprecate
       deprecate :save, "the `update` class method (for examples " \

data/lib/stripe/api_operations/singleton_save.rb

@@ -61,8 +61,11 @@ module Stripe
 
         values = serialize_params(self).merge(params)
 
-        resp, opts = execute_resource_request(:post, resource_url, values, opts, ["save"])
-        initialize_from(resp.data, opts, resp)
+        opts = Util.normalize_opts(opts)
+
+        APIRequestor.active_requestor.execute_request_initialize_from(:post, resource_url, :api, self,
+                                                                      params: values, opts: opts,
+                                                                      usage: ["save"])
       end
       extend Gem::Deprecate
       deprecate :save, "the `update` class method (for examples " \