belt-connect 0.2.0

data/lib/belt/connect/templates/frontend/widgets.js.erb

@@ -0,0 +1,59 @@
+<%# belt-connect :: frontend/src/connect/widgets.js -%>
+// Amazon Connect widget registry.
+// Generated by belt-connect. This is the single place that declares every
+// hosted chat widget the app knows about — convention over configuration.
+//
+// Each widget's identity (id, snippetId, widgetUrl) comes straight from the
+// `<script>` snippet the Connect console hands you. Run
+// `belt generate connect add-widget <name> <snippet-file>` to parse a pasted
+// snippet into this file so the base64 snippetId is never retyped by hand
+// (that's what caused the right-instance/wrong-widget 403).
+//
+// The snippetId is a secret, so it's read from a Vite env var at build time;
+// everything else is readable config that lives in the repo. Brand color and
+// typeface default to the belt-connect config but can be overridden per widget.
+//
+// Add a second widget by dropping another entry in the map — no new component,
+// no new env-var sprawl:
+//
+//   sales: {
+//     id: '...',
+//     snippetId: import.meta.env.VITE_CONNECT_SALES_SNIPPET_ID,
+//     widgetUrl: 'https://<instance>.my.connect.aws/.../amazon-connect-chat-interface-client.js',
+//     styles: { iconType: 'CHAT', brandColor: '#0ea5e9' },
+//   }
+
+const BRAND_COLOR = "<%= @brand_color %>";
+const TYPEFACE = "<%= @typeface %>";
+
+export const widgets = {
+  support: {
+    // Widget instance id (4th arg of the Connect bootstrap snippet).
+    id: import.meta.env.VITE_CONNECT_SUPPORT_WIDGET_ID || "",
+    // Secret — stays in env/SSM, never committed.
+    snippetId: import.meta.env.VITE_CONNECT_SUPPORT_SNIPPET_ID,
+    // Hosted widget loader URL (same per Connect instance).
+    widgetUrl: import.meta.env.VITE_CONNECT_SUPPORT_WIDGET_URL,
+    styles: {
+      iconType: "CHAT",
+      brandColor: BRAND_COLOR,
+      typeface: TYPEFACE,
+    },
+  },
+};
+
+// Defaults applied to any widget that doesn't override them.
+export const widgetDefaults = {
+  brandColor: BRAND_COLOR,
+  typeface: TYPEFACE,
+};
+
+export function getWidget(name) {
+  const widget = widgets[name];
+  if (!widget) {
+    throw new Error(
+      `[belt-connect] Unknown widget "${name}". Known widgets: ${Object.keys(widgets).join(", ") || "(none)"}`,
+    );
+  }
+  return widget;
+}

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

