belt-pay 0.0.1

data/lib/belt/pay/billable.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+
+module Belt
+  module Pay
+    # Mix into your Customer/User model to get payment capabilities.
+    #
+    # @example
+    #   class Customer < ActiveItem::Base
+    #     include Belt::Pay::Billable
+    #   end
+    #
+    #   customer.ensure_pay_customer!
+    #   customer.subscribe!(price_id: 'price_xxx')
+    #   customer.active_subscription?
+    #   customer.cancel_subscription!
+    #   customer.transactions
+    #
+    module Billable
+      extend ActiveSupport::Concern
+
+      included do
+        attr_accessor :pay_customer_id, :pay_subscription_id, :pay_payment_method_id
+      end
+
+      # Ensure this customer has a provider customer account.
+      # Creates one if it doesn't exist. Idempotent.
+      # @return [String] The provider customer ID
+      def ensure_pay_customer!
+        Belt::Pay.ensure_customer(self)
+      end
+
+      # Attach a payment method and set as default.
+      # @param payment_method_id [String] Provider payment method token (e.g., 'pm_xxx')
+      # @return [PaymentMethodAttacher::Result]
+      def attach_payment_method(payment_method_id)
+        Belt::Pay.attach_payment_method(self, payment_method_id)
+      end
+
+      # Create a setup intent for collecting payment details.
+      # @return [SetupIntentCreator::Result] { client_secret:, pay_customer_id: }
+      def create_setup_intent
+        Belt::Pay.create_setup_intent(self)
+      end
+
+      # Subscribe to a plan.
+      # @param price_id [String] Provider price ID
+      # @param metadata [Hash] Additional metadata to store on the subscription
+      # @return [Hash] { subscription_id:, status: }
+      def subscribe!(price_id:, metadata: {})
+        result = Belt::Pay.subscribe(self, price_id: price_id, metadata: metadata)
+        self.pay_subscription_id = result[:subscription_id]
+        save(validate: false)
+        result
+      end
+
+      # Check if customer has an active subscription.
+      # @return [Boolean]
+      def active_subscription?
+        return false unless pay_subscription_id
+
+        Belt::Pay::Subscription.active?(self)
+      end
+
+      # Cancel the current subscription.
+      # @param immediately [Boolean] Cancel now (true) or at period end (false, default)
+      def cancel_subscription!(immediately: false)
+        Belt::Pay.cancel_subscription(self, immediately: immediately)
+        self.pay_subscription_id = nil if immediately
+        save(validate: false) if immediately
+      end
+
+      # Generate a billing portal URL for self-service management.
+      # @param return_url [String] URL to redirect back to
+      # @return [Hash] { url: }
+      def billing_portal_url(return_url:)
+        Belt::Pay.billing_portal(self, return_url: return_url)
+      end
+
+      # Get payment method details (last4, brand, expiry).
+      # @return [Hash, nil] { last4:, brand:, exp_month:, exp_year: }
+      def payment_method_details
+        Belt::Pay.provider.payment_method_details(self)
+      end
+
+      # Get all transactions for this customer.
+      # @return [Array<Belt::Pay::Transaction>]
+      def transactions
+        Belt::Pay::Transaction.for_customer(id)
+      end
+    end
+  end
+end

