paddle_rails 0.1.0

data/lib/paddle_rails/configuration.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module PaddleRails
+  # Configuration class for PaddleRails gem settings.
+  #
+  # @example Configuring PaddleRails
+  #   PaddleRails.configure do |config|
+  #     config.api_key = "your_api_key"
+  #     config.public_token = "your_public_token"
+  #     config.subscription_owner_authenticator do
+  #       current_user || warden.authenticate!(scope: :user)
+  #     end
+  #   end
+  class Configuration
+    # @!attribute subscription_owner_authenticator
+    #   @return [Proc] The block used to authenticate the subscription owner.
+    #     Defaults to `current_user || warden.authenticate!(scope: :user)`
+    # @!attribute customer_portal_back_path
+    #   @return [Proc] The block used to generate the back link path shown in
+    #     the customer portal sidebar. Evaluated in the controller or view
+    #     context and defaults to `main_app.root_path`.
+    # @!attribute api_key
+    #   @return [String] The Paddle API key. Defaults to ENV["PADDLE_API_KEY"]
+    # @!attribute public_token
+    #   @return [String] The Paddle public token. Defaults to ENV["PADDLE_PUBLIC_TOKEN"]
+    # @!attribute environment
+    #   @return [String] The Paddle environment ("sandbox" or "production"). Defaults to ENV["PADDLE_ENVIRONMENT"] or "sandbox"
+    # @!attribute webhook_secret
+    #   @return [String] The webhook secret key for verifying webhook signatures. Defaults to ENV["PADDLE_WEBHOOK_SECRET"]
+    attr_accessor :subscription_owner_authenticator,
+                  :customer_portal_back_path,
+                  :api_key,
+                  :public_token,
+                  :environment,
+                  :webhook_secret
+
+    # Initialize a new Configuration instance with default values.
+    #
+    # Sets up default authenticator following Doorkeeper pattern and
+    # loads API key and public token from environment variables.
+    def initialize
+      # Default authenticator following Doorkeeper pattern
+      @subscription_owner_authenticator = proc do
+        current_user || warden.authenticate!(scope: :user)
+      end
+
+      # Default back link in the customer portal sidebar
+      @customer_portal_back_path = proc do
+        main_app.root_path
+      end
+
+      @api_key = ENV.fetch("PADDLE_API_KEY")
+      @public_token = ENV.fetch("PADDLE_PUBLIC_TOKEN")
+      @environment = ENV.fetch("PADDLE_ENVIRONMENT", "sandbox")
+      @webhook_secret = ENV["PADDLE_WEBHOOK_SECRET"]
+    end
+
+    # Configure the subscription owner authenticator block.
+    #
+    # @param block [Proc] The block to use for authenticating subscription owners.
+    #   The block is evaluated in the context of the controller or view.
+    # @return [Proc] The configured authenticator block
+    #
+    # @example
+    #   config.subscription_owner_authenticator do
+    #     current_user
+    #   end
+    #
+    # @example Multi-tenant setup
+    #   config.subscription_owner_authenticator do
+    #     current_tenant
+    #   end
+    def subscription_owner_authenticator(&block)
+      @subscription_owner_authenticator = block if block_given?
+      @subscription_owner_authenticator
+    end
+
+    # Configure the customer portal back path block.
+    #
+    # @param block [Proc] The block to use for generating the back link path.
+    #   The block is evaluated in the context of the controller or view.
+    # @return [Proc] The configured back path block
+    #
+    # @example
+    #   config.customer_portal_back_path do
+    #     main_app.dashboard_path
+    #   end
+    def customer_portal_back_path(&block)
+      @customer_portal_back_path = block if block_given?
+      @customer_portal_back_path
+    end
+  end
+
+  class << self
+    # Configure PaddleRails settings.
+    #
+    # @yield [config] Yields the configuration instance
+    # @yieldparam config [Configuration] The configuration instance to modify
+    # @return [Configuration] The configuration instance
+    #
+    # @example
+    #   PaddleRails.configure do |config|
+    #     config.api_key = "your_api_key"
+    #     config.subscription_owner_authenticator do
+    #       current_user
+    #     end
+    #   end
+    def configure
+      yield(configuration) if block_given?
+      configuration
+    end
+
+    # Get the current configuration instance.
+    #
+    # @return [Configuration] The singleton configuration instance
+    def configuration
+      @configuration ||= Configuration.new
+    end
+  end
+end
+

