@dszp/netsapiens-lib 0.1.0

package/dist/jwt.d.ts

@@ -0,0 +1,174 @@
+/**
+ * NetSapiens `ns_t` JWT validation — runtime-portable (Cloudflare Worker + Node 18+).
+ *
+ * Ported from n8n-nodes-netsapiens (nodes/NetSapiens/NetSapiens.node.ts), which exposes two
+ * operations we mirror here:
+ *   - Validate JWT Format  → local base64url-decode + `exp` check, NO server contact, NO
+ *     signature verification (low-security; matches the node exactly).
+ *   - Validate JWT (live)  → GET {server}/ns-api/v2/jwt with `Authorization: Bearer <token>`;
+ *     HTTP 401/403 ⇒ rejected. Authoritative, but a server roundtrip.
+ *
+ * Design constraint (David): the live path must NOT overload the NS API. So `verify()` gates on
+ * the cheap local check first, then serves a *cached* live verdict keyed by a hash of the token,
+ * with a TTL capped by the token's own `exp`. A bad or expired token never reaches the server.
+ *
+ * Uses only Web-standard globals (atob, TextDecoder, crypto.subtle, fetch) — no Node Buffer — so
+ * the same file runs in a Worker and in the ns-onboard CLI.
+ */
+export interface JwtContext {
+    /** The token's domain (from claims). Scopes downstream NS reads. When masking, this is the
+     *  MASKED user's domain — the token is NS-scoped to it, not the operator's. */
+    domain?: string;
+    /** The token's user / extension (the masked user, when masking). */
+    user?: string;
+    /** user_scope / scope claim if present (Reseller / Office Manager / Basic User / …). When masking
+     *  this is the MASKED user's scope, NOT the operator's — so don't infer "a reseller drives this"
+     *  from scope alone; consult `maskChain`. */
+    scope?: string;
+    /** sub claim (typically user@domain — the effective/masked identity). */
+    sub?: string;
+    /** `mask_chain` claim: absent/null ⇒ NOT masking; `"user@domain"` ⇒ the REAL operator behind the
+     *  mask (e.g. the reseller impersonating a domain user). The masking flag + operator identity. */
+    maskChain?: string;
+    /** user_email claim. */
+    email?: string;
+    /** displayName claim. */
+    displayName?: string;
+    /** territory claim. */
+    territory?: string;
+}
+export interface JwtVerdict extends JwtContext {
+    /** Structurally a JWT (3 segments, decodable payload). */
+    validFormat: boolean;
+    /** `exp` claim exists and is in the future. */
+    unexpired: boolean;
+    /** Result of the live server check, when performed. */
+    live: 'valid' | 'invalid' | 'skipped' | 'error';
+    /** Local HS256 signature check: 'valid'/'invalid' when a signingSecret is configured, else
+     *  'unverified' (no local key — the live `/jwt` check is the signature authority). */
+    signature?: 'valid' | 'invalid' | 'unverified';
+    /** Overall gate: safe to proceed. */
+    ok: boolean;
+    expiresAt?: string;
+    expiresInSeconds?: number;
+    reason?: string;
+    statusCode?: number;
+    checkedAt: string;
+    fromCache?: boolean;
+    /** Full decoded payload (local decode). */
+    payload?: Record<string, unknown>;
+}
+/** Strip a leading "Bearer " and whitespace. */
+export declare function normalizeToken(raw: string): string;
+/**
+ * Assert the ns_t audience (and, by default, issuer). `aud` defaults to "ns" — that value is fixed by
+ * the NetSapiens platform, true for every deployment — and is ALWAYS checked.
+ *
+ * `iss` is your Manager Portal host, which is deployment-specific, so it has **no default**: you must
+ * either pass `iss` or explicitly opt out with `validateIss: false`. Omitting both fails closed rather
+ * than silently skipping the check. (Earlier versions defaulted to one specific portal host, which
+ * quietly bound every consumer to someone else's deployment — a bug, not a convenience.)
+ *
+ * `iss` accepts a LIST, mirroring `aud`: several portal hostnames can front the same backend (a
+ * white-labelled host and the vendor's unbranded one), and a token minted by either is equally valid.
+ * Matching is an **exact, case-sensitive** string compare against an explicit list — no wildcards, no
+ * suffix matching. `["manage.example.com", "manage.vendor.example"]` is allowed; `"*.vendor.example"`
+ * is not, and would be treated as a literal hostname that never matches.
+ *
+ * Pure claim comparison — no key needed, no network.
+ */
+export interface ClaimExpectations {
+    /** Required audience — default "ns". Token `aud` must equal (or, if array, include) one of these. */
+    aud?: string | string[];
+    /** Required issuer(s) — YOUR portal host(s), e.g. "manage.example.com" or
+     *  ["manage.example.com", "manage.vendor.example"]. Token `iss` must EXACTLY equal one of them.
+     *  No default: required unless `validateIss: false`. */
+    iss?: string | string[];
+    /** Set false to SKIP issuer validation (e.g. accepting tokens across portal domains). Default true,
+     *  which makes `iss` mandatory. */
+    validateIss?: boolean;
+}
+export declare function assertClaims(payload: Record<string, unknown>, exp?: ClaimExpectations): {
+    ok: boolean;
+    reason?: string;
+};
+/**
+ * Verify an ns_t's HS256 signature locally with the shared secret. ns_t is HS256 (symmetric), signed
+ * by the NetSapiens core — so this needs that HMAC secret (there is no public JWKS). Returns false for
+ * a wrong/absent secret, tampered token, or any header alg other than HS256 (blocks alg:none / alg
+ * confusion). Async (crypto.subtle HMAC). When you don't hold the secret, leave it unset and rely on
+ * the live `/jwt` roundtrip as the (server-side) signature authority.
+ */
+export declare function verifyHs256Signature(token: string, secret: string): Promise<boolean>;
+/** Pull the routing-relevant context out of NS claims (tolerant of naming variants). */
+export declare function extractContext(payload: Record<string, unknown>): JwtContext;
+export interface FormatResult {
+    validFormat: boolean;
+    unexpired: boolean;
+    expiresAt?: string;
+    expiresInSeconds?: number;
+    reason?: string;
+    payload?: Record<string, unknown>;
+    context: JwtContext;
+}
+/**
+ * Local format + expiry check. No network, no signature verification.
+ * `nowMs` is injectable for testing.
+ */
+export declare function validateJwtFormat(token: string, nowMs?: number): FormatResult;
+/** Pluggable verdict cache (back with Workers Cache API / KV / DO / memory). */
+export interface VerdictCache {
+    get(key: string): Promise<JwtVerdict | undefined>;
+    /** ttlSeconds is a hint; the store may evict earlier. */
+    set(key: string, verdict: JwtVerdict, ttlSeconds: number): Promise<void>;
+}
+/** Simple in-isolate cache for dev / a single Worker isolate (not shared across isolates). */
+export declare class MemoryVerdictCache implements VerdictCache {
+    private store;
+    get(key: string): Promise<JwtVerdict | undefined>;
+    set(key: string, verdict: JwtVerdict, ttlSeconds: number): Promise<void>;
+}
+/** SHA-256 hex of the token — cache key that never stores the raw token. */
+export declare function tokenKey(token: string): Promise<string>;
+export interface VerifyOptions {
+    /** NS API host, e.g. "api.example.com". */
+    server: string;
+    /** 'format' = local only (no roundtrip). 'live' = local gate + cached server check. */
+    mode?: 'format' | 'live';
+    cache?: VerdictCache;
+    /** Max seconds to trust a cached live verdict (also capped by the token's exp). Default 60. */
+    maxLiveTtlSeconds?: number;
+    /** How long to cache a negative live verdict. Default 30. */
+    negativeTtlSeconds?: number;
+    /** Abort the live `/jwt` fetch after this many ms (→ live:'error', fail closed). Default 4000. */
+    timeoutMs?: number;
+    /**
+     * Bypass the cache READ and always do the live server check — for writes / sensitive reads. The
+     * cache can serve a stale "valid" verdict for a token that has since been logged out / revoked
+     * (we get no logout event to evict it); force-fresh closes that window. The fresh verdict is still
+     * written back, so it OVERWRITES a stale entry (a now-invalid token's cached "valid" becomes
+     * "invalid"). Use it on the operations where ≤`maxLiveTtlSeconds` of staleness is unacceptable.
+     */
+    forceFresh?: boolean;
+    /** Audience to require — default "ns". Always enforced locally (cheap, before any roundtrip). */
+    expectedAud?: string | string[];
+    /** Issuer(s) to require — YOUR portal host(s), e.g. "manage.example.com", or a list when one backend
+     *  is fronted by several portal hostnames. Exact match, no wildcards. No default: required unless
+     *  `validateIss: false`. Omitting both fails closed. */
+    expectedIss?: string | string[];
+    /** Set false to skip issuer validation (e.g. work across portal domains). Default true, which makes
+     *  `expectedIss` mandatory. */
+    validateIss?: boolean;
+    /** ns_t HS256 shared secret. When set, the signature is verified LOCALLY FIRST (forged/tampered
+     *  tokens are rejected with no roundtrip). When unset, `signature` is 'unverified' and the live
+     *  `/jwt` check is the signature authority. */
+    signingSecret?: string;
+    fetchImpl?: typeof fetch;
+    nowMs?: number;
+}
+/**
+ * Full gate. Order: cheap local format+exp → (live mode) cached live verdict → live GET /jwt.
+ * A malformed/expired token returns immediately and never touches the server.
+ */
+export declare function verify(token: string, opts: VerifyOptions): Promise<JwtVerdict>;
+//# sourceMappingURL=jwt.d.ts.map