data/lib/belt/pay/checkout.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Belt
+  module Pay
+    # Creates checkout sessions for one-time or subscription payments.
+    module Checkout
+      class << self
+        # Create a checkout session.
+        # @param customer [Object] App model
+        # @param line_items [Array<Hash>] Items to charge for
+        # @param mode [String] 'payment' or 'subscription'
+        # @param success_url [String]
+        # @param cancel_url [String]
+        # @param metadata [Hash]
+        # @return [Hash] { url:, session_id: }
+        def create(customer, line_items:, mode: 'payment', success_url:, cancel_url:, metadata: {}, **options)
+          # Ensure provider customer exists
+          CustomerProvisioner.new(customer).call
+
+          result = Belt::Pay.provider.create_checkout_session(
+            customer.pay_customer_id,
+            line_items: line_items,
+            mode: mode,
+            success_url: success_url,
+            cancel_url: cancel_url,
+            metadata: metadata.merge(app_customer_id: customer.id),
+            **options
+          )
+
+          # Record pending transaction
+          Transaction.create!(
+            customer_id: customer.id,
+            provider: Belt::Pay.configuration.provider.to_s,
+            provider_session_id: result[:session_id],
+            type: mode == 'subscription' ? 'subscription' : 'checkout',
+            status: 'pending',
+            currency: 'usd',
+            description: "Checkout session created (#{mode})",
+            metadata: metadata
+          )
+
+          Belt::Pay.log(:info, 'Belt::Pay::Checkout: session created',
+                        customer_id: customer.id, session_id: result[:session_id], mode: mode)
+
+          result
+        end
+      end
+    end
+  end
+end

data/lib/belt/pay/configuration.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Belt
+  module Pay
+    class Configuration
+      attr_accessor :provider, :secret_name, :webhook_secret_name,
+                    :table_name_prefix, :logger, :test_mode
+
+      def initialize
+        @provider = :stripe
+        @secret_name = ENV['BELT_PAY_SECRET_NAME']
+        @webhook_secret_name = ENV['BELT_PAY_WEBHOOK_SECRET_NAME']
+        @table_name_prefix = "#{ENV['APP_NAME']}-#{ENV['ENVIRONMENT']}"
+        @logger = nil
+        @test_mode = ENV['BELT_PAY_MODE'] != 'live'
+      end
+
+      def transactions_table_name
+        "#{table_name_prefix}-pay-transactions"
+      end
+    end
+  end
+end

data/lib/belt/pay/controllers/webhooks_controller.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Belt
+  module Pay
+    module Controllers
+      # Default webhook controller for Stripe events.
+      # Lives in the gem — override by generating a controller into your app:
+      #   belt g pay --controllers
+      class WebhooksController < BeltController::Base
+        skip_before_action :authenticate!, only: [:webhook]
+
+        # POST /pay/webhooks
+        def webhook
+          payload = raw_body
+          signature = headers['Stripe-Signature'] || headers['stripe-signature']
+
+          unless signature
+            return error_response('Missing Stripe-Signature header', 400)
+          end
+
+          result = Belt::Pay::WebhookHandler.process(payload: payload, signature: signature)
+          success_response(result)
+        rescue ::Stripe::SignatureVerificationError => e
+          Belt::Pay.log(:warn, 'Belt::Pay webhook signature verification failed', error: e.message)
+          error_response('Invalid signature', 400)
+        rescue StandardError => e
+          Belt::Pay.log(:error, 'Belt::Pay webhook processing error', error: e.message)
+          error_response('Webhook processing error', 500)
+        end
+
+        private
+
+        # Get the raw request body for signature verification.
+        # Stripe requires the exact raw body — not parsed JSON.
+        def raw_body
+          event.dig('body') || ''
+        end
+
+        def headers
+          event.dig('headers') || {}
+        end
+      end
+    end
+  end
+end

data/lib/belt/pay/customer_provisioner.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Belt
+  module Pay
+    # Ensures a payment provider customer exists for a given app customer.
+    # Idempotent — safe to call multiple times.
+    class CustomerProvisioner
+      attr_reader :customer
+
+      def initialize(customer)
+        @customer = customer
+      end
+
+      # @return [String] The provider customer ID
+      def call
+        return customer.pay_customer_id if customer.pay_customer_id
+
+        # Check for concurrent write (another request may have created one)
+        fresh = customer.class.find(customer.id)
+        if fresh&.pay_customer_id
+          customer.pay_customer_id = fresh.pay_customer_id
+          Belt::Pay.log(:info, 'Belt::Pay::CustomerProvisioner: found existing (concurrent write)',
+                        customer_id: customer.id, pay_customer_id: fresh.pay_customer_id)
+          return fresh.pay_customer_id
+        end
+
+        # Create via provider
+        pay_customer_id = Belt::Pay.provider.create_customer(customer)
+
+        customer.pay_customer_id = pay_customer_id
+        unless customer.save(validate: false)
+          raise Error, "Belt::Pay::CustomerProvisioner: failed to persist pay_customer_id=#{pay_customer_id}"
+        end
+
+        Belt::Pay.log(:info, 'Belt::Pay::CustomerProvisioner: created',
+                      customer_id: customer.id, pay_customer_id: pay_customer_id)
+        pay_customer_id
+      end
+    end
+  end
+end

