@siphon-project/control 0.1.3 → 0.2.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
  }
@@ -707,6 +714,41 @@ var Call = class {
707
714
  async answer(options) {
708
715
  await this.sip(SipVerb.Answer, options ? responseArgs(options) : {});
709
716
  }
717
+ /**
718
+ * Answer the parked A-leg **and** anchor its media to the media engine in one
719
+ * act — the verb form of the routing script's
720
+ * `call.handover(answer=True, profile=…, ws_uri=…)`.
721
+ *
722
+ * This is how an application that accepted an **un-answered** handover
723
+ * connects the call. It can already hold the call open for as long as its own
724
+ * policy says with {@link Call.ring}; what it could not do is connect the
725
+ * caller to anything, because a plain {@link Call.answer} sends a 2xx and
726
+ * anchors nothing. Answering first and attaching a stream afterwards is not
727
+ * the same thing: `received_from`, echo cancellation and the VAD engine are
728
+ * properties of the answer, not of a bridge attached after it.
729
+ *
730
+ * Synthesizing the RFC 3264 answer against the media engine is a siphon-rtp
731
+ * capability, so on rtpengine / rtpproxy this rejects with
732
+ * `code === "unavailable"` rather than sending a 200 with nothing behind it.
733
+ * On any media failure the 2xx is never sent and the call stays parked —
734
+ * retry with another profile, or reject it.
735
+ */
736
+ async answerAnchored(options) {
737
+ const args = { anchor: true };
738
+ if (options?.code !== void 0) {
739
+ args.code = options.code;
740
+ }
741
+ if (options?.reason !== void 0) {
742
+ args.reason = options.reason;
743
+ }
744
+ if (options?.profile !== void 0) {
745
+ args.profile = options.profile;
746
+ }
747
+ if (options?.wsUri !== void 0) {
748
+ args.ws_uri = options.wsUri;
749
+ }
750
+ await this.sip(SipVerb.Answer, args);
751
+ }
710
752
  /**
711
753
  * Send `180 Ringing`: alerting only, no early media.
712
754
  *
@@ -892,6 +934,48 @@ var Call = class {
892
934
  async unbridge(reason) {
893
935
  return this.sip(SipVerb.Unbridge, reason !== void 0 ? { reason } : {});
894
936
  }
937
+ /**
938
+ * Replace one leg of this answered call with a freshly dialed target, with no
939
+ * REFER involved.
940
+ *
941
+ * The transfer siphon already runs for a REFER it terminates, reachable
942
+ * because *this app* decided: an IVR that has worked out where the caller
943
+ * should go, a controller handing a call from an AI to a human, a supervisor
944
+ * take-over. siphon dials `target` as a new leg on the same call, re-anchors
945
+ * the surviving party's media onto it, and once the target answers promotes
946
+ * it into the surviving pair and BYEs the leg it replaced.
947
+ *
948
+ * The replaced leg **stays up while the target rings**, so the surviving
949
+ * party hears ringback rather than silence, and a target that refuses or
950
+ * never answers leaves the call exactly as it was.
951
+ *
952
+ * `replaceALeg` picks the direction: omitted/`false` replaces the callee and
953
+ * keeps the caller, `true` does the reverse. `profile` names the media
954
+ * profile for the pair this creates — required when the call is anchored with
955
+ * a direction-bound one, whose answer half describes the party that is
956
+ * leaving. `timeout` bounds the ring in seconds (`0` = no ring policy, only
957
+ * siphon's guard against a target that answers nothing).
958
+ *
959
+ * Resolves as soon as the INVITE is on the wire
960
+ * (`{channel, replacement: "dialing", target}`) and says nothing about the
961
+ * target. Wait for the `PeerReplaced`
962
+ * ({@link import("./protocol").PeerReplacedPayload}) or `ReplaceFailed`
963
+ * ({@link import("./protocol").ReplaceFailedPayload}) event for the outcome —
964
+ * acting on the reply alone would tear down a call whose replacement is still
965
+ * ringing.
966
+ *
967
+ * Rejects with `code === "not_found"` (no such call), `"invalid_state"` (not
968
+ * answered, no peer leg, or a replacement already in flight — all worth
969
+ * retrying later) or `"bad_request"` (the target will not parse or route).
970
+ */
971
+ async replacePeer(target, options = {}) {
972
+ const args = { target };
973
+ if (options.nextHop !== void 0) args.next_hop = options.nextHop;
974
+ if (options.replaceALeg !== void 0) args.replace_a_leg = options.replaceALeg;
975
+ if (options.profile !== void 0) args.profile = options.profile;
976
+ if (options.timeout !== void 0) args.timeout = options.timeout;
977
+ return this.sip(SipVerb.ReplacePeer, args);
978
+ }
895
979
  /** Set a header on the stored A-leg INVITE. */
896
980
  async setHeader(name, value) {
897
981
  await this.sip(SipVerb.SetHeader, { name, value });
@@ -1192,5 +1276,6 @@ exports.isBridgeFinal = isBridgeFinal;
1192
1276
  exports.isTransferFinal = isTransferFinal;
1193
1277
  exports.parseInboundFrame = parseInboundFrame;
1194
1278
  exports.sipEventKind = sipEventKind;
1279
+ exports.transferOutcome = transferOutcome;
1195
1280
  //# sourceMappingURL=index.cjs.map
1196
1281
  //# sourceMappingURL=index.cjs.map