wldx-admin-cli 1.2.1 → 1.3.0

package/src/cli.mjs

@@ -6,6 +6,7 @@ import {AuthError, UsageError} from 'wldx-core/errors';
 import {clean, paint} from 'wldx-core/format';
 import {program, setProgram} from 'wldx-core/program';
 import {COMMANDS, GLOBAL_OPTIONS, GROUPS} from './commands/index.mjs';
+import {SERVICES} from './cloud/env.mjs';
 import {loginPbxOf, savedPbxs} from './pbx.mjs';
 import {VERSION} from './version.mjs';
 
@@ -57,11 +58,13 @@ export const SPEC = {
       '  --pbx PBX           the PBX: name.wildixin.com, name, an IP, or the serial of a known PBX; else the',
       '                      default one (wx-admin pbx use), else the PBX of the x-bees login',
       "  --all-pbx           run a command that reads on every PBX: saved access, then the x-bees login's",
+      "  --env ENV           the environment of the cloud services: prod, stable or stage (default: the PBX's)",
     ],
     exitCodes: 'Exit codes: 0 done, 1 error, 2 not logged in or the access was refused, 64 wrong usage.',
   },
   // The PBX with saved access, by host and by serial.
   completers: {
+    cloudServices: () => Object.entries(SERVICES).map(([name, s]) => [name, s.label]),
     pbxs: (env) => savedPbxs(env).flatMap((p) => [[p.host, p.auth], ...(p.serial ? [[p.serial, p.host]] : [])]),
   },
   around: (cmd, ctx, io, run) => (ctx.allPbx ? runOnAllPbx(cmd, ctx, io) : run()),

package/src/cloud/client.mjs

