@siphon-project/control 0.4.0 → 0.6.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/dist/index.d.cts CHANGED
@@ -180,6 +180,19 @@ declare const SipVerb: {
180
180
  readonly Progress: "progress";
181
181
  readonly Reject: "reject";
182
182
  readonly Hangup: "hangup";
183
+ /**
184
+ * Abandon an **unanswered** call with nothing on the wire: no final response,
185
+ * no CANCEL, and the call released so the stack stops tracking it.
186
+ *
187
+ * The third way out of a parked call, and the only silent one. `reject` and an
188
+ * unanswered `hangup` both answer, and on a publicly reachable SIP port that
189
+ * answer is the prize: a `404` to an INVITE for a number nobody claims
190
+ * confirms the number to an enumeration sweep, where silence leaves it unable
191
+ * to tell a missing extension from a filtered one. Refused
192
+ * (`invalid_state`) on an answered call, whose dialog is owed a BYE
193
+ * (RFC 3261 §15) — that is {@link SipVerb.Hangup}'s job.
194
+ */
195
+ readonly Drop: "drop";
183
196
  readonly Refer: "refer";
184
197
  readonly Route: "route";
185
198
  /**
@@ -210,7 +223,7 @@ declare const SipVerb: {
210
223
  /** A value of {@link SipVerb}. */
211
224
  type SipVerbToken = (typeof SipVerb)[keyof typeof SipVerb];
212
225
  /** The well-known SIP-adapter event names (the ARI *Stasis* model). */
213
- type SipEventKind = "StasisStart" | "StasisEnd" | "ChannelStateChange" | "ChannelHangupRequest" | "ChannelDtmfReceived" | "PlayStarted" | "TransferRequested" | "TransferProgress" | "TransferCompleted" | "TransferFailed" | "ChannelBridged" | "BridgeFailed" | "ChannelUnbridged" | "PeerReplaced" | "ReplaceFailed" | "PlayFinished" | "WsTeeStarted" | "WsTeeEnded" | "WsBridgeStarted" | "WsBridgeEnded" | (string & {});
226
+ type SipEventKind = "StasisStart" | "StasisEnd" | "ChannelStateChange" | "ChannelHangupRequest" | "ChannelDtmfReceived" | "PlayStarted" | "TransferRequested" | "TransferProgress" | "TransferCompleted" | "TransferFailed" | "ChannelBridged" | "BridgeFailed" | "ChannelUnbridged" | "PeerReplaced" | "ReplaceFailed" | "PlayFinished" | "WsTeeStarted" | "WsTeeEnded" | "WsBridgeStarted" | "WsBridgeEnded" | "MediaSummary" | "MediaStarted" | "DialBranch" | "DialBranchFailed" | "DialAnswered" | "DialFailed" | "DialogStateChanged" | (string & {});
214
227
  /** Parse a wire event name; unknown names pass through verbatim (forward-compatible). */
215
228
  declare function sipEventKind(name: string): SipEventKind;
216
229
  /**
@@ -249,6 +262,11 @@ interface PlayStartedPayload {
249
262
  play_id?: number | null;
250
263
  /** The playback's length in ms, when the engine knew it at accept time. */
251
264
  duration_ms?: number | null;
265
+ /**
266
+ * Who started it, when siphon did rather than a `play`: `"ringback"` for the
267
+ * ringback of a `dial {on_answer: "bridge"}`. Absent for the app's own.
268
+ */
269
+ origin?: string;
252
270
  }
253
271
  /** The RFC 3891 `Replaces` triple embedded in a {@link TransferRequestedPayload}. */
