@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 CHANGED
@@ -125,6 +125,7 @@ var SipVerb = {
125
125
  RejectRefer: "reject_refer",
126
126
  Bridge: "bridge",
127
127
  Unbridge: "unbridge",
128
+ ReplacePeer: "replace_peer",
128
129
  Play: "play",
129
130
  Stop: "stop",
130
131
  Dtmf: "dtmf",
@@ -139,6 +140,12 @@ function sipEventKind(name) {
139
140
  function isTransferFinal(name) {
140
141
  return name === "TransferCompleted" || name === "TransferFailed";
141
142
  }
143
+ function transferOutcome(event) {
144
+ if (event.kind !== "TransferProgress" && event.kind !== "TransferCompleted" && event.kind !== "TransferFailed") {
145
+ return null;
146
+ }
147
+ return event.payload ?? null;
148
+ }
142
149
  function isBridgeFinal(name) {
143
150
  return name === "ChannelBridged" || name === "BridgeFailed";
144
151
  }
@@ -624,6 +631,9 @@ function routeTargetToWire(target) {
624
631
  if (target.timeout !== void 0) {
625
632
  object.timeout = target.timeout;
626
633
  }
634
+ if (target.rerouteAfterProgress === true) {
635
+ object.reroute_after_progress = true;
636
+ }
627
637
  return object;
628
638
  }
629
639
  function stringValue(result) {
@@ -635,6 +645,41 @@ function stringValue(result) {
635
645
  }
636
646
  return null;
637
647
  }
648
+ function originateArgs(channel, to, media, options) {
649
+ const args = { channel, to };
650
+ if ("anchor" in media) {
651
+ args.media = true;
652
+ if (media.profile !== void 0) args.profile = media.profile;
653
+ if (media.wsUri !== void 0) args.ws_uri = media.wsUri;
654
+ } else if ("sdp" in media) {
655
+ args.sdp = media.sdp;
656
+ } else {
657
+ args.body = media.body;
658
+ args.content_type = media.contentType;
659
+ }
660
+ if (!options) return args;
661
+ if (options.from !== void 0) args.from = options.from;
662
+ if (options.fromDisplay !== void 0) args.from_display = options.fromDisplay;
663
+ if (options.toDisplay !== void 0) args.to_display = options.toDisplay;
664
+ if (options.nextHop !== void 0) args.next_hop = options.nextHop;
665
+ if (options.pAssertedIdentity !== void 0) {
666
+ args.p_asserted_identity = options.pAssertedIdentity;
667
+ }
668
+ if (options.privacy !== void 0) args.privacy = options.privacy;
669
+ if (options.headers !== void 0) args.headers = options.headers;
670
+ if (options.timeout !== void 0) args.timeout = options.timeout;
671
+ if (options.onLost !== void 0) args.on_lost = options.onLost;
672
+ if (options.vars !== void 0) args.vars = options.vars;
673
+ if (options.sessionTimer !== void 0) {
674
+ const timer = {};
675
+ const { expires, minSe, refresher } = options.sessionTimer;
676
+ if (expires !== void 0) timer.expires = expires;
677
+ if (minSe !== void 0) timer.min_se = minSe;
678
+ if (refresher !== void 0) timer.refresher = refresher;
679
+ args.session_timer = timer;
680
+ }
681
+ return args;
682
+ }
638
683
  function playArgs(source, options) {
639
684
  const args = {};
640
685
  if ("file" in source) {
@@ -707,6 +752,41 @@ var Call = class {
707
752
  async answer(options) {
708
753
  await this.sip(SipVerb.Answer, options ? responseArgs(options) : {});
709
754
  }
755
+ /**
756
+ * Answer the parked A-leg **and** anchor its media to the media engine in one
757
+ * act — the verb form of the routing script's
758
+ * `call.handover(answer=True, profile=…, ws_uri=…)`.
759
+ *
760
+ * This is how an application that accepted an **un-answered** handover
761
+ * connects the call. It can already hold the call open for as long as its own
762
+ * policy says with {@link Call.ring}; what it could not do is connect the
763
+ * caller to anything, because a plain {@link Call.answer} sends a 2xx and
764
+ * anchors nothing. Answering first and attaching a stream afterwards is not
765
+ * the same thing: `received_from`, echo cancellation and the VAD engine are
766
+ * properties of the answer, not of a bridge attached after it.
767
+ *
768
+ * Synthesizing the RFC 3264 answer against the media engine is a siphon-rtp
769
+ * capability, so on rtpengine / rtpproxy this rejects with
770
+ * `code === "unavailable"` rather than sending a 200 with nothing behind it.
771
+ * On any media failure the 2xx is never sent and the call stays parked —
772
+ * retry with another profile, or reject it.
773
+ */
774
+ async answerAnchored(options) {
775
+ const args = { anchor: true };
776
+ if (options?.code !== void 0) {
777
+ args.code = options.code;
778
+ }
779
+ if (options?.reason !== void 0) {
780
+ args.reason = options.reason;
781
+ }
782
+ if (options?.profile !== void 0) {
783
+ args.profile = options.profile;
784
+ }
785
+ if (options?.wsUri !== void 0) {
786
+ args.ws_uri = options.wsUri;
787
+ }
788
+ await this.sip(SipVerb.Answer, args);
789
+ }
710
790
  /**
711
791
  * Send `180 Ringing`: alerting only, no early media.
712
792
  *
@@ -781,7 +861,9 @@ var Call = class {
781
861
  *
782
862
  * `targets` is a non-empty list of carriers tried cheapest-first: each entry
783
863
  * is a bare URI string or a {@link RouteTargetObject}
784
- * (`{uri, nextHop?, headers?, timeout?}`). `strategy` defaults to
864
+ * (`{uri, nextHop?, headers?, timeout?, rerouteAfterProgress?}`). A target
865
+ * that has shown progress keeps the call past its `timeout` unless it sets
866
+ * `rerouteAfterProgress`. `strategy` defaults to
785
867
  * `"sequential"` (v1 supports only sequential/single — anything else rejects
786
868
  * with `code === "unsupported_verb"`). `headers` is applied to every
787
869
  * attempt's B-leg INVITE.
@@ -892,6 +974,48 @@ var Call = class {
892
974
  async unbridge(reason) {
893
975
  return this.sip(SipVerb.Unbridge, reason !== void 0 ? { reason } : {});
894
976
  }
977
+ /**
978
+ * Replace one leg of this answered call with a freshly dialed target, with no
979
+ * REFER involved.
980
+ *
981
+ * The transfer siphon already runs for a REFER it terminates, reachable
982
+ * because *this app* decided: an IVR that has worked out where the caller
983
+ * should go, a controller handing a call from an AI to a human, a supervisor
984
+ * take-over. siphon dials `target` as a new leg on the same call, re-anchors
985
+ * the surviving party's media onto it, and once the target answers promotes
986
+ * it into the surviving pair and BYEs the leg it replaced.
987
+ *
988
+ * The replaced leg **stays up while the target rings**, so the surviving
989
+ * party hears ringback rather than silence, and a target that refuses or
990
+ * never answers leaves the call exactly as it was.
991
+ *
992
+ * `replaceALeg` picks the direction: omitted/`false` replaces the callee and
993
+ * keeps the caller, `true` does the reverse. `profile` names the media
994
+ * profile for the pair this creates — required when the call is anchored with
995
+ * a direction-bound one, whose answer half describes the party that is
996
+ * leaving. `timeout` bounds the ring in seconds (`0` = no ring policy, only
997
+ * siphon's guard against a target that answers nothing).
998
+ *
999
+ * Resolves as soon as the INVITE is on the wire
1000
+ * (`{channel, replacement: "dialing", target}`) and says nothing about the
1001
+ * target. Wait for the `PeerReplaced`
1002
+ * ({@link import("./protocol").PeerReplacedPayload}) or `ReplaceFailed`
1003
+ * ({@link import("./protocol").ReplaceFailedPayload}) event for the outcome —
1004
+ * acting on the reply alone would tear down a call whose replacement is still
1005
+ * ringing.
1006
+ *
1007
+ * Rejects with `code === "not_found"` (no such call), `"invalid_state"` (not
1008
+ * answered, no peer leg, or a replacement already in flight — all worth
1009
+ * retrying later) or `"bad_request"` (the target will not parse or route).
1010
+ */
1011
+ async replacePeer(target, options = {}) {
1012
+ const args = { target };
1013
+ if (options.nextHop !== void 0) args.next_hop = options.nextHop;
1014
+ if (options.replaceALeg !== void 0) args.replace_a_leg = options.replaceALeg;
1015
+ if (options.profile !== void 0) args.profile = options.profile;
1016
+ if (options.timeout !== void 0) args.timeout = options.timeout;
1017
+ return this.sip(SipVerb.ReplacePeer, args);
1018
+ }
895
1019
  /** Set a header on the stored A-leg INVITE. */
896
1020
  async setHeader(name, value) {
897
1021
  await this.sip(SipVerb.SetHeader, { name, value });
@@ -1120,6 +1244,42 @@ var SipClient = class _SipClient {
1120
1244
  describe() {
1121
1245
  return this.client.describe();
1122
1246
  }
1247
+ /**
1248
+ * Place an outbound call under a caller-supplied channel id.
1249
+ *
1250
+ * The one verb that *creates* a channel rather than addressing one, which is
1251
+ * why it lives here and not on {@link Call}. It resolves as soon as the
1252
+ * INVITE is on the wire — the call is `calling`, and the answer, failure or
1253
+ * timeout arrives later as an event on the channel.
1254
+ *
1255
+ * ```ts
1256
+ * const call = await client.originate(
1257
+ * "wake-up-42",
1258
+ * "sip:1001@pbx.example",
1259
+ * { anchor: true },
1260
+ * { from: "sip:alarm@pbx.example", timeout: 20 },
1261
+ * );
1262
+ * ```
1263
+ */
1264
+ async originate(channel, to, media, options) {
1265
+ const result = await this.client.command(
1266
+ MODULE_SIP,
1267
+ "originate",
1268
+ null,
1269
+ originateArgs(channel, to, media, options)
1270
+ );
1271
+ const text = (name) => {
1272
+ const value = result?.[name];
1273
+ return typeof value === "string" ? value : void 0;
1274
+ };
1275
+ return {
1276
+ // The server echoes the id back; fall back to the one we asked for
1277
+ // rather than returning an empty channel a caller cannot address.
1278
+ channel: text("channel") ?? channel,
1279
+ callId: text("call_id"),
1280
+ sipCallId: text("sip_call_id")
1281
+ };
1282
+ }
1123
1283
  /** Send a raw command on any module (the generic escape hatch). */
1124
1284
  command(module, verb, target, args) {
1125
1285
  return this.client.command(module, verb, target, args);
@@ -1190,7 +1350,9 @@ exports.SipVerb = SipVerb;
1190
1350
  exports.encodeCommand = encodeCommand;
1191
1351
  exports.isBridgeFinal = isBridgeFinal;
1192
1352
  exports.isTransferFinal = isTransferFinal;
1353
+ exports.originateArgs = originateArgs;
1193
1354
  exports.parseInboundFrame = parseInboundFrame;
1194
1355
  exports.sipEventKind = sipEventKind;
1356
+ exports.transferOutcome = transferOutcome;
1195
1357
  //# sourceMappingURL=index.cjs.map
1196
1358
  //# sourceMappingURL=index.cjs.map