@nodium.io/cli 0.1.0 → 0.2.1

package/dist/output.js

@@ -4,6 +4,15 @@ const CODES = { dim: 2, red: 31, green: 32, yellow: 33, cyan: 36, bold: 1 };
 export function paint(output, style, text) {
     return output.color ? `\u001b[${CODES[style]}m${text}\u001b[0m` : text;
 }
+/** Le bloc « Next: » : les commandes à lancer ensuite, une par ligne. */
+export function printNext(output, steps) {
+    if (!steps?.length)
+        return;
+    output.out('');
+    output.out('Next:');
+    for (const step of steps)
+        output.out(`  ${step}`);
+}
 /** L'heure locale, `HH:MM:SS`. */
 export function clock(date = new Date()) {
     return date.toTimeString().slice(0, 8);
@@ -22,9 +31,7 @@ export function describeError(error, baseUrl) {
         return error instanceof Error ? error.message : String(error);
     const lines = [`${error.status ? `Error ${error.status}` : 'Error'} ${error.code}: ${error.message}`];
     if (error.status === 401)
-        lines.push('The key is missing, malformed or revoked: check NODIUM_KEY (or --key).');
-    if (error.status === 403)
-        lines.push('This key does not have the role the command needs (`listen` reads the event log: `admin`).');
+        lines.push('The key is missing, malformed, expired or revoked: check --key, NODIUM_KEY, or run `nodium login` again.');
     if (error.retryAfter !== null)
         lines.push(`Retry in ${error.retryAfter} s.`);
     if (error.requestId)
@@ -37,3 +44,31 @@ export function describeError(error, baseUrl) {
     }
     return lines.join('\n');
 }
+/**
+ * Le refus en JSON, sur la sortie d'erreur : `{ "error": { status, code,
+ * message, requestId } }`. Une faute d'usage a `status` 0 et le code `usage_error`.
+ */
+export function errorJson(error) {
+    const body = error instanceof NodiumError
+        ? { status: error.status, code: error.code, message: error.message, requestId: error.requestId }
+        : { status: 0, code: error instanceof UsageError ? 'usage_error' : 'cli_error', message: error instanceof Error ? error.message : String(error), requestId: null };
+    return JSON.stringify({ error: body }, null, 2);
+}
+/** Des colonnes alignées, une ligne par entrée ; la dernière colonne n'est pas complétée. */
+export function table(rows) {
+    const widths = [];
+    for (const row of rows)
+        row.forEach((cell, i) => { widths[i] = Math.max(widths[i] ?? 0, cell.length); });
+    return rows.map(row => row.map((cell, i) => (i === row.length - 1 ? cell : cell.padEnd(widths[i]))).join('  ').trimEnd());
+}
+/** Une date ISO en `AAAA-MM-JJ HH:MM`, ou `—`. */
+export function when(iso) {
+    return iso ? iso.slice(0, 16).replace('T', ' ') : '—';
+}
+/** Un objet en lignes `clé  valeur` ; ce qui est imbriqué s'écrit en JSON compact. */
+export function details(object) {
+    return table(Object.entries(object).map(([key, value]) => [
+        key,
+        value === null || value === undefined ? '—' : typeof value === 'object' ? JSON.stringify(value) : String(value)
+    ]));
+}

package/dist/run.js

@@ -2,71 +2,64 @@ import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { DEFAULT_BASE_URL, Nodium } from '@nodium.io/whatsapp';
 import { UsageError, flag, hasFlag, parseArgs, rejectUnknown } from './args.js';
-import { DEFAULT_INTERVAL_MS, listen, parseEventFilter, parseForwardUrl } from './listen.js';
-import { describeError, paint } from './output.js';
-import { readSendInput, send } from './send.js';
+import { COMMANDS, findCommands } from './commands/index.js';
+import { configPath as defaultConfigPath, readConfig, resolveKey } from './config.js';
+import { confirmWrite, outputMode } from './context.js';
+import { pause } from './listen.js';
+import { describeError, errorJson, paint, table, printNext } from './output.js';
 /**
- * La commande `nodium` : lit la ligne de commande, branche le client, rend le
- * code de sortie (0 réussi, 1 refusé par Nodium ou par Meta, 2 mal appelé).
+ * La commande `nodium` : lit la ligne de commande, cherche la commande dans la
+ * table (`commands/index.ts`), branche le client, rend le code de sortie
+ * (0 réussi, 1 refusé par Nodium ou par Meta, 2 mal appelé).
  *
- * ⚠️ La clé se donne de préférence par `NODIUM_KEY` : `--key` reste dans
- *    l'historique du terminal.
+ * ⚠️ La clé se donne de préférence par `nodium login` ou `NODIUM_KEY` :
+ *    `--key` reste dans l'historique du terminal.
  */
-const HELP = `nodium: the Nodium API from your terminal.
-
-Usage
-  nodium listen --forward <url> [--secret <whsec_…>] [--events a,b]
-  nodium send --channel <id> --to <+33…> --text "…"
+/** Les drapeaux qu'accepte toute commande. */
+const COMMON = ['key', 'tenant', 'base-url', 'output', 'yes', 'no-color', 'help'];
+const COMMON_HELP = `Options for every command
+  --key <nod_…>          API key. Default: $NODIUM_KEY, then the key saved by \`nodium login\`.
+  --tenant <id>          Act for one client: its id or your own externalId.
+  --output <json|human>  json: the API's object, for scripts and agents. Default: human in a
+                         terminal, json when piped.
+  -y, --yes              Approve a command that sends or changes something, without asking.
+                         Required when not in a terminal.
+  --base-url <url>       API address. Default: ${DEFAULT_BASE_URL} ($NODIUM_BASE_URL).
+  --no-color             No colors (also: $NO_COLOR).
+  -h, --help             This help, or the help of a command.
+  -v, --version          The version.`;
+function usage(command) {
+    return ['nodium', ...command.path, ...(command.args ?? [])].join(' ');
+}
+export function globalHelp() {
+    return `nodium: the Nodium WhatsApp API from your terminal.
 
 Commands
-  listen   Replay your events to a local URL, signed like production: no tunnel.
-  send     Send a WhatsApp message, to try things.
+${table(COMMANDS.map(c => [`  ${usage(c)}`, c.summary])).join('\n')}
+
+${COMMON_HELP}
 
-Options for every command
-  --key <nod_…>      API key. Default: $NODIUM_KEY.
-  --tenant <id>      Act for one client: its id or your own externalId.
-  --base-url <url>   API address. Default: ${DEFAULT_BASE_URL} ($NODIUM_BASE_URL).
-  --no-color         No colors (also: $NO_COLOR).
-  -h, --help         This help, or the help of a command.
-  -v, --version      The version.
+Exit codes: 0 done, 1 refused by Nodium or Meta, 2 wrong command line.
+More: nodium help <command>, for example \`nodium help templates wait\`.
 `;
-const HELP_LISTEN = `nodium listen: replay your events to your own server, without a tunnel.
+}
+export function commandHelp(command) {
+    return `${usage(command)}: ${command.summary}
 
 Usage
-  nodium listen --forward <url> [options]
-
-Options
-  --forward <url>    Your local address, for example http://localhost:3000/webhook. Required.
-  --secret <whsec>   Signs each call with X-Nodium-Signature (t=…,v1=…), as in production.
-                     Use the secret of your webhook subscription, or any string your code also
-                     uses to verify: the signature is computed here. Default: $NODIUM_WEBHOOK_SECRET.
-  --events <a,b>     Only these events (message.received,message.failed…). Default: all.
-  --from <seq>       Start after this event number (the "Resume with" line printed on exit).
-                     Default: from now.
-  --interval <ms>    Wait between two reads when nothing is new. Default: ${DEFAULT_INTERVAL_MS}.
-  --verbose          Also print each event's data.
-
-The key needs the admin role: it reads the event log (GET /events). Events of
-every client of the account arrive, unless --tenant names one or the key is
-pinned to one. A call your server answers with a non-2xx status, or not at
-all, is shown and not retried.
+  ${usage(command)}${command.flags?.length ? ' [options]' : ''}
+${command.help ? `\nOptions\n${command.help}\n` : ''}
+Options for every command: \`nodium --help\`.
 `;
-const HELP_SEND = `nodium send: send a WhatsApp message.
+}
+function groupHelp(noun, commands) {
+    return `nodium ${noun}
 
-Usage
-  nodium send --channel <id> --to <+33612345678> --text "Hello"
-  nodium send --channel <id> --to <+33612345678> --template order_ready --language en --var 1=Karim
+${table(commands.map(c => [`  ${usage(c)}`, c.summary])).join('\n')}
 
-Options
-  --channel <id>          The number to send from (GET /channels). Required.
-  --to <number>           The recipient, in international format. Or --recipient wa:… for a
-                          contact who shows no number.
-  --text <text>           Free text: only within 24 hours of the person's last message.
-  --template <name>       An approved template: the only way to write first.
-  --language <code>       The template language, for example en or fr.
-  --var <n=value>         A template variable (repeat it): --var 1=Karim --var 2=Friday.
-  --idempotency-key <k>   Your own anti-duplicate key (8 to 200 characters).
+More: nodium help ${noun} <${commands.map(c => c.path[1]).join('|')}>
 `;
+}
 function packageVersion() {
     try {
         const file = fileURLToPath(new URL('../package.json', import.meta.url));
@@ -76,74 +69,98 @@ function packageVersion() {
         return 'unknown';
     }
 }
-/** Les drapeaux qu'accepte toute commande. */
-const COMMON = ['key', 'tenant', 'base-url', 'no-color', 'help'];
+const NO_IO = {
+    ask: async () => '',
+    readSecret: async () => '',
+    readStdin: async () => ''
+};
+/**
+ * La commande nommée par les mots de la ligne : `templates wait` ou `send`.
+ * Rend aussi les mots qui restent (ses arguments).
+ */
+export function resolveCommand(words) {
+    const [noun, verb, ...more] = words;
+    if (!noun)
+        return { command: null, rest: [], group: [] };
+    const group = findCommands([noun]);
+    const exact = group.find(c => c.path.length === 1);
+    if (exact)
+        return { command: exact, rest: words.slice(1), group };
+    const command = verb ? group.find(c => c.path[1] === verb) ?? null : null;
+    return { command, rest: command ? more : [], group };
+}
 export async function run(argv, context) {
     const { output, env } = context;
     let baseUrl = env.NODIUM_BASE_URL || DEFAULT_BASE_URL;
+    let json = false;
     try {
         const args = parseArgs(argv);
+        json = outputMode(flag(args, 'output'), Boolean(context.stdoutIsTty)) === 'json';
         if (hasFlag(args, 'version')) {
             output.out(packageVersion());
             return 0;
         }
-        if (!args.command || args.command === 'help') {
-            output.out(HELP);
-            return args.command || hasFlag(args, 'help') ? 0 : 2;
+        // `nodium help templates wait` vaut `nodium templates wait --help`.
+        const asksHelp = args.command === 'help' || hasFlag(args, 'help');
+        const words = args.command === 'help' ? args.positionals : [args.command ?? '', ...args.positionals].filter(Boolean);
+        if (!words.length) {
+            output.out(globalHelp());
+            return asksHelp ? 0 : 2;
         }
-        if (args.command !== 'listen' && args.command !== 'send') {
-            throw new UsageError(`Unknown command "${args.command}". Try \`nodium --help\`.`);
+        const { command, rest, group } = resolveCommand(words);
+        if (!command) {
+            if (!group.length)
+                throw new UsageError(`Unknown command "${words[0]}". Try \`nodium --help\`.`);
+            if (asksHelp || words.length === 1) {
+                output.out(groupHelp(words[0], group));
+                return asksHelp ? 0 : 2;
+            }
+            throw new UsageError(`Unknown command "${words.slice(0, 2).join(' ')}". Try \`nodium help ${words[0]}\`.`);
         }
-        if (hasFlag(args, 'help')) {
-            output.out(args.command === 'listen' ? HELP_LISTEN : HELP_SEND);
+        if (asksHelp) {
+            output.out(commandHelp(command));
             return 0;
         }
-        baseUrl = flag(args, 'base-url') ?? baseUrl;
-        const key = flag(args, 'key') ?? env.NODIUM_KEY;
-        if (!key)
-            throw new UsageError('No API key: set NODIUM_KEY (or pass --key). Create one in the console, under Settings › API keys.');
-        const nodium = new Nodium(key, { baseUrl, ...(context.fetch ? { fetch: context.fetch } : {}) });
-        const tenant = flag(args, 'tenant');
-        const scope = tenant ? nodium.as(tenant) : nodium;
-        return args.command === 'listen'
-            ? await runListen(args, scope, baseUrl, env, context)
-            : await runSend(args, scope, output);
+        const name = command.path.join(' ');
+        const commandArgs = { ...args, command: name, positionals: rest };
+        rejectUnknown(commandArgs, [...COMMON, ...(command.flags ?? [])], name, command.args?.length ?? 0);
+        const path = context.configPath ?? defaultConfigPath(env);
+        const config = readConfig(path);
+        baseUrl = flag(args, 'base-url') ?? (env.NODIUM_BASE_URL || config.baseUrl || DEFAULT_BASE_URL);
+        let client = null;
+        const nodium = () => {
+            if (!client) {
+                const { key } = resolveKey(flag(args, 'key'), env, config);
+                client = new Nodium(key, { baseUrl, ...(context.fetch ? { fetch: context.fetch } : {}) });
+            }
+            return client;
+        };
+        const io = context.io ?? NO_IO;
+        const interactive = Boolean(context.interactive);
+        const ctx = {
+            args: commandArgs, output, json, interactive, env, signal: context.signal, io,
+            ...(context.fetch ? { fetch: context.fetch } : {}),
+            sleep: context.sleep ?? pause,
+            baseUrl, configPath: path, config,
+            nodium,
+            scope: () => {
+                const tenant = flag(args, 'tenant');
+                return tenant ? nodium().as(tenant) : nodium();
+            },
+            print: (data, human, next) => {
+                if (json)
+                    return output.out(JSON.stringify(data, null, 2));
+                human();
+                printNext(output, next);
+            },
+            confirm: what => confirmWrite(what, { yes: hasFlag(args, 'yes'), interactive, ask: io.ask })
+        };
+        if (command.needsKey !== false)
+            nodium();
+        return await command.run(ctx);
     }
     catch (error) {
-        output.err(paint(output, 'red', describeError(error, baseUrl)));
+        output.err(json ? errorJson(error) : paint(output, 'red', describeError(error, baseUrl)));
         return error instanceof UsageError ? 2 : 1;
     }
 }