data/lib/belt/pay/payment_method_attacher.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Belt
+  module Pay
+    # Attaches a payment method to a customer's provider account and sets it as default.
+    class PaymentMethodAttacher
+      Result = Struct.new(:pay_customer_id, :payment_method_id, keyword_init: true)
+
+      attr_reader :customer, :payment_method_id
+
+      def initialize(customer, payment_method_id)
+        @customer = customer
+        @payment_method_id = payment_method_id
+      end
+
+      # @return [Result]
+      def call
+        # Ensure provider customer exists
+        CustomerProvisioner.new(customer).call
+
+        # Attach via provider
+        Belt::Pay.provider.attach_payment_method(customer.pay_customer_id, payment_method_id)
+
+        # Persist the payment method ID
+        customer.pay_payment_method_id = payment_method_id
+        unless customer.save(validate: false)
+          raise Error, "Belt::Pay::PaymentMethodAttacher: failed to persist payment_method_id=#{payment_method_id}"
+        end
+
+        Belt::Pay.log(:info, 'Belt::Pay::PaymentMethodAttacher: completed',
+                      customer_id: customer.id, pay_customer_id: customer.pay_customer_id,
+                      payment_method_id: payment_method_id)
+
+        Result.new(pay_customer_id: customer.pay_customer_id, payment_method_id: payment_method_id)
+      end
+    end
+  end
+end