@@ -0,0 +1,323 @@
+<%# belt-connect :: infrastructure/modules/connect/main.tf -%>
+# Amazon Connect (Connect Customer) module.
+# Generated by belt-connect for the "<%= @app_name %>" app.
+# Extracted and generalized from Stowzilla's standalone connect-infrastructure.
+
+terraform {
+  required_providers {
+    aws    = { source = "hashicorp/aws" }
+    null   = { source = "hashicorp/null" }
+    random = { source = "hashicorp/random" }
+  }
+}
+
+locals {
+  name_prefix = "${var.app_name}-${var.environment}"
+}
+
+# --- Connect Instance ---
+# Note: the Connect service-linked role (AWSServiceRoleForAmazonConnect) is
+# created automatically by AWS when the first instance is provisioned. It's a
+# one-per-account resource and should not be managed by per-environment Terraform.
+#
+# identity_management_type is a create-time setting: changing it replaces the
+# instance (and everything in it — flows, queues, users, hosted widgets).
+resource "aws_connect_instance" "this" {
+  identity_management_type  = var.identity_management_type
+  instance_alias            = var.instance_alias
+  inbound_calls_enabled     = true
+  outbound_calls_enabled    = false
+  contact_flow_logs_enabled = true
+}
+
+# --- Approved Origins ---
+# Domains allowed to embed the Connect chat widget.
+# No native Terraform resource exists, so we use local-exec.
+resource "null_resource" "approved_origins" {
+  for_each = toset(var.approved_origins)
+
+  provisioner "local-exec" {
+    command = "aws connect associate-approved-origin --instance-id ${aws_connect_instance.this.id} --origin ${each.value}"
+  }
+
+  provisioner "local-exec" {
+    when    = destroy
+    command = "aws connect disassociate-approved-origin --instance-id ${self.triggers.instance_id} --origin ${self.triggers.origin} || true"
+  }
+
+  triggers = {
+    instance_id = aws_connect_instance.this.id
+    origin      = each.value
+  }
+}
+
+# --- Hours of Operation ---
+resource "aws_connect_hours_of_operation" "business_hours" {
+  instance_id = aws_connect_instance.this.id
+  name        = "${local.name_prefix}-business-hours"
+  description = "24/7 availability"
+  time_zone   = var.timezone
+
+  dynamic "config" {
+    for_each = ["MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY", "SATURDAY", "SUNDAY"]
+    content {
+      day = config.value
+      start_time {
+        hours   = 0
+        minutes = 0
+      }
+      end_time {
+        hours   = 0
+        minutes = 0
+      }
+    }
+  }
+
+  tags = { Name = "${local.name_prefix}-business-hours" }
+}
+
+# --- Contact Flow ---
+# Routes to queue during hours, plays message and disconnects off-hours.
+# Off-hours messages are captured as missed contacts in Connect reporting.
+resource "aws_connect_contact_flow" "chat" {
+  instance_id = aws_connect_instance.this.id
+  name        = "${local.name_prefix}-chat-flow"
+  description = "Chat routing with off-hours message queuing"
+  type        = "CONTACT_FLOW"
+
+  content = jsonencode({
+    Version     = "2019-10-30"
+    StartAction = "set-queue"
+    Actions = [
+      {
+        Identifier = "set-queue"
+        Type       = "UpdateContactTargetQueue"
+        Parameters = { QueueId = aws_connect_queue.chat.queue_id }
+        Transitions = {
+          NextAction = "transfer-to-queue"
+          Conditions = []
+          Errors     = [{ NextAction = "disconnect", ErrorType = "NoMatchingError" }]
+        }
+      },
+      {
+        Identifier = "transfer-to-queue"
+        Type       = "TransferContactToQueue"
+        Parameters = {}
+        Transitions = {
+          NextAction = "disconnect"
+          Conditions = []
+          Errors = [
+            { NextAction = "disconnect", ErrorType = "QueueAtCapacity" },
+            { NextAction = "disconnect", ErrorType = "NoMatchingError" }
+          ]
+        }
+      },
+      {
+        Identifier  = "disconnect"
+        Type        = "DisconnectParticipant"
+        Parameters  = {}
+        Transitions = {}
+      }
+    ]
+  })
+
+  tags = { Name = "${local.name_prefix}-chat-flow" }
+}
+
+# --- Queue ---
+resource "aws_connect_queue" "chat" {
+  instance_id           = aws_connect_instance.this.id
+  name                  = "${local.name_prefix}-chat-queue"
+  description           = "Queue for customer chat contacts"
+  hours_of_operation_id = aws_connect_hours_of_operation.business_hours.hours_of_operation_id
+
+  tags = { Name = "${local.name_prefix}-chat-queue" }
+}
+
+# --- Routing Profile ---
+resource "aws_connect_routing_profile" "chat_agents" {
+  instance_id               = aws_connect_instance.this.id
+  name                      = "${local.name_prefix}-chat-agents"
+  description               = "Routing profile for chat agents"
+  default_outbound_queue_id = aws_connect_queue.chat.queue_id
+
+  media_concurrencies {
+    channel     = "CHAT"
+    concurrency = 3
+  }
+
+  queue_configs {
+    channel  = "CHAT"
+    delay    = 0
+    priority = 1
+    queue_id = aws_connect_queue.chat.queue_id
+  }
+
+  tags = { Name = "${local.name_prefix}-chat-agents" }
+}
+
+# --- Users (CONNECT_MANAGED only) ---
+# A chat only "works" once someone can sign in to the CCP and go Available.
+# With SAML that someone comes from your IdP; with CONNECT_MANAGED we create
+# the logins here, attach them to the chat routing profile, and park each
+# generated password in SSM (SecureString) so nothing secret lands in state
+# outputs or in the repo.
+locals {
+  user_security_profiles = distinct(flatten([for u in var.users : u.security_profiles]))
+}
+
+data "aws_connect_security_profile" "builtin" {
+  for_each    = toset(local.user_security_profiles)
+  instance_id = aws_connect_instance.this.id
+  name        = each.value
+}
+
+resource "random_password" "user" {
+  for_each    = var.users
+  length      = 20
+  min_upper   = 2
+  min_lower   = 2
+  min_numeric = 2
+  special     = false
+}
+
+resource "aws_connect_user" "this" {
+  for_each = var.users
+
+  instance_id          = aws_connect_instance.this.id
+  name                 = each.key
+  password             = random_password.user[each.key].result
+  routing_profile_id   = aws_connect_routing_profile.chat_agents.routing_profile_id
+  security_profile_ids = [for p in each.value.security_profiles : data.aws_connect_security_profile.builtin[p].security_profile_id]
+
+  identity_info {
+    first_name = each.value.first_name != "" ? each.value.first_name : each.key
+    last_name  = each.value.last_name != "" ? each.value.last_name : var.environment
+    email      = each.value.email != "" ? each.value.email : null
+  }
+
+  phone_config {
+    phone_type                    = "SOFT_PHONE"
+    auto_accept                   = false
+    after_contact_work_time_limit = 0
+  }
+
+  tags = { Name = "${local.name_prefix}-user-${each.key}" }
+}
+
+resource "aws_ssm_parameter" "user_password" {
+  for_each = var.users
+
+  name        = "/${var.app_name}/${var.environment}/connect/users/${each.key}/password"
+  type        = "SecureString"
+  value       = random_password.user[each.key].result
+  description = "Amazon Connect password for ${each.key} (${var.environment}) — sign in at https://${var.instance_alias}.my.connect.aws"
+
+  tags = { Name = "${local.name_prefix}-user-${each.key}-password" }
+}
+
+# --- SSM Parameters for Chat Widget ---
+# Set these after creating the widget in the Connect admin console.
+# The SSM prefix is /<app_name>/<environment>/connect/ — app-scoped, not hard-coded.
+resource "aws_ssm_parameter" "chat_snippet_id" {
+  name        = "/${var.app_name}/${var.environment}/connect/chat-snippet-id"
+  type        = "String"
+  value       = var.chat_snippet_id != "" ? var.chat_snippet_id : "PENDING_CONSOLE_SETUP"
+  description = "Amazon Connect chat snippet ID for ${var.environment}"
+
+  tags = { Name = "${local.name_prefix}-chat-snippet-id" }
+
+  lifecycle { ignore_changes = [value] }
+}
+
+resource "aws_ssm_parameter" "chat_widget_url" {
+  name        = "/${var.app_name}/${var.environment}/connect/chat-widget-url"
+  type        = "String"
+  value       = var.chat_widget_url != "" ? var.chat_widget_url : "PENDING_CONSOLE_SETUP"
+  description = "Amazon Connect chat widget script URL for ${var.environment}"
+
+  tags = { Name = "${local.name_prefix}-chat-widget-url" }
+
+  lifecycle { ignore_changes = [value] }
+}
+
+resource "aws_ssm_parameter" "chat_widget_element_id" {
+  name        = "/${var.app_name}/${var.environment}/connect/chat-widget-element-id"
+  type        = "String"
+  value       = var.chat_widget_element_id != "" ? var.chat_widget_element_id : "PENDING_CONSOLE_SETUP"
+  description = "Amazon Connect chat widget element/instance ID for ${var.environment}"
+
+  tags = { Name = "${local.name_prefix}-chat-widget-element-id" }
+
+  lifecycle { ignore_changes = [value] }
+}
+
+# Read the widget params back so outputs reflect the LIVE value (set after the
+# console widget exists via `aws ssm put-parameter`) rather than the apply-time
+# var. The snippetId + script URL + element id are a MATCHED SET and must come
+# from the same widget — see the demo-app README "Chat widget 403" runbook.
+data "aws_ssm_parameter" "chat_snippet_id" {
+  name       = aws_ssm_parameter.chat_snippet_id.name
+  depends_on = [aws_ssm_parameter.chat_snippet_id]
+}
+
+data "aws_ssm_parameter" "chat_widget_url" {
+  name       = aws_ssm_parameter.chat_widget_url.name
+  depends_on = [aws_ssm_parameter.chat_widget_url]
+}
+
+data "aws_ssm_parameter" "chat_widget_element_id" {
+  name       = aws_ssm_parameter.chat_widget_element_id.name
+  depends_on = [aws_ssm_parameter.chat_widget_element_id]
+}
+
+# --- SAML Federation ---
+# IAM SAML provider and role for Identity Center SSO into the Connect console.
+# Count-gated: only created when a SAML metadata file is supplied.
+data "aws_caller_identity" "current" {}
+
+resource "aws_iam_saml_provider" "connect" {
+  count                  = var.saml_metadata_file != "" ? 1 : 0
+  name                   = "${local.name_prefix}-connect-saml"
+  saml_metadata_document = file(var.saml_metadata_file)
+}
+
+resource "aws_iam_role" "connect_saml" {
+  count = var.saml_metadata_file != "" ? 1 : 0
+  name  = "${local.name_prefix}-connect-saml-role"
+
+  assume_role_policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [
+      {
+        Effect    = "Allow"
+        Principal = { Federated = aws_iam_saml_provider.connect[0].arn }
+        Action    = "sts:AssumeRoleWithSAML"
+        Condition = {
+          StringEquals = {
+            "SAML:aud" = "https://signin.aws.amazon.com/saml"
+          }
+        }
+      }
+    ]
+  })
+
+  tags = { Name = "${local.name_prefix}-connect-saml-role" }
+}
+
+resource "aws_iam_role_policy" "connect_saml" {
+  count = var.saml_metadata_file != "" ? 1 : 0
+  name  = "connect-federation"
+  role  = aws_iam_role.connect_saml[0].id
+
+  policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [
+      {
+        Effect   = "Allow"
+        Action   = "connect:GetFederationToken"
+        Resource = "${aws_connect_instance.this.arn}/user/*"
+      }
+    ]
+  })
+}

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

