paddle 2.10 → 3.0

data/lib/paddle/client.rb

@@ -2,43 +2,60 @@ require "faraday"
 
 module Paddle
   class Client
+    @connections = {}
+    @mutex = Mutex.new
+
     class << self
+      # One connection is kept per base URL and set of connection options. The API key and
+      # version are sent with each request, so config changes take effect straight away
       def connection
-        @connection ||= create_connection
+        config = Paddle.config
+        key = [ config.url, config.connection_options.hash ]
+
+        @mutex.synchronize do
+          @connections[key] ||= create_connection(config)
+        end
       end
 
       def get_request(url, params: {}, headers: {})
-        handle_response(connection.get(url, params, headers))
+        # Paddle expects arrays as comma-separated lists, e.g. status=active,past_due
+        params = params.transform_values { |value| value.is_a?(Array) ? value.join(",") : value }
+
+        # skip_count is sent as a header rather than a query param
+        headers = headers.merge("Skip-Count" => "true") if params.delete(:skip_count)
+
+        handle_response(connection.get(url, params, request_headers(headers)))
       end
 
       def post_request(url, body: {}, headers: {})
-        handle_response(connection.post(url, body, headers))
+        handle_response(connection.post(url, body, request_headers(headers)))
       end
 
       def patch_request(url, body:, headers: {})
-        handle_response(connection.patch(url, body, headers))
+        handle_response(connection.patch(url, body, request_headers(headers)))
       end
 
       def delete_request(url, headers: {})
-        handle_response(connection.delete(url, headers))
+        handle_response(connection.delete(url, nil, request_headers(headers)))
       end
 
       private
 
-      def create_connection
-        Faraday.new(Paddle.config.url, Paddle.config.connection_options) do |conn|
-          conn.request :authorization, :Bearer, Paddle.config.api_key
-          conn.headers = default_headers
+      def create_connection(config)
+        Faraday.new(config.url, config.connection_options) do |conn|
+          conn.headers = { "User-Agent" => "paddle/v#{VERSION} (github.com/d34ndev/paddle)" }
           conn.request :json
           conn.response :json
         end
       end
 
-      def default_headers
+      def request_headers(headers)
+        config = Paddle.config
+
         {
-          "User-Agent" => "paddle/v#{VERSION} (github.com/deanpcmad/paddle)",
-          "Paddle-Version" => Paddle.config.version.to_s
-        }
+          "Authorization" => "Bearer #{config.api_key}",
+          "Paddle-Version" => config.version.to_s
+        }.merge(headers)
       end
 
       def handle_response(response)
@@ -49,8 +66,7 @@ module Paddle
       end
 
       def error?(response)
-        [ 400, 401, 403, 404, 409, 429, 500, 501, 503 ].include?(response.status) ||
-          response.body&.key?("error")
+        !response.success? || (response.body.is_a?(Hash) && response.body.key?("error"))
       end
 
       def raise_error(response)

data/lib/paddle/collection.rb

@@ -2,28 +2,64 @@ module Paddle
   class Collection
     include Enumerable
 
-    attr_reader :data, :total
+    attr_reader :data, :total, :per_page, :next_url
 
     def self.from_response(response, type:)
       body = response.body
 
-      data  = body["data"].map { |attrs| type.new(attrs) }
+      data = body["data"].map { |attrs| type.new(attrs) }
+      pagination = body.dig("meta", "pagination")
 
-      if body["meta"]["pagination"]
-        total = body["meta"]["pagination"]["estimated_total"]
+      if pagination
+        new(
+          data: data,
+          total: pagination["estimated_total"],
+          per_page: pagination["per_page"],
+          has_more: pagination["has_more"],
+          next_url: pagination["next"],
+          type: type,
+          skip_count: response.env.request_headers["Skip-Count"] == "true"
+        )
       else
-        total = body["data"].count
+        new(data: data, total: data.count)
       end
-
-      new(
-        data: data,
-        total: total
-      )
     end
 
-    def initialize(data:, total:)
+    def initialize(data:, total:, per_page: nil, has_more: false, next_url: nil, type: nil, skip_count: false)
       @data = data
       @total = total
