dvgateway-sdk 1.6.0 → 1.6.2

package/dist/client.d.ts

@@ -21,9 +21,10 @@
  */
 import { type AudioStreamHandle, type PipelineType } from './streams/audio-stream.js';
 import { PipelineBuilder } from './pipeline/builder.js';
+import { VoiceFlowBuilder } from './flow/builder.js';
 import { PipelineMetrics } from './observability/metrics.js';
 import { type SimulateOptions, type SimulatedCall } from './simulator/simulator.js';
-import type { DVGatewayOptions, CallSession, CallEvent, ChannelStateChangeEvent, TTSCompleteEvent, TranscriptResult, StreamDir, TtsAdapter, Unsubscribe, DTMFResult, PlayAudioResult, WarmTransferResult } from './types/index.js';
+import type { DVGatewayOptions, CallSession, CallEvent, ChannelStateChangeEvent, AudioPlaybackEvent, TTSCompleteEvent, TtsPlaybackEvent, TranscriptResult, StreamDir, TtsAdapter, Unsubscribe, DTMFResult, InjectTtsResult, PlayAudioResult, WarmTransferResult } from './types/index.js';
 export declare class DVGatewayClient {
     private readonly auth;
     private readonly wsPool;
@@ -131,6 +132,89 @@ export declare class DVGatewayClient {
         dir?: StreamDir;
         pipelineType?: PipelineType;
     }): AudioStreamHandle;
+    /**
+     * Attach audio streaming (ExternalMedia) to a flow-mode call mid-call.
+     *
+     * Only valid for calls that entered the gateway with the dialplan arg
+     * `Stasis(dvgateway, flow=true, ...)` — those calls land in a holding
+     * bridge with no ExternalMedia until this method is called. Idempotent —
+     * if audio is already attached the gateway returns the existing channel.
+     *
+     * Use `dir`:
+     *  - `'both'` (default) — full duplex, STT + TTS
+     *  - `'out'`           — gateway → caller only (TTS playback, no STT cost)
+     *  - `'in'`            — caller → gateway only (STT only)
+     *
+     * @returns The Asterisk ExternalMedia channel ID. Returned mainly for
+     *          observability — most callers will ignore it.
+     *
+     * @example
+     * ```typescript
+     * await gw.attachAudio(linkedId, 'out');
+     * await gw.say(linkedId, 'Welcome', tts);
+     * await gw.detachAudio(linkedId);
+     * ```
+     *
+     * @see {@link flow} for the high-level VoiceFlow builder that handles
+     * attach/detach automatically per stage.
+     */
+    attachAudio(linkedId: string, dir?: 'both' | 'in' | 'out'): Promise<string>;
+    /**
+     * Detach audio streaming from a flow-mode call. The original channel
+     * stays parked in its holding bridge so {@link attachAudio} can be
+     * called again later. Idempotent — no-op if audio is not attached.
+     */
+    detachAudio(linkedId: string): Promise<void>;
+    /**
+     * Query audio attach state for a flow-mode call.
+     *
+     * `flowMode` is `false` when the call did NOT enter with `flow=true`
+     * (or has already ended) — those calls have audio attached at
+     * StasisStart and cannot be detached.
+     */
+    getAudioStatus(linkedId: string): Promise<{
+        flowMode: boolean;
+        attached: boolean;
+        extMediaId: string;
+        bridgeId: string;
+    }>;
+    /**
+     * Create a fluent SDK voice flow — a stage graph that drives a call
+     * through IVR-like steps, attaching/detaching audio per stage.
+     *
+     * Only meaningful for calls that entered with dialplan arg
+     * `flow=true`. The flow runtime listens for `call:new` events and
+     * spawns a per-call execution that:
+     *  1. Enters the start stage (calls `attachAudio` if `audio !== 'none'`)
+     *  2. Runs the stage's `onEnter` (which can `say`, `playAudio`, `collectDtmf`)
+     *  3. Transitions on DTMF (`onDtmf` map) or explicit `ctx.transitionTo()`
+     *  4. Detaches audio between stages when modes differ
+     *  5. Ends on `call:ended` or when a stage calls `ctx.hangup()`
+     *
+     * @example IVR menu
+     * ```typescript
+     * gw.flow()
+     *   .stage('greet', {
+     *     audio: 'tts-only',
+     *     onEnter: async (ctx) => ctx.say('1번 상담, 9번 종료', tts),
+     *     onDtmf: { '1': 'chat', '9': 'bye' },
+     *   })
+     *   .stage('chat', {
+     *     audio: 'full',
+     *     onEnter: async (ctx) => ctx.runPipeline(myPipeline),
+     *   })
+     *   .stage('bye', {
+     *     audio: 'tts-only',
+     *     onEnter: async (ctx) => {
+     *       await ctx.say('감사합니다', tts);
+     *       await ctx.hangup();
+     *     },
+     *   })
+     *   .startStage('greet')
+     *   .start();
+     * ```
+     */
+    flow(): VoiceFlowBuilder;
     /**
      * Notify the gateway that AI processing has started (STT → LLM → TTS).
      * If comfort noise is enabled on the gateway (GW_COMFORT_NOISE_ENABLED=true),
@@ -180,17 +264,34 @@ export declare class DVGatewayClient {
      * Inject synthesized speech into an active call.
      * audioChunks should be 16kHz, 16-bit PCM (slin16) audio.
      *
+     * Returns an {@link InjectTtsResult} carrying the `injectId` (UUID) the
+     * gateway will surface on the corresponding `tts:playback` events. SDK
+     * 1.6.1+ generates the UUID client-side so callers can correlate events
+     * to *this* inject without an extra round-trip.
+     *
      * @example
      * ```typescript
-     * const ttsAdapter = new ElevenLabsAdapter({ apiKey: '...' });
-     * await gw.injectTts('abc123', ttsAdapter.synthesize('Hello!'));
+     * const r = await gw.injectTts(linkedId, ttsAdapter.synthesize('Hello!'));
+     * gw.onTtsPlayback((ev) => {
+     *   if (ev.injectId === r.injectId && ev.phase === 'complete') {
+     *     console.log('real RTP playback complete');
+     *   }
+     * });
      * ```
+     *
+     * @param injectId - Optional caller-supplied UUID; defaults to a fresh
+     *                   one. Override only for tests / multi-process correlation.
      */
