belt-messaging 0.1.0

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Belt
+  module Messaging
+    module Controllers
+      # Default SMS verification controller.
+      # Provides send-code and verify-code actions.
+      #
+      # To customize, generate the controller override:
+      #   belt g messaging
+      #
+      # Then modify lambda/controllers/<app>/sms_verification_controller.rb
+      #
+      # This default implementation requires you to handle persistence yourself
+      # via the on_code_generated and on_code_verified callbacks.
+      class SmsVerificationController < BeltController::Base
+        # POST /sms-verification — send a verification code
+        def create
+          phone = params[:phone]
+          return error_response('Phone number is required', 422) if phone.to_s.strip.empty?
+
+          formatted = PhoneFormatter.format_e164(phone)
+          return error_response('Invalid phone number format', 422) unless formatted
+
+          code = SecureRandom.random_number(10**6).to_s.rjust(6, '0')
+
+          sent = Belt::Messaging.send_sms(
+            to: formatted,
+            message: "Your verification code is: #{code}"
+          )
+
+          unless sent
+            return error_response('Unable to send SMS. Please try again later.', 503)
+          end
+
+          Belt::Messaging.log(:info, 'SMS verification code sent', phone: formatted)
+          success_response(message: 'Verification code sent')
+        end
+
+        # PUT /sms-verification — verify the code
+        def update
+          code = params[:code].to_s.strip
+          return error_response('Verification code is required', 422) if code.empty?
+
+          # Default: no persistence layer — override this controller
+          Belt::Messaging.log(:warn,
+            'SMS verification attempted but no persistence configured. Override SmsVerificationController.')
+
+          success_response(message: 'Verification not implemented — override the controller')
+        end
+      end
+    end
+  end
+end

data/lib/belt/messaging/email.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require 'aws-sdk-sesv2'
+
+module Belt
+  module Messaging
+    # Core email sending via AWS SESv2.
+    module Email
+      extend Logging
+
+      # Send a transactional email.
+      #
+      # All recipients must pass the EmailGate check. If any recipient is blocked,
+      # the entire send is rejected (returns false). This mirrors SMS behavior where
+      # a blocked recipient causes the send to fail. Callers who want partial delivery
+      # should filter recipients through EmailGate.allowed? before calling send.
+      #
+      # @param to [String, Array<String>] Recipient email address(es)
+      # @param subject [String] Email subject
+      # @param body [String] Email body (plain text)
+      # @param html [String, nil] Optional HTML body
+      # @param from [String, nil] Override the configured from address
+      # @return [Boolean] true if sent successfully, false otherwise
+      def self.send(to:, subject:, body:, html: nil, from: nil)
+        config = Belt::Messaging.configuration
+
+        unless config.email_enabled?
+          log(:warn, 'Email sending is disabled (ENABLE_EMAIL != true)')
+          return false
+        end
+
+        recipients = Array(to)
+        if recipients.empty?
+          log(:error, 'No recipients provided')
+          return false
+        end
+
+        invalid = recipients.reject { |email| valid_email?(email) }
+        if invalid.any?
+          log(:error, 'Invalid email address format', invalid: invalid)
+          return false
+        end
+
+        blocked = recipients.reject { |email| EmailGate.allowed?(email) }
+        if blocked.any?
+          log(:warn, 'Email recipients blocked by current EMAIL_MODE',
+              blocked: blocked, mode: config.email_mode)
+          return false
+        end
+
+        from_address = from || config.email_from_address
+        if from_address.nil? || from_address.empty?
+          log(:error, 'EMAIL_FROM_ADDRESS not configured')
+          return false
+        end
+
+        begin
+          client = Aws::SESV2::Client.new(region: config.aws_region)
+
+          email_content = build_email_content(subject, body, html)
+
+          client.send_email({
+            from_email_address: from_address,
+            destination: { to_addresses: recipients },
+            content: { simple: email_content }
+          })
+
+          log(:info, 'Email sent successfully', to: recipients, subject: subject)
+          true
+        rescue Aws::SESV2::Errors::AccessDeniedException => e
+          raise Belt::Messaging::Error,
+            "Email AccessDenied: ses:SendEmail not allowed. " \
+            "Check SES permissions in your messaging terraform module. " \
+            "Original: #{e.message}"
+        rescue Aws::SESV2::Errors::MessageRejected => e
+          log(:error, 'Email rejected by SES', error: e.message, to: recipients)
+          false
+        rescue Aws::SESV2::Errors::ServiceError => e
+          log(:error, 'Failed to send email', error: e.message, to: recipients)
+          false
+        end
+      end
+
+      # Validate basic email format.
+      # @param email [String]
+      # @return [Boolean]
+      def self.valid_email?(email)
+        return false if email.nil? || email.empty?
+
+        # Basic validation: has @ with something before and after
+        email.match?(/\A[^@\s]+@[^@\s]+\.[^@\s]+\z/)
+      end
+
+      def self.build_email_content(subject, body, html)
+        content = {
+          subject: { data: subject, charset: 'UTF-8' },
+          body: {
+            text: { data: body, charset: 'UTF-8' }
+          }
+        }
+        content[:body][:html] = { data: html, charset: 'UTF-8' } if html
+        content
+      end
+      private_class_method :build_email_content
+    end
+  end
+end