254
272
  interface TransferReplaces {
@@ -418,6 +436,84 @@ interface ChannelUnbridgedPayload {
418
436
  /** The reason the `unbridge` carried (default `"unbridged"`). */
419
437
  reason: string;
420
438
  }
439
+ /**
440
+ * The `payload` of a `DialBranch` event — a B-leg a `dial` just created, its
441
+ * INVITE about to go out. Every fork branch, and each attempt of a sequential
442
+ * hunt when the hunt places it.
443
+ *
444
+ * Each branch is its own SIP dialog, on a Call-ID the server generated, so this
445
+ * is what ties it to the channel. The pair follows
446
+ * {@link ChannelBridgedPayload}'s `peer_call_id` / `peer_sip_call_id`; the
447
+ * frame's own `sip_call_id` stays the caller's.
448
+ */
449
+ interface DialBranchPayload {
450
+ /** The server's id for the B-leg, stable across a 401/407 or 422 retry of it. */
451
+ leg_id: string;
452
+ /** The SIP `Call-ID` the branch's INVITE carries — the CDR / HEP join key for this leg. */
453
+ leg_sip_call_id: string;
454
+ /** The target the branch was dialled at. */
455
+ target: string;
456
+ /**
457
+ * The registered AoR the branch was dialled for, when the target was one of
458
+ * the contacts an `{aor}` target resolved to. Absent for a raw URI, and from a
459
+ * server that predates it. Answers "which phone rang / picked up".
460
+ */
461
+ aor?: string;
462
+ }
463
+ /**
464
+ * How a `dial` branch ended without answering: `rejected` (the far end's final
465
+ * non-2xx), `timeout` (`408`, it rang out), `cancelled` (`487`, the server
466
+ * CANCELled it: another branch answered, a 6xx ended the fork, or the caller
467
+ * hung up; on a bridge dial also a phone released once another was bridged),
468
+ * `unsent` (`503`, the INVITE never reached the transport) or `bridge_failed`
469
+ * (a bridge dial's phone answered and its bridge to the caller failed). Unknown
470
+ * tokens pass through verbatim (forward-compatible).
471
+ */
472
+ type DialBranchCause = "rejected" | "timeout" | "cancelled" | "unsent" | "bridge_failed" | (string & {});
473
+ /**
474
+ * A `dial` branch and how it ended — the `payload` of a `DialBranchFailed`
475
+ * event, and each entry of {@link DialFailedPayload.branches}.
476
+ */
477
+ interface DialBranchOutcome extends DialBranchPayload {
478
+ /** The status it ended on. */
479
+ code: number;
480
+ /** The reason phrase that goes with `code`. */
481
+ reason: string;
482
+ /** Why it ended. */
483
+ cause: DialBranchCause;
484
+ }
485
+ /** The `payload` of a `DialAnswered` event — the branch that answered the `dial`. */
486
+ interface DialAnsweredPayload extends DialBranchPayload {
487
+ /** The 2xx it answered with. */
488
+ code: number;
489
+ /**
490
+ * On a `dial {on_answer: "bridge"}`, the channel siphon minted for the
491
+ * bridged phone, registered to this app and connection with the caller's
492
+ * `on_lost` policy; the phone's own events follow on it. `null` when that
493
+ * channel has no live owner; absent on a connecting dial.
494
+ */
495
+ channel?: string | null;
496
+ }
497
+ /**
498
+ * The `payload` of a `DialFailed` event — nobody answered the `dial`, and the
499
+ * caller is still ringing and still owned.
500
+ */
501
+ interface DialFailedPayload {
502
+ /** The status the dial ended on. */
503
+ code: number;
504
+ /** The reason phrase that goes with `code`. */
505
+ reason: string;
506
+ /** Whether it ended at the ring timeout. */
507
+ timed_out: boolean;
508
+ /**
509
+ * How a `dial {on_answer: "bridge"}` ended: `rejected`, `ring timeout`,
510
+ * `unsent`, `bridge_failed`, or `caller_hangup` when the caller went away
511
+ * while the phones rang. Absent on a connecting dial.
512
+ */
513
+ cause?: string;
514
+ /** Every branch the dial rang, each with its outcome. Absent from a server that predates branch reporting. */
515
+ branches?: DialBranchOutcome[];
516
+ }
421
517
  /**
422
518
  * The `payload` of a `PlayFinished` event — a playback ended.
423
519
  *
@@ -469,11 +565,81 @@ interface WsTeeEndedPayload {
469
565
  stream_id: string;
470
566
  /** `detached`, `server_closed`, `server_stopped`, `call_ended` or `transport_error`. */
471
567
  reason: string;
472
- /** `detached` is the only orderly end; anything else stopped the audio mid-call. */
568
+ /** `detached` and `call_ended` are the orderly ends; anything else stopped the audio mid-call. */
473
569
  unexpected: boolean;
474
570
  frames_sent?: number | null;
475
571
  frames_dropped?: number | null;
476
572
  }
573
+ /**
574
+ * The `payload` of a `MediaSummary` event: the media engine's summary of a
575
+ * media session it ended on this channel. On an ordinary hang-up it arrives
576
+ * **after** `StasisEnd`, within 30 s, under the channel id the call had; it is
577
+ * the only event that can follow `StasisEnd`, so accept it for a channel that
578
+ * already ended. A bridged pair's session carries both legs: its summary goes
579
+ * to both channels, once each.
580
+ */
581
+ interface MediaSummaryPayload {
582
+ /** `delete` or `media_timeout`. */
583
+ reason: string;
584
+ duration_ms: number;
585
+ /** One entry per party, matched on `tag`. */
586
+ legs: MediaLegSummary[];
587
+ }
588
+ /**
589
+ * One party's figures in a {@link MediaSummaryPayload}. A quality field the
590
+ * engine did not measure is absent, which is not the same as perfect.
591
+ */
592
+ interface MediaLegSummary {
593
+ tag: string;
594
+ codec?: string;
595
+ packets_in: number;
596
+ bytes_in: number;
597
+ packets_out: number;
598
+ bytes_out: number;
599
+ /** Dropped on the engine's side of the leg, not network loss. */
600
+ packets_dropped: number;
601
+ ssrc?: number;
602
+ packets_lost?: number;
603
+ loss_percent?: number;
604
+ jitter_ms?: number;
605
+ rtt_ms?: number;
606
+ mos_average?: number;
607
+ mos_min?: number;
608
+ mos_max?: number;
609
+ /** `full` or `loss+jitter`. */
610
+ mos_basis?: string;
611
+ text?: Record<string, number>;
612
+ local_address?: string;
613
+ remote_address?: string;
614
+ egress_ssrc?: number;
615
+ payload_type?: number;
616
+ /**
617
+ * When this party's first packet reached the engine, as Unix milliseconds.
618
+ * Absent for a leg that never carried media.
619
+ */
620
+ media_started_at_unix_ms?: number;
621
+ }
622
+ /**
623
+ * The `payload` of a `MediaStarted` event: the first packet on one of the
624
+ * channel's media legs reached the media engine. Once per leg, not again on a
625
+ * re-latch or re-INVITE; on a bridged pair each leg's report goes to that
626
+ * leg's channel only.
627
+ */
628
+ interface MediaStartedPayload {
629
+ /**
630
+ * `near` (facing the offerer, `from_tag`) or `far` (facing the answerer,
631
+ * `to_tag`). The engine leg, not a party.
632
+ */
633
+ leg: "near" | "far";
634
+ from_tag: string;
635
+ to_tag?: string;
636
+ /** Where the first packet came from (`ip:port`), when latched. */
637
+ source?: string;
638
+ /** The address the SDP signalled for this leg (`ip:port`). */
639
+ signalled?: string;
640
+ /** `source` differs from `signalled`: a NAT. Absent unless both are known. */
641
+ nat_rewritten?: boolean;
642
+ }
477
643
  /**
478
644
  * The `payload` of a `WsBridgeStarted` event — a WebSocket **takeover** bridge
479
645
  * began. Unlike a tee this *replaced* the call's audio path: the WebSocket
@@ -492,7 +658,8 @@ interface WsBridgeStartedPayload {
492
658
  * followed by a fresh started.
493
659
  *
494
660
  * `unexpected` matters more here than on a tee: a bridge *is* the call's media
495
- * path, so anything but `detached` leaves both parties up and hearing nothing.
661
+ * path, so anything but `detached` or `call_ended` leaves both parties up and
662
+ * hearing nothing.
496
663
  */
