@jambonz/sdk 0.6.0 → 0.8.0

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.
Files changed (39) hide show
  1. package/AGENTS.md +21 -14
  2. package/dist/client/index.d.cts +2 -2
  3. package/dist/client/index.d.ts +2 -2
  4. package/dist/index.cjs +28 -1
  5. package/dist/index.cjs.map +1 -1
  6. package/dist/index.d.cts +3 -3
  7. package/dist/index.d.ts +3 -3
  8. package/dist/index.js +28 -1
  9. package/dist/index.js.map +1 -1
  10. package/dist/{rest-usG3riy3.d.cts → rest-BehrJ_ai.d.cts} +16 -1
  11. package/dist/{rest-DQrUmoQN.d.ts → rest-CIi3fP4n.d.ts} +16 -1
  12. package/dist/types/index.cjs.map +1 -1
  13. package/dist/types/index.d.cts +2 -2
  14. package/dist/types/index.d.ts +2 -2
  15. package/dist/types/index.js.map +1 -1
  16. package/dist/{verb-builder-CNdBB1t6.d.cts → verb-builder-8zDaN7ba.d.ts} +3 -1
  17. package/dist/{verb-builder-DF5pnZWH.d.ts → verb-builder-Cc9cLrYj.d.cts} +3 -1
  18. package/dist/{verbs-lEtMeHGd.d.cts → verbs-BuObLiyU.d.cts} +25 -4
  19. package/dist/{verbs-lEtMeHGd.d.ts → verbs-BuObLiyU.d.ts} +25 -4
  20. package/dist/webhook/index.cjs +4 -0
  21. package/dist/webhook/index.cjs.map +1 -1
  22. package/dist/webhook/index.d.cts +2 -2
  23. package/dist/webhook/index.d.ts +2 -2
  24. package/dist/webhook/index.js +4 -0
  25. package/dist/webhook/index.js.map +1 -1
  26. package/dist/websocket/index.cjs +28 -1
  27. package/dist/websocket/index.cjs.map +1 -1
  28. package/dist/websocket/index.d.cts +28 -2
  29. package/dist/websocket/index.d.ts +28 -2
  30. package/dist/websocket/index.js +28 -1
  31. package/dist/websocket/index.js.map +1 -1
  32. package/examples/bedrock-agent.ts +6 -1
  33. package/examples/room-play-tone/ws-app.ts +63 -0
  34. package/examples/room-say/ws-app.ts +67 -0
  35. package/examples/room-with-stream/ws-app.ts +64 -0
  36. package/examples/s2s-move-to-room/ws-app.ts +82 -0
  37. package/examples/{listen-record → stream-record}/app.ts +2 -2
  38. package/examples/stream-then-room/ws-app.ts +74 -0
  39. package/package.json +2 -2
