belt-messaging 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 57f12b22980eee716c98dcd00612c63b7b72a964cb3fef007fc0c1e594893cef
+  data.tar.gz: 81c05386abb62cfd11aceb9c68fb089dc81e5aa870904cfad5f27920d7bf6590
+SHA512:
+  metadata.gz: add692f4eed8cf815613228ed61aa4e9905c9be7bf07289e7f31e736ae943fae216749938282f766bb39a848f4ea7aab5f6e0bfa8e7e2bf85a02c600b68f8910
+  data.tar.gz: b016a16412ad2bfad897cddd6dd3a765e1a2a0a4760bd1229d960843021331e6964d5512236c09679a0a2ed396a3e6ab8f29e07bc035793b380ba6d1abd9ba96

data/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+## 0.1.0
+
+- Add `Belt::Messaging.send_email(to:, subject:, body:, html:)` — send email via AWS SESv2
+- Add `Belt::Messaging::Email` — core email sending module
+- Add `Belt::Messaging::EmailGate` — mode-based send gating (none/whitelist/all)
+- Add `Belt::Messaging::Logging` — shared logging concern extracted from all modules
+- Add email configuration: `ENABLE_EMAIL`, `EMAIL_MODE`, `EMAIL_WHITELIST`, `EMAIL_FROM_ADDRESS`
+- Add `aws-sdk-sesv2` dependency
+- Terraform module: SES email identity verification (domain or address), email send IAM policy
+- Terraform outputs: `email_identity`, `email_send_policy_arn`, `email_domain_dkim_tokens`
+
+## 0.0.1
+
+- Initial release
+- `Belt::Messaging.send_sms(to:, message:)` — send SMS via AWS PinpointSMSVoiceV2
+- `Belt::Messaging::PhoneFormatter` — E.164 phone number formatting
+- `Belt::Messaging::SmsGate` — mode-based send gating (none/whitelist/all)
+- `Belt::Messaging::Configuration` — environment-based configuration
+- Generator: `belt g messaging` — installs Terraform module, Lambda entry point, controllers
+- Destroy: `belt d messaging` — cleanly removes all generated files
+- Default controllers (Devise-style — work from gem, override by generating)
+- Terraform module: Pinpoint toll-free number, two-way messaging, SNS, IAM

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,224 @@
+# belt-messaging
+
+SMS and email messaging for [Belt](https://github.com/stowzilla/belt) applications via AWS.
+
+- **SMS** via AWS End User Messaging (PinpointSMSVoiceV2)
+- **Email** via AWS Simple Email Service (SESv2)
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'belt-messaging'
+```
+
+Then:
+
+```bash
+bundle install
+belt generate messaging
+```
+
+## What You Get
+
+### From the gem (no generation needed)
+
+```ruby
+# Send an SMS from anywhere in your app
+Belt::Messaging.send_sms(to: '+15551234567', message: 'Your order is ready!')
+Belt::Messaging.send_sms(to: '555-123-4567', message: 'Hello!') # auto-formats to E.164
+
+# Send an email from anywhere in your app
+Belt::Messaging.send_email(
+  to: 'user@example.com',
+  subject: 'Welcome!',
+  body: 'Thanks for signing up.'
+)
+
+# With HTML body
+Belt::Messaging.send_email(
+  to: ['user1@example.com', 'user2@example.com'],
+  subject: 'Weekly Update',
+  body: 'Plain text version...',
+  html: '<h1>Weekly Update</h1><p>HTML version...</p>'
+)
+
+# Phone number utilities
+Belt::Messaging::PhoneFormatter.format_e164('(555) 123-4567') #=> '+15551234567'
+Belt::Messaging::PhoneFormatter.valid?('555-123-4567')         #=> true
+
+# Email validation
+Belt::Messaging::Email.valid_email?('user@example.com')        #=> true
+```
+
+### From the generator (`belt g messaging`)
+
+- **Terraform module** — Pinpoint phone number, SES identity, SNS topics, IAM policies
+- **Lambda entry point** — Dedicated Lambda for inbound SMS (STOP/START handling)
+- **Controllers** — SMS verification + messaging events (override to customize)
+- **Route injection** — Adds `sms-verification` to your routes
+
+## Configuration
+
+Environment variables:
+
+### SMS Configuration
+
+| Variable | Purpose | Default |
+|----------|---------|---------|
+| `ENABLE_SMS` | Master switch for sending SMS | `false` |
+| `SMS_MODE` | Gating mode: `none`, `whitelist`, `all` | `none` |
+| `SMS_WHITELIST` | Comma-separated E.164 numbers (for whitelist mode) | — |
+| `SMS_ORIGINATION_NUMBER` | Your toll-free number (E.164) | — |
+
+### Email Configuration
+
+| Variable | Purpose | Default |
+|----------|---------|---------|
+| `ENABLE_EMAIL` | Master switch for sending email | `false` |
+| `EMAIL_MODE` | Gating mode: `none`, `whitelist`, `all` | `none` |
+| `EMAIL_WHITELIST` | Comma-separated addresses (for whitelist mode) | — |
+| `EMAIL_FROM_ADDRESS` | Your verified sender address | — |
+| `AWS_REGION` | AWS region for SES/Pinpoint | `us-east-1` |
+
+### Programmatic configuration
+
+```ruby
+Belt::Messaging.configure do |config|
+  # SMS
+  config.sms_mode = 'whitelist'
+  config.sms_whitelist = ['+15551234567']
+  config.origination_number = '+18005550000'
+
+  # Email
+  config.email_mode = 'whitelist'
+  config.email_whitelist = ['dev@example.com']
+  config.email_from_address = 'noreply@example.com'
+end
+```
+
+## Messaging Modes
+
+Both SMS and email use the same gating pattern:
+
+| Mode | Behavior |
+|------|----------|
+| `none` | Never send (safe default for development) |
+| `whitelist` | Only send to addresses in the whitelist |
+| `all` | Send to everyone (production) |
+
+## Customizing Controllers
+
+By default, the gem provides controllers that handle SMS verification and opt-in/opt-out.
+To customize behavior, generate controller overrides into your app:
+
+```bash
+belt g messaging --controllers    # Generate overrides you can edit
+```
+
+The generated controllers are scaffolds with TODO comments showing where to add your persistence logic.
+If you don't generate them, the gem's built-in controllers handle everything with sensible defaults.
+
+## Terraform Module
+
+After running `belt g messaging`, add the module to your environment's `main.tf`:
+
+```hcl
+module "messaging" {
+  source      = "../modules/messaging"
+  app_name    = var.app_name
+  environment = var.environment
+  aws_region  = var.aws_region
+
+  # SMS Configuration
+  enable_sms = true
+
+  # Optional: request a new toll-free number
+  # request_toll_free_number = true
+
+  # Optional: use a shared number for dev
+  # sms_origination_number = "+18005550000"
+
+  # Email Configuration
+  enable_email = true
+
+  # Option 1: Verify entire domain (recommended for production)
+  # email_domain = "example.com"
+
+  # Option 2: Verify single address (quick setup)
+  email_from_address = "noreply@example.com"
+}
+```
+
+### Email Identity Verification
+
+For **domain verification** (production):
+1. Set `email_domain = "your-domain.com"` and deploy
+2. Add the DKIM DNS records output by Terraform
+3. Wait for verification (usually minutes)
+4. Set `EMAIL_FROM_ADDRESS` to any address on that domain
+
+For **address verification** (quick dev setup):
+1. Set `email_from_address = "noreply@example.com"` and deploy
+2. Check the inbox and click the verification link
+3. Set `EMAIL_FROM_ADDRESS` to the verified address
+
+### SES Sandbox
+
+New AWS accounts start in the SES sandbox, which limits sending to verified addresses only.
+For production, request production access in the AWS Console → SES → Account Dashboard.
+
+## AWS Approval Process
+
+### SMS: Toll-Free Verification (Recommended)
+
+1. Set `request_toll_free_number = true` and deploy
+2. Go to AWS Console → End User Messaging → Registrations
+3. Submit toll-free verification:
+   - Company name and address
+   - Use case description
+   - Sample messages
+4. Wait 2-15 business days for approval
+5. Once ACTIVE, update `SMS_ORIGINATION_NUMBER` with the new number
+
+**Cost:** ~$2/month + $0.0075/message segment
+
+### SMS: 10DLC (Higher Volume)
+
+For higher throughput at lower per-message cost:
+
+1. Register your brand in the 10DLC registry
+2. Create a campaign describing your use case
+3. Provision a 10DLC number
+4. Update configuration
+
+**Cost:** $0.0025-$0.005/segment, requires brand ($4/month) + campaign registration
+
+### SMS: Short Code (Highest Throughput)
+
+For very high volume (100+ messages/second):
+
+1. Apply for a short code through AWS
+2. Complete carrier vetting process
+3. Wait 8-12 weeks for approval
+
+**Cost:** $1000+/month
+
+### Email: SES Pricing
+
+- **First 62,000 emails/month:** Free (from EC2/Lambda)
+- **After that:** $0.10 per 1,000 emails
+- Attachments: $0.12 per GB
+
+## Removing
+
+```bash
+belt destroy messaging
+```
+
+Then remove the module reference from your environment `main.tf` files.
+
+## License
+
+MIT

data/lib/belt/generators/messaging_generator.rb

@@ -0,0 +1,316 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'erb'
+
+module Belt
+  module Generators
+    class MessagingGenerator
+      TEMPLATE_DIR = File.expand_path('../messaging/templates', __dir__)
+
+      def self.description
+        'Install two-way SMS messaging (AWS PinpointSMSVoiceV2)'
+      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 two-way SMS messaging infrastructure for your Belt app.
+
+          Usage: belt generate messaging [options]
+
+          Options:
+            --controllers         Generate controller overrides (to customize behavior)
+            --force               Overwrite existing files
+
+          What gets created:
+            infrastructure/modules/messaging/           Terraform module (Pinpoint, SNS, IAM)
+            config/lambda/messaging_events.yml          Lambda configuration (timeout, memory, env, triggers)
+            config/routes.tf.rb                         Routes for sms-verification (updated)
+            lambda/messaging_events.rb                  Lambda entry point for inbound SMS
+
+          What stays in the gem (no generation needed):
+            Belt::Messaging.send_sms(to:, message:)    Send SMS from anywhere
+            Belt::Messaging::PhoneFormatter             E.164 formatting
+            Belt::Messaging::SmsGate                    Whitelist/mode gating
+            SmsVerificationController                   Phone verification (gem default)
+            SmsEventsController                         Opt-in/opt-out handling (gem default)
+
+          To override controllers (like `rails g devise:views`):
+            belt g messaging --controllers
+
+          After generation:
+            1. Add module reference to your environment's main.tf
+            2. Configure environment variables (ENABLE_SMS, SMS_MODE, etc.)
+            3. Deploy: belt apply <env>
+            4. Request toll-free number via AWS console (if not already acquired)
+
+          Examples:
+            belt g messaging                 # Infrastructure only (use gem defaults)
+            belt g messaging --controllers   # Also generate controller overrides
+            belt d messaging
+        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_routes
+        print_success
+      end
+
+      def destroy
+        remove_terraform_module
+        remove_lambda_config
+        remove_lambda_entry_point
+        remove_controllers
+        remove_routes
+        puts "\n✓ Messaging 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
+
+      # Finds routes.tf.rb checking config/ first, then infrastructure/ (legacy).
+      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/messaging'
+
+        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}/messaging_events.yml"
+
+        if File.exist?(dest) && !@force
+          puts "  skip    #{dest} (already exists)"
+          return
+        end
+
+        FileUtils.mkdir_p(config_dir)
+        write_template('config/messaging_events.yml.erb', dest)
+        puts "  create  #{dest}"
+      end
+
+      def generate_lambda_entry_point
+        dest = 'lambda/messaging_events.rb'
+
+        if File.exist?(dest) && !@force
+          puts "  skip    #{dest} (already exists)"
+          return
+        end
+
+        write_template('lambda/messaging_events.rb.erb', dest)
+        puts "  create  #{dest}"
+      end
+
+      def generate_controllers
+        controller_dir = "lambda/controllers/#{@app_name}"
+        FileUtils.mkdir_p(controller_dir)
+
+        # SMS Verification controller
+        verification_dest = "#{controller_dir}/sms_verification_controller.rb"
+        if File.exist?(verification_dest) && !@force
+          puts "  skip    #{verification_dest} (already exists)"
+        else
+          write_template('controllers/sms_verification_controller.rb.erb', verification_dest)
+          puts "  create  #{verification_dest}"
+        end
+
+        # SMS Events controller (for override)
+        events_dir = 'lambda/controllers/messaging_events'
+        FileUtils.mkdir_p(events_dir)
+
+        events_dest = "#{events_dir}/messaging_events_controller.rb"
+        if File.exist?(events_dest) && !@force
+          puts "  skip    #{events_dest} (already exists)"
+        else
+          write_template('controllers/messaging_events_controller.rb.erb', events_dest)
+          puts "  create  #{events_dest}"
+        end
+      end
+
+      def inject_routes
+        routes_file = find_routes_file_path
+        return unless routes_file && File.exist?(routes_file)
+
+        content = File.read(routes_file)
+
+        # Add sms-verification route to app namespace
+        unless content.include?('sms_verification') || content.include?('sms-verification')
+          namespace_pattern = /^(\s*)namespace :#{Regexp.escape(@app_name)}\b[^\n]*do\s*\n(.*?)^\1end/m
+          if content.match?(namespace_pattern)
+            sms_route = "    resource :sms_verification, only: [:create, :update]"
+            content.sub!(namespace_pattern) do |match|
+              indent = ::Regexp.last_match(1)
+              match.sub(/^(#{indent})end\z/m, "#{sms_route}\n#{indent}end")
+            end
+          end
+        end
+
+        File.write(routes_file, content)
+        puts "  update  #{routes_file}"
+      end
+
+      # ---- Destroy ----
+
+      def remove_terraform_module
+        module_dir = 'infrastructure/modules/messaging'
+        if Dir.exist?(module_dir)
+          FileUtils.rm_rf(module_dir)
+          puts "  remove  #{module_dir}/"
+        end
+      end
+
+      def remove_lambda_config
+        path = 'config/lambda/messaging_events.yml'
+        if File.exist?(path)
+          File.delete(path)
+          puts "  remove  #{path}"
+        end
+      end
+
+      def remove_lambda_entry_point
+        path = 'lambda/messaging_events.rb'
+        if File.exist?(path)
+          File.delete(path)
+          puts "  remove  #{path}"
+        end
+      end
+
+      def remove_controllers
+        events_dir = 'lambda/controllers/messaging_events'
+        if Dir.exist?(events_dir)
+          FileUtils.rm_rf(events_dir)
+          puts "  remove  #{events_dir}/"
+        end
+
+        verification = "lambda/controllers/#{@app_name}/sms_verification_controller.rb"
+        if File.exist?(verification)
+          File.delete(verification)
+          puts "  remove  #{verification}"
+        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*resource :sms_verification.*\n/, '')
+
+        if content != original
+          File.write(routes_file, content)
+          puts "  update  #{routes_file}"
+        end
+      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
+
+          ✓ Messaging installed!
+
+          Next steps:
+            1. Add the module to your environment's main.tf:
+
+               module "messaging" {
+                 source      = "../modules/messaging"
+                 app_name    = var.app_name
+                 environment = var.environment
+                 aws_region  = var.aws_region
+               }
+
+            2. Configure environment variables:
+               ENABLE_SMS=true
+               SMS_MODE=whitelist
+               SMS_WHITELIST=+15551234567
+               SMS_ORIGINATION_NUMBER=+1XXXXXXXXXX
+
+            3. Deploy:
+               belt apply <env>
+
+            4. Request a toll-free number (if needed):
+               Set request_toll_free_number = true in your module call,
+               or provide sms_origination_number for a shared number.
+
+            5. Complete AWS Toll-Free Verification:
+               - Go to AWS Console → End User Messaging → Registrations
+               - Submit toll-free verification (company info, use case, sample messages)
+               - Typical approval: 2-15 business days
+
+            6. Test:
+               belt c <env> --run "Belt::Messaging.send_sms(to: '+15551234567', message: 'Hello!')"
+
+          SMS Modes:
+            none       — Never send (default, safe for dev)
+            whitelist  — Only send to numbers in SMS_WHITELIST
+            all        — Send to everyone (production)
+
+          Documentation:
+            Toll-Free:  Simplest approval, ~$2/mo + $0.0075/segment
+            10DLC:      Cheaper at volume, requires brand + campaign registration
+            Short Code: Highest throughput, $1000+/mo, lengthy approval
+
+        SUCCESS
+      end
+    end
+  end
+end

data/lib/belt/messaging/configuration.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Belt
+  module Messaging
+    class Configuration
+      # SMS configuration
+      attr_accessor :aws_region, :origination_number, :sms_mode, :sms_whitelist,
+                    :opt_in_message, :logger
+
+      # Email configuration
+      attr_accessor :email_from_address, :email_mode, :email_whitelist
+
+      def initialize
+        @aws_region = ENV['AWS_REGION'] || 'us-east-1'
+
+        # SMS
+        @origination_number = ENV['SMS_ORIGINATION_NUMBER']
+        @sms_mode = ENV['SMS_MODE'] || 'none'
+        @sms_whitelist = (ENV['SMS_WHITELIST'] || '').split(',').map(&:strip)
+        @opt_in_message = 'You have been re-subscribed to SMS notifications.'
+
+        # Email
+        @email_from_address = ENV['EMAIL_FROM_ADDRESS']
+        @email_mode = ENV['EMAIL_MODE'] || 'none'
+        @email_whitelist = (ENV['EMAIL_WHITELIST'] || '').split(',').map(&:strip)
+
+        @logger = nil # Falls back to Belt::Observability::Logger if available
+      end
+
+      # SMS enabled check
+      def enabled?
+        ENV['ENABLE_SMS'] == 'true'
+      end
+
+      # Email enabled check
+      def email_enabled?
+        ENV['ENABLE_EMAIL'] == 'true'
+      end
+    end
+  end
+end

data/lib/belt/messaging/controllers/messaging_events_controller.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Belt
+  module Messaging
+    module Controllers
+      # Default SMS events controller for handling inbound opt-out/opt-in messages.
+      # This controller processes STOP/START keywords from two-way messaging.
+      #
+      # To customize behavior, generate the controller override:
+      #   belt g messaging
+      #
+      # Then modify lambda/controllers/messaging_events/messaging_events_controller.rb
+      class MessagingEventsController < BeltController::Base
+        OPT_OUT_KEYWORDS = %w[ARRET CANCEL END OPT-OUT OPTOUT QUIT REMOVE STOP TD UNSUBSCRIBE].freeze
+        OPT_IN_KEYWORDS = %w[START UNSTOP].freeze
+
+        def opt_out
+          phone = sms_origin_phone
+
+          Belt::Messaging.log(:info, 'Processing SMS opt-out', phone: phone)
+
+          # Default: log the opt-out. Users should override this controller
+          # to update their own user/customer model.
+          Belt::Messaging.log(:warn,
+            'SMS opt-out received but no handler configured. Override MessagingEventsController to handle.',
+            phone: phone
+          )
+
+          success_response(success: true, processed: false, reason: 'no_handler_configured')
+        end
+
+        def opt_in
+          phone = sms_origin_phone
+
+          Belt::Messaging.log(:info, 'Processing SMS opt-in', phone: phone)
+
+          Belt::Messaging.log(:warn,
+            'SMS opt-in received but no handler configured. Override MessagingEventsController to handle.',
+            phone: phone
+          )
+
+          success_response(success: true, processed: false, reason: 'no_handler_configured')
+        end
+
+        private
+
+        def sms_origin_phone
+          records = @event['Records']
+          return nil unless records&.first
+
+          message = JSON.parse(records.first.dig('Sns', 'Message') || '{}')
+          message['originationNumber']
+        end
+      end
+    end
+  end
+end