@nodium.io/cli 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 By-Tech.io
+
+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

@@ -1,3 +1,64 @@
-# Temporary Holding Version
+# @nodium.io/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm version](https://img.shields.io/npm/v/@nodium.io/cli.svg)](https://www.npmjs.com/package/@nodium.io/cli)
+[![license](https://img.shields.io/npm/l/@nodium.io/cli.svg)](./LICENSE)
+
+The `nodium` command for the [Nodium](https://nodium.io) WhatsApp API: replay
+your webhooks to your local server, signed like production, and send WhatsApp
+messages from the terminal. Built on
+[`@nodium.io/whatsapp`](https://www.npmjs.com/package/@nodium.io/whatsapp).
+
+## Install
+
+```bash
+npm install -g @nodium.io/cli   # or run it once: npx @nodium.io/cli …
+export NODIUM_KEY=nod_…         # Settings › API keys in the console
+```
+
+## Listen
+
+No tunnel, no public address: it reads your events from Nodium and replays
+each one to a URL on your machine.
+
+```bash
+export NODIUM_KEY=nod_…
+nodium listen --forward http://localhost:3000/webhook --secret whsec_… --events message.received,message.failed
+```
+
+```
+Listening from now → http://localhost:3000/webhook
+10:32:01  message.received         200     12 ms  evt_0123…
+10:32:07  message.failed           500      4 ms  evt_4567… [crm-4187]
+```
+
+- Each call is the body of a real delivery and carries the real headers
+  (`X-Nodium-Event`, `X-Nodium-Delivery`, and `X-Nodium-Signature: t=…,v1=…` when
+  you give `--secret`, or `NODIUM_WEBHOOK_SECRET`). The signature is computed
+  locally with the secret you give: use the one of your webhook subscription, or
+  any string your code also uses to verify.
+- It reads the event log (`GET /events`) from a cursor, so a dropped connection
+  loses nothing; `Ctrl+C` stops it and prints the number to resume from
+  (`--from <seq>`). The key needs the `admin` role.
+- It acts on the events of every client of the account, unless `--tenant <id>`
+  names one or the key is pinned to one. `--events` filters; `--verbose` prints
+  each event's `data`; `--interval <ms>` sets the polling pace (default 1000).
+- A call your server answers with a non-`2xx` status, or not at all, is shown
+  and not retried.
+
+## Send
+
+To make something happen, send a message to yourself:
+
+```bash
+nodium send --channel <id> --to +33612345678 --text "Hello"
+nodium send --channel <id> --to +33612345678 --template order_ready --language en --var 1=Karim
+```
+
+`--base-url` (or `NODIUM_BASE_URL`) changes the API address; `nodium --help` and
+`nodium listen --help` list everything. Exit code 0 on success, 1 when Nodium or
+Meta refuses (the `error.code` and the request id are printed), 2 for a wrong
+command line.
+
+## License
+
+MIT © By-Tech.io

package/dist/args.js

@@ -0,0 +1,80 @@
+/**
+ * Les arguments de la ligne de commande, sans dépendance : `--nom valeur`,
+ * `--nom=valeur`, un drapeau sans valeur (`--verbose`), `--` pour finir.
+ *
+ * ⚠️ Un drapeau qui prend une valeur prend le mot SUIVANT tel quel, même s'il
+ *    commence par `--` : `--text "--hello"` envoie `--hello`.
+ */
+/** Une faute d'usage : message lisible, code de sortie 2, aucune trace d'appel. */
+export class UsageError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'UsageError';
+    }
+}
+/** Les drapeaux qui ne prennent jamais de valeur. */
+const SWITCHES = new Set(['help', 'version', 'verbose', 'no-color']);
+/** Les abréviations d'une lettre. */
+const SHORT = { h: 'help', v: 'version' };
+export function parseArgs(argv) {
+    const flags = new Map();
+    const words = [];
+    const add = (name, value) => flags.set(name, [...(flags.get(name) ?? []), value]);
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '--') {
+            words.push(...argv.slice(i + 1));
+            break;
+        }
+        const short = /^-([a-zA-Z])$/.exec(arg);
+        if (short) {
+            const name = SHORT[short[1]];
+            if (!name)
+                throw new UsageError(`Unknown option ${arg}.`);
+            add(name, 'true');
+            continue;
+        }
+        if (!arg.startsWith('--')) {
+            words.push(arg);
+            continue;
+        }
+        const eq = arg.indexOf('=');
+        const name = eq < 0 ? arg.slice(2) : arg.slice(2, eq);
+        if (!name)
+            throw new UsageError(`Unknown option ${arg}.`);
+        if (SWITCHES.has(name)) {
+            add(name, 'true');
+            continue;
+        }
+        if (eq >= 0) {
+            add(name, arg.slice(eq + 1));
+            continue;
+        }
+        const value = argv[++i];
+        if (value === undefined)
+            throw new UsageError(`--${name} needs a value.`);
+        add(name, value);
+    }
+    return { command: words.shift() ?? null, positionals: words, flags };
+}
+/** La dernière valeur d'un drapeau, ou `undefined`. */
+export function flag(args, name) {
+    const values = args.flags.get(name);
+    return values?.[values.length - 1];
+}
+/** Toutes les valeurs d'un drapeau répété. */
+export function flagAll(args, name) {
+    return args.flags.get(name) ?? [];
+}
+export function hasFlag(args, name) {
+    return args.flags.has(name);
+}
+/** Refuse un drapeau que la commande ne connaît pas : une faute de frappe ne passe pas en silence. */
+export function rejectUnknown(args, allowed) {
+    for (const name of args.flags.keys()) {
+        if (!allowed.includes(name))
+            throw new UsageError(`Unknown option --${name} for \`${args.command}\`. Try \`nodium ${args.command} --help\`.`);
+    }
+    if (args.positionals.length)
+        throw new UsageError(`Unexpected argument "${args.positionals[0]}". Try \`nodium ${args.command} --help\`.`);
+}