497
664
  interface WsBridgeEndedPayload {
498
665
  from_tag: string;
@@ -507,6 +674,56 @@ interface WsBridgeEndedPayload {
507
674
  * is not one of them — it ends a bridge that already formed.
508
675
  */
509
676
  declare function isBridgeFinal(name: string): boolean;
677
+ /**
678
+ * An RFC 4235 dialog state — the `state` of a {@link DialogStateChangedPayload}:
679
+ * `trying` (INVITE sent or received, nothing answered), `proceeding` (an
680
+ * untagged provisional), `early` (a tagged provisional: ringing), `confirmed`
681
+ * (a 2xx: in a call) or `terminated`. Unknown tokens pass through verbatim.
682
+ */
683
+ type DialogState = "trying" | "proceeding" | "early" | "confirmed" | "terminated" | (string & {});
684
+ /**
685
+ * Which end of the dialog the AoR is: `initiator` (the phone placed the call)
686
+ * or `recipient` (the phone is being called).
687
+ */
688
+ type DialogDirection = "initiator" | "recipient" | (string & {});
689
+ /** The party a dialog is with, as dialog-info renders `<remote><identity>`. */
690
+ interface DialogIdentity {
691
+ /** The other party's URI, as presented on the phone's leg. */
692
+ uri: string;
693
+ /** Its display name, or `null` when the header carried none. */
694
+ display_name: string | null;
695
+ }
696
+ /**
697
+ * The `payload` of a `DialogStateChanged` event — application-level, behind
698
+ * `control.apps[].events: [dialog]`, so its frame has no channel. One dialog of
699
+ * a registered AoR moved to a new RFC 4235 state, as the server observed it on
700
+ * the wire; everything is from the AoR's point of view. Each dialog reports its
701
+ * states in order and `terminated` exactly once.
702
+ */
703
+ interface DialogStateChangedPayload {
704
+ /** The registered AoR (its canonical key) the dialog belongs to. */
705
+ aor: string;
706
+ state: DialogState;
707
+ direction: DialogDirection;
708
+ /**
709
+ * The server's id for the phone's leg — stable and unique, usable as the
710
+ * dialog-info `id`. For a `dial` branch it is the `leg_id` of its `DialBranch`.
711
+ */
712
+ leg_id: string;
713
+ /** The SIP Call-ID of the phone's own dialog. */
714
+ call_id: string;
715
+ /** The phone's tag, or `null` until known. */
716
+ local_tag: string | null;
717
+ /** The other end's tag, or `null` until known. */
718
+ remote_tag: string | null;
719
+ remote_identity: DialogIdentity;
720
+ }
721
+ /**
722
+ * Whether an event name ends a `dial`. Exactly one `DialAnswered` or
723
+ * `DialFailed` arrives per dial, so this is the signal to stop waiting;
724
+ * `DialBranch` / `DialBranchFailed` are per-branch and may be many.
725
+ */
726
+ declare function isDialFinal(name: string): boolean;
510
727
 
511
728
  /** Small internal utilities shared by the client, server, and SIP facade. */
512
729
  /**
@@ -720,6 +937,23 @@ interface CallEvent {
720
937
  /** The raw frame (for fields not surfaced above). */
721
938
  frame: EventFrame;
722
939
  }
940
+ /**
941
+ * An application-level event: pushed to every connection of an app that opted
942
+ * into its class (`control.apps[].events`), about the deployment rather than a
943
+ * channel — `RegistrationChanged`, `DialogStateChanged` (cast `payload` to
944
+ * {@link import("./protocol").DialogStateChangedPayload}). Its frame has no
945
+ * channel, so it reaches {@link SipClient.onAppEvent}, never a call.
946
+ */
947
+ interface AppEvent {
948
+ /** The parsed event kind. */
949
+ kind: SipEventKind;
950
+ /** The event-specific payload. */
951
+ payload: unknown;
952
+ /** The raw frame. */
953
+ frame: EventFrame;
954
+ }
955
+ /** A handler for application-level events. */
956
+ type AppEventHandler = (event: AppEvent) => void;
723
957
  /** Options for a UAS provisional / final response (`answer` / `progress`). */
724
958
  interface ResponseOptions {
725
959
  code?: number;
@@ -737,7 +971,9 @@ interface AnchoredAnswerOptions {
737
971
  profile?: string;
738
972
  /**
739
973
  * Per-call WebSocket bridge URI, overriding the profile's own. Supports
740
- * `{call_id}` / `{from_tag}` / `{from_user}` / `{to_user}` templating.
974
+ * `{call_id}` / `{from_tag}` / `{from_user}` / `{to_user}` templating;
975
+ * `{call_id}` is the call's SIP Call-ID (`sipCallId`), not the control-plane
976
+ * `callId`.
741
977
  */
742
978
  wsUri?: string;
743
979
  }
@@ -896,7 +1132,53 @@ interface Originated {
896
1132
  /** The SIP Call-ID on the wire, for joining CDR / HEP. */
897
1133
  sipCallId?: string;
898
1134
  }
1135
+ /**
1136
+ * How {@link SipClient.originateAor} rings the phones registered at an AoR.
1137
+ * Anything left out takes the server's own default.
1138
+ */
1139
+ interface OriginateRing {
1140
+ /**
1141
+ * `"parallel"` (the server's default) rings every phone at once;
1142
+ * `"sequential"` rings them one at a time in registration q-value order,
1143
+ * moving on when one declines or rings out its own `timeout`.
1144
+ */
1145
+ strategy?: "parallel" | "sequential";
1146
+ /**
1147
+ * Seconds the whole group may ring before every phone still ringing is
1148
+ * CANCELled. Server-side it defaults to `timeout` for a parallel group and to
1149
+ * `timeout` times the number of phones for a sequential one; `0` is none.
1150
+ */
1151
+ totalTimeout?: number;
1152
+ }
1153
+ /**
1154
+ * What the server answers an accepted `originate {aor}` with: every registered
1155
+ * phone is being rung (`state: "calling"`) and none has answered yet.
1156
+ */
1157
+ interface OriginatedGroup {
1158
+ /** The caller-supplied channel id the group is addressed by. */
1159
+ channel: string;
1160
+ /**
1161
+ * siphon's id for the group of phones. Until one answers, the channel's
1162
+ * events carry it as their `call_id` / `sip_call_id`, since no single dialog
1163
+ * is the call yet; from `DialAnswered` on they carry the winning leg's own.
1164
+ */
1165
+ groupId?: string;
1166
+ /** The AoR as it is registered (its canonical key), which every leg's To carries. */
1167
+ aor?: string;
1168
+ /** The strategy in force (the server's default when none was asked for). */
1169
+ strategy?: string;
1170
+ /** The group's deadline in force, in seconds (`0` = none). */
1171
+ totalTimeout?: number;
1172
+ /** One entry per phone INVITE built so far (a sequential group adds more as it hunts). */
1173
+ branches: DialBranchPayload[];
1174
+ }
899
1175
  declare function originateArgs(channel: string, to: string, media: OriginateMedia, options?: OriginateOptions): Record<string, unknown>;
1176
+ /**
1177
+ * The args of an `originate {aor}`. `to` is never sent beside `aor` — the
1178
+ * server refuses both — and the ring shaping goes only here, since beside a
1179
+ * single `to` the server refuses it too.
1180
+ */
1181
+ declare function originateAorArgs(channel: string, aor: string, media: OriginateMedia, options?: OriginateOptions, ring?: OriginateRing): Record<string, unknown>;
900
1182
  /**
901
1183
  * One {@link Call.dial} target: a URI dialed as written, or an AoR forked to
902
1184
  * every contact registered against it.
@@ -938,6 +1220,70 @@ interface DialOptions {
938
1220
  timeout?: number;
939
1221
  /** Headers injected on every branch's INVITE, under each target's own. */
940
1222
  headers?: Record<string, string>;
1223
+ /**
1224
+ * A configured media profile to anchor both legs through, so the caller and
1225
+ * the phones never exchange media directly.
1226
+ *
1227
+ * What a carrier-delivered call to a ring group needs: the carrier hands over
1228
+ * plain RTP at a routable address and every phone answers from an address on
1229
+ * its own LAN, so without the relay in the middle the two ends cannot reach
1230
+ * each other. Left out, the caller's own SDP passes through.
1231
+ */
1232
+ profile?: string;
1233
+ /**
1234
+ * The calling identity to present — the From URI (RFC 3261 §8.1.1.3).
1235
+ *
1236
+ * Without it a B-leg presents the caller's own From, which on a call out to a
1237
+ * trunk is the internal extension. A carrier that looks its account up by the
1238
+ * From user does not recognise that, so it challenges the INVITE and keeps
1239
+ * challenging however correct the digest is. A `headers` entry cannot do
1240
+ * this: From is framework-managed on a B-leg and is rewritten after the fact.
1241
+ */
1242
+ from?: string;
1243
+ /**
1244
+ * The From display name. Naming a `from` without one drops the caller's
1245
+ * rather than presenting it beside a number that replaced it.
1246
+ */
1247
+ fromDisplay?: string;
1248
+ /**
1249
+ * `P-Asserted-Identity` for a trusted next hop (RFC 3325 §9.1). Reaches the
1250
+ * wire after the header policy, so a preset that strips `P-*` at a trust
1251
+ * boundary cannot silently drop it.
1252
+ */
1253
+ pAssertedIdentity?: string;
1254
+ /**
1255
+ * Whether the calling identity may be presented (RFC 3323 §4.1 / TS 24.607).
1256
+ * `"restricted"` anonymises From and asserts `Privacy: id`, keeping the real
1257
+ * identity in `pAssertedIdentity` for the trusted next hop.
1258
+ */
1259
+ privacy?: "allowed" | "restricted";
1260
+ /**
1261
+ * What happens when a phone picks up (`"connect"` server-side when unset).
1262
+ *
1263
+ * `"connect"` answers the caller with the phone's answer, so it is refused on
1264
+ * a caller that is already answered. `"bridge"` is the end of an IVR flow: it
1265
+ * is accepted **only** on an answered caller with an anchored media session
1266
+ * (`answerAnchored`), rings each phone as a call siphon places itself, and
1267
+ * bridges the first one to answer to the caller as {@link Call.bridge} would,
1268
+ * with `onPeerHangup: "hangup"`. Its outcome arrives as `DialAnswered` (with
1269
+ * the `channel` siphon minted for the phone) then `ChannelBridged`, or as
1270
+ * `DialFailed` with the caller still answered and owned.
1271
+ */
1272
+ onAnswer?: "connect" | "bridge";
1273
+ /**
1274
+ * What the caller hears while the phones ring on an `onAnswer: "bridge"`
1275
+ * dial: a tone preset or cadence (`"ringback_eu"`, `"425/1000,0/4000*inf"`,
1276
+ * anything `play {tone}` takes), `true` for the default, or `false` for none
1277
+ * (the caller hears whatever the app left playing). `"ringback_eu"`
1278
+ * server-side when unset. It starts on the first 180-183 from any phone, never
1279
+ * talks over a prompt the app started, and its `PlayStarted` / `PlayFinished`
1280
+ * carry `origin: "ringback"`.
1281
+ *
1282
+ * Bridge-only: naming it without `onAnswer: "bridge"` throws a `TypeError`
1283
+ * before anything is sent, since the server refuses it on a connecting dial
1284
+ * (`bad_request`, `requires_bridge`).
1285
+ */
1286
+ ringback?: string | boolean;
941
1287
  }
942
1288
  /**
943
1289
  * What the server answers an accepted `dial` with: the INVITEs are on the wire
@@ -955,6 +1301,19 @@ interface Dialing {
955
1301
  strategy?: string;
956
1302
  /** The ring timeout in force, in seconds. */
957
1303
  timeout?: number;
1304
+ /** `"bridge"` on an `onAnswer: "bridge"` dial; absent on a connecting one. */
1305
+ onAnswer?: string;
1306
+ /** siphon's id for the group of phones a bridge dial rings. */
1307
+ groupId?: string;
1308
+ /**
1309
+ * How long a bridge dial as a whole rings, in seconds: `timeout` (parallel)
1310
+ * or `timeout` times the number of phones (sequential).
1311
+ */
1312
+ totalTimeout?: number;
1313
+ /** The ringback in force on a bridge dial (a preset or cadence, or `false`). */
1314
+ ringback?: string | boolean;
1315
+ /** The phone INVITEs a bridge dial built, one per branch. */
1316
+ branches?: DialBranchPayload[];
958
1317
  }