-    injectTts(linkedId: string, audioChunks: AsyncIterable<Buffer>): Promise<void>;
+    injectTts(linkedId: string, audioChunks: AsyncIterable<Buffer>, injectId?: string): Promise<InjectTtsResult>;
     /**
      * Broadcast synthesized speech to all conference participants.
+     *
+     * Returns {@link InjectTtsResult} for parity with {@link injectTts}.
+     * Note: gateway 1.3.9.3 does not yet emit `tts:playback` for conference
+     * participant Players (only 1:1 calls), so the ID is forward-compat
+     * plumbing today.
      */
-    broadcastTts(confId: string, audioChunks: AsyncIterable<Buffer>): Promise<void>;
+    broadcastTts(confId: string, audioChunks: AsyncIterable<Buffer>, injectId?: string): Promise<InjectTtsResult>;
     /**
      * Convenience: synthesize text and inject it directly.
      * Requires a TtsAdapter instance.
@@ -210,7 +311,7 @@ export declare class DVGatewayClient {
      * await gw.say(linkedId, '안녕하세요', tts); // cache hit — no API call
      * ```
      */
-    say(linkedId: string, text: string, tts: TtsAdapter): Promise<void>;
+    say(linkedId: string, text: string, tts: TtsAdapter): Promise<InjectTtsResult>;
     /**
      * Broadcast synthesized speech to a conference.
      * Pass a CachedTtsAdapter for zero-cost repeated broadcasts.
@@ -220,7 +321,7 @@ export declare class DVGatewayClient {
      * await gw.broadcastSay(confId, '회의를 시작합니다.', cachedTts);
      * ```
      */
-    broadcastSay(confId: string, text: string, tts: TtsAdapter): Promise<void>;
+    broadcastSay(confId: string, text: string, tts: TtsAdapter): Promise<InjectTtsResult>;
     /**
      * Mute the gateway's STT audio pipeline for a call.
      *
@@ -637,6 +738,102 @@ export declare class DVGatewayClient {
      * @since SDK 1.5.3
      */
     onChannelState(handler: (event: ChannelStateChangeEvent) => void | Promise<void>): Unsubscribe;
