@siphon-project/control 0.8.0 → 0.10.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
@@ -86,6 +86,16 @@ declare const DESCRIBE = "describe";
86
86
  declare const SET_VAR = "set_var";
87
87
  /** Substrate verb: read a per-channel variable. */
88
88
  declare const GET_VAR = "get_var";
89
+ /**
90
+ * Substrate verb: every registered AoR and the `seq` the set is current to
91
+ * (the app must subscribe to `registration`).
92
+ */
93
+ declare const REGISTRATIONS = "registrations";
94
+ /**
95
+ * Substrate verb: every outbound registration and its `seq` (the app must
96
+ * subscribe to `outbound_registration`).
97
+ */
98
+ declare const OUTBOUND_REGISTRATIONS = "outbound_registrations";
89
99
  /** The `type` discriminator on every frame. */
90
100
  type FrameType = "command" | "reply" | "event";
91
101
  /** The status of a reply. */
@@ -232,7 +242,7 @@ declare const SipVerb: {
232
242
  /** A value of {@link SipVerb}. */
233
243
  type SipVerbToken = (typeof SipVerb)[keyof typeof SipVerb];
234
244
  /** The well-known SIP-adapter event names (the ARI *Stasis* model). */
235
- type SipEventKind = "StasisStart" | "StasisEnd" | "ChannelStateChange" | "ChannelHangupRequest" | "ChannelDtmfReceived" | "PlayStarted" | "TransferRequested" | "TransferTimedOut" | "TransferProgress" | "TransferCompleted" | "TransferFailed" | "ChannelBridged" | "BridgeFailed" | "ChannelUnbridged" | "PeerReplaced" | "ReplaceFailed" | "PlayFinished" | "WsTeeStarted" | "WsTeeEnded" | "WsBridgeStarted" | "WsBridgeEnded" | "MediaSummary" | "MediaStarted" | "DialBranch" | "DialBranchFailed" | "DialAnswered" | "DialFailed" | "DialogStateChanged" | (string & {});
245
+ type SipEventKind = "StasisStart" | "StasisEnd" | "ChannelStateChange" | "ChannelHangupRequest" | "ChannelDtmfReceived" | "PlayStarted" | "TransferRequested" | "TransferTimedOut" | "TransferProgress" | "TransferCompleted" | "TransferFailed" | "ChannelBridged" | "BridgeFailed" | "ChannelUnbridged" | "PeerReplaced" | "ReplaceFailed" | "PlayFinished" | "WsTeeStarted" | "WsTeeEnded" | "WsBridgeStarted" | "WsBridgeEnded" | "MediaSummary" | "MediaStarted" | "DialBranch" | "DialBranchFailed" | "DialAnswered" | "DialFailed" | "DialogStateChanged" | "RegistrationChanged" | "RegistrantChanged" | (string & {});
236
246
  /** Parse a wire event name; unknown names pass through verbatim (forward-compatible). */
237
247
  declare function sipEventKind(name: string): SipEventKind;
238
248
  /**
@@ -780,6 +790,121 @@ interface DialogStateChangedPayload {
780
790
  remote_tag: string | null;
781
791
  remote_identity: DialogIdentity;
782
792
  }
793
+ /**
794
+ * One binding of a registered AoR, as `RegistrationChanged` and the
795
+ * `registrations` reply report it. Fields past `q` are absent from a server
796
+ * older than the one that added them.
797
+ */
798
+ interface RegistrationContact {
799
+ /** The Contact URI. */
800
+ uri: string;
801
+ /** Seconds left on the binding. */
802
+ expires: number;
803
+ /** Its q-value. */
804
+ q: number;
805
+ /**
806
+ * Where the REGISTER came from, `sip:<ip>:<port>;transport=<proto>`, byte for
807
+ * byte the script's `Contact.received`; `null` when unknown. This, not `uri`,
808
+ * is what an INVITE from the same phone comes from.
809
+ */
810
+ received?: string | null;
811
+ /** The transport the REGISTER arrived on. */
812
+ transport?: string | null;
813
+ /** The transport the client used to reach a front that declared a different one. */
814
+ client_transport?: string;
815
+ /** The `+sip.instance` (RFC 5626). */
816
+ instance?: string | null;
817
+ /** The `reg-id` (RFC 5626). */
818
+ reg_id?: number | null;
819
+ /** The binding's Path (RFC 3327), topmost first. */
820
+ path?: string[];
821
+ /** The Call-ID of the REGISTER that last wrote the binding. */
822
+ call_id?: string;
823
+ /** The CSeq number of the REGISTER that last wrote the binding. */
824
+ cseq?: number;
825
+ }
826
+ /**
827
+ * The `payload` of a `RegistrationChanged` event (`events: [registration]`).
828
+ * A gap in `seq` means events were lost: call
829
+ * {@link import("./sip").SipClient.registrations} and apply only events numbered
830
+ * above its `seq`.
831
+ */
832
+ interface RegistrationChangedPayload {
833
+ /** Per-process number, one higher per event published. */
834
+ seq?: number;
835
+ /**
836
+ * The server process's boot epoch, new at every start: `seq` restarts with
837
+ * it, so a changed epoch means the numbers began again. An identifier, not an
838
+ * order; `null` without a registrar identity.
839
+ */
840
+ instance_epoch?: string | null;
841
+ aor: string;
842
+ /**
843
+ * `registered`, `refreshed`, `deregistered`, `expired` or `snapshot` (a
844
+ * re-report after the server's event task fell behind, not a change).
845
+ */
846
+ event: string;
847
+ /** The AoR's bindings now; empty once it has none. */
848
+ contacts: RegistrationContact[];
849
+ }
850
+ /** The reply of `registrations`, one page in AoR order. */
851
+ interface RegistrationsReply {
852
+ /** Every event numbered at or below this is reflected here; across pages keep the first's. */
853
+ seq: number;
854
+ /**
855
+ * The server process's boot epoch, new at every start: `seq` restarts with
856
+ * it, so a changed epoch means the numbers began again. An identifier, not an
857
+ * order; `null` without a registrar identity.
858
+ */
859
+ instance_epoch?: string | null;
860
+ /** The registered AoRs of this page; over the whole set, one not listed has no binding. */
861
+ registrations: {
862
+ aor: string;
863
+ contacts: RegistrationContact[];
864
+ }[];
865
+ /** The `after` that asks for the next page; `null` on the last. */
866
+ next?: string | null;
867
+ }
868
+ /** One outbound registration (a REGISTER the server sends upstream). */
869
+ interface OutboundRegistration {
870
+ aor: string;
871
+ /** The registrar it registers with; `null` once removed. */
872
+ registrar: string | null;
873
+ /** `unregistered`, `registering`, `challenging`, `registered` or `failed`; `null` once removed. */
874
+ state: string | null;
875
+ /** Seconds left on the granted binding, `0` when none. */
876
+ expires_in: number;
877
+ /** Consecutive failed attempts. */
878
+ failure_count: number;
879
+ /** The status of the last failed attempt, `null` once one succeeded. */
880
+ status_code: number | null;
881
+ }
882
+ /** The `payload` of a `RegistrantChanged` event (`events: [outbound_registration]`). */
883
+ interface RegistrantChangedPayload extends OutboundRegistration {
884
+ /** Per-process number, its own sequence. */
885
+ seq?: number;
886
+ /**
887
+ * The server process's boot epoch, new at every start: `seq` restarts with
888
+ * it, so a changed epoch means the numbers began again. An identifier, not an
889
+ * order; `null` without a registrar identity.
890
+ */
891
+ instance_epoch?: string | null;
892
+ /** `registered`, `refreshed`, `failed`, `deregistered` or `snapshot`. */
893
+ event: string;
894
+ }
895
+ /** The reply of `outbound_registrations`, paged like {@link RegistrationsReply}. */
896
+ interface OutboundRegistrationsReply {
897
+ seq: number;
898
+ /**
899
+ * The server process's boot epoch, new at every start: `seq` restarts with
900
+ * it, so a changed epoch means the numbers began again. An identifier, not an
901
+ * order; `null` without a registrar identity.
902
+ */
903
+ instance_epoch?: string | null;
904
+ registrations: OutboundRegistration[];
905
+ /** The `after` that asks for the next page; `null` on the last. */
906
+ next?: string | null;
907
+ }
783
908
  /**
784
909
  * Whether an event name ends a `dial`. Exactly one `DialAnswered` or
785
910
  * `DialFailed` arrives per dial, so this is the signal to stop waiting;
@@ -1002,7 +1127,9 @@ interface CallEvent {
1002
1127
  /**
1003
1128
  * An application-level event: pushed to every connection of an app that opted
1004
1129
  * into its class (`control.apps[].events`), about the deployment rather than a
1005
- * channel — `RegistrationChanged`, `DialogStateChanged` (cast `payload` to
1130
+ * channel — `RegistrationChanged`, `RegistrantChanged`, `DialogStateChanged`
1131
+ * (cast `payload` to {@link import("./protocol").RegistrationChangedPayload},
1132
+ * {@link import("./protocol").RegistrantChangedPayload} or
1006
1133
  * {@link import("./protocol").DialogStateChangedPayload}). Its frame has no
1007
1134
  * channel, so it reaches {@link SipClient.onAppEvent}, never a call.
1008
1135
  */
@@ -1022,6 +1149,58 @@ interface ResponseOptions {
1022
1149
  reason?: string;
1023
1150
  body?: string;
1024
1151
  contentType?: string;
1152
+ /**
1153
+ * Host siphon presents in its own `Contact` toward the caller, in place of
1154
+ * the address it advertises, for a peer that identifies the tenant or
1155
+ * account by that host. Only the host changes, and every later Contact
1156
+ * siphon presents the caller carries it. Fixed once an 18x or 2xx went out:
1157
+ * the same host again is accepted, another rejects with `invalid_state`.
1158
+ */
1159
+ contactHost?: string;
1160
+ /**
1161
+ * User part siphon presents in its own `Contact` toward the caller, which is
1162
+ * otherwise userless (`<sip:trunk-7@sbc.example.net:5061;transport=tls>`),
1163
+ * for a peer that keys the account on the Contact user. An RFC 3261 SIP URI
1164
+ * user; the server refuses an empty or invalid one with `bad_request`. Fixed
1165
+ * as `contactHost` is: another one after an 18x or 2xx rejects with
1166
+ * `invalid_state`.
1167
+ */
1168
+ contactUser?: string;
1169
+ }
1170
+ /** Options for {@link Call.ring}. */
1171
+ interface RingOptions {
1172
+ /**
1173
+ * Host siphon presents in its own `Contact` toward the caller, in place of
1174
+ * the address it advertises, for a peer that identifies the tenant or
1175
+ * account by that host. Only the host changes, and every later Contact
1176
+ * siphon presents the caller carries it. Fixed once an 18x or 2xx went out:
1177
+ * the same host again is accepted, another rejects with `invalid_state`.
1178
+ */
1179
+ contactHost?: string;
1180
+ /**
1181
+ * User part siphon presents in its own `Contact` toward the caller, which is
1182
+ * otherwise userless (`<sip:trunk-7@sbc.example.net:5061;transport=tls>`),
1183
+ * for a peer that keys the account on the Contact user. An RFC 3261 SIP URI
1184
+ * user; the server refuses an empty or invalid one with `bad_request`. Fixed
1185
+ * as `contactHost` is: another one after an 18x or 2xx rejects with
1186
+ * `invalid_state`.
1187
+ */
1188
+ contactUser?: string;
1189
+ }
1190
+ /** Options for {@link Call.route}. */
1191
+ interface RouteOptions {
1192
+ /**
1193
+ * Host of siphon's own `Contact` toward the caller, as `contactHost` is on
1194
+ * {@link Call.answer}. Each target's `contactHost` is the host its attempt
1195
+ * presents the carrier.
1196
+ */
1197
+ callerContactHost?: string;
1198
+ /**
1199
+ * User part of siphon's own `Contact` toward the caller, as `contactUser` is
1200
+ * on {@link Call.answer}. Each target's `contactUser` is the user its
1201
+ * attempt presents the carrier.
1202
+ */
1203
+ callerContactUser?: string;
1025
1204
  }
1026
1205
  /** Options for an anchored answer ({@link Call.answerAnchored}). */
1027
1206
  interface AnchoredAnswerOptions {
@@ -1038,6 +1217,10 @@ interface AnchoredAnswerOptions {
1038
1217
  * `callId`.
1039
1218
  */
1040
1219
  wsUri?: string;
1220
+ /** Host of siphon's own `Contact` toward the caller; see {@link ResponseOptions}. */
1221
+ contactHost?: string;
1222
+ /** User part of siphon's own `Contact` toward the caller; see {@link ResponseOptions}. */
1223
+ contactUser?: string;
1041
1224
  }
1042
1225
  /** The RFC 3891 `Replaces` triple for an attended transfer. */
1043
1226
  interface ReferReplaces {
@@ -1159,6 +1342,29 @@ interface RouteTargetObject {
1159
1342
  * reached anyone. Default `false`, which is never sent.
1160
1343
  */
1161
1344
  rerouteAfterProgress?: boolean;
1345
+ /**
1346
+ * The route set this attempt's INVITE carries, topmost first, each entry one
1347
+ * Route value in name-addr form (`"<sip:scscf.example;lr>"`). The attempt
1348
+ * goes to the topmost entry unless `nextHop` pins it. See
1349
+ * {@link DialTarget}'s `route`.
1350
+ */
1351
+ route?: string[];
1352
+ /**
1353
+ * Host siphon presents in its own `Contact` on this attempt, in place of the
1354
+ * address it advertises. See {@link DialTarget}'s `contactHost`.
1355
+ */
1356
+ contactHost?: string;
1357
+ /**
1358
+ * User part siphon presents in its own `Contact` on this attempt, which is
1359
+ * otherwise userless. See {@link DialTarget}'s `contactUser`.
1360
+ */
1361
+ contactUser?: string;
1362
+ /**
1363
+ * Verify (`true`) or not (`false`) the server certificate when this attempt
1364
+ * opens a new outbound TLS connection. See {@link DialTarget}'s
1365
+ * `verifyServer`.
1366
+ */
1367
+ verifyServer?: boolean;
1162
1368
  }
1163
1369
  /**
1164
1370
  * One entry in a {@link Call.route} target list: a bare URI string, or a
@@ -1241,18 +1447,20 @@ interface OriginateOptions {
1241
1447
  * has configured runs, if any.
1242
1448
  */
1243
1449
  sessionTimer?: SessionTimer;
1244
- }
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;
1450
+ /**
1451
+ * Host siphon presents in its own `Contact` on the call (on every leg of an
1452
+ * {@link SipClient.originateAor}), in place of the address it advertises,
1453
+ * for a peer that identifies the tenant or account by that host. Only the
1454
+ * host changes, and every in-dialog request on the call presents it too.
1455
+ */
1456
+ contactHost?: string;
1457
+ /**
1458
+ * User part siphon presents in its own `Contact` on the call (on every leg
1459
+ * of an {@link SipClient.originateAor}), which is otherwise userless, for a
1460
+ * peer that keys the account on the Contact user. An RFC 3261 SIP URI user;
1461
+ * the server refuses anything else with `bad_request`.
1462
+ */
1463
+ contactUser?: string;
1256
1464
  }
1257
1465
  /**
1258
1466
  * How {@link SipClient.originateAor} rings the phones registered at an AoR.
@@ -1279,6 +1487,11 @@ interface OriginateRing {
1279
1487
  interface OriginatedGroup {
1280
1488
  /** The caller-supplied channel id the group is addressed by. */
1281
1489
  channel: string;
1490
+ /**
1491
+ * The placed call: its events (`DialBranch`, `DialAnswered`, then the
1492
+ * winning phone's) and every verb on the channel.
1493
+ */
1494
+ call: Call;
1282
1495
  /**
1283
1496
  * siphon's id for the group of phones. Until one answers, the channel's
1284
1497
  * events carry it as their `call_id` / `sip_call_id`, since no single dialog
@@ -1329,18 +1542,102 @@ type DialTarget = {
1329
1542
  * requests carry it too, which a `To` header override cannot do.
1330
1543
  */
1331
1544
  to?: string;
1545
+ /**
1546
+ * The route set this branch's INVITE carries, topmost first, each entry
1547
+ * one Route value in name-addr form (`"<sip:scscf.example;lr>"`,
1548
+ * RFC 3261 §25.1). The branch goes to the topmost entry unless `nextHop`
1549
+ * pins it. This is how a controller acting as an IMS application server
1550
+ * continues a session through the S-CSCF with the Route the S-CSCF gave
1551
+ * it (TS 24.229 §5.7.5.2.1); `Route` cannot ride `headers`.
1552
+ */
1553
+ route?: string[];
1554
+ /**
1555
+ * Host siphon presents in its own `Contact` on this branch, in place of
1556
+ * the address it advertises, for a peer that identifies the tenant or
1557
+ * account by that host. Only the host changes (port, transport and user
1558
+ * part stay siphon's), and siphon keeps it as the leg's dialog Contact,
1559
+ * so every in-dialog request on the leg presents it too. A hostname or an
1560
+ * IP address; the server refuses anything else with `bad_request`.
1561
+ */
1562
+ contactHost?: string;
1563
+ /**
1564
+ * User part siphon presents in its own `Contact` on this branch, which is
1565
+ * otherwise userless (`<sip:trunk-7@sbc.example.net:5061;transport=tls>`),
1566
+ * for a peer that keys the account on the Contact user. Composes with
1567
+ * `contactHost`, sticks the same way, and outranks a script's
1568
+ * `call.set_contact_user()`. An RFC 3261 SIP URI user; the server
1569
+ * refuses anything else with `bad_request`.
1570
+ */
1571
+ contactUser?: string;
1572
+ /**
1573
+ * Whether a sequential dial still moves on from this target once it has
1574
+ * rung (sent the far end's 101-199). Sent only when given; the server's
1575
+ * default is `true`, a hunt through phones moving on when one rings out
1576
+ * or is busy. `false` ends a sequential dial on this target once it has
1577
+ * rung: its ring timeout, busy or other failure is the dial's and no
1578
+ * later target is rung, for a hunt across several routes to the same
1579
+ * destination. A target that never rang, and a `503` carrying
1580
+ * `Retry-After`, still move the hunt on; a `6xx` ends a sequential dial
1581
+ * whatever this says. A parallel dial ignores it.
1582
+ */
1583
+ rerouteAfterProgress?: boolean;
1584
+ /**
1585
+ * Media profile for this branch alone, over the dial's own. A target
1586
+ * without one inherits the dial's. One ring can then reach a phone behind
1587
+ * NAT that needs a latching relay and a trunk that asks for SDES-SRTP. An
1588
+ * unknown name fails the dial as an unknown dial-level `profile` does; a
1589
+ * connecting dial that names no `profile` anchors every branch or none, so
1590
+ * either every target names one or none does (a mix is `bad_request`).
1591
+ */
1592
+ profile?: string;
1593
+ /**
1594
+ * When this branch's INVITE carries its SDP offer, over the dial's own
1595
+ * `offer` (see {@link DialOptions.offer}). Bridge dials only.
1596
+ */
1597
+ offer?: DialOffer;
1598
+ /**
1599
+ * Verify (`true`) or not (`false`) the server certificate when this branch
1600
+ * opens a new outbound TLS connection, over the gateway it routes to and
1601
+ * the server's `tls.verify_server`: the chain against the server's
1602
+ * `tls.server_ca` (or its bundled public roots), and the host this branch
1603
+ * routes to (`nextHop`, else `uri`) as a SIP domain (RFC 5922 §7: exact
1604
+ * match, no wildcards), or its IP address for an IP-literal target. A
1605
+ * branch that fails is not sent. Unset leaves it to the server.
1606
+ */
1607
+ verifyServer?: boolean;
1332
1608
  } | {
1333
1609
  /**
1334
1610
  * 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.
1611
+ * `nextHop` or `route`: each branch routes over its own binding's
1612
+ * captured flow and Path, so there would be nothing for one to apply to.
1337
1613
  */
1338
1614
  aor: string;
1339
1615
  /** Headers injected on every branch the AoR expands to. */
1340
1616
  headers?: Record<string, string>;
1341
1617
  /** Called party for every branch the AoR expands to (see the URI form). */
1342
1618
  to?: string;
1619
+ /** Host of siphon's own `Contact` on every branch the AoR expands to (see the URI form). */
1620
+ contactHost?: string;
1621
+ /** User part of siphon's own `Contact` on every branch the AoR expands to (see the URI form). */
1622
+ contactUser?: string;
1623
+ /** `rerouteAfterProgress` for every branch the AoR expands to (see the URI form). */
1624
+ rerouteAfterProgress?: boolean;
1625
+ /** Media profile for every branch the AoR expands to (see the URI form). */
1626
+ profile?: string;
1627
+ /** When every branch the AoR expands to carries its offer (see the URI form). */
1628
+ offer?: DialOffer;
1629
+ /** Server certificate verification on every branch the AoR expands to (see the URI form). */
1630
+ verifyServer?: boolean;
1343
1631
  };
