@nodium.io/cli 0.1.0 → 0.2.0

package/dist/commands/templates.js

@@ -0,0 +1,151 @@
+import { UsageError, flag, hasFlag } from '../args.js';
+import { readJsonInput } from '../input.js';
+import { details, paint, table, when } from '../output.js';
+/** Les états d'où Meta ne revient pas seul : il faut corriger, puis redéployer. */
+const REFUSED = new Set(['rejected', 'paused', 'disabled', 'failed']);
+/** Le verdict d'ensemble : approuvé partout, refusé quelque part, en revue, ou pas déployé. */
+export function templateOutcome(deployments) {
+    if (!deployments.length)
+        return 'not_deployed';
+    if (deployments.some(d => REFUSED.has(d.status)))
+        return 'refused';
+    if (deployments.some(d => d.status === 'not_deployed' || d.status === 'no_number'))
+        return 'not_deployed';
+    if (deployments.every(d => d.status === 'approved'))
+        return 'approved';
+    return 'pending';
+}
+/** `10m`, `90s`, `1h`, ou un nombre de secondes → millisecondes. */
+export function parseDuration(text) {
+    const match = /^(\d+)\s*(s|m|h)?$/.exec(text.trim());
+    if (!match)
+        throw new UsageError(`--timeout "${text}" must look like 90s, 10m or 1h.`);
+    return Number(match[1]) * { s: 1000, m: 60_000, h: 3_600_000 }[(match[2] ?? 's')];
+}
+/** L'attente entre deux questions à Meta. */
+export const WAIT_INTERVAL_MS = 15_000;
+async function list(ctx) {
+    const result = await ctx.scope().templates.list(hasFlag(ctx.args, 'all') ? { scope: 'account' } : {});
+    ctx.print(result, () => {
+        for (const line of table(result.templates.map(t => [t.id, t.name, t.language, t.category.toLowerCase(), t.status])))
+            ctx.output.out(line);
+        ctx.output.out(paint(ctx.output, 'dim', `${result.summary.total} templates: ${result.summary.deployed} deployed, ${result.summary.draft} drafts.`));
+    });
+    return 0;
+}
+async function get(ctx) {
+    const result = await ctx.scope().templates.get(ctx.args.positionals[0]);
+    ctx.print(result, () => {
+        details(result.template).forEach(line => ctx.output.out(line));
+        if (result.deployments.length)
+            ctx.output.out(paint(ctx.output, 'bold', 'At Meta'));
+        for (const line of table(result.deployments.map(d => [d.wabaId ?? '—', d.status, d.rejectionReason ?? '', when(d.reviewedAt)])))
+            ctx.output.out(`  ${line}`);
+    });
+    return 0;
+}
+async function requireInput(ctx) {
+    const input = await readJsonInput(ctx);
+    if (!input)
+        throw new UsageError('Give the template as JSON: --input <file.json> or --stdin. See `nodium help templates new`.');
+    return input;
+}
+async function create(ctx) {
+    const result = await ctx.scope().templates.create(await requireInput(ctx));
+    ctx.print(result, () => {
+        ctx.output.out(`${paint(ctx.output, 'green', 'Draft saved')}: ${result.template.name} (${result.template.id}). Nothing went to Meta yet.`);
+        ctx.output.out(paint(ctx.output, 'dim', `Next: nodium templates deploy ${result.template.id}`));
+    });
+    return 0;
+}
+async function update(ctx) {
+    const result = await ctx.scope().templates.update(ctx.args.positionals[0], await requireInput(ctx));
+    ctx.print(result, () => ctx.output.out(`Saved: ${result.template.name} (${result.template.status}).`));
+    return 0;
+}
+async function deploy(ctx) {
+    const id = ctx.args.positionals[0];
+    await ctx.confirm(`Submit template ${id} to Meta for review (its name is then reserved there)`);
+    const result = await ctx.scope().templates.deploy(id);
+    const refused = result.results.some(r => REFUSED.has(r.status));
+    ctx.print(result, () => {
+        for (const line of table(result.results.map(r => [r.clientName, r.wabaId ?? '—', r.status, r.reason ?? ''])))
+            ctx.output.out(line);
+        if (!refused)
+            ctx.output.out(paint(ctx.output, 'dim', `Wait for Meta's review: nodium templates wait ${id}`));
+    });
+    return refused ? 1 : 0;
+}
+async function refresh(ctx) {
+    const result = await ctx.scope().templates.refresh(ctx.args.positionals[0]);
+    ctx.print(result, () => ctx.output.out(`${result.template.name}: ${result.template.status} (${result.changed} changed).`));
+    return 0;
+}
+async function remove(ctx) {
+    const id = ctx.args.positionals[0];
+    await ctx.confirm(`Delete template ${id}`);
+    const result = await ctx.scope().templates.delete(id);
+    ctx.print(result, () => ctx.output.out(result.deleted ? `Template ${id} deleted.` : `Template ${id} was not deleted.`));
+    return result.deleted ? 0 : 1;
+}
+async function wait(ctx) {
+    const id = ctx.args.positionals[0];
+    const timeout = parseDuration(flag(ctx.args, 'timeout') ?? '10m');
+    const deadline = Date.now() + timeout;
+    const templates = ctx.scope().templates;
+    for (;;) {
+        await templates.refresh(id);
+        const detail = await templates.get(id);
+        const outcome = templateOutcome(detail.deployments);
+        if (outcome !== 'pending' || Date.now() + WAIT_INTERVAL_MS > deadline || ctx.signal.aborted) {
+            ctx.print({ outcome: outcome === 'pending' ? 'timeout' : outcome, template: detail.template, deployments: detail.deployments }, () => {
+                const { out, err } = ctx.output;
+                if (outcome === 'approved')
+                    out(paint(ctx.output, 'green', `${detail.template.name} is approved: it can be sent.`));
+                else if (outcome === 'not_deployed')
+                    err(`${detail.template.name} is not at Meta yet: run \`nodium templates deploy ${id}\` first.`);
+                else if (outcome === 'pending')
+                    err(`Still in review at Meta after ${Math.round(timeout / 1000)} s. Run the command again later.`);
+                else {
+                    err(paint(ctx.output, 'red', `${detail.template.name} was not approved.`));
+                    for (const d of detail.deployments.filter(d => REFUSED.has(d.status)))
+                        err(`  ${d.wabaId ?? '—'}  ${d.status}  ${d.rejectionReason ?? ''}`);
+                    err('Fix it with `nodium templates update`, then deploy again.');
+                }
+            });
+            return outcome === 'approved' ? 0 : 1;
+        }
+        if (!ctx.json)
+            ctx.output.err(paint(ctx.output, 'dim', `In review at Meta… checking again in ${WAIT_INTERVAL_MS / 1000} s.`));
+        await ctx.sleep(WAIT_INTERVAL_MS, ctx.signal);
+    }
+}
+const INPUT_HELP = `  --input <file.json>   The template as JSON, or --stdin to read it from a pipe.`;
+export const TEMPLATE_COMMANDS = [
+    {
+        path: ['templates', 'list'], summary: 'Your templates and their state at Meta.', flags: ['all'],
+        help: '  --all   The templates of every client of the account.', run: list
+    },
+    { path: ['templates', 'get'], args: ['<id>'], summary: 'One template, and its review at Meta.', run: get },
+    {
+        path: ['templates', 'new'], summary: 'Save a draft template (nothing goes to Meta yet).', flags: ['input', 'stdin'],
+        help: `${INPUT_HELP}
+
+Example file:
+  { "name": "order_ready", "language": "en", "category": "UTILITY",
+    "body": "Hello {{1}}, your order is ready." }`,
+        run: create
+    },
+    { path: ['templates', 'update'], args: ['<id>'], summary: 'Change a draft, or a template Meta refused.', flags: ['input', 'stdin'], help: INPUT_HELP, run: update },
+    { path: ['templates', 'deploy'], args: ['<id>'], summary: 'Submit it to Meta for review. Asks first.', run: deploy },
+    { path: ['templates', 'refresh'], args: ['<id>'], summary: 'Ask Meta where the review is.', run: refresh },
+    {
+        path: ['templates', 'wait'], args: ['<id>'], summary: 'Wait for Meta\'s verdict. Exit 0 approved, 1 refused or timed out.', flags: ['timeout'],
+        help: `  --timeout <time>   How long to wait: 90s, 10m, 1h. Default: 10m.
+
+It asks Meta every ${WAIT_INTERVAL_MS / 1000} s until every WhatsApp account approved it, or one
+rejected, paused or disabled it.`,
+        run: wait
+    },
+    { path: ['templates', 'delete'], args: ['<id>'], summary: 'Delete a template. Asks first.', run: remove }
+];