@@ -0,0 +1,75 @@
+// Requests to a Wildix cloud service with the CPA token of the PBX: only to the base URL of that service (a path,
+// never a URL, is accepted), redirects refused, the token cut out of every error. raw() is for presigned links
+// (uploads, downloads): it never sends the token.
+import {AuthError, UsageError} from 'wldx-core/errors';
+import {query} from 'wldx-core/http';
+import {userAgent} from 'wldx-core/program';
+import {baseOf, envOf, SERVICES} from './env.mjs';
+import {cloudToken} from './token.mjs';
+
+const PATH = /^\/(?!\/)[^\s#\\]*$/;
+
+export async function cloudClient(ctx, service) {
+  if (!Object.hasOwn(SERVICES, service)) baseOf(service, 'prod'); // the error of an unknown service
+  if (ctx.cloudEnv) baseOf(service, ctx.cloudEnv); // an environment the service lacks: refused before any request
+  const first = await cloudToken(ctx);
+  const env = ctx.cloudEnv ?? envOf(first.portal);
+  const base = baseOf(service, env);
+  const fetchImpl = ctx.fetch ?? globalThis.fetch;
+  const seen = new Set([first.token]); // every token this client used: none may show in an error
+  const scrub = (s) => [...seen].reduce((out, token) => out.replaceAll(token, '<token>'), String(s ?? ''));
+
+  async function call(method, path, {query: params, json} = {}) {
+    if (typeof path !== 'string' || !PATH.test(path) || path.split(/[/?]/).includes('..'))
+      throw new UsageError(`Not a path of ${service}: ${path}`);
+    // The token of each request: the one in memory, or a new one from the PBX when it is near its end (a long watch).
+    const t = await cloudToken(ctx);
+    seen.add(t.token);
+    const url = `${base}${path}${params ? query(params) : ''}`;
+    const headers = {'user-agent': userAgent(), accept: 'application/json', authorization: `Bearer ${t.token}`};
+    if (json !== undefined) headers['content-type'] = 'application/json';
+    let res;
+    try {
+      res = await fetchImpl(url, {
+        method,
+        headers,
+        body: json === undefined ? undefined : JSON.stringify(json),
+        redirect: 'error',
+        signal: ctx.signal,
+      });
+    } catch (e) {
+      throw new Error(`${service} (${base}) is not reachable: ${scrub(e.message)}`);
+    }
+    const text = scrub(await res.text());
+    if (!res.ok) {
+      let reason = text.slice(0, 300);
+      try {
+        const j = JSON.parse(text);
+        reason = j.message ?? j.reason ?? j.error ?? reason;
+      } catch {
+        // not JSON: the text as it is
+      }
+      if (res.status === 401 || res.status === 403)
+        throw new AuthError(
+          `the cloud refused the token of ${t.company} for ${service} (${res.status}): ${scrub(reason)}`,
+        );
+      const err = new Error(`${service} answered ${res.status}: ${scrub(reason)}`);
+      err.status = res.status;
+      err.exitCode = 1;
+      throw err;
+    }
+    if (!text) return null;
+    try {
+      return JSON.parse(text);
+    } catch {
+      return text;
+    }
+  }
+
+  async function raw(method, url, {headers = {}, body} = {}) {
+    if (!/^https:\/\//.test(String(url))) throw new UsageError('A presigned link must be https');
+    return fetchImpl(url, {method, headers, body, redirect: 'error', signal: ctx.signal});
+  }
+
+  return {env, base, company: first.company, companyName: first.companyName, pbx: first.pbx, call, raw};
+}

package/src/cloud/env.mjs

@@ -0,0 +1,60 @@
+// The Wildix cloud services wx-admin reaches with the CPA token of a PBX, and their addresses per environment (the
+// `servers` of their OpenAPI, 2026-11-07, corrected where the service does not exist: the knowledge base has no
+// stable, although its spec names one).
+import {UsageError} from 'wldx-core/errors';
+
+export const ENVIRONMENTS = ['prod', 'stable', 'stage'];
+
+export const SERVICES = {
+  kb: {
+    label: 'the knowledge base',
+    bases: {prod: 'https://kb.wim.wildix.com', stage: 'https://kb.wim-stage.wildix.com'},
+  },
+  voicebots: {
+    label: 'voicebots',
+    bases: {
+      prod: 'https://wim.wildix.com',
+      stable: 'https://wim-stable.wildix.com',
+      stage: 'https://wim-stage.wildix.com',
+    },
+  },
+  tools: {
+    label: 'WIM tools',
+    bases: {
+      prod: 'https://tools.wim.wildix.com',
+      stable: 'https://tools.wim-stable.wildix.com',
+      stage: 'https://tools.wim-stage.wildix.com',
+    },
+  },
+  wilma: {
+    label: 'Wilma',
+    bases: {
+      prod: 'https://api.wilma.wildix.com',
+      stable: 'https://api-stable.wilma.wildix.com',
+      stage: 'https://api-stage.wilma.wildix.com',
+    },
+  },
+};
+
+// The environment of the PBX, from the address of its WIM console (the `portal` of the CPA route).
+export function envOf(portal) {
+  const host = (() => {
+    try {
+      return new URL(String(portal)).hostname;
+    } catch {
+      return '';
+    }
+  })();
+  if (host.includes('-stage.')) return 'stage';
+  if (host.includes('-stable.')) return 'stable';
+  return 'prod';
+}
+
+export function baseOf(service, env) {
+  if (!Object.hasOwn(SERVICES, service))
+    throw new UsageError(`Unknown cloud service: ${service}. Known: ${Object.keys(SERVICES).join(', ')}`);
+  const s = SERVICES[service];
+  if (!Object.hasOwn(s.bases, env))
+    throw new UsageError(`${s.label} has no ${env} environment: ${Object.keys(s.bases).join(' or ')}`);
+  return s.bases[env];
+}

package/src/cloud/mask.mjs

@@ -0,0 +1,39 @@
+// Secrets in the answers of the cloud services, masked: fields whose name says secret (keys, tokens, passwords,
+// credentials), the value of a header whose name does (headers as [{name, value}]), every custom header, every
+// sandbox environment value, a key or token in the query of a URI; never the cursors and page tokens of paged lists.
+// The shapes come from the specs of WIM voicebots, WIM tools and Wilma (docs/research of 2026-11-07).
+export const MASK = '********';
+
+const SECRET = /secret|password|passwd|^register$|^key$|api_?key|token|credentials|private_?key|authorization|cookie/i;
+const PAGING = /^(?:(?:next|prev|previous)(?:page)?|page)(?:token|cursor)$|^cursor$/i;
+const SECRET_HEADER = /authorization|api-?key|token|secret|cookie|auth/i;
+const URI_SECRET = /([?&](?:api_?key|access_?token|token|key|secret)=)[^&#\s]+/gi;
+
+const isSecretKey = (k) => SECRET.test(k) && !PAGING.test(k);
+const hide = (v) => (v === null || v === undefined || v === '' ? v : MASK);
+
+export function maskCloud(value, key = '') {
+  if (Array.isArray(value)) {
+    if (/^headers$/i.test(key))
+      return value.map((h) =>
+        h && typeof h === 'object' && SECRET_HEADER.test(String(h.name ?? h.key ?? ''))
+          ? {...maskCloud(h), value: hide(h.value)}
+          : maskCloud(h),
+      );
+    if (/^env$/i.test(key))
+      return value.map((e) => (e && typeof e === 'object' ? {...maskCloud(e), value: hide(e.value)} : e));
+    return value.map((v) => maskCloud(v));
+  }
+  if (value && typeof value === 'object') {
+    if (/^customHeaders$/i.test(key)) return Object.fromEntries(Object.keys(value).map((k) => [k, hide(value[k])]));
+    return Object.fromEntries(
+      Object.entries(value).map(([k, v]) => {
+        if (isSecretKey(k) && v && typeof v === 'object') return [k, MASK]; // a whole credential (a service account)
+        if (isSecretKey(k) && typeof v === 'string') return [k, hide(v)];
+        return [k, maskCloud(v, k)];
+      }),
+    );
+  }
+  if (typeof value === 'string' && /[?&]/.test(value)) return value.replace(URI_SECRET, `$1${MASK}`);
+  return value;
+}

package/src/cloud/specs.mjs

@@ -0,0 +1,26 @@
+// The operations of the cloud services that accept the CPA token, from the OpenAPI bundled in specs/ (made by
+// tools/fetch-cloud-specs.mjs): operationId → {method, path, summary, params, body}.
+import fs from 'node:fs';
+
+const cache = new Map();
+
+export function operationsOf(service) {
+  if (cache.has(service)) return cache.get(service);
+  const spec = JSON.parse(fs.readFileSync(new URL(`../../specs/${service}.openapi.json`, import.meta.url), 'utf8'));
+  const ops = new Map();
+  for (const [path, item] of Object.entries(spec.paths ?? {})) {
+    for (const [method, op] of Object.entries(item)) {
+      ops.set(op.operationId, {
+        method: method.toUpperCase(),
+        path,
+        summary: op.summary ?? '',
+        params: (op.parameters ?? []).map((p) => ({name: p.name, in: p.in, required: p.required})),
+        body: Boolean(op.requestBody),
+        bodyRequired: Boolean(op.requestBody?.required),
+        schema: op.requestBody?.schema,
+      });
+    }
+  }
+  cache.set(service, ops);
+  return ops;
+}

package/src/cloud/token.mjs

@@ -0,0 +1,47 @@
+// The CPA token (Cognito PBX Auth): the cloud identity of a PBX, a Cognito ID token whose user is the PBX itself
+// (cognito:username = its serial) in the company of the PBX. The PBX gives it to an administrator on an internal route
+// of its WMS interface and keeps it until it expires (12 hours). Kept here in the memory of the process only, per PBX,
+// and taken again a minute before its end.
+import {jwtClaims} from 'wldx-core/auth';
+import {AuthError} from 'wldx-core/errors';
+import {PbxError, pbxClient} from '../pbx.mjs';
+
+const ROUTE = '/PBX/integration/x-bees?skip-basic-auth-header=true';
+const EARLY_MS = 60_000;
+const tokens = new Map(); // PBX host → {token, company, companyName, portal, expiresAt, pbx}
+
+export function clearCloudTokens() {
+  tokens.clear();
+}
+
+export async function cloudToken(ctx) {
+  const client = await pbxClient(ctx);
+  const host = client.target.host;
+  const now = ctx.clock?.() ?? Date.now();
+  const kept = tokens.get(host);
+  if (kept && kept.expiresAt - now > EARLY_MS) return kept;
+  let answer;
+  try {
+    answer = await client.call('GET', ROUTE);
+  } catch (e) {
+    if (e instanceof PbxError && (e.status === 401 || e.status === 403))
+      throw new AuthError(
+        `${host} gives its cloud token only to an administrator: use an access with the Admin role (wx-admin pbx check)`,
+      );
+    throw e;
+  }
+  const token = answer?.token;
+  if (typeof token !== 'string' || token.split('.').length !== 3)
+    throw new Error(`${host} answered no cloud token (WMS too old, or the PBX not linked to the cloud)`);
+  const claims = jwtClaims(token);
+  const t = {
+    token,
+    company: claims['custom:company_id'],
+    companyName: claims['custom:company_name'],
+    portal: answer.portal,
+    expiresAt: Number(claims.exp) * 1000,
+    pbx: host,
+  };
+  tokens.set(host, t);
+  return t;
+}

package/src/commands/cloud.mjs

@@ -0,0 +1,122 @@
+// wx-admin cloud: any operation of the Wildix cloud services that accept the CPA token of the PBX (the knowledge
+// base, voicebots, WIM tools, Wilma), from their OpenAPI bundled in specs/. GET reads; every other method needs
+// --yes. Answers are masked (keys, tokens, passwords) unless --show-secrets.
+import {UsageError} from 'wldx-core/errors';
+import {readJsonInput} from 'wldx-core/files';
+import {apiPath} from 'wldx-core/http';
+import {cloudClient} from '../cloud/client.mjs';
+import {SERVICES} from '../cloud/env.mjs';
+import {operationsOf} from '../cloud/specs.mjs';
+import {maskCloud} from '../cloud/mask.mjs';
+
+const segment = (value) => apiPath(['', ''], value);
+
+// The request of an operation: the path with its parameters, the query, the body; usage errors before any request.
+export async function requestOf(ctx, service, operationId) {
+  const ops = operationsOf(service);
+  const op = ops.get(operationId);
+  if (!op)
+    throw new UsageError(`Unknown operation of ${service}: ${operationId}. Its operations: wx-admin cloud ${service}`);
+  const given = new Map();
+  for (const kv of ctx.values.param ?? []) {
+    const at = kv.indexOf('=');
+    if (at < 1) throw new UsageError(`--param is NAME=VALUE: ${kv}`);
+    const name = kv.slice(0, at);
+    if (!op.params.some((p) => p.name === name))
+      throw new UsageError(
+        `${operationId} has no parameter ${name}. Its parameters: ${op.params.map((p) => p.name).join(', ') || 'none'}`,
+      );
+    given.set(name, kv.slice(at + 1));
+  }
+  for (const p of op.params)
+    if (p.required && !given.has(p.name)) throw new UsageError(`${operationId} needs --param ${p.name}=…`);
+  const path = op.path.replace(/\{([^}]+)\}/g, (_, name) => segment(given.get(name)));
+  const query = Object.fromEntries(
+    op.params.filter((p) => p.in === 'query' && given.has(p.name)).map((p) => [p.name, given.get(p.name)]),
+  );
+  let json;
+  const v = ctx.values;
+  if (v.data !== undefined && v['data-file'] !== undefined)
+    throw new UsageError('Give --data or --data-file, not both');
+  if (v.data !== undefined || v['data-file'] !== undefined) {
+    if (!op.body) throw new UsageError(`${operationId} takes no body`);
+    if (v['data-file'] !== undefined) json = await readJsonInput(ctx, v['data-file']);
+    else {
+      try {
+        json = JSON.parse(v.data);
+      } catch {
+        throw new UsageError('--data is not JSON');
+      }
+    }
+  } else if (op.bodyRequired) throw new UsageError(`${operationId} needs a body: --data JSON or --data-file FILE`);
+  if (op.method !== 'GET' && !v.yes)
+    throw new UsageError(
+      `${operationId} is a ${op.method}: it changes or runs something in the cloud, confirm with --yes`,
+    );
+  return {op, path, query, json};
+}
+
+export const commands = {
+  cloud: {
+    summary:
+      'any operation of the cloud services (knowledge base, voicebots, WIM tools, Wilma) with the token of the PBX',
+    usage:
+      'wx-admin cloud [<service> [<operation>]] [--param NAME=VALUE]... [--data JSON | --data-file FILE|-] [--yes] [--show-secrets]',
+    details: [
+      'Without a service: the services. With a service: its operations. The PBX (--pbx, the default one…) gives its',
+      'cloud token to an administrator; the environment is the one of the PBX, or --env prod|stable|stage.',
+      'Methods other than GET need --yes. Answers are masked (keys, tokens, passwords) unless --show-secrets.',
+    ].join('\n'),
+    options: {
+      param: {type: 'string', multiple: true, placeholder: 'NAME=VALUE', description: 'a path or query parameter'},
+      data: {type: 'string', placeholder: 'JSON', description: 'the JSON body'},
+      'data-file': {type: 'string', placeholder: 'FILE', description: 'the JSON body from a file, or - for stdin'},
+      yes: {type: 'boolean', description: 'yes, run an operation that is not a GET'},
+      'show-secrets': {
+        type: 'boolean',
+        description: 'show keys, tokens and passwords in the answer (masked otherwise)',
+      },
+    },
+    args: [0, 2],
+    complete: 'cloudServices',
+    async run(ctx) {
+      const [service, operationId] = ctx.positionals;
+      if (!service)
+        return {
+          services: Object.entries(SERVICES).map(([name, s]) => ({
+            name,
+            label: s.label,
+            environments: Object.keys(s.bases),
+            operations: operationsOf(name).size,
+          })),
+        };
+      if (!Object.hasOwn(SERVICES, service))
+        throw new UsageError(`Unknown cloud service: ${service}. Known: ${Object.keys(SERVICES).join(', ')}`);
+      if (!operationId)
+        return {
+          service,
+          operations: [...operationsOf(service)].map(([id, o]) => ({
+            operationId: id,
+            method: o.method,
+            path: o.path,
+            summary: o.summary,
+          })),
+        };
+      const {op, path, query, json} = await requestOf(ctx, service, operationId);
+      const client = await cloudClient(ctx, service);
+      const answer = await client.call(op.method, path, {query, json});
+      return ctx.values['show-secrets'] ? answer : maskCloud(answer);
+    },
+    text(r) {
+      if (r?.services)
+        return r.services.map(
+          (s) => `${s.name.padEnd(10)} ${s.label} · ${s.environments.join(', ')} · ${s.operations} operations`,
+        );
+      if (r?.operations && r.service)
+        return r.operations.map(
+          (o) => `${o.operationId.padEnd(40)} ${o.method.padEnd(6)} ${o.path}${o.summary ? `  ${o.summary}` : ''}`,
+        );
+      return JSON.stringify(r, null, 2);
+    },
+  },
+};

package/src/commands/index.mjs

@@ -4,10 +4,12 @@
 // offers the PBX with saved access. `readOnly: true` on a command that only reads lets it run with --all-pbx
 // (READ_ONLY below sets it).
 import {commands as api} from './api.mjs';
+import {commands as cloud} from './cloud.mjs';
 import {groups as acl} from './acl.mjs';
 import {groups as config} from './config.mjs';
 import {groups as device} from './device.mjs';
 import {groups as dialplan} from './dialplan.mjs';
+import {groups as kb} from './kb.mjs';
 import {login, logout} from 'wldx-core/commands/login';
 import {groups as pbx} from './pbx.mjs';
 import {groups as phonebook} from './phonebook.mjs';
@@ -39,11 +41,12 @@ export const GROUPS = {
   ...sound,
   ...records,
   ...config,
+  ...kb,
   ...pbx,
   ...profile,
 };
 
-export const COMMANDS = {...api, login, logout, status};
+export const COMMANDS = {...api, ...cloud, login, logout, status};
 
 // The commands that only read the PBX (no change there, no file written): they may run with --all-pbx.
 const READ_ONLY = {
@@ -82,4 +85,10 @@ export const GLOBAL_OPTIONS = {
     complete: 'pbxs',
   },
   'all-pbx': {type: 'boolean', description: 'run a command that reads on every PBX'},
+  env: {
+    type: 'string',
+    choices: ['prod', 'stable', 'stage'],
+    key: 'cloudEnv',
+    description: 'the environment of the cloud services (default: the one of the PBX)',
+  },
 };