stripe 5.55.0 → 13.5.1

data/lib/stripe/resources/quote.rb

@@ -2,104 +2,162 @@
 # frozen_string_literal: true
 
 module Stripe
+  # A Quote is a way to model prices that you'd like to provide to a customer.
+  # Once accepted, it will automatically create an invoice, subscription or subscription schedule.
   class Quote < APIResource
     extend Stripe::APIOperations::Create
     extend Stripe::APIOperations::List
     include Stripe::APIOperations::Save
 
     OBJECT_NAME = "quote"
+    def self.object_name
+      "quote"
+    end
 
-    custom_method :accept, http_verb: :post
-    custom_method :cancel, http_verb: :post
-    custom_method :finalize_quote, http_verb: :post, http_path: "finalize"
-    custom_method :list_computed_upfront_line_items, http_verb: :get, http_path: "computed_upfront_line_items"
-    custom_method :list_line_items, http_verb: :get, http_path: "line_items"
-
+    # Accepts the specified quote.
     def accept(params = {}, opts = {})
       request_stripe_object(
         method: :post,
-        path: resource_url + "/accept",
+        path: format("/v1/quotes/%<quote>s/accept", { quote: CGI.escape(self["id"]) }),
+        params: params,
+        opts: opts
+      )
+    end
+
+    # Accepts the specified quote.
+    def self.accept(quote, params = {}, opts = {})
+      request_stripe_object(
+        method: :post,
+        path: format("/v1/quotes/%<quote>s/accept", { quote: CGI.escape(quote) }),
         params: params,
         opts: opts
       )
     end
 
+    # Cancels the quote.
     def cancel(params = {}, opts = {})
       request_stripe_object(
         method: :post,
-        path: resource_url + "/cancel",
+        path: format("/v1/quotes/%<quote>s/cancel", { quote: CGI.escape(self["id"]) }),
         params: params,
         opts: opts
       )
     end
 
+    # Cancels the quote.
+    def self.cancel(quote, params = {}, opts = {})
+      request_stripe_object(
+        method: :post,
+        path: format("/v1/quotes/%<quote>s/cancel", { quote: CGI.escape(quote) }),
+        params: params,
+        opts: opts
+      )
+    end
+
+    # A quote models prices and services for a customer. Default options for header, description, footer, and expires_at can be set in the dashboard via the [quote template](https://dashboard.stripe.com/settings/billing/quote).
+    def self.create(params = {}, opts = {})
+      request_stripe_object(method: :post, path: "/v1/quotes", params: params, opts: opts)
+    end
+
+    # Finalizes the quote.
     def finalize_quote(params = {}, opts = {})
       request_stripe_object(
         method: :post,
-        path: resource_url + "/finalize",
+        path: format("/v1/quotes/%<quote>s/finalize", { quote: CGI.escape(self["id"]) }),
         params: params,
         opts: opts
       )
     end
 
+    # Finalizes the quote.
+    def self.finalize_quote(quote, params = {}, opts = {})
+      request_stripe_object(
+        method: :post,
+        path: format("/v1/quotes/%<quote>s/finalize", { quote: CGI.escape(quote) }),
+        params: params,
+        opts: opts
+      )
+    end
+
+    # Returns a list of your quotes.
+    def self.list(params = {}, opts = {})
+      request_stripe_object(method: :get, path: "/v1/quotes", params: params, opts: opts)
+    end
+
+    # When retrieving a quote, there is an includable [computed.upfront.line_items](https://stripe.com/docs/api/quotes/object#quote_object-computed-upfront-line_items) property containing the first handful of those items. There is also a URL where you can retrieve the full (paginated) list of upfront line items.
     def list_computed_upfront_line_items(params = {}, opts = {})
       request_stripe_object(
         method: :get,
-        path: resource_url + "/computed_upfront_line_items",
+        path: format("/v1/quotes/%<quote>s/computed_upfront_line_items", { quote: CGI.escape(self["id"]) }),
         params: params,
         opts: opts
       )
     end
 