package/dist/commands/tenants.js

@@ -0,0 +1,99 @@
+import { UsageError, flag, hasFlag, readInteger } from '../args.js';
+import { listLimit, pageSize, take } from '../context.js';
+import { details, paint, table } from '../output.js';
+/**
+ * Vos clients (un par client final, « Mon entreprise » compris) et le lien
+ * hébergé où chacun branche son WhatsApp.
+ *
+ * ⚠️ L'adresse d'un lien ne se montre qu'à sa création : la commande l'écrit
+ *    une fois, rien ne la relit.
+ */
+/** `--redirect-url` et `--expires-in-days`, s'ils sont donnés. */
+function linkInput(ctx) {
+    const redirectUrl = flag(ctx.args, 'redirect-url');
+    const expiresInDays = readInteger(ctx.args, 'expires-in-days', 1);
+    if (expiresInDays !== null && expiresInDays > 30)
+        throw new UsageError('--expires-in-days must be 30 or less.');
+    return { ...(redirectUrl ? { redirectUrl } : {}), ...(expiresInDays !== null ? { expiresInDays } : {}) };
+}
+function printLink(ctx, url, expiresAt) {
+    ctx.output.out(`Send this link to your client (single use, until ${expiresAt.slice(0, 10)}):`);
+    ctx.output.out(paint(ctx.output, 'bold', url));
+    ctx.output.err(paint(ctx.output, 'dim', 'It is shown only now. A lost link is replaced by a new one.'));
+}
+async function list(ctx) {
+    const limit = listLimit(ctx.args);
+    const externalId = flag(ctx.args, 'external-id');
+    const items = await take(ctx.nodium().tenants.each({ limit: pageSize(limit), ...(externalId ? { externalId } : {}) }), limit);
+    ctx.print(items, () => {
+        for (const line of table(items.map(t => [t.id, t.externalId ?? '—', t.name, `WhatsApp ${t.whatsapp.status.replace('_', ' ')}`, t.status])))
+            ctx.output.out(line);
+    });
+    return 0;
+}
+async function get(ctx) {
+    const tenant = await ctx.nodium().tenants.get(ctx.args.positionals[0]);
+    ctx.print(tenant, () => details(tenant).forEach(line => ctx.output.out(line)));
+    return 0;
+}
+async function create(ctx) {
+    const name = flag(ctx.args, 'name');
+    if (!name)
+        throw new UsageError('--name "<client name>" is required.');
+    const externalId = flag(ctx.args, 'external-id');
+    const withLink = hasFlag(ctx.args, 'connect-link');
+    await ctx.confirm(`Add the client "${name}"${withLink ? ' and create its connect link' : ''}`);
+    const input = { name, ...(externalId ? { externalId } : {}) };
+    const tenants = ctx.nodium().tenants;
+    if (withLink) {
+        const tenant = await tenants.create(input, { connectLink: linkInput(ctx) });
+        ctx.print(tenant, () => {
+            ctx.output.out(`${paint(ctx.output, 'green', 'Client added')}: ${tenant.name} (${tenant.id}).`);
+            printLink(ctx, tenant.connectLink.url, tenant.connectLink.expiresAt);
+        });
+        return 0;
+    }
+    const tenant = await tenants.create(input);
+    ctx.print(tenant, () => {
+        ctx.output.out(`${paint(ctx.output, 'green', 'Client added')}: ${tenant.name} (${tenant.id}).`);
+        ctx.output.out(paint(ctx.output, 'dim', `Next: nodium connect-link new --tenant ${tenant.externalId ?? tenant.id}`));
+    });
+    return 0;
+}
+async function newLink(ctx) {
+    const tenant = flag(ctx.args, 'tenant');
+    if (!tenant)
+        throw new UsageError('--tenant <id> is required: the client who connects (its id or your externalId).');
+    const input = linkInput(ctx);
+    await ctx.confirm(`Create a connect link for client ${tenant}`);
+    const link = await ctx.nodium().tenants.connectLink(tenant, input);
+    ctx.print(link, () => printLink(ctx, link.url, link.expiresAt));
+    return 0;
+}
+const LINK_HELP = `  --redirect-url <https://…>   Where your client lands once connected.
+  --expires-in-days <n>        1 to 30, default 7.`;
+export const TENANT_COMMANDS = [
+    {
+        path: ['tenants', 'list'], summary: 'Your clients, newest first.', flags: ['limit', 'external-id'],
+        help: `  --external-id <id>   The client with your own identifier.
+  --limit <n>          At most n (default 20).`,
+        run: list
+    },
+    { path: ['tenants', 'get'], args: ['<id>'], summary: 'One client, by its id or your externalId.', run: get },
+    {
+        path: ['tenants', 'new'], summary: 'Add a client. With --connect-link, prints the link to send it.',
+        flags: ['name', 'external-id', 'connect-link', 'redirect-url', 'expires-in-days'],
+        help: `  --name <text>          The client's name. Required.
+  --external-id <id>     Your own identifier for it: unique, it makes the call safe to repeat.
+  --connect-link         Also create the link where it connects its WhatsApp.
+${LINK_HELP}`,
+        run: create
+    },
+    {
+        path: ['connect-link', 'new'], summary: 'A link where your client connects its WhatsApp number.',
+        flags: ['redirect-url', 'expires-in-days'],
+        help: `  --tenant <id>                The client. Required.
+${LINK_HELP}`,
+        run: newLink
+    }
+];

