@dszp/netsapiens-lib 0.8.0 → 0.9.0

package/src/index.ts

@@ -37,7 +37,7 @@ export {
 } from './html.js';
 export { resolveSvgSize, rasterizerScript } from './raster.js';
 export { NsClient, NsApiError, assertBareServer, fetchDomainSnapshot, listDomains, asArray, type NsClientConfig, type FetchSnapshotOptions } from './nsClient.js';
-export { countDomainInventory, countInventoryDetail, listDomainInventory, itemsFor, itemLabel, destinationOf, usersByExt, DEFAULT_DEVICE_SUFFIXES, type DeviceSuffixLegend, type DomainInventory, type DomainInventoryDetail, type InventoryOptions, type ExtensionItem, type NumberItem, type AddressItem, type SmsItem, type InventoryItem } from './inventory.js';
+export { countDomainInventory, countInventoryDetail, listDomainInventory, itemsFor, itemLabel, destinationOf, emergencyDigits, legacyEmergencyNumber, resolveEmergency, usersByExt, DEFAULT_DEVICE_SUFFIXES, type DeviceSuffixLegend, type DomainInventory, type DomainInventoryDetail, type EmergencyModel, type InventoryOptions, type ExtensionItem, type NumberItem, type AddressItem, type EndpointItem, type LegacyE911Item, type SmsItem, type InventoryItem } from './inventory.js';
 export { attributeDomainInventory, type DomainAttribution, type ItemAttribution } from './attribution.js';
 export { NsWriteClient, type NsWriteClientConfig } from './nsWriteClient.js';
 export {

package/src/inventory.selftest.ts

@@ -1,5 +1,5 @@
 /** Offline test for the domain inventory counter. pnpm test:inventory */
-import { countDomainInventory, listDomainInventory, itemsFor, itemLabel, destinationOf, usersByExt, DEFAULT_DEVICE_SUFFIXES } from './inventory.js';
+import { countDomainInventory, emergencyDigits, legacyEmergencyNumber, listDomainInventory, itemsFor, itemLabel, destinationOf, resolveEmergency, usersByExt, DEFAULT_DEVICE_SUFFIXES } from './inventory.js';
 import type { Rec, Snapshot } from './model.js';
 
 let pass = 0, fail = 0;
@@ -474,5 +474,191 @@ ok(sysDev.devices.total === 0, 'a system user device is not counted');
     '[suffix] the exported default marks only t as the Teams connector');
 }
 
