@siphon-project/control 0.8.0 → 0.9.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
@@ -1159,6 +1159,13 @@ interface RouteTargetObject {
1159
1159
  * reached anyone. Default `false`, which is never sent.
1160
1160
  */
1161
1161
  rerouteAfterProgress?: boolean;
1162
+ /**
1163
+ * The route set this attempt's INVITE carries, topmost first, each entry one
1164
+ * Route value in name-addr form (`"<sip:scscf.example;lr>"`). The attempt
1165
+ * goes to the topmost entry unless `nextHop` pins it. See
1166
+ * {@link DialTarget}'s `route`.
1167
+ */
1168
+ route?: string[];
1162
1169
  }
1163
1170
  /**
1164
1171
  * One entry in a {@link Call.route} target list: a bare URI string, or a
@@ -1242,18 +1249,6 @@ interface OriginateOptions {
1242
1249
  */
1243
1250
  sessionTimer?: SessionTimer;
1244
1251
  }
1245
- /**
1246
- * What the server answers an accepted `originate` with: the call is `calling`,
1247
- * not answered — the answer arrives later as an event on the channel.
1248
- */
1249
- interface Originated {
1250
- /** The caller-supplied channel id the call is addressed by. */
1251
- channel: string;
1252
- /** siphon's internal call id. */
1253
- callId?: string;
1254
- /** The SIP Call-ID on the wire, for joining CDR / HEP. */
1255
- sipCallId?: string;
1256
- }
1257
1252
  /**
1258
1253
  * How {@link SipClient.originateAor} rings the phones registered at an AoR.
1259
1254
  * Anything left out takes the server's own default.
@@ -1279,6 +1274,11 @@ interface OriginateRing {
1279
1274
  interface OriginatedGroup {
1280
1275
  /** The caller-supplied channel id the group is addressed by. */
1281
1276
  channel: string;
1277
+ /**
1278
+ * The placed call: its events (`DialBranch`, `DialAnswered`, then the
1279
+ * winning phone's) and every verb on the channel.
1280
+ */
1281
+ call: Call;
1282
1282
  /**
1283
1283
  * siphon's id for the group of phones. Until one answers, the channel's
1284
1284
  * events carry it as their `call_id` / `sip_call_id`, since no single dialog
@@ -1329,11 +1329,20 @@ type DialTarget = {
1329
1329
  * requests carry it too, which a `To` header override cannot do.
1330
1330
  */
1331
1331
  to?: string;
