paddle_rails 0.1.0

data/app/helpers/paddle_rails/application_helper.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module PaddleRails
+  module ApplicationHelper
+    # Returns the path to the billing dashboard.
+    #
+    # This is a convenience helper that provides a clean, global way to
+    # reference the PaddleRails billing portal root path.
+    #
+    # @example
+    #   <%= link_to "Manage Billing", billing_dashboard_path %>
+    #
+    # @return [String] the path to the billing dashboard
+    def billing_dashboard_path
+      paddle_rails.root_path
+    end
+
+    # Returns the URL to the billing dashboard.
+    #
+    # @example
+    #   <%= link_to "Manage Billing", billing_dashboard_url %>
+    #
+    # @return [String] the URL to the billing dashboard
+    def billing_dashboard_url
+      paddle_rails.root_url
+    end
+
+    # Returns an SVG icon for the given card brand.
+    #
+    # @param brand [String] The card brand (e.g., "VISA", "MASTERCARD", "AMEX")
+    # @param size [String] CSS classes for sizing (default: "w-8 h-5")
+    # @return [String] The SVG markup (html_safe)
+    def payment_method_icon(brand, size: "w-8 h-5")
+      svg = case brand&.to_s&.upcase
+            when "VISA"
+              <<~SVG
+                <svg class="#{size}" viewBox="0 0 48 32" fill="none" xmlns="http://www.w3.org/2000/svg">
+                  <rect width="48" height="32" rx="4" fill="#1A1F71"/>
+                  <path d="M19.5 21H17L18.8 11H21.3L19.5 21Z" fill="white"/>
+                  <path d="M28.1 11.2C27.5 11 26.7 10.7 25.7 10.7C23.2 10.7 21.4 12 21.4 13.9C21.4 15.3 22.7 16.1 23.7 16.6C24.7 17.1 25 17.4 25 17.9C25 18.6 24.1 18.9 23.3 18.9C22.2 18.9 21.6 18.8 20.7 18.4L20.3 18.2L19.9 20.7C20.6 21 21.8 21.3 23 21.3C25.7 21.3 27.4 20 27.4 18C27.4 16.9 26.7 16 25.2 15.3C24.3 14.8 23.7 14.5 23.7 14C23.7 13.5 24.3 13 25.4 13C26.3 13 27 13.2 27.5 13.4L27.8 13.5L28.1 11.2Z" fill="white"/>
+                  <path d="M32.9 11H30.9C30.3 11 29.8 11.2 29.5 11.8L25.8 21H28.5L29 19.6H32.3L32.6 21H35L32.9 11ZM29.8 17.6C30 17 30.9 14.5 30.9 14.5C30.9 14.5 31.1 14 31.3 13.6L31.5 14.4C31.5 14.4 32 16.7 32.1 17.5H29.8V17.6Z" fill="white"/>
+                  <path d="M15.4 11L12.9 17.8L12.6 16.3C12.1 14.7 10.6 13 8.9 12.1L11.2 21H14L18.2 11H15.4Z" fill="white"/>
+                  <path d="M11.1 11H6.9L6.8 11.2C10.1 12 12.3 14 13.1 16.3L12.2 11.9C12.1 11.3 11.7 11.1 11.1 11Z" fill="#F9A51A"/>
+                </svg>
+              SVG
+            when "MASTERCARD"
+              <<~SVG
+                <svg class="#{size}" viewBox="0 0 48 32" fill="none" xmlns="http://www.w3.org/2000/svg">
+                  <rect width="48" height="32" rx="4" fill="#000"/>
+                  <circle cx="18" cy="16" r="8" fill="#EB001B"/>
+                  <circle cx="30" cy="16" r="8" fill="#F79E1B"/>
+                  <path d="M24 10.4C25.8 11.9 27 14 27 16C27 18 25.8 20.1 24 21.6C22.2 20.1 21 18 21 16C21 14 22.2 11.9 24 10.4Z" fill="#FF5F00"/>
+                </svg>
+              SVG
+            when "AMEX", "AMERICAN EXPRESS"
+              <<~SVG
+                <svg class="#{size}" viewBox="0 0 48 32" fill="none" xmlns="http://www.w3.org/2000/svg">
+                  <rect width="48" height="32" rx="4" fill="#006FCF"/>
+                  <path d="M10 16.5L12.5 11H15L18.5 19H16L15.3 17.5H12.2L11.5 19H9L10 16.5ZM13.7 13L12.8 15.5H14.7L13.7 13Z" fill="white"/>
+                  <path d="M19 11H22L24 15L26 11H29V19H27V14L24.5 19H23.5L21 14V19H19V11Z" fill="white"/>
+                  <path d="M30 11H37V12.8H32V14H36.8V15.8H32V17.2H37V19H30V11Z" fill="white"/>
+                  <path d="M38 11H40.5L42 14L43.5 11H46L43 15.5L46 20H43.5L42 17L40.5 20H38L41 15.5L38 11Z" fill="white"/>
+                </svg>
+              SVG
+            when "DISCOVER"
+              <<~SVG
+                <svg class="#{size}" viewBox="0 0 48 32" fill="none" xmlns="http://www.w3.org/2000/svg">
+                  <rect width="48" height="32" rx="4" fill="#fff"/>
+                  <rect x="0.5" y="0.5" width="47" height="31" rx="3.5" stroke="#E5E7EB"/>
+                  <path d="M0 16H24C24 22 29 28 36 28H48V32H0V16Z" fill="#F48024"/>
+                  <circle cx="30" cy="16" r="6" fill="#F48024"/>
+                  <text x="8" y="18" font-family="Arial" font-size="8" font-weight="bold" fill="#000">DISCOVER</text>
+                </svg>
+              SVG
+            when "DINERS", "DINERS CLUB"
+              <<~SVG
+                <svg class="#{size}" viewBox="0 0 48 32" fill="none" xmlns="http://www.w3.org/2000/svg">
+                  <rect width="48" height="32" rx="4" fill="#0079BE"/>
+                  <circle cx="24" cy="16" r="9" fill="white"/>
+                  <path d="M19 16C19 13.2 20.8 10.9 23.3 10.2V21.8C20.8 21.1 19 18.8 19 16Z" fill="#0079BE"/>
+                  <path d="M29 16C29 18.8 27.2 21.1 24.7 21.8V10.2C27.2 10.9 29 13.2 29 16Z" fill="#0079BE"/>
+                </svg>
+              SVG
+            when "JCB"
+              <<~SVG
+                <svg class="#{size}" viewBox="0 0 48 32" fill="none" xmlns="http://www.w3.org/2000/svg">
+                  <rect width="48" height="32" rx="4" fill="#fff"/>
+                  <rect x="0.5" y="0.5" width="47" height="31" rx="3.5" stroke="#E5E7EB"/>
+                  <rect x="8" y="6" width="10" height="20" rx="2" fill="#0E4C96"/>
+                  <rect x="19" y="6" width="10" height="20" rx="2" fill="#E01536"/>
+                  <rect x="30" y="6" width="10" height="20" rx="2" fill="#00A14F"/>
+                  <text x="10" y="19" font-family="Arial" font-size="6" font-weight="bold" fill="white">J</text>
+                  <text x="22" y="19" font-family="Arial" font-size="6" font-weight="bold" fill="white">C</text>
+                  <text x="33" y="19" font-family="Arial" font-size="6" font-weight="bold" fill="white">B</text>
+                </svg>
+              SVG
+            when "UNIONPAY"
+              <<~SVG
+                <svg class="#{size}" viewBox="0 0 48 32" fill="none" xmlns="http://www.w3.org/2000/svg">
+                  <rect width="48" height="32" rx="4" fill="#1A4788"/>
+                  <path d="M12 6H20L18 26H10L12 6Z" fill="#E21836"/>
+                  <path d="M18 6H28L26 26H16L18 6Z" fill="#00447C"/>
+                  <path d="M26 6H36L34 26H24L26 6Z" fill="#007B84"/>
+                </svg>
+              SVG
+            else
+              # Generic card icon
+              <<~SVG
+                <svg class="#{size}" viewBox="0 0 48 32" fill="none" xmlns="http://www.w3.org/2000/svg">
+                  <rect width="48" height="32" rx="4" fill="#6B7280"/>
+                  <rect x="6" y="10" width="12" height="8" rx="1" fill="#9CA3AF"/>
+                  <rect x="6" y="22" width="20" height="2" rx="1" fill="#9CA3AF"/>
+                  <rect x="28" y="22" width="8" height="2" rx="1" fill="#9CA3AF"/>
+                </svg>
+              SVG
+            end
+
+      svg.html_safe
+    end
+  end
+end

