@n42/cli 0.1.21

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (C) 2026, Node42. <code@node42.dev>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,92 @@
+# Node42 CLI (n42)
+
+Command-line interface for **eDelivery discovery, diagnostics, and
+validation**, with support for the Peppol network.
+
+The Node42 CLI is designed for **system integrators, service providers,
+and operators** who need fast, repeatable insight into eDelivery
+routing, SMP resolution, and Access Point behavior.
+
+------------------------------------------------------------------------
+
+## Features
+
+-   Peppol eDelivery path discovery
+-   SMP and Access Point resolution diagnostics
+-   Supported document type detection
+-   PlantUML and SVG visualizations
+-   Authenticated API access
+-   Deterministic, script-friendly output
+-   No browser automation or UI side effects
+
+## Installation
+
+### Requirements
+
+-   Node.js **18+** (Node 20 recommended)
+-   npm
+
+### Install globally
+
+``` bash
+npm install -g @n42/cli
+```
+
+Verify installation:
+
+``` bash
+n42 --version
+```
+
+------------------------------------------------------------------------
+
+## Authentication
+
+Authenticate once using your Node42 account credentials.\
+Tokens are stored locally under `~/.node42/`.
+
+``` bash
+n42 signin
+```
+
+Check authentication status:
+
+``` bash
+n42 me
+```
+
+------------------------------------------------------------------------
+
+## Peppol Discovery
+
+### Basic discovery
+
+``` bash
+n42 discover peppol <environment> <participantId>
+```
+
+------------------------------------------------------------------------
+
+## Artifacts
+
+Artifacts are stored under:
+
+    ~/.node42/artifacts/
+
+------------------------------------------------------------------------
+
+## Error Handling
+
+Errors are printed with a clickable reference link:
+
+    https://www.node42.dev/errors?code=XXXX
+
+## Security
+
+-   TLS verification enabled by default
+-   Explicit `--insecure` flag for testing only
+-   Tokens stored locally, never logged
+
+## License
+
+MIT License

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@n42/cli",
+  "version": "0.1.21",
+  "description": "Node42 CLI – Command-line interface for eDelivery path discovery, diagnostics, and tooling",
+  "keywords": [
+    "node42"
+  ],
+  "homepage": "https://github.com/node42-dev/node42-cli",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/node42-dev/node42-cli.git"
+  },
+  "license": "MIT",
+  "author": "Node42 @n42",
+  "type": "commonjs",
+  "bin": {
+    "n42": "src/cli.js"
+  },
+  "dependencies": {
+    "commander": "^11.1.0",
+    "inquirer": "^8.2.7",
+    "open": "^11.0.0"
+  }
+}

package/src/auth.js

@@ -0,0 +1,123 @@
+const fs = require("fs");
+const { NODE42_DIR, TOKENS_FILE, API_URL, EP_REFRESH } = require("./config");
+const { handleError } = require("./errors");
+const { updateUserInfo, updateUserUsage } = require("./user");
+
+
+function loadAuth() {
+  if (!fs.existsSync(TOKENS_FILE)) {
+    console.error("Not logged in. Run: n42 signin");
+    process.exit(1);
+  }
+  return JSON.parse(fs.readFileSync(TOKENS_FILE, "utf8"));
+}
+
+async function checkAuth() {
+  if (!fs.existsSync(TOKENS_FILE)) {
+    handleError({ code: "N42E-9033", message: "Token missing..."})
+    process.exit(1);
+  }
+
+  const res = await fetchWithAuth(`${API_URL}/users/me`, {
+        method: "GET",
+        headers: {
+            "Content-Type": "application/json"
+        }
+    });
+
+  if (!res) { 
+    return false;
+  }
+
+  if (!res.ok) {
+    const err = await res.json();
+    await handleError(err);
+    return false;
+  }
+
+  const auth = await res.json();
+  if (auth) {  
+    updateUserInfo({
+      userName: auth.userName,
+      userMail: auth.userMail,
+      role: auth.role,
+    });
+
+    updateUserUsage({ serviceUsage: auth.serviceUsage });
+    return true;
+  }
+
+  return false;
+}
+
+async function refreshSession() {
+  const { refreshToken } = loadAuth();
+  if (!refreshToken) {
+    return false;
+  }
+
+  const payload = {
+      refreshToken,
+  };
+
+  const res = await fetch(`${API_URL}/${EP_REFRESH}`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json'
+    },
+    body: JSON.stringify(payload)
+  });
+
+  const data = await res.json();
+  //console.log(data);
+
+  if (!res.ok || data.__type) {
+    //console.log(data);
+    return false;
+  }
+
+  if (data) {
+    fs.mkdirSync(NODE42_DIR, { recursive: true });
+    fs.writeFileSync(
+      TOKENS_FILE,
+      JSON.stringify({ 
+        accessToken: data.accessToken, 
+        refreshToken: data.refreshToken,
+        idToken: data.idToken 
+      })
+    );
+    //console.log("Token refreshed");
+  }
+
+  return true;
+}
+
+async function fetchWithAuth(url, options = {}) {
+  const { accessToken } = loadAuth();
+  if (!accessToken) { // N42E-9032
+    //console.log("Token missing...");
+
+    handleError({ code: "N42E-9032" });
+    return;
+  }
+
+  const res = await fetch(url, {
+    ...options,
+    headers: {
+      ...(options.headers || {}),
+      ...(accessToken ? { Authorization: `Bearer ${accessToken}` } : {})
+    }
+  });
+
+  if (res.status !== 401) {
+    return res;
+  }
+
+  const refreshed = await refreshSession();
+  if (!refreshed) { // N42E-9033
+    //console.log("Token expired...");
+    return res;
+  }
+}
+
+module.exports = { loadAuth, checkAuth, fetchWithAuth };

