@siphon-project/control 0.5.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/README.md +10 -1
- package/dist/index.cjs +232 -10
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +483 -14
- package/dist/index.d.ts +483 -14
- package/dist/index.js +231 -11
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/dist/index.d.ts
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`
|
|
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
|
|
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.
|
|
@@ -975,6 +1257,33 @@ interface DialOptions {
|
|
|
975
1257
|
* identity in `pAssertedIdentity` for the trusted next hop.
|
|
976
1258
|
*/
|
|
977
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;
|
|
978
1287
|
}
|
|
979
1288
|
/**
|
|
980
1289
|
* What the server answers an accepted `dial` with: the INVITEs are on the wire
|
|
@@ -992,6 +1301,19 @@ interface Dialing {
|
|
|
992
1301
|
strategy?: string;
|
|
993
1302
|
/** The ring timeout in force, in seconds. */
|
|
994
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[];
|
|
995
1317
|
}
|
|
996
1318
|
/** Which side of the call {@link Call.recordStart} writes. */
|
|
997
1319
|
type RecordDirection = "ingress" | "egress" | "both";
|
|
@@ -1052,12 +1374,41 @@ interface DtmfOptions {
|
|
|
1052
1374
|
/** Scope the tones to one peer of an MPTY bridge (its To-tag). */
|
|
1053
1375
|
toTag?: string;
|
|
1054
1376
|
}
|
|
1055
|
-
/**
|
|
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}. */
|
|
1056
1386
|
interface StreamOptions {
|
|
1057
|
-
/**
|
|
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
|
+
*/
|
|
1058
1396
|
direction?: "both" | "caller" | "callee";
|
|
1059
|
-
/**
|
|
1397
|
+
/**
|
|
1398
|
+
* `1` = mixed mono, `2` = caller/callee stereo (only with `"both"`). Tee
|
|
1399
|
+
* only.
|
|
1400
|
+
*/
|
|
1060
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;
|
|
1061
1412
|
}
|
|
1062
1413
|
/**
|
|
1063
1414
|
* A handed-over SIP call. Cheap to hold (shares one connection + event stream).
|
|
@@ -1140,6 +1491,41 @@ declare class Call {
|
|
|
1140
1491
|
terminate(reason?: string): Promise<void>;
|
|
1141
1492
|
/** Alias for {@link Call.terminate}. */
|
|
1142
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>;
|
|
1143
1529
|
/**
|
|
1144
1530
|
* Send an in-dialog REFER on the A-leg (blind transfer).
|
|
1145
1531
|
*
|
|
@@ -1188,7 +1574,11 @@ declare class Call {
|
|
|
1188
1574
|
* The first 2xx answers the caller with the winner's SDP and the pair becomes
|
|
1189
1575
|
* an ordinary two-leg call, still owned by this app. A failure or timeout
|
|
1190
1576
|
* arrives as a `DialFailed` event with the caller still ringing and still
|
|
1191
|
-
* 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.
|
|
1192
1582
|
*
|
|
1193
1583
|
* Each target is a URI (dialed as written) or an `{aor}` (forked to every
|
|
1194
1584
|
* registered contact over its own flow) — see {@link DialTarget}, and note
|
|
@@ -1206,6 +1596,23 @@ declare class Call {
|
|
|
1206
1596
|
* answered, which is what this verb exists to avoid), `"bad_request"` (an
|
|
1207
1597
|
* empty or malformed target list) or `"unsupported_verb"` (a strategy siphon
|
|
1208
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
|
+
* ```
|
|
1209
1616
|
*/
|
|
1210
1617
|
dial(targets: DialTarget[], options?: DialOptions): Promise<Dialing>;
|
|
1211
1618
|
/**
|
|
@@ -1342,13 +1749,35 @@ declare class Call {
|
|
|
1342
1749
|
/** Resume the A-leg media after a {@link Call.hold}. */
|
|
1343
1750
|
unhold(): Promise<void>;
|
|
1344
1751
|
/**
|
|
1345
|
-
* Attach a WebSocket audio
|
|
1346
|
-
*
|
|
1347
|
-
*
|
|
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()`).
|
|
1348
1772
|
*/
|
|
1349
1773
|
streamStart(wsUri: string, options?: StreamOptions): Promise<void>;
|
|
1350
|
-
/**
|
|
1351
|
-
|
|
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>;
|
|
1352
1781
|
/**
|
|
1353
1782
|
* Record this call's decoded audio to a wav file.
|
|
1354
1783
|
*
|
|
@@ -1430,6 +1859,13 @@ declare class SipClient {
|
|
|
1430
1859
|
onCall(handler: CallHandler): Promise<void>;
|
|
1431
1860
|
/** A pull-style stream of handed-over calls (alternative to a handler). */
|
|
1432
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;
|
|
1433
1869
|
/** Drive the supervised connection loop (reconnect + resync). */
|
|
1434
1870
|
run(): Promise<void>;
|
|
1435
1871
|
/** Fetch the registered adapters' schema (`describe`). */
|
|
@@ -1452,6 +1888,39 @@ declare class SipClient {
|
|
|
1452
1888
|
* ```
|
|
1453
1889
|
*/
|
|
1454
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>;
|
|
1455
1924
|
/** Send a raw command on any module (the generic escape hatch). */
|
|
1456
1925
|
command(module: string | null, verb: string, target: unknown, args: unknown): Promise<unknown>;
|
|
1457
1926
|
/** Stop the client. */
|
|
@@ -1478,4 +1947,4 @@ declare class SipServer {
|
|
|
1478
1947
|
close(): Promise<void>;
|
|
1479
1948
|
}
|
|
1480
1949
|
|
|
1481
|
-
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 };
|