package/dist/jwt.js

@@ -0,0 +1,290 @@
+/**
+ * NetSapiens `ns_t` JWT validation — runtime-portable (Cloudflare Worker + Node 18+).
+ *
+ * Ported from n8n-nodes-netsapiens (nodes/NetSapiens/NetSapiens.node.ts), which exposes two
+ * operations we mirror here:
+ *   - Validate JWT Format  → local base64url-decode + `exp` check, NO server contact, NO
+ *     signature verification (low-security; matches the node exactly).
+ *   - Validate JWT (live)  → GET {server}/ns-api/v2/jwt with `Authorization: Bearer <token>`;
+ *     HTTP 401/403 ⇒ rejected. Authoritative, but a server roundtrip.
+ *
+ * Design constraint (David): the live path must NOT overload the NS API. So `verify()` gates on
+ * the cheap local check first, then serves a *cached* live verdict keyed by a hash of the token,
+ * with a TTL capped by the token's own `exp`. A bad or expired token never reaches the server.
+ *
+ * Uses only Web-standard globals (atob, TextDecoder, crypto.subtle, fetch) — no Node Buffer — so
+ * the same file runs in a Worker and in the ns-onboard CLI.
+ */
+// ---------------------------------------------------------------------------
+// Local decode (base64url) — Buffer-free
+// ---------------------------------------------------------------------------
+/** Decode a base64url string to UTF-8 without Node Buffer. */
+function base64urlToUtf8(b64url) {
+    const b64 = b64url.replace(/-/g, '+').replace(/_/g, '/');
+    const padded = b64 + '='.repeat((4 - (b64.length % 4)) % 4);
+    const binary = atob(padded);
+    const bytes = Uint8Array.from(binary, (c) => c.charCodeAt(0));
+    return new TextDecoder().decode(bytes);
+}
+/** Strip a leading "Bearer " and whitespace. */
+export function normalizeToken(raw) {
+    return String(raw ?? '')
+        .replace(/^Bearer\s+/i, '')
+        .trim();
+}
+/** base64url → bytes (no Node Buffer). Explicit `new Uint8Array(len)` so it's ArrayBuffer-backed
+ *  (a plain BufferSource for crypto.subtle), not `Uint8Array<ArrayBufferLike>`. */
+function base64urlToBytes(b64url) {
+    const b64 = b64url.replace(/-/g, '+').replace(/_/g, '/');
+    const padded = b64 + '='.repeat((4 - (b64.length % 4)) % 4);
+    const binary = atob(padded);
+    const out = new Uint8Array(binary.length); // inferred Uint8Array<ArrayBuffer> — a plain BufferSource
+    for (let i = 0; i < binary.length; i++)
+        out[i] = binary.charCodeAt(i);
+    return out;
+}
+export function assertClaims(payload, exp = {}) {
+    const wantAud = exp.aud ?? 'ns';
+    const wanted = Array.isArray(wantAud) ? wantAud : [wantAud];
+    const rawAud = payload.aud;
+    const got = Array.isArray(rawAud) ? rawAud.map(String) : rawAud != null ? [String(rawAud)] : [];
+    if (!got.some((a) => wanted.includes(a))) {
+        return { ok: false, reason: `aud mismatch (want ${wanted.join('|')}, got ${got.join('|') || '∅'})` };
+    }
+    if (exp.validateIss !== false) {
+        // Accept one issuer or several (same backend behind more than one portal hostname). Exact match
+        // only — a wildcard here would let any host under a suffix mint tokens we accept.
+        const rawIss = exp.iss;
+        const wantedIss = (Array.isArray(rawIss) ? rawIss : rawIss != null ? [rawIss] : []).map((i) => String(i).trim()).filter(Boolean);
+        // No default: an issuer default would be someone's specific portal. Fail closed and say how to fix.
+        if (!wantedIss.length) {
+            return { ok: false, reason: 'iss expectation missing — pass `iss` (your portal host, e.g. "manage.example.com", or a list of them) or set `validateIss: false` to opt out' };
+        }
+        const gotIss = String(payload.iss ?? '');
+        if (!wantedIss.includes(gotIss)) {
+            return { ok: false, reason: `iss mismatch (want ${wantedIss.join('|')}, got ${gotIss || '∅'})` };
+        }
+    }
+    return { ok: true };
+}
+/**
+ * Verify an ns_t's HS256 signature locally with the shared secret. ns_t is HS256 (symmetric), signed
+ * by the NetSapiens core — so this needs that HMAC secret (there is no public JWKS). Returns false for
+ * a wrong/absent secret, tampered token, or any header alg other than HS256 (blocks alg:none / alg
+ * confusion). Async (crypto.subtle HMAC). When you don't hold the secret, leave it unset and rely on
+ * the live `/jwt` roundtrip as the (server-side) signature authority.
+ */
+export async function verifyHs256Signature(token, secret) {
+    const parts = normalizeToken(token).split('.');
+    if (parts.length !== 3 || !secret)
+        return false;
+    try {
+        const header = JSON.parse(base64urlToUtf8(parts[0]));
+        if (header.alg !== 'HS256')
+            return false;
+        const key = await crypto.subtle.importKey('raw', new TextEncoder().encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['verify']);
+        return await crypto.subtle.verify('HMAC', key, base64urlToBytes(parts[2]), new TextEncoder().encode(`${parts[0]}.${parts[1]}`));
+    }
+    catch {
+        return false;
+    }
+}
+/** exp/nbf claims may be number or numeric string (matches the node's toEpochSeconds). */
+function toEpochSeconds(value) {
+    if (typeof value === 'number' && Number.isFinite(value))
+        return Math.trunc(value);
+    if (typeof value === 'string') {
+        const n = Number.parseInt(value.trim(), 10);
+        if (Number.isFinite(n))
+            return n;
+    }
+    return undefined;
+}
+/** Pull the routing-relevant context out of NS claims (tolerant of naming variants). */
+export function extractContext(payload) {
+    const pick = (...keys) => {
+        for (const k of keys) {
+            const v = payload[k];
+            if (typeof v === 'string' && v.trim())
+                return v.trim();
+        }
+        return undefined;
+    };
+    const sub = pick('sub', 'username', 'user_name');
+    let domain = pick('domain', 'nsDomain', 'territory_domain');
+    let user = pick('user', 'uid', 'extension');
+    // sub is often user@domain — derive the halves if the explicit claims are absent.
+    if (sub && sub.includes('@')) {
+        const [u, d] = sub.split('@');
+        user = user ?? u;
+        domain = domain ?? d;
+    }
+    return {
+        domain,
+        user,
+        scope: pick('user_scope', 'scope', 'role'),
+        sub,
+        maskChain: pick('mask_chain', 'maskChain'),
+        email: pick('user_email', 'email'),
+        displayName: pick('displayName', 'display_name', 'name'),
+        territory: pick('territory'),
+    };
+}
+/**
+ * Local format + expiry check. No network, no signature verification.
+ * `nowMs` is injectable for testing.
+ */
+export function validateJwtFormat(token, nowMs = Date.now()) {
+    const t = normalizeToken(token);
+    if (!t)
+        return { validFormat: false, unexpired: false, reason: 'Empty token', context: {} };
+    const parts = t.split('.');
+    if (parts.length !== 3) {
+        return { validFormat: false, unexpired: false, reason: `Expected 3 JWT segments, got ${parts.length}`, context: {} };
+    }
+    let payload;
+    try {
+        payload = JSON.parse(base64urlToUtf8(parts[1]));
+    }
+    catch {
+        return { validFormat: false, unexpired: false, reason: 'Failed to decode JWT payload (invalid base64url or JSON)', context: {} };
+    }
+    const expSeconds = toEpochSeconds(payload.exp);
+    const nowSeconds = Math.trunc(nowMs / 1000);
+    const context = extractContext(payload);
+    if (expSeconds === undefined) {
+        return { validFormat: true, unexpired: false, reason: 'Missing or invalid exp claim', payload, context };
+    }
+    const expiresInSeconds = expSeconds - nowSeconds;
+    return {
+        validFormat: true,
+        unexpired: expiresInSeconds > 0,
+        expiresAt: new Date(expSeconds * 1000).toISOString(),
+        expiresInSeconds,
+        ...(expiresInSeconds <= 0 ? { reason: 'Token exp is in the past' } : {}),
+        payload,
+        context,
+    };
+}
+/** Simple in-isolate cache for dev / a single Worker isolate (not shared across isolates). */
+export class MemoryVerdictCache {
+    store = new Map();
+    async get(key) {
+        const hit = this.store.get(key);
+        if (!hit)
+            return undefined;
+        if (hit.expiresAtMs <= Date.now()) {
+            this.store.delete(key);
+            return undefined;
+        }
+        return hit.verdict;
+    }
+    async set(key, verdict, ttlSeconds) {
+        this.store.set(key, { verdict, expiresAtMs: Date.now() + ttlSeconds * 1000 });
+    }
+}
+/** SHA-256 hex of the token — cache key that never stores the raw token. */
+export async function tokenKey(token) {
+    const data = new TextEncoder().encode(normalizeToken(token));
+    const digest = await crypto.subtle.digest('SHA-256', data);
+    return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, '0')).join('');
+}
+/**
+ * Full gate. Order: cheap local format+exp → (live mode) cached live verdict → live GET /jwt.
+ * A malformed/expired token returns immediately and never touches the server.
+ */
+export async function verify(token, opts) {
+    const nowMs = opts.nowMs ?? Date.now();
+    const checkedAt = new Date(nowMs).toISOString();
+    const fmt = validateJwtFormat(token, nowMs);
+    const base = {
+        validFormat: fmt.validFormat,
+        unexpired: fmt.unexpired,
+        live: 'skipped',
+        ok: false,
+        ...fmt.context,
+        ...(fmt.expiresAt ? { expiresAt: fmt.expiresAt } : {}),
+        ...(fmt.expiresInSeconds !== undefined ? { expiresInSeconds: fmt.expiresInSeconds } : {}),
+        ...(fmt.reason ? { reason: fmt.reason } : {}),
+        payload: fmt.payload,
+        checkedAt,
+    };
+    // Local gate: bad format or expired ⇒ reject without a roundtrip.
+    if (!fmt.validFormat || !fmt.unexpired)
+        return base;
+    // Claim assertions (always, no key needed): aud must be "ns"; iss must match unless opted out.
+    const claims = assertClaims(fmt.payload ?? {}, { aud: opts.expectedAud, iss: opts.expectedIss, validateIss: opts.validateIss });
+    if (!claims.ok)
+        return { ...base, ok: false, reason: claims.reason };
+    // Signature: when a shared secret is configured, verify HS256 LOCALLY FIRST (reject forgeries with
+    // no roundtrip). Without a secret we can't verify locally (no public JWKS) → 'unverified', and the
+    // live check below is the authority.
+    let signature = 'unverified';
+    if (opts.signingSecret) {
+        signature = (await verifyHs256Signature(token, opts.signingSecret)) ? 'valid' : 'invalid';
+        if (signature === 'invalid')
+            return { ...base, signature, ok: false, reason: 'Signature verification failed' };
+    }
+    const withSig = { ...base, signature };
+    if ((opts.mode ?? 'live') === 'format') {
+        // Local-only mode. `ok` means AUTHENTICATED, so it requires a locally-verified signature
+        // (`signingSecret`). ns_t has no public JWKS, so without a secret the signature is 'unverified' ⇒
+        // ok:false (structurally + aud/iss valid, but NOT attested). Use mode:'live' — the server-side
+        // signature authority — to actually authenticate an ns_t.
+        return signature === 'valid'
+            ? { ...withSig, live: 'skipped', ok: true }
+            : { ...withSig, live: 'skipped', ok: false, reason: 'Signature not verified (format mode without signingSecret)' };
+    }
+    // Live mode — consult cache first (unless force-fresh: writes/sensitive reads always re-check).
+    const key = await tokenKey(token);
+    if (opts.cache && !opts.forceFresh) {
+        const cached = await opts.cache.get(key);
+        if (cached)
+            return { ...cached, fromCache: true, checkedAt };
+    }
+    // Cache miss → the one server roundtrip. This is the SIGNATURE/revocation authority, so make it
+    // brittle-safe: a timeout (a hung NS core can't tie up the request), NO redirect following
+    // (`manual`), and ONLY a literal 200 counts as valid — any 3xx/5xx/other fails closed, uncached.
+    const doFetch = opts.fetchImpl ?? fetch;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? 4000);
+    let verdict;
+    try {
+        const res = await doFetch(`https://${opts.server}/ns-api/v2/jwt`, {
+            method: 'GET',
+            headers: { Authorization: `Bearer ${normalizeToken(token)}` },
+            redirect: 'manual',
+            signal: controller.signal,
+        });
+        if (res.status === 401 || res.status === 403) {
+            verdict = { ...withSig, live: 'invalid', ok: false, statusCode: res.status, reason: `JWT rejected by API (${res.status})` };
+        }
+        else if (res.status === 200) {
+            verdict = { ...withSig, live: 'valid', ok: true, statusCode: res.status };
+        }
+        else {
+            // Anything else (3xx redirect, 5xx, opaque, 0) — don't trust it. Fail closed, don't cache.
+            verdict = { ...withSig, live: 'error', ok: false, statusCode: res.status, reason: `Unexpected /jwt status ${res.status}` };
+        }
+    }
+    catch (err) {
+        verdict = { ...withSig, live: 'error', ok: false, reason: `JWT check failed: ${err.message}` };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    // Cache valid/invalid verdicts (never 'error'). TTL capped by the token's own exp.
+    if (opts.cache && (verdict.live === 'valid' || verdict.live === 'invalid')) {
+        const cap = verdict.live === 'valid' ? (opts.maxLiveTtlSeconds ?? 60) : (opts.negativeTtlSeconds ?? 30);
+        const untilExp = fmt.expiresInSeconds ?? 0;
+        const ttl = verdict.live === 'valid' ? Math.max(0, Math.min(cap, untilExp)) : cap;
+        // Trim the full decoded claims blob before persisting: nothing downstream reads verdict.payload
+        // (toPrincipal uses the typed context fields), and it's the largest PII surface to leave sitting
+        // in the per-colo cache. Keep it on the returned verdict (this request only), drop it from storage.
+        const { payload: _payload, ...cacheable } = verdict;
+        if (ttl > 0)
+            await opts.cache.set(key, cacheable, ttl);
+    }
+    return verdict;
+}
+//# sourceMappingURL=jwt.js.map

