@siphon-project/control 0.8.0 → 0.9.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 +4 -4
- package/dist/index.cjs +108 -52
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +45 -21
- package/dist/index.d.ts +45 -21
- package/dist/index.js +108 -52
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -109,13 +109,13 @@ await client.command("sip", "answer", { channel: "ch1" }, { code: 200 });
|
|
|
109
109
|
| `setVar(key, value)` | `set_var` (substrate) | per-call variable |
|
|
110
110
|
| `getVar(key)` | `get_var` (substrate) | returns `string \| null` |
|
|
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 |
|
|
112
|
+
| `route(targets, strategy?, headers?)` | `route` (`sip`) | hand the call back to siphon with a routing decision: the targets are tried in order. A target's `route` is the route set its INVITE carries, topmost first. Refused `invalid_state` while a `dial` still rings; `cancelDial` first |
|
|
113
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
114
|
| `rejectRefer(code, reason?)` | `reject_refer` (`sip`) | decline a pending inbound REFER with a final non-2xx |
|
|
115
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 |
|
|
116
116
|
| `bridge(withChannel, options?)` | `bridge` (`sip`) | join two answered legs; the verdict arrives as `ChannelBridged` / `BridgeFailed` |
|
|
117
117
|
| `unbridge(reason?)` | `unbridge` (`sip`) | break the bridge — both legs stay answered, owned and held |
|
|
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 |
|
|
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. A `{uri}` target may carry `route`, the route set its INVITE carries, topmost first (`["<sip:term@scscf.example;lr;odi=4f1c>"]`), which is how an IMS application server sends a session back through the S-CSCF; a `route` on `{aor}` 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
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
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` |
|
|
121
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 |
|
|
@@ -138,8 +138,8 @@ addressing one:
|
|
|
138
138
|
|
|
139
139
|
| Method | Wire verb (`module`) | Notes |
|
|
140
140
|
| --- | --- | --- |
|
|
141
|
-
| `originate(channel, to, media, options?)` | `originate` (`sip`) | one URI, resolved as written; resolves once the INVITE is on the wire |
|
|
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` |
|
|
141
|
+
| `originate(channel, to, media, options?)` | `originate` (`sip`) | one URI, resolved as written; resolves once the INVITE is on the wire to the `Call` it placed, whose `nextEvent()` carries the answer, a rejection or the ring timeout. An id still live on this client is `conflict`, refused before anything is sent |
|
|
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? }`. The result carries the placed `call`. Nobody registered is `not_found` (`no_contacts`); `drop` is refused while the phones ring, use `hangup` |
|
|
143
143
|
|
|
144
144
|
The server implements every verb in these tables. `unsupported_verb`
|
|
145
145
|
(`error.isUnsupportedVerb()`) is what a verb answers when the configured media
|
package/dist/index.cjs
CHANGED
|
@@ -87,10 +87,10 @@ function encodeCommand(id, module, verb, target, args) {
|
|
|
87
87
|
frame.args = args ?? null;
|
|
88
88
|
return JSON.stringify(frame);
|
|
89
89
|
}
|
|
90
|
-
function parseInboundFrame(
|
|
90
|
+
function parseInboundFrame(text2) {
|
|
91
91
|
let value;
|
|
92
92
|
try {
|
|
93
|
-
value = JSON.parse(
|
|
93
|
+
value = JSON.parse(text2);
|
|
94
94
|
} catch {
|
|
95
95
|
return null;
|
|
96
96
|
}
|
|
@@ -263,7 +263,7 @@ var Session = class {
|
|
|
263
263
|
return Promise.reject(ControlError.closed());
|
|
264
264
|
}
|
|
265
265
|
const id = `c-${this.nextId.value++}`;
|
|
266
|
-
const
|
|
266
|
+
const text2 = encodeCommand(id, module, verb, target, args);
|
|
267
267
|
return new Promise((resolve, reject) => {
|
|
268
268
|
const timer = setTimeout(() => {
|
|
269
269
|
this.pending.delete(id);
|
|
@@ -271,7 +271,7 @@ var Session = class {
|
|
|
271
271
|
}, this.replyTimeoutMs);
|
|
272
272
|
this.pending.set(id, { resolve, reject, timer });
|
|
273
273
|
try {
|
|
274
|
-
this.socket.send(
|
|
274
|
+
this.socket.send(text2);
|
|
275
275
|
} catch (error) {
|
|
276
276
|
this.pending.delete(id);
|
|
277
277
|
clearTimeout(timer);
|
|
@@ -279,8 +279,8 @@ var Session = class {
|
|
|
279
279
|
}
|
|
280
280
|
});
|
|
281
281
|
}
|
|
282
|
-
onMessage(
|
|
283
|
-
const frame = parseInboundFrame(
|
|
282
|
+
onMessage(text2) {
|
|
283
|
+
const frame = parseInboundFrame(text2);
|
|
284
284
|
if (frame === null) {
|
|
285
285
|
return;
|
|
286
286
|
}
|
|
@@ -662,10 +662,18 @@ function insertTransferIdentity(args, identity) {
|
|
|
662
662
|
if (identity?.format !== void 0) args.format = identity.format;
|
|
663
663
|
if (identity?.headers !== void 0) args.headers = identity.headers;
|
|
664
664
|
}
|
|
665
|
+
function routeSetToWire(route) {
|
|
666
|
+
if (route === void 0 || route === null) return void 0;
|
|
667
|
+
if (!Array.isArray(route) || route.some((entry) => typeof entry !== "string")) {
|
|
668
|
+
throw new TypeError(`a target's "route" is an array of Route entry strings`);
|
|
669
|
+
}
|
|
670
|
+
return route.length === 0 ? void 0 : [...route];
|
|
671
|
+
}
|
|
665
672
|
function routeTargetToWire(target) {
|
|
666
673
|
if (typeof target === "string") {
|
|
667
674
|
return target;
|
|
668
675
|
}
|
|
676
|
+
const route = routeSetToWire(target.route);
|
|
669
677
|
const object = { uri: target.uri };
|
|
670
678
|
if (target.nextHop !== void 0) {
|
|
671
679
|
object.next_hop = target.nextHop;
|
|
@@ -679,6 +687,9 @@ function routeTargetToWire(target) {
|
|
|
679
687
|
if (target.rerouteAfterProgress === true) {
|
|
680
688
|
object.reroute_after_progress = true;
|
|
681
689
|
}
|
|
690
|
+
if (route !== void 0) {
|
|
691
|
+
object.route = route;
|
|
692
|
+
}
|
|
682
693
|
return object;
|
|
683
694
|
}
|
|
684
695
|
function stringValue(result) {
|
|
@@ -690,6 +701,10 @@ function stringValue(result) {
|
|
|
690
701
|
}
|
|
691
702
|
return null;
|
|
692
703
|
}
|
|
704
|
+
function text(result, name) {
|
|
705
|
+
const value = result?.[name];
|
|
706
|
+
return typeof value === "string" ? value : void 0;
|
|
707
|
+
}
|
|
693
708
|
function originateArgs(channel, to, media, options) {
|
|
694
709
|
return originateCommonArgs({ channel, to }, media, options);
|
|
695
710
|
}
|
|
@@ -739,6 +754,7 @@ function dialTargetToWire(target) {
|
|
|
739
754
|
const nextHop = target.nextHop;
|
|
740
755
|
const headers = target.headers;
|
|
741
756
|
const to = target.to;
|
|
757
|
+
const route = routeSetToWire(target.route);
|
|
742
758
|
if (to !== void 0 && typeof to !== "string") {
|
|
743
759
|
throw new TypeError(`a dial target's "to" is a SIP URI string`);
|
|
744
760
|
}
|
|
@@ -753,6 +769,11 @@ function dialTargetToWire(target) {
|
|
|
753
769
|
`an aor target takes no "nextHop": each of its branches routes over its own contact's captured flow`
|
|
754
770
|
);
|
|
755
771
|
}
|
|
772
|
+
if (route !== void 0) {
|
|
773
|
+
throw new TypeError(
|
|
774
|
+
`an aor target takes no "route": each of its branches follows its own contact's Path`
|
|
775
|
+
);
|
|
776
|
+
}
|
|
756
777
|
const object2 = { aor };
|
|
757
778
|
if (headers !== void 0) object2.headers = headers;
|
|
758
779
|
if (to !== void 0) object2.to = to;
|
|
@@ -761,11 +782,14 @@ function dialTargetToWire(target) {
|
|
|
761
782
|
if (typeof uri !== "string") {
|
|
762
783
|
throw new TypeError('a dial target requires a string "uri" or "aor"');
|
|
763
784
|
}
|
|
764
|
-
if (nextHop === void 0 && headers === void 0 && to === void 0)
|
|
785
|
+
if (nextHop === void 0 && headers === void 0 && to === void 0 && route === void 0) {
|
|
786
|
+
return uri;
|
|
787
|
+
}
|
|
765
788
|
const object = { uri };
|
|
766
789
|
if (nextHop !== void 0) object.next_hop = nextHop;
|
|
767
790
|
if (headers !== void 0) object.headers = headers;
|
|
768
791
|
if (to !== void 0) object.to = to;
|
|
792
|
+
if (route !== void 0) object.route = route;
|
|
769
793
|
return object;
|
|
770
794
|
}
|
|
771
795
|
function dialArgs(targets, options) {
|
|
@@ -1074,7 +1098,7 @@ var Call = class {
|
|
|
1074
1098
|
*
|
|
1075
1099
|
* `targets` is a non-empty list of carriers tried cheapest-first: each entry
|
|
1076
1100
|
* is a bare URI string or a {@link RouteTargetObject}
|
|
1077
|
-
* (`{uri, nextHop?, headers?, timeout?, rerouteAfterProgress?}`). A target
|
|
1101
|
+
* (`{uri, nextHop?, headers?, timeout?, rerouteAfterProgress?, route?}`). A target
|
|
1078
1102
|
* that has shown progress keeps the call past its `timeout` unless it sets
|
|
1079
1103
|
* `rerouteAfterProgress`. `strategy` defaults to
|
|
1080
1104
|
* `"sequential"` (v1 supports only sequential/single — anything else rejects
|
|
@@ -1151,7 +1175,7 @@ var Call = class {
|
|
|
1151
1175
|
*/
|
|
1152
1176
|
async dial(targets, options) {
|
|
1153
1177
|
const result = await this.sip(SipVerb.Dial, dialArgs(targets, options));
|
|
1154
|
-
const
|
|
1178
|
+
const text2 = (name) => {
|
|
1155
1179
|
const value = result?.[name];
|
|
1156
1180
|
return typeof value === "string" ? value : void 0;
|
|
1157
1181
|
};
|
|
@@ -1162,12 +1186,12 @@ var Call = class {
|
|
|
1162
1186
|
return {
|
|
1163
1187
|
// The server echoes the channel back; fall back to the one addressed
|
|
1164
1188
|
// rather than returning an empty id.
|
|
1165
|
-
channel:
|
|
1189
|
+
channel: text2("channel") ?? this.channelId,
|
|
1166
1190
|
targets: count("targets"),
|
|
1167
|
-
strategy:
|
|
1191
|
+
strategy: text2("strategy"),
|
|
1168
1192
|
timeout: count("timeout"),
|
|
1169
|
-
onAnswer:
|
|
1170
|
-
groupId:
|
|
1193
|
+
onAnswer: text2("on_answer"),
|
|
1194
|
+
groupId: text2("group_id"),
|
|
1171
1195
|
totalTimeout: count("total_timeout"),
|
|
1172
1196
|
ringback: (() => {
|
|
1173
1197
|
const value = result?.ringback;
|
|
@@ -1472,13 +1496,13 @@ var Call = class {
|
|
|
1472
1496
|
SipVerb.RecordStart,
|
|
1473
1497
|
recordStartArgs(options)
|
|
1474
1498
|
);
|
|
1475
|
-
const
|
|
1499
|
+
const text2 = (name) => {
|
|
1476
1500
|
const value = result?.[name];
|
|
1477
1501
|
return typeof value === "string" ? value : void 0;
|
|
1478
1502
|
};
|
|
1479
1503
|
return {
|
|
1480
|
-
channel:
|
|
1481
|
-
recordingId:
|
|
1504
|
+
channel: text2("channel") ?? this.channelId,
|
|
1505
|
+
recordingId: text2("recording_id")
|
|
1482
1506
|
};
|
|
1483
1507
|
}
|
|
1484
1508
|
/**
|
|
@@ -1597,6 +1621,25 @@ var SipFacade = class {
|
|
|
1597
1621
|
);
|
|
1598
1622
|
this.dispatch(call);
|
|
1599
1623
|
}
|
|
1624
|
+
/**
|
|
1625
|
+
* Open the event queue of a call this client is placing, before its
|
|
1626
|
+
* `originate` goes out: siphon sends no `StasisStart` for it, and its first
|
|
1627
|
+
* event can overtake the reply. `null` when the channel is already live here,
|
|
1628
|
+
* which must not be taken over.
|
|
1629
|
+
*/
|
|
1630
|
+
openChannel(channel) {
|
|
1631
|
+
if (this.channels.has(channel)) {
|
|
1632
|
+
return null;
|
|
1633
|
+
}
|
|
1634
|
+
const queue = new AsyncQueue();
|
|
1635
|
+
this.channels.set(channel, queue);
|
|
1636
|
+
return queue;
|
|
1637
|
+
}
|
|
1638
|
+
/** Close a channel {@link SipFacade.openChannel} opened for a refused originate. */
|
|
1639
|
+
closeChannel(channel) {
|
|
1640
|
+
this.channels.get(channel)?.close();
|
|
1641
|
+
this.channels.delete(channel);
|
|
1642
|
+
}
|
|
1600
1643
|
route(channel, event) {
|
|
1601
1644
|
this.channels.get(channel)?.push(event);
|
|
1602
1645
|
}
|
|
@@ -1669,8 +1712,14 @@ var SipClient = class _SipClient {
|
|
|
1669
1712
|
*
|
|
1670
1713
|
* The one verb that *creates* a channel rather than addressing one, which is
|
|
1671
1714
|
* why it lives here and not on {@link Call}. It resolves as soon as the
|
|
1672
|
-
* INVITE is on the wire — the call is `calling
|
|
1673
|
-
*
|
|
1715
|
+
* INVITE is on the wire — the call is `calling` — to the {@link Call} it
|
|
1716
|
+
* placed: the answer, failure or timeout arrives on {@link Call.nextEvent},
|
|
1717
|
+
* exactly as a handed-over call's does, and `hangup` CANCELs or BYEs it.
|
|
1718
|
+
*
|
|
1719
|
+
* siphon sends no `StasisStart` for a channel its controller created, so the
|
|
1720
|
+
* channel is opened here before the command goes out (a fast 180 can
|
|
1721
|
+
* overtake the reply). An id still live on this client rejects with
|
|
1722
|
+
* `code === "conflict"` before anything is sent.
|
|
1674
1723
|
*
|
|
1675
1724
|
* ```ts
|
|
1676
1725
|
* const call = await client.originate(
|
|
@@ -1682,23 +1731,8 @@ var SipClient = class _SipClient {
|
|
|
1682
1731
|
* ```
|
|
1683
1732
|
*/
|
|
1684
1733
|
async originate(channel, to, media, options) {
|
|
1685
|
-
const result = await this.
|
|
1686
|
-
|
|
1687
|
-
"originate",
|
|
1688
|
-
null,
|
|
1689
|
-
originateArgs(channel, to, media, options)
|
|
1690
|
-
);
|
|
1691
|
-
const text = (name) => {
|
|
1692
|
-
const value = result?.[name];
|
|
1693
|
-
return typeof value === "string" ? value : void 0;
|
|
1694
|
-
};
|
|
1695
|
-
return {
|
|
1696
|
-
// The server echoes the id back; fall back to the one we asked for
|
|
1697
|
-
// rather than returning an empty channel a caller cannot address.
|
|
1698
|
-
channel: text("channel") ?? channel,
|
|
1699
|
-
callId: text("call_id"),
|
|
1700
|
-
sipCallId: text("sip_call_id")
|
|
1701
|
-
};
|
|
1734
|
+
const { result, queue } = await this.place(channel, originateArgs(channel, to, media, options));
|
|
1735
|
+
return this.placedCall(channel, text(result, "call_id"), text(result, "sip_call_id"), result, queue);
|
|
1702
1736
|
}
|
|
1703
1737
|
/**
|
|
1704
1738
|
* Ring every phone registered at `aor` under a caller-supplied channel id —
|
|
@@ -1733,29 +1767,51 @@ var SipClient = class _SipClient {
|
|
|
1733
1767
|
* ```
|
|
1734
1768
|
*/
|
|
1735
1769
|
async originateAor(channel, aor, media, options, ring) {
|
|
1736
|
-
const result = await this.
|
|
1737
|
-
|
|
1738
|
-
"originate",
|
|
1739
|
-
null,
|
|
1770
|
+
const { result, queue } = await this.place(
|
|
1771
|
+
channel,
|
|
1740
1772
|
originateAorArgs(channel, aor, media, options, ring)
|
|
1741
1773
|
);
|
|
1742
|
-
const
|
|
1743
|
-
|
|
1744
|
-
return typeof value === "string" ? value : void 0;
|
|
1745
|
-
};
|
|
1746
|
-
const count = (name) => {
|
|
1747
|
-
const value = result?.[name];
|
|
1748
|
-
return typeof value === "number" ? value : void 0;
|
|
1749
|
-
};
|
|
1774
|
+
const groupId = text(result, "group_id");
|
|
1775
|
+
const totalTimeout = result?.total_timeout;
|
|
1750
1776
|
return {
|
|
1751
|
-
|
|
1752
|
-
|
|
1753
|
-
|
|
1754
|
-
|
|
1755
|
-
|
|
1777
|
+
// The server echoes the id back; fall back to the one we asked for
|
|
1778
|
+
// rather than returning an empty channel a caller cannot address.
|
|
1779
|
+
channel: text(result, "channel") ?? channel,
|
|
1780
|
+
// Until a phone answers, the group stands in for the call, as its events say.
|
|
1781
|
+
call: this.placedCall(channel, groupId, groupId, result, queue),
|
|
1782
|
+
groupId,
|
|
1783
|
+
aor: text(result, "aor"),
|
|
1784
|
+
strategy: text(result, "strategy"),
|
|
1785
|
+
totalTimeout: typeof totalTimeout === "number" ? totalTimeout : void 0,
|
|
1756
1786
|
branches: branchList(result?.branches) ?? []
|
|
1757
1787
|
};
|
|
1758
1788
|
}
|
|
1789
|
+
/** Open `channel`, send the originate, and close it again if the server refuses. */
|
|
1790
|
+
async place(channel, args) {
|
|
1791
|
+
const queue = this.facade.openChannel(channel);
|
|
1792
|
+
if (queue === null) {
|
|
1793
|
+
throw ControlError.command("conflict", `channel ${channel} is already live on this client`);
|
|
1794
|
+
}
|
|
1795
|
+
try {
|
|
1796
|
+
const result = await this.client.command(MODULE_SIP, "originate", null, args);
|
|
1797
|
+
return { result, queue };
|
|
1798
|
+
} catch (error) {
|
|
1799
|
+
this.facade.closeChannel(channel);
|
|
1800
|
+
throw error;
|
|
1801
|
+
}
|
|
1802
|
+
}
|
|
1803
|
+
placedCall(channel, callId, sipCallId, reply, queue) {
|
|
1804
|
+
return new Call(
|
|
1805
|
+
this.client.commander(),
|
|
1806
|
+
channel,
|
|
1807
|
+
callId ?? null,
|
|
1808
|
+
sipCallId ?? null,
|
|
1809
|
+
null,
|
|
1810
|
+
reply,
|
|
1811
|
+
false,
|
|
1812
|
+
queue
|
|
1813
|
+
);
|
|
1814
|
+
}
|
|
1759
1815
|
/** Send a raw command on any module (the generic escape hatch). */
|
|
1760
1816
|
command(module, verb, target, args) {
|
|
1761
1817
|
return this.client.command(module, verb, target, args);
|