@nodium.io/cli 0.0.0-stage → 0.2.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,168 @@
-# 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: check
+your setup, read your numbers and conversations, ship templates, webhooks and
+Flows, add clients — and replay your webhooks to your local server, signed like
+production. A thin layer over
+[`@nodium.io/whatsapp`](https://www.npmjs.com/package/@nodium.io/whatsapp):
+same key, same client header, same errors. Node 20 or later.
+
+## Install
+
+```bash
+npm install -g @nodium.io/cli   # or run it once: npx @nodium.io/cli …
+nodium login                    # paste your key (nod_…, Settings › API keys in the console)
+nodium status                   # what the key is, your numbers, your webhooks, the next step
+```
+
+`nodium login` checks the key with Nodium and saves it to
+`$XDG_CONFIG_HOME/nodium/config.json` (`~/.config/nodium/config.json` by
+default), readable by you only. The key is looked up in this order: `--key`,
+then `NODIUM_KEY`, then that file. It is never printed in full. `nodium logout`
+deletes the file.
+
+## Commands
+
+```
+nodium login | logout | status | health
+nodium events [--after <seq>] [--limit <n>]
+
+nodium numbers list [--all] | get <id> | check <id>
+nodium conversations list [--channel <id>] [--contact <id>] [--phone <n>] | get <id>
+nodium messages list <conversationId> | get <id>
+nodium contacts list [--search <text>] | get <id>
+nodium templates list [--all] | get <id> | new --input <file> | update <id> --input <file>
+nodium templates deploy <id> | refresh <id> | wait <id> [--timeout 10m] | delete <id>
+nodium webhooks list | deliveries [--failed] | new --url <url> --event <name> | update <id>
+nodium webhooks delete <id> | test <id> | redeliver <deliveryId> | rotate-secret <id>
+nodium tenants list | get <id> | new --name <name> [--external-id <id>] [--connect-link]
+nodium connect-link new --tenant <id>
+nodium flows deploy <file.json> [--name <name>] [--id <flowId>] [--publish]
+
+nodium send --channel <id> --to <+33…> --text "…" | --template <name> | --input <file> | --stdin
+nodium listen --forward <url> [--secret <whsec_…>] [--events a,b]
+```
+
+`nodium help <command>` (or `--help`) describes each one. Lists show the newest
+20; `--limit <n>` shows more, following the pages for you.
+
+Options for every command:
+
+- `--tenant <id>` acts for one of your clients (its id or your own
+  `externalId`). Without it, a command acts on "My company", or on the client
+  the key is pinned to.
+- `--output json|human` — see below.
+- `--yes` (`-y`) approves a command that sends or changes something.
+- `--key`, `--base-url` (or `NODIUM_BASE_URL`), `--no-color` (or `NO_COLOR`).
+
+## A template, from file to approved
+
+```bash
+cat > order_ready.json <<'EOF'
+{ "name": "order_ready", "language": "en", "category": "UTILITY",
+  "body": "Hello {{1}}, your order is ready." }
+EOF
+
+nodium templates new --input order_ready.json   # a draft: nothing goes to Meta yet
+nodium templates deploy <id>                     # asks "Proceed? [y/N]"
+nodium templates wait <id> --timeout 10m         # exit 0 approved, 1 refused or timed out
+nodium send --channel <id> --to +33612345678 --template order_ready --language en --var 1=Karim
+```
+
+`templates wait` asks Meta every 15 seconds until every WhatsApp account of the
+client approved the template, or one rejected, paused or disabled it.
+
+## Send
+
+```bash
+nodium send --channel <id> --to +33612345678 --text "Hello"
+nodium send --channel <id> --to +33612345678 --input image.json   # any message: the JSON of POST /messages
+```
+
+Free text only goes within 24 hours of the person's last message; a template is
+the only way to write first. A send Meta refuses answers HTTP 200: the command
+reads the message status, prints why, and exits 1.
+
+## Webhooks, clients, Flows
+
+```bash
+nodium webhooks new --url https://app.example.com/webhooks/nodium --event message.received --event message.failed
+nodium webhooks deliveries --failed
+nodium webhooks redeliver <deliveryId>
+
+nodium tenants new --name "Agence Horizon" --external-id crm-4187 --connect-link
+nodium connect-link new --tenant crm-4187
+
+nodium flows deploy booking.json                    # a draft Flow at Meta; validation problems printed
+nodium flows deploy booking.json --id <flowId> --publish
+```
+
+The webhook secret and the connect link are shown only once: store them. A
+published Flow can no longer change.
+
+## Listen
+
+No tunnel, no public address: it reads your events from Nodium and replays
+each one to a URL on your machine.
+
+```bash
+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>`).
+- It acts on the events of every client of the account, unless `--tenant <id>`
+  names one or the key is pinned to one. `--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.
+
+## Output and exit codes
+
+- `--output human` (the default in a terminal): short lines and tables.
+- `--output json` (the default when the output is piped): the object the SDK
+  returns, unchanged, on stdout. A refusal goes to stderr as
+  `{ "error": { "status", "code", "message", "requestId" } }`.
+- Exit code `0` done, `1` refused by Nodium or Meta (also a template refused, a
+  Flow with problems, a failed send), `2` a wrong command line or a missing
+  approval.
+
+## Approval before a write
+
+`send`, `templates deploy|delete`, `webhooks new|update|delete|redeliver|rotate-secret`,
+`tenants new`, `connect-link new` and `flows deploy` say what they are about to
+do and ask `Proceed? [y/N]`. Outside a terminal nobody can answer: they refuse
+(exit 2) unless you pass `--yes`.
+
+## Using the CLI with an AI agent
+
+The CLI suits a coding agent (Claude Code, Cursor, Codex…) as it is:
+
+1. **Read first.** `nodium status`, `nodium numbers list`, `nodium templates get <id>`,
+   `nodium conversations list`: they change nothing and need no approval.
+2. **Confirm before writing.** Show the person what will be sent or changed,
+   then run the command with `--yes` only once they agreed. Without `--yes`, a
+   write run by an agent stops with exit code 2: nothing is sent.
+3. **Use JSON.** Piped, every command prints JSON; pass `--output json` to be
+   sure. Branch on `error.code`, never on the message.
+4. **Give the agent its own key**, pinned to one client and with an expiry
+   (`POST /keys` with `clientId` and `expiresInDays`), through `NODIUM_KEY`.
+
+## License
+
+MIT © By-Tech.io

package/dist/args.js

@@ -0,0 +1,96 @@
+/**
+ * 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', 'yes', 'stdin', 'publish', 'failed', 'all', 'connect-link']);
+/** Les abréviations d'une lettre. */
+const SHORT = { h: 'help', v: 'version', y: 'yes' };
+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, et un nombre d'arguments
+ * qui n'est pas le sien : une faute de frappe ne passe pas en silence.
+ * `name` est le chemin de la commande (`templates wait`).
+ */
+export function rejectUnknown(args, allowed, name, arity = 0) {
+    for (const key of args.flags.keys()) {
+        if (!allowed.includes(key))
+            throw new UsageError(`Unknown option --${key} for \`${name}\`. Try \`nodium ${name} --help\`.`);
+    }
+    if (args.positionals.length > arity)
+        throw new UsageError(`Unexpected argument "${args.positionals[arity]}". Try \`nodium ${name} --help\`.`);
+    if (args.positionals.length < arity)
+        throw new UsageError(`Missing argument. Try \`nodium ${name} --help\`.`);
+}
+/** Un entier au moins égal à `min`, ou `null` si le drapeau est absent. */
+export 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/commands/account.js