-async function runListen(args, scope, baseUrl, env, context) {
-    rejectUnknown(args, [...COMMON, 'forward', 'secret', 'events', 'from', 'interval', 'verbose']);
-    const forward = parseForwardUrl(flag(args, 'forward'));
-    const events = parseEventFilter(flag(args, 'events'));
-    const from = readInteger(args, 'from', 0);
-    const interval = readInteger(args, 'interval', 1);
-    const summary = await listen({
-        scope, baseUrl, forward, events,
-        secret: flag(args, 'secret') ?? env.NODIUM_WEBHOOK_SECRET ?? null,
-        from,
-        intervalMs: interval ?? DEFAULT_INTERVAL_MS,
-        verbose: hasFlag(args, 'verbose'),
-        signal: context.signal,
-        output: context.output,
-        ...(context.fetch ? { fetch: context.fetch } : {})
-    });
-    context.output.out(`Stopped. ${summary.forwarded} forwarded, ${summary.failed} not answered with a 2xx. Resume with --from ${summary.after}.`);
-    return 0;
-}
-async function runSend(args, scope, output) {
-    rejectUnknown(args, [...COMMON, 'channel', 'to', 'recipient', 'text', 'template', 'language', 'var', 'idempotency-key']);
-    return await send(scope, readSendInput(args), output);
-}
-/** Un entier au moins égal à `min`, ou `null` si le drapeau est absent. */
-function readInteger(args, name, min) {
-    const text = flag(args, name);
-    if (text === undefined)
-        return null;
-    const value = Number(text);
-    if (!Number.isInteger(value) || value < min)
-        throw new UsageError(`--${name} must be a whole number, ${min} or more.`);
-    return value;
-}

