@siphon-project/control 0.7.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/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 — the state a
35
- * media verb (`playFile`/`dtmf`/…) lands in until the server implements it.
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
- interface AcceptReferOptions {
989
- target?: string;
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
- mode?: "terminate" | "transparent";
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
- /** Repeat the prompt this many times (0/undefined → play once). */
1358
- repeat?: number;
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
  }
@@ -1534,6 +1681,26 @@ declare class Call {
1534
1681
  drop(reason?: string, options?: {
1535
1682
  ban?: boolean;
1536
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>;
1537
1704
  /**
1538
1705
  * Send an in-dialog REFER on the A-leg (blind transfer).
1539
1706
  *
@@ -1630,10 +1797,27 @@ declare class Call {
1630
1797
  * `b2bua.default_refer_mode`. No pending REFER (already decided, timed out, or
1631
1798
  * the call is gone) rejects with `code === "not_found"`.
1632
1799
  *
1800
+ * `mode: "controller"` leaves the transfer to this application — see
1801
+ * {@link AcceptReferOptions.mode} and {@link Call.completeRefer}.
1802
+ *
1633
1803
  * `profile` names the media profile for the pairing the transfer creates —
1634
1804
  * see {@link AcceptReferOptions.profile}, which is required at an SRTP edge.
1635
1805
  */
1636
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>;
1637
1821
  /**
1638
1822
  * Reject a *pending inbound* REFER with a final non-2xx (default
1639
1823
  * `603 Decline`). No pending REFER rejects with `code === "not_found"`.
@@ -1720,12 +1904,12 @@ declare class Call {
1720
1904
  * answered, no peer leg, or a replacement already in flight — all worth
1721
1905
  * retrying later) or `"bad_request"` (the target will not parse or route).
1722
1906
  */
1723
- replacePeer(target: string, options?: {
1907
+ replacePeer(target: TransferTarget, options?: {
1724
1908
  nextHop?: string;
1725
1909
  replaceALeg?: boolean;
1726
1910
  profile?: string;
1727
1911
  timeout?: number;
1728
- }): Promise<unknown>;
1912
+ } & TransferIdentity): Promise<unknown>;
1729
1913
  /** Set a header on the stored A-leg INVITE. */
1730
1914
  setHeader(name: string, value: string): Promise<void>;
1731
1915
  /** Read a header from the stored A-leg INVITE (`null` when absent). */
@@ -1752,9 +1936,15 @@ declare class Call {
1752
1936
  * optional `durationMs` / `volumeDbm0` / `pauseMs` / `toTag` shaping.
1753
1937
  */
1754
1938
  dtmf(digits: string, options?: DtmfOptions): Promise<void>;
1755
- /** Hold the A-leg media via silence. */
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
+ */
1756
1946
  hold(): Promise<void>;
1757
- /** Resume the A-leg media after a {@link Call.hold}. */
1947
+ /** Restore the call's media after a {@link Call.hold}. */
1758
1948
  unhold(): Promise<void>;
1759
1949
  /**
1760
1950
  * Attach a WebSocket audio stream to `wsUri`: an additive tee (the default)
@@ -1956,4 +2146,4 @@ declare class SipServer {
1956
2146
  close(): Promise<void>;
1957
2147
  }
1958
2148
 
1959
- 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 — the state a
21
- * media verb (`playFile`/`dtmf`/…) lands in until the server implements it.
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
- /** Hold the A-leg media via silence. */
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
- /** Resume the A-leg media after a {@link Call.hold}. */
1393
+ /** Restore the call's media after a {@link Call.hold}. */
1301
1394
  async unhold() {
1302
1395
  await this.sip(SipVerb.Unhold, {});
1303
1396
  }