package/dist/index.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+import { run } from './run.js';
+/**
+ * Le point d'entrée de `nodium` (`bin` du paquet). Ctrl+C et SIGTERM arrêtent
+ * proprement : la boucle de `listen` finit l'événement en cours, puis la
+ * commande dit où reprendre. Un second Ctrl+C sort tout de suite.
+ */
+const argv = process.argv.slice(2);
+const controller = new AbortController();
+const stop = () => {
+    if (controller.signal.aborted)
+        process.exit(130);
+    controller.abort();
+    process.stderr.write('\nStopping…\n');
+};
+process.on('SIGINT', stop);
+process.on('SIGTERM', stop);
+const color = Boolean(process.stdout.isTTY) && !process.env.NO_COLOR && !argv.includes('--no-color');
+run(argv, {
+    env: process.env,
+    signal: controller.signal,
+    output: {
+        out: text => process.stdout.write(`${text}\n`),
+        err: text => process.stderr.write(`${text}\n`),
+        color
+    }
+}).then((code) => { process.exitCode = code; }, (error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+});

package/dist/listen.js

@@ -0,0 +1,200 @@
+import { NodiumError, WEBHOOK_EVENTS } from '@nodium.io/whatsapp';
+import { signWebhook } from '@nodium.io/whatsapp/server';
+import { UsageError } from './args.js';
+import { clock, paint } from './output.js';
+/**
+ * `nodium listen` : les événements de votre compte, rejoués vers une adresse
+ * locale, signés comme en production. Aucun tunnel : c'est la commande qui
+ * interroge Nodium, jamais l'inverse.
+ *
+ * Elle lit le JOURNAL D'ÉVÉNEMENTS (`GET /events`, depuis un curseur) : chaque
+ * ligne est l'enveloppe exacte d'un webhook, plus son `seq`. Le direct du
+ * journal de la console (`GET /events/stream`) porte d'autres lignes (messages,
+ * livraisons, appels) et non ces enveloppes : il ne sert pas ici.
+ *
+ * ⚠️ Le corps envoyé est l'enveloppe SANS `seq`, sérialisée une fois ; la
+ *    signature est calculée sur ces octets (`t=<s>,v1=hmac-sha256(secret, "<t>.<corps>")`,
+ *    la même fonction que `signWebhook` de `@nodium.io/whatsapp/server`). Un récepteur qui vérifie sur
+ *    le corps brut accepte l'appel comme en production.
+ * ⚠️ Le curseur avance après chaque page rejouée, que l'adresse locale ait
+ *    répondu ou non : un échec local n'est pas rejoué (production le fait ;
+ *    ici, relancez avec `--from <seq>` ou rejouez depuis la console).
+ * ⚠️ `message.imported` ne sonne jamais en production : il n'est rejoué que si
+ *    `--events` le nomme.
+ */
+/** Le délai d'attente de l'adresse locale : celui de Nodium en production. */
+export const FORWARD_TIMEOUT_MS = 10_000;
+/** Événements lus par appel (le défaut de l'API est 100, son plafond 500). */
+const PAGE = 100;
+/** Attente entre deux lectures du journal quand il n'y a rien de neuf, en millisecondes. */
+export const DEFAULT_INTERVAL_MS = 1000;
+const MIN_INTERVAL_MS = 250;
+/** L'attente maximale entre deux essais quand Nodium est injoignable. */
+const BACKOFF_CAP_MS = 15_000;
+/**
+ * L'appel que Nodium ferait : le corps (l'enveloppe, sans `seq`) et les
+ * en-têtes. Sans `secret`, pas d'en-tête de signature.
+ */
+export function buildDelivery(entry, secret, nowSeconds = Math.floor(Date.now() / 1000)) {
+    const envelope = Object.fromEntries(Object.entries(entry).filter(([key]) => key !== 'seq'));
+    const body = JSON.stringify(envelope);
+    return {
+        body,
+        headers: {
+            'Content-Type': 'application/json',
+            'User-Agent': 'Nodium-Webhooks/1',
+            'X-Nodium-Event': entry.event,
+            'X-Nodium-Delivery': `local-${entry.id}`,
+            ...(secret ? { 'X-Nodium-Signature': signWebhook(secret, nowSeconds, body) } : {})
+        }
+    };
+}
+/**
+ * `--events message.received,message.failed` → l'ensemble voulu ; `null` pour
+ * « tous ceux qui sonnent ». `*` veut dire tous, comme dans un abonnement.
+ */
+export function parseEventFilter(text) {
+    if (text === undefined)
+        return null;
+    const names = text.split(',').map(name => name.trim()).filter(Boolean);
+    if (!names.length)
+        throw new UsageError('--events needs at least one event name.');
+    if (names.includes('*'))
+        return null;
+    const known = new Set(WEBHOOK_EVENTS);
+    const unknown = names.filter(name => !known.has(name));
+    if (unknown.length)
+        throw new UsageError(`Unknown event ${unknown.map(n => `"${n}"`).join(', ')}. Known: ${WEBHOOK_EVENTS.join(', ')}.`);
+    return new Set(names);
+}
+/** Cet événement est-il rejoué ? Sans filtre : tous, sauf l'historique importé. */
+export function wanted(filter, event) {
+    return filter ? filter.has(event) : event !== 'message.imported';
+}
+/** L'adresse locale : http ou https, rien d'autre. */
+export function parseForwardUrl(text) {
+    if (!text)
+        throw new UsageError('--forward <url> is required, for example --forward http://localhost:3000/webhook.');
+    let url;
+    try {
+        url = new URL(text);
+    }
+    catch {
+        throw new UsageError(`--forward "${text}" is not a valid URL. Example: http://localhost:3000/webhook.`);
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:')
+        throw new UsageError('--forward must be an http:// or https:// URL.');
+    return url.toString();
+}
+async function forwardOne(url, delivery, fetchImpl) {
+    const started = performance.now();
+    try {
+        const response = await fetchImpl(url, {
+            method: 'POST',
+            headers: delivery.headers,
+            body: delivery.body,
+            redirect: 'manual',
+            signal: AbortSignal.timeout(FORWARD_TIMEOUT_MS)
+        });
+        await response.arrayBuffer().catch(() => { });
+        return { status: response.status, ms: Math.round(performance.now() - started), error: null };
+    }
+    catch (cause) {
+        const ms = Math.round(performance.now() - started);
+        if (cause?.name === 'TimeoutError' || cause?.name === 'AbortError') {
+            return { status: null, ms, error: `no answer within ${FORWARD_TIMEOUT_MS / 1000} s (Nodium waits as long in production)` };
+        }
+        const code = cause?.cause?.code ?? cause?.code;
+        if (code === 'ECONNREFUSED')
+            return { status: null, ms, error: `connection refused: is your server listening on ${new URL(url).host}?` };
+        return { status: null, ms, error: String(cause?.cause?.message ?? cause?.message ?? cause) };
+    }
+}
+/** Une attente que l'arrêt interrompt. */
+export function pause(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal.aborted)
+            return resolve();
+        const done = () => {
+            clearTimeout(timer);
+            signal.removeEventListener('abort', done);
+            resolve();
+        };
+        const timer = setTimeout(done, ms);
+        signal.addEventListener('abort', done, { once: true });
+    });
+}
+/** Ce qui ne se réessaie pas : la clé, le rôle, le client visé. */
+function isFatal(error) {
+    return error instanceof NodiumError && (error.status === 401 || error.status === 403 || error.status === 404);
+}
+export async function listen(options) {
+    const { scope, signal, output } = options;
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    const sleep = options.sleep ?? pause;
+    const intervalMs = Math.max(MIN_INTERVAL_MS, options.intervalMs);
+    const summary = { forwarded: 0, failed: 0, after: 0 };
+    // Un premier appel sans `after` rend la tête du journal : le curseur du « maintenant ».
+    summary.after = options.from ?? (await scope.events.list()).next_after;
+    output.out(`${paint(output, 'bold', 'Listening')} ${options.from === null ? 'from now' : `after event #${options.from}`} → ${options.forward}`);
+    output.out(paint(output, 'dim', options.secret
+        ? 'Calls are signed with your secret: verify X-Nodium-Signature as in production.'
+        : 'No --secret: calls carry no X-Nodium-Signature header.'));
+    output.out(paint(output, 'dim', 'Press Ctrl+C to stop.'));
+    let failures = 0;
+    while (!signal.aborted) {
+        let full;
+        try {
+            const page = await scope.events.list(summary.after, PAGE);
+            if (failures) {
+                output.out(paint(output, 'green', 'Connection with Nodium restored.'));
+                failures = 0;
+            }
+            for (const entry of page.data) {
+                if (signal.aborted)
+                    break;
+                if (wanted(options.events, entry.event))
+                    await deliver(entry, options, fetchImpl, summary);
+                summary.after = entry.seq;
+            }
+            // Une page rejouée en entier : tout ce qui précède `next_after` est rendu ou n'est pas à vous.
+            if (!signal.aborted)
+                summary.after = page.next_after;
+            full = page.data.length >= PAGE;
+        }
+        catch (error) {
+            if (error instanceof NodiumError && error.code === 'cursor_expired') {
+                // Le journal garde 30 jours : un curseur plus vieux est repris à la tête.
+                summary.after = (await scope.events.list()).next_after;
+                output.err(paint(output, 'yellow', 'The cursor is older than the event log (30 days): restarting from now.'));
+                continue;
+            }
+            if (isFatal(error))
+                throw error;
+            failures++;
+            const wait = Math.min(BACKOFF_CAP_MS, intervalMs * 2 ** failures);
+            output.err(paint(output, 'yellow', `Nodium is unreachable (${error instanceof NodiumError ? error.code : 'error'}); retrying in ${Math.round(wait / 1000)} s from event #${summary.after}.`));
+            await sleep(wait, signal);
+            continue;
+        }
+        if (!full)
+            await sleep(intervalMs, signal);
+    }
+    return summary;
+}
+/** Rejoue un événement et en écrit la ligne. */
+async function deliver(entry, options, fetchImpl, summary) {
+    const { output } = options;
+    const result = await forwardOne(options.forward, buildDelivery(entry, options.secret), fetchImpl);
+    summary.forwarded++;
+    const ok = result.status !== null && result.status >= 200 && result.status < 300;
+    if (!ok)
+        summary.failed++;
+    const client = entry.external_id ? ` [${entry.external_id}]` : '';
+    const status = paint(output, ok ? 'green' : 'red', result.status === null ? 'ERR' : String(result.status));
+    output.out(`${paint(output, 'dim', clock())}  ${entry.event.padEnd(24)} ${status}  ${String(result.ms).padStart(5)} ms  ${paint(output, 'dim', entry.id + client)}`);
+    if (result.error)
+        output.out(`          ${paint(output, 'red', result.error)}`);
+    if (options.verbose)
+        output.out(paint(output, 'dim', JSON.stringify(entry.data, null, 2).replace(/^/gm, '          ')));
+}

package/dist/output.js

@@ -0,0 +1,39 @@
+import { NodiumError } from '@nodium.io/whatsapp';
+import { UsageError } from './args.js';
+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;
+}
+/** L'heure locale, `HH:MM:SS`. */
+export function clock(date = new Date()) {
+    return date.toTimeString().slice(0, 8);
+}
+/** Les codes qui n'ont pas de ligne dans le guide des erreurs. */
+const NO_GUIDE = new Set(['unknown_error', 'network_error', 'timeout']);
+/**
+ * Une erreur en quelques lignes : le statut et le `code` (stable, c'est lui
+ * qu'on cherche dans la documentation), le texte, l'identifiant à donner au
+ * support, et la ligne du guide des erreurs.
+ */
+export function describeError(error, baseUrl) {
+    if (error instanceof UsageError)
+        return error.message;
+    if (!(error instanceof NodiumError))
+        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`).');
+    if (error.retryAfter !== null)
+        lines.push(`Retry in ${error.retryAfter} s.`);
+    if (error.requestId)
+        lines.push(`Request id: ${error.requestId}`);
+    if (error.status > 0 && !NO_GUIDE.has(error.code)) {
+        try {
+            lines.push(`More: ${new URL(baseUrl).origin}/en/docs/api/guide/responses#${error.code}`);
+        }
+        catch { /* adresse illisible : pas de lien */ }
+    }
+    return lines.join('\n');
+}

