@siphon-project/control 0.1.1 → 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/dist/index.js CHANGED
@@ -101,21 +101,41 @@ 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",
107
113
  Refer: "refer",
114
+ Route: "route",
108
115
  SetHeader: "set_header",
109
116
  GetHeader: "get_header",
110
117
  RemoveHeader: "remove_header",
111
118
  AcceptRefer: "accept_refer",
112
119
  RejectRefer: "reject_refer",
120
+ Bridge: "bridge",
121
+ Unbridge: "unbridge",
113
122
  Play: "play",
114
- Dtmf: "dtmf"
123
+ Stop: "stop",
124
+ Dtmf: "dtmf",
125
+ Hold: "hold",
126
+ Unhold: "unhold",
127
+ StreamStart: "stream_start",
128
+ StreamStop: "stream_stop"
115
129
  };
116
130
  function sipEventKind(name) {
117
131
  return name;
118
132
  }
133
+ function isTransferFinal(name) {
134
+ return name === "TransferCompleted" || name === "TransferFailed";
135
+ }
136
+ function isBridgeFinal(name) {
137
+ return name === "ChannelBridged" || name === "BridgeFailed";
138
+ }
119
139
 
120
140
  // src/internal.ts
121
141
  var AsyncQueue = class {
@@ -584,6 +604,22 @@ function responseArgs(options) {
584
604
  }
585
605
  return args;
586
606
  }
