@dszp/netsapiens-lib 0.6.0 → 0.8.0

package/src/inventory.ts

@@ -9,9 +9,9 @@
  * A device record from NetSapiens carries the SIP registration password. `listDomainInventory` builds
  * per-item lists — an extension's name and site, a number's kind and routing destination, an address's
  * label — from an allowlist of named fields, and `countDomainInventory` is a fold over those same
- * lists. The allowlist now includes a device's NAME (its `aor` local part, e.g. `101b` — the same
- * short id the portal shows) alongside its model; a device's MAC, SIP password and email never appear,
- * and nothing here should be added that carries one.
+ * lists. The allowlist now includes a device's NAME (the local part of its `device` SIP URI, falling back
+ * to `aor` — e.g. `101b`, the same short id the portal shows) alongside its model; a device's MAC, SIP
+ * password and email never appear, and nothing here should be added that carries one.
  *
  * ## Every countable dimension is a numeric leaf
  *
@@ -24,6 +24,20 @@
  * A user whose `service-code` is empty or does not begin with `system-`. NetSapiens models auto
  * attendants, queues and time-of-day routers as users, and counting them as seats would overstate
  * every domain that has any. They are counted separately, as information, and never compared.
+ *
+ * ## What counts as a fax line
+ *
+ * On the portal's "Fax Server" treatment a number is an ordinary phone number whose dial rule hands it
+ * to a fax server host — `dial-rule-application: to-connection` with
+ * `dial-rule-translation-destination-host` set to that host. There is no fax-account endpoint and the
+ * ATA is not a device on any user, so the host is the only thing in the API that says "this is a fax
+ * line", and nothing in the API can tell an analog fax from a digital one.
+ *
+ * The host is therefore the whole test, and it is the CALLER's: pass `{ faxServerHosts }` to
+ * {@link listDomainInventory} or {@link countDomainInventory}. Matching is on the trimmed host,
+ * 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.
  */
 import type { Rec, Snapshot } from './model.js';
 
@@ -47,13 +61,25 @@ 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 SIP `aor` local part is the
-   * extension number followed by `t` (`1000t`), which is how the TeamMate connector registers.
-   * 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;
-  /** Phone numbers on the domain, split by NANP toll-free prefix. */
-  dids: { total: number; tollFree: number; local: number };
+  /**
+   * Phone numbers on the domain, split by NANP toll-free prefix — **fax lines excluded**.
+   *
+   * A number handed to the fax server is billed as a fax line, not as a DID, so `total`, `tollFree`
+   * and `local` all leave it out and `fax` counts it instead. `all` is every phone number the domain
+   * holds, fax lines included: `total + fax === all`.
+   *
+   * With no `faxServerHosts` supplied nothing is a fax line, `fax` is 0 and `total === all` — the
+   * 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. */
   e911Addresses: number;
   /** SMS-enabled numbers on the domain. */