@@ -0,0 +1,129 @@
+import { Nodium } from '@nodium.io/whatsapp';
+import { UsageError, flag, readInteger } from '../args.js';
+import { deleteConfig, maskKey, writeConfig } from '../config.js';
+import { paint, table, when } from '../output.js';
+/**
+ * La clé et le compte : `login`, `logout`, `status`, `health`, `events`.
+ */
+/** Un numéro en une ligne : son état d'abord. */
+export function numberState(channel) {
+    if (!channel.isActive)
+        return 'off';
+    if (channel.paymentMissing)
+        return 'payment missing';
+    return channel.qualityRating ? `on (${channel.qualityRating.toLowerCase()})` : 'on';
+}
+/** Ce qu'il reste à faire, d'après les numéros et les abonnements. */
+export function nextSteps(numbers, activeWebhooks) {
+    const steps = [];
+    if (!numbers)
+        steps.push('Connect a WhatsApp number: `nodium tenants list`, then `nodium connect-link new --tenant <id>` and open the link.');
+    if (!activeWebhooks)
+        steps.push('Receive messages: `nodium webhooks new --url <https://…> --event message.received`, or `nodium listen --forward <local url>` while you build.');
+    if (numbers && activeWebhooks)
+        steps.push('All set: try `nodium send --channel <id> --to <+33…> --text "Hello"`.');
+    return steps;
+}
+async function login(ctx) {
+    let key = flag(ctx.args, 'key');
+    if (!key) {
+        key = ctx.interactive
+            ? await ctx.io.readSecret('API key (nod_…, Settings › API keys in the console): ')
+            : await ctx.io.readStdin();
+        key = key.trim();
+    }
+    if (!key)
+        throw new UsageError('No key given. Paste it when asked, pipe it (`echo $KEY | nodium login`), or pass --key.');
+    const current = await new Nodium(key, { baseUrl: ctx.baseUrl, ...(ctx.fetch ? { fetch: ctx.fetch } : {}) }).keys.current();
+    const baseUrl = flag(ctx.args, 'base-url');
+    writeConfig(ctx.configPath, { key, ...(baseUrl ? { baseUrl } : {}) });
+    ctx.print({ key: current, saved: ctx.configPath }, () => {
+        ctx.output.out(`${paint(ctx.output, 'green', 'Logged in')} with ${maskKey(key)} (account ${current.accountId}${current.pinned ? ', pinned to one client' : ''}).`);
+        ctx.output.out(paint(ctx.output, 'dim', `Saved to ${ctx.configPath} (readable by you only). NODIUM_KEY and --key still win over it.`));
+    });
+    return 0;
+}
+async function logout(ctx) {
+    const removed = deleteConfig(ctx.configPath);
+    ctx.print({ removed, path: ctx.configPath }, () => {
+        ctx.output.out(removed ? `Logged out: ${ctx.configPath} deleted.` : 'No saved key: nothing to do.');
+        if (ctx.env.NODIUM_KEY)
+            ctx.output.out(paint(ctx.output, 'yellow', 'NODIUM_KEY is still set in this shell.'));
+    });
+    return 0;
+}
+async function status(ctx) {
+    const nodium = ctx.nodium();
+    const key = await nodium.keys.current();
+    const tenant = flag(ctx.args, 'tenant');
+    // Une clé du compte, sans client nommé, voit les numéros de tous ses clients.
+    const numbers = !tenant && !key.pinned
+        ? await nodium.channels.list({ scope: 'account' })
+        : await ctx.scope().channels.list();
+    const { subscriptions } = await ctx.scope().webhooks.list();
+    const active = subscriptions.filter(s => s.isActive).length;
+    const next = nextSteps(numbers.filter(n => !n.isTest).length, active);
+    ctx.print({ key, numbers, webhooks: { total: subscriptions.length, active }, next }, () => {
+        const { out } = ctx.output;
+        out(paint(ctx.output, 'bold', 'Key'));
+        out(`  account ${key.accountId} · ${key.pinned ? 'pinned to one client' : 'acts for every client'} · ${key.expiresAt ? `expires ${when(key.expiresAt)}` : 'never expires'}`);
+        out(paint(ctx.output, 'bold', `Numbers (${numbers.length})`));
+        if (!numbers.length)
+            out('  none connected');
+        for (const line of table(numbers.map(n => [n.id, n.identity, n.name, numberState(n) + (n.isTest ? ' · sandbox' : '')])))
+            out(`  ${line}`);
+        out(paint(ctx.output, 'bold', 'Webhooks'));
+        out(`  ${subscriptions.length} subscription${subscriptions.length === 1 ? '' : 's'}, ${active} active`);
+        out(paint(ctx.output, 'bold', 'Next'));
+        for (const step of next)
+            out(`  ${step}`);
+    });
+    return 0;
+}
+async function health(ctx) {
+    const result = await ctx.nodium().health();
+    ctx.print(result, () => {
+        ctx.output.out(result.healthy ? paint(ctx.output, 'green', 'Healthy.') : paint(ctx.output, 'red', 'Something needs your attention:'));
+        for (const alert of result.alerts)
+            ctx.output.out(`  ${alert.level.padEnd(8)} ${alert.code}  ${alert.message} (number ${alert.channelId})`);
+    });
+    return result.healthy ? 0 : 1;
+}
+async function events(ctx) {
+    const after = readInteger(ctx.args, 'after', 0);
+    const limit = readInteger(ctx.args, 'limit', 1);
+    if (limit !== null && limit > 500)
+        throw new UsageError('--limit must be 500 or less.');
+    const page = await ctx.scope().events.list(after ?? undefined, limit ?? undefined);
+    ctx.print(page, () => {
+        if (after === null)
+            ctx.output.out(`The log is at event #${page.next_after}. Read what comes next with --after ${page.next_after}.`);
+        for (const line of table(page.data.map(e => [String(e.seq), when(e.occurred_at), e.event, e.id, e.external_id ?? ''])))
+            ctx.output.out(line);
+        if (after !== null)
+            ctx.output.out(paint(ctx.output, 'dim', `Next: --after ${page.next_after}`));
+    });
+    return 0;
+}
+export const ACCOUNT_COMMANDS = [
+    {
+        path: ['login'], summary: 'Save your API key for the next commands.', needsKey: false,
+        help: `Asks for the key (hidden), or reads it from a pipe or --key, checks it with Nodium and
+saves it to $XDG_CONFIG_HOME/nodium/config.json (~/.config by default), readable by you
+only. --base-url is saved with it. NODIUM_KEY and --key still win over the saved key.`,
+        run: login
+    },
+    { path: ['logout'], summary: 'Forget the saved key.', needsKey: false, run: logout },
+    {
+        path: ['status'], summary: 'What your key is, your numbers, your webhooks, and what to do next.',
+        run: status
+    },
+    { path: ['health'], summary: 'Anything wrong with your numbers? Exit code 1 if so.', run: health },
+    {
+        path: ['events'], summary: 'Read the event log (what your webhooks receive), from a cursor.',
+        flags: ['after', 'limit'],
+        help: `  --after <seq>   The events after this number. Without it: where the log is now.
+  --limit <n>     At most n events (1 to 500, default 100).`,
+        run: events
+    }
+];

