paddle_rails 0.1.0

data/app/views/paddle_rails/shared/configuration_error.html.erb

@@ -0,0 +1,94 @@
+<div class="max-w-2xl mx-auto p-8 md:p-12">
+  <div class="bg-red-50 border border-red-200 rounded-lg p-6 md:p-8">
+    <!-- Error Icon and Title -->
+    <div class="flex items-start gap-4 mb-6">
+      <div class="flex-shrink-0">
+        <svg class="w-6 h-6 text-red-600" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z" />
+        </svg>
+      </div>
+      <div class="flex-1">
+        <h1 class="text-xl font-medium text-gray-900 mb-2">PaddleRails Configuration Error</h1>
+        <p class="text-gray-600 text-sm leading-relaxed">
+          Your PaddleRails integration is not properly configured. Please complete the following steps to set up the gem.
+        </p>
+      </div>
+    </div>
+
+    <!-- Checklist -->
+    <div class="space-y-4">
+      <h2 class="text-sm font-medium text-gray-900 mb-3">Configuration Checklist:</h2>
+      
+      <div class="space-y-3">
+        <!-- API Keys / Environment Variables -->
+        <div class="flex items-start gap-3">
+          <div class="flex-shrink-0 mt-0.5">
+            <svg class="w-5 h-5 text-gray-400" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+              <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 12l2 2 4-4m6 2a9 9 0 11-18 0 9 9 0 0118 0z" />
+            </svg>
+          </div>
+          <div class="flex-1">
+            <h3 class="text-sm font-medium text-gray-900 mb-1">API Keys / Environment Variables</h3>
+            <p class="text-sm text-gray-600 mb-2">
+              Set the following environment variables in your application:
+            </p>
+            <ul class="list-disc list-inside text-sm text-gray-600 space-y-1 ml-4">
+              <li><code class="bg-gray-100 px-1.5 py-0.5 rounded text-xs font-mono">PADDLE_API_KEY</code> - Your Paddle API key</li>
+              <li><code class="bg-gray-100 px-1.5 py-0.5 rounded text-xs font-mono">PADDLE_PUBLIC_TOKEN</code> - Your Paddle public token</li>
+              <li><code class="bg-gray-100 px-1.5 py-0.5 rounded text-xs font-mono">PADDLE_ENVIRONMENT</code> - Set to "production" or "sandbox"</li>
+            </ul>
+          </div>
+        </div>
+
+        <!-- Setup subscription_owner -->
+        <div class="flex items-start gap-3">
+          <div class="flex-shrink-0 mt-0.5">
+            <svg class="w-5 h-5 text-gray-400" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+              <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 12l2 2 4-4m6 2a9 9 0 11-18 0 9 9 0 0118 0z" />
+            </svg>
+          </div>
+          <div class="flex-1">
+            <h3 class="text-sm font-medium text-gray-900 mb-1">Setup subscription_owner</h3>
+            <p class="text-sm text-gray-600 mb-2">
+              Configure the <code class="bg-gray-100 px-1.5 py-0.5 rounded text-xs font-mono">subscription_owner_authenticator</code> in your PaddleRails initializer:
+            </p>
+            <pre class="bg-gray-100 rounded p-3 text-xs font-mono text-gray-800 overflow-x-auto"><code>PaddleRails.configure do |config|
+  config.subscription_owner_authenticator do
+    current_user || warden.authenticate!(scope: :user)
+  end
+end</code></pre>
+          </div>
+        </div>
+
+        <!-- Add Subscribable concern -->
+        <div class="flex items-start gap-3">
+          <div class="flex-shrink-0 mt-0.5">
+            <svg class="w-5 h-5 text-gray-400" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+              <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 12l2 2 4-4m6 2a9 9 0 11-18 0 9 9 0 0118 0z" />
+            </svg>
+          </div>
+          <div class="flex-1">
+            <h3 class="text-sm font-medium text-gray-900 mb-1">Add Subscribable concern to subscription owner</h3>
+            <p class="text-sm text-gray-600 mb-2">
+              Include the <code class="bg-gray-100 px-1.5 py-0.5 rounded text-xs font-mono">PaddleRails::Subscribable</code> concern in your subscription owner model:
+            </p>
+            <pre class="bg-gray-100 rounded p-3 text-xs font-mono text-gray-800 overflow-x-auto"><code>class User < ApplicationRecord
+  include PaddleRails::Subscribable
+end</code></pre>
+          </div>
+        </div>
+      </div>
+    </div>
+
+    <!-- Documentation Link -->
+    <div class="mt-6 pt-6 border-t border-red-200">
+      <p class="text-sm text-gray-600">
+        For more information, see the 
+        <a href="https://github.com/kjellberg/paddle_rails" class="text-red-600 hover:text-red-700 font-medium underline" target="_blank" rel="noopener noreferrer">
+          PaddleRails documentation
+        </a>.
+      </p>
+    </div>
+  </div>
+</div>
+

