belt-pay 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 673206d18a5fad12255912de6c7833796e147e88e99ce32d70ba48ef727ff9e4
+  data.tar.gz: d5b2171c33ef68447b501183287ab53d209621e859e40a16e2721d0af60a74a2
+SHA512:
+  metadata.gz: 475ef6bdadb87b2712145d0e69f3f74c58a7fa07f7a6d2f293e0a34aa19f6a340794feb1d74e76c7d8dd584a1576650c4572670a443b640f7336e2a4e1f16a6a
+  data.tar.gz: e03f179b799302a256b741ff882defab8064909ecef72c25f5ec3043e1c26d76fe2ffde9ae7c1014a6ad76c5d1b25dfe385d9df7ec860404e3a74f6d3c73f87a

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.0.1 — 2026-09-01
+
+- Initial release
+- Stripe provider with customer provisioning, payment methods, checkout sessions
+- Subscription management (create, cancel, billing portal)
+- Transaction model for audit logging (DynamoDB)
+- Billable concern for customer models
+- Webhook handler with signature verification
+- Generator: `belt g pay` (Terraform module, webhook Lambda, config, schema)
+- Getting started guide

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stowzilla
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,271 @@
+# belt-pay
+
+Payments and subscriptions for [Belt](https://github.com/stowzilla/belt) applications via Stripe.
+
+> **New to Belt Pay?** Check out the [Getting Started Guide](docs/getting-started.md) for a complete walkthrough.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'belt-pay'
+```
+
+Then:
+
+```bash
+bundle install
+belt generate pay
+```
+
+## What You Get
+
+### From the gem (no generation needed)
+
+```ruby
+# Include in your Customer/User model
+class Customer < ActiveItem::Base
+  include Belt::Pay::Billable
+end
+
+# Ensure a Stripe customer exists
+customer.ensure_pay_customer!
+
+# Create a checkout session (one-time or subscription)
+Belt::Pay.create_checkout(customer,
+  line_items: [{ price: 'price_xxx', quantity: 1 }],
+  mode: 'subscription',
+  success_url: 'https://app.example.com/success?session_id={CHECKOUT_SESSION_ID}',
+  cancel_url: 'https://app.example.com/cancel')
+
+# Subscribe directly (when payment method is already attached)
+customer.subscribe!(price_id: 'price_xxx')
+
+# Check subscription status
+customer.active_subscription?  # => true
+
+# Customer self-service billing portal
+customer.billing_portal_url(return_url: 'https://app.example.com/settings')
+# => { url: "https://billing.stripe.com/p/session/..." }
+
+# Collect payment method (returns client_secret for Stripe Elements)
+result = customer.create_setup_intent
+result.client_secret  # => "seti_xxx_secret_yyy"
+
+# Attach a payment method
+customer.attach_payment_method('pm_xxx')
+
+# View payment details
+customer.payment_method_details
+# => { last4: "4242", brand: "visa", exp_month: 12, exp_year: 2027 }
+
+# Transaction history
+customer.transactions
+# => [#<Belt::Pay::Transaction type="subscription" status="completed" ...>]
+```
+
+### From the generator (`belt g pay`)
+
+- **Terraform module** — Secrets Manager for Stripe keys, IAM policies
+- **Lambda entry point** — Dedicated webhook Lambda for Stripe events
+- **Lambda config** — `config/lambda/pay_webhooks.yml`
+- **Schema update** — DynamoDB table for transaction audit log
+- **Route injection** — Adds `/pay/webhooks` endpoint
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Purpose | Default |
+|----------|---------|---------|
+| `BELT_PAY_SECRET_NAME` | Secrets Manager secret name for Stripe keys | — |
+| `BELT_PAY_WEBHOOK_SECRET_NAME` | Secret name for webhook signing (falls back to BELT_PAY_SECRET_NAME) | — |
+| `BELT_PAY_MODE` | `test` or `live` | `test` |
+| `APP_NAME` | App name for table naming | — |
+| `ENVIRONMENT` | Environment for table naming | — |
+
+### Programmatic Configuration
+
+```ruby
+Belt::Pay.configure do |config|
+  config.provider = :stripe                    # Only :stripe for now
+  config.secret_name = 'myapp-prod-stripe'     # Secrets Manager secret
+  config.table_name_prefix = 'myapp-prod'      # DynamoDB table prefix
+end
+```
+
+### Secrets Manager Format
+
+The Stripe secret should contain:
+
+```json
+{
+  "stripe_secret_key": "sk_live_...",
+  "stripe_webhook_secret": "whsec_..."
+}
+```
+
+## Common Patterns
+
+### Annual Subscription (Feature Gating)
+
+```ruby
+# In your controller
+class SubscriptionsController < BeltController::Base
+  def create
+    price_id = ENV['STRIPE_ANNUAL_PRICE_ID']  # Created in Stripe Dashboard
+    result = current_customer.subscribe!(price_id: price_id, metadata: { plan: 'pro' })
+    success_response(subscription_id: result[:subscription_id], status: result[:status])
+  end
+
+  def status
+    success_response(active: current_customer.active_subscription?)
+  end
+
+  def cancel
+    current_customer.cancel_subscription!  # Cancels at period end
+    success_response(message: 'Subscription will cancel at end of billing period')
+  end
+
+  def portal
+    result = current_customer.billing_portal_url(return_url: "#{ENV['FRONTEND_URL']}/settings")
+    success_response(url: result[:url])
+  end
+end
+```
+
+### One-Time Payment (Product Purchase)
+
+```ruby
+class CheckoutController < BeltController::Base
+  def create
+    product = Product.find(params['product_id'])
+
+    result = Belt::Pay.create_checkout(current_customer,
+      line_items: [{
+        price_data: {
+          currency: 'usd',
+          product_data: { name: product.name },
+          unit_amount: product.price_cents
+        },
+        quantity: 1
+      }],
+      mode: 'payment',
+      success_url: "#{ENV['FRONTEND_URL']}/checkout/success?session_id={CHECKOUT_SESSION_ID}",
+      cancel_url: "#{ENV['FRONTEND_URL']}/products")
+
+    success_response(checkout_url: result[:url])
+  end
+end
+```
+
+### Checking Subscription Access (Middleware Pattern)
+
+```ruby
+class ProController < BeltController::Base
+  before_action :require_subscription!
+
+  private
+
+  def require_subscription!
+    unless current_customer.active_subscription?
+      error_response('Pro subscription required', 403)
+    end
+  end
+end
+```
+
+## Webhook Events
+
+The gem automatically handles these Stripe webhook events:
+
+| Event | Behavior |
+|-------|----------|
+| `checkout.session.completed` | Marks pending transaction as completed |
+| `checkout.session.expired` | Marks pending transaction as failed |
+| `invoice.paid` | Records subscription renewal transaction |
+| `invoice.payment_failed` | Logs payment failure |
+| `customer.subscription.deleted` | Logs subscription cancellation |
+| `customer.subscription.updated` | Logs subscription status changes |
+
+### Customizing Webhook Behavior
+
+Override the webhook controller to add custom logic:
+
+```bash
+belt g pay --controllers
+```
+
+This generates a controller in your app that inherits from the gem's default. Override individual handler methods as needed.
+
+## Transaction Model
+
+`Belt::Pay::Transaction` lives inside the gem and records all payment activity:
+
+```ruby
+customer.transactions.each do |txn|
+  puts "#{txn.type}: #{txn.amount_cents} #{txn.currency} — #{txn.status}"
+end
+# subscription: 9900 usd — completed
+# subscription_renewal: 9900 usd — completed
+```
+
+### Fields
+
+| Field | Description |
+|-------|-------------|
+| `id` | UUID primary key |
+| `customer_id` | Your app's customer/user ID |
+| `provider` | Payment provider (`stripe`) |
+| `provider_session_id` | Stripe checkout session ID |
+| `provider_subscription_id` | Stripe subscription ID |
+| `type` | `checkout`, `subscription`, `subscription_renewal`, `refund` |
+| `status` | `pending`, `completed`, `failed`, `refunded`, `canceled` |
+| `amount_cents` | Amount in cents |
+| `currency` | ISO currency code |
+| `metadata` | Free-form JSON metadata |
+| `created_at` | ISO 8601 timestamp |
+
+## Terraform Module
+
+After running `belt g pay`, add the module to your environment's `main.tf`:
+
+```hcl
+module "pay" {
+  source      = "../modules/pay"
+  app_name    = var.app_name
+  environment = var.environment
+
+  # Set these or update secrets manually after apply
+  # stripe_secret_key     = var.stripe_secret_key
+  # stripe_webhook_secret = var.stripe_webhook_secret
+}
+```
+
+## Stripe Dashboard Setup
+
+After deploying, configure your Stripe webhook endpoint:
+
+1. Go to Stripe Dashboard → Developers → Webhooks
+2. Add endpoint: `https://<your-api-domain>/pay/webhooks`
+3. Select events:
+   - `checkout.session.completed`
+   - `checkout.session.expired`
+   - `invoice.paid`
+   - `invoice.payment_failed`
+   - `customer.subscription.deleted`
+   - `customer.subscription.updated`
+4. Copy the signing secret into your Secrets Manager secret
+
+## Removing
+
+```bash
+belt destroy pay
+```
+
+Then remove the module reference from your environment `main.tf` files.
+
+## License
+
+MIT

data/lib/belt/generators/pay_generator.rb

@@ -0,0 +1,352 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'erb'
+
+module Belt
+  module Generators
+    class PayGenerator
+      TEMPLATE_DIR = File.expand_path('../pay/templates', __dir__)
+
+      def self.description
+        'Install payments and subscriptions (Stripe)'
+      end
+
+      def self.run(args)
+        if args.include?('--help') || args.include?('-h')
+          print_help
+          return
+        end
+
+        new(args).generate
+      end
+
+      def self.destroy(args)
+        new(args).destroy
+      end
+
+      def self.print_help
+        puts <<~HELP
+          Install payment and subscription infrastructure for your Belt app.
+
+          Usage: belt generate pay [options]
+
+          Options:
+            --controllers         Generate controller overrides (to customize webhook behavior)
+            --force               Overwrite existing files
+
+          What gets created:
+            infrastructure/modules/pay/              Terraform module (Secrets Manager, IAM)
+            config/lambda/pay_webhooks.yml           Lambda configuration (timeout, memory, env)
+            lambda/pay_webhooks.rb                   Lambda entry point for Stripe webhooks
+            infrastructure/schema.tf.rb              Updated with pay_transactions table
+
+          What stays in the gem (no generation needed):
+            Belt::Pay::Transaction                   Transaction audit log model
+            Belt::Pay::Billable                      Concern for your Customer model
+            Belt::Pay.create_checkout(...)           Create checkout sessions
+            Belt::Pay.subscribe(...)                 Manage subscriptions
+            Belt::Pay.billing_portal(...)            Customer self-service portal
+            Belt::Pay::Controllers::WebhooksController  Default webhook handler
+
+          To override the webhook controller:
+            belt g pay --controllers
+
+          After generation:
+            1. Add module reference to your environment's main.tf
+            2. Create Stripe keys in Secrets Manager (or via Terraform)
+            3. Include Belt::Pay::Billable in your Customer/User model
+            4. Deploy: belt apply <env>
+            5. Configure Stripe webhook URL: https://<api-domain>/pay/webhooks
+
+          Examples:
+            belt g pay                     # Infrastructure only (use gem defaults)
+            belt g pay --controllers       # Also generate controller overrides
+            belt d pay
+        HELP
+      end
+
+      def initialize(args)
+        @force = args.include?('--force')
+        @with_controllers = args.include?('--controllers')
+        @app_name = detect_namespace
+      end
+
+      def generate
+        generate_terraform_module
+        generate_lambda_config
+        generate_lambda_entry_point
+        generate_controllers if @with_controllers
+        inject_schema
+        inject_routes
+        print_success
+      end
+
+      def destroy
+        remove_terraform_module
+        remove_lambda_config
+        remove_lambda_entry_point
+        remove_controllers
+        remove_schema
+        remove_routes
+        puts "\n✓ Pay removed!"
+        puts "  Don't forget to remove the module reference from your environment main.tf files."
+      end
+
+      private
+
+      def detect_namespace
+        routes_file = find_routes_file_path
+        if routes_file && File.exist?(routes_file)
+          match = File.read(routes_file).match(/namespace :(\w+)/)
+          return match[1] if match
+        end
+        File.basename(Dir.pwd)
+      end
+
+      def find_routes_file_path
+        candidates = ['config/routes.tf.rb', 'infrastructure/routes.tf.rb']
+        candidates.find { |f| File.exist?(f) }
+      end
+
+      # ---- Generate ----
+
+      def generate_terraform_module
+        module_dir = 'infrastructure/modules/pay'
+
+        if Dir.exist?(module_dir) && !@force
+          puts "  skip    #{module_dir}/ (already exists, use --force to overwrite)"
+          return
+        end
+
+        FileUtils.mkdir_p(module_dir)
+
+        write_template('terraform/main.tf.erb', "#{module_dir}/main.tf")
+        write_template('terraform/variables.tf.erb', "#{module_dir}/variables.tf")
+        write_template('terraform/outputs.tf.erb', "#{module_dir}/outputs.tf")
+
+        puts "  create  #{module_dir}/main.tf"
+        puts "  create  #{module_dir}/variables.tf"
+        puts "  create  #{module_dir}/outputs.tf"
+      end
+
+      def generate_lambda_config
+        config_dir = 'config/lambda'
+        dest = "#{config_dir}/pay_webhooks.yml"
+
+        if File.exist?(dest) && !@force
+          puts "  skip    #{dest} (already exists)"
+          return
+        end
+
+        FileUtils.mkdir_p(config_dir)
+        write_template('config/pay_webhooks.yml.erb', dest)
+        puts "  create  #{dest}"
+      end
+
+      def generate_lambda_entry_point
+        dest = 'lambda/pay_webhooks.rb'
+
+        if File.exist?(dest) && !@force
+          puts "  skip    #{dest} (already exists)"
+          return
+        end
+
+        write_template('lambda/pay_webhooks.rb.erb', dest)
+        puts "  create  #{dest}"
+      end
+
+      def generate_controllers
+        controller_dir = "lambda/controllers/#{@app_name}"
+        FileUtils.mkdir_p(controller_dir)
+
+        dest = "#{controller_dir}/pay_webhooks_controller.rb"
+        if File.exist?(dest) && !@force
+          puts "  skip    #{dest} (already exists)"
+        else
+          write_template('controllers/pay_webhooks_controller.rb.erb', dest)
+          puts "  create  #{dest}"
+        end
+      end
+
+      def inject_schema
+        schema_file = find_schema_file_path
+        return unless schema_file && File.exist?(schema_file)
+
+        content = File.read(schema_file)
+        return if content.include?('pay_transactions') || content.include?('pay-transactions')
+
+        # Add transactions table to schema
+        schema_block = <<~SCHEMA
+
+  model :pay_transaction do
+    partition_key :id, :string
+    global_secondary_index :CustomerIndex, partition_key: :customer_id
+    global_secondary_index :ProviderSessionIndex, partition_key: :provider_session_id
+  end
+        SCHEMA
+
+        # Insert before the closing `end` of the schema.define block
+        if content.match?(/^end\s*\z/m)
+          content.sub!(/^end\s*\z/m, "#{schema_block}end\n")
+        else
+          content << "\n#{schema_block}"
+        end
+
+        File.write(schema_file, content)
+        puts "  update  #{schema_file} (added pay_transactions table)"
+      end
+
+      def inject_routes
+        routes_file = find_routes_file_path
+        return unless routes_file && File.exist?(routes_file)
+
+        content = File.read(routes_file)
+        return if content.include?('pay_webhooks') || content.include?('pay/webhooks')
+
+        # Add webhook route to the namespace
+        namespace_pattern = /^(\s*)namespace :#{Regexp.escape(@app_name)}\b[^\n]*do\s*\n(.*?)^\1end/m
+        if content.match?(namespace_pattern)
+          webhook_route = "    post \"pay/webhooks\", controller: :pay_webhooks, action: :webhook, auth: :none"
+          content.sub!(namespace_pattern) do |match|
+            indent = ::Regexp.last_match(1)
+            match.sub(/^(#{indent})end\z/m, "#{webhook_route}\n#{indent}end")
+          end
+        end
+
+        File.write(routes_file, content)
+        puts "  update  #{routes_file} (added pay webhook route)"
+      end
+
+      # ---- Destroy ----
+
+      def remove_terraform_module
+        module_dir = 'infrastructure/modules/pay'
+        if Dir.exist?(module_dir)
+          FileUtils.rm_rf(module_dir)
+          puts "  remove  #{module_dir}/"
+        end
+      end
+
+      def remove_lambda_config
+        path = 'config/lambda/pay_webhooks.yml'
+        if File.exist?(path)
+          File.delete(path)
+          puts "  remove  #{path}"
+        end
+      end
+
+      def remove_lambda_entry_point
+        path = 'lambda/pay_webhooks.rb'
+        if File.exist?(path)
+          File.delete(path)
+          puts "  remove  #{path}"
+        end
+      end
+
+      def remove_controllers
+        path = "lambda/controllers/#{@app_name}/pay_webhooks_controller.rb"
+        if File.exist?(path)
+          File.delete(path)
+          puts "  remove  #{path}"
+        end
+      end
+
+      def remove_schema
+        schema_file = find_schema_file_path
+        return unless schema_file && File.exist?(schema_file)
+
+        content = File.read(schema_file)
+        original = content.dup
+
+        content.gsub!(/\n\s*model :pay_transaction do.*?end\n/m, '')
+
+        if content != original
+          File.write(schema_file, content)
+          puts "  update  #{schema_file} (removed pay_transactions table)"
+        end
+      end
+
+      def remove_routes
+        routes_file = find_routes_file_path
+        return unless routes_file && File.exist?(routes_file)
+
+        content = File.read(routes_file)
+        original = content.dup
+
+        content.gsub!(/^\s*post "pay\/webhooks".*\n/, '')
+
+        if content != original
+          File.write(routes_file, content)
+          puts "  update  #{routes_file}"
+        end
+      end
+
+      def find_schema_file_path
+        candidates = ['infrastructure/schema.tf.rb', 'config/schema.tf.rb']
+        candidates.find { |f| File.exist?(f) }
+      end
+
+      def write_template(template_name, dest_path)
+        template_path = File.join(TEMPLATE_DIR, template_name)
+        FileUtils.mkdir_p(File.dirname(dest_path))
+        content = ERB.new(File.read(template_path), trim_mode: '-').result(binding)
+        File.write(dest_path, content)
+      end
+
+      def print_success
+        puts <<~SUCCESS
+
+          ✓ Payments installed!
+
+          Next steps:
+            1. Add the module to your environment's main.tf:
+
+               module "pay" {
+                 source      = "../modules/pay"
+                 app_name    = var.app_name
+                 environment = var.environment
+               }
+
+            2. Include Belt::Pay::Billable in your Customer/User model:
+
+               class Customer < ActiveItem::Base
+                 include Belt::Pay::Billable
+                 # ...
+               end
+
+            3. Create your Stripe API keys in Secrets Manager:
+               Secret name: <app_name>-<env>-stripe
+               Keys: stripe_secret_key, stripe_webhook_secret
+
+            4. Deploy:
+               belt apply <env>
+
+            5. Configure Stripe webhook endpoint:
+               URL: https://<your-api-domain>/pay/webhooks
+               Events: checkout.session.completed, checkout.session.expired,
+                       invoice.paid, invoice.payment_failed,
+                       customer.subscription.deleted, customer.subscription.updated
+
+          Quick Usage:
+            # Create a checkout session
+            Belt::Pay.create_checkout(customer,
+              line_items: [{ price: 'price_xxx', quantity: 1 }],
+              mode: 'subscription',
+              success_url: 'https://app.example.com/success',
+              cancel_url: 'https://app.example.com/cancel')
+
+            # Subscribe directly (if payment method already attached)
+            customer.subscribe!(price_id: 'price_xxx')
+
+            # Check subscription status
+            customer.active_subscription?  # => true
+
+            # Customer self-service
+            customer.billing_portal_url(return_url: 'https://app.example.com/settings')
+
+        SUCCESS
+      end
+    end
+  end
+end