belt-pay 0.0.1

data/lib/belt/pay/templates/terraform/main.tf.erb

@@ -0,0 +1,73 @@
+# Pay Module — Stripe Payments & Subscriptions
+# Generated by: belt generate pay
+#
+# Provides:
+# - Secrets Manager secret for Stripe API keys
+# - IAM policy for Lambda to read secrets
+# - DynamoDB table for transaction audit log
+
+terraform {
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = "~> 5.0"
+    }
+  }
+}
+
+locals {
+  common_tags = {
+    Module      = "pay"
+    Environment = var.environment
+    ManagedBy   = "Terraform"
+  }
+  secret_name = "${var.app_name}-${var.environment}-stripe"
+}
+
+# ============================================================================
+# Secrets Manager — Stripe API Keys
+# ============================================================================
+
+resource "aws_secretsmanager_secret" "stripe" {
+  name        = local.secret_name
+  description = "Stripe API keys for ${var.app_name} (${var.environment})"
+
+  tags = merge(local.common_tags, {
+    Name = local.secret_name
+  })
+}
+
+# Initial secret value — update manually or via CI after creation
+resource "aws_secretsmanager_secret_version" "stripe" {
+  secret_id = aws_secretsmanager_secret.stripe.id
+  secret_string = jsonencode({
+    stripe_secret_key    = var.stripe_secret_key
+    stripe_webhook_secret = var.stripe_webhook_secret
+  })
+
+  lifecycle {
+    ignore_changes = [secret_string]
+  }
+}
+
+# ============================================================================
+# IAM Policy — Read Stripe Secrets
+# ============================================================================
+
+data "aws_iam_policy_document" "read_stripe_secrets" {
+  statement {
+    effect = "Allow"
+    actions = [
+      "secretsmanager:GetSecretValue"
+    ]
+    resources = [aws_secretsmanager_secret.stripe.arn]
+  }
+}
+
+resource "aws_iam_policy" "read_stripe_secrets" {
+  name        = "${var.app_name}-${var.environment}-pay-secrets"
+  description = "Allow Lambda to read Stripe secrets"
+  policy      = data.aws_iam_policy_document.read_stripe_secrets.json
+
+  tags = local.common_tags
+}

data/lib/belt/pay/templates/terraform/outputs.tf.erb

@@ -0,0 +1,14 @@
+output "stripe_secret_arn" {
+  description = "ARN of the Stripe secrets in Secrets Manager"
+  value       = aws_secretsmanager_secret.stripe.arn
+}
+
+output "stripe_secret_name" {
+  description = "Name of the Stripe secret (for Lambda env vars)"
+  value       = local.secret_name
+}
+
+output "read_secrets_policy_arn" {
+  description = "ARN of the IAM policy for reading Stripe secrets"
+  value       = aws_iam_policy.read_stripe_secrets.arn
+}

data/lib/belt/pay/templates/terraform/variables.tf.erb

@@ -0,0 +1,23 @@
+variable "app_name" {
+  description = "Application name"
+  type        = string
+}
+
+variable "environment" {
+  description = "Environment name (dev, staging, prod)"
+  type        = string
+}
+
+variable "stripe_secret_key" {
+  description = "Stripe secret API key (initial value — update via console/CI)"
+  type        = string
+  default     = "sk_test_PLACEHOLDER"
+  sensitive   = true
+}
+
+variable "stripe_webhook_secret" {
+  description = "Stripe webhook signing secret (initial value — update via console/CI)"
+  type        = string
+  default     = "whsec_PLACEHOLDER"
+  sensitive   = true
+}

