@dszp/netsapiens-lib 0.1.5 → 0.1.7

package/dist/nsSubscriptions.js

@@ -0,0 +1,444 @@
+import { NsApiError, assertBareServer, asArray } from './nsClient.js';
+/** Every valid `model` value, for validating configuration before it reaches the API. */
+export const SUBSCRIPTION_MODELS = [
+    'agent',
+    'auditlog',
+    'auditlog_lite',
+    'call',
+    'call_origid',
+    'cdr',
+    'message',
+    'messagesession',
+    'subscriber',
+    'presence',
+    'voicemail',
+];
+/** Narrowing guard for a configured model string. */
+export function isSubscriptionModel(v) {
+    return typeof v === 'string' && SUBSCRIPTION_MODELS.includes(v);
+}
+const enc = encodeURIComponent;
+const two = (n) => String(n).padStart(2, '0');
+/**
+ * Format a `Date` as the documented write format `YYYY-MM-DD HH:MM:SS`, **in UTC**.
+ *
+ * The API documents no timezone for this field. Emitting UTC is the only self-consistent choice, and it
+ * round-trips with {@link parseNsDatetime}, which also reads a bare timestamp as UTC.
+ */
+export function nsDatetime(d) {
+    return (`${d.getUTCFullYear()}-${two(d.getUTCMonth() + 1)}-${two(d.getUTCDate())}` +
+        ` ${two(d.getUTCHours())}:${two(d.getUTCMinutes())}:${two(d.getUTCSeconds())}`);
+}
+/**
+ * Parse either datetime shape the API uses: the documented `YYYY-MM-DD HH:MM:SS` (read as **UTC**) or the
+ * ISO-8601-with-offset form that reads actually return. Returns `undefined` rather than an Invalid Date so
+ * callers fail closed on a value they can't interpret.
+ */
+export function parseNsDatetime(s) {
+    if (typeof s !== 'string')
+        return undefined;
+    const t = s.trim();
+    if (!t)
+        return undefined;
+    // Bare "YYYY-MM-DD HH:MM:SS" (optionally with fractional seconds) carries no zone → treat as UTC.
+    const bare = /^(\d{4})-(\d{2})-(\d{2})[ T](\d{2}):(\d{2})(?::(\d{2}))?(?:\.\d+)?$/.exec(t);
+    if (bare) {
+        const ms = Date.UTC(Number(bare[1]), Number(bare[2]) - 1, Number(bare[3]), Number(bare[4]), Number(bare[5]), Number(bare[6] ?? 0));
+        return Number.isNaN(ms) ? undefined : new Date(ms);
+    }
+    const ms = Date.parse(t);
+    return Number.isNaN(ms) ? undefined : new Date(ms);
+}
+function num(v) {
+    if (typeof v === 'number' && Number.isFinite(v))
+        return v;
+    if (typeof v === 'string' && v.trim() !== '') {
+        const n = Number(v);
+        if (Number.isFinite(n))
+            return n;
+    }
+    return undefined;
+}
+function str(v) {
+    return typeof v === 'string' && v !== '' ? v : undefined;
+}
+/** Map one API record to {@link Subscription}. Tolerant: an unmodelled or missing field is simply absent. */
+export function subscriptionFromWire(rec) {
+    return {
+        id: String(rec['id'] ?? ''),
+        ...(str(rec['model']) ? { model: str(rec['model']) } : {}),
+        ...(str(rec['post-url']) ? { postUrl: str(rec['post-url']) } : {}),
+        ...(str(rec['subscription-geo-support']) ? { geoSupport: str(rec['subscription-geo-support']) } : {}),
+        ...(str(rec['user-scope']) ? { userScope: str(rec['user-scope']) } : {}),
+        ...(str(rec['reseller']) ? { reseller: str(rec['reseller']) } : {}),
+        ...(str(rec['domain']) ? { domain: str(rec['domain']) } : {}),
+        ...(str(rec['user']) ? { user: str(rec['user']) } : {}),
+        ...(str(rec['subscription-creation-datetime']) ? { createdAt: str(rec['subscription-creation-datetime']) } : {}),
+        ...(str(rec['subscription-expires-datetime']) ? { expiresAt: str(rec['subscription-expires-datetime']) } : {}),
+        ...(str(rec['preferred-server']) ? { preferredServer: str(rec['preferred-server']) } : {}),
+        ...(str(rec['current-active-server']) ? { currentActiveServer: str(rec['current-active-server']) } : {}),
+        ...(str(rec['status']) ? { status: str(rec['status']) } : {}),
+        ...(num(rec['error-count']) !== undefined ? { errorCount: num(rec['error-count']) } : {}),
+        ...(num(rec['posts-count']) !== undefined ? { postsCount: num(rec['posts-count']) } : {}),
+        raw: rec,
+    };
+}
+function expiryToWire(v) {
+    if (v === undefined)
+        return undefined;
+    return typeof v === 'string' ? v : nsDatetime(v);
+}
+/** Map {@link CreateSubscriptionInput} to the hyphenated request body. */
+export function createInputToWire(input) {
+    const body = { model: input.model, 'post-url': input.postUrl };
+    if (input.domain !== undefined)
+        body['domain'] = input.domain;
+    if (input.user !== undefined)
+        body['user'] = input.user;
+    if (input.reseller !== undefined)
+        body['reseller'] = input.reseller;
+    if (input.geoSupport !== undefined)
+        body['subscription-geo-support'] = input.geoSupport;
+    const exp = expiryToWire(input.expiresAt);
+    if (exp !== undefined)
+        body['subscription-expires-datetime'] = exp;
+    if (input.preferredServer !== undefined)
+        body['preferred-server'] = input.preferredServer;
+    return body;
+}
+/** Map {@link UpdateSubscriptionInput} to the hyphenated request body. */
+export function updateInputToWire(changes) {
+    const body = {};
+    if (changes.model !== undefined)
+        body['model'] = changes.model;
+    if (changes.postUrl !== undefined)
+        body['post-url'] = changes.postUrl;
+    if (changes.geoSupport !== undefined)
+        body['subscription-geo-support'] = changes.geoSupport;
+    const exp = expiryToWire(changes.expiresAt);
+    if (exp !== undefined)
+        body['subscription-expires-datetime'] = exp;
+    if (changes.preferredServer !== undefined)
+        body['preferred-server'] = changes.preferredServer;
+    if (changes.errorCount !== undefined)
+        body['error-count'] = changes.errorCount;
+    if (changes.postsCount !== undefined)
+        body['posts-count'] = changes.postsCount;
+    return body;
+}
+/** Thrown by {@link NsSubscriptionsClient.create} on the API's 409 "already exists" response. */
+export class NsSubscriptionConflictError extends NsApiError {
+    constructor(message, path, body) {
+        super(message, 409, path, body, 'POST');
+        this.name = 'NsSubscriptionConflictError';
+    }
+}
+/**
+ * Read/write client for `/subscriptions`.
+ *
+ * ```ts
+ * const subs = new NsSubscriptionsClient({ server: 'api.example.com', token: key });
+ * const mine = (await subs.list()).filter((s) => s.postUrl?.startsWith('https://hooks.example.com/'));
+ * ```
+ */
+export class NsSubscriptionsClient {
+    #baseUrl;
+    #token;
+    #fetchImpl;
+    #pageSize;
+    constructor(cfg) {
+        this.#baseUrl = `https://${assertBareServer(cfg.server)}/ns-api/v2`;
+        this.#token = cfg.token;
+        this.#fetchImpl = cfg.fetchImpl ?? fetch;
+        this.#pageSize = cfg.pageSize && cfg.pageSize > 0 ? cfg.pageSize : 500;
+    }
+    /**
+     * Every subscription the credential can see, paged to completion.
+     *
+     * Paging matters: with no local registry this list *is* the source of truth, so a partial read would
+     * make a reconciler create duplicates or skip renewals. The loop is defensive in both directions — it
+     * stops on a short page, and also if a server that ignores the paging parameters returns the same
+     * records again.
+     */
+    list() {
+        return this.#listPaged('/subscriptions');
+    }
+    /** Subscriptions filtered to one domain. ⚠️ Requires API v45+; a v44 cluster returns 404. */
+    listForDomain(domain) {
+        return this.#listPaged(`/domains/${enc(domain)}/subscriptions`);
+    }
+    /** Read one subscription by id. */
+    async get(id) {
+        const rec = await this.#request('GET', `/subscriptions/${enc(id)}`);
+        return subscriptionFromWire(rec);
+    }
+    /**
+     * Create a subscription. Throws {@link NsSubscriptionConflictError} on 409, which the API returns when a
+     * subscription with a matching set of parameters already exists — usually meaning the desired state is
+     * already in place.
+     */
+    create(input) {
+        return this.#create('/subscriptions', createInputToWire(input));
+    }
+    /** Create against the domain-scoped path. ⚠️ Requires API v45+; a v44 cluster returns 404. */
+    createForDomain(domain, input) {
+        return this.#create(`/domains/${enc(domain)}/subscriptions`, createInputToWire(input));
+    }
+    /**
+     * Update a subscription — this is how renewal works (a new `subscription-expires-datetime`) and how a
+     * callback URL is rotated (`post-url`). The event filters cannot be changed.
+     */
+    update(id, changes) {
+        return this.#request('PUT', `/subscriptions/${enc(id)}`, updateInputToWire(changes));
+    }
+    /** Update against the domain-scoped path. ⚠️ Requires API v45+; a v44 cluster returns 404. */
+    updateForDomain(domain, id, changes) {
+        return this.#request('PUT', `/domains/${enc(domain)}/subscriptions/${enc(id)}`, updateInputToWire(changes));
+    }
+    /**
+     * Delete a subscription.
+     *
+     * Note the body: this endpoint takes `subscription_id` (and `domain`, required for scopes below Super
+     * User) *in addition to* the path id. That is why this client exists rather than reusing a generic write
+     * client whose `delete()` sends no body.
+     */
+    remove(id, opts = {}) {
+        const body = { subscription_id: id };
+        if (opts.domain !== undefined)
+            body['domain'] = opts.domain;
+        return this.#request('DELETE', `/subscriptions/${enc(id)}`, body);
+    }
+    async #create(path, body) {
+        try {
+            const rec = await this.#request('POST', path, body);
+            return subscriptionFromWire(rec);
+        }
+        catch (e) {
+            if (e instanceof NsApiError && e.status === 409) {
+                throw new NsSubscriptionConflictError(e.message, path, e.body);
+            }
+            throw e;
+        }
+    }
+    async #listPaged(path) {
+        const out = [];
+        const seen = new Set();
+        const limit = this.#pageSize;
+        for (let start = 0, guard = 0; guard < 200; guard++, start += limit) {
+            const page = asArray(await this.#request('GET', path, undefined, { limit, start }));
+            if (page.length === 0)
+                break;
+            let added = 0;
+            for (const rec of page) {
+                const sub = subscriptionFromWire(rec);
+                if (!sub.id || seen.has(sub.id))
+                    continue;
+                seen.add(sub.id);
+                out.push(sub);
+                added++;
+            }
+            // Short page ⇒ done. No new ids ⇒ the server ignored our paging parameters; stop rather than loop.
+            if (page.length < limit || added === 0)
+                break;
+        }
+        return out;
+    }
+    async #request(method, path, body, query) {
+        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,
+            headers: {
+                Authorization: `Bearer ${this.#token}`,
+                Accept: 'application/json',
+                ...(body ? { 'Content-Type': 'application/json' } : {}),
+            },
+            ...(body ? { body: JSON.stringify(body) } : {}),
+        });
+        const text = await res.text();
+        let parsed = text;
+        if (text) {
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                /* some endpoints return empty / plain bodies */
+            }
+        }
+        if (!res.ok) {
+            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)'
+                    : res.status === 409
+                        ? ' (a subscription with matching parameters already exists)'
+                        : '';
+            throw new NsApiError(`${method} ${path} → ${res.status}${hint}: ${detail}`, res.status, path, parsed, method);
+        }
+        return parsed;
+    }
+}
+function pickCanonical(subs) {
+    // Prefer an active one, then the most recently created; mirrors how the rest of the stack breaks ties.
+    const score = (s) => (s.status === 'active' ? 2 : s.status === 'pending' ? 1 : 0);
+    return [...subs].sort((a, b) => {
+        const d = score(b) - score(a);
+        if (d !== 0)
+            return d;
+        const at = parseNsDatetime(a.createdAt)?.getTime() ?? 0;
+        const bt = parseNsDatetime(b.createdAt)?.getTime() ?? 0;
+        return bt - at;
+    })[0];
+}
+/**
+ * Decide what to do, given what we want and what the API currently reports. Pure: no I/O, no clock, no
+ * configuration beyond {@link PlanSubscriptionsOptions} — so the whole decision surface is unit-testable
+ * and shareable by any consumer that manages its own subscriptions.
+ *
+ * Deliberate behaviours worth knowing:
+ * - Subscriptions outside `ownedPrefix` are **never** modified. If one collides with a desired
+ *   (domain, model) it is *reported*, because two subscriptions on one domain double-deliver.
+ * - `errorCount > 0` alone is **not** a fault — see this module's header.
+ * - An already-expired subscription yields `renew`, not `delete`+`create`; the caller should fall back to
+ *   `create` only if the `PUT` reports the subscription is gone.
+ */
+export function planSubscriptions(desired, actual, nowMs, opts) {
+    const rateThreshold = opts.errorRateThreshold ?? 0.5;
+    const minPosts = opts.minPostsForRate ?? 25;
+    const targetExpiry = nsDatetime(new Date(nowMs + opts.targetLifetimeSeconds * 1000));
+    const isOurs = (s) => typeof s.postUrl === 'string' && s.postUrl.startsWith(opts.ownedPrefix);
+    const ours = actual.filter(isOurs);
+    const foreign = actual.filter((s) => !isOurs(s));
+    const key = (domain, model) => `${domain.toLowerCase()}\u0000${model}`;
+    const actions = [];
+    const claimed = new Set();
+    for (const want of desired) {
+        const k = key(want.domain, want.model);
+        claimed.add(k);
+        const matches = ours.filter((s) => key(s.domain ?? '', s.model ?? '') === k);
+        for (const f of foreign) {
+            if (key(f.domain ?? '', f.model ?? '') === k) {
+                actions.push({
+                    kind: 'report',
+                    id: f.id,
+                    domain: want.domain,
+                    reason: 'another integration already subscribes to this domain+model; events will be delivered twice',
+                    ...(f.status !== undefined ? { status: f.status } : {}),
+                });
+            }
+        }
+        if (matches.length === 0) {
+            actions.push({
+                kind: 'create',
+                domain: want.domain,
+                model: want.model,
+                postUrl: want.postUrl,
+                expiresAt: targetExpiry,
+                reason: 'no subscription exists for this domain+model',
+            });
+            continue;
+        }
+        const canonical = pickCanonical(matches);
+        for (const extra of matches) {
+            if (extra.id !== canonical.id) {
+                actions.push({
+                    kind: 'delete',
+                    id: extra.id,
+                    domain: extra.domain ?? want.domain,
+                    reason: 'duplicate of our own subscription for this domain+model',
+                });
+            }
+        }
+        // Health is reported independently of whether the record also needs a url/expiry change.
+        const errs = canonical.errorCount ?? 0;
+        const posts = canonical.postsCount ?? 0;
+        if (canonical.status === 'error') {
+            actions.push({
+                kind: 'report',
+                id: canonical.id,
+                domain: canonical.domain ?? want.domain,
+                reason: 'delivery is failing (status=error)',
+                ...(canonical.status !== undefined ? { status: canonical.status } : {}),
+                errorCount: errs,
+                postsCount: posts,
+            });
+        }
+        else if (posts >= minPosts && errs / posts > rateThreshold) {
+            actions.push({
+                kind: 'report',
+                id: canonical.id,
+                domain: canonical.domain ?? want.domain,
+                reason: `sustained delivery error rate ${errs}/${posts}`,
+                ...(canonical.status !== undefined ? { status: canonical.status } : {}),
+                errorCount: errs,
+                postsCount: posts,
+            });
+        }
+        if (canonical.postUrl !== want.postUrl) {
+            actions.push({
+                kind: 'repair-url',
+                id: canonical.id,
+                domain: canonical.domain ?? want.domain,
+                postUrl: want.postUrl,
+                reason: 'callback URL differs from the configured one (deploy moved, or secret rotated)',
+            });
+            continue;
+        }
+        const expiry = parseNsDatetime(canonical.expiresAt);
+        if (!expiry) {
+            actions.push({
+                kind: 'renew',
+                id: canonical.id,
+                domain: canonical.domain ?? want.domain,
+                expiresAt: targetExpiry,
+                reason: 'expiry missing or unparseable',
+            });
+            continue;
+        }
+        const remainingSeconds = (expiry.getTime() - nowMs) / 1000;
+        if (remainingSeconds <= 0) {
+            actions.push({
+                kind: 'renew',
+                id: canonical.id,
+                domain: canonical.domain ?? want.domain,
+                expiresAt: targetExpiry,
+                reason: 'already expired',
+            });
+        }
+        else if (remainingSeconds < opts.renewHorizonSeconds) {
+            actions.push({
+                kind: 'renew',
+                id: canonical.id,
+                domain: canonical.domain ?? want.domain,
+                expiresAt: targetExpiry,
+                reason: `expires in ${Math.floor(remainingSeconds)}s, inside the renewal horizon`,
+            });
+        }
+        else {
+            actions.push({
+                kind: 'noop',
+                id: canonical.id,
+                domain: canonical.domain ?? want.domain,
+                reason: 'present, correct, and not near expiry',
+            });
+        }
+    }
+    // Ours, but no longer wanted.
+    for (const s of ours) {
+        const k = key(s.domain ?? '', s.model ?? '');
+        if (!claimed.has(k)) {
+            actions.push({
+                kind: 'delete',
+                id: s.id,
+                domain: s.domain ?? '',
+                reason: 'ours, but this domain+model is no longer configured',
+            });
+        }
+    }
+    return actions;
+}