+    /**
+     * Subscribe to `audio:playback` events — the canonical signal for
+     * {@link playAudio} lifecycle (start / complete / canceled / failed).
+     *
+     * **Primary use case — DTMF prompt audio with accurate timeout extension:**
+     * application code that plays an instructional prompt and then waits for
+     * DTMF input previously had to estimate prompt length with a hard-coded
+     * fallback (e.g. `baseTimeoutMs + 8000`). With this event the application
+     * can extend its timeout by the *actual* playback duration, dropping both
+     * unnecessary slack and the risk of the timer firing before the prompt
+     * finishes.
+     *
+     * @example
+     * ```typescript
+     * const result = await gw.playAudio({
+     *   linkedId,
+     *   url: promptUrl,
+     *   waitForCompletion: false,
+     * });
+     * const playbackId = result.playbackId;
+     *
+     * let actualMs = 0;
+     * const audioDone = new Promise<void>((resolve) => {
+     *   const unsub = gw.onAudioPlayback((ev) => {
+     *     if (ev.playbackId !== playbackId) return;
+     *     if (ev.phase === 'complete' || ev.phase === 'canceled' || ev.phase === 'failed') {
+     *       actualMs = ev.durationMs ?? 0;
+     *       unsub();
+     *       resolve();
+     *     }
+     *   });
+     * });
+     *
+     * try {
+     *   await Promise.race([audioDone, sleep(30_000)]);
+     *   const effectiveTimeout = baseTimeoutMs + actualMs + 500;
+     * } catch {
+     *   // fallback to conservative estimate
+     * }
+     * ```
+     *
+     * @see AudioPlaybackEvent for phase contract, `errorReason` vocabulary,
+     *      and full payload details.
+     *
+     * @since SDK 1.6.0 (gateway v1.3.9.2+ required)
+     */
+    onAudioPlayback(handler: (event: AudioPlaybackEvent) => void | Promise<void>): Unsubscribe;
+    /**
+     * Subscribe to `tts:playback` events — the canonical signal for
+     * {@link injectTts} lifecycle (start / complete / canceled / failed).
+     *
+     * Mirrors {@link onAudioPlayback} for the streaming-PCM injection path.
+     * Strictly more informative than the legacy {@link onTtsComplete}:
+     *
+     * - `onTtsComplete` fires for *every* terminal phase but exposes only
+     *   `linkedId` — no way to distinguish complete from canceled
+     *   (e.g. preempted by a new `injectTts`) or failed (e.g. `channel_lost`).
+     * - `onTtsPlayback` carries `injectId` (correlation across sequential
+     *   injects in the same call), `phase` (4-way), `durationMs`
+     *   (deterministic — gateway ticker is exactly 20ms paced), and
+     *   `errorReason` (cancel cause / error class).
+     *
+     * @example
+     * ```typescript
+     * // Chain TTS prompts and wait for the *real* end of each.
+     * const r1 = await gw.injectTts(linkedId, greetingAudio());
+     * const done = new Promise<void>((resolve) => {
+     *   const unsub = gw.onTtsPlayback((ev) => {
+     *     if (ev.injectId !== r1.injectId) return;
+     *     if (ev.phase === 'complete' || ev.phase === 'canceled' || ev.phase === 'failed') {
+     *       unsub();
+     *       resolve();
+     *     }
+     *   });
+     * });
+     * await done;
+     * const r2 = await gw.injectTts(linkedId, menuAudio()); // safe to start now
+     * ```
+     *
+     * **Pre-1.6.1 fallback** for SDK consumers — older SDKs / older gateways
+     * won't see `tts:playback`. Use a `hasattr`-style feature check if
+     * supporting both:
+     * ```typescript
+     * if ('onTtsPlayback' in gw) {
+     *   gw.onTtsPlayback(handler);
+     * } else {
+     *   gw.onTtsComplete((ev) => handler({ ...ev, phase: 'complete' } as any));
+     * }
+     * ```
+     *
+     * @see TtsPlaybackEvent for phase contract, `errorReason` vocabulary,
+     *      and full payload details.
+     *
+     * @since SDK 1.6.1 (gateway v1.3.9.3+ required)
+     */
+    onTtsPlayback(handler: (event: TtsPlaybackEvent) => void | Promise<void>): Unsubscribe;
     /** List all currently active call sessions */
     listSessions(): Promise<CallSession[]>;
     /** List active call sessions filtered by tenant ID */

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/client.js

@@ -28,6 +28,7 @@ import { TtsInjector } from './streams/tts-stream.js';
 import { SessionManager } from './session/manager.js';
 import { MinutesManager } from './minutes/manager.js';
 import { PipelineBuilder } from './pipeline/builder.js';