data/lib/belt/pay/transaction.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require 'activeitem'
+require 'securerandom'
+
+module Belt
+  module Pay
+    # Internal Transaction model — lives in the gem, not generated into apps.
+    # Records all payment events (checkouts, subscriptions, refunds) for audit logging.
+    #
+    # Override by creating your own Belt::Pay::Transaction class before requiring belt-pay,
+    # or monkey-patch individual methods as needed.
+    class Transaction < ActiveItem::Base
+      self.table_name = -> { Belt::Pay.configuration.transactions_table_name }
+      self.primary_key = :id
+
+      attr_accessor :id, :customer_id, :provider, :provider_customer_id,
+                    :provider_session_id, :provider_subscription_id, :provider_payment_intent_id,
+                    :type, :status, :amount_cents, :currency, :description,
+                    :metadata, :created_at, :updated_at
+
+      validates :customer_id, presence: true
+      validates :type, presence: true
+      validates :status, presence: true
+
+      before_create { self.id ||= SecureRandom.uuid }
+      before_create { self.created_at ||= Time.now.utc.iso8601 }
+      before_save { self.updated_at = Time.now.utc.iso8601 }
+
+      # Transaction types
+      TYPES = %w[checkout subscription subscription_renewal refund payment_method_update].freeze
+
+      # Transaction statuses
+      STATUSES = %w[pending completed failed refunded canceled].freeze
+
+      class << self
+        # Record a checkout completion
+        def record_checkout(customer_id:, session_id:, amount_cents:, currency: 'usd', metadata: {})
+          create!(
+            customer_id: customer_id,
+            provider: Belt::Pay.configuration.provider.to_s,
+            provider_session_id: session_id,
+            type: 'checkout',
+            status: 'completed',
+            amount_cents: amount_cents,
+            currency: currency,
+            description: 'Checkout session completed',
+            metadata: metadata
+          )
+        end
+
+        # Record a subscription creation
+        def record_subscription(customer_id:, subscription_id:, amount_cents:, currency: 'usd', metadata: {})
+          create!(
+            customer_id: customer_id,
+            provider: Belt::Pay.configuration.provider.to_s,
+            provider_subscription_id: subscription_id,
+            type: 'subscription',
+            status: 'completed',
+            amount_cents: amount_cents,
+            currency: currency,
+            description: 'Subscription created',
+            metadata: metadata
+          )
+        end
+
+        # Record a subscription renewal (invoice paid)
+        def record_renewal(customer_id:, subscription_id:, amount_cents:, currency: 'usd', metadata: {})
+          create!(
+            customer_id: customer_id,
+            provider: Belt::Pay.configuration.provider.to_s,
+            provider_subscription_id: subscription_id,
+            type: 'subscription_renewal',
+            status: 'completed',
+            amount_cents: amount_cents,
+            currency: currency,
+            description: 'Subscription renewal',
+            metadata: metadata
+          )
+        end
+
+        # Record a refund
+        def record_refund(customer_id:, amount_cents:, currency: 'usd', metadata: {})
+          create!(
+            customer_id: customer_id,
+            provider: Belt::Pay.configuration.provider.to_s,
+            type: 'refund',
+            status: 'completed',
+            amount_cents: amount_cents,
+            currency: currency,
+            description: 'Refund issued',
+            metadata: metadata
+          )
+        end
+
+        # Find transactions for a customer
+        def for_customer(customer_id)
+          where(customer_id: customer_id, index: 'CustomerIndex')
+        end
+      end
+    end
+  end
+end

data/lib/belt/pay/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Belt
+  module Pay
+    VERSION = '0.0.1'
+  end
+end