959
1318
  /** Which side of the call {@link Call.recordStart} writes. */
960
1319
  type RecordDirection = "ingress" | "egress" | "both";
@@ -1015,12 +1374,41 @@ interface DtmfOptions {
1015
1374
  /** Scope the tones to one peer of an MPTY bridge (its To-tag). */
1016
1375
  toTag?: string;
1017
1376
  }
1018
- /** Options for {@link Call.streamStart} (the WebSocket audio tee). */
1377
+ /**
1378
+ * Which kind of WebSocket stream {@link Call.streamStart} /
1379
+ * {@link Call.streamStop} address. The two are opposites: a `"tee"` is
1380
+ * additive (a copy streams out, the call keeps relaying), a `"bridge"` is a
1381
+ * takeover (the server becomes the leg's far side and the call's own media
1382
+ * path is unwired).
1383
+ */
1384
+ type StreamMode = "tee" | "bridge";
1385
+ /** Options for {@link Call.streamStart}. */
1019
1386
  interface StreamOptions {
1020
- /** Which leg(s) to tee — `"both"` (default), `"caller"`, or `"callee"`. */
1387
+ /**
1388
+ * `"tee"` (default) or `"bridge"`. Always sent, the default included, so a
1389
+ * server whose default moved can never turn a transcription into a takeover.
1390
+ */
1391
+ mode?: StreamMode;
1392
+ /**
1393
+ * Which leg(s) a tee streams — `"both"` (default), `"caller"`, or `"callee"`.
1394
+ * Tee only: the server refuses it alongside `mode: "bridge"`.
1395
+ */
1021
1396
  direction?: "both" | "caller" | "callee";
1022
- /** `1` = mixed mono, `2` = caller/callee stereo (only with `"both"`). */
1397
+ /**
1398
+ * `1` = mixed mono, `2` = caller/callee stereo (only with `"both"`). Tee
1399
+ * only.
1400
+ */
1023
1401
  channels?: 1 | 2;
1402
+ /**
1403
+ * A tee's L16 sample rate in Hz: a multiple of 1000 within 8000–48000 (the
1404
+ * engine's default when unset). Tee only; the server refuses anything else.
1405
+ */
1406
+ sampleRate?: number;
1407
+ }
1408
+ /** Options for {@link Call.streamStop}. */
1409
+ interface StreamStopOptions {
1410
+ /** Which stream to detach: `"tee"` (default, always sent) or `"bridge"`. */
1411
+ mode?: StreamMode;
1024
1412
  }
