belt-connect 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 125076cec482c05865c29378d307c53e93a7f4a7220672ee9d658e0e46681e9d
+  data.tar.gz: 2f245194a4675ac5078c7e24718f43dc32bb2e15b402c139c3d4151b96c23abb
+SHA512:
+  metadata.gz: 57d369a7f0a7464ac1bb243e20077f7e3014529320755968e34da063ce9db7213aa1df856b925854ff7613c1a5ccb3f2cbed2a9de7de99b963ec5f5deab2b7d2
+  data.tar.gz: e78e4a39a94a0fc78f757f8b51779b767852ce90d767b830be6e3594f4ec1d1bbda15e4ad0f3a1f392d920c8eb0cd4bb90e05d7ea8390b2a92bcd044b77d480c

data/CHANGELOG.md

@@ -0,0 +1,121 @@
+# Changelog
+
+All notable changes to belt-connect are documented here.
+Format follows [Keep a Changelog](https://keepachangelog.com/).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-10-31
+
+### Added
+- **Widget snippet convention: `config/connect/widgets/<name>.js`.** Raw
+  "Get widget code" snippets now have one home in the host app; the directory
+  is gitignored (the snippet holds the secret snippetId) with a committed
+  README. `belt generate connect` scaffolds the README and the `.gitignore`
+  entry (idempotently); `add-widget <name>` reads `<name>.js` from there when
+  no file is given, and copies a file passed from anywhere else into it.
+- **`add-widget --env <env>`** writes the matched set (snippet id, widget URL,
+  element id) to the module's three SSM parameters from the one parsed snippet,
+  so nobody runs three `aws ssm put-parameter` commands by hand and mixes
+  widgets. `--app-name` / `--ssm-prefix` override the derived prefix. The
+  success message spells out the `terraform apply -refresh-only` step the SSM
+  data-source outputs need before `belt deploy frontend` — skipping it ships
+  the `PENDING_CONSOLE_SETUP` placeholder.
+- **JWT detection.** `SnippetParser` flags an `amazon_connect('authenticate', …)`
+  hook (`result.jwt?`) and `add-widget` warns, since the loader does not sign
+  tokens yet and a JWT-secured widget would refuse to start a chat.
+- **`scripts/chat-smoke-test/widget-check.mjs`** (demo app) replays the hosted
+  widget's handshake (`GET …/connectwidget/api/<widgetId>` with the page
+  `Origin` and `x-amz-snippet-id`) from the CLI, so a widget 403/400 can be
+  checked and re-checked without a browser, and tells you which gate you hit:
+  `400 Invalid Request` = origin not on the widget's Domains; `403 explicit
+  deny` = widget id unknown or snippet missing/stale. The README's runbook
+  has the same table.
+- **`identity_management_type` + `users` module variables.** The Connect
+  instance can now be `CONNECT_MANAGED` (username + password logins) instead of
+  the SAML default, and the module will create the logins: each entry in
+  `users` gets the chat routing profile, the named built-in security profiles,
+  and a generated password stored as an SSM SecureString at
+  `/<app_name>/<env>/connect/users/<username>/password`. This is what makes a
+  demo chat actually connect — with SAML and no IdP, nobody can sign in to the
+  CCP to answer it. New outputs: `ccp_url`, `identity_management_type`,
+  `user_password_ssm_params`.
+- Module `terraform { required_providers }` block (aws, null, random).
+- **Multi-widget registry architecture.** `belt generate connect` now emits a
+  widget registry (`frontend/src/connect/widgets.js`) — a named map that is the
+  single source of truth for every hosted widget (id, loader URL, styles) — plus
+  one generic `ConnectWidget.jsx` loader driven by a widget name
+  (`<ConnectWidget name="support" />`, `openConnectChat('support')`). Adding a
+  second widget is pure config, no new component.
+- `Belt::Connect::SnippetParser` — parses an Amazon Connect "Get widget code"
+  snippet into `{ id, snippet_id, widget_url, styles }`, so the base64 snippetId
+  is never retyped by hand (the drift that caused a right-instance/wrong-widget
+  403).
+- `belt generate connect add-widget <name> <snippet-file>` — parses a pasted
+  snippet into the registry (id + URL as readable config) and prints the
+  `VITE_CONNECT_<NAME>_SNIPPET_ID` env line (the snippetId stays a secret).
+
+### Fixed
+- **Hosted widget handshake 403 caused by the loader itself.** `ConnectWidget.jsx`
+  mounted the widget `<script>` with `id="amazon-connect-chat-widget-<name>"`.
+  Amazon's client script locates its own element by id and uses **that id as
+  the widget id** in `GET <instance>/connectwidget/api/<id>`, so every chat
+  attempt hit `…/api/amazon-connect-chat-widget-support` and got
+  `403 "explicit deny in an identity-based policy"` regardless of the console's
+  domain/security settings. The loader now sets the element id to the
+  registry's `id` (the bootstrap arg of the console snippet) and treats a
+  missing id as "not configured". Several widgets still coexist — widget ids
+  are unique. Regenerate `frontend/src/connect/ConnectWidget.jsx` (or apply the
+  same change) in apps generated before this fix.
+
+### Changed
+- Frontend assets moved from `frontend/src/components/AmazonConnectChat.jsx` to a
+  dedicated `frontend/src/connect/` directory (registry + generic loader).
+- The single secret per widget is now `VITE_CONNECT_<NAME>_SNIPPET_ID`; the
+  widget id and loader URL are committed config in the registry (previously all
+  three were smeared across `VITE_AMAZON_CONNECT_*` env vars + hardcoded styles).
+
+- demo-app: `frontend/env.yml` now maps `VITE_CONNECT_SUPPORT_SNIPPET_ID` to the
+  `connect_chat_snippet_id` Terraform output (the registry's single secret) so
+  `belt deploy frontend <env>` keeps injecting the snippet from SSM at build time.
+  The demo-app README's 403 runbook is rewritten in terms of the registry.
+
+### Fixed
+- Gem templates were behind the demo module: `chat_widget_element_id` (var, SSM
+  param) and the SSM read-back data sources + `chat_*` outputs added in #1632
+  only landed in `examples/demo-app`. They're now in the templates too.
+- `chat_snippet_id` output is marked `sensitive` and the URL/element-id outputs
+  are wrapped in `nonsensitive()`. Without this `terraform plan`/`destroy`
+  fails with "Output refers to sensitive values" the moment a root module
+  forwards them (which the demo app does for `frontend/env.yml`).
+- demo-app: `backend.tf` in every env pointed at the bare `belt-terraform-state`
+  placeholder instead of belt's `belt-terraform-state-<account>` bucket, so a
+  fresh checkout couldn't init against the live sandbox state.
+
+### Removed
+- The single-purpose `AmazonConnectChat.jsx` component template (replaced by the
+  registry + generic `ConnectWidget`).
+
+## [0.1.0] - 2026-10-28
+
+Initial release. Extracted and generalized from Stowzilla's standalone
+`connect-infrastructure`.
+
+### Added
+- `belt generate connect` / `belt destroy connect` generator
+  (`Belt::Generators::ConnectGenerator`), auto-discovered by Belt's
+  `GeneratorRegistry`.
+- Terraform module (`infrastructure/modules/connect/`): Connect instance (SAML,
+  chat), approved origins (null_resource + local-exec), 24/7 hours of operation,
+  chat contact flow with off-hours queuing, queue, CHAT routing profile
+  (concurrency 3), SSM params for the hosted chat widget snippet/URL
+  (with `ignore_changes`), and opt-in SAML federation (IAM provider + role) for
+  Identity Center SSO.
+- React hosted-chat widget loader (`AmazonConnectChat.jsx`) exporting
+  `openConnectChat()`; snippet/URL read from `VITE_AMAZON_CONNECT_*` env vars.
+- `Belt::Connect.configure` — app-agnostic config for `brand_color`, `typeface`,
+  `timezone`, `app_name`, `instance_alias` (replaces hard-coded Stowzilla green,
+  `*.stowzilla.com` origins, and the `/stowzilla/` SSM prefix).
+- `--skip-frontend` and `--force` generator flags.
+- Demo Belt app (`examples/demo-app`) with a `/support` page (chat widget +
+  call-center panel) and a `sandbox` nested (ephemeral) environment.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stowzilla Inc.
+
+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,169 @@
+# belt-connect
+
+Amazon Connect (Connect Customer) for [Belt](https://belt.dev) applications — a
+**chat widget** and a **call-center contact flow**, scaffolded into your app with
+one command.
+
+`belt-connect` is a Belt plugin. Like `belt-cost-monitoring`, it emits Terraform
+your app owns and then gets out of the way — the gem never applies AWS itself.
+It was extracted and generalized from Stowzilla's standalone
+`connect-infrastructure`, with the Stowzilla-specific bits (brand color, approved
+origins, SSM prefix) turned into configuration.
+
+## What it scaffolds
+
+`belt generate connect` writes:
+
+```
+infrastructure/modules/connect/
+  main.tf        # Connect instance (SAML or Connect-managed, chat), approved
+                 # origins, 24/7 hours of operation, chat contact flow with
+                 # off-hours queuing, queue, CHAT routing profile, optional
+                 # Connect-managed users (passwords in SSM SecureString), SSM
+                 # params for the hosted widget, and SAML federation (IAM
+                 # provider + role) for Identity Center SSO
+  variables.tf   # app_name, environment, instance_alias, approved_origins,
+                 # identity_management_type, users, brand/SSM knobs,
+                 # saml_metadata_file (SSO is opt-in)
+  outputs.tf     # instance_id/arn, admin_console_url, ccp_url, contact_flow_id,
+                 # queue_id, routing_profile_id, user_password_ssm_params,
+                 # chat_* widget values (from SSM), saml_* arns
+
+frontend/src/connect/widgets.js        # Widget registry — the single source of
+                 # truth for every hosted widget (id, url, styles). snippetId is
+                 # read from env (it's a secret).
+frontend/src/connect/ConnectWidget.jsx # Generic React hosted-chat loader driven
+                 # by a widget name; exports openConnectChat(name)
+```
+
+The chat widget is **hosted by AWS** and the browser WebSocket does the talking,
+so there is **no runtime Lambda** to deploy.
+
+## Install
+
+Add the gem to your Belt app's `Gemfile`:
+
+```ruby
+gem 'belt-connect', '~> 0.2'
+```
+
+Then:
+
+```bash
+bundle install
+belt generate connect        # scaffold the module + widget
+belt generate connect --skip-frontend   # Terraform only
+belt destroy connect         # remove what was generated
+```
+
+## Wire it up
+
+1. Reference the module in your environment `main.tf`:
+
+   ```hcl
+   module "connect" {
+     source           = "../modules/connect"
+     app_name         = var.app_name
+     environment      = var.environment
+     aws_region       = var.aws_region
+     instance_alias   = "${var.app_name}-${var.environment}"
+     approved_origins = ["https://${var.environment}.example.com", "http://localhost:3000"]
+
+     # Optional: Identity Center SSO into the Connect console
+     # saml_metadata_file = "${path.module}/saml-metadata.xml"
+   }
+   ```
+
+   **Who answers the chat?** The module defaults to SAML identity management,
+   which means nobody can sign in to the Contact Control Panel (CCP) until an
+   identity provider is federated in via `saml_metadata_file`. For demos,
+   sandboxes, and ephemeral environments, flip to Connect-managed logins and
+   let the module create them:
+
+   ```hcl
+   identity_management_type = "CONNECT_MANAGED"
+   users = {
+     "admin" = { security_profiles = ["Admin"] }   # creates the widget in the console
+     "agent" = { security_profiles = ["Agent"] }   # signs in to the CCP, takes chats
+   }
+   ```
+
+   Each user gets the chat routing profile and a generated password stored at
+   `/<app_name>/<env>/connect/users/<username>/password` (SSM SecureString).
+   `identity_management_type` is a create-time setting: changing it replaces
+   the Connect instance.
+
+2. Deploy: `belt deploy <env>`.
+
+3. In the Connect admin console, create a **hosted chat widget**, copy its
+   "Get widget code" snippet into a file, then parse it into the registry:
+
+   ```bash
+   belt generate connect add-widget support path/to/code.js
+   ```
+
+   This reads the widget id, loader URL, and snippetId straight out of the
+   snippet — no hand-copying the base64 monster. The id and URL land in
+   `src/connect/widgets.js` (readable config); the snippetId is a secret, so the
+   command prints the env line to add:
+
+   ```
+   VITE_CONNECT_SUPPORT_SNIPPET_ID=...
+   ```
+
+4. Mount the widget by name and open it from anywhere:
+
+   ```jsx
+   import ConnectWidget, { openConnectChat } from './connect/ConnectWidget'
+
+   <ConnectWidget name="support" />
+   <button onClick={() => openConnectChat('support')}>Chat with us</button>
+   ```
+
+   Adding a second widget is pure config — `add-widget sales code.js`, drop a
+   `<ConnectWidget name="sales" />`, done. No new component, no env-var sprawl.
+
+## Configuration
+
+Brand the widget (defaults are app-agnostic, not Stowzilla green):
+
+```ruby
+# config/initializers/belt_connect.rb (or anywhere loaded before `belt generate`)
+Belt::Connect.configure do |c|
+  c.brand_color = '#632d91'                 # header + chat bubbles
+  c.typeface    = "'Inter', sans-serif"
+end
+```
+
+| Setting          | Default               | Purpose                                   |
+| ---------------- | --------------------- | ----------------------------------------- |
+| `brand_color`    | `#2563eb`             | Chat widget header + bubble color         |
+| `typeface`       | `'Inter', sans-serif` | Chat widget font                          |
+| `timezone`       | `America/New_York`    | Hours-of-operation timezone (also a TF var) |
+| `app_name`       | detected from routes  | Resource name prefix + SSM path           |
+| `instance_alias` | —                     | Globally-unique Connect instance alias    |
+
+Terraform-side knobs (module variables, not gem config):
+
+| Variable                   | Default | Purpose                                                        |
+| -------------------------- | ------- | -------------------------------------------------------------- |
+| `identity_management_type` | `SAML`  | `SAML` (federate an IdP) or `CONNECT_MANAGED` (password logins) |
+| `users`                    | `{}`    | Connect-managed logins to create; passwords land in SSM        |
+| `saml_metadata_file`       | `""`    | IdP metadata XML; enables the IAM SAML provider + role         |
+
+## Demo app
+
+A full, working Belt app that uses this plugin lives in
+[`examples/demo-app`](examples/demo-app) — a React frontend with a `/support`
+page wiring the chat widget + a call-center panel, plus a **sandbox** nested
+environment. See its README to run and deploy it.
+
+## Chat-first (today)
+
+Mirrors Stowzilla's live rig: `inbound_calls_enabled = true`,
+`outbound_calls_enabled = false`, CHAT-only routing (concurrency 3). Voice/cases
+can follow by extending the routing profile + contact flow.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

