@dszp/netsapiens-lib 0.1.4 → 0.1.6

package/dist/eligibility.d.ts

@@ -38,11 +38,27 @@ export interface EligContext {
     isReseller: boolean;
     /** Reseller RUNTIME force: bypass ALL soft categories — never HARD, never the email precondition. */
     force?: boolean;
+    /**
+     * Credentials are delivered by LOGIN, not email, so the email precondition does not apply. Set this on
+     * an SSO/JIT path, where the account is created from the user's own directory credentials on first
+     * sign-in and nothing is mailed. It waives ONLY the email precondition — never HARD, never SOFT.
+     *
+     * The caller decides WHEN to set it; the engine only guarantees the outcome is the same everywhere it
+     * is set. A waived result stays distinguishable via `emailWaived`, so a caller can still branch on
+     * "eligible, but there is no address to mail anything to".
+     */
+    emailNotRequired?: boolean;
 }
 export type EligTier = 'ok' | 'hard' | 'soft' | 'precondition';
 export interface EligResult {
     activatable: boolean;
     tier: EligTier;
     reasons: string[];
+    /**
+     * The user has no email address and `emailNotRequired` waived the precondition. `tier` is `'ok'` —
+     * they are eligible — but there is no address, so a caller must not try to mail them credentials.
+     * Absent whenever an address is present or the precondition was not reached.
+     */
+    emailWaived?: true;
 }
 export declare function evaluateEligibility(user: EligUser, ctx: EligContext, config: EligibilityConfig): EligResult;

package/dist/eligibility.js

@@ -42,7 +42,17 @@ export function evaluateEligibility(user, ctx, config) {
         return { activatable: false, tier: 'soft', reasons: [`extension "${user.ext}" matches excluded pattern "${extHit}"`] };
     }
     if (blank(user.email)) {
-        return { activatable: false, tier: 'precondition', reasons: ['an email address is required to activate'] };
+        if (!ctx.emailNotRequired) {
+            return { activatable: false, tier: 'precondition', reasons: ['an email address is required to activate'] };
+        }
+        // Waived: credentials arrive by login, not mail. Eligible — but say the address is missing, so a
+        // caller that WOULD have mailed something can still tell.
+        return {
+            activatable: true,
+            tier: 'ok',
+            reasons: ['no email address (precondition waived: credentials are not emailed)'],
+            emailWaived: true,
+        };
     }
     return { activatable: true, tier: 'ok', reasons: [] };
 }

package/dist/index.d.ts