1025
1413
  /**
1026
1414
  * A handed-over SIP call. Cheap to hold (shares one connection + event stream).
@@ -1103,6 +1491,41 @@ declare class Call {
1103
1491
  terminate(reason?: string): Promise<void>;
1104
1492
  /** Alias for {@link Call.terminate}. */
1105
1493
  hangup(reason?: string): Promise<void>;
1494
+ /**
1495
+ * Abandon this **unanswered** call with nothing on the wire — no final
1496
+ * response, no CANCEL — and release it.
1497
+ *
1498
+ * The third way out of a parked call, and the only silent one.
1499
+ * {@link Call.reject} and an unanswered {@link Call.hangup} both answer, and
1500
+ * on a SIP port reachable from the internet that answer is the prize: a `404`
1501
+ * to an INVITE for a number nobody claims confirms the number to an
1502
+ * enumeration sweep, where silence leaves it unable to tell a missing
1503
+ * extension from a filtered one. Your controller holds the only knowledge of
1504
+ * which numbers are real, so it is the only thing that can decide an INVITE is
1505
+ * unsolicited.
1506
+ *
1507
+ * Not a way to hang up: an answered dialog is owed a BYE (RFC 3261 §15), so an
1508
+ * answered call rejects with `code === "invalid_state"` rather than being
1509
+ * orphaned — use {@link Call.hangup} there. A call that has already ended
1510
+ * rejects with `code === "not_found"`.
1511
+ *
1512
+ * `reason` is for the record, not the wire: it reaches siphon's log and the
1513
+ * CDR (`sip_reason`, beside `disconnect_initiator: "control"` and no response
1514
+ * code), so a dropped call reads as deliberate rather than as a leak.
1515
+ *
1516
+ * `options.ban` makes the verdict stick: siphon also scores the caller's
1517
+ * source address in the `security.failed_auth_ban` store, so a source the
1518
+ * controller keeps dropping is banned at the transport before its next INVITE
1519
+ * is parsed. The weight follows how far the address can be believed — a
1520
+ * strong signal over TCP / TLS / WS / WSS, whose handshake proved it, and
1521
+ * weight 1 over UDP, where one datagram can name any address. A no-op without
1522
+ * `security.failed_auth_ban`; `trusted_cidrs` are never scored; only a
1523
+ * successful drop scores, so a refused one leaves the source alone. Sent only
1524
+ * when `true`.
1525
+ */
1526
+ drop(reason?: string, options?: {
1527
+ ban?: boolean;
1528
+ }): Promise<void>;
1106
1529
  /**
1107
1530
  * Send an in-dialog REFER on the A-leg (blind transfer).
1108
1531
  *
@@ -1151,7 +1574,11 @@ declare class Call {
1151
1574
  * The first 2xx answers the caller with the winner's SDP and the pair becomes
1152
1575
  * an ordinary two-leg call, still owned by this app. A failure or timeout
1153
1576
  * arrives as a `DialFailed` event with the caller still ringing and still
1154
- * parked, so the app decides what happens next.
1577
+ * parked, so the app decides what happens next. Every branch is named as it is
1578
+ * created (`DialBranch`) and as it ends (`DialBranchFailed` / `DialAnswered`),
1579
+ * by its `leg_id` and `leg_sip_call_id` — see
1580
+ * {@link import("./protocol").DialBranchPayload} — and `DialFailed` lists them
1581
+ * all.
1155
1582
  *
1156
1583
  * Each target is a URI (dialed as written) or an `{aor}` (forked to every
1157
1584
  * registered contact over its own flow) — see {@link DialTarget}, and note
@@ -1169,6 +1596,23 @@ declare class Call {
1169
1596
  * answered, which is what this verb exists to avoid), `"bad_request"` (an
1170
1597
  * empty or malformed target list) or `"unsupported_verb"` (a strategy siphon
1171
1598
  * does not implement).
1599
+ *
1600
+ * A caller the app answered on purpose, to play it prompts first, is what
1601
+ * `onAnswer: "bridge"` is for (see {@link DialOptions.onAnswer}): the phones
1602
+ * ring while the caller hears `ringback`, and the first to answer is bridged
1603
+ * to it. The reply then also carries `onAnswer`, `groupId`, `totalTimeout`,
1604
+ * `ringback` and the `branches` rung. It refuses with `"invalid_state"` a
1605
+ * caller that is not answered, not anchored, already bridged or already has
1606
+ * phones ringing for it.
1607
+ *
1608
+ * ```ts
1609
+ * await call.answerAnchored();
1610
+ * await call.play({ file: "/prompts/menu.wav" });
1611
+ * await call.dial([{ aor: "sip:204@pbx.example" }], {
1612
+ * onAnswer: "bridge",
1613
+ * ringback: "ringback_eu",
1614
+ * });
1615
+ * ```
1172
1616
  */
