@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/README.md CHANGED
@@ -93,9 +93,9 @@ await client.command("sip", "answer", { channel: "ch1" }, { code: 200 });
93
93
 
94
94
  | Method | Wire verb (`module`) | Notes |
95
95
  | --- | --- | --- |
96
- | `answer(options?)` | `answer` (`sip`) | UAS 2xx (default `200 OK`) |
96
+ | `answer(options?)` | `answer` (`sip`) | UAS 2xx (default `200 OK`). `options.contactHost` (here, on `answerAnchored`, `ring` and `progress`) is the host of siphon's own Contact toward the caller, for a peer that identifies the tenant by it; fixed once an 18x or 2xx went out (another is `invalid_state`). `options.contactUser` (on the same verbs) is the user part of that Contact, otherwise userless, fixed the same way |
97
97
  | `answerAnchored(options?)` | `answer` (`sip`) | answer and anchor the caller's media on the media engine in one act (`profile`, `wsUri`); what `play`, `hold` and `dial` with `onAnswer: "bridge"` need |
98
- | `ring(reason?)` | `ring` (`sip`) | `180 Ringing`: alerting only, no early media |
98
+ | `ring(reason?, options?)` | `ring` (`sip`) | `180 Ringing`: alerting only, no early media |
99
99
  | `progress(options?)` | `progress` (`sip`) | UAS 1xx / early media (default `183`) |
100
100
  | `reject(code, reason?)` | `reject` (`sip`) | final non-2xx + teardown |
101
101
  | `terminate(reason?)` | `hangup` (`sip`) | primary teardown name |
@@ -109,13 +109,13 @@ await client.command("sip", "answer", { channel: "ch1" }, { code: 200 });
109
109
  | `setVar(key, value)` | `set_var` (substrate) | per-call variable |
110
110
  | `getVar(key)` | `get_var` (substrate) | returns `string \| null` |
111
111
  | `removeHeader(name)` | `remove_header` (`sip`) | on the stored A-leg INVITE |
112
- | `route(targets, strategy?, headers?)` | `route` (`sip`) | hand the call back to siphon with a routing decision: the targets are tried in order. Refused `invalid_state` while a `dial` still rings; `cancelDial` first |
112
+ | `route(targets, strategy?, headers?, options?)` | `route` (`sip`) | hand the call back to siphon with a routing decision: the targets are tried in order. A target's `route` is the route set its INVITE carries, topmost first, its `contactHost` the host of siphon's own Contact on that attempt, and its `verifyServer` whether that attempt's outbound TLS verifies the server certificate. A target's `contactUser` is the user part of siphon's own Contact on that attempt, and `options.callerContactUser` the caller-side user part. `options.callerContactHost` is the host of siphon's Contact toward the caller, as `contactHost` is on `answer`. Refused `invalid_state` while a `dial` still rings; `cancelDial` first |
113
113
  | `acceptRefer(options?)` | `accept_refer` (`sip`) | accept a pending inbound REFER (a `TransferRequested` event). `mode` is `"terminate"` (siphon dials the target), `"transparent"` (siphon relays the REFER) or `"controller"` (siphon answers `202` and dials nothing; this app moves the parties and reports with `completeRefer` within `timeout` seconds, default 60, at most 180). `target` is a URI string or `{ aor }`, a registered address-of-record dialled over the flow its phone registered on, every registered contact rung and the first to answer kept. `from`, `fromDisplay`, `pAssertedIdentity`, `privacy` and `headers` shape the leg the transfer dials, and `numberPolicy` (a number policy configured on the server) or `format` says how the numbers in them are written. `{ aor }` and the identity options go with `"terminate"`; `"controller"` takes `timeout` only, and `timeout` goes with no other mode. The server refuses the rest |
114
114
  | `rejectRefer(code, reason?)` | `reject_refer` (`sip`) | decline a pending inbound REFER with a final non-2xx |
115
115
  | `completeRefer(code, reason?)` | `complete_refer` (`sip`) | report how a transfer accepted with `acceptRefer({ mode: "controller" })` went: the referrer gets the sipfrag NOTIFY that ends its subscription, a 2xx for success. Report before releasing the referrer's leg |
116
116
  | `bridge(withChannel, options?)` | `bridge` (`sip`) | join two answered legs; the verdict arrives as `ChannelBridged` / `BridgeFailed` |
117
117
  | `unbridge(reason?)` | `unbridge` (`sip`) | break the bridge — both legs stay answered, owned and held |