1632
+ /**
1633
+ * When a phone an `onAnswer: "bridge"` dial rings is sent its SDP offer:
1634
+ * `"delayed"` (the server's default) sends the INVITE offerless and the phone
1635
+ * offers in its 2xx; `"early"` sends an offer the media engine allocated from
1636
+ * the caller's media under the phone's profile, for peers that refuse a
1637
+ * delayed-offer INVITE. The phone then answers in its 2xx (one without SDP
1638
+ * fails that branch with 488) and only the caller is re-INVITEd at the bridge.
1639
+ */
1640
+ type DialOffer = "early" | "delayed";
1344
1641
  /**
1345
1642
  * Optional shaping for {@link Call.dial}; anything left out takes the server's
1346
1643
  * own default rather than a copy of it pinned here.
@@ -1416,6 +1713,28 @@ interface DialOptions {
1416
1713
  * (`bad_request`, `requires_bridge`).
1417
1714
  */
1418
1715
  ringback?: string | boolean;
1716
+ /**
1717
+ * Host of siphon's own `Contact` toward the caller, as `contactHost` is on
1718
+ * {@link Call.answer}; each target's `contactHost` is the host its leg
1719
+ * presents. On a bridging dial, whose caller is answered already, it can
1720
+ * only repeat the host that answer carried (another rejects with
1721
+ * `invalid_state`).
1722
+ */
1723
+ callerContactHost?: string;
1724
+ /**
1725
+ * User part of siphon's own `Contact` toward the caller, as `contactUser` is
1726
+ * on {@link Call.answer}; each target's `contactUser` is the user its leg
1727
+ * presents. On a bridging dial it can only repeat what the answer carried.
1728
+ */
1729
+ callerContactUser?: string;
1730
+ /**
1731
+ * When each phone of an `onAnswer: "bridge"` dial is sent its offer, where
1732
+ * its target names none ({@link DialOffer}). Bridge-only: naming it, on the
1733
+ * dial or on a target, without `onAnswer: "bridge"` throws a `TypeError`
1734
+ * before anything is sent, since the server refuses it on a connecting dial
1735
+ * (`bad_request`, `requires_bridge`).
1736
+ */
1737
+ offer?: DialOffer;
1419
1738
  }
