@siphon-project/control 0.1.2 → 0.2.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
@@ -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
@@ -171,6 +171,12 @@ declare function parseInboundFrame(text: string): ReplyFrame | EventFrame | null
171
171
  */
172
172
  declare const SipVerb: {
173
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";
174
180
  readonly Progress: "progress";
175
181
  readonly Reject: "reject";
176
182
  readonly Hangup: "hangup";
@@ -181,6 +187,9 @@ declare const SipVerb: {
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";
192
+ readonly ReplacePeer: "replace_peer";
184
193
  readonly Play: "play";
185
194
  readonly Stop: "stop";
186
195
  readonly Dtmf: "dtmf";
@@ -192,7 +201,7 @@ declare const SipVerb: {
192
201
  /** A value of {@link SipVerb}. */
193
202
  type SipVerbToken = (typeof SipVerb)[keyof typeof SipVerb];
194
203
  /** The well-known SIP-adapter event names (the ARI *Stasis* model). */
195
- type SipEventKind = "StasisStart" | "StasisEnd" | "ChannelStateChange" | "ChannelHangupRequest" | "ChannelDtmfReceived" | "TransferRequested" | (string & {});
204
+ type SipEventKind = "StasisStart" | "StasisEnd" | "ChannelStateChange" | "ChannelHangupRequest" | "ChannelDtmfReceived" | "PlayStarted" | "TransferRequested" | "TransferProgress" | "TransferCompleted" | "TransferFailed" | "ChannelBridged" | "BridgeFailed" | "ChannelUnbridged" | "PeerReplaced" | "ReplaceFailed" | "PlayFinished" | "WsTeeStarted" | "WsTeeEnded" | "WsBridgeStarted" | "WsBridgeEnded" | (string & {});
196
205
  /** Parse a wire event name; unknown names pass through verbatim (forward-compatible). */
197
206
  declare function sipEventKind(name: string): SipEventKind;
198
207
  /**
@@ -211,6 +220,27 @@ interface ChannelDtmfPayload {
211
220
  /** The From-tag of the leg the digit came from. */
212
221
  from_tag: string;
213
222
  }
223
+ /**
224
+ * The `payload` of a `PlayStarted` event — a `play` the media backend accepted
225
+ * and started. Cast a {@link import("./sip").CallEvent}'s `payload` to this when
226
+ * `kind === "PlayStarted"`.
227
+ *
228
+ * `play_id` is the engine's handle on that one playback — what a targeted `stop`
229
+ * ends and what a gain change addresses — and is the same value the `play`
230
+ * command reply carried, which is how the event correlates with the command.
231
+ * The media contract answers `play` accept-on-start, so this event is the
232
+ * playback beginning, not a claim that audio has reached the wire: a fetched
233
+ * source (`source: "url"`) accepts before its body has arrived, which is why
234
+ * `duration_ms` can be absent.
235
+ */
236
+ interface PlayStartedPayload {
237
+ /** Which source it started from: `file`, `blob`, `db_id`, `tone` or `url`. */
238
+ source: string;
239
+ /** The engine's handle on this playback, when it assigned one. */
240
+ play_id?: number | null;
241
+ /** The playback's length in ms, when the engine knew it at accept time. */
242
+ duration_ms?: number | null;
243
+ }
214
244
  /** The RFC 3891 `Replaces` triple embedded in a {@link TransferRequestedPayload}. */
215
245
  interface TransferReplaces {
216
246
  call_id: string;
@@ -232,6 +262,242 @@ interface TransferRequestedPayload {
232
262
  /** The From-tag of the referring party, if known. */
233
263
  from_tag?: string | null;
234
264
  }
265
+ /**
266
+ * Where a verdict on an *outbound* REFER came from — the `stage` of a
267
+ * {@link TransferOutcomePayload}. Unknown tokens pass through verbatim
268
+ * (forward-compatible).
269
+ */
270
+ type TransferStage =
271
+ /** `2xx` to the REFER: accepted for processing only (RFC 3515 §2.4.4). */
272
+ "accepted"
273
+ /** `401`/`407` answered with credentials; `attempt` says which try. */
274
+ | "challenged"
275
+ /** A non-terminating `message/sipfrag` NOTIFY reported progress. */
276
+ | "notify"
277
+ /** A terminating sipfrag NOTIFY reported a `2xx`: the transfer completed. */
278
+ | "transferred"
279
+ /** A terminating sipfrag NOTIFY reported `3xx`+: the target failed. */
280
+ | "refused"
281
+ /** The referee refused the REFER itself: the transfer never started. */
282
+ | "rejected"
283
+ /** Challenged with no way to answer (no credentials / retry cap). */
284
+ | "unauthorized"
285
+ /** The subscription ended with no usable status — never read as success. */
286
+ | "no_outcome"
287
+ /** The call ended with the transfer still outstanding. */
288
+ | "call_ended" | (string & {});
289
+ /**
290
+ * The `payload` shared by the `TransferProgress`, `TransferCompleted` and
291
+ * `TransferFailed` events — one verdict on a transfer this app asked for with
292
+ * the `refer` verb.
293
+ *
294
+ * The `refer` command resolves as soon as siphon has sent the REFER; RFC 3515
295
+ * §2.4.4 puts the real outcome on the implicit subscription that follows. Expect
296
+ * zero or more `TransferProgress`, then exactly one `TransferCompleted` /
297
+ * `TransferFailed`. Cast a {@link import("./sip").CallEvent}'s `payload` to this
298
+ * when `kind` is one of those three.
299
+ */
300
+ interface TransferOutcomePayload {
301
+ /** Where this verdict came from. */
302
+ stage: TransferStage;
303
+ /** The Refer-To URI the REFER carried, when known. */
304
+ refer_to?: string | null;
305
+ /**
306
+ * The SIP status this verdict rests on: the REFER's own response status for
307
+ * `accepted` / `challenged` / `rejected` / `unauthorized`, the sipfrag status
308
+ * for the NOTIFY-driven stages.
309
+ */
310
+ code?: number | null;
311
+ /** That status's reason phrase, when the peer supplied one. */
312
+ reason?: string | null;
313
+ /**
314
+ * Which REFER attempt this verdict is about, 1-based. `null` once the REFER
315
+ * transaction is over (the NOTIFY-driven stages).
316
+ */
317
+ attempt?: number | null;
318
+ }
319
+ /**
320
+ * Whether an event name ends a transfer this app asked for. Exactly one such
321
+ * event arrives per `refer`, so this is the signal to stop waiting.
322
+ */
323
+ declare function isTransferFinal(name: string): boolean;
324
+ /**
325
+ * The transfer verdict carried by an event, or `null` if it is not one.
326
+ *
327
+ * Takes an event as {@link import("./sip").CallEvent} shapes it and narrows its
328
+ * `payload` to {@link TransferOutcomePayload} for `TransferProgress` /
329
+ * `TransferCompleted` / `TransferFailed`. Anything else — including
330
+ * `TransferRequested`, which is an *inbound* REFER somebody else asked for
331
+ * rather than a verdict on one of ours — gives `null`.
332
+ */
333
+ declare function transferOutcome(event: {
334
+ kind: string;
335
+ payload: unknown;
336
+ }): TransferOutcomePayload | null;
337
+ /**
338
+ * What happens to the surviving leg when its bridge partner hangs up — the
339
+ * `onPeerHangup` option of {@link import("./sip").Call.bridge}.
340
+ *
341
+ * `"hangup"` (the default) tears the survivor down too: a bridged pair behaves
342
+ * like one call. `"hold"` keeps it up, held (RFC 3264 §8.4) and still owned, so
343
+ * the app can bridge it to somebody else — the supervisor / attended-hand-off
344
+ * case. A closed set: the server refuses anything else with
345
+ * `code === "bad_request"` rather than guessing at a teardown policy.
346
+ */
347
+ type PeerHangupPolicy = "hangup" | "hold";
348
+ /**
349
+ * Which side of a bridge a leg is — the `role` of a
350
+ * {@link ChannelBridgedPayload}. The `anchor` is the channel the `bridge` was
351
+ * addressed to and keeps its media session; the `peer` is the one named by
352
+ * `with`, whose own media session was deleted when it joined. Unknown tokens
353
+ * pass through verbatim (forward-compatible).
354
+ */
355
+ type BridgeRole = "anchor" | "peer" | (string & {});
356
+ /**
357
+ * Which of a bridge's two re-INVITEs was refused — the `stage` of a
358
+ * {@link BridgeFailedPayload}. `offering_peer` means the `with` leg refused the
359
+ * anchor's media and the anchor was never touched; `offering_anchor` means the
360
+ * peer answered but the anchor refused what it was re-offered. Unknown tokens
361
+ * pass through verbatim (forward-compatible).
362
+ */
363
+ type BridgeStage = "offering_peer" | "offering_anchor" | (string & {});
364
+ /**
365
+ * The `payload` of a `ChannelBridged` event — the bridge formed and the two
366
+ * parties can hear each other.
367
+ *
368
+ * A bridge is two RFC 3261 §14 re-INVITEs across two dialogs, so the `bridge`
369
+ * command reply reports only the local action (the media re-pointed, the first
370
+ * re-INVITE on the wire) and this event is the outcome. It is pushed on **both**
371
+ * bridged channels, each copy naming the other leg. Cast a
372
+ * {@link import("./sip").CallEvent}'s `payload` to this when
373
+ * `kind === "ChannelBridged"`.
374
+ */
375
+ interface ChannelBridgedPayload {
376
+ /** The internal `CallActor` id of the leg on the other side. */
377
+ peer_call_id: string;
378
+ /** That leg's SIP `Call-ID` — the CDR / HEP join key for the other party. */
379
+ peer_sip_call_id: string;
380
+ /** Which side *this* channel is. */
381
+ role: BridgeRole;
382
+ /** Whether the bridged pair lives on the media engine (the anchor's session). */
383
+ anchored: boolean;
384
+ }
385
+ /**
386
+ * The `payload` of a `BridgeFailed` event — one of the bridge's two re-INVITEs
387
+ * was refused and both legs were left exactly as they were. Never a teardown:
388
+ * the app still owns both calls and can retry, bridge elsewhere, or hang up.
389
+ */
390
+ interface BridgeFailedPayload {
391
+ /** Which re-INVITE was refused. */
392
+ stage: BridgeStage;
393
+ /** The SIP status the refusing leg answered with (`488`, `491`, `500`, …). */
394
+ code?: number | null;
395
+ /** The SIP `Call-ID` of the other leg in the attempt. */
396
+ peer_sip_call_id?: string | null;
397
+ }
398
+ /**
399
+ * The `payload` of a `ChannelUnbridged` event — the bridge was broken. Both legs
400
+ * stay answered, owned and held (RFC 3264 §8.4 `a=sendonly`); neither is hung
401
+ * up, because that would be indistinguishable from two hangups. Pushed on both
402
+ * channels.
403
+ */
404
+ interface ChannelUnbridgedPayload {
405
+ /** The internal `CallActor` id of the leg that was on the other side. */
406
+ peer_call_id: string;
407
+ /** That leg's SIP `Call-ID`. */
408
+ peer_sip_call_id: string;
409
+ /** The reason the `unbridge` carried (default `"unbridged"`). */
410
+ reason: string;
411
+ }
412
+ /**
413
+ * The `payload` of a `PlayFinished` event — a playback ended.
414
+ *
415
+ * `completed` is the field to branch on: a stop, a supersede and an error all
416
+ * end a playback without the prompt having been heard in full, and the accept's
417
+ * estimated duration says nothing about which happened.
418
+ */
419
+ interface PlayFinishedPayload {
420
+ from_tag: string;
421
+ to_tag?: string | null;
422
+ /** Correlates with the `play` accept and the `PlayStarted` event. */
423
+ play_id: number;
424
+ /** `completed`, `stopped`, `superseded` or `error`. */
425
+ reason: string;
426
+ /** Whether the prompt drained naturally — the only reason it was heard in full. */
427
+ completed: boolean;
428
+ played_ms?: number | null;
429
+ }
430
+ /**
431
+ * The `payload` of a `WsTeeStarted` event — a WebSocket audio **tee** began
432
+ * streaming a copy of the channel's audio. Additive: the call relays on
433
+ * regardless, so a tee never affects the parties.
434
+ *
435
+ * `streamId` correlates this event with the `start` frame on the socket, and
436
+ * the wire shape is stated so a consumer decodes the binary frames without
437
+ * guessing.
438
+ */
439
+ interface WsTeeStartedPayload {
440
+ from_tag: string;
441
+ stream_id: string;
442
+ ws_uri: string;
443
+ /** `both`, `caller` or `callee`. */
444
+ direction: string;
445
+ /** 1 = mono/mixed, 2 = caller/callee interleaved. */
446
+ channels: number;
447
+ /** Wire sample rate in Hz (L16, little-endian). */
448
+ sample_rate: number;
449
+ }
450
+ /**
451
+ * The `payload` of a `WsTeeEnded` event. Exactly one arrives per
452
+ * `WsTeeStarted`, including when the *server* ends it, so a consumer learns
453
+ * the stream died rather than silently losing the audio.
454
+ *
455
+ * `frames_dropped > 0` means the consumer could not keep up; the call itself
456
+ * was never affected.
457
+ */
458
+ interface WsTeeEndedPayload {
459
+ from_tag: string;
460
+ stream_id: string;
461
+ /** `detached`, `server_closed`, `server_stopped`, `call_ended` or `transport_error`. */
462
+ reason: string;
463
+ /** `detached` is the only orderly end; anything else stopped the audio mid-call. */
464
+ unexpected: boolean;
465
+ frames_sent?: number | null;
466
+ frames_dropped?: number | null;
467
+ }
468
+ /**
469
+ * The `payload` of a `WsBridgeStarted` event — a WebSocket **takeover** bridge
470
+ * began. Unlike a tee this *replaced* the call's audio path: the WebSocket
471
+ * server is now the leg's far side and A-to-B is unwired.
472
+ */
473
+ interface WsBridgeStartedPayload {
474
+ from_tag: string;
475
+ stream_id: string;
476
+ ws_uri: string;
477
+ /** Wire sample rate in Hz (L16, little-endian). */
478
+ sample_rate: number;
479
+ }
480
+ /**
481
+ * The `payload` of a `WsBridgeEnded` event. Exactly one per
482
+ * `WsBridgeStarted`; a re-point arrives as an ended (reason `detached`)
483
+ * followed by a fresh started.
484
+ *
485
+ * `unexpected` matters more here than on a tee: a bridge *is* the call's media
486
+ * path, so anything but `detached` leaves both parties up and hearing nothing.
487
+ */
488
+ interface WsBridgeEndedPayload {
489
+ from_tag: string;
490
+ stream_id: string;
491
+ /** `detached`, `server_closed`, `server_stopped`, `call_ended` or `transport_error`. */
492
+ reason: string;
493
+ unexpected: boolean;
494
+ }
495
+ /**
496
+ * Whether an event name ends a bridge this app asked for. Exactly one such event
497
+ * arrives per `bridge`, so this is the signal to stop waiting. `ChannelUnbridged`
498
+ * is not one of them — it ends a bridge that already formed.
499
+ */
500
+ declare function isBridgeFinal(name: string): boolean;
235
501
 
236
502
  /** Small internal utilities shared by the client, server, and SIP facade. */
237
503
  /**
@@ -428,9 +694,15 @@ declare class ControlServer {
428
694
 
429
695
  /** One event delivered to a call's stream (`ChannelStateChange`,
430
696
  * `ChannelHangupRequest`, `ChannelDtmfReceived`, `TransferRequested`,
431
- * `StasisEnd`, …). Cast `payload` to
697
+ * `TransferProgress`, `TransferCompleted`, `TransferFailed`, `ChannelBridged`,
698
+ * `BridgeFailed`, `ChannelUnbridged`, `StasisEnd`, …).
699
+ * Cast `payload` to
432
700
  * {@link import("./protocol").ChannelDtmfPayload} /
433
- * {@link import("./protocol").TransferRequestedPayload} by `kind`. */
701
+ * {@link import("./protocol").TransferRequestedPayload} /
702
+ * {@link import("./protocol").TransferOutcomePayload} /
703
+ * {@link import("./protocol").ChannelBridgedPayload} /
704
+ * {@link import("./protocol").BridgeFailedPayload} /
705
+ * {@link import("./protocol").ChannelUnbridgedPayload} by `kind`. */
434
706
  interface CallEvent {
435
707
  /** The parsed event kind. */
436
708
  kind: SipEventKind;
@@ -446,6 +718,20 @@ interface ResponseOptions {
446
718
  body?: string;
447
719
  contentType?: string;
448
720
  }
721
+ /** Options for an anchored answer ({@link Call.answerAnchored}). */
722
+ interface AnchoredAnswerOptions {
723
+ /** UAS 2xx code (default `200`). */
724
+ code?: number;
725
+ /** Reason phrase (default `OK`). */
726
+ reason?: string;
727
+ /** Media profile to anchor with (default `voice_ai`). */
728
+ profile?: string;
729
+ /**
730
+ * Per-call WebSocket bridge URI, overriding the profile's own. Supports
731
+ * `{call_id}` / `{from_tag}` / `{from_user}` / `{to_user}` templating.
732
+ */
733
+ wsUri?: string;
734
+ }
449
735
  /** The RFC 3891 `Replaces` triple for an attended transfer. */
450
736
  interface ReferReplaces {
451
737
  callId: string;
@@ -458,6 +744,32 @@ interface AcceptReferOptions {
458
744
  target?: string;
459
745
  nextHop?: string;
460
746
  mode?: "terminate" | "transparent";
747
+ /**
748
+ * Media profile for the pairing the transfer creates.
749
+ *
750
+ * **Required when the call is anchored with a direction-bound profile** — one
751
+ * whose offer and answer halves describe different sides, such as
752
+ * `srtp_to_rtp` at an SRTP edge. A transfer moves the party that half was
753
+ * written for out of the call, so inheriting the profile re-offers *that
754
+ * party's* transport to whoever remains: SRTP toward a plain-RTP carrier,
755
+ * which answers `m=audio 0`. The call connects and carries no audio in either
756
+ * direction while the SIP trace looks healthy.
757
+ *
758
+ * Pass the profile for the pair that remains (commonly `"rtp_passthrough"`).
759
+ * Omitted inherits the call's profile, which is correct only when it is
760
+ * symmetric.
761
+ */
762
+ profile?: string;
763
+ }
764
+ /** Options for {@link Call.bridge}. */
765
+ interface BridgeOptions {
766
+ /**
767
+ * What happens to the surviving leg when its bridge partner hangs up —
768
+ * `"hangup"` (the default) tears it down too, `"hold"` keeps it up, held and
769
+ * still owned so it can be bridged to somebody else. See
770
+ * {@link import("./protocol").PeerHangupPolicy}.
771
+ */
772
+ onPeerHangup?: PeerHangupPolicy;
461
773
  }
462
774
  /** A {@link Call.route} target carrying per-target overrides. */
463
775
  interface RouteTargetObject {
@@ -553,7 +865,40 @@ declare class Call {
553
865
  private substrate;
554
866
  /** Send a UAS 2xx to the parked A-leg (default `200 OK`). */
555
867
  answer(options?: ResponseOptions): Promise<void>;
556
- /** Send a UAS 1xx / early media (default `183 Session Progress`). */
868
+ /**
869
+ * Answer the parked A-leg **and** anchor its media to the media engine in one
870
+ * act — the verb form of the routing script's
871
+ * `call.handover(answer=True, profile=…, ws_uri=…)`.
872
+ *
873
+ * This is how an application that accepted an **un-answered** handover
874
+ * connects the call. It can already hold the call open for as long as its own
875
+ * policy says with {@link Call.ring}; what it could not do is connect the
876
+ * caller to anything, because a plain {@link Call.answer} sends a 2xx and
877
+ * anchors nothing. Answering first and attaching a stream afterwards is not
878
+ * the same thing: `received_from`, echo cancellation and the VAD engine are
879
+ * properties of the answer, not of a bridge attached after it.
880
+ *
881
+ * Synthesizing the RFC 3264 answer against the media engine is a siphon-rtp
882
+ * capability, so on rtpengine / rtpproxy this rejects with
883
+ * `code === "unavailable"` rather than sending a 200 with nothing behind it.
884
+ * On any media failure the 2xx is never sent and the call stays parked —
885
+ * retry with another profile, or reject it.
886
+ */
887
+ answerAnchored(options?: AnchoredAnswerOptions): Promise<void>;
888
+ /**
889
+ * Send `180 Ringing`: alerting only, no early media.
890
+ *
891
+ * RFC 3261 §13.2.1 makes the 180 the "callee is being alerted" signal, and
892
+ * RFC 3960 §3.1 puts early media on a response that carries SDP — two
893
+ * different acts, so two verbs. Ring for as long as your own policy says,
894
+ * then {@link Call.answer}; open an early-media path with
895
+ * {@link Call.progress}.
896
+ */
897
+ ring(reason?: string): Promise<void>;
898
+ /**
899
+ * Send a UAS 1xx, optionally opening an early-media path with SDP (default
900
+ * `183 Session Progress`). For plain alerting use {@link Call.ring}.
901
+ */
557
902
  progress(options?: ResponseOptions): Promise<void>;
558
903
  /** Send a final non-2xx and tear the call down. */
559
904
  reject(code: number, reason?: string): Promise<void>;
@@ -564,7 +909,17 @@ declare class Call {
564
909
  terminate(reason?: string): Promise<void>;
565
910
  /** Alias for {@link Call.terminate}. */
566
911
  hangup(reason?: string): Promise<void>;
567
- /** Send an in-dialog REFER on the A-leg (blind transfer). */
912
+ /**
913
+ * Send an in-dialog REFER on the A-leg (blind transfer).
914
+ *
915
+ * Resolves as soon as siphon has sent the REFER — that is *sent*, not
916
+ * *transferred*. RFC 3515 §2.4.4 delivers the outcome afterwards on the
917
+ * implicit subscription, so read it off {@link Call.events}: zero or more
918
+ * `TransferProgress`, then exactly one `TransferCompleted` /
919
+ * `TransferFailed`, each carrying a
920
+ * {@link import("./protocol").TransferOutcomePayload}. Use
921
+ * {@link import("./protocol").isTransferFinal} to know when to stop waiting.
922
+ */
568
923
  refer(to: string): Promise<void>;
569
924
  /** Blind-transfer alias for {@link Call.refer}. */
570
925
  transfer(to: string): Promise<void>;
@@ -592,6 +947,9 @@ declare class Call {
592
947
  * egress, and `mode` (`"terminate"` / `"transparent"`) overrides
593
948
  * `b2bua.default_refer_mode`. No pending REFER (already decided, timed out, or
594
949
  * the call is gone) rejects with `code === "not_found"`.
950
+ *
951
+ * `profile` names the media profile for the pairing the transfer creates —
952
+ * see {@link AcceptReferOptions.profile}, which is required at an SRTP edge.
595
953
  */
596
954
  acceptRefer(options?: AcceptReferOptions): Promise<void>;
597
955
  /**
@@ -599,6 +957,93 @@ declare class Call {
599
957
  * `603 Decline`). No pending REFER rejects with `code === "not_found"`.
600
958
  */
601
959
  rejectRefer(code: number, reason?: string): Promise<void>;
960
+ /**
961
+ * Join this call to another leg the app owns, so the two parties hear each
962
+ * other.
963
+ *
964
+ * **This call is the anchor.** It keeps its media session — its ports and
965
+ * everything attached to them; the `withChannel` leg's own media session is
966
+ * deleted and it becomes the second party on this one's. So bridge *into* the
967
+ * leg whose media you want to keep (the one being recorded, teed, or carrying
968
+ * the prompt).
969
+ *
970
+ * Both legs must already be answered. `options.onPeerHangup` says what happens
971
+ * to the survivor when its partner hangs up (see
972
+ * {@link import("./protocol").PeerHangupPolicy}); omitted means `"hangup"`.
973
+ *
974
+ * Resolves as soon as the media has been re-pointed and the first re-INVITE is
975
+ * on the wire — that is *offered*, not *bridged*. A bridge is two RFC 3261 §14
976
+ * re-INVITEs across two dialogs, so the outcome arrives on {@link Call.events}
977
+ * instead: exactly one `ChannelBridged`
978
+ * ({@link import("./protocol").ChannelBridgedPayload}) / `BridgeFailed`
979
+ * ({@link import("./protocol").BridgeFailedPayload}), on **both** channels.
980
+ * {@link import("./protocol").isBridgeFinal} says when to stop waiting.
981
+ *
982
+ * Resolves to the reply `result` (`{channel, with, call_id, peer_call_id,
983
+ * anchored, on_peer_hangup, state: "bridging"}`). Rejects with a `code` a
984
+ * caller can act on: `"not_found"` (no such leg), `"invalid_state"` (a leg has
985
+ * not answered, is already bridged, has a re-INVITE outstanding, or carries no
986
+ * media description), `"bad_request"` (the same leg named twice, or a bad
987
+ * `onPeerHangup`), `"forbidden"` (the other channel belongs to another app),
988
+ * `"unsupported_verb"` (the media backend cannot express it).
989
+ */
990
+ bridge(withChannel: string, options?: BridgeOptions): Promise<unknown>;
991
+ /**
992
+ * Break this call's bridge.
993
+ *
994
+ * Both legs stay answered, owned and held — re-offered `a=sendonly`
995
+ * (RFC 3264 §8.4, which RFC 6337 §3.1 prefers to `c=0.0.0.0`). Neither is hung
996
+ * up: that would be indistinguishable from two hangups and would take away the
997
+ * calls the app still owns. A later {@link Call.bridge} re-offers `sendrecv`.
998
+ *
999
+ * `reason` is free text carried on the `ChannelUnbridged`
1000
+ * ({@link import("./protocol").ChannelUnbridgedPayload}) event both channels
1001
+ * receive; omitted means `"unbridged"`. Resolves to the reply `result`
1002
+ * (`{channel, with, reason, state: "unbridged"}`), where `with` is the channel
1003
+ * id of the leg that was on the other side. A call that is not bridged rejects
1004
+ * with `code === "invalid_state"`.
1005
+ */
1006
+ unbridge(reason?: string): Promise<unknown>;
1007
+ /**
1008
+ * Replace one leg of this answered call with a freshly dialed target, with no
1009
+ * REFER involved.
1010
+ *
1011
+ * The transfer siphon already runs for a REFER it terminates, reachable
1012
+ * because *this app* decided: an IVR that has worked out where the caller
1013
+ * should go, a controller handing a call from an AI to a human, a supervisor
1014
+ * take-over. siphon dials `target` as a new leg on the same call, re-anchors
1015
+ * the surviving party's media onto it, and once the target answers promotes
1016
+ * it into the surviving pair and BYEs the leg it replaced.
1017
+ *
1018
+ * The replaced leg **stays up while the target rings**, so the surviving
1019
+ * party hears ringback rather than silence, and a target that refuses or
1020
+ * never answers leaves the call exactly as it was.
1021
+ *
1022
+ * `replaceALeg` picks the direction: omitted/`false` replaces the callee and
1023
+ * keeps the caller, `true` does the reverse. `profile` names the media
1024
+ * profile for the pair this creates — required when the call is anchored with
1025
+ * a direction-bound one, whose answer half describes the party that is
1026
+ * leaving. `timeout` bounds the ring in seconds (`0` = no ring policy, only
1027
+ * siphon's guard against a target that answers nothing).
1028
+ *
1029
+ * Resolves as soon as the INVITE is on the wire
1030
+ * (`{channel, replacement: "dialing", target}`) and says nothing about the
1031
+ * target. Wait for the `PeerReplaced`
1032
+ * ({@link import("./protocol").PeerReplacedPayload}) or `ReplaceFailed`
1033
+ * ({@link import("./protocol").ReplaceFailedPayload}) event for the outcome —
1034
+ * acting on the reply alone would tear down a call whose replacement is still
1035
+ * ringing.
1036
+ *
1037
+ * Rejects with `code === "not_found"` (no such call), `"invalid_state"` (not
1038
+ * answered, no peer leg, or a replacement already in flight — all worth
1039
+ * retrying later) or `"bad_request"` (the target will not parse or route).
1040
+ */
1041
+ replacePeer(target: string, options?: {
1042
+ nextHop?: string;
1043
+ replaceALeg?: boolean;
1044
+ profile?: string;
1045
+ timeout?: number;
1046
+ }): Promise<unknown>;
602
1047
  /** Set a header on the stored A-leg INVITE. */
603
1048
  setHeader(name: string, value: string): Promise<void>;
604
1049
  /** Read a header from the stored A-leg INVITE (`null` when absent). */
@@ -641,7 +1086,8 @@ declare class Call {
641
1086
  command(verb: string, args?: unknown): Promise<unknown>;
642
1087
  /**
643
1088
  * Await the next event for this call (`ChannelStateChange`,
644
- * `ChannelHangupRequest`, `StasisEnd`). `null` once the stream closes.
1089
+ * `ChannelHangupRequest`, `ChannelBridged`, `BridgeFailed`,
1090
+ * `ChannelUnbridged`, `StasisEnd`). `null` once the stream closes.
645
1091
  */
646
1092
  nextEvent(): Promise<CallEvent | null>;
647
1093
  /** Async-iterate this call's events until the stream closes. */
@@ -721,4 +1167,4 @@ declare class SipServer {
721
1167
  close(): Promise<void>;
722
1168
  }
723
1169
 
724
- export { type AcceptReferOptions, Call, type CallEvent, type CallHandler, CallStream, type ChannelDtmfPayload, type ChannelSnapshot, 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 PlayOptions, type PlaySource, 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 TransferReplaces, type TransferRequestedPayload, encodeCommand, parseInboundFrame, sipEventKind };
1170
+ export { type AcceptReferOptions, type AnchoredAnswerOptions, 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, transferOutcome };