@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/dist/index.d.ts
CHANGED
|
@@ -31,8 +31,9 @@ declare class ControlError extends Error {
|
|
|
31
31
|
status?: number;
|
|
32
32
|
});
|
|
33
33
|
/**
|
|
34
|
-
* True when this is a server-side `unsupported_verb` rejection —
|
|
35
|
-
*
|
|
34
|
+
* True when this is a server-side `unsupported_verb` rejection — what a verb
|
|
35
|
+
* answers when the configured media backend cannot carry it out (streaming
|
|
36
|
+
* and recording on anything but siphon-rtp).
|
|
36
37
|
*/
|
|
37
38
|
isUnsupportedVerb(): boolean;
|
|
38
39
|
/** A server `status:"error"` reply. */
|
|
@@ -200,11 +201,19 @@ declare const SipVerb: {
|
|
|
200
201
|
* the channel. Channel-addressed, unlike `originate`, which creates one.
|
|
201
202
|
*/
|
|
202
203
|
readonly Dial: "dial";
|
|
204
|
+
/**
|
|
205
|
+
* Give up on the dial ringing for this channel's caller and leave the caller
|
|
206
|
+
* alone: the phones are CANCELled and the dial ends in `DialFailed` with code
|
|
207
|
+
* 487. Refused (`invalid_state`) when nothing is ringing, and once a phone
|
|
208
|
+
* has answered and is being bridged.
|
|
209
|
+
*/
|
|
210
|
+
readonly CancelDial: "cancel_dial";
|
|
203
211
|
readonly SetHeader: "set_header";
|
|
204
212
|
readonly GetHeader: "get_header";
|
|
205
213
|
readonly RemoveHeader: "remove_header";
|
|
206
214
|
readonly AcceptRefer: "accept_refer";
|
|
207
215
|
readonly RejectRefer: "reject_refer";
|
|
216
|
+
readonly CompleteRefer: "complete_refer";
|
|
208
217
|
readonly Bridge: "bridge";
|
|
209
218
|
readonly Unbridge: "unbridge";
|
|
210
219
|
readonly ReplacePeer: "replace_peer";
|
|
@@ -223,7 +232,7 @@ declare const SipVerb: {
|
|
|
223
232
|
/** A value of {@link SipVerb}. */
|
|
224
233
|
type SipVerbToken = (typeof SipVerb)[keyof typeof SipVerb];
|
|
225
234
|
/** The well-known SIP-adapter event names (the ARI *Stasis* model). */
|
|
226
|
-
type SipEventKind = "StasisStart" | "StasisEnd" | "ChannelStateChange" | "ChannelHangupRequest" | "ChannelDtmfReceived" | "PlayStarted" | "TransferRequested" | "TransferProgress" | "TransferCompleted" | "TransferFailed" | "ChannelBridged" | "BridgeFailed" | "ChannelUnbridged" | "PeerReplaced" | "ReplaceFailed" | "PlayFinished" | "WsTeeStarted" | "WsTeeEnded" | "WsBridgeStarted" | "WsBridgeEnded" | "MediaSummary" | "MediaStarted" | "DialBranch" | "DialBranchFailed" | "DialAnswered" | "DialFailed" | "DialogStateChanged" | (string & {});
|
|
235
|
+
type SipEventKind = "StasisStart" | "StasisEnd" | "ChannelStateChange" | "ChannelHangupRequest" | "ChannelDtmfReceived" | "PlayStarted" | "TransferRequested" | "TransferTimedOut" | "TransferProgress" | "TransferCompleted" | "TransferFailed" | "ChannelBridged" | "BridgeFailed" | "ChannelUnbridged" | "PeerReplaced" | "ReplaceFailed" | "PlayFinished" | "WsTeeStarted" | "WsTeeEnded" | "WsBridgeStarted" | "WsBridgeEnded" | "MediaSummary" | "MediaStarted" | "DialBranch" | "DialBranchFailed" | "DialAnswered" | "DialFailed" | "DialogStateChanged" | (string & {});
|
|
227
236
|
/** Parse a wire event name; unknown names pass through verbatim (forward-compatible). */
|
|
228
237
|
declare function sipEventKind(name: string): SipEventKind;
|
|
229
238
|
/**
|
|
@@ -274,6 +283,29 @@ interface TransferReplaces {
|
|
|
274
283
|
from_tag: string;
|
|
275
284
|
to_tag: string;
|
|
276
285
|
early_only: boolean;
|
|
286
|
+
/**
|
|
287
|
+
* The dialog named, when the server hosts it — which is what lets an
|
|
288
|
+
* application act on a `Replaces` at all, since it addresses calls by channel
|
|
289
|
+
* and never sees a Call-ID or a tag. Absent or `null` for a dialog hosted
|
|
290
|
+
* elsewhere, and from a server that predates it.
|
|
291
|
+
*/
|
|
292
|
+
local?: HostedDialog | null;
|
|
293
|
+
}
|
|
294
|
+
/** A dialog the server hosts, as a `Replaces` named it. */
|
|
295
|
+
interface HostedDialog {
|
|
296
|
+
/** The call the dialog belongs to. */
|
|
297
|
+
call_actor_id: string;
|
|
298
|
+
/** The channel controlling that call, when an application owns it. */
|
|
299
|
+
channel?: string | null;
|
|
300
|
+
/** Which leg of the call the dialog is. */
|
|
301
|
+
leg: "a" | "b";
|
|
302
|
+
/**
|
|
303
|
+
* The channel that call is bridged with — the party that stays when the
|
|
304
|
+
* named one is replaced. `null` when it is not a bridge.
|
|
305
|
+
*/
|
|
306
|
+
bridged_with?: string | null;
|
|
307
|
+
/** On a `StasisStart` only: the `early-only` flag the INVITE's `Replaces` carried. */
|
|
308
|
+
early_only?: boolean;
|
|
277
309
|
}
|
|
278
310
|
/**
|
|
279
311
|
* The `payload` of a `TransferRequested` event — an inbound REFER on a
|
|
@@ -288,6 +320,36 @@ interface TransferRequestedPayload {
|
|
|
288
320
|
replaces?: TransferReplaces | null;
|
|
289
321
|
/** The From-tag of the referring party, if known. */
|
|
290
322
|
from_tag?: string | null;
|
|
323
|
+
/**
|
|
324
|
+
* Which party of the channel's call sent the REFER: `"a"` for the party the
|
|
325
|
+
* call came from, `"b"` for the party it was connected to. Absent from a
|
|
326
|
+
* server that predates it.
|
|
327
|
+
*/
|
|
328
|
+
referrer_leg?: "a" | "b" | null;
|
|
329
|
+
/**
|
|
330
|
+
* The SIP Call-ID of the dialog the REFER arrived on. For a `"b"` referrer
|
|
331
|
+
* this is the `leg_sip_call_id` its `DialBranch` named, not the channel's.
|
|
332
|
+
*/
|
|
333
|
+
referrer_sip_call_id?: string | null;
|
|
334
|
+
}
|
|
335
|
+
/**
|
|
336
|
+
* The `payload` of a `TransferTimedOut` event — a transfer accepted with
|
|
337
|
+
* `acceptRefer({ mode: "controller" })` passed its deadline with no
|
|
338
|
+
* `completeRefer`. siphon ended the referrer's subscription for the app, with
|
|
339
|
+
* a sipfrag NOTIFY of its own (RFC 3515 §2.4.5); a `completeRefer` now is
|
|
340
|
+
* refused. Cast a {@link import("./sip").CallEvent}'s `payload` to this when
|
|
341
|
+
* `kind === "TransferTimedOut"`.
|
|
342
|
+
*/
|
|
343
|
+
interface TransferTimedOutPayload {
|
|
344
|
+
/** Why the transfer ended: `"timeout"`. */
|
|
345
|
+
reason: string;
|
|
346
|
+
/**
|
|
347
|
+
* The sipfrag status siphon reported to the referrer (`503`), or `null` when
|
|
348
|
+
* the referrer's leg had already left the call and nothing could be sent.
|
|
349
|
+
*/
|
|
350
|
+
code?: number | null;
|
|
351
|
+
/** Which party of the channel's call had referred, as on {@link TransferRequestedPayload}. */
|
|
352
|
+
referrer_leg?: "a" | "b" | null;
|
|
291
353
|
}
|
|
292
354
|
/**
|
|
293
355
|
* Where a verdict on an *outbound* REFER came from — the `stage` of a
|
|
@@ -985,10 +1047,70 @@ interface ReferReplaces {
|
|
|
985
1047
|
earlyOnly?: boolean;
|
|
986
1048
|
}
|
|
987
1049
|
/** Options for {@link Call.acceptRefer}. */
|
|
988
|
-
|
|
989
|
-
|
|
1050
|
+
/**
|
|
1051
|
+
* Who a transfer's new leg is dialled at: a SIP URI, or `{ aor }` — a
|
|
1052
|
+
* registered address-of-record, dialled over the flow its phone registered on
|
|
1053
|
+
* (the only way to reach one on TCP, TLS or WebSocket behind NAT). An AoR nobody
|
|
1054
|
+
* is registered at rejects with `not_found`. One with several registered
|
|
1055
|
+
* contacts rings them all: the first to answer is the party brought into the
|
|
1056
|
+
* call, and the server CANCELs the rest.
|
|
1057
|
+
*/
|
|
1058
|
+
type TransferTarget = string | {
|
|
1059
|
+
aor: string;
|
|
1060
|
+
};
|
|
1061
|
+
/**
|
|
1062
|
+
* The identity a transfer's new leg presents — the arguments {@link Call.dial}
|
|
1063
|
+
* takes. Unset, the leg presents what the call's own INVITE carried.
|
|
1064
|
+
*/
|
|
1065
|
+
interface TransferIdentity {
|
|
1066
|
+
/** The calling identity — the From URI (RFC 3261 §8.1.1.3). */
|
|
1067
|
+
from?: string;
|
|
1068
|
+
/** The From display name. An empty one removes the caller's. */
|
|
1069
|
+
fromDisplay?: string;
|
|
1070
|
+
/** `P-Asserted-Identity` for a trusted next hop (RFC 3325 §9.1). */
|
|
1071
|
+
pAssertedIdentity?: string;
|
|
1072
|
+
/** Whether the calling identity may be presented (RFC 3323 §4.1). */
|
|
1073
|
+
privacy?: "allowed" | "restricted";
|
|
1074
|
+
/**
|
|
1075
|
+
* The name of a number policy configured on the server, which decides how
|
|
1076
|
+
* the numbers in the new leg's identity headers are written. Unset, the
|
|
1077
|
+
* server's default for the calls it dials applies. Not together with
|
|
1078
|
+
* `format`: the server refuses the two.
|
|
1079
|
+
*/
|
|
1080
|
+
numberPolicy?: string;
|
|
1081
|
+
/**
|
|
1082
|
+
* One number format for the new leg's identity headers, in place of a named
|
|
1083
|
+
* policy.
|
|
1084
|
+
*/
|
|
1085
|
+
format?: "e164" | "plain" | "international" | "national";
|
|
1086
|
+
/** Headers for the new leg's INVITE, injected after the header policy. */
|
|
1087
|
+
headers?: Record<string, string>;
|
|
1088
|
+
}
|
|
1089
|
+
/**
|
|
1090
|
+
* Options for {@link Call.acceptRefer}. The {@link TransferIdentity} fields and
|
|
1091
|
+
* an `{ aor }` target apply to `mode: "terminate"`, which dials a leg; the
|
|
1092
|
+
* server refuses them with `"transparent"`, which relays the REFER, and with
|
|
1093
|
+
* `"controller"`, which dials nothing and takes `timeout` only.
|
|
1094
|
+
*/
|
|
1095
|
+
interface AcceptReferOptions extends TransferIdentity {
|
|
1096
|
+
target?: TransferTarget;
|
|
990
1097
|
nextHop?: string;
|
|
991
|
-
|
|
1098
|
+
/**
|
|
1099
|
+
* Who carries the transfer out. `"terminate"`: the server dials the target.
|
|
1100
|
+
* `"transparent"`: it relays the REFER to the far end. `"controller"`: it
|
|
1101
|
+
* answers `202`, sends the first sipfrag NOTIFY and dials nothing — this
|
|
1102
|
+
* application moves the parties with its other verbs and then reports with
|
|
1103
|
+
* {@link Call.completeRefer}.
|
|
1104
|
+
*/
|
|
1105
|
+
mode?: "terminate" | "transparent" | "controller";
|
|
1106
|
+
/**
|
|
1107
|
+
* With `mode: "controller"`, how many seconds there are to report in
|
|
1108
|
+
* (default 60, at most 180). Past it the server reports `503` to the
|
|
1109
|
+
* referrer itself and tells this application with a `TransferTimedOut`
|
|
1110
|
+
* event ({@link import("./protocol").TransferTimedOutPayload}). The server
|
|
1111
|
+
* refuses it with any other mode.
|
|
1112
|
+
*/
|
|
1113
|
+
timeout?: number;
|
|
992
1114
|
/**
|
|
993
1115
|
* Media profile for the pairing the transfer creates.
|
|
994
1116
|
*
|
|
@@ -1199,6 +1321,14 @@ type DialTarget = {
|
|
|
1199
1321
|
nextHop?: string;
|
|
1200
1322
|
/** Headers injected on this branch's INVITE, over the command's. */
|
|
1201
1323
|
headers?: Record<string, string>;
|
|
1324
|
+
/**
|
|
1325
|
+
* Called party: the B-leg's `To` URI. Without it `To` keeps the caller's
|
|
1326
|
+
* user at the target's host, right for a forward and wrong for a divert,
|
|
1327
|
+
* where a next hop routing on `To` would serve the call as one to the
|
|
1328
|
+
* original number. Kept as the leg's dialog `To`, so later in-dialog
|
|
1329
|
+
* requests carry it too, which a `To` header override cannot do.
|
|
1330
|
+
*/
|
|
1331
|
+
to?: string;
|
|
1202
1332
|
} | {
|
|
1203
1333
|
/**
|
|
1204
1334
|
* The address of record to fork to its registered contacts. It takes no
|
|
@@ -1208,6 +1338,8 @@ type DialTarget = {
|
|
|
1208
1338
|
aor: string;
|
|
1209
1339
|
/** Headers injected on every branch the AoR expands to. */
|
|
1210
1340
|
headers?: Record<string, string>;
|
|
1341
|
+
/** Called party for every branch the AoR expands to (see the URI form). */
|
|
1342
|
+
to?: string;
|
|
1211
1343
|
};
|
|
1212
1344
|
/**
|
|
1213
1345
|
* Optional shaping for {@link Call.dial}; anything left out takes the server's
|
|
@@ -1345,21 +1477,36 @@ interface Recording {
|
|
|
1345
1477
|
declare function dialArgs(targets: DialTarget[], options?: DialOptions): Record<string, unknown>;
|
|
1346
1478
|
declare function recordStartArgs(options?: RecordOptions): Record<string, unknown>;
|
|
1347
1479
|
declare function recordStopArgs(recordingId?: string): Record<string, unknown>;
|
|
1480
|
+
/**
|
|
1481
|
+
* The audio source for {@link Call.play}: a server-side file, a media-DB id,
|
|
1482
|
+
* inline bytes, a tone the media engine generates (a preset name such as
|
|
1483
|
+
* `"ringback_eu"` or a cadence such as `"425/1000,0/4000*inf"`), or an
|
|
1484
|
+
* `http://` / `https://` URL it fetches.
|
|
1485
|
+
*/
|
|
1348
1486
|
type PlaySource = {
|
|
1349
1487
|
file: string;
|
|
1350
1488
|
} | {
|
|
1351
1489
|
dbId: number;
|
|
1352
1490
|
} | {
|
|
1353
1491
|
blob: Uint8Array;
|
|
1492
|
+
} | {
|
|
1493
|
+
tone: string;
|
|
1494
|
+
} | {
|
|
1495
|
+
url: string;
|
|
1354
1496
|
};
|
|
1355
1497
|
/** Optional shaping for {@link Call.play}. */
|
|
1356
1498
|
interface PlayOptions {
|
|
1357
|
-
/**
|
|
1358
|
-
|
|
1499
|
+
/**
|
|
1500
|
+
* How many times to play in total (undefined → once), or `"inf"` to play
|
|
1501
|
+
* until stopped — music on hold. The server refuses any other value.
|
|
1502
|
+
*/
|
|
1503
|
+
repeat?: number | "inf";
|
|
1359
1504
|
/** Start playback at this offset into the source, in milliseconds. */
|
|
1360
1505
|
startMs?: number;
|
|
1361
1506
|
/** Cap playback to this duration, in milliseconds. */
|
|
1362
1507
|
durationMs?: number;
|
|
1508
|
+
/** Play louder (positive) or quieter (negative) by this many decibels. */
|
|
1509
|
+
gainDecibels?: number;
|
|
1363
1510
|
/** Scope the prompt to one peer of an MPTY bridge (its To-tag). */
|
|
1364
1511
|
toTag?: string;
|
|
1365
1512
|
}
|
|
@@ -1404,6 +1551,14 @@ interface StreamOptions {
|
|
|
1404
1551
|
* engine's default when unset). Tee only; the server refuses anything else.
|
|
1405
1552
|
*/
|
|
1406
1553
|
sampleRate?: number;
|
|
1554
|
+
/**
|
|
1555
|
+
* Bridge only: the name of a media profile on the server whose bridge
|
|
1556
|
+
* settings (wire rate, noise suppression, echo cancellation, VAD, barge-in)
|
|
1557
|
+
* the bridge runs with, as an `answer` with `wsUri` would. Unset, the bridge
|
|
1558
|
+
* runs at the leg's own rate with uplink processing off. Refused on a tee,
|
|
1559
|
+
* and an unknown name rejects with `bad_request`.
|
|
1560
|
+
*/
|
|
1561
|
+
profile?: string;
|
|
1407
1562
|
}
|
|
1408
1563
|
/** Options for {@link Call.streamStop}. */
|
|
1409
1564
|
interface StreamStopOptions {
|
|
@@ -1526,6 +1681,26 @@ declare class Call {
|
|
|
1526
1681
|
drop(reason?: string, options?: {
|
|
1527
1682
|
ban?: boolean;
|
|
1528
1683
|
}): Promise<void>;
|
|
1684
|
+
/**
|
|
1685
|
+
* Give up on the dial ringing for this call and leave the caller alone.
|
|
1686
|
+
*
|
|
1687
|
+
* Every phone still ringing is CANCELled (RFC 3261 §9.1), each reported by
|
|
1688
|
+
* `DialBranchFailed` with cause `cancelled`, and the dial ends in
|
|
1689
|
+
* `DialFailed` with code 487. The caller is exactly as the dial found it —
|
|
1690
|
+
* answered and anchored for an `onAnswer: "bridge"` dial, unanswered and
|
|
1691
|
+
* parked otherwise — still this app's, and free to be dialled for again.
|
|
1692
|
+
* {@link Call.hangup} ends the caller as well.
|
|
1693
|
+
*
|
|
1694
|
+
* `reason` is reported as the `cause` of a bridging dial's `DialFailed`
|
|
1695
|
+
* (default `cancelled`), so the handler that hears it can tell its own cancel
|
|
1696
|
+
* from a dial that failed by itself.
|
|
1697
|
+
*
|
|
1698
|
+
* Rejects with `invalid_state` when nothing is ringing (`details.reason` is
|
|
1699
|
+
* `no_dial_in_progress`), and once a phone has answered and is being bridged
|
|
1700
|
+
* (`dial_answered`), whose outcome arrives as `DialAnswered` or
|
|
1701
|
+
* `BridgeFailed`.
|
|
1702
|
+
*/
|
|
1703
|
+
cancelDial(reason?: string): Promise<void>;
|
|
1529
1704
|
/**
|
|
1530
1705
|
* Send an in-dialog REFER on the A-leg (blind transfer).
|
|
1531
1706
|
*
|
|
@@ -1622,10 +1797,27 @@ declare class Call {
|
|
|
1622
1797
|
* `b2bua.default_refer_mode`. No pending REFER (already decided, timed out, or
|
|
1623
1798
|
* the call is gone) rejects with `code === "not_found"`.
|
|
1624
1799
|
*
|
|
1800
|
+
* `mode: "controller"` leaves the transfer to this application — see
|
|
1801
|
+
* {@link AcceptReferOptions.mode} and {@link Call.completeRefer}.
|
|
1802
|
+
*
|
|
1625
1803
|
* `profile` names the media profile for the pairing the transfer creates —
|
|
1626
1804
|
* see {@link AcceptReferOptions.profile}, which is required at an SRTP edge.
|
|
1627
1805
|
*/
|
|
1628
1806
|
acceptRefer(options?: AcceptReferOptions): Promise<void>;
|
|
1807
|
+
/**
|
|
1808
|
+
* Report how a transfer accepted with `acceptRefer({ mode: "controller" })`
|
|
1809
|
+
* went: the server sends the referrer the sipfrag NOTIFY that ends its
|
|
1810
|
+
* subscription. `code` is the status in it (200-699), a 2xx for a transfer
|
|
1811
|
+
* that succeeded, and `reason` its reason phrase, used as given. Nothing
|
|
1812
|
+
* else happens to the call.
|
|
1813
|
+
*
|
|
1814
|
+
* **Report before releasing the referrer's leg.** The NOTIFY travels on its
|
|
1815
|
+
* dialog, so once that leg is hung up or replaced this rejects with
|
|
1816
|
+
* `code === "not_found"`. With no such transfer open on the call — already
|
|
1817
|
+
* reported, past its deadline, or its referrer hung up — it rejects with
|
|
1818
|
+
* `code === "invalid_state"` (`details.reason === "no_transfer_pending"`).
|
|
1819
|
+
*/
|
|
1820
|
+
completeRefer(code: number, reason?: string): Promise<void>;
|
|
1629
1821
|
/**
|
|
1630
1822
|
* Reject a *pending inbound* REFER with a final non-2xx (default
|
|
1631
1823
|
* `603 Decline`). No pending REFER rejects with `code === "not_found"`.
|
|
@@ -1712,12 +1904,12 @@ declare class Call {
|
|
|
1712
1904
|
* answered, no peer leg, or a replacement already in flight — all worth
|
|
1713
1905
|
* retrying later) or `"bad_request"` (the target will not parse or route).
|
|
1714
1906
|
*/
|
|
1715
|
-
replacePeer(target:
|
|
1907
|
+
replacePeer(target: TransferTarget, options?: {
|
|
1716
1908
|
nextHop?: string;
|
|
1717
1909
|
replaceALeg?: boolean;
|
|
1718
1910
|
profile?: string;
|
|
1719
1911
|
timeout?: number;
|
|
1720
|
-
}): Promise<unknown>;
|
|
1912
|
+
} & TransferIdentity): Promise<unknown>;
|
|
1721
1913
|
/** Set a header on the stored A-leg INVITE. */
|
|
1722
1914
|
setHeader(name: string, value: string): Promise<void>;
|
|
1723
1915
|
/** Read a header from the stored A-leg INVITE (`null` when absent). */
|
|
@@ -1744,9 +1936,15 @@ declare class Call {
|
|
|
1744
1936
|
* optional `durationMs` / `volumeDbm0` / `pauseMs` / `toTag` shaping.
|
|
1745
1937
|
*/
|
|
1746
1938
|
dtmf(digits: string, options?: DtmfOptions): Promise<void>;
|
|
1747
|
-
/**
|
|
1939
|
+
/**
|
|
1940
|
+
* Silence the call's media in both directions on the media engine.
|
|
1941
|
+
*
|
|
1942
|
+
* A media gate, not a SIP hold: nothing is sent on either dialog, so no
|
|
1943
|
+
* phone shows a held call. Rejects with `invalid_state` on a call the engine
|
|
1944
|
+
* only relays; to hold one party of a bridge, use {@link Call.unbridge}.
|
|
1945
|
+
*/
|
|
1748
1946
|
hold(): Promise<void>;
|
|
1749
|
-
/**
|
|
1947
|
+
/** Restore the call's media after a {@link Call.hold}. */
|
|
1750
1948
|
unhold(): Promise<void>;
|
|
1751
1949
|
/**
|
|
1752
1950
|
* Attach a WebSocket audio stream to `wsUri`: an additive tee (the default)
|
|
@@ -1759,8 +1957,9 @@ declare class Call {
|
|
|
1759
1957
|
* direction: "caller",
|
|
1760
1958
|
* sampleRate: 16000,
|
|
1761
1959
|
* });
|
|
1762
|
-
* // Hand the leg to a voice agent; the agent is now the far side
|
|
1763
|
-
*
|
|
1960
|
+
* // Hand the leg to a voice agent; the agent is now the far side, with the
|
|
1961
|
+
* // server's `voice_ai` profile's rate, echo cancellation and barge-in.
|
|
1962
|
+
* await call.streamStart("wss://ai.example/agent", { mode: "bridge", profile: "voice_ai" });
|
|
1764
1963
|
* ```
|
|
1765
1964
|
*
|
|
1766
1965
|
* A bridge on a leg that already has one re-points it in place. `wsUri` may
|
|
@@ -1947,4 +2146,4 @@ declare class SipServer {
|
|
|
1947
2146
|
close(): Promise<void>;
|
|
1948
2147
|
}
|
|
1949
2148
|
|
|
1950
|
-
export { type AcceptReferOptions, type AnchoredAnswerOptions, type AppEvent, type AppEventHandler, type BridgeFailedPayload, type BridgeOptions, type BridgeRole, type BridgeStage, Call, type CallEvent, type CallHandler, CallStream, type ChannelBridgedPayload, type ChannelDtmfPayload, type ChannelSnapshot, type ChannelUnbridgedPayload, type ClientConfig, type ClientEvent, type CommandTransport, type ConnectionEventSink, ControlClient, ControlError, type ControlErrorCode, type ControlErrorKind, ControlServer, DESCRIBE, type DialAnsweredPayload, type DialBranchCause, type DialBranchOutcome, type DialBranchPayload, type DialFailedPayload, type DialOptions, type DialTarget, type Dialing, type DialogDirection, type DialogIdentity, type DialogState, type DialogStateChangedPayload, type DtmfOptions, type EventFrame, type EventSink, EventStream, type FrameType, GET_VAR, HELLO, type HelloArgs, type HelloResult, MODULE_SIP, MODULE_SMPP, MODULE_SS7, type MediaLegSummary, type MediaStartedPayload, type MediaSummaryPayload, type OriginateMedia, type OriginateOptions, type OriginateRing, type Originated, type OriginatedGroup, PROTOCOL_VERSION, type PeerHangupPolicy, type PlayFinishedPayload, type PlayOptions, type PlaySource, type PlayStartedPayload, RESYNC, type RecordChannels, type RecordDirection, type RecordOptions, type Recording, type ReferReplaces, type ReplyError, type ReplyFrame, type ReplyStatus, type ResponseOptions, type ResyncResult, type RouteTarget, type RouteTargetObject, SET_VAR, SUBPROTOCOL, type ServerConfig, type SessionRefresher, type SessionTimer, SipClient, type SipEventKind, SipServer, SipVerb, type SipVerbToken, type StreamMode, type StreamOptions, type StreamStopOptions, type TransferOutcomePayload, type TransferReplaces, type TransferRequestedPayload, type TransferStage, type WsBridgeEndedPayload, type WsBridgeStartedPayload, type WsTeeEndedPayload, type WsTeeStartedPayload, dialArgs, encodeCommand, isBridgeFinal, isDialFinal, isTransferFinal, originateAorArgs, originateArgs, parseInboundFrame, recordStartArgs, recordStopArgs, sipEventKind, transferOutcome };
|
|
2149
|
+
export { type AcceptReferOptions, type AnchoredAnswerOptions, type AppEvent, type AppEventHandler, type BridgeFailedPayload, type BridgeOptions, type BridgeRole, type BridgeStage, Call, type CallEvent, type CallHandler, CallStream, type ChannelBridgedPayload, type ChannelDtmfPayload, type ChannelSnapshot, type ChannelUnbridgedPayload, type ClientConfig, type ClientEvent, type CommandTransport, type ConnectionEventSink, ControlClient, ControlError, type ControlErrorCode, type ControlErrorKind, ControlServer, DESCRIBE, type DialAnsweredPayload, type DialBranchCause, type DialBranchOutcome, type DialBranchPayload, type DialFailedPayload, type DialOptions, type DialTarget, type Dialing, type DialogDirection, type DialogIdentity, type DialogState, type DialogStateChangedPayload, type DtmfOptions, type EventFrame, type EventSink, EventStream, type FrameType, GET_VAR, HELLO, type HelloArgs, type HelloResult, MODULE_SIP, MODULE_SMPP, MODULE_SS7, type MediaLegSummary, type MediaStartedPayload, type MediaSummaryPayload, type OriginateMedia, type OriginateOptions, type OriginateRing, type Originated, type OriginatedGroup, PROTOCOL_VERSION, type PeerHangupPolicy, type PlayFinishedPayload, type PlayOptions, type PlaySource, type PlayStartedPayload, RESYNC, type RecordChannels, type RecordDirection, type RecordOptions, type Recording, type ReferReplaces, type ReplyError, type ReplyFrame, type ReplyStatus, type ResponseOptions, type ResyncResult, type RouteTarget, type RouteTargetObject, SET_VAR, SUBPROTOCOL, type ServerConfig, type SessionRefresher, type SessionTimer, SipClient, type SipEventKind, SipServer, SipVerb, type SipVerbToken, type StreamMode, type StreamOptions, type StreamStopOptions, type TransferOutcomePayload, type TransferReplaces, type TransferRequestedPayload, type TransferStage, type TransferTimedOutPayload, type WsBridgeEndedPayload, type WsBridgeStartedPayload, type WsTeeEndedPayload, type WsTeeStartedPayload, dialArgs, encodeCommand, isBridgeFinal, isDialFinal, isTransferFinal, originateAorArgs, originateArgs, parseInboundFrame, recordStartArgs, recordStopArgs, sipEventKind, transferOutcome };
|
package/dist/index.js
CHANGED
|
@@ -17,8 +17,9 @@ var ControlError = class _ControlError extends Error {
|
|
|
17
17
|
Object.setPrototypeOf(this, _ControlError.prototype);
|
|
18
18
|
}
|
|
19
19
|
/**
|
|
20
|
-
* True when this is a server-side `unsupported_verb` rejection —
|
|
21
|
-
*
|
|
20
|
+
* True when this is a server-side `unsupported_verb` rejection — what a verb
|
|
21
|
+
* answers when the configured media backend cannot carry it out (streaming
|
|
22
|
+
* and recording on anything but siphon-rtp).
|
|
22
23
|
*/
|
|
23
24
|
isUnsupportedVerb() {
|
|
24
25
|
return this.kind === "command" && this.code === "unsupported_verb";
|
|
@@ -130,11 +131,19 @@ var SipVerb = {
|
|
|
130
131
|
* the channel. Channel-addressed, unlike `originate`, which creates one.
|
|
131
132
|
*/
|
|
132
133
|
Dial: "dial",
|
|
134
|
+
/**
|
|
135
|
+
* Give up on the dial ringing for this channel's caller and leave the caller
|
|
136
|
+
* alone: the phones are CANCELled and the dial ends in `DialFailed` with code
|
|
137
|
+
* 487. Refused (`invalid_state`) when nothing is ringing, and once a phone
|
|
138
|
+
* has answered and is being bridged.
|
|
139
|
+
*/
|
|
140
|
+
CancelDial: "cancel_dial",
|
|
133
141
|
SetHeader: "set_header",
|
|
134
142
|
GetHeader: "get_header",
|
|
135
143
|
RemoveHeader: "remove_header",
|
|
136
144
|
AcceptRefer: "accept_refer",
|
|
137
145
|
RejectRefer: "reject_refer",
|
|
146
|
+
CompleteRefer: "complete_refer",
|
|
138
147
|
Bridge: "bridge",
|
|
139
148
|
Unbridge: "unbridge",
|
|
140
149
|
ReplacePeer: "replace_peer",
|
|
@@ -636,6 +645,17 @@ function responseArgs(options) {
|
|
|
636
645
|
}
|
|
637
646
|
return args;
|
|
638
647
|
}
|
|
648
|
+
function insertTransferIdentity(args, identity) {
|
|
649
|
+
if (identity?.from !== void 0) args.from = identity.from;
|
|
650
|
+
if (identity?.fromDisplay !== void 0) args.from_display = identity.fromDisplay;
|
|
651
|
+
if (identity?.pAssertedIdentity !== void 0) {
|
|
652
|
+
args.p_asserted_identity = identity.pAssertedIdentity;
|
|
653
|
+
}
|
|
654
|
+
if (identity?.privacy !== void 0) args.privacy = identity.privacy;
|
|
655
|
+
if (identity?.numberPolicy !== void 0) args.number_policy = identity.numberPolicy;
|
|
656
|
+
if (identity?.format !== void 0) args.format = identity.format;
|
|
657
|
+
if (identity?.headers !== void 0) args.headers = identity.headers;
|
|
658
|
+
}
|
|
639
659
|
function routeTargetToWire(target) {
|
|
640
660
|
if (typeof target === "string") {
|
|
641
661
|
return target;
|
|
@@ -712,6 +732,10 @@ function dialTargetToWire(target) {
|
|
|
712
732
|
const aor = target.aor;
|
|
713
733
|
const nextHop = target.nextHop;
|
|
714
734
|
const headers = target.headers;
|
|
735
|
+
const to = target.to;
|
|
736
|
+
if (to !== void 0 && typeof to !== "string") {
|
|
737
|
+
throw new TypeError(`a dial target's "to" is a SIP URI string`);
|
|
738
|
+
}
|
|
715
739
|
if (typeof uri === "string" && typeof aor === "string") {
|
|
716
740
|
throw new TypeError(
|
|
717
741
|
'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'
|
|
@@ -725,15 +749,17 @@ function dialTargetToWire(target) {
|
|
|
725
749
|
}
|
|
726
750
|
const object2 = { aor };
|
|
727
751
|
if (headers !== void 0) object2.headers = headers;
|
|
752
|
+
if (to !== void 0) object2.to = to;
|
|
728
753
|
return object2;
|
|
729
754
|
}
|
|
730
755
|
if (typeof uri !== "string") {
|
|
731
756
|
throw new TypeError('a dial target requires a string "uri" or "aor"');
|
|
732
757
|
}
|
|
733
|
-
if (nextHop === void 0 && headers === void 0) return uri;
|
|
758
|
+
if (nextHop === void 0 && headers === void 0 && to === void 0) return uri;
|
|
734
759
|
const object = { uri };
|
|
735
760
|
if (nextHop !== void 0) object.next_hop = nextHop;
|
|
736
761
|
if (headers !== void 0) object.headers = headers;
|
|
762
|
+
if (to !== void 0) object.to = to;
|
|
737
763
|
return object;
|
|
738
764
|
}
|
|
739
765
|
function dialArgs(targets, options) {
|
|
@@ -792,6 +818,10 @@ function playArgs(source, options) {
|
|
|
792
818
|
args.file = source.file;
|
|
793
819
|
} else if ("dbId" in source) {
|
|
794
820
|
args.db_id = source.dbId;
|
|
821
|
+
} else if ("tone" in source) {
|
|
822
|
+
args.tone = source.tone;
|
|
823
|
+
} else if ("url" in source) {
|
|
824
|
+
args.url = source.url;
|
|
795
825
|
} else {
|
|
796
826
|
args.blob = Buffer.from(source.blob).toString("base64");
|
|
797
827
|
}
|
|
@@ -804,6 +834,9 @@ function playArgs(source, options) {
|
|
|
804
834
|
if (options?.durationMs !== void 0) {
|
|
805
835
|
args.duration_ms = options.durationMs;
|
|
806
836
|
}
|
|
837
|
+
if (options?.gainDecibels !== void 0) {
|
|
838
|
+
args.gain_decibels = options.gainDecibels;
|
|
839
|
+
}
|
|
807
840
|
if (options?.toTag !== void 0) {
|
|
808
841
|
args.to_tag = options.toTag;
|
|
809
842
|
}
|
|
@@ -973,6 +1006,32 @@ var Call = class {
|
|
|
973
1006
|
}
|
|
974
1007
|
await this.sip(SipVerb.Drop, args);
|
|
975
1008
|
}
|
|
1009
|
+
/**
|
|
1010
|
+
* Give up on the dial ringing for this call and leave the caller alone.
|
|
1011
|
+
*
|
|
1012
|
+
* Every phone still ringing is CANCELled (RFC 3261 §9.1), each reported by
|
|
1013
|
+
* `DialBranchFailed` with cause `cancelled`, and the dial ends in
|
|
1014
|
+
* `DialFailed` with code 487. The caller is exactly as the dial found it —
|
|
1015
|
+
* answered and anchored for an `onAnswer: "bridge"` dial, unanswered and
|
|
1016
|
+
* parked otherwise — still this app's, and free to be dialled for again.
|
|
1017
|
+
* {@link Call.hangup} ends the caller as well.
|
|
1018
|
+
*
|
|
1019
|
+
* `reason` is reported as the `cause` of a bridging dial's `DialFailed`
|
|
1020
|
+
* (default `cancelled`), so the handler that hears it can tell its own cancel
|
|
1021
|
+
* from a dial that failed by itself.
|
|
1022
|
+
*
|
|
1023
|
+
* Rejects with `invalid_state` when nothing is ringing (`details.reason` is
|
|
1024
|
+
* `no_dial_in_progress`), and once a phone has answered and is being bridged
|
|
1025
|
+
* (`dial_answered`), whose outcome arrives as `DialAnswered` or
|
|
1026
|
+
* `BridgeFailed`.
|
|
1027
|
+
*/
|
|
1028
|
+
async cancelDial(reason) {
|
|
1029
|
+
const args = {};
|
|
1030
|
+
if (reason !== void 0) {
|
|
1031
|
+
args.reason = reason;
|
|
1032
|
+
}
|
|
1033
|
+
await this.sip(SipVerb.CancelDial, args);
|
|
1034
|
+
}
|
|
976
1035
|
/**
|
|
977
1036
|
* Send an in-dialog REFER on the A-leg (blind transfer).
|
|
978
1037
|
*
|
|
@@ -1118,6 +1177,9 @@ var Call = class {
|
|
|
1118
1177
|
* `b2bua.default_refer_mode`. No pending REFER (already decided, timed out, or
|
|
1119
1178
|
* the call is gone) rejects with `code === "not_found"`.
|
|
1120
1179
|
*
|
|
1180
|
+
* `mode: "controller"` leaves the transfer to this application — see
|
|
1181
|
+
* {@link AcceptReferOptions.mode} and {@link Call.completeRefer}.
|
|
1182
|
+
*
|
|
1121
1183
|
* `profile` names the media profile for the pairing the transfer creates —
|
|
1122
1184
|
* see {@link AcceptReferOptions.profile}, which is required at an SRTP edge.
|
|
1123
1185
|
*/
|
|
@@ -1135,8 +1197,32 @@ var Call = class {
|
|
|
1135
1197
|
if (options?.profile !== void 0) {
|
|
1136
1198
|
args.profile = options.profile;
|
|
1137
1199
|
}
|
|
1200
|
+
if (options?.timeout !== void 0) {
|
|
1201
|
+
args.timeout = options.timeout;
|
|
1202
|
+
}
|
|
1203
|
+
insertTransferIdentity(args, options);
|
|
1138
1204
|
await this.sip(SipVerb.AcceptRefer, args);
|
|
1139
1205
|
}
|
|
1206
|
+
/**
|
|
1207
|
+
* Report how a transfer accepted with `acceptRefer({ mode: "controller" })`
|
|
1208
|
+
* went: the server sends the referrer the sipfrag NOTIFY that ends its
|
|
1209
|
+
* subscription. `code` is the status in it (200-699), a 2xx for a transfer
|
|
1210
|
+
* that succeeded, and `reason` its reason phrase, used as given. Nothing
|
|
1211
|
+
* else happens to the call.
|
|
1212
|
+
*
|
|
1213
|
+
* **Report before releasing the referrer's leg.** The NOTIFY travels on its
|
|
1214
|
+
* dialog, so once that leg is hung up or replaced this rejects with
|
|
1215
|
+
* `code === "not_found"`. With no such transfer open on the call — already
|
|
1216
|
+
* reported, past its deadline, or its referrer hung up — it rejects with
|
|
1217
|
+
* `code === "invalid_state"` (`details.reason === "no_transfer_pending"`).
|
|
1218
|
+
*/
|
|
1219
|
+
async completeRefer(code, reason) {
|
|
1220
|
+
const args = { code };
|
|
1221
|
+
if (reason !== void 0) {
|
|
1222
|
+
args.reason = reason;
|
|
1223
|
+
}
|
|
1224
|
+
await this.sip(SipVerb.CompleteRefer, args);
|
|
1225
|
+
}
|
|
1140
1226
|
/**
|
|
1141
1227
|
* Reject a *pending inbound* REFER with a final non-2xx (default
|
|
1142
1228
|
* `603 Decline`). No pending REFER rejects with `code === "not_found"`.
|
|
@@ -1243,6 +1329,7 @@ var Call = class {
|
|
|
1243
1329
|
if (options.replaceALeg !== void 0) args.replace_a_leg = options.replaceALeg;
|
|
1244
1330
|
if (options.profile !== void 0) args.profile = options.profile;
|
|
1245
1331
|
if (options.timeout !== void 0) args.timeout = options.timeout;
|
|
1332
|
+
insertTransferIdentity(args, options);
|
|
1246
1333
|
return this.sip(SipVerb.ReplacePeer, args);
|
|
1247
1334
|
}
|
|
1248
1335
|
/** Set a header on the stored A-leg INVITE. */
|
|
@@ -1293,11 +1380,17 @@ var Call = class {
|
|
|
1293
1380
|
async dtmf(digits, options) {
|
|
1294
1381
|
await this.sip(SipVerb.Dtmf, dtmfArgs(digits, options));
|
|
1295
1382
|
}
|
|
1296
|
-
/**
|
|
1383
|
+
/**
|
|
1384
|
+
* Silence the call's media in both directions on the media engine.
|
|
1385
|
+
*
|
|
1386
|
+
* A media gate, not a SIP hold: nothing is sent on either dialog, so no
|
|
1387
|
+
* phone shows a held call. Rejects with `invalid_state` on a call the engine
|
|
1388
|
+
* only relays; to hold one party of a bridge, use {@link Call.unbridge}.
|
|
1389
|
+
*/
|
|
1297
1390
|
async hold() {
|
|
1298
1391
|
await this.sip(SipVerb.Hold, {});
|
|
1299
1392
|
}
|
|
1300
|
-
/**
|
|
1393
|
+
/** Restore the call's media after a {@link Call.hold}. */
|
|
1301
1394
|
async unhold() {
|
|
1302
1395
|
await this.sip(SipVerb.Unhold, {});
|
|
1303
1396
|
}
|
|
@@ -1312,8 +1405,9 @@ var Call = class {
|
|
|
1312
1405
|
* direction: "caller",
|
|
1313
1406
|
* sampleRate: 16000,
|
|
1314
1407
|
* });
|
|
1315
|
-
* // Hand the leg to a voice agent; the agent is now the far side
|
|
1316
|
-
*
|
|
1408
|
+
* // Hand the leg to a voice agent; the agent is now the far side, with the
|
|
1409
|
+
* // server's `voice_ai` profile's rate, echo cancellation and barge-in.
|
|
1410
|
+
* await call.streamStart("wss://ai.example/agent", { mode: "bridge", profile: "voice_ai" });
|
|
1317
1411
|
* ```
|
|
1318
1412
|
*
|
|
1319
1413
|
* A bridge on a leg that already has one re-points it in place. `wsUri` may
|
|
@@ -1337,6 +1431,9 @@ var Call = class {
|
|
|
1337
1431
|
if (options?.sampleRate !== void 0) {
|
|
1338
1432
|
args.sample_rate = options.sampleRate;
|
|
1339
1433
|
}
|
|
1434
|
+
if (options?.profile !== void 0) {
|
|
1435
|
+
args.profile = options.profile;
|
|
1436
|
+
}
|
|
1340
1437
|
await this.sip(SipVerb.StreamStart, args);
|
|
1341
1438
|
}
|
|
1342
1439
|
/**
|