@dszp/netsapiens-lib 0.7.0 → 0.9.0

package/src/inventory.ts

@@ -38,6 +38,35 @@
  * case-insensitively, and on nothing else — not the `dial-rule-description`, which is a portal-written
  * note an operator can edit. **With no hosts supplied nothing is a fax line**, because a library that
  * hardcoded one deployment's fax server would be wrong everywhere else.
+ *
+ * ## E911: the ENDPOINT is the billable unit, the address is a location
+ *
+ * An **Emergency Endpoint** is a callback number, a caller name, a billing address and a vendor. It is
+ * what the E911 carrier routes on and what it bills per, and it is counted as `e911Endpoints`. An
+ * **Emergency Address** is a dispatchable location forwarded to responders; several of them can sit
+ * under one endpoint, and nobody bills them. `e911Addresses` stays, as information.
+ *
+ * Users, devices and sites point at an endpoint through their Emergency Caller ID
+ * (`caller-id-number-emergency`) matching the endpoint's callback number. This library then INFERS two
+ * fallbacks for a blank field — a blank `emergency-address-id` reads as the domain default address, and
+ * a blank caller ID reads as that address's endpoint. **Neither is a measured platform behaviour**; see
+ * the ⚠️ on {@link EmergencyModel} for what is known and what is assumed. They live in
+ * {@link resolveEmergency} alone, so the counter and `attribution.ts` cannot disagree about them, and
+ * they fail closed: nothing to inherit leaves a user referencing nothing rather than referencing a
+ * guess.
+ *
+ * ## Legacy emergency numbers, which have no API object at all
+ *
+ * A domain still on the legacy provisioning model has no endpoint records. Every one of its users
+ * carries an EMPTY `emergency-address-id` and a `caller-id-number-emergency` set to one of a handful of
+ * DIDs — and the carrier bills per one of those DIDs, exactly as it bills per endpoint on the new
+ * model. `e911Legacy` is therefore the count of DISTINCT such numbers, and a rulebook can count the two
+ * dimensions together so one retail E911 line pays for either model.
+ *
+ * A number that IS an endpoint callback is excluded, because a half-migrated domain that counted it in
+ * both dimensions would bill the same place twice. That exclusion is also the precondition: with no
+ * endpoint list read there is nothing to exclude against, so `e911Legacy` is 0 whenever
+ * `snapshot.addressEndpoints` is `undefined` rather than an array. See {@link DomainInventory.e911Legacy}.
  */
 import type { Rec, Snapshot } from './model.js';
 
@@ -61,10 +90,12 @@ export interface DomainInventory {
   /** Extensions whose `voicemail-transcription-enabled` is anything but empty or `no`. */
   transcriptionEnabled: number;
   /**
-   * Extensions with a Microsoft Teams connector device — one whose device NAME is the extension number
-   * followed by `t` (`1000t`), which is how the TeamMate connector registers. See {@link deviceName} for
-   * which field that name is read from, and why reading the wrong one silently miscounted this.
-   * That device is NOT counted under `devices`: it is a connector, not a handset.
+   * Extensions with a Microsoft Teams connector device — one whose device-name SUFFIX the legend marks
+   * `teams: true`, which under {@link DEFAULT_DEVICE_SUFFIXES} is the extension number followed by `t`
+   * (`1000t`), how the TeamMate connector registers. See {@link deviceName} for which field that name is
+   * read from, and why reading the wrong one silently miscounted this. That device is NOT counted under
+   * `devices`: it is a connector, not a handset. A supplied legend with no `teams` suffix — a deployment
+   * without TeamMate — leaves this 0 and counts every device as a handset.
    */
   teamsConnected: number;
   /**
@@ -78,8 +109,25 @@ export interface DomainInventory {
    * numbers this returned before 0.7.0, unchanged.
    */
   dids: { total: number; tollFree: number; local: number; fax: number; all: number };
-  /** E911 address records on the domain. */
+  /**
+   * E911 address records on the domain — dispatchable LOCATIONS, and information only. The billable
+   * unit is {@link DomainInventory.e911Endpoints}; see the module doc.
+   */
   e911Addresses: number;
+  /** Provisioned Emergency Endpoints — the unit the E911 carrier bills per. */
+  e911Endpoints: number;
+  /**
+   * Distinct legacy emergency numbers — the pre-endpoint model, which has no API object of its own.
+   * Comparable with {@link DomainInventory.e911Endpoints}, and never overlapping it **provided the
+   * snapshot carries an endpoint list**: the two are kept apart by excluding numbers that are already
+   * endpoint callbacks, which needs the endpoints to have been read.
+   *
+   * So this is **0 whenever `snapshot.addressEndpoints` is `undefined`** — the fetch never asked, and a
+   * count derived from the users alone would report a fully-migrated domain's every emergency caller ID
+   * as a line to bill for. An empty ARRAY is the other fact — asked, and the domain has none — and that
+   * one does support a count. Fetch with `includeAddresses: true` (see `fetchDomainSnapshot`).
+   */
+  e911Legacy: number;
   /** SMS-enabled numbers on the domain. */
   smsNumbers: number;
   /** Devices belonging to real extensions only — a system user's device is not a seat. */
@@ -122,8 +170,15 @@ export interface ExtensionItem {
    * has no model), and `teams` marks the connector entry itself. `deviceCount`/`deviceModels`/`teams`
    * above stay handset-only; this list is the one place a connector's own row shows up. Never the MAC
    * or the SIP password.
+   *
+   * `suffix` is what the name carries AFTER the extension number (`1001wp` on ext `1001` → `wp`; a bare
+   * `1001` → `''`), lower-cased; a name that does not start with the extension has no suffix, and neither
+   * does a device on an extension with no number. `kind` is that suffix's label from the legend in
+   * {@link InventoryOptions.deviceSuffixes} — `''` when the suffix is empty OR when the legend does not
+   * carry it, because an unlisted suffix is a name this deployment has not explained, not a device type
+   * to guess at.
    */
-  devices: Array<{ name: string; model: string; teams: boolean }>;
+  devices: Array<{ name: string; model: string; teams: boolean; suffix: string; kind: string }>;
   /** `deviceCount > 0 || teams` — has a device of any kind, handset or connector. */
   anyDevice: boolean;
 }
