paddle 2.2.1 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6224fc2a3ec9423990985241a118780185a090617407f95e97bb542120eb9323
-  data.tar.gz: 03403341d8dce73c881ed3fc2c722cf738b625803c6352dd2cca15e5d4cd65a7
+  metadata.gz: 8f5aba3cef837ddde090eb1759279427dcf213115c5950b18c167cbea59f4de3
+  data.tar.gz: 8bd53cd25b7d29113a5f5e942bac4457afd976cca2995ba232ce888051dc5367
 SHA512:
-  metadata.gz: 6453da01350a80adf7f8723817b7d45edfac636d5ae72ebeb92b281ad93d85d59866631eb60a17c3a8225f5a8f51780b857e1aeab940c0264daaa53446a70637
-  data.tar.gz: 716ef3061039df26a5cfc0dd0f8931cb1e9edcf964947047acf37ed8b95cc63a3cc36595288f6aaccc45ee2b1e3f8fe0b74ae39969123f2c99eeeeea9da41381
+  metadata.gz: e844d8f2c15d7c7d0ad0de2d6dadc566fee298b5a1e1930529b709f9532cf673efc7258e02fe9b636338ed9e7730f90a1a293e71faa7d71293e1c1996c479ac5
+  data.tar.gz: 895d3532f3a0ddf935427e186d5a06e28fd7e5af610594d88540b009887023683c0ae0ad4cf06bacbef7c7c7ab9f09e29d3931e65f898b779ccd0ee888623a1c

data/.rubocop.yml

@@ -6,3 +6,6 @@ inherit_gem: { rubocop-rails-omakase: rubocop.yml }
 # # Use `[a, [b, c]]` not `[ a, [ b, c ] ]`
 # Layout/SpaceInsideArrayLiteralBrackets:
 #   Enabled: false
+
+Rails/RefuteMethods:
+  Enabled: false

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    paddle (2.2.1)
+    paddle (2.4.0)
       faraday (~> 2.0)
 
 GEM
@@ -40,9 +40,9 @@ GEM
       ast (~> 2.4.1)
       racc
     racc (1.8.0)
-    rack (3.1.3)
+    rack (3.1.7)
     rainbow (3.1.1)
-    rake (13.0.6)
+    rake (13.2.1)
     regexp_parser (2.9.2)
     rexml (3.3.0)
       strscan

data/README.md

@@ -7,7 +7,7 @@ The easiest and most complete Ruby library for the Paddle APIs, both Classic and
 Add this line to your application's Gemfile:
 
 ```ruby
-gem "paddle", "~> 2.2"
+gem "paddle", "~> 2.3"
 ```
 
 ## Billing API
@@ -77,6 +77,14 @@ Paddle::Product.list(per_page: 10, after: "abc123")
 >
 > The Paddle API doesn't take `nil` values for optional parameters. If you want to remove a value, you'll need to pass `"null"` instead.
 
+### Updating records
+
+For API endpoints that support it, you can use the `update` method to update a record, like so:
+
+```ruby
+Paddle::Product.retrieve(id: "pro_abc123").update(name: "My New Name")
+```
+
 ### Products
 
 ```ruby
@@ -93,10 +101,12 @@ Paddle::Product.create(name: "My SAAS Plan", tax_category: "saas")
 Paddle::Product.create(name: "My Standard Product", tax_category: "standard")
 
 # Retrieve a product
-Paddle::Product.retrieve(id: "pro_abc123")
+product = Paddle::Product.retrieve(id: "pro_abc123")
 
 # Update a product
 # https://developer.paddle.com/api-reference/products/update-product
+product.update(description: "This is a plan")
+# or
 Paddle::Product.update(id: "pro_abc123", description: "This is a plan")
 ```
 
@@ -116,10 +126,12 @@ Paddle::Price.list(product_id: "pro_abc123")
 Paddle::Price.create(product_id: "pro_abc123", description: "A one off price", amount: "1000", currency: "GBP")
 
 # Retrieve a price
-Paddle::Price.retrieve(id: "pri_123abc")
+price = Paddle::Price.retrieve(id: "pri_123abc")
 
 # Update a price
 # https://developer.paddle.com/api-reference/prices/update-price
+price.update(description: "An updated description")
+# or
 Paddle::Price.update(id: "pri_123abc", description: "An updated description")
 ```
 
@@ -149,10 +161,12 @@ Paddle::Discount.create(description: "$5 off", type: "flat", amount: "500", curr
 Paddle::Discount.create(description: "10% Off", type: "percentage", amount: "10", code: "10OFF")
 
 # Retrieve a discount
-Paddle::Discount.retrieve(id: "dsc_abc123")
+discount = Paddle::Discount.retrieve(id: "dsc_abc123")
 
 # Update a discount
 # https://developer.paddle.com/api-reference/discounts/update-discount
+discount.update(description: "An updated description")
+# or
 Paddle::Discount.update(id: "dsc_abc123", description: "An updated description")
 ```
 