package/dist/send.js

@@ -1,9 +1,11 @@
-import { UsageError, flag, flagAll } from './args.js';
+import { UsageError, flag, flagAll, hasFlag } from './args.js';
+import { readJsonInput } from './input.js';
 import { paint } from './output.js';
 /**
- * `nodium send` : un message, pour essayer. Du texte libre (dans les 24 h qui
- * suivent le dernier message de la personne) ou un modèle approuvé (le seul
- * envoi possible pour écrire en premier).
+ * `nodium send` : un message. Du texte libre (dans les 24 h qui suivent le
+ * dernier message de la personne) ou un modèle approuvé (le seul envoi
+ * possible pour écrire en premier) par drapeaux ; tout autre message (fichier,
+ * boutons, liste…) en JSON, par `--input` ou `--stdin`.
  *
  * ⚠️ Un envoi refusé par Meta répond HTTP 200 : la commande lit
  *    `message.status` et sort en erreur (code 1) quand il vaut `failed`.
@@ -44,27 +46,67 @@ export function readSendInput(args) {
         ...(Object.keys(variables).length ? { variables } : {})
     };
 }
+/** Les drapeaux qui décrivent le message ; avec `--input` ou `--stdin`, aucun ne se donne. */
+const MESSAGE_FLAGS = ['channel', 'to', 'recipient', 'text', 'template', 'language', 'var', 'idempotency-key'];
+/** Le message à envoyer : le JSON de `--input`/`--stdin` (un `SendInput`), sinon les drapeaux. */
+async function readMessage(ctx) {
+    const json = await readJsonInput(ctx);
+    if (!json)
+        return readSendInput(ctx.args);
+    const mixed = MESSAGE_FLAGS.find(name => hasFlag(ctx.args, name));
+    if (mixed)
+        throw new UsageError(`--${mixed} cannot be mixed with --input or --stdin: put everything in the JSON.`);
+    if (typeof json.channelId !== 'string' || (typeof json.to !== 'string' && typeof json.recipient !== 'string')) {
+        throw new UsageError('The JSON needs "channelId" and "to" (or "recipient"), plus "type" and its fields.');
+    }
+    return json;
+}
 /** Envoie, écrit le résultat, rend le code de sortie. */