data/config/routes.rb

@@ -0,0 +1,13 @@
+PaddleRails::Engine.routes.draw do
+  root "dashboard#show"
+  get "onboarding", to: "onboarding#show", as: :onboarding
+  post "onboarding/checkout", to: "onboarding#create_checkout", as: :onboarding_checkout
+  get "checkout", to: "checkout#show", as: :checkout
+  get "checkout/check_status/:transaction_id", to: "checkout#check_status", as: :check_transaction_status
+  post "checkout/update_payment_method", to: "checkout#update_payment_method", as: :update_payment_method
+  post "subscriptions/revoke_cancellation", to: "subscriptions#revoke_cancellation", as: :revoke_subscription_cancellation
+  post "subscriptions/cancel", to: "subscriptions#cancel", as: :cancel_subscription
+  post "subscriptions/change_plan", to: "subscriptions#change_plan", as: :change_subscription_plan
+  get "payments/:id/invoice", to: "payments#view_invoice", as: :view_payment_invoice
+  get "payments/:id/download", to: "payments#download_invoice", as: :download_payment_invoice
+end

data/db/migrate/20251124180624_create_paddle_rails_subscription_plans.rb

@@ -0,0 +1,18 @@
+class CreatePaddleRailsSubscriptionPlans < ActiveRecord::Migration[8.1]
+  def change
+    create_table :paddle_rails_subscription_plans do |t|
+      t.string :paddle_product_id, null: false
+      t.string :name
+      t.text :description
+      t.string :status
+      t.string :type
+      t.string :tax_category
+      t.string :image_url
+      t.json :custom_data
+
+      t.timestamps
+    end
+
+    add_index :paddle_rails_subscription_plans, :paddle_product_id, unique: true
+  end
+end

data/db/migrate/20251124180817_create_paddle_rails_subscription_prices.rb

@@ -0,0 +1,26 @@
+class CreatePaddleRailsSubscriptionPrices < ActiveRecord::Migration[8.1]
+  def change
+    create_table :paddle_rails_subscription_prices do |t|
+      t.references :subscription_plan, null: false, foreign_key: { to_table: :paddle_rails_subscription_plans }
+      t.string :paddle_price_id, null: false
+      t.string :currency
+      t.integer :unit_price
+      t.string :billing_interval
+      t.integer :billing_interval_count
+      t.integer :trial_days
+      t.string :type
+      t.string :name
+      t.text :description
+      t.string :status
+      t.string :tax_mode
+      t.integer :quantity_minimum
+      t.integer :quantity_maximum
+      t.json :trial_period
+      t.json :custom_data
+
+      t.timestamps
+    end
+
+    add_index :paddle_rails_subscription_prices, :paddle_price_id, unique: true
+  end
+end

data/db/migrate/20251127221947_create_paddle_rails_webhook_events.rb

@@ -0,0 +1,19 @@
+class CreatePaddleRailsWebhookEvents < ActiveRecord::Migration[8.1]
+  def change
+    create_table :paddle_rails_webhook_events do |t|
+      t.string :external_id, null: false
+      t.string :event_type, null: false
+      t.json :payload, null: false
+      t.string :status, null: false, default: "pending"
+      t.text :processing_errors
+      t.datetime :processed_at
+
+      t.timestamps
+    end
+
+    add_index :paddle_rails_webhook_events, :external_id, unique: true
+    add_index :paddle_rails_webhook_events, :event_type
+    add_index :paddle_rails_webhook_events, :status
+  end
+end
+

