paddle_rails 0.1.0

data/lib/paddle_rails/webhook_processor.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module PaddleRails
+  # Service class for processing webhook events.
+  #
+  # Delegates to specific handlers based on event type and emits
+  # ActiveSupport::Notifications for host applications to listen to.
+  #
+  # @example
+  #   PaddleRails::WebhookProcessor.process(webhook_event)
+  class WebhookProcessor
+    # Process a webhook event.
+    #
+    # @param event [PaddleRails::WebhookEvent] The webhook event to process
+    # @return [void]
+    def self.process(event)
+      new(event).process
+    end
+
+    # @param event [PaddleRails::WebhookEvent]
+    def initialize(event)
+      @event = event
+      @payload = event.payload
+      @event_type = event.event_type
+    end
+
+    # Process the webhook event.
+    #
+    # Emits an ActiveSupport::Notification with the event type and payload
+    # so host applications can subscribe to specific events.
+    #
+    # @return [void]
+    def process
+      # Emit notification for host applications to listen to
+      # Format: "paddle_rails.{event_type}"
+      notification_name = "paddle_rails.#{@event_type}"
+      
+      ActiveSupport::Notifications.instrument(notification_name) do |payload|
+        payload[:webhook_event] = @event
+        payload[:event_type] = @event_type
+        payload[:raw_payload] = @payload
+        
+        # Delegate to specific handler if it exists
+        handler_method = handler_method_name
+        if respond_to?(handler_method, true)
+          send(handler_method)
+        end
+      end
+    end
+
+    private
+
+    # Get the handler method name for the event type.
+    #
+    # Converts "subscription.created" to "handle_subscription_created"
+    #
+    # @return [String] The handler method name
+    def handler_method_name
+      "handle_#{@event_type.tr('.', '_')}"
+    end
+
+    # Handler for subscription.created events.
+    def handle_subscription_created
+      subscription_data = @payload["data"]
+      return unless subscription_data
+
+      SubscriptionSync.sync_from_payload(subscription_data)
+    end
+
+    # Handler for subscription.updated events.
+    def handle_subscription_updated
+      subscription_data = @payload["data"]
+      return unless subscription_data
+
+      SubscriptionSync.sync_from_payload(subscription_data)
+    end
+
+    # Handler for subscription.canceled events.
+    def handle_subscription_canceled
+      subscription_data = @payload["data"]
+      return unless subscription_data
+
+      SubscriptionSync.sync_from_payload(subscription_data)
+    end
+
+    # Handler for transaction.completed events.
+    #
+    # Syncs payment record and payment method details from the completed transaction
+    # to the associated subscription.
+    def handle_transaction_completed
+      transaction_data = @payload["data"]
+      return unless transaction_data
+
+      # Sync payment record
+      SubscriptionSync.sync_payment(transaction_data)
+      
+      # Sync payment method from the transaction
+      SubscriptionSync.sync_payment_method_from_transaction(transaction_data)
+    end
+  end
+end
+