@@ -0,0 +1,76 @@
+<%# belt-connect :: infrastructure/modules/connect/outputs.tf -%>
+output "instance_id" {
+  description = "Amazon Connect instance ID"
+  value       = aws_connect_instance.this.id
+}
+
+output "instance_arn" {
+  description = "Amazon Connect instance ARN"
+  value       = aws_connect_instance.this.arn
+}
+
+output "admin_console_url" {
+  description = "URL for the Amazon Connect admin console"
+  value       = "https://${var.instance_alias}.my.connect.aws"
+}
+
+output "ccp_url" {
+  description = "Contact Control Panel (CCP) URL — where agents sign in to take chats"
+  value       = "https://${var.instance_alias}.my.connect.aws/ccp-v2"
+}
+
+output "identity_management_type" {
+  description = "How users sign in: SAML (via IdP) or CONNECT_MANAGED (username + password)"
+  value       = var.identity_management_type
+}
+
+output "user_password_ssm_params" {
+  description = "Map of username => SSM SecureString parameter holding that user's generated password (CONNECT_MANAGED only)"
+  value       = { for name, p in aws_ssm_parameter.user_password : name => p.name }
+}
+
+# --- Chat widget values (matched set, sourced from SSM) ---
+# Wire these into the frontend build via env.yml so the snippet can never go
+# stale in a hand-edited .env. See the demo-app README "Chat widget 403" runbook.
+output "chat_snippet_id" {
+  description = "Amazon Connect chat snippet ID (VITE_CONNECT_<NAME>_SNIPPET_ID)"
+  value       = data.aws_ssm_parameter.chat_snippet_id.value
+  # SSM data-source values are sensitive; root outputs that forward this must
+  # also set sensitive = true (belt reads it back with `terraform output -json`).
+  sensitive   = true
+}
+
+output "chat_widget_url" {
+  description = "Amazon Connect chat widget script URL (widgetUrl in the frontend widget registry)"
+  value       = nonsensitive(data.aws_ssm_parameter.chat_widget_url.value)
+}
+
+output "chat_widget_element_id" {
+  description = "Amazon Connect chat widget element/instance ID (id in the frontend widget registry)"
+  value       = nonsensitive(data.aws_ssm_parameter.chat_widget_element_id.value)
+}
+
+output "contact_flow_id" {
+  description = "Chat contact flow ID"
+  value       = aws_connect_contact_flow.chat.contact_flow_id
+}
+
+output "queue_id" {
+  description = "Chat queue ID"
+  value       = aws_connect_queue.chat.queue_id
+}
+
+output "routing_profile_id" {
+  description = "Chat agents routing profile ID"
+  value       = aws_connect_routing_profile.chat_agents.routing_profile_id
+}
+
+output "saml_provider_arn" {
+  description = "SAML provider ARN for Identity Center federation"
+  value       = length(aws_iam_saml_provider.connect) > 0 ? aws_iam_saml_provider.connect[0].arn : ""
+}
+
+output "saml_role_arn" {
+  description = "IAM role ARN for SAML federation into Connect"
+  value       = length(aws_iam_role.connect_saml) > 0 ? aws_iam_role.connect_saml[0].arn : ""
+}

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