data/db/migrate/20251128135831_create_paddle_rails_subscriptions.rb

@@ -0,0 +1,21 @@
+class CreatePaddleRailsSubscriptions < ActiveRecord::Migration[8.1]
+  def change
+    create_table :paddle_rails_subscriptions do |t|
+      t.references :owner, polymorphic: true, null: false, index: true
+      t.string :paddle_subscription_id, null: false
+      t.string :paddle_price_id
+      t.string :status
+      t.datetime :current_period_end_at
+      t.datetime :trial_ends_at
+      t.json :raw_payload
+      t.references :subscription_price, foreign_key: { to_table: :paddle_rails_subscription_prices }, index: true
+
+      t.timestamps
+    end
+
+    add_index :paddle_rails_subscriptions, :paddle_subscription_id, unique: true
+    add_index :paddle_rails_subscriptions, :paddle_price_id
+    add_index :paddle_rails_subscriptions, :status
+  end
+end
+

data/db/migrate/20251128142327_create_paddle_rails_subscription_items.rb

@@ -0,0 +1,16 @@
+class CreatePaddleRailsSubscriptionItems < ActiveRecord::Migration[8.1]
+  def change
+    create_table :paddle_rails_subscription_items do |t|
+      t.references :subscription, foreign_key: { to_table: :paddle_rails_subscriptions }, null: false, index: true
+      t.references :subscription_price, foreign_key: { to_table: :paddle_rails_subscription_prices }, null: false, index: true
+      t.integer :quantity, default: 1
+      t.string :status
+      t.boolean :recurring, default: false
+
+      t.timestamps
+    end
+
+    add_index :paddle_rails_subscription_items, [:subscription_id, :subscription_price_id], unique: true, name: "index_subscription_items_on_subscription_and_price"
+  end
+end
+

data/db/migrate/20251128151334_remove_paddle_price_id_from_subscriptions.rb

@@ -0,0 +1,7 @@
+class RemovePaddlePriceIdFromSubscriptions < ActiveRecord::Migration[8.1]
+  def change
+    remove_index :paddle_rails_subscriptions, :paddle_price_id, if_exists: true
+    remove_column :paddle_rails_subscriptions, :paddle_price_id, :string, if_exists: true
+  end
+end
+

data/db/migrate/20251128151401_rename_subscription_plans_to_products.rb

@@ -0,0 +1,6 @@
+class RenameSubscriptionPlansToProducts < ActiveRecord::Migration[8.1]
+  def change
+    rename_table :paddle_rails_subscription_plans, :paddle_rails_subscription_products
+  end
+end
+

data/db/migrate/20251128151402_rename_subscription_plan_id_to_subscription_product_id.rb

@@ -0,0 +1,13 @@
+class RenameSubscriptionPlanIdToSubscriptionProductId < ActiveRecord::Migration[8.1]
+  def change
+    # Remove old foreign key
+    remove_foreign_key :paddle_rails_subscription_prices, :paddle_rails_subscription_plans if foreign_key_exists?(:paddle_rails_subscription_prices, :paddle_rails_subscription_plans)
+    
+    # Rename the column
+    rename_column :paddle_rails_subscription_prices, :subscription_plan_id, :subscription_product_id
+    
+    # Add new foreign key
+    add_foreign_key :paddle_rails_subscription_prices, :paddle_rails_subscription_products, column: :subscription_product_id
+  end
+end
+

data/db/migrate/20251128151453_remove_subscription_price_id_from_subscriptions.rb

@@ -0,0 +1,8 @@
+class RemoveSubscriptionPriceIdFromSubscriptions < ActiveRecord::Migration[8.1]
+  def change
+    remove_foreign_key :paddle_rails_subscriptions, :paddle_rails_subscription_prices, if_exists: true
+    remove_index :paddle_rails_subscriptions, :subscription_price_id, if_exists: true
+    remove_column :paddle_rails_subscriptions, :subscription_price_id, :integer, if_exists: true
+  end
+end
+

