paddle 2.7.1 → 2.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d34df63b33ad8a971eabe70779c7ff47f025a8ab2ef5d96dcea24838c6835419
-  data.tar.gz: fc46cb72067fc2c22a9c8c011d3dc341329e36edaf089b80fce2e048ccba47d6
+  metadata.gz: cc578ecefeacc14fa58ae9fc433429c3180d5c5bc6015493bc66afc50172cccd
+  data.tar.gz: 03d85b6ee1f8fedb0c5b56028dfb741d32155471bfda087b7cf61bd2872f60ef
 SHA512:
-  metadata.gz: c02dfdef5f72c98767c66bbf841981a31edbc762febc19aa691230a19961d80565dfd40a61ef6b7e26c8d124f1a38c33bc48f94de789ae00b188eff10ea301fa
-  data.tar.gz: a045b9fb22b89645c8b3d3fb6ed4eb7bf3e33d6547b719d521ee977aef9de12bce773ac679c683f6b20a8f0320fb0e71c87f049992210774fca3b59aa85e0d04
+  metadata.gz: 4ecdcde91d5d11a03c7f5e1506f923b3cfd738bbc70113436891768e2cdbdc194694a67e9e452256b6d8be5918b0eed315ce27ab9e5a7a5920312023f3ed3acc
+  data.tar.gz: 851daa7f4a126c94891cf136b80761f7a98745cd3a21455cadb8af1e7f782f3972a8e0123585320052d6335bd25598706e212e1224aaabd93c18c100f195c16b

data/Gemfile.lock

@@ -1,89 +1,97 @@
 PATH
   remote: .
   specs:
-    paddle (2.7.1)
+    paddle (2.9)
+      cgi
       faraday (~> 2.11)
       ostruct (~> 0.6.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (7.2.1)
+    activesupport (8.1.1)
       base64
       bigdecimal
       concurrent-ruby (~> 1.0, >= 1.3.1)
       connection_pool (>= 2.2.5)
       drb
       i18n (>= 1.6, < 2)
+      json
       logger (>= 1.4.2)
       minitest (>= 5.1)
       securerandom (>= 0.3)
       tzinfo (~> 2.0, >= 2.0.5)
-    ast (2.4.2)
-    base64 (0.2.0)
-    bigdecimal (3.1.8)
-    concurrent-ruby (1.3.4)
-    connection_pool (2.4.1)
-    dotenv (3.1.2)
-    drb (2.2.1)
-    faraday (2.12.2)
+      uri (>= 0.13.1)
+    ast (2.4.3)
+    base64 (0.3.0)
+    bigdecimal (3.3.1)
+    cgi (0.5.1)
+    concurrent-ruby (1.3.5)
+    connection_pool (3.0.2)
+    dotenv (3.2.0)
+    drb (2.2.3)
+    faraday (2.14.0)
       faraday-net_http (>= 2.0, < 3.5)
       json
       logger
-    faraday-net_http (3.4.0)
-      net-http (>= 0.5.0)
-    i18n (1.14.5)
+    faraday-net_http (3.4.2)
+      net-http (~> 0.5)
+    i18n (1.14.7)
       concurrent-ruby (~> 1.0)
-    json (2.7.2)
-    language_server-protocol (3.17.0.3)
-    logger (1.6.4)
-    minitest (5.25.1)
-    net-http (0.6.0)
-      uri
-    ostruct (0.6.0)
-    parallel (1.26.3)
-    parser (3.3.5.0)
+    json (2.18.0)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    logger (1.7.0)
+    minitest (5.27.0)
+    net-http (0.8.0)
+      uri (>= 0.11.1)
+    ostruct (0.6.3)
+    parallel (1.27.0)
+    parser (3.3.10.0)
       ast (~> 2.4.1)
       racc
+    prism (1.6.0)
     racc (1.8.1)
-    rack (3.1.7)
+    rack (3.2.4)
     rainbow (3.1.1)
-    rake (13.2.1)
-    regexp_parser (2.9.2)
-    rubocop (1.66.1)
+    rake (13.3.1)
+    regexp_parser (2.11.3)
+    rubocop (1.82.1)
       json (~> 2.3)
-      language_server-protocol (>= 3.17.0)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
       parallel (~> 1.10)
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
-      regexp_parser (>= 2.4, < 3.0)
-      rubocop-ast (>= 1.32.2, < 2.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.48.0, < 2.0)
       ruby-progressbar (~> 1.7)
-      unicode-display_width (>= 2.4.0, < 3.0)
-    rubocop-ast (1.32.3)
-      parser (>= 3.3.1.0)
-    rubocop-minitest (0.36.0)
-      rubocop (>= 1.61, < 2.0)
-      rubocop-ast (>= 1.31.1, < 2.0)
-    rubocop-performance (1.21.1)
-      rubocop (>= 1.48.1, < 2.0)
-      rubocop-ast (>= 1.31.1, < 2.0)
-    rubocop-rails (2.26.0)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.48.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.4)
+    rubocop-performance (1.26.1)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.75.0, < 2.0)
+      rubocop-ast (>= 1.47.1, < 2.0)
+    rubocop-rails (2.34.2)
       activesupport (>= 4.2.0)