data/lib/paddle_rails/engine.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module PaddleRails
+  # Rails engine for PaddleRails gem.
+  #
+  # Handles configuration of the Paddle client and makes subscription
+  # owner helpers available globally in controllers and views.
+  #
+  # @see PaddleRails::Configuration
+  class Engine < ::Rails::Engine
+    isolate_namespace PaddleRails
+
+    # Configure the Paddle client with API key from configuration.
+    #
+    # Sets up the Paddle gem with environment and API key from
+    # PaddleRails configuration, falling back to environment variables.
+    initializer "paddle_rails.configuration" do
+      Paddle.configure do |config|
+        config.environment = ENV.fetch("PADDLE_ENVIRONMENT", "sandbox").to_sym
+        config.api_key = PaddleRails.configuration.api_key
+      end
+    end
+
+    # Add webhook route to main application
+    initializer "paddle_rails.routes" do |app|
+      app.routes.prepend do
+        post "/paddle_rails/webhooks", to: "paddle_rails/webhooks#create", as: :paddle_rails_webhooks
+      end
+    end
+
+    # Prepare helpers for inclusion in controllers and views.
+    #
+    # Makes {PaddleRails::SubscriptionOwner} and {PaddleRails::SubscriptionOwnerHelper}
+    # available both within the engine namespace and globally in all controllers
+    # and views.
+    config.to_prepare do
+      # Include controller concern in engine's ApplicationController
+      PaddleRails::ApplicationController.include(PaddleRails::SubscriptionOwner)
+
+      # Include view helper in engine's ApplicationHelper
+      PaddleRails::ApplicationHelper.include(PaddleRails::SubscriptionOwnerHelper)
+
+      # Make helpers available globally
+      ActionController::Base.include(PaddleRails::SubscriptionOwner)
+      ActionView::Base.include(PaddleRails::SubscriptionOwnerHelper)
+      ActionView::Base.include(PaddleRails::ApplicationHelper)
+    end
+  end
+end

data/lib/paddle_rails/product_sync.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module PaddleRails
+  # Service class for syncing Paddle products and prices to local database.
+  #
+  # Fetches all products and prices from the Paddle API and creates or updates
+  # corresponding {Product} and {Price} records locally.
+  #
+  # @example Sync all products and prices
+  #   PaddleRails::ProductSync.call
+  #
+  # @see Product
+  # @see Price
+  class ProductSync
+    # Convenience method to create a new instance and call it.
+    #
+    # @return [ProductSync] The instance that was called
+    def self.call
+      new.call
+    end
+
+    # Perform the sync operation.
+    #
+    # Syncs all products and prices from Paddle to local database.
+    #
+    # @return [void]
+    def call
+      sync_products
+      sync_prices
+    end
+
+    private
+
+    # Sync all products from Paddle API.
+    #
+    # Fetches products in pages of 50 and creates or updates local
+    # {Product} records.
+    #
+    # @return [void]
+    # @raise [StandardError] If product sync fails
+    def sync_products
+      page = 1
+      per_page = 50
+      loop do
+        products = Paddle::Product.list(per_page: per_page, page: page)
+        break if products.data.empty?
+        
+        products.data.each do |product|
+          sync_product(product)
+        end
+        
+        # Check if there are more pages by comparing current page size with total
+        break if (page * per_page) >= products.total
+        page += 1
+      end
+    end
+
+    # Sync a single product to local database.
+    #
+    # @param product_data [Paddle::Product] The product data from Paddle API
+    # @return [void]
+    # @raise [StandardError] If product save fails
+    def sync_product(product_data)
+      product = Product.find_or_initialize_by(paddle_product_id: product_data.id)
+      
+      product.assign_attributes(
+        name: product_data.name,
+        description: product_data.description,
+        status: product_data.status,
+        type: product_data.type,
+        tax_category: product_data.tax_category,
+        image_url: product_data.image_url,
+        custom_data: product_data.custom_data
+      )
+      
+      product.save!
+    rescue StandardError => e
+      Rails.logger.error("PaddleRails::ProductSync: Failed to sync product #{product_data.id}: #{e.message}")
+      raise
+    end
+
+    # Sync all prices from Paddle API.
+    #
+    # Fetches prices in pages of 50 and creates or updates local
+    # {Price} records.
+    #
+    # @return [void]
+    # @raise [StandardError] If price sync fails
+    def sync_prices
+      page = 1
+      per_page = 50
+      loop do
+        prices = Paddle::Price.list(per_page: per_page, page: page)
+        break if prices.data.empty?
+        
+        prices.data.each do |price|
+          sync_price(price)
+        end
+        
+        # Check if there are more pages by comparing current page size with total
+        break if (page * per_page) >= prices.total
+        page += 1
+      end
+    end
+
+    # Sync a single price to local database.
+    #
+    # @param price_data [Paddle::Price] The price data from Paddle API
+    # @return [void]
+    # @raise [StandardError] If price save fails
+    def sync_price(price_data)
+      # Find the product by product_id
+      product = Product.find_by(paddle_product_id: price_data.product_id)
+      unless product
+        Rails.logger.warn("PaddleRails::ProductSync: Skipping price #{price_data.id} - product #{price_data.product_id} not found locally")
+        return
+      end
+
+      price = Price.find_or_initialize_by(paddle_price_id: price_data.id)
+      
+      # Extract billing cycle info (OpenStruct from paddle gem)
+      billing_interval = price_data.billing_cycle&.interval
+      billing_interval_count = price_data.billing_cycle&.frequency
+      
+      # Extract unit price info (OpenStruct from paddle gem)
+      unit_price_amount = price_data.unit_price&.amount&.to_i
+      currency_code = price_data.unit_price&.currency_code
+      
+      # Extract trial period (store as JSON, extract days if available)
+      trial_period = price_data.trial_period
+      trial_days = extract_trial_days(trial_period)
+      
+      # Extract quantity constraints
+      quantity_minimum = price_data.quantity&.minimum
+      quantity_maximum = price_data.quantity&.maximum
+      
+      price.assign_attributes(
+        product: product,
+        name: price_data.name,
+        description: price_data.description,
+        status: price_data.status,
+        type: price_data.type,
+        currency: currency_code,
+        unit_price: unit_price_amount,
+        billing_interval: billing_interval,
+        billing_interval_count: billing_interval_count,
+        trial_days: trial_days,
+        trial_period: trial_period,
+        tax_mode: price_data.tax_mode,
+        quantity_minimum: quantity_minimum,
+        quantity_maximum: quantity_maximum,
+        custom_data: price_data.custom_data
+      )
+      
+      price.save!
+    rescue StandardError => e
+      Rails.logger.error("PaddleRails::ProductSync: Failed to sync price #{price_data.id}: #{e.message}")
+      raise
+    end
+
+    # Extract trial days from trial period data.
+    #
+    # @param trial_period [OpenStruct, nil] Trial period data from Paddle API
+    # @return [Integer, nil] Number of trial days, or nil if not applicable
+    def extract_trial_days(trial_period)
+      return nil unless trial_period
+      
+      # trial_period is OpenStruct from paddle gem
+      # Common structure: interval: "day", frequency: 14
+      return trial_period.frequency if trial_period.interval == "day"
+      
+      nil
+    end
+  end
+end
+