118
- | `dial(targets, options?)` | `dial` (`sip`) | ring B-legs while the caller stays **unanswered** and this app keeps the channel. A target is `{uri}` (dialed as written) or `{aor}` (forked to every registered contact over its own flow); one naming both, or neither, throws. `onAnswer: "bridge"` rings phones for an **answered**, anchored caller and bridges the first to pick up, with `ringback` playing meanwhile; `ringback` without it throws |
118
+ | `dial(targets, options?)` | `dial` (`sip`) | ring B-legs while the caller stays **unanswered** and this app keeps the channel. A target is `{uri}` (dialed as written) or `{aor}` (forked to every registered contact over its own flow); one naming both, or neither, throws. A `{uri}` target may carry `route`, the route set its INVITE carries, topmost first (`["<sip:term@scscf.example;lr;odi=4f1c>"]`), which is how an IMS application server sends a session back through the S-CSCF; a `route` on `{aor}` throws. Either form may carry `contactHost`, the host siphon presents in its own Contact on that leg in place of the address it advertises, for a peer that identifies the tenant or account by that host (only the host changes), and `contactUser`, the user part of that otherwise userless Contact, for a peer that keys the account on it. `callerContactUser` names the caller's user part as `callerContactHost` does its host. Either form may also carry `verifyServer` (a boolean): verify the server certificate when that leg opens a new outbound TLS connection, over the gateway it routes to and the server's `tls.verify_server`. Either form may carry `profile`, the media profile for that branch alone over the dial's own; a target without one inherits the dial's (a connecting dial that names no `profile` anchors every branch or none, so either every target names one or none does). Either form may carry `rerouteAfterProgress` (a boolean, anything else throws; server default `true`): `false` ends a sequential dial on that target once it has rung, its ring timeout, busy or other failure being the dial's, for a hunt across several routes to one destination; a target that never rang, and a 503 with Retry-After, still move the hunt on, and a 6xx ends a sequential dial either way. `callerContactHost` in the options is the caller's side: the host of siphon's Contact toward the caller (on a bridging dial it can only repeat the one the caller's answer carried). `onAnswer: "bridge"` rings phones for an **answered**, anchored caller and bridges the first to pick up, with `ringback` playing meanwhile; `ringback` without it throws. `offer: "early"` (in the options, or on a target, which wins) sends each phone of a bridge dial an SDP offer in its INVITE, allocated on the media engine from the caller's media, for peers that refuse a delayed-offer INVITE; `"delayed"` is the server's default, and `offer` without `onAnswer: "bridge"` throws |
119
119
  | `cancelDial(reason?)` | `cancel_dial` (`sip`) | give up on the dial ringing for this call and leave the caller alone: the phones are CANCELled, each reported by `DialBranchFailed` (cause `cancelled`), and the dial ends in `DialFailed` with code 487. `reason` is the `cause` of a bridging dial's `DialFailed` (default `cancelled`). Refused `invalid_state` when nothing is ringing, and once a phone has answered and is being bridged |
120
120
  | `replacePeer(target, options?)` | `replace_peer` (`sip`) | swap one party of this answered call for a freshly dialled target, no REFER involved; the replaced leg stays up while the target rings. `target` is a URI string or `{ aor }`, and `options` takes `nextHop`, `replaceALeg`, `profile`, `timeout` and the identity options of `acceptRefer`. The verdict arrives as `PeerReplaced` / `ReplaceFailed` |
121
121
  | `recordStart(options?)` | `record_start` (`sip`) | record the call's decoded audio to a wav file; the reply names the `recordingId`, `RecordingFinished` says the file is closed. siphon-rtp only |
@@ -138,8 +138,8 @@ addressing one:
138
138
 
139
139
  | Method | Wire verb (`module`) | Notes |
140
140
  | --- | --- | --- |
141
- | `originate(channel, to, media, options?)` | `originate` (`sip`) | one URI, resolved as written; resolves once the INVITE is on the wire |
142
- | `originateAor(channel, aor, media, options?, ring?)` | `originate` (`sip`) | ring every phone registered at `aor` over its own flow and Path; first to answer wins. `ring` is `{ strategy?, totalTimeout? }`. Nobody registered is `not_found` (`no_contacts`); `drop` is refused while the phones ring, use `hangup` |
141
+ | `originate(channel, to, media, options?)` | `originate` (`sip`) | one URI, resolved as written; resolves once the INVITE is on the wire to the `Call` it placed, whose `nextEvent()` carries the answer, a rejection or the ring timeout. An id still live on this client is `conflict`, refused before anything is sent. `options.contactUser` adds that user part to siphon's own (otherwise userless) Contact on the call, as `options.contactHost` does the host. `options.contactHost` presents that host in siphon's own Contact on the call (on every leg of `originateAor`) |
142
+ | `originateAor(channel, aor, media, options?, ring?)` | `originate` (`sip`) | ring every phone registered at `aor` over its own flow and Path; first to answer wins. `ring` is `{ strategy?, totalTimeout? }`. The result carries the placed `call`. Nobody registered is `not_found` (`no_contacts`); `drop` is refused while the phones ring, use `hangup` |
143
143
 