@@ -0,0 +1,67 @@
1
+ import http from 'http';
2
+ import { createEndpoint } from '@jambonz/sdk/websocket';
3
+
4
+ /*
5
+ * Speak TTS into a Room, heard by every member, mid-call.
6
+ *
7
+ * The caller joins a Room. SAY_DELAY_MS after joining, we call
8
+ * session.injectSay({...}) — a one-shot announcement synthesized into the Room and
9
+ * heard by all members (not just the caller). The optional `id` is echoed back on
10
+ * the say-start / say-done events so you can correlate them.
11
+ *
12
+ * The room verb subscribes to the say lifecycle via statusEvents + statusHook;
13
+ * say-start fires when audio begins, say-done when it finishes.
14
+ */
15
+
16
+ const server = http.createServer();
17
+ const makeService = createEndpoint({
18
+ server,
19
+ port: 3000,
20
+ envVars: {
21
+ ROOM_NAME: { type: 'string', description: 'Room name', default: 'demo-room' },
22
+ SAY_TEXT: { type: 'string', description: 'text to announce into the Room', default: 'Welcome — this announcement is heard by everyone in the room.' },
23
+ SAY_VENDOR: { type: 'string', description: 'TTS vendor (optional; account default if unset)', required: false },
24
+ SAY_DELAY_MS: { type: 'number', description: 'ms after joining before the announcement', default: 5000 },
25
+ },
26
+ });
27
+
28
+ const svc = makeService({ path: '/room-say' });
29
+
30
+ svc.on('session:new', (session) => {
31
+ const env = session.data.env_vars || {};
32
+ const room = env.ROOM_NAME || 'demo-room';
33
+ const text = env.SAY_TEXT || 'Welcome — this announcement is heard by everyone in the room.';
34
+ const synthesizer = env.SAY_VENDOR ? { vendor: env.SAY_VENDOR } : undefined;
35
+ const sayDelayMs = parseInt(env.SAY_DELAY_MS ?? '5000', 10);
36
+
37
+ console.log(`Incoming call ${session.callSid} -> Room '${room}', announcing in ${sayDelayMs}ms`);
38
+
39
+ let announced = false;
40
+ session
41
+ .on('/room-status', (evt: Record<string, any>) => {
42
+ console.log(`room status: ${evt?.event}`, { sayId: evt?.say_id, id: evt?.id, reason: evt?.reason });
43
+ // announce once the caller has joined the Room
44
+ if ((evt?.event === 'join' || evt?.event === 'start') && !announced) {
45
+ announced = true;
46
+ setTimeout(() => {
47
+ console.log('>>> injectSay into the Room');
48
+ session.injectSay({ text, id: 'announcement', ...(synthesizer && { synthesizer }) });
49
+ }, Math.max(0, sayDelayMs));
50
+ }
51
+ })
52
+ .on('/room-done', () => session.reply())
53
+ .on('close', (code: number) => console.log(`session ${session.callSid} closed: ${code}`))
54
+ .on('error', (err: Error) => console.error('session error:', err));
55
+
56
+ session
57
+ .answer()
58
+ .room({
59
+ name: room,
60
+ actionHook: '/room-done',
61
+ statusHook: '/room-status',
62
+ statusEvents: ['start', 'end', 'join', 'leave', 'say-start', 'say-done'],
63
+ })
64
+ .send();
65
+ });
66
+
67
+ console.log('room-say listening on port 3000 (path /room-say)');
@@ -0,0 +1,64 @@
1
+ import http from 'http';
2
+ import { createEndpoint } from '@jambonz/sdk/websocket';
3
+
4
+ /*
5
+ * A Room with a nested audio stream.
6
+ *
7
+ * The caller is answered straight into a Room whose `stream` property forks the
8
+ * room's mixed audio to a WebSocket endpoint. With bidirectionalAudio enabled,
9
+ * whatever the endpoint streams back is mixed into the room and heard by every
10
+ * member — so the stream socket is effectively a participant in the Room.
11
+ *
12
+ * (`stream` is the preferred synonym for the nested `listen` property.)
13
+ */
14
+
15
+ const server = http.createServer();
16
+ const makeService = createEndpoint({
17
+ server,
18
+ port: 3000,
19
+ envVars: {
20
+ STREAM_WS_URL: { type: 'string', description: 'WebSocket URL to stream the room audio to', required: true },
21
+ ROOM_NAME: { type: 'string', description: 'Room name', default: 'demo-room' },
22
+ SAMPLE_RATE: { type: 'number', description: 'audio sample rate for the stream', default: 8000 },
23
+ },
24
+ });
25
+
26
+ const svc = makeService({ path: '/room-with-stream' });
27
+
28
+ svc.on('session:new', (session) => {
29
+ const env = session.data.env_vars || {};
30
+ const streamUrl = env.STREAM_WS_URL;
31
+ const room = env.ROOM_NAME || 'demo-room';
32
+ const sampleRate = parseInt(env.SAMPLE_RATE ?? '8000', 10);
33
+
34
+ console.log(`Incoming call ${session.callSid} -> Room '${room}' with a nested audio stream`);
35
+ if (!streamUrl) {
36
+ console.error('STREAM_WS_URL is not configured as an application environment variable');
37
+ return;
38
+ }
39
+
40
+ session
41
+ .on('/room-done', () => session.reply()) // room verb completed (caller left)
42
+ .on('/stream-event', (evt: Record<string, any>) => console.log('stream event:', evt?.type))
43
+ .on('close', (code: number) => console.log(`session ${session.callSid} closed: ${code}`))
44
+ .on('error', (err: Error) => console.error('session error:', err));
45
+
46
+ session
47
+ .answer()
48
+ .room({
49
+ name: room,
50
+ beep: true,
51
+ actionHook: '/room-done',
52
+ // nested stream: fork the room's audio to STREAM_WS_URL; audio streamed back
53
+ // is mixed into the room (bidirectional).
54
+ stream: {
55
+ url: streamUrl,
56
+ sampleRate,
57
+ bidirectionalAudio: { enabled: true, streaming: true, sampleRate },
58
+ actionHook: '/stream-event',
59
+ },
60
+ })
61
+ .send();
62
+ });
63
+
64
+ console.log('room-with-stream listening on port 3000 (path /room-with-stream)');
@@ -0,0 +1,82 @@
1
+ import http from 'http';
2
+ import { createEndpoint } from '@jambonz/sdk/websocket';
3
+
4
+ /*
5
+ * Connect a caller to an Ultravox speech-to-speech agent, then move BOTH the
6
+ * caller and the agent into a Room — keeping the same conversation and the vendor
7
+ * WebSocket alive.
8
+ *
9
+ * The caller is answered into a 1:1 Ultravox s2s session. Once the agent is live
10
+ * (first event), we wait MOVE_DELAY_MS and issue one live-call-control command:
11
+ * llm:status { llm_status: 'move-to-room', room }
12
+ * jambonz joins the caller into the Room (created if needed) and re-homes the
13
+ * agent's s2s engine into the Room as a member — no reconnect, the agent now
14
+ * hears (and is heard by) the whole Room.
15
+ *
16
+ * Set MOVE_DELAY_MS=0 to land the caller + agent in the Room immediately.
17
+ */
18
+
19
+ const server = http.createServer();
20
+ const makeService = createEndpoint({
21
+ server,
22
+ port: 3000,
23
+ envVars: {
24
+ ULTRAVOX_API_KEY: { type: 'string', description: 'Ultravox API key', required: true, obscure: true },
25
+ ULTRAVOX_AGENT_ID: { type: 'string', description: 'Ultravox agent id', required: true },
26
+ ROOM_NAME: { type: 'string', description: 'Room to move into', default: 'agent-room' },
27
+ MOVE_DELAY_MS: { type: 'number', description: 'ms after the agent connects before moving into a Room', default: 15000 },
28
+ },
29
+ });
30
+
31
+ const svc = makeService({ path: '/s2s-move-to-room' });
32
+
33
+ svc.on('session:new', (session) => {
34
+ const env = session.data.env_vars || {};
35
+ const apiKey = env.ULTRAVOX_API_KEY;
36
+ const agentId = env.ULTRAVOX_AGENT_ID;
37
+ const room = env.ROOM_NAME || 'agent-room';
38
+ const moveDelayMs = parseInt(env.MOVE_DELAY_MS ?? '15000', 10);
39
+
40
+ console.log(`Incoming call ${session.callSid} -> Ultravox s2s; moving into Room '${room}' ${moveDelayMs}ms after connect`);
41
+ if (!apiKey || !agentId) {
42
+ console.error('ULTRAVOX_API_KEY and ULTRAVOX_AGENT_ID must be configured as application environment variables');
43
+ session.say({ text: 'Configuration error.' }).hangup().send();
44
+ return;
45
+ }
46
+
47
+ let armed = false;
48
+ let moved = false;
49
+ const moveToRoom = () => {
50
+ if (moved) return;
51
+ moved = true;
52
+ console.log(`>>> moving caller + agent into Room '${room}' (vendor WebSocket preserved)`);
53
+ session.injectCommand('llm:status', { llm_status: 'move-to-room', room });
54
+ };
55
+
56
+ session
57
+ .on('/event', () => {
58
+ // the first agent event fires only after the vendor WebSocket connects, so
59
+ // the s2s engine exists server-side; arm the move timer from here.
60
+ if (!armed) {
61
+ armed = true;
62
+ setTimeout(moveToRoom, Math.max(0, moveDelayMs));
63
+ }
64
+ })
65
+ .on('/final', () => session.reply()) // s2s (llm) verb completed
66
+ .on('close', (code: number) => console.log(`session ${session.callSid} closed: ${code}`))
67
+ .on('error', (err: Error) => console.error('session error:', err));
68
+
69
+ session
70
+ .answer()
71
+ .ultravox_s2s({
72
+ auth: { apiKey, agent_id: agentId },
73
+ actionHook: '/final',
74
+ eventHook: '/event',
75
+ events: ['all'],
76
+ llmOptions: {},
77
+ })
78
+ .hangup()
79
+ .send();
80
+ });
81
+
82
+ console.log('s2s-move-to-room listening on port 3000 (path /s2s-move-to-room)');
@@ -14,9 +14,9 @@ app.post('/record', (_req, res) => {
14
14
  .say({
15
15
  text: 'Hi there. Please leave a message, and we will get back to you shortly.',
16
16
  })
17
- .listen({ url: wsUrl });
17
+ .stream({ url: wsUrl });
18
18
 
19
19
  res.json(jambonz);
20
20
  });
