@siphon-project/control 0.3.0 → 0.5.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
@@ -110,6 +110,9 @@ await client.command("sip", "answer", { channel: "ch1" }, { code: 200 });
110
110
  | `rejectRefer(code, reason?)` | `reject_refer` (`sip`) | ‡ |
111
111
  | `bridge(withChannel, options?)` | `bridge` (`sip`) | join two answered legs; the verdict arrives as `ChannelBridged` / `BridgeFailed` |
112
112
  | `unbridge(reason?)` | `unbridge` (`sip`) | break the bridge — both legs stay answered, owned and held |
113
+ | `dial(targets, options?)` | `dial` (`sip`) | ring B-legs while the caller stays **unanswered** and this app keeps the channel. A target is `{uri}` (dialed as written) or `{aor}` (forked to every registered contact over its own flow); one naming both, or neither, throws |
114
+ | `recordStart(options?)` | `record_start` (`sip`) | record the call's decoded audio to a wav file; the reply names the `recordingId`, `RecordingFinished` says the file is closed. siphon-rtp only |
115
+ | `recordStop(recordingId?)` | `record_stop` (`sip`) | stop one recording, or every recording on the call when no id is given |
113
116
  | `playFile(file)` | `play` (`sip`) | ‡ media |
114
117
  | `dtmf(digits)` | `dtmf` (`sip`) | ‡ media |
115
118
  | `command(verb, args?)` | (`sip`) | arbitrary SIP-adapter verb |