144
144
  The server implements every verb in these tables. `unsupported_verb`
145
145
  (`error.isUnsupportedVerb()`) is what a verb answers when the configured media
package/dist/index.cjs CHANGED
@@ -77,6 +77,8 @@ var RESYNC = "resync";
77
77
  var DESCRIBE = "describe";
78
78
  var SET_VAR = "set_var";
79
79
  var GET_VAR = "get_var";
80
+ var REGISTRATIONS = "registrations";
81
+ var OUTBOUND_REGISTRATIONS = "outbound_registrations";
80
82
  function encodeCommand(id, module, verb, target, args) {
81
83
  const frame = { id, type: "command" };
82
84
  if (module != null) {
@@ -87,10 +89,10 @@ function encodeCommand(id, module, verb, target, args) {
87
89
  frame.args = args ?? null;
88
90
  return JSON.stringify(frame);
89
91
  }
90
- function parseInboundFrame(text) {
92
+ function parseInboundFrame(text2) {
91
93
  let value;
92
94
  try {
93
- value = JSON.parse(text);
95
+ value = JSON.parse(text2);
94
96
  } catch {
95
97
  return null;
96
98
  }
@@ -263,7 +265,7 @@ var Session = class {
263
265
  return Promise.reject(ControlError.closed());
264
266
  }
265
267
  const id = `c-${this.nextId.value++}`;
266
- const text = encodeCommand(id, module, verb, target, args);
268
+ const text2 = encodeCommand(id, module, verb, target, args);
267
269
  return new Promise((resolve, reject) => {
268
270
  const timer = setTimeout(() => {
269
271
  this.pending.delete(id);
@@ -271,7 +273,7 @@ var Session = class {
271
273
  }, this.replyTimeoutMs);
272
274
  this.pending.set(id, { resolve, reject, timer });
273
275
  try {
274
- this.socket.send(text);
276
+ this.socket.send(text2);
275
277
  } catch (error) {
276
278
  this.pending.delete(id);
277
279
  clearTimeout(timer);
@@ -279,8 +281,8 @@ var Session = class {
279
281
  }
280
282
  });
281
283
  }
282
- onMessage(text) {
283
- const frame = parseInboundFrame(text);
284
+ onMessage(text2) {
285
+ const frame = parseInboundFrame(text2);
284
286
  if (frame === null) {
285
287
  return;
286
288
  }
@@ -649,6 +651,12 @@ function responseArgs(options) {
649
651
  if (options.contentType !== void 0) {
650
652
  args.content_type = options.contentType;
651
653
  }
654
+ if (options.contactHost !== void 0) {
655
+ args.contact_host = options.contactHost;
656
+ }
657
+ if (options.contactUser !== void 0) {
658
+ args.contact_user = options.contactUser;
659
+ }
652
660
  return args;
653
661
  }
654
662
  function insertTransferIdentity(args, identity) {
@@ -662,10 +670,42 @@ function insertTransferIdentity(args, identity) {
662
670
  if (identity?.format !== void 0) args.format = identity.format;
663
671
  if (identity?.headers !== void 0) args.headers = identity.headers;
664
672
  }
673
+ function verifyServerToWire(verifyServer) {
674
+ if (verifyServer === void 0 || verifyServer === null) return void 0;
675
+ if (typeof verifyServer !== "boolean") {
676
+ throw new TypeError(`a target's "verifyServer" is a boolean`);
677
+ }
678
+ return verifyServer;
679
+ }
680
+ function contactHostToWire(contactHost) {
681
+ if (contactHost === void 0 || contactHost === null) return void 0;
682
+ if (typeof contactHost !== "string") {
683
+ throw new TypeError(`a target's "contactHost" is a hostname or IP address string`);
684
+ }
685
+ return contactHost;
686
+ }
687
+ function contactUserToWire(contactUser) {
688
+ if (contactUser === void 0 || contactUser === null) return void 0;
689
+ if (typeof contactUser !== "string") {
690
+ throw new TypeError(`a target's "contactUser" is a SIP URI user string`);
691
+ }
692
+ return contactUser;
693
+ }
694
+ function routeSetToWire(route) {
695
+ if (route === void 0 || route === null) return void 0;
696
+ if (!Array.isArray(route) || route.some((entry) => typeof entry !== "string")) {
697
+ throw new TypeError(`a target's "route" is an array of Route entry strings`);
698
+ }
699
+ return route.length === 0 ? void 0 : [...route];
700
+ }
665
701
  function routeTargetToWire(target) {
666
702
  if (typeof target === "string") {
667
703
  return target;
668
704
  }
705
+ const route = routeSetToWire(target.route);
706
+ const contactHost = contactHostToWire(target.contactHost);
707
+ const contactUser = contactUserToWire(target.contactUser);
708
+ const verifyServer = verifyServerToWire(target.verifyServer);
669
709
  const object = { uri: target.uri };
670
710
  if (target.nextHop !== void 0) {
671
711
  object.next_hop = target.nextHop;
@@ -679,6 +719,18 @@ function routeTargetToWire(target) {
679
719
  if (target.rerouteAfterProgress === true) {
680
720
  object.reroute_after_progress = true;
681
721
  }
722
+ if (route !== void 0) {
723
+ object.route = route;
724
+ }
725
+ if (contactHost !== void 0) {
726
+ object.contact_host = contactHost;
727
+ }
728
+ if (contactUser !== void 0) {
729
+ object.contact_user = contactUser;
730
+ }
731
+ if (verifyServer !== void 0) {
732
+ object.verify_server = verifyServer;
733
+ }
682
734
  return object;
683
735
  }
684
736
  function stringValue(result) {
@@ -690,6 +742,10 @@ function stringValue(result) {
690
742
  }
691
743
  return null;
692
744
  }
745
+ function text(result, name) {
746
+ const value = result?.[name];
747
+ return typeof value === "string" ? value : void 0;
748
+ }
693
749
  function originateArgs(channel, to, media, options) {
694
750
  return originateCommonArgs({ channel, to }, media, options);
695
751
  }
@@ -723,6 +779,8 @@ function originateCommonArgs(args, media, options) {
723
779
  if (options.timeout !== void 0) args.timeout = options.timeout;
724
780
  if (options.onLost !== void 0) args.on_lost = options.onLost;
725
781
  if (options.vars !== void 0) args.vars = options.vars;
782
+ if (options.contactHost !== void 0) args.contact_host = options.contactHost;
783
+ if (options.contactUser !== void 0) args.contact_user = options.contactUser;
726
784
  if (options.sessionTimer !== void 0) {
727
785
  const timer = {};
728
786
  const { expires, minSe, refresher } = options.sessionTimer;
@@ -739,6 +797,22 @@ function dialTargetToWire(target) {
739
797
  const nextHop = target.nextHop;
740
798
  const headers = target.headers;
741
799
  const to = target.to;
800
+ const route = routeSetToWire(target.route);
801
+ const contactHost = contactHostToWire(target.contactHost);
802
+ const contactUser = contactUserToWire(target.contactUser);
803
+ const rerouteAfterProgress = target.rerouteAfterProgress;
804
+ if (rerouteAfterProgress !== void 0 && typeof rerouteAfterProgress !== "boolean") {
805
+ throw new TypeError(`a dial target's "rerouteAfterProgress" is a boolean`);
806
+ }
807
+ const profile = target.profile ?? void 0;
808
+ if (profile !== void 0 && typeof profile !== "string") {
809
+ throw new TypeError(`a dial target's "profile" is a media profile name string`);
810
+ }
811
+ const offer = target.offer ?? void 0;
812
+ if (offer !== void 0 && offer !== "early" && offer !== "delayed") {
813
+ throw new TypeError(`a dial target's "offer" is "early" or "delayed"`);
814
+ }
815
+ const verifyServer = verifyServerToWire(target.verifyServer);
742
816
  if (to !== void 0 && typeof to !== "string") {
743
817
  throw new TypeError(`a dial target's "to" is a SIP URI string`);
744
818
  }
@@ -753,23 +827,58 @@ function dialTargetToWire(target) {
753
827
  `an aor target takes no "nextHop": each of its branches routes over its own contact's captured flow`
754
828
  );
755
829
  }
830
+ if (route !== void 0) {
831
+ throw new TypeError(
832
+ `an aor target takes no "route": each of its branches follows its own contact's Path`
833
+ );
834
+ }
756
835
  const object2 = { aor };
757
836
  if (headers !== void 0) object2.headers = headers;
758
837
  if (to !== void 0) object2.to = to;
838
+ if (contactHost !== void 0) object2.contact_host = contactHost;
839
+ if (contactUser !== void 0) object2.contact_user = contactUser;
840
+ if (rerouteAfterProgress !== void 0) {
841
+ object2.reroute_after_progress = rerouteAfterProgress;
842
+ }
843
+ if (profile !== void 0) object2.profile = profile;
844
+ if (offer !== void 0) object2.offer = offer;
845
+ if (verifyServer !== void 0) object2.verify_server = verifyServer;
759
846
  return object2;
760
847
  }
761
848
  if (typeof uri !== "string") {
762
849
  throw new TypeError('a dial target requires a string "uri" or "aor"');
763
850
  }
764
- if (nextHop === void 0 && headers === void 0 && to === void 0) return uri;
851
+ if (nextHop === void 0 && headers === void 0 && to === void 0 && route === void 0 && contactHost === void 0 && contactUser === void 0 && rerouteAfterProgress === void 0 && profile === void 0 && offer === void 0 && verifyServer === void 0) {
852
+ return uri;
853
+ }
765
854
  const object = { uri };
766
855
  if (nextHop !== void 0) object.next_hop = nextHop;
767
856
  if (headers !== void 0) object.headers = headers;
768
857
  if (to !== void 0) object.to = to;
858
+ if (route !== void 0) object.route = route;
859
+ if (contactHost !== void 0) object.contact_host = contactHost;
860
+ if (contactUser !== void 0) object.contact_user = contactUser;
861
+ if (rerouteAfterProgress !== void 0) {
862
+ object.reroute_after_progress = rerouteAfterProgress;
863
+ }
864
+ if (profile !== void 0) object.profile = profile;
865
+ if (offer !== void 0) object.offer = offer;
866
+ if (verifyServer !== void 0) object.verify_server = verifyServer;
769
867
  return object;
770
868
  }
771
869
  function dialArgs(targets, options) {
772
870
  const args = { targets: targets.map(dialTargetToWire) };
871
+ const targetOffer = targets.some(
872
+ (target) => target.offer !== void 0
873
+ );
874
+ if ((options?.offer !== void 0 || targetOffer) && options?.onAnswer !== "bridge") {
875
+ throw new TypeError(
876
+ `dial "offer" requires onAnswer: "bridge" \u2014 a connecting dial's branches carry the caller's own offer, and siphon refuses it there`
877
+ );
878
+ }
879
+ if (options?.offer !== void 0 && options.offer !== "early" && options.offer !== "delayed") {
880
+ throw new TypeError('dial "offer" is "early" or "delayed"');
881
+ }
773
882
  if (!options) return args;
774
883
  if (options.strategy !== void 0) args.strategy = options.strategy;
775
884
  if (options.timeout !== void 0) args.timeout = options.timeout;
@@ -788,6 +897,13 @@ function dialArgs(targets, options) {
788
897
  }
789
898
  if (options.onAnswer !== void 0) args.on_answer = options.onAnswer;
790
899
  if (options.ringback !== void 0) args.ringback = options.ringback;
900
+ if (options.offer !== void 0) args.offer = options.offer;
901
+ if (options.callerContactHost !== void 0) {
902
+ args.caller_contact_host = options.callerContactHost;
903
+ }
904
+ if (options.callerContactUser !== void 0) {
905
+ args.caller_contact_user = options.callerContactUser;
906
+ }
791
907
  return args;
792
908
  }
793
909
  function branchList(value) {
@@ -930,6 +1046,12 @@ var Call = class {
930
1046
  if (options?.wsUri !== void 0) {
931
1047
  args.ws_uri = options.wsUri;
932
1048
  }
1049
+ if (options?.contactHost !== void 0) {
1050
+ args.contact_host = options.contactHost;
1051
+ }
1052
+ if (options?.contactUser !== void 0) {
1053
+ args.contact_user = options.contactUser;
1054
+ }
933
1055
  await this.sip(SipVerb.Answer, args);
934
1056
  }
935
1057
  /**
@@ -941,8 +1063,15 @@ var Call = class {
941
1063
  * then {@link Call.answer}; open an early-media path with
942
1064
  * {@link Call.progress}.
943
1065
  */
944
- async ring(reason) {
945
- await this.sip(SipVerb.Ring, reason !== void 0 ? { reason } : {});
1066
+ async ring(reason, options) {
1067
+ const args = reason !== void 0 ? { reason } : {};
1068
+ if (options?.contactHost !== void 0) {
1069
+ args.contact_host = options.contactHost;
1070
+ }
1071
+ if (options?.contactUser !== void 0) {
1072
+ args.contact_user = options.contactUser;
1073
+ }
1074
+ await this.sip(SipVerb.Ring, args);
946
1075
  }
947
1076
  /**
948
1077
  * Send a UAS 1xx, optionally opening an early-media path with SDP (default
@@ -1074,7 +1203,7 @@ var Call = class {
1074
1203
  *
1075
1204
  * `targets` is a non-empty list of carriers tried cheapest-first: each entry
1076
1205
  * is a bare URI string or a {@link RouteTargetObject}
1077
- * (`{uri, nextHop?, headers?, timeout?, rerouteAfterProgress?}`). A target
1206
+ * (`{uri, nextHop?, headers?, timeout?, rerouteAfterProgress?, route?, contactHost?, contactUser?}`). A target
1078
1207
  * that has shown progress keeps the call past its `timeout` unless it sets
1079
1208
  * `rerouteAfterProgress`. `strategy` defaults to
1080
1209
  * `"sequential"` (v1 supports only sequential/single — anything else rejects
@@ -1085,7 +1214,7 @@ var Call = class {
1085
1214
  * empty / invalid `targets` list rejects with `code === "bad_request"`; a call
1086
1215
  * that is already gone rejects with `code === "not_found"`.
1087
1216
  */
1088
- async route(targets, strategy = "sequential", headers) {
1217
+ async route(targets, strategy = "sequential", headers, options) {
1089
1218
  const args = {
1090
1219
  targets: targets.map(routeTargetToWire),
1091
1220
  strategy
@@ -1093,6 +1222,12 @@ var Call = class {
1093
1222
  if (headers !== void 0) {
1094
1223
  args.headers = headers;
1095
1224
  }
1225
+ if (options?.callerContactHost !== void 0) {
1226
+ args.caller_contact_host = options.callerContactHost;
1227
+ }
1228
+ if (options?.callerContactUser !== void 0) {
1229
+ args.caller_contact_user = options.callerContactUser;
1230
+ }
1096
1231
  return this.sip(SipVerb.Route, args);
1097
1232
  }
1098
1233
  /**
@@ -1151,7 +1286,7 @@ var Call = class {
1151
1286
  */
1152
1287
  async dial(targets, options) {
1153
1288
  const result = await this.sip(SipVerb.Dial, dialArgs(targets, options));
1154
- const text = (name) => {
1289
+ const text2 = (name) => {
1155
1290
  const value = result?.[name];
1156
1291
  return typeof value === "string" ? value : void 0;
1157
1292
  };
@@ -1162,17 +1297,21 @@ var Call = class {
1162
1297
  return {
1163
1298
  // The server echoes the channel back; fall back to the one addressed
1164
1299
  // rather than returning an empty id.
1165
- channel: text("channel") ?? this.channelId,
1300
+ channel: text2("channel") ?? this.channelId,
1166
1301
  targets: count("targets"),
1167
- strategy: text("strategy"),
1302
+ strategy: text2("strategy"),
1168
1303
  timeout: count("timeout"),
1169
- onAnswer: text("on_answer"),
1170
- groupId: text("group_id"),
1304
+ onAnswer: text2("on_answer"),
1305
+ groupId: text2("group_id"),
1171
1306
  totalTimeout: count("total_timeout"),
1172
1307
  ringback: (() => {
1173
1308
  const value = result?.ringback;
1174
1309
  return typeof value === "string" || typeof value === "boolean" ? value : void 0;
1175
1310
  })(),
1311
+ offer: (() => {
1312
+ const value = result?.offer;
1313
+ return value === "early" || value === "delayed" ? value : void 0;
1314
+ })(),
1176
1315
  branches: branchList(result?.branches)
1177
1316
  };
1178
1317
  }
@@ -1472,13 +1611,13 @@ var Call = class {
1472
1611
  SipVerb.RecordStart,
1473
1612
  recordStartArgs(options)
1474
1613
  );
1475
- const text = (name) => {
1614
+ const text2 = (name) => {
1476
1615
  const value = result?.[name];
1477
1616
  return typeof value === "string" ? value : void 0;
1478
1617
  };
1479
1618
  return {
1480
- channel: text("channel") ?? this.channelId,
1481
- recordingId: text("recording_id")
1619
+ channel: text2("channel") ?? this.channelId,
1620
+ recordingId: text2("recording_id")
1482
1621
  };
1483
1622
  }
1484
1623
  /**
@@ -1597,6 +1736,25 @@ var SipFacade = class {
1597
1736
  );
1598
1737
  this.dispatch(call);
1599
1738
  }
1739
+ /**
1740
+ * Open the event queue of a call this client is placing, before its
1741
+ * `originate` goes out: siphon sends no `StasisStart` for it, and its first
1742
+ * event can overtake the reply. `null` when the channel is already live here,
1743
+ * which must not be taken over.
1744
+ */
1745
+ openChannel(channel) {
1746
+ if (this.channels.has(channel)) {
1747
+ return null;
1748
+ }
1749
+ const queue = new AsyncQueue();
1750
+ this.channels.set(channel, queue);
1751
+ return queue;
1752
+ }
1753
+ /** Close a channel {@link SipFacade.openChannel} opened for a refused originate. */
1754
+ closeChannel(channel) {
1755
+ this.channels.get(channel)?.close();
1756
+ this.channels.delete(channel);
1757
+ }
1600
1758
  route(channel, event) {
1601
1759
  this.channels.get(channel)?.push(event);
1602
1760
  }
@@ -1664,13 +1822,52 @@ var SipClient = class _SipClient {
1664
1822
  describe() {
1665
1823
  return this.client.describe();
1666
1824
  }
1825
+ /**
1826
+ * Everything the registrar holds now and the `seq` it is current to
1827
+ * (`registrations`; the app must subscribe to `registration`). Fetches every
1828
+ * page and merges them, keeping the first page's `seq`. Ask on connecting
1829
+ * and whenever a `RegistrationChanged` `seq` skips a number: replace your
1830
+ * copy with the reply and apply only events numbered above it.
1831
+ */
1832
+ async registrations() {
1833
+ return this.everyPage(REGISTRATIONS);
1834
+ }
1835
+ /**
1836
+ * Every outbound registration's state and its `seq`
1837
+ * (`outbound_registrations`; the app must subscribe to `outbound_registration`).
1838
+ * Fetches every page, as {@link SipClient.registrations} does.
1839
+ */
1840
+ async outboundRegistrations() {
1841
+ return this.everyPage(OUTBOUND_REGISTRATIONS);
1842
+ }
1843
+ async everyPage(verb) {
1844
+ const whole = await this.client.command(null, verb, null, null);
1845
+ let after = whole.next ?? null;
1846
+ while (after !== null) {
1847
+ const page = await this.client.command(null, verb, null, { after });
1848
+ whole.registrations.push(...page.registrations);
1849
+ const next = page.next ?? null;
1850
+ if (next !== null && next <= after) {
1851
+ throw new Error(`${verb}: the page after ${after} named ${next} as the next`);
1852
+ }
1853
+ after = next;
1854
+ }
1855
+ whole.next = null;
1856
+ return whole;
1857
+ }
1667
1858
  /**
1668
1859
  * Place an outbound call under a caller-supplied channel id.
1669
1860
  *
1670
1861
  * The one verb that *creates* a channel rather than addressing one, which is
1671
1862
  * why it lives here and not on {@link Call}. It resolves as soon as the
1672
- * INVITE is on the wire — the call is `calling`, and the answer, failure or
1673
- * timeout arrives later as an event on the channel.
1863
+ * INVITE is on the wire — the call is `calling` — to the {@link Call} it
1864
+ * placed: the answer, failure or timeout arrives on {@link Call.nextEvent},
1865
+ * exactly as a handed-over call's does, and `hangup` CANCELs or BYEs it.
1866
+ *
1867
+ * siphon sends no `StasisStart` for a channel its controller created, so the
1868
+ * channel is opened here before the command goes out (a fast 180 can
1869
+ * overtake the reply). An id still live on this client rejects with
1870
+ * `code === "conflict"` before anything is sent.
1674
1871
  *
1675
1872
  * ```ts
1676
1873
  * const call = await client.originate(
@@ -1682,23 +1879,8 @@ var SipClient = class _SipClient {
1682
1879
  * ```
1683
1880
  */
1684
1881
  async originate(channel, to, media, options) {
1685
- const result = await this.client.command(
1686
- MODULE_SIP,
1687
- "originate",
1688
- null,
1689
- originateArgs(channel, to, media, options)
1690
- );
1691
- const text = (name) => {
1692
- const value = result?.[name];
1693
- return typeof value === "string" ? value : void 0;
1694
- };
1695
- return {
1696
- // The server echoes the id back; fall back to the one we asked for
1697
- // rather than returning an empty channel a caller cannot address.
1698
- channel: text("channel") ?? channel,
1699
- callId: text("call_id"),
1700
- sipCallId: text("sip_call_id")
1701
- };
1882
+ const { result, queue } = await this.place(channel, originateArgs(channel, to, media, options));
1883
+ return this.placedCall(channel, text(result, "call_id"), text(result, "sip_call_id"), result, queue);
1702
1884
  }
1703
1885
  /**
1704
1886
  * Ring every phone registered at `aor` under a caller-supplied channel id —
@@ -1733,29 +1915,51 @@ var SipClient = class _SipClient {
1733
1915
  * ```
1734
1916
  */
1735
1917
  async originateAor(channel, aor, media, options, ring) {
1736
- const result = await this.client.command(
1737
- MODULE_SIP,
1738
- "originate",
1739
- null,
1918
+ const { result, queue } = await this.place(
1919
+ channel,
1740
1920
  originateAorArgs(channel, aor, media, options, ring)
1741
1921
  );
1742
- const text = (name) => {
1743
- const value = result?.[name];
1744
- return typeof value === "string" ? value : void 0;
1745
- };
1746
- const count = (name) => {
1747
- const value = result?.[name];
1748
- return typeof value === "number" ? value : void 0;
1749
- };
1922
+ const groupId = text(result, "group_id");
1923
+ const totalTimeout = result?.total_timeout;
1750
1924
  return {
1751
- channel: text("channel") ?? channel,
1752
- groupId: text("group_id"),
1753
- aor: text("aor"),
1754
- strategy: text("strategy"),
1755
- totalTimeout: count("total_timeout"),
1925
+ // The server echoes the id back; fall back to the one we asked for
1926
+ // rather than returning an empty channel a caller cannot address.
1927
+ channel: text(result, "channel") ?? channel,
1928
+ // Until a phone answers, the group stands in for the call, as its events say.
1929
+ call: this.placedCall(channel, groupId, groupId, result, queue),
1930
+ groupId,
1931
+ aor: text(result, "aor"),
1932
+ strategy: text(result, "strategy"),
1933
+ totalTimeout: typeof totalTimeout === "number" ? totalTimeout : void 0,
1756
1934
  branches: branchList(result?.branches) ?? []
1757
1935
  };
1758
1936
  }
1937
+ /** Open `channel`, send the originate, and close it again if the server refuses. */
1938
+ async place(channel, args) {
1939
+ const queue = this.facade.openChannel(channel);
1940
+ if (queue === null) {
1941
+ throw ControlError.command("conflict", `channel ${channel} is already live on this client`);
1942
+ }
1943
+ try {
1944
+ const result = await this.client.command(MODULE_SIP, "originate", null, args);
1945
+ return { result, queue };
1946
+ } catch (error) {
1947
+ this.facade.closeChannel(channel);
1948
+ throw error;
1949
+ }
1950
+ }
1951
+ placedCall(channel, callId, sipCallId, reply, queue) {
1952
+ return new Call(
1953
+ this.client.commander(),
1954
+ channel,
1955
+ callId ?? null,
1956
+ sipCallId ?? null,
1957
+ null,
1958
+ reply,
1959
+ false,
1960
+ queue
1961
+ );
1962
+ }
1759
1963
  /** Send a raw command on any module (the generic escape hatch). */
1760
1964
  command(module, verb, target, args) {
1761
1965
  return this.client.command(module, verb, target, args);
@@ -1816,7 +2020,9 @@ exports.HELLO = HELLO;
1816
2020
  exports.MODULE_SIP = MODULE_SIP;
1817
2021
  exports.MODULE_SMPP = MODULE_SMPP;
1818
2022
  exports.MODULE_SS7 = MODULE_SS7;
2023
+ exports.OUTBOUND_REGISTRATIONS = OUTBOUND_REGISTRATIONS;
1819
2024
  exports.PROTOCOL_VERSION = PROTOCOL_VERSION;
2025
+ exports.REGISTRATIONS = REGISTRATIONS;
1820
2026
  exports.RESYNC = RESYNC;
1821
2027
  exports.SET_VAR = SET_VAR;
1822
2028
  exports.SUBPROTOCOL = SUBPROTOCOL;