@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 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?}`). `strategy` defaults to
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