data/db/migrate/20251128151501_add_subscription_product_id_to_subscription_items.rb

@@ -0,0 +1,8 @@
+class AddSubscriptionProductIdToSubscriptionItems < ActiveRecord::Migration[8.1]
+  def change
+    add_reference :paddle_rails_subscription_items, :subscription_product, 
+                  foreign_key: { to_table: :paddle_rails_subscription_products }, 
+                  index: true
+  end
+end
+

data/db/migrate/20251128152025_remove_paddle_item_id_from_subscription_items.rb

@@ -0,0 +1,6 @@
+class RemovePaddleItemIdFromSubscriptionItems < ActiveRecord::Migration[8.1]
+  def change
+    remove_column :paddle_rails_subscription_items, :paddle_item_id, :string, if_exists: true
+  end
+end
+

data/db/migrate/20251128212046_rename_subscription_products_to_products.rb

@@ -0,0 +1,6 @@
+class RenameSubscriptionProductsToProducts < ActiveRecord::Migration[8.1]
+  def change
+    rename_table :paddle_rails_subscription_products, :paddle_rails_products
+  end
+end
+

data/db/migrate/20251128212047_rename_subscription_prices_to_prices.rb

@@ -0,0 +1,6 @@
+class RenameSubscriptionPricesToPrices < ActiveRecord::Migration[8.1]
+  def change
+    rename_table :paddle_rails_subscription_prices, :paddle_rails_prices
+  end
+end
+

data/db/migrate/20251128212053_rename_subscription_product_id_to_product_id_in_prices.rb

@@ -0,0 +1,13 @@
+class RenameSubscriptionProductIdToProductIdInPrices < ActiveRecord::Migration[8.1]
+  def change
+    # Remove old foreign key
+    remove_foreign_key :paddle_rails_prices, :paddle_rails_subscription_products, if_exists: true
+    
+    # Rename the column
+    rename_column :paddle_rails_prices, :subscription_product_id, :product_id
+    
+    # Add new foreign key
+    add_foreign_key :paddle_rails_prices, :paddle_rails_products, column: :product_id
+  end
+end
+

data/db/migrate/20251128212054_rename_fks_in_subscription_items.rb

@@ -0,0 +1,20 @@
+class RenameFksInSubscriptionItems < ActiveRecord::Migration[8.1]
+  def change
+    # Remove old foreign keys
+    remove_foreign_key :paddle_rails_subscription_items, :paddle_rails_subscription_prices, if_exists: true
+    remove_foreign_key :paddle_rails_subscription_items, :paddle_rails_subscription_products, if_exists: true
+    
+    # Rename the columns
+    rename_column :paddle_rails_subscription_items, :subscription_price_id, :price_id
+    rename_column :paddle_rails_subscription_items, :subscription_product_id, :product_id
+    
+    # Update the unique index
+    remove_index :paddle_rails_subscription_items, name: "index_subscription_items_on_subscription_and_price", if_exists: true
+    add_index :paddle_rails_subscription_items, [:subscription_id, :price_id], unique: true, name: "index_subscription_items_on_subscription_and_price"
+    
+    # Add new foreign keys
+    add_foreign_key :paddle_rails_subscription_items, :paddle_rails_prices, column: :price_id
+    add_foreign_key :paddle_rails_subscription_items, :paddle_rails_products, column: :product_id
+  end
+end
+

data/db/migrate/20251128220016_add_scheduled_cancelation_at_to_subscriptions.rb

@@ -0,0 +1,6 @@
+class AddScheduledCancelationAtToSubscriptions < ActiveRecord::Migration[8.1]
+  def change
+    add_column :paddle_rails_subscriptions, :scheduled_cancelation_at, :datetime
+  end
+end
+

data/db/migrate/20251129121336_add_payment_method_to_subscriptions.rb

