belt-messaging 0.1.0

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

@@ -0,0 +1,266 @@
+# Messaging Module — SMS via AWS PinpointSMSVoiceV2, Email via AWS SESv2
+# Generated by: belt generate messaging
+#
+# Provides:
+# - Toll-free number provisioning (or shared number configuration)
+# - Two-way messaging (inbound SMS → SNS → Lambda)
+# - IAM policy for sending SMS
+# - Opt-in keyword configuration (START/UNSTOP)
+# - SES email identity verification
+# - IAM policy for sending email
+
+terraform {
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = "~> 5.0"
+    }
+  }
+}
+
+locals {
+  common_tags = {
+    Module      = "messaging"
+    Environment = var.environment
+    ManagedBy   = "Terraform"
+  }
+
+  # Safe three-way resolution: domain takes precedence, then address, then empty.
+  # If enable_email is true but neither identity var is set, this resolves to ""
+  # and the email_send policy is skipped (count gated on this being non-empty).
+  email_identity_arn = var.enable_email ? (
+    var.email_domain != "" ? aws_sesv2_email_identity.domain[0].arn : (
+      var.email_from_address != "" ? aws_sesv2_email_identity.address[0].arn : ""
+    )
+  ) : ""
+}
+
+# ============================================================================
+# SNS Topic for Two-Way Messaging (Inbound SMS)
+# ============================================================================
+
+resource "aws_sns_topic" "sms_inbound" {
+  count = var.enable_sms ? 1 : 0
+
+  name = "${var.app_name}-${var.environment}-sms-inbound"
+  tags = merge(local.common_tags, {
+    Name = "${var.app_name}-${var.environment}-sms-inbound"
+  })
+}
+
+# Allow Pinpoint SMS/Voice v2 to publish to the inbound SNS topic
+resource "aws_sns_topic_policy" "sms_inbound" {
+  count = var.enable_sms ? 1 : 0
+
+  arn = aws_sns_topic.sms_inbound[0].arn
+  policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [{
+      Sid       = "AllowPinpointSMSPublish"
+      Effect    = "Allow"
+      Principal = { Service = "sms-voice.amazonaws.com" }
+      Action    = "sns:Publish"
+      Resource  = aws_sns_topic.sms_inbound[0].arn
+    }]
+  })
+}
+
+# ============================================================================
+# Toll-Free Number (Optional — Production)
+# ============================================================================
+# Toll-Free Verification (TFV) must be completed manually in the AWS console
+# after provisioning. Number stays PENDING until approved (2-15 business days).
+#
+# Recovery after Terraform timeout:
+#   1. terraform state rm 'module.messaging.aws_pinpointsmsvoicev2_phone_number.toll_free[0]'
+#   2. terraform import 'module.messaging.aws_pinpointsmsvoicev2_phone_number.toll_free[0]' phone-XXXXX
+#   3. Complete TFV registration in the End User Messaging console
+
+resource "aws_pinpointsmsvoicev2_phone_number" "toll_free" {
+  count = var.request_toll_free_number ? 1 : 0
+
+  iso_country_code    = "US"
+  message_type        = "TRANSACTIONAL"
+  number_type         = "TOLL_FREE"
+  number_capabilities = ["SMS"]
+
+  deletion_protection_enabled = true
+
+  two_way_channel_arn           = var.enable_sms ? aws_sns_topic.sms_inbound[0].arn : null
+  two_way_channel_enabled       = var.enable_sms
+  self_managed_opt_outs_enabled = var.enable_sms
+
+  timeouts {
+    create = "2m"
+  }
+
+  tags = merge(local.common_tags, {
+    Name = "${var.app_name}-${var.environment}-sms-toll-free"
+  })
+}
+
+# Configure START/UNSTOP keywords for opt-in on the toll-free number
+resource "terraform_data" "toll_free_opt_in_keywords" {
+  count = var.request_toll_free_number && var.enable_sms ? 1 : 0
+
+  triggers_replace = [aws_pinpointsmsvoicev2_phone_number.toll_free[0].id]
+
+  provisioner "local-exec" {
+    command = <<-EOT
+      aws pinpoint-sms-voice-v2 put-keyword \
+        --origination-identity ${aws_pinpointsmsvoicev2_phone_number.toll_free[0].id} \
+        --keyword START --keyword-message "${var.opt_in_message}" \
+        --keyword-action OPT_IN --region ${var.aws_region} && \
+      aws pinpoint-sms-voice-v2 put-keyword \
+        --origination-identity ${aws_pinpointsmsvoicev2_phone_number.toll_free[0].id} \
+        --keyword UNSTOP --keyword-message "${var.opt_in_message}" \
+        --keyword-action OPT_IN --region ${var.aws_region}
+    EOT
+  }
+}
+
+# ============================================================================
+# Shared Number Two-Way Configuration (Dev/Staging)
+# ============================================================================
+# When using a pre-existing shared toll-free number, configure two-way messaging
+# so inbound STOP/START messages reach this environment's SNS topic.
+#
+# NOTE: Only one environment can "own" two-way on a shared number at a time.
+# The last to apply wins. Fine for dev; production should own its number.
+
+resource "terraform_data" "shared_number_two_way" {
+  count = var.enable_sms && !var.request_toll_free_number && var.sms_origination_number != "" ? 1 : 0
+
+  triggers_replace = [var.sms_origination_number, aws_sns_topic.sms_inbound[0].arn]
+
+  provisioner "local-exec" {
+    command = <<-EOT
+      PHONE_ID=$(aws pinpoint-sms-voice-v2 describe-phone-numbers \
+        --region ${var.aws_region} --output json \
+        | jq -r '.PhoneNumbers[] | select(.PhoneNumber=="${var.sms_origination_number}") | .PhoneNumberId') && \
+      [ -n "$PHONE_ID" ] && \
+      aws pinpoint-sms-voice-v2 update-phone-number \
+        --phone-number-id "$PHONE_ID" \
+        --two-way-enabled \
+        --two-way-channel-arn ${aws_sns_topic.sms_inbound[0].arn} \
+        --self-managed-opt-outs-enabled \
+        --region ${var.aws_region}
+    EOT
+  }
+}
+
+# Configure START/UNSTOP keywords on the shared number
+resource "terraform_data" "shared_number_opt_in_keywords" {
+  count = var.enable_sms && !var.request_toll_free_number && var.sms_origination_number != "" ? 1 : 0
+
+  triggers_replace = [var.sms_origination_number]
+
+  provisioner "local-exec" {
+    command = <<-EOT
+      PHONE_ID=$(aws pinpoint-sms-voice-v2 describe-phone-numbers \
+        --region ${var.aws_region} --output json \
+        | jq -r '.PhoneNumbers[] | select(.PhoneNumber=="${var.sms_origination_number}") | .PhoneNumberId') && \
+      [ -n "$PHONE_ID" ] && \
+      aws pinpoint-sms-voice-v2 put-keyword \
+        --origination-identity "$PHONE_ID" \
+        --keyword START --keyword-message "${var.opt_in_message}" \
+        --keyword-action OPT_IN --region ${var.aws_region} && \
+      aws pinpoint-sms-voice-v2 put-keyword \
+        --origination-identity "$PHONE_ID" \
+        --keyword UNSTOP --keyword-message "${var.opt_in_message}" \
+        --keyword-action OPT_IN --region ${var.aws_region}
+    EOT
+  }
+}
+
+# ============================================================================
+# IAM Policy — SMS Send Permission
+# ============================================================================
+
+data "aws_iam_policy_document" "sms_send" {
+  count = var.enable_sms ? 1 : 0
+
+  statement {
+    effect = "Allow"
+    actions = [
+      "sms-voice:SendTextMessage"
+    ]
+    resources = ["*"]
+  }
+}
+
+resource "aws_iam_policy" "sms_send" {
+  count = var.enable_sms ? 1 : 0
+
+  name        = "${var.app_name}-${var.environment}-sms-send"
+  description = "Allow Lambda to send SMS via PinpointSMSVoiceV2"
+  policy      = data.aws_iam_policy_document.sms_send[0].json
+
+  tags = local.common_tags
+}
+
+# ============================================================================
+# SES Email Identity
+# ============================================================================
+# When enable_email is true, we verify either a domain or specific email address
+# for sending transactional email.
+#
+# Domain verification (recommended for production):
+#   Set email_domain = "example.com" and add the generated DNS records.
+#
+# Email address verification (quick setup):
+#   Set email_from_address = "noreply@example.com" — a verification email is sent.
+
+resource "aws_sesv2_email_identity" "domain" {
+  count = var.enable_email && var.email_domain != "" ? 1 : 0
+
+  email_identity = var.email_domain
+
+  tags = merge(local.common_tags, {
+    Name = "${var.app_name}-${var.environment}-email-domain"
+  })
+}
+
+resource "aws_sesv2_email_identity" "address" {
+  count = var.enable_email && var.email_domain == "" && var.email_from_address != "" ? 1 : 0
+
+  email_identity = var.email_from_address
+
+  tags = merge(local.common_tags, {
+    Name = "${var.app_name}-${var.environment}-email-address"
+  })
+}
+
+# ============================================================================
+# IAM Policy — Email Send Permission
+# ============================================================================
+
+check "email_identity_configured" {
+  assert {
+    condition     = !var.enable_email || var.email_domain != "" || var.email_from_address != ""
+    error_message = "enable_email is true but neither email_domain nor email_from_address is set. No email identity will be created and sending will not work."
+  }
+}
+
+data "aws_iam_policy_document" "email_send" {
+  count = var.enable_email && local.email_identity_arn != "" ? 1 : 0
+
+  statement {
+    effect = "Allow"
+    actions = [
+      "ses:SendEmail",
+      "ses:SendRawEmail" # Forward-looking: supports future attachment/raw MIME use cases
+    ]
+    resources = [local.email_identity_arn]
+  }
+}
+
+resource "aws_iam_policy" "email_send" {
+  count = var.enable_email && local.email_identity_arn != "" ? 1 : 0
+
+  name        = "${var.app_name}-${var.environment}-email-send"
+  description = "Allow Lambda to send email via SESv2"
+  policy      = data.aws_iam_policy_document.email_send[0].json
+
+  tags = local.common_tags
+}

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