data/lib/paddle_rails/subscription_sync.rb

@@ -0,0 +1,303 @@
+# frozen_string_literal: true
+
+module PaddleRails
+  # Service for synchronizing Paddle subscription data to the local database.
+  #
+  # Handles resolving the owner from custom_data and creating/updating the
+  # PaddleRails::Subscription record.
+  class SubscriptionSync
+    # Sync a subscription by fetching it from the Paddle API.
+    #
+    # @param subscription_id [String] The Paddle subscription ID (sub_...)
+    # @return [PaddleRails::Subscription] The synced subscription record
+    def self.sync_from_paddle(subscription_id)
+      # Use the Paddle gem to retrieve the subscription
+      subscription = Paddle::Subscription.retrieve(id: subscription_id)
+      
+      # Convert to a hash compatible with our sync logic
+      # Note: The Paddle gem returns OpenStruct-like objects, so we need to handle that.
+      # Assuming Paddle gem returns an object where attributes are methods.
+      # We can probably pass the object directly to sync_from_payload if it responds to hash-like methods
+      # or convert it. For safety, let's pass the raw response if possible, or the object.
+      
+      # If the gem returns a response object that wraps the data:
+      payload = subscription.respond_to?(:attributes) ? subscription.attributes : subscription.to_h
+      
+      new(payload).sync
+    end
+
+    # Sync a subscription from a webhook or API payload.
+    #
+    # @param payload [Hash, Object] The subscription data from Paddle
+    # @return [PaddleRails::Subscription] The synced subscription record
+    def self.sync_from_payload(payload)
+      new(payload).sync
+    end
+
+    def initialize(payload)
+      # Normalize payload to a hash with string keys
+      @payload = payload.is_a?(Hash) ? payload.stringify_keys : payload.to_h.stringify_keys
+    end
+
+    def sync
+      paddle_subscription_id = @payload["id"]
+      return nil unless paddle_subscription_id
+
+      # Find existing subscription or initialize new one
+      subscription = Subscription.find_or_initialize_by(paddle_subscription_id: paddle_subscription_id)
+
+      # Extract attributes
+      status = @payload["status"]
+      
+      # Dates
+      current_period = @payload["current_billing_period"]
+      current_period_end_at = current_period&.dig("ends_at")
+      
+      # Scheduled Change
+      scheduled_change = @payload["scheduled_change"]
+      scheduled_cancelation_at = if scheduled_change&.dig("action") == "cancel"
+                                   scheduled_change["effective_at"]
+                                 end
+      
+      # Items
+      items = @payload["items"] || []
+      
+      # Resolve Owner
+      owner = resolve_owner
+      
+      # If owner is missing for a new subscription, we can't save it properly
+      # unless we allow orphans. For now, we log an error if owner is missing.
+      if owner.nil? && subscription.new_record?
+        Rails.logger.error("PaddleRails::SubscriptionSync: Could not resolve owner for subscription #{paddle_subscription_id}. Custom data: #{@payload['custom_data']}")
+        # We might want to create it anyway if we can link it later, but validation requires owner.
+        return nil
+      end
+
+      # Update attributes
+      subscription.status = status
+      subscription.current_period_end_at = current_period_end_at
+      subscription.scheduled_cancelation_at = scheduled_cancelation_at
+      subscription.owner = owner if owner # Only update owner if resolved (don't overwrite with nil)
+      subscription.raw_payload = @payload
+
+      subscription.save!
+
+      # Sync items
+      sync_items(subscription, items)
+
+      subscription
+    end
+
+    private
+
+    def resolve_owner
+      custom_data = @payload["custom_data"] || {}
+      owner_sgid = custom_data["owner_sgid"]
+
+      return nil unless owner_sgid
+
+      # Use GlobalID to locate the owner
+      GlobalID::Locator.locate_signed(owner_sgid, for: "paddle_rails_owner")
+    rescue => e
+      Rails.logger.error("PaddleRails::SubscriptionSync: Error resolving owner: #{e.message}")
+      nil
+    end
+
+    # Sync subscription items from the payload.
+    #
+    # @param subscription [PaddleRails::Subscription] The subscription to sync items for
+    # @param items_payload [Array] Array of item hashes from Paddle
+    # @return [void]
+    def sync_items(subscription, items_payload)
+      return unless items_payload.is_a?(Array)
+
+      # Track which price IDs we've seen in this sync
+      seen_price_ids = []
+
+      items_payload.each do |item_data|
+        price_data = item_data["price"] || item_data.dig("price")
+        next unless price_data
+
+        paddle_price_id = price_data["id"]
+        next unless paddle_price_id
+
+        # Find the local price record
+        price_record = find_price_by_paddle_id(paddle_price_id)
+        next unless price_record
+
+        seen_price_ids << price_record.id
+
+        # Find or initialize the subscription item by subscription and price
+        subscription_item = subscription.items.find_or_initialize_by(
+          price_id: price_record.id
+        )
+
+        # Set product reference (through price)
+        subscription_item.product = price_record.product
+
+        # Update attributes
+        subscription_item.quantity = item_data["quantity"] || 1
+        subscription_item.status = item_data["status"]
+        subscription_item.recurring = item_data["recurring"] == true
+
+        subscription_item.save!
+      end
+
+      # Delete items that are no longer in the payload (full sync)
+      subscription.items.where.not(price_id: seen_price_ids).destroy_all
+    end
+
+    # Find a Price by its Paddle price ID.
+    #
+    # @param paddle_price_id [String] The Paddle price ID
+    # @return [PaddleRails::Price, nil]
+    def find_price_by_paddle_id(paddle_price_id)
+      Price.find_by(paddle_price_id: paddle_price_id)
+    end
+
+    # Sync payment method from a transaction payload.
+    #
+    # Called when processing transaction.completed webhooks.
+    # Extracts payment method details from the transaction's payments array
+    # and updates the associated subscription.
+    #
+    # @param transaction_payload [Hash] The transaction data from Paddle
+    # @return [PaddleRails::Subscription, nil] The updated subscription or nil
+    def self.sync_payment_method_from_transaction(transaction_payload)
+      payload = transaction_payload.is_a?(Hash) ? transaction_payload.stringify_keys : transaction_payload.to_h.stringify_keys
+      
+      subscription_id = payload["subscription_id"]
+      return nil unless subscription_id
+      
+      subscription = Subscription.find_by(paddle_subscription_id: subscription_id)
+      return nil unless subscription
+      
+      # Get the first successful payment from the payments array
+      payments = payload["payments"] || []
+      payment = payments.find { |p| p["status"] == "captured" } || payments.first
+      return nil unless payment
+      
+      payment_method_id = payment["payment_method_id"]
+      method_details = payment["method_details"]
+      
+      return nil unless method_details
+      
+      # Extract payment method details
+      details = extract_payment_details_from_transaction(method_details)
+      
+      subscription.payment_method_id = payment_method_id
+      subscription.payment_method_type = method_details["type"]
+      subscription.payment_method_details = details
+      subscription.save!
+      
+      subscription
+    rescue StandardError => e
+      Rails.logger.error("PaddleRails::SubscriptionSync: Error syncing payment method from transaction: #{e.message}")
+      nil
+    end
+
+    # Extract payment method details from transaction method_details.
+    #
+    # Handles the nested structure from transaction.completed webhooks:
+    # {
+    #   "type": "card",
+    #   "card": {
+    #     "type": "visa",
+    #     "last4": "4242",
+    #     "expiry_year": 2028,
+    #     "expiry_month": 12,
+    #     "cardholder_name": "..."
+    #   }
+    # }
+    #
+    # @param method_details [Hash] The method_details from payment
+    # @return [Hash] Extracted details for storage
+    def self.extract_payment_details_from_transaction(method_details)
+      return {} unless method_details.is_a?(Hash)
+      
+      details = { type: method_details["type"] }
+      
+      card_data = method_details["card"]
+      if card_data.is_a?(Hash)
+        details[:card] = {
+          brand: card_data["type"]&.upcase, # In transaction payload, card brand is in "type" field
+          last4: card_data["last4"],
+          expiry_month: card_data["expiry_month"],
+          expiry_year: card_data["expiry_year"],
+          cardholder_name: card_data["cardholder_name"]
+        }.compact
+      end
+      
+      details
+    end
+
+    # Sync a payment from a transaction.completed webhook payload.
+    #
+    # Creates or updates a Payment record with transaction data.
+    #
+    # @param transaction_payload [Hash] The transaction data from Paddle
+    # @return [PaddleRails::Payment, nil] The synced payment record or nil
+    def self.sync_payment(transaction_payload)
+      payload = transaction_payload.is_a?(Hash) ? transaction_payload.stringify_keys : transaction_payload.to_h.stringify_keys
+      
+      paddle_transaction_id = payload["id"]
+      return nil unless paddle_transaction_id
+      
+      subscription_id = payload["subscription_id"]
+      return nil unless subscription_id
+      
+      subscription = Subscription.find_by(paddle_subscription_id: subscription_id)
+      return nil unless subscription
+      
+      # Resolve owner from custom_data or use subscription's owner
+      owner = resolve_owner_from_payload(payload) || subscription.owner
+      return nil unless owner
+      
+      # Extract totals from details
+      details = payload["details"] || {}
+      totals = details["totals"] || {}
+      
+      # Find or initialize payment
+      payment = PaddleRails::Payment.find_or_initialize_by(paddle_transaction_id: paddle_transaction_id)
+      
+      # Update attributes
+      payment.subscription = subscription
+      payment.owner = owner
+      payment.invoice_id = payload["invoice_id"]
+      payment.invoice_number = payload["invoice_number"]
+      payment.status = payload["status"]
+      payment.origin = payload["origin"]
+      payment.total = totals["total"]&.to_i || totals[:total]&.to_i
+      payment.tax = totals["tax"]&.to_i || totals[:tax]&.to_i
+      payment.subtotal = totals["subtotal"]&.to_i || totals[:subtotal]&.to_i
+      payment.currency = totals["currency_code"] || totals[:currency_code] || payload["currency_code"]
+      payment.billed_at = payload["billed_at"] || payload["billed_at"]
+      payment.details = details
+      payment.raw_payload = payload
+      
+      payment.save!
+      payment
+    rescue StandardError => e
+      Rails.logger.error("PaddleRails::SubscriptionSync: Error syncing payment: #{e.message}")
+      Rails.logger.error(e.backtrace.join("\n"))
+      nil
+    end
+
+    # Resolve owner from transaction payload's custom_data.
+    #
+    # @param payload [Hash] The transaction payload
+    # @return [Object, nil] The owner object or nil
+    def self.resolve_owner_from_payload(payload)
+      custom_data = payload["custom_data"] || {}
+      owner_sgid = custom_data["owner_sgid"]
+      
+      return nil unless owner_sgid
+      
+      GlobalID::Locator.locate_signed(owner_sgid, for: "paddle_rails_owner")
+    rescue => e
+      Rails.logger.error("PaddleRails::SubscriptionSync: Error resolving owner from payload: #{e.message}")
+      nil
+    end
+  end
+end
+

data/lib/paddle_rails/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module PaddleRails
+  # Current version of the PaddleRails gem.
+  VERSION = "0.1.0"
+end