-export async function send(scope, input, output) {
-    const result = await scope.messages.send(input);
-    const message = result.message;
+async function send(ctx) {
+    const input = await readMessage(ctx);
     const target = input.to ?? input.recipient;
-    if (!message) {
-        output.out(`Sent to ${target}.`);
-        return 0;
-    }
-    if (message.status === 'failed') {
-        output.err(paint(output, 'red', `Message ${message.id} to ${target} failed.`));
-        if (message.errorInfo) {
-            output.err(`${message.errorInfo.title}`);
-            output.err(`What to do (${message.errorInfo.actor}): ${message.errorInfo.action}`);
-        }
-        else if (message.error) {
-            output.err(message.error);
+    await ctx.confirm(`Send a ${input.type ?? 'message'} to ${target} from number ${input.channelId}`);
+    const result = await ctx.scope().messages.send(input);
+    const message = result.message;
+    const failed = message?.status === 'failed';
+    ctx.print(result, () => {
+        const { output } = ctx;
+        if (!message)
+            return output.out(`Sent to ${target}.`);
+        if (failed) {
+            output.err(paint(output, 'red', `Message ${message.id} to ${target} failed.`));
+            if (message.errorInfo) {
+                output.err(`${message.errorInfo.title}`);
+                output.err(`What to do (${message.errorInfo.actor}): ${message.errorInfo.action}`);
+            }
+            else if (message.error) {
+                output.err(message.error);
+            }
+            return;
         }
-        return 1;
-    }
-    output.out(`${paint(output, 'green', message.status)}  message ${message.id} to ${target}${result.duplicate ? ' (already sent with this idempotency key: nothing left again)' : ''}`);
-    output.out(paint(output, 'dim', `Follow it: GET /messages/${message.id}, or the message.delivered and message.read events.`));
-    return 0;
+        output.out(`${paint(output, 'green', message.status)}  message ${message.id} to ${target}${result.duplicate ? ' (already sent with this idempotency key: nothing left again)' : ''}`);
+    }, message ? [`nodium messages get ${message.id}`] : []);
+    return failed ? 1 : 0;
 }
+export const SEND_COMMAND = {
+    path: ['send'], summary: 'Send a WhatsApp message. Asks first.',
+    flags: [...MESSAGE_FLAGS, 'input', 'stdin'],
+    help: `  --channel <id>          The number to send from (\`nodium numbers list\`). Required.
+  --to <number>           The recipient, in international format. Or --recipient wa:… for a
+                          contact who shows no number.
+  --text <text>           Free text: only within 24 hours of the person's last message.
+  --template <name>       An approved template: the only way to write first.
+  --language <code>       The template language, for example en or fr.
+  --var <n=value>         A template variable (repeat it): --var 1=Karim --var 2=Friday.
+  --idempotency-key <k>   Your own anti-duplicate key (8 to 200 characters).
+  --input <file.json>     Any message as JSON (image, buttons, list, location…), or --stdin.
+                          The fields of POST /messages: channelId, to, type and its fields.
+
+Examples
+  nodium send --channel <id> --to +33612345678 --text "Hello"
+  nodium send --channel <id> --to +33612345678 --template order_ready --language en --var 1=Karim
+  echo '{"channelId":"<id>","to":"+33612345678","type":"image","mediaId":"<id>"}' | nodium send --stdin --yes
+
+A send Meta refuses answers HTTP 200: the command reads the message status and exits 1.`,
+    run: send
+};

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@nodium.io/cli",
-  "version": "0.1.0",
-  "description": "The nodium command: replay your Nodium webhooks to your local server, signed like production, and send WhatsApp messages from the terminal.",
+  "version": "0.2.1",
+  "description": "The nodium command: the Nodium WhatsApp API from your terminal — numbers, conversations, templates, webhooks, clients, Flows — and your webhooks replayed to your local server, signed like production.",
   "keywords": ["nodium", "cli", "whatsapp", "whatsapp-api", "whatsapp-cloud-api", "webhooks", "local-development"],
   "homepage": "https://nodium.io/en/docs/api",
   "license": "MIT",
   "author": "By-Tech.io",
   "type": "module",
-  "engines": { "node": ">=18" },
+  "engines": { "node": ">=20" },
   "bin": { "nodium": "./dist/index.js" },
   "files": ["dist", "README.md", "LICENSE"],
   "publishConfig": { "access": "public" },
@@ -17,7 +17,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@nodium.io/whatsapp": "^0.1.0"
+    "@nodium.io/whatsapp": "^0.3.1"
   },
   "devDependencies": {
     "@types/node": "^26.4.0",