1173
1617
  dial(targets: DialTarget[], options?: DialOptions): Promise<Dialing>;
1174
1618
  /**
@@ -1305,13 +1749,35 @@ declare class Call {
1305
1749
  /** Resume the A-leg media after a {@link Call.hold}. */
1306
1750
  unhold(): Promise<void>;
1307
1751
  /**
1308
- * Attach a WebSocket audio tee — stream a copy of the call's decoded audio to
1309
- * `wsUri` while the call keeps relaying. siphon-rtp backend only: rtpengine /
1310
- * rtpproxy reject with `code === "unsupported_verb"` (`error.isUnsupportedVerb()`).
1752
+ * Attach a WebSocket audio stream to `wsUri`: an additive tee (the default)
1753
+ * or a takeover bridge, as `options.mode` says.
1754
+ *
1755
+ * ```ts
1756
+ * // Transcribe the caller at 16 kHz; the call keeps relaying.
1757
+ * // siphon expands `{call_id}` to the call's SIP Call-ID.
1758
+ * await call.streamStart("wss://ai.example/stream/{call_id}", {
1759
+ * direction: "caller",
1760
+ * sampleRate: 16000,
1761
+ * });
1762
+ * // Hand the leg to a voice agent; the agent is now the far side.
1763
+ * await call.streamStart("wss://ai.example/agent", { mode: "bridge" });
1764
+ * ```
1765
+ *
1766
+ * A bridge on a leg that already has one re-points it in place. `wsUri` may
1767
+ * use `{call_id}` / `{from_tag}` / `{from_user}` / `{to_user}`, which siphon
1768
+ * expands before the engine sees it: `{call_id}` expands to the call's SIP
1769
+ * Call-ID ({@link Call.sipCallId}), not the control-plane `callId`. An
1770
+ * unknown placeholder rejects with `bad_request`. siphon-rtp backend only: rtpengine / rtpproxy
1771
+ * reject with `code === "unsupported_verb"` (`error.isUnsupportedVerb()`).
1311
1772
  */