package/dist/mermaid.d.ts

@@ -0,0 +1,14 @@
+/**
+ * FlowGraph -> Mermaid flowchart. Node shape + CSS class encode the node kind so a
+ * reader can tell a queue from a mailbox from an external forward at a glance.
+ */
+import type { FlowGraph } from './model.js';
+/** Diagram theme. `dark` is the original palette (Cloudflare Worker / live-chart use);
+ *  `light` matches ns-onboard's light review report. */
+export type FlowTheme = 'light' | 'dark';
+export interface MermaidOptions {
+    /** Emit a themed diagram. OMIT for byte-identical legacy output (the Worker relies on this). */
+    theme?: FlowTheme;
+}
+export declare function toMermaid(g: FlowGraph, opts?: MermaidOptions): string;
+//# sourceMappingURL=mermaid.d.ts.map

package/dist/model.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Normalized call-flow graph — renderer-agnostic. The resolver emits this from a
+ * NetSapiens domain snapshot; the Mermaid emitter (and, later, any other renderer)
+ * consumes it. This is the "real IP" contract from the handoff: a normalized graph JSON.
+ *
+ * Runtime-portable by design: no Node-only imports here or in resolver.ts, so the same
+ * code can run in the ns-onboard CLI and in a Cloudflare Worker.
+ */
+export type NodeKind = 'did' | 'timeframe' | 'user' | 'devices' | 'queue' | 'agents' | 'attendant' | 'prompt' | 'voicemail' | 'external' | 'trunk' | 'hangup' | 'unknown';
+export type EdgeKind = 'route' | 'time' | 'always' | 'noanswer' | 'busy' | 'unreg' | 'dnd' | 'dispatch' | 'overflow' | 'menu' | 'ref';
+export interface FlowNode {
+    id: string;
+    kind: NodeKind;
+    /** Primary label line. */
+    label: string;
+    /** Optional secondary line (e.g. dispatch type, schedule). */
+    sub?: string;
+    /** Optional additional lines rendered one-per-line under the label (e.g. a bulleted agent list). */
+    lines?: string[];
+    /** Full text for a hover tooltip (e.g. a long greeting shown truncated in the label). Viewer-only. */
+    title?: string;
+}
+export interface FlowEdge {
+    from: string;
+    to: string;
+    kind: EdgeKind;
+    /** Edge caption (e.g. "open hrs", "no answer 30s"). */
+    label?: string;
+}
+export interface FlowGraph {
+    /** Entity the flow was resolved for. */
+    entity: {
+        kind: string;
+        ref: string;
+        label: string;
+    };
+    domain: string;
+    rootId: string;
+    nodes: FlowNode[];
+    edges: FlowEdge[];
+    /** Human-facing caveats surfaced during resolution (gaps, unmapped params, cycles). */
+    notes: string[];
+}
+export type Rec = Record<string, any>;
+export interface Snapshot {
+    meta: Rec;
+    domain?: Rec;
+    timeframes?: Rec[];
+    users?: Rec[];
+    devicesByUser?: Record<string, Rec[]>;
+    callqueues?: Rec[];
+    agentsByQueue?: Record<string, Rec[]>;
+    phonenumbers?: Rec[];
+    autoattendants?: Rec[];
+    dialrulesByPlan?: Record<string, Rec[]>;
+    answerrulesByUser?: Record<string, Rec[]>;
+    /**
+     * Optional per-attendant menu detail, keyed by AA extension — the response of
+     * GET /domains/{d}/users/{ext}/autoattendants/{prompt} (an `auto-attendant` tier +
+     * top-level greeting `audio` + `intro-greetings[]` + `time-frame`). When present, the
+     * resolver renders the real keypress menu; when absent, it emits a "not captured" note.
+     *
+     * Two shapes are accepted:
+     *  - `attendantDetails[ext]`        — a single detail (current live fetch; SV builds AAs on `*`).
+     *  - `attendantDetailsByUser[ext]`  — an ARRAY of details (ns-onboard enriched backup: an AA may
+     *    have multiple prompts/timeframes). The resolver picks the `*`/Default one as primary and
+     *    flags the rest as a deviation (see the AA backup enrichment spec, Addendum 2026-07-11).
+     */
+    attendantDetails?: Record<string, Rec>;
+    attendantDetailsByUser?: Record<string, Rec[]>;
+    /**
+     * Per-AA dialplan dialrules, keyed by AA extension — the AUTHORITATIVE menu + default routing that
+     * the /autoattendants detail omits (no-key/star/option). From GET /domains/{d}/dialplans/{domain}_{ext}/dialrules.
+     * The resolver reads `Prompt_<startingPrompt-id>.<suffix>` rules: .Default (no-key/timeout), .* (unassigned),
+     * .<digit> (press N), .Case_[...] (dial-by-ext). See CLAUDE.md → NetSapiens API notes.
+     */
+    attendantDialrulesByExt?: Record<string, Rec[]>;
+    [k: string]: any;
+}
+//# sourceMappingURL=model.d.ts.map