+      lint_roller (~> 1.1)
       rack (>= 1.1)
-      rubocop (>= 1.52.0, < 2.0)
-      rubocop-ast (>= 1.31.1, < 2.0)
-    rubocop-rails-omakase (1.0.0)
-      rubocop
-      rubocop-minitest
-      rubocop-performance
-      rubocop-rails
+      rubocop (>= 1.75.0, < 2.0)
+      rubocop-ast (>= 1.44.0, < 2.0)
+    rubocop-rails-omakase (1.1.0)
+      rubocop (>= 1.72)
+      rubocop-performance (>= 1.24)
+      rubocop-rails (>= 2.30)
     ruby-progressbar (1.13.0)
-    securerandom (0.3.1)
+    securerandom (0.4.1)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
-    unicode-display_width (2.5.0)
-    uri (1.0.2)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+    uri (1.1.1)
     vcr (6.3.1)
       base64
 
@@ -99,4 +107,4 @@ DEPENDENCIES
   vcr
 
 BUNDLED WITH
-   2.5.9
+  4.0.3

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.6"
+gem "paddle", "~> 2.8"
 ```
 
 ## Billing API
@@ -77,6 +77,57 @@ 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.
 
+### Error Handling
+
+When API requests fail, the gem provides detailed error information to help you debug issues. Errors are raised as exceptions with comprehensive details including field-level validation errors.
+
+#### Error Structure
+
+All errors inherit from `Paddle::ErrorGenerator` and include:
+- HTTP status code
+- Error code from Paddle
+- Detailed error message
+- Field-specific validation errors (when applicable)
+- Documentation URL for more information
+- Request ID for support
+
+#### Available Error Classes
+
+- `Paddle::Errors::BadRequestError` (400) - Invalid request parameters
+- `Paddle::Errors::AuthenticationMissingError` (401) - Missing or invalid API credentials
+- `Paddle::Errors::ForbiddenError` (403) - Insufficient permissions
+- `Paddle::Errors::EntityNotFoundError` (404) - Resource not found
+- `Paddle::Errors::ConflictError` (409) - Request conflicts with existing data
+- `Paddle::Errors::TooManyRequestsError` (429) - Rate limit exceeded
+- `Paddle::Errors::InternalError` (500) - Server error
+- `Paddle::Errors::ServiceUnavailableError` (503) - Service unavailable
+
+#### Error Example
+
+When creating a Price with invalid parameters, you'll receive a detailed error:
+
+```ruby
+begin
+  Paddle::Price.create(product_id: "pro_123", trial_period: { frequency: "monthly" })
+rescue Paddle::Errors::BadRequestError => e
+  puts e.message
+  # => Error 400: Invalid request. 'bad_request'
+  #    Field errors:
+  #      - trial_period.frequency: Invalid type. Expected: integer, given: string
+  #      - trial_period: Must validate one and only one schema (oneOf)
+  #    Documentation: https://developer.paddle.com/v1/errors/shared/bad_request
+  #    Request ID: e385967f-4298-4240-a971-f988209b32ca
+
+  # Access error details programmatically
+  e.http_status_code      #=> 400
+  e.paddle_error_code     #=> "bad_request"
+  e.paddle_error_message  #=> "Invalid request."
+  e.paddle_errors         #=> [{"field"=>"trial_period.frequency", "message"=>"Invalid type. Expected: integer, given: string"}, ...]
+  e.documentation_url     #=> "https://developer.paddle.com/v1/errors/shared/bad_request"
+  e.request_id            #=> "e385967f-4298-4240-a971-f988209b32ca"
+end
+```
+
 ### Updating records
 
 For API endpoints that support it, you can use the `update` method to update a record, like so:
@@ -170,6 +221,37 @@ discount.update(description: "An updated description")
 Paddle::Discount.update(id: "dsc_abc123", description: "An updated description")
 ```
 