1312
1773
  streamStart(wsUri: string, options?: StreamOptions): Promise<void>;
1313
- /** Detach the WebSocket audio tee (idempotent on siphon-rtp). */
1314
- streamStop(): Promise<void>;
1774
+ /**
1775
+ * Detach the WebSocket stream of `options.mode` (`"tee"` by default, sent
1776
+ * explicitly). A tee detach is idempotent. A bridge detach is not: the
1777
+ * engine refuses one where there is no relay to hand the call back to, and
1778
+ * that rejects rather than leaving a live call with no audio path.
1779
+ */
1780
+ streamStop(options?: StreamStopOptions): Promise<void>;
1315
1781
  /**
1316
1782
  * Record this call's decoded audio to a wav file.
1317
1783
  *
@@ -1393,6 +1859,13 @@ declare class SipClient {
1393
1859
  onCall(handler: CallHandler): Promise<void>;
1394
1860
  /** A pull-style stream of handed-over calls (alternative to a handler). */
1395
1861
  calls(): CallStream;
1862
+ /**
1863
+ * Register a handler for application-level events — the ones an app opts
1864
+ * into with `control.apps[].events` (`RegistrationChanged`,
1865
+ * `DialogStateChanged`), which concern no channel and so reach no call.
1866
+ * Replaces any previous handler.
1867
+ */
1868
+ onAppEvent(handler: AppEventHandler): void;
1396
1869
  /** Drive the supervised connection loop (reconnect + resync). */
1397
1870
  run(): Promise<void>;
1398
1871
  /** Fetch the registered adapters' schema (`describe`). */