package/src/browser.js

@@ -0,0 +1,10 @@
+const open = require("open").default;
+let browserOpened = false;
+
+async function openOnce(target) {
+  if (browserOpened) return;
+  browserOpened = true;
+  await open(target, { wait: false });
+}
+
+module.exports = { openOnce };

package/src/cli.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+const { Command } = require("commander");
+const { signin } = require("./signin");
+const { checkAuth } = require("./auth");
+const { getUserInfo } = require("./user");
+const { runDiscovery } = require("./discover");
+const { clearScreen, startSpinner, validateEnv, validateId} = require("./utils");
+
+const program = new Command();
+const pkg = require("../package.json");
+
+program
+  .name("n42")
+  .description("Command-line interface for eDelivery path discovery and diagnostics")
+  .version(pkg.version);
+
+program
+  .command("signin")
+  .description("Authenticate using username and password and store tokens locally")
+  .action(signin);
+
+program
+  .command("me")
+  .description("returns identity and billing status for the authenticated user.")
+  .action(() => {
+    const stopSpinner = startSpinner();
+    
+    checkAuth(); 
+    const user = getUserInfo();
+    console.log(
+      `Authenticated as ${user.userName} <${user.userMail}> (${user.role})`
+    );
+
+    stopSpinner();
+  });
+
+const discover = program
+  .command("discover")
+  .description("Discovery and diagnostic tooling for eDelivery paths");
+
+discover
+  .command("peppol <environment> <participantId>")
+  .description("Resolve the Peppol eDelivery message path")
+  .option("--output <type>", "Result type (json | plantuml)", "json")
+  .option("--format <format>", "When output=plantuml (svg | text)", "svg")
+  .option("--force-https", "Force HTTPS endpoints", true)
+  .option("--insecure", "Disable TLS certificate validation", false)
+  .option("--fetch-business-card", "Fetch Peppol business card", false)
+  .option("--reverse-lookup", "Enable reverse lookup", false)
+  .option("--probe-endpoints", "Probe resolved endpoints", false)
+  .action((environment, participantId, options) => {
+
+    clearScreen(`Node42 CLI v${pkg.version}`);
+    
+    try { validateEnv(environment); }
+    catch (e) { 
+      console.error(e.message);
+      process.exit(1);
+    }
+
+    try { validateId("participant", participantId); }
+    catch (e) { 
+      console.error(e.message);
+      process.exit(1);
+    }
+
+    runDiscovery(environment.toUpperCase(), participantId, options);
+  });
+
+program.parse(process.argv);

package/src/config.js