@@ -145,8 +200,40 @@ export interface NumberItem {
   description: string;
 }
 export interface AddressItem { key: string /* addr:<emergency-address-id>, or addr:~<hash> when the id is blank */; label: string }
+/**
+ * One provisioned Emergency Endpoint — the thing the E911 carrier bills per.
+ *
+ * An allowlist like every other item: the callback, the caller name, and the billing address reduced to
+ * the ONE line {@link AddressItem} already exposes. The endpoint record also carries a geolocation XML
+ * and a public IP, and neither belongs in front of a billing operator.
+ */
+export interface EndpointItem {
+  /** `e911:<callback>` — the digits, so a device's 11-digit form and the record's 10-digit form are one
+   *  key. `e911:~<hash>` when the record names no callback at all. */
+  key: string;
+  /** The callback number, digits only ({@link emergencyDigits}); `''` when the record has none. */
+  callback: string;
+  /** `caller-name` — who the carrier announces; `''` when blank. */
+  callerName: string;
+  /** Street and city, one line — no more of the billing address than the address list already shows. */
+  billingAddress: string;
+  /** How many users the RECORD says are configured on it (`count-users-configured`), 0 when it says nothing. */
+  users: number;
+}
+/**
+ * One legacy emergency number: a `caller-id-number-emergency` in use on a domain that has no endpoint
+ * records for it. Derived from the users, because the legacy model has no object of its own to read.
+ */
+export interface LegacyE911Item {
+  /** `e911legacy:<digits>`. Never a hash fallback — a blank number is not one of these. */
+  key: string;
+  /** The number, digits only ({@link emergencyDigits}). */
+  number: string;
+  /** How many real extensions reference it — counted here, not read off a record. */
+  users: number;
+}
 export interface SmsItem { key: string /* sms:<number>, or sms:~<hash> when the number is blank */; number: string }