@@ -167,13 +181,16 @@ Paddle::Customer.list(email: "me@mydomain.com")
 
 # Create a customer
 # https://developer.paddle.com/api-reference/customers/create-customer
+# Returns a Paddle::Errors::ConflictError if the email is already used on Paddle
 Paddle::Customer.create(email: "myemail@mydomain.com", name: "Customer Name")
 
 # Retrieve a customer
-Paddle::Customer.retrieve(id: "ctm_abc123")
+customer = Paddle::Customer.retrieve(id: "ctm_abc123")
 
 # Update a customer
 # https://developer.paddle.com/api-reference/customers/update-customer
+customer.update(status: "archived")
+# or
 Paddle::Customer.update(id: "ctm_abc123", status: "archived")
 
 # Retrieve credit balance for a customer
@@ -193,10 +210,12 @@ Paddle::Address.list(customer: "ctm_abc123")
 Paddle::Address.create(customer: "ctm_abc123", country_code: "GB", postal_code: "SW1A 2AA")
 
 # Retrieve an address
-Paddle::Address.retrieve(customer: "ctm_abc123", id: "add_abc123")
+address = Paddle::Address.retrieve(customer: "ctm_abc123", id: "add_abc123")
 
 # Update an address
 # https://developer.paddle.com/api-reference/addresses/update-address
+address.update(status: "archived")
+# or
 Paddle::Address.update(customer: "ctm_abc123", id: "add_abc123", status: "archived")
 ```
 
@@ -212,10 +231,12 @@ Paddle::Business.list(customer: "ctm_abc123")
 Paddle::Business.create(customer: "ctm_abc123", name: "My Ltd Company")
 
 # Retrieve a business
-Paddle::Business.retrieve(customer: "ctm_abc123", id: "biz_abc123")
+business = Paddle::Business.retrieve(customer: "ctm_abc123", id: "biz_abc123")
 
 # Update a business
 # https://developer.paddle.com/api-reference/businesses/update-business
+business.update(status: "archived")
+# or
 Paddle::Business.update(customer: "ctm_abc123", id: "biz_abc123", status: "archived")
 ```
 
@@ -237,10 +258,12 @@ Paddle::Transaction.retrieve(id: "txn_abc123")
 
 # Retrieve a transaction with extra information
 # extra can be either "address", "adjustment", "adjustments_totals", "business", "customer", "discount"
-Paddle::Transaction.retrieve(id: "txn_abc123", extra: "customer")
+transaction = Paddle::Transaction.retrieve(id: "txn_abc123", extra: "customer")
 
 # Update a transaction
 # https://developer.paddle.com/api-reference/transaction/update-transaction
+transaction.update(items: [ { price_id: "pri_abc123", quantity: 2 } ])
+# or
 Paddle::Transaction.update(id: "txn_abc123", items: [ { price_id: "pri_abc123", quantity: 2 } ])
 
 # Preview a transaction
@@ -271,7 +294,7 @@ Paddle::Subscription.retrieve(id: "sub_abc123")
 
 # Retrieve a subscription with extra information
 # extra can be either "next_transaction" or "recurring_transaction_details"
-Paddle::Subscription.retrieve(id: "sub_abc123", extra: "next_transaction")
+subscription = Paddle::Subscription.retrieve(id: "sub_abc123", extra: "next_transaction")
 
 # Preview an update to a subscription
 # https://developer.paddle.com/api-reference/subscriptions/preview-subscription
