@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/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,21 +107,41 @@ 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",
113
119
  Refer: "refer",
120
+ Route: "route",
114
121
  SetHeader: "set_header",
115
122
  GetHeader: "get_header",
116
123
  RemoveHeader: "remove_header",
117
124
  AcceptRefer: "accept_refer",
118
125
  RejectRefer: "reject_refer",
126
+ Bridge: "bridge",
127
+ Unbridge: "unbridge",
119
128
  Play: "play",
120
- Dtmf: "dtmf"
129
+ Stop: "stop",
130
+ Dtmf: "dtmf",
131
+ Hold: "hold",
132
+ Unhold: "unhold",
133
+ StreamStart: "stream_start",
134
+ StreamStop: "stream_stop"
121
135
  };
122
136
  function sipEventKind(name) {
123
137
  return name;
124
138
  }
139
+ function isTransferFinal(name) {
140
+ return name === "TransferCompleted" || name === "TransferFailed";
141
+ }
142
+ function isBridgeFinal(name) {
143
+ return name === "ChannelBridged" || name === "BridgeFailed";
144
+ }
125
145
 
126
146
  // src/internal.ts
127
147
  var AsyncQueue = class {
@@ -590,6 +610,22 @@ function responseArgs(options) {
590
610
  }
591
611
  return args;
592
612
  }