@@ -0,0 +1,52 @@
+# Generated by: belt generate messaging
+
+# ============================================================================
+# SMS Outputs
+# ============================================================================
+
+output "sms_inbound_topic_arn" {
+  description = "ARN of SNS topic for inbound SMS events (two-way messaging)"
+  value       = var.enable_sms ? aws_sns_topic.sms_inbound[0].arn : ""
+}
+
+output "toll_free_number" {
+  description = "Toll-free phone number provisioned for SMS origination"
+  value       = var.request_toll_free_number ? aws_pinpointsmsvoicev2_phone_number.toll_free[0].phone_number : ""
+}
+
+output "sms_send_policy_arn" {
+  description = "ARN of IAM policy granting sms-voice:SendTextMessage"
+  value       = var.enable_sms ? aws_iam_policy.sms_send[0].arn : ""
+}
+
+# ============================================================================
+# Email Outputs
+# ============================================================================
+
+output "email_identity" {
+  description = "The verified email identity (domain or address)"
+  value = var.enable_email ? (
+    var.email_domain != "" ? var.email_domain : var.email_from_address
+  ) : ""
+}
+
+output "email_identity_verification_status" {
+  description = "Verification status of the email identity"
+  value = var.enable_email ? (
+    var.email_domain != "" ? aws_sesv2_email_identity.domain[0].verified_for_sending_status : (
+      var.email_from_address != "" ? aws_sesv2_email_identity.address[0].verified_for_sending_status : false
+    )
+  ) : false
+}
+
+output "email_send_policy_arn" {
+  description = "ARN of IAM policy granting ses:SendEmail"
+  value       = var.enable_email && local.email_identity_arn != "" ? aws_iam_policy.email_send[0].arn : ""
+}
+
+output "email_domain_dkim_tokens" {
+  description = "DKIM tokens for DNS configuration (only for domain verification)"
+  value = var.enable_email && var.email_domain != "" ? (
+    aws_sesv2_email_identity.domain[0].dkim_signing_attributes[0].tokens
+  ) : []
+}

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

