@siphon-project/control 0.1.2 → 0.1.3

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,8 @@ var SipVerb = {
117
123
  RemoveHeader: "remove_header",
118
124
  AcceptRefer: "accept_refer",
119
125
  RejectRefer: "reject_refer",
126
+ Bridge: "bridge",
127
+ Unbridge: "unbridge",
120
128
  Play: "play",
121
129
  Stop: "stop",
122
130
  Dtmf: "dtmf",
@@ -128,6 +136,12 @@ var SipVerb = {
128
136
  function sipEventKind(name) {
129
137
  return name;
130
138
  }
139
+ function isTransferFinal(name) {
140
+ return name === "TransferCompleted" || name === "TransferFailed";
141
+ }
142
+ function isBridgeFinal(name) {
143
+ return name === "ChannelBridged" || name === "BridgeFailed";
144
+ }
131
145
 
132
146
  // src/internal.ts
133
147
  var AsyncQueue = class {
@@ -693,7 +707,22 @@ var Call = class {
693
707
  async answer(options) {
694
708
  await this.sip(SipVerb.Answer, options ? responseArgs(options) : {});
695
709
  }
696
- /** Send a UAS 1xx / early media (default `183 Session Progress`). */
710
+ /**
711
+ * Send `180 Ringing`: alerting only, no early media.
712
+ *
713
+ * RFC 3261 §13.2.1 makes the 180 the "callee is being alerted" signal, and
714
+ * RFC 3960 §3.1 puts early media on a response that carries SDP — two
715
+ * different acts, so two verbs. Ring for as long as your own policy says,
716
+ * then {@link Call.answer}; open an early-media path with
717
+ * {@link Call.progress}.
718
+ */
719
+ async ring(reason) {
720
+ await this.sip(SipVerb.Ring, reason !== void 0 ? { reason } : {});
721
+ }
722
+ /**
723
+ * Send a UAS 1xx, optionally opening an early-media path with SDP (default
724
+ * `183 Session Progress`). For plain alerting use {@link Call.ring}.
725
+ */
697
726
  async progress(options) {
698
727
  await this.sip(SipVerb.Progress, options ? responseArgs(options) : {});
699
728
  }
@@ -716,7 +745,17 @@ var Call = class {
716
745
  async hangup(reason) {
717
746
  await this.terminate(reason);
718
747
  }
719
- /** Send an in-dialog REFER on the A-leg (blind transfer). */
748
+ /**
749
+ * Send an in-dialog REFER on the A-leg (blind transfer).
750
+ *
751
+ * Resolves as soon as siphon has sent the REFER — that is *sent*, not
752
+ * *transferred*. RFC 3515 §2.4.4 delivers the outcome afterwards on the
753
+ * implicit subscription, so read it off {@link Call.events}: zero or more
754
+ * `TransferProgress`, then exactly one `TransferCompleted` /
755
+ * `TransferFailed`, each carrying a
756
+ * {@link import("./protocol").TransferOutcomePayload}. Use
757
+ * {@link import("./protocol").isTransferFinal} to know when to stop waiting.
758
+ */
720
759
  async refer(to) {
721
760
  await this.sip(SipVerb.Refer, { to });
722
761
  }
@@ -767,6 +806,9 @@ var Call = class {
767
806
  * egress, and `mode` (`"terminate"` / `"transparent"`) overrides
768
807
  * `b2bua.default_refer_mode`. No pending REFER (already decided, timed out, or
769
808
  * the call is gone) rejects with `code === "not_found"`.
809
+ *
810
+ * `profile` names the media profile for the pairing the transfer creates —
811
+ * see {@link AcceptReferOptions.profile}, which is required at an SRTP edge.
770
812
  */
771
813
  async acceptRefer(options) {
772
814
  const args = {};
@@ -779,6 +821,9 @@ var Call = class {
779
821
  if (options?.mode !== void 0) {
780
822
  args.mode = options.mode;
781
823
  }
824
+ if (options?.profile !== void 0) {
825
+ args.profile = options.profile;
826
+ }
782
827
  await this.sip(SipVerb.AcceptRefer, args);
783
828
  }
784
829
  /**
@@ -792,6 +837,61 @@ var Call = class {
792
837
  }
793
838
  await this.sip(SipVerb.RejectRefer, args);
794
839
  }
840
+ /**
841
+ * Join this call to another leg the app owns, so the two parties hear each
842
+ * other.
843
+ *
844
+ * **This call is the anchor.** It keeps its media session — its ports and
845
+ * everything attached to them; the `withChannel` leg's own media session is
846
+ * deleted and it becomes the second party on this one's. So bridge *into* the
847
+ * leg whose media you want to keep (the one being recorded, teed, or carrying
848
+ * the prompt).
849
+ *
850
+ * Both legs must already be answered. `options.onPeerHangup` says what happens
851
+ * to the survivor when its partner hangs up (see
852
+ * {@link import("./protocol").PeerHangupPolicy}); omitted means `"hangup"`.
853
+ *
854
+ * Resolves as soon as the media has been re-pointed and the first re-INVITE is
855
+ * on the wire — that is *offered*, not *bridged*. A bridge is two RFC 3261 §14
856
+ * re-INVITEs across two dialogs, so the outcome arrives on {@link Call.events}
857
+ * instead: exactly one `ChannelBridged`
858
+ * ({@link import("./protocol").ChannelBridgedPayload}) / `BridgeFailed`
859
+ * ({@link import("./protocol").BridgeFailedPayload}), on **both** channels.
860
+ * {@link import("./protocol").isBridgeFinal} says when to stop waiting.
861
+ *
862
+ * Resolves to the reply `result` (`{channel, with, call_id, peer_call_id,
863
+ * anchored, on_peer_hangup, state: "bridging"}`). Rejects with a `code` a
864
+ * caller can act on: `"not_found"` (no such leg), `"invalid_state"` (a leg has
865
+ * not answered, is already bridged, has a re-INVITE outstanding, or carries no
866
+ * media description), `"bad_request"` (the same leg named twice, or a bad
867
+ * `onPeerHangup`), `"forbidden"` (the other channel belongs to another app),
868
+ * `"unsupported_verb"` (the media backend cannot express it).
869
+ */
870
+ async bridge(withChannel, options) {
871
+ const args = { with: withChannel };
872
+ if (options?.onPeerHangup !== void 0) {
873
+ args.on_peer_hangup = options.onPeerHangup;
874
+ }
875
+ return this.sip(SipVerb.Bridge, args);
876
+ }
877
+ /**
878
+ * Break this call's bridge.
879
+ *
880
+ * Both legs stay answered, owned and held — re-offered `a=sendonly`
881
+ * (RFC 3264 §8.4, which RFC 6337 §3.1 prefers to `c=0.0.0.0`). Neither is hung
882
+ * up: that would be indistinguishable from two hangups and would take away the
883
+ * calls the app still owns. A later {@link Call.bridge} re-offers `sendrecv`.
884
+ *
885
+ * `reason` is free text carried on the `ChannelUnbridged`
886
+ * ({@link import("./protocol").ChannelUnbridgedPayload}) event both channels
887
+ * receive; omitted means `"unbridged"`. Resolves to the reply `result`
888
+ * (`{channel, with, reason, state: "unbridged"}`), where `with` is the channel
889
+ * id of the leg that was on the other side. A call that is not bridged rejects
890
+ * with `code === "invalid_state"`.
891
+ */
892
+ async unbridge(reason) {
893
+ return this.sip(SipVerb.Unbridge, reason !== void 0 ? { reason } : {});
894
+ }
795
895
  /** Set a header on the stored A-leg INVITE. */
796
896
  async setHeader(name, value) {
797
897
  await this.sip(SipVerb.SetHeader, { name, value });
@@ -874,7 +974,8 @@ var Call = class {
874
974
  }
875
975
  /**
876
976
  * Await the next event for this call (`ChannelStateChange`,
877
- * `ChannelHangupRequest`, `StasisEnd`). `null` once the stream closes.
977
+ * `ChannelHangupRequest`, `ChannelBridged`, `BridgeFailed`,
978
+ * `ChannelUnbridged`, `StasisEnd`). `null` once the stream closes.
878
979
  */
879
980
  nextEvent() {
880
981
  return this.eventQueue.next();
@@ -1087,6 +1188,8 @@ exports.SipClient = SipClient;
1087
1188
  exports.SipServer = SipServer;
1088
1189
  exports.SipVerb = SipVerb;
1089
1190
  exports.encodeCommand = encodeCommand;
1191
+ exports.isBridgeFinal = isBridgeFinal;
1192
+ exports.isTransferFinal = isTransferFinal;
1090
1193
  exports.parseInboundFrame = parseInboundFrame;
1091
1194
  exports.sipEventKind = sipEventKind;
1092
1195
  //# sourceMappingURL=index.cjs.map