stripe 5.55.0 → 18.2.0.pre.beta.1

data/lib/stripe/util.rb

@@ -4,25 +4,8 @@ require "cgi"
 
 module Stripe
   module Util
-    # Options that a user is allowed to specify.
-    OPTS_USER_SPECIFIED = Set[
-      :api_key,
-      :idempotency_key,
-      :stripe_account,
-      :stripe_version
-    ].freeze
-
-    # Options that should be copyable from one StripeObject to another
-    # including options that may be internal.
-    OPTS_COPYABLE = (
-      OPTS_USER_SPECIFIED + Set[:api_base]
-    ).freeze
-
-    # Options that should be persisted between API requests. This includes
-    # client, which is an object containing an HTTP client to reuse.
-    OPTS_PERSISTABLE = (
-      OPTS_USER_SPECIFIED + Set[:client] - Set[:idempotency_key]
-    ).freeze
+    LEGAL_FIRST_CHARACTER = /[a-zA-Z_]/.freeze
+    LEGAL_VARIABLE_CHARACTER = /[a-zA-Z0-9_]/.freeze
 
     def self.objects_to_ids(obj)
       case obj
@@ -43,6 +26,18 @@ module Stripe
       @object_classes ||= Stripe::ObjectTypes.object_names_to_classes
     end
 
+    def self.v2_object_classes
+      @v2_object_classes ||= Stripe::ObjectTypes.v2_object_names_to_classes
+    end
+
+    def self.v2_event_classes
+      @v2_event_classes ||= Stripe::EventTypes.v2_event_types_to_classes
+    end
+
+    def self.event_notification_classes
+      @event_notification_classes ||= Stripe::EventTypes.event_notification_types_to_classes
+    end
+
     def self.object_name_matches_class?(object_name, klass)
       Util.object_classes[object_name] == klass
     end
@@ -61,6 +56,7 @@ module Stripe
     #     custom_method :capture, http_verb: post
     # adds a `capture` class method to the resource class that, when called,
     # will send a POST request to `/v1/<object_name>/capture`.
+    # TODO: are we comfortable with deleting this?
     def self.custom_method(resource, target, name, http_verb, http_path)
       unless %i[get post delete].include?(http_verb)
         raise ArgumentError,
@@ -79,18 +75,17 @@ module Stripe
                 "id should be a string representing the ID of an API resource"
         end
 
-        url = "#{target.resource_url}/"\
-              "#{CGI.escape(id)}/"\
+        url = "#{target.resource_url}/" \
+              "#{CGI.escape(id)}/" \
               "#{CGI.escape(http_path)}"
 