data/app/helpers/paddle_rails/subscription_owner_helper.rb

@@ -0,0 +1,14 @@
+module PaddleRails
+  module SubscriptionOwnerHelper
+    def subscription_owner
+      authenticator = PaddleRails.configuration.subscription_owner_authenticator
+      return nil unless authenticator
+
+      instance_eval(&authenticator)
+    rescue StandardError => e
+      Rails.logger.error("PaddleRails::SubscriptionOwnerHelper: Error authenticating subscription owner: #{e.message}")
+      nil
+    end
+  end
+end
+

data/app/jobs/paddle_rails/application_job.rb

@@ -0,0 +1,4 @@
+module PaddleRails
+  class ApplicationJob < ActiveJob::Base
+  end
+end

data/app/jobs/paddle_rails/process_webhook_job.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module PaddleRails
+  # Background job for processing webhook events asynchronously.
+  #
+  # This job finds the webhook event, marks it as processing, calls the
+  # WebhookProcessor to handle the event, and updates the status accordingly.
+  #
+  # @example
+  #   PaddleRails::ProcessWebhookJob.perform_later(webhook_event.id)
+  class ProcessWebhookJob < ApplicationJob
+    queue_as :default
+
+    # Process a webhook event.
+    #
+    # @param event_id [Integer] The ID of the WebhookEvent to process
+    def perform(event_id)
+      event = WebhookEvent.find_by(id: event_id)
+      unless event
+        Rails.logger.error("PaddleRails::ProcessWebhookJob: WebhookEvent #{event_id} not found")
+        return
+      end
+
+      event.mark_as_processing!
+
+      begin
+        WebhookProcessor.process(event)
+        event.mark_as_processed!
+      rescue StandardError => e
+        error_message = "#{e.class}: #{e.message}\n#{e.backtrace.join("\n")}"
+        event.mark_as_failed!(error_message)
+        Rails.logger.error("PaddleRails::ProcessWebhookJob: Failed to process webhook #{event_id}: #{error_message}")
+        raise # Re-raise to trigger ActiveJob retry mechanism
+      end
+    end
+  end
+end
+

