@siphon-project/control 0.2.0 → 0.4.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 +3 -0
- package/dist/index.cjs +234 -2
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +277 -3
- package/dist/index.d.ts +277 -3
- package/dist/index.js +231 -3
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -110,6 +110,9 @@ await client.command("sip", "answer", { channel: "ch1" }, { code: 200 });
|
|
|
110
110
|
| `rejectRefer(code, reason?)` | `reject_refer` (`sip`) | ‡ |
|
|
111
111
|
| `bridge(withChannel, options?)` | `bridge` (`sip`) | join two answered legs; the verdict arrives as `ChannelBridged` / `BridgeFailed` |
|
|
112
112
|
| `unbridge(reason?)` | `unbridge` (`sip`) | break the bridge — both legs stay answered, owned and held |
|
|
113
|
+
| `dial(targets, options?)` | `dial` (`sip`) | ring B-legs while the caller stays **unanswered** and this app keeps the channel. A target is `{uri}` (dialed as written) or `{aor}` (forked to every registered contact over its own flow); one naming both, or neither, throws |
|
|
114
|
+
| `recordStart(options?)` | `record_start` (`sip`) | record the call's decoded audio to a wav file; the reply names the `recordingId`, `RecordingFinished` says the file is closed. siphon-rtp only |
|
|
115
|
+
| `recordStop(recordingId?)` | `record_stop` (`sip`) | stop one recording, or every recording on the call when no id is given |
|
|
113
116
|
| `playFile(file)` | `play` (`sip`) | ‡ media |
|
|
114
117
|
| `dtmf(digits)` | `dtmf` (`sip`) | ‡ media |
|
|
115
118
|
| `command(verb, args?)` | (`sip`) | arbitrary SIP-adapter verb |
|
package/dist/index.cjs
CHANGED
|
@@ -118,6 +118,11 @@ var SipVerb = {
|
|
|
118
118
|
Hangup: "hangup",
|
|
119
119
|
Refer: "refer",
|
|
120
120
|
Route: "route",
|
|
121
|
+
/**
|
|
122
|
+
* Ring targets as B-legs while the caller stays unanswered and the app keeps
|
|
123
|
+
* the channel. Channel-addressed, unlike `originate`, which creates one.
|
|
124
|
+
*/
|
|
125
|
+
Dial: "dial",
|
|
121
126
|
SetHeader: "set_header",
|
|
122
127
|
GetHeader: "get_header",
|
|
123
128
|
RemoveHeader: "remove_header",
|
|
@@ -132,7 +137,11 @@ var SipVerb = {
|
|
|
132
137
|
Hold: "hold",
|
|
133
138
|
Unhold: "unhold",
|
|
134
139
|
StreamStart: "stream_start",
|
|
135
|
-
StreamStop: "stream_stop"
|
|
140
|
+
StreamStop: "stream_stop",
|
|
141
|
+
/** Record the call's decoded audio to a wav file (siphon-rtp backend only). */
|
|
142
|
+
RecordStart: "record_start",
|
|
143
|
+
/** Stop one recording by id, or every recording on the call. */
|
|
144
|
+
RecordStop: "record_stop"
|
|
136
145
|
};
|
|
137
146
|
function sipEventKind(name) {
|
|
138
147
|
return name;
|
|
@@ -631,6 +640,9 @@ function routeTargetToWire(target) {
|
|
|
631
640
|
if (target.timeout !== void 0) {
|
|
632
641
|
object.timeout = target.timeout;
|
|
633
642
|
}
|
|
643
|
+
if (target.rerouteAfterProgress === true) {
|
|
644
|
+
object.reroute_after_progress = true;
|
|
645
|
+
}
|
|
634
646
|
return object;
|
|
635
647
|
}
|
|
636
648
|
function stringValue(result) {
|
|
@@ -642,6 +654,91 @@ function stringValue(result) {
|
|
|
642
654
|
}
|
|
643
655
|
return null;
|
|
644
656
|
}
|
|
657
|
+
function originateArgs(channel, to, media, options) {
|
|
658
|
+
const args = { channel, to };
|
|
659
|
+
if ("anchor" in media) {
|
|
660
|
+
args.media = true;
|
|
661
|
+
if (media.profile !== void 0) args.profile = media.profile;
|
|
662
|
+
if (media.wsUri !== void 0) args.ws_uri = media.wsUri;
|
|
663
|
+
} else if ("sdp" in media) {
|
|
664
|
+
args.sdp = media.sdp;
|
|
665
|
+
} else {
|
|
666
|
+
args.body = media.body;
|
|
667
|
+
args.content_type = media.contentType;
|
|
668
|
+
}
|
|
669
|
+
if (!options) return args;
|
|
670
|
+
if (options.from !== void 0) args.from = options.from;
|
|
671
|
+
if (options.fromDisplay !== void 0) args.from_display = options.fromDisplay;
|
|
672
|
+
if (options.toDisplay !== void 0) args.to_display = options.toDisplay;
|
|
673
|
+
if (options.nextHop !== void 0) args.next_hop = options.nextHop;
|
|
674
|
+
if (options.pAssertedIdentity !== void 0) {
|
|
675
|
+
args.p_asserted_identity = options.pAssertedIdentity;
|
|
676
|
+
}
|
|
677
|
+
if (options.privacy !== void 0) args.privacy = options.privacy;
|
|
678
|
+
if (options.headers !== void 0) args.headers = options.headers;
|
|
679
|
+
if (options.timeout !== void 0) args.timeout = options.timeout;
|
|
680
|
+
if (options.onLost !== void 0) args.on_lost = options.onLost;
|
|
681
|
+
if (options.vars !== void 0) args.vars = options.vars;
|
|
682
|
+
if (options.sessionTimer !== void 0) {
|
|
683
|
+
const timer = {};
|
|
684
|
+
const { expires, minSe, refresher } = options.sessionTimer;
|
|
685
|
+
if (expires !== void 0) timer.expires = expires;
|
|
686
|
+
if (minSe !== void 0) timer.min_se = minSe;
|
|
687
|
+
if (refresher !== void 0) timer.refresher = refresher;
|
|
688
|
+
args.session_timer = timer;
|
|
689
|
+
}
|
|
690
|
+
return args;
|
|
691
|
+
}
|
|
692
|
+
function dialTargetToWire(target) {
|
|
693
|
+
const uri = target.uri;
|
|
694
|
+
const aor = target.aor;
|
|
695
|
+
const nextHop = target.nextHop;
|
|
696
|
+
const headers = target.headers;
|
|
697
|
+
if (typeof uri === "string" && typeof aor === "string") {
|
|
698
|
+
throw new TypeError(
|
|
699
|
+
'a dial target names "uri" or "aor", never both \u2014 siphon reads the aor and ignores the uri beside it, so this would place a different call'
|
|
700
|
+
);
|
|
701
|
+
}
|
|
702
|
+
if (typeof aor === "string") {
|
|
703
|
+
if (nextHop !== void 0) {
|
|
704
|
+
throw new TypeError(
|
|
705
|
+
`an aor target takes no "nextHop": each of its branches routes over its own contact's captured flow`
|
|
706
|
+
);
|
|
707
|
+
}
|
|
708
|
+
const object2 = { aor };
|
|
709
|
+
if (headers !== void 0) object2.headers = headers;
|
|
710
|
+
return object2;
|
|
711
|
+
}
|
|
712
|
+
if (typeof uri !== "string") {
|
|
713
|
+
throw new TypeError('a dial target requires a string "uri" or "aor"');
|
|
714
|
+
}
|
|
715
|
+
if (nextHop === void 0 && headers === void 0) return uri;
|
|
716
|
+
const object = { uri };
|
|
717
|
+
if (nextHop !== void 0) object.next_hop = nextHop;
|
|
718
|
+
if (headers !== void 0) object.headers = headers;
|
|
719
|
+
return object;
|
|
720
|
+
}
|
|
721
|
+
function dialArgs(targets, options) {
|
|
722
|
+
const args = { targets: targets.map(dialTargetToWire) };
|
|
723
|
+
if (!options) return args;
|
|
724
|
+
if (options.strategy !== void 0) args.strategy = options.strategy;
|
|
725
|
+
if (options.timeout !== void 0) args.timeout = options.timeout;
|
|
726
|
+
if (options.headers !== void 0) args.headers = options.headers;
|
|
727
|
+
return args;
|
|
728
|
+
}
|
|
729
|
+
function recordStartArgs(options) {
|
|
730
|
+
const args = {};
|
|
731
|
+
if (!options) return args;
|
|
732
|
+
if (options.direction !== void 0) args.direction = options.direction;
|
|
733
|
+
if (options.channels !== void 0) args.channels = options.channels;
|
|
734
|
+
if (options.maxDurationMs !== void 0) args.max_duration_ms = options.maxDurationMs;
|
|
735
|
+
if (options.silenceMs !== void 0) args.silence_ms = options.silenceMs;
|
|
736
|
+
if (options.path !== void 0) args.path = options.path;
|
|
737
|
+
return args;
|
|
738
|
+
}
|
|
739
|
+
function recordStopArgs(recordingId) {
|
|
740
|
+
return recordingId === void 0 ? {} : { recording_id: recordingId };
|
|
741
|
+
}
|
|
645
742
|
function playArgs(source, options) {
|
|
646
743
|
const args = {};
|
|
647
744
|
if ("file" in source) {
|
|
@@ -823,7 +920,9 @@ var Call = class {
|
|
|
823
920
|
*
|
|
824
921
|
* `targets` is a non-empty list of carriers tried cheapest-first: each entry
|
|
825
922
|
* is a bare URI string or a {@link RouteTargetObject}
|
|
826
|
-
* (`{uri, nextHop?, headers?, timeout?}`).
|
|
923
|
+
* (`{uri, nextHop?, headers?, timeout?, rerouteAfterProgress?}`). A target
|
|
924
|
+
* that has shown progress keeps the call past its `timeout` unless it sets
|
|
925
|
+
* `rerouteAfterProgress`. `strategy` defaults to
|
|
827
926
|
* `"sequential"` (v1 supports only sequential/single — anything else rejects
|
|
828
927
|
* with `code === "unsupported_verb"`). `headers` is applied to every
|
|
829
928
|
* attempt's B-leg INVITE.
|
|
@@ -842,6 +941,58 @@ var Call = class {
|
|
|
842
941
|
}
|
|
843
942
|
return this.sip(SipVerb.Route, args);
|
|
844
943
|
}
|
|
944
|
+
/**
|
|
945
|
+
* Ring `targets` as B-legs while the caller stays **unanswered** and this
|
|
946
|
+
* application keeps the channel.
|
|
947
|
+
*
|
|
948
|
+
* The difference from {@link Call.route} is who holds the call afterwards.
|
|
949
|
+
* `route` hands it back to siphon, so the app gets `StasisEnd{reason: routed}`
|
|
950
|
+
* and loses it; there is then no way to say "ring the extension, and if nobody
|
|
951
|
+
* answers, voicemail" without answering the caller first — which starts
|
|
952
|
+
* billing before anyone picks up, records an unanswered call as answered, and
|
|
953
|
+
* denies the caller the callee's own ringback.
|
|
954
|
+
*
|
|
955
|
+
* The first 2xx answers the caller with the winner's SDP and the pair becomes
|
|
956
|
+
* an ordinary two-leg call, still owned by this app. A failure or timeout
|
|
957
|
+
* arrives as a `DialFailed` event with the caller still ringing and still
|
|
958
|
+
* parked, so the app decides what happens next.
|
|
959
|
+
*
|
|
960
|
+
* Each target is a URI (dialed as written) or an `{aor}` (forked to every
|
|
961
|
+
* registered contact over its own flow) — see {@link DialTarget}, and note
|
|
962
|
+
* that a target naming both, or neither, throws before anything is sent.
|
|
963
|
+
*
|
|
964
|
+
* ```ts
|
|
965
|
+
* const dialing = await call.dial(
|
|
966
|
+
* [{ aor: "sip:204@pbx.example" }],
|
|
967
|
+
* { strategy: "sequential", timeout: 20 },
|
|
968
|
+
* );
|
|
969
|
+
* ```
|
|
970
|
+
*
|
|
971
|
+
* Rejects with `code === "not_found"` (the call is gone, or no target yielded
|
|
972
|
+
* a branch — an AoR nobody has registered), `"invalid_state"` (already
|
|
973
|
+
* answered, which is what this verb exists to avoid), `"bad_request"` (an
|
|
974
|
+
* empty or malformed target list) or `"unsupported_verb"` (a strategy siphon
|
|
975
|
+
* does not implement).
|
|
976
|
+
*/
|
|
977
|
+
async dial(targets, options) {
|
|
978
|
+
const result = await this.sip(SipVerb.Dial, dialArgs(targets, options));
|
|
979
|
+
const text = (name) => {
|
|
980
|
+
const value = result?.[name];
|
|
981
|
+
return typeof value === "string" ? value : void 0;
|
|
982
|
+
};
|
|
983
|
+
const count = (name) => {
|
|
984
|
+
const value = result?.[name];
|
|
985
|
+
return typeof value === "number" ? value : void 0;
|
|
986
|
+
};
|
|
987
|
+
return {
|
|
988
|
+
// The server echoes the channel back; fall back to the one addressed
|
|
989
|
+
// rather than returning an empty id.
|
|
990
|
+
channel: text("channel") ?? this.channelId,
|
|
991
|
+
targets: count("targets"),
|
|
992
|
+
strategy: text("strategy"),
|
|
993
|
+
timeout: count("timeout")
|
|
994
|
+
};
|
|
995
|
+
}
|
|
845
996
|
/**
|
|
846
997
|
* Accept a *pending inbound* REFER (surfaced as a `TransferRequested` event)
|
|
847
998
|
* and run the transfer. `target` overrides the Refer-To URI, `nextHop` steers
|
|
@@ -1051,6 +1202,47 @@ var Call = class {
|
|
|
1051
1202
|
async streamStop() {
|
|
1052
1203
|
await this.sip(SipVerb.StreamStop, {});
|
|
1053
1204
|
}
|
|
1205
|
+
/**
|
|
1206
|
+
* Record this call's decoded audio to a wav file.
|
|
1207
|
+
*
|
|
1208
|
+
* The reply names the `recordingId` a later {@link Call.recordStop}
|
|
1209
|
+
* addresses. It is **not** the file: `RecordingFinished` fires when the file
|
|
1210
|
+
* is *closed* and names its path, which is what an app that mails the audio
|
|
1211
|
+
* has to wait for — acting on this reply races a half-written file.
|
|
1212
|
+
*
|
|
1213
|
+
* `maxDurationMs` and `silenceMs` are the two stop conditions a voicemail
|
|
1214
|
+
* greeting announces, and the engine evaluates both where the decoded audio
|
|
1215
|
+
* already is. Not SIPREC: this writes a file and works on a single-leg,
|
|
1216
|
+
* engine-terminated call, which is what a voicemail box is. siphon-rtp
|
|
1217
|
+
* backend only — rtpengine / rtpproxy reject with
|
|
1218
|
+
* `code === "unsupported_verb"`; a call with no anchored media session
|
|
1219
|
+
* rejects with `"not_found"`.
|
|
1220
|
+
*/
|
|
1221
|
+
async recordStart(options) {
|
|
1222
|
+
const result = await this.sip(
|
|
1223
|
+
SipVerb.RecordStart,
|
|
1224
|
+
recordStartArgs(options)
|
|
1225
|
+
);
|
|
1226
|
+
const text = (name) => {
|
|
1227
|
+
const value = result?.[name];
|
|
1228
|
+
return typeof value === "string" ? value : void 0;
|
|
1229
|
+
};
|
|
1230
|
+
return {
|
|
1231
|
+
channel: text("channel") ?? this.channelId,
|
|
1232
|
+
recordingId: text("recording_id")
|
|
1233
|
+
};
|
|
1234
|
+
}
|
|
1235
|
+
/**
|
|
1236
|
+
* Stop the recording named by `recordingId`, or **every** recording on this
|
|
1237
|
+
* call when it is left out.
|
|
1238
|
+
*
|
|
1239
|
+
* Resolves once the engine has accepted the stop; the file is not closed yet.
|
|
1240
|
+
* `RecordingFinished` says that, and carries the path and the reason
|
|
1241
|
+
* (`stopped`, `max_duration`, `silence`, `call_ended`, `error`).
|
|
1242
|
+
*/
|
|
1243
|
+
async recordStop(recordingId) {
|
|
1244
|
+
await this.sip(SipVerb.RecordStop, recordStopArgs(recordingId));
|
|
1245
|
+
}
|
|
1054
1246
|
// --- escape hatch + events --------------------------------------------
|
|
1055
1247
|
/** Send an arbitrary SIP-adapter verb + args and return the raw result. */
|
|
1056
1248
|
async command(verb, args) {
|
|
@@ -1204,6 +1396,42 @@ var SipClient = class _SipClient {
|
|
|
1204
1396
|
describe() {
|
|
1205
1397
|
return this.client.describe();
|
|
1206
1398
|
}
|
|
1399
|
+
/**
|
|
1400
|
+
* Place an outbound call under a caller-supplied channel id.
|
|
1401
|
+
*
|
|
1402
|
+
* The one verb that *creates* a channel rather than addressing one, which is
|
|
1403
|
+
* why it lives here and not on {@link Call}. It resolves as soon as the
|
|
1404
|
+
* INVITE is on the wire — the call is `calling`, and the answer, failure or
|
|
1405
|
+
* timeout arrives later as an event on the channel.
|
|
1406
|
+
*
|
|
1407
|
+
* ```ts
|
|
1408
|
+
* const call = await client.originate(
|
|
1409
|
+
* "wake-up-42",
|
|
1410
|
+
* "sip:1001@pbx.example",
|
|
1411
|
+
* { anchor: true },
|
|
1412
|
+
* { from: "sip:alarm@pbx.example", timeout: 20 },
|
|
1413
|
+
* );
|
|
1414
|
+
* ```
|
|
1415
|
+
*/
|
|
1416
|
+
async originate(channel, to, media, options) {
|
|
1417
|
+
const result = await this.client.command(
|
|
1418
|
+
MODULE_SIP,
|
|
1419
|
+
"originate",
|
|
1420
|
+
null,
|
|
1421
|
+
originateArgs(channel, to, media, options)
|
|
1422
|
+
);
|
|
1423
|
+
const text = (name) => {
|
|
1424
|
+
const value = result?.[name];
|
|
1425
|
+
return typeof value === "string" ? value : void 0;
|
|
1426
|
+
};
|
|
1427
|
+
return {
|
|
1428
|
+
// The server echoes the id back; fall back to the one we asked for
|
|
1429
|
+
// rather than returning an empty channel a caller cannot address.
|
|
1430
|
+
channel: text("channel") ?? channel,
|
|
1431
|
+
callId: text("call_id"),
|
|
1432
|
+
sipCallId: text("sip_call_id")
|
|
1433
|
+
};
|
|
1434
|
+
}
|
|
1207
1435
|
/** Send a raw command on any module (the generic escape hatch). */
|
|
1208
1436
|
command(module, verb, target, args) {
|
|
1209
1437
|
return this.client.command(module, verb, target, args);
|
|
@@ -1271,10 +1499,14 @@ exports.SUBPROTOCOL = SUBPROTOCOL;
|
|
|
1271
1499
|
exports.SipClient = SipClient;
|
|
1272
1500
|
exports.SipServer = SipServer;
|
|
1273
1501
|
exports.SipVerb = SipVerb;
|
|
1502
|
+
exports.dialArgs = dialArgs;
|
|
1274
1503
|
exports.encodeCommand = encodeCommand;
|
|
1275
1504
|
exports.isBridgeFinal = isBridgeFinal;
|
|
1276
1505
|
exports.isTransferFinal = isTransferFinal;
|
|
1506
|
+
exports.originateArgs = originateArgs;
|
|
1277
1507
|
exports.parseInboundFrame = parseInboundFrame;
|
|
1508
|
+
exports.recordStartArgs = recordStartArgs;
|
|
1509
|
+
exports.recordStopArgs = recordStopArgs;
|
|
1278
1510
|
exports.sipEventKind = sipEventKind;
|
|
1279
1511
|
exports.transferOutcome = transferOutcome;
|
|
1280
1512
|
//# sourceMappingURL=index.cjs.map
|