package/dist/commands/webhooks.js

@@ -0,0 +1,160 @@
+import { WEBHOOK_EVENTS } from '@nodium.io/whatsapp';
+import { UsageError, flag, flagAll, hasFlag } from '../args.js';
+import { listLimit, pageSize, take } from '../context.js';
+import { paint, table, when } from '../output.js';
+/**
+ * Les abonnements aux événements, et leurs livraisons.
+ *
+ * ⚠️ Le secret de signature ne se montre qu'à la création et au changement de
+ *    secret : la commande le dit, une fois.
+ */
+/** `--event a --event b,c` → `['a', 'b', 'c']`, chaque nom connu (`*` = tous). */
+export function readEvents(values) {
+    const names = values.flatMap(v => v.split(',')).map(n => n.trim()).filter(Boolean);
+    const known = new Set([...WEBHOOK_EVENTS, '*']);
+    const unknown = names.filter(n => !known.has(n));
+    if (unknown.length)
+        throw new UsageError(`Unknown event ${unknown.map(n => `"${n}"`).join(', ')}. Known: ${WEBHOOK_EVENTS.join(', ')}, or * for all.`);
+    return names;
+}
+function printSecret(ctx, secret) {
+    ctx.output.out(`Signing secret: ${secret}`);
+    ctx.output.err(paint(ctx.output, 'yellow', 'Store it now (for example in NODIUM_WEBHOOK_SECRET): it is never shown again.'));
+}
+async function list(ctx) {
+    const result = await ctx.scope().webhooks.list();
+    ctx.print(result, () => {
+        if (!result.subscriptions.length)
+            ctx.output.out('No subscription. Add one: nodium webhooks new --url <https://…> --event message.received');
+        for (const line of table(result.subscriptions.map(s => [
+            s.id, s.isActive ? 'active' : `paused${s.disabledReason ? ` (${s.disabledReason})` : ''}`, s.url, s.events.join(','), s.lastError ? `last error: ${s.lastError}` : ''
+        ])))
+            ctx.output.out(line);
+    });
+    return 0;
+}
+async function deliveries(ctx) {
+    const limit = listLimit(ctx.args);
+    const subscriptionId = flag(ctx.args, 'subscription');
+    const event = flag(ctx.args, 'event');
+    const items = await take(ctx.scope().webhooks.eachDelivery({
+        limit: pageSize(limit),
+        ...(hasFlag(ctx.args, 'failed') ? { status: 'failed' } : {}),
+        ...(subscriptionId ? { subscriptionId } : {}), ...(event ? { event } : {})
+    }), limit);
+    ctx.print(items, () => {
+        for (const line of table(items.map(d => [
+            when(d.createdAt), d.id, d.event, d.status, d.responseStatus === null ? '—' : String(d.responseStatus), `${d.attempts} attempt${d.attempts === 1 ? '' : 's'}`, d.lastError ?? ''
+        ])))
+            ctx.output.out(line);
+        if (items.some(d => d.status === 'failed'))
+            ctx.output.out(paint(ctx.output, 'dim', 'Send one again: nodium webhooks redeliver <deliveryId>'));
+    });
+    return 0;
+}
+async function create(ctx) {
+    const url = flag(ctx.args, 'url');
+    if (!url)
+        throw new UsageError('--url <https://…> is required: the address Nodium calls.');
+    const events = readEvents(flagAll(ctx.args, 'event'));
+    if (!events.length)
+        throw new UsageError('Name at least one event: --event message.received (repeat it), or --event "*" for all.');
+    const channelIds = flagAll(ctx.args, 'channel');
+    const label = flag(ctx.args, 'label');
+    await ctx.confirm(`Subscribe ${url} to ${events.join(', ')}`);
+    const result = await ctx.scope().webhooks.create({ url, events, ...(channelIds.length ? { channelIds } : {}), ...(label ? { label } : {}) });
+    ctx.print(result, () => {
+        ctx.output.out(`${paint(ctx.output, 'green', 'Subscribed')}: ${result.id}`);
+        printSecret(ctx, result.secret);
+        ctx.output.out(paint(ctx.output, 'dim', `Try it: nodium webhooks test ${result.id}`));
+    });
+    return 0;
+}
+async function update(ctx) {
+    const id = ctx.args.positionals[0];
+    const input = {};
+    const url = flag(ctx.args, 'url');
+    const label = flag(ctx.args, 'label');
+    const active = flag(ctx.args, 'active');
+    if (url)
+        input.url = url;
+    if (label !== undefined)
+        input.label = label;
+    if (hasFlag(ctx.args, 'event'))
+        input.events = readEvents(flagAll(ctx.args, 'event'));
+    if (hasFlag(ctx.args, 'channel'))
+        input.channelIds = flagAll(ctx.args, 'channel').filter(Boolean);
+    if (active !== undefined) {
+        if (active !== 'true' && active !== 'false')
+            throw new UsageError('--active must be true or false.');
+        input.isActive = active === 'true';
+    }
+    if (!Object.keys(input).length)
+        throw new UsageError('Nothing to change: give --url, --event, --channel, --label or --active.');
+    await ctx.confirm(`Change webhook ${id} (${Object.keys(input).join(', ')})`);
+    const subscription = await ctx.scope().webhooks.update(id, input);
+    ctx.print(subscription, () => ctx.output.out(`Saved: ${subscription.id} → ${subscription.url} (${subscription.isActive ? 'active' : 'paused'}).`));
+    return 0;
+}
+async function remove(ctx) {
+    const id = ctx.args.positionals[0];
+    await ctx.confirm(`Delete webhook ${id}: Nodium stops calling it`);
+    const result = await ctx.scope().webhooks.delete(id);
+    ctx.print(result ?? { deleted: true }, () => ctx.output.out(`Webhook ${id} deleted.`));
+    return 0;
+}
+async function test(ctx) {
+    const result = await ctx.scope().webhooks.test(ctx.args.positionals[0]);
+    ctx.print(result, () => {
+        ctx.output.out(result.ok
+            ? `${paint(ctx.output, 'green', String(result.status))}  answered in ${result.ms} ms.`
+            : `${paint(ctx.output, 'red', result.status === null ? 'ERR' : String(result.status))}  ${result.error ?? 'not a 2xx answer'} (${result.ms} ms).`);
+    });
+    return result.ok ? 0 : 1;
+}
+async function redeliver(ctx) {
+    const id = ctx.args.positionals[0];
+    await ctx.confirm(`Send delivery ${id} again`);
+    const delivery = await ctx.scope().webhooks.redeliver(id);
+    ctx.print(delivery, () => ctx.output.out(`Delivery ${delivery.id}: ${delivery.status}${delivery.responseStatus ? ` (${delivery.responseStatus})` : ''}.`));
+    return delivery.status === 'failed' ? 1 : 0;
+}
+async function rotateSecret(ctx) {
+    const id = ctx.args.positionals[0];
+    await ctx.confirm(`Issue a new signing secret for webhook ${id}`);
+    const result = await ctx.scope().webhooks.rotateSecret(id);
+    ctx.print(result, () => {
+        printSecret(ctx, result.secret);
+        ctx.output.out(`The old secret still signs until ${when(result.previousValidUntil)}: verify with both meanwhile.`);
+    });
+    return 0;
+}
+export const WEBHOOK_COMMANDS = [
+    { path: ['webhooks', 'list'], summary: 'Your subscriptions.', run: list },
+    {
+        path: ['webhooks', 'deliveries'], summary: 'The latest deliveries, newest first.', flags: ['limit', 'failed', 'subscription', 'event'],
+        help: `  --failed               Only the failed ones.
+  --subscription <id>    Only for this subscription.
+  --event <name>         Only this event.
+  --limit <n>            At most n (default 20).`,
+        run: deliveries
+    },
+    {
+        path: ['webhooks', 'new'], summary: 'Subscribe an https address to events. Prints the secret once.', flags: ['url', 'event', 'channel', 'label'],
+        help: `  --url <https://…>   The address Nodium calls. Required.
+  --event <name>      An event (repeat it, or a,b), * for all. Required.
+  --channel <id>      Only the events of this number (repeat it). Default: all numbers.
+  --label <text>      A name for you.`,
+        run: create
+    },
+    {
+        path: ['webhooks', 'update'], args: ['<id>'], summary: 'Change the address, events, numbers, label, or pause it.', flags: ['url', 'event', 'channel', 'label', 'active'],
+        help: `  --url, --event, --channel, --label   As for \`webhooks new\`; --event and --channel replace the list.
+  --active <true|false>                Resume or pause it.`,
+        run: update
+    },
+    { path: ['webhooks', 'delete'], args: ['<id>'], summary: 'Delete a subscription.', run: remove },
+    { path: ['webhooks', 'test'], args: ['<id>'], summary: 'Call the address once with a test event.', run: test },
+    { path: ['webhooks', 'redeliver'], args: ['<deliveryId>'], summary: 'Send a delivery again.', run: redeliver },
+    { path: ['webhooks', 'rotate-secret'], args: ['<id>'], summary: 'A new signing secret; the old one still works for a while.', run: rotateSecret }
+];