data/app/mailers/paddle_rails/application_mailer.rb

@@ -0,0 +1,6 @@
+module PaddleRails
+  class ApplicationMailer < ActionMailer::Base
+    default from: "from@example.com"
+    layout "mailer"
+  end
+end

data/app/models/concerns/paddle_rails/subscribable.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module PaddleRails
+  module Subscribable
+    extend ActiveSupport::Concern
+
+    included do
+      has_many :paddle_subscriptions, as: :owner, class_name: "PaddleRails::Subscription", dependent: :destroy
+      has_many :payments, as: :owner, class_name: "PaddleRails::Payment", dependent: :destroy
+    end
+
+    # Returns all subscriptions for the model instance
+    # @return [Array]
+    def subscriptions
+      paddle_subscriptions
+    end
+
+    # Returns the current active subscription or nil
+    # @return [PaddleRails::Subscription, nil]
+    def subscription
+      paddle_subscriptions.active.order(created_at: :desc).first
+    end
+
+    # Returns true if the model has a current active subscription
+    # @return [Boolean]
+    def subscription?
+      subscription.present?
+    end
+
+    # Create a Paddle checkout for this model instance
+    #
+    # @param paddle_price_id [String] The Paddle Price ID
+    # @param custom_data [Hash] Optional custom data to include
+    # @param options [Hash] Additional options for Paddle::Transaction.create
+    # @return [Paddle::Transaction]
+    def create_paddle_checkout(paddle_price_id:, custom_data: {}, **options)
+      PaddleRails::Checkout.create(
+        owner: self,
+        paddle_price_id: paddle_price_id,
+        custom_data: custom_data,
+        **options
+      )
+    end
+  end
+end
+