@@ -0,0 +1,100 @@
+<%# belt-connect :: infrastructure/modules/connect/variables.tf -%>
+variable "app_name" {
+  description = "Application name prefix (used for resource names and the SSM path)"
+  type        = string
+  default     = "<%= @app_name %>"
+}
+
+variable "environment" {
+  description = "Environment name"
+  type        = string
+}
+
+variable "aws_region" {
+  description = "AWS region"
+  type        = string
+  default     = "us-east-1"
+}
+
+variable "instance_alias" {
+  description = "Alias for the Connect instance (must be globally unique)"
+  type        = string
+}
+
+variable "identity_management_type" {
+  description = <<-EOT
+    How agents and admins sign in to this instance.
+      SAML            — federate from your IdP (pair with saml_metadata_file).
+                        Nobody can log in until the IdP is wired up; the only
+                        back door is "Log in for emergency access" in the AWS console.
+      CONNECT_MANAGED — usernames + passwords stored in Connect. No IdP needed;
+                        the simplest choice for demos, sandboxes, and ephemeral envs.
+                        Pair with the `users` variable to create logins.
+  EOT
+  type        = string
+  default     = "SAML"
+
+  validation {
+    condition     = contains(["SAML", "CONNECT_MANAGED"], var.identity_management_type)
+    error_message = "identity_management_type must be \"SAML\" or \"CONNECT_MANAGED\"."
+  }
+}
+
+variable "users" {
+  description = <<-EOT
+    Connect-managed logins to create (CONNECT_MANAGED only), keyed by username.
+    Every user is attached to the chat routing profile so they can take chats
+    from the CCP. A password is generated per user and stored as an SSM
+    SecureString at /<app_name>/<environment>/connect/users/<username>/password.
+    security_profiles are the built-in Connect profile names
+    (Admin, Agent, CallCenterManager, QualityAnalyst).
+  EOT
+  type = map(object({
+    first_name        = optional(string, "")
+    last_name         = optional(string, "")
+    email             = optional(string, "")
+    security_profiles = optional(list(string), ["Agent"])
+  }))
+  default = {}
+
+  validation {
+    condition     = length(var.users) == 0 || var.identity_management_type == "CONNECT_MANAGED"
+    error_message = "users can only be created when identity_management_type = \"CONNECT_MANAGED\" (SAML users come from your IdP)."
+  }
+}
+
+variable "timezone" {
+  description = "Timezone for hours of operation"
+  type        = string
+  default     = "America/New_York"
+}
+
+variable "chat_snippet_id" {
+  description = "Snippet ID from the Connect admin console chat widget configuration"
+  type        = string
+  default     = ""
+}
+
+variable "chat_widget_url" {
+  description = "Widget script URL from the Connect admin console chat widget configuration"
+  type        = string
+  default     = ""
+}
+
+variable "chat_widget_element_id" {
+  description = "Widget element/instance ID from the Connect admin console chat widget snippet (the id passed as the 4th arg of the snippet IIFE)"
+  type        = string
+  default     = ""
+}
+
+variable "approved_origins" {
+  description = "Domains allowed to embed the Connect chat widget (e.g. https://app.example.com)"
+  type        = list(string)
+  default     = []
+}
+
+variable "saml_metadata_file" {
+  description = "Path to the SAML metadata XML file from Identity Center (empty = no SSO federation)"
+  type        = string
+  default     = ""
+}

data/lib/belt/connect/version.rb

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

data/lib/belt/connect.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative 'connect/version'
+require_relative 'connect/configuration'
+
+module Belt
+  # Belt plugin for Amazon Connect (Connect Customer): a chat widget and
+  # call-center contact flow, extracted and generalized from Stowzilla's
+  # standalone connect-infrastructure. Scaffolds Terraform the host app owns
+  # plus a frontend widget loader. The gem never applies AWS itself.
+  module Connect
+    class Error < StandardError; end
+    class ConfigurationError < 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
+    end
+  end
+end
+
+# Required after Belt::Connect::Error is defined (SnippetParser::ParseError
+# inherits from it).
+require_relative 'connect/snippet_parser'