package/dist/nsSynchronous.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Which NetSapiens v2 write operations accept the `synchronous` request-body flag.
+ *
+ * `synchronous: 'yes'` asks the API to complete the write before replying, so the response is
+ * **200 with the resulting resource inline** — including server-generated fields a caller cannot
+ * otherwise learn without a second read (a new device's SIP registration password is the worked
+ * example). Without it, or on an operation that does not support it, the API replies
+ * **202 Accepted** with a bare `{code, message}` acknowledgement and applies the write behind the
+ * scenes.
+ *
+ * **It is a per-operation capability, not a global one.** Only the operations listed below declare
+ * a `synchronous` property in the v2 OpenAPI specification (core 44.4.10) — 17 of them, almost all
+ * creates. Sending the flag to any other endpoint is inert: NetSapiens ignores unrecognized body
+ * fields and still answers 202. That is harmless but misleading, because it makes code look as
+ * though it has a synchronous guarantee it never had.
+ *
+ * The most consequential absence is **`PUT /domains/{domain}/users/{user}`** — a user *update*
+ * cannot be made synchronous, though a user *create* can. Verified live 2026-08-03: the flag in the
+ * body, as `?synchronous=yes`, as `?synchronous=true`, both at once, and omitted entirely all return
+ * an identical 202 on that endpoint. Any confirmation of a user update has to come from reading the
+ * record back, not from the response.
+ *
+ * Kept as data rather than folded into each method so both this library's write client and other
+ * NetSapiens clients can share one answer instead of drifting apart.
+ */
+/** The HTTP methods any `synchronous`-capable operation uses. */
+export type SynchronousMethod = 'POST' | 'PUT';
+/** One operation that accepts `synchronous`, as a method plus an OpenAPI-style templated path. */
+export interface SynchronousOperation {
+    method: SynchronousMethod;
+    /** Templated path, e.g. `/domains/{domain}/users`. A `{...}` segment matches exactly one path segment. */
+    path: string;
+}
+/**
+ * Every operation declaring `synchronous` in the v2 spec (core 44.4.10), deduplicated — the
+ * specification lists several of these more than once under `#1`…`#4` suffixes for differing
+ * request shapes, which are the same HTTP operation.
+ *
+ * Note the near-misses, which are the whole reason this list is explicit: user and domain **create**
+ * are here, user **update** is not; greeting and MOH **update** are here, device update is not.
+ */
+export declare const SYNCHRONOUS_OPERATIONS: readonly SynchronousOperation[];
+/**
+ * Does `method path` accept `synchronous`?
+ *
+ * `path` is a concrete request path relative to the `/ns-api/v2` base, with its dynamic segments
+ * already filled in and URI-encoded — exactly what a client passes to `post()`/`put()`. Encoding is
+ * what makes the match safe: a value containing a slash arrives as `%2F` and stays one segment, so
+ * it cannot masquerade as a deeper path.
+ *
+ * Unknown paths answer `false`. That is the safe direction: the flag is then omitted, and the caller
+ * gets the 202 it would have received anyway — rather than a promise of a 200 that never arrives.
+ */
+export declare function supportsSynchronous(method: string, path: string): boolean;