1420
1739
  /**
1421
1740
  * What the server answers an accepted `dial` with: the INVITEs are on the wire
@@ -1444,6 +1763,8 @@ interface Dialing {
1444
1763
  totalTimeout?: number;
1445
1764
  /** The ringback in force on a bridge dial (a preset or cadence, or `false`). */
1446
1765
  ringback?: string | boolean;
1766
+ /** The offer mode of a bridge dial's phones, where a target names none. */
1767
+ offer?: DialOffer;
1447
1768
  /** The phone INVITEs a bridge dial built, one per branch. */
1448
1769
  branches?: DialBranchPayload[];
1449
1770
  }
@@ -1579,7 +1900,10 @@ declare class Call {
1579
1900
  readonly sipCallId: string | null;
1580
1901
  /** The application this call was handed to. */
1581
1902
  readonly app: string | null;
1582
- /** The `StasisStart` payload (full SIP context), or the `resync` snapshot. */
1903
+ /**
1904
+ * The `StasisStart` payload (full SIP context), the `resync` snapshot, or
1905
+ * the `originate` reply for a call this client placed.
1906
+ */
1583
1907
  readonly payload: unknown;
1584
1908
  /** True when this call came from a `resync` re-attach after a reconnect. */
1585
1909
  readonly reattached: boolean;
@@ -1593,7 +1917,10 @@ declare class Call {
1593
1917
  sipCallId: string | null,
1594
1918
  /** The application this call was handed to. */
1595
1919
  app: string | null,
1596
- /** The `StasisStart` payload (full SIP context), or the `resync` snapshot. */
1920
+ /**
1921
+ * The `StasisStart` payload (full SIP context), the `resync` snapshot, or
1922
+ * the `originate` reply for a call this client placed.
1923
+ */
1597
1924
  payload: unknown,
1598
1925
  /** True when this call came from a `resync` re-attach after a reconnect. */
1599
1926
  reattached: boolean, eventQueue: AsyncQueue<CallEvent>);
@@ -1631,7 +1958,7 @@ declare class Call {
1631
1958
  * then {@link Call.answer}; open an early-media path with
1632
1959
  * {@link Call.progress}.
1633
1960
  */
1634
- ring(reason?: string): Promise<void>;
1961
+ ring(reason?: string, options?: RingOptions): Promise<void>;
1635
1962
  /**
1636
1963
  * Send a UAS 1xx, optionally opening an early-media path with SDP (default
1637
1964
  * `183 Session Progress`). For plain alerting use {@link Call.ring}.
@@ -1723,7 +2050,7 @@ declare class Call {
1723
2050
  *
1724
2051
  * `targets` is a non-empty list of carriers tried cheapest-first: each entry
1725
2052
  * is a bare URI string or a {@link RouteTargetObject}
1726
- * (`{uri, nextHop?, headers?, timeout?, rerouteAfterProgress?}`). A target
2053
+ * (`{uri, nextHop?, headers?, timeout?, rerouteAfterProgress?, route?, contactHost?, contactUser?}`). A target
1727
2054
  * that has shown progress keeps the call past its `timeout` unless it sets
1728
2055
  * `rerouteAfterProgress`. `strategy` defaults to
1729
2056
  * `"sequential"` (v1 supports only sequential/single — anything else rejects
@@ -1734,7 +2061,7 @@ declare class Call {
1734
2061
  * empty / invalid `targets` list rejects with `code === "bad_request"`; a call
1735
2062
  * that is already gone rejects with `code === "not_found"`.
1736
2063
  */
1737
- route(targets: RouteTarget[], strategy?: string, headers?: Record<string, string>): Promise<unknown>;
2064
+ route(targets: RouteTarget[], strategy?: string, headers?: Record<string, string>, options?: RouteOptions): Promise<unknown>;
1738
2065
  /**
1739
2066
  * Ring `targets` as B-legs while the caller stays **unanswered** and this
1740
2067
  * application keeps the channel.
@@ -2069,13 +2396,34 @@ declare class SipClient {
2069
2396
  run(): Promise<void>;
2070
2397
  /** Fetch the registered adapters' schema (`describe`). */
2071
2398
  describe(): Promise<unknown>;
2399
+ /**
2400
+ * Everything the registrar holds now and the `seq` it is current to
2401
+ * (`registrations`; the app must subscribe to `registration`). Fetches every
2402
+ * page and merges them, keeping the first page's `seq`. Ask on connecting
2403
+ * and whenever a `RegistrationChanged` `seq` skips a number: replace your
2404
+ * copy with the reply and apply only events numbered above it.
2405
+ */
2406
+ registrations(): Promise<RegistrationsReply>;
2407
+ /**
2408
+ * Every outbound registration's state and its `seq`
2409
+ * (`outbound_registrations`; the app must subscribe to `outbound_registration`).
2410
+ * Fetches every page, as {@link SipClient.registrations} does.
2411
+ */
2412
+ outboundRegistrations(): Promise<OutboundRegistrationsReply>;
2413
+ private everyPage;
2072
2414
  /**
2073
2415
  * Place an outbound call under a caller-supplied channel id.
2074
2416
  *
2075
2417
  * The one verb that *creates* a channel rather than addressing one, which is
2076
2418
  * 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.
2419
+ * INVITE is on the wire — the call is `calling` — to the {@link Call} it
2420
+ * placed: the answer, failure or timeout arrives on {@link Call.nextEvent},
2421
+ * exactly as a handed-over call's does, and `hangup` CANCELs or BYEs it.
2422
+ *
2423
+ * siphon sends no `StasisStart` for a channel its controller created, so the
2424
+ * channel is opened here before the command goes out (a fast 180 can
2425
+ * overtake the reply). An id still live on this client rejects with
2426
+ * `code === "conflict"` before anything is sent.
2079
2427
  *
2080
2428
  * ```ts
2081
2429
  * const call = await client.originate(
@@ -2086,7 +2434,7 @@ declare class SipClient {
2086
2434
  * );
2087
2435
  * ```
2088
2436
  */
2089
- originate(channel: string, to: string, media: OriginateMedia, options?: OriginateOptions): Promise<Originated>;
2437
+ originate(channel: string, to: string, media: OriginateMedia, options?: OriginateOptions): Promise<Call>;
2090
2438
  /**
2091
2439
  * Ring every phone registered at `aor` under a caller-supplied channel id —
2092
2440
  * {@link SipClient.originate} for a phone rather than a URI.
@@ -2120,6 +2468,9 @@ declare class SipClient {
2120
2468
  * ```
2121
2469
  */
2122
2470
  originateAor(channel: string, aor: string, media: OriginateMedia, options?: OriginateOptions, ring?: OriginateRing): Promise<OriginatedGroup>;
2471
+ /** Open `channel`, send the originate, and close it again if the server refuses. */
2472
+ private place;
2473
+ private placedCall;
2123
2474
  /** Send a raw command on any module (the generic escape hatch). */
2124
2475
  command(module: string | null, verb: string, target: unknown, args: unknown): Promise<unknown>;
2125
2476
  /** Stop the client. */
@@ -2146,4 +2497,4 @@ declare class SipServer {
2146
2497
  close(): Promise<void>;
2147
2498
  }
2148
2499
 
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 };
2500
+ 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 DialOffer, 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, OUTBOUND_REGISTRATIONS, type OriginateMedia, type OriginateOptions, type OriginateRing, type OriginatedGroup, type OutboundRegistration, type OutboundRegistrationsReply, PROTOCOL_VERSION, type PeerHangupPolicy, type PlayFinishedPayload, type PlayOptions, type PlaySource, type PlayStartedPayload, REGISTRATIONS, RESYNC, type RecordChannels, type RecordDirection, type RecordOptions, type Recording, type ReferReplaces, type RegistrantChangedPayload, type RegistrationChangedPayload, type RegistrationContact, type RegistrationsReply, type ReplyError, type ReplyFrame, type ReplyStatus, type ResponseOptions, type ResyncResult, type RingOptions, type RouteOptions, 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 };