-        resp, opts = resource.execute_resource_request(
+        resource.execute_resource_request(
           http_verb,
           url,
+          :api,
           params,
           opts
         )
-
-        Util.convert_to_stripe_object(resp.data, opts)
       end
     end
 
@@ -104,19 +99,80 @@ module Stripe
     # ==== Attributes
     #
     # * +data+ - Hash of fields and values to be converted into a StripeObject.
+    # * +params+ - Params for +StripeObject+ like filters used in search that
+    #   will be reused on subsequent API calls.
     # * +opts+ - Options for +StripeObject+ like an API key that will be reused
     #   on subsequent API calls.
-    def self.convert_to_stripe_object(data, opts = {})
+    def self.convert_to_stripe_object(data, opts = {}, api_mode: :v1, requestor: nil, klass: nil)
+      convert_to_stripe_object_with_params(data, {}, opts, api_mode: api_mode, requestor: requestor, klass: klass)
+    end
+
+    # Converts a hash of fields or an array of hashes into a +StripeObject+ or
+    # array of +StripeObject+s. These new objects will be created as a concrete
+    # type as dictated by their `object` field (e.g. an `object` value of
+    # `charge` would create an instance of +Charge+), but if `object` is not
+    # present or of an unknown type, the newly created instance will fall back
+    # to being a +StripeObject+.
+    #
+    # ==== Attributes
+    #
+    # * +data+ - Hash of fields and values to be converted into a StripeObject.
+    # * +opts+ - Options for +StripeObject+ like an API key that will be reused
+    #   on subsequent API calls.
+    # * +last_response+ - The raw response associated with the object.
+    # * +api_mode+ - The API mode to use when converting the object, either :v1 or :v2.
+    # * +requestor+ - The requestor to use when constructing the object.
+    # * +v2_deleted_object+ - If true, ignore the object tag for casting purposes
+    # * +klass+ - The class to use for inner types
+    def self.convert_to_stripe_object_with_params(
+      data,
+      params,
+      opts = {},
+      last_response = nil,
+      api_mode: :v1,
+      requestor: nil,
+      v2_deleted_object: false,
+      klass: nil
+    )
       opts = normalize_opts(opts)
 
       case data
       when Array
-        data.map { |i| convert_to_stripe_object(i, opts) }
+        data.map { |i| convert_to_stripe_object(i, opts, api_mode: api_mode, requestor: requestor, klass: klass) }
       when Hash
+        # TODO: This is a terrible hack.
+        # Waiting on https://go/j/API_SERVICES-3167 to add an object in v2 lists
+        if api_mode == :v2 && data.include?(:data) && data.include?(:next_page_url)
+          return V2::ListObject.construct_from(data, opts, last_response, api_mode, requestor)
+        end
+
         # Try converting to a known object class.  If none available, fall back
         # to generic StripeObject
-        object_classes.fetch(data[:object], StripeObject)
-                      .construct_from(data, opts)
+        object_type = data[:type] || data["type"]
+        object_name = data[:object] || data["object"]
+        object_class = if klass
+                         klass
+                       elsif api_mode == :v2
+                         if v2_deleted_object
+                           V2::DeletedObject
+                         elsif object_name == "v2.core.event" && v2_event_classes.key?(object_type)
+                           v2_event_classes.fetch(object_type)
+                         else
+                           v2_object_classes.fetch(
+                             object_name, StripeObject
+                           )
+                         end
+                       else
+                         object_classes.fetch(object_name, StripeObject)
+                       end
+
+        obj = object_class.construct_from(data, opts, last_response, api_mode, requestor)
+
+        # set filters so that we can fetch the same limit, expansions, and
+        # predicates when accessing the next and previous pages
+        obj.filters = params.dup if obj && (obj.is_a?(SearchResultObject) || obj.is_a?(ListObject))
+
+        obj
       else
         data
       end
@@ -126,7 +182,7 @@ module Stripe
       config = data.delete(:config) || Stripe.config
       logger = config.logger || Stripe.logger
       if !logger.nil? ||
-         !config.log_level.nil? && config.log_level <= Stripe::LEVEL_ERROR
+         (!config.log_level.nil? && config.log_level <= Stripe::LEVEL_ERROR)
         log_internal(message, data, color: :cyan, level: Stripe::LEVEL_ERROR,
                                     logger: Stripe.logger, out: $stderr)
       end
@@ -136,7 +192,7 @@ module Stripe
       config = data.delete(:config) || Stripe.config
       logger = config.logger || Stripe.logger
       if !logger.nil? ||
-         !config.log_level.nil? && config.log_level <= Stripe::LEVEL_INFO
+         (!config.log_level.nil? && config.log_level <= Stripe::LEVEL_INFO)
         log_internal(message, data, color: :cyan, level: Stripe::LEVEL_INFO,
                                     logger: Stripe.logger, out: $stdout)
       end
@@ -146,7 +202,7 @@ module Stripe
       config = data.delete(:config) || Stripe.config
       logger = config.logger || Stripe.logger
       if !logger.nil? ||
-         !config.log_level.nil? && config.log_level <= Stripe::LEVEL_DEBUG
+         (!config.log_level.nil? && config.log_level <= Stripe::LEVEL_DEBUG)
         log_internal(message, data, color: :blue, level: Stripe::LEVEL_DEBUG,
                                     logger: Stripe.logger, out: $stdout)
       end
@@ -158,10 +214,10 @@ module Stripe
         new_hash = {}
         object.each do |key, value|
           key = (begin
-                   key.to_sym
-                 rescue StandardError
-                   key
-                 end) || key
+            key.to_sym
+          rescue StandardError
+            key
+          end) || key
           new_hash[key] = symbolize_names(value)
         end
         new_hash
