@jokken/chat-core

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

Entry points

| Import | Contents | |---|---| | @jokken/chat-core | Headless engine — controllers, API client, SignalR, WebRTC, page interaction, provider registry. No provider SDK references. | | @jokken/chat-core/openai | Side-effect entry: registers the OpenAI realtime provider (lazy loader — the SDK stays in its own async chunk). | | @jokken/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 '@jokken/chat-core/openai';
import '@jokken/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 .claude/docs/chat-sdk-npm-packaging-plan.md).

Targets

• nx test chat-core — unit tests (Vitest)
• nx run chat-core:typecheck — tsc --noEmit
• nx run chat-core:build — emits ESM + .d.ts to dist/ (the exports map in package.json points there; not published yet — consumed via tsconfig path aliases)