package/dist/commands/conversations.js

@@ -0,0 +1,92 @@
+import { flag } from '../args.js';
+import { listLimit, pageSize, take } from '../context.js';
+import { details, table, when } from '../output.js';
+/**
+ * Lire ce qui s'est échangé : les conversations, leurs messages, les contacts.
+ * Aucune écriture ici.
+ */
+/** Le texte d'un message sur une ligne, coupé. */
+function preview(text, type) {
+    const line = (text ?? `[${type}]`).replace(/\s+/g, ' ');
+    return line.length > 60 ? `${line.slice(0, 59)}…` : line;
+}
+async function listConversations(ctx) {
+    const limit = listLimit(ctx.args);
+    const channelId = flag(ctx.args, 'channel');
+    const contactId = flag(ctx.args, 'contact');
+    const phone = flag(ctx.args, 'phone');
+    const items = await take(ctx.scope().conversations.each({
+        limit: pageSize(limit),
+        ...(channelId ? { channelId } : {}), ...(contactId ? { contactId } : {}), ...(phone ? { phone } : {})
+    }), limit);
+    ctx.print(items, () => {
+        for (const line of table(items.map(c => [
+            c.id, c.contact.displayName ?? c.contact.identity, c.channelName,
+            c.window.open ? 'window open' : 'window closed', when(c.lastInboundAt)
+        ])))
+            ctx.output.out(line);
+    });
+    return 0;
+}
+async function getConversation(ctx) {
+    const conversation = await ctx.scope().conversations.get(ctx.args.positionals[0]);
+    ctx.print(conversation, () => details(conversation).forEach(line => ctx.output.out(line)));
+    return 0;
+}
+async function listMessages(ctx) {
+    const limit = listLimit(ctx.args);
+    const items = await take(ctx.scope().messages.each(ctx.args.positionals[0], { limit: pageSize(limit) }), limit);
+    ctx.print(items, () => {
+        for (const line of table(items.map(m => [
+            when(m.createdAt), m.direction === 'inbound' ? '←' : '→', m.status, m.id, preview(m.textContent, m.type)
+        ])))
+            ctx.output.out(line);
+    });
+    return 0;
+}
+async function getMessage(ctx) {
+    const message = await ctx.scope().messages.get(ctx.args.positionals[0]);
+    ctx.print(message, () => details(message).forEach(line => ctx.output.out(line)));
+    return 0;
+}
+async function listContacts(ctx) {
+    const limit = listLimit(ctx.args);
+    const q = flag(ctx.args, 'search');
+    const items = await take(ctx.scope().contacts.each({ limit: pageSize(limit), ...(q ? { q } : {}) }), limit);
+    ctx.print(items, () => {
+        for (const line of table(items.map(c => [
+            c.id, c.displayName ?? '—', c.phone ?? c.email ?? c.externalId ?? '—', c.optInAt ? 'opted in' : c.optOutAt ? 'opted out' : '', c.blocked ? 'blocked' : ''
+        ])))
+            ctx.output.out(line);
+    });
+    return 0;
+}
+async function getContact(ctx) {
+    const contact = await ctx.scope().contacts.get(ctx.args.positionals[0]);
+    ctx.print(contact, () => details(contact).forEach(line => ctx.output.out(line)));
+    return 0;
+}
+const LIMIT_HELP = '  --limit <n>       At most n items, newest first (default 20); pages are followed for you.';
+export const CONVERSATION_COMMANDS = [
+    {
+        path: ['conversations', 'list'], summary: 'The latest conversations.', flags: ['limit', 'channel', 'contact', 'phone'],
+        help: `${LIMIT_HELP}
+  --channel <id>    Only on this number.
+  --contact <id>    Only with this contact.
+  --phone <number>  Only with the contact who has this number.`,
+        run: listConversations
+    },
+    { path: ['conversations', 'get'], args: ['<id>'], summary: 'One conversation and its 24-hour window.', run: getConversation },
+    {
+        path: ['messages', 'list'], args: ['<conversationId>'], summary: 'The messages of a conversation, newest first.', flags: ['limit'],
+        help: LIMIT_HELP, run: listMessages
+    },
+    { path: ['messages', 'get'], args: ['<id>'], summary: 'One message: its status, and why it failed.', run: getMessage },
+    {
+        path: ['contacts', 'list'], summary: 'Your contacts.', flags: ['limit', 'search'],
+        help: `${LIMIT_HELP}
+  --search <text>   A name, a number or an e-mail.`,
+        run: listContacts
+    },
+    { path: ['contacts', 'get'], args: ['<id>'], summary: 'One contact.', run: getContact }
+];