@@ -176,8 +232,8 @@ module Stripe
     # parameters in a URI or as form parameters in a request body. This mainly
     # involves escaping special characters from parameter keys and values (e.g.
     # `&`).
-    def self.encode_parameters(params)
-      Util.flatten_params(params)
+    def self.encode_parameters(params, api_mode)
+      Util.flatten_params(params, api_mode)
           .map { |k, v| "#{url_encode(k)}=#{url_encode(v)}" }.join("&")
     end
 
@@ -192,7 +248,7 @@ module Stripe
         gsub("%5B", "[").gsub("%5D", "]")
     end
 
-    def self.flatten_params(params, parent_key = nil)
+    def self.flatten_params(params, api_mode, parent_key = nil)
       result = []
 
       # do not sort the final output because arrays (and arrays of hashes
@@ -200,9 +256,9 @@ module Stripe
       params.each do |key, value|
         calculated_key = parent_key ? "#{parent_key}[#{key}]" : key.to_s
         if value.is_a?(Hash)
-          result += flatten_params(value, calculated_key)
+          result += flatten_params(value, api_mode, calculated_key)
         elsif value.is_a?(Array)
-          result += flatten_params_array(value, calculated_key)
+          result += flatten_params_array(value, api_mode, calculated_key)
         else
           result << [calculated_key, value]
         end
@@ -211,14 +267,15 @@ module Stripe
       result
     end
 
-    def self.flatten_params_array(value, calculated_key)
+    def self.flatten_params_array(value, api_mode, calculated_key)
       result = []
       value.each_with_index do |elem, i|
         if elem.is_a?(Hash)
-          result += flatten_params(elem, "#{calculated_key}[#{i}]")
+          result += flatten_params(elem, api_mode, "#{calculated_key}[#{i}]")
         elsif elem.is_a?(Array)
-          result += flatten_params_array(elem, calculated_key)
+          result += flatten_params_array(elem, api_mode, calculated_key)
         else
+          # Always use indexed format for arrays
           result << ["#{calculated_key}[#{i}]", elem]
         end
       end
@@ -254,7 +311,13 @@ module Stripe
       when String
         { api_key: opts }
       when Hash
-        check_api_key!(opts.fetch(:api_key)) if opts.key?(:api_key)
+        # If the user is using request signing for authentication,
+        # no need to check the api_key per request.
+        if !(opts.key?(:client) &&
+           opts.fetch(:client).config.authenticator) &&
+           opts.key?(:api_key)
+          check_api_key!(opts.fetch(:api_key))
+        end
         # Explicitly use dup here instead of clone to avoid preserving freeze
         # state on input params.
         opts.dup
@@ -263,6 +326,14 @@ module Stripe
       end
     end
 
+    # Return false for strings that are invalid variable names
+    # Does NOT expect there to be a preceding '@' for instance variables
+    def self.valid_variable_name?(key)
+      return false if key.empty? || key[0] !~ LEGAL_FIRST_CHARACTER
+
+      key[1..].chars.all? { |char| char =~ LEGAL_VARIABLE_CHARACTER }
+    end
+
     def self.check_string_argument!(key)
       raise TypeError, "argument must be a string" unless key.is_a?(String)
 
@@ -309,6 +380,15 @@ module Stripe
       res.zero?
     end
 
+    # Returns either v1 or v2 as api_mode based on the given path
+    def self.get_api_mode(path)
+      if path.start_with?("/v2/")
+        :v2
+      else
+        :v1
+      end
+    end
+
     #
     # private
     #
@@ -351,7 +431,7 @@ module Stripe
     private_class_method :level_name
 
     def self.log_internal(message, data = {}, color:, level:, logger:, out:)