data/lib/paddle_rails/webhook_verifier.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module PaddleRails
+  # Service class for verifying Paddle webhook signatures.
+  #
+  # Implements Paddle's webhook signature verification as documented at:
+  # https://developer.paddle.com/webhooks/signature-verification
+  #
+  # @example
+  #   verifier = PaddleRails::WebhookVerifier.new(secret_key)
+  #   if verifier.verify(raw_body, signature_header)
+  #     # Webhook is valid
+  #   end
+  class WebhookVerifier
+    # Default tolerance for timestamp validation (5 seconds)
+    TIMESTAMP_TOLERANCE = 5
+
+    # @param secret_key [String] The webhook secret key from Paddle
+    # @param timestamp_tolerance [Integer] Maximum age of webhook in seconds (default: 5)
+    def initialize(secret_key, timestamp_tolerance: TIMESTAMP_TOLERANCE)
+      @secret_key = secret_key
+      @timestamp_tolerance = timestamp_tolerance
+    end
+
+    # Verify a webhook signature.
+    #
+    # @param raw_body [String] The raw request body (must not be transformed)
+    # @param signature_header [String] The value of the Paddle-Signature header
+    # @return [Boolean] true if signature is valid, false otherwise
+    def verify(raw_body, signature_header)
+      return false if raw_body.nil? || signature_header.nil? || @secret_key.nil?
+
+      timestamp, signatures = parse_signature_header(signature_header)
+      return false unless timestamp && signatures.any?
+
+      # Check timestamp to prevent replay attacks
+      return false unless timestamp_valid?(timestamp)
+
+      # Build signed payload: timestamp:raw_body
+      signed_payload = "#{timestamp}:#{raw_body}"
+
+      # Compute expected signature using HMAC-SHA256
+      expected_signature = compute_signature(signed_payload)
+
+      # Compare signatures (use timing-safe comparison)
+      signatures.any? { |sig| timing_safe_compare(sig, expected_signature) }
+    rescue StandardError => e
+      Rails.logger.error("PaddleRails::WebhookVerifier: Error verifying signature: #{e.message}")
+      false
+    end
+
+    private
+
+    # Parse the Paddle-Signature header.
+    #
+    # Format: "ts=1671552777;h1=eb4d0dc8853be92b7f063b9f3ba5233eb920a09459b6e6b2c26705b4364db151"
+    #
+    # @param signature_header [String] The Paddle-Signature header value
+    # @return [Array<Integer, Array<String>>] [timestamp, array_of_signatures]
+    def parse_signature_header(signature_header)
+      parts = signature_header.split(";")
+      timestamp = nil
+      signatures = []
+
+      parts.each do |part|
+        key, value = part.split("=", 2)
+        case key
+        when "ts"
+          timestamp = value.to_i
+        when "h1"
+          signatures << value
+        end
+      end
+
+      [timestamp, signatures]
+    end
+
+    # Check if the timestamp is within the tolerance window.
+    #
+    # @param timestamp [Integer] Unix timestamp from the webhook
+    # @return [Boolean] true if timestamp is valid
+    def timestamp_valid?(timestamp)
+      current_time = Time.now.to_i
+      (current_time - timestamp).abs <= @timestamp_tolerance
+    end
+
+    # Compute HMAC-SHA256 signature for the signed payload.
+    #
+    # @param signed_payload [String] The timestamp:raw_body string
+    # @return [String] Hexadecimal signature
+    def compute_signature(signed_payload)
+      OpenSSL::HMAC.hexdigest("SHA256", @secret_key, signed_payload)
+    end
+
+    # Timing-safe string comparison to prevent timing attacks.
+    #
+    # @param a [String] First string
+    # @param b [String] Second string
+    # @return [Boolean] true if strings are equal
+    def timing_safe_compare(a, b)
+      return false if a.nil? || b.nil?
+      return false unless a.length == b.length
+
+      OpenSSL.fixed_length_secure_compare(a, b)
+    end
+  end
+end
+

data/lib/paddle_rails.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# PaddleRails is a zero-hassle Paddle subscription integration for Rails
+# using custom_data-based identity.
+#
+# @example Basic usage
+#   # In config/initializers/paddle_rails.rb
+#   PaddleRails.configure do |config|
+#     config.api_key = ENV["PADDLE_API_KEY"]
+#     config.subscription_owner_authenticator do
+#       current_user || warden.authenticate!(scope: :user)
+#     end
+#   end
+#
+# @example Making a model subscribable
+#   class User < ApplicationRecord
+#     include PaddleRails::Subscribable
+#   end
+#
+# @see https://github.com/kjellberg/paddle_rails
+module PaddleRails
+end
+
+require "paddle"
+require "paddle_rails/version"
+require "paddle_rails/engine"
+require "paddle_rails/configuration"
+require "paddle_rails/product_sync"
+require "paddle_rails/checkout"
+require "paddle_rails/webhook_verifier"
+require "paddle_rails/webhook_processor"
+require "paddle_rails/subscription_sync"