package/dist/model.js

@@ -0,0 +1,10 @@
+/**
+ * Normalized call-flow graph — renderer-agnostic. The resolver emits this from a
+ * NetSapiens domain snapshot; the Mermaid emitter (and, later, any other renderer)
+ * consumes it. This is the "real IP" contract from the handoff: a normalized graph JSON.
+ *
+ * Runtime-portable by design: no Node-only imports here or in resolver.ts, so the same
+ * code can run in the ns-onboard CLI and in a Cloudflare Worker.
+ */
+export {};
+//# sourceMappingURL=model.js.map

package/dist/nsClient.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Portable NetSapiens API read client — the seed of the eventual "NS API for Worker/Node"
+ * library (see CLAUDE.md → North star). Ported from NetSapiens-Onboarding-Backup (`src/api/client.ts`
+ * NsClient + `src/backup/snapshot.ts` backupDomain), trimmed to the READ-ONLY routing subset the
+ * resolver needs, and kept Node-free (fetch/URL only) so it runs in a Cloudflare Worker unchanged.
+ *
+ * `fetchDomainSnapshot()` assembles the same `Snapshot` shape the resolver already consumes, so a
+ * live domain flows end-to-end: domain + token → Snapshot → resolveFlow → FlowGraph.
+ *
+ * This tool never writes to NetSapiens — only GET is exposed.
+ */
+import type { Rec, Snapshot } from './model.js';
+export declare class NsApiError extends Error {
+    readonly status: number;
+    readonly path: string;
+    readonly body: unknown;
+    constructor(message: string, status: number, path: string, body: unknown);
+}
+export interface NsClientConfig {
+    /** API host, e.g. "api.example.com". Base URL becomes https://{server}/ns-api/v2. */
+    server: string;
+    /** Bearer token (the portal user's `ns_t`, or an API key). */
+    token: string;
+    /** Injectable for tests / non-global fetch. */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * NS API v2 client — READ-ONLY BY DESIGN (the central gate for this whole tool).
+ *
+ * The ONLY method is `get()`, which hardcodes `method: 'GET'`. There is deliberately no
+ * post/put/delete/patch — the viewer must never mutate NetSapiens. Keep it that way: do not add a
+ * mutating method here. Any write capability must be a separate, explicitly-reviewed client, not a
+ * quiet addition to this one. This is the single choke point every NS call in the Worker flows through.
+ */
+export declare class NsClient {
+    private readonly baseUrl;
+    private readonly token;
+    private readonly fetchImpl;
+    constructor(cfg: NsClientConfig);
+    get<T = unknown>(path: string, query?: Record<string, string | number>): Promise<T>;
+}
+/** Normalize a v2 response to an array of records (endpoints return an array or a bare object). */
+export declare function asArray(res: unknown): Rec[];
+/** List domains the token can read (for the internal viewer's domain browser). `locked` is set only
+ *  for domains flagged `is-domain-locked: yes` (config-locked in NetSapiens). */
+export declare function listDomains(client: NsClient): Promise<{
+    domain: string;
+    description?: string;
+    locked?: boolean;
+}[]>;
+export interface FetchSnapshotOptions {
+    /** Fetch each AA's keypress menu (GET .../autoattendants/{prompt}). Default true. */
+    includeAttendantMenus?: boolean;
+    /** Also fetch the default-plan dialrules (rarely needed — classifyParam handles aliases). Default false. */
+    includeDialrules?: boolean;
+    /** Max concurrent per-item requests. Default 5. Mind Workers' subrequest cap on huge domains. */
+    concurrency?: number;
+    /**
+     * Shallow: fetch only the top-level lists (domain, timeframes, users, callqueues, phonenumbers,
+     * autoattendants) and skip the per-user/queue/AA fan-out. Enough for `listEntities()` (the entity
+     * picker) at a fraction of the requests. Default false.
+     */
+    shallow?: boolean;
+    /**
+     * With `shallow`, also fetch answer rules for the DIDs' destination users (a handful of extra
+     * reads) so `listEntities()` can flag time-of-day (TOD) DIDs. Default false.
+     */
+    includeDidDestRules?: boolean;
+}
+/**
+ * Read a live domain into the `Snapshot` shape the resolver consumes. Routing subset only:
+ * domain, timeframes, users, callqueues, phonenumbers, autoattendants, per-user answerrules,
+ * per-queue agents, and (by default) per-AA menu detail.
+ *
+ * A per-item read that fails is treated as "absent" (empty) so one missing child never aborts the
+ * whole flow — the resolver tolerates gaps. A failing top-level read (e.g. 401) DOES throw.
+ */
+export declare function fetchDomainSnapshot(client: NsClient, domain: string, opts?: FetchSnapshotOptions): Promise<Snapshot>;
+//# sourceMappingURL=nsClient.d.ts.map