@siphon-project/control 0.6.0 → 0.8.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
@@ -94,6 +94,8 @@ await client.command("sip", "answer", { channel: "ch1" }, { code: 200 });
94
94
  | Method | Wire verb (`module`) | Notes |
95
95
  | --- | --- | --- |
96
96
  | `answer(options?)` | `answer` (`sip`) | UAS 2xx (default `200 OK`) |
97
+ | `answerAnchored(options?)` | `answer` (`sip`) | answer and anchor the caller's media on the media engine in one act (`profile`, `wsUri`); what `play`, `hold` and `dial` with `onAnswer: "bridge"` need |
98
+ | `ring(reason?)` | `ring` (`sip`) | `180 Ringing`: alerting only, no early media |
97
99
  | `progress(options?)` | `progress` (`sip`) | UAS 1xx / early media (default `183`) |
98
100
  | `reject(code, reason?)` | `reject` (`sip`) | final non-2xx + teardown |
99
101
  | `terminate(reason?)` | `hangup` (`sip`) | primary teardown name |
@@ -106,16 +108,25 @@ await client.command("sip", "answer", { channel: "ch1" }, { code: 200 });
106
108
  | `getHeader(name)` | `get_header` (`sip`) | returns `string \| null` |
107
109
  | `setVar(key, value)` | `set_var` (substrate) | per-call variable |
108
110
  | `getVar(key)` | `get_var` (substrate) | returns `string \| null` |
109
- | `removeHeader(name)` | `remove_header` (`sip`) | ‡ |
110
- | `acceptRefer(options?)` | `accept_refer` (`sip`) | ‡ |
111
- | `rejectRefer(code, reason?)` | `reject_refer` (`sip`) | ‡ |
111
+ | `removeHeader(name)` | `remove_header` (`sip`) | on the stored A-leg INVITE |
112
+ | `route(targets, strategy?, headers?)` | `route` (`sip`) | hand the call back to siphon with a routing decision: the targets are tried in order. Refused `invalid_state` while a `dial` still rings; `cancelDial` first |
113
+ | `acceptRefer(options?)` | `accept_refer` (`sip`) | accept a pending inbound REFER (a `TransferRequested` event). `mode` is `"terminate"` (siphon dials the target), `"transparent"` (siphon relays the REFER) or `"controller"` (siphon answers `202` and dials nothing; this app moves the parties and reports with `completeRefer` within `timeout` seconds, default 60, at most 180). `target` is a URI string or `{ aor }`, a registered address-of-record dialled over the flow its phone registered on, every registered contact rung and the first to answer kept. `from`, `fromDisplay`, `pAssertedIdentity`, `privacy` and `headers` shape the leg the transfer dials, and `numberPolicy` (a number policy configured on the server) or `format` says how the numbers in them are written. `{ aor }` and the identity options go with `"terminate"`; `"controller"` takes `timeout` only, and `timeout` goes with no other mode. The server refuses the rest |
114
+ | `rejectRefer(code, reason?)` | `reject_refer` (`sip`) | decline a pending inbound REFER with a final non-2xx |
115
+ | `completeRefer(code, reason?)` | `complete_refer` (`sip`) | report how a transfer accepted with `acceptRefer({ mode: "controller" })` went: the referrer gets the sipfrag NOTIFY that ends its subscription, a 2xx for success. Report before releasing the referrer's leg |
112
116
  | `bridge(withChannel, options?)` | `bridge` (`sip`) | join two answered legs; the verdict arrives as `ChannelBridged` / `BridgeFailed` |
113
117
  | `unbridge(reason?)` | `unbridge` (`sip`) | break the bridge — both legs stay answered, owned and held |
