@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.js CHANGED
@@ -119,6 +119,7 @@ var SipVerb = {
119
119
  RejectRefer: "reject_refer",
120
120
  Bridge: "bridge",
121
121
  Unbridge: "unbridge",
122
+ ReplacePeer: "replace_peer",
122
123
  Play: "play",
123
124
  Stop: "stop",
124
125
  Dtmf: "dtmf",
@@ -133,6 +134,12 @@ function sipEventKind(name) {
133
134
  function isTransferFinal(name) {
134
135
  return name === "TransferCompleted" || name === "TransferFailed";
135
136
  }
137
+ function transferOutcome(event) {
138
+ if (event.kind !== "TransferProgress" && event.kind !== "TransferCompleted" && event.kind !== "TransferFailed") {
139
+ return null;
140
+ }
141
+ return event.payload ?? null;
142
+ }
136
143
  function isBridgeFinal(name) {
137
144
  return name === "ChannelBridged" || name === "BridgeFailed";
138
145
  }
@@ -618,6 +625,9 @@ function routeTargetToWire(target) {
618
625
  if (target.timeout !== void 0) {
619
626
  object.timeout = target.timeout;
620
627
  }
628
+ if (target.rerouteAfterProgress === true) {
629
+ object.reroute_after_progress = true;
630
+ }
621
631
  return object;
622
632
  }
623
633
  function stringValue(result) {
@@ -629,6 +639,41 @@ function stringValue(result) {
629
639
  }
630
640
  return null;
631
641
  }
642
+ function originateArgs(channel, to, media, options) {
643
+ const args = { channel, to };
644
+ if ("anchor" in media) {
645
+ args.media = true;
646
+ if (media.profile !== void 0) args.profile = media.profile;
647
+ if (media.wsUri !== void 0) args.ws_uri = media.wsUri;
648
+ } else if ("sdp" in media) {
649
+ args.sdp = media.sdp;
650
+ } else {
651
+ args.body = media.body;
652
+ args.content_type = media.contentType;
653
+ }
654
+ if (!options) return args;
655
+ if (options.from !== void 0) args.from = options.from;
656
+ if (options.fromDisplay !== void 0) args.from_display = options.fromDisplay;
657
+ if (options.toDisplay !== void 0) args.to_display = options.toDisplay;
658
+ if (options.nextHop !== void 0) args.next_hop = options.nextHop;
659
+ if (options.pAssertedIdentity !== void 0) {
660
+ args.p_asserted_identity = options.pAssertedIdentity;
661
+ }
662
+ if (options.privacy !== void 0) args.privacy = options.privacy;
663
+ if (options.headers !== void 0) args.headers = options.headers;
664
+ if (options.timeout !== void 0) args.timeout = options.timeout;
665
+ if (options.onLost !== void 0) args.on_lost = options.onLost;
666
+ if (options.vars !== void 0) args.vars = options.vars;
667
+ if (options.sessionTimer !== void 0) {
668
+ const timer = {};
669
+ const { expires, minSe, refresher } = options.sessionTimer;
670
+ if (expires !== void 0) timer.expires = expires;
671
+ if (minSe !== void 0) timer.min_se = minSe;
672
+ if (refresher !== void 0) timer.refresher = refresher;
673
+ args.session_timer = timer;
674
+ }
675
+ return args;
676
+ }
632
677
  function playArgs(source, options) {
633
678
  const args = {};
634
679
  if ("file" in source) {
@@ -701,6 +746,41 @@ var Call = class {
701
746
  async answer(options) {
702
747
  await this.sip(SipVerb.Answer, options ? responseArgs(options) : {});
703
748
  }
749
+ /**
750
+ * Answer the parked A-leg **and** anchor its media to the media engine in one
751
+ * act — the verb form of the routing script's
752
+ * `call.handover(answer=True, profile=…, ws_uri=…)`.
753
+ *
754
+ * This is how an application that accepted an **un-answered** handover
755
+ * connects the call. It can already hold the call open for as long as its own
756
+ * policy says with {@link Call.ring}; what it could not do is connect the
757
+ * caller to anything, because a plain {@link Call.answer} sends a 2xx and
758
+ * anchors nothing. Answering first and attaching a stream afterwards is not
759
+ * the same thing: `received_from`, echo cancellation and the VAD engine are
760
+ * properties of the answer, not of a bridge attached after it.
761
+ *
762
+ * Synthesizing the RFC 3264 answer against the media engine is a siphon-rtp
763
+ * capability, so on rtpengine / rtpproxy this rejects with
764
+ * `code === "unavailable"` rather than sending a 200 with nothing behind it.
765
+ * On any media failure the 2xx is never sent and the call stays parked —
766
+ * retry with another profile, or reject it.
767
+ */
768
+ async answerAnchored(options) {
769
+ const args = { anchor: true };
770
+ if (options?.code !== void 0) {
771
+ args.code = options.code;
772
+ }
773
+ if (options?.reason !== void 0) {
774
+ args.reason = options.reason;
775
+ }
776
+ if (options?.profile !== void 0) {
777
+ args.profile = options.profile;
778
+ }
779
+ if (options?.wsUri !== void 0) {
780
+ args.ws_uri = options.wsUri;
781
+ }
782
+ await this.sip(SipVerb.Answer, args);
783
+ }
704
784
  /**
705
785
  * Send `180 Ringing`: alerting only, no early media.
706
786
  *
@@ -775,7 +855,9 @@ var Call = class {
775
855
  *
776
856
  * `targets` is a non-empty list of carriers tried cheapest-first: each entry
777
857
  * is a bare URI string or a {@link RouteTargetObject}
778
- * (`{uri, nextHop?, headers?, timeout?}`). `strategy` defaults to
858
+ * (`{uri, nextHop?, headers?, timeout?, rerouteAfterProgress?}`). A target
859
+ * that has shown progress keeps the call past its `timeout` unless it sets
860
+ * `rerouteAfterProgress`. `strategy` defaults to
779
861
  * `"sequential"` (v1 supports only sequential/single — anything else rejects
780
862
  * with `code === "unsupported_verb"`). `headers` is applied to every
781
863
  * attempt's B-leg INVITE.
@@ -886,6 +968,48 @@ var Call = class {
886
968
  async unbridge(reason) {
887
969
  return this.sip(SipVerb.Unbridge, reason !== void 0 ? { reason } : {});
888
970
  }
971
+ /**
972
+ * Replace one leg of this answered call with a freshly dialed target, with no
973
+ * REFER involved.
974
+ *
975
+ * The transfer siphon already runs for a REFER it terminates, reachable
976
+ * because *this app* decided: an IVR that has worked out where the caller
977
+ * should go, a controller handing a call from an AI to a human, a supervisor
978
+ * take-over. siphon dials `target` as a new leg on the same call, re-anchors
979
+ * the surviving party's media onto it, and once the target answers promotes
980
+ * it into the surviving pair and BYEs the leg it replaced.
981
+ *
982
+ * The replaced leg **stays up while the target rings**, so the surviving
983
+ * party hears ringback rather than silence, and a target that refuses or
984
+ * never answers leaves the call exactly as it was.
985
+ *
986
+ * `replaceALeg` picks the direction: omitted/`false` replaces the callee and
987
+ * keeps the caller, `true` does the reverse. `profile` names the media
988
+ * profile for the pair this creates — required when the call is anchored with
989
+ * a direction-bound one, whose answer half describes the party that is
990
+ * leaving. `timeout` bounds the ring in seconds (`0` = no ring policy, only
991
+ * siphon's guard against a target that answers nothing).
992
+ *
993
+ * Resolves as soon as the INVITE is on the wire
994
+ * (`{channel, replacement: "dialing", target}`) and says nothing about the
995
+ * target. Wait for the `PeerReplaced`
996
+ * ({@link import("./protocol").PeerReplacedPayload}) or `ReplaceFailed`
997
+ * ({@link import("./protocol").ReplaceFailedPayload}) event for the outcome —
998
+ * acting on the reply alone would tear down a call whose replacement is still
999
+ * ringing.
1000
+ *
1001
+ * Rejects with `code === "not_found"` (no such call), `"invalid_state"` (not
1002
+ * answered, no peer leg, or a replacement already in flight — all worth
1003
+ * retrying later) or `"bad_request"` (the target will not parse or route).
1004
+ */
1005
+ async replacePeer(target, options = {}) {
1006
+ const args = { target };
1007
+ if (options.nextHop !== void 0) args.next_hop = options.nextHop;
1008
+ if (options.replaceALeg !== void 0) args.replace_a_leg = options.replaceALeg;
1009
+ if (options.profile !== void 0) args.profile = options.profile;
1010
+ if (options.timeout !== void 0) args.timeout = options.timeout;
1011
+ return this.sip(SipVerb.ReplacePeer, args);
1012
+ }
889
1013
  /** Set a header on the stored A-leg INVITE. */
890
1014
  async setHeader(name, value) {
891
1015
  await this.sip(SipVerb.SetHeader, { name, value });
@@ -1114,6 +1238,42 @@ var SipClient = class _SipClient {
1114
1238
  describe() {
1115
1239
  return this.client.describe();
1116
1240
  }
1241
+ /**
1242
+ * Place an outbound call under a caller-supplied channel id.
1243
+ *
1244
+ * The one verb that *creates* a channel rather than addressing one, which is
1245
+ * why it lives here and not on {@link Call}. It resolves as soon as the
1246
+ * INVITE is on the wire — the call is `calling`, and the answer, failure or
1247
+ * timeout arrives later as an event on the channel.
1248
+ *
1249
+ * ```ts
1250
+ * const call = await client.originate(
1251
+ * "wake-up-42",
1252
+ * "sip:1001@pbx.example",
1253
+ * { anchor: true },
1254
+ * { from: "sip:alarm@pbx.example", timeout: 20 },
1255
+ * );
1256
+ * ```
1257
+ */
1258
+ async originate(channel, to, media, options) {
1259
+ const result = await this.client.command(
1260
+ MODULE_SIP,
1261
+ "originate",
1262
+ null,
1263
+ originateArgs(channel, to, media, options)
1264
+ );
1265
+ const text = (name) => {
1266
+ const value = result?.[name];
1267
+ return typeof value === "string" ? value : void 0;
1268
+ };
1269
+ return {
1270
+ // The server echoes the id back; fall back to the one we asked for
1271
+ // rather than returning an empty channel a caller cannot address.
1272
+ channel: text("channel") ?? channel,
1273
+ callId: text("call_id"),
1274
+ sipCallId: text("sip_call_id")
1275
+ };
1276
+ }
1117
1277
  /** Send a raw command on any module (the generic escape hatch). */
1118
1278
  command(module, verb, target, args) {
1119
1279
  return this.client.command(module, verb, target, args);
@@ -1162,6 +1322,6 @@ var SipServer = class _SipServer {
1162
1322
  }
1163
1323
  };
1164
1324
 
1165
- export { Call, CallStream, ControlClient, ControlError, ControlServer, DESCRIBE, EventStream, GET_VAR, HELLO, MODULE_SIP, MODULE_SMPP, MODULE_SS7, PROTOCOL_VERSION, RESYNC, SET_VAR, SUBPROTOCOL, SipClient, SipServer, SipVerb, encodeCommand, isBridgeFinal, isTransferFinal, parseInboundFrame, sipEventKind };
1325
+ export { Call, CallStream, ControlClient, ControlError, ControlServer, DESCRIBE, EventStream, GET_VAR, HELLO, MODULE_SIP, MODULE_SMPP, MODULE_SS7, PROTOCOL_VERSION, RESYNC, SET_VAR, SUBPROTOCOL, SipClient, SipServer, SipVerb, encodeCommand, isBridgeFinal, isTransferFinal, originateArgs, parseInboundFrame, sipEventKind, transferOutcome };
1166
1326
  //# sourceMappingURL=index.js.map
1167
1327
  //# sourceMappingURL=index.js.map