@@ -0,0 +1,46 @@
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+const config = {
+  APP_NAME: "n42",
+  API_URL: "https://api.node42.dev",
+  WWW_URL: "https://www.node42.dev",
+  API_TIMEOUT_MS: 30000,
+
+  NODE42_DIR: path.join(os.homedir(), ".node42"),
+  ARTEFACTS_DIR: null,
+  USAGE_FILE: null,     // filled below
+  USER_FILE: null,      // filled below
+  TOKENS_FILE: null,    // filled below
+  CONFIG_FILE: null,    // filled below
+
+  DEFAULT_OUTPUT: "json",
+  DEFAULT_FORMAT: "svg",
+
+  EP_SIGNIN: "auth/signin",
+  EP_REFRESH: "auth/refresh",
+  EP_DISCOVER: "discover/peppol"
+};
+
+config.ARTEFACTS_DIR = path.join(config.NODE42_DIR, "artefacts", "discovery");
+config.USER_FILE = path.join(config.NODE42_DIR, "user.json");
+config.USAGE_FILE = path.join(config.NODE42_DIR, "usage.json");
+config.TOKENS_FILE = path.join(config.NODE42_DIR, "tokens.json");
+config.CONFIG_FILE = path.join(config.NODE42_DIR, "config.json");
+
+function createAppDirs() {
+  fs.mkdirSync(config.NODE42_DIR, { recursive: true });
+  fs.mkdirSync(config.ARTEFACTS_DIR, { recursive: true });
+
+  //if (!fs.existsSync(config.CONFIG_FILE)) {
+    fs.writeFileSync(
+      config.CONFIG_FILE,
+      JSON.stringify(config, null, 2)
+    );
+  //}
+}
+
+createAppDirs();
+
+module.exports = config;

package/src/discover.js

@@ -0,0 +1,151 @@
+const fs = require("fs");
+const path = require("path");
+const pkg = require("../package.json");
+
+const { fetchWithAuth } = require("./auth");
+const { API_URL, EP_DISCOVER, DEFAULT_OUTPUT, DEFAULT_FORMAT, ARTEFACTS_DIR } = require("./config");
+const { getUserUsage, updateUserUsage } = require("./user");
+const { clearScreen, startSpinner, buildDocLabel, promptForDocument } = require("./utils");
+const { handleError } = require("./errors"); 
+
+const DEFAULT_DISCOVERY_INPUT = {
+  env: "TEST",
+  options: {
+    forceHttps: true,
+    insecure: false,
+    fetchBusinessCard: false,
+    reverseLookup: false,
+    probeEndpoints: false
+  },
+  participant: {
+    scheme: "iso6523-actorid-upis",
+    value: "",
+  },
+  document: {
+    scheme: "peppol-doctype-wildcard",
+    value: "",
+  },
+  overrides: {
+    smpUrl: "",
+    apUrl: "",
+  }
+};
+const discoveryInput = DEFAULT_DISCOVERY_INPUT;
+let docSelected = false;
+
+
+async function runDiscovery(environment, participantId, options) {
+  const {
+    output = DEFAULT_OUTPUT,
+    format = DEFAULT_FORMAT,
+    forceHttps,
+    insecure,
+    fetchBusinessCard,
+    reverseLookup,
+    probeEndpoints
+  } = options;
+
+  discoveryInput.participant.value = participantId;
+
+  const payload = {
+    ...discoveryInput,
+    env: environment,
+    options: {
+      output,
+      format,
+      forceHttps,
+      rejectUnauthorized: insecure,
+      fetchBusinessCard,
+      reverseLookup,
+      probeEndpoints
+    }
+  };
+
+  clearScreen(`Node42 CLI v${pkg.version}`);
+  const stopSpinner = startSpinner();
+
+  const url = `${API_URL}/${EP_DISCOVER}?output=${output}&format=${format}`;
+  const res = await fetchWithAuth(url, {
+      method: "POST",
+      headers: {
+          "Content-Type": "application/json"
+      },
+      body: JSON.stringify(payload)
+  });
+
+  if (!res.ok) {
+    const err = await res.json();
+    stopSpinner();
+
+    if (err.code) {
+      await handleError(err);
+    }
+
+    process.exit(1);
+  }
+
+  if (output === "plantuml" && format === "svg") {
+    const svg = await res.text();
+    stopSpinner();
+
+    if (!svg || svg.trim().length === 0) {
+      await handleError({ code: "6123" });
+      process.exit(1);
+    }
+
+    const refId = res.headers.get("X-Node42-RefId");  
+    const serviceUsage = res.headers.get("X-Node42-ServiceUsage");
+    const rateLimit = res.headers.get("X-Node42-RateLimit");
+
+    const userUsage = getUserUsage();
+    const currentMonth = new Date().toISOString().slice(0, 7);
+    userUsage.serviceUsage.discovery[currentMonth] = serviceUsage;
+    
+    updateUserUsage(userUsage);
+
+    const encodedDocs = res.headers.get("X-Node42-Documents");
+    if (encodedDocs && !docSelected) {
+       const docs = JSON.parse(Buffer.from(encodedDocs, "base64").toString("utf8"))
+        .map(d => ({ ...d, label: buildDocLabel(d) }));
+
+      if (docs.length) {
+        console.log(`Discovery completed`);
+        console.log(`Found ${docs.length} supported document type(s)\n`);
+        
+        docSelected = await promptForDocument(docs);
+
+        if (docSelected.scheme) {
+          discoveryInput.document.scheme = docSelected.scheme;
+        }
+
+        if (docSelected.value) {
+          discoveryInput.document.value = docSelected.value;
+        }
+
+        runDiscovery(environment, participantId, options);
+      }
+    }
+
+    const file = path.join(ARTEFACTS_DIR, `${refId}.svg`);
+    fs.writeFileSync(file, svg);
+
+    console.log(`Discovery completed`);
+    console.log(`Usage    : ${serviceUsage} / ${rateLimit}`);
+    console.log(`Artifact : ${file}\n`);
+
+    stopSpinner();
+    return;
+  }
+
+  if (output === "plantuml" && output === "text") {
+    const text = await res.text();
+    console.log(text);
+    return;
+  }
+
+  // default: json
+  const json = await res.json();
+  console.log(JSON.stringify(json, null, 2));
+}
+
+module.exports = { runDiscovery };