data/lib/belt/pay/providers/stripe.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+require 'stripe'
+
+module Belt
+  module Pay
+    module Providers
+      # Stripe provider adapter.
+      # Handles API key management and provides the Stripe-specific implementations
+      # that the generic Belt::Pay API delegates to.
+      class Stripe
+        # Ensure the Stripe API key is set for the current request.
+        # Reads from Secrets Manager via the configured secret name.
+        def ensure_api_key!
+          ::Stripe.api_key ||= fetch_api_key
+          raise ConfigurationError, 'Stripe API key not configured' unless ::Stripe.api_key
+        end
+
+        # Get the webhook signing secret for signature verification.
+        # @return [String]
+        def webhook_signing_secret
+          @webhook_signing_secret ||= fetch_webhook_secret
+        end
+
+        # Create a Stripe customer for the given user.
+        # @param customer [Object] App model with #id, #email
+        # @return [String] Stripe customer ID (cus_xxx)
+        def create_customer(customer)
+          ensure_api_key!
+          stripe_customer = ::Stripe::Customer.create(
+            email: customer.respond_to?(:email) ? customer.email : nil,
+            metadata: { app_customer_id: customer.id }
+          )
+          stripe_customer.id
+        end
+
+        # Attach a payment method to a Stripe customer and set as default.
+        # @param pay_customer_id [String] Stripe customer ID
+        # @param payment_method_id [String] Payment method ID (pm_xxx)
+        def attach_payment_method(pay_customer_id, payment_method_id)
+          ensure_api_key!
+          ::Stripe::PaymentMethod.attach(payment_method_id, { customer: pay_customer_id })
+          ::Stripe::Customer.update(pay_customer_id, {
+            invoice_settings: { default_payment_method: payment_method_id }
+          })
+        rescue ::Stripe::InvalidRequestError => e
+          raise unless e.message.include?('already been attached')
+
+          # Idempotent — already attached, just set as default
+          ::Stripe::Customer.update(pay_customer_id, {
+            invoice_settings: { default_payment_method: payment_method_id }
+          })
+        end
+
+        # Create a SetupIntent for collecting payment details.
+        # @param pay_customer_id [String] Stripe customer ID
+        # @param customer_id [String] App customer ID (for metadata)
+        # @return [Hash] { client_secret:, setup_intent_id: }
+        def create_setup_intent(pay_customer_id, customer_id:)
+          ensure_api_key!
+          setup_intent = ::Stripe::SetupIntent.create({
+            customer: pay_customer_id,
+            payment_method_types: ['card'],
+            usage: 'off_session',
+            metadata: { app_customer_id: customer_id }
+          })
+          { client_secret: setup_intent.client_secret, setup_intent_id: setup_intent.id }
+        end
+
+        # Create a Checkout Session.
+        # @param pay_customer_id [String] Stripe customer ID
+        # @param options [Hash] line_items, mode, success_url, cancel_url, metadata
+        # @return [Hash] { url:, session_id: }
+        def create_checkout_session(pay_customer_id, **options)
+          ensure_api_key!
+          params = {
+            customer: pay_customer_id,
+            line_items: options[:line_items],
+            mode: options[:mode] || 'payment',
+            success_url: options[:success_url],
+            cancel_url: options[:cancel_url],
+            metadata: options[:metadata] || {}
+          }
+          # For subscription mode, allow trial periods
+          params[:subscription_data] = options[:subscription_data] if options[:subscription_data]
+
+          session = ::Stripe::Checkout::Session.create(params)
+          { url: session.url, session_id: session.id }
+        end
+
+        # Create a subscription directly (without Checkout).
+        # @param pay_customer_id [String] Stripe customer ID
+        # @param price_id [String] Stripe price ID
+        # @param metadata [Hash]
+        # @return [Hash] { subscription_id:, status:, current_period_end: }
+        def create_subscription(pay_customer_id, price_id:, metadata: {})
+          ensure_api_key!
+          subscription = ::Stripe::Subscription.create({
+            customer: pay_customer_id,
+            items: [{ price: price_id }],
+            metadata: metadata,
+            payment_behavior: 'default_incomplete',
+            expand: ['latest_invoice.payment_intent']
+          })
+          {
+            subscription_id: subscription.id,
+            status: subscription.status,
+            current_period_end: Time.at(subscription.current_period_end).utc.iso8601
+          }
+        end
+
+        # Cancel a subscription.
+        # @param subscription_id [String] Stripe subscription ID
+        # @param immediately [Boolean] Cancel now or at period end
+        def cancel_subscription(subscription_id, immediately: false)
+          ensure_api_key!
+          if immediately
+            ::Stripe::Subscription.cancel(subscription_id)
+          else
+            ::Stripe::Subscription.update(subscription_id, { cancel_at_period_end: true })
+          end
+        end
+
+        # Check if a subscription is active.
+        # @param subscription_id [String] Stripe subscription ID
+        # @return [Boolean]
+        def subscription_active?(subscription_id)
+          ensure_api_key!
+          sub = ::Stripe::Subscription.retrieve(subscription_id)
+          %w[active trialing].include?(sub.status)
+        rescue ::Stripe::InvalidRequestError
+          false
+        end
+
+        # Generate a billing portal session URL.
+        # @param pay_customer_id [String] Stripe customer ID
+        # @param return_url [String]
+        # @return [Hash] { url: }
+        def billing_portal(customer, return_url:)
+          ensure_api_key!
+          pay_customer_id = customer.pay_customer_id
+          raise Error, 'Customer has no payment account' unless pay_customer_id
+
+          session = ::Stripe::BillingPortal::Session.create({
+            customer: pay_customer_id,
+            return_url: return_url
+          })
+          { url: session.url }
+        end
+
+        # Get payment method details for a customer.
+        # @param customer [Object] App model with #pay_customer_id
+        # @return [Hash, nil] { last4:, brand:, exp_month:, exp_year: }
+        def payment_method_details(customer)
+          ensure_api_key!
+          return nil unless customer.pay_customer_id
+
+          stripe_customer = ::Stripe::Customer.retrieve(customer.pay_customer_id)
+          default_pm_id = stripe_customer.invoice_settings&.default_payment_method
+          return nil unless default_pm_id
+
+          pm = ::Stripe::PaymentMethod.retrieve(default_pm_id)
+          return nil unless pm&.card
+
+          { last4: pm.card.last4, brand: pm.card.brand,
+            exp_month: pm.card.exp_month, exp_year: pm.card.exp_year }
+        rescue ::Stripe::InvalidRequestError
+          nil
+        end
+
+        # Verify a webhook signature and parse the event.
+        # @param payload [String] Raw request body
+        # @param signature [String] Stripe-Signature header
+        # @return [Stripe::Event]
+        def verify_webhook(payload, signature)
+          ::Stripe::Webhook.construct_event(payload, signature, webhook_signing_secret)
+        end
+
+        private
+
+        def fetch_api_key
+          secret_name = Belt::Pay.configuration.secret_name
+          return nil unless secret_name
+
+          require_secrets_helper
+          SecretsHelper.get_secret(secret_name: secret_name, key: 'stripe_secret_key', required: true)
+        rescue StandardError => e
+          Belt::Pay.log(:error, 'Failed to fetch Stripe API key', error: e.message)
+          nil
+        end
+
+        def fetch_webhook_secret
+          secret_name = Belt::Pay.configuration.webhook_secret_name || Belt::Pay.configuration.secret_name
+          return nil unless secret_name
+
+          require_secrets_helper
+          SecretsHelper.get_secret(secret_name: secret_name, key: 'stripe_webhook_secret', required: true)
+        rescue StandardError => e
+          Belt::Pay.log(:error, 'Failed to fetch Stripe webhook secret', error: e.message)
+          nil
+        end
+
+        def require_secrets_helper
+          require 'belt/secrets_helper' if defined?(Belt::SecretsHelper)
+        rescue LoadError
+          # SecretsHelper not available — key must be set via Stripe.api_key directly
+        end
+      end
+    end
+  end
+end

