@nextpa/chat-core

Framework-neutral voice & text chat engine for the NextPA platform: realtime voice providers (OpenAI / Google / VertexAI), text + voice conversation orchestration, backend API/auth client, notification stream, audio and WebRTC handling.

Entry points

| Import | Contents | |---|---| | @nextpa/chat-core | Headless engine — controllers, API client, notification stream (server-sent events), WebRTC, page interaction, provider registry. No provider SDK references. | | @nextpa/chat-core/openai | Side-effect entry: registers the OpenAI realtime provider (lazy loader — the SDK stays in its own async chunk). | | @nextpa/chat-core/google | Side-effect entry: registers both Google Live providers (google + vertexai). |

Apps import the provider entries for the providers they use (the internal apps import both — "works with whatever the backend says"):

import '@nextpa/chat-core/openai';
import '@nextpa/chat-core/google';

Provider SDKs (@openai/agents-realtime, @google/genai) are optional peer dependencies — install only what you import.

Auth

WidgetApiClient acquires its bearer token through a pluggable tokenProvider:

• Default (turnkey): pass apiKey — the public widget key (public by design, see .claude/docs/widget.md § Threat Model) is exchanged for a short-lived JWT via /api/widget/authenticate.
• Custom (server-minted): pass tokenProvider: (ctx) => Promise<WidgetTokenResult> — e.g. a partner backend that mints/exchanges the token server-side, so no long-lived secret ever reaches the browser. Called with { baseUrl, clientId } and re-invoked automatically when the token expires.

new WidgetApiClient({ apiKey: 'npa_…' });                        // turnkey
new WidgetApiClient({ baseUrl, tokenProvider: myBackendMint });   // partner backend

⚠ Never add "sideEffects": false to package.json: provider registration runs via side-effect modules and would be tree-shaken away (see the widget-embedding capability under openspec/specs/).

Levels of a spoken conversation

WidgetController reports how loud a spoken conversation is as two events of their own. They do not arrive through stateChanged, which fires only when the conversation itself changes:

| Event | Level of | |---|---| | inputLevel | the person's microphone | | outputLevel | the assistant's voice as it is played |

Both are 0..1 on a perceived scale, rise within a syllable and fall over a moment, read 0 in silence, and a moving level is reported at 0 once when the conversation ends; the input level also when the microphone is muted. They mean the same for every provider.

controller.on('inputLevel', (level) => {
    halo.style.opacity = String(Math.min(0.7, 0.22 + level * 0.6));
    halo.style.transform = `scale(${1 + Math.min(1, level) * 0.6})`;
});

What a version number promises

The package is on the 0.x line. A patch release never breaks an integration that follows the developer documentation. A minor release may break one — by removing or changing a promised event, state field or operation — and says so on the portal's Versions & breaking changes page before anyone adopts it. The package moves to 1.0.0 when the SDK is released to partners; from then on only a major release may break.

Targets

• nx test chat-core — unit tests (Vitest); builds first, because one of them loads the built package the way a consumer outside this workspace does
• nx run chat-core:typecheck — tsc --noEmit
• nx run chat-core:build — emits ESM + .d.ts to dist/, where the exports map points, and then resolves every emitted relative specifier to a file

How it is consumed, and why the build has a second step

Inside this workspace the widget and the extension reach the sources through a tsconfig path alias and a Vite alias, so a change needs no release to be seen. Everything outside it resolves the published package from npmjs.com.

Those two paths do not accept the same import specifiers. tsc emits relative specifiers exactly as the sources write them, and with classic node module resolution the sources may leave off the extension and name a directory (./core). A bundler resolves both; Node's ESM loader resolves neither, so the emitted artifact would throw Directory import … is not supported on the first import from any consumer that is not bundling. The second build step rewrites those specifiers in dist/ to name a file (./core/index.js), which every consumer accepts. The sources are left alone, so nothing about how the widget and the extension build changes.

tests/published-package.test.ts is the guard: it loads every entry point the exports map offers in a real Node process. A specifier the step cannot resolve fails the build instead of shipping.

Releasing is a git tag — see .claude/docs/scripts.md, Chat-Core Package Release.