package/dist/commands/flows.js

@@ -0,0 +1,71 @@
+import { readFileSync } from 'node:fs';
+import { basename, extname } from 'node:path';
+import { UsageError, flag, hasFlag } from '../args.js';
+import { parseJsonObject } from '../input.js';
+import { paint } from '../output.js';
+/**
+ * `nodium flows deploy <file.json>` : un Flow écrit en local part chez Meta —
+ * un nouveau brouillon, ou une version de plus d'un brouillon (`--id`). Meta
+ * valide le JSON ; ses erreurs s'affichent. `--publish` publie ensuite, et
+ * seulement si Meta n'a rien trouvé.
+ *
+ * ⚠️ Publier est définitif : un Flow publié ne se modifie plus.
+ */
+/** Une erreur de Meta sur une ligne : où, et quoi. */
+export function describeFlowError(error) {
+    const where = error.line_start !== undefined ? `line ${error.line_start}${error.column_start !== undefined ? `:${error.column_start}` : ''}  ` : '';
+    return `${where}${error.error}: ${error.message}`;
+}
+async function deploy(ctx) {
+    const file = ctx.args.positionals[0];
+    let text;
+    try {
+        text = readFileSync(file, 'utf8');
+    }
+    catch (error) {
+        throw new UsageError(`Cannot read ${file}: ${error?.code === 'ENOENT' ? 'no such file' : error?.message ?? error}.`);
+    }
+    const flowJson = parseJsonObject(text, file);
+    const id = flag(ctx.args, 'id');
+    const publish = hasFlag(ctx.args, 'publish');
+    if (id && flag(ctx.args, 'name'))
+        throw new UsageError('--name is for a new Flow; to rename one, use the console.');
+    const flows = ctx.scope().flows;
+    await ctx.confirm(`${id ? `Save a new version of Flow ${id}` : 'Create a Flow'} at Meta from ${file}${publish ? ', then publish it (final)' : ''}`);
+    const saved = id
+        ? { flow: null, ...(await flows.saveVersion(id, flowJson)) }
+        : await flows.create({ name: flag(ctx.args, 'name') ?? basename(file, extname(file)), flowJson });
+    const flowId = saved.flow?.id ?? id;
+    const errors = saved.validationErrors;
+    const published = publish && !errors.length ? await flows.publish(flowId) : null;
+    ctx.print({ flowId, version: saved.version, validationErrors: errors, published }, () => {
+        const { out, err } = ctx.output;
+        out(`${paint(ctx.output, 'green', 'Saved')}: Flow ${flowId}, version ${saved.version.label}.`);
+        if (errors.length) {
+            err(paint(ctx.output, 'red', `Meta found ${errors.length} problem${errors.length === 1 ? '' : 's'}:`));
+            for (const e of errors)
+                err(`  ${describeFlowError(e)}`);
+            if (publish)
+                err('Not published: fix the file and deploy again.');
+        }
+        else if (published) {
+            out(`${paint(ctx.output, 'green', 'Published')}: ${published.name} can now be sent.`);
+        }
+        else {
+            out(paint(ctx.output, 'dim', `Valid. Publish it with --publish --id ${flowId} once tested.`));
+        }
+    });
+    return errors.length ? 1 : 0;
+}
+export const FLOW_COMMANDS = [
+    {
+        path: ['flows', 'deploy'], args: ['<file.json>'], summary: 'Send a local Flow JSON to Meta, as a new draft or a new version.',
+        flags: ['name', 'id', 'publish'],
+        help: `  --id <flowId>   Save a new version of this draft Flow. Without it: a new Flow.
+  --name <text>   The new Flow's name. Default: the file name.
+  --publish       Publish it once Meta finds no problem. Final: a published Flow cannot change.
+
+Meta's validation problems are printed, with their line; exit code 1 if there are any.`,
+        run: deploy
+    }
+];