data/lib/belt/pay/webhook_handler.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module Belt
+  module Pay
+    # Handles incoming webhooks from the payment provider.
+    # Verifies signatures, dispatches events, and records transactions.
+    module WebhookHandler
+      class << self
+        # Process a raw webhook request.
+        # @param payload [String] Raw request body
+        # @param signature [String] Provider signature header
+        # @return [Hash] { received: true }
+        def process(payload:, signature:)
+          event = Belt::Pay.provider.verify_webhook(payload, signature)
+          dispatch(event)
+          { received: true }
+        end
+
+        private
+
+        def dispatch(event)
+          event_type = event['type'] || event.type
+
+          Belt::Pay.log(:info, 'Belt::Pay::WebhookHandler: received event', event_type: event_type)
+
+          case event_type
+          when 'checkout.session.completed'
+            handle_checkout_completed(event.data.object)
+          when 'checkout.session.expired'
+            handle_checkout_expired(event.data.object)
+          when 'invoice.paid'
+            handle_invoice_paid(event.data.object)
+          when 'invoice.payment_failed'
+            handle_invoice_payment_failed(event.data.object)
+          when 'customer.subscription.deleted'
+            handle_subscription_deleted(event.data.object)
+          when 'customer.subscription.updated'
+            handle_subscription_updated(event.data.object)
+          else
+            Belt::Pay.log(:info, 'Belt::Pay::WebhookHandler: unhandled event type', event_type: event_type)
+          end
+        end
+
+        def handle_checkout_completed(session)
+          customer_id = session.metadata&.app_customer_id || session.metadata&.[]('app_customer_id')
+          return unless customer_id
+
+          # Complete the pending transaction
+          pending = Transaction.where(
+            provider_session_id: session.id,
+            index: 'ProviderSessionIndex'
+          ).first
+
+          if pending&.status == 'pending'
+            pending.status = 'completed'
+            pending.amount_cents = session.amount_total
+            pending.save!
+          else
+            # No pending record — create one (webhook-first flow)
+            Transaction.record_checkout(
+              customer_id: customer_id,
+              session_id: session.id,
+              amount_cents: session.amount_total || 0,
+              metadata: { payment_status: session.payment_status }
+            )
+          end
+
+          Belt::Pay.log(:info, 'Belt::Pay::WebhookHandler: checkout completed',
+                        customer_id: customer_id, session_id: session.id,
+                        amount_cents: session.amount_total)
+        end
+
+        def handle_checkout_expired(session)
+          # Mark pending transaction as failed
+          pending = Transaction.where(
+            provider_session_id: session.id,
+            index: 'ProviderSessionIndex'
+          ).first
+
+          if pending&.status == 'pending'
+            pending.status = 'failed'
+            pending.description = 'Checkout session expired'
+            pending.save!
+          end
+
+          Belt::Pay.log(:info, 'Belt::Pay::WebhookHandler: checkout expired', session_id: session.id)
+        end
+
+        def handle_invoice_paid(invoice)
+          subscription_id = invoice.subscription
+          customer_id = invoice.metadata&.app_customer_id || invoice.metadata&.[]('app_customer_id')
+
+          # Try to resolve customer from subscription metadata if not on invoice
+          unless customer_id
+            customer_id = resolve_customer_from_subscription(subscription_id)
+          end
+
+          return unless customer_id && subscription_id
+
+          Transaction.record_renewal(
+            customer_id: customer_id,
+            subscription_id: subscription_id,
+            amount_cents: invoice.amount_paid || 0,
+            metadata: { invoice_id: invoice.id, billing_reason: invoice.billing_reason }
+          )
+
+          Belt::Pay.log(:info, 'Belt::Pay::WebhookHandler: invoice paid',
+                        customer_id: customer_id, subscription_id: subscription_id,
+                        amount_cents: invoice.amount_paid)
+        end
+
+        def handle_invoice_payment_failed(invoice)
+          customer_id = invoice.metadata&.app_customer_id || invoice.metadata&.[]('app_customer_id')
+          unless customer_id
+            customer_id = resolve_customer_from_subscription(invoice.subscription)
+          end
+
+          Belt::Pay.log(:warn, 'Belt::Pay::WebhookHandler: invoice payment failed',
+                        customer_id: customer_id, invoice_id: invoice.id)
+        end
+
+        def handle_subscription_deleted(subscription)
+          customer_id = subscription.metadata&.app_customer_id || subscription.metadata&.[]('app_customer_id')
+          return unless customer_id
+
+          Belt::Pay.log(:info, 'Belt::Pay::WebhookHandler: subscription deleted',
+                        customer_id: customer_id, subscription_id: subscription.id)
+        end
+
+        def handle_subscription_updated(subscription)
+          customer_id = subscription.metadata&.app_customer_id || subscription.metadata&.[]('app_customer_id')
+          return unless customer_id
+
+          Belt::Pay.log(:info, 'Belt::Pay::WebhookHandler: subscription updated',
+                        customer_id: customer_id, subscription_id: subscription.id,
+                        status: subscription.status)
+        end
+
+        def resolve_customer_from_subscription(subscription_id)
+          return nil unless subscription_id
+
+          Belt::Pay.provider.ensure_api_key!
+          sub = ::Stripe::Subscription.retrieve(subscription_id)
+          sub.metadata&.app_customer_id || sub.metadata&.[]('app_customer_id')
+        rescue StandardError => e
+          Belt::Pay.log(:warn, 'Belt::Pay::WebhookHandler: failed to resolve customer from subscription',
+                        subscription_id: subscription_id, error: e.message)
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/belt/pay.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require_relative 'pay/version'
+require_relative 'pay/configuration'
+require_relative 'pay/transaction'
+require_relative 'pay/billable'
+require_relative 'pay/checkout'
+require_relative 'pay/subscription'
+require_relative 'pay/customer_provisioner'
+require_relative 'pay/payment_method_attacher'
+require_relative 'pay/setup_intent_creator'
+require_relative 'pay/webhook_handler'
+require_relative 'pay/providers/stripe'
+
+module Belt
+  module Pay
+    class Error < StandardError; end
+    class ConfigurationError < Error; end
+    class ProviderError < Error; end
+
+    class << self
+      attr_writer :configuration
+
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def configure
+        yield(configuration)
+      end
+
+      def reset_configuration!
+        @configuration = Configuration.new
+      end
+
+      # --- Convenience API (provider-agnostic names) ---
+
+      # Ensure a payment provider customer exists for this user.
+      # @param customer [Object] Your app's user/customer model instance
+      # @return [String] The provider customer ID
+      def ensure_customer(customer)
+        CustomerProvisioner.new(customer).call
+      end
+
+      # Attach a payment method and set as default.
+      # @param customer [Object] Your app's user/customer model instance
+      # @param payment_method_id [String] Provider payment method token
+      # @return [PaymentMethodAttacher::Result]
+      def attach_payment_method(customer, payment_method_id)
+        PaymentMethodAttacher.new(customer, payment_method_id).call
+      end
+
+      # Create a setup intent for collecting payment details on the frontend.
+      # @param customer [Object] Your app's user/customer model instance
+      # @return [SetupIntentCreator::Result]
+      def create_setup_intent(customer)
+        SetupIntentCreator.new(customer).call
+      end
+
+      # Create a checkout session for one-time or subscription payments.
+      # @param customer [Object] Your app's user/customer model instance
+      # @param options [Hash] Checkout options (line_items, mode, success_url, cancel_url, metadata)
+      # @return [Hash] { url:, session_id: }
+      def create_checkout(customer, **options)
+        Checkout.create(customer, **options)
+      end
+
+      # Subscribe a customer to a plan.
+      # @param customer [Object] Your app's user/customer model instance
+      # @param price_id [String] Provider price/plan ID
+      # @param metadata [Hash] Additional metadata
+      # @return [Hash] { subscription_id:, status: }
+      def subscribe(customer, price_id:, metadata: {})
+        Subscription.create(customer, price_id: price_id, metadata: metadata)
+      end
+
+      # Cancel a customer's subscription.
+      # @param customer [Object] Your app's user/customer model instance
+      # @param immediately [Boolean] Cancel now vs at period end (default: false)
+      def cancel_subscription(customer, immediately: false)
+        Subscription.cancel(customer, immediately: immediately)
+      end
+
+      # Generate a billing portal URL for customer self-service.
+      # @param customer [Object] Your app's user/customer model instance
+      # @param return_url [String] URL to redirect back to after portal
+      # @return [Hash] { url: }
+      def billing_portal(customer, return_url:)
+        provider.billing_portal(customer, return_url: return_url)
+      end
+
+      # Get the configured provider adapter instance.
+      # @return [Belt::Pay::Providers::Stripe] (or future providers)
+      def provider
+        @provider ||= resolve_provider
+      end
+
+      # Reset provider (useful for testing)
+      def reset_provider!
+        @provider = nil
+      end
+
+      # Internal logging helper
+      def log(level, message, **kwargs)
+        if defined?(Belt::Observability::Logger)
+          Belt::Observability::Logger.public_send(level, message, **kwargs)
+        elsif configuration.logger
+          configuration.logger.public_send(level, message, **kwargs)
+        end
+      end
+
+      private
+
+      def resolve_provider
+        case configuration.provider
+        when :stripe
+          Providers::Stripe.new
+        else
+          raise ConfigurationError, "Unknown provider: #{configuration.provider}. Supported: :stripe"
+        end
+      end
+    end
+  end
+end