package/dist/index.cjs CHANGED
@@ -118,6 +118,11 @@ var SipVerb = {
118
118
  Hangup: "hangup",
119
119
  Refer: "refer",
120
120
  Route: "route",
121
+ /**
122
+ * Ring targets as B-legs while the caller stays unanswered and the app keeps
123
+ * the channel. Channel-addressed, unlike `originate`, which creates one.
124
+ */
125
+ Dial: "dial",
121
126
  SetHeader: "set_header",
122
127
  GetHeader: "get_header",
123
128
  RemoveHeader: "remove_header",
@@ -132,7 +137,11 @@ var SipVerb = {
132
137
  Hold: "hold",
133
138
  Unhold: "unhold",
134
139
  StreamStart: "stream_start",
135
- StreamStop: "stream_stop"
140
+ StreamStop: "stream_stop",
141
+ /** Record the call's decoded audio to a wav file (siphon-rtp backend only). */
142
+ RecordStart: "record_start",
143
+ /** Stop one recording by id, or every recording on the call. */
144
+ RecordStop: "record_stop"
136
145
  };
137
146
  function sipEventKind(name) {
138
147
  return name;
@@ -680,6 +689,63 @@ function originateArgs(channel, to, media, options) {
680
689
  }
681
690
  return args;
682
691
  }
692
+ function dialTargetToWire(target) {
693
+ const uri = target.uri;
694
+ const aor = target.aor;
695
+ const nextHop = target.nextHop;
696
+ const headers = target.headers;
697
+ if (typeof uri === "string" && typeof aor === "string") {
698
+ throw new TypeError(
699
+ 'a dial target names "uri" or "aor", never both \u2014 siphon reads the aor and ignores the uri beside it, so this would place a different call'
700
+ );
701
+ }
702
+ if (typeof aor === "string") {
703
+ if (nextHop !== void 0) {
704
+ throw new TypeError(
705
+ `an aor target takes no "nextHop": each of its branches routes over its own contact's captured flow`
706
+ );
707
+ }
708
+ const object2 = { aor };
709
+ if (headers !== void 0) object2.headers = headers;
710
+ return object2;
711
+ }
712
+ if (typeof uri !== "string") {
713
+ throw new TypeError('a dial target requires a string "uri" or "aor"');
714
+ }
715
+ if (nextHop === void 0 && headers === void 0) return uri;
716
+ const object = { uri };
717
+ if (nextHop !== void 0) object.next_hop = nextHop;
718
+ if (headers !== void 0) object.headers = headers;
719
+ return object;
720
+ }
721
+ function dialArgs(targets, options) {
722
+ const args = { targets: targets.map(dialTargetToWire) };
723
+ if (!options) return args;
724
+ if (options.strategy !== void 0) args.strategy = options.strategy;
725
+ if (options.timeout !== void 0) args.timeout = options.timeout;
726
+ if (options.headers !== void 0) args.headers = options.headers;
727
+ if (options.profile !== void 0) args.profile = options.profile;
728
+ if (options.from !== void 0) args.from = options.from;
729
+ if (options.fromDisplay !== void 0) args.from_display = options.fromDisplay;
730
+ if (options.pAssertedIdentity !== void 0) {
731
+ args.p_asserted_identity = options.pAssertedIdentity;
732
+ }
733
+ if (options.privacy !== void 0) args.privacy = options.privacy;
734
+ return args;
735
+ }
736
+ function recordStartArgs(options) {
737
+ const args = {};
738
+ if (!options) return args;
739
+ if (options.direction !== void 0) args.direction = options.direction;
740
+ if (options.channels !== void 0) args.channels = options.channels;
741
+ if (options.maxDurationMs !== void 0) args.max_duration_ms = options.maxDurationMs;
742
+ if (options.silenceMs !== void 0) args.silence_ms = options.silenceMs;
743
+ if (options.path !== void 0) args.path = options.path;
744
+ return args;
745
+ }
746
+ function recordStopArgs(recordingId) {
747
+ return recordingId === void 0 ? {} : { recording_id: recordingId };
748
+ }
683
749
  function playArgs(source, options) {
684
750
  const args = {};
685
751
  if ("file" in source) {
@@ -882,6 +948,58 @@ var Call = class {
882
948
  }
883
949
  return this.sip(SipVerb.Route, args);
884
950
  }
951
+ /**
952
+ * Ring `targets` as B-legs while the caller stays **unanswered** and this
953
+ * application keeps the channel.
954
+ *
955
+ * The difference from {@link Call.route} is who holds the call afterwards.
956
+ * `route` hands it back to siphon, so the app gets `StasisEnd{reason: routed}`
957
+ * and loses it; there is then no way to say "ring the extension, and if nobody
958
+ * answers, voicemail" without answering the caller first — which starts
959
+ * billing before anyone picks up, records an unanswered call as answered, and
960
+ * denies the caller the callee's own ringback.
961
+ *
962
+ * The first 2xx answers the caller with the winner's SDP and the pair becomes
963
+ * an ordinary two-leg call, still owned by this app. A failure or timeout
964
+ * arrives as a `DialFailed` event with the caller still ringing and still
965
+ * parked, so the app decides what happens next.
966
+ *
967
+ * Each target is a URI (dialed as written) or an `{aor}` (forked to every
968
+ * registered contact over its own flow) — see {@link DialTarget}, and note
969
+ * that a target naming both, or neither, throws before anything is sent.
970
+ *
971
+ * ```ts
972
+ * const dialing = await call.dial(
973
+ * [{ aor: "sip:204@pbx.example" }],
974
+ * { strategy: "sequential", timeout: 20 },
975
+ * );
976
+ * ```
977
+ *
978
+ * Rejects with `code === "not_found"` (the call is gone, or no target yielded
979
+ * a branch — an AoR nobody has registered), `"invalid_state"` (already
980
+ * answered, which is what this verb exists to avoid), `"bad_request"` (an
981
+ * empty or malformed target list) or `"unsupported_verb"` (a strategy siphon
982
+ * does not implement).
983
+ */
984
+ async dial(targets, options) {
985
+ const result = await this.sip(SipVerb.Dial, dialArgs(targets, options));
986
+ const text = (name) => {
987
+ const value = result?.[name];
988
+ return typeof value === "string" ? value : void 0;
989
+ };
990
+ const count = (name) => {
991
+ const value = result?.[name];
992
+ return typeof value === "number" ? value : void 0;
993
+ };
994
+ return {
995
+ // The server echoes the channel back; fall back to the one addressed
996
+ // rather than returning an empty id.
997
+ channel: text("channel") ?? this.channelId,
998
+ targets: count("targets"),
999
+ strategy: text("strategy"),
1000
+ timeout: count("timeout")
1001
+ };
1002
+ }
885
1003
  /**
886
1004
  * Accept a *pending inbound* REFER (surfaced as a `TransferRequested` event)
887
1005
  * and run the transfer. `target` overrides the Refer-To URI, `nextHop` steers
@@ -1091,6 +1209,47 @@ var Call = class {
1091
1209
  async streamStop() {
1092
1210
  await this.sip(SipVerb.StreamStop, {});
1093
1211
  }
1212
+ /**
1213
+ * Record this call's decoded audio to a wav file.
1214
+ *
1215
+ * The reply names the `recordingId` a later {@link Call.recordStop}
1216
+ * addresses. It is **not** the file: `RecordingFinished` fires when the file
1217
+ * is *closed* and names its path, which is what an app that mails the audio
1218
+ * has to wait for — acting on this reply races a half-written file.
1219
+ *
1220
+ * `maxDurationMs` and `silenceMs` are the two stop conditions a voicemail
1221
+ * greeting announces, and the engine evaluates both where the decoded audio
1222
+ * already is. Not SIPREC: this writes a file and works on a single-leg,
1223
+ * engine-terminated call, which is what a voicemail box is. siphon-rtp
1224
+ * backend only — rtpengine / rtpproxy reject with
1225
+ * `code === "unsupported_verb"`; a call with no anchored media session
1226
+ * rejects with `"not_found"`.
1227
+ */
1228
+ async recordStart(options) {
1229
+ const result = await this.sip(
1230
+ SipVerb.RecordStart,
1231
+ recordStartArgs(options)
1232
+ );
1233
+ const text = (name) => {
1234
+ const value = result?.[name];
1235
+ return typeof value === "string" ? value : void 0;
1236
+ };
1237
+ return {
1238
+ channel: text("channel") ?? this.channelId,
1239
+ recordingId: text("recording_id")
1240
+ };
1241
+ }
1242
+ /**
1243
+ * Stop the recording named by `recordingId`, or **every** recording on this
1244
+ * call when it is left out.
1245
+ *
1246
+ * Resolves once the engine has accepted the stop; the file is not closed yet.
1247
+ * `RecordingFinished` says that, and carries the path and the reason
1248
+ * (`stopped`, `max_duration`, `silence`, `call_ended`, `error`).
1249
+ */
1250
+ async recordStop(recordingId) {
1251
+ await this.sip(SipVerb.RecordStop, recordStopArgs(recordingId));
1252
+ }
1094
1253
  // --- escape hatch + events --------------------------------------------
1095
1254
  /** Send an arbitrary SIP-adapter verb + args and return the raw result. */
1096
1255
  async command(verb, args) {
@@ -1347,11 +1506,14 @@ exports.SUBPROTOCOL = SUBPROTOCOL;
1347
1506
  exports.SipClient = SipClient;
1348
1507
  exports.SipServer = SipServer;
1349
1508
  exports.SipVerb = SipVerb;
1509
+ exports.dialArgs = dialArgs;
1350
1510
  exports.encodeCommand = encodeCommand;
1351
1511
  exports.isBridgeFinal = isBridgeFinal;
1352
1512
  exports.isTransferFinal = isTransferFinal;
1353
1513
  exports.originateArgs = originateArgs;
1354
1514
  exports.parseInboundFrame = parseInboundFrame;
1515
+ exports.recordStartArgs = recordStartArgs;
1516
+ exports.recordStopArgs = recordStopArgs;
1355
1517
  exports.sipEventKind = sipEventKind;
1356
1518
  exports.transferOutcome = transferOutcome;
1357
1519
  //# sourceMappingURL=index.cjs.map