613
+ function routeTargetToWire(target) {
614
+ if (typeof target === "string") {
615
+ return target;
616
+ }
617
+ const object = { uri: target.uri };
618
+ if (target.nextHop !== void 0) {
619
+ object.next_hop = target.nextHop;
620
+ }
621
+ if (target.headers !== void 0) {
622
+ object.headers = target.headers;
623
+ }
624
+ if (target.timeout !== void 0) {
625
+ object.timeout = target.timeout;
626
+ }
627
+ return object;
628
+ }
593
629
  function stringValue(result) {
594
630
  if (typeof result === "object" && result !== null) {
595
631
  const value = result.value;
@@ -599,6 +635,45 @@ function stringValue(result) {
599
635
  }
600
636
  return null;
601
637
  }
638
+ function playArgs(source, options) {
639
+ const args = {};
640
+ if ("file" in source) {
641
+ args.file = source.file;
642
+ } else if ("dbId" in source) {
643
+ args.db_id = source.dbId;
644
+ } else {
645
+ args.blob = Buffer.from(source.blob).toString("base64");
646
+ }
647
+ if (options?.repeat !== void 0) {
648
+ args.repeat = options.repeat;
649
+ }
650
+ if (options?.startMs !== void 0) {
651
+ args.start_ms = options.startMs;
652
+ }
653
+ if (options?.durationMs !== void 0) {
654
+ args.duration_ms = options.durationMs;
655
+ }
656
+ if (options?.toTag !== void 0) {
657
+ args.to_tag = options.toTag;
658
+ }
659
+ return args;
660
+ }
661
+ function dtmfArgs(digits, options) {
662
+ const args = { digits };
663
+ if (options?.durationMs !== void 0) {
664
+ args.duration_ms = options.durationMs;
665
+ }
666
+ if (options?.volumeDbm0 !== void 0) {
667
+ args.volume_dbm0 = options.volumeDbm0;
668
+ }
669
+ if (options?.pauseMs !== void 0) {
670
+ args.pause_ms = options.pauseMs;
671
+ }
672
+ if (options?.toTag !== void 0) {
673
+ args.to_tag = options.toTag;
674
+ }
675
+ return args;
676
+ }
602
677
  var Call = class {
603
678
  constructor(transport, channelId, callId, sipCallId, app, payload, reattached, eventQueue) {
604
679
  this.transport = transport;
@@ -632,7 +707,22 @@ var Call = class {
632
707
  async answer(options) {
633
708
  await this.sip(SipVerb.Answer, options ? responseArgs(options) : {});
634
709
  }
635
- /** 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
+ */
636
726
  async progress(options) {
637
727
  await this.sip(SipVerb.Progress, options ? responseArgs(options) : {});
638
728
  }
@@ -655,7 +745,17 @@ var Call = class {
655
745
  async hangup(reason) {
656
746
  await this.terminate(reason);
657
747
  }
658
- /** 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
+ */
659
759
  async refer(to) {
660
760
  await this.sip(SipVerb.Refer, { to });
661
761
  }
@@ -676,9 +776,39 @@ var Call = class {
676
776
  });
677
777
  }
678
778
  /**
679
- * Accept an inbound REFER on this tracked call. **Not implemented server-side
680
- * in Phase 1** — resolves to a {@link ControlError} with `code ===
681
- * "unsupported_verb"` until the server adds it.
779
+ * Un-park this controlled call and dial the B-leg via siphon's LCR
780
+ * sequential-failover engine, returning control to siphon.
781
+ *
782
+ * `targets` is a non-empty list of carriers tried cheapest-first: each entry
783
+ * is a bare URI string or a {@link RouteTargetObject}
784
+ * (`{uri, nextHop?, headers?, timeout?}`). `strategy` defaults to
785
+ * `"sequential"` (v1 supports only sequential/single — anything else rejects
786
+ * with `code === "unsupported_verb"`). `headers` is applied to every
787
+ * attempt's B-leg INVITE.
788
+ *
789
+ * Resolves to the reply `result` (`{channel, state: "routing", targets}`). An
790
+ * empty / invalid `targets` list rejects with `code === "bad_request"`; a call
791
+ * that is already gone rejects with `code === "not_found"`.
792
+ */
793
+ async route(targets, strategy = "sequential", headers) {
794
+ const args = {
795
+ targets: targets.map(routeTargetToWire),
796
+ strategy
797
+ };
798
+ if (headers !== void 0) {
799
+ args.headers = headers;
800
+ }
801
+ return this.sip(SipVerb.Route, args);
802
+ }
803
+ /**
804
+ * Accept a *pending inbound* REFER (surfaced as a `TransferRequested` event)
805
+ * and run the transfer. `target` overrides the Refer-To URI, `nextHop` steers
806
+ * egress, and `mode` (`"terminate"` / `"transparent"`) overrides
807
+ * `b2bua.default_refer_mode`. No pending REFER (already decided, timed out, or
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.
682
812
  */
683
813
  async acceptRefer(options) {
684
814
  const args = {};
@@ -691,11 +821,14 @@ var Call = class {
691
821
  if (options?.mode !== void 0) {
692
822
  args.mode = options.mode;
693
823
  }
824
+ if (options?.profile !== void 0) {
825
+ args.profile = options.profile;
826
+ }
694
827
  await this.sip(SipVerb.AcceptRefer, args);
695
828
  }
696
829
  /**
697
- * Reject an inbound REFER on this tracked call. **Not implemented server-side
698
- * in Phase 1** — see {@link Call.acceptRefer}.
830
+ * Reject a *pending inbound* REFER with a final non-2xx (default
831
+ * `603 Decline`). No pending REFER rejects with `code === "not_found"`.
699
832
  */
700
833
  async rejectRefer(code, reason) {
701
834
  const args = { code };
@@ -704,6 +837,61 @@ var Call = class {
704
837
  }
705
838
  await this.sip(SipVerb.RejectRefer, args);
706
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
+ }
707
895
  /** Set a header on the stored A-leg INVITE. */
708
896
  async setHeader(name, value) {
709
897
  await this.sip(SipVerb.SetHeader, { name, value });
@@ -713,11 +901,7 @@ var Call = class {
713
901
  const result = await this.sip(SipVerb.GetHeader, { name });
714
902
  return stringValue(result);
715
903
  }
716
- /**
717
- * Remove a header from the stored A-leg INVITE. **Not implemented server-side
718
- * in Phase 1** — resolves to a {@link ControlError} with `code ===
719
- * "unsupported_verb"` until the server adds it.
720
- */
904
+ /** Remove a header from the stored A-leg INVITE. */
721
905
  async removeHeader(name) {
722
906
  await this.sip(SipVerb.RemoveHeader, { name });
723
907
  }
@@ -731,18 +915,57 @@ var Call = class {
731
915
  const result = await this.substrate(GET_VAR, { key });
732
916
  return stringValue(result);
733
917
  }
734
- // --- media (server answers `unsupported_verb` today) -------------------
918
+ // --- media -------------------------------------------------------------
735
919
  /**
736
- * Play an announcement. **Not yet implemented server-side** — resolves to a
737
- * {@link ControlError} with `code === "unsupported_verb"` until the media
738
- * backend lands.
920
+ * Play an announcement on the A-leg media (fire-and-forget). `source` is a
921
+ * {@link PlaySource} (a blob is base64-encoded on the wire); `options` shapes
922
+ * playback. A call with no anchored media session rejects with
923
+ * `code === "not_found"`.
739
924
  */
925
+ async play(source, options) {
926
+ await this.sip(SipVerb.Play, playArgs(source, options));
927
+ }
928
+ /** Convenience for {@link Call.play} of a server-side file with default options. */
740
929
  async playFile(file) {
741
- await this.sip(SipVerb.Play, { file });
930
+ await this.play({ file });
931
+ }
932
+ /** Stop the announcement currently playing on the A-leg media. */
933
+ async stop() {
934
+ await this.sip(SipVerb.Stop, {});
935
+ }
936
+ /**
937
+ * Inject DTMF digits toward the A-leg (fire-and-forget). `options` carries the
938
+ * optional `durationMs` / `volumeDbm0` / `pauseMs` / `toTag` shaping.
939
+ */
940
+ async dtmf(digits, options) {
941
+ await this.sip(SipVerb.Dtmf, dtmfArgs(digits, options));
942
+ }
943
+ /** Hold the A-leg media via silence. */
944
+ async hold() {
945
+ await this.sip(SipVerb.Hold, {});
946
+ }
947
+ /** Resume the A-leg media after a {@link Call.hold}. */
948
+ async unhold() {
949
+ await this.sip(SipVerb.Unhold, {});
950
+ }
951
+ /**
952
+ * Attach a WebSocket audio tee — stream a copy of the call's decoded audio to
953
+ * `wsUri` while the call keeps relaying. siphon-rtp backend only: rtpengine /
954
+ * rtpproxy reject with `code === "unsupported_verb"` (`error.isUnsupportedVerb()`).
955
+ */
956
+ async streamStart(wsUri, options) {
957
+ const args = { ws_uri: wsUri };
958
+ if (options?.direction !== void 0) {
959
+ args.direction = options.direction;
960
+ }
961
+ if (options?.channels !== void 0) {
962
+ args.channels = options.channels;
963
+ }
964
+ await this.sip(SipVerb.StreamStart, args);
742
965
  }
743
- /** Send DTMF. **Not yet implemented server-side** — see {@link Call.playFile}. */
744
- async dtmf(digits) {
745
- await this.sip(SipVerb.Dtmf, { digits });
966
+ /** Detach the WebSocket audio tee (idempotent on siphon-rtp). */
967
+ async streamStop() {
968
+ await this.sip(SipVerb.StreamStop, {});
746
969
  }
747
970
  // --- escape hatch + events --------------------------------------------
748
971
  /** Send an arbitrary SIP-adapter verb + args and return the raw result. */
@@ -751,7 +974,8 @@ var Call = class {
751
974
  }
752
975
  /**
753
976
  * Await the next event for this call (`ChannelStateChange`,
754
- * `ChannelHangupRequest`, `StasisEnd`). `null` once the stream closes.
977
+ * `ChannelHangupRequest`, `ChannelBridged`, `BridgeFailed`,
978
+ * `ChannelUnbridged`, `StasisEnd`). `null` once the stream closes.
755
979
  */
756
980
  nextEvent() {
757
981
  return this.eventQueue.next();
@@ -964,6 +1188,8 @@ exports.SipClient = SipClient;
964
1188
  exports.SipServer = SipServer;
965
1189
  exports.SipVerb = SipVerb;
966
1190
  exports.encodeCommand = encodeCommand;
1191
+ exports.isBridgeFinal = isBridgeFinal;
1192
+ exports.isTransferFinal = isTransferFinal;
967
1193
  exports.parseInboundFrame = parseInboundFrame;
968
1194
  exports.sipEventKind = sipEventKind;
969
1195
  //# sourceMappingURL=index.cjs.map