+      @per_page = per_page
+      @has_more = has_more
+      @next_url = next_url
+      @type = type
+      @skip_count = skip_count
+    end
+
+    def has_more?
+      @has_more == true
+    end
+
+    def skip_count?
+      @skip_count
+    end
+
+    # Paddle returns a next URL even on the last page, so has_more is checked first
+    def next_page
+      return unless has_more? && next_url && @type
+
+      # Only the path and query are used, so requests always go to the configured API host
+      response = Client.get_request(URI(next_url).request_uri.delete_prefix("/"), params: { skip_count: skip_count? })
+      Collection.from_response(response, type: @type)
+    end
+
+    def auto_paging_each(&block)
+      return enum_for(:auto_paging_each) unless block_given?
+
+      page = self
+      while page
+        page.each(&block)
+        page = page.next_page
+      end
     end
 
     def each(&block)

data/lib/paddle/configuration.rb

@@ -3,23 +3,67 @@
 module Paddle
   class Configuration
     attr_reader :environment
+    attr_reader :api_key
 
     attr_accessor :version
-    attr_accessor :api_key
     attr_accessor :connection_options
 
     def initialize
-      @environment ||= :production
+      @environment = :production
+      @environment_set = false
       @version ||= 1
       @connection_options = {}
     end
 
+    # When the environment isn't set, it's detected from the API key
     def environment=(env)
-      env = env.nil? ? :production : env.to_sym
+      if env.nil?
+        @environment_set = false
+        @environment = key_environment || :production
+        return
+      end
+
+      env = env.to_sym
       unless [ :development, :sandbox, :production ].include?(env)
         raise ArgumentError, "#{env.inspect} is not a valid environment"
       end
+
+      check_key_matches!(env)
       @environment = env
+      @environment_set = true
+    end
+
+    def api_key=(key)
+      @api_key = key
+
+      if @environment_set
+        check_key_matches!(@environment)
+      else
+        @environment = key_environment || :production
+      end
+    end
+
+    MERGEABLE = [ :api_key, :environment, :version, :connection_options ].freeze
+
+    # Returns a new Configuration with the given options applied over this one. When a new
+    # API key is given without an environment, the environment is detected from the key,
+    # or kept from this config for older keys without a prefix
+    def merge(**options)
+      unknown = options.keys - MERGEABLE
+      raise ArgumentError, "Unknown config options: #{unknown.join(", ")}" if unknown.any?
+
+      config = Configuration.new
+      config.version = options.fetch(:version, version)
+      config.connection_options = options.fetch(:connection_options, connection_options)
+      config.api_key = options.fetch(:api_key, api_key)
+
+      if options.key?(:environment)
+        config.environment = options[:environment]
+      elsif !options.key?(:api_key) || config.key_environment.nil?
+        config.environment = environment
+      end
+
+      config
     end
 
     def url
@@ -30,5 +74,24 @@ module Paddle
         "https://sandbox-api.paddle.com"
       end
     end
+
+    protected
+
+    # API keys created since May 2025 start with pdl_live_ or pdl_sdbx_. Older keys have no prefix
+    def key_environment
+      case @api_key
+      when /\Apdl_live_/ then :production
+      when /\Apdl_sdbx_/ then :sandbox
+      end
+    end
+
+    private
+
+    def check_key_matches!(env)
+      key_env = key_environment
+      return if key_env.nil? || (key_env == :production) == (env == :production)
+
+      raise ArgumentError, "The API key is for the #{key_env} environment, but environment is set to #{env.inspect}"
+    end
   end
 end

data/lib/paddle/error_generator.rb

@@ -8,7 +8,8 @@ module Paddle
     attr_reader :request_id
 
     def initialize(response_body, http_status_code)
-      @response_body = response_body
+      # Non-JSON responses (e.g. an HTML page from a gateway) have no Paddle error details
+      @response_body = response_body.is_a?(Hash) ? response_body : {}
       @http_status_code = http_status_code
       set_paddle_error_values
       super(build_message)
@@ -25,9 +26,7 @@ module Paddle
     end
 
     def error_message
-      @paddle_error_message || @response_body.dig("error", "code")
-    rescue NoMethodError
-      "An unknown error occurred."
+      @paddle_error_message || @paddle_error_code || "An unknown error occurred."
     end
 
     def build_message
@@ -121,7 +120,7 @@ module Paddle
       private
 
       def error_message