@@ -91,14 +117,22 @@ export interface ExtensionItem {
   /** `device-models-model` per handset, `(unknown)` when blank. Never the MAC. */
   deviceModels: string[];
   /**
-   * Every device on this extension, in record order, connector included: `name` is the `aor` local
-   * part (`sip:101b@acme.example` → `101b`) — the device NAME as the portal shows it — `model` is
+   * Every device on this extension, in record order, connector included: `name` is the local part of its
+   * `device` SIP URI, or of `aor` when that is all the record has (`sip:101b@acme.example` → `101b`) —
+   * the device NAME as the portal shows it — `model` is
    * `device-models-model` (`(unknown)` when blank on a handset, `''` for the Teams connector, which
    * 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;
 }
@@ -106,6 +140,14 @@ export interface NumberItem {
   key: string /* did:<phonenumber>, or did:~<hash> when the number is blank */;
   number: string;
   kind: 'local' | 'tollFree';
+  /**
+   * This number is handed to a fax server — see the module doc. `false` whenever the caller supplied no
+   * `faxServerHosts`, since without a host list nothing here can tell a fax line from any other number.
+   *
+   * `kind` is still set on a fax line (a fax number is local or toll-free like any other), but the
+   * COUNTS exclude it from `dids.total`/`local`/`tollFree` and count it under `dids.fax` instead.
+   */
+  fax: boolean;
   /** Where the number routes, for a person: see {@link destinationOf}. `''` when the record says nothing. */
   destination: string;
   /** `dial-rule-description` trimmed — the note the portal writes ("Portal Created: User - 1001"); `''` when blank. */
@@ -125,6 +167,49 @@ export interface DomainInventoryDetail {
   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.
+ */
+export interface InventoryOptions {
+  /**
+   * The hosts a fax line is handed to — an IP or a hostname, as it appears in
+   * `dial-rule-translation-destination-host`. Compared trimmed and case-insensitively; blanks are
+   * ignored. Absent or empty means NO number is a fax line. See the module doc for why this is the
+   * 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. */
 const TOLL_FREE = new Set(['800', '833', '844', '855', '866', '877', '888']);
 
@@ -176,18 +261,81 @@ function isTollFree(raw: string): boolean {
   return nanp.length === 10 && TOLL_FREE.has(nanp.slice(0, 3));
 }
 
-/** The local part of a device's `aor` (`sip:103t@acme.example` → `103t`), read only to test for Teams. */
-function aorLocal(device: Rec): string {
-  const a = str(device.aor).replace(/^sip:/i, '');
+/** The fax-server hosts, trimmed, lower-cased and with blanks dropped — the shape {@link isFaxLine} tests against. */
+function faxHosts(hosts: readonly string[] | undefined): Set<string> {
+  const out = new Set<string>();
+  for (const h of hosts ?? []) { const v = str(h).toLowerCase(); if (v) out.add(v); }
+  return out;
+}
+
+/**
+ * Is this number handed to a fax server? The `dial-rule-translation-destination-host` alone, matched
+ * against the caller's list — never the `dial-rule-description`, which is a note the portal writes and
+ * an operator can edit. An empty host set answers `false` for everything, which is the point: this
+ * library knows no fax server of its own.
+ */
+function isFaxLine(p: Rec, hosts: Set<string>): boolean {
+  if (!hosts.size) return false;
+  return hosts.has(str(p['dial-rule-translation-destination-host']).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.
+ *
+ * **`device` first, `aor` second.** A live `/users/<ext>/devices` record names the device in `device` and
+ * frequently carries no `aor` at all; reading `aor` alone therefore returned `''` on live data, which
+ * blanked every device name on the page AND broke the `<ext>t` Teams test — so a Teams connector read as
+ * `teams: false` and was counted as a handset in `deviceCount` and `devices.total`. Some records carry
+ * both, and then `device` wins, being the field the system actually names the device by. Neither, and the
+ * name is `''` rather than a guess.
+ */
+function deviceName(device: Rec): string {
+  const a = (str(device.device) || str(device.aor)).replace(/^sip:/i, '');
   const at = a.indexOf('@');
   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 whose aor local part is a
-  // bare `t` as a connector. No extension number, no Teams claim.
-  const handsets = ext ? devices.filter((d) => aorLocal(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();
@@ -205,12 +353,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 isTeams = ext ? aorLocal(d) === `${ext}t` : false;
-      return { name: aorLocal(d), 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,
   };
 }
@@ -249,8 +400,14 @@ export function usersByExt(users: Rec[]): Map<string, Rec> {
  * - No destination but an application is set → `to <application>` (`to-connection` → `to connection`,
  *   `to-voicemail` → `to voicemail`).
  * - Neither is set → `''`.
+ *
+ * A FAX LINE — a number whose destination host is one of `faxServerHosts` — short-circuits all of that
+ * and reads `to fax server`, host omitted. Otherwise it would render as `to connection` (which names
+ * plumbing, not a destination) or, on a rule that also carries a destination user, as a bare IP address
+ * beside a customer's phone number. Nobody reading this line needs the fax server's address.
  */
-export function destinationOf(p: Rec, userByExt: Map<string, Rec>): string {
+export function destinationOf(p: Rec, userByExt: Map<string, Rec>, faxServerHosts?: readonly string[]): string {
+  if (isFaxLine(p, faxHosts(faxServerHosts))) return 'to fax server';
   const dest = str(p['dial-rule-translation-destination-user']);
   const app = str(p['dial-rule-application']).replace(/^to-/i, '');
   const host = str(p['dial-rule-translation-destination-host']);
@@ -288,7 +445,7 @@ export function destinationOf(p: Rec, userByExt: Map<string, Rec>): string {
  * countable thing, and one derived row is more honest than two that shuffle. A blank id is a
  * provisioning fault to fix; the fallback only keeps the distinguishable ones apart until it is.
  */
-export function listDomainInventory(snapshot: Snapshot): DomainInventoryDetail {
+export function listDomainInventory(snapshot: Snapshot, opts?: InventoryOptions): DomainInventoryDetail {
   const users: Rec[] = Array.isArray(snapshot.users) ? snapshot.users : [];
   const devicesByUser: Record<string, Rec[]> = (snapshot.devicesByUser ?? {}) as Record<string, Rec[]>;
   const phonenumbers: Rec[] = Array.isArray(snapshot.phonenumbers) ? snapshot.phonenumbers : [];
@@ -297,6 +454,8 @@ export function listDomainInventory(snapshot: Snapshot): DomainInventoryDetail {
 
   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);
@@ -306,16 +465,21 @@ export function listDomainInventory(snapshot: Snapshot): DomainInventoryDetail {
     // 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);
+  // Normalised once, not per number: the host list is the caller's and does not change mid-fold.
+  const hosts = faxHosts(opts?.faxServerHosts);
   const dids: NumberItem[] = phonenumbers.map((p) => {
     const number = str(p.phonenumber);
     const kind: 'local' | 'tollFree' = isTollFree(number) ? 'tollFree' : 'local';
-    const destination = destinationOf(p, userByExt);
+    const fax = isFaxLine(p, hosts);
+    // The KEY does not carry `fax`. It is a fact about how the number is routed today, and routing a
+    // number to the fax server must not orphan every decision a consumer recorded against it.
+    const destination = fax ? 'to fax server' : destinationOf(p, userByExt);
     const description = str(p['dial-rule-description']);
-    return { key: identityKey('did', number, JSON.stringify({ number, kind })), number, kind, destination, description };
+    return { key: identityKey('did', number, JSON.stringify({ number, kind })), number, kind, fax, destination, description };
   });
   const e911Addresses: AddressItem[] = addresses.map((a, i) => {
     const id = str(a['emergency-address-id']);
@@ -339,8 +503,8 @@ export function listDomainInventory(snapshot: Snapshot): DomainInventoryDetail {
 }
 
 /** The counts, as a fold over {@link listDomainInventory} so the two can never disagree. */
-export function countDomainInventory(snapshot: Snapshot): DomainInventory {
-  return countInventoryDetail(listDomainInventory(snapshot));
+export function countDomainInventory(snapshot: Snapshot, opts?: InventoryOptions): DomainInventory {
+  return countInventoryDetail(listDomainInventory(snapshot, opts));
 }
 
 /**
@@ -353,7 +517,7 @@ export function countInventoryDetail(d: DomainInventoryDetail): DomainInventory
     systemUsers: { total: d.systemUsers.length, byServiceCode: {} },
     transcriptionEnabled: 0,
     teamsConnected: 0,
-    dids: { total: d.dids.length, tollFree: 0, local: 0 },
+    dids: { total: 0, tollFree: 0, local: 0, fax: 0, all: d.dids.length },
     e911Addresses: d.e911Addresses.length,
     smsNumbers: d.smsNumbers.length,
     devices: { total: 0, byModel: {} },
@@ -371,7 +535,15 @@ export function countInventoryDetail(d: DomainInventoryDetail): DomainInventory
     inv.devices.total += x.deviceCount;
     for (const m of x.deviceModels) bump(inv.devices.byModel, m);
   }
-  for (const n of d.dids) { if (n.kind === 'tollFree') inv.dids.tollFree++; else inv.dids.local++; }
+  // A fax line is billed as a fax line, so it lands in `fax` and in NEITHER of the two DID buckets —
+  // counting it as both would bill one number twice on a rulebook that has a rule for each. `fax` is
+  // read off the item rather than recomputed: an item list a consumer FILTERED still carries it, and a
+  // list built by a pre-0.7.0 lib has no `fax` at all, which reads as false and counts as it always did.
+  for (const n of d.dids) {
+    if (n.fax) { inv.dids.fax++; continue; }
+    inv.dids.total++;
+    if (n.kind === 'tollFree') inv.dids.tollFree++; else inv.dids.local++;
+  }
   return inv;
 }
 
@@ -393,9 +565,14 @@ export function itemsFor(detail: DomainInventoryDetail, path: string): Inventory
   if (path === 'extensions.withNoDevice') return ex.filter((x) => !x.anyDevice);
   if (path === 'transcriptionEnabled') return ex.filter((x) => x.transcription);
   if (path === 'teamsConnected') return ex.filter((x) => x.teams);
-  if (path === 'dids.total') return detail.dids;
-  if (path === 'dids.tollFree') return detail.dids.filter((n) => n.kind === 'tollFree');
-  if (path === 'dids.local') return detail.dids.filter((n) => n.kind === 'local');
+  // The three DID paths exclude fax lines, exactly as the counts do — a `counts: "dids.total"` rule
+  // whose observed number left the fax lines out but whose item list showed them would offer an
+  // operator rows to accept that the number above them does not count.
+  if (path === 'dids.total') return detail.dids.filter((n) => !n.fax);
+  if (path === 'dids.tollFree') return detail.dids.filter((n) => !n.fax && n.kind === 'tollFree');
+  if (path === 'dids.local') return detail.dids.filter((n) => !n.fax && n.kind === 'local');
+  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 === 'smsNumbers') return detail.smsNumbers;
   return undefined;

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`);

package/src/resolver.ts

@@ -24,6 +24,7 @@
  */
 
 import type { EdgeKind, FlowGraph, FlowNode, NodeKind, Rec, Snapshot } from './model.js';
+import { DEFAULT_DEVICE_SUFFIXES } from './inventory.js';
 
 export interface EntityRef {
   kind: 'did' | 'user' | 'queue' | 'attendant';
@@ -42,27 +43,49 @@ const GREET_MAX = 90;
 const trim = (v: string, max = GREET_MAX): string => (v.length > max ? `${v.slice(0, max - 1).trimEnd()}…` : v);
 
 /**
- * Endpoint type by the agent-id / extension letter suffix (heuristic):
- *   wp → SNAPmobile Web (browser phone) · t → Microsoft Teams · m → SNAPmobile (mobile) ·
- *   r → mobile/desktop app · b / other lower letters → usually a desk phone.
+ * A diagram needs a glyph, and a suffix legend carries none — so the icons are the resolver's own,
+ * keyed by the same suffixes. `r` is here without being in the legend on purpose: it is the conventional
+ * NetSapiens+Ringotel app suffix, common enough to draw with a phone rather than a desk handset, but not
+ * something NetSapiens ships, so it has no place in a table this library states as fact.
+ *
+ * **Both tables are prototype-free.** The key is a device-name suffix off a snapshot, so `constructor`,
+ * `toString` and `hasOwnProperty` are all reachable keys; on a plain object literal each of them answers
+ * with something inherited and truthy, and `?? 'desk phone'` then never fires. A `Map` would do as well;
+ * `Object.create(null)` keeps the lookup a subscript.
+ */
+const SUFFIX_ICONS: Record<string, string> = Object.assign(Object.create(null) as Record<string, string>,
+  { wp: '🌐', t: '💻', m: '📱', r: '📱' });
+/** Kinds for suffixes {@link DEFAULT_DEVICE_SUFFIXES} does not name. `r` for the reason above; anything
+ *  else lower-cased (`b`, and the rest) is a desk phone, which is what an unadorned device usually is.
+ *  Prototype-free for the reason above. */
+const SUFFIX_FALLBACK_KINDS: Record<string, string> = Object.assign(Object.create(null) as Record<string, string>,
+  { r: 'app' });
+
+/**
+ * Endpoint type by the agent-id / extension letter suffix (heuristic). The KIND comes from
+ * {@link DEFAULT_DEVICE_SUFFIXES} — the same legend `listDomainInventory` labels a device with, so a
+ * suffix means one thing across this library and the two cannot drift — with the icons above supplying
+ * what the legend does not.
+ *
  * Exact device info (model, MAC, transport) IS available via the device API but isn't pulled yet —
- * see ARCHITECTURE.md → NetSapiens routing model; this suffix guess is the cheap approximation.
+ * see ARCHITECTURE.md → NetSapiens routing model; this suffix guess is the cheap approximation. Note the
+ * resolver reads the DEFAULT legend and takes no options: a call flow is drawn from a snapshot alone, and
+ * a deployment's own suffixes reach the inventory through `InventoryOptions.deviceSuffixes` instead.
+ *
+ * Exported for its own test. Not on the package surface (`index.ts`) — it is an internal heuristic, and
+ * a consumer wanting the legend should read `DEFAULT_DEVICE_SUFFIXES`, which is the thing being stated.
  */
-function deviceKindBySuffix(suffix: string): { icon: string; kind: string } {
-  switch (suffix.toLowerCase()) {
-    case 'wp':
-      return { icon: '🌐', kind: 'web app' };
-    case 't':
-      return { icon: '💻', kind: 'Teams' };
-    case 'm':
-      return { icon: '📱', kind: 'mobile app' };
-    case 'r':
-      return { icon: '📱', kind: 'app' };
-    case '':
-      return { icon: '', kind: '' };
-    default:
-      return { icon: '📞', kind: 'desk phone' }; // b and other letters
-  }
+export function deviceKindBySuffix(suffix: string): { icon: string; kind: string } {
+  const k = suffix.toLowerCase();
+  if (!k) return { icon: '', kind: '' };
+  // `Object.hasOwn` rather than a truthiness test: `DEFAULT_DEVICE_SUFFIXES` is a plain object, so
+  // `[k]` on an inherited name answers a function whose `.label` is undefined — which happens to fall
+  // through correctly, and would stop doing so the day an entry gained an optional field read here.
+  const entry = Object.hasOwn(DEFAULT_DEVICE_SUFFIXES, k) ? DEFAULT_DEVICE_SUFFIXES[k] : undefined;
+  return {
+    icon: SUFFIX_ICONS[k] ?? '📞',
+    kind: entry?.label ?? SUFFIX_FALLBACK_KINDS[k] ?? 'desk phone',
+  };
 }
 
 /** Compact agent queue-priority badge: "P" + a keycap digit (e.g. P2️⃣). Priority is a cross-queue