@@ -279,6 +302,8 @@ Paddle::Subscription.preview(id: "sub_abc123", items: [ { price_id: "pri_123abc"
 
 # Update a subscription
 # https://developer.paddle.com/api-reference/subscriptions/update-subscription
+subscription.update(billing_details: {purchase_order_number: "PO-1234"})
+# or
 Paddle::Subscription.update(id: "sub_abc123", billing_details: {purchase_order_number: "PO-1234"})
 
 # Get a transaction to update payment method
@@ -358,7 +383,7 @@ Used for creating webhook and email notifications
 Paddle::NotificationSetting.list
 
 # Retrieve a notification setting
-Paddle::NotificationSetting.retrieve(id: "ntfset_abc123")
+setting = Paddle::NotificationSetting.retrieve(id: "ntfset_abc123")
 
 # Create a notification setting
 # https://developer.paddle.com/api-reference/notification-settings/create-notification-setting
@@ -374,6 +399,8 @@ Paddle::NotificationSetting.create(
 
 # Update a notification setting
 # https://developer.paddle.com/api-reference/notification-settings/update-notification-setting
+setting.update(subscribed_events: %w[subscription.activated transaction.completed transaction.billed])
+# or
 Paddle::NotificationSetting.update(id: "ntfset_abc123",
   subscribed_events: [
     "subscription.activated",

data/lib/paddle/classic/error.rb

@@ -0,0 +1,6 @@
+module Paddle
+  module Classic
+    class Error < StandardError
+    end
+  end
+end

data/lib/paddle/client.rb

@@ -1,66 +1,61 @@
+require "faraday"
+
 module Paddle
   class Client
     class << self
       def connection
-        @connection ||= Faraday.new(Paddle.config.url) do |conn|
-          conn.request :authorization, :Bearer, Paddle.config.api_key
-
-          conn.headers = {
-            "User-Agent" => "paddle/v#{VERSION} (github.com/deanpcmad/paddle)",
-            "Paddle-Version" => Paddle.config.version.to_s
-          }
-
-          conn.request :json
-          conn.response :json
-        end
+        @connection ||= create_connection
       end
 
-
       def get_request(url, params: {}, headers: {})
-        handle_response connection.get(url, params, headers)
+        handle_response(connection.get(url, params, headers))
       end
 
       def post_request(url, body: {}, headers: {})
-        handle_response connection.post(url, body, headers)
+        handle_response(connection.post(url, body, headers))
       end
 
       def patch_request(url, body:, headers: {})
-        handle_response connection.patch(url, body, headers)
+        handle_response(connection.patch(url, body, headers))
       end
 
       def delete_request(url, headers: {})
-        handle_response connection.delete(url, headers)
+        handle_response(connection.delete(url, headers))
       end
 
-      def handle_response(response)
-        case response.status
-        when 400
-          raise Error, "Error 400: Your request was malformed. '#{response.body["error"]["code"]}'"
-        when 401
-          raise Error, "Error 401: You did not supply valid authentication credentials. '#{response.body["error"]}'"
-        when 403
-          raise Error, "Error 403: You are not allowed to perform that action. '#{response.body["error"]["code"]}'"
-        when 404
-          raise Error, "Error 404: No results were found for your request. '#{response.body["error"]["code"]}'"
-        when 409
-          raise Error, "Error 409: Your request was a conflict. '#{response.body["error"]["code"]}'"
-        when 429
-          raise Error, "Error 429: Your request exceeded the API rate limit. '#{response.body["error"]["code"]}'"
-        when 500
-          raise Error, "Error 500: We were unable to perform the request due to server-side problems. '#{response.body["error"]["code"]}'"
-        when 503
-          raise Error, "Error 503: You have been rate limited for sending more than 20 requests per second. '#{response.body["error"]["code"]}'"
-        when 501
-          raise Error, "Error 501: This resource has not been implemented. '#{response.body["error"]["code"]}'"
-        when 204
-          return true
-        end
+      private
 
-        if response.body && response.body["error"]
-          raise Error, "Error #{response.body["error"]["code"]} - #{response.body["errors"]["message"]}"
+      def create_connection
+        Faraday.new(Paddle.config.url) do |conn|
+          conn.request :authorization, :Bearer, Paddle.config.api_key
+          conn.headers = default_headers
+          conn.request :json
+          conn.response :json
         end
+      end
+
+      def default_headers
+        {
+          "User-Agent" => "paddle/v#{VERSION} (github.com/deanpcmad/paddle)",
+          "Paddle-Version" => Paddle.config.version.to_s
+        }
+      end
+
+      def handle_response(response)
+        return true if response.status == 204
+        return response unless error?(response)
+
+        raise_error(response)
+      end
+
+      def error?(response)
+        [ 400, 401, 403, 404, 409, 429, 500, 501, 503 ].include?(response.status) ||
+          response.body&.key?("error")
+      end
 
-        response
+      def raise_error(response)
+        error = Paddle::ErrorFactory.create(response.body, response.status)
+        raise error if error
       end
     end
   end

data/lib/paddle/error_generator.rb

@@ -0,0 +1,128 @@
+module Paddle
+  class ErrorGenerator < StandardError
+    attr_reader :http_status_code
+    attr_reader :paddle_error_code
+    attr_reader :paddle_error_message
+
+    def initialize(response_body, http_status_code)
+      @response_body = response_body
+      @http_status_code = http_status_code
+      set_paddle_error_values
+      super(build_message)
+    end
+
+    private
+
+    def set_paddle_error_values
+      @paddle_error_code = @response_body.dig("error", "code")
+      @paddle_error_message = @response_body.dig("error", "detail")
+    end
+
+    def error_message
+      @paddle_error_message || @response_body.dig("error", "code")
+    rescue NoMethodError
+      "An unknown error occurred."
+    end
+
+    def build_message
+      if paddle_error_code.nil?
+        return "Error #{@http_status_code}: #{error_message}"
+      end
+      "Error #{@http_status_code}: #{error_message} '#{paddle_error_code}'"
+    end
+  end
+
+  module Errors
+    class BadRequestError < ErrorGenerator
+      private
+
+      def error_message
+        "Your request was malformed."
+      end
+    end
+
+    class AuthenticationMissingError < ErrorGenerator
+      private
+
+      def error_message
+        "You did not supply valid authentication credentials."
+      end
+    end
+
+    class ForbiddenError < ErrorGenerator
+      private
+
+      def error_message
+        "You are not allowed to perform that action."
+      end
+    end
+
+    class EntityNotFoundError < ErrorGenerator
+      private
+
+      def error_message
+        "No results were found for your request."
+      end
+    end
+
+    class ConflictError < ErrorGenerator
+      private
+
+      def error_message
+        "Your request was a conflict."
+      end
+    end
+
+    class TooManyRequestsError < ErrorGenerator
+      private
+
+      def error_message
+        "Your request exceeded the API rate limit."
+      end
+    end
+
+    class InternalError < ErrorGenerator
+      private
+
+      def error_message
+        "We were unable to perform the request due to server-side problems."
+      end
+    end
+
+    class ServiceUnavailableError < ErrorGenerator
+      private
+
+      def error_message
+        "You have been rate limited for sending more than 20 requests per second."
+      end
+    end
+
+    class NotImplementedError < ErrorGenerator
+      private
+
+      def error_message
+        "This resource has not been implemented."
+      end
+    end
+  end
+
+  class ErrorFactory
+    HTTP_ERROR_MAP = {
+      400 => Errors::BadRequestError,
+      401 => Errors::AuthenticationMissingError,
+      403 => Errors::ForbiddenError,
+      404 => Errors::EntityNotFoundError,
+      409 => Errors::ConflictError,
+      429 => Errors::TooManyRequestsError,
+      500 => Errors::InternalError,
+      503 => Errors::ServiceUnavailableError,
+      501 => Errors::NotImplementedError
+    }.freeze
+
+    def self.create(response_body, http_status_code)
+      status = http_status_code
+      error_class = HTTP_ERROR_MAP[status] || ErrorGenerator
+      error_class.new(response_body, http_status_code) if error_class
+    end
+  end
+end

data/lib/paddle/object.rb

@@ -15,5 +15,26 @@ module Paddle
         obj
       end
     end
+
+    def update(**params)
+      method_missing :update 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.
+
+      primary_attributes.each do |attrib|
+        # ? Should we need to handle blank strings here?
+        params[attrib] = self[attrib] || self["#{attrib}_id"] # Handling for customer (customer_id) and id.
+      end
+
+      klass.public_send(:update, **params).each_pair { |key, val| self[key] = val } # Updating self
+
+      self
+    end
+
+    private
+
+    def klass
+      self.class
+    end
   end
 end

data/lib/paddle/version.rb

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

data/lib/paddle.rb

@@ -9,6 +9,9 @@ module Paddle
   autoload :Client, "paddle/client"
   autoload :Collection, "paddle/collection"
   autoload :Error, "paddle/error"
+  autoload :ErrorGenerator, "paddle/error_generator"
+  autoload :ErrorFactory, "paddle/error_generator"
+
   autoload :Object, "paddle/object"
 
   class << self
@@ -48,6 +51,7 @@ module Paddle
     autoload :Client, "paddle/classic/client"
     autoload :Collection, "paddle/classic/collection"
     autoload :Resource, "paddle/classic/resource"
+    autoload :Error, "paddle/classic/error"
 
     autoload :PlansResource, "paddle/classic/resources/plans"
     autoload :CouponsResource, "paddle/classic/resources/coupons"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: paddle
 version: !ruby/object:Gem::Version
-  version: 2.2.1
+  version: 2.4.0
 platform: ruby
 authors:
 - Dean Perry
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-06-28 00:00:00.000000000 Z
+date: 2024-08-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -42,6 +42,7 @@ files:
 - lib/paddle.rb
 - lib/paddle/classic/client.rb
 - lib/paddle/classic/collection.rb
+- lib/paddle/classic/error.rb
 - lib/paddle/classic/objects/charge.rb
 - lib/paddle/classic/objects/coupon.rb
 - lib/paddle/classic/objects/license.rb
@@ -70,6 +71,7 @@ files:
 - lib/paddle/collection.rb
 - lib/paddle/configuration.rb
 - lib/paddle/error.rb
+- lib/paddle/error_generator.rb
 - lib/paddle/models/address.rb
 - lib/paddle/models/adjustment.rb
 - lib/paddle/models/business.rb
@@ -110,7 +112,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.9
+rubygems_version: 3.5.11
 signing_key:
 specification_version: 4
 summary: Ruby library for the Paddle Billing & Classic APIs