@dszp/netsapiens-lib 0.1.9 → 0.3.1

package/src/index.ts

@@ -0,0 +1,120 @@
+/**
+ * Public API of the portable call-flow library — the surface any host imports (Cloudflare
+ * Worker, an onboarding CLI / review page / build-preview, the portal viewer). Everything
+ * re-exported here is Node-free and runtime-portable; any Node-only host code (e.g. a CLI) lives
+ * outside this surface.
+ *
+ * Typical use in another project:
+ *   import { resolveFlow, toMermaid, renderGalleryHtml, verify } from '@dszp/netsapiens-lib';
+ *   const graph = resolveFlow(snapshot, { kind: 'did', ref: '13175550100' });
+ *   const html  = renderGalleryHtml(snapshot.meta.domain, [graph]);
+ */
+
+export type { FlowGraph, FlowNode, FlowEdge, NodeKind, EdgeKind, Snapshot, Rec } from './model.js';
+export { resolveFlow, listEntities, type EntityRef } from './resolver.js';
+export { toMermaid, type FlowTheme, type MermaidOptions } from './mermaid.js';
+export {
+  THEMES,
+  DEFAULT_LIGHT_THEME,
+  DEFAULT_DARK_THEME,
+  NODE_LIGHT,
+  NODE_DARK,
+  NODE_SLATE,
+  NODE_A11Y,
+  type ThemeDef,
+  type ThemeChrome,
+  type ThemeMode,
+  type NodePalette,
+} from './themes.js';
+export {
+  renderGalleryHtml,
+  renderFlowCards,
+  renderFlowCard,
+  mermaidBootstrap,
+  flowAnchorId,
+  type GalleryOptions,
+  type CardOptions,
+} 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, listDomainInventory, itemsFor, itemLabel, type DomainInventory, type DomainInventoryDetail, type ExtensionItem, type NumberItem, type AddressItem, type SmsItem, type InventoryItem } from './inventory.js';
+export { NsWriteClient, type NsWriteClientConfig } from './nsWriteClient.js';
+export {
+  supportsSynchronous,
+  SYNCHRONOUS_OPERATIONS,
+  type SynchronousMethod,
+  type SynchronousOperation,
+} from './nsSynchronous.js';
+export {
+  ensureNsDevice,
+  generateSipPassword,
+  SIP_PW_FIELD,
+  type NsDeviceWriter,
+  type EnsureNsDeviceOptions,
+  type EnsureNsDeviceResult,
+} from './nsDevice.js';
+export { NsAuthClient, NsAuthError, type NsAuthClientConfig, type NsTokenResponse } from './nsAuthClient.js';
+export {
+  NsSubscriptionsClient,
+  NsSubscriptionConflictError,
+  SUBSCRIPTION_MODELS,
+  isSubscriptionModel,
+  nsDatetime,
+  parseNsDatetime,
+  subscriptionFromWire,
+  createInputToWire,
+  updateInputToWire,
+  planSubscriptions,
+  type SubscriptionModel,
+  type SubscriptionStatus,
+  type Subscription,
+  type CreateSubscriptionInput,
+  type UpdateSubscriptionInput,
+  type NsSubscriptionsClientConfig,
+  type DesiredSubscription,
+  type SubscriptionAction,
+  type PlanSubscriptionsOptions,
+} from './nsSubscriptions.js';
+export {
+  verify,
+  validateJwtFormat,
+  extractContext,
+  assertClaims,
+  verifyHs256Signature,
+  normalizeToken,
+  tokenKey,
+  MemoryVerdictCache,
+  type JwtVerdict,
+  type JwtContext,
+  type ClaimExpectations,
+  type VerdictCache,
+  type VerifyOptions,
+  type FormatResult,
+} from './jwt.js';
+export { type CallSensitivity, needsFreshAuth, SENSITIVITY_NOTE } from './sensitivity.js';
+export {
+  toPrincipal,
+  parseOperator,
+  isResellerScope,
+  isAdminScope,
+  type Principal,
+  type Operator,
+  type Scope,
+} from './principal.js';
+export {
+  ruleMatches,
+  isAllowed,
+  can,
+  type PolicyRule,
+  type Policy,
+  type FeaturePolicies,
+} from './policy.js';
+export {
+  evaluateEligibility,
+  type SoftCategory,
+  type EligibilityConfig,
+  type EligUser,
+  type EligContext,
+  type EligTier,
+  type EligResult,
+} from './eligibility.js';