-      data_str = data.reject { |_k, v| v.nil? }
+      data_str = data.compact
                      .map do |(k, v)|
         format("%<key>s=%<value>s",
                key: colorize(k, color, logger.nil? && !out.nil? && out.isatty),
@@ -390,6 +470,15 @@ module Stripe
       # Hopefully val is a string, but protect in case it's not.
       val = val.to_s
 
+      # Some values returned by the server are encoded in ASCII-8BIT before
+      # being parsed as UTF-8 by Marshal. If we don't transform these here, then
+      # puts will fail as it tries to render UTF-8 characters as ASCII-8BIT
+      # which is not valid.
+      if val && val.encoding == Encoding::ASCII_8BIT
+        # Dup the string as it is a frozen literal.
+        val = val.dup.force_encoding("UTF-8")
+      end
+
       if %r{[^\w\-/]} =~ val
         # If the string contains any special characters, escape any double
         # quotes it has, remove newlines, and wrap the whole thing in quotes.

data/lib/stripe/v2_list_object.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Stripe
+  module V2
+    class ListObject < StripeObject
+      OBJECT_NAME = "list"
+      def self.object_name
+        "list"
+      end
+
+      # An empty list object. This is returned from +fetch_next_page+ when we know that
+      # there isn't a next page.
+      def self.empty_list(opts = {})
+        ListObject.construct_from({ data: [] }, opts, nil, :v2)
+      end
+
+      def [](key)
+        case key
+        when String, Symbol
+          super
+        else
+          raise ArgumentError,
+                "You tried to access the #{key.inspect} index, but ListObject " \
+                "types only support String keys. (HINT: List calls return an " \
+                "object with a 'data' (which is the data array). You likely " \
+                "want to call #data[#{key.inspect}])"
+        end
+      end
+
+      # Iterates through each resource in the page represented by the current
+      # `ListObject`.
+      #
+      # Note that this method makes no effort to fetch a new page when it gets to
+      # the end of the current page's resources. See also +auto_paging_each+.
+      def each(&blk)
+        data.each(&blk)
+      end
+
+      # Iterates through each resource in the page represented by the current
+      # `ListObject` in reverse.
+      def reverse_each(&blk)
+        data.reverse_each(&blk)
+      end
+
+      # Iterates through each resource in all pages, making additional fetches to
+      # the API as necessary.
+      #
+      # Note that this method will make as many API calls as necessary to fetch
+      # all resources. For more granular control, please see +each+ and
+      # +fetch_next_page+.
+      def auto_paging_each(&blk)
+        return enum_for(:auto_paging_each) unless block_given?
+
+        page = self
+        loop do
+          page.each(&blk)
+
+          break if page.next_page_url.nil?
+
+          page = page.fetch_next_page
+        end
+      end
+
+      # Returns true if the page object contains no elements.
+      def empty?
+        data.empty?
+      end
+
+      # Fetches the next page in the resource list (if there is one).
+      #
+      # This method will try to respect the limit of the current page. If none
+      # was given, the default limit will be fetched again.
+      def fetch_next_page(opts = {})
+        return self.class.empty_list(opts) if next_page_url.nil?
+
+        _request(
+          method: :get,
+          path: next_page_url,
+          base_address: :api
+        )
+      end
+    end
+  end
+end

data/lib/stripe/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Stripe
-  VERSION = "5.55.0"
+  VERSION = "18.2.0-beta.1"
 end

data/lib/stripe/webhook.rb

@@ -18,7 +18,7 @@ module Stripe
       # doesn't GC symbols. It also decreases the likelihood that we receive a
       # bad payload that fails to parse and throws an exception.
       data = JSON.parse(payload, symbolize_names: true)
-      Event.construct_from(data)
+      Event.construct_from(data, {}, nil, :v1, APIRequestor.active_requestor)
     end
 
     module Signature
@@ -108,8 +108,9 @@ module Stripe
         end
 
         if tolerance && timestamp < Time.now - tolerance
+          formatted_timestamp = Time.at(timestamp).strftime("%F %T")
           raise SignatureVerificationError.new(
-            "Timestamp outside the tolerance zone (#{Time.at(timestamp)})",
+            "Timestamp outside the tolerance zone (#{formatted_timestamp})",
             header, http_body: payload
           )
         end

data/lib/stripe.rb

@@ -15,6 +15,7 @@ require "uri"
 require "forwardable"
 
 # Version
+require "stripe/api_version"
 require "stripe/version"
 
 # API operations
@@ -24,31 +25,46 @@ require "stripe/api_operations/list"
 require "stripe/api_operations/nested_resource"
 require "stripe/api_operations/request"
 require "stripe/api_operations/save"
+require "stripe/api_operations/singleton_save"
 require "stripe/api_operations/search"
 
 # API resource support classes
 require "stripe/errors"
 require "stripe/object_types"
+require "stripe/event_types"
+require "stripe/request_options"
+require "stripe/request_params"
+require "stripe/stripe_context"
 require "stripe/util"
 require "stripe/connection_manager"
 require "stripe/multipart_encoder"
+require "stripe/api_requestor"
+require "stripe/stripe_service"
 require "stripe/stripe_client"
 require "stripe/stripe_object"
 require "stripe/stripe_response"
 require "stripe/list_object"
+require "stripe/v2_list_object"
 require "stripe/search_result_object"
 require "stripe/error_object"
 require "stripe/api_resource"
 require "stripe/api_resource_test_helpers"
 require "stripe/singleton_api_resource"
 require "stripe/webhook"
+require "stripe/stripe_event_notification_handler"
 require "stripe/stripe_configuration"
+require "stripe/resources/v2/amount"
+require "stripe/resources/v2/deleted_object"
+require "stripe/resources/v2/core/event_notification"
 
 # Named API resources
 require "stripe/resources"
+require "stripe/services"
+require "stripe/params"
 
 # OAuth
 require "stripe/oauth"
+require "stripe/services/oauth_service"
 
 module Stripe
   DEFAULT_CA_BUNDLE_PATH = __dir__ + "/data/ca-certificates.crt"
@@ -58,6 +74,34 @@ module Stripe
   LEVEL_ERROR = Logger::ERROR
   LEVEL_INFO = Logger::INFO
 
+  # API base constants
+  DEFAULT_API_BASE = "https://api.stripe.com"
+  DEFAULT_CONNECT_BASE = "https://connect.stripe.com"
+  DEFAULT_UPLOAD_BASE = "https://files.stripe.com"
+  DEFAULT_METER_EVENTS_BASE = "https://meter-events.stripe.com"
+
+  # Options that can be configured globally by users
+  USER_CONFIGURABLE_GLOBAL_OPTIONS = Set.new(%i[
+    api_key
+    api_version
+    stripe_account
+    api_base
+    uploads_base
+    connect_base
+    meter_events_base
+    open_timeout
+    read_timeout
+    write_timeout
+    proxy
+    verify_ssl_certs
+    ca_bundle_path
+    log_level
+    logger
+    max_network_retries
+    enable_telemetry
+    client_id
+  ])
+
   @app_info = nil
 
   @config = Stripe::StripeConfiguration.setup
@@ -69,11 +113,13 @@ module Stripe
 
     # User configurable options
     def_delegators :@config, :api_key, :api_key=
+    def_delegators :@config, :authenticator, :authenticator=
     def_delegators :@config, :api_version, :api_version=
     def_delegators :@config, :stripe_account, :stripe_account=
     def_delegators :@config, :api_base, :api_base=
     def_delegators :@config, :uploads_base, :uploads_base=
     def_delegators :@config, :connect_base, :connect_base=
+    def_delegators :@config, :meter_events_base, :meter_events_base=
     def_delegators :@config, :open_timeout, :open_timeout=
     def_delegators :@config, :read_timeout, :read_timeout=
     def_delegators :@config, :write_timeout, :write_timeout=
@@ -115,6 +161,58 @@ module Stripe
       version: version,
     }
   end
