@dszp/netsapiens-lib 0.1.8 → 0.3.0

package/src/mermaid.ts

@@ -0,0 +1,169 @@
+/**
+ * FlowGraph -> Mermaid flowchart. Node shape + CSS class encode the node kind so a
+ * reader can tell a queue from a mailbox from an external forward at a glance.
+ */
+
+import type { EdgeKind, FlowGraph, FlowNode, NodeKind } from './model.js';
+import { NODE_LIGHT, NODE_DARK } from './themes.js';
+
+/** Wrap a label in the shape delimiters for its kind. */
+function shape(n: FlowNode): string {
+  const text = quote(n);
+  switch (n.kind) {
+    case 'did':
+      return `(${text})`; // stadium
+    case 'timeframe':
+      return `{${text}}`; // diamond decision
+    case 'attendant':
+      return `{{${text}}}`; // hexagon
+    case 'queue':
+      return `[[${text}]]`; // subroutine
+    case 'voicemail':
+      return `[(${text})]`; // cylinder
+    case 'external':
+    case 'trunk':
+    case 'prompt':
+      return `[/${text}/]`; // parallelogram
+    case 'hangup':
+      return `((${text}))`; // circle
+    case 'devices':
+    case 'agents':
+    default:
+      return `[${text}]`; // rectangle
+  }
+}
+
+// Mermaid measures label width in a font that under-measures emoji, so it sizes the node box too
+// narrow and the emoji-bearing line clips on the right (rectangles lack the stadium's built-in slack).
+// Appending two non-breaking spaces to each line makes the MEASURED width include real slack, so the
+// box is drawn wide enough for the rendered emoji. ` ` isn't collapsed and survives esc().
+const PAD = '\u00a0\u00a0';
+
+function quote(n: FlowNode): string {
+  const main = `${esc(n.label)}${PAD}`;
+  let extra = n.sub ? `<br/><small>${esc(n.sub)}${PAD}</small>` : '';
+  // A "header" line (a short label ending in ':' with no interior colon, e.g. "Tier 1:") renders
+  // bold at normal size so it reads as a heading above the small list rows beneath it.
+  if (n.lines?.length)
+    extra += n.lines
+      .map((l) => (/^\S[^:]*:$/.test(l.trim()) ? `<br/><b>${esc(l.trim())}${PAD}</b>` : `<br/><small>${esc(l)}${PAD}</small>`))
+      .join('');
+  return `"${main}${extra}"`;
+}
+
+/**
+ * Escape a dynamic (customer-sourced) label so it can't break Mermaid syntax or inject markup.
+ * Angle brackets, quotes and `#` become entities; newlines collapse to spaces (a raw `\n` would
+ * break the flowchart line). The renderer additionally runs `securityLevel: 'strict'` (DOMPurify +
+ * no click callbacks) as defense-in-depth — so injected tags are neutralized at both layers.
+ * Our own `<br/>`/`<small>` are added around the *escaped* text in quote(), never from input.
+ */
+function esc(t: string): string {
+  return String(t)
+    .replace(/[\r\n]+/g, ' ')
+    .replace(/"/g, '&quot;')
+    .replace(/#/g, '&num;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
+const EDGE_STYLE: Partial<Record<EdgeKind, string>> = {
+  ref: '-.->',
+};
+
+function edgeArrow(kind: EdgeKind): string {
+  return EDGE_STYLE[kind] ?? '-->';
+}
+
+/** Diagram theme. `dark` is the original palette (Cloudflare Worker / live-chart use);
+ *  `light` matches a light review report. */
+export type FlowTheme = 'light' | 'dark';
+export interface MermaidOptions {
+  /** Emit a themed diagram. OMIT for byte-identical legacy output (the Worker relies on this). */
+  theme?: FlowTheme;
+}
+
+// Per-kind node styling comes from the shared theme registry (themes.ts) so palettes live in one
+// place. `dark` = saturated fills + white text (Worker legacy path); `light` = tints + dark text.
+// (The registry also carries the richer viewer themes — slate / a11y / portal — over the same kinds.)
+
+/** Mermaid YAML frontmatter carrying the Tier-0 polish (look: neo) + theme. Static config
+ *  only — no customer data reaches it, so the synthetic-ID invariant is untouched. */
+function frontmatter(theme: FlowTheme): string[] {
+  const base = theme === 'light' ? 'base' : 'dark';
+  const vars =
+    theme === 'light'
+      ? "{fontFamily: 'system-ui, sans-serif', fontSize: '14px', lineColor: '#64748b', primaryTextColor: '#1e293b', primaryBorderColor: '#cbd5e1'}"
+      : "{fontFamily: 'system-ui, sans-serif', fontSize: '14px', lineColor: '#8a94a6'}";
+  return ['---', `config: {look: neo, theme: ${base}, themeVariables: ${vars}}`, '---'];
+}
+
+export function toMermaid(g: FlowGraph, opts?: MermaidOptions): string {
+  const theme = opts?.theme;
+  const palette = theme === 'light' ? NODE_LIGHT : NODE_DARK;
+  // No theme → legacy output (no frontmatter, dark palette): byte-identical to pre-theming.
+  const lines: string[] = theme ? [...frontmatter(theme), 'flowchart TD'] : ['flowchart TD'];
+
+  // Mermaid node IDs must be a safe identifier — but FlowGraph ids are built from raw NS data
+  // (hosts, dialrule params, applications) that can contain '.', ':', '@', '*', spaces, '<>'.
+  // Map every id to a synthetic `n<i>` so no data ever lands in an id position; all human content
+  // lives in the (quoted) labels. Prevents mermaid.render() from throwing on real-world domains.
+  const mid = new Map<string, string>();
+  g.nodes.forEach((n, i) => mid.set(n.id, `n${i}`));
+  const safe = (id: string): string => mid.get(id) ?? `n_${id.replace(/[^A-Za-z0-9_]/g, '_')}`;
+
+  for (const n of g.nodes) lines.push(`  ${safe(n.id)}${shape(n)}`);
+  lines.push('');
+
+  // Merge edges that share the same source, destination and arrow into ONE connector, stacking their
+  // distinct labels (e.g. an AA whose "press 0", "no key / timeout" and "unknown input" all go to the
+  // same voicemail → a single edge labelled with all three on separate lines).
+  const groups = new Map<string, { from: string; to: string; arrow: string; labels: string[]; time: boolean }>();
+  for (const e of g.edges) {
+    const arrow = edgeArrow(e.kind);
+    const key = `${e.from}\u0000${e.to}\u0000${arrow}`;
+    let grp = groups.get(key);
+    if (!grp) {
+      grp = { from: e.from, to: e.to, arrow, labels: [], time: false };
+      groups.set(key, grp);
+    }
+    if (e.kind === 'time') grp.time = true;
+    if (e.label && !grp.labels.includes(e.label)) grp.labels.push(e.label);
+  }
+  for (const grp of groups.values()) {
+    // Multiple options on one connector → bullet each (left-aligned via host CSS) so it reads as a
+    // list. A lone label is used as-is — it may carry its own `\n` line breaks (e.g. a timeframe:
+    // header line + bulleted schedule segments). Split on `\n` BEFORE esc (esc collapses newlines).
+    // Bullet only single-line labels when merging; a label that's already a multi-line "header +
+    // bulleted segments" (a timeframe schedule) keeps its own formatting so its header isn't bulleted.
+    // sibling OPTIONS get a bullet; TIMEFRAME branches (time_open, otherwise) stay header-level.
+    let rawLines: string[];
+    if (grp.labels.length > 1) rawLines = grp.time ? grp.labels : grp.labels.map((l) => (l.includes('\n') ? l : `• ${l}`));
+    else rawLines = grp.labels[0] ? [grp.labels[0]] : [];
+    // NO nbsp PAD on edge labels (unlike node labels — see quote()). The old trailing-PAD kludge tried
+    // to buy measurement slack so labels like "press *" / "press 2" wouldn't clip, but Mermaid's font
+    // measurement still drifts ~10px under `look: neo`, so the right edge clipped anyway (the recurring
+    // "numbers get cut off"). The durable fix is host CSS: edge-label foreignObjects are `overflow:
+    // visible` (so nothing clips regardless of drift) and `span.edgeLabel` carries symmetric padding —
+    // trailing PAD would only bias that padding rightward and break the even before/after spacing.
+    const body = rawLines
+      .flatMap((l) => l.split('\n'))
+      .map((l) => esc(l))
+      .join('<br/>');
+    const lbl = body ? `|"${body}"|` : '';
+    lines.push(`  ${safe(grp.from)} ${grp.arrow}${lbl} ${safe(grp.to)}`);
+  }
+  lines.push('');
+
+  // class assignments grouped by kind
+  const byKind = new Map<NodeKind, string[]>();
+  for (const n of g.nodes) {
+    if (!byKind.has(n.kind)) byKind.set(n.kind, []);
+    byKind.get(n.kind)!.push(safe(n.id));
+  }
+  for (const [kind, ids] of byKind) {
+    lines.push(`  classDef ${kind} ${palette[kind]}`);
+    lines.push(`  class ${ids.join(',')} ${kind}`);
+  }
+  return lines.join('\n');
+}

package/src/model.ts

@@ -0,0 +1,130 @@
+/**
+ * Normalized call-flow graph — renderer-agnostic. The resolver emits this from a
+ * NetSapiens domain snapshot; the Mermaid emitter (and, later, any other renderer)
+ * consumes it. This is the "real IP" contract from the handoff: a normalized graph JSON.
+ *
+ * Runtime-portable by design: no Node-only imports here or in resolver.ts, so the same
+ * code can run in an onboarding CLI and in a Cloudflare Worker.
+ */
+
+export type NodeKind =
+  | 'did' // inbound phone number
+  | 'timeframe' // time-of-day / schedule decision
+  | 'user' // a subscriber extension
+  | 'devices' // "ring the user's registered devices"
+  | 'queue' // ACD call queue
+  | 'agents' // the agent roster of a queue
+  | 'attendant' // auto attendant
+  | 'prompt' // a played greeting / announcement
+  | 'voicemail' // a mailbox (terminal)
+  | 'external' // off-net / PSTN forward (terminal)
+  | 'trunk' // SIP connection / trunk (e.g. fax server) (terminal)
+  | 'hangup' // dead end / no route
+  | 'unknown';
+
+export type EdgeKind =
+  | 'route' // plain "goes to"
+  | 'time' // a time-of-day branch
+  | 'always' // forward-always (unconditional)
+  | 'noanswer' // ring-no-answer timeout
+  | 'busy' // forward-on-busy
+  | 'unreg' // forward-when-unregistered
+  | 'dnd' // do-not-disturb path
+  | 'dispatch' // queue -> agents
+  | 'overflow' // queue overflow
+  | 'menu' // auto-attendant keypress
+  | 'ref'; // link back to an already-drawn node (breaks a cycle)
+
+export interface FlowNode {
+  id: string;
+  kind: NodeKind;
+  /** Primary label line. */
+  label: string;
+  /** Optional secondary line (e.g. dispatch type, schedule). */
+  sub?: string;
+  /** Optional additional lines rendered one-per-line under the label (e.g. a bulleted agent list). */
+  lines?: string[];
+  /** Full text for a hover tooltip (e.g. a long greeting shown truncated in the label). Viewer-only. */
+  title?: string;
+}
+
+export interface FlowEdge {
+  from: string;
+  to: string;
+  kind: EdgeKind;
+  /** Edge caption (e.g. "open hrs", "no answer 30s"). */
+  label?: string;
+}
+
+export interface FlowGraph {
+  /** Entity the flow was resolved for. */
+  entity: { kind: string; ref: string; label: string };
+  domain: string;
+  rootId: string;
+  nodes: FlowNode[];
+  edges: FlowEdge[];
+  /** Human-facing caveats surfaced during resolution (gaps, unmapped params, cycles). */
+  notes: string[];
+}
+
+// ---------------------------------------------------------------------------
+// Loose snapshot typings. The snapshot is raw NetSapiens JSON with hyphenated
+// keys; we type only what the resolver reads and keep everything index-signature
+// loose so drift in unrelated fields never breaks the build.
+// ---------------------------------------------------------------------------
+
+export type Rec = Record<string, any>;
+
+export interface Snapshot {
+  meta: Rec;
+  domain?: Rec;
+  timeframes?: Rec[];
+  users?: Rec[];
+  devicesByUser?: Record<string, Rec[]>;
+  /**
+   * Extensions whose `/devices` read failed with something other than 404 — present only when
+   * `includeDevices` was asked for. The extension is still in `users`, with no entry in
+   * `devicesByUser`, so a consumer counting devices sees zero for it and must read this list to
+   * know that zero is not a fact.
+   */
+  deviceReadFailures?: string[];
+  callqueues?: Rec[];
+  agentsByQueue?: Record<string, Rec[]>;
+  phonenumbers?: Rec[];
+  /**
+   * E911 address records — GET /domains/{d}/addresses. Present only when the fetch asked for them;
+   * `undefined` means "not read", which is not the same fact as an empty array.
+   */
+  addresses?: 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
+   * that returns the list. Present only when the fetch asked for them.
+   */
+  smsnumbers?: Rec[];
+  autoattendants?: Rec[];
+  dialrulesByPlan?: Record<string, Rec[]>;
+  answerrulesByUser?: Record<string, Rec[]>;
+  /**
+   * Optional per-attendant menu detail, keyed by AA extension — the response of
+   * GET /domains/{d}/users/{ext}/autoattendants/{prompt} (an `auto-attendant` tier +
+   * top-level greeting `audio` + `intro-greetings[]` + `time-frame`). When present, the
+   * resolver renders the real keypress menu; when absent, it emits a "not captured" note.
+   *
+   * Two shapes are accepted:
+   *  - `attendantDetails[ext]`        — a single detail (current live fetch; SV builds AAs on `*`).
+   *  - `attendantDetailsByUser[ext]`  — an ARRAY of details (an enriched backup: an AA may
+   *    have multiple prompts/timeframes). The resolver picks the `*`/Default one as primary and
+   *    flags the rest as a deviation (see the AA backup enrichment spec, Addendum 2026-07-11).
+   */
+  attendantDetails?: Record<string, Rec>;
+  attendantDetailsByUser?: Record<string, Rec[]>;
+  /**
+   * Per-AA dialplan dialrules, keyed by AA extension — the AUTHORITATIVE menu + default routing that
+   * the /autoattendants detail omits (no-key/star/option). From GET /domains/{d}/dialplans/{domain}_{ext}/dialrules.
+   * The resolver reads `Prompt_<startingPrompt-id>.<suffix>` rules: .Default (no-key/timeout), .* (unassigned),
+   * .<digit> (press N), .Case_[...] (dial-by-ext). See ARCHITECTURE.md → NetSapiens routing model.
+   */
+  attendantDialrulesByExt?: Record<string, Rec[]>;
+  [k: string]: any;
+}

package/src/nsAuthClient.selftest.ts

@@ -0,0 +1,60 @@
+/**
+ * Offline test for NsAuthClient — OAuth2 password-grant against a recording mock fetch (no live
+ * creds). Asserts the token endpoint URL + form body, the token body passthrough, NsAuthError on a
+ * non-2xx, and the verifyCredentials fail-closed contract (4xx -> ok:false, 5xx -> rethrow).
+ * tsx src/nsAuthClient.selftest.ts
+ */
+import { NsAuthClient, NsAuthError } from './index.js';
+
+let pass = 0, fail = 0;
+const ok = (c: boolean, m: string) => { c ? pass++ : fail++; console.log(`${c ? '✓' : '✗ FAIL'} ${m}`); };
+
+interface Recorded { url: string; body: string }
+let last: Recorded = { url: '', body: '' };
+const mk = (status: number, body: unknown) =>
+  (async (input: any, init: any = {}) => {
+    last = { url: String(input), body: String(init.body ?? '') };
+    return new Response(typeof body === 'string' ? body : JSON.stringify(body), {
+      status,
+      headers: { 'content-type': 'application/json' },
+    });
+  }) as unknown as typeof fetch;
+
+const cfg = (fetchImpl: typeof fetch) => ({ server: 'api.example.com', clientId: 'cid', clientSecret: 'csec', fetchImpl });
+
+(async () => {
+  // passwordGrant posts a form to the token endpoint and returns the token body.
+  const okBody = { access_token: 'tok', user: '100', domain: 'demo.12345.service' };
+  const res = await new NsAuthClient(cfg(mk(200, okBody))).passwordGrant('100@demo', 'pw');
+  ok(last.url === 'https://api.example.com/ns-api/oauth2/token/', 'passwordGrant posts to the token endpoint');
+  ok(last.body.includes('grant_type=password'), 'passwordGrant body carries grant_type=password');
+  ok(last.body.includes('client_id=cid'), 'passwordGrant body carries client_id');
+  ok(last.body.includes('username=100%40demo'), 'passwordGrant body URI-encodes the username');
+  ok(res.access_token === 'tok' && res.user === '100', 'passwordGrant returns the token body incl. user');
+
+  // passwordGrant throws NsAuthError on a 400 (bad credentials).
+  let err400: any;
+  try { await new NsAuthClient(cfg(mk(400, { error: 'invalid_grant' }))).passwordGrant('x', 'y'); } catch (e) { err400 = e; }
+  ok(err400 instanceof NsAuthError, 'passwordGrant throws NsAuthError on a 400');
+
+  // verifyCredentials returns ok:true with the token on 200.
+  const verifiedOk = await new NsAuthClient(cfg(mk(200, { access_token: 'tok', user: '100' }))).verifyCredentials('100@demo', 'pw');
+  ok(verifiedOk.ok === true && verifiedOk.token?.access_token === 'tok', 'verifyCredentials returns ok:true with the token on 200');
+
+  // verifyCredentials returns ok:false on a 401 (invalid creds).
+  const verified401 = await new NsAuthClient(cfg(mk(401, { error: 'invalid_grant' }))).verifyCredentials('x', 'y');
+  ok(verified401.ok === false && verified401.token === undefined, 'verifyCredentials returns ok:false on a 401');
+
+  // verifyCredentials returns ok:false on a 200 whose body lacks access_token (fail-open regression:
+  // NS can return HTTP 200 with an empty/in-band-error body carrying no token, which is NOT a login).
+  const verifiedTokenless = await new NsAuthClient(cfg(mk(200, { user: '100', domain: 'demo.12345.service' }))).verifyCredentials('x', 'y');
+  ok(verifiedTokenless.ok === false, 'verifyCredentials returns ok:false on a 200 with no access_token');
+
+  // verifyCredentials RETHROWS on a 5xx (caller fails closed).
+  let err503: any;
+  try { await new NsAuthClient(cfg(mk(503, 'upstream down'))).verifyCredentials('x', 'y'); } catch (e) { err503 = e; }
+  ok(err503 instanceof NsAuthError, 'verifyCredentials rethrows NsAuthError on a 503');
+
+  console.log(`\n${pass} passed, ${fail} failed`);
+  process.exit(fail ? 1 : 0);
+})();

package/src/nsAuthClient.ts

@@ -0,0 +1,102 @@
+/**
+ * NsAuthClient — the NetSapiens OAuth2 password-grant surface. Two jobs off one call:
+ *   - verifyCredentials(user, pass): confirm an END USER's credentials (the SSO webhook's auth check).
+ *   - passwordGrant(adminUser, adminPass): mint a reseller/admin access token to use as a write bearer,
+ *     an alternative to a static API key.
+ * Both use the deployment's "master key" (an OAuth application's client_id/client_secret). Node-free
+ * (fetch/URLSearchParams). The token endpoint is form-encoded and returns JSON.
+ *
+ * Fail-closed contract: passwordGrant throws NsAuthError on ANY non-2xx. verifyCredentials treats a 4xx as
+ * "bad credentials" ({ ok:false }) but RETHROWS a 5xx / network error, so a caller cannot mistake an
+ * upstream outage for a failed login.
+ */
+
+import { assertBareServer } from './nsClient.js';
+
+export class NsAuthError extends Error {
+  constructor(message: string, readonly status: number) {
+    super(message);
+    this.name = 'NsAuthError';
+  }
+}
+
+export interface NsTokenResponse {
+  access_token?: string;
+  /** The authenticated user's extension (NetSapiens returns this on the token body). */
+  user?: string;
+  domain?: string;
+  scope?: string;
+  [k: string]: unknown;
+}
+
+export interface NsAuthClientConfig {
+  /** API host, e.g. "api.example.com" (bare — no scheme/path). Token endpoint = https://{server}/ns-api/oauth2/token/ */
+  server: string;
+  /** OAuth application client id (the "master key" id). */
+  clientId: string;
+  /** OAuth application client secret. */
+  clientSecret: string;
+  /** Injectable for tests / non-global fetch. */
+  fetchImpl?: typeof fetch;
+}
+
+export class NsAuthClient {
+  readonly #url: string;
+  readonly #clientId: string;
+  readonly #clientSecret: string;
+  readonly #fetchImpl: typeof fetch;
+
+  constructor(cfg: NsAuthClientConfig) {
+    this.#url = `https://${assertBareServer(cfg.server)}/ns-api/oauth2/token/`;
+    this.#clientId = cfg.clientId;
+    this.#clientSecret = cfg.clientSecret;
+    this.#fetchImpl = cfg.fetchImpl ?? fetch;
+  }
+
+  async passwordGrant(username: string, password: string): Promise<NsTokenResponse> {
+    const body = new URLSearchParams({
+      grant_type: 'password',
+      client_id: this.#clientId,
+      client_secret: this.#clientSecret,
+      username,
+      password,
+      format: 'json',
+    });
+    // Call via a local, NOT this.#fetchImpl(...): the global fetch requires a global `this` in workerd.
+    const doFetch = this.#fetchImpl;
+    const res = await doFetch(this.#url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json' },
+      body: body.toString(),
+    });
+    const text = await res.text();
+    let parsed: unknown = text;
+    if (text) {
+      try { parsed = JSON.parse(text); } catch { /* non-JSON error body */ }
+    }
+    if (!res.ok) {
+      const detail = (typeof parsed === 'object' && parsed !== null ? JSON.stringify(parsed) : String(parsed)).slice(0, 300);
+      throw new NsAuthError(`NS oauth2/token → ${res.status}: ${detail}`, res.status);
+    }
+    return (parsed && typeof parsed === 'object' ? parsed : {}) as NsTokenResponse;
+  }
+
+  /**
+   * Confirm an end user's credentials via OAuth2 password-grant.
+   *
+   * Contract: `ok` is true IF AND ONLY IF the token response carried a non-empty `access_token`.
+   * NetSapiens can return HTTP 200 with an empty/in-band-error body (no `access_token`) — that is
+   * NOT a successful login, so a bare 2xx is not sufficient. A 4xx maps to `{ ok: false }`; a 5xx /
+   * network error rethrows so a caller cannot mistake an upstream outage for a failed login.
+   */
+  async verifyCredentials(username: string, password: string): Promise<{ ok: boolean; token?: NsTokenResponse }> {
+    try {
+      const token = await this.passwordGrant(username, password);
+      if (!token.access_token) return { ok: false };
+      return { ok: true, token };
+    } catch (e) {
+      if (e instanceof NsAuthError && e.status >= 400 && e.status < 500) return { ok: false };
+      throw e; // 5xx / network → fail closed upstream
+    }
+  }
+}

package/src/nsClient.selftest.ts

@@ -0,0 +1,173 @@
+/**
+ * Offline end-to-end test for the portable NS client (no live creds):
+ *   tsx src/nsClient.selftest.ts <snapshot.json> [attendantsDir]
+ *
+ * Serves the NS v2 read endpoints from a real fixture snapshot via a mock fetch, then asserts
+ * that fetchDomainSnapshot() reconstructs a Snapshot which resolveFlow() turns into the SAME
+ * FlowGraph as resolving the raw fixture directly. Proves the client's endpoint map + assembly.
+ */
+import { readFileSync, readdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { NsApiError, NsClient, fetchDomainSnapshot } from './nsClient.js';
+import { resolveFlow, listEntities } from './resolver.js';
+import type { Snapshot } from './model.js';
+
+// The fixture-diff test below (fetchDomainSnapshot vs a raw fixture, resolved both ways) needs a
+// snapshot file and is skipped without one. The fake-client test further down needs nothing but
+// the client, so it always runs — `pnpm exec tsx src/nsClient.selftest.ts` with no args exercises it.
+const snapPath = process.argv[2];
+const raw = snapPath ? (JSON.parse(readFileSync(snapPath, 'utf8')) as Snapshot) : undefined;
+const domain = String(raw?.meta?.domain ?? raw?.domain?.domain ?? '');
+
+// Optional AA menu sidecars keyed by ext.
+const attendantsDir = snapPath ? (process.argv[3] ?? join(resolve(snapPath, '..'), 'attendants')) : undefined;
+const aaByExt: Record<string, unknown> = {};
+try {
+  if (attendantsDir) {
+    for (const f of readdirSync(attendantsDir).filter((f) => f.endsWith('.json'))) {
+      const d = JSON.parse(readFileSync(join(attendantsDir, f), 'utf8'));
+      aaByExt[String(d.user ?? f.replace(/\.json$/, ''))] = d;
+    }
+  }
+} catch {
+  /* no sidecars */
+}
+
+// Mock fetch: route NS v2 read paths to fixture data.
+const j = (body: unknown) => new Response(JSON.stringify(body), { status: 200, headers: { 'content-type': 'application/json' } });
+const notFound = () => new Response('[]', { status: 404 });
+const mockFetch = (async (input: string) => {
+  const path = new URL(String(input)).pathname.replace(/^\/ns-api\/v2/, '');
+  const b = `/domains/${domain}`;
+  if (path === b) return j(raw?.domain ?? { domain });
+  if (path === `${b}/timeframes`) return j(raw?.timeframes ?? []);
+  if (path === `${b}/users`) return j(raw?.users ?? []);
+  if (path === `${b}/callqueues`) return j(raw?.callqueues ?? []);
+  if (path === `${b}/phonenumbers`) return j(raw?.phonenumbers ?? []);
+  if (path === `${b}/autoattendants`) return j(raw?.autoattendants ?? []);
+  let m = path.match(new RegExp(`^${b}/users/([^/]+)/answerrules$`));
+  if (m) return j(raw?.answerrulesByUser?.[decodeURIComponent(m[1]!)] ?? []);
+  m = path.match(new RegExp(`^${b}/callqueues/([^/]+)/agents$`));
+  if (m) return j(raw?.agentsByQueue?.[decodeURIComponent(m[1]!)] ?? []);
+  m = path.match(new RegExp(`^${b}/users/([^/]+)/autoattendants/([^/]+)$`));
+  if (m) {
+    const detail = aaByExt[decodeURIComponent(m[1]!)];
+    return detail ? j(detail) : notFound();
+  }
+  if (path === `${b}/dialplans/${domain}/dialrules`) return j(raw?.dialrulesByPlan?.[domain] ?? []);
+  return notFound();
+}) as unknown as typeof fetch;
+
+let pass = 0;
+let fail = 0;
+const ok = (c: boolean, msg: string) => {
+  c ? pass++ : fail++;
+  console.log(`${c ? '✓' : '✗ FAIL'} ${msg}`);
+};
+
+(async () => {
+  if (raw) {
+    const client = new NsClient({ server: 'mock.local', token: 'x', fetchImpl: mockFetch });
+    const rebuilt = await fetchDomainSnapshot(client, domain, { includeDialrules: true });
+
+    // Feed the raw fixture its sidecar AA details too, so both sides render menus identically.
+    const rawWithAa: Snapshot = { ...raw, attendantDetails: aaByExt as Record<string, any> };
+
+    const ents = listEntities(rebuilt);
+    const cases = [
+      ...ents.dids.map((d) => ({ kind: 'did' as const, ref: d.ref })),
+      ...ents.queues.map((q) => ({ kind: 'queue' as const, ref: q.ref })),
+      ...ents.attendants.map((a) => ({ kind: 'attendant' as const, ref: a.ref })),
+      ...ents.users.map((u) => ({ kind: 'user' as const, ref: u.ref })),
+    ];
+    ok(cases.length > 0, `enumerated ${cases.length} entities from the rebuilt snapshot`);
+
+    let mismatches = 0;
+    for (const c of cases) {
+      const a = JSON.stringify(resolveFlow(rawWithAa, c));
+      const b = JSON.stringify(resolveFlow(rebuilt, c));
+      if (a !== b) {
+        mismatches++;
+        console.log(`   ✗ graph differs for ${c.kind} ${c.ref}`);
+      }
+    }
+    ok(mismatches === 0, `all ${cases.length} flows identical: rebuilt-from-API vs raw fixture`);
+  } else {
+    console.log('(no fixture given — skipping the rebuilt-vs-raw comparison; usage: tsx src/nsClient.selftest.ts <snapshot.json> [attendantsDir])');
+  }
+
+  // -- the optional inventory reads ----------------------------------------------------------------
+  {
+    const seen: string[] = [];
+    const fake = {
+      get: async (p: string) => {
+        seen.push(p);
+        if (/\/users$/.test(p)) return [
+          { user: '100', 'service-code': '' },
+          { user: '700', 'service-code': 'system-aa' },
+        ];
+        if (/\/users\/100\/devices$/.test(p)) return [{ aor: 'sip:100@acme.example', 'device-models-model': 'Yealink T54W' }];
+        if (/\/addresses$/.test(p)) return [{ 'address-id': '1' }];
+        if (/\/smsnumbers/.test(p)) return [{ number: '13175550100' }];
+        return [];
+      },
+    } as unknown as NsClient;
+
+    const snap = await fetchDomainSnapshot(fake, 'acme.example', {
+      includeAttendantMenus: false, includeAddresses: true, includeSmsNumbers: true, includeDevices: true,
+    });
+
+    ok(Array.isArray(snap.addresses) && snap.addresses.length === 1, 'addresses are read into the snapshot');
+    ok(Array.isArray(snap.smsnumbers) && snap.smsnumbers.length === 1, 'SMS numbers are read into the snapshot');
+    ok(seen.some((p) => p === '/domains/acme.example/smsnumbers?dest=*'), 'the SMS read carries dest=* - the live server refuses the documented no-parameter call');
+    ok(snap.devicesByUser?.['100']?.length === 1, 'a real extension devices are read');
+    ok(snap.devicesByUser?.['700'] === undefined, 'a system user costs no device call');
+    ok(!seen.some((p) => /\/users\/700\/devices$/.test(p)), 'and none was made');
+
+    const off = await fetchDomainSnapshot(fake, 'acme.example', { includeAttendantMenus: false });
+    ok(off.addresses === undefined && off.smsnumbers === undefined && off.devicesByUser === undefined,
+      'all three reads are opt-in - a caller that wants routing pays for none of them');
+  }
+
+  // -- a per-extension devices read that fails is reported, not swallowed -------------------------
+  {
+    const failFake = {
+      get: async (p: string) => {
+        if (/\/users$/.test(p)) return [
+          { user: '100', 'service-code': '' },
+          { user: '102', 'service-code': '' },
+          { user: '103', 'service-code': '' },
+        ];
+        if (/\/users\/100\/devices$/.test(p)) return [{ aor: 'sip:100@acme.example' }];
+        if (/\/users\/102\/devices$/.test(p)) throw new NsApiError('GET .../devices → 500', 500, p, null);
+        if (/\/users\/103\/devices$/.test(p)) throw new NsApiError('GET .../devices → 404', 404, p, null);
+        return [];
+      },
+    } as unknown as NsClient;
+
+    const failSnap = await fetchDomainSnapshot(failFake, 'acme.example', { includeAttendantMenus: false, includeDevices: true });
+    ok(failSnap.devicesByUser?.['100']?.length === 1, 'the extension whose read succeeded keeps its devices');
+    ok(failSnap.devicesByUser?.['102'] === undefined, 'the extension whose read failed has no devicesByUser entry');
+    ok(failSnap.devicesByUser?.['103'] === undefined, 'a 404 extension also has no devicesByUser entry');
+    ok(JSON.stringify(failSnap.deviceReadFailures) === JSON.stringify(['102']),
+      'deviceReadFailures names only the non-404 failure, not the 404');
+
+    const okFake = {
+      get: async (p: string) => {
+        if (/\/users$/.test(p)) return [{ user: '100', 'service-code': '' }];
+        if (/\/users\/100\/devices$/.test(p)) return [{ aor: 'sip:100@acme.example' }];
+        return [];
+      },
+    } as unknown as NsClient;
+
+    const okSnap = await fetchDomainSnapshot(okFake, 'acme.example', { includeAttendantMenus: false, includeDevices: true });
+    ok(Array.isArray(okSnap.deviceReadFailures) && okSnap.deviceReadFailures.length === 0,
+      'no failures - deviceReadFailures is an empty array, not absent');
+
+    const noDevicesSnap = await fetchDomainSnapshot(okFake, 'acme.example', { includeAttendantMenus: false });
+    ok(noDevicesSnap.deviceReadFailures === undefined, 'without includeDevices, deviceReadFailures is absent entirely');
+  }
+
+  console.log(`\n${pass} passed, ${fail} failed`);
+  process.exit(fail ? 1 : 0);
+})();