package/dist/run.js

@@ -0,0 +1,149 @@
+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';
+/**
+ * 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 clé se donne de préférence par `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 "…"
+
+Commands
+  listen   Replay your events to a local URL, signed like production: no tunnel.
+  send     Send a WhatsApp message, to try things.
+
+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.
+`;
+const HELP_LISTEN = `nodium listen: replay your events to your own server, without a tunnel.
+
+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.
+`;
+const HELP_SEND = `nodium send: send a WhatsApp message.
+
+Usage
+  nodium send --channel <id> --to <+33612345678> --text "Hello"
+  nodium send --channel <id> --to <+33612345678> --template order_ready --language en --var 1=Karim
+
+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).
+`;
+function packageVersion() {
+    try {
+        const file = fileURLToPath(new URL('../package.json', import.meta.url));
+        return String(JSON.parse(readFileSync(file, 'utf8')).version);
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/** Les drapeaux qu'accepte toute commande. */
+const COMMON = ['key', 'tenant', 'base-url', 'no-color', 'help'];
+export async function run(argv, context) {
+    const { output, env } = context;
+    let baseUrl = env.NODIUM_BASE_URL || DEFAULT_BASE_URL;
+    try {
+        const args = parseArgs(argv);
+        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;
+        }
+        if (args.command !== 'listen' && args.command !== 'send') {
+            throw new UsageError(`Unknown command "${args.command}". Try \`nodium --help\`.`);
+        }
+        if (hasFlag(args, 'help')) {
+            output.out(args.command === 'listen' ? HELP_LISTEN : HELP_SEND);
+            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);
+    }
+    catch (error) {
+        output.err(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

@@ -0,0 +1,70 @@
+import { UsageError, flag, flagAll } from './args.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).
+ *
+ * ⚠️ Un envoi refusé par Meta répond HTTP 200 : la commande lit
+ *    `message.status` et sort en erreur (code 1) quand il vaut `failed`.
+ */
+/** Ce que la commande a lu de la ligne de commande, vérifié. */
+export function readSendInput(args) {
+    const channelId = flag(args, 'channel');
+    if (!channelId)
+        throw new UsageError('--channel <id> is required: the number to send from (`GET /channels`).');
+    const to = flag(args, 'to');
+    const recipient = flag(args, 'recipient');
+    if (!to && !recipient)
+        throw new UsageError('--to <+33612345678> is required (or --recipient wa:… for a contact without a number).');
+    if (to && recipient)
+        throw new UsageError('Give --to or --recipient, never both.');
+    const address = to ? { to } : { recipient: recipient };
+    const text = flag(args, 'text');
+    const template = flag(args, 'template');
+    if (text !== undefined && template)
+        throw new UsageError('Give --text or --template, not both.');
+    if (text === undefined && !template)
+        throw new UsageError('Nothing to send: give --text "…" or --template <name>.');
+    const idempotencyKey = flag(args, 'idempotency-key');
+    const base = { channelId, ...(idempotencyKey ? { idempotencyKey } : {}) };
+    if (text !== undefined)
+        return { ...base, ...address, type: 'text', text };
+    const variables = {};
+    for (const pair of flagAll(args, 'var')) {
+        const eq = pair.indexOf('=');
+        if (eq <= 0)
+            throw new UsageError(`--var "${pair}" must look like 1=Karim (the number of the {{variable}}, then its value).`);
+        variables[pair.slice(0, eq)] = pair.slice(eq + 1);
+    }
+    const language = flag(args, 'language');
+    return {
+        ...base, ...address, type: 'template', templateName: template,
+        ...(language ? { templateLanguage: language } : {}),
+        ...(Object.keys(variables).length ? { variables } : {})
+    };
+}
+/** 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;
+    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);
+        }
+        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;
+}

package/package.json

@@ -1,6 +1,26 @@
 {
   "name": "@nodium.io/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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.",
+  "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" },
+  "bin": { "nodium": "./dist/index.js" },
+  "files": ["dist", "README.md", "LICENSE"],
+  "publishConfig": { "access": "public" },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "typecheck": "node scripts/build.mjs --check",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@nodium.io/whatsapp": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.4.0",
+    "typescript": "^5.9.2"
+  }
+}