@@ -0,0 +1,66 @@
+# Generated by: belt generate messaging
+
+variable "app_name" {
+  description = "Application name"
+  type        = string
+}
+
+variable "environment" {
+  description = "Environment name (dev01, staging, prod)"
+  type        = string
+}
+
+variable "aws_region" {
+  description = "AWS region"
+  type        = string
+}
+
+# ============================================================================
+# SMS Configuration
+# ============================================================================
+
+variable "enable_sms" {
+  description = "Enable SMS messaging"
+  type        = bool
+  default     = true
+}
+
+variable "request_toll_free_number" {
+  description = "Provision a new toll-free number (requires TFV registration, 2-15 day approval)"
+  type        = bool
+  default     = false
+}
+
+variable "sms_origination_number" {
+  description = "Pre-existing origination number in E.164 format (for shared dev environments)"
+  type        = string
+  default     = ""
+}
+
+variable "opt_in_message" {
+  description = "Auto-reply message when user texts START/UNSTOP to opt back in"
+  type        = string
+  default     = "You have been re-subscribed to SMS notifications."
+}
+
+# ============================================================================
+# Email Configuration
+# ============================================================================
+
+variable "enable_email" {
+  description = "Enable email messaging via SES"
+  type        = bool
+  default     = false
+}
+
+variable "email_domain" {
+  description = "Domain to verify for sending email (e.g., 'example.com'). Takes precedence over email_from_address."
+  type        = string
+  default     = ""
+}
+
+variable "email_from_address" {
+  description = "Email address to verify for sending (e.g., 'noreply@example.com'). Used only if email_domain is not set."
+  type        = string
+  default     = ""
+}