@@ -17,7 +17,9 @@ export { renderGalleryHtml, renderFlowCards, renderFlowCard, mermaidBootstrap, f
 export { resolveSvgSize, rasterizerScript } from './raster.js';
 export { NsClient, NsApiError, assertBareServer, fetchDomainSnapshot, listDomains, asArray, type NsClientConfig, type FetchSnapshotOptions } from './nsClient.js';
 export { NsWriteClient, type NsWriteClientConfig } from './nsWriteClient.js';
+export { ensureNsDevice, generateSipPassword, SIP_PW_FIELD, type NsDeviceWriter, type EnsureNsDeviceOptions, type EnsureNsDeviceResult, } from './nsDevice.js';
 export { NsAuthClient, NsAuthError, type NsAuthClientConfig, type NsTokenResponse } from './nsAuthClient.js';
+export { NsSubscriptionsClient, NsSubscriptionConflictError, SUBSCRIPTION_MODELS, isSubscriptionModel, nsDatetime, parseNsDatetime, subscriptionFromWire, createInputToWire, updateInputToWire, planSubscriptions, type SubscriptionModel, type SubscriptionStatus, type Subscription, type CreateSubscriptionInput, type UpdateSubscriptionInput, type NsSubscriptionsClientConfig, type DesiredSubscription, type SubscriptionAction, type PlanSubscriptionsOptions, } from './nsSubscriptions.js';
 export { verify, validateJwtFormat, extractContext, assertClaims, verifyHs256Signature, normalizeToken, tokenKey, MemoryVerdictCache, type JwtVerdict, type JwtContext, type ClaimExpectations, type VerdictCache, type VerifyOptions, type FormatResult, } from './jwt.js';
 export { type CallSensitivity, needsFreshAuth, SENSITIVITY_NOTE } from './sensitivity.js';
 export { toPrincipal, parseOperator, isResellerScope, isAdminScope, type Principal, type Operator, type Scope, } from './principal.js';

package/dist/index.js

@@ -16,7 +16,9 @@ export { renderGalleryHtml, renderFlowCards, renderFlowCard, mermaidBootstrap, f
 export { resolveSvgSize, rasterizerScript } from './raster.js';
 export { NsClient, NsApiError, assertBareServer, fetchDomainSnapshot, listDomains, asArray } from './nsClient.js';
 export { NsWriteClient } from './nsWriteClient.js';
+export { ensureNsDevice, generateSipPassword, SIP_PW_FIELD, } from './nsDevice.js';
 export { NsAuthClient, NsAuthError } from './nsAuthClient.js';
+export { NsSubscriptionsClient, NsSubscriptionConflictError, SUBSCRIPTION_MODELS, isSubscriptionModel, nsDatetime, parseNsDatetime, subscriptionFromWire, createInputToWire, updateInputToWire, planSubscriptions, } from './nsSubscriptions.js';
 export { verify, validateJwtFormat, extractContext, assertClaims, verifyHs256Signature, normalizeToken, tokenKey, MemoryVerdictCache, } from './jwt.js';
 export { needsFreshAuth, SENSITIVITY_NOTE } from './sensitivity.js';
 export { toPrincipal, parseOperator, isResellerScope, isAdminScope, } from './principal.js';

package/dist/nsDevice.d.ts

@@ -0,0 +1,89 @@
+/**
+ * NetSapiens device orchestration — ensure a named device exists and hand back its SIP registration
+ * password, optionally rotating it.
+ *
+ * This lives in the library because two separate consumers had grown their own copy of it, and a
+ * divergence between them is expensive: they both provision the same softphone device for the same
+ * extension, and disagreeing about whether to reuse or replace its credentials produces bugs that look
+ * like a phone problem rather than a code problem. One implementation, one set of tests.
+ *
+ * Mechanism only — no policy. The device NAME is a caller-supplied string (a consumer's `<ext><suffix>`
+ * convention is its own business), *whether* creation is permitted is the caller's decision, and *when*
+ * rotation is appropriate is very much the caller's decision. See {@link ensureNsDevice}.
+ */
+import type { Rec } from './model.js';
+/** The NS device field carrying the auto-generated SIP registration password (API v2). */
+export declare const SIP_PW_FIELD = "device-sip-registration-password";
+/** The subset of a write client this needs. Structural, so a consumer can inject a mock or a subset. */
+export interface NsDeviceWriter {
+    getDevices(domain: string, user: string): Promise<Rec[]>;
+    getDevice(domain: string, user: string, device: string): Promise<Rec>;
+    createDevice(domain: string, user: string, device: string, extra?: Rec): Promise<Rec>;
+    updateDevice(domain: string, user: string, device: string, changes: Rec): Promise<Rec>;
+}
+/**
+ * Generate a SIP registration password.
+ *
+ * Alphanumeric only: the value travels through SIP digest auth, device provisioning templates, and
+ * whatever the consuming app stores it in, and punctuation buys no meaningful entropy while risking an
+ * escaping bug in any one of those. Characters are rejection-sampled rather than modulo-reduced, so every
+ * symbol is equally likely.
+ *
+ * **Guarantees at least one uppercase, one lowercase, and one digit** (for `length >= 3`). A uniform draw
+ * from a 62-symbol alphabet omits digits entirely about 3% of the time at length 20, which looks like a
+ * bug to anyone who eyeballs one and can trip a downstream password-complexity rule. The whole candidate
+ * is redrawn until it qualifies — never patched in place, which would bias the positions it patched.
+ */
+export declare function generateSipPassword(length?: number): string;
+export interface EnsureNsDeviceOptions {
+    domain: string;
+    /** The NS user / extension that owns the device. */
+    user: string;
+    /** The device name, e.g. `100r`. */
+    device: string;
+    /**
+     * May this create the device when it is absent? Default `true`. Pass `false` to look without creating —
+     * the result's `password` is then `''` for a missing device, which a caller can treat as "refuse".
+     */
+    mayCreate?: boolean;
+    /**
+     * Replace the password of a device that **already existed**.
+     *
+     * This closes a subtle and genuinely hard-to-diagnose failure: reusing the stored password leaves any
+     * *other* endpoint still holding it with valid credentials for the same address-of-record. Both clients
+     * then register, the most recent wins, and they trade the registration back and forth — intermittent
+     * call failures with nothing obviously wrong in either system.
+     *
+     * Rotate only where something has just declared this device to belong to one client — a deliberate
+     * activation or a first-time provision. **Do not rotate on a per-login or per-request path**: concurrent
+     * runs would churn the credential and can race a re-registration.
+     *
+     * Rotation is **best-effort** and never throws: on failure the result carries the pre-existing password
+     * plus `rotated: false` and `rotateError`, because failing the whole operation over a hardening step
+     * would be worse than the contention it prevents. Notably a NetSapiens release without the device `PUT`
+     * lands here.
+     */
+    rotateExisting?: boolean;
+    /** Length for a rotated password. Default 20. */
+    passwordLength?: number;
+}
+export interface EnsureNsDeviceResult {
+    /** The SIP password to give the client. `''` means "absent and not created" — treat as a refusal. */
+    password: string;
+    /** True when this call created the device. */
+    created: boolean;
+    /** Present only when `rotateExisting` was requested: whether the rotation actually happened. */
+    rotated?: boolean;
+    /** Why rotation failed, when it did. */
+    rotateError?: string;
+}
+/**
+ * Ensure the device exists and return its SIP password.
+ *
+ * Present: read it back with a per-device GET, because a device *list* may omit the password. Absent:
+ * create it (NetSapiens generates the password; a `synchronous` write returns it inline) unless
+ * `mayCreate` is false.
+ *
+ * A newly created device is never rotated — it already has a fresh, exclusive password.
+ */
+export declare function ensureNsDevice(writer: NsDeviceWriter, opts: EnsureNsDeviceOptions): Promise<EnsureNsDeviceResult>;

package/dist/nsDevice.js

@@ -0,0 +1,101 @@
+/** The NS device field carrying the auto-generated SIP registration password (API v2). */
+export const SIP_PW_FIELD = 'device-sip-registration-password';
+const PW_UPPER = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
+const PW_LOWER = 'abcdefghijklmnopqrstuvwxyz';
+const PW_DIGIT = '0123456789';
+const PW_ALPHABET = PW_UPPER + PW_LOWER + PW_DIGIT;
+/** Uniformly-drawn characters from the alphabet, rejection-sampled so no symbol is over-represented. */
+function randomChars(n) {
+    const out = [];
+    const buf = new Uint8Array(n * 2);
+    const limit = Math.floor(256 / PW_ALPHABET.length) * PW_ALPHABET.length; // 248 for a 62-symbol alphabet
+    while (out.length < n) {
+        crypto.getRandomValues(buf);
+        for (const b of buf) {
+            if (b >= limit)
+                continue; // reject, to keep the distribution uniform
+            out.push(PW_ALPHABET[b % PW_ALPHABET.length]);
+            if (out.length === n)
+                break;
+        }
+    }
+    return out;
+}
+const hasEach = (s) => /[A-Z]/.test(s) && /[a-z]/.test(s) && /[0-9]/.test(s);
+/**
+ * Generate a SIP registration password.
+ *
+ * Alphanumeric only: the value travels through SIP digest auth, device provisioning templates, and
+ * whatever the consuming app stores it in, and punctuation buys no meaningful entropy while risking an
+ * escaping bug in any one of those. Characters are rejection-sampled rather than modulo-reduced, so every
+ * symbol is equally likely.
+ *
+ * **Guarantees at least one uppercase, one lowercase, and one digit** (for `length >= 3`). A uniform draw
+ * from a 62-symbol alphabet omits digits entirely about 3% of the time at length 20, which looks like a
+ * bug to anyone who eyeballs one and can trip a downstream password-complexity rule. The whole candidate
+ * is redrawn until it qualifies — never patched in place, which would bias the positions it patched.
+ */
+export function generateSipPassword(length = 20) {
+    if (!Number.isInteger(length) || length < 1)
+        throw new Error('generateSipPassword: length must be a positive integer');
+    // Below 3 characters the guarantee is arithmetically impossible; return a uniform draw.
+    if (length < 3)
+        return randomChars(length).join('');
+    for (let attempt = 0; attempt < 100; attempt++) {
+        const candidate = randomChars(length).join('');
+        if (hasEach(candidate))
+            return candidate;
+    }
+    // Unreachable in practice (the odds compound to ~0). Draw one character from each class DIRECTLY —
+    // upper-casing an arbitrary draw is not a guarantee, since upper-casing a digit yields the same digit.
+    const pick = (alphabet) => {
+        const b = new Uint8Array(1);
+        const limit = Math.floor(256 / alphabet.length) * alphabet.length;
+        for (;;) {
+            crypto.getRandomValues(b);
+            if (b[0] < limit)
+                return alphabet[b[0] % alphabet.length];
+        }
+    };
+    return [pick(PW_UPPER), pick(PW_LOWER), pick(PW_DIGIT), ...randomChars(length - 3)].join('');
+}
+/**
+ * Ensure the device exists and return its SIP password.
+ *
+ * Present: read it back with a per-device GET, because a device *list* may omit the password. Absent:
+ * create it (NetSapiens generates the password; a `synchronous` write returns it inline) unless
+ * `mayCreate` is false.
+ *
+ * A newly created device is never rotated — it already has a fresh, exclusive password.
+ */
+export async function ensureNsDevice(writer, opts) {
+    const { domain, user, device } = opts;
+    const devices = await writer.getDevices(domain, user);
+    const existing = Array.isArray(devices) ? devices.find((d) => String(d['device'] ?? '') === device) : undefined;
+    if (existing) {
+        const dev = await writer.getDevice(domain, user, device);
+        const current = String(dev[SIP_PW_FIELD] ?? existing[SIP_PW_FIELD] ?? '');
+        if (!opts.rotateExisting)
+            return { password: current, created: false };
+        const fresh = generateSipPassword(opts.passwordLength ?? 20);
+        try {
+            const updated = await writer.updateDevice(domain, user, device, { [SIP_PW_FIELD]: fresh });
+            // Prefer what NS echoes back if it echoes anything; otherwise the value we just set.
+            // `||` not `??`: an echoed empty string would otherwise be handed back as the password, and the
+            // caller's blank-password guard would refuse AFTER the device was already rotated.
+            return { password: String(updated?.[SIP_PW_FIELD] || fresh), created: false, rotated: true };
+        }
+        catch (e) {
+            return {
+                password: current,
+                created: false,
+                rotated: false,
+                rotateError: String(e?.message ?? e).slice(0, 200),
+            };
+        }
+    }
+    if (opts.mayCreate === false)
+        return { password: '', created: false };
+    const created = await writer.createDevice(domain, user, device);
+    return { password: String(created?.[SIP_PW_FIELD] ?? ''), created: true };
+}

package/dist/nsSubscriptions.d.ts

@@ -0,0 +1,266 @@
+/**
+ * NetSapiens API v2 **Event Subscriptions** — a separate client for the `/subscriptions` surface, plus a
+ * pure reconciliation planner.
+ *
+ * This is its own class on purpose. `NsClient` is read-only by charter (a consumer holds one precisely to
+ * know it cannot write), and `NsWriteClient` is unsuitable here for two concrete reasons: it injects
+ * `synchronous: 'yes'` into every POST/PUT, and its `delete()` sends no body — while
+ * `DELETE /subscriptions/{id}` *requires* a body (`subscription_id`, plus `domain` for scopes below Super
+ * User). Node-free (fetch/URL/crypto only), so it runs unchanged in a Cloudflare Worker.
+ *
+ * An event subscription tells NetSapiens to POST change events to a URL you own. Notable API properties
+ * that shape this module:
+ *
+ * - **`id` is server-generated**, so a subscription cannot be tagged by the client. Ours are therefore
+ *   identified by `post-url`, which makes the URL both the address *and* the label.
+ * - **Filters are immutable.** `PUT` accepts `post-url` and `subscription-expires-datetime` but not
+ *   `domain`/`user`/`reseller`, so a filter change means a new subscription.
+ * - **Always send an explicit `expiresAt`.** Observed behaviour: an explicit expiry is stored verbatim
+ *   *even when the request is authenticated with a one-hour OAuth access token* — the expiry is not
+ *   clamped to the credential's lifetime. Omitting it yields a ~20-year expiry for an API key but only the
+ *   token's expiry for a timed token, so relying on the default makes lifetime depend on how you
+ *   authenticated. Renewal, when needed, is a `PUT`, never delete-and-recreate.
+ * - ⚠️ **`subscription-geo-support` behaves as `no` when omitted**, despite the API describing the default
+ *   as `yes`. Send it explicitly if you want geo-redundant delivery (you almost certainly do — otherwise
+ *   delivery is pinned and stops when that node is down).
+ * - ⚠️ **The domain-scoped routes (`/domains/{domain}/subscriptions`, API v45+) are not present on every
+ *   cluster** — a v44 cluster answers `404 No Route Found` while the flat `/subscriptions` paths work.
+ *   Prefer the flat methods and treat the domain-scoped ones as an opt-in optimization.
+ * - **Datetimes are asymmetric.** Reads observably return ISO-8601 with an offset; the documented *write*
+ *   format is `YYYY-MM-DD HH:MM:SS`. {@link parseNsDatetime} accepts both; {@link nsDatetime} emits the
+ *   documented form.
+ * - **`error-count` > 0 is normal on a healthy subscription** — a live example sat at 7 errors across 7195
+ *   posts while `status` stayed `active`. Treat `status === 'error'` or a sustained error *rate* as the
+ *   signal, and never reset the counters as routine maintenance: they are the only history the API keeps.
+ */
+import type { Rec } from './model.js';
+import { NsApiError } from './nsClient.js';
+/** Event types a subscription can carry. One subscription carries exactly one model. */
+export type SubscriptionModel = 'agent' | 'auditlog' | 'auditlog_lite' | 'call' | 'call_origid' | 'cdr' | 'message' | 'messagesession' | 'subscriber' | 'presence' | 'voicemail';
+/** Every valid `model` value, for validating configuration before it reaches the API. */
+export declare const SUBSCRIPTION_MODELS: readonly SubscriptionModel[];
+/** Narrowing guard for a configured model string. */
+export declare function isSubscriptionModel(v: unknown): v is SubscriptionModel;
+/** Server-reported delivery health. `pending` until the first successful post. */
+export type SubscriptionStatus = 'pending' | 'active' | 'error';
+/**
+ * A subscription, with the API's hyphenated wire keys mapped to camelCase. Datetimes are kept as the
+ * **raw strings** the API returned (parse with {@link parseNsDatetime} when you need a `Date`), and `raw`
+ * carries the untouched record so a caller never loses a field this type hasn't modelled.
+ */
+export interface Subscription {
+    id: string;
+    model?: string;
+    postUrl?: string;
+    geoSupport?: string;
+    userScope?: string;
+    reseller?: string;
+    domain?: string;
+    user?: string;
+    /** Raw `subscription-creation-datetime`. */
+    createdAt?: string;
+    /** Raw `subscription-expires-datetime`. */
+    expiresAt?: string;
+    preferredServer?: string;
+    /** Read-only: the node currently delivering. Changes on failover. */
+    currentActiveServer?: string;
+    status?: string;
+    errorCount?: number;
+    postsCount?: number;
+    /** The untouched API record. */
+    raw: Rec;
+}
+/** Fields accepted when creating. `domain`/`user`/`reseller` are the (immutable) event filters. */
+export interface CreateSubscriptionInput {
+    model: SubscriptionModel;
+    /** Absolute https URL NetSapiens will POST to. */
+    postUrl: string;
+    /** Restrict to one domain. `'*'` means all domains and requires Super User scope. */
+    domain?: string;
+    /** Restrict to one user/extension. Defaults to all. */
+    user?: string;
+    /** Restrict to one reseller. `'*'` requires Super User scope. */
+    reseller?: string;
+    /**
+     * Geo-redundant delivery across nodes. ⚠️ Behaves as `'no'` when omitted, despite the API documenting
+     * `'yes'` as the default — send `'yes'` explicitly unless you deliberately want delivery pinned.
+     */
+    geoSupport?: 'yes' | 'no';
+    /**
+     * Explicit expiry, and you should always set one. It is honoured verbatim even when the request is
+     * authenticated with a short-lived OAuth token. Omitting it makes the lifetime depend on the credential
+     * (API key ⇒ ~20 years; timed token ⇒ that token's expiry).
+     */
+    expiresAt?: Date | string;
+    /** Preferred delivering node. A preference, not a pin — other nodes deliver during instability. */
+    preferredServer?: string;
+}
+/** Fields `PUT` accepts. The event filters are deliberately absent — they cannot be changed. */
+export interface UpdateSubscriptionInput {
+    model?: SubscriptionModel;
+    postUrl?: string;
+    geoSupport?: 'yes' | 'no';
+    expiresAt?: Date | string;
+    preferredServer?: string;
+    /** Only `0` is accepted — a reset. Prefer leaving counters alone; they are the only history kept. */
+    errorCount?: 0;
+    /** Only `0` is accepted — a reset. */
+    postsCount?: 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 declare function nsDatetime(d: Date): string;
+/**
+ * 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 declare function parseNsDatetime(s: string | undefined | null): Date | undefined;
+/** Map one API record to {@link Subscription}. Tolerant: an unmodelled or missing field is simply absent. */
+export declare function subscriptionFromWire(rec: Rec): Subscription;
+/** Map {@link CreateSubscriptionInput} to the hyphenated request body. */
+export declare function createInputToWire(input: CreateSubscriptionInput): Rec;
+/** Map {@link UpdateSubscriptionInput} to the hyphenated request body. */
+export declare function updateInputToWire(changes: UpdateSubscriptionInput): Rec;
+export interface NsSubscriptionsClientConfig {
+    /** API host, e.g. `"api.example.com"`. Base URL becomes `https://{server}/ns-api/v2`. */
+    server: string;
+    /** Bearer token — an API key, or an OAuth access token, with scope to manage subscriptions. */
+    token: string;
+    /** Injectable for tests / non-global fetch. */
+    fetchImpl?: typeof fetch;
+    /** Page size for list calls. Default 500. */
+    pageSize?: number;
+}
+/** Thrown by {@link NsSubscriptionsClient.create} on the API's 409 "already exists" response. */
+export declare class NsSubscriptionConflictError extends NsApiError {
+    constructor(message: string, path: string, body: unknown);
+}
+/**
+ * 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 declare class NsSubscriptionsClient {
+    #private;
+    constructor(cfg: NsSubscriptionsClientConfig);
+    /**
+     * 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(): Promise<Subscription[]>;
+    /** Subscriptions filtered to one domain. ⚠️ Requires API v45+; a v44 cluster returns 404. */
+    listForDomain(domain: string): Promise<Subscription[]>;
+    /** Read one subscription by id. */
+    get(id: string): Promise<Subscription>;
+    /**
+     * 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: CreateSubscriptionInput): Promise<Subscription>;
+    /** Create against the domain-scoped path. ⚠️ Requires API v45+; a v44 cluster returns 404. */
+    createForDomain(domain: string, input: CreateSubscriptionInput): Promise<Subscription>;
+    /**
+     * 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: string, changes: UpdateSubscriptionInput): Promise<unknown>;
+    /** Update against the domain-scoped path. ⚠️ Requires API v45+; a v44 cluster returns 404. */
+    updateForDomain(domain: string, id: string, changes: UpdateSubscriptionInput): Promise<unknown>;
+    /**
+     * 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: string, opts?: {
+        domain?: string;
+    }): Promise<unknown>;
+}
+/** One subscription we want to exist. */
+export interface DesiredSubscription {
+    domain: string;
+    model: SubscriptionModel;
+    /** The exact callback URL this (domain, model) should post to. */
+    postUrl: string;
+}
+/** An action the caller should execute. Every variant carries a human-readable `reason` for logging. */
+export type SubscriptionAction = {
+    kind: 'create';
+    domain: string;
+    model: SubscriptionModel;
+    postUrl: string;
+    expiresAt: string;
+    reason: string;
+} | {
+    kind: 'renew';
+    id: string;
+    domain: string;
+    expiresAt: string;
+    reason: string;
+} | {
+    kind: 'repair-url';
+    id: string;
+    domain: string;
+    postUrl: string;
+    reason: string;
+} | {
+    kind: 'delete';
+    id: string;
+    domain: string;
+    reason: string;
+} | {
+    kind: 'report';
+    id: string;
+    domain: string;
+    reason: string;
+    status?: string;
+    errorCount?: number;
+    postsCount?: number;
+} | {
+    kind: 'noop';
+    id: string;
+    domain: string;
+    reason: string;
+};
+export interface PlanSubscriptionsOptions {
+    /**
+     * Only subscriptions whose `postUrl` starts with this prefix are considered ours. Everything else is
+     * left strictly alone — other integrations legitimately subscribe to the same domains.
+     */
+    ownedPrefix: string;
+    /** Renew when the remaining lifetime is below this. */
+    renewHorizonSeconds: number;
+    /** Lifetime to request on create and renew. */
+    targetLifetimeSeconds: number;
+    /** Report when `errorCount / postsCount` exceeds this. Default 0.5. */
+    errorRateThreshold?: number;
+    /** Don't judge an error rate below this many posts — small samples are noise. Default 25. */
+    minPostsForRate?: number;
+}
+/**
+ * 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 declare function planSubscriptions(desired: DesiredSubscription[], actual: Subscription[], nowMs: number, opts: PlanSubscriptionsOptions): SubscriptionAction[];

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()}${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/nsWriteClient.d.ts

@@ -13,6 +13,7 @@
  * instead of a 202 with replication lag. 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;
@@ -40,6 +41,26 @@ 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.
+     *
+     * 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>;
 }

package/dist/nsWriteClient.js

@@ -1,4 +1,5 @@
 import { NsApiError, assertBareServer, asArray } from './nsClient.js';
+import { ensureNsDevice } from './nsDevice.js';
 const enc = encodeURIComponent;
 export class NsWriteClient {
     #baseUrl;
@@ -41,10 +42,34 @@ 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.
+     *
+     * 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,6 +1,6 @@
 {
   "name": "@dszp/netsapiens-lib",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "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.",
   "type": "module",
   "license": "MIT",
@@ -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,8 +55,8 @@
     "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: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",
@@ -58,7 +64,9 @@
     "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",