-export type InventoryItem = ExtensionItem | NumberItem | AddressItem | SmsItem;
+export type InventoryItem = ExtensionItem | NumberItem | AddressItem | EndpointItem | LegacyE911Item | SmsItem;
 
 export interface DomainInventoryDetail {
   /** Real seats only, same rule as the count. */
@@ -155,9 +242,28 @@ export interface DomainInventoryDetail {
   systemUsers: ExtensionItem[];
   dids: NumberItem[];
   e911Addresses: AddressItem[];
+  e911Endpoints: EndpointItem[];
+  e911Legacy: LegacyE911Item[];
   smsNumbers: SmsItem[];
 }
 
+/** A device-name suffix legend: `suffix → { label, teams? }`. See {@link InventoryOptions.deviceSuffixes}. */
+export type DeviceSuffixLegend = Record<string, { label: string; teams?: boolean }>;
+
+/**
+ * The three device-name suffixes NetSapiens itself ships — SNAPmobile Web, SNAPmobile, and the TeamMate
+ * Microsoft Teams connector. Used whenever a caller supplies no `deviceSuffixes`, and it is the same
+ * table `resolver.ts` names a simultaneous-ring device by, so a suffix means one thing in this library.
+ *
+ * A deployment's OWN suffixes (a white-labelled app, say) are not here and never will be: they belong to
+ * the operator, who supplies them through {@link InventoryOptions.deviceSuffixes}.
+ */
+export const DEFAULT_DEVICE_SUFFIXES: Readonly<DeviceSuffixLegend> = Object.freeze({
+  wp: { label: 'SNAPmobile Web' },
+  m: { label: 'SNAPmobile' },
+  t: { label: 'Teams', teams: true },
+});
+
 /**
  * What the caller has to tell the counter that the API cannot. Optional in full: every option absent is
  * the pre-0.7.0 behaviour, and no option changes what a snapshot has to contain.
@@ -170,6 +276,18 @@ export interface InventoryOptions {
    * caller's to supply.
    */
   faxServerHosts?: readonly string[];
+  /**
+   * What a device-name SUFFIX means on this deployment: `suffix → { label, teams? }`. Compared
+   * case-insensitively, and it REPLACES {@link DEFAULT_DEVICE_SUFFIXES} wholesale rather than merging
+   * with it — a deployment that has no TeamMate omits `t` and Teams detection is then off entirely,
+   * which a merge could not express.
+   *
+   * `teams: true` marks the suffix that names a Microsoft Teams CONNECTOR rather than a handset: it is
+   * what {@link ExtensionItem.teams} and {@link DomainInventory.teamsConnected} test, and what keeps the
+   * connector out of `deviceCount`/`deviceModels`. At most one suffix normally carries it, but nothing
+   * here requires that.
+   */
+  deviceSuffixes?: DeviceSuffixLegend;
 }
 
 /** NANP toll-free area codes, 800 through 888. A number outside this set is counted local. */
@@ -241,6 +359,25 @@ function isFaxLine(p: Rec, hosts: Set<string>): boolean {
   return hosts.has(str(p['dial-rule-translation-destination-host']).toLowerCase());
 }
 
