@siphon-project/control 0.3.0 → 0.4.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,56 @@ 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
+ return args;
728
+ }
729
+ function recordStartArgs(options) {
730
+ const args = {};
731
+ if (!options) return args;
732
+ if (options.direction !== void 0) args.direction = options.direction;
733
+ if (options.channels !== void 0) args.channels = options.channels;
734
+ if (options.maxDurationMs !== void 0) args.max_duration_ms = options.maxDurationMs;
735
+ if (options.silenceMs !== void 0) args.silence_ms = options.silenceMs;
736
+ if (options.path !== void 0) args.path = options.path;
737
+ return args;
738
+ }
739
+ function recordStopArgs(recordingId) {
740
+ return recordingId === void 0 ? {} : { recording_id: recordingId };
741
+ }
683
742
  function playArgs(source, options) {
684
743
  const args = {};
685
744
  if ("file" in source) {
@@ -882,6 +941,58 @@ var Call = class {
882
941
  }
883
942
  return this.sip(SipVerb.Route, args);
884
943
  }
944
+ /**
945
+ * Ring `targets` as B-legs while the caller stays **unanswered** and this
946
+ * application keeps the channel.
947
+ *
948
+ * The difference from {@link Call.route} is who holds the call afterwards.
949
+ * `route` hands it back to siphon, so the app gets `StasisEnd{reason: routed}`
950
+ * and loses it; there is then no way to say "ring the extension, and if nobody
951
+ * answers, voicemail" without answering the caller first — which starts
952
+ * billing before anyone picks up, records an unanswered call as answered, and
953
+ * denies the caller the callee's own ringback.
954
+ *
955
+ * The first 2xx answers the caller with the winner's SDP and the pair becomes
956
+ * an ordinary two-leg call, still owned by this app. A failure or timeout
957
+ * arrives as a `DialFailed` event with the caller still ringing and still
958
+ * parked, so the app decides what happens next.
959
+ *
960
+ * Each target is a URI (dialed as written) or an `{aor}` (forked to every
961
+ * registered contact over its own flow) — see {@link DialTarget}, and note
962
+ * that a target naming both, or neither, throws before anything is sent.
963
+ *
964
+ * ```ts
965
+ * const dialing = await call.dial(
966
+ * [{ aor: "sip:204@pbx.example" }],
967
+ * { strategy: "sequential", timeout: 20 },
968
+ * );
969
+ * ```
970
+ *
971
+ * Rejects with `code === "not_found"` (the call is gone, or no target yielded
972
+ * a branch — an AoR nobody has registered), `"invalid_state"` (already
973
+ * answered, which is what this verb exists to avoid), `"bad_request"` (an
974
+ * empty or malformed target list) or `"unsupported_verb"` (a strategy siphon
975
+ * does not implement).
976
+ */
977
+ async dial(targets, options) {
978
+ const result = await this.sip(SipVerb.Dial, dialArgs(targets, options));
979
+ const text = (name) => {
980
+ const value = result?.[name];
981
+ return typeof value === "string" ? value : void 0;
982
+ };
983
+ const count = (name) => {
984
+ const value = result?.[name];
985
+ return typeof value === "number" ? value : void 0;
986
+ };
987
+ return {
988
+ // The server echoes the channel back; fall back to the one addressed
989
+ // rather than returning an empty id.
990
+ channel: text("channel") ?? this.channelId,
991
+ targets: count("targets"),
992
+ strategy: text("strategy"),
993
+ timeout: count("timeout")
994
+ };
995
+ }
885
996
  /**
886
997
  * Accept a *pending inbound* REFER (surfaced as a `TransferRequested` event)
887
998
  * and run the transfer. `target` overrides the Refer-To URI, `nextHop` steers
@@ -1091,6 +1202,47 @@ var Call = class {
1091
1202
  async streamStop() {
1092
1203
  await this.sip(SipVerb.StreamStop, {});
1093
1204
  }
1205
+ /**
1206
+ * Record this call's decoded audio to a wav file.
1207
+ *
1208
+ * The reply names the `recordingId` a later {@link Call.recordStop}
1209
+ * addresses. It is **not** the file: `RecordingFinished` fires when the file
1210
+ * is *closed* and names its path, which is what an app that mails the audio
1211
+ * has to wait for — acting on this reply races a half-written file.
1212
+ *
1213
+ * `maxDurationMs` and `silenceMs` are the two stop conditions a voicemail
1214
+ * greeting announces, and the engine evaluates both where the decoded audio
1215
+ * already is. Not SIPREC: this writes a file and works on a single-leg,
1216
+ * engine-terminated call, which is what a voicemail box is. siphon-rtp
1217
+ * backend only — rtpengine / rtpproxy reject with
1218
+ * `code === "unsupported_verb"`; a call with no anchored media session
1219
+ * rejects with `"not_found"`.
1220
+ */
1221
+ async recordStart(options) {
1222
+ const result = await this.sip(
1223
+ SipVerb.RecordStart,
1224
+ recordStartArgs(options)
1225
+ );
1226
+ const text = (name) => {
1227
+ const value = result?.[name];
1228
+ return typeof value === "string" ? value : void 0;
1229
+ };
1230
+ return {
1231
+ channel: text("channel") ?? this.channelId,
1232
+ recordingId: text("recording_id")
1233
+ };
1234
+ }
1235
+ /**
1236
+ * Stop the recording named by `recordingId`, or **every** recording on this
1237
+ * call when it is left out.
1238
+ *
1239
+ * Resolves once the engine has accepted the stop; the file is not closed yet.
1240
+ * `RecordingFinished` says that, and carries the path and the reason
1241
+ * (`stopped`, `max_duration`, `silence`, `call_ended`, `error`).
1242
+ */
1243
+ async recordStop(recordingId) {
1244
+ await this.sip(SipVerb.RecordStop, recordStopArgs(recordingId));
1245
+ }
1094
1246
  // --- escape hatch + events --------------------------------------------
1095
1247
  /** Send an arbitrary SIP-adapter verb + args and return the raw result. */
1096
1248
  async command(verb, args) {
@@ -1347,11 +1499,14 @@ exports.SUBPROTOCOL = SUBPROTOCOL;
1347
1499
  exports.SipClient = SipClient;
1348
1500
  exports.SipServer = SipServer;
1349
1501
  exports.SipVerb = SipVerb;
1502
+ exports.dialArgs = dialArgs;
1350
1503
  exports.encodeCommand = encodeCommand;
1351
1504
  exports.isBridgeFinal = isBridgeFinal;
1352
1505
  exports.isTransferFinal = isTransferFinal;
1353
1506
  exports.originateArgs = originateArgs;
1354
1507
  exports.parseInboundFrame = parseInboundFrame;
1508
+ exports.recordStartArgs = recordStartArgs;
1509
+ exports.recordStopArgs = recordStopArgs;
1355
1510
  exports.sipEventKind = sipEventKind;
1356
1511
  exports.transferOutcome = transferOutcome;
1357
1512
  //# sourceMappingURL=index.cjs.map