-        "You have been rate limited for sending more than 20 requests per second."
+        "The Paddle API is temporarily unavailable. Try again later."
       end
     end
 

data/lib/paddle/models/adjustment.rb

@@ -6,17 +6,17 @@ module Paddle
         Collection.from_response(response, type: Adjustment)
       end
 
-      def create(transaction_id:, action:, reason:, items:, **params)
-        attrs = { transaction_id: transaction_id, action: action, reason: reason, items: items }
+      # items can be omitted when type is "full"
+      def create(transaction_id:, action:, reason:, items: nil, **params)
+        attrs = { transaction_id: transaction_id, action: action, reason: reason }
+        attrs[:items] = items if items
         response = Client.post_request("adjustments", body: attrs.merge(params))
         Adjustment.new(response.body["data"])
       end
 
       def credit_note(id:, disposition: "attachment")
-        response = Client.get_request("adjustments/#{id}/credit-note?disposition=#{disposition}")
-        if response.success?
-          response.body["data"]["url"]
-        end
+        response = Client.get_request("adjustments/#{id}/credit-note", params: { disposition: disposition })
+        response.body["data"]["url"]
       end
     end
   end

data/lib/paddle/models/customer.rb

@@ -22,9 +22,15 @@ module Paddle
         Customer.new(response.body["data"])
       end
 
+      def credit_balances(id:, **params)
+        response = Client.get_request("customers/#{id}/credit-balances", params: params)
+        Collection.from_response(response, type: CreditBalance)
+      end
+
+      # Returns only the first credit balance. Customers have a balance per currency,
+      # so use credit_balances to get all of them.
       def credit(id:)
-        response = Client.get_request("customers/#{id}/credit-balances")
-        CreditBalance.new(response.body["data"][0])
+        credit_balances(id: id).first
       end
 
       def auth_token(id:)

data/lib/paddle/models/explore_entity.rb

@@ -0,0 +1,4 @@
+module Paddle
+  class ExploreEntity < Object
+  end
+end

data/lib/paddle/models/explore_result.rb

@@ -0,0 +1,50 @@
+module Paddle
+  # The result of an Explore query. Pages are made up of series (one per combination of dimension
+  # values), and the next page is requested by POSTing the same query to the next URL
+  class ExploreResult < Object
+    def self.from_response(response, query:)
+      new(response.body["data"], query: query, pagination: response.body.dig("meta", "pagination"))
+    end
+
+    def initialize(attributes, query: {}, pagination: nil)
+      super(attributes)
+      @query = query
+      @pagination = pagination || {}
+    end
+
+    def per_page
+      @pagination["per_page"]
+    end
+
+    def total
+      @pagination["estimated_total"]
+    end
+
+    def next_url
+      @pagination["next"]
+    end
+
+    def has_more?
+      @pagination["has_more"] == true
+    end
+
+    def next_page
+      return unless has_more? && next_url
+
+      # Only the path and query are used, so requests always go to the configured API host
+      response = Client.post_request(URI(next_url).request_uri.delete_prefix("/"), body: @query)
+      ExploreResult.from_response(response, query: @query)
+    end
+
+    # Yields each series across all pages
+    def auto_paging_each(&block)
+      return enum_for(:auto_paging_each) unless block_given?
+
+      page = self
+      while page
+        page.series.each(&block)
+        page = page.next_page
+      end
+    end
+  end
+end

data/lib/paddle/models/metric.rb