data/lib/belt/connect/configuration.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Belt
+  module Connect
+    # Configuration for the belt-connect plugin. These values are consumed by
+    # the generator when rendering the Terraform module and the frontend widget
+    # loader. Everything here used to be hard-coded to Stowzilla (green brand,
+    # *.stowzilla.com origins, /stowzilla/ SSM prefix) — now it is all knobs so
+    # the plugin stays app-agnostic.
+    class Configuration
+      # App name prefix used for resource names and the SSM parameter path.
+      attr_accessor :app_name
+
+      # Alias for the Connect instance (globally unique across AWS Connect).
+      attr_accessor :instance_alias
+
+      # Timezone for the 24/7 hours-of-operation resource.
+      attr_accessor :timezone
+
+      # Brand color for the hosted chat widget (header + bubbles).
+      attr_accessor :brand_color
+
+      # Typeface for the chat widget.
+      attr_accessor :typeface
+
+      def initialize
+        @app_name       = nil
+        @instance_alias = nil
+        @timezone       = 'America/New_York'
+        @brand_color    = '#2563eb'
+        @typeface       = "'Inter', sans-serif"
+      end
+    end
+  end
+end

data/lib/belt/connect/snippet_parser.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Belt
+  module Connect
+    # Parses the self-contained `<script>` snippet that the Amazon Connect admin
+    # console hands you when you create a hosted chat widget ("Get widget code").
+    #
+    # The snippet is the single source of truth for a widget's identity. Rather
+    # than hand-copying the base64 snippetId and the widget URL into env vars —
+    # which is exactly the drift that caused a right-instance/wrong-widget 403 —
+    # we read them straight out of the snippet mechanically.
+    #
+    # A snippet looks like:
+    #
+    #   <script type="text/javascript">
+    #     (function(w, d, x, id){
+    #       s=d.createElement('script');
+    #       s.src='https://<instance>.my.connect.aws/connectwidget/static/amazon-connect-chat-interface-client.js';
+    #       ...
+    #     })(window, document, 'amazon_connect', '9da2678d-3ef8-41e5-ae28-bd380558574f');
+    #     amazon_connect('styles', { iconType: 'CHAT', openChat: { ... }, closeChat: { ... } });
+    #     amazon_connect('snippetId', 'QVFJREFIaDR...=');
+    #     amazon_connect('supportedMessagingContentTypes', [ ... ]);
+    #   </script>
+    #
+    # Usage:
+    #   result = Belt::Connect::SnippetParser.parse(File.read('code.js'))
+    #   result.id          # => "9da2678d-3ef8-41e5-ae28-bd380558574f"
+    #   result.snippet_id  # => "QVFJREFIaDR...="
+    #   result.widget_url  # => "https://<instance>.my.connect.aws/.../amazon-connect-chat-interface-client.js"
+    #   result.styles      # => { "iconType" => "CHAT", "openChat" => { ... }, ... }  (best-effort)
+    #   result.jwt?        # => true when the console emitted an authenticate hook
+    #   result.to_h        # => { id:, snippet_id:, widget_url:, styles:, jwt: }
+    class SnippetParser
+      Result = Struct.new(:id, :snippet_id, :widget_url, :styles, :jwt, keyword_init: true) do
+        # Did the admin pick "Yes" on "Add security for new communication widget
+        # requests"? That makes the console emit an
+        # `amazon_connect('authenticate', function(callback) { ... })` stub, and
+        # the widget refuses to start a chat until that callback hands it a JWT
+        # signed with the widget's security key. belt-connect's loader does not
+        # implement that hook yet, so a JWT snippet is something to warn about.
+        def jwt?
+          !!jwt
+        end
+
+        def to_h
+          { id: id, snippet_id: snippet_id, widget_url: widget_url, styles: styles, jwt: jwt? }
+        end
+      end
+
+      class ParseError < Belt::Connect::Error; end
+
+      # The 4th positional arg of the bootstrap IIFE is the widget instance id,
+      # e.g. ...)(window, document, 'amazon_connect', '<UUID-ish-id>');
+      ID_PATTERN = /\(\s*window\s*,\s*document\s*,\s*['"][^'"]+['"]\s*,\s*['"]([^'"]+)['"]\s*\)/.freeze
+
+      # amazon_connect('snippetId', '<base64>')
+      SNIPPET_ID_PATTERN = /amazon_connect\(\s*['"]snippetId['"]\s*,\s*['"]([^'"]+)['"]\s*\)/.freeze
+
+      # s.src='https://.../amazon-connect-chat-interface-client.js'
+      WIDGET_URL_PATTERN = /\.src\s*=\s*['"]([^'"]+)['"]/.freeze
+
+      # amazon_connect('styles', { ... }) — captures the object literal body.
+      STYLES_PATTERN = /amazon_connect\(\s*['"]styles['"]\s*,\s*(\{.*?\})\s*\)\s*;/m.freeze
+
+      # amazon_connect('authenticate', function(callback) { ... }) — only present
+      # when JWT security was enabled for the widget in the console.
+      AUTHENTICATE_PATTERN = /amazon_connect\(\s*['"]authenticate['"]\s*,/.freeze
+
+      def self.parse(snippet)
+        new(snippet).parse
+      end
+
+      def initialize(snippet)
+        @snippet = snippet.to_s
+      end
+
+      def parse
+        id         = extract(ID_PATTERN, 'widget id (4th arg of the bootstrap IIFE)')
+        snippet_id = extract(SNIPPET_ID_PATTERN, "amazon_connect('snippetId', '...')")
+        widget_url = extract(WIDGET_URL_PATTERN, "the widget script src ('...amazon-connect-chat-interface-client.js')")
+
+        Result.new(
+          id: id,
+          snippet_id: snippet_id,
+          widget_url: widget_url,
+          styles: extract_styles,
+          jwt: @snippet.match?(AUTHENTICATE_PATTERN)
+        )
+      end
+
+      private
+
+      def extract(pattern, label)
+        match = @snippet.match(pattern)
+        raise ParseError, "Could not find #{label} in the Connect snippet" unless match
+
+        match[1].strip
+      end
+
+      # Styles are best-effort: the console emits a JS object literal (unquoted
+      # keys, trailing commas allowed), not JSON. We do a light normalization so
+      # a human never has to retype the brand colors, but a parse failure here is
+      # non-fatal — id/snippetId/widgetUrl are what actually wire the widget up.
+      def extract_styles
+        match = @snippet.match(STYLES_PATTERN)
+        return nil unless match
+
+        normalize_js_object(match[1])
+      rescue StandardError
+        nil
+      end
+
+      def normalize_js_object(js)
+        require 'json'
+
+        normalized = js.dup
+        # Quote bare object keys:  iconType:  ->  "iconType":
+        normalized = normalized.gsub(/([{,]\s*)([A-Za-z_]\w*)\s*:/, '\1"\2":')
+        # Single- to double-quoted string values.
+        normalized = normalized.gsub(/'([^']*)'/, '"\1"')
+        # Drop trailing commas before } or ].
+        normalized = normalized.gsub(/,\s*([}\]])/, '\1')
+
+        JSON.parse(normalized)
+      end
+    end
+  end
+end

data/lib/belt/connect/templates/config/widgets-README.md.erb

@@ -0,0 +1,63 @@
+<%# belt-connect :: config/connect/widgets/README.md -%>
+# Amazon Connect widget sources
+
+One file per hosted chat widget, named after its registry key:
+
+```
+config/connect/widgets/
+├── README.md       # this file (committed)
+└── support.js      # raw "Get widget code" snippet (gitignored)
+```
+
+Each `<name>.js` is the untouched `<script>` block the Connect admin console
+hands you under **Channels → Communications widgets → Copy script**. It holds
+the base64 `snippetId`, which is a secret, so `*.js` in this directory is
+gitignored. The committed source of truth for what the app *knows* about a
+widget is `frontend/src/connect/widgets.js`; the secret itself lives in SSM.
+
+## Registering a widget
+
+```bash
+# Save the console snippet here, then:
+belt generate connect add-widget support --env sandbox
+```
+
+That parses `config/connect/widgets/support.js`, upserts the `support` entry in
+`frontend/src/connect/widgets.js` (widget id + loader URL — readable config,
+commit it), and writes the matched set to the module's SSM parameters under
+`/<app>/sandbox/connect/`.
+
+The module exposes those parameters as Terraform outputs via SSM *data
+sources*, which only re-read on apply. Refresh state, then rebuild so
+`frontend/env.yml` injects the new snippet from the output:
+
+```bash
+terraform -chdir=infrastructure/sandbox apply -refresh-only -auto-approve
+belt deploy frontend sandbox
+```
+
+Skipping the refresh is the one way to ship a build whose widget still says
+"pending" after the snippet is in SSM.
+
+Passing a file from somewhere else copies it here first:
+
+```bash
+belt generate connect add-widget support ~/Downloads/code.js --env sandbox
+```
+
+## Security (JWT)
+
+When creating the widget, answer **No - I do not want to enable JWT security
+measures** unless the app implements the `authenticate` callback. Snippets with
+JWT enabled contain `amazon_connect('authenticate', ...)`; `add-widget` warns
+when it sees one, because the belt-connect loader does not sign tokens yet and
+the widget would refuse to start a chat.
+
+## More than one widget
+
+The registry and `ConnectWidget` loader take any number of named widgets, one
+mounted per page. The Terraform module provisions one matched set of SSM
+params per environment, which `frontend/env.yml` maps to
+`VITE_CONNECT_SUPPORT_SNIPPET_ID`. A second widget needs its own
+`VITE_CONNECT_<NAME>_SNIPPET_ID` line in `env.yml` backed by a parameter and
+output you add, or a value in the local `.env`.

data/lib/belt/connect/templates/frontend/ConnectWidget.jsx.erb

@@ -0,0 +1,116 @@
+<%# belt-connect :: frontend/src/connect/ConnectWidget.jsx -%>
+// Generic Amazon Connect hosted-chat widget loader.
+// Generated by belt-connect. One component, driven by a widget name that it
+// looks up in the registry (./widgets.js). Mount as many as you have widgets:
+//
+//   import ConnectWidget, { openConnectChat } from './connect/ConnectWidget'
+//
+//   <ConnectWidget name="support" />
+//   <button onClick={() => openConnectChat('support')}>Chat with us</button>
+//
+import { useEffect } from "react";
+import { getWidget, widgetDefaults } from "./widgets";
+
+// The <script> element's id MUST be the widget id (the 4th arg of the console
+// snippet's bootstrap IIFE). Amazon's client script looks itself up with
+// `script[id="<widgetId>"]` to find its origin, then calls
+// `GET <origin>/connectwidget/api/<that id>` as the chat handshake. Any other
+// id turns that handshake into a 403 "explicit deny in an identity-based
+// policy". Widget ids are unique, so several widgets still coexist on a page.
+
+// Is a widget fully configured (id + snippet + url present)? Lets callers render
+// conditional UI without duplicating the env-var checks.
+// The Terraform module seeds the SSM params with this placeholder until a
+// widget exists in the console; belt injects it verbatim, so treat it as unset.
+const PLACEHOLDER = /^PENDING/;
+
+function isUsable(value) {
+  return !!value && !PLACEHOLDER.test(value);
+}
+
+export function isWidgetConfigured(name) {
+  try {
+    const w = getWidget(name);
+    return isUsable(w.id) && isUsable(w.snippetId) && isUsable(w.widgetUrl);
+  } catch {
+    return false;
+  }
+}
+
+// Programmatically open a widget's chat panel (e.g. from a "Chat with us" button).
+export function openConnectChat(name = "support") {
+  const btn = document.getElementById("amazon-connect-open-widget-button");
+  if (btn) {
+    btn.click();
+    return;
+  }
+  // Fallback: if the widget hasn't rendered yet, queue the open command.
+  if (window.amazon_connect) {
+    window.amazon_connect("open");
+  }
+}
+
+export default function ConnectWidget({ name = "support" }) {
+  useEffect(() => {
+    const widget = getWidget(name);
+    const { id, snippetId, widgetUrl, styles = {} } = widget;
+    if (!isUsable(id) || !isUsable(snippetId) || !isUsable(widgetUrl)) return;
+
+    const elementId = id;
+    if (document.getElementById(elementId)) return;
+
+    const brandColor = styles.brandColor || widgetDefaults.brandColor;
+    const typeface = styles.typeface || widgetDefaults.typeface;
+    const iconType = styles.iconType || "CHAT";
+
+    window.amazon_connect =
+      window.amazon_connect ||
+      function () {
+        (window.amazon_connect.ac = window.amazon_connect.ac || []).push(
+          arguments,
+        );
+      };
+
+    amazon_connect("styles", {
+      iconType,
+      openChat: { color: "#ffffff", backgroundColor: brandColor },
+      closeChat: { color: "#ffffff", backgroundColor: brandColor },
+    });
+
+    amazon_connect("snippetId", snippetId);
+
+    amazon_connect("supportedMessagingContentTypes", [
+      "text/plain",
+      "text/markdown",
+      "application/vnd.amazonaws.connect.message.interactive",
+      "application/vnd.amazonaws.connect.message.interactive.response",
+    ]);
+
+    amazon_connect("customStyles", {
+      global: { typeface },
+      header: {
+        headerTextColor: "#ffffff",
+        headerBackgroundColor: brandColor,
+      },
+      transcript: {
+        customerChatBubbleColor: brandColor,
+        customerMessageTextColor: "#ffffff",
+      },
+    });
+
+    const script = document.createElement("script");
+    script.id = elementId;
+    script.src = widgetUrl;
+    script.async = true;
+    // Registry name, for debugging which entry mounted this element.
+    script.dataset.connectWidgetName = name;
+    document.head.appendChild(script);
+
+    return () => {
+      const el = document.getElementById(elementId);
+      if (el) el.remove();
+    };
+  }, [name]);
+
+  return null;
+}