data/lib/tasks/paddle_rails_tasks.rake

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# Rake tasks for PaddleRails gem.
+#
+# @note This file currently contains placeholder tasks.
+#   Actual rake tasks will be added as needed.
+#
+# @example Running a task
+#   rake paddle_rails:sync_products
+#
+# @see PaddleRails::ProductSync
+# desc "Explaining what the task does"
+# task :paddle_rails do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,157 @@
+--- !ruby/object:Gem::Specification
+name: paddle_rails
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Rasmus Kjellberg
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 8.1.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 8.1.1
+- !ruby/object:Gem::Dependency
+  name: paddle
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+description: |
+  PaddleRails is a production-ready Rails engine that drops a complete subscription management portal into your application in minutes.
+
+  It's not just an API wrapper—it's a full-stack billing solution that handles the hard parts of SaaS payments: webhooks, plan upgrades, prorations, cancellation flows, and payment method updates. Fully compliant with Paddle Billing (v2), handling global tax/VAT and localized pricing automatically.
+
+  Features:
+  - Mountable billing dashboard ready in minutes
+  - Built for Paddle Billing V2
+  - Two-way sync via webhooks
+  - Beautiful UI built with Tailwind CSS
+  - Uses GlobalID for bulletproof user mapping (no email mismatch issues)
+  - Supports subscriptions on Users, Teams, Organizations, or Tenants
+  - Payment history with invoice viewing and download
+  - Plan upgrades/downgrades with proration
+  - Payment method management
+
+  No need to build billing UI from scratch. Just mount the engine and focus on your product.
+email:
+- 2277443+kjellberg@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/assets/stylesheets/paddle_rails/application.css
+- app/assets/stylesheets/paddle_rails/tailwind.css
+- app/assets/tailwind/application.css
+- app/controllers/concerns/paddle_rails/paddle_checkout_error_handler.rb
+- app/controllers/concerns/paddle_rails/subscription_owner.rb
+- app/controllers/paddle_rails/application_controller.rb
+- app/controllers/paddle_rails/checkout_controller.rb
+- app/controllers/paddle_rails/dashboard_controller.rb
+- app/controllers/paddle_rails/onboarding_controller.rb
+- app/controllers/paddle_rails/payments_controller.rb
+- app/controllers/paddle_rails/subscriptions_controller.rb
+- app/controllers/paddle_rails/webhooks_controller.rb
+- app/helpers/paddle_rails/application_helper.rb
+- app/helpers/paddle_rails/subscription_owner_helper.rb
+- app/jobs/paddle_rails/application_job.rb
+- app/jobs/paddle_rails/process_webhook_job.rb
+- app/mailers/paddle_rails/application_mailer.rb
+- app/models/concerns/paddle_rails/subscribable.rb
+- app/models/paddle_rails/application_record.rb
+- app/models/paddle_rails/payment.rb
+- app/models/paddle_rails/price.rb
+- app/models/paddle_rails/product.rb
+- app/models/paddle_rails/subscription.rb
+- app/models/paddle_rails/subscription_item.rb
+- app/models/paddle_rails/webhook_event.rb
+- app/presenters/paddle_rails/payment_presenter.rb
+- app/presenters/paddle_rails/product_presenter.rb
+- app/presenters/paddle_rails/subscription_presenter.rb
+- app/views/layouts/paddle_rails/application.html.erb
+- app/views/paddle_rails/checkout/show.html.erb
+- app/views/paddle_rails/dashboard/_change_plan.html.erb
+- app/views/paddle_rails/dashboard/_current_subscription.html.erb
+- app/views/paddle_rails/dashboard/_payment_history.html.erb
+- app/views/paddle_rails/dashboard/_payment_method.html.erb
+- app/views/paddle_rails/dashboard/show.html.erb
+- app/views/paddle_rails/onboarding/show.html.erb
+- app/views/paddle_rails/shared/configuration_error.html.erb
+- config/routes.rb
+- db/migrate/20251124180624_create_paddle_rails_subscription_plans.rb
+- db/migrate/20251124180817_create_paddle_rails_subscription_prices.rb
+- db/migrate/20251127221947_create_paddle_rails_webhook_events.rb
+- db/migrate/20251128135831_create_paddle_rails_subscriptions.rb
+- db/migrate/20251128142327_create_paddle_rails_subscription_items.rb
+- db/migrate/20251128151334_remove_paddle_price_id_from_subscriptions.rb
+- db/migrate/20251128151401_rename_subscription_plans_to_products.rb
+- db/migrate/20251128151402_rename_subscription_plan_id_to_subscription_product_id.rb
+- db/migrate/20251128151453_remove_subscription_price_id_from_subscriptions.rb
+- db/migrate/20251128151501_add_subscription_product_id_to_subscription_items.rb
+- db/migrate/20251128152025_remove_paddle_item_id_from_subscription_items.rb
+- db/migrate/20251128212046_rename_subscription_products_to_products.rb
+- db/migrate/20251128212047_rename_subscription_prices_to_prices.rb
+- db/migrate/20251128212053_rename_subscription_product_id_to_product_id_in_prices.rb
+- db/migrate/20251128212054_rename_fks_in_subscription_items.rb
+- db/migrate/20251128220016_add_scheduled_cancelation_at_to_subscriptions.rb
+- db/migrate/20251129121336_add_payment_method_to_subscriptions.rb
+- db/migrate/20251129222345_create_paddle_rails_payments.rb
+- lib/paddle_rails.rb
+- lib/paddle_rails/checkout.rb
+- lib/paddle_rails/configuration.rb
+- lib/paddle_rails/engine.rb
+- lib/paddle_rails/product_sync.rb
+- lib/paddle_rails/subscription_sync.rb
+- lib/paddle_rails/version.rb
+- lib/paddle_rails/webhook_processor.rb
+- lib/paddle_rails/webhook_verifier.rb
+- lib/tasks/paddle_rails_tasks.rake
+homepage: https://github.com/kjellberg/paddle_rails
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/kjellberg/paddle_rails
+  source_code_uri: https://github.com/kjellberg/paddle_rails
+  changelog_uri: https://github.com/kjellberg/paddle_rails/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: Plug-and-play billing engine for Rails + Paddle. Full subscription management
+  portal with webhooks, plan changes, and payment history.
+test_files: []