+/**
+ * An Emergency Caller ID reduced to what two records can be compared on: its digits, with an 11-digit
+ * `1NXXNXXXXXX` collapsed to its 10-digit form so a device's spelling matches an endpoint's.
+ *
+ * `''` for "not set", which the API says three ways: empty, absent, and the `[*]` wildcard the portal
+ * renders as "Select a Caller ID for 911 calls". Treating `[*]` as a value would give every unset
+ * device on a domain one shared fake endpoint.
+ */
+export function emergencyDigits(v: unknown): string {
+  const raw = str(v);
+  if (!raw || raw === '[*]') return '';
+  const digits = raw.replace(/\D+/g, '');
+  if (!digits) return '';
+  return digits.length === 11 && digits.startsWith('1') ? digits.slice(1) : digits;
+}
+
+/** A NetSapiens boolean, which arrives as a JSON `true` from one endpoint and as `"yes"` from another. */
+const flag = (v: unknown): boolean => v === true || ['yes', 'true', '1'].includes(str(v).toLowerCase());
+
 /**
  * A device's NAME — the local part of its SIP URI (`sip:103t@acme.example` → `103t`), which is the short
  * id the portal shows and the string the Teams test matches against.
@@ -258,11 +395,46 @@ function deviceName(device: Rec): string {
   return at === -1 ? a : a.slice(0, at);
 }
 
-function extensionItem(u: Rec, devices: Rec[]): ExtensionItem {
+/**
+ * The legend, lower-cased once so every lookup is a case-insensitive hit rather than a scan. A caller's
+ * legend REPLACES the default; two keys differing only in case collapse, last one wins, which is the
+ * only sane reading of a case-insensitive table.
+ */
+function suffixLegend(opts: InventoryOptions | undefined): DeviceSuffixLegend {
+  const src = opts?.deviceSuffixes ?? DEFAULT_DEVICE_SUFFIXES;
+  // Prototype-free: the key is a device-name suffix off a snapshot, so `constructor`, `toString` and
+  // `hasOwnProperty` are all reachable keys, and on a plain object each would answer with something
+  // inherited. `Object.entries` copies own enumerable keys only, so nothing inherited gets in either.
+  const out: DeviceSuffixLegend = Object.create(null) as DeviceSuffixLegend;
+  for (const [k, v] of Object.entries(src)) out[k.trim().toLowerCase()] = v;
+  return out;
+}
+
+/**
+ * What a device's name carries AFTER the extension number, lower-cased: `1001wp` on ext `1001` → `wp`,
+ * a bare `1001` → `''`. A name that does not start with the extension has no suffix at all — `sales1` on
+ * ext `1001` is a differently-named device, not a device of kind `sales1` — and neither does anything on
+ * an extension with no number, which is what keeps a device NAMED a bare `t` off the Teams legend.
+ */
+function deviceSuffix(name: string, ext: string): string {
+  if (!ext || !name.startsWith(ext)) return '';
+  return name.slice(ext.length).toLowerCase();
+}
+
+function extensionItem(u: Rec, devices: Rec[], legend: DeviceSuffixLegend): ExtensionItem {
   const ext = str(u.user);
-  // The Teams test is `<ext>t`, so a blank ext would read every device NAMED a bare `t` as a connector.
-  // No extension number, no Teams claim.
-  const handsets = ext ? devices.filter((d) => deviceName(d) !== `${ext}t`) : devices;
+  // Every device, once: its name, its suffix, and what the legend says that suffix is. Computed here and
+  // read three times below, so the Teams test, the handset filter and the display list cannot disagree.
+  const rows = devices.map((d) => {
+    const name = deviceName(d);
+    const suffix = deviceSuffix(name, ext);
+    const entry = suffix ? legend[suffix] : undefined;
+    return { d, name, suffix, kind: entry?.label ?? '', teams: entry?.teams === true };
+  });
+  // A CONNECTOR is a device whose suffix the legend marks `teams` — under the default legend that is
+  // `<ext>t` and nothing else, which is exactly the test this replaced. A legend without a `teams`
+  // suffix has no connectors, and every device on the extension is a handset.
+  const handsets = rows.filter((r) => !r.teams);
   const transcription = str(u['voicemail-transcription-enabled']).toLowerCase();
   const teams = handsets.length !== devices.length;
   const name = `${str(u['name-first-name'])} ${str(u['name-last-name'])}`.trim();
@@ -280,13 +452,15 @@ function extensionItem(u: Rec, devices: Rec[]): ExtensionItem {
     deviceCount: handsets.length,
     // A device whose model is blank is listed under a named bucket rather than dropped: a missing
     // model is a provisioning gap worth seeing, and a silently smaller total hides it.
-    deviceModels: handsets.map((d) => str(d['device-models-model']) || '(unknown)'),
+    deviceModels: handsets.map((r) => str(r.d['device-models-model']) || '(unknown)'),
     // Every device, including the Teams connector — this is a display list, not a seat count.
-    devices: devices.map((d) => {
-      const name = deviceName(d);
-      const isTeams = ext ? name === `${ext}t` : false;
-      return { name, model: isTeams ? '' : str(d['device-models-model']) || '(unknown)', teams: isTeams };
-    }),
+    devices: rows.map((r) => ({
+      name: r.name,
+      model: r.teams ? '' : str(r.d['device-models-model']) || '(unknown)',
+      teams: r.teams,
+      suffix: r.suffix,
+      kind: r.kind,
+    })),
     anyDevice: handsets.length > 0 || teams,
   };
 }
@@ -305,6 +479,107 @@ export function usersByExt(users: Rec[]): Map<string, Rec> {
   return map;
 }
 