package/src/inventory.selftest.ts

@@ -0,0 +1,213 @@
+/** Offline test for the domain inventory counter. pnpm test:inventory */
+import { countDomainInventory, listDomainInventory, itemsFor, itemLabel } from './inventory.js';
+import type { Snapshot } from './model.js';
+
+let pass = 0, fail = 0;
+const ok = (c: boolean, m: string) => { c ? pass++ : fail++; console.log(`${c ? 'PASS' : 'FAIL'} ${m}`); };
+
+const snap: Snapshot = {
+  meta: { domain: 'acme.example' },
+  users: [
+    { user: '100', 'user-scope': 'Basic User', 'service-code': '', 'voicemail-transcription-enabled': 'no', 'name-first-name': 'Ann', 'name-last-name': 'Lee', site: 'North' },
+    { user: '101', 'user-scope': 'Basic User', 'service-code': 'premium', 'voicemail-transcription-enabled': 'yes' },
+    { user: '102', 'user-scope': 'Office Manager', 'service-code': 'premium', 'voicemail-transcription-enabled': 'voicebase' },
+    { user: '103', 'user-scope': 'Basic User', 'service-code': '' },
+    { user: '104', 'user-scope': 'Basic User', 'service-code': '' },
+    { user: '700', 'user-scope': 'Basic User', 'service-code': 'system-aa' },
+    { user: '701', 'user-scope': 'Basic User', 'service-code': 'system-queue' },
+    { user: '702', 'user-scope': 'Basic User', 'service-code': 'system-tod' },
+  ],
+  devicesByUser: {
+    '100': [{ aor: 'sip:100@acme.example', 'device-models-model': 'Yealink T54W' }],
+    '101': [
+      { aor: 'sip:101a@acme.example', 'device-models-model': 'Yealink T54W' },
+      { aor: 'sip:101b@acme.example', 'device-models-model': 'Yealink T31P' },
+      { aor: 'sip:101c@acme.example', 'device-models-model': '' },
+    ],
+    '102': [{ aor: 'sip:102@acme.example', 'device-models-model': 'Yealink T31P' }],
+    '103': [{ aor: 'sip:103t@acme.example', 'device-models-model': 'Teams' }],
+  },
+  phonenumbers: [
+    { phonenumber: '13175550100' }, { phonenumber: '13175550101' },
+    { phonenumber: '18005550102' }, { phonenumber: '18335550103' },
+  ],
+  addresses: [
+    { 'emergency-address-id': 'a-1', 'address-name': 'HQ', 'address-line-1': '1 Main St', 'address-city': 'Springfield' },
+    { 'emergency-address-id': 'a-2', 'address-name': 'Annex' },
+  ],
+  smsnumbers: [{ number: '13175550100' }],
+} as Snapshot;
+
+const inv = countDomainInventory(snap);
+
+ok(inv.extensions.total === 5, 'five real extensions — the three system-* users are not extensions');
+ok(inv.extensions.byScope['Basic User'] === 4, 'four Basic User extensions');
+ok(inv.extensions.byScope['Office Manager'] === 1, 'one Office Manager extension');
+ok(inv.extensions.byScope['system-aa'] === undefined, 'byScope never carries a system user');
+ok(inv.extensions.byServiceCode[''] === 3, 'the empty service code is a key, not a dropped bucket');
+ok(inv.extensions.byServiceCode['premium'] === 2, 'two premium-coded extensions');
+ok(inv.extensions.byDeviceCount['0'] === 2, 'two extensions with no device');
+ok(inv.extensions.byDeviceCount['1'] === 2, 'two extensions with one device');
+ok(inv.extensions.byDeviceCount['2'] === 0, 'none with exactly two');
+ok(inv.extensions.byDeviceCount['3+'] === 1, 'one extension with three devices lands in 3+');
+ok(inv.systemUsers.total === 3, 'three system users');
+ok(inv.systemUsers.byServiceCode['system-aa'] === 1, 'one auto attendant');
+ok(inv.systemUsers.byServiceCode['system-queue'] === 1, 'one queue');
+ok(inv.systemUsers.byServiceCode['system-tod'] === 1, 'one time-of-day');
+ok(inv.transcriptionEnabled === 2, 'yes and a provider name both count; no and absent do not');
+ok(inv.dids.total === 4, 'four phone numbers');
+ok(inv.dids.tollFree === 2, '800 and 833 are toll-free');
+ok(inv.dids.local === 2, 'and the rest are local');
+ok(inv.e911Addresses === 2, 'two address records');
+ok(inv.smsNumbers === 1, 'one SMS number');
+ok(inv.devices.total === 5, 'five devices across all extensions');
+ok(inv.devices.byModel['Yealink T54W'] === 2, 'two T54W');
+ok(inv.devices.byModel['Yealink T31P'] === 2, 'two T31P');
+ok(inv.devices.byModel['(unknown)'] === 1, 'a device with no model is counted under (unknown), never dropped');
+
+// An empty snapshot must answer zeros, not throw — a domain can genuinely have nothing.
+const empty = countDomainInventory({ meta: { domain: 'empty.example' } } as Snapshot);
+ok(empty.extensions.total === 0, 'empty snapshot: no extensions');
+ok(empty.dids.total === 0 && empty.dids.tollFree === 0 && empty.dids.local === 0, 'empty snapshot: no numbers');
+ok(empty.devices.total === 0, 'empty snapshot: no devices');
+ok(empty.smsNumbers === 0 && empty.e911Addresses === 0, 'empty snapshot: no addresses and no SMS numbers');
+
+// Devices belonging to a system user are not counted: they are not seats and never appear on a bill.
+const sysDev = countDomainInventory({
+  meta: { domain: 'sys.example' },
+  users: [{ user: '700', 'service-code': 'system-aa' }],
+  devicesByUser: { '700': [{ aor: 'sip:700@sys.example', 'device-models-model': 'Yealink T54W' }] },
+} as Snapshot);
+ok(sysDev.devices.total === 0, 'a system user device is not counted');
+
+// ── listDomainInventory ─────────────────────────────────────────────────────────────────────────────
+{
+  const d = listDomainInventory(snap);
+  ok(d.extensions.length === 5, '[list] five real extensions');
+  ok(d.systemUsers.length === 3, '[list] three system users, listed apart');
+  const e100 = d.extensions.find((x) => x.ext === '100')!;
+  ok(e100.key === 'ext:100', '[list] an extension key is ext:<user>');
+  ok(e100.name === 'Ann Lee', '[list] name is first + last');
+  ok(e100.site === 'North', '[list] site is carried');
+  ok(e100.deviceCount === 1 && e100.deviceModels[0] === 'Yealink T54W', '[list] device count and models, never the MAC');
+  ok(e100.teams === false, '[list] a desk phone is not Teams');
+  const e103 = d.extensions.find((x) => x.ext === '103')!;
+  ok(e103.teams === true, '[list] a device whose aor local part is <ext>t marks the extension Teams-connected');
+  ok(e103.deviceCount === 0 && e103.deviceModels.length === 0, '[list] and that connector is not counted as a device');
+  ok(d.extensions.find((x) => x.ext === '101')!.transcription === true, '[list] transcription flag');
+  ok(d.extensions.find((x) => x.ext === '103')!.name === '', '[list] a user with no name has an empty name, not "undefined undefined"');
+  ok(d.extensions.find((x) => x.ext === '103')!.anyDevice === true, '[list] an extension with only the Teams connector still has a device');
+  ok(d.extensions.find((x) => x.ext === '104')!.anyDevice === false, '[list] and one with nothing has none');
+  ok(d.dids.length === 4 && d.dids.filter((n) => n.kind === 'tollFree').length === 2, '[list] numbers with kind');
+  ok(d.dids[0]!.key === 'did:13175550100', '[list] a number key is did:<phonenumber>');
+  ok(d.e911Addresses.length === 2, '[list] two address items');
+  ok(d.e911Addresses[0]!.key === 'addr:a-1', '[list] an address key is addr:<emergency-address-id>');
+  ok(d.e911Addresses[0]!.label === 'HQ — 1 Main St, Springfield', '[list] an address label is name — line 1, city');
+  ok(d.e911Addresses[1]!.label === 'Annex', '[list] and degrades to whatever parts exist');
+  ok(d.smsNumbers.length === 1 && d.smsNumbers[0]!.key === 'sms:13175550100', '[list] an SMS key is sms:<number>');
+  for (const x of d.extensions) ok(!JSON.stringify(x).includes('aor') && !JSON.stringify(x).includes('sip:'), `[list] no aor leaks on ${x.ext}`);
+}
+
+// ── counts are a fold over the lists ─────────────────────────────────────────────────────────────────
+{
+  const c = countDomainInventory(snap);
+  const d = listDomainInventory(snap);
+  ok(c.extensions.total === d.extensions.length, '[fold] extensions.total equals the list length');
+  ok(c.transcriptionEnabled === d.extensions.filter((x) => x.transcription).length, '[fold] transcription count equals the flagged items');
+  ok(c.teamsConnected === 1, '[fold] teamsConnected is a new numeric leaf');
+  ok(c.devices.total === 5, '[fold] the Teams connector is excluded from devices.total (still 5)');
+  ok(c.extensions.byDeviceCount['0'] === 2, '[fold] and from byDeviceCount — 103 and 104 have zero handsets');
+  ok(c.extensions.withAnyDevice === 4 && c.extensions.withNoDevice === 1, '[fold] device presence counts, connector included');
+  ok(c.extensions.withAnyDevice + c.extensions.withNoDevice === c.extensions.total, '[fold] the two presence leaves partition the total');
+  ok(c.dids.total === d.dids.length, '[fold] dids.total equals the number list length');
+  ok(c.dids.tollFree === d.dids.filter((n) => n.kind === 'tollFree').length, '[fold] dids.tollFree equals the toll-free items');
+  ok(c.e911Addresses === d.e911Addresses.length && c.smsNumbers === d.smsNumbers.length, '[fold] address and SMS counts equal the lists');
+}
+
+// ── itemsFor ──────────────────────────────────────────────────────────────────────────────────────────
+{
+  const d = listDomainInventory(snap);
+  const keys = (p: string) => (itemsFor(d, p) ?? []).map((x) => x.key).join(',');
+  ok(keys('extensions.total') === 'ext:100,ext:101,ext:102,ext:103,ext:104', '[itemsFor] extensions.total is every extension');
+  ok(keys('extensions.byScope.Office Manager') === 'ext:102', '[itemsFor] byScope filters on scope');
+  ok(keys('extensions.byServiceCode.premium') === 'ext:101,ext:102', '[itemsFor] byServiceCode filters on service code');
+  ok(keys('extensions.byServiceCode.') === 'ext:100,ext:103,ext:104', '[itemsFor] the empty service code is addressable with a trailing dot');
+  ok(keys('extensions.byDeviceCount.3+') === 'ext:101', '[itemsFor] byDeviceCount buckets');
+  ok(keys('extensions.withAnyDevice') === 'ext:100,ext:101,ext:102,ext:103', '[itemsFor] withAnyDevice includes the Teams-only extension');
+  ok(keys('extensions.withNoDevice') === 'ext:104', '[itemsFor] withNoDevice is the rest');
+  ok(keys('transcriptionEnabled') === 'ext:101,ext:102', '[itemsFor] transcriptionEnabled is the flagged extensions');
+  ok(keys('teamsConnected') === 'ext:103', '[itemsFor] teamsConnected is the Teams extensions');
+  ok(keys('dids.total').split(',').length === 4, '[itemsFor] dids.total is every number');
+  ok(keys('dids.tollFree') === 'did:18005550102,did:18335550103', '[itemsFor] dids.tollFree is the toll-free numbers');
+  ok(keys('dids.local') === 'did:13175550100,did:13175550101', '[itemsFor] dids.local is the rest');
+  ok(keys('e911Addresses') === 'addr:a-1,addr:a-2', '[itemsFor] addresses');
+  ok(keys('smsNumbers') === 'sms:13175550100', '[itemsFor] SMS numbers');
+  ok(itemsFor(d, 'devices.total') === undefined, '[itemsFor] devices have no item list');
+  ok(itemsFor(d, 'devices.byModel.Yealink T54W') === undefined, '[itemsFor] not even per model');
+  ok(itemsFor(d, 'systemUsers.total') === undefined, '[itemsFor] system users are never compared, so no list');
+  ok(itemsFor(d, 'nonsense.path') === undefined, '[itemsFor] an unknown path is undefined, not []');
+  ok(itemLabel(d.extensions[0]!) === '100 — Ann Lee, North', '[label] extension: ext — name, site');
+  ok(itemLabel(d.extensions[3]!) === '103', '[label] extension with no name and no site is just the number');
+  ok(itemLabel(d.dids[2]!) === '18005550102 (toll-free)', '[label] number with kind');
+  ok(itemLabel(d.e911Addresses[0]!) === 'HQ — 1 Main St, Springfield', '[label] address is its label');
+  ok(itemLabel(d.smsNumbers[0]!) === '13175550100', '[label] SMS is its number');
+}
+
+// ── blank identity fields never collide onto one key ─────────────────────────────────────────────────
+{
+  const blank = {
+    meta: { domain: 'blank.example' },
+    users: [{ 'user-scope': 'Basic User', 'service-code': '', 'name-first-name': 'No', 'name-last-name': 'Id' }],
+    devicesByUser: { '': [{ aor: 'sip:t@blank.example', 'device-models-model': 'Yealink T31P' }] },
+    phonenumbers: [{ phonenumber: '' }, { phonenumber: '' }],
+    addresses: [
+      { 'emergency-address-id': '', 'address-name': 'Suite A', 'address-line-1': '1 Main St', 'address-city': 'Springfield' },
+      { 'emergency-address-id': '', 'address-name': 'Suite B', 'address-line-1': '2 Main St', 'address-city': 'Springfield' },
+    ],
+    smsnumbers: [{ number: '' }, { number: '' }],
+  } as Snapshot;
+  const d = listDomainInventory(blank);
+  const again = listDomainInventory(blank);
+
+  const [a0, a1] = d.e911Addresses;
+  ok(a0!.key.startsWith('addr:~'), '[blank] a blank address id falls back to addr:~<hash>');
+  ok(a1!.key.startsWith('addr:~'), '[blank] and so does the second one');
+  ok(a0!.key !== a1!.key, '[blank] two blank-id addresses on different streets get different keys');
+  ok(a0!.key === again.e911Addresses[0]!.key, '[blank] the derived key is stable across two calls');
+  ok(a1!.key === again.e911Addresses[1]!.key, '[blank] for the second address too');
+  ok(a0!.label !== '', '[blank] a blank-id address still has a non-empty label');
+  ok(a0!.label === 'Suite A — 1 Main St, Springfield', '[blank] and it is the same name — line 1, city label');
+
+  const [n0, n1] = d.dids;
+  ok(n0!.key.startsWith('did:~'), '[blank] a blank number falls back to did:~<hash>');
+  ok(n0!.key === n1!.key, '[blank] two blank numbers share one derived key: nothing distinguishes them');
+  ok(n0!.key === again.dids[0]!.key, '[blank] and that key is stable across two calls');
+
+  const [s0, s1] = d.smsNumbers;
+  ok(s0!.key.startsWith('sms:~'), '[blank] a blank SMS number falls back to sms:~<hash>');
+  ok(s0!.key === s1!.key, '[blank] and two blank SMS numbers do the same');
+
+  const x = d.extensions[0]!;
+  ok(x.key.startsWith('ext:~'), '[blank] a blank user falls back to ext:~<hash>');
+  ok(x.teams === false, '[blank] and a bare `t` aor is not a Teams connector without an extension number to match');
+  ok(x.deviceCount === 1, '[blank] that device is counted as a handset rather than dropped');
+  ok(x.key === again.extensions[0]!.key, '[blank] the extension key is stable across two calls');
+}
+
+// ── a derived key does not depend on where the record sat in the array ───────────────────────────────
+{
+  const numbers = [
+    { phonenumber: '' },
+    { phonenumber: '13175550100' },
+    { phonenumber: '' , 'dial-rule-application': 'to-user' },
+  ];
+  const forward = listDomainInventory({ meta: { domain: 'order.example' }, phonenumbers: numbers } as Snapshot);
+  const reversed = listDomainInventory({ meta: { domain: 'order.example' }, phonenumbers: [...numbers].reverse() } as Snapshot);
+  const derived = (d: ReturnType<typeof listDomainInventory>) =>
+    d.dids.map((n) => n.key).filter((k) => k.startsWith('did:~')).sort().join(',');
+  ok(derived(forward) !== '', '[order] the fixture really does produce derived keys');
+  ok(derived(forward) === derived(reversed), '[order] reversing the phonenumbers array leaves the did:~ keys unchanged');
+}
+
+console.log(`\n${pass} passed, ${fail} failed`);
+if (fail) process.exit(1);