data/lib/belt/messaging/email_gate.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Belt
+  module Messaging
+    # Controls whether emails are actually sent based on EMAIL_MODE.
+    # Modes:
+    #   - "none"      — never send (default, safe for development)
+    #   - "whitelist" — only send to addresses in EMAIL_WHITELIST
+    #   - "all"       — send to everyone (production)
+    module EmailGate
+      extend Logging
+
+      # Check if a given email address is allowed to receive email.
+      # @param email [String] Email address
+      # @return [Boolean]
+      def self.allowed?(email)
+        config = Belt::Messaging.configuration
+        mode = config.email_mode
+
+        case mode
+        when 'none'
+          false
+        when 'all'
+          true
+        when 'whitelist'
+          normalized = email.to_s.downcase.strip
+          config.email_whitelist.any? { |allowed| allowed.downcase.strip == normalized }
+        else
+          log(:warn, 'Unknown EMAIL_MODE, defaulting to none', mode: mode)
+          false
+        end
+      end
+    end
+  end
+end

data/lib/belt/messaging/logging.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Belt
+  module Messaging
+    # Shared logging helper for messaging modules.
+    # Routes to the configured logger, or falls back to Belt::Observability::Logger.
+    module Logging
+      private
+
+      def log(level, message, **kwargs)
+        logger = Belt::Messaging.configuration.logger
+        if logger
+          logger.public_send(level, message, **kwargs)
+        elsif defined?(Belt::Observability::Logger)
+          Belt::Observability::Logger.public_send(level, message, **kwargs)
+        end
+      end
+    end
+  end
+end

data/lib/belt/messaging/phone_formatter.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Belt
+  module Messaging
+    # Formats phone numbers to E.164 format (+1XXXXXXXXXX for US numbers).
+    module PhoneFormatter
+      # Format a phone number to E.164.
+      # @param phone [String] Phone number in any common US format
+      # @return [String, nil] E.164 formatted number, or nil if invalid
+      def self.format_e164(phone)
+        return nil if phone.nil? || phone.to_s.strip.empty?
+
+        # Already has + prefix — validate it
+        if phone.start_with?('+')
+          digits = phone.gsub(/\D/, '')
+          return "+#{digits}" if digits.length >= 11
+          return nil
+        end
+
+        # Remove all non-digit characters
+        digits = phone.gsub(/\D/, '')
+
+        case digits.length
+        when 10
+          # US number without country code
+          "+1#{digits}"
+        when 11
+          # US number with country code
+          digits.start_with?('1') ? "+#{digits}" : nil
+        else
+          nil
+        end
+      end
+
+      # Check if a string looks like a valid phone number.
+      # @param phone [String] Phone number to validate
+      # @return [Boolean]
+      def self.valid?(phone)
+        !format_e164(phone).nil?
+      end
+    end
+  end
+end

data/lib/belt/messaging/sms.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'aws-sdk-pinpointsmsvoicev2'
+
+module Belt
+  module Messaging
+    # Core SMS sending via AWS PinpointSMSVoiceV2.
+    module SMS
+      extend Logging
+
+      # Send an SMS message.
+      # @param to [String] Recipient phone number (any US format)
+      # @param message [String] Message body (max 160 chars for single segment)
+      # @return [Boolean] true if sent successfully, false otherwise
+      def self.send(to:, message:)
+        config = Belt::Messaging.configuration
+
+        unless config.enabled?
+          log(:warn, 'SMS sending is disabled (ENABLE_SMS != true)')
+          return false
+        end
+
+        formatted_phone = PhoneFormatter.format_e164(to)
+        unless formatted_phone
+          log(:error, 'Invalid phone number format', phone: to)
+          return false
+        end
+
+        unless SmsGate.allowed?(formatted_phone)
+          log(:warn, 'SMS recipient not allowed by current SMS_MODE', to: formatted_phone, mode: config.sms_mode)
+          return false
+        end
+
+        origination = config.origination_number
+        if origination.nil? || origination.empty?
+          log(:error, 'SMS_ORIGINATION_NUMBER not configured')
+          return false
+        end
+
+        begin
+          client = Aws::PinpointSMSVoiceV2::Client.new(region: config.aws_region)
+
+          client.send_text_message({
+            destination_phone_number: formatted_phone,
+            origination_identity: origination,
+            message_body: message,
+            message_type: 'TRANSACTIONAL'
+          })
+
+          log(:info, 'SMS sent successfully', to: formatted_phone)
+          true
+        rescue Aws::PinpointSMSVoiceV2::Errors::AccessDeniedException => e
+          raise Belt::Messaging::Error,
+            "SMS AccessDenied: sms-voice:SendTextMessage not allowed. " \
+            "Check Pinpoint SMS permissions in your messaging terraform module. " \
+            "Original: #{e.message}"
+        rescue Aws::PinpointSMSVoiceV2::Errors::ServiceError => e
+          log(:error, 'Failed to send SMS', error: e.message, to: formatted_phone)
+          false
+        end
+      end
+    end
+  end
+end