607
+ function routeTargetToWire(target) {
608
+ if (typeof target === "string") {
609
+ return target;
610
+ }
611
+ const object = { uri: target.uri };
612
+ if (target.nextHop !== void 0) {
613
+ object.next_hop = target.nextHop;
614
+ }
615
+ if (target.headers !== void 0) {
616
+ object.headers = target.headers;
617
+ }
618
+ if (target.timeout !== void 0) {
619
+ object.timeout = target.timeout;
620
+ }
621
+ return object;
622
+ }
587
623
  function stringValue(result) {
588
624
  if (typeof result === "object" && result !== null) {
589
625
  const value = result.value;
@@ -593,6 +629,45 @@ function stringValue(result) {
593
629
  }
594
630
  return null;
595
631
  }
632
+ function playArgs(source, options) {
633
+ const args = {};
634
+ if ("file" in source) {
635
+ args.file = source.file;
636
+ } else if ("dbId" in source) {
637
+ args.db_id = source.dbId;
638
+ } else {
639
+ args.blob = Buffer.from(source.blob).toString("base64");
640
+ }
641
+ if (options?.repeat !== void 0) {
642
+ args.repeat = options.repeat;
643
+ }
644
+ if (options?.startMs !== void 0) {
645
+ args.start_ms = options.startMs;
646
+ }
647
+ if (options?.durationMs !== void 0) {
648
+ args.duration_ms = options.durationMs;
649
+ }
650
+ if (options?.toTag !== void 0) {
651
+ args.to_tag = options.toTag;
652
+ }
653
+ return args;
654
+ }
655
+ function dtmfArgs(digits, options) {
656
+ const args = { digits };
657
+ if (options?.durationMs !== void 0) {
658
+ args.duration_ms = options.durationMs;
659
+ }
660
+ if (options?.volumeDbm0 !== void 0) {
661
+ args.volume_dbm0 = options.volumeDbm0;
662
+ }
663
+ if (options?.pauseMs !== void 0) {
664
+ args.pause_ms = options.pauseMs;
665
+ }
666
+ if (options?.toTag !== void 0) {
667
+ args.to_tag = options.toTag;
668
+ }
669
+ return args;
670
+ }
596
671
  var Call = class {
597
672
  constructor(transport, channelId, callId, sipCallId, app, payload, reattached, eventQueue) {
598
673
  this.transport = transport;
@@ -626,7 +701,22 @@ var Call = class {
626
701
  async answer(options) {
627
702
  await this.sip(SipVerb.Answer, options ? responseArgs(options) : {});
628
703
  }
629
- /** Send a UAS 1xx / early media (default `183 Session Progress`). */
704
+ /**
705
+ * Send `180 Ringing`: alerting only, no early media.
706
+ *
707
+ * RFC 3261 §13.2.1 makes the 180 the "callee is being alerted" signal, and
708
+ * RFC 3960 §3.1 puts early media on a response that carries SDP — two
709
+ * different acts, so two verbs. Ring for as long as your own policy says,
710
+ * then {@link Call.answer}; open an early-media path with
711
+ * {@link Call.progress}.
712
+ */
713
+ async ring(reason) {
714
+ await this.sip(SipVerb.Ring, reason !== void 0 ? { reason } : {});
715
+ }
716
+ /**
717
+ * Send a UAS 1xx, optionally opening an early-media path with SDP (default
718
+ * `183 Session Progress`). For plain alerting use {@link Call.ring}.
719
+ */
630
720
  async progress(options) {
631
721
  await this.sip(SipVerb.Progress, options ? responseArgs(options) : {});
632
722
  }
@@ -649,7 +739,17 @@ var Call = class {
649
739
  async hangup(reason) {
650
740
  await this.terminate(reason);
651
741
  }
652
- /** Send an in-dialog REFER on the A-leg (blind transfer). */
742
+ /**
743
+ * Send an in-dialog REFER on the A-leg (blind transfer).
744
+ *
745
+ * Resolves as soon as siphon has sent the REFER — that is *sent*, not
746
+ * *transferred*. RFC 3515 §2.4.4 delivers the outcome afterwards on the
747
+ * implicit subscription, so read it off {@link Call.events}: zero or more
748
+ * `TransferProgress`, then exactly one `TransferCompleted` /
749
+ * `TransferFailed`, each carrying a
750
+ * {@link import("./protocol").TransferOutcomePayload}. Use
751
+ * {@link import("./protocol").isTransferFinal} to know when to stop waiting.
752
+ */
653
753
  async refer(to) {
654
754
  await this.sip(SipVerb.Refer, { to });
655
755
  }
@@ -670,9 +770,39 @@ var Call = class {
670
770
  });
671
771
  }
672
772
  /**
673
- * Accept an inbound REFER on this tracked call. **Not implemented server-side
674
- * in Phase 1** — resolves to a {@link ControlError} with `code ===
675
- * "unsupported_verb"` until the server adds it.
773
+ * Un-park this controlled call and dial the B-leg via siphon's LCR
774
+ * sequential-failover engine, returning control to siphon.
775
+ *
776
+ * `targets` is a non-empty list of carriers tried cheapest-first: each entry
777
+ * is a bare URI string or a {@link RouteTargetObject}
778
+ * (`{uri, nextHop?, headers?, timeout?}`). `strategy` defaults to
779
+ * `"sequential"` (v1 supports only sequential/single — anything else rejects
780
+ * with `code === "unsupported_verb"`). `headers` is applied to every
781
+ * attempt's B-leg INVITE.
782
+ *
783
+ * Resolves to the reply `result` (`{channel, state: "routing", targets}`). An
784
+ * empty / invalid `targets` list rejects with `code === "bad_request"`; a call
785
+ * that is already gone rejects with `code === "not_found"`.
786
+ */
787
+ async route(targets, strategy = "sequential", headers) {
788
+ const args = {
789
+ targets: targets.map(routeTargetToWire),
790
+ strategy
791
+ };
792
+ if (headers !== void 0) {
793
+ args.headers = headers;
794
+ }
795
+ return this.sip(SipVerb.Route, args);
796
+ }
797
+ /**
798
+ * Accept a *pending inbound* REFER (surfaced as a `TransferRequested` event)
799
+ * and run the transfer. `target` overrides the Refer-To URI, `nextHop` steers
800
+ * egress, and `mode` (`"terminate"` / `"transparent"`) overrides
801
+ * `b2bua.default_refer_mode`. No pending REFER (already decided, timed out, or
802
+ * the call is gone) rejects with `code === "not_found"`.
803
+ *
804
+ * `profile` names the media profile for the pairing the transfer creates —
805
+ * see {@link AcceptReferOptions.profile}, which is required at an SRTP edge.
676
806
  */
677
807
  async acceptRefer(options) {
678
808
  const args = {};
@@ -685,11 +815,14 @@ var Call = class {
685
815
  if (options?.mode !== void 0) {
686
816
  args.mode = options.mode;
687
817
  }
818
+ if (options?.profile !== void 0) {
819
+ args.profile = options.profile;
820
+ }
688
821
  await this.sip(SipVerb.AcceptRefer, args);
689
822
  }
690
823
  /**
691
- * Reject an inbound REFER on this tracked call. **Not implemented server-side
692
- * in Phase 1** — see {@link Call.acceptRefer}.
824
+ * Reject a *pending inbound* REFER with a final non-2xx (default
825
+ * `603 Decline`). No pending REFER rejects with `code === "not_found"`.
693
826
  */
694
827
  async rejectRefer(code, reason) {
695
828
  const args = { code };
@@ -698,6 +831,61 @@ var Call = class {
698
831
  }
699
832
  await this.sip(SipVerb.RejectRefer, args);
700
833
  }
834
+ /**
835
+ * Join this call to another leg the app owns, so the two parties hear each
836
+ * other.
837
+ *
838
+ * **This call is the anchor.** It keeps its media session — its ports and
839
+ * everything attached to them; the `withChannel` leg's own media session is
840
+ * deleted and it becomes the second party on this one's. So bridge *into* the
841
+ * leg whose media you want to keep (the one being recorded, teed, or carrying
842
+ * the prompt).
843
+ *
844
+ * Both legs must already be answered. `options.onPeerHangup` says what happens
845
+ * to the survivor when its partner hangs up (see
846
+ * {@link import("./protocol").PeerHangupPolicy}); omitted means `"hangup"`.
847
+ *
848
+ * Resolves as soon as the media has been re-pointed and the first re-INVITE is
849
+ * on the wire — that is *offered*, not *bridged*. A bridge is two RFC 3261 §14
850
+ * re-INVITEs across two dialogs, so the outcome arrives on {@link Call.events}
851
+ * instead: exactly one `ChannelBridged`
852
+ * ({@link import("./protocol").ChannelBridgedPayload}) / `BridgeFailed`
853
+ * ({@link import("./protocol").BridgeFailedPayload}), on **both** channels.
854
+ * {@link import("./protocol").isBridgeFinal} says when to stop waiting.
855
+ *
856
+ * Resolves to the reply `result` (`{channel, with, call_id, peer_call_id,
857
+ * anchored, on_peer_hangup, state: "bridging"}`). Rejects with a `code` a
858
+ * caller can act on: `"not_found"` (no such leg), `"invalid_state"` (a leg has
859
+ * not answered, is already bridged, has a re-INVITE outstanding, or carries no
860
+ * media description), `"bad_request"` (the same leg named twice, or a bad
861
+ * `onPeerHangup`), `"forbidden"` (the other channel belongs to another app),
862
+ * `"unsupported_verb"` (the media backend cannot express it).
863
+ */
864
+ async bridge(withChannel, options) {
865
+ const args = { with: withChannel };
866
+ if (options?.onPeerHangup !== void 0) {
867
+ args.on_peer_hangup = options.onPeerHangup;
868
+ }
869
+ return this.sip(SipVerb.Bridge, args);
870
+ }
871
+ /**
872
+ * Break this call's bridge.
873
+ *
874
+ * Both legs stay answered, owned and held — re-offered `a=sendonly`
875
+ * (RFC 3264 §8.4, which RFC 6337 §3.1 prefers to `c=0.0.0.0`). Neither is hung
876
+ * up: that would be indistinguishable from two hangups and would take away the
877
+ * calls the app still owns. A later {@link Call.bridge} re-offers `sendrecv`.
878
+ *
879
+ * `reason` is free text carried on the `ChannelUnbridged`
880
+ * ({@link import("./protocol").ChannelUnbridgedPayload}) event both channels
881
+ * receive; omitted means `"unbridged"`. Resolves to the reply `result`
882
+ * (`{channel, with, reason, state: "unbridged"}`), where `with` is the channel
883
+ * id of the leg that was on the other side. A call that is not bridged rejects
884
+ * with `code === "invalid_state"`.
885
+ */
886
+ async unbridge(reason) {
887
+ return this.sip(SipVerb.Unbridge, reason !== void 0 ? { reason } : {});
888
+ }
701
889
  /** Set a header on the stored A-leg INVITE. */
702
890
  async setHeader(name, value) {
703
891
  await this.sip(SipVerb.SetHeader, { name, value });
@@ -707,11 +895,7 @@ var Call = class {
707
895
  const result = await this.sip(SipVerb.GetHeader, { name });
708
896
  return stringValue(result);
709
897
  }
710
- /**
711
- * Remove a header from the stored A-leg INVITE. **Not implemented server-side
712
- * in Phase 1** — resolves to a {@link ControlError} with `code ===
713
- * "unsupported_verb"` until the server adds it.
714
- */
898
+ /** Remove a header from the stored A-leg INVITE. */
715
899
  async removeHeader(name) {
716
900
  await this.sip(SipVerb.RemoveHeader, { name });
717
901
  }
@@ -725,18 +909,57 @@ var Call = class {
725
909
  const result = await this.substrate(GET_VAR, { key });
726
910
  return stringValue(result);
727
911
  }
728
- // --- media (server answers `unsupported_verb` today) -------------------
912
+ // --- media -------------------------------------------------------------
729
913
  /**
730
- * Play an announcement. **Not yet implemented server-side** — resolves to a
731
- * {@link ControlError} with `code === "unsupported_verb"` until the media
732
- * backend lands.
914
+ * Play an announcement on the A-leg media (fire-and-forget). `source` is a
915
+ * {@link PlaySource} (a blob is base64-encoded on the wire); `options` shapes
916
+ * playback. A call with no anchored media session rejects with
917
+ * `code === "not_found"`.
733
918
  */
919
+ async play(source, options) {
920
+ await this.sip(SipVerb.Play, playArgs(source, options));
921
+ }
922
+ /** Convenience for {@link Call.play} of a server-side file with default options. */
734
923
  async playFile(file) {
735
- await this.sip(SipVerb.Play, { file });
924
+ await this.play({ file });
925
+ }
926
+ /** Stop the announcement currently playing on the A-leg media. */
927
+ async stop() {
928
+ await this.sip(SipVerb.Stop, {});
929
+ }
930
+ /**
931
+ * Inject DTMF digits toward the A-leg (fire-and-forget). `options` carries the
932
+ * optional `durationMs` / `volumeDbm0` / `pauseMs` / `toTag` shaping.
933
+ */
934
+ async dtmf(digits, options) {
935
+ await this.sip(SipVerb.Dtmf, dtmfArgs(digits, options));
936
+ }
937
+ /** Hold the A-leg media via silence. */
938
+ async hold() {
939
+ await this.sip(SipVerb.Hold, {});
940
+ }
941
+ /** Resume the A-leg media after a {@link Call.hold}. */
942
+ async unhold() {
943
+ await this.sip(SipVerb.Unhold, {});
944
+ }
945
+ /**
946
+ * Attach a WebSocket audio tee — stream a copy of the call's decoded audio to
947
+ * `wsUri` while the call keeps relaying. siphon-rtp backend only: rtpengine /
948
+ * rtpproxy reject with `code === "unsupported_verb"` (`error.isUnsupportedVerb()`).
949
+ */
950
+ async streamStart(wsUri, options) {
951
+ const args = { ws_uri: wsUri };
952
+ if (options?.direction !== void 0) {
953
+ args.direction = options.direction;
954
+ }
955
+ if (options?.channels !== void 0) {
956
+ args.channels = options.channels;
957
+ }
958
+ await this.sip(SipVerb.StreamStart, args);
736
959
  }
737
- /** Send DTMF. **Not yet implemented server-side** — see {@link Call.playFile}. */
738
- async dtmf(digits) {
739
- await this.sip(SipVerb.Dtmf, { digits });
960
+ /** Detach the WebSocket audio tee (idempotent on siphon-rtp). */
961
+ async streamStop() {
962
+ await this.sip(SipVerb.StreamStop, {});
740
963
  }
741
964
  // --- escape hatch + events --------------------------------------------
742
965
  /** Send an arbitrary SIP-adapter verb + args and return the raw result. */
@@ -745,7 +968,8 @@ var Call = class {
745
968
  }
746
969
  /**
747
970
  * Await the next event for this call (`ChannelStateChange`,
748
- * `ChannelHangupRequest`, `StasisEnd`). `null` once the stream closes.
971
+ * `ChannelHangupRequest`, `ChannelBridged`, `BridgeFailed`,
972
+ * `ChannelUnbridged`, `StasisEnd`). `null` once the stream closes.
749
973
  */
750
974
  nextEvent() {
751
975
  return this.eventQueue.next();
@@ -938,6 +1162,6 @@ var SipServer = class _SipServer {
938
1162
  }
939
1163
  };
940
1164
 
941
- 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 };
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 };
942
1166
  //# sourceMappingURL=index.js.map
943
1167
  //# sourceMappingURL=index.js.map