+/**
+ * How a domain's E911 records join up, and the two INHERITANCES this library reads into a blank field.
+ *
+ * Both the counter and `attribution.ts` need to answer "which endpoint does this user reference?" and
+ * "which address?". Resolved in one place so the count and the site attribution cannot disagree about
+ * who references what.
+ *
+ * ⚠️ **Both inheritances are this library's inference, not a measured platform behaviour.** Two
+ * separate assumptions sit under them, and a consumer relying on the placement should know which:
+ *
+ * 1. **That a blank field falls back to the domain default at all.** A user with a blank
+ *    `caller-id-number-emergency` is read here as referencing the default address's endpoint, and one
+ *    with a blank `emergency-address-id` as referencing the default address. That is a plausible
+ *    reading of a record the portal badges "Domain Default" — but it has not been confirmed against a
+ *    live 911 call, and the same state can be read as an E911 GAP rather than an inheritance.
+ * 2. **That the default address's callback is joined by `address-name`.** An address record carries no
+ *    callback field of its own (checked against a live domain and 34 captured snapshots), so the only
+ *    thing tying the domain default to an endpoint is that the endpoint names the same address. Every
+ *    captured domain carrying both agreed on that name.
+ *
+ * Both fail CLOSED. No default address, no endpoint naming it, or a name that does not match, and
+ * `defaultCallback` is `''` — the users who would have inherited it reference nothing and are left
+ * unattributed, rather than being attached to a guess. The COUNTS are unaffected either way
+ * (`e911Endpoints` is a record count, and a user with both fields blank is correctly not legacy); what
+ * these assumptions move is PLACEMENT, which on a split domain decides which accounts are told they
+ * need an E911 line.
+ */
+export interface EmergencyModel {
+  /** The `emergency-address-id` of the record marked `domain_default`; `''` when the domain has none. */
+  defaultAddressId: string;
+  /** The callback of the endpoint bound to the DEFAULT address, digits only; `''` when there is none. */
+  defaultCallback: string;
+  /** Every provisioned endpoint's callback, digits only — the "is this number already an endpoint?" test. */
+  endpointCallbacks: Set<string>;
+  /** Which address a user references: their own field, the domain default when it is blank. */
+  addressIdFor: (user: Rec) => string;
+  /** The callback a user SETS: their own field, else any of their devices'; `''` when neither does. */
+  setCallbackFor: (user: Rec) => string;
+  /** Which endpoint a user references: {@link EmergencyModel.setCallbackFor}, else the domain default's. */
+  callbackFor: (user: Rec) => string;
+}
+
+export function resolveEmergency(snapshot: Snapshot): EmergencyModel {
+  const addresses: Rec[] = Array.isArray(snapshot.addresses) ? snapshot.addresses : [];
+  const endpoints: Rec[] = Array.isArray(snapshot.addressEndpoints) ? snapshot.addressEndpoints : [];
+  const devicesByUser: Record<string, Rec[]> = (snapshot.devicesByUser ?? {}) as Record<string, Rec[]>;
+
+  // First one wins. Two records marked default is a provisioning fault, and picking one of them
+  // silently is better than resolving every blank user to nothing because two records disagree.
+  const def = addresses.find((a) => flag(a['domain_default']));
+  const defaultAddressId = def ? str(def['emergency-address-id']) : '';
+  const defName = def ? str(def['address-name']).toLowerCase() : '';
+  const boundToDefault = defName ? endpoints.find((e) => str(e['address-name']).toLowerCase() === defName) : undefined;
+  // NB: on an ENDPOINT record `emergency-address-id` holds the callback NUMBER, not an address id.
+  const defaultCallback = boundToDefault ? emergencyDigits(boundToDefault['emergency-address-id']) : '';
+  const endpointCallbacks = new Set(endpoints.map((e) => emergencyDigits(e['emergency-address-id'])).filter(Boolean));
+
+  const setCallbackFor = (user: Rec): string => {
+    const own = emergencyDigits(user['caller-id-number-emergency']);
+    if (own) return own;
+    // A user who sets none can still have a handset that does — the portal reads the device's own
+    // setting first and only then the user's, so a domain whose numbers live on the devices is
+    // invisible to a rule that reads the user record alone.
+    for (const d of devicesByUser[str(user.user)] ?? []) {
+      const dev = emergencyDigits(d['caller-id-number-emergency']);
+      if (dev) return dev;
+    }
+    return '';
+  };
+
+  return {
+    defaultAddressId,
+    defaultCallback,
+    endpointCallbacks,
+    addressIdFor: (user) => str(user['emergency-address-id']) || defaultAddressId,
+    setCallbackFor,
+    callbackFor: (user) => setCallbackFor(user) || defaultCallback,
+  };
+}
+
+/**
+ * Is this user on the LEGACY emergency model — a caller ID set by hand, with no address record behind
+ * it and no endpoint provisioned for the number?
+ *
+ * All three clauses matter. A blank `emergency-address-id` alone is not legacy: a user with BOTH fields
+ * blank inherits the domain default address, which is the new model working as designed. And a number
+ * that IS an endpoint callback is the new model too — counting it here as well would bill a
+ * half-migrated domain twice for one place.
+ *
+ * ⚠️ **The `em` must come from a snapshot whose endpoints were READ.** The third clause tests against
+ * `em.endpointCallbacks`, which is empty both when the domain has no endpoints and when nobody asked
+ * for them — so on a snapshot fetched without `includeAddresses` this answers "legacy" for every user
+ * on a fully-migrated domain. {@link listDomainInventory} refuses to derive the list at all in that
+ * state; a caller using this predicate directly has to make the same check.
+ */
+export function legacyEmergencyNumber(user: Rec, em: EmergencyModel): string {
+  if (str(user['emergency-address-id'])) return '';
+  const n = em.setCallbackFor(user);
+  return n && !em.endpointCallbacks.has(n) ? n : '';
+}
+
 /**
  * Where a phone number routes, in words a person reads at a glance — not the raw NetSapiens dial
  * rule fields. Pure; looks the destination user up in `userByExt` ({@link usersByExt}) so it can
@@ -379,6 +654,8 @@ export function listDomainInventory(snapshot: Snapshot, opts?: InventoryOptions)
 
   const extensions: ExtensionItem[] = [];
   const systemUsers: ExtensionItem[] = [];
+  // Normalised once, not per extension: the legend is the caller's and does not change mid-fold.
+  const legend = suffixLegend(opts);
   for (let i = 0; i < users.length; i++) {
     const u = users[i]!;
     const ext = str(u.user);
@@ -388,7 +665,7 @@ export function listDomainInventory(snapshot: Snapshot, opts?: InventoryOptions)
     // from a backup or a fixture. Dropping it would read as a clean match on a domain that has
     // handsets nobody can see; two blank users sharing one list overcount instead, which is a
     // visible drift an operator investigates, and that is the failure worth having.
-    const item = extensionItem(u, devicesByUser[ext] ?? []);
+    const item = extensionItem(u, devicesByUser[ext] ?? [], legend);
     (isSystemUser(u) ? systemUsers : extensions).push(item);
   }
   const userByExt = usersByExt(users);
@@ -418,11 +695,49 @@ export function listDomainInventory(snapshot: Snapshot, opts?: InventoryOptions)
       label: label || id || `(address ${i + 1})`,
     };
   });
+  // The two E911 lists share one resolution of the domain's inheritance — see `resolveEmergency`.
+  const em = resolveEmergency(snapshot);
+  const endpoints: Rec[] = Array.isArray(snapshot.addressEndpoints) ? snapshot.addressEndpoints : [];
+  const e911Endpoints: EndpointItem[] = endpoints.map((e) => {
+    // NB: `emergency-address-id` on an ENDPOINT record is the callback NUMBER. See `Snapshot`.
+    const callback = emergencyDigits(e['emergency-address-id']);
+    const callerName = str(e['caller-name']);
+    const line1 = str(e['address-line-1']);
+    const city = str(e['address-city']);
+    return {
+      key: identityKey('e911', callback, `${callerName} ${line1} ${city}`),
+      callback,
+      callerName,
+      billingAddress: [line1, city].filter(Boolean).join(', '),
+      // `count-users-configured` and NOT `sub_count_total`: the two disagree on live records (a
+      // captured endpoint had 0 and 16), and only the first one names what it counts.
+      users: Number(e['count-users-configured'] ?? 0) || 0,
+    };
+  });
+  // Legacy numbers are DERIVED — there is no record to map over. One entry per distinct number, in the
+  // order the users first name it, so the list does not reshuffle between two reads of one domain.
+  //
+  // ⚠️ ONLY when the endpoint list was actually READ. `snapshot.addressEndpoints` is `undefined` when
+  // the fetch never asked for it and `[]` when it asked and the domain has none, and the difference
+  // decides whether this list can exist at all: the legacy test excludes numbers that are already
+  // endpoint callbacks, and with no endpoint list there is nothing to exclude against — so a domain
+  // fully on the ENDPOINT model, read with `includeAddresses` off, would report every distinct
+  // emergency caller ID as a legacy line the carrier bills for. `e911Addresses` answering 0 in that
+  // state is a safe under-count; this answering N is a confident over-count that looks like real data.
+  const legacyUsers = new Map<string, number>();
+  if (Array.isArray(snapshot.addressEndpoints)) {
+    for (const u of users) {
+      if (isSystemUser(u)) continue;
+      const n = legacyEmergencyNumber(u, em);
+      if (n) legacyUsers.set(n, (legacyUsers.get(n) ?? 0) + 1);
+    }
+  }
+  const e911Legacy: LegacyE911Item[] = [...legacyUsers].map(([number, count]) => ({ key: `e911legacy:${number}`, number, users: count }));
   const smsNumbers: SmsItem[] = smsnumbers.map((s) => {
     const number = str(s.number);
     return { key: identityKey('sms', number, JSON.stringify({ number })), number };
   });
-  return { extensions, systemUsers, dids, e911Addresses, smsNumbers };
+  return { extensions, systemUsers, dids, e911Addresses, e911Endpoints, e911Legacy, smsNumbers };
 }
 
 /** The counts, as a fold over {@link listDomainInventory} so the two can never disagree. */