package/src/inventory.ts

@@ -0,0 +1,324 @@
+/**
+ * Count a domain's inventory along the dimensions a VoIP operator actually sells on.
+ *
+ * Pure: it fetches nothing. Feed it a `Snapshot` — from `fetchDomainSnapshot`, a backup, or a
+ * fixture — and it returns fixed, named counts and nothing else.
+ *
+ * ## Counts, and the lists behind them
+ *
+ * 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, an address's label — from an
+ * allowlist of named fields, and `countDomainInventory` is a fold over those same lists. Either way, a
+ * device's MAC and SIP credentials never appear: nothing here returns a raw record, and nothing should
+ * be added that does.
+ *
+ * ## Every countable dimension is a numeric leaf
+ *
+ * A caller comparing this against a billing system addresses a dimension by dotted path —
+ * `extensions.total`, `dids.tollFree`, `extensions.byServiceCode.premium`. Keeping every leaf numeric
+ * is what makes that possible without this module knowing anything about the billing side.
+ *
+ * ## What counts as an extension
+ *
+ * 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.
+ */
+import type { Rec, Snapshot } from './model.js';
+
+export interface DomainInventory {
+  /** Real seats: users whose `service-code` is empty or non-`system-*`. */
+  extensions: {
+    total: number;
+    /** Keyed by the raw `user-scope` value, e.g. "Basic User". */
+    byScope: Record<string, number>;
+    /** Keyed by the raw `service-code`, the empty string included. */
+    byServiceCode: Record<string, number>;
+    /** Multi-device extensions are a real billing shape (a restaurant with four handsets on one seat). */
+    byDeviceCount: Record<'0' | '1' | '2' | '3+', number>;
+    /** Extensions with `anyDevice` true — handset or Teams connector, either counts. */
+    withAnyDevice: number;
+    /** The rest: no handset and no Teams connector. `withAnyDevice + withNoDevice === total`. */
+    withNoDevice: number;
+  };
+  /** `system-aa`, `system-queue`, `system-tod` and any other `system-*` code. Informational. */
+  systemUsers: { total: number; byServiceCode: Record<string, number> };
+  /** 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.
+   */
+  teamsConnected: number;
+  /** Phone numbers on the domain, split by NANP toll-free prefix. */
+  dids: { total: number; tollFree: number; local: number };
+  /** E911 address records on the domain. */
+  e911Addresses: number;
+  /** SMS-enabled numbers on the domain. */
+  smsNumbers: number;
+  /** Devices belonging to real extensions only — a system user's device is not a seat. */
+  devices: { total: number; byModel: Record<string, number> };
+}
+
+/**
+ * One extension, as a billing consumer may see it. An allowlist, not a record: name, site and the
+ * device MODELS are here; the MAC, the SIP credentials and the email are not, and nothing here should
+ * be added that carries one.
+ */
+export interface ExtensionItem {
+  /**
+   * `ext:<user>` — the stable identity a consumer records a decision against. When `user` is blank
+   * the key falls back to `ext:~<hash>` of the remaining fields (see {@link listDomainInventory}),
+   * which keeps two differently-named nameless records apart and deliberately merges two whose
+   * fields are identical.
+   */
+  key: string;
+  ext: string;
+  /** `name-first-name` + `name-last-name`, trimmed; `''` when both are blank. */
+  name: string;
+  /** The user's `site`; `''` when none. */
+  site: string;
+  scope: string;
+  /** `service-code`, `''` included. */
+  serviceCode: string;
+  transcription: boolean;
+  /** See {@link DomainInventory.teamsConnected}. */
+  teams: boolean;
+  /** Handsets only — the Teams connector is excluded. */
+  deviceCount: number;
+  /** `device-models-model` per handset, `(unknown)` when blank. Never the MAC. */
+  deviceModels: string[];
+  /** `deviceCount > 0 || teams` — has a device of any kind, handset or connector. */
+  anyDevice: boolean;
+}
+export interface NumberItem { key: string /* did:<phonenumber>, or did:~<hash> when the number is blank */; number: string; kind: 'local' | 'tollFree' }
+export interface AddressItem { key: string /* addr:<emergency-address-id>, or addr:~<hash> when the id is blank */; label: string }
+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 interface DomainInventoryDetail {
+  /** Real seats only, same rule as the count. */
+  extensions: ExtensionItem[];
+  /** Informational, never compared. */
+  systemUsers: ExtensionItem[];
+  dids: NumberItem[];
+  e911Addresses: AddressItem[];
+  smsNumbers: SmsItem[];
+}
+
+/** 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']);
+
+const str = (v: unknown): string => (typeof v === 'string' ? v.trim() : v == null ? '' : String(v).trim());
+const bump = (into: Record<string, number>, key: string): void => { into[key] = (into[key] ?? 0) + 1; };
+
+/**
+ * FNV-1a over a string, as eight lowercase hex digits. Synchronous and dependency-free on purpose:
+ * `crypto.subtle.digest` is async, and an item key is built inside a pure, synchronous fold.
+ * This is an identity, not a checksum — nothing here defends against a chosen collision.
+ */
+function hash32(s: string): string {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return (h >>> 0).toString(16).padStart(8, '0');
+}
+
+/**
+ * `<kind>:<id>` when the record names itself, `<kind>:~<hash of seed>` when it does not. A blank
+ * identity field would otherwise hand every nameless record of that kind the same key, and a
+ * consumer keying decisions by it would accept one record and believe it had accepted all of them.
+ * The `~` is what tells a reader the key is derived rather than the system's own id.
+ *
+ * The seed is the record's OWN fields and nothing else — never its position in the array. A key that
+ * depended on position would change under a re-fetch that reordered the list, orphaning every
+ * decision a consumer had recorded against it. The price is that two blank records whose remaining
+ * fields are identical collapse onto ONE key, and that is the right trade: a number with no number
+ * is not a countable thing, and one derived row is more honest than two that shuffle.
+ */
+function identityKey(kind: string, id: string, seed: string): string {
+  return id ? `${kind}:${id}` : `${kind}:~${hash32(seed)}`;
+}
+
+/** Is this user one of NetSapiens' internal routing objects rather than a seat? */
+function isSystemUser(user: Rec): boolean {
+  return str(user['service-code']).toLowerCase().startsWith('system-');
+}
+
+/**
+ * Toll-free test on the digits alone. `+1 (800) 555-0102`, `18005550102` and `8005550102` all read as
+ * toll-free; anything that is not a 10- or 11-digit NANP number is counted local rather than guessed at.
+ */
+function isTollFree(raw: string): boolean {
+  const digits = raw.replace(/\D+/g, '');
+  const nanp = digits.length === 11 && digits.startsWith('1') ? digits.slice(1) : digits;
+  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, '');
+  const at = a.indexOf('@');
+  return at === -1 ? a : a.slice(0, at);
+}
+
+function extensionItem(u: Rec, devices: Rec[]): 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;
+  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();
+  const scope = str(u['user-scope']);
+  const serviceCode = str(u['service-code']);
+  return {
+    key: identityKey('ext', ext, `${scope}\u0000${serviceCode}\u0000${name}`),
+    ext,
+    name,
+    site: str(u.site),
+    scope,
+    serviceCode,
+    transcription: transcription !== '' && transcription !== 'no',
+    teams,
+    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)'),
+    anyDevice: handsets.length > 0 || teams,
+  };
+}
+
+/**
+ * The items behind every count. Pure. Fields are copied by name from an allowlist; no record passes
+ * through, so a device's MAC or SIP password cannot reach a consumer by accident.
+ *
+ * ## Item keys, and what happens when the identity field is blank
+ *
+ * Each item's `key` is `<kind>:<the record's own id>` — `ext:1000`, `did:13175550100`,
+ * `addr:a-1`, `sms:13175550100`. NetSapiens will hand back a record whose id is blank, and a key of
+ * `addr:` shared by two records is worse than no key: a consumer recording an acceptance against it
+ * accepts both. So a blank id falls back to `<kind>:~<hash>`, an FNV-1a over whatever else names the
+ * record — an address by its name, street line and city; an extension by scope, service code and
+ * name; a number or SMS number by the (blank) number itself. No seed carries the array index, so a
+ * re-fetch that reorders the list returns the same keys. Two blank records that agree on every
+ * remaining field therefore land on ONE key rather than two: a number with no number is not a
+ * 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 {
+  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 : [];
+  const addresses: Rec[] = Array.isArray(snapshot.addresses) ? snapshot.addresses : [];
+  const smsnumbers: Rec[] = Array.isArray(snapshot.smsnumbers) ? snapshot.smsnumbers : [];
+
+  const extensions: ExtensionItem[] = [];
+  const systemUsers: ExtensionItem[] = [];
+  for (let i = 0; i < users.length; i++) {
+    const u = users[i]!;
+    const ext = str(u.user);
+    // A blank `user` is looked up too, rather than handed an empty device list. This library's own
+    // `fetchDomainSnapshot` never files anything under `''` — it skips a blank extension before the
+    // device read (see `nsClient.ts`) — so this lookup can only hit in a snapshot built elsewhere,
+    // 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] ?? []);
+    (isSystemUser(u) ? systemUsers : extensions).push(item);
+  }
+  const dids: NumberItem[] = phonenumbers.map((p) => {
+    const number = str(p.phonenumber);
+    const kind: 'local' | 'tollFree' = isTollFree(number) ? 'tollFree' : 'local';
+    return { key: identityKey('did', number, JSON.stringify({ number, kind })), number, kind };
+  });
+  const e911Addresses: AddressItem[] = addresses.map((a, i) => {
+    const id = str(a['emergency-address-id']);
+    const name = str(a['address-name']);
+    const line1 = str(a['address-line-1']);
+    const city = str(a['address-city']);
+    const where = [line1, city].filter(Boolean).join(', ');
+    const label = [name, where].filter(Boolean).join(' — ');
+    return {
+      key: identityKey('addr', id, `${name} ${line1} ${city}`),
+      // An address with neither an id nor anything to name it by is still a row an operator has to
+      // decide about, so it gets a positional label rather than an empty cell.
+      label: label || id || `(address ${i + 1})`,
+    };
+  });
+  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 };
+}
+
+/** The counts, as a fold over {@link listDomainInventory} so the two can never disagree. */
+export function countDomainInventory(snapshot: Snapshot): DomainInventory {
+  const d = listDomainInventory(snapshot);
+  const inv: DomainInventory = {
+    extensions: { total: 0, byScope: {}, byServiceCode: {}, byDeviceCount: { '0': 0, '1': 0, '2': 0, '3+': 0 }, withAnyDevice: 0, withNoDevice: 0 },
+    systemUsers: { total: d.systemUsers.length, byServiceCode: {} },
+    transcriptionEnabled: 0,
+    teamsConnected: 0,
+    dids: { total: d.dids.length, tollFree: 0, local: 0 },
+    e911Addresses: d.e911Addresses.length,
+    smsNumbers: d.smsNumbers.length,
+    devices: { total: 0, byModel: {} },
+  };
+  for (const s of d.systemUsers) bump(inv.systemUsers.byServiceCode, s.serviceCode);
+  for (const x of d.extensions) {
+    inv.extensions.total++;
+    if (x.scope) bump(inv.extensions.byScope, x.scope);
+    bump(inv.extensions.byServiceCode, x.serviceCode);
+    if (x.transcription) inv.transcriptionEnabled++;
+    if (x.teams) inv.teamsConnected++;
+    if (x.anyDevice) inv.extensions.withAnyDevice++; else inv.extensions.withNoDevice++;
+    const bucket = x.deviceCount >= 3 ? '3+' : (String(x.deviceCount) as '0' | '1' | '2');
+    inv.extensions.byDeviceCount[bucket]++;
+    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++; }
+  return inv;
+}
+
+/**
+ * The items a `counts` path selects — the same vocabulary of dotted paths `countDomainInventory`
+ * answers numbers for. `undefined` means that dimension has no item list (devices, system users, or a
+ * path this module does not know), which is a different fact from an empty list.
+ */
+export function itemsFor(detail: DomainInventoryDetail, path: string): InventoryItem[] | undefined {
+  const ex = detail.extensions;
+  if (path === 'extensions.total') return ex;
+  if (path.startsWith('extensions.byScope.')) { const v = path.slice('extensions.byScope.'.length); return ex.filter((x) => x.scope === v); }
+  if (path.startsWith('extensions.byServiceCode.')) { const v = path.slice('extensions.byServiceCode.'.length); return ex.filter((x) => x.serviceCode === v); }
+  if (path.startsWith('extensions.byDeviceCount.')) {
+    const v = path.slice('extensions.byDeviceCount.'.length);
+    return ex.filter((x) => (x.deviceCount >= 3 ? '3+' : String(x.deviceCount)) === v);
+  }
+  if (path === 'extensions.withAnyDevice') return ex.filter((x) => x.anyDevice);
+  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');
+  if (path === 'e911Addresses') return detail.e911Addresses;
+  if (path === 'smsNumbers') return detail.smsNumbers;
+  return undefined;
+}
+
+/** One line naming an item to a person: what an operator sees when they accept it, and what history keeps. */
+export function itemLabel(item: InventoryItem): string {
+  if ('ext' in item) {
+    const who = [item.name, item.site].filter(Boolean).join(', ');
+    return who ? `${item.ext} — ${who}` : item.ext;
+  }
+  if ('kind' in item) return item.kind === 'tollFree' ? `${item.number} (toll-free)` : item.number;
+  if ('label' in item) return item.label;
+  return item.number;
+}