@dszp/netsapiens-lib 0.1.8 → 0.3.0

package/src/nsClient.ts

@@ -0,0 +1,323 @@
+/**
+ * Portable NetSapiens API read client — the seed of the eventual "NS API for Worker/Node"
+ * library. Ported from an internal onboarding tool (its API client
+ * NsClient + `src/backup/snapshot.ts` backupDomain), trimmed to the READ-ONLY routing subset the
+ * resolver needs, and kept Node-free (fetch/URL only) so it runs in a Cloudflare Worker unchanged.
+ *
+ * `fetchDomainSnapshot()` assembles the same `Snapshot` shape the resolver already consumes, so a
+ * live domain flows end-to-end: domain + token → Snapshot → resolveFlow → FlowGraph.
+ *
+ * This client never writes — only GET is exposed. Writes live in the separate `NsWriteClient`.
+ */
+
+import type { Rec, Snapshot } from './model.js';
+
+export class NsApiError extends Error {
+  constructor(
+    message: string,
+    public readonly status: number,
+    public readonly path: string,
+    public readonly body: unknown,
+    /** HTTP method — set by the write client; optional so read-client call sites stay unchanged. */
+    public readonly method?: string,
+  ) {
+    super(message);
+    this.name = 'NsApiError';
+  }
+}
+
+export interface NsClientConfig {
+  /** API host, e.g. "api.example.com". Base URL becomes https://{server}/ns-api/v2. */
+  server: string;
+  /** Bearer token (the portal user's `ns_t`, or an API key). */
+  token: string;
+  /** Injectable for tests / non-global fetch. */
+  fetchImpl?: typeof fetch;
+}
+
+/**
+ * NS API v2 client — READ-ONLY BY DESIGN.
+ *
+ * The ONLY method is `get()`, which hardcodes `method: 'GET'`. There is deliberately no
+ * post/put/delete/patch. Keep it that way: **do not add a mutating method here.** The point of this
+ * class is that holding one is proof you cannot write — a guarantee by construction, not convention,
+ * and adding a single mutating method destroys it for every consumer at once.
+ *
+ * Writes are a separate, explicitly-imported class: `NsWriteClient` (see `nsWriteClient.ts`). New
+ * write capability extends that one, never this one. `NsSubscriptionsClient` is a third client for
+ * the same reason — its `DELETE` semantics differ from `NsWriteClient`'s.
+ */
+/**
+ * Reject a `server` that isn't a bare host or `host:port`. A caller that derives `server` from
+ * request input (a multi-tenant tool) would otherwise let `api.example.com@evil.example` or
+ * `evil.example#…` redirect the Bearer token to another origin — `new URL('https://'+server).host`
+ * is what actually gets contacted, not the string. Comparing the parsed host back to the input
+ * catches an embedded `@`, `/path`, `?query`, `#frag`, or scheme; credentials are refused explicitly.
+ * Host comparison is case-insensitive (URL lowercases the host; NS hostnames are case-insensitive).
+ */
+export function assertBareServer(server: string): string {
+  const s = String(server ?? '').trim().replace(/\/+$/, '');
+  let u: URL;
+  try {
+    u = new URL(`https://${s}`);
+  } catch {
+    throw new Error(`Invalid NS server "${server}": expected a bare host or host:port`);
+  }
+  if (u.host !== s.toLowerCase() || u.username || u.password) {
+    throw new Error(`Invalid NS server "${server}": expected a bare host or host:port (no scheme, path, query, fragment, or credentials)`);
+  }
+  return u.host;
+}
+
+export class NsClient {
+  readonly #baseUrl: string;
+  readonly #token: string;
+  readonly #fetchImpl: typeof fetch;
+
+  constructor(cfg: NsClientConfig) {
+    this.#baseUrl = `https://${assertBareServer(cfg.server)}/ns-api/v2`;
+    this.#token = cfg.token;
+    this.#fetchImpl = cfg.fetchImpl ?? fetch;
+  }
+
+  async get<T = unknown>(path: string, query?: Record<string, string | number>): Promise<T> {
+    const url = new URL(this.#baseUrl + path);
+    for (const [k, v] of Object.entries(query ?? {})) url.searchParams.set(k, String(v));
+
+    // Call via a local, NOT `this.#fetchImpl(...)`: invoking the global fetch as a method of this
+    // instance throws "Illegal invocation" in workerd (the global fetch requires a global `this`).
+    const doFetch = this.#fetchImpl;
+    const res = await doFetch(url.toString(), {
+      method: 'GET',
+      headers: { Authorization: `Bearer ${this.#token}`, Accept: 'application/json' },
+    });
+    const text = await res.text();
+    let parsed: unknown = text;
+    if (text) {
+      try {
+        parsed = JSON.parse(text);
+      } catch {
+        /* some endpoints return empty / plain bodies */
+      }
+    }
+    if (!res.ok) {
+      // Truncate BOTH branches to 500 chars: the object branch used to JSON.stringify the whole
+      // upstream body unbounded, so a consumer that logs err.message could log an arbitrarily large
+      // NS response. No credential is ever in it, but size alone is a footgun.
+      const detail = (typeof parsed === 'object' && parsed !== null ? JSON.stringify(parsed) : String(parsed)).slice(0, 500);
+      const hint = res.status === 401 ? ' (token expired/invalid or domain out of scope)' : res.status === 403 ? ' (token lacks permission)' : '';
+      throw new NsApiError(`GET ${path} → ${res.status}${hint}: ${detail}`, res.status, path, parsed);
+    }
+    return parsed as T;
+  }
+}
+
+/** Normalize a v2 response to an array of records (endpoints return an array or a bare object). */
+export function asArray(res: unknown): Rec[] {
+  if (Array.isArray(res)) return res as Rec[];
+  if (res && typeof res === 'object') return [res as Rec];
+  return [];
+}
+
+/** Map with bounded concurrency — keeps per-user/queue/AA fan-out from hammering the API. */
+async function mapLimit<T>(items: T[], limit: number, fn: (item: T, index: number) => Promise<void>): Promise<void> {
+  let i = 0;
+  const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
+    while (i < items.length) {
+      const idx = i++;
+      await fn(items[idx]!, idx);
+    }
+  });
+  await Promise.all(workers);
+}
+
+const enc = encodeURIComponent;
+
+/** List domains the token can read (for the internal viewer's domain browser). `locked` is set only
+ *  for domains flagged `is-domain-locked: yes` (config-locked in NetSapiens). */
+export async function listDomains(client: NsClient): Promise<{ domain: string; description?: string; locked?: boolean }[]> {
+  const recs = asArray(await client.get('/domains'));
+  return recs
+    .map((r) => ({
+      domain: String(r.domain ?? ''),
+      ...(r.description ? { description: String(r.description) } : {}),
+      ...(r['is-domain-locked'] === 'yes' ? { locked: true } : {}),
+    }))
+    .filter((d) => d.domain);
+}
+
+export interface FetchSnapshotOptions {
+  /** Fetch each AA's keypress menu (GET .../autoattendants/{prompt}). Default true. */
+  includeAttendantMenus?: boolean;
+  /** Also fetch the default-plan dialrules (rarely needed — classifyParam handles aliases). Default false. */
+  includeDialrules?: boolean;
+  /** Max concurrent per-item requests. Default 5. Mind Workers' subrequest cap on huge domains. */
+  concurrency?: number;
+  /**
+   * Shallow: fetch only the top-level lists (domain, timeframes, users, callqueues, phonenumbers,
+   * autoattendants) and skip the per-user/queue/AA fan-out. Enough for `listEntities()` (the entity
+   * picker) at a fraction of the requests. Default false.
+   */
+  shallow?: boolean;
+  /**
+   * With `shallow`, also fetch answer rules for the DIDs' destination users (a handful of extra
+   * reads) so `listEntities()` can flag time-of-day (TOD) DIDs. Default false.
+   */
+  includeDidDestRules?: boolean;
+  /**
+   * Also read the domain's E911 addresses into `snapshot.addresses`. One extra call. Default false —
+   * the resolver does not use them; an inventory count does.
+   */
+  includeAddresses?: boolean;
+  /**
+   * Also read the domain's SMS-enabled numbers into `snapshot.smsnumbers`. One extra call. Default false.
+   *
+   * Sent as `?dest=*`. The endpoint is documented as taking no parameters and a live server rejects it
+   * that way, demanding `dest` or `number`; the wildcard is what answers with the list.
+   */
+  includeSmsNumbers?: boolean;
+  /**
+   * Also read each REAL extension's devices into `devicesByUser`. Costs one call per extension —
+   * NetSapiens exposes devices only per user — so it is off by default and belongs to inventory
+   * callers, not routing ones. Users whose `service-code` starts with `system-` are skipped: they are
+   * auto attendants and queues, and they hold no seat.
+   */
+  includeDevices?: boolean;
+}
+
+/**
+ * Read a live domain into the `Snapshot` shape the resolver consumes. Routing subset only:
+ * domain, timeframes, users, callqueues, phonenumbers, autoattendants, per-user answerrules,
+ * per-queue agents, and (by default) per-AA menu detail.
+ *
+ * A per-item read that fails is treated as "absent" (empty) so one missing child never aborts the
+ * whole flow — the resolver tolerates gaps. A failing top-level read (e.g. 401) DOES throw.
+ */
+export async function fetchDomainSnapshot(client: NsClient, domain: string, opts: FetchSnapshotOptions = {}): Promise<Snapshot> {
+  const conc = opts.concurrency ?? 5;
+  const base = `/domains/${enc(domain)}`;
+  const soft = async (p: string): Promise<Rec[]> => {
+    try {
+      return asArray(await client.get(p));
+    } catch (err) {
+      if (err instanceof NsApiError && err.status === 404) return [];
+      throw err;
+    }
+  };
+
+  const domainRec = asArray(await client.get(base))[0] ?? { domain };
+  const [timeframes, users, callqueues, phonenumbers, autoattendants, addresses, smsnumbers] = await Promise.all([
+    soft(`${base}/timeframes`),
+    soft(`${base}/users`),
+    soft(`${base}/callqueues`),
+    soft(`${base}/phonenumbers`),
+    soft(`${base}/autoattendants`),
+    opts.includeAddresses ? soft(`${base}/addresses`) : Promise.resolve(undefined),
+    // `dest=*`: see includeSmsNumbers. A 404 is already softened to []; a 400 from a server that wants
+    // a different parameter throws, which is right — a silent empty list would read as "no SMS numbers".
+    opts.includeSmsNumbers ? soft(`${base}/smsnumbers?dest=*`) : Promise.resolve(undefined),
+  ]);
+
+  // Shallow mode stops here — enough for listEntities() (the picker). `includeDevices` is ignored in
+  // shallow mode: shallow's whole contract is "no per-item fan-out".
+  if (opts.shallow) {
+    let answerrulesByUser: Record<string, Rec[]> | undefined;
+    if (opts.includeDidDestRules) {
+      const dests = [...new Set(phonenumbers.map((p) => String(p['dial-rule-translation-destination-user'] ?? '')).filter(Boolean))];
+      answerrulesByUser = {};
+      await mapLimit(dests, conc, async (u) => {
+        const rules = await soft(`${base}/users/${enc(u)}/answerrules`).catch(() => []);
+        if (rules.length) answerrulesByUser![u] = rules;
+      });
+    }
+    return {
+      meta: { domain }, domain: domainRec, timeframes, users, callqueues, phonenumbers, autoattendants,
+      ...(answerrulesByUser ? { answerrulesByUser } : {}),
+      ...(addresses ? { addresses } : {}),
+      ...(smsnumbers ? { smsnumbers } : {}),
+    };
+  }
+
+  // Devices, per REAL extension. One call each — there is no domain-level device list — so this is the
+  // expensive half of an inventory read and is opt-in for that reason.
+  let devicesByUser: Record<string, Rec[]> | undefined;
+  let deviceReadFailures: string[] | undefined;
+  if (opts.includeDevices) {
+    devicesByUser = {};
+    deviceReadFailures = [];
+    const seats = users.filter((u) => !String(u['service-code'] ?? '').trim().toLowerCase().startsWith('system-'));
+    await mapLimit(seats, conc, async (u) => {
+      const ext = String(u.user ?? '');
+      if (!ext) return;
+      // `soft()` already turns a 404 into `[]` — that is "no devices", not a failure. Anything else
+      // it rethrows, and THAT is what gets recorded here: a consumer counting devices must be able
+      // to tell a genuine zero from a read that never completed.
+      const devs = await soft(`${base}/users/${enc(ext)}/devices`).catch(() => {
+        deviceReadFailures!.push(ext);
+        return [];
+      });
+      if (devs.length) devicesByUser![ext] = devs;
+    });
+  }
+
+  const answerrulesByUser: Record<string, Rec[]> = {};
+  await mapLimit(users, conc, async (u) => {
+    const ext = String(u.user ?? '');
+    if (!ext) return;
+    const rules = await soft(`${base}/users/${enc(ext)}/answerrules`).catch(() => []);
+    if (rules.length) answerrulesByUser[ext] = rules;
+  });
+
+  const agentsByQueue: Record<string, Rec[]> = {};
+  await mapLimit(callqueues, conc, async (q) => {
+    const ext = String(q.callqueue ?? '');
+    if (!ext) return;
+    const ags = await soft(`${base}/callqueues/${enc(ext)}/agents`).catch(() => []);
+    if (ags.length) agentsByQueue[ext] = ags;
+  });
+
+  // One list row per (user, prompt); an AA may have several (multi-timeframe). Collect ALL detail
+  // records per user (array) so the resolver can flag multi-prompt deviations, not just last-wins.
+  // Also fetch each AA's OWN dialplan dialrules ({domain}_{ext}) — the authoritative menu/default
+  // routing the /autoattendants detail omits (no-key/star/option). See ARCHITECTURE.md → NetSapiens routing model.
+  let attendantDetailsByUser: Record<string, Rec[]> | undefined;
+  let attendantDialrulesByExt: Record<string, Rec[]> | undefined;
+  if (opts.includeAttendantMenus ?? true) {
+    const rows = autoattendants.map((aa) => ({ ext: String(aa.user ?? ''), prompt: String(aa['starting-prompt'] ?? '') })).filter((r) => r.ext && r.prompt);
+    attendantDetailsByUser = {};
+    for (const r of rows) attendantDetailsByUser[r.ext] ??= []; // pre-init (avoid concurrent-init race)
+    await mapLimit(rows, conc, async (r) => {
+      const detail = (await soft(`${base}/users/${enc(r.ext)}/autoattendants/${enc(r.prompt)}`).catch(() => []))[0];
+      if (detail) attendantDetailsByUser![r.ext].push(detail);
+    });
+    attendantDialrulesByExt = {};
+    await mapLimit([...new Set(rows.map((r) => r.ext))], conc, async (ext) => {
+      const dr = await soft(`${base}/dialplans/${enc(`${domain}_${ext}`)}/dialrules`).catch(() => []);
+      if (dr.length) attendantDialrulesByExt![ext] = dr;
+    });
+  }
+
+  let dialrulesByPlan: Record<string, Rec[]> | undefined;
+  if (opts.includeDialrules) {
+    dialrulesByPlan = { [domain]: await soft(`${base}/dialplans/${enc(domain)}/dialrules`).catch(() => []) };
+  }
+
+  return {
+    meta: { domain },
+    domain: domainRec,
+    timeframes,
+    users,
+    callqueues,
+    phonenumbers,
+    autoattendants,
+    answerrulesByUser,
+    agentsByQueue,
+    ...(addresses ? { addresses } : {}),
+    ...(smsnumbers ? { smsnumbers } : {}),
+    ...(devicesByUser ? { devicesByUser } : {}),
+    ...(deviceReadFailures ? { deviceReadFailures } : {}),
+    ...(attendantDetailsByUser && Object.keys(attendantDetailsByUser).length ? { attendantDetailsByUser } : {}),
+    ...(attendantDialrulesByExt && Object.keys(attendantDialrulesByExt).length ? { attendantDialrulesByExt } : {}),
+    ...(dialrulesByPlan ? { dialrulesByPlan } : {}),
+  };
+}

