@siphon-project/control 0.1.2 → 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.js CHANGED
@@ -101,6 +101,12 @@ function parseInboundFrame(text) {
101
101
  }
102
102
  var SipVerb = {
103
103
  Answer: "answer",
104
+ /**
105
+ * `180 Ringing` — alerting only, no early media (RFC 3261 §13.2.1). A body is
106
+ * refused: SDP on an 18x is early media (RFC 3960 §3.1), which is
107
+ * {@link SipVerb.Progress}'s job.
108
+ */
109
+ Ring: "ring",
104
110
  Progress: "progress",
105
111
  Reject: "reject",
106
112
  Hangup: "hangup",
@@ -111,6 +117,9 @@ var SipVerb = {
111
117
  RemoveHeader: "remove_header",
112
118
  AcceptRefer: "accept_refer",
113
119
  RejectRefer: "reject_refer",
120
+ Bridge: "bridge",
121
+ Unbridge: "unbridge",
122
+ ReplacePeer: "replace_peer",
114
123
  Play: "play",
115
124
  Stop: "stop",
116
125
  Dtmf: "dtmf",
@@ -122,6 +131,18 @@ var SipVerb = {
122
131
  function sipEventKind(name) {
123
132
  return name;
124
133
  }
134
+ function isTransferFinal(name) {
135
+ return name === "TransferCompleted" || name === "TransferFailed";
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
+ }
143
+ function isBridgeFinal(name) {
144
+ return name === "ChannelBridged" || name === "BridgeFailed";
145
+ }
125
146
 
126
147
  // src/internal.ts
127
148
  var AsyncQueue = class {
@@ -687,7 +708,57 @@ var Call = class {
687
708
  async answer(options) {
688
709
  await this.sip(SipVerb.Answer, options ? responseArgs(options) : {});
689
710
  }
690
- /** Send a UAS 1xx / early media (default `183 Session Progress`). */
711
+ /**
712
+ * Answer the parked A-leg **and** anchor its media to the media engine in one
713
+ * act — the verb form of the routing script's
714
+ * `call.handover(answer=True, profile=…, ws_uri=…)`.
715
+ *
716
+ * This is how an application that accepted an **un-answered** handover
717
+ * connects the call. It can already hold the call open for as long as its own
718
+ * policy says with {@link Call.ring}; what it could not do is connect the
719
+ * caller to anything, because a plain {@link Call.answer} sends a 2xx and
720
+ * anchors nothing. Answering first and attaching a stream afterwards is not
721
+ * the same thing: `received_from`, echo cancellation and the VAD engine are
722
+ * properties of the answer, not of a bridge attached after it.
723
+ *
724
+ * Synthesizing the RFC 3264 answer against the media engine is a siphon-rtp
725
+ * capability, so on rtpengine / rtpproxy this rejects with
726
+ * `code === "unavailable"` rather than sending a 200 with nothing behind it.
727
+ * On any media failure the 2xx is never sent and the call stays parked —
728
+ * retry with another profile, or reject it.
729
+ */
730
+ async answerAnchored(options) {
731
+ const args = { anchor: true };
732
+ if (options?.code !== void 0) {
733
+ args.code = options.code;
734
+ }
735
+ if (options?.reason !== void 0) {
736
+ args.reason = options.reason;
737
+ }
738
+ if (options?.profile !== void 0) {
739
+ args.profile = options.profile;
740
+ }
741
+ if (options?.wsUri !== void 0) {
742
+ args.ws_uri = options.wsUri;
743
+ }
744
+ await this.sip(SipVerb.Answer, args);
745
+ }
746
+ /**
747
+ * Send `180 Ringing`: alerting only, no early media.
748
+ *
749
+ * RFC 3261 §13.2.1 makes the 180 the "callee is being alerted" signal, and
750
+ * RFC 3960 §3.1 puts early media on a response that carries SDP — two
751
+ * different acts, so two verbs. Ring for as long as your own policy says,
752
+ * then {@link Call.answer}; open an early-media path with
753
+ * {@link Call.progress}.
754
+ */
755
+ async ring(reason) {
756
+ await this.sip(SipVerb.Ring, reason !== void 0 ? { reason } : {});
757
+ }
758
+ /**
759
+ * Send a UAS 1xx, optionally opening an early-media path with SDP (default
760
+ * `183 Session Progress`). For plain alerting use {@link Call.ring}.
761
+ */
691
762
  async progress(options) {
692
763
  await this.sip(SipVerb.Progress, options ? responseArgs(options) : {});
693
764
  }
@@ -710,7 +781,17 @@ var Call = class {
710
781
  async hangup(reason) {
711
782
  await this.terminate(reason);
712
783
  }
713
- /** Send an in-dialog REFER on the A-leg (blind transfer). */
784
+ /**
785
+ * Send an in-dialog REFER on the A-leg (blind transfer).
786
+ *
787
+ * Resolves as soon as siphon has sent the REFER — that is *sent*, not
788
+ * *transferred*. RFC 3515 §2.4.4 delivers the outcome afterwards on the
789
+ * implicit subscription, so read it off {@link Call.events}: zero or more
790
+ * `TransferProgress`, then exactly one `TransferCompleted` /
791
+ * `TransferFailed`, each carrying a
792
+ * {@link import("./protocol").TransferOutcomePayload}. Use
793
+ * {@link import("./protocol").isTransferFinal} to know when to stop waiting.
794
+ */
714
795
  async refer(to) {
715
796
  await this.sip(SipVerb.Refer, { to });
716
797
  }
@@ -761,6 +842,9 @@ var Call = class {
761
842
  * egress, and `mode` (`"terminate"` / `"transparent"`) overrides
762
843
  * `b2bua.default_refer_mode`. No pending REFER (already decided, timed out, or
763
844
  * the call is gone) rejects with `code === "not_found"`.
845
+ *
846
+ * `profile` names the media profile for the pairing the transfer creates —
847
+ * see {@link AcceptReferOptions.profile}, which is required at an SRTP edge.
764
848
  */
765
849
  async acceptRefer(options) {
766
850
  const args = {};
@@ -773,6 +857,9 @@ var Call = class {
773
857
  if (options?.mode !== void 0) {
774
858
  args.mode = options.mode;
775
859
  }
860
+ if (options?.profile !== void 0) {
861
+ args.profile = options.profile;
862
+ }
776
863
  await this.sip(SipVerb.AcceptRefer, args);
777
864
  }
778
865
  /**
@@ -786,6 +873,103 @@ var Call = class {
786
873
  }
787
874
  await this.sip(SipVerb.RejectRefer, args);
788
875
  }
876
+ /**
877
+ * Join this call to another leg the app owns, so the two parties hear each
878
+ * other.
879
+ *
880
+ * **This call is the anchor.** It keeps its media session — its ports and
881
+ * everything attached to them; the `withChannel` leg's own media session is
882
+ * deleted and it becomes the second party on this one's. So bridge *into* the
883
+ * leg whose media you want to keep (the one being recorded, teed, or carrying
884
+ * the prompt).
885
+ *
886
+ * Both legs must already be answered. `options.onPeerHangup` says what happens
887
+ * to the survivor when its partner hangs up (see
888
+ * {@link import("./protocol").PeerHangupPolicy}); omitted means `"hangup"`.
889
+ *
890
+ * Resolves as soon as the media has been re-pointed and the first re-INVITE is
891
+ * on the wire — that is *offered*, not *bridged*. A bridge is two RFC 3261 §14
892
+ * re-INVITEs across two dialogs, so the outcome arrives on {@link Call.events}
893
+ * instead: exactly one `ChannelBridged`
894
+ * ({@link import("./protocol").ChannelBridgedPayload}) / `BridgeFailed`
895
+ * ({@link import("./protocol").BridgeFailedPayload}), on **both** channels.
896
+ * {@link import("./protocol").isBridgeFinal} says when to stop waiting.
897
+ *
898
+ * Resolves to the reply `result` (`{channel, with, call_id, peer_call_id,
899
+ * anchored, on_peer_hangup, state: "bridging"}`). Rejects with a `code` a
900
+ * caller can act on: `"not_found"` (no such leg), `"invalid_state"` (a leg has
901
+ * not answered, is already bridged, has a re-INVITE outstanding, or carries no
902
+ * media description), `"bad_request"` (the same leg named twice, or a bad
903
+ * `onPeerHangup`), `"forbidden"` (the other channel belongs to another app),
904
+ * `"unsupported_verb"` (the media backend cannot express it).
905
+ */
906
+ async bridge(withChannel, options) {
907
+ const args = { with: withChannel };
908
+ if (options?.onPeerHangup !== void 0) {
909
+ args.on_peer_hangup = options.onPeerHangup;
910
+ }
911
+ return this.sip(SipVerb.Bridge, args);
912
+ }
913
+ /**
914
+ * Break this call's bridge.
915
+ *
916
+ * Both legs stay answered, owned and held — re-offered `a=sendonly`
917
+ * (RFC 3264 §8.4, which RFC 6337 §3.1 prefers to `c=0.0.0.0`). Neither is hung
918
+ * up: that would be indistinguishable from two hangups and would take away the
919
+ * calls the app still owns. A later {@link Call.bridge} re-offers `sendrecv`.
920
+ *
921
+ * `reason` is free text carried on the `ChannelUnbridged`
922
+ * ({@link import("./protocol").ChannelUnbridgedPayload}) event both channels
923
+ * receive; omitted means `"unbridged"`. Resolves to the reply `result`
924
+ * (`{channel, with, reason, state: "unbridged"}`), where `with` is the channel
925
+ * id of the leg that was on the other side. A call that is not bridged rejects
926
+ * with `code === "invalid_state"`.
927
+ */
928
+ async unbridge(reason) {
929
+ return this.sip(SipVerb.Unbridge, reason !== void 0 ? { reason } : {});
930
+ }
931
+ /**
932
+ * Replace one leg of this answered call with a freshly dialed target, with no
933
+ * REFER involved.
934
+ *
935
+ * The transfer siphon already runs for a REFER it terminates, reachable
936
+ * because *this app* decided: an IVR that has worked out where the caller
937
+ * should go, a controller handing a call from an AI to a human, a supervisor
938
+ * take-over. siphon dials `target` as a new leg on the same call, re-anchors
939
+ * the surviving party's media onto it, and once the target answers promotes
940
+ * it into the surviving pair and BYEs the leg it replaced.
941
+ *
942
+ * The replaced leg **stays up while the target rings**, so the surviving
943
+ * party hears ringback rather than silence, and a target that refuses or
944
+ * never answers leaves the call exactly as it was.
945
+ *
946
+ * `replaceALeg` picks the direction: omitted/`false` replaces the callee and
947
+ * keeps the caller, `true` does the reverse. `profile` names the media
948
+ * profile for the pair this creates — required when the call is anchored with
949
+ * a direction-bound one, whose answer half describes the party that is
950
+ * leaving. `timeout` bounds the ring in seconds (`0` = no ring policy, only
951
+ * siphon's guard against a target that answers nothing).
952
+ *
953
+ * Resolves as soon as the INVITE is on the wire
954
+ * (`{channel, replacement: "dialing", target}`) and says nothing about the
955
+ * target. Wait for the `PeerReplaced`
956
+ * ({@link import("./protocol").PeerReplacedPayload}) or `ReplaceFailed`
957
+ * ({@link import("./protocol").ReplaceFailedPayload}) event for the outcome —
958
+ * acting on the reply alone would tear down a call whose replacement is still
959
+ * ringing.
960
+ *
961
+ * Rejects with `code === "not_found"` (no such call), `"invalid_state"` (not
962
+ * answered, no peer leg, or a replacement already in flight — all worth
963
+ * retrying later) or `"bad_request"` (the target will not parse or route).
964
+ */
965
+ async replacePeer(target, options = {}) {
966
+ const args = { target };
967
+ if (options.nextHop !== void 0) args.next_hop = options.nextHop;
968
+ if (options.replaceALeg !== void 0) args.replace_a_leg = options.replaceALeg;
969
+ if (options.profile !== void 0) args.profile = options.profile;
970
+ if (options.timeout !== void 0) args.timeout = options.timeout;
971
+ return this.sip(SipVerb.ReplacePeer, args);
972
+ }
789
973
  /** Set a header on the stored A-leg INVITE. */
790
974
  async setHeader(name, value) {
791
975
  await this.sip(SipVerb.SetHeader, { name, value });
@@ -868,7 +1052,8 @@ var Call = class {
868
1052
  }
869
1053
  /**
870
1054
  * Await the next event for this call (`ChannelStateChange`,
871
- * `ChannelHangupRequest`, `StasisEnd`). `null` once the stream closes.
1055
+ * `ChannelHangupRequest`, `ChannelBridged`, `BridgeFailed`,
1056
+ * `ChannelUnbridged`, `StasisEnd`). `null` once the stream closes.
872
1057
  */
873
1058
  nextEvent() {
874
1059
  return this.eventQueue.next();
@@ -1061,6 +1246,6 @@ var SipServer = class _SipServer {
1061
1246
  }
1062
1247
  };
1063
1248
 
1064
- 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, parseInboundFrame, sipEventKind };
1249
+ 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, transferOutcome };
1065
1250
  //# sourceMappingURL=index.js.map
1066
1251
  //# sourceMappingURL=index.js.map