data/app/models/paddle_rails/application_record.rb

@@ -0,0 +1,5 @@
+module PaddleRails
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/paddle_rails/payment.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module PaddleRails
+  # Model representing a completed payment/transaction from Paddle.
+  #
+  # Stores payment data parsed from transaction.completed webhooks.
+  class Payment < ApplicationRecord
+    self.table_name = "paddle_rails_payments"
+
+    belongs_to :subscription, class_name: "PaddleRails::Subscription"
+    belongs_to :owner, polymorphic: true
+
+    validates :paddle_transaction_id, presence: true, uniqueness: true
+    validates :status, presence: true
+
+    scope :completed, -> { where(status: "completed") }
+    scope :recent, -> { order(billed_at: :desc) }
+
+    # Returns the amount in the payment's currency as a decimal.
+    # @return [Float]
+    def amount_in_currency
+      return 0.0 unless total
+      total / 100.0
+    end
+
+    # Returns a description of the payment based on line items.
+    # @return [String]
+    def description
+      return "Payment" unless details.is_a?(Hash)
+
+      line_items = details["line_items"] || details[:line_items] || []
+      return "Payment" if line_items.empty?
+
+      # Get the first line item's product name
+      first_item = line_items.first
+      product = first_item&.dig("product") || first_item&.dig(:product)
+      product_name = product&.dig("name") || product&.dig(:name)
+
+      product_name || "Payment"
+    end
+  end
+end
+

data/app/models/paddle_rails/price.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module PaddleRails
+  class Price < ApplicationRecord
+    self.table_name = "paddle_rails_prices"
+    self.inheritance_column = nil # Disable STI since we use 'type' for Paddle price type
+
+    belongs_to :product, class_name: "PaddleRails::Product"
+
+    validates :paddle_price_id, presence: true, uniqueness: true
+
+    scope :active, -> { joins(:product).where(paddle_rails_products: { status: "active" }).where(status: "active") }
+    scope :for_currency, ->(currency) { where(currency: currency) }
+
+    # Whether this price is active.
+    #
+    # Mirrors the `active` scope but operates on a single record.
+    #
+    # @return [Boolean]
+    def active?
+      status == "active"
+    end
+  end
+end
+

data/app/models/paddle_rails/product.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module PaddleRails
+  class Product < ApplicationRecord
+    self.table_name = "paddle_rails_products"
+    self.inheritance_column = nil # Disable STI since we use 'type' for Paddle product type
+
+    has_many :prices, class_name: "PaddleRails::Price", foreign_key: "product_id", dependent: :destroy
+
+    validates :paddle_product_id, presence: true, uniqueness: true
+
+    scope :active, -> { where(status: "active") }
+    scope :archived, -> { where(status: "archived") }
+  end
+end
+

