stripe 12.7.0.pre.beta.2 → 13.0.1

data/OPENAPI_VERSION

@@ -1 +1 @@
-v1267
+v1268

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.0.1

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/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 " \