package/src/errors.js

@@ -0,0 +1,27 @@
+const { openOnce } = require("./browser");
+const { WWW_URL } = require("./config");
+
+
+async function handleError(err) {
+  //console.log(err);
+
+  const code = err.code?.startsWith("N42E-")
+      ? err.code.slice(5)
+      : undefined;
+
+  const message = err.message;
+
+  const url = code
+    ? `${WWW_URL}/errors?code=${code}`
+    : `${WWW_URL}/errors`;
+  //console.log(url);
+
+  if (message) {
+    console.error(`${err.message}\nSee details: ${url}\n`);
+  } else {
+    console.error(`See details: ${url}\n`);
+  }
+  //await openOnce(url);
+}
+
+module.exports = { handleError };

package/src/signin.js

@@ -0,0 +1,58 @@
+const fs = require("fs");
+
+const { NODE42_DIR, TOKENS_FILE, API_URL, EP_SIGNIN } = require("./config");
+const { checkAuth } = require("./auth");
+const { getUserInfo } = require("./user");
+const { clearScreen, ask, startSpinner } = require("./utils");
+
+
+async function signin() {
+  clearScreen("Sign in to Node42");
+
+  const username = await ask("Username: ");
+  const password = await ask("Password: ", true);
+
+  let stopSpinner = startSpinner();
+
+  const res = await fetch(`${API_URL}/${EP_SIGNIN}`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ username, password })
+  });
+
+  if (!res.ok) {
+    stopSpinner();
+
+    console.error("Login failed: ", res.status);
+    process.exit(1);
+  }
+
+  const tokens = await res.json();
+
+  const { accessToken, refreshToken, idToken } = tokens;
+  if (!accessToken || !refreshToken || !idToken) {
+    stopSpinner();
+
+    console.error("Invalid auth response");
+    process.exit(1);
+  }
+
+  fs.mkdirSync(NODE42_DIR, { recursive: true });
+  fs.writeFileSync(
+    TOKENS_FILE,
+    JSON.stringify({ accessToken, refreshToken, idToken }, null, 2)
+  );
+
+  stopSpinner();
+  stopSpinner = startSpinner();
+
+  checkAuth();
+  const user = getUserInfo();
+  console.log(
+    `Authenticated as ${user.userName} <${user.userMail}> (${user.role})`
+  );
+  
+  stopSpinner();
+}
+
+module.exports = { signin };

package/src/user.js

@@ -0,0 +1,64 @@
+const fs = require("fs");
+const { NODE42_DIR, USER_FILE, USAGE_FILE } = require("./config");
+
+function updateUserInfo(user) {
+  fs.mkdirSync(NODE42_DIR, { recursive: true });
+
+  fs.writeFileSync(
+    USER_FILE,
+    JSON.stringify(user, null, 2)
+  );  
+}
+
+function getUserInfo() {
+  try {
+    if (!fs.existsSync(USER_FILE)) {
+      return {
+        userName: "n/a",
+        userMail: "n/a",
+        role: "n/a"
+      };
+    }
+    return JSON.parse(fs.readFileSync(USER_FILE, "utf8"));
+  } catch {
+    return {
+        userName: "n/a",
+        userMail: "n/a",
+        role: "n/a"
+    };
+  }
+}
+
+function updateUserUsage(usage) {
+  fs.mkdirSync(NODE42_DIR, { recursive: true });
+
+  fs.writeFileSync(
+    USAGE_FILE,
+    JSON.stringify(usage, null, 2)
+  );
+}
+
+function getUserUsage() {
+  try {
+    if (!fs.existsSync(USAGE_FILE)) {
+      return {
+        serviceUsage: {
+          discovery: {},
+          validation: {},
+          transactions: {}
+        }
+      };
+    }
+    return JSON.parse(fs.readFileSync(USAGE_FILE, "utf8"));
+  } catch {
+    return {
+      serviceUsage: {
+        discovery: {},
+        validation: {},
+        transactions: {}
+      }
+    };
+  }
+}
+
+module.exports = { updateUserInfo, getUserInfo, updateUserUsage, getUserUsage };