package/dist/commands/index.js

@@ -0,0 +1,58 @@
+import { flag, hasFlag, readInteger } from '../args.js';
+import { DEFAULT_INTERVAL_MS, listen, parseEventFilter, parseForwardUrl } from '../listen.js';
+import { SEND_COMMAND } from '../send.js';
+import { ACCOUNT_COMMANDS } from './account.js';
+import { CONVERSATION_COMMANDS } from './conversations.js';
+import { FLOW_COMMANDS } from './flows.js';
+import { NUMBER_COMMANDS } from './numbers.js';
+import { TEMPLATE_COMMANDS } from './templates.js';
+import { TENANT_COMMANDS } from './tenants.js';
+import { WEBHOOK_COMMANDS } from './webhooks.js';
+/**
+ * LA TABLE DES COMMANDES — un nom (`templates`), au besoin un verbe (`wait`) :
+ * l'aide, les drapeaux permis et ce que fait chacune vivent ensemble, ici et
+ * dans `commands/*.ts`. `run.ts` ne fait que chercher dans cette table.
+ */
+async function runListen(ctx) {
+    const forward = parseForwardUrl(flag(ctx.args, 'forward'));
+    const events = parseEventFilter(flag(ctx.args, 'events'));
+    const summary = await listen({
+        scope: ctx.scope(), baseUrl: ctx.baseUrl, forward, events,
+        secret: flag(ctx.args, 'secret') ?? ctx.env.NODIUM_WEBHOOK_SECRET ?? null,
+        from: readInteger(ctx.args, 'from', 0),
+        intervalMs: readInteger(ctx.args, 'interval', 1) ?? DEFAULT_INTERVAL_MS,
+        verbose: hasFlag(ctx.args, 'verbose'),
+        signal: ctx.signal,
+        output: ctx.output,
+        ...(ctx.fetch ? { fetch: ctx.fetch } : {})
+    });
+    ctx.output.out(`Stopped. ${summary.forwarded} forwarded, ${summary.failed} not answered with a 2xx. Resume with --from ${summary.after}.`);
+    return 0;
+}
+const LISTEN_COMMAND = {
+    path: ['listen'], summary: 'Replay your events to a local URL, signed like production: no tunnel.',
+    flags: ['forward', 'secret', 'events', 'from', 'interval', 'verbose'],
+    help: `  --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.
+
+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. It prints lines as they come,
+whatever --output says.`,
+    run: runListen
+};
+export const COMMANDS = [
+    ...ACCOUNT_COMMANDS, SEND_COMMAND, LISTEN_COMMAND,
+    ...NUMBER_COMMANDS, ...CONVERSATION_COMMANDS, ...TEMPLATE_COMMANDS, ...WEBHOOK_COMMANDS, ...TENANT_COMMANDS, ...FLOW_COMMANDS
+];
+/** Les commandes dont le chemin commence par ces mots. */
+export function findCommands(words) {
+    return COMMANDS.filter(c => words.every((w, i) => c.path[i] === w));
+}