@@ -442,6 +757,11 @@ export function countInventoryDetail(d: DomainInventoryDetail): DomainInventory
     teamsConnected: 0,
     dids: { total: 0, tollFree: 0, local: 0, fax: 0, all: d.dids.length },
     e911Addresses: d.e911Addresses.length,
+    // `?? []` on the two newest lists alone: a detail object cached or serialised by a consumer running
+    // an older version of this library has neither field, and a count that threw on it would take out a
+    // whole page over a dimension that did not exist when the entry was written.
+    e911Endpoints: (d.e911Endpoints ?? []).length,
+    e911Legacy: (d.e911Legacy ?? []).length,
     smsNumbers: d.smsNumbers.length,
     devices: { total: 0, byModel: {} },
   };
@@ -497,6 +817,8 @@ export function itemsFor(detail: DomainInventoryDetail, path: string): Inventory
   if (path === 'dids.fax') return detail.dids.filter((n) => n.fax);
   if (path === 'dids.all') return detail.dids;
   if (path === 'e911Addresses') return detail.e911Addresses;
+  if (path === 'e911Endpoints') return detail.e911Endpoints ?? [];
+  if (path === 'e911Legacy') return detail.e911Legacy ?? [];
   if (path === 'smsNumbers') return detail.smsNumbers;
   return undefined;
 }