data/lib/belt-pay.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative 'belt/pay'

metadata

@@ -0,0 +1,99 @@
+--- !ruby/object:Gem::Specification
+name: belt-pay
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Stowzilla
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: belt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: stripe
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: Belt plugin providing payment collection, subscriptions, and billing
+  management. Ships with Stripe as the default provider. Includes webhook handling,
+  customer provisioning, and a Transaction model for audit logging.
+email:
+- andy@stowzilla.com
+- adam@stowzilla.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/belt-pay.rb
+- lib/belt/generators/pay_generator.rb
+- lib/belt/pay.rb
+- lib/belt/pay/billable.rb
+- lib/belt/pay/checkout.rb
+- lib/belt/pay/configuration.rb
+- lib/belt/pay/controllers/webhooks_controller.rb
+- lib/belt/pay/customer_provisioner.rb
+- lib/belt/pay/payment_method_attacher.rb
+- lib/belt/pay/providers/stripe.rb
+- lib/belt/pay/setup_intent_creator.rb
+- lib/belt/pay/subscription.rb
+- lib/belt/pay/templates/config/pay_webhooks.yml.erb
+- lib/belt/pay/templates/controllers/pay_webhooks_controller.rb.erb
+- lib/belt/pay/templates/lambda/pay_webhooks.rb.erb
+- lib/belt/pay/templates/terraform/main.tf.erb
+- lib/belt/pay/templates/terraform/outputs.tf.erb
+- lib/belt/pay/templates/terraform/variables.tf.erb
+- lib/belt/pay/transaction.rb
+- lib/belt/pay/version.rb
+- lib/belt/pay/webhook_handler.rb
+homepage: https://github.com/stowzilla/belt-pay
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/stowzilla/belt-pay
+  source_code_uri: https://github.com/stowzilla/belt-pay
+  changelog_uri: https://github.com/stowzilla/belt-pay/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Payments and subscriptions for Belt applications via Stripe
+test_files: []