@@ -0,0 +1,10 @@
+class AddPaymentMethodToSubscriptions < ActiveRecord::Migration[8.1]
+  def change
+    add_column :paddle_rails_subscriptions, :payment_method_id, :string
+    add_column :paddle_rails_subscriptions, :payment_method_type, :string
+    add_column :paddle_rails_subscriptions, :payment_method_details, :json
+
+    add_index :paddle_rails_subscriptions, :payment_method_id
+  end
+end
+

data/db/migrate/20251129222345_create_paddle_rails_payments.rb

@@ -0,0 +1,24 @@
+class CreatePaddleRailsPayments < ActiveRecord::Migration[8.1]
+  def change
+    create_table :paddle_rails_payments do |t|
+      t.references :subscription, null: false, foreign_key: { to_table: :paddle_rails_subscriptions }
+      t.references :owner, polymorphic: true, null: false
+      t.string :paddle_transaction_id, null: false
+      t.string :invoice_id
+      t.string :invoice_number
+      t.string :status, null: false
+      t.string :origin  # subscription_recurring, subscription_update, etc.
+      t.integer :total  # total in cents (incl. tax)
+      t.integer :tax
+      t.integer :subtotal
+      t.string :currency
+      t.datetime :billed_at
+      t.json :details  # store line_items and other details
+      t.json :raw_payload
+      t.timestamps
+    end
+
+    add_index :paddle_rails_payments, :paddle_transaction_id, unique: true
+    add_index :paddle_rails_payments, [:owner_type, :owner_id]
+  end
+end