data/lib/belt/pay/setup_intent_creator.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Belt
+  module Pay
+    # Creates a SetupIntent for securely collecting payment details on the frontend.
+    class SetupIntentCreator
+      Result = Struct.new(:client_secret, :pay_customer_id, keyword_init: true)
+
+      attr_reader :customer
+
+      def initialize(customer)
+        @customer = customer
+      end
+
+      # @return [Result]
+      def call
+        # Ensure provider customer exists
+        pay_customer_id = CustomerProvisioner.new(customer).call
+
+        # Create setup intent via provider
+        result = Belt::Pay.provider.create_setup_intent(pay_customer_id, customer_id: customer.id)
+
+        Belt::Pay.log(:info, 'Belt::Pay::SetupIntentCreator: created',
+                      customer_id: customer.id, pay_customer_id: pay_customer_id)
+
+        Result.new(client_secret: result[:client_secret], pay_customer_id: pay_customer_id)
+      end
+    end
+  end
+end

data/lib/belt/pay/subscription.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Belt
+  module Pay
+    # Manages subscriptions — create, cancel, check status.
+    module Subscription
+      class << self
+        # Create a subscription for a customer.
+        # @param customer [Object] App model with Billable included
+        # @param price_id [String] Provider price/plan ID
+        # @param metadata [Hash]
+        # @return [Hash] { subscription_id:, status:, current_period_end: }
+        def create(customer, price_id:, metadata: {})
+          CustomerProvisioner.new(customer).call
+
+          result = Belt::Pay.provider.create_subscription(
+            customer.pay_customer_id,
+            price_id: price_id,
+            metadata: metadata.merge(app_customer_id: customer.id)
+          )
+
+          # Record the transaction
+          Transaction.record_subscription(
+            customer_id: customer.id,
+            subscription_id: result[:subscription_id],
+            amount_cents: 0, # Amount comes from invoice.paid webhook
+            metadata: metadata.merge(price_id: price_id)
+          )
+
+          Belt::Pay.log(:info, 'Belt::Pay::Subscription: created',
+                        customer_id: customer.id, subscription_id: result[:subscription_id],
+                        status: result[:status])
+
+          result
+        end
+
+        # Cancel a subscription.
+        # @param customer [Object] App model
+        # @param immediately [Boolean]
+        def cancel(customer, immediately: false)
+          subscription_id = customer.pay_subscription_id
+          raise Error, 'Customer has no active subscription' unless subscription_id
+
+          Belt::Pay.provider.cancel_subscription(subscription_id, immediately: immediately)
+
+          Belt::Pay.log(:info, 'Belt::Pay::Subscription: canceled',
+                        customer_id: customer.id, subscription_id: subscription_id,
+                        immediately: immediately)
+        end
+
+        # Check if a customer's subscription is active.
+        # @param customer [Object] App model
+        # @return [Boolean]
+        def active?(customer)
+          subscription_id = customer.pay_subscription_id
+          return false unless subscription_id
+
+          Belt::Pay.provider.subscription_active?(subscription_id)
+        end
+      end
+    end
+  end
+end