package/dist/config.js

@@ -0,0 +1,48 @@
+import { chmodSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { UsageError } from './args.js';
+export function configPath(env) {
+    return join(env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'nodium', 'config.json');
+}
+/** Le fichier lu ; absent ou illisible : rien. */
+export function readConfig(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        return parsed && typeof parsed === 'object' ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+export function writeConfig(path, config) {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+    // Un fichier déjà là garde ses droits à l'écriture : on les resserre.
+    chmodSync(path, 0o600);
+}
+/** Vrai si un fichier a été effacé. */
+export function deleteConfig(path) {
+    try {
+        readFileSync(path);
+    }
+    catch {
+        return false;
+    }
+    rmSync(path, { force: true });
+    return true;
+}
+/** La clé à employer, et d'où elle vient : `--key`, puis `NODIUM_KEY`, puis le fichier. */
+export function resolveKey(flagKey, env, config) {
+    if (flagKey)
+        return { key: flagKey, source: '--key' };
+    if (env.NODIUM_KEY)
+        return { key: env.NODIUM_KEY, source: 'NODIUM_KEY' };
+    if (config.key)
+        return { key: config.key, source: 'config' };
+    throw new UsageError('No API key: run `nodium login`, or set NODIUM_KEY (or pass --key). Create one in the console, under Settings › API keys.');
+}
+/** Le début d'une clé, assez pour la reconnaître : `nod_ab12…`. */
+export function maskKey(key) {
+    return `${key.slice(0, 8)}…`;
+}

package/dist/context.js

@@ -0,0 +1,48 @@
+import { UsageError, readInteger } from './args.js';
+/**
+ * La sortie par défaut : lisible devant un terminal, JSON dans un tube (un
+ * script ou un agent). `--output` l'impose.
+ */
+export function outputMode(value, stdoutIsTty) {
+    if (value === undefined)
+        return stdoutIsTty ? 'human' : 'json';
+    if (value !== 'json' && value !== 'human')
+        throw new UsageError('--output must be json or human.');
+    return value;
+}
+/**
+ * L'accord avant d'envoyer ou de changer quelque chose : `--yes` le donne ;
+ * sinon, devant un terminal, la question « Proceed? [y/N] » ; hors d'un
+ * terminal, sans `--yes`, la commande refuse (code 2).
+ */
+export async function confirmWrite(what, options) {
+    if (options.yes)
+        return;
+    if (!options.interactive) {
+        throw new UsageError(`${what}: this changes something and needs your approval. Run it again with --yes (not in a terminal, nobody can answer the question).`);
+    }
+    const answer = (await options.ask(`${what}. Proceed? [y/N] `)).trim().toLowerCase();
+    if (answer !== 'y' && answer !== 'yes')
+        throw new UsageError('Cancelled: nothing was sent or changed.');
+}
+/** Les premiers éléments d'une liste parcourue page après page. */
+export async function take(items, limit) {
+    const out = [];
+    if (limit <= 0)
+        return out;
+    for await (const item of items) {
+        out.push(item);
+        if (out.length >= limit)
+            break;
+    }
+    return out;
+}
+/** Combien d'éléments montre une liste : `--limit`, 20 par défaut. */
+export const DEFAULT_LIMIT = 20;
+export function listLimit(args) {
+    return readInteger(args, 'limit', 1) ?? DEFAULT_LIMIT;
+}
+/** La taille d'une page demandée à l'API pour en montrer `limit` (100 au plus). */
+export function pageSize(limit) {
+    return Math.min(limit, 100);
+}

package/dist/index.js

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
+import { createInterface } from 'node:readline';
+import { Writable } from 'node:stream';
 import { run } from './run.js';
 /**
  * Le point d'entrée de `nodium` (`bin` du paquet). Ctrl+C et SIGTERM arrêtent
@@ -16,9 +18,49 @@ const stop = () => {
 process.on('SIGINT', stop);
 process.on('SIGTERM', stop);
 const color = Boolean(process.stdout.isTTY) && !process.env.NO_COLOR && !argv.includes('--no-color');
+/** Une question au terminal, sur la sortie d'erreur ; `hidden` n'affiche pas la frappe. */
+function prompt(question, hidden) {
+    return new Promise((resolve) => {
+        let muted = false;
+        const sink = new Writable({
+            write(chunk, encoding, done) {
+                if (!muted)
+                    process.stderr.write(chunk, encoding);
+                done();
+            }
+        });
+        const rl = createInterface({ input: process.stdin, output: sink, terminal: true });
+        // Ctrl+C pendant la question : une réponse vide, donc « non ».
+        rl.on('SIGINT', () => {
+            rl.close();
+            process.stderr.write('\n');
+            resolve('');
+        });
+        rl.question(question, (answer) => {
+            rl.close();
+            if (hidden)
+                process.stderr.write('\n');
+            resolve(answer);
+        });
+        muted = hidden;
+    });
+}
+const io = {
+    ask: question => prompt(question, false),
+    readSecret: question => prompt(question, true),
+    readStdin: async () => {
+        const chunks = [];
+        for await (const chunk of process.stdin)
+            chunks.push(Buffer.from(chunk));
+        return Buffer.concat(chunks).toString('utf8');
+    }
+};
 run(argv, {
     env: process.env,
     signal: controller.signal,
+    stdoutIsTty: Boolean(process.stdout.isTTY),
+    interactive: Boolean(process.stdin.isTTY),
+    io,
     output: {
         out: text => process.stdout.write(`${text}\n`),
         err: text => process.stderr.write(`${text}\n`),

package/dist/input.js

@@ -0,0 +1,39 @@
+import { readFileSync } from 'node:fs';
+import { UsageError, flag, hasFlag } from './args.js';
+/**
+ * Un corps JSON donné à une commande : `--input <fichier.json>` ou `--stdin`.
+ * `null` quand aucun des deux n'est donné.
+ */
+export async function readJsonInput(ctx) {
+    const file = flag(ctx.args, 'input');
+    const stdin = hasFlag(ctx.args, 'stdin');
+    if (file && stdin)
+        throw new UsageError('Give --input <file> or --stdin, not both.');
+    if (!file && !stdin)
+        return null;
+    let text;
+    if (file) {
+        try {
+            text = readFileSync(file, 'utf8');
+        }
+        catch (error) {
+            throw new UsageError(`Cannot read ${file}: ${error?.code === 'ENOENT' ? 'no such file' : error?.message ?? error}.`);
+        }
+    }
+    else {
+        text = await ctx.io.readStdin();
+    }
+    return parseJsonObject(text, file ?? 'stdin');
+}
+export function parseJsonObject(text, where) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch (error) {
+        throw new UsageError(`${where} is not valid JSON: ${error instanceof Error ? error.message : error}`);
+    }
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new UsageError(`${where} must hold one JSON object.`);
+    return value;
+}

package/dist/listen.js

@@ -124,7 +124,7 @@ export function pause(ms, signal) {
         signal.addEventListener('abort', done, { once: true });
     });
 }
-/** Ce qui ne se réessaie pas : la clé, le rôle, le client visé. */
+/** Ce qui ne se réessaie pas : la clé, un appel interdit, le client visé. */
 function isFatal(error) {
     return error instanceof NodiumError && (error.status === 401 || error.status === 403 || error.status === 404);
 }

package/dist/output.js

@@ -22,9 +22,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 +35,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)
+    ]));
+}