@siphon-project/control 0.2.0 → 0.4.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.cts CHANGED
@@ -182,6 +182,11 @@ declare const SipVerb: {
182
182
  readonly Hangup: "hangup";
183
183
  readonly Refer: "refer";
184
184
  readonly Route: "route";
185
+ /**
186
+ * Ring targets as B-legs while the caller stays unanswered and the app keeps
187
+ * the channel. Channel-addressed, unlike `originate`, which creates one.
188
+ */
189
+ readonly Dial: "dial";
185
190
  readonly SetHeader: "set_header";
186
191
  readonly GetHeader: "get_header";
187
192
  readonly RemoveHeader: "remove_header";
@@ -197,6 +202,10 @@ declare const SipVerb: {
197
202
  readonly Unhold: "unhold";
198
203
  readonly StreamStart: "stream_start";
199
204
  readonly StreamStop: "stream_stop";
205
+ /** Record the call's decoded audio to a wav file (siphon-rtp backend only). */
206
+ readonly RecordStart: "record_start";
207
+ /** Stop one recording by id, or every recording on the call. */
208
+ readonly RecordStop: "record_stop";
200
209
  };
201
210
  /** A value of {@link SipVerb}. */
202
211
  type SipVerbToken = (typeof SipVerb)[keyof typeof SipVerb];
@@ -779,8 +788,19 @@ interface RouteTargetObject {
779
788
  nextHop?: string;
780
789
  /** Headers injected on this attempt's B-leg INVITE. */
781
790
  headers?: Record<string, string>;
782
- /** Per-target ring timeout in seconds. */
791
+ /**
792
+ * Per-target ring timeout in seconds. It bounds the wait for this carrier to
793
+ * show progress (a 101-199), not the wait for its answer.
794
+ */
783
795
  timeout?: number;
796
+ /**
797
+ * Fail this carrier over at its ring timeout even after it has shown
798
+ * progress. By default a carrier that has sent a 180/183 keeps the call past
799
+ * `timeout`, and the call then fails with 408 rather than trying the next
800
+ * target; `true` is for a carrier that plays its own ringback before it has
801
+ * reached anyone. Default `false`, which is never sent.
802
+ */
803
+ rerouteAfterProgress?: boolean;
784
804
  }
785
805
  /**
786
806
  * One entry in a {@link Call.route} target list: a bare URI string, or a
@@ -792,6 +812,180 @@ type RouteTarget = string | RouteTargetObject;
792
812
  * path, an rtpengine media-DB id, or an inline blob. A blob is base64-encoded on
793
813
  * the wire (the control rail is JSON text).
794
814
  */
815
+ /**
816
+ * The media plan for {@link SipClient.originate} — what the outbound INVITE
817
+ * offers.
818
+ *
819
+ * Required, and a union, because the server requires exactly one plan and
820
+ * rejects every combination of the raw `sdp` / `body` / `media` arguments that
821
+ * names none or more than one. Expressed this way those errors cannot be
822
+ * written down.
823
+ */
824
+ type OriginateMedia =
825
+ /** Offerless INVITE: siphon anchors the leg on the media engine. */
826
+ {
827
+ anchor: true;
828
+ profile?: string;
829
+ wsUri?: string;
830
+ }
831
+ /** Your own SDP offer (`application/sdp` by definition). */
832
+ | {
833
+ sdp: string;
834
+ }
835
+ /** Your own body with its own content type. */
836
+ | {
837
+ body: string;
838
+ contentType: string;
839
+ };
840
+ /**
841
+ * Who refreshes each dialog of an originated call where the RFC 4028 negotiation
842
+ * leaves siphon the choice (§7.1): the UAC of each dialog, the UAS of each, or
843
+ * siphon on both.
844
+ */
845
+ type SessionRefresher = "uac" | "uas" | "b2bua";
846
+ /**
847
+ * The RFC 4028 session timer siphon runs on an originated call, over its
848
+ * `session_timer:` block. A field left out takes the server's default, as in the
849
+ * script API's `call.session_timer()`: 1800 s, a `Min-SE` of 90 s, and `b2bua`.
850
+ */
851
+ interface SessionTimer {
852
+ /** The session interval, in seconds. */
853
+ expires?: number;
854
+ /** The smallest session interval siphon accepts, in seconds. */
855
+ minSe?: number;
856
+ /** Who refreshes where the negotiation leaves siphon the choice. */
857
+ refresher?: SessionRefresher;
858
+ }
859
+ /** Optional shaping for {@link SipClient.originate}. */
860
+ interface OriginateOptions {
861
+ /** From-URI to place the call as. */
862
+ from?: string;
863
+ /** From display name. */
864
+ fromDisplay?: string;
865
+ /** To display name. */
866
+ toDisplay?: string;
867
+ /** Route the INVITE here while keeping `to` as the R-URI. */
868
+ nextHop?: string;
869
+ /** P-Asserted-Identity to assert (RFC 3325). */
870
+ pAssertedIdentity?: string;
871
+ /** Caller-identity presentation (RFC 3323 §4.1). */
872
+ privacy?: "allowed" | "restricted";
873
+ /** Extra headers on the outbound INVITE. */
874
+ headers?: Record<string, string>;
875
+ /** Ring timeout in seconds. */
876
+ timeout?: number;
877
+ /** Control-loss policy for the created channel. */
878
+ onLost?: string;
879
+ /** Per-call variables carried on the channel. */
880
+ vars?: Record<string, string>;
881
+ /**
882
+ * The RFC 4028 session timer to run on the call; left out, the one the server
883
+ * has configured runs, if any.
884
+ */
885
+ sessionTimer?: SessionTimer;
886
+ }
887
+ /**
888
+ * What the server answers an accepted `originate` with: the call is `calling`,
889
+ * not answered — the answer arrives later as an event on the channel.
890
+ */
891
+ interface Originated {
892
+ /** The caller-supplied channel id the call is addressed by. */
893
+ channel: string;
894
+ /** siphon's internal call id. */
895
+ callId?: string;
896
+ /** The SIP Call-ID on the wire, for joining CDR / HEP. */
897
+ sipCallId?: string;
898
+ }
899
+ declare function originateArgs(channel: string, to: string, media: OriginateMedia, options?: OriginateOptions): Record<string, unknown>;
900
+ /**
901
+ * One {@link Call.dial} target: a URI dialed as written, or an AoR forked to
902
+ * every contact registered against it.
903
+ *
904
+ * Two shapes rather than a bare string, because the server accepts both and they
905
+ * do entirely different things. A URI is dialed as written and resolved by DNS.
906
+ * An AoR is resolved against the registrar and forked to *every* registered
907
+ * contact, each branch over that contact's own captured flow — the only way to
908
+ * reach a phone registered over TCP, TLS or WSS behind NAT, since such a contact
909
+ * is reachable only on the connection it registered over.
910
+ * `"sip:204@pbx.example"` is a plausible spelling of both, and the wrong one
911
+ * places a call that connects to nothing while the trace looks healthy.
912
+ */
913
+ type DialTarget = {
914
+ /** The B-leg request URI, dialed as written. */
915
+ uri: string;
916
+ /** Send the INVITE here instead; the R-URI keeps `uri`'s shape. */
917
+ nextHop?: string;
918
+ /** Headers injected on this branch's INVITE, over the command's. */
919
+ headers?: Record<string, string>;
920
+ } | {
921
+ /**
922
+ * The address of record to fork to its registered contacts. It takes no
923
+ * `nextHop`: each branch routes over its own binding's captured flow, so
924
+ * there would be nothing for one to apply to.
925
+ */
926
+ aor: string;
927
+ /** Headers injected on every branch the AoR expands to. */
928
+ headers?: Record<string, string>;
929
+ };
930
+ /**
931
+ * Optional shaping for {@link Call.dial}; anything left out takes the server's
932
+ * own default rather than a copy of it pinned here.
933
+ */
934
+ interface DialOptions {
935
+ /** How to try the targets (`"parallel"` server-side when unset). */
936
+ strategy?: "parallel" | "sequential";
937
+ /** Ring timeout in seconds (30 server-side when unset, clamped to 1..3600). */
938
+ timeout?: number;
939
+ /** Headers injected on every branch's INVITE, under each target's own. */
940
+ headers?: Record<string, string>;
941
+ }
942
+ /**
943
+ * What the server answers an accepted `dial` with: the INVITEs are on the wire
944
+ * and nobody has answered yet.
945
+ */
946
+ interface Dialing {
947
+ /** The channel the targets are being rung for — still the caller's. */
948
+ channel: string;
949
+ /**
950
+ * How many **branches** the server resolved, which an AoR expands: a single
951
+ * AoR target registered on three devices reports three.
952
+ */
953
+ targets?: number;
954
+ /** The strategy in force (the server's default when none was asked for). */
955
+ strategy?: string;
956
+ /** The ring timeout in force, in seconds. */
957
+ timeout?: number;
958
+ }
959
+ /** Which side of the call {@link Call.recordStart} writes. */
960
+ type RecordDirection = "ingress" | "egress" | "both";
961
+ /** The channel layout of the recorded file. */
962
+ type RecordChannels = "mono" | "stereo";
963
+ /** Optional shaping for {@link Call.recordStart}. */
964
+ interface RecordOptions {
965
+ /** Which side to record (`"ingress"` server-side when unset). */
966
+ direction?: RecordDirection;
967
+ /** The file's channel layout (`"mono"` server-side when unset). */
968
+ channels?: RecordChannels;
969
+ /** Stop after this many milliseconds of recording. */
970
+ maxDurationMs?: number;
971
+ /** Stop after this many milliseconds of silence. */
972
+ silenceMs?: number;
973
+ /** Where the engine writes the file. */
974
+ path?: string;
975
+ }
976
+ /** What the server answers an accepted `record_start` with. */
977
+ interface Recording {
978
+ /** The channel being recorded. */
979
+ channel: string;
980
+ /**
981
+ * The id a later {@link Call.recordStop} and the `RecordingFinished` event
982
+ * carry.
983
+ */
984
+ recordingId?: string;
985
+ }
986
+ declare function dialArgs(targets: DialTarget[], options?: DialOptions): Record<string, unknown>;
987
+ declare function recordStartArgs(options?: RecordOptions): Record<string, unknown>;
988
+ declare function recordStopArgs(recordingId?: string): Record<string, unknown>;
795
989
  type PlaySource = {
796
990
  file: string;
797
991
  } | {
@@ -931,7 +1125,9 @@ declare class Call {
931
1125
  *
932
1126
  * `targets` is a non-empty list of carriers tried cheapest-first: each entry
933
1127
  * is a bare URI string or a {@link RouteTargetObject}
934
- * (`{uri, nextHop?, headers?, timeout?}`). `strategy` defaults to
1128
+ * (`{uri, nextHop?, headers?, timeout?, rerouteAfterProgress?}`). A target
1129
+ * that has shown progress keeps the call past its `timeout` unless it sets
1130
+ * `rerouteAfterProgress`. `strategy` defaults to
935
1131
  * `"sequential"` (v1 supports only sequential/single — anything else rejects
936
1132
  * with `code === "unsupported_verb"`). `headers` is applied to every
937
1133
  * attempt's B-leg INVITE.
@@ -941,6 +1137,40 @@ declare class Call {
941
1137
  * that is already gone rejects with `code === "not_found"`.
942
1138
  */
943
1139
  route(targets: RouteTarget[], strategy?: string, headers?: Record<string, string>): Promise<unknown>;
1140
+ /**
1141
+ * Ring `targets` as B-legs while the caller stays **unanswered** and this
1142
+ * application keeps the channel.
1143
+ *
1144
+ * The difference from {@link Call.route} is who holds the call afterwards.
1145
+ * `route` hands it back to siphon, so the app gets `StasisEnd{reason: routed}`
1146
+ * and loses it; there is then no way to say "ring the extension, and if nobody
1147
+ * answers, voicemail" without answering the caller first — which starts
1148
+ * billing before anyone picks up, records an unanswered call as answered, and
1149
+ * denies the caller the callee's own ringback.
1150
+ *
1151
+ * The first 2xx answers the caller with the winner's SDP and the pair becomes
1152
+ * an ordinary two-leg call, still owned by this app. A failure or timeout
1153
+ * arrives as a `DialFailed` event with the caller still ringing and still
1154
+ * parked, so the app decides what happens next.
1155
+ *
1156
+ * Each target is a URI (dialed as written) or an `{aor}` (forked to every
1157
+ * registered contact over its own flow) — see {@link DialTarget}, and note
1158
+ * that a target naming both, or neither, throws before anything is sent.
1159
+ *
1160
+ * ```ts
1161
+ * const dialing = await call.dial(
1162
+ * [{ aor: "sip:204@pbx.example" }],
1163
+ * { strategy: "sequential", timeout: 20 },
1164
+ * );
1165
+ * ```
1166
+ *
1167
+ * Rejects with `code === "not_found"` (the call is gone, or no target yielded
1168
+ * a branch — an AoR nobody has registered), `"invalid_state"` (already
1169
+ * answered, which is what this verb exists to avoid), `"bad_request"` (an
1170
+ * empty or malformed target list) or `"unsupported_verb"` (a strategy siphon
1171
+ * does not implement).
1172
+ */
1173
+ dial(targets: DialTarget[], options?: DialOptions): Promise<Dialing>;
944
1174
  /**
945
1175
  * Accept a *pending inbound* REFER (surfaced as a `TransferRequested` event)
946
1176
  * and run the transfer. `target` overrides the Refer-To URI, `nextHop` steers
@@ -1082,6 +1312,32 @@ declare class Call {
1082
1312
  streamStart(wsUri: string, options?: StreamOptions): Promise<void>;
1083
1313
  /** Detach the WebSocket audio tee (idempotent on siphon-rtp). */
1084
1314
  streamStop(): Promise<void>;
1315
+ /**
1316
+ * Record this call's decoded audio to a wav file.
1317
+ *
1318
+ * The reply names the `recordingId` a later {@link Call.recordStop}
1319
+ * addresses. It is **not** the file: `RecordingFinished` fires when the file
1320
+ * is *closed* and names its path, which is what an app that mails the audio
1321
+ * has to wait for — acting on this reply races a half-written file.
1322
+ *
1323
+ * `maxDurationMs` and `silenceMs` are the two stop conditions a voicemail
1324
+ * greeting announces, and the engine evaluates both where the decoded audio
1325
+ * already is. Not SIPREC: this writes a file and works on a single-leg,
1326
+ * engine-terminated call, which is what a voicemail box is. siphon-rtp
1327
+ * backend only — rtpengine / rtpproxy reject with
1328
+ * `code === "unsupported_verb"`; a call with no anchored media session
1329
+ * rejects with `"not_found"`.
1330
+ */
1331
+ recordStart(options?: RecordOptions): Promise<Recording>;
1332
+ /**
1333
+ * Stop the recording named by `recordingId`, or **every** recording on this
1334
+ * call when it is left out.
1335
+ *
1336
+ * Resolves once the engine has accepted the stop; the file is not closed yet.
1337
+ * `RecordingFinished` says that, and carries the path and the reason
1338
+ * (`stopped`, `max_duration`, `silence`, `call_ended`, `error`).
1339
+ */
1340
+ recordStop(recordingId?: string): Promise<void>;
1085
1341
  /** Send an arbitrary SIP-adapter verb + args and return the raw result. */
1086
1342
  command(verb: string, args?: unknown): Promise<unknown>;
1087
1343
  /**
@@ -1141,6 +1397,24 @@ declare class SipClient {
1141
1397
  run(): Promise<void>;
1142
1398
  /** Fetch the registered adapters' schema (`describe`). */
1143
1399
  describe(): Promise<unknown>;
1400
+ /**
1401
+ * Place an outbound call under a caller-supplied channel id.
1402
+ *
1403
+ * The one verb that *creates* a channel rather than addressing one, which is
1404
+ * why it lives here and not on {@link Call}. It resolves as soon as the
1405
+ * INVITE is on the wire — the call is `calling`, and the answer, failure or
1406
+ * timeout arrives later as an event on the channel.
1407
+ *
1408
+ * ```ts
1409
+ * const call = await client.originate(
1410
+ * "wake-up-42",
1411
+ * "sip:1001@pbx.example",
1412
+ * { anchor: true },
1413
+ * { from: "sip:alarm@pbx.example", timeout: 20 },
1414
+ * );
1415
+ * ```
1416
+ */
1417
+ originate(channel: string, to: string, media: OriginateMedia, options?: OriginateOptions): Promise<Originated>;
1144
1418
  /** Send a raw command on any module (the generic escape hatch). */
1145
1419
  command(module: string | null, verb: string, target: unknown, args: unknown): Promise<unknown>;
1146
1420
  /** Stop the client. */
@@ -1167,4 +1441,4 @@ declare class SipServer {
1167
1441
  close(): Promise<void>;
1168
1442
  }
1169
1443
 
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 };
1444
+ 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 DialOptions, type DialTarget, type Dialing, type DtmfOptions, type EventFrame, type EventSink, EventStream, type FrameType, GET_VAR, HELLO, type HelloArgs, type HelloResult, MODULE_SIP, MODULE_SMPP, MODULE_SS7, type OriginateMedia, type OriginateOptions, type Originated, 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 StreamOptions, type TransferOutcomePayload, type TransferReplaces, type TransferRequestedPayload, type TransferStage, type WsBridgeEndedPayload, type WsBridgeStartedPayload, type WsTeeEndedPayload, type WsTeeStartedPayload, dialArgs, encodeCommand, isBridgeFinal, isTransferFinal, originateArgs, parseInboundFrame, recordStartArgs, recordStopArgs, sipEventKind, transferOutcome };
package/dist/index.d.ts CHANGED
@@ -182,6 +182,11 @@ declare const SipVerb: {
182
182
  readonly Hangup: "hangup";
183
183
  readonly Refer: "refer";
184
184
  readonly Route: "route";
185
+ /**
186
+ * Ring targets as B-legs while the caller stays unanswered and the app keeps
187
+ * the channel. Channel-addressed, unlike `originate`, which creates one.
188
+ */
189
+ readonly Dial: "dial";
185
190
  readonly SetHeader: "set_header";
186
191
  readonly GetHeader: "get_header";
187
192
  readonly RemoveHeader: "remove_header";
@@ -197,6 +202,10 @@ declare const SipVerb: {
197
202
  readonly Unhold: "unhold";
198
203
  readonly StreamStart: "stream_start";
199
204
  readonly StreamStop: "stream_stop";
205
+ /** Record the call's decoded audio to a wav file (siphon-rtp backend only). */
206
+ readonly RecordStart: "record_start";
207
+ /** Stop one recording by id, or every recording on the call. */
208
+ readonly RecordStop: "record_stop";
200
209
  };
201
210
  /** A value of {@link SipVerb}. */
202
211
  type SipVerbToken = (typeof SipVerb)[keyof typeof SipVerb];
@@ -779,8 +788,19 @@ interface RouteTargetObject {
779
788
  nextHop?: string;
780
789
  /** Headers injected on this attempt's B-leg INVITE. */
781
790
  headers?: Record<string, string>;
782
- /** Per-target ring timeout in seconds. */
791
+ /**
792
+ * Per-target ring timeout in seconds. It bounds the wait for this carrier to
793
+ * show progress (a 101-199), not the wait for its answer.
794
+ */
783
795
  timeout?: number;
796
+ /**
797
+ * Fail this carrier over at its ring timeout even after it has shown
798
+ * progress. By default a carrier that has sent a 180/183 keeps the call past
799
+ * `timeout`, and the call then fails with 408 rather than trying the next
800
+ * target; `true` is for a carrier that plays its own ringback before it has
801
+ * reached anyone. Default `false`, which is never sent.
802
+ */
803
+ rerouteAfterProgress?: boolean;
784
804
  }
785
805
  /**
786
806
  * One entry in a {@link Call.route} target list: a bare URI string, or a
@@ -792,6 +812,180 @@ type RouteTarget = string | RouteTargetObject;
792
812
  * path, an rtpengine media-DB id, or an inline blob. A blob is base64-encoded on
793
813
  * the wire (the control rail is JSON text).
794
814
  */
815
+ /**
816
+ * The media plan for {@link SipClient.originate} — what the outbound INVITE
817
+ * offers.
818
+ *
819
+ * Required, and a union, because the server requires exactly one plan and
820
+ * rejects every combination of the raw `sdp` / `body` / `media` arguments that
821
+ * names none or more than one. Expressed this way those errors cannot be
822
+ * written down.
823
+ */
824
+ type OriginateMedia =
825
+ /** Offerless INVITE: siphon anchors the leg on the media engine. */
826
+ {
827
+ anchor: true;
828
+ profile?: string;
829
+ wsUri?: string;
830
+ }
831
+ /** Your own SDP offer (`application/sdp` by definition). */
832
+ | {
833
+ sdp: string;
834
+ }
835
+ /** Your own body with its own content type. */
836
+ | {
837
+ body: string;
838
+ contentType: string;
839
+ };
840
+ /**
841
+ * Who refreshes each dialog of an originated call where the RFC 4028 negotiation
842
+ * leaves siphon the choice (§7.1): the UAC of each dialog, the UAS of each, or
843
+ * siphon on both.
844
+ */
845
+ type SessionRefresher = "uac" | "uas" | "b2bua";
846
+ /**
847
+ * The RFC 4028 session timer siphon runs on an originated call, over its
848
+ * `session_timer:` block. A field left out takes the server's default, as in the
849
+ * script API's `call.session_timer()`: 1800 s, a `Min-SE` of 90 s, and `b2bua`.
850
+ */
851
+ interface SessionTimer {
852
+ /** The session interval, in seconds. */
853
+ expires?: number;
854
+ /** The smallest session interval siphon accepts, in seconds. */
855
+ minSe?: number;
856
+ /** Who refreshes where the negotiation leaves siphon the choice. */
857
+ refresher?: SessionRefresher;
858
+ }
859
+ /** Optional shaping for {@link SipClient.originate}. */
860
+ interface OriginateOptions {
861
+ /** From-URI to place the call as. */
862
+ from?: string;
863
+ /** From display name. */
864
+ fromDisplay?: string;
865
+ /** To display name. */
866
+ toDisplay?: string;
867
+ /** Route the INVITE here while keeping `to` as the R-URI. */
868
+ nextHop?: string;
869
+ /** P-Asserted-Identity to assert (RFC 3325). */
870
+ pAssertedIdentity?: string;
871
+ /** Caller-identity presentation (RFC 3323 §4.1). */
872
+ privacy?: "allowed" | "restricted";
873
+ /** Extra headers on the outbound INVITE. */
874
+ headers?: Record<string, string>;
875
+ /** Ring timeout in seconds. */
876
+ timeout?: number;
877
+ /** Control-loss policy for the created channel. */
878
+ onLost?: string;
879
+ /** Per-call variables carried on the channel. */
880
+ vars?: Record<string, string>;
881
+ /**
882
+ * The RFC 4028 session timer to run on the call; left out, the one the server
883
+ * has configured runs, if any.
884
+ */
885
+ sessionTimer?: SessionTimer;
886
+ }
887
+ /**
888
+ * What the server answers an accepted `originate` with: the call is `calling`,
889
+ * not answered — the answer arrives later as an event on the channel.
890
+ */
891
+ interface Originated {
892
+ /** The caller-supplied channel id the call is addressed by. */
893
+ channel: string;
894
+ /** siphon's internal call id. */
895
+ callId?: string;
896
+ /** The SIP Call-ID on the wire, for joining CDR / HEP. */
897
+ sipCallId?: string;
898
+ }
899
+ declare function originateArgs(channel: string, to: string, media: OriginateMedia, options?: OriginateOptions): Record<string, unknown>;
900
+ /**
901
+ * One {@link Call.dial} target: a URI dialed as written, or an AoR forked to
902
+ * every contact registered against it.
903
+ *
904
+ * Two shapes rather than a bare string, because the server accepts both and they
905
+ * do entirely different things. A URI is dialed as written and resolved by DNS.
906
+ * An AoR is resolved against the registrar and forked to *every* registered
907
+ * contact, each branch over that contact's own captured flow — the only way to
908
+ * reach a phone registered over TCP, TLS or WSS behind NAT, since such a contact
909
+ * is reachable only on the connection it registered over.
910
+ * `"sip:204@pbx.example"` is a plausible spelling of both, and the wrong one
911
+ * places a call that connects to nothing while the trace looks healthy.
912
+ */
913
+ type DialTarget = {
914
+ /** The B-leg request URI, dialed as written. */
915
+ uri: string;
916
+ /** Send the INVITE here instead; the R-URI keeps `uri`'s shape. */
917
+ nextHop?: string;
918
+ /** Headers injected on this branch's INVITE, over the command's. */
919
+ headers?: Record<string, string>;
920
+ } | {
921
+ /**
922
+ * The address of record to fork to its registered contacts. It takes no
923
+ * `nextHop`: each branch routes over its own binding's captured flow, so
924
+ * there would be nothing for one to apply to.
925
+ */
926
+ aor: string;
927
+ /** Headers injected on every branch the AoR expands to. */
928
+ headers?: Record<string, string>;
929
+ };
930
+ /**
931
+ * Optional shaping for {@link Call.dial}; anything left out takes the server's
932
+ * own default rather than a copy of it pinned here.
933
+ */
934
+ interface DialOptions {
935
+ /** How to try the targets (`"parallel"` server-side when unset). */
936
+ strategy?: "parallel" | "sequential";
937
+ /** Ring timeout in seconds (30 server-side when unset, clamped to 1..3600). */
938
+ timeout?: number;
939
+ /** Headers injected on every branch's INVITE, under each target's own. */
940
+ headers?: Record<string, string>;
941
+ }
942
+ /**
943
+ * What the server answers an accepted `dial` with: the INVITEs are on the wire
944
+ * and nobody has answered yet.
945
+ */
946
+ interface Dialing {
947
+ /** The channel the targets are being rung for — still the caller's. */
948
+ channel: string;
949
+ /**
950
+ * How many **branches** the server resolved, which an AoR expands: a single
951
+ * AoR target registered on three devices reports three.
952
+ */
953
+ targets?: number;
954
+ /** The strategy in force (the server's default when none was asked for). */
955
+ strategy?: string;
956
+ /** The ring timeout in force, in seconds. */
957
+ timeout?: number;
958
+ }
959
+ /** Which side of the call {@link Call.recordStart} writes. */
960
+ type RecordDirection = "ingress" | "egress" | "both";
961
+ /** The channel layout of the recorded file. */
962
+ type RecordChannels = "mono" | "stereo";
963
+ /** Optional shaping for {@link Call.recordStart}. */
964
+ interface RecordOptions {
965
+ /** Which side to record (`"ingress"` server-side when unset). */
966
+ direction?: RecordDirection;
967
+ /** The file's channel layout (`"mono"` server-side when unset). */
968
+ channels?: RecordChannels;
969
+ /** Stop after this many milliseconds of recording. */
970
+ maxDurationMs?: number;
971
+ /** Stop after this many milliseconds of silence. */
972
+ silenceMs?: number;
973
+ /** Where the engine writes the file. */
974
+ path?: string;
975
+ }
976
+ /** What the server answers an accepted `record_start` with. */
977
+ interface Recording {
978
+ /** The channel being recorded. */
979
+ channel: string;
980
+ /**
981
+ * The id a later {@link Call.recordStop} and the `RecordingFinished` event
982
+ * carry.
983
+ */
984
+ recordingId?: string;
985
+ }
986
+ declare function dialArgs(targets: DialTarget[], options?: DialOptions): Record<string, unknown>;
987
+ declare function recordStartArgs(options?: RecordOptions): Record<string, unknown>;
988
+ declare function recordStopArgs(recordingId?: string): Record<string, unknown>;
795
989
  type PlaySource = {
796
990
  file: string;
797
991
  } | {
@@ -931,7 +1125,9 @@ declare class Call {
931
1125
  *
932
1126
  * `targets` is a non-empty list of carriers tried cheapest-first: each entry
933
1127
  * is a bare URI string or a {@link RouteTargetObject}
934
- * (`{uri, nextHop?, headers?, timeout?}`). `strategy` defaults to
1128
+ * (`{uri, nextHop?, headers?, timeout?, rerouteAfterProgress?}`). A target
1129
+ * that has shown progress keeps the call past its `timeout` unless it sets
1130
+ * `rerouteAfterProgress`. `strategy` defaults to
935
1131
  * `"sequential"` (v1 supports only sequential/single — anything else rejects
936
1132
  * with `code === "unsupported_verb"`). `headers` is applied to every
937
1133
  * attempt's B-leg INVITE.
@@ -941,6 +1137,40 @@ declare class Call {
941
1137
  * that is already gone rejects with `code === "not_found"`.
942
1138
  */
943
1139
  route(targets: RouteTarget[], strategy?: string, headers?: Record<string, string>): Promise<unknown>;
1140
+ /**
1141
+ * Ring `targets` as B-legs while the caller stays **unanswered** and this
1142
+ * application keeps the channel.
1143
+ *
1144
+ * The difference from {@link Call.route} is who holds the call afterwards.
1145
+ * `route` hands it back to siphon, so the app gets `StasisEnd{reason: routed}`
1146
+ * and loses it; there is then no way to say "ring the extension, and if nobody
1147
+ * answers, voicemail" without answering the caller first — which starts
1148
+ * billing before anyone picks up, records an unanswered call as answered, and
1149
+ * denies the caller the callee's own ringback.
1150
+ *
1151
+ * The first 2xx answers the caller with the winner's SDP and the pair becomes
1152
+ * an ordinary two-leg call, still owned by this app. A failure or timeout
1153
+ * arrives as a `DialFailed` event with the caller still ringing and still
1154
+ * parked, so the app decides what happens next.
1155
+ *
1156
+ * Each target is a URI (dialed as written) or an `{aor}` (forked to every
1157
+ * registered contact over its own flow) — see {@link DialTarget}, and note
1158
+ * that a target naming both, or neither, throws before anything is sent.
1159
+ *
1160
+ * ```ts
1161
+ * const dialing = await call.dial(
1162
+ * [{ aor: "sip:204@pbx.example" }],
1163
+ * { strategy: "sequential", timeout: 20 },
1164
+ * );
1165
+ * ```
1166
+ *
1167
+ * Rejects with `code === "not_found"` (the call is gone, or no target yielded
1168
+ * a branch — an AoR nobody has registered), `"invalid_state"` (already
1169
+ * answered, which is what this verb exists to avoid), `"bad_request"` (an
1170
+ * empty or malformed target list) or `"unsupported_verb"` (a strategy siphon
1171
+ * does not implement).
1172
+ */
1173
+ dial(targets: DialTarget[], options?: DialOptions): Promise<Dialing>;
944
1174
  /**
945
1175
  * Accept a *pending inbound* REFER (surfaced as a `TransferRequested` event)
946
1176
  * and run the transfer. `target` overrides the Refer-To URI, `nextHop` steers
@@ -1082,6 +1312,32 @@ declare class Call {
1082
1312
  streamStart(wsUri: string, options?: StreamOptions): Promise<void>;
1083
1313
  /** Detach the WebSocket audio tee (idempotent on siphon-rtp). */
1084
1314
  streamStop(): Promise<void>;
1315
+ /**
1316
+ * Record this call's decoded audio to a wav file.
1317
+ *
1318
+ * The reply names the `recordingId` a later {@link Call.recordStop}
1319
+ * addresses. It is **not** the file: `RecordingFinished` fires when the file
1320
+ * is *closed* and names its path, which is what an app that mails the audio
1321
+ * has to wait for — acting on this reply races a half-written file.
1322
+ *
1323
+ * `maxDurationMs` and `silenceMs` are the two stop conditions a voicemail
1324
+ * greeting announces, and the engine evaluates both where the decoded audio
1325
+ * already is. Not SIPREC: this writes a file and works on a single-leg,
1326
+ * engine-terminated call, which is what a voicemail box is. siphon-rtp
1327
+ * backend only — rtpengine / rtpproxy reject with
1328
+ * `code === "unsupported_verb"`; a call with no anchored media session
1329
+ * rejects with `"not_found"`.
1330
+ */
1331
+ recordStart(options?: RecordOptions): Promise<Recording>;
1332
+ /**
1333
+ * Stop the recording named by `recordingId`, or **every** recording on this
1334
+ * call when it is left out.
1335
+ *
1336
+ * Resolves once the engine has accepted the stop; the file is not closed yet.
1337
+ * `RecordingFinished` says that, and carries the path and the reason
1338
+ * (`stopped`, `max_duration`, `silence`, `call_ended`, `error`).
1339
+ */
1340
+ recordStop(recordingId?: string): Promise<void>;
1085
1341
  /** Send an arbitrary SIP-adapter verb + args and return the raw result. */
1086
1342
  command(verb: string, args?: unknown): Promise<unknown>;
1087
1343
  /**
@@ -1141,6 +1397,24 @@ declare class SipClient {
1141
1397
  run(): Promise<void>;
1142
1398
  /** Fetch the registered adapters' schema (`describe`). */
1143
1399
  describe(): Promise<unknown>;
1400
+ /**
1401
+ * Place an outbound call under a caller-supplied channel id.
1402
+ *
1403
+ * The one verb that *creates* a channel rather than addressing one, which is
1404
+ * why it lives here and not on {@link Call}. It resolves as soon as the
1405
+ * INVITE is on the wire — the call is `calling`, and the answer, failure or
1406
+ * timeout arrives later as an event on the channel.
1407
+ *
1408
+ * ```ts
1409
+ * const call = await client.originate(
1410
+ * "wake-up-42",
1411
+ * "sip:1001@pbx.example",
1412
+ * { anchor: true },
1413
+ * { from: "sip:alarm@pbx.example", timeout: 20 },
1414
+ * );
1415
+ * ```
1416
+ */
1417
+ originate(channel: string, to: string, media: OriginateMedia, options?: OriginateOptions): Promise<Originated>;
1144
1418
  /** Send a raw command on any module (the generic escape hatch). */
1145
1419
  command(module: string | null, verb: string, target: unknown, args: unknown): Promise<unknown>;
1146
1420
  /** Stop the client. */
@@ -1167,4 +1441,4 @@ declare class SipServer {
1167
1441
  close(): Promise<void>;
1168
1442
  }
1169
1443
 
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 };
1444
+ 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 DialOptions, type DialTarget, type Dialing, type DtmfOptions, type EventFrame, type EventSink, EventStream, type FrameType, GET_VAR, HELLO, type HelloArgs, type HelloResult, MODULE_SIP, MODULE_SMPP, MODULE_SS7, type OriginateMedia, type OriginateOptions, type Originated, 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 StreamOptions, type TransferOutcomePayload, type TransferReplaces, type TransferRequestedPayload, type TransferStage, type WsBridgeEndedPayload, type WsBridgeStartedPayload, type WsTeeEndedPayload, type WsTeeStartedPayload, dialArgs, encodeCommand, isBridgeFinal, isTransferFinal, originateArgs, parseInboundFrame, recordStartArgs, recordStopArgs, sipEventKind, transferOutcome };