1332
+ /**
1333
+ * The route set this branch's INVITE carries, topmost first, each entry
1334
+ * one Route value in name-addr form (`"<sip:scscf.example;lr>"`,
1335
+ * RFC 3261 §25.1). The branch goes to the topmost entry unless `nextHop`
1336
+ * pins it. This is how a controller acting as an IMS application server
1337
+ * continues a session through the S-CSCF with the Route the S-CSCF gave
1338
+ * it (TS 24.229 §5.7.5.2.1); `Route` cannot ride `headers`.
1339
+ */
1340
+ route?: string[];
1332
1341
  } | {
1333
1342
  /**
1334
1343
  * The address of record to fork to its registered contacts. It takes no
1335
- * `nextHop`: each branch routes over its own binding's captured flow, so
1336
- * there would be nothing for one to apply to.
1344
+ * `nextHop` or `route`: each branch routes over its own binding's
1345
+ * captured flow and Path, so there would be nothing for one to apply to.
1337
1346
  */
1338
1347
  aor: string;
1339
1348
  /** Headers injected on every branch the AoR expands to. */
@@ -1579,7 +1588,10 @@ declare class Call {
1579
1588
  readonly sipCallId: string | null;
1580
1589
  /** The application this call was handed to. */
1581
1590
  readonly app: string | null;
1582
- /** The `StasisStart` payload (full SIP context), or the `resync` snapshot. */
1591
+ /**
1592
+ * The `StasisStart` payload (full SIP context), the `resync` snapshot, or
1593
+ * the `originate` reply for a call this client placed.
1594
+ */
1583
1595
  readonly payload: unknown;
1584
1596
  /** True when this call came from a `resync` re-attach after a reconnect. */
1585
1597
  readonly reattached: boolean;
@@ -1593,7 +1605,10 @@ declare class Call {
1593
1605
  sipCallId: string | null,
1594
1606
  /** The application this call was handed to. */
1595
1607
  app: string | null,
1596
- /** The `StasisStart` payload (full SIP context), or the `resync` snapshot. */
1608
+ /**
1609
+ * The `StasisStart` payload (full SIP context), the `resync` snapshot, or
1610
+ * the `originate` reply for a call this client placed.
1611
+ */
1597
1612
  payload: unknown,
1598
1613
  /** True when this call came from a `resync` re-attach after a reconnect. */
1599
1614
  reattached: boolean, eventQueue: AsyncQueue<CallEvent>);
@@ -1723,7 +1738,7 @@ declare class Call {
1723
1738
  *
1724
1739
  * `targets` is a non-empty list of carriers tried cheapest-first: each entry
1725
1740
  * is a bare URI string or a {@link RouteTargetObject}
1726
- * (`{uri, nextHop?, headers?, timeout?, rerouteAfterProgress?}`). A target
1741
+ * (`{uri, nextHop?, headers?, timeout?, rerouteAfterProgress?, route?}`). A target
1727
1742
  * that has shown progress keeps the call past its `timeout` unless it sets
1728
1743
  * `rerouteAfterProgress`. `strategy` defaults to
1729
1744
  * `"sequential"` (v1 supports only sequential/single — anything else rejects
@@ -2074,8 +2089,14 @@ declare class SipClient {
2074
2089
  *
2075
2090
  * The one verb that *creates* a channel rather than addressing one, which is
2076
2091
  * why it lives here and not on {@link Call}. It resolves as soon as the
2077
- * INVITE is on the wire — the call is `calling`, and the answer, failure or
2078
- * timeout arrives later as an event on the channel.
2092
+ * INVITE is on the wire — the call is `calling` — to the {@link Call} it
2093
+ * placed: the answer, failure or timeout arrives on {@link Call.nextEvent},
2094
+ * exactly as a handed-over call's does, and `hangup` CANCELs or BYEs it.
2095
+ *
2096
+ * siphon sends no `StasisStart` for a channel its controller created, so the
2097
+ * channel is opened here before the command goes out (a fast 180 can
2098
+ * overtake the reply). An id still live on this client rejects with
2099
+ * `code === "conflict"` before anything is sent.
2079
2100
  *
2080
2101
  * ```ts
2081
2102
  * const call = await client.originate(
@@ -2086,7 +2107,7 @@ declare class SipClient {
2086
2107
  * );
2087
2108
  * ```
2088
2109
  */
2089
- originate(channel: string, to: string, media: OriginateMedia, options?: OriginateOptions): Promise<Originated>;
2110
+ originate(channel: string, to: string, media: OriginateMedia, options?: OriginateOptions): Promise<Call>;
2090
2111
  /**
2091
2112
  * Ring every phone registered at `aor` under a caller-supplied channel id —
2092
2113
  * {@link SipClient.originate} for a phone rather than a URI.
@@ -2120,6 +2141,9 @@ declare class SipClient {
2120
2141
  * ```
2121
2142
  */
2122
2143
  originateAor(channel: string, aor: string, media: OriginateMedia, options?: OriginateOptions, ring?: OriginateRing): Promise<OriginatedGroup>;
2144
+ /** Open `channel`, send the originate, and close it again if the server refuses. */
2145
+ private place;
2146
+ private placedCall;
2123
2147
  /** Send a raw command on any module (the generic escape hatch). */
2124
2148
  command(module: string | null, verb: string, target: unknown, args: unknown): Promise<unknown>;
2125
2149
  /** Stop the client. */
@@ -2146,4 +2170,4 @@ declare class SipServer {
2146
2170
  close(): Promise<void>;
2147
2171
  }
2148
2172
 
2149
- export { type AcceptReferOptions, type AnchoredAnswerOptions, type AppEvent, type AppEventHandler, type BridgeFailedPayload, type BridgeOptions, type BridgeRole, type BridgeStage, Call, type CallEvent, type CallHandler, CallStream, type ChannelBridgedPayload, type ChannelDtmfPayload, type ChannelSnapshot, type ChannelUnbridgedPayload, type ClientConfig, type ClientEvent, type CommandTransport, type ConnectionEventSink, ControlClient, ControlError, type ControlErrorCode, type ControlErrorKind, ControlServer, DESCRIBE, type DialAnsweredPayload, type DialBranchCause, type DialBranchOutcome, type DialBranchPayload, type DialFailedPayload, type DialOptions, type DialTarget, type Dialing, type DialogDirection, type DialogIdentity, type DialogState, type DialogStateChangedPayload, type DtmfOptions, type EventFrame, type EventSink, EventStream, type FrameType, GET_VAR, HELLO, type HelloArgs, type HelloResult, MODULE_SIP, MODULE_SMPP, MODULE_SS7, type MediaLegSummary, type MediaStartedPayload, type MediaSummaryPayload, type OriginateMedia, type OriginateOptions, type OriginateRing, type Originated, type OriginatedGroup, PROTOCOL_VERSION, type PeerHangupPolicy, type PlayFinishedPayload, type PlayOptions, type PlaySource, type PlayStartedPayload, RESYNC, type RecordChannels, type RecordDirection, type RecordOptions, type Recording, type ReferReplaces, type ReplyError, type ReplyFrame, type ReplyStatus, type ResponseOptions, type ResyncResult, type RouteTarget, type RouteTargetObject, SET_VAR, SUBPROTOCOL, type ServerConfig, type SessionRefresher, type SessionTimer, SipClient, type SipEventKind, SipServer, SipVerb, type SipVerbToken, type StreamMode, type StreamOptions, type StreamStopOptions, type TransferOutcomePayload, type TransferReplaces, type TransferRequestedPayload, type TransferStage, type TransferTimedOutPayload, type WsBridgeEndedPayload, type WsBridgeStartedPayload, type WsTeeEndedPayload, type WsTeeStartedPayload, dialArgs, encodeCommand, isBridgeFinal, isDialFinal, isTransferFinal, originateAorArgs, originateArgs, parseInboundFrame, recordStartArgs, recordStopArgs, sipEventKind, transferOutcome };
2173
+ export { type AcceptReferOptions, type AnchoredAnswerOptions, type AppEvent, type AppEventHandler, type BridgeFailedPayload, type BridgeOptions, type BridgeRole, type BridgeStage, Call, type CallEvent, type CallHandler, CallStream, type ChannelBridgedPayload, type ChannelDtmfPayload, type ChannelSnapshot, type ChannelUnbridgedPayload, type ClientConfig, type ClientEvent, type CommandTransport, type ConnectionEventSink, ControlClient, ControlError, type ControlErrorCode, type ControlErrorKind, ControlServer, DESCRIBE, type DialAnsweredPayload, type DialBranchCause, type DialBranchOutcome, type DialBranchPayload, type DialFailedPayload, type DialOptions, type DialTarget, type Dialing, type DialogDirection, type DialogIdentity, type DialogState, type DialogStateChangedPayload, type DtmfOptions, type EventFrame, type EventSink, EventStream, type FrameType, GET_VAR, HELLO, type HelloArgs, type HelloResult, MODULE_SIP, MODULE_SMPP, MODULE_SS7, type MediaLegSummary, type MediaStartedPayload, type MediaSummaryPayload, type OriginateMedia, type OriginateOptions, type OriginateRing, type OriginatedGroup, PROTOCOL_VERSION, type PeerHangupPolicy, type PlayFinishedPayload, type PlayOptions, type PlaySource, type PlayStartedPayload, RESYNC, type RecordChannels, type RecordDirection, type RecordOptions, type Recording, type ReferReplaces, type ReplyError, type ReplyFrame, type ReplyStatus, type ResponseOptions, type ResyncResult, type RouteTarget, type RouteTargetObject, SET_VAR, SUBPROTOCOL, type ServerConfig, type SessionRefresher, type SessionTimer, SipClient, type SipEventKind, SipServer, SipVerb, type SipVerbToken, type StreamMode, type StreamOptions, type StreamStopOptions, type TransferOutcomePayload, type TransferReplaces, type TransferRequestedPayload, type TransferStage, type TransferTimedOutPayload, type WsBridgeEndedPayload, type WsBridgeStartedPayload, type WsTeeEndedPayload, type WsTeeStartedPayload, dialArgs, encodeCommand, isBridgeFinal, isDialFinal, isTransferFinal, originateAorArgs, originateArgs, parseInboundFrame, recordStartArgs, recordStopArgs, sipEventKind, transferOutcome };
package/dist/index.d.ts CHANGED
@@ -1159,6 +1159,13 @@ interface RouteTargetObject {
1159
1159
  * reached anyone. Default `false`, which is never sent.
1160
1160
  */
1161
1161
  rerouteAfterProgress?: boolean;
1162
+ /**
1163
+ * The route set this attempt's INVITE carries, topmost first, each entry one
1164
+ * Route value in name-addr form (`"<sip:scscf.example;lr>"`). The attempt
1165
+ * goes to the topmost entry unless `nextHop` pins it. See
1166
+ * {@link DialTarget}'s `route`.
1167
+ */
1168
+ route?: string[];
1162
1169
  }
1163
1170
  /**
1164
1171
  * One entry in a {@link Call.route} target list: a bare URI string, or a
@@ -1242,18 +1249,6 @@ interface OriginateOptions {
1242
1249
  */
1243
1250
  sessionTimer?: SessionTimer;
1244
1251
  }
1245
- /**
1246
- * What the server answers an accepted `originate` with: the call is `calling`,
1247
- * not answered — the answer arrives later as an event on the channel.
1248
- */
1249
- interface Originated {
1250
- /** The caller-supplied channel id the call is addressed by. */
1251
- channel: string;
1252
- /** siphon's internal call id. */
1253
- callId?: string;
1254
- /** The SIP Call-ID on the wire, for joining CDR / HEP. */
1255
- sipCallId?: string;
1256
- }
1257
1252
  /**
1258
1253
  * How {@link SipClient.originateAor} rings the phones registered at an AoR.
1259
1254
  * Anything left out takes the server's own default.
@@ -1279,6 +1274,11 @@ interface OriginateRing {
1279
1274
  interface OriginatedGroup {
1280
1275
  /** The caller-supplied channel id the group is addressed by. */
1281
1276
  channel: string;
1277
+ /**
1278
+ * The placed call: its events (`DialBranch`, `DialAnswered`, then the
1279
+ * winning phone's) and every verb on the channel.
1280
+ */
1281
+ call: Call;
1282
1282
  /**
1283
1283
  * siphon's id for the group of phones. Until one answers, the channel's
1284
1284
  * events carry it as their `call_id` / `sip_call_id`, since no single dialog
@@ -1329,11 +1329,20 @@ type DialTarget = {
1329
1329
  * requests carry it too, which a `To` header override cannot do.
1330
1330
  */
1331
1331
  to?: string;
1332
+ /**
1333
+ * The route set this branch's INVITE carries, topmost first, each entry
1334
+ * one Route value in name-addr form (`"<sip:scscf.example;lr>"`,
1335
+ * RFC 3261 §25.1). The branch goes to the topmost entry unless `nextHop`
1336
+ * pins it. This is how a controller acting as an IMS application server
1337
+ * continues a session through the S-CSCF with the Route the S-CSCF gave
1338
+ * it (TS 24.229 §5.7.5.2.1); `Route` cannot ride `headers`.
1339
+ */
1340
+ route?: string[];
1332
1341
  } | {
1333
1342
  /**
1334
1343
  * The address of record to fork to its registered contacts. It takes no
1335
- * `nextHop`: each branch routes over its own binding's captured flow, so
1336
- * there would be nothing for one to apply to.
1344
+ * `nextHop` or `route`: each branch routes over its own binding's
1345
+ * captured flow and Path, so there would be nothing for one to apply to.
1337
1346
  */
1338
1347
  aor: string;
1339
1348
  /** Headers injected on every branch the AoR expands to. */
@@ -1579,7 +1588,10 @@ declare class Call {
1579
1588
  readonly sipCallId: string | null;
1580
1589
  /** The application this call was handed to. */
1581
1590
  readonly app: string | null;
1582
- /** The `StasisStart` payload (full SIP context), or the `resync` snapshot. */
1591
+ /**
1592
+ * The `StasisStart` payload (full SIP context), the `resync` snapshot, or
1593
+ * the `originate` reply for a call this client placed.
1594
+ */
1583
1595
  readonly payload: unknown;
1584
1596
  /** True when this call came from a `resync` re-attach after a reconnect. */
1585
1597
  readonly reattached: boolean;
@@ -1593,7 +1605,10 @@ declare class Call {
1593
1605
  sipCallId: string | null,
1594
1606
  /** The application this call was handed to. */
1595
1607
  app: string | null,
1596
- /** The `StasisStart` payload (full SIP context), or the `resync` snapshot. */
1608
+ /**
1609
+ * The `StasisStart` payload (full SIP context), the `resync` snapshot, or
1610
+ * the `originate` reply for a call this client placed.
1611
+ */
1597
1612
  payload: unknown,
1598
1613
  /** True when this call came from a `resync` re-attach after a reconnect. */
1599
1614
  reattached: boolean, eventQueue: AsyncQueue<CallEvent>);
@@ -1723,7 +1738,7 @@ declare class Call {
1723
1738
  *
1724
1739
  * `targets` is a non-empty list of carriers tried cheapest-first: each entry
1725
1740
  * is a bare URI string or a {@link RouteTargetObject}
1726
- * (`{uri, nextHop?, headers?, timeout?, rerouteAfterProgress?}`). A target
1741
+ * (`{uri, nextHop?, headers?, timeout?, rerouteAfterProgress?, route?}`). A target
1727
1742
  * that has shown progress keeps the call past its `timeout` unless it sets
1728
1743
  * `rerouteAfterProgress`. `strategy` defaults to
1729
1744
  * `"sequential"` (v1 supports only sequential/single — anything else rejects
@@ -2074,8 +2089,14 @@ declare class SipClient {
2074
2089
  *
2075
2090
  * The one verb that *creates* a channel rather than addressing one, which is
2076
2091
  * why it lives here and not on {@link Call}. It resolves as soon as the
2077
- * INVITE is on the wire — the call is `calling`, and the answer, failure or
2078
- * timeout arrives later as an event on the channel.
2092
+ * INVITE is on the wire — the call is `calling` — to the {@link Call} it
2093
+ * placed: the answer, failure or timeout arrives on {@link Call.nextEvent},
2094
+ * exactly as a handed-over call's does, and `hangup` CANCELs or BYEs it.
2095
+ *
2096
+ * siphon sends no `StasisStart` for a channel its controller created, so the
2097
+ * channel is opened here before the command goes out (a fast 180 can
2098
+ * overtake the reply). An id still live on this client rejects with
2099
+ * `code === "conflict"` before anything is sent.
2079
2100
  *
2080
2101
  * ```ts
2081
2102
  * const call = await client.originate(
@@ -2086,7 +2107,7 @@ declare class SipClient {
2086
2107
  * );
2087
2108
  * ```
2088
2109
  */
2089
- originate(channel: string, to: string, media: OriginateMedia, options?: OriginateOptions): Promise<Originated>;
2110
+ originate(channel: string, to: string, media: OriginateMedia, options?: OriginateOptions): Promise<Call>;
2090
2111
  /**
2091
2112
  * Ring every phone registered at `aor` under a caller-supplied channel id —
2092
2113
  * {@link SipClient.originate} for a phone rather than a URI.
@@ -2120,6 +2141,9 @@ declare class SipClient {
2120
2141
  * ```
2121
2142
  */
2122
2143
  originateAor(channel: string, aor: string, media: OriginateMedia, options?: OriginateOptions, ring?: OriginateRing): Promise<OriginatedGroup>;
2144
+ /** Open `channel`, send the originate, and close it again if the server refuses. */
2145
+ private place;
2146
+ private placedCall;
2123
2147
  /** Send a raw command on any module (the generic escape hatch). */
2124
2148
  command(module: string | null, verb: string, target: unknown, args: unknown): Promise<unknown>;
2125
2149
  /** Stop the client. */
@@ -2146,4 +2170,4 @@ declare class SipServer {
2146
2170
  close(): Promise<void>;
2147
2171
  }
2148
2172
 
2149
- export { type AcceptReferOptions, type AnchoredAnswerOptions, type AppEvent, type AppEventHandler, type BridgeFailedPayload, type BridgeOptions, type BridgeRole, type BridgeStage, Call, type CallEvent, type CallHandler, CallStream, type ChannelBridgedPayload, type ChannelDtmfPayload, type ChannelSnapshot, type ChannelUnbridgedPayload, type ClientConfig, type ClientEvent, type CommandTransport, type ConnectionEventSink, ControlClient, ControlError, type ControlErrorCode, type ControlErrorKind, ControlServer, DESCRIBE, type DialAnsweredPayload, type DialBranchCause, type DialBranchOutcome, type DialBranchPayload, type DialFailedPayload, type DialOptions, type DialTarget, type Dialing, type DialogDirection, type DialogIdentity, type DialogState, type DialogStateChangedPayload, type DtmfOptions, type EventFrame, type EventSink, EventStream, type FrameType, GET_VAR, HELLO, type HelloArgs, type HelloResult, MODULE_SIP, MODULE_SMPP, MODULE_SS7, type MediaLegSummary, type MediaStartedPayload, type MediaSummaryPayload, type OriginateMedia, type OriginateOptions, type OriginateRing, type Originated, type OriginatedGroup, PROTOCOL_VERSION, type PeerHangupPolicy, type PlayFinishedPayload, type PlayOptions, type PlaySource, type PlayStartedPayload, RESYNC, type RecordChannels, type RecordDirection, type RecordOptions, type Recording, type ReferReplaces, type ReplyError, type ReplyFrame, type ReplyStatus, type ResponseOptions, type ResyncResult, type RouteTarget, type RouteTargetObject, SET_VAR, SUBPROTOCOL, type ServerConfig, type SessionRefresher, type SessionTimer, SipClient, type SipEventKind, SipServer, SipVerb, type SipVerbToken, type StreamMode, type StreamOptions, type StreamStopOptions, type TransferOutcomePayload, type TransferReplaces, type TransferRequestedPayload, type TransferStage, type TransferTimedOutPayload, type WsBridgeEndedPayload, type WsBridgeStartedPayload, type WsTeeEndedPayload, type WsTeeStartedPayload, dialArgs, encodeCommand, isBridgeFinal, isDialFinal, isTransferFinal, originateAorArgs, originateArgs, parseInboundFrame, recordStartArgs, recordStopArgs, sipEventKind, transferOutcome };
2173
+ export { type AcceptReferOptions, type AnchoredAnswerOptions, type AppEvent, type AppEventHandler, type BridgeFailedPayload, type BridgeOptions, type BridgeRole, type BridgeStage, Call, type CallEvent, type CallHandler, CallStream, type ChannelBridgedPayload, type ChannelDtmfPayload, type ChannelSnapshot, type ChannelUnbridgedPayload, type ClientConfig, type ClientEvent, type CommandTransport, type ConnectionEventSink, ControlClient, ControlError, type ControlErrorCode, type ControlErrorKind, ControlServer, DESCRIBE, type DialAnsweredPayload, type DialBranchCause, type DialBranchOutcome, type DialBranchPayload, type DialFailedPayload, type DialOptions, type DialTarget, type Dialing, type DialogDirection, type DialogIdentity, type DialogState, type DialogStateChangedPayload, type DtmfOptions, type EventFrame, type EventSink, EventStream, type FrameType, GET_VAR, HELLO, type HelloArgs, type HelloResult, MODULE_SIP, MODULE_SMPP, MODULE_SS7, type MediaLegSummary, type MediaStartedPayload, type MediaSummaryPayload, type OriginateMedia, type OriginateOptions, type OriginateRing, type OriginatedGroup, PROTOCOL_VERSION, type PeerHangupPolicy, type PlayFinishedPayload, type PlayOptions, type PlaySource, type PlayStartedPayload, RESYNC, type RecordChannels, type RecordDirection, type RecordOptions, type Recording, type ReferReplaces, type ReplyError, type ReplyFrame, type ReplyStatus, type ResponseOptions, type ResyncResult, type RouteTarget, type RouteTargetObject, SET_VAR, SUBPROTOCOL, type ServerConfig, type SessionRefresher, type SessionTimer, SipClient, type SipEventKind, SipServer, SipVerb, type SipVerbToken, type StreamMode, type StreamOptions, type StreamStopOptions, type TransferOutcomePayload, type TransferReplaces, type TransferRequestedPayload, type TransferStage, type TransferTimedOutPayload, type WsBridgeEndedPayload, type WsBridgeStartedPayload, type WsTeeEndedPayload, type WsTeeStartedPayload, dialArgs, encodeCommand, isBridgeFinal, isDialFinal, isTransferFinal, originateAorArgs, originateArgs, parseInboundFrame, recordStartArgs, recordStopArgs, sipEventKind, transferOutcome };
package/dist/index.js CHANGED
@@ -81,10 +81,10 @@ function encodeCommand(id, module, verb, target, args) {
81
81
  frame.args = args ?? null;
82
82
  return JSON.stringify(frame);
83
83
  }
84
- function parseInboundFrame(text) {
84
+ function parseInboundFrame(text2) {
85
85
  let value;
86
86
  try {
87
- value = JSON.parse(text);
87
+ value = JSON.parse(text2);
88
88
  } catch {
89
89
  return null;
90
90
  }
@@ -257,7 +257,7 @@ var Session = class {
257
257
  return Promise.reject(ControlError.closed());
258
258
  }
259
259
  const id = `c-${this.nextId.value++}`;
260
- const text = encodeCommand(id, module, verb, target, args);
260
+ const text2 = encodeCommand(id, module, verb, target, args);
261
261
  return new Promise((resolve, reject) => {
262
262
  const timer = setTimeout(() => {
263
263
  this.pending.delete(id);
@@ -265,7 +265,7 @@ var Session = class {
265
265
  }, this.replyTimeoutMs);
266
266
  this.pending.set(id, { resolve, reject, timer });
267
267
  try {
268
- this.socket.send(text);
268
+ this.socket.send(text2);
269
269
  } catch (error) {
270
270
  this.pending.delete(id);
271
271
  clearTimeout(timer);
@@ -273,8 +273,8 @@ var Session = class {
273
273
  }
274
274
  });
275
275
  }
276
- onMessage(text) {
277
- const frame = parseInboundFrame(text);
276
+ onMessage(text2) {
277
+ const frame = parseInboundFrame(text2);
278
278
  if (frame === null) {
279
279
  return;
280
280
  }
@@ -656,10 +656,18 @@ function insertTransferIdentity(args, identity) {
656
656
  if (identity?.format !== void 0) args.format = identity.format;
657
657
  if (identity?.headers !== void 0) args.headers = identity.headers;
658
658
  }
659
+ function routeSetToWire(route) {
660
+ if (route === void 0 || route === null) return void 0;
661
+ if (!Array.isArray(route) || route.some((entry) => typeof entry !== "string")) {
662
+ throw new TypeError(`a target's "route" is an array of Route entry strings`);
663
+ }
664
+ return route.length === 0 ? void 0 : [...route];
665
+ }
659
666
  function routeTargetToWire(target) {
660
667
  if (typeof target === "string") {
661
668
  return target;
662
669
  }
670
+ const route = routeSetToWire(target.route);
663
671
  const object = { uri: target.uri };
664
672
  if (target.nextHop !== void 0) {
665
673
  object.next_hop = target.nextHop;
@@ -673,6 +681,9 @@ function routeTargetToWire(target) {
673
681
  if (target.rerouteAfterProgress === true) {
674
682
  object.reroute_after_progress = true;
675
683
  }
684
+ if (route !== void 0) {
685
+ object.route = route;
686
+ }
676
687
  return object;
677
688
  }
678
689
  function stringValue(result) {
@@ -684,6 +695,10 @@ function stringValue(result) {
684
695
  }
685
696
  return null;
686
697
  }
698
+ function text(result, name) {
699
+ const value = result?.[name];
700
+ return typeof value === "string" ? value : void 0;
701
+ }
687
702
  function originateArgs(channel, to, media, options) {
688
703
  return originateCommonArgs({ channel, to }, media, options);
689
704
  }
@@ -733,6 +748,7 @@ function dialTargetToWire(target) {
733
748
  const nextHop = target.nextHop;
734
749
  const headers = target.headers;
735
750
  const to = target.to;
751
+ const route = routeSetToWire(target.route);
736
752
  if (to !== void 0 && typeof to !== "string") {
737
753
  throw new TypeError(`a dial target's "to" is a SIP URI string`);
738
754
  }
@@ -747,6 +763,11 @@ function dialTargetToWire(target) {
747
763
  `an aor target takes no "nextHop": each of its branches routes over its own contact's captured flow`
748
764
  );
749
765
  }
766
+ if (route !== void 0) {
767
+ throw new TypeError(
768
+ `an aor target takes no "route": each of its branches follows its own contact's Path`
769
+ );
770
+ }
750
771
  const object2 = { aor };
751
772
  if (headers !== void 0) object2.headers = headers;
752
773
  if (to !== void 0) object2.to = to;
@@ -755,11 +776,14 @@ function dialTargetToWire(target) {
755
776
  if (typeof uri !== "string") {
756
777
  throw new TypeError('a dial target requires a string "uri" or "aor"');
757
778
  }
758
- if (nextHop === void 0 && headers === void 0 && to === void 0) return uri;
779
+ if (nextHop === void 0 && headers === void 0 && to === void 0 && route === void 0) {
780
+ return uri;
781
+ }
759
782
  const object = { uri };
760
783
  if (nextHop !== void 0) object.next_hop = nextHop;
761
784
  if (headers !== void 0) object.headers = headers;
762
785
  if (to !== void 0) object.to = to;
786
+ if (route !== void 0) object.route = route;
763
787
  return object;
764
788
  }
765
789
  function dialArgs(targets, options) {
@@ -1068,7 +1092,7 @@ var Call = class {
1068
1092
  *
1069
1093
  * `targets` is a non-empty list of carriers tried cheapest-first: each entry
1070
1094
  * is a bare URI string or a {@link RouteTargetObject}
1071
- * (`{uri, nextHop?, headers?, timeout?, rerouteAfterProgress?}`). A target
1095
+ * (`{uri, nextHop?, headers?, timeout?, rerouteAfterProgress?, route?}`). A target
1072
1096
  * that has shown progress keeps the call past its `timeout` unless it sets
1073
1097
  * `rerouteAfterProgress`. `strategy` defaults to
1074
1098
  * `"sequential"` (v1 supports only sequential/single — anything else rejects
@@ -1145,7 +1169,7 @@ var Call = class {
1145
1169
  */
1146
1170
  async dial(targets, options) {
1147
1171
  const result = await this.sip(SipVerb.Dial, dialArgs(targets, options));
1148
- const text = (name) => {
1172
+ const text2 = (name) => {
1149
1173
  const value = result?.[name];
1150
1174
  return typeof value === "string" ? value : void 0;
1151
1175
  };
@@ -1156,12 +1180,12 @@ var Call = class {
1156
1180
  return {
1157
1181
  // The server echoes the channel back; fall back to the one addressed
1158
1182
  // rather than returning an empty id.
1159
- channel: text("channel") ?? this.channelId,
1183
+ channel: text2("channel") ?? this.channelId,
1160
1184
  targets: count("targets"),
1161
- strategy: text("strategy"),
1185
+ strategy: text2("strategy"),
1162
1186
  timeout: count("timeout"),
1163
- onAnswer: text("on_answer"),
1164
- groupId: text("group_id"),
1187
+ onAnswer: text2("on_answer"),
1188
+ groupId: text2("group_id"),
1165
1189
  totalTimeout: count("total_timeout"),
1166
1190
  ringback: (() => {
1167
1191
  const value = result?.ringback;
@@ -1466,13 +1490,13 @@ var Call = class {
1466
1490
  SipVerb.RecordStart,
1467
1491
  recordStartArgs(options)
1468
1492
  );
1469
- const text = (name) => {
1493
+ const text2 = (name) => {
1470
1494
  const value = result?.[name];
1471
1495
  return typeof value === "string" ? value : void 0;
1472
1496
  };
1473
1497
  return {
1474
- channel: text("channel") ?? this.channelId,
1475
- recordingId: text("recording_id")
1498
+ channel: text2("channel") ?? this.channelId,
1499
+ recordingId: text2("recording_id")
1476
1500
  };
1477
1501
  }
1478
1502
  /**
@@ -1591,6 +1615,25 @@ var SipFacade = class {
1591
1615
  );
1592
1616
  this.dispatch(call);
1593
1617
  }
1618
+ /**
1619
+ * Open the event queue of a call this client is placing, before its
1620
+ * `originate` goes out: siphon sends no `StasisStart` for it, and its first
1621
+ * event can overtake the reply. `null` when the channel is already live here,
1622
+ * which must not be taken over.
1623
+ */
1624
+ openChannel(channel) {
1625
+ if (this.channels.has(channel)) {
1626
+ return null;
1627
+ }
1628
+ const queue = new AsyncQueue();
1629
+ this.channels.set(channel, queue);
1630
+ return queue;
1631
+ }
1632
+ /** Close a channel {@link SipFacade.openChannel} opened for a refused originate. */
1633
+ closeChannel(channel) {
1634
+ this.channels.get(channel)?.close();
1635
+ this.channels.delete(channel);
1636
+ }
1594
1637
  route(channel, event) {
1595
1638
  this.channels.get(channel)?.push(event);
1596
1639
  }
@@ -1663,8 +1706,14 @@ var SipClient = class _SipClient {
1663
1706
  *
1664
1707
  * The one verb that *creates* a channel rather than addressing one, which is
1665
1708
  * why it lives here and not on {@link Call}. It resolves as soon as the
1666
- * INVITE is on the wire — the call is `calling`, and the answer, failure or
1667
- * timeout arrives later as an event on the channel.
1709
+ * INVITE is on the wire — the call is `calling` — to the {@link Call} it
1710
+ * placed: the answer, failure or timeout arrives on {@link Call.nextEvent},
1711
+ * exactly as a handed-over call's does, and `hangup` CANCELs or BYEs it.
1712
+ *
1713
+ * siphon sends no `StasisStart` for a channel its controller created, so the
1714
+ * channel is opened here before the command goes out (a fast 180 can
1715
+ * overtake the reply). An id still live on this client rejects with
1716
+ * `code === "conflict"` before anything is sent.
1668
1717
  *
1669
1718
  * ```ts
1670
1719
  * const call = await client.originate(
@@ -1676,23 +1725,8 @@ var SipClient = class _SipClient {
1676
1725
  * ```
1677
1726
  */
1678
1727
  async originate(channel, to, media, options) {
1679
- const result = await this.client.command(
1680
- MODULE_SIP,
1681
- "originate",
1682
- null,
1683
- originateArgs(channel, to, media, options)
1684
- );
1685
- const text = (name) => {
1686
- const value = result?.[name];
1687
- return typeof value === "string" ? value : void 0;
1688
- };
1689
- return {
1690
- // The server echoes the id back; fall back to the one we asked for
1691
- // rather than returning an empty channel a caller cannot address.
1692
- channel: text("channel") ?? channel,
1693
- callId: text("call_id"),
1694
- sipCallId: text("sip_call_id")
1695
- };
1728
+ const { result, queue } = await this.place(channel, originateArgs(channel, to, media, options));
1729
+ return this.placedCall(channel, text(result, "call_id"), text(result, "sip_call_id"), result, queue);
1696
1730
  }
1697
1731
  /**
1698
1732
  * Ring every phone registered at `aor` under a caller-supplied channel id —
@@ -1727,29 +1761,51 @@ var SipClient = class _SipClient {
1727
1761
  * ```
1728
1762
  */
1729
1763
  async originateAor(channel, aor, media, options, ring) {
1730
- const result = await this.client.command(
1731
- MODULE_SIP,
1732
- "originate",
1733
- null,
1764
+ const { result, queue } = await this.place(
1765
+ channel,
1734
1766
  originateAorArgs(channel, aor, media, options, ring)
1735
1767
  );
1736
- const text = (name) => {
1737
- const value = result?.[name];
1738
- return typeof value === "string" ? value : void 0;
1739
- };
1740
- const count = (name) => {
1741
- const value = result?.[name];
1742
- return typeof value === "number" ? value : void 0;
1743
- };
1768
+ const groupId = text(result, "group_id");
1769
+ const totalTimeout = result?.total_timeout;
1744
1770
  return {
1745
- channel: text("channel") ?? channel,
1746
- groupId: text("group_id"),
1747
- aor: text("aor"),
1748
- strategy: text("strategy"),
1749
- totalTimeout: count("total_timeout"),
1771
+ // The server echoes the id back; fall back to the one we asked for
1772
+ // rather than returning an empty channel a caller cannot address.
1773
+ channel: text(result, "channel") ?? channel,
1774
+ // Until a phone answers, the group stands in for the call, as its events say.
1775
+ call: this.placedCall(channel, groupId, groupId, result, queue),
1776
+ groupId,
1777
+ aor: text(result, "aor"),
1778
+ strategy: text(result, "strategy"),
1779
+ totalTimeout: typeof totalTimeout === "number" ? totalTimeout : void 0,
1750
1780
  branches: branchList(result?.branches) ?? []
1751
1781
  };
1752
1782
  }
1783
+ /** Open `channel`, send the originate, and close it again if the server refuses. */
1784
+ async place(channel, args) {
1785
+ const queue = this.facade.openChannel(channel);
1786
+ if (queue === null) {
1787
+ throw ControlError.command("conflict", `channel ${channel} is already live on this client`);
1788
+ }
1789
+ try {
1790
+ const result = await this.client.command(MODULE_SIP, "originate", null, args);
1791
+ return { result, queue };
1792
+ } catch (error) {
1793
+ this.facade.closeChannel(channel);
1794
+ throw error;
1795
+ }
1796
+ }
1797
+ placedCall(channel, callId, sipCallId, reply, queue) {
1798
+ return new Call(
1799
+ this.client.commander(),
1800
+ channel,
1801
+ callId ?? null,
1802
+ sipCallId ?? null,
1803
+ null,
1804
+ reply,
1805
+ false,
1806
+ queue
1807
+ );
1808
+ }
1753
1809
  /** Send a raw command on any module (the generic escape hatch). */
1754
1810
  command(module, verb, target, args) {
1755
1811
  return this.client.command(module, verb, target, args);