@siphon-project/control 0.1.1 → 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.
package/dist/index.d.cts CHANGED
@@ -164,11 +164,10 @@ declare function parseInboundFrame(text: string): ReplyFrame | EventFrame | null
164
164
  /**
165
165
  * The verbs the built-in SIP adapter accepts (`module = "sip"`).
166
166
  *
167
- * These are the exact wire tokens. The Phase-1 server implements
168
- * `answer`/`progress`/`reject`/`hangup`/`refer`/`set_header`/`get_header`;
169
- * the rest (`remove_header`, `accept_refer`, `reject_refer`, `play`, `dtmf`)
170
- * are accepted names the server answers `unsupported_verb` until it implements
171
- * them.
167
+ * These are the exact wire tokens. The media verbs
168
+ * (`play`/`stop`/`dtmf`/`hold`/`unhold`/`stream_start`/`stream_stop`) dispatch
169
+ * against the configured media backend; the WebSocket-tee pair is
170
+ * siphon-rtp-only, so a non-siphon-rtp backend answers them `unsupported_verb`.
172
171
  */
173
172
  declare const SipVerb: {
174
173
  readonly Answer: "answer";
@@ -176,20 +175,63 @@ declare const SipVerb: {
176
175
  readonly Reject: "reject";
177
176
  readonly Hangup: "hangup";
178
177
  readonly Refer: "refer";
178
+ readonly Route: "route";
179
179
  readonly SetHeader: "set_header";
180
180
  readonly GetHeader: "get_header";
181
181
  readonly RemoveHeader: "remove_header";
182
182
  readonly AcceptRefer: "accept_refer";
183
183
  readonly RejectRefer: "reject_refer";
184
184
  readonly Play: "play";
185
+ readonly Stop: "stop";
185
186
  readonly Dtmf: "dtmf";
187
+ readonly Hold: "hold";
188
+ readonly Unhold: "unhold";
189
+ readonly StreamStart: "stream_start";
190
+ readonly StreamStop: "stream_stop";
186
191
  };
187
192
  /** A value of {@link SipVerb}. */
188
193
  type SipVerbToken = (typeof SipVerb)[keyof typeof SipVerb];
189
194
  /** The well-known SIP-adapter event names (the ARI *Stasis* model). */
190
- type SipEventKind = "StasisStart" | "StasisEnd" | "ChannelStateChange" | "ChannelHangupRequest" | (string & {});
195
+ type SipEventKind = "StasisStart" | "StasisEnd" | "ChannelStateChange" | "ChannelHangupRequest" | "ChannelDtmfReceived" | "TransferRequested" | (string & {});
191
196
  /** Parse a wire event name; unknown names pass through verbatim (forward-compatible). */
192
197
  declare function sipEventKind(name: string): SipEventKind;
198
+ /**
199
+ * The `payload` of a `ChannelDtmfReceived` event — an in-band DTMF digit the
200
+ * media engine detected on a controlled call's leg. Cast a
201
+ * {@link import("./sip").CallEvent}'s `payload` to this when
202
+ * `kind === "ChannelDtmfReceived"`.
203
+ */
204
+ interface ChannelDtmfPayload {
205
+ /** The single detected digit (`0`–`9`, `*`, `#`, `A`–`D`). */
206
+ digit: string;
207
+ /** The tone duration in milliseconds. */
208
+ duration_ms: number;
209
+ /** The tone volume in dBm0 (negative). */
210
+ volume: number;
211
+ /** The From-tag of the leg the digit came from. */
212
+ from_tag: string;
213
+ }
214
+ /** The RFC 3891 `Replaces` triple embedded in a {@link TransferRequestedPayload}. */
215
+ interface TransferReplaces {
216
+ call_id: string;
217
+ from_tag: string;
218
+ to_tag: string;
219
+ early_only: boolean;
220
+ }
221
+ /**
222
+ * The `payload` of a `TransferRequested` event — an inbound REFER on a
223
+ * controlled call, handed to the app to accept / reject. Cast a
224
+ * {@link import("./sip").CallEvent}'s `payload` to this when
225
+ * `kind === "TransferRequested"`.
226
+ */
227
+ interface TransferRequestedPayload {
228
+ /** The Refer-To URI (the transfer target). */
229
+ refer_to: string;
230
+ /** The embedded `Replaces` triple for an attended transfer, if present. */
231
+ replaces?: TransferReplaces | null;
232
+ /** The From-tag of the referring party, if known. */
233
+ from_tag?: string | null;
234
+ }
193
235
 
194
236
  /** Small internal utilities shared by the client, server, and SIP facade. */
195
237
  /**
@@ -385,7 +427,10 @@ declare class ControlServer {
385
427
  }
386
428
 
387
429
  /** One event delivered to a call's stream (`ChannelStateChange`,
388
- * `ChannelHangupRequest`, `StasisEnd`, …). */
430
+ * `ChannelHangupRequest`, `ChannelDtmfReceived`, `TransferRequested`,
431
+ * `StasisEnd`, …). Cast `payload` to
432
+ * {@link import("./protocol").ChannelDtmfPayload} /
433
+ * {@link import("./protocol").TransferRequestedPayload} by `kind`. */
389
434
  interface CallEvent {
390
435
  /** The parsed event kind. */
391
436
  kind: SipEventKind;
@@ -414,6 +459,63 @@ interface AcceptReferOptions {
414
459
  nextHop?: string;
415
460
  mode?: "terminate" | "transparent";
416
461
  }
462
+ /** A {@link Call.route} target carrying per-target overrides. */
463
+ interface RouteTargetObject {
464
+ /** The B-leg request URI to dial. */
465
+ uri: string;
466
+ /** Route egress to this next hop instead of resolving `uri`. */
467
+ nextHop?: string;
468
+ /** Headers injected on this attempt's B-leg INVITE. */
469
+ headers?: Record<string, string>;
470
+ /** Per-target ring timeout in seconds. */
471
+ timeout?: number;
472
+ }
473
+ /**
474
+ * One entry in a {@link Call.route} target list: a bare URI string, or a
475
+ * {@link RouteTargetObject} with per-target overrides.
476
+ */
477
+ type RouteTarget = string | RouteTargetObject;
478
+ /**
479
+ * The audio source for {@link Call.play}: exactly one of a server-side file
480
+ * path, an rtpengine media-DB id, or an inline blob. A blob is base64-encoded on
481
+ * the wire (the control rail is JSON text).
482
+ */
483
+ type PlaySource = {
484
+ file: string;
485
+ } | {
486
+ dbId: number;
487
+ } | {
488
+ blob: Uint8Array;
489
+ };
490
+ /** Optional shaping for {@link Call.play}. */
491
+ interface PlayOptions {
492
+ /** Repeat the prompt this many times (0/undefined → play once). */
493
+ repeat?: number;
494
+ /** Start playback at this offset into the source, in milliseconds. */
495
+ startMs?: number;
496
+ /** Cap playback to this duration, in milliseconds. */
497
+ durationMs?: number;
498
+ /** Scope the prompt to one peer of an MPTY bridge (its To-tag). */
499
+ toTag?: string;
500
+ }
501
+ /** Optional shaping for {@link Call.dtmf}. */
502
+ interface DtmfOptions {
503
+ /** Per-digit tone duration, in milliseconds. */
504
+ durationMs?: number;
505
+ /** Tone volume in dBm0 (negative). */
506
+ volumeDbm0?: number;
507
+ /** Inter-digit pause, in milliseconds. */
508
+ pauseMs?: number;
509
+ /** Scope the tones to one peer of an MPTY bridge (its To-tag). */
510
+ toTag?: string;
511
+ }
512
+ /** Options for {@link Call.streamStart} (the WebSocket audio tee). */
513
+ interface StreamOptions {
514
+ /** Which leg(s) to tee — `"both"` (default), `"caller"`, or `"callee"`. */
515
+ direction?: "both" | "caller" | "callee";
516
+ /** `1` = mixed mono, `2` = caller/callee stereo (only with `"both"`). */
517
+ channels?: 1 | 2;
518
+ }
417
519
  /**
418
520
  * A handed-over SIP call. Cheap to hold (shares one connection + event stream).
419
521
  * Verb names mirror the in-process `call.*` scripting API.
@@ -469,38 +571,72 @@ declare class Call {
469
571
  /** Attended transfer — REFER with a `Replaces` triple (RFC 3891). */
470
572
  referReplaces(to: string, replaces: ReferReplaces): Promise<void>;
471
573
  /**
472
- * Accept an inbound REFER on this tracked call. **Not implemented server-side
473
- * in Phase 1** — resolves to a {@link ControlError} with `code ===
474
- * "unsupported_verb"` until the server adds it.
574
+ * Un-park this controlled call and dial the B-leg via siphon's LCR
575
+ * sequential-failover engine, returning control to siphon.
576
+ *
577
+ * `targets` is a non-empty list of carriers tried cheapest-first: each entry
578
+ * is a bare URI string or a {@link RouteTargetObject}
579
+ * (`{uri, nextHop?, headers?, timeout?}`). `strategy` defaults to
580
+ * `"sequential"` (v1 supports only sequential/single — anything else rejects
581
+ * with `code === "unsupported_verb"`). `headers` is applied to every
582
+ * attempt's B-leg INVITE.
583
+ *
584
+ * Resolves to the reply `result` (`{channel, state: "routing", targets}`). An
585
+ * empty / invalid `targets` list rejects with `code === "bad_request"`; a call
586
+ * that is already gone rejects with `code === "not_found"`.
587
+ */
588
+ route(targets: RouteTarget[], strategy?: string, headers?: Record<string, string>): Promise<unknown>;
589
+ /**
590
+ * Accept a *pending inbound* REFER (surfaced as a `TransferRequested` event)
591
+ * and run the transfer. `target` overrides the Refer-To URI, `nextHop` steers
592
+ * egress, and `mode` (`"terminate"` / `"transparent"`) overrides
593
+ * `b2bua.default_refer_mode`. No pending REFER (already decided, timed out, or
594
+ * the call is gone) rejects with `code === "not_found"`.
475
595
  */
476
596
  acceptRefer(options?: AcceptReferOptions): Promise<void>;
477
597
  /**
478
- * Reject an inbound REFER on this tracked call. **Not implemented server-side
479
- * in Phase 1** — see {@link Call.acceptRefer}.
598
+ * Reject a *pending inbound* REFER with a final non-2xx (default
599
+ * `603 Decline`). No pending REFER rejects with `code === "not_found"`.
480
600
  */
481
601
  rejectRefer(code: number, reason?: string): Promise<void>;
482
602
  /** Set a header on the stored A-leg INVITE. */
483
603
  setHeader(name: string, value: string): Promise<void>;
484
604
  /** Read a header from the stored A-leg INVITE (`null` when absent). */
485
605
  getHeader(name: string): Promise<string | null>;
486
- /**
487
- * Remove a header from the stored A-leg INVITE. **Not implemented server-side
488
- * in Phase 1** — resolves to a {@link ControlError} with `code ===
489
- * "unsupported_verb"` until the server adds it.
490
- */
606
+ /** Remove a header from the stored A-leg INVITE. */
491
607
  removeHeader(name: string): Promise<void>;
492
608
  /** Set a per-call variable (survives a reconnect via `resync`). */
493
609
  setVar(key: string, value: string): Promise<void>;
494
610
  /** Read a per-call variable (`null` when unset). */
495
611
  getVar(key: string): Promise<string | null>;
496
612
  /**
497
- * Play an announcement. **Not yet implemented server-side** — resolves to a
498
- * {@link ControlError} with `code === "unsupported_verb"` until the media
499
- * backend lands.
613
+ * Play an announcement on the A-leg media (fire-and-forget). `source` is a
614
+ * {@link PlaySource} (a blob is base64-encoded on the wire); `options` shapes
615
+ * playback. A call with no anchored media session rejects with
616
+ * `code === "not_found"`.
500
617
  */
618
+ play(source: PlaySource, options?: PlayOptions): Promise<void>;
619
+ /** Convenience for {@link Call.play} of a server-side file with default options. */
501
620
  playFile(file: string): Promise<void>;
502
- /** Send DTMF. **Not yet implemented server-side** — see {@link Call.playFile}. */
503
- dtmf(digits: string): Promise<void>;
621
+ /** Stop the announcement currently playing on the A-leg media. */
622
+ stop(): Promise<void>;
623
+ /**
624
+ * Inject DTMF digits toward the A-leg (fire-and-forget). `options` carries the
625
+ * optional `durationMs` / `volumeDbm0` / `pauseMs` / `toTag` shaping.
626
+ */
627
+ dtmf(digits: string, options?: DtmfOptions): Promise<void>;
628
+ /** Hold the A-leg media via silence. */
629
+ hold(): Promise<void>;
630
+ /** Resume the A-leg media after a {@link Call.hold}. */
631
+ unhold(): Promise<void>;
632
+ /**
633
+ * Attach a WebSocket audio tee — stream a copy of the call's decoded audio to
634
+ * `wsUri` while the call keeps relaying. siphon-rtp backend only: rtpengine /
635
+ * rtpproxy reject with `code === "unsupported_verb"` (`error.isUnsupportedVerb()`).
636
+ */
637
+ streamStart(wsUri: string, options?: StreamOptions): Promise<void>;
638
+ /** Detach the WebSocket audio tee (idempotent on siphon-rtp). */
639
+ streamStop(): Promise<void>;
504
640
  /** Send an arbitrary SIP-adapter verb + args and return the raw result. */
505
641
  command(verb: string, args?: unknown): Promise<unknown>;
506
642
  /**
@@ -585,4 +721,4 @@ declare class SipServer {
585
721
  close(): Promise<void>;
586
722
  }
587
723
 
588
- export { type AcceptReferOptions, Call, type CallEvent, type CallHandler, CallStream, type ChannelSnapshot, type ClientConfig, type ClientEvent, type CommandTransport, type ConnectionEventSink, ControlClient, ControlError, type ControlErrorCode, type ControlErrorKind, ControlServer, DESCRIBE, type EventFrame, type EventSink, EventStream, type FrameType, GET_VAR, HELLO, type HelloArgs, type HelloResult, MODULE_SIP, MODULE_SMPP, MODULE_SS7, PROTOCOL_VERSION, RESYNC, type ReferReplaces, type ReplyError, type ReplyFrame, type ReplyStatus, type ResponseOptions, type ResyncResult, SET_VAR, SUBPROTOCOL, type ServerConfig, SipClient, type SipEventKind, SipServer, SipVerb, type SipVerbToken, encodeCommand, parseInboundFrame, sipEventKind };
724
+ export { type AcceptReferOptions, Call, type CallEvent, type CallHandler, CallStream, type ChannelDtmfPayload, type ChannelSnapshot, type ClientConfig, type ClientEvent, type CommandTransport, type ConnectionEventSink, ControlClient, ControlError, type ControlErrorCode, type ControlErrorKind, ControlServer, DESCRIBE, type DtmfOptions, type EventFrame, type EventSink, EventStream, type FrameType, GET_VAR, HELLO, type HelloArgs, type HelloResult, MODULE_SIP, MODULE_SMPP, MODULE_SS7, PROTOCOL_VERSION, type PlayOptions, type PlaySource, RESYNC, type ReferReplaces, type ReplyError, type ReplyFrame, type ReplyStatus, type ResponseOptions, type ResyncResult, type RouteTarget, type RouteTargetObject, SET_VAR, SUBPROTOCOL, type ServerConfig, SipClient, type SipEventKind, SipServer, SipVerb, type SipVerbToken, type StreamOptions, type TransferReplaces, type TransferRequestedPayload, encodeCommand, parseInboundFrame, sipEventKind };
package/dist/index.d.ts CHANGED
@@ -164,11 +164,10 @@ declare function parseInboundFrame(text: string): ReplyFrame | EventFrame | null
164
164
  /**
165
165
  * The verbs the built-in SIP adapter accepts (`module = "sip"`).
166
166
  *
167
- * These are the exact wire tokens. The Phase-1 server implements
168
- * `answer`/`progress`/`reject`/`hangup`/`refer`/`set_header`/`get_header`;
169
- * the rest (`remove_header`, `accept_refer`, `reject_refer`, `play`, `dtmf`)
170
- * are accepted names the server answers `unsupported_verb` until it implements
171
- * them.
167
+ * These are the exact wire tokens. The media verbs
168
+ * (`play`/`stop`/`dtmf`/`hold`/`unhold`/`stream_start`/`stream_stop`) dispatch
169
+ * against the configured media backend; the WebSocket-tee pair is
170
+ * siphon-rtp-only, so a non-siphon-rtp backend answers them `unsupported_verb`.
172
171
  */
173
172
  declare const SipVerb: {
174
173
  readonly Answer: "answer";
@@ -176,20 +175,63 @@ declare const SipVerb: {
176
175
  readonly Reject: "reject";
177
176
  readonly Hangup: "hangup";
178
177
  readonly Refer: "refer";
178
+ readonly Route: "route";
179
179
  readonly SetHeader: "set_header";
180
180
  readonly GetHeader: "get_header";
181
181
  readonly RemoveHeader: "remove_header";
182
182
  readonly AcceptRefer: "accept_refer";
183
183
  readonly RejectRefer: "reject_refer";
184
184
  readonly Play: "play";
185
+ readonly Stop: "stop";
185
186
  readonly Dtmf: "dtmf";
187
+ readonly Hold: "hold";
188
+ readonly Unhold: "unhold";
189
+ readonly StreamStart: "stream_start";
190
+ readonly StreamStop: "stream_stop";
186
191
  };
187
192
  /** A value of {@link SipVerb}. */
188
193
  type SipVerbToken = (typeof SipVerb)[keyof typeof SipVerb];
189
194
  /** The well-known SIP-adapter event names (the ARI *Stasis* model). */
190
- type SipEventKind = "StasisStart" | "StasisEnd" | "ChannelStateChange" | "ChannelHangupRequest" | (string & {});
195
+ type SipEventKind = "StasisStart" | "StasisEnd" | "ChannelStateChange" | "ChannelHangupRequest" | "ChannelDtmfReceived" | "TransferRequested" | (string & {});
191
196
  /** Parse a wire event name; unknown names pass through verbatim (forward-compatible). */
192
197
  declare function sipEventKind(name: string): SipEventKind;
198
+ /**
199
+ * The `payload` of a `ChannelDtmfReceived` event — an in-band DTMF digit the
200
+ * media engine detected on a controlled call's leg. Cast a
201
+ * {@link import("./sip").CallEvent}'s `payload` to this when
202
+ * `kind === "ChannelDtmfReceived"`.
203
+ */
204
+ interface ChannelDtmfPayload {
205
+ /** The single detected digit (`0`–`9`, `*`, `#`, `A`–`D`). */
206
+ digit: string;
207
+ /** The tone duration in milliseconds. */
208
+ duration_ms: number;
209
+ /** The tone volume in dBm0 (negative). */
210
+ volume: number;
211
+ /** The From-tag of the leg the digit came from. */
212
+ from_tag: string;
213
+ }
214
+ /** The RFC 3891 `Replaces` triple embedded in a {@link TransferRequestedPayload}. */
215
+ interface TransferReplaces {
216
+ call_id: string;
217
+ from_tag: string;
218
+ to_tag: string;
219
+ early_only: boolean;
220
+ }
221
+ /**
222
+ * The `payload` of a `TransferRequested` event — an inbound REFER on a
223
+ * controlled call, handed to the app to accept / reject. Cast a
224
+ * {@link import("./sip").CallEvent}'s `payload` to this when
225
+ * `kind === "TransferRequested"`.
226
+ */
227
+ interface TransferRequestedPayload {
228
+ /** The Refer-To URI (the transfer target). */
229
+ refer_to: string;
230
+ /** The embedded `Replaces` triple for an attended transfer, if present. */
231
+ replaces?: TransferReplaces | null;
232
+ /** The From-tag of the referring party, if known. */
233
+ from_tag?: string | null;
234
+ }
193
235
 
194
236
  /** Small internal utilities shared by the client, server, and SIP facade. */
195
237
  /**
@@ -385,7 +427,10 @@ declare class ControlServer {
385
427
  }
386
428
 
387
429
  /** One event delivered to a call's stream (`ChannelStateChange`,
388
- * `ChannelHangupRequest`, `StasisEnd`, …). */
430
+ * `ChannelHangupRequest`, `ChannelDtmfReceived`, `TransferRequested`,
431
+ * `StasisEnd`, …). Cast `payload` to
432
+ * {@link import("./protocol").ChannelDtmfPayload} /
433
+ * {@link import("./protocol").TransferRequestedPayload} by `kind`. */
389
434
  interface CallEvent {
390
435
  /** The parsed event kind. */
391
436
  kind: SipEventKind;
@@ -414,6 +459,63 @@ interface AcceptReferOptions {
414
459
  nextHop?: string;
415
460
  mode?: "terminate" | "transparent";
416
461
  }
462
+ /** A {@link Call.route} target carrying per-target overrides. */
463
+ interface RouteTargetObject {
464
+ /** The B-leg request URI to dial. */
465
+ uri: string;
466
+ /** Route egress to this next hop instead of resolving `uri`. */
467
+ nextHop?: string;
468
+ /** Headers injected on this attempt's B-leg INVITE. */
469
+ headers?: Record<string, string>;
470
+ /** Per-target ring timeout in seconds. */
471
+ timeout?: number;
472
+ }
473
+ /**
474
+ * One entry in a {@link Call.route} target list: a bare URI string, or a
475
+ * {@link RouteTargetObject} with per-target overrides.
476
+ */
477
+ type RouteTarget = string | RouteTargetObject;
478
+ /**
479
+ * The audio source for {@link Call.play}: exactly one of a server-side file
480
+ * path, an rtpengine media-DB id, or an inline blob. A blob is base64-encoded on
481
+ * the wire (the control rail is JSON text).
482
+ */
483
+ type PlaySource = {
484
+ file: string;
485
+ } | {
486
+ dbId: number;
487
+ } | {
488
+ blob: Uint8Array;
489
+ };
490
+ /** Optional shaping for {@link Call.play}. */
491
+ interface PlayOptions {
492
+ /** Repeat the prompt this many times (0/undefined → play once). */
493
+ repeat?: number;
494
+ /** Start playback at this offset into the source, in milliseconds. */
495
+ startMs?: number;
496
+ /** Cap playback to this duration, in milliseconds. */
497
+ durationMs?: number;
498
+ /** Scope the prompt to one peer of an MPTY bridge (its To-tag). */
499
+ toTag?: string;
500
+ }
501
+ /** Optional shaping for {@link Call.dtmf}. */
502
+ interface DtmfOptions {
503
+ /** Per-digit tone duration, in milliseconds. */
504
+ durationMs?: number;
505
+ /** Tone volume in dBm0 (negative). */
506
+ volumeDbm0?: number;
507
+ /** Inter-digit pause, in milliseconds. */
508
+ pauseMs?: number;
509
+ /** Scope the tones to one peer of an MPTY bridge (its To-tag). */
510
+ toTag?: string;
511
+ }
512
+ /** Options for {@link Call.streamStart} (the WebSocket audio tee). */
513
+ interface StreamOptions {
514
+ /** Which leg(s) to tee — `"both"` (default), `"caller"`, or `"callee"`. */
515
+ direction?: "both" | "caller" | "callee";
516
+ /** `1` = mixed mono, `2` = caller/callee stereo (only with `"both"`). */
517
+ channels?: 1 | 2;
518
+ }
417
519
  /**
418
520
  * A handed-over SIP call. Cheap to hold (shares one connection + event stream).
419
521
  * Verb names mirror the in-process `call.*` scripting API.
@@ -469,38 +571,72 @@ declare class Call {
469
571
  /** Attended transfer — REFER with a `Replaces` triple (RFC 3891). */
470
572
  referReplaces(to: string, replaces: ReferReplaces): Promise<void>;
471
573
  /**
472
- * Accept an inbound REFER on this tracked call. **Not implemented server-side
473
- * in Phase 1** — resolves to a {@link ControlError} with `code ===
474
- * "unsupported_verb"` until the server adds it.
574
+ * Un-park this controlled call and dial the B-leg via siphon's LCR
575
+ * sequential-failover engine, returning control to siphon.
576
+ *
577
+ * `targets` is a non-empty list of carriers tried cheapest-first: each entry
578
+ * is a bare URI string or a {@link RouteTargetObject}
579
+ * (`{uri, nextHop?, headers?, timeout?}`). `strategy` defaults to
580
+ * `"sequential"` (v1 supports only sequential/single — anything else rejects
581
+ * with `code === "unsupported_verb"`). `headers` is applied to every
582
+ * attempt's B-leg INVITE.
583
+ *
584
+ * Resolves to the reply `result` (`{channel, state: "routing", targets}`). An
585
+ * empty / invalid `targets` list rejects with `code === "bad_request"`; a call
586
+ * that is already gone rejects with `code === "not_found"`.
587
+ */
588
+ route(targets: RouteTarget[], strategy?: string, headers?: Record<string, string>): Promise<unknown>;
589
+ /**
590
+ * Accept a *pending inbound* REFER (surfaced as a `TransferRequested` event)
591
+ * and run the transfer. `target` overrides the Refer-To URI, `nextHop` steers
592
+ * egress, and `mode` (`"terminate"` / `"transparent"`) overrides
593
+ * `b2bua.default_refer_mode`. No pending REFER (already decided, timed out, or
594
+ * the call is gone) rejects with `code === "not_found"`.
475
595
  */
476
596
  acceptRefer(options?: AcceptReferOptions): Promise<void>;
477
597
  /**
478
- * Reject an inbound REFER on this tracked call. **Not implemented server-side
479
- * in Phase 1** — see {@link Call.acceptRefer}.
598
+ * Reject a *pending inbound* REFER with a final non-2xx (default
599
+ * `603 Decline`). No pending REFER rejects with `code === "not_found"`.
480
600
  */
481
601
  rejectRefer(code: number, reason?: string): Promise<void>;
482
602
  /** Set a header on the stored A-leg INVITE. */
483
603
  setHeader(name: string, value: string): Promise<void>;
484
604
  /** Read a header from the stored A-leg INVITE (`null` when absent). */
485
605
  getHeader(name: string): Promise<string | null>;
486
- /**
487
- * Remove a header from the stored A-leg INVITE. **Not implemented server-side
488
- * in Phase 1** — resolves to a {@link ControlError} with `code ===
489
- * "unsupported_verb"` until the server adds it.
490
- */
606
+ /** Remove a header from the stored A-leg INVITE. */
491
607
  removeHeader(name: string): Promise<void>;
492
608
  /** Set a per-call variable (survives a reconnect via `resync`). */
493
609
  setVar(key: string, value: string): Promise<void>;
494
610
  /** Read a per-call variable (`null` when unset). */
495
611
  getVar(key: string): Promise<string | null>;
496
612
  /**
497
- * Play an announcement. **Not yet implemented server-side** — resolves to a
498
- * {@link ControlError} with `code === "unsupported_verb"` until the media
499
- * backend lands.
613
+ * Play an announcement on the A-leg media (fire-and-forget). `source` is a
614
+ * {@link PlaySource} (a blob is base64-encoded on the wire); `options` shapes
615
+ * playback. A call with no anchored media session rejects with
616
+ * `code === "not_found"`.
500
617
  */
618
+ play(source: PlaySource, options?: PlayOptions): Promise<void>;
619
+ /** Convenience for {@link Call.play} of a server-side file with default options. */
501
620
  playFile(file: string): Promise<void>;
502
- /** Send DTMF. **Not yet implemented server-side** — see {@link Call.playFile}. */
503
- dtmf(digits: string): Promise<void>;
621
+ /** Stop the announcement currently playing on the A-leg media. */
622
+ stop(): Promise<void>;
623
+ /**
624
+ * Inject DTMF digits toward the A-leg (fire-and-forget). `options` carries the
625
+ * optional `durationMs` / `volumeDbm0` / `pauseMs` / `toTag` shaping.
626
+ */
627
+ dtmf(digits: string, options?: DtmfOptions): Promise<void>;
628
+ /** Hold the A-leg media via silence. */
629
+ hold(): Promise<void>;
630
+ /** Resume the A-leg media after a {@link Call.hold}. */
631
+ unhold(): Promise<void>;
632
+ /**
633
+ * Attach a WebSocket audio tee — stream a copy of the call's decoded audio to
634
+ * `wsUri` while the call keeps relaying. siphon-rtp backend only: rtpengine /
635
+ * rtpproxy reject with `code === "unsupported_verb"` (`error.isUnsupportedVerb()`).
636
+ */
637
+ streamStart(wsUri: string, options?: StreamOptions): Promise<void>;
638
+ /** Detach the WebSocket audio tee (idempotent on siphon-rtp). */
639
+ streamStop(): Promise<void>;
504
640
  /** Send an arbitrary SIP-adapter verb + args and return the raw result. */
505
641
  command(verb: string, args?: unknown): Promise<unknown>;
506
642
  /**
@@ -585,4 +721,4 @@ declare class SipServer {
585
721
  close(): Promise<void>;
586
722
  }
587
723
 
588
- export { type AcceptReferOptions, Call, type CallEvent, type CallHandler, CallStream, type ChannelSnapshot, type ClientConfig, type ClientEvent, type CommandTransport, type ConnectionEventSink, ControlClient, ControlError, type ControlErrorCode, type ControlErrorKind, ControlServer, DESCRIBE, type EventFrame, type EventSink, EventStream, type FrameType, GET_VAR, HELLO, type HelloArgs, type HelloResult, MODULE_SIP, MODULE_SMPP, MODULE_SS7, PROTOCOL_VERSION, RESYNC, type ReferReplaces, type ReplyError, type ReplyFrame, type ReplyStatus, type ResponseOptions, type ResyncResult, SET_VAR, SUBPROTOCOL, type ServerConfig, SipClient, type SipEventKind, SipServer, SipVerb, type SipVerbToken, encodeCommand, parseInboundFrame, sipEventKind };
724
+ export { type AcceptReferOptions, Call, type CallEvent, type CallHandler, CallStream, type ChannelDtmfPayload, type ChannelSnapshot, type ClientConfig, type ClientEvent, type CommandTransport, type ConnectionEventSink, ControlClient, ControlError, type ControlErrorCode, type ControlErrorKind, ControlServer, DESCRIBE, type DtmfOptions, type EventFrame, type EventSink, EventStream, type FrameType, GET_VAR, HELLO, type HelloArgs, type HelloResult, MODULE_SIP, MODULE_SMPP, MODULE_SS7, PROTOCOL_VERSION, type PlayOptions, type PlaySource, RESYNC, type ReferReplaces, type ReplyError, type ReplyFrame, type ReplyStatus, type ResponseOptions, type ResyncResult, type RouteTarget, type RouteTargetObject, SET_VAR, SUBPROTOCOL, type ServerConfig, SipClient, type SipEventKind, SipServer, SipVerb, type SipVerbToken, type StreamOptions, type TransferReplaces, type TransferRequestedPayload, encodeCommand, parseInboundFrame, sipEventKind };