data/lib/belt/messaging/sms_gate.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Belt
+  module Messaging
+    # Controls whether SMS messages are actually sent based on SMS_MODE.
+    # Modes:
+    #   - "none"      — never send (default, safe for development)
+    #   - "whitelist" — only send to numbers in SMS_WHITELIST
+    #   - "all"       — send to everyone (production)
+    module SmsGate
+      extend Logging
+
+      # Check if a given phone number is allowed to receive SMS.
+      # @param phone [String] E.164 formatted phone number
+      # @return [Boolean]
+      def self.allowed?(phone)
+        config = Belt::Messaging.configuration
+        mode = config.sms_mode
+
+        case mode
+        when 'none'
+          false
+        when 'all'
+          true
+        when 'whitelist'
+          config.sms_whitelist.include?(phone)
+        else
+          log(:warn, 'Unknown SMS_MODE, defaulting to none', mode: mode)
+          false
+        end
+      end
+    end
+  end
+end

data/lib/belt/messaging/templates/config/messaging_events.yml.erb

@@ -0,0 +1,41 @@
+# Lambda configuration for the messaging_events function.
+# Handles inbound SMS events (STOP/START keywords) via SNS two-way messaging.
+#
+# Generated by: belt generate messaging
+#
+# Keys:
+#   timeout           Lambda timeout in seconds
+#   memory_size       Lambda memory in MB
+#   env_vars          Environment variables (static values or ref() for Terraform values)
+#   sns_triggers      SNS topic triggers (inbound SMS events)
+#
+# ref(name) references are resolved from lambda_env_refs in Terraform.
+#
+# Usage:
+#   belt lambda-config -e prod         # View merged config for prod
+#   belt lambda-config -f terraform    # Output as Terraform-ready lambda_config
+
+default: &default
+  timeout: 30
+  memory_size: 256
+  env_vars:
+    ENABLE_SMS: "true"
+    SMS_MODE: ref(sms_mode)
+    SMS_ORIGINATION_NUMBER: ref(sms_origination_number)
+  sns_triggers:
+    - ref(sms_inbound_topic_arn)
+
+dev:
+  <<: *default
+  env_vars:
+    ENABLE_SMS: "true"
+    SMS_MODE: "whitelist"
+    SMS_WHITELIST: ref(sms_whitelist)
+    SMS_ORIGINATION_NUMBER: ref(sms_origination_number)
+
+prod:
+  <<: *default
+  env_vars:
+    ENABLE_SMS: "true"
+    SMS_MODE: "all"
+    SMS_ORIGINATION_NUMBER: ref(sms_origination_number)

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+# Generated by: belt generate messaging
+# Override this controller to customize inbound SMS opt-in/opt-out handling.
+# The default implementation is in Belt::Messaging::Controllers::MessagingEventsController.
+
+require 'belt'
+require 'belt/messaging'
+
+class MessagingEventsController < BeltController::Base
+  OPT_OUT_KEYWORDS = Belt::Messaging::Controllers::MessagingEventsController::OPT_OUT_KEYWORDS
+  OPT_IN_KEYWORDS = Belt::Messaging::Controllers::MessagingEventsController::OPT_IN_KEYWORDS
+
+  def opt_out
+    phone = sms_origin_phone
+    Belt::Observability::Logger.info('Processing SMS opt-out', phone: phone)
+
+    # Implement your opt-out logic here.
+    # Example: User.where(phone: phone).each { |u| u.update(sms_opted_out: true) }
+
+    success_response(success: true, processed: true)
+  end
+
+  def opt_in
+    phone = sms_origin_phone
+    Belt::Observability::Logger.info('Processing SMS opt-in', phone: phone)
+
+    # Implement your opt-in logic here.
+    # Example: User.where(phone: phone).each { |u| u.update(sms_opted_out: false) }
+
+    success_response(success: true, processed: true)
+  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