@@ -509,5 +831,20 @@ export function itemLabel(item: InventoryItem): string {
   }
   if ('kind' in item) return item.kind === 'tollFree' ? `${item.number} (toll-free)` : item.number;
   if ('label' in item) return item.label;
+  // An ENDPOINT is named by the number the carrier bills, then by who it announces and where it sends
+  // responders. Either half is dropped when blank rather than printed against a dangling dash, and a
+  // record with NEITHER falls back to its derived key — the same shape an address with nothing to name
+  // it by gets, except the id here is the key rather than a position, so two blank-callback endpoints
+  // stay apart. Never the empty string: this label is what a consumer writes into its acceptance
+  // history, and a row that cannot name its own item is worse than an ugly one.
+  if ('callback' in item) {
+    const who = [item.callerName, item.billingAddress].filter(Boolean).join(', ');
+    if (item.callback) return who ? `${item.callback} — ${who}` : item.callback;
+    return who || `(endpoint ${item.key.slice('e911:'.length)})`;
+  }
+  // A LEGACY number says so on its own line: it looks like a DID, and nothing else on the page would
+  // tell a reader why a bare number is sitting on an E911 row. Singular is written out: a label that
+  // does not agree with itself reads as a rendering fault, and this one is frozen into history rows.
+  if ('users' in item) return `${item.number} — legacy E911 (${item.users} user${item.users === 1 ? '' : 's'})`;
   return item.number;
 }

package/src/model.ts

