nocheckout 0.1.4 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1940078d7a818e06033361f4c961bb23fed76c724f7273d2c9cfc7e24cf509b8
-  data.tar.gz: 48a81f066625fd4d946358f5dd010e15703b59ad482e860493c48b28a56c95c4
+  metadata.gz: 36cc99edab4e1790d54150c8528af4a8909e9894c08716ee9d6893a4966772da
+  data.tar.gz: e909fba5b3d5dff31373ef0f268fabf3fa53297ea77d1fd09f7f13ad5147e541
 SHA512:
-  metadata.gz: 7fb7484da98f62bef30539907231a8429f690419c9d0f0c7ac9cbf78ac9de62630391c82978dd6d1d0a9a89d3b7ffd326d3ff1858c6b7ea19afeda83d93504a9
-  data.tar.gz: 7beaf4fe8e90dda879b1107ee8173e0cd16ebf771f2fb1d53de35dcd90abf20f03333335b2443a87c2275f5f92c8704625c300ad40c19c5e651c7dbaf871ed14
+  metadata.gz: b03567f074c779298ed5d3ae1b2e3bf81146b169f7002ce81ab6b8a75e399dd26c8b54833cdc3469cbe636c368365d5225c30d191341a317b22beee1f411018a
+  data.tar.gz: 05e63b688befdcf2f12274e7b5daac3d9ff07cf8f90749d86e08cc952947d98773d5bc9e3019f3d44d902bcbe9eb0be441430952a8101dd0cbc6ac93a394b67c

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 ## [Unreleased]
 
+### Changed
+- **BREAKING**: Refactored `CheckoutSessionsController` from a base class to a composable module
+  - `NoCheckout::Stripe::CheckoutSession` is now a concern/module that you include in your controllers
+  - Controllers no longer need to inherit from `NoCheckout::Stripe::CheckoutSessionsController`
+  - Provides more flexibility - controllers can inherit from any base class in your app
+  - All protected methods (`create_checkout_session`, `retrieve_checkout_session`, `callback_url`, etc.) remain the same
+  - `@checkout_session` is still automatically assigned via before_action callbacks
+  - See README for migration examples
+
+### Added
+- Comprehensive test suite for `CheckoutSession` module and `CheckoutSessionsController`
+- Architecture documentation in README explaining the module-based design pattern
+
 ## [0.1.0] - 2023-09-08
 
 - Initial release

data/Gemfile.lock

@@ -112,6 +112,7 @@ GEM
       net-smtp
     marcel (1.0.4)
     mini_mime (1.1.5)
+    mini_portile2 (2.8.9)
     minitest (5.25.1)
     net-imap (0.4.16)
       date
@@ -123,6 +124,9 @@ GEM
     net-smtp (0.5.0)
       net-protocol
     nio4r (2.7.3)
+    nokogiri (1.16.7)
+      mini_portile2 (~> 2.8.2)
+      racc (~> 1.4)
     nokogiri (1.16.7-arm64-darwin)
       racc (~> 1.4)
     nokogiri (1.16.7-x86_64-linux)
@@ -239,6 +243,7 @@ GEM
 PLATFORMS
   arm64-darwin-22
   arm64-darwin-23
+  arm64-darwin-24
   x86_64-linux
 
 DEPENDENCIES
@@ -248,4 +253,4 @@ DEPENDENCIES
   standard (~> 1.3)
 
 BUNDLED WITH
-   2.4.8
+   2.6.5

data/README.md