data/lib/paddle_rails/checkout.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+module PaddleRails
+  # Service object for creating Paddle transactions (checkouts).
+  #
+  # Wraps {Paddle::Transaction.create} and is responsible for:
+  # - Building the items array from a Paddle price ID.
+  # - Merging the owner's **signed** GlobalID into the `custom_data` hash under
+  #   the \"owner_sgid\" key, so the owner reference is tamper‑evident.
+  # - Returning the resulting {Paddle::Transaction} instance.
+  #
+  # @example Basic usage
+  #   checkout = PaddleRails::Checkout.create(
+  #     owner: user,
+  #     paddle_price_id: "pri_123"
+  #   )
+  #
+  #   redirect_to checkout.details.checkout.url, allow_other_host: true
+  #
+  # @example With additional custom data
+  #   checkout = PaddleRails::Checkout.create(
+  #     owner: user,
+  #     paddle_price_id: "pri_123",
+  #     custom_data: { foo: "bar" }
+  #   )
+  #
+  #   # custom_data will be merged with a signed owner SGID:
+  #   # { \"owner_sgid\" => user.to_sgid_param(for: \"paddle_rails_owner\"), \"foo\" => \"bar\" }
+  class Checkout
+    attr_reader :owner, :paddle_price_id, :custom_data, :checkout_url
+
+    # Create a new checkout (transaction) for a given owner and price.
+    #
+    # @param owner [Object] the subscription owner (e.g. User) – must support `to_gid_param`
+    # @param paddle_price_id [String] the Paddle Price ID used for the transaction
+    # @param custom_data [Hash] optional extra metadata to merge into `custom_data`
+    # @param checkout_url [String, nil] optional URL that Paddle should use for the checkout
+    # @return [Paddle::Transaction] the created transaction
+    def self.create(owner:, paddle_price_id:, custom_data: {}, checkout_url: nil)
+      new(
+        owner: owner,
+        paddle_price_id: paddle_price_id,
+        custom_data: custom_data,
+        checkout_url: checkout_url
+      ).create
+    end
+
+    # Convenience helper that creates a checkout and returns only the hosted URL.
+    #
+    # @param owner [Object] the subscription owner (e.g. User)
+    # @param paddle_price_id [String] the Paddle Price ID used for the transaction
+    # @param custom_data [Hash] optional extra metadata to merge into `custom_data`
+    # @param checkout_url [String, nil] optional URL that Paddle should use for the checkout
+    # @return [String, nil] the checkout URL, if present
+    def self.url_for(owner:, paddle_price_id:, custom_data: {}, checkout_url: nil)
+      transaction = create(
+        owner: owner,
+        paddle_price_id: paddle_price_id,
+        custom_data: custom_data,
+        checkout_url: checkout_url
+      )
+
+      extract_url(transaction)
+    end
+
+    # @param owner [Object]
+    # @param paddle_price_id [String]
+    # @param custom_data [Hash]
+    # @param checkout_url [String, nil]
+    def initialize(owner:, paddle_price_id:, custom_data: {}, checkout_url: nil)
+      @owner = owner
+      @paddle_price_id = paddle_price_id
+      @custom_data = custom_data || {}
+      @checkout_url = checkout_url
+    end
+
+    # Perform the transaction creation against the Paddle API.
+    #
+    # @return [Paddle::Transaction]
+    def create
+      attrs = {
+        items: [{ price_id: paddle_price_id, quantity: 1 }],
+        custom_data: merged_custom_data
+      }
+
+      if checkout_url
+        attrs[:checkout] = { url: normalize_checkout_url_for_paddle(checkout_url) }
+      end
+
+      Paddle::Transaction.create(**attrs)
+    end
+
+    private
+
+    def merged_custom_data
+      base = { "owner_sgid" => owner_sgid }
+      # Stringify keys to keep custom_data consistent with Paddle expectations
+      base.merge(stringified_custom_data)
+    end
+
+    # Build a signed GlobalID string for the owner that can be verified later.
+    #
+    # NOTE: Webhook processing is not implemented yet, but when it is, you
+    # should resolve this using:
+    #
+    #   GlobalID::Locator.locate_signed(owner_sgid, for: \"paddle_rails_owner\")
+    #
+    # @return [String]
+    def owner_sgid
+      if owner.respond_to?(:to_sgid_param)
+        owner.to_sgid_param(for: "paddle_rails_owner")
+      elsif defined?(GlobalID::SignedGlobalID)
+        GlobalID::SignedGlobalID.create(owner, for: "paddle_rails_owner").to_s
+      else
+        owner.to_s
+      end
+    end
+
+    def stringified_custom_data
+      custom_data.to_h.transform_keys(&:to_s)
+    end
+
+    # In development, convert all http:// URLs to https:// for
+    # checkout URLs to avoid Paddle's domain approval error.
+    #
+    # @param url [String, nil]
+    # @return [String, nil]
+    def normalize_checkout_url_for_paddle(url)
+      return url unless url
+      return url unless defined?(Rails) && Rails.env.development?
+
+      url.sub(/\Ahttp:\/\//, "https://")
+    end
+
+    # Extract the hosted checkout URL from a Paddle::Transaction.
+    #
+    # The Paddle gem currently exposes this via an internal OpenStruct
+    # where the raw attributes live in `checkout.table`.
+    #
+    # @param transaction [Paddle::Transaction, nil]
+    # @return [String, nil]
+    def self.extract_url(transaction)
+      return nil unless transaction
+
+      url = nil
+
+      # Preferred: transaction.checkout.table[:url]
+      if transaction.respond_to?(:checkout) && transaction.checkout
+        checkout = transaction.checkout
+        if checkout.respond_to?(:table)
+          url = checkout.table[:url] || checkout.table["url"]
+        end
+
+        url ||= checkout.url if checkout.respond_to?(:url)
+      end
+
+      # Fallback: nested details.checkout.url (for other Paddle shapes)
+      if url.nil? && transaction.respond_to?(:details) && transaction.details&.respond_to?(:checkout)
+        nested = transaction.details.checkout
+        url = nested.url if nested.respond_to?(:url)
+      end
+
+      rewrite_localhost_url(url)
+    end
+
+    # In development, Paddle may return https URLs which
+    # Rails typically serves over plain HTTP. Normalize those so we
+    # don't hit mixed-scheme issues in local setups.
+    #
+    # @param url [String, nil]
+    # @return [String, nil]
+    def self.rewrite_localhost_url(url)
+      return url unless url
+      return url unless defined?(Rails) && Rails.env.development?
+
+      url.sub(/\Ahttps:\/\//, "http://")
+    end
+  end
+end
+
+