@@ -0,0 +1,55 @@
+module Paddle
+  class Metric < Object
+    class << self
+      # from and to are dates, e.g. "2025-09-01" or a Date. Returns daily data with a timeseries
+      def monthly_recurring_revenue(from:, to:)
+        get("monthly-recurring-revenue", from: from, to: to)
+      end
+
+      def monthly_recurring_revenue_change(from:, to:)
+        get("monthly-recurring-revenue-change", from: from, to: to)
+      end
+
+      def active_subscribers(from:, to:)
+        get("active-subscribers", from: from, to: to)
+      end
+
+      def revenue(from:, to:)
+        get("revenue", from: from, to: to)
+      end
+
+      def refunds(from:, to:)
+        get("refunds", from: from, to: to)
+      end
+
+      def chargebacks(from:, to:)
+        get("chargebacks", from: from, to: to)
+      end
+
+      def checkout_conversion(from:, to:)
+        get("checkout-conversion", from: from, to: to)
+      end
+
+      # Lists the entities that can be queried with explore, with their dimensions and measures
+      def explore_entities(**params)
+        response = Client.get_request("metrics/explore/entities", params: params)
+        Collection.from_response(response, type: ExploreEntity)
+      end
+
+      # Runs an Explore query. from is inclusive and to is exclusive.
+      # measures is an array of hashes, e.g. [ { field: "gross_revenue", agg: "sum" } ]
+      def explore(entity:, from:, to:, measures:, **params)
+        query = { entity: entity, from: from, to: to, measures: measures }.merge(params)
+        response = Client.post_request("metrics/explore", body: query)
+        ExploreResult.from_response(response, query: query)
+      end
+
+      private
+
+      def get(metric, from:, to:)
+        response = Client.get_request("metrics/#{metric}", params: { from: from, to: to })
+        Metric.new(response.body["data"])
+      end
+    end
+  end
+end

data/lib/paddle/models/notification.rb

@@ -11,11 +11,12 @@ module Paddle
         Notification.new(response.body["data"])
       end
 
-      # Currently not working
-      # def replay(id)
-      #   response = Client.post_request("notifications/#{id}/replay", body: {})
-      #   Notification.new(response.body["data"])
-      # end
+      # Only delivered or failed notifications with an origin of "event" can be replayed.
+      # Returns a Notification with the notification_id of the new notification.
+      def replay(id:)
+        response = Client.post_request("notifications/#{id}/replay")
+        Notification.new(response.body["data"])
+      end
 
       def logs(id:, **params)
         response = Client.get_request("notifications/#{id}/logs", params: params)

data/lib/paddle/models/report.rb

@@ -19,9 +19,7 @@ module Paddle
 
       def csv(id:)
         response = Client.get_request("reports/#{id}/download-url")
-        if response.success?
-          response.body["data"]["url"]
-        end
+        response.body["data"]["url"]
       end
     end
   end

data/lib/paddle/models/simulation.rb

@@ -22,8 +22,8 @@ module Paddle
         Simulation.new(response.body["data"])
       end
 
-      def runs(id:)
-        response = Client.get_request("simulations/#{id}/runs")
+      def runs(id:, **params)
+        response = Client.get_request("simulations/#{id}/runs", params: params)
         Collection.from_response(response, type: SimulationRun)
       end
     end

data/lib/paddle/models/simulation_run.rb

@@ -11,8 +11,8 @@ module Paddle
         SimulationRun.new(response.body["data"])
       end
 
-      def events(simulation_id:, id:)
-        response = Client.get_request("simulations/#{simulation_id}/runs/#{id}/events")
+      def events(simulation_id:, id:, **params)
+        response = Client.get_request("simulations/#{simulation_id}/runs/#{id}/events", params: params)
         Collection.from_response(response, type: SimulationRunEvent)
       end
     end

data/lib/paddle/models/subscription.rb

@@ -12,6 +12,11 @@ module Paddle
         Subscription.new(response.body["data"])
       end
 
+      def history(id:, **params)
+        response = Client.get_request("subscriptions/#{id}/history", params: params)
+        Collection.from_response(response, type: SubscriptionHistory)
+      end
+
       def get_transaction(id:)
         response = Client.get_request("subscriptions/#{id}/update-payment-method-transaction")
         Transaction.new(response.body["data"])
@@ -33,6 +38,13 @@ module Paddle
         Subscription.new(response.body["data"])
       end
 
+      # Previews a one-time charge without billing it. Takes the same params as charge
+      def charge_preview(id:, items:, effective_from:, **params)
+        attrs = { items: items, effective_from: effective_from }
+        response = Client.post_request("subscriptions/#{id}/charge/preview", body: attrs.merge(params))
+        Subscription.new(response.body["data"])
+      end
+
       def pause(id:, **params)
         response = Client.post_request("subscriptions/#{id}/pause", body: params)
         Subscription.new(response.body["data"])

data/lib/paddle/models/subscription_history.rb

@@ -0,0 +1,4 @@
+module Paddle
+  class SubscriptionHistory < Object
+  end
+end