@@ -34,22 +34,32 @@ Stripe.api_key = Rails.configuration.stripe[:secret_key]
 
 [Stripe Checkout Sessions](https://stripe.com/docs/api/checkout/sessions) send users from your website to a branded stripe.com page where they can enter their credit card details and complete the purchase. Once the purchase is complete, the user is redirected back to your website.
 
-The NoCheckout::CheckoutSessionsController handles the interface between Stripe and your Rails application and tries to be as small as possible.
+NoCheckout provides a `CheckoutSession` module that you can include in your controllers to handle the interface between Stripe and your Rails application. The module is designed to be minimal and flexible.
 
-To get started, create a base CheckoutSessionsController that maps the Users from your application with [Stripe Customers](https://stripe.com/docs/api/customers).
+To get started, create a controller and include the `NoCheckout::Stripe::CheckoutSession` module. The module provides:
+
+- **`#new` action**: Creates a Checkout Session and redirects users to Stripe
+- **`#show` action**: Handles the callback when users return from Stripe
+- **Protected methods**: `create_checkout_session`, `retrieve_checkout_session`, `callback_url`, `success_url`, `cancel_url`
+
+The module automatically sets up `before_action` callbacks that:
+- Call `create_checkout_session` and assign it to `@checkout_session` before the `new` action
+- Call `retrieve_checkout_session` and assign it to `@checkout_session` before the `show` action
 
 ### Create user record after checkout is complete
 
 This approach creates a new user record after the checkout is complete with the name and email they give during the Stripe checkout process.
 
 ```ruby
-class PaymentsController < NoCheckout::Stripe::CheckoutSessionsController
-  STRIPE_PRICE = "test_price_..."
+class PaymentsController < ApplicationController
+  include NoCheckout::Stripe::CheckoutSession
+
+  STRIPE_PRICE = "price_..."
 
   def show
-    # Retrieve info from Stripe
-    customer = Stripe::Customer.retrieve checkout_session.customer
-    subscription = Stripe::Subscription.retrieve checkout_session.subscription
+    # @checkout_session is automatically assigned by the module
+    customer = Stripe::Customer.retrieve @checkout_session.customer
+    subscription = Stripe::Subscription.retrieve @checkout_session.subscription
 
     # Do stuff with Stripe info
     user = User.find_or_create_by email: customer.email
@@ -76,7 +86,7 @@ class PaymentsController < NoCheckout::Stripe::CheckoutSessionsController
 end
 ```
 
-Then, for each product you want to offer, create a controller and inherit the `CheckoutSessionsController`.
+Then, for each product you want to offer, create a controller and include the `CheckoutSession` module. You can also inherit from a base controller:
 
 ```ruby
 class PlusCheckoutSessionsController < PaymentsController
@@ -84,34 +94,70 @@ class PlusCheckoutSessionsController < PaymentsController
 end
 ```
 
+Or include the module directly:
+
+```ruby
+class ProCheckoutSessionsController < ApplicationController
+  include NoCheckout::Stripe::CheckoutSession
+  
+  STRIPE_PRICE = "price_..."
+
+  def show
+    # Handle callback after successful checkout
+    redirect_to dashboard_url, notice: "Welcome to Pro!"
+  end
+
+  protected
+    def create_checkout_session
+      super \
+        mode: "subscription",
+        line_items: [{price: self.class::STRIPE_PRICE, quantity: 1}]
+    end
+end
+```
+
 There's a lot of different ways you can wire up the controllers depending on how many Stripe prices are in your application. This README assumes you're selling just a few products, so the prices are hard coded as constants in the controller. This could easily be populated from a database.
 
 ### Create a user record before checkout is complete
 
 ```ruby
-class PaymentsController < NoCheckout::Stripe::CheckoutSessionsController
-  before_action :authorize_user # Loads a current_user
+class PaymentsController < ApplicationController
+  include NoCheckout::Stripe::CheckoutSession
+  
+  before_action :authenticate_user! # Loads a current_user
 
-  STRIPE_PRICE = "test_price_..."
+  STRIPE_PRICE = "price_..."
 
   def show
-    customer = Stripe::Customer.retrieve checkout_session.customer
-    subscription = Stripe::Subscription.retrieve checkout_session.subscription
+    # @checkout_session is automatically assigned by the module
+    customer = Stripe::Customer.retrieve @checkout_session.customer
+    subscription = Stripe::Subscription.retrieve @checkout_session.subscription
 
-    # Do stuff with Stripe info
+    # Update user with subscription info
+    current_user.update!(
+      stripe_customer_id: customer.id,
+      stripe_subscription_id: subscription.id
+    )
 
-    redirect_to root_url
+    redirect_to root_url, notice: "Subscription activated!"
   end
 
   protected
     def create_checkout_session
+      # Find or create a Stripe customer for the current user
+      customer = if current_user.stripe_customer_id.present?
+        Stripe::Customer.retrieve(current_user.stripe_customer_id)
+      else
+        Stripe::Customer.create(
+          email: current_user.email,
+          name: current_user.name,
+          metadata: {user_id: current_user.id}
+        )
+      end
+
       super \
         mode: "subscription",
-        customer: retrieve_or_create_customer(
-          id: current_user.id,
-          email: current_user.email,
-          name: current_user.name
-        ),
+        customer: customer.id,
         line_items: [{
           price: self.class::STRIPE_PRICE,
           quantity: 1
@@ -120,6 +166,85 @@ class PaymentsController < NoCheckout::Stripe::CheckoutSessionsController
 end
 ```
 
+### Customizing callback URLs
+
+By default, the module uses the same URL for both `success_url` and `cancel_url`, pointing to the `show` action with the Checkout Session ID. You can override these methods to customize the behavior:
+
+```ruby
+class PaymentsController < ApplicationController
+  include NoCheckout::Stripe::CheckoutSession
+
+  protected
+    def success_url
+      # Custom success URL
+      callback_url(status: "success")
+    end
+
+    def cancel_url
+      # Custom cancel URL - could point to a different action or controller
+      pricing_url
+    end
+end
+```
+
+### Routes
+
+Don't forget to add routes for your checkout controllers:
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  resources :payments, controller: "payments", only: [:new, :show]
+  
+  # Or for multiple products:
+  resource :plus_checkout, controller: "plus_checkout_sessions", only: [:new, :show]
+  resource :pro_checkout, controller: "pro_checkout_sessions", only: [:new, :show]
+end
+```
+
+## Architecture
+
+The `CheckoutSession` module is designed as a Rails concern that provides a minimal, composable interface for Stripe Checkout Sessions. Here's how it works:
+
+### Module-Based Design
+
+Instead of inheriting from a base controller class, you **include** the `CheckoutSession` module into your own controllers. This gives you maximum flexibility:
+
+- **No forced inheritance**: Your controllers can inherit from any base controller in your app
+- **Composable**: Mix and match with other concerns and modules
+- **Customizable**: Override any method to change behavior
+- **Testable**: Each piece can be tested independently
+
+### What the Module Provides
+
+1. **Before Actions**: Automatically sets up `@checkout_session` for `new` and `show` actions
+2. **Action Methods**: Provides `#new` action that redirects to Stripe
+3. **Protected Methods**: Gives you `create_checkout_session`, `retrieve_checkout_session`, `callback_url`, `success_url`, and `cancel_url` to override as needed
+4. **Constants**: Includes helper constants for handling Stripe's callback parameter
+
+### Customization Pattern
+
+The module follows a simple pattern:
+
+```ruby
+class YourController < ApplicationController
+  include NoCheckout::Stripe::CheckoutSession
+  
+  # 1. Override protected methods to customize Stripe session creation
+  protected
+    def create_checkout_session
+      super(mode: "payment", line_items: [...])
+    end
+  
+  # 2. Implement show action to handle the callback
+  def show
+    # Access @checkout_session that was automatically retrieved
+    # Do your business logic
+    # Redirect user
+  end
+end
+```
+
 ## Webhooks Controller
 
 [Stripe Webhooks](https://stripe.com/docs/webhooks) are extensive and keep your application up-to-date with what Stripe. In this example, we'll look at how to handle a subscription that's expiring and update a User record in our database.
@@ -128,8 +253,6 @@ end
 class StripesController < NoCheckout::Stripe::WebhooksController
   STRIPE_SIGNING_SECRET = ENV["STRIPE_SIGNING_SECRET"]
 
-  protected
-
   def customer_subscription_created
     user.subscription_expires_at data.current_period_end
   end

data/app/controllers/nocheckout/stripe/checkout_session.rb

@@ -0,0 +1,57 @@
+module NoCheckout::Stripe
+  module CheckoutSession
+    extend ActiveSupport::Concern
+
+    # Unescaped placeholder for Stripe to insert the Checkout Session ID.
+    STRIPE_CALLBACK_PARAMETER = "{CHECKOUT_SESSION_ID}".freeze
+
+    # Escaped version that Rails will emit.
+    ESCAPED_STRIPE_CALLBACK_PARAMETER = CGI.escape(STRIPE_CALLBACK_PARAMETER).freeze
+
+    # Hoist the Stripe constant for easier access.
+    Stripe = ::Stripe
+
+    included do
+      before_action def assign_created_checkout_session
+        @checkout_session = create_checkout_session
+      end, only: :new
+
+      before_action def assign_retrieved_checkout_session
+        @checkout_session = retrieve_checkout_session
+      end, only: :show
+    end
+
+    # Creates a new Checkout Session and redirects to it.
+    def new
+      redirect_to @checkout_session.url, allow_other_host: true
+    end
+
+    protected
+
+    # Creates a Stripe Checkout Session with callback URLs appended.
+    def create_checkout_session(**)
+      Stripe::Checkout::Session.create(success_url:, cancel_url:, **)
+    end
+
+    # Retrieves an existing Stripe Checkout Session by ID.
+    def retrieve_checkout_session(*, **)
+      Stripe::Checkout::Session.retrieve params.fetch(:id), *, **
+    end
+
+    def unescape_stripe_callback_parameter(url)
+      url.gsub(ESCAPED_STRIPE_CALLBACK_PARAMETER, STRIPE_CALLBACK_PARAMETER)
+    end
+
+    # Default success URL. Override for custom behavior.
+    def callback_url(**)
+      unescape_stripe_callback_parameter url_for(
+        action: :show,
+        id: STRIPE_CALLBACK_PARAMETER,
+        only_path: false,
+        **
+      )
+    end
+    alias :success_url :callback_url
+    alias :cancel_url :callback_url
+  end
+end

data/app/controllers/nocheckout/stripe/checkout_sessions_controller.rb

@@ -1,101 +1,5 @@
 module NoCheckout::Stripe
   class CheckoutSessionsController < ApplicationController
-    # Name of the URL parameter stripe uses for the Checkout Session ID.
-    CHECKOUT_SESSION_ID_KEY = :checkout_session_id
-
-    def new
-      redirect_to checkout_session.url, allow_other_host: true
-    end
-
-    protected
-      def checkout_session
-        @checkout_session ||= retrieve_or_create_checkout_session
-      end
-
-      # Actually creates a Stripe checkout session. The reason I had to create
-      # this method is so I could "curry" the values within so the `create_checkout_session`
-      # could be a bit more readable and work better with inheritance.
-      def create_checkout_session(**attributes)
-        Stripe::Checkout::Session.create(**append_callback_urls(**attributes))
-      end
-
-      def append_callback_urls(success_url:, cancel_url:, **attributes)
-        attributes.merge \
-          success_url: concat_unescaped_stripe_checkout_session_id(success_url),
-          cancel_url: concat_unescaped_stripe_checkout_session_id(cancel_url)
-      end
-
-      def retrieve_checkout_session(id: checkout_session_id)
-        Stripe::Checkout::Session.retrieve id
-      end
-
-      def checkout_session_id
-        params.fetch CHECKOUT_SESSION_ID_KEY, nil
-      end
-
-      def retrieve_or_create_checkout_session
-        if checkout_session_id.present?
-          retrieve_checkout_session
-        else
-          create_checkout_session
-        end
-      end
-
-      def callback_url_for(*args, only_path: false, **kwargs)
-        url_for(*args, only_path: only_path, **kwargs)
-      end
-
-      STRIPE_CALLBACK_PARAMETER = "#{CHECKOUT_SESSION_ID_KEY}={CHECKOUT_SESSION_ID}"
-
-      # For some reason Stripe decided to not escape the `{CHECKOUT_SESSION_ID}`, if we try to
-      # pass it through Rails URL builders or the URI object, it will URL encode the value and
-      # not work with stripe. Consequently, we have to do some weirdness here to append the callback.
-      #
-      # More information at https://stripe.com/docs/payments/checkout/custom-success-page#modify-success-url
-      def concat_unescaped_stripe_checkout_session_id(url)
-        if URI(url).query
-          url.concat("&#{STRIPE_CALLBACK_PARAMETER}")
-        else
-          url.concat("?#{STRIPE_CALLBACK_PARAMETER}")
-        end
-      end
-
-      # def success_url
-      #   callback_url(state: :success)
-      # end
-
-      # def cancel_url
-      #   callback_url(state: :cancel)
-      # end
-
-      # Retrives a customer from Stripe and returns a nil if the customer does not exist (instead)
-      # of raising an exception, because this is not exceptional).
-      def retrieve_customer(id:)
-        return nil if customer_id.blank?
-
-        begin
-          Stripe::Customer.retrieve(String(customer_id))
-        # Blurg ... wish Stripe just returned a response object that's not an exception.
-        rescue Stripe::InvalidRequestError => e
-          case e.response.data
-            in error: { code: "resource_missing" }
-              nil
-            else
-              raise
-          end
-        end
-      end
-
-      # Creates a customer and automatically converts the ID to a string so this
-      # thing doesn't explode into oblivion.
-      def create_customer(id: nil, **attributes)
-        # If an ID is given, stripe insists that its a string.
-        id = String(id) unless id.nil?
-        Stripe::Customer.create(id: id, **attributes)
-      end
-
-      def retrieve_or_create_customer(id:, **attributes)
-        retrieve_customer(id: id) || create_customer(id: id, **attributes)
-      end
+    include CheckoutSession
   end
 end

data/lib/nocheckout/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module NoCheckout
-  VERSION = "0.1.4"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: nocheckout
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.2.0
 platform: ruby
 authors:
 - Brad Gessler
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-10-07 00:00:00.000000000 Z
+date: 2025-10-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: zeitwerk
@@ -69,6 +68,7 @@ files:
 - README.md
 - Rakefile
 - app/controllers/nocheckout/stripe.rb
+- app/controllers/nocheckout/stripe/checkout_session.rb
 - app/controllers/nocheckout/stripe/checkout_sessions_controller.rb
 - app/controllers/nocheckout/stripe/webhooks_controller.rb
 - app/controllers/nocheckout/webhooks_controller.rb
@@ -87,7 +87,6 @@ metadata:
   homepage_uri: https://github.com/rubymonolith/nocheckout
   source_code_uri: https://github.com/rubymonolith/nocheckout
   changelog_uri: https://github.com/rubymonolith/nocheckout
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -102,8 +101,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.9
-signing_key:
+rubygems_version: 3.6.2
 specification_version: 4
 summary: Rails controllers for Stripe Checkout Sessions and Webhooks
 test_files: []