package/src/utils.js

@@ -0,0 +1,134 @@
+const inquirer = require("inquirer");
+const readline = require("readline");
+
+function clearScreen(text) {
+  process.stdout.write("\x1Bc");
+  if (text) {
+    process.stdout.write(text + "\n");
+  }
+}
+
+function ask(question, hidden=false) {
+  return new Promise(resolve => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+      terminal: true
+    });
+
+    process.stdin.on("data", char => {
+      char = char + "";
+      switch (char) {
+        case "\n":
+        case "\r":
+        case "\u0004":
+          process.stdin.pause();
+          break;
+        default:
+          if (hidden) {
+            process.stdout.clearLine(0);
+            process.stdout.cursorTo(0);
+            process.stdout.write(question + "*".repeat(rl.line.length));
+          }
+          break;
+      }
+    });
+
+    rl.question(question, answer => {
+      rl.history = rl.history.slice(1);
+      rl.close();
+      resolve(answer);
+    });
+  });
+}
+
+function startSpinner(text = "Working") {
+  const frames = ["-", "\\", "|", "/"];
+  let i = 0;
+
+  const timer = setInterval(() => {
+    process.stdout.write("\r[" + frames[i++ % frames.length] + "] " + text);
+  }, 120);
+
+  return () => {
+    clearInterval(timer);
+    process.stdout.write("\r\x1b[K"); // carriage return + clear line
+  };
+}
+
+function buildDocLabel({ scheme, value }) {
+  // 1. Document name (after :: before ##)
+  const docMatch = value.match(/::([^#]+)##/);
+  const docName = docMatch ? docMatch[1].replace(/([A-Z])/g, " $1").trim() : "Document";
+
+  // 2. Wildcard
+  if (value.endsWith("##*")) {
+    return `Any ${docName} (Wildcard)`;
+  }
+
+  // 3. PINT profile
+  if (value.includes(":pint:")) {
+    const regionMatch = value.match(/@([a-z0-9-]+)/i);
+    const region = regionMatch
+      ? regionMatch[1].replace(/-1$/, "").toUpperCase()
+      : "PINT";
+
+    const prefix = scheme === "peppol-doctype-wildcard" ? "Wildcard" : "PINT";
+    return `${docName} (${prefix} ${region})`;
+  }
+
+  // 4. BIS profile
+  if (value.includes(":bis:") || value.includes("en16931")) {
+    const bisMatch = value.match(/bis:[^:]+:(\d+)/);
+    const version = bisMatch ? bisMatch[1] : "3";
+    return `${docName} (BIS ${version})`;
+  }
+
+  // 4. TRNS profile
+  if (value.includes(":trns:")) {
+    const trnsMatch = value.match(/:trns:([^:]+):([\d.]+)/);
+    const version = trnsMatch ? ` ${trnsMatch[2]}` : "";
+    return `${docName} (TRNS${version})`;
+  }
+
+  // 5. Fallback
+  return docName;
+}
+
+async function promptForDocument(docs) {
+  const { document } = await inquirer.prompt([
+    {
+      type: "list",
+      name: "document",
+      message: "Select document type:",
+      choices: docs.map(d => ({
+        name: d.label,
+        value: d
+      }))
+    }
+  ]);
+
+  return document;
+}
+
+function validateEnv(env) {
+  const allowedEnvs = ["TEST", "PROD"];
+  if (!allowedEnvs.includes(env.toUpperCase())) {
+    throw new Error(
+      `Invalid environment: ${env}\nAllowed values: ${allowedEnvs.join(", ")}`
+    );
+  }
+}
+
+function validateId(type, id) {
+  const value = id.replace(/\s+/g, "");
+
+  // ISO 6523–safe; participant id like 0000:12345 or 9915:abcde
+  if (!/^[0-9]{4}:[a-zA-Z0-9\-\._~]{1,135}$/.test(value)) {
+    throw new Error(
+      `Invalid ${type}Id: ${id}\nExpected format: 0007:123456789 or 0007:abcd`
+    );
+  }
+}
+
+module.exports = { clearScreen, startSpinner, ask, buildDocLabel, promptForDocument, validateEnv, validateId };