@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
package/AGENTS.md CHANGED
@@ -188,7 +188,9 @@ console.log('Speech echo WebSocket app listening on port 3000');
188
188
 
189
189
  Both `WebhookResponse` and `Session` support the same chainable verb methods:
190
190
 
191
- `.say(opts)` `.play(opts)` `.gather(opts)` `.dial(opts)` `.llm(opts)` `.s2s(opts)` `.openai_s2s(opts)` `.google_s2s(opts)` `.elevenlabs_s2s(opts)` `.deepgram_s2s(opts)` `.ultravox_s2s(opts)` `.dialogflow(opts)` `.conference(opts)` `.enqueue(opts)` `.dequeue(opts)` `.hangup()` `.pause(opts)` `.redirect(opts)` `.config(opts)` `.tag(opts)` `.dtmf(opts)` `.listen(opts)` `.transcribe(opts)` `.message(opts)` `.stream(opts)` `.agent(opts)` `.dub(opts)` `.alert(opts)` `.answer(opts)` `.leave()` `.sipDecline(opts)` `.sipRefer(opts)` `.sipRequest(opts)`
191
+ `.say(opts)` `.play(opts)` `.gather(opts)` `.dial(opts)` `.llm(opts)` `.s2s(opts)` `.openai_s2s(opts)` `.google_s2s(opts)` `.elevenlabs_s2s(opts)` `.deepgram_s2s(opts)` `.ultravox_s2s(opts)` `.dialogflow(opts)` `.room(opts)` `.enqueue(opts)` `.dequeue(opts)` `.hangup()` `.pause(opts)` `.redirect(opts)` `.config(opts)` `.tag(opts)` `.dtmf(opts)` `.stream(opts)` `.transcribe(opts)` `.message(opts)` `.agent(opts)` `.dub(opts)` `.alert(opts)` `.answer(opts)` `.leave()` `.sipDecline(opts)` `.sipRefer(opts)` `.sipRequest(opts)`
192
+
193
+ Prefer `.room(opts)` and `.stream(opts)`. `.conference(opts)` and `.listen(opts)` remain as backward-compatible synonyms (same options), but new apps should use `room`/`stream`.
192
194
 
193
195
  All methods accept the same options as the corresponding verb JSON Schema. Methods are chainable — they return `this`.
194
196
 
@@ -415,9 +417,9 @@ session.on('close', (code, reason) => { /* connection closed */ });
415
417
  session.on('error', (err) => { /* error */ });
416
418
  ```
417
419
 
418
- ## Audio WebSocket (Listen/Stream)
420
+ ## Audio WebSocket (Stream/Listen)
419
421
 
420
- The `listen` and `stream` verbs open a separate WebSocket connection from jambonz to your application, carrying raw audio. This is independent of the control WebSocket (`ws.jambonz.org`) — it uses the `audio.drachtio.org` subprotocol.
422
+ The `stream` verb (and its backward-compatible synonym `listen`) opens a separate WebSocket connection from jambonz to your application, carrying raw audio. This is independent of the control WebSocket (`ws.jambonz.org`) — it uses the `audio.drachtio.org` subprotocol.
421
423
 
422
424
  ### Receiving Audio in the Same Application
423
425
 
@@ -433,14 +435,14 @@ const makeService = createEndpoint({ server, port: 3000 });
433
435
  // Control pipe — handles call sessions
434
436
  const svc = makeService({ path: '/' });
435
437
 
436
- // Audio pipe — receives listen/stream audio
438
+ // Audio pipe — receives stream audio
437
439
  const audioSvc = makeService.audio({ path: '/audio-stream' });
438
440
 
439
441
  svc.on('session:new', (session) => {
440
442
  session
441
443
  .answer()
442
444
  .say({ text: 'Recording your audio.' })
443
- .listen({
445
+ .stream({
444
446
  url: '/audio-stream', // relative path — jambonz connects back to same server
445
447
  sampleRate: 16000,
446
448
  mixType: 'mono',
@@ -472,7 +474,7 @@ The `stream` object in the `connection` event is an `AudioStream` instance:
472
474
 
473
475
  **Events**:
474
476
  - `audio` — L16 PCM binary frame (`Buffer`)
475
- - `dtmf` — `{digit, duration}` (only if `passDtmf: true` on listen verb)
477
+ - `dtmf` — `{digit, duration}` (only if `passDtmf: true` on stream verb)
476
478
  - `playDone` — `{id}` (after non-streaming playAudio completes)
477
479
  - `mark` — `{name, event}` where event is `'playout'` or `'cleared'`
478
480
  - `close` — `(code, reason)`
@@ -480,7 +482,7 @@ The `stream` object in the `connection` event is an `AudioStream` instance:
480
482
 
481
483
  ### Sending Audio Back (Bidirectional)
482
484
 
483
- The listen verb supports bidirectional audio. There are two modes, controlled by the `bidirectionalAudio.streaming` option on the listen verb.
485
+ The stream verb supports bidirectional audio. There are two modes, controlled by the `bidirectionalAudio.streaming` option on the stream verb.
484
486
 
485
487
  **Non-streaming mode** (`streaming: false`, the default) — send complete audio clips as base64:
486
488
 
@@ -502,7 +504,7 @@ Up to 10 playAudio commands can be queued simultaneously.
502
504
  **Streaming mode** (`streaming: true`) — send raw binary PCM frames directly:
503
505
 
504
506
  ```typescript