114
118
  | `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. `onAnswer: "bridge"` rings phones for an **answered**, anchored caller and bridges the first to pick up, with `ringback` playing meanwhile; `ringback` without it throws |
119
+ | `cancelDial(reason?)` | `cancel_dial` (`sip`) | give up on the dial ringing for this call and leave the caller alone: the phones are CANCELled, each reported by `DialBranchFailed` (cause `cancelled`), and the dial ends in `DialFailed` with code 487. `reason` is the `cause` of a bridging dial's `DialFailed` (default `cancelled`). Refused `invalid_state` when nothing is ringing, and once a phone has answered and is being bridged |
120
+ | `replacePeer(target, options?)` | `replace_peer` (`sip`) | swap one party of this answered call for a freshly dialled target, no REFER involved; the replaced leg stays up while the target rings. `target` is a URI string or `{ aor }`, and `options` takes `nextHop`, `replaceALeg`, `profile`, `timeout` and the identity options of `acceptRefer`. The verdict arrives as `PeerReplaced` / `ReplaceFailed` |
115
121
  | `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 |
116
122
  | `recordStop(recordingId?)` | `record_stop` (`sip`) | stop one recording, or every recording on the call when no id is given |
117
- | `playFile(file)` | `play` (`sip`) | ‡ media |
118
- | `dtmf(digits)` | `dtmf` (`sip`) | ‡ media |
123
+ | `play(source, options?)` | `play` (`sip`) | play `{ file }`, `{ dbId }`, `{ blob }`, `{ tone }` (a preset or a cadence) or `{ url }` (HTTP or HTTPS) on the caller's media. `options.repeat` is a total play count, or `"inf"` to play until stopped (`stop` ends it); also `startMs`, `durationMs`, `gainDecibels`, `toTag`. Needs an anchored media session (`not_found` without one) |
124
+ | `playFile(file)` | `play` (`sip`) | `play({ file })` with default options |
125
+ | `stop()` | `stop` (`sip`) | stop the announcement that is playing |
126
+ | `dtmf(digits, options?)` | `dtmf` (`sip`) | inject DTMF digits toward the caller (`durationMs`, `volumeDbm0`, `pauseMs`, `toTag`) |
127
+ | `hold()` / `unhold()` | `hold` / `unhold` (`sip`) | silence, then restore, the call's media on the engine. A media gate, not a SIP hold; refused `invalid_state` on a call the engine only relays |
128
+ | `streamStart(wsUri, options?)` | `stream_start` (`sip`) | stream the call's audio to a WebSocket server: `mode: "tee"` (default, a copy) or `"bridge"` (a takeover). siphon-rtp only |
129
+ | `streamStop(options?)` | `stream_stop` (`sip`) | detach the stream of `options.mode` |
119
130
  | `command(verb, args?)` | (`sip`) | arbitrary SIP-adapter verb |
120
131
  | `nextEvent()` / `events()` | — | per-call event stream |
121
132
 
@@ -130,9 +141,10 @@ addressing one:
130
141
  | `originate(channel, to, media, options?)` | `originate` (`sip`) | one URI, resolved as written; resolves once the INVITE is on the wire |
131
142
  | `originateAor(channel, aor, media, options?, ring?)` | `originate` (`sip`) | ring every phone registered at `aor` over its own flow and Path; first to answer wins. `ring` is `{ strategy?, totalTimeout? }`. Nobody registered is `not_found` (`no_contacts`); `drop` is refused while the phones ring, use `hangup` |
132
143
 
133
- ‡ Accepted verb names the Phase-1 server answers with a `ControlError` whose
134
- `.code === "unsupported_verb"` (`error.isUnsupportedVerb()`) until it implements
135
- them. They send a real command — nothing is stubbed client-side.
144
+ The server implements every verb in these tables. `unsupported_verb`
145
+ (`error.isUnsupportedVerb()`) is what a verb answers when the configured media
146
+ backend cannot carry it out: `streamStart` / `streamStop` and `recordStart` /
147
+ `recordStop` on rtpengine or rtpproxy, and `play` with `repeat: "inf"` there.
136
148
 
137
149
  ## Errors
138
150
 
@@ -144,10 +156,10 @@ Transport / handshake / timeout failures throw a `ControlError` with a `.kind`
144
156
 