+import { VoiceFlowBuilder } from './flow/builder.js';
 import { PipelineMetrics } from './observability/metrics.js';
 import { createLogger } from './observability/logger.js';
 import { createSimulatedCall, } from './simulator/simulator.js';
@@ -156,6 +157,106 @@ export class DVGatewayClient {
     streamAudio(linkedId, opts = {}) {
         return createAudioStream(this.wsPool, linkedId, this.logger, opts);
     }
+    // ─── Voice-Flow On-Demand Audio (gateway flow=true mode) ──────────────
+    // @since SDK 1.6.2 (gateway v1.3.9.4+ required)
+    /**
+     * Attach audio streaming (ExternalMedia) to a flow-mode call mid-call.
+     *
+     * Only valid for calls that entered the gateway with the dialplan arg
+     * `Stasis(dvgateway, flow=true, ...)` — those calls land in a holding
+     * bridge with no ExternalMedia until this method is called. Idempotent —
+     * if audio is already attached the gateway returns the existing channel.
+     *
+     * Use `dir`:
+     *  - `'both'` (default) — full duplex, STT + TTS
+     *  - `'out'`           — gateway → caller only (TTS playback, no STT cost)
+     *  - `'in'`            — caller → gateway only (STT only)
+     *
+     * @returns The Asterisk ExternalMedia channel ID. Returned mainly for
+     *          observability — most callers will ignore it.
+     *
+     * @example
+     * ```typescript
+     * await gw.attachAudio(linkedId, 'out');
+     * await gw.say(linkedId, 'Welcome', tts);
+     * await gw.detachAudio(linkedId);
+     * ```
+     *
+     * @see {@link flow} for the high-level VoiceFlow builder that handles
+     * attach/detach automatically per stage.
+     */
+    async attachAudio(linkedId, dir = 'both') {
+        const res = await this.http.post(`/api/v1/audio/${encodeURIComponent(linkedId)}/attach`, { dir });
+        const data = (res.data ?? {});
+        const extMediaId = typeof data['extMediaId'] === 'string' ? data['extMediaId'] : '';
+        this.logger.debug({ linkedId, dir, extMediaId }, 'Audio attached');
+        return extMediaId;
+    }
+    /**
+     * Detach audio streaming from a flow-mode call. The original channel
+     * stays parked in its holding bridge so {@link attachAudio} can be
+     * called again later. Idempotent — no-op if audio is not attached.
+     */
+    async detachAudio(linkedId) {
+        await this.http.delete(`/api/v1/audio/${encodeURIComponent(linkedId)}/detach`);
+        this.logger.debug({ linkedId }, 'Audio detached');
+    }
+    /**
+     * Query audio attach state for a flow-mode call.
+     *
+     * `flowMode` is `false` when the call did NOT enter with `flow=true`
+     * (or has already ended) — those calls have audio attached at
+     * StasisStart and cannot be detached.
+     */
+    async getAudioStatus(linkedId) {
+        const res = await this.http.get(`/api/v1/audio/${encodeURIComponent(linkedId)}/status`);
+        const data = (res.data ?? {});
+        return {
+            flowMode: Boolean(data['flowMode']),
+            attached: Boolean(data['attached']),
+            extMediaId: typeof data['extMediaId'] === 'string' ? data['extMediaId'] : '',
+            bridgeId: typeof data['bridgeId'] === 'string' ? data['bridgeId'] : '',
+        };
+    }
+    /**
+     * Create a fluent SDK voice flow — a stage graph that drives a call
+     * through IVR-like steps, attaching/detaching audio per stage.
+     *
+     * Only meaningful for calls that entered with dialplan arg
+     * `flow=true`. The flow runtime listens for `call:new` events and
+     * spawns a per-call execution that:
+     *  1. Enters the start stage (calls `attachAudio` if `audio !== 'none'`)
+     *  2. Runs the stage's `onEnter` (which can `say`, `playAudio`, `collectDtmf`)
+     *  3. Transitions on DTMF (`onDtmf` map) or explicit `ctx.transitionTo()`
+     *  4. Detaches audio between stages when modes differ
+     *  5. Ends on `call:ended` or when a stage calls `ctx.hangup()`
+     *
+     * @example IVR menu
+     * ```typescript
+     * gw.flow()
+     *   .stage('greet', {
+     *     audio: 'tts-only',
+     *     onEnter: async (ctx) => ctx.say('1번 상담, 9번 종료', tts),
+     *     onDtmf: { '1': 'chat', '9': 'bye' },
+     *   })
+     *   .stage('chat', {
+     *     audio: 'full',
+     *     onEnter: async (ctx) => ctx.runPipeline(myPipeline),
+     *   })
+     *   .stage('bye', {
+     *     audio: 'tts-only',
+     *     onEnter: async (ctx) => {
+     *       await ctx.say('감사합니다', tts);
+     *       await ctx.hangup();
+     *     },
+     *   })
+     *   .startStage('greet')
+     *   .start();
+     * ```
+     */
+    flow() {
+        return new VoiceFlowBuilder(this, this.logger);
+    }
     // ─── Comfort Noise / Thinking Signals ─────────────────────────────────
     /**
      * Notify the gateway that AI processing has started (STT → LLM → TTS).
@@ -219,20 +320,37 @@ export class DVGatewayClient {
      * Inject synthesized speech into an active call.
      * audioChunks should be 16kHz, 16-bit PCM (slin16) audio.
      *
+     * Returns an {@link InjectTtsResult} carrying the `injectId` (UUID) the
+     * gateway will surface on the corresponding `tts:playback` events. SDK
+     * 1.6.1+ generates the UUID client-side so callers can correlate events
+     * to *this* inject without an extra round-trip.
+     *
      * @example
      * ```typescript
-     * const ttsAdapter = new ElevenLabsAdapter({ apiKey: '...' });
-     * await gw.injectTts('abc123', ttsAdapter.synthesize('Hello!'));
+     * const r = await gw.injectTts(linkedId, ttsAdapter.synthesize('Hello!'));
+     * gw.onTtsPlayback((ev) => {
+     *   if (ev.injectId === r.injectId && ev.phase === 'complete') {
+     *     console.log('real RTP playback complete');
+     *   }
+     * });
      * ```
+     *
+     * @param injectId - Optional caller-supplied UUID; defaults to a fresh
+     *                   one. Override only for tests / multi-process correlation.
      */
-    async injectTts(linkedId, audioChunks) {
-        return this.ttsInjector.injectStreaming(linkedId, audioChunks);
+    async injectTts(linkedId, audioChunks, injectId) {
+        return this.ttsInjector.injectStreaming(linkedId, audioChunks, injectId);
     }
     /**
      * Broadcast synthesized speech to all conference participants.
+     *
+     * Returns {@link InjectTtsResult} for parity with {@link injectTts}.
+     * Note: gateway 1.3.9.3 does not yet emit `tts:playback` for conference
+     * participant Players (only 1:1 calls), so the ID is forward-compat
+     * plumbing today.
      */
-    async broadcastTts(confId, audioChunks) {
-        return this.ttsInjector.broadcastToConference(confId, audioChunks);
+    async broadcastTts(confId, audioChunks, injectId) {
+        return this.ttsInjector.broadcastToConference(confId, audioChunks, injectId);
     }
     /**
      * Convenience: synthesize text and inject it directly.
@@ -557,9 +675,19 @@ export class DVGatewayClient {
         };
         const res = await this.http.post(`/api/v1/play/${encodeURIComponent(linkedId)}`, body);
         const data = (res.data ?? {});
+        // playbackId is surfaced on both 202 (async start) and 200 (sync result).
+        // Empty string when the gateway is older than 1.3.9.2 — older code
+        // treats it as "no correlation handle available".
+        const playbackIdRaw = data['playbackId'];
+        const playbackId = typeof playbackIdRaw === 'string' ? playbackIdRaw : '';
         if (!waitForCompletion) {
             // 202 — gateway accepted the request; playback proceeds async.
-            return { completed: false, interruptedByDtmf: null, durationMs: 0 };
+            return {
+                completed: false,
+                interruptedByDtmf: null,
+                durationMs: 0,
+                playbackId,
+            };
         }
         const rawDtmf = data['interruptedByDtmf'];
         const interruptedByDtmf = typeof rawDtmf === 'string' && rawDtmf !== '' ? rawDtmf : null;
@@ -569,6 +697,7 @@ export class DVGatewayClient {
             completed: Boolean(data['completed']),
             interruptedByDtmf,
             durationMs,
+            playbackId,
         };
     }
     /**
@@ -973,6 +1102,106 @@ export class DVGatewayClient {
     onChannelState(handler) {
         return this.callEvents.onType('channel:state', handler);
     }
+    /**
+     * Subscribe to `audio:playback` events — the canonical signal for
+     * {@link playAudio} lifecycle (start / complete / canceled / failed).
+     *
+     * **Primary use case — DTMF prompt audio with accurate timeout extension:**
+     * application code that plays an instructional prompt and then waits for
+     * DTMF input previously had to estimate prompt length with a hard-coded
+     * fallback (e.g. `baseTimeoutMs + 8000`). With this event the application
+     * can extend its timeout by the *actual* playback duration, dropping both
+     * unnecessary slack and the risk of the timer firing before the prompt
+     * finishes.
+     *
+     * @example
+     * ```typescript
+     * const result = await gw.playAudio({
+     *   linkedId,
+     *   url: promptUrl,
+     *   waitForCompletion: false,
+     * });
+     * const playbackId = result.playbackId;
+     *
+     * let actualMs = 0;
+     * const audioDone = new Promise<void>((resolve) => {
+     *   const unsub = gw.onAudioPlayback((ev) => {
+     *     if (ev.playbackId !== playbackId) return;
+     *     if (ev.phase === 'complete' || ev.phase === 'canceled' || ev.phase === 'failed') {
+     *       actualMs = ev.durationMs ?? 0;
+     *       unsub();
+     *       resolve();
+     *     }
+     *   });
+     * });
+     *
+     * try {
+     *   await Promise.race([audioDone, sleep(30_000)]);
+     *   const effectiveTimeout = baseTimeoutMs + actualMs + 500;
+     * } catch {
+     *   // fallback to conservative estimate
+     * }
+     * ```
+     *
+     * @see AudioPlaybackEvent for phase contract, `errorReason` vocabulary,
+     *      and full payload details.
+     *
+     * @since SDK 1.6.0 (gateway v1.3.9.2+ required)
+     */
+    onAudioPlayback(handler) {
+        return this.callEvents.onType('audio:playback', handler);
+    }
+    /**
+     * Subscribe to `tts:playback` events — the canonical signal for
+     * {@link injectTts} lifecycle (start / complete / canceled / failed).
+     *
+     * Mirrors {@link onAudioPlayback} for the streaming-PCM injection path.
+     * Strictly more informative than the legacy {@link onTtsComplete}:
+     *
+     * - `onTtsComplete` fires for *every* terminal phase but exposes only
+     *   `linkedId` — no way to distinguish complete from canceled
+     *   (e.g. preempted by a new `injectTts`) or failed (e.g. `channel_lost`).
+     * - `onTtsPlayback` carries `injectId` (correlation across sequential
+     *   injects in the same call), `phase` (4-way), `durationMs`
+     *   (deterministic — gateway ticker is exactly 20ms paced), and
+     *   `errorReason` (cancel cause / error class).
+     *
+     * @example
+     * ```typescript
+     * // Chain TTS prompts and wait for the *real* end of each.
+     * const r1 = await gw.injectTts(linkedId, greetingAudio());
+     * const done = new Promise<void>((resolve) => {
+     *   const unsub = gw.onTtsPlayback((ev) => {
+     *     if (ev.injectId !== r1.injectId) return;
+     *     if (ev.phase === 'complete' || ev.phase === 'canceled' || ev.phase === 'failed') {
+     *       unsub();
+     *       resolve();
+     *     }
+     *   });
+     * });
+     * await done;
+     * const r2 = await gw.injectTts(linkedId, menuAudio()); // safe to start now
+     * ```
+     *
+     * **Pre-1.6.1 fallback** for SDK consumers — older SDKs / older gateways
+     * won't see `tts:playback`. Use a `hasattr`-style feature check if
+     * supporting both:
+     * ```typescript
+     * if ('onTtsPlayback' in gw) {
+     *   gw.onTtsPlayback(handler);
+     * } else {
+     *   gw.onTtsComplete((ev) => handler({ ...ev, phase: 'complete' } as any));
+     * }
+     * ```
+     *
+     * @see TtsPlaybackEvent for phase contract, `errorReason` vocabulary,
+     *      and full payload details.
+     *
+     * @since SDK 1.6.1 (gateway v1.3.9.3+ required)
+     */
+    onTtsPlayback(handler) {
+        return this.callEvents.onType('tts:playback', handler);
+    }
     // ─── Session Management ─────────────────────────────────────────────────
     /** List all currently active call sessions */
     async listSessions() {