@siphon-project/control 0.1.3 → 0.3.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.cjs +163 -1
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +208 -4
- package/dist/index.d.ts +208 -4
- package/dist/index.js +162 -2
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/dist/index.d.cts
CHANGED
|
@@ -189,6 +189,7 @@ declare const SipVerb: {
|
|
|
189
189
|
readonly RejectRefer: "reject_refer";
|
|
190
190
|
readonly Bridge: "bridge";
|
|
191
191
|
readonly Unbridge: "unbridge";
|
|
192
|
+
readonly ReplacePeer: "replace_peer";
|
|
192
193
|
readonly Play: "play";
|
|
193
194
|
readonly Stop: "stop";
|
|
194
195
|
readonly Dtmf: "dtmf";
|
|
@@ -200,7 +201,7 @@ declare const SipVerb: {
|
|
|
200
201
|
/** A value of {@link SipVerb}. */
|
|
201
202
|
type SipVerbToken = (typeof SipVerb)[keyof typeof SipVerb];
|
|
202
203
|
/** The well-known SIP-adapter event names (the ARI *Stasis* model). */
|
|
203
|
-
type SipEventKind = "StasisStart" | "StasisEnd" | "ChannelStateChange" | "ChannelHangupRequest" | "ChannelDtmfReceived" | "PlayStarted" | "TransferRequested" | "TransferProgress" | "TransferCompleted" | "TransferFailed" | "ChannelBridged" | "BridgeFailed" | "ChannelUnbridged" | "PlayFinished" | "WsTeeStarted" | "WsTeeEnded" | "WsBridgeStarted" | "WsBridgeEnded" | (string & {});
|
|
204
|
+
type SipEventKind = "StasisStart" | "StasisEnd" | "ChannelStateChange" | "ChannelHangupRequest" | "ChannelDtmfReceived" | "PlayStarted" | "TransferRequested" | "TransferProgress" | "TransferCompleted" | "TransferFailed" | "ChannelBridged" | "BridgeFailed" | "ChannelUnbridged" | "PeerReplaced" | "ReplaceFailed" | "PlayFinished" | "WsTeeStarted" | "WsTeeEnded" | "WsBridgeStarted" | "WsBridgeEnded" | (string & {});
|
|
204
205
|
/** Parse a wire event name; unknown names pass through verbatim (forward-compatible). */
|
|
205
206
|
declare function sipEventKind(name: string): SipEventKind;
|
|
206
207
|
/**
|
|
@@ -320,6 +321,19 @@ interface TransferOutcomePayload {
|
|
|
320
321
|
* event arrives per `refer`, so this is the signal to stop waiting.
|
|
321
322
|
*/
|
|
322
323
|
declare function isTransferFinal(name: string): boolean;
|
|
324
|
+
/**
|
|
325
|
+
* The transfer verdict carried by an event, or `null` if it is not one.
|
|
326
|
+
*
|
|
327
|
+
* Takes an event as {@link import("./sip").CallEvent} shapes it and narrows its
|
|
328
|
+
* `payload` to {@link TransferOutcomePayload} for `TransferProgress` /
|
|
329
|
+
* `TransferCompleted` / `TransferFailed`. Anything else — including
|
|
330
|
+
* `TransferRequested`, which is an *inbound* REFER somebody else asked for
|
|
331
|
+
* rather than a verdict on one of ours — gives `null`.
|
|
332
|
+
*/
|
|
333
|
+
declare function transferOutcome(event: {
|
|
334
|
+
kind: string;
|
|
335
|
+
payload: unknown;
|
|
336
|
+
}): TransferOutcomePayload | null;
|
|
323
337
|
/**
|
|
324
338
|
* What happens to the surviving leg when its bridge partner hangs up — the
|
|
325
339
|
* `onPeerHangup` option of {@link import("./sip").Call.bridge}.
|
|
@@ -704,6 +718,20 @@ interface ResponseOptions {
|
|
|
704
718
|
body?: string;
|
|
705
719
|
contentType?: string;
|
|
706
720
|
}
|
|
721
|
+
/** Options for an anchored answer ({@link Call.answerAnchored}). */
|
|
722
|
+
interface AnchoredAnswerOptions {
|
|
723
|
+
/** UAS 2xx code (default `200`). */
|
|
724
|
+
code?: number;
|
|
725
|
+
/** Reason phrase (default `OK`). */
|
|
726
|
+
reason?: string;
|
|
727
|
+
/** Media profile to anchor with (default `voice_ai`). */
|
|
728
|
+
profile?: string;
|
|
729
|
+
/**
|
|
730
|
+
* Per-call WebSocket bridge URI, overriding the profile's own. Supports
|
|
731
|
+
* `{call_id}` / `{from_tag}` / `{from_user}` / `{to_user}` templating.
|
|
732
|
+
*/
|
|
733
|
+
wsUri?: string;
|
|
734
|
+
}
|
|
707
735
|
/** The RFC 3891 `Replaces` triple for an attended transfer. */
|
|
708
736
|
interface ReferReplaces {
|
|
709
737
|
callId: string;
|
|
@@ -751,8 +779,19 @@ interface RouteTargetObject {
|
|
|
751
779
|
nextHop?: string;
|
|
752
780
|
/** Headers injected on this attempt's B-leg INVITE. */
|
|
753
781
|
headers?: Record<string, string>;
|
|
754
|
-
/**
|
|
782
|
+
/**
|
|
783
|
+
* Per-target ring timeout in seconds. It bounds the wait for this carrier to
|
|
784
|
+
* show progress (a 101-199), not the wait for its answer.
|
|
785
|
+
*/
|
|
755
786
|
timeout?: number;
|
|
787
|
+
/**
|
|
788
|
+
* Fail this carrier over at its ring timeout even after it has shown
|
|
789
|
+
* progress. By default a carrier that has sent a 180/183 keeps the call past
|
|
790
|
+
* `timeout`, and the call then fails with 408 rather than trying the next
|
|
791
|
+
* target; `true` is for a carrier that plays its own ringback before it has
|
|
792
|
+
* reached anyone. Default `false`, which is never sent.
|
|
793
|
+
*/
|
|
794
|
+
rerouteAfterProgress?: boolean;
|
|
756
795
|
}
|
|
757
796
|
/**
|
|
758
797
|
* One entry in a {@link Call.route} target list: a bare URI string, or a
|
|
@@ -764,6 +803,91 @@ type RouteTarget = string | RouteTargetObject;
|
|
|
764
803
|
* path, an rtpengine media-DB id, or an inline blob. A blob is base64-encoded on
|
|
765
804
|
* the wire (the control rail is JSON text).
|
|
766
805
|
*/
|
|
806
|
+
/**
|
|
807
|
+
* The media plan for {@link SipClient.originate} — what the outbound INVITE
|
|
808
|
+
* offers.
|
|
809
|
+
*
|
|
810
|
+
* Required, and a union, because the server requires exactly one plan and
|
|
811
|
+
* rejects every combination of the raw `sdp` / `body` / `media` arguments that
|
|
812
|
+
* names none or more than one. Expressed this way those errors cannot be
|
|
813
|
+
* written down.
|
|
814
|
+
*/
|
|
815
|
+
type OriginateMedia =
|
|
816
|
+
/** Offerless INVITE: siphon anchors the leg on the media engine. */
|
|
817
|
+
{
|
|
818
|
+
anchor: true;
|
|
819
|
+
profile?: string;
|
|
820
|
+
wsUri?: string;
|
|
821
|
+
}
|
|
822
|
+
/** Your own SDP offer (`application/sdp` by definition). */
|
|
823
|
+
| {
|
|
824
|
+
sdp: string;
|
|
825
|
+
}
|
|
826
|
+
/** Your own body with its own content type. */
|
|
827
|
+
| {
|
|
828
|
+
body: string;
|
|
829
|
+
contentType: string;
|
|
830
|
+
};
|
|
831
|
+
/**
|
|
832
|
+
* Who refreshes each dialog of an originated call where the RFC 4028 negotiation
|
|
833
|
+
* leaves siphon the choice (§7.1): the UAC of each dialog, the UAS of each, or
|
|
834
|
+
* siphon on both.
|
|
835
|
+
*/
|
|
836
|
+
type SessionRefresher = "uac" | "uas" | "b2bua";
|
|
837
|
+
/**
|
|
838
|
+
* The RFC 4028 session timer siphon runs on an originated call, over its
|
|
839
|
+
* `session_timer:` block. A field left out takes the server's default, as in the
|
|
840
|
+
* script API's `call.session_timer()`: 1800 s, a `Min-SE` of 90 s, and `b2bua`.
|
|
841
|
+
*/
|
|
842
|
+
interface SessionTimer {
|
|
843
|
+
/** The session interval, in seconds. */
|
|
844
|
+
expires?: number;
|
|
845
|
+
/** The smallest session interval siphon accepts, in seconds. */
|
|
846
|
+
minSe?: number;
|
|
847
|
+
/** Who refreshes where the negotiation leaves siphon the choice. */
|
|
848
|
+
refresher?: SessionRefresher;
|
|
849
|
+
}
|
|
850
|
+
/** Optional shaping for {@link SipClient.originate}. */
|
|
851
|
+
interface OriginateOptions {
|
|
852
|
+
/** From-URI to place the call as. */
|
|
853
|
+
from?: string;
|
|
854
|
+
/** From display name. */
|
|
855
|
+
fromDisplay?: string;
|
|
856
|
+
/** To display name. */
|
|
857
|
+
toDisplay?: string;
|
|
858
|
+
/** Route the INVITE here while keeping `to` as the R-URI. */
|
|
859
|
+
nextHop?: string;
|
|
860
|
+
/** P-Asserted-Identity to assert (RFC 3325). */
|
|
861
|
+
pAssertedIdentity?: string;
|
|
862
|
+
/** Caller-identity presentation (RFC 3323 §4.1). */
|
|
863
|
+
privacy?: "allowed" | "restricted";
|
|
864
|
+
/** Extra headers on the outbound INVITE. */
|
|
865
|
+
headers?: Record<string, string>;
|
|
866
|
+
/** Ring timeout in seconds. */
|
|
867
|
+
timeout?: number;
|
|
868
|
+
/** Control-loss policy for the created channel. */
|
|
869
|
+
onLost?: string;
|
|
870
|
+
/** Per-call variables carried on the channel. */
|
|
871
|
+
vars?: Record<string, string>;
|
|
872
|
+
/**
|
|
873
|
+
* The RFC 4028 session timer to run on the call; left out, the one the server
|
|
874
|
+
* has configured runs, if any.
|
|
875
|
+
*/
|
|
876
|
+
sessionTimer?: SessionTimer;
|
|
877
|
+
}
|
|
878
|
+
/**
|
|
879
|
+
* What the server answers an accepted `originate` with: the call is `calling`,
|
|
880
|
+
* not answered — the answer arrives later as an event on the channel.
|
|
881
|
+
*/
|
|
882
|
+
interface Originated {
|
|
883
|
+
/** The caller-supplied channel id the call is addressed by. */
|
|
884
|
+
channel: string;
|
|
885
|
+
/** siphon's internal call id. */
|
|
886
|
+
callId?: string;
|
|
887
|
+
/** The SIP Call-ID on the wire, for joining CDR / HEP. */
|
|
888
|
+
sipCallId?: string;
|
|
889
|
+
}
|
|
890
|
+
declare function originateArgs(channel: string, to: string, media: OriginateMedia, options?: OriginateOptions): Record<string, unknown>;
|
|
767
891
|
type PlaySource = {
|
|
768
892
|
file: string;
|
|
769
893
|
} | {
|
|
@@ -837,6 +961,26 @@ declare class Call {
|
|
|
837
961
|
private substrate;
|
|
838
962
|
/** Send a UAS 2xx to the parked A-leg (default `200 OK`). */
|
|
839
963
|
answer(options?: ResponseOptions): Promise<void>;
|
|
964
|
+
/**
|
|
965
|
+
* Answer the parked A-leg **and** anchor its media to the media engine in one
|
|
966
|
+
* act — the verb form of the routing script's
|
|
967
|
+
* `call.handover(answer=True, profile=…, ws_uri=…)`.
|
|
968
|
+
*
|
|
969
|
+
* This is how an application that accepted an **un-answered** handover
|
|
970
|
+
* connects the call. It can already hold the call open for as long as its own
|
|
971
|
+
* policy says with {@link Call.ring}; what it could not do is connect the
|
|
972
|
+
* caller to anything, because a plain {@link Call.answer} sends a 2xx and
|
|
973
|
+
* anchors nothing. Answering first and attaching a stream afterwards is not
|
|
974
|
+
* the same thing: `received_from`, echo cancellation and the VAD engine are
|
|
975
|
+
* properties of the answer, not of a bridge attached after it.
|
|
976
|
+
*
|
|
977
|
+
* Synthesizing the RFC 3264 answer against the media engine is a siphon-rtp
|
|
978
|
+
* capability, so on rtpengine / rtpproxy this rejects with
|
|
979
|
+
* `code === "unavailable"` rather than sending a 200 with nothing behind it.
|
|
980
|
+
* On any media failure the 2xx is never sent and the call stays parked —
|
|
981
|
+
* retry with another profile, or reject it.
|
|
982
|
+
*/
|
|
983
|
+
answerAnchored(options?: AnchoredAnswerOptions): Promise<void>;
|
|
840
984
|
/**
|
|
841
985
|
* Send `180 Ringing`: alerting only, no early media.
|
|
842
986
|
*
|
|
@@ -883,7 +1027,9 @@ declare class Call {
|
|
|
883
1027
|
*
|
|
884
1028
|
* `targets` is a non-empty list of carriers tried cheapest-first: each entry
|
|
885
1029
|
* is a bare URI string or a {@link RouteTargetObject}
|
|
886
|
-
* (`{uri, nextHop?, headers?, timeout?}`).
|
|
1030
|
+
* (`{uri, nextHop?, headers?, timeout?, rerouteAfterProgress?}`). A target
|
|
1031
|
+
* that has shown progress keeps the call past its `timeout` unless it sets
|
|
1032
|
+
* `rerouteAfterProgress`. `strategy` defaults to
|
|
887
1033
|
* `"sequential"` (v1 supports only sequential/single — anything else rejects
|
|
888
1034
|
* with `code === "unsupported_verb"`). `headers` is applied to every
|
|
889
1035
|
* attempt's B-leg INVITE.
|
|
@@ -956,6 +1102,46 @@ declare class Call {
|
|
|
956
1102
|
* with `code === "invalid_state"`.
|
|
957
1103
|
*/
|
|
958
1104
|
unbridge(reason?: string): Promise<unknown>;
|
|
1105
|
+
/**
|
|
1106
|
+
* Replace one leg of this answered call with a freshly dialed target, with no
|
|
1107
|
+
* REFER involved.
|
|
1108
|
+
*
|
|
1109
|
+
* The transfer siphon already runs for a REFER it terminates, reachable
|
|
1110
|
+
* because *this app* decided: an IVR that has worked out where the caller
|
|
1111
|
+
* should go, a controller handing a call from an AI to a human, a supervisor
|
|
1112
|
+
* take-over. siphon dials `target` as a new leg on the same call, re-anchors
|
|
1113
|
+
* the surviving party's media onto it, and once the target answers promotes
|
|
1114
|
+
* it into the surviving pair and BYEs the leg it replaced.
|
|
1115
|
+
*
|
|
1116
|
+
* The replaced leg **stays up while the target rings**, so the surviving
|
|
1117
|
+
* party hears ringback rather than silence, and a target that refuses or
|
|
1118
|
+
* never answers leaves the call exactly as it was.
|
|
1119
|
+
*
|
|
1120
|
+
* `replaceALeg` picks the direction: omitted/`false` replaces the callee and
|
|
1121
|
+
* keeps the caller, `true` does the reverse. `profile` names the media
|
|
1122
|
+
* profile for the pair this creates — required when the call is anchored with
|
|
1123
|
+
* a direction-bound one, whose answer half describes the party that is
|
|
1124
|
+
* leaving. `timeout` bounds the ring in seconds (`0` = no ring policy, only
|
|
1125
|
+
* siphon's guard against a target that answers nothing).
|
|
1126
|
+
*
|
|
1127
|
+
* Resolves as soon as the INVITE is on the wire
|
|
1128
|
+
* (`{channel, replacement: "dialing", target}`) and says nothing about the
|
|
1129
|
+
* target. Wait for the `PeerReplaced`
|
|
1130
|
+
* ({@link import("./protocol").PeerReplacedPayload}) or `ReplaceFailed`
|
|
1131
|
+
* ({@link import("./protocol").ReplaceFailedPayload}) event for the outcome —
|
|
1132
|
+
* acting on the reply alone would tear down a call whose replacement is still
|
|
1133
|
+
* ringing.
|
|
1134
|
+
*
|
|
1135
|
+
* Rejects with `code === "not_found"` (no such call), `"invalid_state"` (not
|
|
1136
|
+
* answered, no peer leg, or a replacement already in flight — all worth
|
|
1137
|
+
* retrying later) or `"bad_request"` (the target will not parse or route).
|
|
1138
|
+
*/
|
|
1139
|
+
replacePeer(target: string, options?: {
|
|
1140
|
+
nextHop?: string;
|
|
1141
|
+
replaceALeg?: boolean;
|
|
1142
|
+
profile?: string;
|
|
1143
|
+
timeout?: number;
|
|
1144
|
+
}): Promise<unknown>;
|
|
959
1145
|
/** Set a header on the stored A-leg INVITE. */
|
|
960
1146
|
setHeader(name: string, value: string): Promise<void>;
|
|
961
1147
|
/** Read a header from the stored A-leg INVITE (`null` when absent). */
|
|
@@ -1053,6 +1239,24 @@ declare class SipClient {
|
|
|
1053
1239
|
run(): Promise<void>;
|
|
1054
1240
|
/** Fetch the registered adapters' schema (`describe`). */
|
|
1055
1241
|
describe(): Promise<unknown>;
|
|
1242
|
+
/**
|
|
1243
|
+
* Place an outbound call under a caller-supplied channel id.
|
|
1244
|
+
*
|
|
1245
|
+
* The one verb that *creates* a channel rather than addressing one, which is
|
|
1246
|
+
* why it lives here and not on {@link Call}. It resolves as soon as the
|
|
1247
|
+
* INVITE is on the wire — the call is `calling`, and the answer, failure or
|
|
1248
|
+
* timeout arrives later as an event on the channel.
|
|
1249
|
+
*
|
|
1250
|
+
* ```ts
|
|
1251
|
+
* const call = await client.originate(
|
|
1252
|
+
* "wake-up-42",
|
|
1253
|
+
* "sip:1001@pbx.example",
|
|
1254
|
+
* { anchor: true },
|
|
1255
|
+
* { from: "sip:alarm@pbx.example", timeout: 20 },
|
|
1256
|
+
* );
|
|
1257
|
+
* ```
|
|
1258
|
+
*/
|
|
1259
|
+
originate(channel: string, to: string, media: OriginateMedia, options?: OriginateOptions): Promise<Originated>;
|
|
1056
1260
|
/** Send a raw command on any module (the generic escape hatch). */
|
|
1057
1261
|
command(module: string | null, verb: string, target: unknown, args: unknown): Promise<unknown>;
|
|
1058
1262
|
/** Stop the client. */
|
|
@@ -1079,4 +1283,4 @@ declare class SipServer {
|
|
|
1079
1283
|
close(): Promise<void>;
|
|
1080
1284
|
}
|
|
1081
1285
|
|
|
1082
|
-
export { type AcceptReferOptions, 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 DtmfOptions, type EventFrame, type EventSink, EventStream, type FrameType, GET_VAR, HELLO, type HelloArgs, type HelloResult, MODULE_SIP, MODULE_SMPP, MODULE_SS7, PROTOCOL_VERSION, type PeerHangupPolicy, type PlayFinishedPayload, type PlayOptions, type PlaySource, type PlayStartedPayload, 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 TransferOutcomePayload, type TransferReplaces, type TransferRequestedPayload, type TransferStage, type WsBridgeEndedPayload, type WsBridgeStartedPayload, type WsTeeEndedPayload, type WsTeeStartedPayload, encodeCommand, isBridgeFinal, isTransferFinal, parseInboundFrame, sipEventKind };
|
|
1286
|
+
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 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 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, encodeCommand, isBridgeFinal, isTransferFinal, originateArgs, parseInboundFrame, sipEventKind, transferOutcome };
|
package/dist/index.d.ts
CHANGED
|
@@ -189,6 +189,7 @@ declare const SipVerb: {
|
|
|
189
189
|
readonly RejectRefer: "reject_refer";
|
|
190
190
|
readonly Bridge: "bridge";
|
|
191
191
|
readonly Unbridge: "unbridge";
|
|
192
|
+
readonly ReplacePeer: "replace_peer";
|
|
192
193
|
readonly Play: "play";
|
|
193
194
|
readonly Stop: "stop";
|
|
194
195
|
readonly Dtmf: "dtmf";
|
|
@@ -200,7 +201,7 @@ declare const SipVerb: {
|
|
|
200
201
|
/** A value of {@link SipVerb}. */
|
|
201
202
|
type SipVerbToken = (typeof SipVerb)[keyof typeof SipVerb];
|
|
202
203
|
/** The well-known SIP-adapter event names (the ARI *Stasis* model). */
|
|
203
|
-
type SipEventKind = "StasisStart" | "StasisEnd" | "ChannelStateChange" | "ChannelHangupRequest" | "ChannelDtmfReceived" | "PlayStarted" | "TransferRequested" | "TransferProgress" | "TransferCompleted" | "TransferFailed" | "ChannelBridged" | "BridgeFailed" | "ChannelUnbridged" | "PlayFinished" | "WsTeeStarted" | "WsTeeEnded" | "WsBridgeStarted" | "WsBridgeEnded" | (string & {});
|
|
204
|
+
type SipEventKind = "StasisStart" | "StasisEnd" | "ChannelStateChange" | "ChannelHangupRequest" | "ChannelDtmfReceived" | "PlayStarted" | "TransferRequested" | "TransferProgress" | "TransferCompleted" | "TransferFailed" | "ChannelBridged" | "BridgeFailed" | "ChannelUnbridged" | "PeerReplaced" | "ReplaceFailed" | "PlayFinished" | "WsTeeStarted" | "WsTeeEnded" | "WsBridgeStarted" | "WsBridgeEnded" | (string & {});
|
|
204
205
|
/** Parse a wire event name; unknown names pass through verbatim (forward-compatible). */
|
|
205
206
|
declare function sipEventKind(name: string): SipEventKind;
|
|
206
207
|
/**
|
|
@@ -320,6 +321,19 @@ interface TransferOutcomePayload {
|
|
|
320
321
|
* event arrives per `refer`, so this is the signal to stop waiting.
|
|
321
322
|
*/
|
|
322
323
|
declare function isTransferFinal(name: string): boolean;
|
|
324
|
+
/**
|
|
325
|
+
* The transfer verdict carried by an event, or `null` if it is not one.
|
|
326
|
+
*
|
|
327
|
+
* Takes an event as {@link import("./sip").CallEvent} shapes it and narrows its
|
|
328
|
+
* `payload` to {@link TransferOutcomePayload} for `TransferProgress` /
|
|
329
|
+
* `TransferCompleted` / `TransferFailed`. Anything else — including
|
|
330
|
+
* `TransferRequested`, which is an *inbound* REFER somebody else asked for
|
|
331
|
+
* rather than a verdict on one of ours — gives `null`.
|
|
332
|
+
*/
|
|
333
|
+
declare function transferOutcome(event: {
|
|
334
|
+
kind: string;
|
|
335
|
+
payload: unknown;
|
|
336
|
+
}): TransferOutcomePayload | null;
|
|
323
337
|
/**
|
|
324
338
|
* What happens to the surviving leg when its bridge partner hangs up — the
|
|
325
339
|
* `onPeerHangup` option of {@link import("./sip").Call.bridge}.
|
|
@@ -704,6 +718,20 @@ interface ResponseOptions {
|
|
|
704
718
|
body?: string;
|
|
705
719
|
contentType?: string;
|
|
706
720
|
}
|
|
721
|
+
/** Options for an anchored answer ({@link Call.answerAnchored}). */
|
|
722
|
+
interface AnchoredAnswerOptions {
|
|
723
|
+
/** UAS 2xx code (default `200`). */
|
|
724
|
+
code?: number;
|
|
725
|
+
/** Reason phrase (default `OK`). */
|
|
726
|
+
reason?: string;
|
|
727
|
+
/** Media profile to anchor with (default `voice_ai`). */
|
|
728
|
+
profile?: string;
|
|
729
|
+
/**
|
|
730
|
+
* Per-call WebSocket bridge URI, overriding the profile's own. Supports
|
|
731
|
+
* `{call_id}` / `{from_tag}` / `{from_user}` / `{to_user}` templating.
|
|
732
|
+
*/
|
|
733
|
+
wsUri?: string;
|
|
734
|
+
}
|
|
707
735
|
/** The RFC 3891 `Replaces` triple for an attended transfer. */
|
|
708
736
|
interface ReferReplaces {
|
|
709
737
|
callId: string;
|
|
@@ -751,8 +779,19 @@ interface RouteTargetObject {
|
|
|
751
779
|
nextHop?: string;
|
|
752
780
|
/** Headers injected on this attempt's B-leg INVITE. */
|
|
753
781
|
headers?: Record<string, string>;
|
|
754
|
-
/**
|
|
782
|
+
/**
|
|
783
|
+
* Per-target ring timeout in seconds. It bounds the wait for this carrier to
|
|
784
|
+
* show progress (a 101-199), not the wait for its answer.
|
|
785
|
+
*/
|
|
755
786
|
timeout?: number;
|
|
787
|
+
/**
|
|
788
|
+
* Fail this carrier over at its ring timeout even after it has shown
|
|
789
|
+
* progress. By default a carrier that has sent a 180/183 keeps the call past
|
|
790
|
+
* `timeout`, and the call then fails with 408 rather than trying the next
|
|
791
|
+
* target; `true` is for a carrier that plays its own ringback before it has
|
|
792
|
+
* reached anyone. Default `false`, which is never sent.
|
|
793
|
+
*/
|
|
794
|
+
rerouteAfterProgress?: boolean;
|
|
756
795
|
}
|
|
757
796
|
/**
|
|
758
797
|
* One entry in a {@link Call.route} target list: a bare URI string, or a
|
|
@@ -764,6 +803,91 @@ type RouteTarget = string | RouteTargetObject;
|
|
|
764
803
|
* path, an rtpengine media-DB id, or an inline blob. A blob is base64-encoded on
|
|
765
804
|
* the wire (the control rail is JSON text).
|
|
766
805
|
*/
|
|
806
|
+
/**
|
|
807
|
+
* The media plan for {@link SipClient.originate} — what the outbound INVITE
|
|
808
|
+
* offers.
|
|
809
|
+
*
|
|
810
|
+
* Required, and a union, because the server requires exactly one plan and
|
|
811
|
+
* rejects every combination of the raw `sdp` / `body` / `media` arguments that
|
|
812
|
+
* names none or more than one. Expressed this way those errors cannot be
|
|
813
|
+
* written down.
|
|
814
|
+
*/
|
|
815
|
+
type OriginateMedia =
|
|
816
|
+
/** Offerless INVITE: siphon anchors the leg on the media engine. */
|
|
817
|
+
{
|
|
818
|
+
anchor: true;
|
|
819
|
+
profile?: string;
|
|
820
|
+
wsUri?: string;
|
|
821
|
+
}
|
|
822
|
+
/** Your own SDP offer (`application/sdp` by definition). */
|
|
823
|
+
| {
|
|
824
|
+
sdp: string;
|
|
825
|
+
}
|
|
826
|
+
/** Your own body with its own content type. */
|
|
827
|
+
| {
|
|
828
|
+
body: string;
|
|
829
|
+
contentType: string;
|
|
830
|
+
};
|
|
831
|
+
/**
|
|
832
|
+
* Who refreshes each dialog of an originated call where the RFC 4028 negotiation
|
|
833
|
+
* leaves siphon the choice (§7.1): the UAC of each dialog, the UAS of each, or
|
|
834
|
+
* siphon on both.
|
|
835
|
+
*/
|
|
836
|
+
type SessionRefresher = "uac" | "uas" | "b2bua";
|
|
837
|
+
/**
|
|
838
|
+
* The RFC 4028 session timer siphon runs on an originated call, over its
|
|
839
|
+
* `session_timer:` block. A field left out takes the server's default, as in the
|
|
840
|
+
* script API's `call.session_timer()`: 1800 s, a `Min-SE` of 90 s, and `b2bua`.
|
|
841
|
+
*/
|
|
842
|
+
interface SessionTimer {
|
|
843
|
+
/** The session interval, in seconds. */
|
|
844
|
+
expires?: number;
|
|
845
|
+
/** The smallest session interval siphon accepts, in seconds. */
|
|
846
|
+
minSe?: number;
|
|
847
|
+
/** Who refreshes where the negotiation leaves siphon the choice. */
|
|
848
|
+
refresher?: SessionRefresher;
|
|
849
|
+
}
|
|
850
|
+
/** Optional shaping for {@link SipClient.originate}. */
|
|
851
|
+
interface OriginateOptions {
|
|
852
|
+
/** From-URI to place the call as. */
|
|
853
|
+
from?: string;
|
|
854
|
+
/** From display name. */
|
|
855
|
+
fromDisplay?: string;
|
|
856
|
+
/** To display name. */
|
|
857
|
+
toDisplay?: string;
|
|
858
|
+
/** Route the INVITE here while keeping `to` as the R-URI. */
|
|
859
|
+
nextHop?: string;
|
|
860
|
+
/** P-Asserted-Identity to assert (RFC 3325). */
|
|
861
|
+
pAssertedIdentity?: string;
|
|
862
|
+
/** Caller-identity presentation (RFC 3323 §4.1). */
|
|
863
|
+
privacy?: "allowed" | "restricted";
|
|
864
|
+
/** Extra headers on the outbound INVITE. */
|
|
865
|
+
headers?: Record<string, string>;
|
|
866
|
+
/** Ring timeout in seconds. */
|
|
867
|
+
timeout?: number;
|
|
868
|
+
/** Control-loss policy for the created channel. */
|
|
869
|
+
onLost?: string;
|
|
870
|
+
/** Per-call variables carried on the channel. */
|
|
871
|
+
vars?: Record<string, string>;
|
|
872
|
+
/**
|
|
873
|
+
* The RFC 4028 session timer to run on the call; left out, the one the server
|
|
874
|
+
* has configured runs, if any.
|
|
875
|
+
*/
|
|
876
|
+
sessionTimer?: SessionTimer;
|
|
877
|
+
}
|
|
878
|
+
/**
|
|
879
|
+
* What the server answers an accepted `originate` with: the call is `calling`,
|
|
880
|
+
* not answered — the answer arrives later as an event on the channel.
|
|
881
|
+
*/
|
|
882
|
+
interface Originated {
|
|
883
|
+
/** The caller-supplied channel id the call is addressed by. */
|
|
884
|
+
channel: string;
|
|
885
|
+
/** siphon's internal call id. */
|
|
886
|
+
callId?: string;
|
|
887
|
+
/** The SIP Call-ID on the wire, for joining CDR / HEP. */
|
|
888
|
+
sipCallId?: string;
|
|
889
|
+
}
|
|
890
|
+
declare function originateArgs(channel: string, to: string, media: OriginateMedia, options?: OriginateOptions): Record<string, unknown>;
|
|
767
891
|
type PlaySource = {
|
|
768
892
|
file: string;
|
|
769
893
|
} | {
|
|
@@ -837,6 +961,26 @@ declare class Call {
|
|
|
837
961
|
private substrate;
|
|
838
962
|
/** Send a UAS 2xx to the parked A-leg (default `200 OK`). */
|
|
839
963
|
answer(options?: ResponseOptions): Promise<void>;
|
|
964
|
+
/**
|
|
965
|
+
* Answer the parked A-leg **and** anchor its media to the media engine in one
|
|
966
|
+
* act — the verb form of the routing script's
|
|
967
|
+
* `call.handover(answer=True, profile=…, ws_uri=…)`.
|
|
968
|
+
*
|
|
969
|
+
* This is how an application that accepted an **un-answered** handover
|
|
970
|
+
* connects the call. It can already hold the call open for as long as its own
|
|
971
|
+
* policy says with {@link Call.ring}; what it could not do is connect the
|
|
972
|
+
* caller to anything, because a plain {@link Call.answer} sends a 2xx and
|
|
973
|
+
* anchors nothing. Answering first and attaching a stream afterwards is not
|
|
974
|
+
* the same thing: `received_from`, echo cancellation and the VAD engine are
|
|
975
|
+
* properties of the answer, not of a bridge attached after it.
|
|
976
|
+
*
|
|
977
|
+
* Synthesizing the RFC 3264 answer against the media engine is a siphon-rtp
|
|
978
|
+
* capability, so on rtpengine / rtpproxy this rejects with
|
|
979
|
+
* `code === "unavailable"` rather than sending a 200 with nothing behind it.
|
|
980
|
+
* On any media failure the 2xx is never sent and the call stays parked —
|
|
981
|
+
* retry with another profile, or reject it.
|
|
982
|
+
*/
|
|
983
|
+
answerAnchored(options?: AnchoredAnswerOptions): Promise<void>;
|
|
840
984
|
/**
|
|
841
985
|
* Send `180 Ringing`: alerting only, no early media.
|
|
842
986
|
*
|
|
@@ -883,7 +1027,9 @@ declare class Call {
|
|
|
883
1027
|
*
|
|
884
1028
|
* `targets` is a non-empty list of carriers tried cheapest-first: each entry
|
|
885
1029
|
* is a bare URI string or a {@link RouteTargetObject}
|
|
886
|
-
* (`{uri, nextHop?, headers?, timeout?}`).
|
|
1030
|
+
* (`{uri, nextHop?, headers?, timeout?, rerouteAfterProgress?}`). A target
|
|
1031
|
+
* that has shown progress keeps the call past its `timeout` unless it sets
|
|
1032
|
+
* `rerouteAfterProgress`. `strategy` defaults to
|
|
887
1033
|
* `"sequential"` (v1 supports only sequential/single — anything else rejects
|
|
888
1034
|
* with `code === "unsupported_verb"`). `headers` is applied to every
|
|
889
1035
|
* attempt's B-leg INVITE.
|
|
@@ -956,6 +1102,46 @@ declare class Call {
|
|
|
956
1102
|
* with `code === "invalid_state"`.
|
|
957
1103
|
*/
|
|
958
1104
|
unbridge(reason?: string): Promise<unknown>;
|
|
1105
|
+
/**
|
|
1106
|
+
* Replace one leg of this answered call with a freshly dialed target, with no
|
|
1107
|
+
* REFER involved.
|
|
1108
|
+
*
|
|
1109
|
+
* The transfer siphon already runs for a REFER it terminates, reachable
|
|
1110
|
+
* because *this app* decided: an IVR that has worked out where the caller
|
|
1111
|
+
* should go, a controller handing a call from an AI to a human, a supervisor
|
|
1112
|
+
* take-over. siphon dials `target` as a new leg on the same call, re-anchors
|
|
1113
|
+
* the surviving party's media onto it, and once the target answers promotes
|
|
1114
|
+
* it into the surviving pair and BYEs the leg it replaced.
|
|
1115
|
+
*
|
|
1116
|
+
* The replaced leg **stays up while the target rings**, so the surviving
|
|
1117
|
+
* party hears ringback rather than silence, and a target that refuses or
|
|
1118
|
+
* never answers leaves the call exactly as it was.
|
|
1119
|
+
*
|
|
1120
|
+
* `replaceALeg` picks the direction: omitted/`false` replaces the callee and
|
|
1121
|
+
* keeps the caller, `true` does the reverse. `profile` names the media
|
|
1122
|
+
* profile for the pair this creates — required when the call is anchored with
|
|
1123
|
+
* a direction-bound one, whose answer half describes the party that is
|
|
1124
|
+
* leaving. `timeout` bounds the ring in seconds (`0` = no ring policy, only
|
|
1125
|
+
* siphon's guard against a target that answers nothing).
|
|
1126
|
+
*
|
|
1127
|
+
* Resolves as soon as the INVITE is on the wire
|
|
1128
|
+
* (`{channel, replacement: "dialing", target}`) and says nothing about the
|
|
1129
|
+
* target. Wait for the `PeerReplaced`
|
|
1130
|
+
* ({@link import("./protocol").PeerReplacedPayload}) or `ReplaceFailed`
|
|
1131
|
+
* ({@link import("./protocol").ReplaceFailedPayload}) event for the outcome —
|
|
1132
|
+
* acting on the reply alone would tear down a call whose replacement is still
|
|
1133
|
+
* ringing.
|
|
1134
|
+
*
|
|
1135
|
+
* Rejects with `code === "not_found"` (no such call), `"invalid_state"` (not
|
|
1136
|
+
* answered, no peer leg, or a replacement already in flight — all worth
|
|
1137
|
+
* retrying later) or `"bad_request"` (the target will not parse or route).
|
|
1138
|
+
*/
|
|
1139
|
+
replacePeer(target: string, options?: {
|
|
1140
|
+
nextHop?: string;
|
|
1141
|
+
replaceALeg?: boolean;
|
|
1142
|
+
profile?: string;
|
|
1143
|
+
timeout?: number;
|
|
1144
|
+
}): Promise<unknown>;
|
|
959
1145
|
/** Set a header on the stored A-leg INVITE. */
|
|
960
1146
|
setHeader(name: string, value: string): Promise<void>;
|
|
961
1147
|
/** Read a header from the stored A-leg INVITE (`null` when absent). */
|
|
@@ -1053,6 +1239,24 @@ declare class SipClient {
|
|
|
1053
1239
|
run(): Promise<void>;
|
|
1054
1240
|
/** Fetch the registered adapters' schema (`describe`). */
|
|
1055
1241
|
describe(): Promise<unknown>;
|
|
1242
|
+
/**
|
|
1243
|
+
* Place an outbound call under a caller-supplied channel id.
|
|
1244
|
+
*
|
|
1245
|
+
* The one verb that *creates* a channel rather than addressing one, which is
|
|
1246
|
+
* why it lives here and not on {@link Call}. It resolves as soon as the
|
|
1247
|
+
* INVITE is on the wire — the call is `calling`, and the answer, failure or
|
|
1248
|
+
* timeout arrives later as an event on the channel.
|
|
1249
|
+
*
|
|
1250
|
+
* ```ts
|
|
1251
|
+
* const call = await client.originate(
|
|
1252
|
+
* "wake-up-42",
|
|
1253
|
+
* "sip:1001@pbx.example",
|
|
1254
|
+
* { anchor: true },
|
|
1255
|
+
* { from: "sip:alarm@pbx.example", timeout: 20 },
|
|
1256
|
+
* );
|
|
1257
|
+
* ```
|
|
1258
|
+
*/
|
|
1259
|
+
originate(channel: string, to: string, media: OriginateMedia, options?: OriginateOptions): Promise<Originated>;
|
|
1056
1260
|
/** Send a raw command on any module (the generic escape hatch). */
|
|
1057
1261
|
command(module: string | null, verb: string, target: unknown, args: unknown): Promise<unknown>;
|
|
1058
1262
|
/** Stop the client. */
|
|
@@ -1079,4 +1283,4 @@ declare class SipServer {
|
|
|
1079
1283
|
close(): Promise<void>;
|
|
1080
1284
|
}
|
|
1081
1285
|
|
|
1082
|
-
export { type AcceptReferOptions, 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 DtmfOptions, type EventFrame, type EventSink, EventStream, type FrameType, GET_VAR, HELLO, type HelloArgs, type HelloResult, MODULE_SIP, MODULE_SMPP, MODULE_SS7, PROTOCOL_VERSION, type PeerHangupPolicy, type PlayFinishedPayload, type PlayOptions, type PlaySource, type PlayStartedPayload, 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 TransferOutcomePayload, type TransferReplaces, type TransferRequestedPayload, type TransferStage, type WsBridgeEndedPayload, type WsBridgeStartedPayload, type WsTeeEndedPayload, type WsTeeStartedPayload, encodeCommand, isBridgeFinal, isTransferFinal, parseInboundFrame, sipEventKind };
|
|
1286
|
+
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 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 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, encodeCommand, isBridgeFinal, isTransferFinal, originateArgs, parseInboundFrame, sipEventKind, transferOutcome };
|