+// ── E911: endpoints bill, addresses locate, legacy numbers are derived ──────────────────────────────
+{
+  // One domain default address, one endpoint bound to it by name, and a second endpoint that nothing
+  // defaults to. `emergency-address-id` on an ENDPOINT is the callback number; on an ADDRESS it is the
+  // `a-…` id — the same field name meaning two things is the trap this fixture pins down.
+  const e911: Snapshot = {
+    meta: { domain: 'acme.example' },
+    users: [
+      { user: '100', 'service-code': '', site: 'North', 'emergency-address-id': 'a-1', 'caller-id-number-emergency': '3175550100' },
+      // Eleven digits where the endpoint says ten — the same endpoint, and the point of `emergencyDigits`.
+      { user: '101', 'service-code': '', site: 'North', 'emergency-address-id': 'a-2', 'caller-id-number-emergency': '13175550101' },
+      // Both fields blank: inherits the domain default address AND its endpoint. Not legacy.
+      { user: '102', 'service-code': '', site: 'South' },
+      // The wildcard is "not set", not a value.
+      { user: '103', 'service-code': '', site: 'South', 'caller-id-number-emergency': '[*]' },
+      { user: '700', 'service-code': 'system-aa', 'caller-id-number-emergency': '3175559999' },
+    ],
+    addresses: [
+      { 'emergency-address-id': 'a-1', 'address-name': 'HQ', 'address-line-1': '1 Main St', 'address-city': 'Springfield', domain_default: true },
+      { 'emergency-address-id': 'a-2', 'address-name': 'Annex', 'address-line-1': '2 Side St', 'address-city': 'Springfield' },
+    ],
+    addressEndpoints: [
+      { 'emergency-address-id': '3175550100', 'address-name': 'HQ', 'caller-name': 'Acme HQ', 'address-line-1': '1 Main St', 'address-city': 'Springfield', 'count-users-configured': 3, sub_count_total: 9 },
+      { 'emergency-address-id': '3175550101', 'address-name': 'Annex', 'caller-name': '', 'address-line-1': '', 'address-city': '' },
+    ],
+  } as Snapshot;
+
+  const inv = countDomainInventory(e911);
+  const d = listDomainInventory(e911);
+  ok(inv.e911Endpoints === 2, '[e911] two provisioned endpoints');
+  ok(inv.e911Addresses === 2, '[e911] and the two addresses are still counted, as information');
+  ok(inv.e911Legacy === 0, '[e911] a domain on the endpoint model has no legacy numbers');
+
+  const hq = d.e911Endpoints[0]!;
+  ok(hq.key === 'e911:3175550100', '[e911] the key is the callback, taken from the endpoint’s emergency-address-id');
+  ok(hq.callback === '3175550100' && hq.callerName === 'Acme HQ', '[e911] the callback and the caller name come off the record');
+  ok(hq.billingAddress === '1 Main St, Springfield', '[e911] the billing address is one line, no wider than the address list');
+  ok(hq.users === 3, '[e911] users is count-users-configured, not sub_count_total');
+  ok(itemLabel(hq) === '3175550100 — Acme HQ, 1 Main St, Springfield', '[e911] the label names the number, then who and where');
+  ok(itemLabel(d.e911Endpoints[1]!) === '3175550101', '[e911] and an endpoint with neither is just its number — no dangling dash');
+  {
+    // NO CALLBACK. The label is what `applyAssignment` writes into acceptance history, so a leading
+    // dash is bad and an empty string is worse — it records a decision about a thing it cannot name.
+    const [named, blank] = listDomainInventory({ ...e911, addressEndpoints: [
+      { 'caller-name': 'Acme Dock', 'address-line-1': '9 Dock Rd', 'address-city': 'Springfield' },
+      { 'address-name': 'Nothing' },
+    ] } as Snapshot).e911Endpoints;
+    ok(itemLabel(named!) === 'Acme Dock, 9 Dock Rd, Springfield', '[e911] an endpoint with no callback leads with what it does have, never a dash');
+    ok(itemLabel(blank!) === `(endpoint ${blank!.key.slice('e911:'.length)})`,
+      '[e911] and one with nothing at all is named by its derived key - never the empty string');
+    ok(itemLabel(blank!) !== '', '[e911] which is the fact that matters: an acceptance row can always name its item');
+  }
+  ok(itemsFor(d, 'e911Endpoints')!.length === 2, '[e911] itemsFor answers the endpoints path');
+  ok(itemsFor(d, 'e911Addresses')!.length === 2, '[e911] and the addresses path still answers separately');
+
+  const em = resolveEmergency(e911);
+  ok(em.defaultAddressId === 'a-1', '[e911] the domain default is the address flagged domain_default');
+  ok(em.defaultCallback === '3175550100', '[e911] whose callback is joined through the endpoint naming the same address');
+  ok(em.addressIdFor(e911.users![2]!) === 'a-1', '[e911] a user with a blank address id inherits the domain default');
+  ok(em.addressIdFor(e911.users![1]!) === 'a-2', '[e911] and one that sets its own keeps it');
+  ok(em.callbackFor(e911.users![2]!) === '3175550100', '[e911] a user with a blank caller ID inherits the default address’s callback');
+  ok(em.callbackFor(e911.users![1]!) === '3175550101', '[e911] an 11-digit caller ID resolves to the 10-digit endpoint');
+  ok(em.setCallbackFor(e911.users![3]!) === '', '[e911] the [*] wildcard is not set');
+  ok(em.callbackFor(e911.users![3]!) === '3175550100', '[e911] so that user inherits the default too');
+
+  // An endpoint whose record names no callback still has to be a distinguishable row.
+  const blank = listDomainInventory({ ...e911, addressEndpoints: [{ 'address-name': 'Dock', 'caller-name': 'Acme Dock' }] } as Snapshot).e911Endpoints[0]!;
+  ok(blank.key.startsWith('e911:~'), '[e911] an endpoint with no callback falls back to a derived key');
+}
+
+{
+  // A LEGACY domain: no endpoints at all, every user with a blank emergency-address-id and one of two
+  // numbers set by hand. Measured shape — a 100-user domain with exactly two such numbers.
+  const legacy: Snapshot = {
+    meta: { domain: 'demo.12345.service' },
+    users: [
+      { user: '100', 'service-code': '', site: 'North', 'caller-id-number-emergency': '3175550200' },
+      { user: '101', 'service-code': '', site: 'North', 'caller-id-number-emergency': '13175550200' },
+      { user: '102', 'service-code': '', site: 'South', 'caller-id-number-emergency': '3175550201' },
+      // Nothing set anywhere and no domain default to inherit: not legacy, and not anything else.
+      { user: '103', 'service-code': '', site: 'South' },
+      // On its device rather than on the user.
+      { user: '104', 'service-code': '', site: 'South' },
+      // A system user is not a seat and does not make a number legacy.
+      { user: '700', 'service-code': 'system-queue', 'caller-id-number-emergency': '3175550299' },
+    ],
+    devicesByUser: { '104': [{ device: 'sip:104@demo.12345.service', 'caller-id-number-emergency': '3175550201' }] },
+    // READ, and there are none — which is what a legacy domain looks like. An ABSENT list means the
+    // fetch never asked, and then no legacy count is derivable at all; that pair is tested below.
+    addressEndpoints: [],
+  } as Snapshot;
+
+  const inv = countDomainInventory(legacy);
+  const d = listDomainInventory(legacy);
+  ok(inv.e911Legacy === 2, '[legacy] two DISTINCT numbers across five seats, matching the carrier’s two lines');
+  ok(inv.e911Endpoints === 0 && inv.e911Addresses === 0, '[legacy] and no endpoints or addresses to count');
+  ok(d.e911Legacy.map((x) => x.key).join() === 'e911legacy:3175550200,e911legacy:3175550201', '[legacy] keyed by the digits');
+  ok(d.e911Legacy[0]!.users === 2, '[legacy] the 10- and 11-digit spellings are one number');
+  ok(d.e911Legacy[1]!.users === 2, '[legacy] and a device’s number counts when the user sets none');
+  ok(itemLabel(d.e911Legacy[0]!) === '3175550200 — legacy E911 (2 users)', '[legacy] the label says why a bare number is on an E911 row');
+  ok(itemLabel({ key: 'e911legacy:3175550299', number: '3175550299', users: 1 }) === '3175550299 — legacy E911 (1 user)',
+    '[legacy] and it agrees with itself on one — a label that reads "(1 users)" reads as a rendering fault');
+  ok(itemsFor(d, 'e911Legacy')!.length === 2, '[legacy] itemsFor answers the legacy path');
+
+  // HALF-MIGRATED: one of the two numbers is now a provisioned endpoint. It must be counted once, as an
+  // endpoint, or the domain pays for the same place twice.
+  const half = { ...legacy, addressEndpoints: [{ 'emergency-address-id': '3175550200', 'address-name': 'HQ', 'caller-name': 'Demo HQ' }] } as Snapshot;
+  const hi = countDomainInventory(half);
+  ok(hi.e911Endpoints === 1 && hi.e911Legacy === 1, '[legacy] a number that became an endpoint leaves the legacy count');
+  ok(listDomainInventory(half).e911Legacy[0]!.number === '3175550201', '[legacy] and the one still on the old model stays');
+
+  // A user with BOTH fields blank on a domain that HAS a default is on the new model, not the old one.
+  const withDefault = {
+    ...legacy,
+    users: [{ user: '110', 'service-code': '', site: 'North' }],
+    devicesByUser: {},
+    addresses: [{ 'emergency-address-id': 'a-9', 'address-name': 'HQ', domain_default: true }],
+    addressEndpoints: [{ 'emergency-address-id': '3175550300', 'address-name': 'HQ', 'caller-name': 'Demo HQ' }],
+  } as Snapshot;
+  ok(countDomainInventory(withDefault).e911Legacy === 0, '[legacy] both fields blank is the domain default, not a legacy number');
+  const em = resolveEmergency(withDefault);
+  ok(legacyEmergencyNumber(withDefault.users![0]!, em) === '', '[legacy] and the predicate says so directly');
+
+  // A user who SETS an emergency address is on the new model whatever their caller ID says — even when
+  // that number matches no endpoint this snapshot can see. Without the address-id clause of
+  // `legacyEmergencyNumber` this reads as a legacy line, and the account is billed for one.
+  const addressed = {
+    ...legacy,
+    users: [{ user: '120', 'service-code': '', site: 'North', 'emergency-address-id': 'a-9', 'caller-id-number-emergency': '3175550777' }],
+    devicesByUser: {},
+    addresses: [{ 'emergency-address-id': 'a-9', 'address-name': 'HQ', domain_default: true }],
+    addressEndpoints: [{ 'emergency-address-id': '3175550300', 'address-name': 'HQ', 'caller-name': 'Demo HQ' }],
+  } as Snapshot;
+  ok(countDomainInventory(addressed).e911Legacy === 0,
+    '[legacy] a user with a SET emergency address is never legacy, whatever its caller ID matches');
+  ok(legacyEmergencyNumber(addressed.users![0]!, resolveEmergency(addressed)) === '',
+    '[legacy] and the predicate refuses it on the address id alone, not on the number');
+}
+
+{
+  // ── the USER's own caller ID wins over its devices' ────────────────────────────────────────────
+  // The device is consulted only where the user sets nothing. Reversing the two would attribute the
+  // seat to whichever handset happened to be first in the record, which is not what the portal does.
+  const both = {
+    meta: { domain: 'acme.example' },
+    users: [{ user: '100', 'service-code': '', 'caller-id-number-emergency': '3175550100' }],
+    devicesByUser: { '100': [{ device: 'sip:100@acme.example', 'caller-id-number-emergency': '3175550101' }] },
+    addressEndpoints: [],
+  } as Snapshot;
+  ok(resolveEmergency(both).setCallbackFor(both.users![0]!) === '3175550100',
+    '[e911] a user carrying its own caller ID wins over a device carrying a different one');
+  const deviceOnly = { ...both, users: [{ user: '100', 'service-code': '' }] } as Snapshot;
+  ok(resolveEmergency(deviceOnly).setCallbackFor(deviceOnly.users![0]!) === '3175550101',
+    '[e911] and the device is read only where the user sets nothing');
+}
+
+{
+  // ── the ENDPOINTS list was never READ ──────────────────────────────────────────────────────────
+  // `undefined` (the fetch never asked) and `[]` (asked, and the domain has none) are different facts,
+  // and only the second one can support a legacy count: without the endpoint list there is nothing to
+  // exclude against, so every emergency caller ID on a fully-migrated domain would read as a legacy
+  // line. An under-count is safe here; a confident over-count on a billing page is not.
+  const users = [
+    { user: '100', 'service-code': '', site: 'North', 'emergency-address-id': '', 'caller-id-number-emergency': '3175550100' },
+    { user: '101', 'service-code': '', site: 'North', 'emergency-address-id': '', 'caller-id-number-emergency': '3175550101' },
+  ];
+  const never = { meta: { domain: 'acme.example' }, users } as Snapshot;
+  const read = { ...never, addressEndpoints: [] } as Snapshot;
+  const provisioned = { ...never, addressEndpoints: [
+    { 'emergency-address-id': '3175550100', 'address-name': 'HQ', 'caller-name': 'Acme HQ' },
+    { 'emergency-address-id': '3175550101', 'address-name': 'Annex', 'caller-name': 'Acme Annex' },
+  ] } as Snapshot;
+  ok(countDomainInventory(never).e911Legacy === 0 && listDomainInventory(never).e911Legacy.length === 0,
+    '[legacy] no endpoint read at all answers 0 legacy numbers rather than inventing two');
+  ok(countDomainInventory(read).e911Legacy === 2,
+    '[legacy] while an endpoint list that was read and is EMPTY is a real legacy domain');
+  ok(countDomainInventory(provisioned).e911Legacy === 0 && countDomainInventory(provisioned).e911Endpoints === 2,
+    '[legacy] and the same two users on the endpoint model are two endpoints and no legacy numbers');
+}
+
+ok(emergencyDigits('+1 (317) 555-0100') === '3175550100' && emergencyDigits('13175550100') === '3175550100',
+  '[e911] a caller ID normalises to ten digits however it is punctuated');
+ok(emergencyDigits('[*]') === '' && emergencyDigits('') === '' && emergencyDigits(undefined) === '',
+  '[e911] and the three ways of saying "not set" all answer empty');
+
+
 console.log(`\n${pass} passed, ${fail} failed`);
 if (fail) process.exit(1);

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';
 
@@ -80,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. */
@@ -154,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. */
@@ -164,6 +242,8 @@ export interface DomainInventoryDetail {
   systemUsers: ExtensionItem[];
   dids: NumberItem[];
   e911Addresses: AddressItem[];
+  e911Endpoints: EndpointItem[];
+  e911Legacy: LegacyE911Item[];
   smsNumbers: SmsItem[];
 }
 
@@ -279,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.
@@ -380,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
@@ -495,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. */
@@ -519,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: {} },
   };
@@ -574,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;
 }
@@ -586,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 } : {}),