@jambonz/sdk 0.1.0 → 0.1.2

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 (122) hide show
  1. package/dist/client/index.cjs +60 -13
  2. package/dist/client/index.cjs.map +1 -1
  3. package/dist/client/index.d.cts +36 -7
  4. package/dist/client/index.d.ts +36 -7
  5. package/dist/client/index.js +59 -13
  6. package/dist/client/index.js.map +1 -1
  7. package/dist/common-BSJZX7WO.d.cts +34 -0
  8. package/dist/common-BSJZX7WO.d.ts +34 -0
  9. package/dist/index.cjs +364 -32
  10. package/dist/index.cjs.map +1 -1
  11. package/dist/index.d.cts +8 -7
  12. package/dist/index.d.ts +8 -7
  13. package/dist/index.js +360 -32
  14. package/dist/index.js.map +1 -1
  15. package/dist/rest-BF9HKZrA.d.ts +136 -0
  16. package/dist/rest-v8weIueZ.d.cts +136 -0
  17. package/dist/session-DHc6G_9y.d.cts +112 -0
  18. package/dist/session-DHc6G_9y.d.ts +112 -0
  19. package/dist/types/index.d.cts +4 -3
  20. package/dist/types/index.d.ts +4 -3
  21. package/dist/{verb-builder-But-DJle.d.cts → verb-builder-Dg_IPC4I.d.ts} +35 -2
  22. package/dist/{verb-builder-CO_qoYxC.d.ts → verb-builder-DkHAJrk4.d.cts} +35 -2
  23. package/dist/{verbs-B_afNNUM.d.cts → verbs-fjJjfGEt.d.cts} +40 -14
  24. package/dist/{verbs-B_afNNUM.d.ts → verbs-fjJjfGEt.d.ts} +40 -14
  25. package/dist/webhook/index.cjs +68 -8
  26. package/dist/webhook/index.cjs.map +1 -1
  27. package/dist/webhook/index.d.cts +45 -3
  28. package/dist/webhook/index.d.ts +45 -3
  29. package/dist/webhook/index.js +68 -9
  30. package/dist/webhook/index.js.map +1 -1
  31. package/dist/websocket/index.cjs +291 -19
  32. package/dist/websocket/index.cjs.map +1 -1
  33. package/dist/websocket/index.d.cts +198 -4
  34. package/dist/websocket/index.d.ts +198 -4
  35. package/dist/websocket/index.js +290 -20
  36. package/dist/websocket/index.js.map +1 -1
  37. package/package.json +19 -6
  38. package/schema/callbacks/base.schema.json +29 -0
  39. package/schema/callbacks/call-status.schema.json +22 -0
  40. package/schema/callbacks/conference-status.schema.json +24 -0
  41. package/schema/callbacks/conference-wait.schema.json +11 -0
  42. package/schema/callbacks/conference.schema.json +11 -0
  43. package/schema/callbacks/dequeue.schema.json +19 -0
  44. package/schema/callbacks/dial-dtmf.schema.json +18 -0
  45. package/schema/callbacks/dial-hold.schema.json +22 -0
  46. package/schema/callbacks/dial-refer.schema.json +28 -0
  47. package/schema/callbacks/dial.schema.json +31 -0
  48. package/schema/callbacks/enqueue-wait.schema.json +17 -0
  49. package/schema/callbacks/enqueue.schema.json +27 -0
  50. package/schema/callbacks/gather-partial.schema.json +54 -0
  51. package/schema/callbacks/gather.schema.json +60 -0
  52. package/schema/callbacks/listen.schema.json +21 -0
  53. package/schema/callbacks/llm.schema.json +30 -0
  54. package/schema/callbacks/message.schema.json +35 -0
  55. package/schema/callbacks/play.schema.json +36 -0
  56. package/schema/callbacks/session-new.schema.json +143 -0
  57. package/schema/callbacks/session-reconnect.schema.json +9 -0
  58. package/schema/callbacks/session-redirect.schema.json +38 -0
  59. package/schema/callbacks/sip-refer-event.schema.json +20 -0
  60. package/schema/callbacks/sip-refer.schema.json +22 -0
  61. package/schema/callbacks/sip-request.schema.json +27 -0
  62. package/schema/callbacks/transcribe-translation.schema.json +24 -0
  63. package/schema/callbacks/transcribe.schema.json +46 -0
  64. package/schema/callbacks/verb-status.schema.json +57 -0
  65. package/schema/components/actionHook.schema.json +36 -0
  66. package/schema/components/actionHookDelayAction.schema.json +37 -0
  67. package/schema/components/amd.schema.json +68 -0
  68. package/schema/components/auth.schema.json +18 -0
  69. package/schema/components/bidirectionalAudio.schema.json +22 -0
  70. package/schema/components/fillerNoise.schema.json +25 -0
  71. package/schema/components/recognizer-assemblyAiOptions.schema.json +35 -0
  72. package/schema/components/recognizer-awsOptions.schema.json +52 -0
  73. package/schema/components/recognizer-azureOptions.schema.json +32 -0
  74. package/schema/components/recognizer-cobaltOptions.schema.json +34 -0
  75. package/schema/components/recognizer-customOptions.schema.json +27 -0
  76. package/schema/components/recognizer-deepgramOptions.schema.json +147 -0
  77. package/schema/components/recognizer-elevenlabsOptions.schema.json +39 -0
  78. package/schema/components/recognizer-gladiaOptions.schema.json +8 -0
  79. package/schema/components/recognizer-googleOptions.schema.json +35 -0
  80. package/schema/components/recognizer-houndifyOptions.schema.json +53 -0
  81. package/schema/components/recognizer-ibmOptions.schema.json +54 -0
  82. package/schema/components/recognizer-nuanceOptions.schema.json +150 -0
  83. package/schema/components/recognizer-nvidiaOptions.schema.json +39 -0
  84. package/schema/components/recognizer-openaiOptions.schema.json +59 -0
  85. package/schema/components/recognizer-sonioxOptions.schema.json +46 -0
  86. package/schema/components/recognizer-speechmaticsOptions.schema.json +91 -0
  87. package/schema/components/recognizer-verbioOptions.schema.json +46 -0
  88. package/schema/components/recognizer.schema.json +212 -0
  89. package/schema/components/synthesizer.schema.json +82 -0
  90. package/schema/components/target.schema.json +105 -0
  91. package/schema/components/vad.schema.json +48 -0
  92. package/schema/jambonz-app.schema.json +106 -0
  93. package/schema/verbs/alert.schema.json +20 -0
  94. package/schema/verbs/answer.schema.json +12 -0
  95. package/schema/verbs/conference.schema.json +43 -0
  96. package/schema/verbs/config.schema.json +170 -0
  97. package/schema/verbs/dequeue.schema.json +36 -0
  98. package/schema/verbs/dial.schema.json +153 -0
  99. package/schema/verbs/dtmf.schema.json +27 -0
  100. package/schema/verbs/dub.schema.json +52 -0
  101. package/schema/verbs/enqueue.schema.json +38 -0
  102. package/schema/verbs/gather.schema.json +145 -0
  103. package/schema/verbs/hangup.schema.json +29 -0
  104. package/schema/verbs/leave.schema.json +12 -0
  105. package/schema/verbs/listen.schema.json +109 -0
  106. package/schema/verbs/llm.schema.json +131 -0
  107. package/schema/verbs/message.schema.json +30 -0
  108. package/schema/verbs/pause.schema.json +26 -0
  109. package/schema/verbs/pipeline.schema.json +61 -0
  110. package/schema/verbs/play.schema.json +69 -0
  111. package/schema/verbs/redirect.schema.json +23 -0
  112. package/schema/verbs/say.schema.json +84 -0
  113. package/schema/verbs/sip-decline.schema.json +31 -0
  114. package/schema/verbs/sip-refer.schema.json +41 -0
  115. package/schema/verbs/sip-request.schema.json +33 -0
  116. package/schema/verbs/stream.schema.json +30 -0
  117. package/schema/verbs/tag.schema.json +21 -0
  118. package/schema/verbs/transcribe.schema.json +48 -0
  119. package/dist/common-Bsqv1Brz.d.cts +0 -69
  120. package/dist/common-Bsqv1Brz.d.ts +0 -69
  121. package/dist/rest-BV_FsqnH.d.cts +0 -97
  122. package/dist/rest-CthGXHnw.d.ts +0 -97