505
- // In the listen verb config:
507
+ // In the stream verb config:
506
508
  // bidirectionalAudio: { enabled: true, streaming: true, sampleRate: 16000 }
507
509
 
508
510
  stream.on('audio', (pcm) => {
@@ -513,16 +515,16 @@ stream.on('audio', (pcm) => {
513
515
 
514
516
  ### Marks (Synchronization Markers)
515
517
 
516
- Marks let you track when streamed audio has been played out to the caller. They work **only with bidirectional streaming mode** — you must enable `bidirectionalAudio: { enabled: true, streaming: true }` on the listen verb.
518
+ Marks let you track when streamed audio has been played out to the caller. They work **only with bidirectional streaming mode** — you must enable `bidirectionalAudio: { enabled: true, streaming: true }` on the stream verb.
517
519
 
518
520
  The pattern is: stream audio via `sendAudio()`, then send a mark. When all the audio sent before the mark finishes playing out, jambonz sends back a mark event with `event: 'playout'`. This is how you know the caller has heard a specific chunk of audio.
519
521
 
520
522
  ```typescript
521
- // Listen verb must enable bidirectional streaming for marks to work
523
+ // Stream verb must enable bidirectional streaming for marks to work
522
524
  session
523
- .listen({
525
+ .stream({
524
526
  url: '/audio',
525
- actionHook: '/listen-done',
527
+ actionHook: '/stream-done',
526
528
  bidirectionalAudio: {
527
529
  enabled: true,
528
530
  streaming: true,
@@ -557,7 +559,7 @@ audioSvc.on('connection', (stream) => {
557
559
 
558
560
  ```typescript
559
561
  stream.killAudio(); // Stop playback, flush buffer
560
- stream.disconnect(); // Close connection, end listen verb
562
+ stream.disconnect(); // Close connection, end stream verb
561
563
  stream.sendMark('sync-pt'); // Insert synchronization marker
562
564
  stream.clearMarks(); // Clear all pending markers
563
565
  stream.close(); // Close the WebSocket
@@ -710,7 +712,7 @@ Complete working examples are in the `examples/` directory:
710
712
  - **echo** — Speech echo using gather with actionHook pattern (webhook + WebSocket). The canonical example for understanding actionHook event handling.
711
713
  - **ivr-menu** — Interactive menu with speech and DTMF input (webhook)
712
714
  - **dial** — Simple outbound dial to a phone number (webhook)
713
- - **listen-record** — Record audio using the listen verb to stream to a WebSocket (webhook)
715
+ - **stream-record** — Record audio using the stream verb to stream to a WebSocket (webhook)
714
716
  - **voice-agent** — LLM-powered conversational AI with tool calls (webhook + WebSocket)
715
717
  - **openai-realtime** — OpenAI Realtime API voice agent with function calling (WebSocket)
716
718
  - **deepgram-voice-agent** — Deepgram Voice Agent API with function calling (WebSocket)
@@ -719,3 +721,8 @@ Complete working examples are in the `examples/` directory:
719
721
  - **queue-with-hold** — Call queue with hold music and agent dequeue (webhook + WebSocket)
720
722
  - **call-recording** — Mid-call recording control via REST API and inject commands (webhook + WebSocket)
721
723
  - **realtime-translator** — Bridges two parties with real-time speech translation using STT, Google Translate, and TTS dub tracks. Multi-file example with `src/routes/` structure (WebSocket)
724
+ - **room-with-stream** — A Room with a nested bidirectional audio stream forked to a WebSocket (WebSocket)
725
+ - **stream-then-room** — 1:1 stream, then move the caller + stream into a Room mid-call (WebSocket)
726
+ - **s2s-move-to-room** — Ultravox s2s, then move the caller + agent into a Room mid-call (WebSocket)
727
+ - **room-say** — injectSay a one-shot TTS announcement heard by the whole Room (WebSocket)
728
+ - **room-play-tone** — injectPlay a tone heard by the whole Room (WebSocket)
@@ -1,5 +1,5 @@
1
- import { b as CreateCallRequest, L as ListCallsFilter, a as CallInfo, C as CallCount, U as UpdateCallRequest, Q as QueueInfo } from '../rest-usG3riy3.cjs';
2
- import { A as ActionHook, W as Verb } from '../verbs-lEtMeHGd.cjs';
1
+ import { b as CreateCallRequest, L as ListCallsFilter, a as CallInfo, C as CallCount, U as UpdateCallRequest, Q as QueueInfo } from '../rest-BehrJ_ai.cjs';
2
+ import { A as ActionHook, W as Verb } from '../verbs-BuObLiyU.cjs';
3
3
 
4
4
  /**
5
5
  * JambonzClient — REST API client for the jambonz platform.
@@ -1,5 +1,5 @@
1
- import { b as CreateCallRequest, L as ListCallsFilter, a as CallInfo, C as CallCount, U as UpdateCallRequest, Q as QueueInfo } from '../rest-DQrUmoQN.js';
2
- import { A as ActionHook, W as Verb } from '../verbs-lEtMeHGd.js';
1
+ import { b as CreateCallRequest, L as ListCallsFilter, a as CallInfo, C as CallCount, U as UpdateCallRequest, Q as QueueInfo } from '../rest-CIi3fP4n.js';
2
+ import { A as ActionHook, W as Verb } from '../verbs-BuObLiyU.js';
3
3
 
4
4
  /**
5
5
  * JambonzClient — REST API client for the jambonz platform.
package/dist/index.cjs CHANGED
@@ -192,6 +192,10 @@ var VerbBuilder = class {
192
192
  conference(opts) {
193
193
  return this.addVerb({ verb: "conference", ...opts });
194
194
  }
195
+ /** `room` is a synonym for `conference` — prefer it in new applications. */
196
+ room(opts) {
197
+ return this.addVerb({ verb: "room", ...opts });
198
+ }
195
199
  /** Place the caller into a named queue. */
196
200
  enqueue(opts) {
197
201
  return this.addVerb({ verb: "enqueue", ...opts });
@@ -693,6 +697,25 @@ var Session = class extends events.EventEmitter {
693
697
  injectListenStatus(status, callSid) {
694
698
  this.injectCommand("listen:status", { listen_status: status }, callSid);
695
699
  }
700
+ /**
701
+ * Speak one-shot TTS into the room (conference) this call is in, so EVERY
702
+ * member hears it. Mirrors the `say` verb; the room is inferred from the
703
+ * call's current conference. `say-start`/`say-done` events are delivered to
704
+ * the conference verb's `statusHook` when listed in its `statusEvents`
705
+ * (include 'say-start','say-done'); the optional `id` is echoed for
706
+ * correlation. (Streaming — `stream:true` — is not yet supported server-side.)
707
+ */
708
+ injectSay(opts, callSid) {
709
+ this.injectCommand("room:say", opts, callSid);
710
+ }
711
+ /**
712
+ * Play a file/tone into the room (conference) this call is in, heard by every
713
+ * member. `play-start`/`play-done` events go to the conference verb's
714
+ * `statusHook` when listed in its `statusEvents`.
715
+ */
716
+ injectPlay(opts, callSid) {
717
+ this.injectCommand("room:play", opts, callSid);
718
+ }
696
719
  /** Control call recording. */
697
720
  injectRecord(action, opts, callSid) {
698
721
  this.injectCommand("record", { action, ...opts }, callSid);
@@ -868,16 +891,20 @@ var Session = class extends events.EventEmitter {
868
891
  switch (type) {
869
892
  case "verb:hook":
870
893
  case "session:redirect":
871
- case "dial:confirm":
894
+ case "dial:confirm": {
872
895
  this.msgid = msgid;
896
+ const isNotification = type === "verb:hook" && !!data && typeof data === "object" && typeof data.event === "string";
873
897
  if (hook && this.listenerCount(hook) > 0) {
874
898
  this.emit(hook, data);
899
+ if (isNotification) this.reply();
875
900
  } else if (type === "verb:hook" && this.listenerCount("verb:hook") > 0) {
876
901
  this.emit("verb:hook", hook, data);
902
+ if (isNotification) this.reply();
877
903
  } else {
878
904
  this.reply();
879
905
  }
880
906
  break;
907
+ }
881
908
  case "llm:event":
882
909
  case "llm:tool-call":
883
910
  case "agent:event":