@siphon-project/control 0.9.0 → 0.10.1

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. A target's `route` is the route set its INVITE carries, topmost first. 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. 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. `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,7 +138,7 @@ 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 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 |
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
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`
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) {
@@ -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,6 +670,27 @@ 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
+ }
665
694
  function routeSetToWire(route) {
666
695
  if (route === void 0 || route === null) return void 0;
667
696
  if (!Array.isArray(route) || route.some((entry) => typeof entry !== "string")) {
@@ -674,6 +703,9 @@ function routeTargetToWire(target) {
674
703
  return target;
675
704
  }
676
705
  const route = routeSetToWire(target.route);
706
+ const contactHost = contactHostToWire(target.contactHost);
707
+ const contactUser = contactUserToWire(target.contactUser);
708
+ const verifyServer = verifyServerToWire(target.verifyServer);
677
709
  const object = { uri: target.uri };
678
710
  if (target.nextHop !== void 0) {
679
711
  object.next_hop = target.nextHop;
@@ -690,6 +722,15 @@ function routeTargetToWire(target) {
690
722
  if (route !== void 0) {
691
723
  object.route = route;
692
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
+ }
693
734
  return object;
694
735
  }
695
736
  function stringValue(result) {
@@ -738,6 +779,8 @@ function originateCommonArgs(args, media, options) {
738
779
  if (options.timeout !== void 0) args.timeout = options.timeout;
739
780
  if (options.onLost !== void 0) args.on_lost = options.onLost;
740
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;
741
784
  if (options.sessionTimer !== void 0) {
742
785
  const timer = {};
743
786
  const { expires, minSe, refresher } = options.sessionTimer;
@@ -755,6 +798,21 @@ function dialTargetToWire(target) {
755
798
  const headers = target.headers;
756
799
  const to = target.to;
757
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);
758
816
  if (to !== void 0 && typeof to !== "string") {
759
817
  throw new TypeError(`a dial target's "to" is a SIP URI string`);
760
818
  }
@@ -777,12 +835,20 @@ function dialTargetToWire(target) {
777
835
  const object2 = { aor };
778
836
  if (headers !== void 0) object2.headers = headers;
779
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;
780
846
  return object2;
781
847
  }
782
848
  if (typeof uri !== "string") {
783
849
  throw new TypeError('a dial target requires a string "uri" or "aor"');
784
850
  }
785
- if (nextHop === void 0 && headers === void 0 && to === void 0 && route === void 0) {
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) {
786
852
  return uri;
787
853
  }
788
854
  const object = { uri };
@@ -790,10 +856,29 @@ function dialTargetToWire(target) {
790
856
  if (headers !== void 0) object.headers = headers;
791
857
  if (to !== void 0) object.to = to;
792
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;
793
867
  return object;
794
868
  }
795
869
  function dialArgs(targets, options) {
796
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
+ }
797
882
  if (!options) return args;
798
883
  if (options.strategy !== void 0) args.strategy = options.strategy;
799
884
  if (options.timeout !== void 0) args.timeout = options.timeout;
@@ -812,6 +897,13 @@ function dialArgs(targets, options) {
812
897
  }
813
898
  if (options.onAnswer !== void 0) args.on_answer = options.onAnswer;
814
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
+ }
815
907
  return args;
816
908
  }
817
909
  function branchList(value) {
@@ -954,6 +1046,12 @@ var Call = class {
954
1046
  if (options?.wsUri !== void 0) {
955
1047
  args.ws_uri = options.wsUri;
956
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
+ }
957
1055
  await this.sip(SipVerb.Answer, args);
958
1056
  }
959
1057
  /**
@@ -965,8 +1063,15 @@ var Call = class {
965
1063
  * then {@link Call.answer}; open an early-media path with
966
1064
  * {@link Call.progress}.
967
1065
  */
968
- async ring(reason) {
969
- 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);
970
1075
  }
971
1076
  /**
972
1077
  * Send a UAS 1xx, optionally opening an early-media path with SDP (default
@@ -1098,7 +1203,7 @@ var Call = class {
1098
1203
  *
1099
1204
  * `targets` is a non-empty list of carriers tried cheapest-first: each entry
1100
1205
  * is a bare URI string or a {@link RouteTargetObject}
1101
- * (`{uri, nextHop?, headers?, timeout?, rerouteAfterProgress?, route?}`). A target
1206
+ * (`{uri, nextHop?, headers?, timeout?, rerouteAfterProgress?, route?, contactHost?, contactUser?}`). A target
1102
1207
  * that has shown progress keeps the call past its `timeout` unless it sets
1103
1208
  * `rerouteAfterProgress`. `strategy` defaults to
1104
1209
  * `"sequential"` (v1 supports only sequential/single — anything else rejects
@@ -1109,7 +1214,7 @@ var Call = class {
1109
1214
  * empty / invalid `targets` list rejects with `code === "bad_request"`; a call
1110
1215
  * that is already gone rejects with `code === "not_found"`.
1111
1216
  */
1112
- async route(targets, strategy = "sequential", headers) {
1217
+ async route(targets, strategy = "sequential", headers, options) {
1113
1218
  const args = {
1114
1219
  targets: targets.map(routeTargetToWire),
1115
1220
  strategy
@@ -1117,6 +1222,12 @@ var Call = class {
1117
1222
  if (headers !== void 0) {
1118
1223
  args.headers = headers;
1119
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
+ }
1120
1231
  return this.sip(SipVerb.Route, args);
1121
1232
  }
1122
1233
  /**
@@ -1197,6 +1308,10 @@ var Call = class {
1197
1308
  const value = result?.ringback;
1198
1309
  return typeof value === "string" || typeof value === "boolean" ? value : void 0;
1199
1310
  })(),
1311
+ offer: (() => {
1312
+ const value = result?.offer;
1313
+ return value === "early" || value === "delayed" ? value : void 0;
1314
+ })(),
1200
1315
  branches: branchList(result?.branches)
1201
1316
  };
1202
1317
  }
@@ -1707,6 +1822,39 @@ var SipClient = class _SipClient {
1707
1822
  describe() {
1708
1823
  return this.client.describe();
1709
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
+ }
1710
1858
  /**
1711
1859
  * Place an outbound call under a caller-supplied channel id.
1712
1860
  *
@@ -1872,7 +2020,9 @@ exports.HELLO = HELLO;
1872
2020
  exports.MODULE_SIP = MODULE_SIP;
1873
2021
  exports.MODULE_SMPP = MODULE_SMPP;
1874
2022
  exports.MODULE_SS7 = MODULE_SS7;
2023
+ exports.OUTBOUND_REGISTRATIONS = OUTBOUND_REGISTRATIONS;
1875
2024
  exports.PROTOCOL_VERSION = PROTOCOL_VERSION;
2025
+ exports.REGISTRATIONS = REGISTRATIONS;
1876
2026
  exports.RESYNC = RESYNC;
1877
2027
  exports.SET_VAR = SET_VAR;
1878
2028
  exports.SUBPROTOCOL = SUBPROTOCOL;