@@ -1,9 +1,10 @@
1
1
  import http, { IncomingMessage } from 'http';
2
- import { C as CallSession, W as WsMessage, L as Logger } from '../common-Bsqv1Brz.js';
2
+ import { L as Logger, a as EnvVarSchema } from '../common-BSJZX7WO.js';
3
3
  import { EventEmitter } from 'events';
4
4
  import { WebSocket } from 'ws';
5
- import { w as Verb } from '../verbs-B_afNNUM.js';
6
- import { c as VerbBuilderOptions, b as VerbBuilder } from '../verb-builder-CO_qoYxC.js';
5
+ import { C as CallSession, W as WsMessage } from '../session-DHc6G_9y.js';
6
+ import { y as Verb } from '../verbs-fjJjfGEt.js';
7
+ import { c as VerbBuilderOptions, b as VerbBuilder } from '../verb-builder-Dg_IPC4I.js';
7
8
 
8
9
  /**
9
10
  * WebSocket Session — represents a single call over a persistent WebSocket connection.
@@ -16,9 +17,34 @@ interface SessionOptions extends VerbBuilderOptions {
16
17
  msg: WsMessage;
17
18
  logger: Logger;
18
19
  }
20
+ /**
21
+ * Represents a single call over a persistent WebSocket connection.
22
+ *
23
+ * Provides verb building (chainable methods), send/reply for verb delivery,
24
+ * TTS token streaming with backpressure, inject commands for mid-call control,
25
+ * and LLM tool output. Emits events for actionHooks, call status, and TTS lifecycle.
26
+ *
27
+ * Created automatically by the SDK when a new call arrives — you receive it
28
+ * via the `session:new` event on a {@link WsClient}.
29
+ */
19
30
  declare class Session extends EventEmitter {
31
+ /** Unique call identifier. */
20
32
  readonly callSid: string;
33
+ /** Caller phone number or SIP URI. */
34
+ readonly from: string;
35
+ /** Called phone number or SIP URI. */
36
+ readonly to: string;
37
+ /** Call direction. */
38
+ readonly direction: 'inbound' | 'outbound';
39
+ /** Account identifier. */
40
+ readonly accountSid: string;
41
+ /** Application identifier. */
42
+ readonly applicationSid: string;
43
+ /** SIP Call-ID. */
44
+ readonly callId: string;
45
+ /** Distributed trace header (B3 format), if present. */
21
46
  readonly b3: string | undefined;
47
+ /** Full call session data from jambonz (includes env_vars, SIP headers, etc.). */
22
48
  readonly data: CallSession;
23
49
  /** Application-specific storage that persists for the session. */
24
50
  locals: Record<string, unknown>;
@@ -30,32 +56,59 @@ declare class Session extends EventEmitter {
30
56
  private commandQueue;
31
57
  private ttsCounter;
32
58
  private ttsPaused;
59
+ /** @internal */
33
60
  constructor(opts: SessionOptions);
61
+ /** Speak text using TTS. Supports SSML, multiple voices, and streaming. */
34
62
  say(opts: Parameters<VerbBuilder['say']>[0]): this;
63
+ /** Play an audio file from a URL. */
35
64
  play(opts: Parameters<VerbBuilder['play']>[0]): this;
65
+ /** Collect speech (STT) and/or DTMF input from the caller. */
36
66
  gather(opts: Parameters<VerbBuilder['gather']>[0]): this;
67
+ /** Connect the caller to an LLM for real-time voice conversation. */
37
68
  llm(opts: Parameters<VerbBuilder['llm']>[0]): this;
69
+ /** Voice AI pipeline with integrated turn detection. */
38
70
  pipeline(opts: Parameters<VerbBuilder['pipeline']>[0]): this;
71
+ /** Stream real-time call audio to a WebSocket endpoint. Supports bidirectional audio. */
39
72
  listen(opts: Parameters<VerbBuilder['listen']>[0]): this;
73
+ /** Stream real-time call audio to a WebSocket endpoint. Synonym for {@link listen}. */
40
74
  stream(opts: Parameters<VerbBuilder['stream']>[0]): this;
75
+ /** Real-time call transcription sent to a webhook. */
41
76
  transcribe(opts: Parameters<VerbBuilder['transcribe']>[0]): this;
77
+ /** Place an outbound call and bridge it to the current caller. */
42
78
  dial(opts: Parameters<VerbBuilder['dial']>[0]): this;
79
+ /** Join or create a multi-party conference room. */
43
80
  conference(opts: Parameters<VerbBuilder['conference']>[0]): this;
81
+ /** Place the caller into a named queue. */
44
82
  enqueue(opts: Parameters<VerbBuilder['enqueue']>[0]): this;
83
+ /** Remove a caller from a queue and bridge them. */
45
84
  dequeue(opts: Parameters<VerbBuilder['dequeue']>[0]): this;
85
+ /** End the call. */
46
86
  hangup(opts?: Parameters<VerbBuilder['hangup']>[0]): this;
87
+ /** Transfer control to a different webhook URL. */
47
88
  redirect(opts: Parameters<VerbBuilder['redirect']>[0]): this;
89
+ /** Wait for a specified duration before continuing. */
48
90
  pause(opts: Parameters<VerbBuilder['pause']>[0]): this;
91
+ /** Leave a conference or queue. */
49
92
  leave(opts?: Parameters<VerbBuilder['leave']>[0]): this;
93
+ /** Reject an incoming call with a SIP error response. */
50
94
  sipDecline(opts: Parameters<VerbBuilder['sipDecline']>[0]): this;
95
+ /** Send a SIP INFO or other request within the dialog. */
51
96
  sipRequest(opts: Parameters<VerbBuilder['sipRequest']>[0]): this;
97
+ /** Transfer the call via SIP REFER. */
52
98
  sipRefer(opts: Parameters<VerbBuilder['sipRefer']>[0]): this;
99
+ /** Set session-level defaults (TTS vendor/voice, STT vendor, VAD, etc.). */
53
100
  config(opts: Parameters<VerbBuilder['config']>[0]): this;
101
+ /** Explicitly answer the call (sends a 200 OK). */
54
102
  answer(opts?: Parameters<VerbBuilder['answer']>[0]): this;
103
+ /** Send a SIP 180 Ringing with optional Alert-Info header. */
55
104
  alert(opts: Parameters<VerbBuilder['alert']>[0]): this;
105
+ /** Attach metadata to the call for tracking or routing. */
56
106
  tag(opts: Parameters<VerbBuilder['tag']>[0]): this;
107
+ /** Send DTMF tones into the call. */
57
108
  dtmf(opts: Parameters<VerbBuilder['dtmf']>[0]): this;
109
+ /** Mix an auxiliary audio track into the call. */
58
110
  dub(opts: Parameters<VerbBuilder['dub']>[0]): this;
111
+ /** Send an SMS or MMS message. */
59
112
  message(opts: Parameters<VerbBuilder['message']>[0]): this;
60
113
  /** Add raw JSON verbs (primary AI agent path). */
61
114
  addVerbs(verbs: Verb[]): this;
@@ -67,6 +120,15 @@ declare class Session extends EventEmitter {
67
120
  reply(opts?: {
68
121
  execImmediate?: boolean;
69
122
  }): void;
123
+ /**
124
+ * Enable real-time verb status events for this session.
125
+ * Once enabled, the session emits 'verb:status' events for verb lifecycle
126
+ * changes (starting, finished, start-playback, stop-playback, etc.).
127
+ *
128
+ * This is a convenience for `.config({ notifyEvents: true })` — it can be
129
+ * chained into the initial verb sequence or called at any time.
130
+ */
131
+ notifyEvents(enabled?: boolean): this;
70
132
  /** Send an inject command for immediate execution. */
71
133
  injectCommand(command: string, data?: unknown, callSid?: string): void;
72
134
  /** Redirect call execution to a new webhook. */
@@ -139,9 +201,117 @@ declare class WsClient extends EventEmitter {
139
201
  private onSessionMessage;
140
202
  }
141
203
 
204
+ /**
205
+ * AudioStream — represents a single listen/stream audio WebSocket connection.
206
+ * Wraps the raw WebSocket for the audio.drachtio.org protocol.
207
+ *
208
+ * Receives: L16 PCM binary frames + JSON text events (dtmf, playDone, mark)
209
+ * Sends: binary PCM (streaming mode) or JSON commands (playAudio, killAudio, etc.)
210
+ */
211
+
212
+ /** Metadata sent by jambonz in the initial text frame. */
213
+ interface AudioStreamMetadata {
214
+ callSid: string;
215
+ from: string;
216
+ to: string;
217
+ callId: string;
218
+ sampleRate: number;
219
+ mixType: 'mono' | 'stereo' | 'mixed';
220
+ accountSid?: string;
221
+ applicationSid?: string;
222
+ direction?: string;
223
+ [key: string]: unknown;
224
+ }
225
+ interface PlayAudioOptions {
226
+ /** Audio encoding: 'raw' (headerless L16) or 'wav'/'wave'. Default: 'raw'. */
227
+ audioContentType?: string;
228
+ /** Sample rate for raw audio. Default: stream's sampleRate. */
229
+ sampleRate?: number;
230
+ /** Optional ID — returned in the playDone event. */
231
+ id?: string;
232
+ /** If true, queue after current playback. If false (default), interrupt current. */
233
+ queuePlay?: boolean;
234
+ }
235
+ interface AudioStreamEvents {
236
+ /** Raw L16 PCM audio data from the call. */
237
+ audio: (data: Buffer) => void;
238
+ /** DTMF event (only if passDtmf was enabled on the listen verb). */
239
+ dtmf: (evt: {
240
+ digit: string;
241
+ duration?: number;
242
+ }) => void;
243
+ /** Non-streaming playback completed. */
244
+ playDone: (evt: {
245
+ id?: string;
246
+ [key: string]: unknown;
247
+ }) => void;
248
+ /** Mark reached playout or was cleared. */
249
+ mark: (evt: {
250
+ name: string;
251
+ event: 'playout' | 'cleared';
252
+ }) => void;
253
+ /** Connection closed. */
254
+ close: (code: number, reason: string) => void;
255
+ /** Error on the underlying WebSocket. */
256
+ error: (err: Error) => void;
257
+ }
258
+ declare interface AudioStream {
259
+ on<E extends keyof AudioStreamEvents>(event: E, listener: AudioStreamEvents[E]): this;
260
+ emit<E extends keyof AudioStreamEvents>(event: E, ...args: Parameters<AudioStreamEvents[E]>): boolean;
261
+ }
262
+ declare class AudioStream extends EventEmitter {
263
+ readonly metadata: AudioStreamMetadata;
264
+ readonly callSid: string;
265
+ readonly sampleRate: number;
266
+ private ws;
267
+ private logger;
268
+ constructor(ws: WebSocket, metadata: AudioStreamMetadata, logger: Logger);
269
+ /** Send raw L16 PCM audio back to the caller (streaming mode). */
270
+ sendAudio(pcm: Buffer): void;
271
+ /** Send a playAudio command with base64-encoded audio (non-streaming mode). */
272
+ playAudio(audioContent: string, opts?: PlayAudioOptions): void;
273
+ /** Stop any currently playing audio and flush the buffer. */
274
+ killAudio(): void;
275
+ /** Tell jambonz to close the connection and end the listen verb. */
276
+ disconnect(): void;
277
+ /** Insert a synchronization marker. */
278
+ sendMark(name: string): void;
279
+ /** Clear all pending markers. */
280
+ clearMarks(): void;
281
+ /** Close the WebSocket connection. */
282
+ close(): void;
283
+ private onTextMessage;
284
+ private sendJson;
285
+ }
286
+
287
+ /**
288
+ * AudioClient — manages audio WebSocket connections on a specific path.
289
+ * Analogous to WsClient but for the audio.drachtio.org protocol.
290
+ *
291
+ * Waits for the initial JSON metadata text frame, then creates an AudioStream.
292
+ */
293
+
294
+ interface AudioClientEvents {
295
+ connection: (stream: AudioStream, req: IncomingMessage) => void;
296
+ error: (err: Error) => void;
297
+ }
298
+ declare interface AudioClient {
299
+ on<E extends keyof AudioClientEvents>(event: E, listener: AudioClientEvents[E]): this;
300
+ emit<E extends keyof AudioClientEvents>(event: E, ...args: Parameters<AudioClientEvents[E]>): boolean;
301
+ }
302
+ declare class AudioClient extends EventEmitter {
303
+ private logger;
304
+ readonly path: string;
305
+ constructor(logger: Logger, path: string);
306
+ /** Handle a new audio WebSocket connection. */
307
+ handle(ws: WebSocket, req: IncomingMessage): void;
308
+ }
309
+
142
310
  /**
143
311
  * createEndpoint — factory that attaches WebSocket handling to an HTTP server.
144
312
  * Returns a makeService function for registering path-based handlers.
313
+ * Supports both the jambonz control protocol (ws.jambonz.org) and the
314
+ * audio streaming protocol (audio.drachtio.org) on the same server.
145
315
  */
146
316
 
147
317
  interface EndpointOptions {
@@ -153,13 +323,37 @@ interface EndpointOptions {
153
323
  logger?: Logger;
154
324
  /** Middleware functions applied during upgrade. */
155
325
  middlewares?: Middleware[];
326
+ /** Application environment variables schema. When provided, the SDK
327
+ * auto-responds to HTTP OPTIONS requests with this schema so the
328
+ * jambonz portal can discover configurable parameters. */
329
+ envVars?: EnvVarSchema;
156
330
  }
157
331
  type Middleware = (req: http.IncomingMessage, res: http.ServerResponse, next: (err?: Error) => void) => void | Promise<void>;
158
332
  interface MakeService {
159
333
  (opts: {
160
334
  path: string;
161
335
  }): WsClient;
336
+ /** Register an audio WebSocket handler for listen/stream connections. */
337
+ audio: (opts: {
338
+ path: string;
339
+ }) => AudioClient;
162
340
  }
341
+ /**
342
+ * Create a jambonz WebSocket endpoint on an HTTP server.
343
+ *
344
+ * Returns a {@link MakeService} factory for registering path-based control
345
+ * and audio WebSocket handlers. Supports both the jambonz control protocol
346
+ * (`ws.jambonz.org`) and the audio streaming protocol (`audio.drachtio.org`).
347
+ *
348
+ * @example
349
+ * ```typescript
350
+ * const server = http.createServer();
351
+ * const makeService = createEndpoint({ server, port: 3000 });
352
+ *
353
+ * const svc = makeService({ path: '/' });
354
+ * const audioSvc = makeService.audio({ path: '/audio' });
355
+ * ```
356
+ */
163
357
  declare function createEndpoint(opts: EndpointOptions): MakeService;
164
358
 
165
359
  /**
@@ -176,4 +370,4 @@ declare class WsRouter {
176
370
  route(req: IncomingMessage): WsClient | undefined;
177
371
  }
178
372
 
179
- export { type EndpointOptions, type MakeService, type Middleware, Session, WsClient, type WsClientEvents, WsRouter, createEndpoint };
373
+ export { AudioClient, type AudioClientEvents, AudioStream, type AudioStreamEvents, type AudioStreamMetadata, type EndpointOptions, type MakeService, type Middleware, type PlayAudioOptions, Session, WsClient, type WsClientEvents, WsRouter, createEndpoint };