package/src/nsDevice.selftest.ts

@@ -0,0 +1,190 @@
+/**
+ * Selftests for device orchestration: ensureNsDevice + generateSipPassword. Fully offline.
+ *
+ * Run: pnpm test:nsdevice
+ */
+import { ensureNsDevice, generateSipPassword, SIP_PW_FIELD, type NsDeviceWriter } from './nsDevice.js';
+import { NsWriteClient } from './nsWriteClient.js';
+import type { Rec } from './model.js';
+
+let pass = 0,
+  fail = 0;
+const ok = (c: boolean, m: string) => {
+  c ? pass++ : fail++;
+  console.log(`${c ? '✓' : '✗ FAIL'} ${m}`);
+};
+
+/** In-memory device store, recording every call. */
+function mockWriter(seed: Record<string, string> = {}) {
+  const store = new Map<string, Rec>();
+  for (const [name, pw] of Object.entries(seed)) store.set(name, { device: name, [SIP_PW_FIELD]: pw });
+  const calls: string[] = [];
+  let failUpdate = false;
+  let omitPwOnUpdate = false;
+  let seq = 0;
+  const w: NsDeviceWriter = {
+    async getDevices() {
+      calls.push('getDevices');
+      return [...store.values()];
+    },
+    async getDevice(_d, _u, device) {
+      calls.push(`getDevice:${device}`);
+      return store.get(device) ?? {};
+    },
+    async createDevice(_d, _u, device) {
+      calls.push(`createDevice:${device}`);
+      const rec = { device, [SIP_PW_FIELD]: `GEN${++seq}` };
+      store.set(device, rec);
+      return rec;
+    },
+    async updateDevice(_d, _u, device, changes) {
+      calls.push(`updateDevice:${device}`);
+      if (failUpdate) throw new Error('404 No Route Found');
+      const rec = { ...(store.get(device) ?? { device }), ...changes };
+      store.set(device, rec);
+      return omitPwOnUpdate ? { device } : rec;
+    },
+  };
+  return { w, calls, store, failUpdate: (v: boolean) => (failUpdate = v), omitPwOnUpdate: (v: boolean) => (omitPwOnUpdate = v) };
+}
+const O = { domain: 'acme.example.com', user: '100', device: '100r' };
+
+// ── generateSipPassword ───────────────────────────────────────────────────────
+ok(generateSipPassword().length === 20, 'defaults to 20 characters');
+ok(/^[A-Za-z0-9]{20}$/.test(generateSipPassword()), 'alphanumeric only — nothing to mis-escape in SIP auth or provisioning');
+ok(generateSipPassword(40).length === 40, 'length is configurable');
+ok(generateSipPassword(1).length === 1, 'a length of 1 works');
+ok(new Set(Array.from({ length: 200 }, () => generateSipPassword(8))).size === 200, '200 generated passwords are all distinct');
+{
+  // A uniform draw omits digits ~3% of the time at length 20 — often enough to look like a bug when you
+  // eyeball one, and enough to trip a downstream complexity rule. Every candidate must carry all three.
+  const sample = Array.from({ length: 500 }, () => generateSipPassword());
+  ok(sample.every((p) => /[0-9]/.test(p)), 'EVERY password contains at least one digit (500 samples)');
+  ok(sample.every((p) => /[a-z]/.test(p)), 'every password contains at least one lowercase letter');
+  ok(sample.every((p) => /[A-Z]/.test(p)), 'every password contains at least one uppercase letter');
+  ok(sample.every((p) => /^[A-Za-z0-9]{20}$/.test(p)), 'and they stay alphanumeric at the requested length');
+  ok(Array.from({ length: 200 }, () => generateSipPassword(3)).every((p) => p.length === 3 && /[0-9]/.test(p) && /[a-z]/.test(p) && /[A-Z]/.test(p)), 'the guarantee holds at the minimum viable length of 3');
+  ok([1, 2].every((n) => generateSipPassword(n).length === n), 'lengths below 3 still work (the guarantee is impossible there)');
+}
+{
+  // Uniformity sanity: with rejection sampling every symbol class should appear across a large sample.
+  const big = Array.from({ length: 400 }, () => generateSipPassword(16)).join('');
+  ok(/[A-Z]/.test(big) && /[a-z]/.test(big) && /[0-9]/.test(big), 'the whole alphabet is reachable');
+  ok(new Set(big).size >= 55, 'nearly every symbol appears in a large sample (no modulo dead zone)');
+}
+for (const bad of [0, -1, 1.5, NaN]) {
+  let threw = false;
+  try {
+    generateSipPassword(bad);
+  } catch {
+    threw = true;
+  }
+  ok(threw, `an invalid length (${bad}) throws rather than looping or returning junk`);
+}
+
+// ── absent device ─────────────────────────────────────────────────────────────
+{
+  const m = mockWriter();
+  const r = await ensureNsDevice(m.w, O);
+  ok(r.created === true && r.password === 'GEN1', 'a missing device is created and its generated password returned');
+  ok(m.calls.includes('createDevice:100r'), 'createDevice was called');
+  ok(r.rotated === undefined, 'a newly created device reports no rotation — it is already exclusive');
+}
+{
+  const m = mockWriter();
+  const r = await ensureNsDevice(m.w, { ...O, mayCreate: false });
+  ok(r.password === '' && r.created === false, 'mayCreate:false on a missing device yields a blank password (a refusal signal)');
+  ok(!m.calls.some((c) => c.startsWith('createDevice')), 'and nothing is created');
+}
+{
+  const m = mockWriter();
+  const r = await ensureNsDevice(m.w, { ...O, mayCreate: false, rotateExisting: true });
+  ok(r.password === '' && !m.calls.some((c) => c.startsWith('updateDevice')), 'a missing device is never rotated');
+}
+
+// ── existing device, no rotation ───────────────────────────────────────────────
+{
+  const m = mockWriter({ '100r': 'STORED_PASSWORD' });
+  const r = await ensureNsDevice(m.w, O);
+  ok(r.password === 'STORED_PASSWORD' && r.created === false, 'an existing device returns its stored password');
+  ok(m.calls.includes('getDevice:100r'), 'a per-device GET is issued because a device LIST may omit the password');
+  ok(!m.calls.some((c) => c.startsWith('updateDevice')), 'nothing is rotated by default — this is the pre-existing behaviour');
+}
+{
+  // The list carries the password but the per-device GET does not: fall back to the list value.
+  const m = mockWriter();
+  m.store.set('100r', { device: '100r' });
+  const w2: NsDeviceWriter = { ...m.w, async getDevices() { return [{ device: '100r', [SIP_PW_FIELD]: 'FROM_LIST' }]; } };
+  const r = await ensureNsDevice(w2, O);
+  ok(r.password === 'FROM_LIST', 'falls back to the list password when the per-device read omits it');
+}
+{
+  const m = mockWriter({ other: 'X' });
+  const r = await ensureNsDevice(m.w, O);
+  ok(r.created === true, 'a device with a different name does not satisfy the requested one');
+}
+
+// ── rotation ──────────────────────────────────────────────────────────────────
+{
+  const m = mockWriter({ '100r': 'STORED_PASSWORD' });
+  const r = await ensureNsDevice(m.w, { ...O, rotateExisting: true });
+  ok(r.rotated === true && r.created === false, 'an existing device is rotated on request');
+  ok(r.password !== 'STORED_PASSWORD' && /^[A-Za-z0-9]{20}$/.test(r.password), 'a fresh password is returned');
+  ok(m.calls.includes('updateDevice:100r'), 'rotation is a PUT');
+  ok(!m.calls.some((c) => c.startsWith('deleteDevice')) && !m.calls.some((c) => c.startsWith('createDevice')), 'rotation never deletes and recreates — other device settings must survive');
+  ok(String(m.store.get('100r')?.[SIP_PW_FIELD]) === r.password, 'the stored device now carries the new password');
+}
+{
+  const m = mockWriter({ '100r': 'STORED_PASSWORD' });
+  m.omitPwOnUpdate(true);
+  const r = await ensureNsDevice(m.w, { ...O, rotateExisting: true });
+  ok(r.rotated === true && /^[A-Za-z0-9]{20}$/.test(r.password), 'when NS echoes nothing back, the value we set is returned');
+  ok(r.password !== 'STORED_PASSWORD', 'and it is definitely not the old one');
+}
+{
+  // The case that matters most: a release without the device PUT must not break the caller.
+  const m = mockWriter({ '100r': 'STORED_PASSWORD' });
+  m.failUpdate(true);
+  const r = await ensureNsDevice(m.w, { ...O, rotateExisting: true });
+  ok(r.rotated === false, 'a failed rotation is REPORTED, never thrown');
+  ok(r.password === 'STORED_PASSWORD', 'and it falls back to the existing password so the client still works');
+  ok((r.rotateError ?? '').includes('No Route Found'), 'the failure reason is carried for logging');
+}
+{
+  const m = mockWriter({ '100r': 'STORED' });
+  const r = await ensureNsDevice(m.w, { ...O, rotateExisting: true, passwordLength: 32 });
+  ok(r.password.length === 32, 'passwordLength is honoured');
+}
+{
+  const m = mockWriter({ '100r': '' });
+  const r = await ensureNsDevice(m.w, O);
+  ok(r.password === '' && r.created === false, 'a device with no readable password yields blank rather than throwing');
+}
+{
+  // A writer whose getDevices returns a non-array must not crash the caller.
+  const m = mockWriter();
+  const w2: NsDeviceWriter = { ...m.w, async getDevices() { return null as unknown as Rec[]; } };
+  const r = await ensureNsDevice(w2, O);
+  ok(r.created === true, 'a non-array device list degrades to "absent" instead of throwing');
+}
+
+// ── the delegating client method ──────────────────────────────────────────────
+{
+  const seen: { method: string; url: string }[] = [];
+  const fetchImpl = (async (input: unknown, init: { method?: string } = {}) => {
+    seen.push({ method: init.method ?? 'GET', url: String(input) });
+    // devices list → one device; per-device GET → with password
+    return new Response(JSON.stringify(seen.length === 1 ? [{ device: '100r' }] : { device: '100r', [SIP_PW_FIELD]: 'VIA_CLIENT' }), {
+      status: 200,
+      headers: { 'content-type': 'application/json' },
+    });
+  }) as unknown as typeof fetch;
+  const client = new NsWriteClient({ server: 'api.example.com', token: 'tok', fetchImpl });
+  const r = await client.ensureDevice(O);
+  ok(r.password === 'VIA_CLIENT' && r.created === false, 'NsWriteClient.ensureDevice delegates and works end to end');
+  ok(seen[0]!.url.endsWith('/domains/acme.example.com/users/100/devices'), 'it drives the real device paths');
+  ok(seen.every((s) => s.method === 'GET'), 'no write was needed for an existing device');
+}
+
+console.log(`\n${pass} passed, ${fail} failed`);
+if (fail > 0) process.exitCode = 1;