@@ -1415,6 +1888,39 @@ declare class SipClient {
1415
1888
  * ```
1416
1889
  */
1417
1890
  originate(channel: string, to: string, media: OriginateMedia, options?: OriginateOptions): Promise<Originated>;
1891
+ /**
1892
+ * Ring every phone registered at `aor` under a caller-supplied channel id —
1893
+ * {@link SipClient.originate} for a phone rather than a URI.
1894
+ *
1895
+ * A phone registered over TCP, TLS or WSS behind NAT is reachable only on the
1896
+ * connection it registered over, and one registered through an edge proxy
1897
+ * only through its Path, so resolving its Contact as a `to` reaches nothing.
1898
+ * This rings each registered contact over its own flow and Path (RFC 5626
1899
+ * §5.3, RFC 3327 §5.3), each as its own originated call with `options`
1900
+ * applied. The first phone to answer wins; every other one still ringing is
1901
+ * CANCELled. `ring` says how the phones are rung ({@link OriginateRing}).
1902
+ *
1903
+ * An AoR with nobody registered rejects with `code === "not_found"` and
1904
+ * `details.reason === "no_contacts"`, with nothing on the wire.
1905
+ *
1906
+ * While the phones ring the channel is bound to the group: its events carry
1907
+ * the {@link OriginatedGroup.groupId} as their `call_id`, and each leg's own
1908
+ * Call-ID is in the payload (`DialBranch`, `DialBranchFailed`). From
1909
+ * `DialAnswered` on, the channel is the winning phone's call. A `hangup`
1910
+ * while they ring CANCELs every one; `drop` is refused (`invalid_state`),
1911
+ * since siphon is their caller and there is no response to withhold.
1912
+ *
1913
+ * ```ts
1914
+ * const group = await client.originateAor(
1915
+ * "wake-201",
1916
+ * "sip:201@pbx.example",
1917
+ * { anchor: true },
1918
+ * { from: "sip:reception@pbx.example", timeout: 25 },
1919
+ * { strategy: "parallel" },
1920
+ * );
1921
+ * ```
1922
+ */
1923
+ originateAor(channel: string, aor: string, media: OriginateMedia, options?: OriginateOptions, ring?: OriginateRing): Promise<OriginatedGroup>;
1418
1924
  /** Send a raw command on any module (the generic escape hatch). */
1419
1925
  command(module: string | null, verb: string, target: unknown, args: unknown): Promise<unknown>;
1420
1926
  /** Stop the client. */
@@ -1441,4 +1947,4 @@ declare class SipServer {
1441
1947
  close(): Promise<void>;
1442
1948
  }
1443
1949
 
1444
- export { type AcceptReferOptions, type AnchoredAnswerOptions, type BridgeFailedPayload, type BridgeOptions, type BridgeRole, type BridgeStage, Call, type CallEvent, type CallHandler, CallStream, type ChannelBridgedPayload, type ChannelDtmfPayload, type ChannelSnapshot, type ChannelUnbridgedPayload, type ClientConfig, type ClientEvent, type CommandTransport, type ConnectionEventSink, ControlClient, ControlError, type ControlErrorCode, type ControlErrorKind, ControlServer, DESCRIBE, type DialOptions, type DialTarget, type Dialing, type DtmfOptions, type EventFrame, type EventSink, EventStream, type FrameType, GET_VAR, HELLO, type HelloArgs, type HelloResult, MODULE_SIP, MODULE_SMPP, MODULE_SS7, type OriginateMedia, type OriginateOptions, type Originated, PROTOCOL_VERSION, type PeerHangupPolicy, type PlayFinishedPayload, type PlayOptions, type PlaySource, type PlayStartedPayload, RESYNC, type RecordChannels, type RecordDirection, type RecordOptions, type Recording, type ReferReplaces, type ReplyError, type ReplyFrame, type ReplyStatus, type ResponseOptions, type ResyncResult, type RouteTarget, type RouteTargetObject, SET_VAR, SUBPROTOCOL, type ServerConfig, type SessionRefresher, type SessionTimer, SipClient, type SipEventKind, SipServer, SipVerb, type SipVerbToken, type StreamOptions, type TransferOutcomePayload, type TransferReplaces, type TransferRequestedPayload, type TransferStage, type WsBridgeEndedPayload, type WsBridgeStartedPayload, type WsTeeEndedPayload, type WsTeeStartedPayload, dialArgs, encodeCommand, isBridgeFinal, isTransferFinal, originateArgs, parseInboundFrame, recordStartArgs, recordStopArgs, sipEventKind, transferOutcome };
1950
+ export { type AcceptReferOptions, type AnchoredAnswerOptions, type AppEvent, type AppEventHandler, type BridgeFailedPayload, type BridgeOptions, type BridgeRole, type BridgeStage, Call, type CallEvent, type CallHandler, CallStream, type ChannelBridgedPayload, type ChannelDtmfPayload, type ChannelSnapshot, type ChannelUnbridgedPayload, type ClientConfig, type ClientEvent, type CommandTransport, type ConnectionEventSink, ControlClient, ControlError, type ControlErrorCode, type ControlErrorKind, ControlServer, DESCRIBE, type DialAnsweredPayload, type DialBranchCause, type DialBranchOutcome, type DialBranchPayload, type DialFailedPayload, type DialOptions, type DialTarget, type Dialing, type DialogDirection, type DialogIdentity, type DialogState, type DialogStateChangedPayload, type DtmfOptions, type EventFrame, type EventSink, EventStream, type FrameType, GET_VAR, HELLO, type HelloArgs, type HelloResult, MODULE_SIP, MODULE_SMPP, MODULE_SS7, type MediaLegSummary, type MediaStartedPayload, type MediaSummaryPayload, type OriginateMedia, type OriginateOptions, type OriginateRing, type Originated, type OriginatedGroup, PROTOCOL_VERSION, type PeerHangupPolicy, type PlayFinishedPayload, type PlayOptions, type PlaySource, type PlayStartedPayload, RESYNC, type RecordChannels, type RecordDirection, type RecordOptions, type Recording, type ReferReplaces, type ReplyError, type ReplyFrame, type ReplyStatus, type ResponseOptions, type ResyncResult, type RouteTarget, type RouteTargetObject, SET_VAR, SUBPROTOCOL, type ServerConfig, type SessionRefresher, type SessionTimer, SipClient, type SipEventKind, SipServer, SipVerb, type SipVerbToken, type StreamMode, type StreamOptions, type StreamStopOptions, type TransferOutcomePayload, type TransferReplaces, type TransferRequestedPayload, type TransferStage, type WsBridgeEndedPayload, type WsBridgeStartedPayload, type WsTeeEndedPayload, type WsTeeStartedPayload, dialArgs, encodeCommand, isBridgeFinal, isDialFinal, isTransferFinal, originateAorArgs, originateArgs, parseInboundFrame, recordStartArgs, recordStopArgs, sipEventKind, transferOutcome };