data/app/models/paddle_rails/subscription.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module PaddleRails
+  class Subscription < ApplicationRecord
+    self.table_name = "paddle_rails_subscriptions"
+
+    # Statuses
+    ACTIVE = "active"
+    TRIALING = "trialing"
+    PAST_DUE = "past_due"
+    PAUSED = "paused"
+    CANCELED = "canceled"
+
+    belongs_to :owner, polymorphic: true
+    has_many :items, class_name: "PaddleRails::SubscriptionItem", dependent: :destroy
+    has_many :prices, through: :items, source: :price
+    has_many :products, through: :prices, source: :product
+    has_many :payments, class_name: "PaddleRails::Payment", dependent: :destroy
+
+    validates :paddle_subscription_id, presence: true, uniqueness: true
+    validates :status, presence: true
+
+    scope :active, -> { where(status: ACTIVE) }
+    scope :trialing, -> { where(status: TRIALING) }
+    scope :past_due, -> { where(status: PAST_DUE) }
+    scope :paused, -> { where(status: PAUSED) }
+    scope :canceled, -> { where(status: CANCELED) }
+
+    # Returns true if the subscription is active.
+    # @return [Boolean]
+    def active?
+      status == ACTIVE
+    end
+
+    # Returns true if the subscription is trialing.
+    # @return [Boolean]
+    def trialing?
+      status == TRIALING
+    end
+
+    # Returns true if the subscription is paused.
+    # @return [Boolean]
+    def paused?
+      status == PAUSED
+    end
+
+    # Returns true if the subscription is canceled.
+    # @return [Boolean]
+    def canceled?
+      status == CANCELED
+    end
+
+    # Returns true if the subscription is currently in a trial period.
+    # @return [Boolean]
+    def in_trial?
+      trial_ends_at.present? && trial_ends_at > Time.current
+    end
+
+    # Returns true if the current period is active (not expired).
+    # @return [Boolean]
+    def current_period_active?
+      current_period_end_at.present? && current_period_end_at > Time.current
+    end
+
+    # Returns true if the subscription is scheduled for cancellation at the end of the period.
+    # @return [Boolean]
+    def scheduled_for_cancellation?
+      scheduled_cancelation_at.present? && scheduled_cancelation_at > Time.current
+    end
+
+    # Returns the primary product for this subscription.
+    # Uses the first recurring item's product, or falls back to the first item's product.
+    # @return [PaddleRails::Product, nil]
+    def product
+      # Try to get product from first recurring item
+      first_recurring_item = items.find_by(recurring: true)
+      return first_recurring_item&.product if first_recurring_item
+
+      # Fallback to first item
+      items.first&.product
+    end
+
+    # Alias for backward compatibility
+    alias_method :plan, :product
+  end
+end
+

data/app/models/paddle_rails/subscription_item.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module PaddleRails
+  # Model representing an individual item within a subscription.
+  #
+  # A subscription can have multiple items (e.g., base plan + addons).
+  # Each item links to a specific price and tracks its quantity and status.
+  class SubscriptionItem < ApplicationRecord
+    self.table_name = "paddle_rails_subscription_items"
+
+    belongs_to :subscription, class_name: "PaddleRails::Subscription"
+    belongs_to :price, class_name: "PaddleRails::Price"
+    belongs_to :product, class_name: "PaddleRails::Product"
+    # Alias for backward compatibility
+    alias_method :plan, :product
+
+    validates :subscription_id, presence: true
+    validates :price_id, presence: true
+    validates :quantity, presence: true, numericality: { greater_than: 0 }
+    validates :status, presence: true
+
+    # Returns true if this item is active.
+    # @return [Boolean]
+    def active?
+      status == "active"
+    end
+
+    # Returns true if this item is recurring.
+    # @return [Boolean]
+    def recurring?
+      recurring == true
+    end
+  end
+end
+