+
+  def self.add_beta_version(beta_name, version)
+    unless version.start_with?("v") && version[1..].to_i.to_s == version[1..]
+      raise ArgumentError, "Version must be in the format 'v' followed by a number (e.g., 'v3')"
+    end
+
+    if (index = api_version.index("; #{beta_name}="))
+      start_index = index + "; #{beta_name}=".length
+      end_index = api_version.index(";", start_index) || api_version.length
+      current_version = api_version[start_index...end_index][1..].to_i
+      new_version = version[1..].to_i
+      return if new_version <= current_version # Keep the higher version, no update needed
+
+      self.api_version = api_version[0...index] + "; #{beta_name}=#{version}" + api_version[end_index..]
+    else
+      self.api_version = "#{api_version}; #{beta_name}=#{version}"
+    end
+  end
+
+  class RawRequest
+    def initialize
+      @opts = {}
+    end
+
+    def execute(method, url, base_address: :api, params: {}, opts: {}, usage: [])
+      opts = Util.normalize_opts(opts)
+      req_opts = RequestOptions.extract_opts_from_hash(opts)
+
+      requestor = APIRequestor.active_requestor
+      resp, = requestor.send(:execute_request_internal, method, url, base_address, params, req_opts,
+                             usage)
+
+      requestor.interpret_response(resp)
+    end
+  end
+
+  # Sends a request to Stripe REST API
+  def self.raw_request(method, url, params = {}, opts = {}, base_address: :api)
+    req = RawRequest.new
+    req.execute(method, url, base_address: base_address, params: params, opts: opts,
+                             usage: ["raw_request"])
+  end
+
+  def self.deserialize(data, api_mode: :v1)
+    data = JSON.parse(data) if data.is_a?(String)
+    Util.convert_to_stripe_object(data, {}, api_mode: api_mode)
+  end
+  class << self
+    extend Gem::Deprecate
+    deprecate :raw_request, "StripeClient#raw_request", 2024, 9
+    deprecate :deserialize, "StripeClient#deserialize", 2024, 9
+  end
 end
 
 Stripe.log_level = ENV["STRIPE_LOG"] unless ENV["STRIPE_LOG"].nil?