package/dist/nsSynchronous.js

@@ -0,0 +1,78 @@
+/**
+ * Which NetSapiens v2 write operations accept the `synchronous` request-body flag.
+ *
+ * `synchronous: 'yes'` asks the API to complete the write before replying, so the response is
+ * **200 with the resulting resource inline** — including server-generated fields a caller cannot
+ * otherwise learn without a second read (a new device's SIP registration password is the worked
+ * example). Without it, or on an operation that does not support it, the API replies
+ * **202 Accepted** with a bare `{code, message}` acknowledgement and applies the write behind the
+ * scenes.
+ *
+ * **It is a per-operation capability, not a global one.** Only the operations listed below declare
+ * a `synchronous` property in the v2 OpenAPI specification (core 44.4.10) — 17 of them, almost all
+ * creates. Sending the flag to any other endpoint is inert: NetSapiens ignores unrecognized body
+ * fields and still answers 202. That is harmless but misleading, because it makes code look as
+ * though it has a synchronous guarantee it never had.
+ *
+ * The most consequential absence is **`PUT /domains/{domain}/users/{user}`** — a user *update*
+ * cannot be made synchronous, though a user *create* can. Verified live 2026-08-03: the flag in the
+ * body, as `?synchronous=yes`, as `?synchronous=true`, both at once, and omitted entirely all return
+ * an identical 202 on that endpoint. Any confirmation of a user update has to come from reading the
+ * record back, not from the response.
+ *
+ * Kept as data rather than folded into each method so both this library's write client and other
+ * NetSapiens clients can share one answer instead of drifting apart.
+ */
+/**
+ * Every operation declaring `synchronous` in the v2 spec (core 44.4.10), deduplicated — the
+ * specification lists several of these more than once under `#1`…`#4` suffixes for differing
+ * request shapes, which are the same HTTP operation.
+ *
+ * Note the near-misses, which are the whole reason this list is explicit: user and domain **create**
+ * are here, user **update** is not; greeting and MOH **update** are here, device update is not.
+ */
+export const SYNCHRONOUS_OPERATIONS = [
+    { method: 'POST', path: '/domains' },
+    { method: 'POST', path: '/domains/{domain}/callqueues' },
+    { method: 'POST', path: '/domains/{domain}/callqueues/{callqueue}/agents' },
+    { method: 'POST', path: '/domains/{domain}/dialplans/{dialplan}/dialrules' },
+    { method: 'POST', path: '/domains/{domain}/moh' },
+    { method: 'PUT', path: '/domains/{domain}/moh/{index}' },
+    { method: 'PUT', path: '/domains/{domain}/sites/{site}' },
+    { method: 'POST', path: '/domains/{domain}/timeframes' },
+    { method: 'POST', path: '/domains/{domain}/users' },
+    { method: 'POST', path: '/domains/{domain}/users/{user}/answerrules' },
+    { method: 'POST', path: '/domains/{domain}/users/{user}/calls' },
+    { method: 'POST', path: '/domains/{domain}/users/{user}/devices' },
+    { method: 'POST', path: '/domains/{domain}/users/{user}/greetings' },
+    { method: 'PUT', path: '/domains/{domain}/users/{user}/greetings/{index}' },
+    { method: 'POST', path: '/domains/{domain}/users/{user}/moh' },
+    { method: 'PUT', path: '/domains/{domain}/users/{user}/moh/{index}' },
+    { method: 'POST', path: '/domains/{domain}/users/{user}/timeframes' },
+];
+/** Split a path into non-empty segments, ignoring any query string and leading/trailing slashes. */
+const segmentsOf = (path) => (path.split('?')[0] ?? '').split('/').filter(Boolean);
+/** Precomputed segment forms, so a lookup is a comparison rather than a re-parse per call. */
+const TABLE = SYNCHRONOUS_OPERATIONS.map((op) => ({ method: op.method, segments: segmentsOf(op.path) }));
+/**
+ * Does `method path` accept `synchronous`?
+ *
+ * `path` is a concrete request path relative to the `/ns-api/v2` base, with its dynamic segments
+ * already filled in and URI-encoded — exactly what a client passes to `post()`/`put()`. Encoding is
+ * what makes the match safe: a value containing a slash arrives as `%2F` and stays one segment, so
+ * it cannot masquerade as a deeper path.
+ *
+ * Unknown paths answer `false`. That is the safe direction: the flag is then omitted, and the caller
+ * gets the 202 it would have received anyway — rather than a promise of a 200 that never arrives.
+ */
+export function supportsSynchronous(method, path) {
+    const verb = method.toUpperCase();
+    if (verb !== 'POST' && verb !== 'PUT')
+        return false;
+    const actual = segmentsOf(path);
+    return TABLE.some((op) => op.method === verb &&
+        op.segments.length === actual.length &&
+        op.segments.every((seg, i) => seg.startsWith('{') && seg.endsWith('}')
+            ? true // a template segment matches any single segment
+            : seg.toLowerCase() === actual[i].toLowerCase()));
+}