-    def list_line_items(params = {}, opts = {})
+    # When retrieving a quote, there is an includable [computed.upfront.line_items](https://stripe.com/docs/api/quotes/object#quote_object-computed-upfront-line_items) property containing the first handful of those items. There is also a URL where you can retrieve the full (paginated) list of upfront line items.
+    def self.list_computed_upfront_line_items(quote, params = {}, opts = {})
       request_stripe_object(
         method: :get,
-        path: resource_url + "/line_items",
+        path: format("/v1/quotes/%<quote>s/computed_upfront_line_items", { quote: CGI.escape(quote) }),
         params: params,
         opts: opts
       )
     end
 
-    def pdf(params = {}, opts = {}, &read_body_chunk_block)
-      unless block_given?
-        raise ArgumentError, "A read_body_chunk_block block parameter is required when calling the pdf method."
-      end
+    # When retrieving a quote, there is an includable line_items property containing the first handful of those items. There is also a URL where you can retrieve the full (paginated) list of line items.
+    def list_line_items(params = {}, opts = {})
+      request_stripe_object(
+        method: :get,
+        path: format("/v1/quotes/%<quote>s/line_items", { quote: CGI.escape(self["id"]) }),
+        params: params,
+        opts: opts
+      )
+    end
 
-      config = opts[:client]&.config || Stripe.config
+    # When retrieving a quote, there is an includable line_items property containing the first handful of those items. There is also a URL where you can retrieve the full (paginated) list of line items.
+    def self.list_line_items(quote, params = {}, opts = {})
+      request_stripe_object(
+        method: :get,
+        path: format("/v1/quotes/%<quote>s/line_items", { quote: CGI.escape(quote) }),
+        params: params,
+        opts: opts
+      )
+    end
 
+    # Download the PDF for a finalized quote. Explanation for special handling can be found [here](https://docs.stripe.com/quotes/overview#quote_pdf)
+    def pdf(params = {}, opts = {}, &read_body_chunk_block)
+      opts = { api_base: APIRequestor.active_requestor.config.uploads_base }.merge(opts)
       request_stream(
         method: :get,
-        path: resource_url + "/pdf",
+        path: format("/v1/quotes/%<quote>s/pdf", { quote: CGI.escape(self["id"]) }),
         params: params,
-        opts: {
-          api_base: config.uploads_base,
-        }.merge(opts),
+        opts: opts,
+        base_address: :files,
         &read_body_chunk_block
       )
     end
 