data/rbi/stripe/resources/v2/core/event_notification.rbi

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+# typed: true
+
+module Stripe
+  module V2
+    module Core
+      class EventReasonRequest
+        sig { returns(String) }
+        def id; end
+        sig { returns(String) }
+        def idempotency_key; end
+
+        sig { params(event_reason_request_payload: T::Hash[T.untyped, T.untyped]).void }
+        def initialize(event_reason_request_payload = {}); end
+      end
+
+      class EventReason
+        sig { returns(String) }
+        def type; end
+        sig { returns(::Stripe::V2::Core::EventReasonRequest) }
+        def request; end
+
+        sig { params(event_reason_payload: T::Hash[T.untyped, T.untyped]).void }
+        def initialize(event_reason_payload = {}); end
+      end
+
+      class EventNotification
+        sig { returns(String) }
+        def id; end
+        sig { returns(String) }
+        def type; end
+        sig { returns(String) }
+        def created; end
+        sig { returns(T.nilable(String)) }
+        def context; end
+        sig { returns(T::Boolean) }
+        def livemode; end
+        sig { returns(T.nilable(::Stripe::V2::Core::EventReason)) }
+        def reason; end
+      end
+    end
+  end
+end

data/rbi/stripe/stripe_client.rbi

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+# typed: true
+
+module Stripe
+  class StripeClient
+    sig do
+      params(
+        payload: String,
+        sig_header: String,
+        secret: String,
+        tolerance: T.nilable(Integer)
+      )
+        .returns(::Stripe::V2::Core::EventNotification)
+    end
+    def parse_event_notification(payload, sig_header, secret, tolerance:); end
+
+    sig do
+      params(
+        webhook_secret: String,
+        blk: T.proc.params(
+          event_notification: ::Stripe::V2::Core::EventNotification,
+          client: ::Stripe::StripeClient,
+          details: ::Stripe::UnhandledNotificationDetails
+        ).void
+      )
+      .returns(::Stripe::StripeEventNotificationHandler)
+    end
+    def notification_handler(webhook_secret, &blk); end
+  end
+end