@@ -96,6 +96,19 @@ export interface Snapshot {
    * `undefined` means "not read", which is not the same fact as an empty array.
    */
   addresses?: Rec[];
+  /**
+   * Emergency ENDPOINT records — GET /domains/{d}/addresses/endpoints. Read alongside `addresses`,
+   * and `undefined` means "not read" the same way.
+   *
+   * An endpoint is what the E911 carrier routes on and bills per: a callback number, a caller name, a
+   * billing address and a vendor. An ADDRESS is a dispatchable location forwarded to responders, and
+   * several of them can sit under one endpoint — so the two lists count different things and neither
+   * substitutes for the other.
+   *
+   * ⚠️ An endpoint record holds its callback NUMBER in `emergency-address-id` — the same field name an
+   * address record uses for its own `a-…` id. Reading it as an address id joins nothing.
+   */
+  addressEndpoints?: Rec[];
   /**
    * SMS-enabled numbers — GET /domains/{d}/smsnumbers?dest=*. The endpoint is documented with no
    * parameters, but a live server answers 400 without `dest` or `number`; `dest=*` is the wildcard

package/src/nsClient.ts

@@ -165,8 +165,14 @@ export interface FetchSnapshotOptions {
    */
   includeDidDestRules?: boolean;
   /**
-   * Also read the domain's E911 addresses into `snapshot.addresses`. One extra call. Default false —
-   * the resolver does not use them; an inventory count does.
+   * Also read the domain's E911 addresses into `snapshot.addresses` AND its emergency ENDPOINTS into
+   * `snapshot.addressEndpoints`. Two extra calls. Default false — the resolver uses neither; an
+   * inventory count uses both.
+   *
+   * ONE flag for the two because they are one subject read two ways: the endpoint is what the E911
+   * carrier bills per, the address is the location responders are sent to, and a caller given the
+   * addresses alone would count the dispatchable locations and bill for them. That was the bug this
+   * option grew to fix, so the two are not separable here.
    */
   includeAddresses?: boolean;
   /**
@@ -212,13 +218,16 @@ export async function fetchDomainSnapshot(client: NsClient, domain: string, opts
   };
 
   const domainRec = asArray(await client.get(base))[0] ?? { domain };
-  const [timeframes, users, callqueues, phonenumbers, autoattendants, addresses, smsnumbers] = await Promise.all([
+  const [timeframes, users, callqueues, phonenumbers, autoattendants, addresses, addressEndpoints, smsnumbers] = await Promise.all([
     soft(`${base}/timeframes`),
     soft(`${base}/users`),
     soft(`${base}/callqueues`),
     soft(`${base}/phonenumbers`),
     soft(`${base}/autoattendants`),
     opts.includeAddresses ? soft(`${base}/addresses`) : Promise.resolve(undefined),
+    // The BILLABLE half of E911, softened like the rest: a domain still on the legacy provisioning
+    // model has no endpoints at all and answers 404, which is "none" rather than a failure.
+    opts.includeAddresses ? soft(`${base}/addresses/endpoints`) : Promise.resolve(undefined),
     // `dest=*`: see includeSmsNumbers. A 404 is already softened to []; a 400 from a server that wants
     // a different parameter throws, which is right — a silent empty list would read as "no SMS numbers".
     opts.includeSmsNumbers ? soft(`${base}/smsnumbers?dest=*`) : Promise.resolve(undefined),
@@ -240,6 +249,7 @@ export async function fetchDomainSnapshot(client: NsClient, domain: string, opts
       meta: { domain }, domain: domainRec, timeframes, users, callqueues, phonenumbers, autoattendants,
       ...(answerrulesByUser ? { answerrulesByUser } : {}),
       ...(addresses ? { addresses } : {}),
+      ...(addressEndpoints ? { addressEndpoints } : {}),
       ...(smsnumbers ? { smsnumbers } : {}),
     };
   }
@@ -343,6 +353,7 @@ export async function fetchDomainSnapshot(client: NsClient, domain: string, opts
     answerrulesByUser,
     agentsByQueue,
     ...(addresses ? { addresses } : {}),
+    ...(addressEndpoints ? { addressEndpoints } : {}),
     ...(smsnumbers ? { smsnumbers } : {}),
     ...(devicesByUser ? { devicesByUser } : {}),
     ...(deviceReadFailures ? { deviceReadFailures } : {}),

package/src/resolver.selftest.ts

@@ -6,7 +6,7 @@
  * cross-queue priority. Queue priority (lower = higher) is shown once when the queue
  * shares one non-default value, per-agent when it varies, and hidden at the default (0).
  */
-import { resolveFlow } from './resolver.js';
+import { deviceKindBySuffix, resolveFlow } from './resolver.js';
 import type { Snapshot, FlowGraph, NodeKind } from './model.js';
 
 let pass = 0,
@@ -221,5 +221,26 @@ const linesOf = (g: FlowGraph, kind: NodeKind) => (g.nodes.find((n) => n.kind ==
   check('announce: no message node is left without an outgoing edge', ['aaannounce_9000_900013', 'aaannounce_9000_900014'].every((id) => g.edges.some((e) => e.from === id)));
 }
 
+// ── the device-suffix legend, as the resolver reads it ──────────────────────────────────────────────
+// The KINDS come from DEFAULT_DEVICE_SUFFIXES so a suffix means one thing across the library; the icons
+// and two fallbacks are the resolver's own. Asserted here because a diagram is where the labels are SEEN,
+// and a drift between this and the inventory's legend would show up nowhere else.
+{
+  const k = (s: string) => deviceKindBySuffix(s);
+  check('suffix wp reads the legend label SNAPmobile Web, with the resolver\'s globe', k('wp').kind === 'SNAPmobile Web' && k('wp').icon === '🌐');
+  check('suffix m reads SNAPmobile', k('m').kind === 'SNAPmobile' && k('m').icon === '📱');
+  check('suffix t reads Teams', k('t').kind === 'Teams' && k('t').icon === '💻');
+  check('an upper-case suffix reads the same', k('WP').kind === 'SNAPmobile Web' && k('T').kind === 'Teams');
+  check('suffix r is the resolver\'s own fallback, not the legend\'s', k('r').kind === 'app' && k('r').icon === '📱');
+  check('any other letter is a desk phone', k('b').kind === 'desk phone' && k('b').icon === '📞');
+  check('no suffix is no kind and no icon', k('').kind === '' && k('').icon === '');
+  // The key is a device-name suffix off a snapshot, so an inherited Object name is a reachable key. On a
+  // plain object literal `SUFFIX_ICONS['constructor']` answers a function and `?? '📞'` never fires.
+  for (const evil of ['constructor', 'toString', 'hasOwnProperty', '__proto__']) {
+    check(`a suffix named ${evil} falls to the defaults rather than an inherited value`,
+      k(evil).kind === 'desk phone' && k(evil).icon === '📞');
+  }
+}
+
 console.log(`\n${pass} passed, ${fail} failed`);
 if (fail) throw new Error(`${fail} check(s) failed`);