Haygen
Wiki/Decisions.md
Decisions — heygen-avatar
ADR index. One row per decision. Full ADR docs in
../Decisions/.
| ID | Decision | Why | Status |
|---|---|---|---|
| D-001 | Two-phase SDK initialization — SDK created synchronously before first await | Tests call startSession() non-awaited and immediately inspect mockAvatar.on.mock.calls. Without sync Phase 1, handlers aren't registered at that point. |
Locked |
| D-002 | CLI tsup entry points directly at src/cli/index.ts — no stub file |
sideEffects: false in package.json causes esbuild to tree-shake any bare import './cli/index.js' stub, producing an empty dist/cli.js. Direct entry eliminates the indirection. |
Locked |
| D-003 | Lite mode uses USER_TALKING_MESSAGE accumulation — NOT USER_END_MESSAGE.message |
UserTalkingEndEvent (USER_END_MESSAGE) has only type + task_id — no message field. Transcript must be accumulated from USER_TALKING_MESSAGE events and drained on END. |
Locked |
| D-004 | server.deps.inline: ['@heygen/streaming-avatar'] in vitest config |
The SDK has "type":"module" but "main" points to a CJS file, causing "exports is not defined in ES module scope" at runtime in vitest. Inlining forces Vite to use the "module" ESM field. |
Locked |
| D-005 | "types" condition before "import"/"require" in exports map |
Bundler resolution order — types must be first or bundlers emit warnings and may resolve the wrong type file. |
Locked |
| D-006 | Full mode and Lite mode share the same component API | Developer switches modes via config, not by using a different component. Same <HeygenAvatar> / useHeygenAvatar API surface for both. Reduces integration friction. |
Locked |
| D-007 | ingest() returns a builder (IngestPipeline) not a function |
Multiple sources need to be combined. Builder pattern allows .addText().addUrl().addPdf().build() without requiring the developer to manage an array manually. |
Locked |
| D-008 | Knowledge delivered as a plain string (not knowledgeId) for MVP | HeyGen's knowledgeId requires pre-creating a KB via their API — extra step. knowledgeBase string covers all MVP use cases. knowledgeId support is a V2 enhancement. |
Locked |