+### Discount Groups
+
+```ruby
+# List all discount groups
+# https://developer.paddle.com/api-reference/discount-groups/list-discount-groups
+Paddle::DiscountGroup.list
+Paddle::DiscountGroup.list(status: "active")
+
+# Create a discount group
+# https://developer.paddle.com/api-reference/discount-groups/create-discount-group
+Paddle::DiscountGroup.create(name: "Black Friday Promotion")
+
+# Retrieve a discount group
+# https://developer.paddle.com/api-reference/discount-groups/get-discount-group
+discount_group = Paddle::DiscountGroup.retrieve(id: "dsg_abc123")
+
+# Update a discount group
+# https://developer.paddle.com/api-reference/discount-groups/update-discount-group
+discount_group.update(name: "Updated name")
+# or
+Paddle::DiscountGroup.update(id: "dsg_abc123", name: "Updated name")
+
+# Create a discount in a discount group
+discount_group.create_discount(description: "$10 off", type: "flat", amount: "1000", currency_code: "USD")
+# or
+Paddle::Discount.create(discount_group_id: discount_group.id, description: "$10 off", type: "flat", amount: "1000", currency_code: "USD")
+
+# List discounts in a discount group
+discounts = discount_group.discounts
+```
+
 ### Customers
 
 ```ruby
@@ -196,6 +278,11 @@ Paddle::Customer.update(id: "ctm_abc123", status: "archived")
 # Retrieve credit balance for a customer
 # https://developer.paddle.com/api-reference/customers/list-credit-balances
 Paddle::Customer.credit(id: "ctm_abc123")
+
+# Generate an authentication token for a customer
+# https://developer.paddle.com/api-reference/customers/generate-customer-authentication-token
+Paddle::Customer.auth_token id: "ctm_abc123"
+#=> #<Paddle::CustomerAuthToken customer_auth_token="pca_abc123", expires_at="2025-12-10T16:21:21.554Z">
 ```
 
 ### Addresses