package/dist/nsWriteClient.d.ts

@@ -8,11 +8,15 @@
  * generic post/put/delete core, and is meant to GROW into the full NS write surface (users, DIDs, …) —
  * porting the endpoint/body shapes from the onboarding tool's resource defs as they're needed.
  *
- * Like the onboarding client, POST/PUT inject `synchronous: 'yes'` so a create returns 200 + the created
- * resource inline (with server-generated fields — e.g. a device's `device-sip-registration-password`)
- * instead of a 202 with replication lag. Shares the read client's SSRF guard and `NsApiError`.
+ * POST/PUT inject `synchronous: 'yes'` **only on the operations that accept it** (see
+ * {@link supportsSynchronous}), where it makes the API return 200 + the resulting resource inline —
+ * with server-generated fields such as a device's `device-sip-registration-password` — instead of a
+ * bare 202 acknowledgement. Everywhere else the flag is omitted, because sending it there is inert:
+ * NetSapiens ignores it and still answers 202, which previously made this client look as though all
+ * of its writes were confirmed when most were not. Shares the read client's SSRF guard and `NsApiError`.
  */
 import type { Rec } from './model.js';
+import { type EnsureNsDeviceOptions, type EnsureNsDeviceResult } from './nsDevice.js';
 export interface NsWriteClientConfig {
     /** API host, e.g. "api.example.com". Base URL becomes https://{server}/ns-api/v2. */
     server: string;
@@ -25,9 +29,15 @@ export declare class NsWriteClient {
     #private;
     constructor(cfg: NsWriteClientConfig);
     get<T = unknown>(path: string, query?: Record<string, string | number>): Promise<T>;
-    /** 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<T = unknown>(path: string, body: Rec): Promise<T>;
-    /** 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<T = unknown>(path: string, body: Rec): Promise<T>;
     delete<T = unknown>(path: string): Promise<T>;
     /** List a user's devices (normalized to an array). */
@@ -40,6 +50,30 @@ export declare class NsWriteClient {
      * optional fields (e.g. an emergency caller-id).
      */
     createDevice(domain: string, user: string, device: string, extra?: Rec): Promise<Rec>;
+    /**
+     * 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: string, user: string, device: string, changes: Rec): Promise<Rec>;
     /** Delete a device. */
     deleteDevice(domain: string, user: string, device: string): Promise<Rec>;
+    /**
+     * 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: EnsureNsDeviceOptions): Promise<EnsureNsDeviceResult>;
 }