@jambonz/sdk 0.8.2 → 0.8.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1 +1 @@
1
- {"version":3,"sources":["../../src/types/llm-vendors.generated.ts"],"names":[],"mappings":";;;AAQO,IAAM,WAAA,GAAc;AAAA,EACzB,QAAA;AAAA,EACA,WAAA;AAAA,EACA,QAAA;AAAA,EACA,eAAA;AAAA,EACA,eAAA;AAAA,EACA,SAAA;AAAA,EACA,UAAA;AAAA,EACA,SAAA;AAAA,EACA,cAAA;AAAA,EACA,MAAA;AAAA,EACA,aAAA;AAAA,EACA,UAAA;AAAA,EACA;AACF","file":"index.cjs","sourcesContent":["// AUTO-GENERATED — DO NOT EDIT BY HAND.\n// Source of truth: @jambonz/schema@0.3.18 verbs/agent.schema.json (llm.vendor.enum)\n// Regenerate with: npm run gen:types\n//\n// This file derives the LLM vendor list from the JSON schema so the SDK's\n// types never drift from the schema when a new vendor is added.\n\n/** Supported LLM vendors for the agent verb, derived from the schema enum. */\nexport const LLM_VENDORS = [\n 'openai',\n 'anthropic',\n 'google',\n 'vertex-gemini',\n 'vertex-openai',\n 'bedrock',\n 'deepseek',\n 'baseten',\n 'azure-openai',\n 'groq',\n 'huggingface',\n 'moonshot',\n 'zai',\n] as const;\n\n/** Union of LLM vendor ids accepted by the agent verb's `llm.vendor`. */\nexport type LlmVendor = (typeof LLM_VENDORS)[number];\n"]}
1
+ {"version":3,"sources":["../../src/types/llm-vendors.generated.ts"],"names":[],"mappings":";;;AAQO,IAAM,WAAA,GAAc;AAAA,EACzB,QAAA;AAAA,EACA,WAAA;AAAA,EACA,QAAA;AAAA,EACA,eAAA;AAAA,EACA,eAAA;AAAA,EACA,SAAA;AAAA,EACA,UAAA;AAAA,EACA,SAAA;AAAA,EACA,cAAA;AAAA,EACA,MAAA;AAAA,EACA,aAAA;AAAA,EACA,UAAA;AAAA,EACA;AACF","file":"index.cjs","sourcesContent":["// AUTO-GENERATED — DO NOT EDIT BY HAND.\n// Source of truth: @jambonz/schema@0.3.19 verbs/agent.schema.json (llm.vendor.enum)\n// Regenerate with: npm run gen:types\n//\n// This file derives the LLM vendor list from the JSON schema so the SDK's\n// types never drift from the schema when a new vendor is added.\n\n/** Supported LLM vendors for the agent verb, derived from the schema enum. */\nexport const LLM_VENDORS = [\n 'openai',\n 'anthropic',\n 'google',\n 'vertex-gemini',\n 'vertex-openai',\n 'bedrock',\n 'deepseek',\n 'baseten',\n 'azure-openai',\n 'groq',\n 'huggingface',\n 'moonshot',\n 'zai',\n] as const;\n\n/** Union of LLM vendor ids accepted by the agent verb's `llm.vendor`. */\nexport type LlmVendor = (typeof LLM_VENDORS)[number];\n"]}
@@ -1 +1 @@
1
- {"version":3,"sources":["../../src/types/llm-vendors.generated.ts"],"names":[],"mappings":";AAQO,IAAM,WAAA,GAAc;AAAA,EACzB,QAAA;AAAA,EACA,WAAA;AAAA,EACA,QAAA;AAAA,EACA,eAAA;AAAA,EACA,eAAA;AAAA,EACA,SAAA;AAAA,EACA,UAAA;AAAA,EACA,SAAA;AAAA,EACA,cAAA;AAAA,EACA,MAAA;AAAA,EACA,aAAA;AAAA,EACA,UAAA;AAAA,EACA;AACF","file":"index.js","sourcesContent":["// AUTO-GENERATED — DO NOT EDIT BY HAND.\n// Source of truth: @jambonz/schema@0.3.18 verbs/agent.schema.json (llm.vendor.enum)\n// Regenerate with: npm run gen:types\n//\n// This file derives the LLM vendor list from the JSON schema so the SDK's\n// types never drift from the schema when a new vendor is added.\n\n/** Supported LLM vendors for the agent verb, derived from the schema enum. */\nexport const LLM_VENDORS = [\n 'openai',\n 'anthropic',\n 'google',\n 'vertex-gemini',\n 'vertex-openai',\n 'bedrock',\n 'deepseek',\n 'baseten',\n 'azure-openai',\n 'groq',\n 'huggingface',\n 'moonshot',\n 'zai',\n] as const;\n\n/** Union of LLM vendor ids accepted by the agent verb's `llm.vendor`. */\nexport type LlmVendor = (typeof LLM_VENDORS)[number];\n"]}
1
+ {"version":3,"sources":["../../src/types/llm-vendors.generated.ts"],"names":[],"mappings":";AAQO,IAAM,WAAA,GAAc;AAAA,EACzB,QAAA;AAAA,EACA,WAAA;AAAA,EACA,QAAA;AAAA,EACA,eAAA;AAAA,EACA,eAAA;AAAA,EACA,SAAA;AAAA,EACA,UAAA;AAAA,EACA,SAAA;AAAA,EACA,cAAA;AAAA,EACA,MAAA;AAAA,EACA,aAAA;AAAA,EACA,UAAA;AAAA,EACA;AACF","file":"index.js","sourcesContent":["// AUTO-GENERATED — DO NOT EDIT BY HAND.\n// Source of truth: @jambonz/schema@0.3.19 verbs/agent.schema.json (llm.vendor.enum)\n// Regenerate with: npm run gen:types\n//\n// This file derives the LLM vendor list from the JSON schema so the SDK's\n// types never drift from the schema when a new vendor is added.\n\n/** Supported LLM vendors for the agent verb, derived from the schema enum. */\nexport const LLM_VENDORS = [\n 'openai',\n 'anthropic',\n 'google',\n 'vertex-gemini',\n 'vertex-openai',\n 'bedrock',\n 'deepseek',\n 'baseten',\n 'azure-openai',\n 'groq',\n 'huggingface',\n 'moonshot',\n 'zai',\n] as const;\n\n/** Union of LLM vendor ids accepted by the agent verb's `llm.vendor`. */\nexport type LlmVendor = (typeof LLM_VENDORS)[number];\n"]}
@@ -0,0 +1,61 @@
1
+ # Conference Supervision
2
+
3
+ Monitor, coach, and barge into live conferences, and tap a room's audio for
4
+ transcription — the core patterns behind a call-center supervision tool,
5
+ distilled into two small files.
6
+
7
+ A complete reference application built on these patterns (React console,
8
+ diarized live transcript, closed-loop e2e tests) is at
9
+ https://github.com/jambonz/room-monitor — see its `docs/ADAPTING.md`.
10
+
11
+ ## What It Demonstrates
12
+
13
+ - **Tagging members** — `memberTag: 'agent'` at join, and mid-call
14
+ `tag`/`untag` via `injectCommand('conf:participant-action', ...)`
15
+ - **The supervisor leg** — one conference member whose join options and
16
+ participant actions produce three modes: silent monitor (`joinMuted`),
17
+ coach (audio delivered only to `agent`-tagged members), and barge-in
18
+ - **Mid-call mode switching** — `conferenceParticipantAction`
19
+ (`coach`/`uncoach`) + `conf_mute_status` via the REST client: no re-dial,
20
+ the room is never interrupted
21
+ - **Conference listen fork** — jambonz streams the room's mixed audio (L16
22
+ PCM) to your WebSocket for transcription/AI; your `metadata` arrives
23
+ verbatim as the fork's first text frame
24
+ - **Application env vars** — the caller flow's room name (`ROOM_NAME`) is
25
+ declared via OPTIONS discovery so operators edit it from the jambonz portal
26
+
27
+ ## Prerequisites
28
+
29
+ - A jambonz account with API credentials
30
+ - Three applications pointed at this app's paths (or one application and
31
+ custom `X-` headers — see the reference app): `/caller`, `/agent`,
32
+ `/supervisor`
33
+ - Conference-level listen (`/Conferences/{name}/listen`) requires a jambonz
34
+ release with MediaJam-based conferencing that includes it
35
+
36
+ ## Environment Variables
37
+
38
+ - `JAMBONZ_BASE_URL` — jambonz API URL (default: `https://api.jambonz.us`)
39
+ - `JAMBONZ_ACCOUNT_SID` — your account SID
40
+ - `JAMBONZ_API_KEY` — your API key
41
+ - `FORK_URL` — public ws(s):// URL of this app's `/fork` path (the media
42
+ server dials out to it)
43
+
44
+ ## Files
45
+
46
+ - `ws-app.ts` — the jambonz application: caller/agent/supervisor call flows +
47
+ the audio-fork sink
48
+ - `monitor.ts` — REST-side supervision driver: list live rooms, switch the
49
+ supervisor's mode (monitor → coach → barge), tag/untag a participant,
50
+ start/stop the transcription fork
51
+
52
+ ## Try It
53
+
54
+ ```bash
55
+ npm install @jambonz/sdk tsx
56
+ npx tsx ws-app.ts # the application (port 3000)
57
+ npx tsx monitor.ts # walk a live room through the supervision modes
58
+ ```
59
+
60
+ Place two calls into a room (one via `/agent`, one via `/caller`), then run
61
+ `monitor.ts` with the supervisor's call_sid to step through the modes.
@@ -0,0 +1,93 @@
1
+ import { JambonzClient } from '@jambonz/sdk/client';
2
+
3
+ /*
4
+ * Conference supervision — the REST-side driver.
5
+ *
6
+ * Walks a live room through the supervision modes using mid-call commands on
7
+ * the supervisor's existing leg (started via ws-app.ts /supervisor). Nothing
8
+ * here re-dials or interrupts the room.
9
+ *
10
+ * Usage:
11
+ * JAMBONZ_ACCOUNT_SID=... JAMBONZ_API_KEY=... \
12
+ * npx tsx monitor.ts <supervisor_call_sid> [room_name]
13
+ */
14
+
15
+ const baseUrl = process.env.JAMBONZ_BASE_URL || 'https://api.jambonz.us';
16
+ const accountSid = process.env.JAMBONZ_ACCOUNT_SID || '';
17
+ const apiKey = process.env.JAMBONZ_API_KEY || '';
18
+ const forkUrl = process.env.FORK_URL || 'wss://your-host/fork';
19
+
20
+ const supervisorCallSid = process.argv[2];
21
+ const roomName = process.argv[3] || 'support-room';
22
+ if (!accountSid || !apiKey || !supervisorCallSid) {
23
+ console.error('usage: JAMBONZ_ACCOUNT_SID=.. JAMBONZ_API_KEY=.. npx tsx monitor.ts <supervisor_call_sid> [room]');
24
+ process.exit(1);
25
+ }
26
+
27
+ const client = new JambonzClient({ baseUrl, accountSid, apiKey });
28
+ const pause = (ms: number) => new Promise((r) => setTimeout(r, ms));
29
+
30
+ /* -- discovery: what rooms are live? --------------------------------------- */
31
+ const conferences = await client.conferences.list();
32
+ console.log('live conferences:', conferences);
33
+
34
+ // On releases with the enriched listing, get participants + tags in one call:
35
+ // GET /Accounts/{sid}/Conferences?expand=participants
36
+ // → [{ id, name, durationSec, participants: [{ call_sid, label, memberTag, isAgent }] }]
37
+ // Derive agent counts (and whether Coach should be offered) from memberTag,
38
+ // and filter out memberTag === 'supervisor' legs before displaying counts.
39
+
40
+ /* -- transcription tap: stream the room mix to our websocket --------------- */
41
+ // jambonz only transports audio — the consumer (ws-app.ts /fork) decides what
42
+ // to do with it. The fork needs no participant leg, is excluded from counts,
43
+ // and is torn down automatically when the room ends.
44
+ const res = await fetch(
45
+ `${baseUrl}/v1/Accounts/${accountSid}/Conferences/${encodeURIComponent(roomName)}/listen`, {
46
+ method: 'POST',
47
+ headers: { Authorization: `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
48
+ body: JSON.stringify({
49
+ url: forkUrl,
50
+ sampleRate: 16000,
51
+ metadata: { room: roomName, sampleRate: 16000 }, // delivered verbatim to the sink
52
+ }),
53
+ });
54
+ console.log(`listen fork: ${res.status}`);
55
+
56
+ /* -- the three supervision modes, as mid-call commands --------------------- */
57
+
58
+ // COACH: audio delivered only to members tagged 'agent'; the caller — and the
59
+ // audio fork — cannot hear it
60
+ console.log('coach mode: only agents hear the supervisor');
61
+ await client.calls.update(supervisorCallSid, {
62
+ conferenceParticipantAction: { action: 'coach', tag: 'agent' },
63
+ });
64
+ await client.calls.update(supervisorCallSid, { conf_mute_status: 'unmute' });
65
+ await pause(10000);
66
+
67
+ // BARGE-IN: heard by everyone
68
+ console.log('barge-in: everyone hears the supervisor');
69
+ await client.calls.update(supervisorCallSid, {
70
+ conferenceParticipantAction: { action: 'uncoach' },
71
+ });
72
+ await pause(10000);
73
+
74
+ // back to SILENT MONITOR
75
+ console.log('silent monitor: heard by no one');
76
+ await client.calls.update(supervisorCallSid, { conf_mute_status: 'mute' });
77
+
78
+ /* -- tags are dynamic too --------------------------------------------------
79
+ // promote/demote any live participant without a re-join; an active coach
80
+ // starts/stops reaching them immediately:
81
+ // await client.calls.update(someCallSid, {
82
+ // conferenceParticipantAction: { action: 'tag', tag: 'agent' },
83
+ // });
84
+ // await client.calls.update(someCallSid, {
85
+ // conferenceParticipantAction: { action: 'untag' },
86
+ // });
87
+ --------------------------------------------------------------------------- */
88
+
89
+ /* -- stop the transcription tap -------------------------------------------- */
90
+ await fetch(
91
+ `${baseUrl}/v1/Accounts/${accountSid}/Conferences/${encodeURIComponent(roomName)}/listen`,
92
+ { method: 'DELETE', headers: { Authorization: `Bearer ${apiKey}` } });
93
+ console.log('listen fork stopped');
@@ -0,0 +1,100 @@
1
+ import http from 'http';
2
+ import { createEndpoint } from '@jambonz/sdk/websocket';
3
+ import type { Session, AudioStream } from '@jambonz/sdk/websocket';
4
+
5
+ /*
6
+ * Conference supervision — the jambonz application side.
7
+ *
8
+ * Three call flows on one endpoint (point one jambonz application at each
9
+ * path), plus the audio sink that receives a conference listen fork:
10
+ *
11
+ * /caller a normal participant; which room they join is the
12
+ * application's ROOM_NAME env var (portal-editable via
13
+ * OPTIONS discovery)
14
+ * /agent joins the same room tagged 'agent' — the coach target
15
+ * /supervisor joins muted (silent monitor); mode changes come later as
16
+ * mid-call participant actions (see monitor.ts)
17
+ * /fork receives the room's mixed audio (L16 PCM) when a
18
+ * conference listen fork is started (see monitor.ts)
19
+ *
20
+ * Full reference app: https://github.com/jambonz/room-monitor
21
+ */
22
+
23
+ const envVars = {
24
+ ROOM_NAME: {
25
+ type: 'string' as const,
26
+ description: 'Conference room inbound callers join',
27
+ default: 'support-room',
28
+ },
29
+ };
30
+
31
+ const server = http.createServer();
32
+ const makeService = createEndpoint({ server, port: 3000, envVars });
33
+
34
+ const room = (session: Session): string =>
35
+ (session.data.env_vars as Record<string, string> | undefined)?.ROOM_NAME || 'support-room';
36
+
37
+ /* -- a normal caller ------------------------------------------------------ */
38
+ makeService({ path: '/caller' }).on('session:new', (session) => {
39
+ session
40
+ .answer()
41
+ .say({ text: 'Connecting you now.' })
42
+ .conference({
43
+ name: room(session),
44
+ startConferenceOnEnter: true,
45
+ endConferenceOnExit: false,
46
+ })
47
+ .send();
48
+ });
49
+
50
+ /* -- an agent: tagged, so coaching reaches them ---------------------------- */
51
+ makeService({ path: '/agent' }).on('session:new', (session) => {
52
+ session
53
+ .answer()
54
+ .conference({
55
+ name: room(session),
56
+ memberTag: 'agent', // <- the coach target; also drives supervision UIs
57
+ startConferenceOnEnter: true,
58
+ endConferenceOnExit: false,
59
+ })
60
+ .send();
61
+
62
+ // Tags are dynamic: promote/demote a live member without re-joining, e.g.
63
+ // session.injectCommand('conf:participant-action', { action: 'untag' });
64
+ // session.injectCommand('conf:participant-action', { action: 'tag', tag: 'agent' });
65
+ });
66
+
67
+ /* -- the supervisor: joins silent; modes switch mid-call ------------------- */
68
+ makeService({ path: '/supervisor' }).on('session:new', (session) => {
69
+ console.log(`supervisor leg ${session.callSid} — use this call_sid with monitor.ts`);
70
+ session
71
+ .answer()
72
+ .conference({
73
+ name: room(session),
74
+ joinMuted: true, // hears everything, heard by no one
75
+ memberTag: 'supervisor', // lets tooling filter this leg out of counts
76
+ startConferenceOnEnter: false, // never create/destroy the room being watched
77
+ endConferenceOnExit: false,
78
+ actionHook: '/conf-done',
79
+ })
80
+ .send();
81
+
82
+ session.on('/conf-done', () => {
83
+ session.hangup().reply();
84
+ });
85
+ });
86
+
87
+ /* -- the audio fork sink: the room mix arrives here ------------------------ */
88
+ makeService.audio({ path: '/fork' }).on('connection', (stream: AudioStream) => {
89
+ // the metadata you passed when starting the fork arrives verbatim as the
90
+ // first text frame — make it self-describing (room, sampleRate)
91
+ console.log('fork connected:', stream.metadata);
92
+
93
+ let bytes = 0;
94
+ stream.on('audio', (pcm: Buffer) => {
95
+ bytes += pcm.length;
96
+ // feed your STT / AI / recorder here — this is raw L16 PCM of the room
97
+ // mix. Note: coached (whispered) audio is never present in this stream.
98
+ });
99
+ stream.on('close', () => console.log(`fork closed after ${bytes} bytes`));
100
+ });
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@jambonz/sdk",
3
- "version": "0.8.2",
3
+ "version": "0.8.3",
4
4
  "description": "jambonz SDK for building voice applications — optimized for AI agents",
5
5
  "author": "Dave Horton",
6
6
  "license": "MIT",
@@ -98,7 +98,7 @@
98
98
  "postpublish": "npm run clean-docs"
99
99
  },
100
100
  "dependencies": {
101
- "@jambonz/schema": "^0.3.18",
101
+ "@jambonz/schema": "^0.3.19",
102
102
  "ajv": "^8.17.1",
103
103
  "ws": "^8.18.0"
104
104
  },