@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/README.md CHANGED
@@ -108,6 +108,8 @@ await client.command("sip", "answer", { channel: "ch1" }, { code: 200 });
108
108
  | `removeHeader(name)` | `remove_header` (`sip`) | ‡ |
109
109
  | `acceptRefer(options?)` | `accept_refer` (`sip`) | ‡ |
110
110
  | `rejectRefer(code, reason?)` | `reject_refer` (`sip`) | ‡ |
111
+ | `bridge(withChannel, options?)` | `bridge` (`sip`) | join two answered legs; the verdict arrives as `ChannelBridged` / `BridgeFailed` |
112
+ | `unbridge(reason?)` | `unbridge` (`sip`) | break the bridge — both legs stay answered, owned and held |
111
113
  | `playFile(file)` | `play` (`sip`) | ‡ media |
112
114
  | `dtmf(digits)` | `dtmf` (`sip`) | ‡ media |
113
115
  | `command(verb, args?)` | (`sip`) | arbitrary SIP-adapter verb |
package/dist/index.cjs CHANGED
@@ -107,6 +107,12 @@ function parseInboundFrame(text) {
107
107
  }
108
108
  var SipVerb = {
109
109
  Answer: "answer",
110
+ /**
111
+ * `180 Ringing` — alerting only, no early media (RFC 3261 §13.2.1). A body is
112
+ * refused: SDP on an 18x is early media (RFC 3960 §3.1), which is
113
+ * {@link SipVerb.Progress}'s job.
114
+ */
115
+ Ring: "ring",
110
116
  Progress: "progress",
111
117
  Reject: "reject",
112
118
  Hangup: "hangup",
@@ -117,6 +123,9 @@ var SipVerb = {
117
123
  RemoveHeader: "remove_header",
118
124
  AcceptRefer: "accept_refer",
119
125
  RejectRefer: "reject_refer",
126
+ Bridge: "bridge",
127
+ Unbridge: "unbridge",
128
+ ReplacePeer: "replace_peer",
120
129
  Play: "play",
121
130
  Stop: "stop",
122
131
  Dtmf: "dtmf",
@@ -128,6 +137,18 @@ var SipVerb = {
128
137
  function sipEventKind(name) {
129
138
  return name;
130
139
  }
140
+ function isTransferFinal(name) {
141
+ return name === "TransferCompleted" || name === "TransferFailed";
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
+ }
149
+ function isBridgeFinal(name) {
150
+ return name === "ChannelBridged" || name === "BridgeFailed";
151
+ }
131
152
 
132
153
  // src/internal.ts
133
154
  var AsyncQueue = class {
@@ -693,7 +714,57 @@ var Call = class {
693
714
  async answer(options) {
694
715
  await this.sip(SipVerb.Answer, options ? responseArgs(options) : {});
695
716
  }
696
- /** Send a UAS 1xx / early media (default `183 Session Progress`). */
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
+ }
752
+ /**
753
+ * Send `180 Ringing`: alerting only, no early media.
754
+ *
755
+ * RFC 3261 §13.2.1 makes the 180 the "callee is being alerted" signal, and
756
+ * RFC 3960 §3.1 puts early media on a response that carries SDP — two
757
+ * different acts, so two verbs. Ring for as long as your own policy says,
758
+ * then {@link Call.answer}; open an early-media path with
759
+ * {@link Call.progress}.
760
+ */
761
+ async ring(reason) {
762
+ await this.sip(SipVerb.Ring, reason !== void 0 ? { reason } : {});
763
+ }
764
+ /**
765
+ * Send a UAS 1xx, optionally opening an early-media path with SDP (default
766
+ * `183 Session Progress`). For plain alerting use {@link Call.ring}.
767
+ */
697
768
  async progress(options) {
698
769
  await this.sip(SipVerb.Progress, options ? responseArgs(options) : {});
699
770
  }
@@ -716,7 +787,17 @@ var Call = class {
716
787
  async hangup(reason) {
717
788
  await this.terminate(reason);
718
789
  }
719
- /** Send an in-dialog REFER on the A-leg (blind transfer). */
790
+ /**
791
+ * Send an in-dialog REFER on the A-leg (blind transfer).
792
+ *
793
+ * Resolves as soon as siphon has sent the REFER — that is *sent*, not
794
+ * *transferred*. RFC 3515 §2.4.4 delivers the outcome afterwards on the
795
+ * implicit subscription, so read it off {@link Call.events}: zero or more
796
+ * `TransferProgress`, then exactly one `TransferCompleted` /
797
+ * `TransferFailed`, each carrying a
798
+ * {@link import("./protocol").TransferOutcomePayload}. Use
799
+ * {@link import("./protocol").isTransferFinal} to know when to stop waiting.
800
+ */
720
801
  async refer(to) {
721
802
  await this.sip(SipVerb.Refer, { to });
722
803
  }
@@ -767,6 +848,9 @@ var Call = class {
767
848
  * egress, and `mode` (`"terminate"` / `"transparent"`) overrides
768
849
  * `b2bua.default_refer_mode`. No pending REFER (already decided, timed out, or
769
850
  * the call is gone) rejects with `code === "not_found"`.
851
+ *
852
+ * `profile` names the media profile for the pairing the transfer creates —
853
+ * see {@link AcceptReferOptions.profile}, which is required at an SRTP edge.
770
854
  */
771
855
  async acceptRefer(options) {
772
856
  const args = {};
@@ -779,6 +863,9 @@ var Call = class {
779
863
  if (options?.mode !== void 0) {
780
864
  args.mode = options.mode;
781
865
  }
866
+ if (options?.profile !== void 0) {
867
+ args.profile = options.profile;
868
+ }
782
869
  await this.sip(SipVerb.AcceptRefer, args);
783
870
  }
784
871
  /**
@@ -792,6 +879,103 @@ var Call = class {
792
879
  }
793
880
  await this.sip(SipVerb.RejectRefer, args);
794
881
  }
882
+ /**
883
+ * Join this call to another leg the app owns, so the two parties hear each
884
+ * other.
885
+ *
886
+ * **This call is the anchor.** It keeps its media session — its ports and
887
+ * everything attached to them; the `withChannel` leg's own media session is
888
+ * deleted and it becomes the second party on this one's. So bridge *into* the
889
+ * leg whose media you want to keep (the one being recorded, teed, or carrying
890
+ * the prompt).
891
+ *
892
+ * Both legs must already be answered. `options.onPeerHangup` says what happens
893
+ * to the survivor when its partner hangs up (see
894
+ * {@link import("./protocol").PeerHangupPolicy}); omitted means `"hangup"`.
895
+ *
896
+ * Resolves as soon as the media has been re-pointed and the first re-INVITE is
897
+ * on the wire — that is *offered*, not *bridged*. A bridge is two RFC 3261 §14
898
+ * re-INVITEs across two dialogs, so the outcome arrives on {@link Call.events}
899
+ * instead: exactly one `ChannelBridged`
900
+ * ({@link import("./protocol").ChannelBridgedPayload}) / `BridgeFailed`
901
+ * ({@link import("./protocol").BridgeFailedPayload}), on **both** channels.
902
+ * {@link import("./protocol").isBridgeFinal} says when to stop waiting.
903
+ *
904
+ * Resolves to the reply `result` (`{channel, with, call_id, peer_call_id,
905
+ * anchored, on_peer_hangup, state: "bridging"}`). Rejects with a `code` a
906
+ * caller can act on: `"not_found"` (no such leg), `"invalid_state"` (a leg has
907
+ * not answered, is already bridged, has a re-INVITE outstanding, or carries no
908
+ * media description), `"bad_request"` (the same leg named twice, or a bad
909
+ * `onPeerHangup`), `"forbidden"` (the other channel belongs to another app),
910
+ * `"unsupported_verb"` (the media backend cannot express it).
911
+ */
912
+ async bridge(withChannel, options) {
913
+ const args = { with: withChannel };
914
+ if (options?.onPeerHangup !== void 0) {
915
+ args.on_peer_hangup = options.onPeerHangup;
916
+ }
917
+ return this.sip(SipVerb.Bridge, args);
918
+ }
919
+ /**
920
+ * Break this call's bridge.
921
+ *
922
+ * Both legs stay answered, owned and held — re-offered `a=sendonly`
923
+ * (RFC 3264 §8.4, which RFC 6337 §3.1 prefers to `c=0.0.0.0`). Neither is hung
924
+ * up: that would be indistinguishable from two hangups and would take away the
925
+ * calls the app still owns. A later {@link Call.bridge} re-offers `sendrecv`.
926
+ *
927
+ * `reason` is free text carried on the `ChannelUnbridged`
928
+ * ({@link import("./protocol").ChannelUnbridgedPayload}) event both channels
929
+ * receive; omitted means `"unbridged"`. Resolves to the reply `result`
930
+ * (`{channel, with, reason, state: "unbridged"}`), where `with` is the channel
931
+ * id of the leg that was on the other side. A call that is not bridged rejects
932
+ * with `code === "invalid_state"`.
933
+ */
934
+ async unbridge(reason) {
935
+ return this.sip(SipVerb.Unbridge, reason !== void 0 ? { reason } : {});
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
+ }
795
979
  /** Set a header on the stored A-leg INVITE. */
796
980
  async setHeader(name, value) {
797
981
  await this.sip(SipVerb.SetHeader, { name, value });
@@ -874,7 +1058,8 @@ var Call = class {
874
1058
  }
875
1059
  /**
876
1060
  * Await the next event for this call (`ChannelStateChange`,
877
- * `ChannelHangupRequest`, `StasisEnd`). `null` once the stream closes.
1061
+ * `ChannelHangupRequest`, `ChannelBridged`, `BridgeFailed`,
1062
+ * `ChannelUnbridged`, `StasisEnd`). `null` once the stream closes.
878
1063
  */
879
1064
  nextEvent() {
880
1065
  return this.eventQueue.next();
@@ -1087,7 +1272,10 @@ exports.SipClient = SipClient;
1087
1272
  exports.SipServer = SipServer;
1088
1273
  exports.SipVerb = SipVerb;
1089
1274
  exports.encodeCommand = encodeCommand;
1275
+ exports.isBridgeFinal = isBridgeFinal;
1276
+ exports.isTransferFinal = isTransferFinal;
1090
1277
  exports.parseInboundFrame = parseInboundFrame;
1091
1278
  exports.sipEventKind = sipEventKind;
1279
+ exports.transferOutcome = transferOutcome;
1092
1280
  //# sourceMappingURL=index.cjs.map
1093
1281
  //# sourceMappingURL=index.cjs.map