@dszp/netsapiens-lib 0.1.5 → 0.1.7

package/dist/nsWriteClient.js

@@ -1,4 +1,6 @@
 import { NsApiError, assertBareServer, asArray } from './nsClient.js';
+import { ensureNsDevice } from './nsDevice.js';
+import { supportsSynchronous } from './nsSynchronous.js';
 const enc = encodeURIComponent;
 export class NsWriteClient {
     #baseUrl;
@@ -13,13 +15,25 @@ export class NsWriteClient {
     get(path, query) {
         return this.#request('GET', path, undefined, query);
     }
-    /** POST with `synchronous:'yes'` injected → 200 + created resource inline. */
+    /**
+     * POST. On an operation that accepts it, `synchronous:'yes'` is injected → 200 + the created
+     * resource inline; otherwise the flag is omitted and the API answers 202 Accepted.
+     */
     post(path, body) {
-        return this.#request('POST', path, { synchronous: 'yes', ...body });
+        return this.#request('POST', path, this.#withSynchronous('POST', path, body));
     }
-    /** PUT with `synchronous:'yes'` injected. */
+    /**
+     * PUT. Same rule as {@link post} — and note most updates do NOT accept the flag, so their
+     * response is a 202 acknowledgement with no resource body. Confirm those by reading back.
+     */
     put(path, body) {
-        return this.#request('PUT', path, { synchronous: 'yes', ...body });
+        return this.#request('PUT', path, this.#withSynchronous('PUT', path, body));
+    }
+    /** Add `synchronous:'yes'` only where the API declares support. An explicit caller value wins. */
+    #withSynchronous(method, path, body) {
+        if (!supportsSynchronous(method, path))
+            return body;
+        return { synchronous: 'yes', ...body };
     }
     delete(path) {
         return this.#request('DELETE', path);
@@ -41,10 +55,38 @@ export class NsWriteClient {
     createDevice(domain, user, device, extra = {}) {
         return this.post(`/domains/${enc(domain)}/users/${enc(user)}/devices`, { device, ...extra });
     }
+    /**
+     * Update a device in place.
+     *
+     * `PUT .../devices/{device}` does **not** accept `synchronous`, so this returns a 202
+     * acknowledgement, not the updated device. Callers must not depend on the response echoing their
+     * change back — {@link ensureNsDevice} falls back to the value it just sent for exactly this reason.
+     *
+     * The reason this exists rather than callers using `put()`: rotating
+     * `device-sip-registration-password` must **not** be done by deleting and recreating the device, which
+     * would discard everything else on it — emergency caller id, the provisioning MAC/model link, SRTP and
+     * transport settings. A PUT changes the one field and preserves the rest.
+     */
+    updateDevice(domain, user, device, changes) {
+        return this.put(`/domains/${enc(domain)}/users/${enc(user)}/devices/${enc(device)}`, changes);
+    }
     /** Delete a device. */
     deleteDevice(domain, user, device) {
         return this.delete(`/domains/${enc(domain)}/users/${enc(user)}/devices/${enc(device)}`);
     }
+    /**
+     * Convenience wrapper over {@link ensureNsDevice} — ensure a device exists and return its SIP password,
+     * optionally rotating it. See that function for the semantics, and for why rotation matters.
+     *
+     * Deliberately a **one-line delegation, not an implementation**. Every other method on this class is
+     * exactly one HTTP request; this one is several with branching, so the logic lives in a standalone
+     * function that composes over any writer (a consumer may have its own client) and that consumers can mock as
+     * a plain 4-method object instead of stubbing a whole client. This method exists only so the capability
+     * is discoverable from the client you already hold.
+     */
+    ensureDevice(opts) {
+        return ensureNsDevice(this, opts);
+    }
     async #request(method, path, body, query) {
         const url = new URL(this.#baseUrl + path);
         for (const [k, v] of Object.entries(query ?? {}))

package/dist/resolver.js

@@ -764,12 +764,25 @@ function aaApp(app, dest, idx, b) {
  *   *                     → unassigned key ("Unknown Input")
  *   Default               → no-key timeout
  * Apps: Announce → play-message; Prompt→own prompt id → repeat greeting; else via aaApp().
+ *
+ * A `Prompt` option pointing at a DIFFERENT prompt id that has its own `Prompt_<id>.` rule family in
+ * this same dialplan is a SECOND-LEVEL MENU — the portal's "Add Tier" on a keypress. Recurse into it
+ * rather than rendering a dead-end "Play prompt <id>" leaf. The tier's prompt id exists ONLY in the
+ * dialplan; the /autoattendants detail nests the tier as `option-N.auto-attendant` with no id at all,
+ * so the two are joined by the keypress digit. Portal-created tiers are one level deep, but the
+ * dialplan grammar is not, so this recurses without a depth bound; claim()/enter() make a back-link
+ * to an ancestor tier draw as a "loops back" reference leaf instead of recursing forever.
+ *
  * `detailTier` (the /autoattendants option-N structure, when present) enriches each key with its
  * CNAM prefix + play-message script/audio, which the dialplan lacks.
  */
-function renderAaFromDialrules(rules, startingPrompt, fromId, ext, idx, b, detailTier) {
+function renderAaFromDialrules(rules, startingPrompt, fromId, ext, idx, b, detailTier, tiers = new Map()) {
     const prefix = `${startingPrompt}.`;
     const promptId = startingPrompt.replace(/^Prompt_/i, ''); // e.g. "912201"
+    // prompt id -> the node whose menu it is. A deeper tier keyed back to an earlier prompt ("9 for the
+    // main menu") is a jump to THAT node, not a second copy of it; Builder.edge turns it into a
+    // loops-back leaf when the target is an ancestor still being expanded.
+    tiers.set(promptId, fromId);
     let dialByExt = false;
     const opts = [];
     let noKey = null;
@@ -808,14 +821,65 @@ function renderAaFromDialrules(rules, startingPrompt, fromId, ext, idx, b, detai
         const script = opt ? s(opt.audio?.['file-script-text']) : '';
         const label = o.label + (cnam && cnam !== '[*]' ? ` · ${cnam}` : '');
         let target;
-        if (/^announce/i.test(o.app))
-            target = b.node(`aaannounce_${ext}_${o.dest}`, 'prompt', `🔊 ${script ? `“${trim(script)}”` : 'Play message'}`, undefined, undefined, script.length > GREET_MAX ? script : undefined).id;
-        else if (/^prompt/i.test(o.app))
-            target = o.dest === promptId ? b.node(`aarepeat_${ext}`, 'prompt', '🔁 Repeat greeting', 're-plays the menu').id : b.node(`aaprompt_${ext}_${o.dest}`, 'prompt', '🔊 Play prompt', o.dest || undefined).id;
+        if (/^announce/i.test(o.app)) {
+            const n = b.node(`aaannounce_${ext}_${o.dest}`, 'prompt', `🔊 ${script ? `“${trim(script)}”` : 'Play message'}`, undefined, undefined, script.length > GREET_MAX ? script : undefined);
+            if (n.isNew)
+                announceReturn(o.dest, n.id); // only once — two keys may play the same message
+            target = n.id;
+        }
+        else if (/^prompt/i.test(o.app)) {
+            if (o.dest === promptId)
+                target = b.node(`aarepeat_${ext}_${promptId}`, 'prompt', '🔁 Repeat greeting', 're-plays the menu').id;
+            else if (tiers.has(o.dest))
+                target = tiers.get(o.dest);
+            else if (hasTier(o.dest))
+                return renderSubTier(o, opt, label);
+            else
+                target = b.node(`aaprompt_${ext}_${o.dest}`, 'prompt', '🔊 Play prompt', o.dest || undefined).id;
+        }
         else
             target = aaApp(o.app, o.dest, idx, b);
         b.edge(fromId, target, 'menu', label);
     };
+    /**
+     * Where the call goes once a played message finishes: the dialplan's `Announce_<id>.Done` rule.
+     * It is almost always `Prompt <this menu>` — i.e. the caller hears the message, then the menu again.
+     * Without this edge a message is drawn as a dead end, which is the one thing it never is.
+     * `Prompt <this menu>` reuses the shared "Repeat greeting" node (same node the no-key default lands
+     * on — identical behavior, so it should be identical on the diagram); a jump to another tier points
+     * at that tier's node. Anything else routes normally. An unrecognized prompt id gets no edge rather
+     * than an invented node.
+     */
+    const announceReturn = (announceId, fromAnnounce) => {
+        const done = rules.find((r) => s(r['dial-rule-matching-to-uri']) === `Announce_${announceId}.Done`);
+        if (!done)
+            return;
+        const app = s(done['dial-rule-application']);
+        const dest = s(done['dial-rule-translation-destination-user']);
+        if (/^announce/i.test(app))
+            return; // message → message chain: not seen in the wild, don't guess
+        let back;
+        if (/^prompt/i.test(app))
+            back = dest === promptId ? b.node(`aarepeat_${ext}_${promptId}`, 'prompt', '🔁 Repeat greeting', 're-plays the menu').id : tiers.get(dest);
+        else
+            back = aaApp(app, dest, idx, b);
+        if (back)
+            b.edge(fromAnnounce, back, 'menu', 'then');
+    };
+    /** Does `dest` have its own rule family here — i.e. is it a nested menu tier, not a bare prompt? */
+    const hasTier = (dest) => !!dest && rules.some((r) => s(r['dial-rule-matching-to-uri']).startsWith(`Prompt_${dest}.`));
+    /** A second-level menu: its own node, then the same grammar again from that tier's prompt. */
+    const renderSubTier = (o, opt, label) => {
+        // Keyed by prompt id, not keypress: two keys may open the same tier, and that should be one node.
+        const greet = s(opt?.audio?.['file-script-text']);
+        const subId = b.node(`aa_${ext}_p${o.dest}`, 'attendant', `🔀 Submenu${o.dtmf ? ` (press ${o.dtmf})` : ''}`, greet ? `“${trim(greet)}”` : 'nested menu', undefined, greet.length > GREET_MAX ? greet : undefined).id;
+        b.edge(fromId, subId, 'menu', label);
+        if (!b.claim(subId))
+            return;
+        b.enter(subId);
+        renderAaFromDialrules(rules, `Prompt_${o.dest}`, subId, ext, idx, b, opt?.['auto-attendant'], tiers);
+        b.leave(null);
+    };
     for (const o of opts.sort((a, c) => a.sort.localeCompare(c.sort)))
         route(o);
     if (noKey)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dszp/netsapiens-lib",
-  "version": "0.1.5",
-  "description": "Portable, Node-free NetSapiens toolkit: read-only API client, JWT (ns_t) validation, and a snapshot -> FlowGraph -> Mermaid call-flow resolver/renderer. Runs unchanged in a Cloudflare Worker, Node, or the browser.",
+  "version": "0.1.7",
+  "description": "Portable, Node-free NetSapiens toolkit: split read/write API clients, JWT (ns_t) validation, and a snapshot -> FlowGraph -> Mermaid call-flow resolver/renderer. Runs unchanged in a Cloudflare Worker, Node, or the browser.",
   "type": "module",
   "license": "MIT",
   "author": {
@@ -12,11 +12,17 @@
     "type": "git",
     "url": "git+https://github.com/dszp/netsapiens-lib.git"
   },
-  "bugs": { "url": "https://github.com/dszp/netsapiens-lib/issues" },
+  "bugs": {
+    "url": "https://github.com/dszp/netsapiens-lib/issues"
+  },
   "homepage": "https://github.com/dszp/netsapiens-lib#readme",
   "//publishConfig": "No `provenance: true` here on purpose: it would force provenance on EVERY publish, including the manual first one that a brand-new package requires (npm can only configure trusted publishing on a package that already exists). Provenance comes from the workflow's explicit `npm publish --provenance` in CI.",
-  "publishConfig": { "access": "public" },
-  "engines": { "node": ">=20" },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
   "keywords": [
     "netsapiens",
     "voip",
@@ -49,16 +55,19 @@
     "build:watch": "tsc -p tsconfig.json --watch",
     "//prepublishOnly": "Publish-only build with sourcemaps OFF. The `files` globs exclude dist/**/*.map on purpose (they point at src/, which does not ship), but tsc still emits a //# sourceMappingURL pointer into every .js/.d.ts -- so consumers' devtools 404 chasing maps that were never published. Dropping the pointer at publish time is what the exclusion always meant. A normal `pnpm build` keeps maps for link: consumers.",
     "prepublishOnly": "tsc -p tsconfig.json --sourceMap false --declarationMap false",
-    "//test": "The offline suite — green on a fresh clone with no credentials and no fixtures. test:ns is NOT included: it needs a domain snapshot that (correctly) isn't in the repo.",
-    "test": "pnpm run test:jwt && pnpm run test:principal && pnpm run test:resolver && pnpm run test:raster && pnpm run test:nswrite && pnpm run test:eligibility && pnpm run test:nsauth",
+    "//test": "The offline suite \u2014 green on a fresh clone with no credentials and no fixtures. test:ns is NOT included: it needs a domain snapshot that (correctly) isn't in the repo.",
+    "test": "pnpm run test:jwt && pnpm run test:principal && pnpm run test:resolver && pnpm run test:raster && pnpm run test:nswrite && pnpm run test:nssync && pnpm run test:eligibility && pnpm run test:nsauth && pnpm test:nssubs && pnpm test:nsdevice",
     "test:jwt": "tsx src/jwt.selftest.ts",
     "test:ns": "tsx src/nsClient.selftest.ts",
     "test:nswrite": "tsx src/nsWriteClient.selftest.ts",
+    "test:nssync": "tsx src/nsSynchronous.selftest.ts",
     "test:nsauth": "tsx src/nsAuthClient.selftest.ts",
     "test:principal": "tsx src/principal.selftest.ts",
     "test:resolver": "tsx src/resolver.selftest.ts",
     "test:raster": "tsx src/raster.selftest.ts",
-    "test:eligibility": "tsx src/eligibility.selftest.ts"
+    "test:eligibility": "tsx src/eligibility.selftest.ts",
+    "test:nssubs": "tsx src/nsSubscriptions.selftest.ts",
+    "test:nsdevice": "tsx src/nsDevice.selftest.ts"
   },
   "devDependencies": {
     "tsx": "^4.22.4",