data/lib/belt/pay/templates/config/pay_webhooks.yml.erb

@@ -0,0 +1,33 @@
+# Lambda configuration for the pay_webhooks function.
+# Handles incoming Stripe webhook events (checkout, invoice, subscription).
+#
+# Generated by: belt generate pay
+#
+# Keys:
+#   timeout           Lambda timeout in seconds
+#   memory_size       Lambda memory in MB
+#   env_vars          Environment variables (static values or ref() for Terraform values)
+#
+# ref(name) references are resolved from lambda_env_refs in Terraform.
+
+default: &default
+  timeout: 30
+  memory_size: 256
+  env_vars:
+    BELT_PAY_SECRET_NAME: ref(stripe_secret_name)
+    BELT_PAY_WEBHOOK_SECRET_NAME: ref(stripe_secret_name)
+    BELT_PAY_MODE: "live"
+
+dev:
+  <<: *default
+  env_vars:
+    BELT_PAY_SECRET_NAME: ref(stripe_secret_name)
+    BELT_PAY_WEBHOOK_SECRET_NAME: ref(stripe_secret_name)
+    BELT_PAY_MODE: "test"
+
+prod:
+  <<: *default
+  env_vars:
+    BELT_PAY_SECRET_NAME: ref(stripe_secret_name)
+    BELT_PAY_WEBHOOK_SECRET_NAME: ref(stripe_secret_name)
+    BELT_PAY_MODE: "live"

data/lib/belt/pay/templates/controllers/pay_webhooks_controller.rb.erb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# Generated by: belt generate pay --controllers
+# Override this controller to customize webhook handling behavior.
+# The gem's default controller handles standard Stripe events automatically.
+
+require 'belt-pay'
+
+<% ns = @app_name.split('_').map(&:capitalize).join %>
+module <%= ns %>Controllers
+  class PayWebhooksController < Belt::Pay::Controllers::WebhooksController
+    # Override webhook to add custom behavior before/after processing
+    # def webhook
+    #   # Custom pre-processing
+    #   result = super
+    #   # Custom post-processing
+    #   result
+    # end
+
+    # Add custom event handlers by overriding the webhook handler:
+    #
+    # Belt::Pay::WebhookHandler.define_method(:handle_custom_event) do |event_data|
+    #   # Your custom logic here
+    # end
+  end
+end

data/lib/belt/pay/templates/lambda/pay_webhooks.rb.erb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Generated by: belt generate pay
+# Lambda entry point for Stripe webhook events.
+# Receives POST requests from Stripe when payment events occur.
+
+require_relative 'config/environment'
+require 'belt-pay'
+
+include Belt::LambdaHandler
+
+ROUTER = Belt::ActionRouter.new(
+  routes: [
+    { verb: 'POST', path: '/pay/webhooks', controller: 'pay_webhooks', action: 'webhook', auth: 'none' }
+  ],
+  namespace: 'pay_webhooks'
+)
+
+def execute(path:, body:, event:)
+  ROUTER.route(event: event, body: body)
+end