feat: Engagement Insights workflow

[walkerfrankenberg]

Overview

Adds a new Engagement Insights Workflow that generates AI-powered explanations of viewer engagement patterns by analyzing Mux video data (hotspots, heatmaps, transcripts, and visual frames).

The workflow identifies high/low engagement moments and explains why they occur, with optional actionable recommendations for content optimization.

What was changed

• New workflow: src/workflows/engagement-insights.ts (741 lines)

  • Fetches engagement data from Mux Data API (peaks and valleys)
  • Computes heatmap statistics (averages, drops, trends)
  • Extracts visual context via thumbnails at hotspot timestamps
  • Analyzes transcript segments matched to engagement moments
  • Generates structured insights using AI (OpenAI/Anthropic/Google)

• Configuration options:

  • hotspotLimit: Number of moments to analyze (1-10, default: 5)
  • insightType: "informational" | "actionable" | "both"
  • timeframe: Engagement data window (default: 7 days)

• Tests: Full integration tests with WorkflowDevKit validation and mock engagement data

• Documentation: Updated README, API.md, and WORKFLOWS.md with usage examples

Suggested review order

1. docs/WORKFLOWS.md - Start here for feature overview and usage examples
2. src/workflows/engagement-insights.ts - Core implementation (types → main workflow function)
3. tests/integration/engagement-insights.test.ts - Integration tests showing real usage
4. tests/helpers/mock-engagement-data.ts - Mock data structure (optional, for context)

[snyk-io]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scanner	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues
✅	Licenses	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.