@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 +22 -10
- package/dist/index.cjs +104 -7
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +214 -15
- package/dist/index.d.ts +214 -15
- package/dist/index.js +104 -7
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
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
|
-
| `
|
|
111
|
-
| `
|
|
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
|
-
| `
|
|
118
|
-
| `
|
|
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
|
-
|
|
134
|
-
|
|
135
|
-
|
|
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.
|
|
159
|
+
await call.streamStart("wss://transcriber.example.com/stream");
|
|
148
160
|
} catch (error) {
|
|
149
161
|
if (error instanceof ControlError && error.isUnsupportedVerb()) {
|
|
150
|
-
// media
|
|
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 —
|
|
27
|
-
*
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
-
*
|
|
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
|
/**
|