@@ -376,6 +463,22 @@ Paddle::Adjustment.create(
 Paddle::Adjustment.credit_note(id: "adj_abc123", disposition: "inline")
 ```
 
+### Payment Methods
+
+```ruby
+# List all payment methods for a customer
+# https://developer.paddle.com/api-reference/payment-methods/list-payment-methods
+Paddle::PaymentMethod.list customer: "ctm_abc123"
+
+# Retrieve a single payment method for a customer
+# https://developer.paddle.com/api-reference/payment-methods/get-payment-method
+Paddle::PaymentMethod.retrieve customer: "ctm_abc123", id: "paymtd_abc123"
+
+# Delete a payment method for a customer
+# https://developer.paddle.com/api-reference/payment-methods/delete-payment-method
+Paddle::PaymentMethod.delete customer: "ctm_abc123", id: "paymtd_abc123"
+```
+
 ### Event Types
 
 ```ruby
@@ -524,6 +627,27 @@ Paddle::SimulationRun.events(simulation_id: "ntfsim_abc123", run_id: "ntfsimrun_
 Paddle::SimulationRunEvent.replay(simulation_id: "ntfsim_abc123", run_id: "ntfsimrun_abc123", id: "ntfsimevt_abc123")
 ```
 
+### Client Tokens
+
+```ruby
+# List all Client Tokens
+# https://developer.paddle.com/api-reference/client-tokens/list-client-tokens
+Paddle::ClientToken.list
+
+# Create a Client Token
+# https://developer.paddle.com/api-reference/client-tokens/create-client-token
+Paddle::ClientToken.create name: "My Token"
+
+# Get a Client Token
+# https://developer.paddle.com/api-reference/client-tokens/get-client-token
+Paddle::ClientToken.retrieve id: "ctkn_abc123"
+
+# Update a Client Token
+# https://developer.paddle.com/api-reference/client-tokens/update-client-token
+Paddle::ClientToken.update id: "ctkn_abc123", status: "revoked"
+```
+
+
 ## Classic API
 
 For accessing the Paddle Classic API

data/lib/paddle/collection.rb

@@ -1,5 +1,7 @@
 module Paddle
   class Collection
+    include Enumerable
+
     attr_reader :data, :total
 
     def self.from_response(response, type:)

data/lib/paddle/error_generator.rb

@@ -3,6 +3,9 @@ module Paddle
     attr_reader :http_status_code
     attr_reader :paddle_error_code
     attr_reader :paddle_error_message
+    attr_reader :paddle_errors
+    attr_reader :documentation_url
+    attr_reader :request_id
 
     def initialize(response_body, http_status_code)
       @response_body = response_body
@@ -16,6 +19,9 @@ module Paddle
     def set_paddle_error_values
       @paddle_error_code = @response_body.dig("error", "code")
       @paddle_error_message = @response_body.dig("error", "detail")
+      @paddle_errors = @response_body.dig("error", "errors") || []
+      @documentation_url = @response_body.dig("error", "documentation_url")
+      @request_id = @response_body.dig("meta", "request_id")
     end
 
     def error_message
@@ -25,10 +31,31 @@ module Paddle
     end
 
     def build_message
-      if paddle_error_code.nil?
-        return "Error #{@http_status_code}: #{error_message}"
+      base_message = if paddle_error_code.nil?
+        "Error #{@http_status_code}: #{error_message}"
+      else
+        "Error #{@http_status_code}: #{error_message} '#{paddle_error_code}'"
       end
-      "Error #{@http_status_code}: #{error_message} '#{paddle_error_code}'"
+
+      # Add detailed field errors if present
+      if @paddle_errors && !@paddle_errors.empty?
+        field_errors = @paddle_errors.map do |err|
+          "  - #{err['field']}: #{err['message']}"
+        end.join("\n")
+        base_message += "\nField errors:\n#{field_errors}"
+      end
+
+      # Add documentation URL if present
+      if @documentation_url
+        base_message += "\nDocumentation: #{@documentation_url}"
+      end
+
+      # Add request ID if present (useful for support)
+      if @request_id
+        base_message += "\nRequest ID: #{@request_id}"
+      end
+
+      base_message
     end
   end
 
@@ -37,7 +64,8 @@ module Paddle
       private
 
       def error_message
-        "Your request was malformed."
+        # Use the detailed Paddle error message if available, otherwise fall back to generic message
+        @paddle_error_message || "Your request was malformed."
       end
     end
 

data/lib/paddle/models/client_token.rb

@@ -0,0 +1,26 @@
+module Paddle
+  class ClientToken < Object
+    class << self
+      def list(**params)
+        response = Client.get_request("client-tokens", params: params)
+        Collection.from_response(response, type: ClientToken)
+      end
+
+      def create(name:, **params)
+        attrs = { name: name }
+        response = Client.post_request("client-tokens", body: attrs.merge(params))
+        ClientToken.new(response.body["data"])
+      end
+
+      def retrieve(id:)
+        response = Client.get_request("client-tokens/#{id}")
+        ClientToken.new(response.body["data"])
+      end
+
+      def update(id:, **params)
+        response = Client.patch_request("client-tokens/#{id}", body: params)
+        ClientToken.new(response.body["data"])
+      end
+    end
+  end
+end

data/lib/paddle/models/customer.rb

@@ -26,6 +26,11 @@ module Paddle
         response = Client.get_request("customers/#{id}/credit-balances")
         CreditBalance.new(response.body["data"][0])
       end
+
+      def auth_token(id:)
+        response = Client.post_request("customers/#{id}/auth-token", body: "")
+        CustomerAuthToken.new(response.body["data"])
+      end
     end
   end
 end

data/lib/paddle/models/customer_auth_token.rb

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

data/lib/paddle/models/discount_group.rb

@@ -0,0 +1,34 @@
+module Paddle
+  class DiscountGroup < Object
+    class << self
+      def list(**params)
+        response = Client.get_request("discount-groups", params: params)
+        Collection.from_response(response, type: DiscountGroup)
+      end
+
+      def create(name:, **params)
+        attrs = { name: name }
+        response = Client.post_request("discount-groups", body: attrs.merge(params))
+        DiscountGroup.new(response.body["data"])
+      end
+
+      def retrieve(id:)
+        response = Client.get_request("discount-groups/#{id}")
+        DiscountGroup.new(response.body["data"])
+      end
+
+      def update(id:, **params)
+        response = Client.patch_request("discount-groups/#{id}", body: params)
+        DiscountGroup.new(response.body["data"])
+      end
+    end
+
+    def create_discount(**params)
+      Discount.create(discount_group_id: id, **params)
+    end
+
+    def discounts(**params)
+      Discount.list(discount_group_id: id, **params)
+    end
+  end
+end

data/lib/paddle/models/payment_method.rb

@@ -0,0 +1,19 @@
+module Paddle
+  class PaymentMethod < Object
+    class << self
+      def list(customer:, **params)
+        response = Client.get_request("customers/#{customer}/payment-methods", params: params)
+        Collection.from_response(response, type: PaymentMethod)
+      end
+
+      def retrieve(customer:, id:)
+        response = Client.get_request("customers/#{customer}/payment-methods/#{id}")
+        PaymentMethod.new(response.body["data"])
+      end
+
+      def delete(customer:, id:)
+        Client.delete_request("customers/#{customer}/payment-methods/#{id}")
+      end
+    end
+  end
+end

data/lib/paddle/version.rb

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

data/lib/paddle.rb

@@ -32,6 +32,7 @@ module Paddle
   autoload :Price, "paddle/models/price"
   autoload :PricingPreview, "paddle/models/pricing_preview"
   autoload :Discount, "paddle/models/discount"
+  autoload :DiscountGroup, "paddle/models/discount_group"
   autoload :Customer, "paddle/models/customer"
   autoload :Address, "paddle/models/address"
   autoload :Business, "paddle/models/business"
@@ -48,9 +49,12 @@ module Paddle
   autoload :SimulationRun, "paddle/models/simulation_run"
   autoload :SimulationRunEvent, "paddle/models/simulation_run_event"
   autoload :PortalSession, "paddle/models/portal_session"
+  autoload :PaymentMethod, "paddle/models/payment_method"
+  autoload :ClientToken, "paddle/models/client_token"
 
   autoload :NotificationLog, "paddle/models/notification_log"
   autoload :CreditBalance, "paddle/models/credit_balance"
+  autoload :CustomerAuthToken, "paddle/models/customer_auth_token"
 
   # Load Classic APIs
   module Classic

data/mise.toml

@@ -0,0 +1,2 @@
+[tools]
+ruby = "4.0"

data/paddle.gemspec

@@ -28,4 +28,5 @@ Gem::Specification.new do |spec|
 
   spec.add_dependency "faraday", "~> 2.11"
   spec.add_dependency "ostruct", "~> 0.6.0"
+  spec.add_dependency "cgi"
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: paddle
 version: !ruby/object:Gem::Version
-  version: 2.7.1
+  version: '2.9'
 platform: ruby
 authors:
 - Dean Perry
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-12-20 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -38,7 +37,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 0.6.0
-description:
+- !ruby/object:Gem::Dependency
+  name: cgi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 email:
 - dean@deanpcmad.com
 executables: []
@@ -89,14 +101,18 @@ files:
 - lib/paddle/models/address.rb
 - lib/paddle/models/adjustment.rb
 - lib/paddle/models/business.rb
+- lib/paddle/models/client_token.rb
 - lib/paddle/models/credit_balance.rb
 - lib/paddle/models/customer.rb
+- lib/paddle/models/customer_auth_token.rb
 - lib/paddle/models/discount.rb
+- lib/paddle/models/discount_group.rb
 - lib/paddle/models/event.rb
 - lib/paddle/models/event_type.rb
 - lib/paddle/models/notification.rb
 - lib/paddle/models/notification_log.rb
 - lib/paddle/models/notification_setting.rb
+- lib/paddle/models/payment_method.rb
 - lib/paddle/models/portal_session.rb
 - lib/paddle/models/price.rb
 - lib/paddle/models/pricing_preview.rb
@@ -110,13 +126,13 @@ files:
 - lib/paddle/models/transaction.rb
 - lib/paddle/object.rb
 - lib/paddle/version.rb
+- mise.toml
 - paddle.gemspec
 homepage: https://github.com/deanpcmad/paddle
 licenses: []
 metadata:
   homepage_uri: https://github.com/deanpcmad/paddle
   source_code_uri: https://github.com/deanpcmad/paddle
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -131,8 +147,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Ruby library for the Paddle Billing & Classic APIs
 test_files: []