145
157
  ```ts
146
158
  try {
147
- await call.playFile("/prompts/welcome.wav");
159
+ await call.streamStart("wss://transcriber.example.com/stream");
148
160
  } catch (error) {
149
161
  if (error instanceof ControlError && error.isUnsupportedVerb()) {
150
- // media isn't wired server-side yet — fall back gracefully
162
+ // the configured media backend cannot stream — carry on without it
151
163
  }
152
164
  }
153
165
  ```
package/dist/index.cjs CHANGED
@@ -23,8 +23,9 @@ var ControlError = class _ControlError extends Error {
23
23
  Object.setPrototypeOf(this, _ControlError.prototype);
24
24
  }
25
25
  /**
26
- * True when this is a server-side `unsupported_verb` rejection — the state a
27
- * media verb (`playFile`/`dtmf`/…) lands in until the server implements it.
26
+ * True when this is a server-side `unsupported_verb` rejection — what a verb
27
+ * answers when the configured media backend cannot carry it out (streaming
28
+ * and recording on anything but siphon-rtp).
28
29
  */
29
30
  isUnsupportedVerb() {
30
31
  return this.kind === "command" && this.code === "unsupported_verb";
@@ -136,11 +137,19 @@ var SipVerb = {
136
137
  * the channel. Channel-addressed, unlike `originate`, which creates one.
137
138
  */
138
139
  Dial: "dial",
140
+ /**
141
+ * Give up on the dial ringing for this channel's caller and leave the caller
142
+ * alone: the phones are CANCELled and the dial ends in `DialFailed` with code
143
+ * 487. Refused (`invalid_state`) when nothing is ringing, and once a phone
144
+ * has answered and is being bridged.
145
+ */
146
+ CancelDial: "cancel_dial",
139
147
  SetHeader: "set_header",
140
148
  GetHeader: "get_header",
141
149
  RemoveHeader: "remove_header",
142
150
  AcceptRefer: "accept_refer",
143
151
  RejectRefer: "reject_refer",
152
+ CompleteRefer: "complete_refer",
144
153
  Bridge: "bridge",
145
154
  Unbridge: "unbridge",
146
155
  ReplacePeer: "replace_peer",
@@ -642,6 +651,17 @@ function responseArgs(options) {
642
651
  }
643
652
  return args;
644
653
  }
654
+ function insertTransferIdentity(args, identity) {
655
+ if (identity?.from !== void 0) args.from = identity.from;
656
+ if (identity?.fromDisplay !== void 0) args.from_display = identity.fromDisplay;
657
+ if (identity?.pAssertedIdentity !== void 0) {
658
+ args.p_asserted_identity = identity.pAssertedIdentity;
659
+ }
660
+ if (identity?.privacy !== void 0) args.privacy = identity.privacy;
661
+ if (identity?.numberPolicy !== void 0) args.number_policy = identity.numberPolicy;
662
+ if (identity?.format !== void 0) args.format = identity.format;
663
+ if (identity?.headers !== void 0) args.headers = identity.headers;
664
+ }
645
665
  function routeTargetToWire(target) {
646
666
  if (typeof target === "string") {
647
667
  return target;
@@ -718,6 +738,10 @@ function dialTargetToWire(target) {
718
738
  const aor = target.aor;
719
739
  const nextHop = target.nextHop;
720
740
  const headers = target.headers;
741
+ const to = target.to;
742
+ if (to !== void 0 && typeof to !== "string") {
743
+ throw new TypeError(`a dial target's "to" is a SIP URI string`);
744
+ }
721
745
  if (typeof uri === "string" && typeof aor === "string") {
722
746
  throw new TypeError(
723
747
  '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'
@@ -731,15 +755,17 @@ function dialTargetToWire(target) {
731
755
  }
732
756
  const object2 = { aor };
733
757
  if (headers !== void 0) object2.headers = headers;
758
+ if (to !== void 0) object2.to = to;
734
759
  return object2;
735
760
  }
736
761
  if (typeof uri !== "string") {
737
762
  throw new TypeError('a dial target requires a string "uri" or "aor"');
738
763
  }
739
- if (nextHop === void 0 && headers === void 0) return uri;
764
+ if (nextHop === void 0 && headers === void 0 && to === void 0) return uri;
740
765
  const object = { uri };
741
766
  if (nextHop !== void 0) object.next_hop = nextHop;
742
767
  if (headers !== void 0) object.headers = headers;
768
+ if (to !== void 0) object.to = to;
743
769
  return object;
744
770
  }
745
771
  function dialArgs(targets, options) {
@@ -798,6 +824,10 @@ function playArgs(source, options) {
798
824
  args.file = source.file;
799
825
  } else if ("dbId" in source) {
800
826
  args.db_id = source.dbId;
827
+ } else if ("tone" in source) {
828
+ args.tone = source.tone;
829
+ } else if ("url" in source) {
830
+ args.url = source.url;
801
831
  } else {
802
832
  args.blob = Buffer.from(source.blob).toString("base64");
803
833
  }
@@ -810,6 +840,9 @@ function playArgs(source, options) {
810
840
  if (options?.durationMs !== void 0) {
811
841
  args.duration_ms = options.durationMs;
812
842
  }
843
+ if (options?.gainDecibels !== void 0) {
844
+ args.gain_decibels = options.gainDecibels;
845
+ }
813
846
  if (options?.toTag !== void 0) {
814
847
  args.to_tag = options.toTag;
815
848
  }
@@ -979,6 +1012,32 @@ var Call = class {
979
1012
  }
980
1013
  await this.sip(SipVerb.Drop, args);
981
1014
  }
1015
+ /**
1016
+ * Give up on the dial ringing for this call and leave the caller alone.
1017
+ *
1018
+ * Every phone still ringing is CANCELled (RFC 3261 §9.1), each reported by
1019
+ * `DialBranchFailed` with cause `cancelled`, and the dial ends in
1020
+ * `DialFailed` with code 487. The caller is exactly as the dial found it —
1021
+ * answered and anchored for an `onAnswer: "bridge"` dial, unanswered and
1022
+ * parked otherwise — still this app's, and free to be dialled for again.
1023
+ * {@link Call.hangup} ends the caller as well.
1024
+ *
1025
+ * `reason` is reported as the `cause` of a bridging dial's `DialFailed`
1026
+ * (default `cancelled`), so the handler that hears it can tell its own cancel
1027
+ * from a dial that failed by itself.
1028
+ *
1029
+ * Rejects with `invalid_state` when nothing is ringing (`details.reason` is
1030
+ * `no_dial_in_progress`), and once a phone has answered and is being bridged
1031
+ * (`dial_answered`), whose outcome arrives as `DialAnswered` or
1032
+ * `BridgeFailed`.
1033
+ */
1034
+ async cancelDial(reason) {
1035
+ const args = {};
1036
+ if (reason !== void 0) {
1037
+ args.reason = reason;
1038
+ }
1039
+ await this.sip(SipVerb.CancelDial, args);
1040
+ }
982
1041
  /**
983
1042
  * Send an in-dialog REFER on the A-leg (blind transfer).
984
1043
  *
@@ -1124,6 +1183,9 @@ var Call = class {
1124
1183
  * `b2bua.default_refer_mode`. No pending REFER (already decided, timed out, or
1125
1184
  * the call is gone) rejects with `code === "not_found"`.
1126
1185
  *
1186
+ * `mode: "controller"` leaves the transfer to this application — see
1187
+ * {@link AcceptReferOptions.mode} and {@link Call.completeRefer}.
1188
+ *
1127
1189
  * `profile` names the media profile for the pairing the transfer creates —
1128
1190
  * see {@link AcceptReferOptions.profile}, which is required at an SRTP edge.
1129
1191
  */
@@ -1141,8 +1203,32 @@ var Call = class {
1141
1203
  if (options?.profile !== void 0) {
1142
1204
  args.profile = options.profile;
1143
1205
  }
1206
+ if (options?.timeout !== void 0) {
1207
+ args.timeout = options.timeout;
1208
+ }
1209
+ insertTransferIdentity(args, options);
1144
1210
  await this.sip(SipVerb.AcceptRefer, args);
1145
1211
  }
1212
+ /**
1213
+ * Report how a transfer accepted with `acceptRefer({ mode: "controller" })`
1214
+ * went: the server sends the referrer the sipfrag NOTIFY that ends its
1215
+ * subscription. `code` is the status in it (200-699), a 2xx for a transfer
1216
+ * that succeeded, and `reason` its reason phrase, used as given. Nothing
1217
+ * else happens to the call.
1218
+ *
1219
+ * **Report before releasing the referrer's leg.** The NOTIFY travels on its
1220
+ * dialog, so once that leg is hung up or replaced this rejects with
1221
+ * `code === "not_found"`. With no such transfer open on the call — already
1222
+ * reported, past its deadline, or its referrer hung up — it rejects with
1223
+ * `code === "invalid_state"` (`details.reason === "no_transfer_pending"`).
1224
+ */
1225
+ async completeRefer(code, reason) {
1226
+ const args = { code };
1227
+ if (reason !== void 0) {
1228
+ args.reason = reason;
1229
+ }
1230
+ await this.sip(SipVerb.CompleteRefer, args);
1231
+ }
1146
1232
  /**
1147
1233
  * Reject a *pending inbound* REFER with a final non-2xx (default
1148
1234
  * `603 Decline`). No pending REFER rejects with `code === "not_found"`.
@@ -1249,6 +1335,7 @@ var Call = class {
1249
1335
  if (options.replaceALeg !== void 0) args.replace_a_leg = options.replaceALeg;
1250
1336
  if (options.profile !== void 0) args.profile = options.profile;
1251
1337
  if (options.timeout !== void 0) args.timeout = options.timeout;
1338
+ insertTransferIdentity(args, options);
1252
1339
  return this.sip(SipVerb.ReplacePeer, args);
1253
1340
  }
1254
1341
  /** Set a header on the stored A-leg INVITE. */
@@ -1299,11 +1386,17 @@ var Call = class {
1299
1386
  async dtmf(digits, options) {
1300
1387
  await this.sip(SipVerb.Dtmf, dtmfArgs(digits, options));
1301
1388
  }
1302
- /** Hold the A-leg media via silence. */
1389
+ /**
1390
+ * Silence the call's media in both directions on the media engine.
1391
+ *
1392
+ * A media gate, not a SIP hold: nothing is sent on either dialog, so no
1393
+ * phone shows a held call. Rejects with `invalid_state` on a call the engine
1394
+ * only relays; to hold one party of a bridge, use {@link Call.unbridge}.
1395
+ */
1303
1396
  async hold() {
1304
1397
  await this.sip(SipVerb.Hold, {});
1305
1398
  }
1306
- /** Resume the A-leg media after a {@link Call.hold}. */
1399
+ /** Restore the call's media after a {@link Call.hold}. */
1307
1400
  async unhold() {
1308
1401
  await this.sip(SipVerb.Unhold, {});
1309
1402
  }
@@ -1318,8 +1411,9 @@ var Call = class {
1318
1411
  * direction: "caller",
1319
1412
  * sampleRate: 16000,
1320
1413
  * });
1321
- * // Hand the leg to a voice agent; the agent is now the far side.
1322
- * await call.streamStart("wss://ai.example/agent", { mode: "bridge" });
1414
+ * // Hand the leg to a voice agent; the agent is now the far side, with the
1415
+ * // server's `voice_ai` profile's rate, echo cancellation and barge-in.
1416
+ * await call.streamStart("wss://ai.example/agent", { mode: "bridge", profile: "voice_ai" });
1323
1417
  * ```
1324
1418
  *
1325
1419
  * A bridge on a leg that already has one re-points it in place. `wsUri` may
@@ -1343,6 +1437,9 @@ var Call = class {
1343
1437
  if (options?.sampleRate !== void 0) {
1344
1438
  args.sample_rate = options.sampleRate;
1345
1439
  }
1440
+ if (options?.profile !== void 0) {
1441
+ args.profile = options.profile;
1442
+ }
1346
1443
  await this.sip(SipVerb.StreamStart, args);
1347
1444
  }
1348
1445
  /**