data/lib/belt/messaging/templates/controllers/sms_verification_controller.rb.erb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+# Generated by: belt generate messaging
+# Override this controller to customize SMS verification behavior.
+# The default implementation is in Belt::Messaging::Controllers::SmsVerificationController.
+
+require 'belt'
+require 'belt/messaging'
+
+class SmsVerificationController < BeltController::Base
+  # POST /sms-verification — send a 6-digit verification code via SMS
+  def create
+    phone = params[:phone]
+    return error_response('Phone number is required', 422) if phone.to_s.strip.empty?
+
+    code = SecureRandom.random_number(10**6).to_s.rjust(6, '0')
+
+    sent = Belt::Messaging.send_sms(
+      to: phone,
+      message: "Your verification code is: #{code}"
+    )
+
+    unless sent
+      return error_response('Unable to send SMS. Please try again later.', 503)
+    end
+
+    # Store the code — implement your own persistence here.
+    # Example: current_user.update(sms_verification_code: code, sms_verification_expires_at: 10.minutes.from_now)
+
+    success_response(message: 'Verification code sent')
+  end
+
+  # PUT /sms-verification — verify the code
+  def update
+    code = params[:code].to_s.strip
+    return error_response('Verification code is required', 422) if code.empty?
+
+    # Implement your own verification logic here.
+    # Example:
+    #   stored_code = current_user.sms_verification_code
+    #   return error_response('Invalid code', 422) unless code == stored_code
+    #   current_user.update(phone_verified: true, sms_verification_code: nil)
+
+    success_response(message: 'Phone number verified', phone_verified: true)
+  end
+end

data/lib/belt/messaging/templates/lambda/messaging_events.rb.erb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+# Generated by: belt generate messaging
+# Lambda entry point for inbound SMS events (two-way messaging).
+# Receives SNS notifications when customers text STOP/START to your number.
+
+require_relative 'config/environment'
+
+include Belt::LambdaHandler
+
+ROUTER = Belt::ActionRouter.new(
+  routes: [
+    { verb: 'POST', path: '/opt_out', controller: 'messaging_events', action: 'opt_out' },
+    { verb: 'POST', path: '/opt_in', controller: 'messaging_events', action: 'opt_in' }
+  ],
+  namespace: 'messaging_events'
+)
+
+def execute(path:, body:, event:)
+  ROUTER.route(event: event, body: body)
+end
+
+# Override lambda_handler to detect SNS events from two-way messaging.
+# Pinpoint forwards inbound SMS via SNS — the event has a Records array
+# instead of httpMethod/path. We translate it into a synthetic API Gateway event.
+def lambda_handler(event:, context:)
+  if event['Records'] && event.dig('Records', 0, 'EventSource') == 'aws:sns'
+    handle_sns_event(event: event, context: context)
+  else
+    super(event: event, context: context)
+  end
+end
+
+private
+
+def handle_sns_event(event:, context:)
+  init_observability(context: context)
+
+  event['Records'].each do |record|
+    message = JSON.parse(record['Sns']['Message'])
+    keyword = message['messageBody']&.strip&.upcase
+
+    opt_out_keywords = Belt::Messaging::Controllers::MessagingEventsController::OPT_OUT_KEYWORDS
+    opt_in_keywords = Belt::Messaging::Controllers::MessagingEventsController::OPT_IN_KEYWORDS
+
+    action_path = if opt_out_keywords.include?(keyword)
+                    '/opt_out'
+                  elsif opt_in_keywords.include?(keyword)
+                    '/opt_in'
+                  else
+                    Belt::Observability::Logger.info('Ignoring unrecognized SMS keyword',
+                      keyword: keyword, phone: message['originationNumber'])
+                    next
+                  end
+
+    Belt::Observability::Logger.info('Routing inbound SMS',
+      keyword: keyword, path: action_path, phone: message['originationNumber'])
+
+    synthetic_event = {
+      'httpMethod' => 'POST',
+      'path' => action_path,
+      'headers' => {},
+      'queryStringParameters' => {},
+      'pathParameters' => {},
+      'Records' => event['Records'],
+      'body' => nil
+    }
+
+    execute(path: action_path, body: {}, event: synthetic_event)
+  end
+
+  { statusCode: 200, body: JSON.generate(success: true) }
+rescue => e
+  Belt::Observability::Logger.error('Unhandled error processing inbound SMS', error: e.message)
+  { statusCode: 500, body: JSON.generate(error: 'Internal server error') }
+end