21
21
 
22
- app.listen(3000, () => console.log('Listen-record webhook app listening on port 3000'));
22
+ app.listen(3000, () => console.log('Stream-record webhook app listening on port 3000'));
@@ -0,0 +1,74 @@
1
+ import http from 'http';
2
+ import { createEndpoint } from '@jambonz/sdk/websocket';
3
+
4
+ /*
5
+ * Start a 1:1 audio stream, then move the caller AND the live stream into a Room
6
+ * — without dropping the stream's WebSocket.
7
+ *
8
+ * The caller is answered into a bidirectional `stream` (1:1 with the WS endpoint).
9
+ * MOVE_DELAY_MS later we issue one live-call-control command:
10
+ * stream:status { stream_status: 'move-to-room', room }
11
+ * jambonz joins the caller into the Room (creating it if needed) and re-homes the
12
+ * existing stream into the Room as a member — the same socket keeps streaming, now
13
+ * mixed for everyone in the Room.
14
+ *
15
+ * The stream verb MUST carry an `id` to be a managed (movable) stream.
16
+ */
17
+
18
+ const server = http.createServer();
19
+ const makeService = createEndpoint({
20
+ server,
21
+ port: 3000,
22
+ envVars: {
23
+ STREAM_WS_URL: { type: 'string', description: 'WebSocket URL for the audio stream', required: true },
24
+ ROOM_NAME: { type: 'string', description: 'Room to move into', default: 'demo-room' },
25
+ SAMPLE_RATE: { type: 'number', description: 'audio sample rate for the stream', default: 8000 },
26
+ MOVE_DELAY_MS: { type: 'number', description: 'ms after answer before moving into the Room', default: 10000 },
27
+ },
28
+ });
29
+
30
+ const svc = makeService({ path: '/stream-then-room' });
31
+
32
+ svc.on('session:new', (session) => {
33
+ const env = session.data.env_vars || {};
34
+ const streamUrl = env.STREAM_WS_URL;
35
+ const room = env.ROOM_NAME || 'demo-room';
36
+ const sampleRate = parseInt(env.SAMPLE_RATE ?? '8000', 10);
37
+ const moveDelayMs = parseInt(env.MOVE_DELAY_MS ?? '10000', 10);
38
+
39
+ console.log(`Incoming call ${session.callSid} -> 1:1 stream, moving into Room '${room}' in ${moveDelayMs}ms`);
40
+ if (!streamUrl) {
41
+ console.error('STREAM_WS_URL is not configured as an application environment variable');
42
+ return;
43
+ }
44
+
45
+ let moved = false;
46
+ const moveToRoom = () => {
47
+ if (moved) return;
48
+ moved = true;
49
+ console.log(`>>> moving caller + stream into Room '${room}' (WebSocket preserved)`);
50
+ // server-side this bundles the caller-join and adopts the stream as a Room member.
51
+ session.injectCommand('stream:status', { stream_status: 'move-to-room', room });
52
+ };
53
+
54
+ session
55
+ .on('/stream-done', () => session.reply())
56
+ .on('close', (code: number) => console.log(`session ${session.callSid} closed: ${code}`))
57
+ .on('error', (err: Error) => console.error('session error:', err));
58
+
59
+ // the stream connects well within the delay, so it exists by the time we move
60
+ setTimeout(moveToRoom, Math.max(0, moveDelayMs));
61
+
62
+ session
63
+ .answer()
64
+ .stream({
65
+ id: 'caller-stream', // managed => movable
66
+ url: streamUrl,
67
+ sampleRate,
68
+ bidirectionalAudio: { enabled: true, streaming: true, sampleRate },
69
+ actionHook: '/stream-done',
70
+ })
71
+ .send();
72
+ });
73
+
74
+ console.log('stream-then-room listening on port 3000 (path /stream-then-room)');
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@jambonz/sdk",
3
- "version": "0.6.0",
3
+ "version": "0.8.0",
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.8",
101
+ "@jambonz/schema": "^0.3.15",
102
102
  "ajv": "^8.17.1",
103
103
  "ws": "^8.18.0"
104
104
  },