data/app/models/paddle_rails/webhook_event.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module PaddleRails
+  # Model for storing incoming webhook events from Paddle.
+  #
+  # Webhooks are stored with their raw payload and processed asynchronously
+  # via background jobs to ensure reliability and allow for replayability.
+  #
+  # @example
+  #   event = PaddleRails::WebhookEvent.create!(
+  #     external_id: "evt_123",
+  #     event_type: "subscription.created",
+  #     payload: { ... },
+  #     status: "pending"
+  #   )
+  class WebhookEvent < ApplicationRecord
+    self.table_name = "paddle_rails_webhook_events"
+
+    # Status values
+    PENDING = "pending"
+    PROCESSING = "processing"
+    PROCESSED = "processed"
+    FAILED = "failed"
+
+    validates :external_id, presence: true, uniqueness: true
+    validates :event_type, presence: true
+    validates :payload, presence: true
+    validates :status, presence: true, inclusion: { in: [PENDING, PROCESSING, PROCESSED, FAILED] }
+
+    scope :pending, -> { where(status: PENDING) }
+    scope :processing, -> { where(status: PROCESSING) }
+    scope :processed, -> { where(status: PROCESSED) }
+    scope :failed, -> { where(status: FAILED) }
+
+    # Mark the event as processing
+    def mark_as_processing!
+      update!(status: PROCESSING)
+    end
+
+    # Mark the event as processed
+    def mark_as_processed!
+      update!(status: PROCESSED, processed_at: Time.current)
+    end
+
+    # Mark the event as failed with an error message
+    def mark_as_failed!(error_message)
+      update!(status: FAILED, processing_errors: error_message)
+    end
+  end
+end
+

data/app/presenters/paddle_rails/payment_presenter.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module PaddleRails
+  class PaymentPresenter
+    attr_reader :payment
+
+    delegate :id, :status, :invoice_id, :invoice_number, :paddle_transaction_id, to: :payment
+
+    def initialize(payment)
+      @payment = payment
+    end
+
+    # Returns the formatted date of the payment.
+    # @return [String]
+    def date
+      return "N/A" unless payment.billed_at
+      payment.billed_at.strftime("%b %d, %Y")
+    end
+
+    # Returns a description of the payment.
+    # @return [String]
+    def description
+      payment.description
+    end
+
+    # Returns the formatted amount with currency symbol.
+    # @return [String]
+    def amount
+      return "N/A" unless payment.total
+      amount_value = payment.amount_in_currency
+      currency_symbol = currency_symbol_for(payment.currency)
+      "#{currency_symbol}#{format('%.2f', amount_value.abs)}"
+    end
+
+    # Returns the status label for display.
+    # @return [String]
+    def status_label
+      case payment.status
+      when "completed"
+        "Paid"
+      when "pending"
+        "Pending"
+      when "failed"
+        "Failed"
+      else
+        payment.status.titleize
+      end
+    end
+
+    # Returns true if the payment is a credit (negative amount).
+    # @return [Boolean]
+    def credit?
+      payment.total && payment.total < 0
+    end
+
+    # Returns the status badge class based on payment status.
+    # @return [String]
+    def status_badge_class
+      case payment.status
+      when "completed"
+        credit? ? "bg-amber-50 text-amber-700 ring-1 ring-inset ring-amber-600/20" : "bg-emerald-50 text-emerald-700 ring-1 ring-inset ring-emerald-600/20"
+      when "pending"
+        "bg-yellow-50 text-yellow-700 ring-1 ring-inset ring-yellow-600/20"
+      when "failed"
+        "bg-red-50 text-red-700 ring-1 ring-inset ring-red-600/20"
+      else
+        "bg-slate-50 text-slate-700 ring-1 ring-inset ring-slate-600/20"
+      end
+    end
+
+    # Returns true if invoice is available.
+    # @return [Boolean]
+    def has_invoice?
+      paddle_transaction_id.present?
+    end
+
+    private
+
+    # Returns the currency symbol for a given currency code.
+    # @param currency [String] The currency code (e.g., "USD", "EUR")
+    # @return [String]
+    def currency_symbol_for(currency)
+      case currency&.upcase
+      when "EUR"
+        "€"
+      when "GBP"
+        "£"
+      when "USD"
+        "$"
+      else
+        currency || "$"
+      end
+    end
+  end
+end
+