data/lib/belt/messaging/version.rb

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

data/lib/belt/messaging.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require_relative 'messaging/version'
+require_relative 'messaging/configuration'
+require_relative 'messaging/logging'
+require_relative 'messaging/phone_formatter'
+require_relative 'messaging/sms_gate'
+require_relative 'messaging/sms'
+require_relative 'messaging/email_gate'
+require_relative 'messaging/email'
+
+module Belt
+  module Messaging
+    class Error < StandardError; end
+    class ConfigurationError < Error; end
+
+    extend Logging
+
+    class << self
+      attr_writer :configuration
+
+      # Public logging interface — delegates to the Logging module.
+      # Used by controllers and available to consumer apps.
+      public :log
+
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def configure
+        yield(configuration)
+      end
+
+      def reset_configuration!
+        @configuration = Configuration.new
+      end
+
+      # Convenience: send an SMS
+      # @param to [String] Phone number (any US format — formatted to E.164 automatically)
+      # @param message [String] Message body
+      # @return [Boolean] true if sent successfully
+      def send_sms(to:, message:)
+        SMS.send(to: to, message: message)
+      end
+
+      # Convenience: send an email
+      # @param to [String, Array<String>] 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 configured from address
+      # @return [Boolean] true if sent successfully
+      def send_email(to:, subject:, body:, html: nil, from: nil)
+        Email.send(to: to, subject: subject, body: body, html: html, from: from)
+      end
+    end
+  end
+end

data/lib/belt-messaging.rb

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

metadata

@@ -0,0 +1,112 @@
+--- !ruby/object:Gem::Specification
+name: belt-messaging
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+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: aws-sdk-pinpointsmsvoicev2
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: aws-sdk-sesv2
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: Belt plugin providing SMS and email messaging. SMS via AWS PinpointSMSVoiceV2,
+  email via AWS SESv2. Includes phone verification, opt-in/opt-out handling, and Terraform
+  infrastructure.
+email:
+- andy@stowzilla.com
+- adam@stowzilla.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/belt-messaging.rb
+- lib/belt/generators/messaging_generator.rb
+- lib/belt/messaging.rb
+- lib/belt/messaging/configuration.rb
+- lib/belt/messaging/controllers/messaging_events_controller.rb
+- lib/belt/messaging/controllers/sms_verification_controller.rb
+- lib/belt/messaging/email.rb
+- lib/belt/messaging/email_gate.rb
+- lib/belt/messaging/logging.rb
+- lib/belt/messaging/phone_formatter.rb
+- lib/belt/messaging/sms.rb
+- lib/belt/messaging/sms_gate.rb
+- lib/belt/messaging/templates/config/messaging_events.yml.erb
+- lib/belt/messaging/templates/controllers/messaging_events_controller.rb.erb
+- lib/belt/messaging/templates/controllers/sms_verification_controller.rb.erb
+- lib/belt/messaging/templates/lambda/messaging_events.rb.erb
+- lib/belt/messaging/templates/terraform/main.tf.erb
+- lib/belt/messaging/templates/terraform/outputs.tf.erb
+- lib/belt/messaging/templates/terraform/variables.tf.erb
+- lib/belt/messaging/version.rb
+homepage: https://github.com/stowzilla/belt-messaging
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/stowzilla/belt-messaging
+  source_code_uri: https://github.com/stowzilla/belt-messaging
+  changelog_uri: https://github.com/stowzilla/belt-messaging/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: SMS and email messaging for Belt applications via AWS
+test_files: []