@siphon-project/control 0.1.1 → 0.1.3
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 +2 -0
- package/dist/index.cjs +248 -22
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +521 -27
- package/dist/index.d.ts +521 -27
- package/dist/index.js +247 -23
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/dist/index.d.ts
CHANGED
|
@@ -11,7 +11,7 @@ import { AddressInfo } from 'node:net';
|
|
|
11
11
|
* `ControlError` enum and the Python `ControlError` exception.
|
|
12
12
|
*/
|
|
13
13
|
/** Stable machine-readable error codes returned in a reply's `error.code`. */
|
|
14
|
-
type ControlErrorCode = "unauthorized" | "forbidden" | "not_found" | "bad_request" | "rate_limited" | "originate_denied" | "unsupported_verb" | "unsupported_version" | "protocol_error" | "unavailable";
|
|
14
|
+
type ControlErrorCode = "unauthorized" | "forbidden" | "not_found" | "bad_request" | "conflict" | "invalid_state" | "rate_limited" | "originate_denied" | "unsupported_verb" | "unsupported_version" | "protocol_error" | "unavailable";
|
|
15
15
|
/**
|
|
16
16
|
* How a {@link ControlError} arose. `command` is the wire-level rejection (it
|
|
17
17
|
* carries a {@link ControlErrorCode}); the rest are transport / local failures
|
|
@@ -164,32 +164,326 @@ declare function parseInboundFrame(text: string): ReplyFrame | EventFrame | null
|
|
|
164
164
|
/**
|
|
165
165
|
* The verbs the built-in SIP adapter accepts (`module = "sip"`).
|
|
166
166
|
*
|
|
167
|
-
* These are the exact wire tokens. The
|
|
168
|
-
* `
|
|
169
|
-
* the
|
|
170
|
-
*
|
|
171
|
-
* them.
|
|
167
|
+
* These are the exact wire tokens. The media verbs
|
|
168
|
+
* (`play`/`stop`/`dtmf`/`hold`/`unhold`/`stream_start`/`stream_stop`) dispatch
|
|
169
|
+
* against the configured media backend; the WebSocket-tee pair is
|
|
170
|
+
* siphon-rtp-only, so a non-siphon-rtp backend answers them `unsupported_verb`.
|
|
172
171
|
*/
|
|
173
172
|
declare const SipVerb: {
|
|
174
173
|
readonly Answer: "answer";
|
|
174
|
+
/**
|
|
175
|
+
* `180 Ringing` — alerting only, no early media (RFC 3261 §13.2.1). A body is
|
|
176
|
+
* refused: SDP on an 18x is early media (RFC 3960 §3.1), which is
|
|
177
|
+
* {@link SipVerb.Progress}'s job.
|
|
178
|
+
*/
|
|
179
|
+
readonly Ring: "ring";
|
|
175
180
|
readonly Progress: "progress";
|
|
176
181
|
readonly Reject: "reject";
|
|
177
182
|
readonly Hangup: "hangup";
|
|
178
183
|
readonly Refer: "refer";
|
|
184
|
+
readonly Route: "route";
|
|
179
185
|
readonly SetHeader: "set_header";
|
|
180
186
|
readonly GetHeader: "get_header";
|
|
181
187
|
readonly RemoveHeader: "remove_header";
|
|
182
188
|
readonly AcceptRefer: "accept_refer";
|
|
183
189
|
readonly RejectRefer: "reject_refer";
|
|
190
|
+
readonly Bridge: "bridge";
|
|
191
|
+
readonly Unbridge: "unbridge";
|
|
184
192
|
readonly Play: "play";
|
|
193
|
+
readonly Stop: "stop";
|
|
185
194
|
readonly Dtmf: "dtmf";
|
|
195
|
+
readonly Hold: "hold";
|
|
196
|
+
readonly Unhold: "unhold";
|
|
197
|
+
readonly StreamStart: "stream_start";
|
|
198
|
+
readonly StreamStop: "stream_stop";
|
|
186
199
|
};
|
|
187
200
|
/** A value of {@link SipVerb}. */
|
|
188
201
|
type SipVerbToken = (typeof SipVerb)[keyof typeof SipVerb];
|
|
189
202
|
/** The well-known SIP-adapter event names (the ARI *Stasis* model). */
|
|
190
|
-
type SipEventKind = "StasisStart" | "StasisEnd" | "ChannelStateChange" | "ChannelHangupRequest" | (string & {});
|
|
203
|
+
type SipEventKind = "StasisStart" | "StasisEnd" | "ChannelStateChange" | "ChannelHangupRequest" | "ChannelDtmfReceived" | "PlayStarted" | "TransferRequested" | "TransferProgress" | "TransferCompleted" | "TransferFailed" | "ChannelBridged" | "BridgeFailed" | "ChannelUnbridged" | "PlayFinished" | "WsTeeStarted" | "WsTeeEnded" | "WsBridgeStarted" | "WsBridgeEnded" | (string & {});
|
|
191
204
|
/** Parse a wire event name; unknown names pass through verbatim (forward-compatible). */
|
|
192
205
|
declare function sipEventKind(name: string): SipEventKind;
|
|
206
|
+
/**
|
|
207
|
+
* The `payload` of a `ChannelDtmfReceived` event — an in-band DTMF digit the
|
|
208
|
+
* media engine detected on a controlled call's leg. Cast a
|
|
209
|
+
* {@link import("./sip").CallEvent}'s `payload` to this when
|
|
210
|
+
* `kind === "ChannelDtmfReceived"`.
|
|
211
|
+
*/
|
|
212
|
+
interface ChannelDtmfPayload {
|
|
213
|
+
/** The single detected digit (`0`–`9`, `*`, `#`, `A`–`D`). */
|
|
214
|
+
digit: string;
|
|
215
|
+
/** The tone duration in milliseconds. */
|
|
216
|
+
duration_ms: number;
|
|
217
|
+
/** The tone volume in dBm0 (negative). */
|
|
218
|
+
volume: number;
|
|
219
|
+
/** The From-tag of the leg the digit came from. */
|
|
220
|
+
from_tag: string;
|
|
221
|
+
}
|
|
222
|
+
/**
|
|
223
|
+
* The `payload` of a `PlayStarted` event — a `play` the media backend accepted
|
|
224
|
+
* and started. Cast a {@link import("./sip").CallEvent}'s `payload` to this when
|
|
225
|
+
* `kind === "PlayStarted"`.
|
|
226
|
+
*
|
|
227
|
+
* `play_id` is the engine's handle on that one playback — what a targeted `stop`
|
|
228
|
+
* ends and what a gain change addresses — and is the same value the `play`
|
|
229
|
+
* command reply carried, which is how the event correlates with the command.
|
|
230
|
+
* The media contract answers `play` accept-on-start, so this event is the
|
|
231
|
+
* playback beginning, not a claim that audio has reached the wire: a fetched
|
|
232
|
+
* source (`source: "url"`) accepts before its body has arrived, which is why
|
|
233
|
+
* `duration_ms` can be absent.
|
|
234
|
+
*/
|
|
235
|
+
interface PlayStartedPayload {
|
|
236
|
+
/** Which source it started from: `file`, `blob`, `db_id`, `tone` or `url`. */
|
|
237
|
+
source: string;
|
|
238
|
+
/** The engine's handle on this playback, when it assigned one. */
|
|
239
|
+
play_id?: number | null;
|
|
240
|
+
/** The playback's length in ms, when the engine knew it at accept time. */
|
|
241
|
+
duration_ms?: number | null;
|
|
242
|
+
}
|
|
243
|
+
/** The RFC 3891 `Replaces` triple embedded in a {@link TransferRequestedPayload}. */
|
|
244
|
+
interface TransferReplaces {
|
|
245
|
+
call_id: string;
|
|
246
|
+
from_tag: string;
|
|
247
|
+
to_tag: string;
|
|
248
|
+
early_only: boolean;
|
|
249
|
+
}
|
|
250
|
+
/**
|
|
251
|
+
* The `payload` of a `TransferRequested` event — an inbound REFER on a
|
|
252
|
+
* controlled call, handed to the app to accept / reject. Cast a
|
|
253
|
+
* {@link import("./sip").CallEvent}'s `payload` to this when
|
|
254
|
+
* `kind === "TransferRequested"`.
|
|
255
|
+
*/
|
|
256
|
+
interface TransferRequestedPayload {
|
|
257
|
+
/** The Refer-To URI (the transfer target). */
|
|
258
|
+
refer_to: string;
|
|
259
|
+
/** The embedded `Replaces` triple for an attended transfer, if present. */
|
|
260
|
+
replaces?: TransferReplaces | null;
|
|
261
|
+
/** The From-tag of the referring party, if known. */
|
|
262
|
+
from_tag?: string | null;
|
|
263
|
+
}
|
|
264
|
+
/**
|
|
265
|
+
* Where a verdict on an *outbound* REFER came from — the `stage` of a
|
|
266
|
+
* {@link TransferOutcomePayload}. Unknown tokens pass through verbatim
|
|
267
|
+
* (forward-compatible).
|
|
268
|
+
*/
|
|
269
|
+
type TransferStage =
|
|
270
|
+
/** `2xx` to the REFER: accepted for processing only (RFC 3515 §2.4.4). */
|
|
271
|
+
"accepted"
|
|
272
|
+
/** `401`/`407` answered with credentials; `attempt` says which try. */
|
|
273
|
+
| "challenged"
|
|
274
|
+
/** A non-terminating `message/sipfrag` NOTIFY reported progress. */
|
|
275
|
+
| "notify"
|
|
276
|
+
/** A terminating sipfrag NOTIFY reported a `2xx`: the transfer completed. */
|
|
277
|
+
| "transferred"
|
|
278
|
+
/** A terminating sipfrag NOTIFY reported `3xx`+: the target failed. */
|
|
279
|
+
| "refused"
|
|
280
|
+
/** The referee refused the REFER itself: the transfer never started. */
|
|
281
|
+
| "rejected"
|
|
282
|
+
/** Challenged with no way to answer (no credentials / retry cap). */
|
|
283
|
+
| "unauthorized"
|
|
284
|
+
/** The subscription ended with no usable status — never read as success. */
|
|
285
|
+
| "no_outcome"
|
|
286
|
+
/** The call ended with the transfer still outstanding. */
|
|
287
|
+
| "call_ended" | (string & {});
|
|
288
|
+
/**
|
|
289
|
+
* The `payload` shared by the `TransferProgress`, `TransferCompleted` and
|
|
290
|
+
* `TransferFailed` events — one verdict on a transfer this app asked for with
|
|
291
|
+
* the `refer` verb.
|
|
292
|
+
*
|
|
293
|
+
* The `refer` command resolves as soon as siphon has sent the REFER; RFC 3515
|
|
294
|
+
* §2.4.4 puts the real outcome on the implicit subscription that follows. Expect
|
|
295
|
+
* zero or more `TransferProgress`, then exactly one `TransferCompleted` /
|
|
296
|
+
* `TransferFailed`. Cast a {@link import("./sip").CallEvent}'s `payload` to this
|
|
297
|
+
* when `kind` is one of those three.
|
|
298
|
+
*/
|
|
299
|
+
interface TransferOutcomePayload {
|
|
300
|
+
/** Where this verdict came from. */
|
|
301
|
+
stage: TransferStage;
|
|
302
|
+
/** The Refer-To URI the REFER carried, when known. */
|
|
303
|
+
refer_to?: string | null;
|
|
304
|
+
/**
|
|
305
|
+
* The SIP status this verdict rests on: the REFER's own response status for
|
|
306
|
+
* `accepted` / `challenged` / `rejected` / `unauthorized`, the sipfrag status
|
|
307
|
+
* for the NOTIFY-driven stages.
|
|
308
|
+
*/
|
|
309
|
+
code?: number | null;
|
|
310
|
+
/** That status's reason phrase, when the peer supplied one. */
|
|
311
|
+
reason?: string | null;
|
|
312
|
+
/**
|
|
313
|
+
* Which REFER attempt this verdict is about, 1-based. `null` once the REFER
|
|
314
|
+
* transaction is over (the NOTIFY-driven stages).
|
|
315
|
+
*/
|
|
316
|
+
attempt?: number | null;
|
|
317
|
+
}
|
|
318
|
+
/**
|
|
319
|
+
* Whether an event name ends a transfer this app asked for. Exactly one such
|
|
320
|
+
* event arrives per `refer`, so this is the signal to stop waiting.
|
|
321
|
+
*/
|
|
322
|
+
declare function isTransferFinal(name: string): boolean;
|
|
323
|
+
/**
|
|
324
|
+
* What happens to the surviving leg when its bridge partner hangs up — the
|
|
325
|
+
* `onPeerHangup` option of {@link import("./sip").Call.bridge}.
|
|
326
|
+
*
|
|
327
|
+
* `"hangup"` (the default) tears the survivor down too: a bridged pair behaves
|
|
328
|
+
* like one call. `"hold"` keeps it up, held (RFC 3264 §8.4) and still owned, so
|
|
329
|
+
* the app can bridge it to somebody else — the supervisor / attended-hand-off
|
|
330
|
+
* case. A closed set: the server refuses anything else with
|
|
331
|
+
* `code === "bad_request"` rather than guessing at a teardown policy.
|
|
332
|
+
*/
|
|
333
|
+
type PeerHangupPolicy = "hangup" | "hold";
|
|
334
|
+
/**
|
|
335
|
+
* Which side of a bridge a leg is — the `role` of a
|
|
336
|
+
* {@link ChannelBridgedPayload}. The `anchor` is the channel the `bridge` was
|
|
337
|
+
* addressed to and keeps its media session; the `peer` is the one named by
|
|
338
|
+
* `with`, whose own media session was deleted when it joined. Unknown tokens
|
|
339
|
+
* pass through verbatim (forward-compatible).
|
|
340
|
+
*/
|
|
341
|
+
type BridgeRole = "anchor" | "peer" | (string & {});
|
|
342
|
+
/**
|
|
343
|
+
* Which of a bridge's two re-INVITEs was refused — the `stage` of a
|
|
344
|
+
* {@link BridgeFailedPayload}. `offering_peer` means the `with` leg refused the
|
|
345
|
+
* anchor's media and the anchor was never touched; `offering_anchor` means the
|
|
346
|
+
* peer answered but the anchor refused what it was re-offered. Unknown tokens
|
|
347
|
+
* pass through verbatim (forward-compatible).
|
|
348
|
+
*/
|
|
349
|
+
type BridgeStage = "offering_peer" | "offering_anchor" | (string & {});
|
|
350
|
+
/**
|
|
351
|
+
* The `payload` of a `ChannelBridged` event — the bridge formed and the two
|
|
352
|
+
* parties can hear each other.
|
|
353
|
+
*
|
|
354
|
+
* A bridge is two RFC 3261 §14 re-INVITEs across two dialogs, so the `bridge`
|
|
355
|
+
* command reply reports only the local action (the media re-pointed, the first
|
|
356
|
+
* re-INVITE on the wire) and this event is the outcome. It is pushed on **both**
|
|
357
|
+
* bridged channels, each copy naming the other leg. Cast a
|
|
358
|
+
* {@link import("./sip").CallEvent}'s `payload` to this when
|
|
359
|
+
* `kind === "ChannelBridged"`.
|
|
360
|
+
*/
|
|
361
|
+
interface ChannelBridgedPayload {
|
|
362
|
+
/** The internal `CallActor` id of the leg on the other side. */
|
|
363
|
+
peer_call_id: string;
|
|
364
|
+
/** That leg's SIP `Call-ID` — the CDR / HEP join key for the other party. */
|
|
365
|
+
peer_sip_call_id: string;
|
|
366
|
+
/** Which side *this* channel is. */
|
|
367
|
+
role: BridgeRole;
|
|
368
|
+
/** Whether the bridged pair lives on the media engine (the anchor's session). */
|
|
369
|
+
anchored: boolean;
|
|
370
|
+
}
|
|
371
|
+
/**
|
|
372
|
+
* The `payload` of a `BridgeFailed` event — one of the bridge's two re-INVITEs
|
|
373
|
+
* was refused and both legs were left exactly as they were. Never a teardown:
|
|
374
|
+
* the app still owns both calls and can retry, bridge elsewhere, or hang up.
|
|
375
|
+
*/
|
|
376
|
+
interface BridgeFailedPayload {
|
|
377
|
+
/** Which re-INVITE was refused. */
|
|
378
|
+
stage: BridgeStage;
|
|
379
|
+
/** The SIP status the refusing leg answered with (`488`, `491`, `500`, …). */
|
|
380
|
+
code?: number | null;
|
|
381
|
+
/** The SIP `Call-ID` of the other leg in the attempt. */
|
|
382
|
+
peer_sip_call_id?: string | null;
|
|
383
|
+
}
|
|
384
|
+
/**
|
|
385
|
+
* The `payload` of a `ChannelUnbridged` event — the bridge was broken. Both legs
|
|
386
|
+
* stay answered, owned and held (RFC 3264 §8.4 `a=sendonly`); neither is hung
|
|
387
|
+
* up, because that would be indistinguishable from two hangups. Pushed on both
|
|
388
|
+
* channels.
|
|
389
|
+
*/
|
|
390
|
+
interface ChannelUnbridgedPayload {
|
|
391
|
+
/** The internal `CallActor` id of the leg that was on the other side. */
|
|
392
|
+
peer_call_id: string;
|
|
393
|
+
/** That leg's SIP `Call-ID`. */
|
|
394
|
+
peer_sip_call_id: string;
|
|
395
|
+
/** The reason the `unbridge` carried (default `"unbridged"`). */
|
|
396
|
+
reason: string;
|
|
397
|
+
}
|
|
398
|
+
/**
|
|
399
|
+
* The `payload` of a `PlayFinished` event — a playback ended.
|
|
400
|
+
*
|
|
401
|
+
* `completed` is the field to branch on: a stop, a supersede and an error all
|
|
402
|
+
* end a playback without the prompt having been heard in full, and the accept's
|
|
403
|
+
* estimated duration says nothing about which happened.
|
|
404
|
+
*/
|
|
405
|
+
interface PlayFinishedPayload {
|
|
406
|
+
from_tag: string;
|
|
407
|
+
to_tag?: string | null;
|
|
408
|
+
/** Correlates with the `play` accept and the `PlayStarted` event. */
|
|
409
|
+
play_id: number;
|
|
410
|
+
/** `completed`, `stopped`, `superseded` or `error`. */
|
|
411
|
+
reason: string;
|
|
412
|
+
/** Whether the prompt drained naturally — the only reason it was heard in full. */
|
|
413
|
+
completed: boolean;
|
|
414
|
+
played_ms?: number | null;
|
|
415
|
+
}
|
|
416
|
+
/**
|
|
417
|
+
* The `payload` of a `WsTeeStarted` event — a WebSocket audio **tee** began
|
|
418
|
+
* streaming a copy of the channel's audio. Additive: the call relays on
|
|
419
|
+
* regardless, so a tee never affects the parties.
|
|
420
|
+
*
|
|
421
|
+
* `streamId` correlates this event with the `start` frame on the socket, and
|
|
422
|
+
* the wire shape is stated so a consumer decodes the binary frames without
|
|
423
|
+
* guessing.
|
|
424
|
+
*/
|
|
425
|
+
interface WsTeeStartedPayload {
|
|
426
|
+
from_tag: string;
|
|
427
|
+
stream_id: string;
|
|
428
|
+
ws_uri: string;
|
|
429
|
+
/** `both`, `caller` or `callee`. */
|
|
430
|
+
direction: string;
|
|
431
|
+
/** 1 = mono/mixed, 2 = caller/callee interleaved. */
|
|
432
|
+
channels: number;
|
|
433
|
+
/** Wire sample rate in Hz (L16, little-endian). */
|
|
434
|
+
sample_rate: number;
|
|
435
|
+
}
|
|
436
|
+
/**
|
|
437
|
+
* The `payload` of a `WsTeeEnded` event. Exactly one arrives per
|
|
438
|
+
* `WsTeeStarted`, including when the *server* ends it, so a consumer learns
|
|
439
|
+
* the stream died rather than silently losing the audio.
|
|
440
|
+
*
|
|
441
|
+
* `frames_dropped > 0` means the consumer could not keep up; the call itself
|
|
442
|
+
* was never affected.
|
|
443
|
+
*/
|
|
444
|
+
interface WsTeeEndedPayload {
|
|
445
|
+
from_tag: string;
|
|
446
|
+
stream_id: string;
|
|
447
|
+
/** `detached`, `server_closed`, `server_stopped`, `call_ended` or `transport_error`. */
|
|
448
|
+
reason: string;
|
|
449
|
+
/** `detached` is the only orderly end; anything else stopped the audio mid-call. */
|
|
450
|
+
unexpected: boolean;
|
|
451
|
+
frames_sent?: number | null;
|
|
452
|
+
frames_dropped?: number | null;
|
|
453
|
+
}
|
|
454
|
+
/**
|
|
455
|
+
* The `payload` of a `WsBridgeStarted` event — a WebSocket **takeover** bridge
|
|
456
|
+
* began. Unlike a tee this *replaced* the call's audio path: the WebSocket
|
|
457
|
+
* server is now the leg's far side and A-to-B is unwired.
|
|
458
|
+
*/
|
|
459
|
+
interface WsBridgeStartedPayload {
|
|
460
|
+
from_tag: string;
|
|
461
|
+
stream_id: string;
|
|
462
|
+
ws_uri: string;
|
|
463
|
+
/** Wire sample rate in Hz (L16, little-endian). */
|
|
464
|
+
sample_rate: number;
|
|
465
|
+
}
|
|
466
|
+
/**
|
|
467
|
+
* The `payload` of a `WsBridgeEnded` event. Exactly one per
|
|
468
|
+
* `WsBridgeStarted`; a re-point arrives as an ended (reason `detached`)
|
|
469
|
+
* followed by a fresh started.
|
|
470
|
+
*
|
|
471
|
+
* `unexpected` matters more here than on a tee: a bridge *is* the call's media
|
|
472
|
+
* path, so anything but `detached` leaves both parties up and hearing nothing.
|
|
473
|
+
*/
|
|
474
|
+
interface WsBridgeEndedPayload {
|
|
475
|
+
from_tag: string;
|
|
476
|
+
stream_id: string;
|
|
477
|
+
/** `detached`, `server_closed`, `server_stopped`, `call_ended` or `transport_error`. */
|
|
478
|
+
reason: string;
|
|
479
|
+
unexpected: boolean;
|
|
480
|
+
}
|
|
481
|
+
/**
|
|
482
|
+
* Whether an event name ends a bridge this app asked for. Exactly one such event
|
|
483
|
+
* arrives per `bridge`, so this is the signal to stop waiting. `ChannelUnbridged`
|
|
484
|
+
* is not one of them — it ends a bridge that already formed.
|
|
485
|
+
*/
|
|
486
|
+
declare function isBridgeFinal(name: string): boolean;
|
|
193
487
|
|
|
194
488
|
/** Small internal utilities shared by the client, server, and SIP facade. */
|
|
195
489
|
/**
|
|
@@ -385,7 +679,16 @@ declare class ControlServer {
|
|
|
385
679
|
}
|
|
386
680
|
|
|
387
681
|
/** One event delivered to a call's stream (`ChannelStateChange`,
|
|
388
|
-
* `ChannelHangupRequest`, `
|
|
682
|
+
* `ChannelHangupRequest`, `ChannelDtmfReceived`, `TransferRequested`,
|
|
683
|
+
* `TransferProgress`, `TransferCompleted`, `TransferFailed`, `ChannelBridged`,
|
|
684
|
+
* `BridgeFailed`, `ChannelUnbridged`, `StasisEnd`, …).
|
|
685
|
+
* Cast `payload` to
|
|
686
|
+
* {@link import("./protocol").ChannelDtmfPayload} /
|
|
687
|
+
* {@link import("./protocol").TransferRequestedPayload} /
|
|
688
|
+
* {@link import("./protocol").TransferOutcomePayload} /
|
|
689
|
+
* {@link import("./protocol").ChannelBridgedPayload} /
|
|
690
|
+
* {@link import("./protocol").BridgeFailedPayload} /
|
|
691
|
+
* {@link import("./protocol").ChannelUnbridgedPayload} by `kind`. */
|
|
389
692
|
interface CallEvent {
|
|
390
693
|
/** The parsed event kind. */
|
|
391
694
|
kind: SipEventKind;
|
|
@@ -413,6 +716,89 @@ interface AcceptReferOptions {
|
|
|
413
716
|
target?: string;
|
|
414
717
|
nextHop?: string;
|
|
415
718
|
mode?: "terminate" | "transparent";
|
|
719
|
+
/**
|
|
720
|
+
* Media profile for the pairing the transfer creates.
|
|
721
|
+
*
|
|
722
|
+
* **Required when the call is anchored with a direction-bound profile** — one
|
|
723
|
+
* whose offer and answer halves describe different sides, such as
|
|
724
|
+
* `srtp_to_rtp` at an SRTP edge. A transfer moves the party that half was
|
|
725
|
+
* written for out of the call, so inheriting the profile re-offers *that
|
|
726
|
+
* party's* transport to whoever remains: SRTP toward a plain-RTP carrier,
|
|
727
|
+
* which answers `m=audio 0`. The call connects and carries no audio in either
|
|
728
|
+
* direction while the SIP trace looks healthy.
|
|
729
|
+
*
|
|
730
|
+
* Pass the profile for the pair that remains (commonly `"rtp_passthrough"`).
|
|
731
|
+
* Omitted inherits the call's profile, which is correct only when it is
|
|
732
|
+
* symmetric.
|
|
733
|
+
*/
|
|
734
|
+
profile?: string;
|
|
735
|
+
}
|
|
736
|
+
/** Options for {@link Call.bridge}. */
|
|
737
|
+
interface BridgeOptions {
|
|
738
|
+
/**
|
|
739
|
+
* What happens to the surviving leg when its bridge partner hangs up —
|
|
740
|
+
* `"hangup"` (the default) tears it down too, `"hold"` keeps it up, held and
|
|
741
|
+
* still owned so it can be bridged to somebody else. See
|
|
742
|
+
* {@link import("./protocol").PeerHangupPolicy}.
|
|
743
|
+
*/
|
|
744
|
+
onPeerHangup?: PeerHangupPolicy;
|
|
745
|
+
}
|
|
746
|
+
/** A {@link Call.route} target carrying per-target overrides. */
|
|
747
|
+
interface RouteTargetObject {
|
|
748
|
+
/** The B-leg request URI to dial. */
|
|
749
|
+
uri: string;
|
|
750
|
+
/** Route egress to this next hop instead of resolving `uri`. */
|
|
751
|
+
nextHop?: string;
|
|
752
|
+
/** Headers injected on this attempt's B-leg INVITE. */
|
|
753
|
+
headers?: Record<string, string>;
|
|
754
|
+
/** Per-target ring timeout in seconds. */
|
|
755
|
+
timeout?: number;
|
|
756
|
+
}
|
|
757
|
+
/**
|
|
758
|
+
* One entry in a {@link Call.route} target list: a bare URI string, or a
|
|
759
|
+
* {@link RouteTargetObject} with per-target overrides.
|
|
760
|
+
*/
|
|
761
|
+
type RouteTarget = string | RouteTargetObject;
|
|
762
|
+
/**
|
|
763
|
+
* The audio source for {@link Call.play}: exactly one of a server-side file
|
|
764
|
+
* path, an rtpengine media-DB id, or an inline blob. A blob is base64-encoded on
|
|
765
|
+
* the wire (the control rail is JSON text).
|
|
766
|
+
*/
|
|
767
|
+
type PlaySource = {
|
|
768
|
+
file: string;
|
|
769
|
+
} | {
|
|
770
|
+
dbId: number;
|
|
771
|
+
} | {
|
|
772
|
+
blob: Uint8Array;
|
|
773
|
+
};
|
|
774
|
+
/** Optional shaping for {@link Call.play}. */
|
|
775
|
+
interface PlayOptions {
|
|
776
|
+
/** Repeat the prompt this many times (0/undefined → play once). */
|
|
777
|
+
repeat?: number;
|
|
778
|
+
/** Start playback at this offset into the source, in milliseconds. */
|
|
779
|
+
startMs?: number;
|
|
780
|
+
/** Cap playback to this duration, in milliseconds. */
|
|
781
|
+
durationMs?: number;
|
|
782
|
+
/** Scope the prompt to one peer of an MPTY bridge (its To-tag). */
|
|
783
|
+
toTag?: string;
|
|
784
|
+
}
|
|
785
|
+
/** Optional shaping for {@link Call.dtmf}. */
|
|
786
|
+
interface DtmfOptions {
|
|
787
|
+
/** Per-digit tone duration, in milliseconds. */
|
|
788
|
+
durationMs?: number;
|
|
789
|
+
/** Tone volume in dBm0 (negative). */
|
|
790
|
+
volumeDbm0?: number;
|
|
791
|
+
/** Inter-digit pause, in milliseconds. */
|
|
792
|
+
pauseMs?: number;
|
|
793
|
+
/** Scope the tones to one peer of an MPTY bridge (its To-tag). */
|
|
794
|
+
toTag?: string;
|
|
795
|
+
}
|
|
796
|
+
/** Options for {@link Call.streamStart} (the WebSocket audio tee). */
|
|
797
|
+
interface StreamOptions {
|
|
798
|
+
/** Which leg(s) to tee — `"both"` (default), `"caller"`, or `"callee"`. */
|
|
799
|
+
direction?: "both" | "caller" | "callee";
|
|
800
|
+
/** `1` = mixed mono, `2` = caller/callee stereo (only with `"both"`). */
|
|
801
|
+
channels?: 1 | 2;
|
|
416
802
|
}
|
|
417
803
|
/**
|
|
418
804
|
* A handed-over SIP call. Cheap to hold (shares one connection + event stream).
|
|
@@ -451,7 +837,20 @@ declare class Call {
|
|
|
451
837
|
private substrate;
|
|
452
838
|
/** Send a UAS 2xx to the parked A-leg (default `200 OK`). */
|
|
453
839
|
answer(options?: ResponseOptions): Promise<void>;
|
|
454
|
-
/**
|
|
840
|
+
/**
|
|
841
|
+
* Send `180 Ringing`: alerting only, no early media.
|
|
842
|
+
*
|
|
843
|
+
* RFC 3261 §13.2.1 makes the 180 the "callee is being alerted" signal, and
|
|
844
|
+
* RFC 3960 §3.1 puts early media on a response that carries SDP — two
|
|
845
|
+
* different acts, so two verbs. Ring for as long as your own policy says,
|
|
846
|
+
* then {@link Call.answer}; open an early-media path with
|
|
847
|
+
* {@link Call.progress}.
|
|
848
|
+
*/
|
|
849
|
+
ring(reason?: string): Promise<void>;
|
|
850
|
+
/**
|
|
851
|
+
* Send a UAS 1xx, optionally opening an early-media path with SDP (default
|
|
852
|
+
* `183 Session Progress`). For plain alerting use {@link Call.ring}.
|
|
853
|
+
*/
|
|
455
854
|
progress(options?: ResponseOptions): Promise<void>;
|
|
456
855
|
/** Send a final non-2xx and tear the call down. */
|
|
457
856
|
reject(code: number, reason?: string): Promise<void>;
|
|
@@ -462,50 +861,145 @@ declare class Call {
|
|
|
462
861
|
terminate(reason?: string): Promise<void>;
|
|
463
862
|
/** Alias for {@link Call.terminate}. */
|
|
464
863
|
hangup(reason?: string): Promise<void>;
|
|
465
|
-
/**
|
|
864
|
+
/**
|
|
865
|
+
* Send an in-dialog REFER on the A-leg (blind transfer).
|
|
866
|
+
*
|
|
867
|
+
* Resolves as soon as siphon has sent the REFER — that is *sent*, not
|
|
868
|
+
* *transferred*. RFC 3515 §2.4.4 delivers the outcome afterwards on the
|
|
869
|
+
* implicit subscription, so read it off {@link Call.events}: zero or more
|
|
870
|
+
* `TransferProgress`, then exactly one `TransferCompleted` /
|
|
871
|
+
* `TransferFailed`, each carrying a
|
|
872
|
+
* {@link import("./protocol").TransferOutcomePayload}. Use
|
|
873
|
+
* {@link import("./protocol").isTransferFinal} to know when to stop waiting.
|
|
874
|
+
*/
|
|
466
875
|
refer(to: string): Promise<void>;
|
|
467
876
|
/** Blind-transfer alias for {@link Call.refer}. */
|
|
468
877
|
transfer(to: string): Promise<void>;
|
|
469
878
|
/** Attended transfer — REFER with a `Replaces` triple (RFC 3891). */
|
|
470
879
|
referReplaces(to: string, replaces: ReferReplaces): Promise<void>;
|
|
471
880
|
/**
|
|
472
|
-
*
|
|
473
|
-
*
|
|
474
|
-
*
|
|
881
|
+
* Un-park this controlled call and dial the B-leg via siphon's LCR
|
|
882
|
+
* sequential-failover engine, returning control to siphon.
|
|
883
|
+
*
|
|
884
|
+
* `targets` is a non-empty list of carriers tried cheapest-first: each entry
|
|
885
|
+
* is a bare URI string or a {@link RouteTargetObject}
|
|
886
|
+
* (`{uri, nextHop?, headers?, timeout?}`). `strategy` defaults to
|
|
887
|
+
* `"sequential"` (v1 supports only sequential/single — anything else rejects
|
|
888
|
+
* with `code === "unsupported_verb"`). `headers` is applied to every
|
|
889
|
+
* attempt's B-leg INVITE.
|
|
890
|
+
*
|
|
891
|
+
* Resolves to the reply `result` (`{channel, state: "routing", targets}`). An
|
|
892
|
+
* empty / invalid `targets` list rejects with `code === "bad_request"`; a call
|
|
893
|
+
* that is already gone rejects with `code === "not_found"`.
|
|
894
|
+
*/
|
|
895
|
+
route(targets: RouteTarget[], strategy?: string, headers?: Record<string, string>): Promise<unknown>;
|
|
896
|
+
/**
|
|
897
|
+
* Accept a *pending inbound* REFER (surfaced as a `TransferRequested` event)
|
|
898
|
+
* and run the transfer. `target` overrides the Refer-To URI, `nextHop` steers
|
|
899
|
+
* egress, and `mode` (`"terminate"` / `"transparent"`) overrides
|
|
900
|
+
* `b2bua.default_refer_mode`. No pending REFER (already decided, timed out, or
|
|
901
|
+
* the call is gone) rejects with `code === "not_found"`.
|
|
902
|
+
*
|
|
903
|
+
* `profile` names the media profile for the pairing the transfer creates —
|
|
904
|
+
* see {@link AcceptReferOptions.profile}, which is required at an SRTP edge.
|
|
475
905
|
*/
|
|
476
906
|
acceptRefer(options?: AcceptReferOptions): Promise<void>;
|
|
477
907
|
/**
|
|
478
|
-
* Reject
|
|
479
|
-
*
|
|
908
|
+
* Reject a *pending inbound* REFER with a final non-2xx (default
|
|
909
|
+
* `603 Decline`). No pending REFER rejects with `code === "not_found"`.
|
|
480
910
|
*/
|
|
481
911
|
rejectRefer(code: number, reason?: string): Promise<void>;
|
|
912
|
+
/**
|
|
913
|
+
* Join this call to another leg the app owns, so the two parties hear each
|
|
914
|
+
* other.
|
|
915
|
+
*
|
|
916
|
+
* **This call is the anchor.** It keeps its media session — its ports and
|
|
917
|
+
* everything attached to them; the `withChannel` leg's own media session is
|
|
918
|
+
* deleted and it becomes the second party on this one's. So bridge *into* the
|
|
919
|
+
* leg whose media you want to keep (the one being recorded, teed, or carrying
|
|
920
|
+
* the prompt).
|
|
921
|
+
*
|
|
922
|
+
* Both legs must already be answered. `options.onPeerHangup` says what happens
|
|
923
|
+
* to the survivor when its partner hangs up (see
|
|
924
|
+
* {@link import("./protocol").PeerHangupPolicy}); omitted means `"hangup"`.
|
|
925
|
+
*
|
|
926
|
+
* Resolves as soon as the media has been re-pointed and the first re-INVITE is
|
|
927
|
+
* on the wire — that is *offered*, not *bridged*. A bridge is two RFC 3261 §14
|
|
928
|
+
* re-INVITEs across two dialogs, so the outcome arrives on {@link Call.events}
|
|
929
|
+
* instead: exactly one `ChannelBridged`
|
|
930
|
+
* ({@link import("./protocol").ChannelBridgedPayload}) / `BridgeFailed`
|
|
931
|
+
* ({@link import("./protocol").BridgeFailedPayload}), on **both** channels.
|
|
932
|
+
* {@link import("./protocol").isBridgeFinal} says when to stop waiting.
|
|
933
|
+
*
|
|
934
|
+
* Resolves to the reply `result` (`{channel, with, call_id, peer_call_id,
|
|
935
|
+
* anchored, on_peer_hangup, state: "bridging"}`). Rejects with a `code` a
|
|
936
|
+
* caller can act on: `"not_found"` (no such leg), `"invalid_state"` (a leg has
|
|
937
|
+
* not answered, is already bridged, has a re-INVITE outstanding, or carries no
|
|
938
|
+
* media description), `"bad_request"` (the same leg named twice, or a bad
|
|
939
|
+
* `onPeerHangup`), `"forbidden"` (the other channel belongs to another app),
|
|
940
|
+
* `"unsupported_verb"` (the media backend cannot express it).
|
|
941
|
+
*/
|
|
942
|
+
bridge(withChannel: string, options?: BridgeOptions): Promise<unknown>;
|
|
943
|
+
/**
|
|
944
|
+
* Break this call's bridge.
|
|
945
|
+
*
|
|
946
|
+
* Both legs stay answered, owned and held — re-offered `a=sendonly`
|
|
947
|
+
* (RFC 3264 §8.4, which RFC 6337 §3.1 prefers to `c=0.0.0.0`). Neither is hung
|
|
948
|
+
* up: that would be indistinguishable from two hangups and would take away the
|
|
949
|
+
* calls the app still owns. A later {@link Call.bridge} re-offers `sendrecv`.
|
|
950
|
+
*
|
|
951
|
+
* `reason` is free text carried on the `ChannelUnbridged`
|
|
952
|
+
* ({@link import("./protocol").ChannelUnbridgedPayload}) event both channels
|
|
953
|
+
* receive; omitted means `"unbridged"`. Resolves to the reply `result`
|
|
954
|
+
* (`{channel, with, reason, state: "unbridged"}`), where `with` is the channel
|
|
955
|
+
* id of the leg that was on the other side. A call that is not bridged rejects
|
|
956
|
+
* with `code === "invalid_state"`.
|
|
957
|
+
*/
|
|
958
|
+
unbridge(reason?: string): Promise<unknown>;
|
|
482
959
|
/** Set a header on the stored A-leg INVITE. */
|
|
483
960
|
setHeader(name: string, value: string): Promise<void>;
|
|
484
961
|
/** Read a header from the stored A-leg INVITE (`null` when absent). */
|
|
485
962
|
getHeader(name: string): Promise<string | null>;
|
|
486
|
-
/**
|
|
487
|
-
* Remove a header from the stored A-leg INVITE. **Not implemented server-side
|
|
488
|
-
* in Phase 1** — resolves to a {@link ControlError} with `code ===
|
|
489
|
-
* "unsupported_verb"` until the server adds it.
|
|
490
|
-
*/
|
|
963
|
+
/** Remove a header from the stored A-leg INVITE. */
|
|
491
964
|
removeHeader(name: string): Promise<void>;
|
|
492
965
|
/** Set a per-call variable (survives a reconnect via `resync`). */
|
|
493
966
|
setVar(key: string, value: string): Promise<void>;
|
|
494
967
|
/** Read a per-call variable (`null` when unset). */
|
|
495
968
|
getVar(key: string): Promise<string | null>;
|
|
496
969
|
/**
|
|
497
|
-
* Play an announcement
|
|
498
|
-
* {@link
|
|
499
|
-
*
|
|
970
|
+
* Play an announcement on the A-leg media (fire-and-forget). `source` is a
|
|
971
|
+
* {@link PlaySource} (a blob is base64-encoded on the wire); `options` shapes
|
|
972
|
+
* playback. A call with no anchored media session rejects with
|
|
973
|
+
* `code === "not_found"`.
|
|
500
974
|
*/
|
|
975
|
+
play(source: PlaySource, options?: PlayOptions): Promise<void>;
|
|
976
|
+
/** Convenience for {@link Call.play} of a server-side file with default options. */
|
|
501
977
|
playFile(file: string): Promise<void>;
|
|
502
|
-
/**
|
|
503
|
-
|
|
978
|
+
/** Stop the announcement currently playing on the A-leg media. */
|
|
979
|
+
stop(): Promise<void>;
|
|
980
|
+
/**
|
|
981
|
+
* Inject DTMF digits toward the A-leg (fire-and-forget). `options` carries the
|
|
982
|
+
* optional `durationMs` / `volumeDbm0` / `pauseMs` / `toTag` shaping.
|
|
983
|
+
*/
|
|
984
|
+
dtmf(digits: string, options?: DtmfOptions): Promise<void>;
|
|
985
|
+
/** Hold the A-leg media via silence. */
|
|
986
|
+
hold(): Promise<void>;
|
|
987
|
+
/** Resume the A-leg media after a {@link Call.hold}. */
|
|
988
|
+
unhold(): Promise<void>;
|
|
989
|
+
/**
|
|
990
|
+
* Attach a WebSocket audio tee — stream a copy of the call's decoded audio to
|
|
991
|
+
* `wsUri` while the call keeps relaying. siphon-rtp backend only: rtpengine /
|
|
992
|
+
* rtpproxy reject with `code === "unsupported_verb"` (`error.isUnsupportedVerb()`).
|
|
993
|
+
*/
|
|
994
|
+
streamStart(wsUri: string, options?: StreamOptions): Promise<void>;
|
|
995
|
+
/** Detach the WebSocket audio tee (idempotent on siphon-rtp). */
|
|
996
|
+
streamStop(): Promise<void>;
|
|
504
997
|
/** Send an arbitrary SIP-adapter verb + args and return the raw result. */
|
|
505
998
|
command(verb: string, args?: unknown): Promise<unknown>;
|
|
506
999
|
/**
|
|
507
1000
|
* Await the next event for this call (`ChannelStateChange`,
|
|
508
|
-
* `ChannelHangupRequest`, `
|
|
1001
|
+
* `ChannelHangupRequest`, `ChannelBridged`, `BridgeFailed`,
|
|
1002
|
+
* `ChannelUnbridged`, `StasisEnd`). `null` once the stream closes.
|
|
509
1003
|
*/
|
|
510
1004
|
nextEvent(): Promise<CallEvent | null>;
|
|
511
1005
|
/** Async-iterate this call's events until the stream closes. */
|
|
@@ -585,4 +1079,4 @@ declare class SipServer {
|
|
|
585
1079
|
close(): Promise<void>;
|
|
586
1080
|
}
|
|
587
1081
|
|
|
588
|
-
export { type AcceptReferOptions, Call, type CallEvent, type CallHandler, CallStream, type ChannelSnapshot, type ClientConfig, type ClientEvent, type CommandTransport, type ConnectionEventSink, ControlClient, ControlError, type ControlErrorCode, type ControlErrorKind, ControlServer, DESCRIBE, type EventFrame, type EventSink, EventStream, type FrameType, GET_VAR, HELLO, type HelloArgs, type HelloResult, MODULE_SIP, MODULE_SMPP, MODULE_SS7, PROTOCOL_VERSION, RESYNC, type ReferReplaces, type ReplyError, type ReplyFrame, type ReplyStatus, type ResponseOptions, type ResyncResult, SET_VAR, SUBPROTOCOL, type ServerConfig, SipClient, type SipEventKind, SipServer, SipVerb, type SipVerbToken, encodeCommand, parseInboundFrame, sipEventKind };
|
|
1082
|
+
export { type AcceptReferOptions, 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 DtmfOptions, type EventFrame, type EventSink, EventStream, type FrameType, GET_VAR, HELLO, type HelloArgs, type HelloResult, MODULE_SIP, MODULE_SMPP, MODULE_SS7, PROTOCOL_VERSION, type PeerHangupPolicy, type PlayFinishedPayload, type PlayOptions, type PlaySource, type PlayStartedPayload, RESYNC, type ReferReplaces, type ReplyError, type ReplyFrame, type ReplyStatus, type ResponseOptions, type ResyncResult, type RouteTarget, type RouteTargetObject, SET_VAR, SUBPROTOCOL, type ServerConfig, SipClient, type SipEventKind, SipServer, SipVerb, type SipVerbToken, type StreamOptions, type TransferOutcomePayload, type TransferReplaces, type TransferRequestedPayload, type TransferStage, type WsBridgeEndedPayload, type WsBridgeStartedPayload, type WsTeeEndedPayload, type WsTeeStartedPayload, encodeCommand, isBridgeFinal, isTransferFinal, parseInboundFrame, sipEventKind };
|