data/lib/paddle/models/transaction.rb

@@ -23,11 +23,16 @@ module Paddle
         Transaction.new(response.body["data"])
       end
 
+      # Revises customer, business and address details on a billed or completed transaction.
+      # A transaction can only be revised once
+      def revise(id:, **params)
+        response = Client.post_request("transactions/#{id}/revise", body: params)
+        Transaction.new(response.body["data"])
+      end
+
       def invoice(id:, disposition: "attachment")
-        response = Client.get_request("transactions/#{id}/invoice?disposition=#{disposition}")
-        if response.success?
-          response.body["data"]["url"]
-        end
+        response = Client.get_request("transactions/#{id}/invoice", params: { disposition: disposition })
+        response.body["data"]["url"]
       end
 
       def preview(items:, **params)

data/lib/paddle/object.rb

@@ -1,23 +1,66 @@
-require "ostruct"
-
 module Paddle
-  class Object < OpenStruct
-    def initialize(attributes)
-      super to_ostruct(attributes)
-    end
-
-    def to_ostruct(obj)
-      if obj.is_a?(Hash)
-        OpenStruct.new(obj.map { |key, val| [ key, to_ostruct(val) ] }.to_h)
-      elsif obj.is_a?(Array)
-        obj.map { |o| to_ostruct(o) }
-      else # Assumed to be a primitive value
-        obj
-      end
+  # A lightweight wrapper around API response data. Attributes can be read with dot notation
+  # (object.id) or like a hash (object[:id] or object["id"]). Nested hashes are wrapped too.
+  class Object
+    def initialize(attributes = {})
+      @attributes = {}
+      (attributes || {}).each { |key, val| self[key] = val }
+    end
+
+    def [](key)
+      @attributes[key.to_sym]
+    end
+
+    def []=(key, val)
+      @attributes[key.to_sym] = wrap(val)
+    end
+
+    def key?(key)
+      @attributes.key?(key.to_sym)
+    end
+
+    def dig(key, *rest)
+      val = self[key]
+      rest.empty? || val.nil? ? val : val.dig(*rest)
     end
 
+    def each_pair(&block)
+      return enum_for(:each_pair) unless block_given?
+
+      @attributes.each_pair(&block)
+      self
+    end
+
+    # Returns the attributes as a hash, with nested objects converted to hashes too
+    def to_h
+      @attributes.transform_values { |val| unwrap(val) }
+    end
+
+    def as_json(*)
+      to_h
+    end
+
+    def to_json(*args)
+      to_h.to_json(*args)
+    end
+
+    def ==(other)
+      other.is_a?(Paddle::Object) && to_h == other.to_h
+    end
+    alias eql? ==
+
+    def hash
+      to_h.hash
+    end
+
+    def inspect
+      attrs = @attributes.map { |key, val| "#{key}=#{val.inspect}" }.join(", ")
+      "#<#{self.class.name}#{" " unless attrs.empty?}#{attrs}>"
+    end
+    alias to_s inspect
+
     def update(**params)
-      method_missing :update unless klass.respond_to? :update
+      raise NoMethodError, "undefined method 'update' for #{klass}" unless klass.respond_to? :update
 
       primary_attributes = klass.method(:update).parameters.select { |(type, name)| type == :keyreq }.map(&:last) # Identified by whatever is a required named parameter.
 
@@ -36,5 +79,37 @@ module Paddle
     def klass
       self.class
     end
+
+    # Unknown attributes return nil, like a hash
+    def method_missing(name, *args)
+      if name.end_with?("=") && args.size == 1
+        self[name.to_s.chomp("=")] = args.first
+      elsif args.empty? && !name.end_with?("=", "?", "!")
+        self[name]
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      key?(name.to_s.chomp("=")) || super
+    end
+
+    def wrap(val)
+      case val
+      when Paddle::Object then val
+      when Hash then Paddle::Object.new(val)
+      when Array then val.map { |v| wrap(v) }
+      else val
+      end
+    end
+
+    def unwrap(val)
+      case val
+      when Paddle::Object then val.to_h
+      when Array then val.map { |v| unwrap(v) }
+      else val
+      end
+    end
   end
 end

data/lib/paddle/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Paddle
-  VERSION = "2.10"
+  VERSION = "3.0"
 end