@dszp/netsapiens-lib 0.1.2 → 0.1.3

package/dist/index.d.ts

@@ -16,6 +16,7 @@ export { THEMES, DEFAULT_LIGHT_THEME, DEFAULT_DARK_THEME, NODE_LIGHT, NODE_DARK,
 export { renderGalleryHtml, renderFlowCards, renderFlowCard, mermaidBootstrap, flowAnchorId, type GalleryOptions, type CardOptions, } from './html.js';
 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 { 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

@@ -15,6 +15,7 @@ export { THEMES, DEFAULT_LIGHT_THEME, DEFAULT_DARK_THEME, NODE_LIGHT, NODE_DARK,
 export { renderGalleryHtml, renderFlowCards, renderFlowCard, mermaidBootstrap, flowAnchorId, } from './html.js';
 export { resolveSvgSize, rasterizerScript } from './raster.js';
 export { NsClient, NsApiError, assertBareServer, fetchDomainSnapshot, listDomains, asArray } from './nsClient.js';
+export { NsWriteClient } from './nsWriteClient.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/nsClient.d.ts

@@ -14,7 +14,11 @@ export declare class NsApiError extends Error {
     readonly status: number;
     readonly path: string;
     readonly body: unknown;
-    constructor(message: string, status: number, path: string, body: unknown);
+    /** HTTP method — set by the write client; optional so read-client call sites stay unchanged. */
+    readonly method?: string | undefined;
+    constructor(message: string, status: number, path: string, body: unknown, 
+    /** HTTP method — set by the write client; optional so read-client call sites stay unchanged. */
+    method?: string | undefined);
 }
 export interface NsClientConfig {
     /** API host, e.g. "api.example.com". Base URL becomes https://{server}/ns-api/v2. */

package/dist/nsClient.js

@@ -13,11 +13,15 @@ export class NsApiError extends Error {
     status;
     path;
     body;
-    constructor(message, status, path, body) {
+    method;
+    constructor(message, status, path, body, 
+    /** HTTP method — set by the write client; optional so read-client call sites stay unchanged. */
+    method) {
         super(message);
         this.status = status;
         this.path = path;
         this.body = body;
+        this.method = method;
         this.name = 'NsApiError';
     }
 }

package/dist/nsWriteClient.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Portable NetSapiens API v2 WRITE client — the separate, explicitly-imported write surface the read-only
+ * `NsClient` deliberately does not have (a consumer holds `NsClient` precisely to know it cannot write).
+ * This realizes the lib's planned split: read and write are two classes; only this one mutates. Node-free
+ * (fetch/URL/crypto only), so it runs unchanged in a Cloudflare Worker.
+ *
+ * Starts with the device methods the portal's Ringotel activation needs (create/get/delete), over a
+ * generic post/put/delete core, and is meant to GROW into the full NS write surface (users, DIDs, …) —
+ * porting the endpoint/body shapes from the onboarding tool's resource defs as they're needed.
+ *
+ * Like the onboarding client, POST/PUT inject `synchronous: 'yes'` so a create returns 200 + the created
+ * resource inline (with server-generated fields — e.g. a device's `device-sip-registration-password`)
+ * instead of a 202 with replication lag. Shares the read client's SSRF guard and `NsApiError`.
+ */
+import type { Rec } from './model.js';
+export interface NsWriteClientConfig {
+    /** API host, e.g. "api.example.com". Base URL becomes https://{server}/ns-api/v2. */
+    server: string;
+    /** Bearer token (an API key with write scope). */
+    token: string;
+    /** Injectable for tests / non-global fetch. */
+    fetchImpl?: typeof fetch;
+}
+export declare class NsWriteClient {
+    #private;
+    constructor(cfg: NsWriteClientConfig);
+    get<T = unknown>(path: string, query?: Record<string, string | number>): Promise<T>;
+    /** POST with `synchronous:'yes'` injected → 200 + created resource inline. */
+    post<T = unknown>(path: string, body: Rec): Promise<T>;
+    /** PUT with `synchronous:'yes'` injected. */
+    put<T = unknown>(path: string, body: Rec): Promise<T>;
+    delete<T = unknown>(path: string): Promise<T>;
+    /** List a user's devices (normalized to an array). */
+    getDevices(domain: string, user: string): Promise<Rec[]>;
+    /** Read one device (e.g. to fetch its `device-sip-registration-password`). */
+    getDevice(domain: string, user: string, device: string): Promise<Rec>;
+    /**
+     * Create a device (softphone when named `<ext><suffix>`, e.g. `100r`). NS auto-generates the SIP
+     * password when unset; with `synchronous:'yes'` it comes back inline in the response. `extra` allows
+     * optional fields (e.g. an emergency caller-id).
+     */
+    createDevice(domain: string, user: string, device: string, extra?: Rec): Promise<Rec>;
+    /** Delete a device. */
+    deleteDevice(domain: string, user: string, device: string): Promise<Rec>;
+}

package/dist/nsWriteClient.js

@@ -0,0 +1,81 @@
+import { NsApiError, assertBareServer, asArray } from './nsClient.js';
+const enc = encodeURIComponent;
+export class NsWriteClient {
+    #baseUrl;
+    #token;
+    #fetchImpl;
+    constructor(cfg) {
+        this.#baseUrl = `https://${assertBareServer(cfg.server)}/ns-api/v2`;
+        this.#token = cfg.token;
+        this.#fetchImpl = cfg.fetchImpl ?? fetch;
+    }
+    // ── generic verbs (the growth surface) ──────────────────────────────────────
+    get(path, query) {
+        return this.#request('GET', path, undefined, query);
+    }
+    /** POST with `synchronous:'yes'` injected → 200 + created resource inline. */
+    post(path, body) {
+        return this.#request('POST', path, { synchronous: 'yes', ...body });
+    }
+    /** PUT with `synchronous:'yes'` injected. */
+    put(path, body) {
+        return this.#request('PUT', path, { synchronous: 'yes', ...body });
+    }
+    delete(path) {
+        return this.#request('DELETE', path);
+    }
+    // ── typed device helpers ────────────────────────────────────────────────────
+    /** List a user's devices (normalized to an array). */
+    getDevices(domain, user) {
+        return this.get(`/domains/${enc(domain)}/users/${enc(user)}/devices`).then(asArray);
+    }
+    /** Read one device (e.g. to fetch its `device-sip-registration-password`). */
+    getDevice(domain, user, device) {
+        return this.get(`/domains/${enc(domain)}/users/${enc(user)}/devices/${enc(device)}`);
+    }
+    /**
+     * Create a device (softphone when named `<ext><suffix>`, e.g. `100r`). NS auto-generates the SIP
+     * password when unset; with `synchronous:'yes'` it comes back inline in the response. `extra` allows
+     * optional fields (e.g. an emergency caller-id).
+     */
+    createDevice(domain, user, device, extra = {}) {
+        return this.post(`/domains/${enc(domain)}/users/${enc(user)}/devices`, { device, ...extra });
+    }
+    /** Delete a device. */
+    deleteDevice(domain, user, device) {
+        return this.delete(`/domains/${enc(domain)}/users/${enc(user)}/devices/${enc(device)}`);
+    }
+    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)' : '';
+            throw new NsApiError(`${method} ${path} → ${res.status}${hint}: ${detail}`, res.status, path, parsed, method);
+        }
+        return parsed;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dszp/netsapiens-lib",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "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",
@@ -50,9 +50,10 @@
     "//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",
+    "test": "pnpm run test:jwt && pnpm run test:principal && pnpm run test:resolver && pnpm run test:raster && pnpm run test:nswrite",
     "test:jwt": "tsx src/jwt.selftest.ts",
     "test:ns": "tsx src/nsClient.selftest.ts",
+    "test:nswrite": "tsx src/nsWriteClient.selftest.ts",
     "test:principal": "tsx src/principal.selftest.ts",
     "test:resolver": "tsx src/resolver.selftest.ts",
     "test:raster": "tsx src/raster.selftest.ts"