-    def self.pdf(id, params = {}, opts = {}, &read_body_chunk_block)
-      unless id.is_a?(String)
-        raise ArgumentError,
-              "id should be a string representing the ID of an API resource"
-      end
-
-      unless block_given?
-        raise ArgumentError, "A read_body_chunk_block block parameter is required when calling the pdf method."
-      end
-
-      config = opts[:client]&.config || Stripe.config
-
-      resp = execute_resource_request_stream(
+    # Download the PDF for a finalized quote. Explanation for special handling can be found [here](https://docs.stripe.com/quotes/overview#quote_pdf)
+    def self.pdf(quote, params = {}, opts = {}, &read_body_chunk_block)
+      opts = { api_base: APIRequestor.active_requestor.config.uploads_base }.merge(opts)
+      execute_resource_request_stream(
         :get,
-        "#{resource_url}/#{CGI.escape(id)}/pdf",
+        format("/v1/quotes/%<quote>s/pdf", { quote: CGI.escape(quote) }),
+        :files,
         params,
-        {
-          api_base: config.uploads_base,
-        }.merge(opts),
+        opts,
         &read_body_chunk_block
       )
-      resp
+    end
+
+    # A quote models prices and services for a customer.
+    def self.update(quote, params = {}, opts = {})
+      request_stripe_object(
+        method: :post,
+        path: format("/v1/quotes/%<quote>s", { quote: CGI.escape(quote) }),
+        params: params,
+        opts: opts
+      )
     end
   end
 end

data/lib/stripe/resources/radar/early_fraud_warning.rb

@@ -3,10 +3,27 @@
 
 module Stripe
   module Radar
+    # An early fraud warning indicates that the card issuer has notified us that a
+    # charge may be fraudulent.
+    #
+    # Related guide: [Early fraud warnings](https://stripe.com/docs/disputes/measuring#early-fraud-warnings)
     class EarlyFraudWarning < APIResource
       extend Stripe::APIOperations::List
 
       OBJECT_NAME = "radar.early_fraud_warning"
+      def self.object_name
+        "radar.early_fraud_warning"
+      end
+
+      # Returns a list of early fraud warnings.
+      def self.list(params = {}, opts = {})
+        request_stripe_object(
+          method: :get,
+          path: "/v1/radar/early_fraud_warnings",
+          params: params,
+          opts: opts
+        )
+      end
     end
   end
 end

data/lib/stripe/resources/radar/value_list.rb

@@ -3,6 +3,9 @@
 
 module Stripe
   module Radar
+    # Value lists allow you to group values together which can then be referenced in rules.
+    #
+    # Related guide: [Default Stripe lists](https://stripe.com/docs/radar/lists#managing-list-items)
     class ValueList < APIResource
       extend Stripe::APIOperations::Create
       include Stripe::APIOperations::Delete
@@ -10,6 +13,59 @@ module Stripe
       include Stripe::APIOperations::Save
 
       OBJECT_NAME = "radar.value_list"
+      def self.object_name
+        "radar.value_list"
+      end
+
+      # Creates a new ValueList object, which can then be referenced in rules.
+      def self.create(params = {}, opts = {})
+        request_stripe_object(
+          method: :post,
+          path: "/v1/radar/value_lists",
+          params: params,
+          opts: opts
+        )
+      end
+
+      # Deletes a ValueList object, also deleting any items contained within the value list. To be deleted, a value list must not be referenced in any rules.
+      def self.delete(value_list, params = {}, opts = {})
+        request_stripe_object(
+          method: :delete,
+          path: format("/v1/radar/value_lists/%<value_list>s", { value_list: CGI.escape(value_list) }),
+          params: params,
+          opts: opts
+        )
+      end
+
+      # Deletes a ValueList object, also deleting any items contained within the value list. To be deleted, a value list must not be referenced in any rules.
+      def delete(params = {}, opts = {})
+        request_stripe_object(
+          method: :delete,
+          path: format("/v1/radar/value_lists/%<value_list>s", { value_list: CGI.escape(self["id"]) }),
+          params: params,
+          opts: opts
+        )
+      end
+
+      # Returns a list of ValueList objects. The objects are sorted in descending order by creation date, with the most recently created object appearing first.
+      def self.list(params = {}, opts = {})
+        request_stripe_object(
+          method: :get,
+          path: "/v1/radar/value_lists",
+          params: params,
+          opts: opts
+        )
+      end
+
+      # Updates a ValueList object by setting the values of the parameters passed. Any parameters not provided will be left unchanged. Note that item_type is immutable.
+      def self.update(value_list, params = {}, opts = {})
+        request_stripe_object(
+          method: :post,
+          path: format("/v1/radar/value_lists/%<value_list>s", { value_list: CGI.escape(value_list) }),
+          params: params,
+          opts: opts
+        )
+      end
     end
   end
 end

data/lib/stripe/resources/radar/value_list_item.rb

@@ -3,12 +3,58 @@
 
 module Stripe
   module Radar
+    # Value list items allow you to add specific values to a given Radar value list, which can then be used in rules.
+    #
+    # Related guide: [Managing list items](https://stripe.com/docs/radar/lists#managing-list-items)
     class ValueListItem < APIResource
       extend Stripe::APIOperations::Create
       include Stripe::APIOperations::Delete
       extend Stripe::APIOperations::List
 
       OBJECT_NAME = "radar.value_list_item"
+      def self.object_name
+        "radar.value_list_item"
+      end
+
+      # Creates a new ValueListItem object, which is added to the specified parent value list.
+      def self.create(params = {}, opts = {})
+        request_stripe_object(
+          method: :post,
+          path: "/v1/radar/value_list_items",
+          params: params,
+          opts: opts
+        )
+      end
+
+      # Deletes a ValueListItem object, removing it from its parent value list.
+      def self.delete(item, params = {}, opts = {})
+        request_stripe_object(
+          method: :delete,
+          path: format("/v1/radar/value_list_items/%<item>s", { item: CGI.escape(item) }),
+          params: params,
+          opts: opts
+        )
+      end
+
+      # Deletes a ValueListItem object, removing it from its parent value list.
+      def delete(params = {}, opts = {})
+        request_stripe_object(
+          method: :delete,
+          path: format("/v1/radar/value_list_items/%<item>s", { item: CGI.escape(self["id"]) }),
+          params: params,
+          opts: opts
+        )
+      end
+
+      # Returns a list of ValueListItem objects. The objects are sorted in descending order by creation date, with the most recently created object appearing first.
+      def self.list(params = {}, opts = {})
+        request_stripe_object(
+          method: :get,
+          path: "/v1/radar/value_list_items",
+          params: params,
+          opts: opts
+        )
+      end
     end
   end
 end

data/lib/stripe/resources/refund.rb

@@ -2,19 +2,72 @@
 # frozen_string_literal: true
 
 module Stripe
+  # Refund objects allow you to refund a previously created charge that isn't
+  # refunded yet. Funds are refunded to the credit or debit card that's
+  # initially charged.
+  #
+  # Related guide: [Refunds](https://stripe.com/docs/refunds)
   class Refund < APIResource
     extend Stripe::APIOperations::Create
     extend Stripe::APIOperations::List
     include Stripe::APIOperations::Save
 
     OBJECT_NAME = "refund"
+    def self.object_name
+      "refund"
+    end
 
-    custom_method :cancel, http_verb: :post
-
+    # Cancels a refund with a status of requires_action.
+    #
+    # You can't cancel refunds in other states. Only refunds for payment methods that require customer action can enter the requires_action state.
     def cancel(params = {}, opts = {})
       request_stripe_object(
         method: :post,
-        path: resource_url + "/cancel",
+        path: format("/v1/refunds/%<refund>s/cancel", { refund: CGI.escape(self["id"]) }),
+        params: params,
+        opts: opts
+      )
+    end
+
+    # Cancels a refund with a status of requires_action.
+    #
+    # You can't cancel refunds in other states. Only refunds for payment methods that require customer action can enter the requires_action state.
+    def self.cancel(refund, params = {}, opts = {})
+      request_stripe_object(
+        method: :post,
+        path: format("/v1/refunds/%<refund>s/cancel", { refund: CGI.escape(refund) }),
+        params: params,
+        opts: opts
+      )
+    end
+
+    # When you create a new refund, you must specify a Charge or a PaymentIntent object on which to create it.
+    #
+    # Creating a new refund will refund a charge that has previously been created but not yet refunded.
+    # Funds will be refunded to the credit or debit card that was originally charged.
+    #
+    # You can optionally refund only part of a charge.
+    # You can do so multiple times, until the entire charge has been refunded.
+    #
+    # Once entirely refunded, a charge can't be refunded again.
+    # This method will raise an error when called on an already-refunded charge,
+    # or when trying to refund more money than is left on a charge.
+    def self.create(params = {}, opts = {})
+      request_stripe_object(method: :post, path: "/v1/refunds", params: params, opts: opts)
+    end
+
+    # Returns a list of all refunds you created. We return the refunds in sorted order, with the most recent refunds appearing first. The 10 most recent refunds are always available by default on the Charge object.
+    def self.list(params = {}, opts = {})
+      request_stripe_object(method: :get, path: "/v1/refunds", params: params, opts: opts)
+    end
+
+    # Updates the refund that you specify by setting the values of the passed parameters. Any parameters that you don't provide remain unchanged.
+    #
+    # This request only accepts metadata as an argument.
+    def self.update(refund, params = {}, opts = {})
+      request_stripe_object(
+        method: :post,
+        path: format("/v1/refunds/%<refund>s", { refund: CGI.escape(refund) }),
         params: params,
         opts: opts
       )
@@ -26,13 +79,25 @@ module Stripe
 
     class TestHelpers < APIResourceTestHelpers
       RESOURCE_CLASS = Refund
+      def self.resource_class
+        "Refund"
+      end
 
-      custom_method :expire, http_verb: :post
+      # Expire a refund with a status of requires_action.
+      def self.expire(refund, params = {}, opts = {})
+        request_stripe_object(
+          method: :post,
+          path: format("/v1/test_helpers/refunds/%<refund>s/expire", { refund: CGI.escape(refund) }),
+          params: params,
+          opts: opts
+        )
+      end
 
+      # Expire a refund with a status of requires_action.
       def expire(params = {}, opts = {})
         @resource.request_stripe_object(
           method: :post,
-          path: resource_url + "/expire",
+          path: format("/v1/test_helpers/refunds/%<refund>s/expire", { refund: CGI.escape(@resource["id"]) }),
           params: params,
           opts: opts
         )

data/lib/stripe/resources/reporting/report_run.rb

@@ -3,11 +3,42 @@
 
 module Stripe
   module Reporting
+    # The Report Run object represents an instance of a report type generated with
+    # specific run parameters. Once the object is created, Stripe begins processing the report.
+    # When the report has finished running, it will give you a reference to a file
+    # where you can retrieve your results. For an overview, see
+    # [API Access to Reports](https://stripe.com/docs/reporting/statements/api).
+    #
+    # Note that certain report types can only be run based on your live-mode data (not test-mode
+    # data), and will error when queried without a [live-mode API key](https://stripe.com/docs/keys#test-live-modes).
     class ReportRun < APIResource
       extend Stripe::APIOperations::Create
       extend Stripe::APIOperations::List
 
       OBJECT_NAME = "reporting.report_run"
+      def self.object_name
+        "reporting.report_run"
+      end
+
+      # Creates a new object and begin running the report. (Certain report types require a [live-mode API key](https://stripe.com/docs/keys#test-live-modes).)
+      def self.create(params = {}, opts = {})
+        request_stripe_object(
+          method: :post,
+          path: "/v1/reporting/report_runs",
+          params: params,
+          opts: opts
+        )
+      end
+
+      # Returns a list of Report Runs, with the most recent appearing first.
+      def self.list(params = {}, opts = {})
+        request_stripe_object(
+          method: :get,
+          path: "/v1/reporting/report_runs",
+          params: params,
+          opts: opts
+        )
+      end
     end
   end
 end

data/lib/stripe/resources/reporting/report_type.rb

@@ -3,11 +3,31 @@
 
 module Stripe
   module Reporting
+    # The Report Type resource corresponds to a particular type of report, such as
+    # the "Activity summary" or "Itemized payouts" reports. These objects are
+    # identified by an ID belonging to a set of enumerated values. See
+    # [API Access to Reports documentation](https://stripe.com/docs/reporting/statements/api)
+    # for those Report Type IDs, along with required and optional parameters.
+    #
+    # Note that certain report types can only be run based on your live-mode data (not test-mode
+    # data), and will error when queried without a [live-mode API key](https://stripe.com/docs/keys#test-live-modes).
     class ReportType < APIResource
-      extend Stripe::APIOperations::Create
       extend Stripe::APIOperations::List
 
       OBJECT_NAME = "reporting.report_type"
+      def self.object_name
+        "reporting.report_type"
+      end
+
+      # Returns a full list of Report Types.
+      def self.list(params = {}, opts = {})
+        request_stripe_object(
+          method: :get,
+          path: "/v1/reporting/report_types",
+          params: params,
+          opts: opts
+        )
+      end
     end
   end
 end

data/lib/stripe/resources/reversal.rb

@@ -2,15 +2,30 @@
 # frozen_string_literal: true
 
 module Stripe
+  # [Stripe Connect](https://stripe.com/docs/connect) platforms can reverse transfers made to a
+  # connected account, either entirely or partially, and can also specify whether
+  # to refund any related application fees. Transfer reversals add to the
+  # platform's balance and subtract from the destination account's balance.
+  #
+  # Reversing a transfer that was made for a [destination
+  # charge](https://stripe.com/docs/connect/destination-charges) is allowed only up to the amount of
+  # the charge. It is possible to reverse a
+  # [transfer_group](https://stripe.com/docs/connect/separate-charges-and-transfers#transfer-options)
+  # transfer only if the destination account has enough balance to cover the
+  # reversal.
+  #
+  # Related guide: [Reverse transfers](https://stripe.com/docs/connect/separate-charges-and-transfers#reverse-transfers)
   class Reversal < APIResource
-    extend Stripe::APIOperations::List
     include Stripe::APIOperations::Save
 
     OBJECT_NAME = "transfer_reversal"
+    def self.object_name
+      "transfer_reversal"
+    end
 
     def resource_url
       "#{Transfer.resource_url}/#{CGI.escape(transfer)}/reversals" \
-      "/#{CGI.escape(id)}"
+        "/#{CGI.escape(id)}"
     end
 
     def self.update(_id, _params = nil, _opts = nil)

data/lib/stripe/resources/review.rb

@@ -2,20 +2,41 @@
 # frozen_string_literal: true
 
 module Stripe
+  # Reviews can be used to supplement automated fraud detection with human expertise.
+  #
+  # Learn more about [Radar](https://stripe.com/radar) and reviewing payments
+  # [here](https://stripe.com/docs/radar/reviews).
   class Review < APIResource
     extend Stripe::APIOperations::List
 
     OBJECT_NAME = "review"
+    def self.object_name
+      "review"
+    end
 
-    custom_method :approve, http_verb: :post
-
+    # Approves a Review object, closing it and removing it from the list of reviews.
     def approve(params = {}, opts = {})
       request_stripe_object(
         method: :post,
-        path: resource_url + "/approve",
+        path: format("/v1/reviews/%<review>s/approve", { review: CGI.escape(self["id"]) }),
         params: params,
         opts: opts
       )
     end
+
+    # Approves a Review object, closing it and removing it from the list of reviews.
+    def self.approve(review, params = {}, opts = {})
+      request_stripe_object(
+        method: :post,
+        path: format("/v1/reviews/%<review>s/approve", { review: CGI.escape(review) }),
+        params: params,
+        opts: opts
+      )
+    end
+
+    # Returns a list of Review objects that have open set to true. The objects are sorted in descending order by creation date, with the most recently created object appearing first.
+    def self.list(params = {}, opts = {})
+      request_stripe_object(method: :get, path: "/v1/reviews", params: params, opts: opts)
+    end
   end
 end

data/lib/stripe/resources/setup_attempt.rb

@@ -2,9 +2,21 @@
 # frozen_string_literal: true
 
 module Stripe
+  # A SetupAttempt describes one attempted confirmation of a SetupIntent,
+  # whether that confirmation is successful or unsuccessful. You can use
+  # SetupAttempts to inspect details of a specific attempt at setting up a
+  # payment method using a SetupIntent.
   class SetupAttempt < APIResource
     extend Stripe::APIOperations::List
 
     OBJECT_NAME = "setup_attempt"
+    def self.object_name
+      "setup_attempt"
+    end
+
+    # Returns a list of SetupAttempts that associate with a provided SetupIntent.
+    def self.list(params = {}, opts = {})
+      request_stripe_object(method: :get, path: "/v1/setup_attempts", params: params, opts: opts)
+    end
   end
 end