@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.
- package/AGENTS.md +21 -14
- package/dist/client/index.d.cts +2 -2
- package/dist/client/index.d.ts +2 -2
- package/dist/index.cjs +28 -1
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +3 -3
- package/dist/index.d.ts +3 -3
- package/dist/index.js +28 -1
- package/dist/index.js.map +1 -1
- package/dist/{rest-usG3riy3.d.cts → rest-BehrJ_ai.d.cts} +16 -1
- package/dist/{rest-DQrUmoQN.d.ts → rest-CIi3fP4n.d.ts} +16 -1
- package/dist/types/index.cjs.map +1 -1
- package/dist/types/index.d.cts +2 -2
- package/dist/types/index.d.ts +2 -2
- package/dist/types/index.js.map +1 -1
- package/dist/{verb-builder-CNdBB1t6.d.cts → verb-builder-8zDaN7ba.d.ts} +3 -1
- package/dist/{verb-builder-DF5pnZWH.d.ts → verb-builder-Cc9cLrYj.d.cts} +3 -1
- package/dist/{verbs-lEtMeHGd.d.cts → verbs-BuObLiyU.d.cts} +25 -4
- package/dist/{verbs-lEtMeHGd.d.ts → verbs-BuObLiyU.d.ts} +25 -4
- package/dist/webhook/index.cjs +4 -0
- package/dist/webhook/index.cjs.map +1 -1
- package/dist/webhook/index.d.cts +2 -2
- package/dist/webhook/index.d.ts +2 -2
- package/dist/webhook/index.js +4 -0
- package/dist/webhook/index.js.map +1 -1
- package/dist/websocket/index.cjs +28 -1
- package/dist/websocket/index.cjs.map +1 -1
- package/dist/websocket/index.d.cts +28 -2
- package/dist/websocket/index.d.ts +28 -2
- package/dist/websocket/index.js +28 -1
- package/dist/websocket/index.js.map +1 -1
- package/examples/bedrock-agent.ts +6 -1
- package/examples/room-play-tone/ws-app.ts +63 -0
- package/examples/room-say/ws-app.ts +67 -0
- package/examples/room-with-stream/ws-app.ts +64 -0
- package/examples/s2s-move-to-room/ws-app.ts +82 -0
- package/examples/{listen-record → stream-record}/app.ts +2 -2
- package/examples/stream-then-room/ws-app.ts +74 -0
- 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)` `.
|
|
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
|
|
420
|
+
## Audio WebSocket (Stream/Listen)
|
|
419
421
|
|
|
420
|
-
The `
|
|
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
|
|
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
|
-
.
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
//
|
|
523
|
+
// Stream verb must enable bidirectional streaming for marks to work
|
|
522
524
|
session
|
|
523
|
-
.
|
|
525
|
+
.stream({
|
|
524
526
|
url: '/audio',
|
|
525
|
-
actionHook: '/
|
|
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
|
|
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
|
-
- **
|
|
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)
|
package/dist/client/index.d.cts
CHANGED
|
@@ -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-
|
|
2
|
-
import { A as ActionHook, W as Verb } from '../verbs-
|
|
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.
|
package/dist/client/index.d.ts
CHANGED
|
@@ -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-
|
|
2
|
-
import { A as ActionHook, W as Verb } from '../verbs-
|
|
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":
|