plazbot-cli 0.4.0 → 0.5.0

package/dist/commands/whatsapp/send-template.js

@@ -1,86 +1,87 @@
 import { Command } from 'commander';
-import { Message } from 'plazbot';
-import { getStoredCredentials } from '../../utils/credentials.js';
 import { logger } from '../../utils/logger.js';
-import { addExamples } from '../../utils/help.js';
+import { addExamples, addNotes } from '../../utils/help.js';
 import { createSpinner } from '../../utils/ui.js';
+import { jsonOption, isJsonMode, printJson, fail, CliError } from '../../utils/output.js';
+import { phoneOption, normalizePhone } from '../../utils/phone.js';
+import { ensureApiSuccess, getMessageClient, parseVariables } from './shared.js';
 export const sendTemplateCommand = new Command('send-template')
-    .description('Send a WhatsApp template message with variables')
-    .requiredOption('-p, --phone <number>', 'Phone number (with country code)')
-    .requiredOption('-t, --template <name>', 'Template name')
-    .option('--var <vars...>', 'Body variables (format: name=value)')
-    .option('--header-var <vars...>', 'Header variables (format: name=value)')
-    .option('--file-url <url>', 'Attachment file URL')
-    .option('--file-name <name>', 'Attachment file name')
+    .description('Send an approved WhatsApp template message')
+    .addOption(phoneOption('Recipient number in international format, e.g. +51912345678'))
+    .requiredOption('-t, --template <name>', 'Template name exactly as approved in Meta (e.g. welcome_message)')
+    .option('--var <name=value...>', 'Body variables, one or more name=value pairs (e.g. --var name=Anna code=PB-123)')
+    .option('--header-var <name=value...>', 'Header text variables, name=value pairs (e.g. --header-var store=Lima)')
+    .option('--file-url <url>', 'Public URL of the media for an image/video/document header')
+    .option('--file-name <name>', 'File name shown to the recipient for a document header (default: "file")')
+    .addOption(jsonOption())
     .option('--dev', 'Use development environment', false)
     .action(async (options) => {
     try {
-        const credentials = await getStoredCredentials();
-        const messageClient = new Message({
-            workspaceId: credentials.workspace,
-            apiKey: credentials.apiKey,
-            zone: credentials.zone,
-            ...(options.dev && { customUrl: "http://localhost:5090" })
-        });
-        // Parsear variables
-        const variablesBody = parseVariables(options.var);
-        const variablesHeader = parseVariables(options.headerVar);
-        // Archivo adjunto
-        const file = options.fileUrl ? {
-            fileUrl: options.fileUrl,
-            fileName: options.fileName || 'file',
-        } : undefined;
-        logger.title('Sending WhatsApp template');
-        logger.label('Destination', options.phone);
-        logger.label('Template', options.template);
-        if (variablesBody.length > 0) {
-            logger.label('Body variables', variablesBody.map(v => `${v.variable}=${v.value}`).join(', '));
+        const phone = normalizePhone(options.phone);
+        const template = String(options.template || '').trim();
+        if (!template) {
+            throw new CliError('Template name is required.', 'missing_template', 'Pass it with -t, --template <name>.');
         }
-        if (variablesHeader.length > 0) {
-            logger.label('Header variables', variablesHeader.map(v => `${v.variable}=${v.value}`).join(', '));
+        if (options.fileName && !options.fileUrl) {
+            throw new CliError('--file-name needs --file-url.', 'missing_file_url', 'Pass the media URL with --file-url <url>.');
         }
-        if (file) {
-            logger.label('File', file.fileUrl);
+        if (options.fileUrl && !/^https?:\/\/\S+$/i.test(options.fileUrl)) {
+            throw new CliError(`Invalid --file-url "${options.fileUrl}".`, 'invalid_file_url', 'Use a public http(s) URL.');
         }
-        const spinner = createSpinner('Sending...');
-        spinner.start();
-        const params = {
-            to: options.phone,
-            template: options.template,
-        };
+        const variablesBody = parseVariables(options.var, '--var');
+        const variablesHeader = parseVariables(options.headerVar, '--header-var');
+        const file = options.fileUrl ? { fileUrl: options.fileUrl, fileName: options.fileName || 'file' } : undefined;
+        const messageClient = await getMessageClient(options.dev);
+        if (!isJsonMode()) {
+            logger.title('Sending WhatsApp template');
+            logger.label('To', `+${phone}`);
+            logger.label('Template', template);
+            if (variablesBody.length > 0)
+                logger.label('Body variables', variablesBody.map(v => `${v.variable}=${v.value}`).join(', '));
+            if (variablesHeader.length > 0)
+                logger.label('Header variables', variablesHeader.map(v => `${v.variable}=${v.value}`).join(', '));
+            if (file)
+                logger.label('File', `${file.fileUrl} (${file.fileName})`);
+        }
+        const params = { to: phone, template };
         if (variablesBody.length > 0)
             params.variablesBody = variablesBody;
         if (variablesHeader.length > 0)
             params.variablesHeader = variablesHeader;
         if (file)
             params.file = file;
-        const response = await messageClient.onConversation(params);
-        spinner.succeed('Template sent successfully');
-        if (options.dev) {
-            logger.warning('Environment: development');
+        const spinner = createSpinner('Sending...').start();
+        let response;
+        try {
+            response = await messageClient.onConversation(params);
+            ensureApiSuccess(response, 'The template was not sent', "Check the template name and its variables in the panel (Templates), and that it's approved.");
+        }
+        catch (error) {
+            spinner.stop();
+            throw error;
+        }
+        spinner.succeed('Template sent');
+        if (isJsonMode()) {
+            printJson({ phone, template, status: 'sent', ...(response?.messageId && { messageId: response.messageId }) });
         }
     }
     catch (error) {
-        const message = error?.message || 'Unknown error while sending the template';
-        logger.error(message);
-        process.exit(1);
+        fail(error);
     }
 });
 addExamples(sendTemplateCommand, [
     { description: 'Send a template with no variables',
-        command: 'plazbot whatsapp send-template -p 51912345678 -t welcome_message' },
+        command: 'plazbot whatsapp send-template -p +51912345678 -t welcome_message' },
     { description: 'Send a template with body variables',
-        command: 'plazbot whatsapp send-template -p 51912345678 -t order_status --var name=Anna code=PB-123' },
-    { description: 'Send a template with an attached PDF',
-        command: 'plazbot whatsapp send-template -p 51912345678 -t invoice_template --file-url https://files.example.com/inv.pdf --file-name invoice.pdf' },
-    { description: 'Send a template with header and body variables',
-        command: 'plazbot whatsapp send-template -p 51912345678 -t promo --header-var image=https://img.example.com/banner.png --var amount=20' },
+        command: 'plazbot whatsapp send-template -p +51912345678 -t order_status --var name=Anna code=PB-123' },
+    { description: 'Header text variable plus body variable',
+        command: 'plazbot whatsapp send-template -p +51912345678 -t promo --header-var store=Lima --var amount=20' },
+    { description: 'Template with a document header',
+        command: 'plazbot whatsapp send-template -p +51912345678 -t invoice --file-url https://files.example.com/inv.pdf --file-name invoice.pdf' },
+]);
+addNotes(sendTemplateCommand, [
+    'Templates can be sent any time, including to new contacts and outside the 24h window.',
+    'Variables use name=value; the value may contain "=" and spaces (quote it: --var "name=Anna Lopez"). Empty values are rejected.',
+    '--header-var fills placeholders of a text header. For an image/video/document header use --file-url (and --file-name for documents).',
+    '--var and --header-var take several pairs; put them after the other options or repeat the flag.',
 ]);
-function parseVariables(vars) {
-    if (!vars)
-        return [];
-    return vars.map(v => {
-        const [variable, ...rest] = v.split('=');
-        return { variable: variable.trim(), value: rest.join('=').trim() };
-    }).filter(v => v.variable && v.value);
-}

package/dist/commands/whatsapp/send.js

@@ -1,46 +1,59 @@
-import { Command } from 'commander';
-import { Message } from 'plazbot';
-import { getStoredCredentials } from '../../utils/credentials.js';
+import { Command, Option } from 'commander';
 import { logger } from '../../utils/logger.js';
-import { addExamples } from '../../utils/help.js';
+import { addExamples, addNotes } from '../../utils/help.js';
 import { createSpinner } from '../../utils/ui.js';
+import { jsonOption, isJsonMode, printJson, fail, CliError } from '../../utils/output.js';
+import { phoneOption, normalizePhone } from '../../utils/phone.js';
+import { ensureApiSuccess, getMessageClient } from './shared.js';
+const WINDOW_HINT = "Free-form text only works within 24h of the contact's last message. Outside that window send an approved template: plazbot whatsapp send-template -p <number> -t <template>";
 export const sendMessageCommand = new Command('send-message')
-    .description('Send a direct WhatsApp message')
-    .requiredOption('-t, --to <phone>', 'Phone number (with country code, e.g.: 51912345678)')
-    .requiredOption('-m, --message <text>', 'Message to send')
+    .description('Send a free-form WhatsApp text message to a contact')
+    .addOption(phoneOption('Recipient number in international format, e.g. +51912345678'))
+    .addOption(new Option('-t, --to <phone>', 'Alias of --phone').hideHelp())
+    .requiredOption('-m, --message <text>', 'Text to send (quote it if it has spaces)')
+    .addOption(jsonOption())
     .option('--dev', 'Use development environment', false)
     .action(async (options) => {
     try {
-        const credentials = await getStoredCredentials();
-        const messageClient = new Message({
-            workspaceId: credentials.workspace,
-            apiKey: credentials.apiKey,
-            zone: credentials.zone,
-            ...(options.dev && { customUrl: "http://localhost:5090" })
-        });
-        logger.title('Sending WhatsApp message');
-        logger.label('Destination', options.to);
-        logger.label('Message', options.message);
-        const spinner = createSpinner('Sending...');
-        spinner.start();
-        const response = await messageClient.onWhatsappMessage({
-            message: options.message,
-            to: options.to
-        });
-        spinner.succeed('Message sent successfully');
-        if (options.dev) {
-            logger.warning('Environment: development');
+        const phone = normalizePhone(options.phone ?? options.to);
+        if (!options.message || !options.message.trim()) {
+            throw new CliError('Message is empty.', 'missing_message', 'Pass the text with -m, --message "Hello".');
+        }
+        const messageClient = await getMessageClient(options.dev);
+        if (!isJsonMode()) {
+            logger.title('Sending WhatsApp message');
+            logger.label('To', `+${phone}`);
+            logger.label('Message', options.message);
+        }
+        const spinner = createSpinner('Sending...').start();
+        let response;
+        try {
+            response = await messageClient.onWhatsappMessage({ message: options.message, to: phone });
+            ensureApiSuccess(response, 'The message was not sent', WINDOW_HINT);
+        }
+        catch (error) {
+            spinner.stop();
+            throw error;
+        }
+        spinner.succeed('Message sent');
+        if (isJsonMode()) {
+            printJson({ phone, status: 'sent', ...(response?.messageId && { messageId: response.messageId }) });
         }
     }
     catch (error) {
-        const message = error?.message || 'Unknown error while sending the message';
-        logger.error(message);
-        process.exit(1);
+        fail(error);
     }
 });
 addExamples(sendMessageCommand, [
-    { description: 'Send a quick WhatsApp message',
-        command: 'plazbot whatsapp send-message -t 51912345678 -m "Hello from Plazbot"' },
-    { description: 'Send through the development backend',
-        command: 'plazbot whatsapp send-message -t 51912345678 -m "Hi" --dev' },
+    { description: 'Send a quick text message',
+        command: 'plazbot whatsapp send-message -p +51912345678 -m "Hello from Plazbot"' },
+    { description: 'Any international format works (spaces, 00 prefix)',
+        command: 'plazbot whatsapp send-message -p "+51 912 345 678" -m "Your order is on its way"' },
+    { description: 'Machine-readable result for scripts',
+        command: 'plazbot whatsapp send-message -p +51912345678 -m "Hi" --json' },
+]);
+addNotes(sendMessageCommand, [
+    "WhatsApp only allows free-form text within 24 hours of the contact's last message (the 24h window).",
+    'Outside the window, or to message a new contact first, use an approved template: plazbot whatsapp send-template.',
+    'The contact must already exist in the workspace (it is created when they write to your number).',
 ]);

package/dist/commands/whatsapp/setup.js

@@ -4,7 +4,9 @@ import chalk from 'chalk';
 import inquirer from 'inquirer';
 import { apiBaseUrl, getStoredCredentials } from '../../utils/credentials.js';
 import { createSpinner, theme } from '../../utils/ui.js';
-import { logger } from '../../utils/logger.js';
+import { fail } from '../../utils/output.js';
+import { requireInteractive } from '../../utils/confirm.js';
+import { normalizePhone } from '../../utils/phone.js';
 import { addExamples, addNotes } from '../../utils/help.js';
 import { runBrowserLogin } from '../auth/browser-login.js';
 import { activateIntegration, apiHeaders, connectNewNumber, fetchIntegrations, integrationLabel, whatsappNumbers, } from './connect-flow.js';
@@ -61,12 +63,12 @@ async function ensureSession(opts) {
         return creds;
     }
     catch {
-        console.log(theme.muted('  No tienes una sesión activa. Vamos a iniciarla desde el navegador.'));
+        console.log(theme.muted('  No active session. Let\'s sign in from the browser.'));
         return runBrowserLogin({ dev: opts.dev, browser: opts.browser });
     }
 }
 async function chooseNumber(creds, opts) {
-    const spinner = createSpinner('Buscando números conectados...').start();
+    const spinner = createSpinner('Looking for connected numbers...').start();
     const numbers = whatsappNumbers(await fetchIntegrations(creds, opts.dev)).filter(n => !n.isUnofficialWsp);
     spinner.stop();
     let choice = 'new';
@@ -74,11 +76,11 @@ async function chooseNumber(creds, opts) {
         const answer = await inquirer.prompt([{
                 type: 'list',
                 name: 'choice',
-                message: '¿Qué número quieres usar?',
+                message: 'Which number do you want to use?',
                 choices: [
-                    ...numbers.map(n => ({ name: `${integrationLabel(n)}${n.isActive ? '' : chalk.hex('#EF5350')('  (inactivo)')}`, value: n.id })),
+                    ...numbers.map(n => ({ name: `${integrationLabel(n)}${n.isActive ? '' : chalk.hex('#EF5350')('  (inactive)')}`, value: n.id })),
                     new inquirer.Separator(),
-                    { name: 'Conectar un número nuevo', value: 'new' },
+                    { name: 'Connect a new number', value: 'new' },
                 ],
             }]);
         choice = answer.choice;
@@ -86,11 +88,11 @@ async function chooseNumber(creds, opts) {
     if (choice !== 'new') {
         const selected = numbers.find(n => n.id === choice);
         if (!selected.isActive) {
-            const act = createSpinner('Activando el número...').start();
+            const act = createSpinner('Activating the number...').start();
             if (await activateIntegration(creds, selected.id, opts.dev))
-                act.succeed('Número activo');
+                act.succeed('Number active');
             else
-                act.warn('No se pudo activar. Actívalo en el panel → Integraciones.');
+                act.warn('Could not activate it. Activate it in the panel → Integrations.');
         }
         console.log(`  ${chalk.green('✓')} ${integrationLabel(selected)}`);
         return selected;
@@ -98,10 +100,10 @@ async function chooseNumber(creds, opts) {
     const { kind } = await inquirer.prompt([{
             type: 'list',
             name: 'kind',
-            message: '¿Cómo quieres conectar WhatsApp?',
+            message: 'How do you want to connect WhatsApp?',
             choices: [
-                { name: `WhatsApp API ${theme.muted('— número nuevo o dedicado, ideal para enviar a escala')}`, value: 'api' },
-                { name: `WhatsApp Business ${theme.muted('— tu app actual en el celular (coexistencia, se vincula con QR)')}`, value: 'business' },
+                { name: `WhatsApp API ${theme.muted('— new or dedicated number, best for sending at scale')}`, value: 'api' },
+                { name: `WhatsApp Business ${theme.muted('— your current phone app (coexistence, linked by QR)')}`, value: 'business' },
             ],
         }]);
     return connectNewNumber(creds, { business: kind === 'business', dev: opts.dev, openInBrowser: opts.browser });
@@ -110,19 +112,25 @@ async function firstMessageTest(creds, number, dev) {
     const { phone } = await inquirer.prompt([{
             type: 'input',
             name: 'phone',
-            message: '¿Desde qué celular vas a escribir? (con código de país, p. ej. 51912345678)',
-            validate: (v) => /^\d{8,15}$/.test(v.replace(/\D/g, '')) || 'Escribe solo el número con código de país.',
+            message: 'Which phone will you write from? (international format, e.g. +51912345678)',
+            validate: (v) => { try {
+                normalizePhone(v);
+                return true;
+            }
+            catch {
+                return 'Enter the number with country code, e.g. +51912345678.';
+            } },
         }]);
-    const digits = String(phone).replace(/\D/g, '');
+    const digits = normalizePhone(String(phone));
     const target = number.cellphoneNumber || '';
     console.log();
-    console.log(`  Desde ese celular envía ${chalk.bold('"hola"')} por WhatsApp a ${chalk.bold(`+${target}`)}`);
+    console.log(`  From that phone, send ${chalk.bold('"hello"')} on WhatsApp to ${chalk.bold(`+${target}`)}`);
     if (target)
-        console.log(`  ${theme.muted('Atajo:')} ${chalk.underline(`https://wa.me/${target}?text=hola`)}`);
-    console.log(theme.muted('  Tu mensaje crea el contacto y abre la ventana de 24 h en la que WhatsApp permite responder con texto libre.'));
+        console.log(`  ${theme.muted('Shortcut:')} ${chalk.underline(`https://wa.me/${target}?text=hello`)}`);
+    console.log(theme.muted('  Your message creates the contact and opens the 24h window in which WhatsApp allows free-form replies.'));
     console.log();
     const since = Date.now() - 60_000;
-    const spinner = createSpinner('Esperando tu mensaje... (Ctrl+C para cancelar)').start();
+    const spinner = createSpinner('Waiting for your message... (Ctrl+C to cancel)').start();
     const deadline = Date.now() + 5 * 60_000;
     let contact = null;
     while (Date.now() < deadline && !contact) {
@@ -130,28 +138,28 @@ async function firstMessageTest(creds, number, dev) {
         contact = await findRecentContact(creds, dev, phoneVariants(digits), since, number.codeCellphoneNumberId);
     }
     if (!contact) {
-        spinner.warn('No recibimos tu mensaje en 5 minutos.');
-        console.log(theme.muted('  Revisa que el número esté activo y vuelve a ejecutar plazbot whatsapp setup.'));
+        spinner.warn('Your message did not arrive within 5 minutes.');
+        console.log(theme.muted('  Check that the number is active and run plazbot whatsapp setup again.'));
         return null;
     }
-    spinner.succeed(`Recibimos tu mensaje${contact.lastMessage ? `: "${contact.lastMessage}"` : ''}`);
-    const { reply } = await inquirer.prompt([{ type: 'confirm', name: 'reply', message: '¿Te respondemos desde la API?', default: true }]);
+    spinner.succeed(`Message received${contact.lastMessage ? `: "${contact.lastMessage}"` : ''}`);
+    const { reply } = await inquirer.prompt([{ type: 'confirm', name: 'reply', message: 'Reply to you from the API?', default: true }]);
     if (!reply)
         return contact.internalWhatsappNumber;
-    const sendSpinner = createSpinner('Enviando respuesta...').start();
+    const sendSpinner = createSpinner('Sending reply...').start();
     try {
         const res = await axios.post(`${apiBaseUrl(creds.zone, dev)}/api/message`, {
             workspaceId: creds.workspace,
             recipientPhone: contact.internalWhatsappNumber,
-            content: '¡Funciona! 🎉 Este mensaje lo envió tu código a través de la API de Plazbot.',
+            content: 'It works! 🎉 This message was sent by your code through the Plazbot API.',
         }, { headers: apiHeaders(creds) });
         if (res.data?.success === false)
-            throw new Error(res.data?.message || 'La API rechazó el envío.');
-        sendSpinner.succeed('Mensaje enviado. Revisa tu WhatsApp.');
+            throw new Error(res.data?.message || 'The API rejected the message.');
+        sendSpinner.succeed('Message sent. Check your WhatsApp.');
     }
     catch (error) {
         const msg = axios.isAxiosError(error) ? (error.response?.data?.message || error.message) : error.message;
-        sendSpinner.fail(`No se pudo enviar: ${msg}`);
+        sendSpinner.fail(`Could not send it: ${msg}`);
     }
     return contact.internalWhatsappNumber;
 }
@@ -159,24 +167,24 @@ async function webhookStep(creds, number, dev) {
     const { url } = await inquirer.prompt([{
             type: 'input',
             name: 'url',
-            message: 'URL de tu webhook para recibir los mensajes entrantes (Enter para omitir):',
+            message: 'Webhook URL to receive incoming messages (Enter to skip):',
             default: number.webhookUrl || '',
-            validate: (v) => !v || /^https:\/\/\S+$/.test(v) || 'Debe ser una URL https://',
+            validate: (v) => !v || /^https:\/\/\S+$/.test(v) || 'It must be an https:// URL',
         }]);
     if (!url) {
-        console.log(theme.muted('  Omitido. Puedes registrarlo después con: plazbot whatsapp register-webhook'));
+        console.log(theme.muted(`  Skipped. Register it later with: plazbot whatsapp register-webhook -p +${number.cellphoneNumber || '51912345678'} -u <url>`));
         return null;
     }
-    const spinner = createSpinner('Registrando webhook...').start();
+    const spinner = createSpinner('Registering webhook...').start();
     try {
         const res = await axios.post(`${apiBaseUrl(creds.zone, dev)}/api/workspace/${creds.workspace}/whatsapp/numbers/${number.cellphoneNumber}/webhook`, { webhook: url }, { headers: apiHeaders(creds) });
         if (res.data?.success === false)
             throw new Error(res.data?.message);
-        spinner.succeed(`Webhook registrado: ${url}`);
+        spinner.succeed(`Webhook registered: ${url}`);
         return url;
     }
     catch (error) {
-        spinner.fail(`No se pudo registrar el webhook${error instanceof Error && error.message ? `: ${error.message}` : ''}`);
+        spinner.fail(`Could not register the webhook${error instanceof Error && error.message ? `: ${error.message}` : ''}`);
         return null;
     }
 }
@@ -192,51 +200,53 @@ function printSnippet(creds, to) {
         ``,
         `await bot.message.onWhatsappMessage({`,
         `  to:      "${to || '51912345678'}",`,
-        `  message: "Hola desde mi app",`,
+        `  message: "Hello from my app",`,
         `})`,
     ];
-    console.log(`\n${chalk.bold('Listo. Usa esto en tu app')} ${theme.muted('(npm i plazbot)')}\n`);
+    console.log(`\n${chalk.bold('Done. Use this in your app')} ${theme.muted('(npm i plazbot)')}\n`);
     code.forEach(l => console.log('  ' + chalk.hex('#9CDCFE')(l)));
     console.log();
-    console.log(theme.muted('  Para tu servidor crea una API key en el panel → Configuración → Developer y guárdala en PLAZBOT_KEY.'));
+    console.log(theme.muted('  For your server, create an API key in the panel → Settings → Developer and store it in PLAZBOT_KEY.'));
     console.log(theme.muted('  Docs: https://developers.plazbot.com/sdk'));
     console.log();
 }
 export const whatsappSetupCommand = new Command('setup')
-    .description('Asistente: conecta WhatsApp y envía/recibe tu primer mensaje')
-    .option('--no-browser', 'No abrir el navegador automáticamente')
-    .option('--dev', 'Usar el entorno de desarrollo local', false)
+    .description('Guided setup: connect WhatsApp and send/receive your first message')
+    .option('--no-browser', 'Print links instead of opening the browser')
+    .option('--dev', 'Use development environment', false)
     .action(async (options) => {
     try {
-        console.log(`\n${chalk.bold('WhatsApp · configuración inicial')}`);
-        step(1, 'Tu cuenta');
+        requireInteractive('The WhatsApp setup wizard', 'Use the individual commands instead: plazbot whatsapp connect, send-message, register-webhook.');
+        console.log(`\n${chalk.bold('WhatsApp · first-time setup')}`);
+        step(1, 'Your account');
         const creds = await ensureSession(options);
-        step(2, 'Tu número de WhatsApp');
+        step(2, 'Your WhatsApp number');
         const number = await chooseNumber(creds, options);
         if (!number) {
-            console.log(theme.muted('\n  Ejecuta plazbot whatsapp setup de nuevo cuando termines el registro en Meta.\n'));
+            console.log(theme.muted('\n  Run plazbot whatsapp setup again when you finish the Meta sign-up.\n'));
             process.exit(1);
         }
-        step(3, 'Prueba de ida y vuelta');
+        step(3, 'Round-trip test');
         const to = await firstMessageTest(creds, number, options.dev);
-        step(4, 'Webhook (opcional)');
+        step(4, 'Webhook (optional)');
         await webhookStep(creds, number, options.dev);
         printSnippet(creds, to);
     }
     catch (error) {
         // Ctrl+C durante un prompt de inquirer
         if (error instanceof Error && error.name === 'ExitPromptError') {
-            console.log(theme.muted('\n  Cancelado.\n'));
+            console.log(theme.muted('\n  Cancelled.\n'));
             process.exit(130);
         }
-        logger.error(error instanceof Error ? error.message : 'Error desconocido');
-        process.exit(1);
+        fail(error);
     }
 });
 addExamples(whatsappSetupCommand, [
-    { description: 'Configurar WhatsApp paso a paso', command: 'plazbot whatsapp setup' },
+    { description: 'Set up WhatsApp step by step', command: 'plazbot whatsapp setup' },
+    { description: 'Print links instead of opening the browser', command: 'plazbot whatsapp setup --no-browser' },
 ]);
 addNotes(whatsappSetupCommand, [
-    'La prueba usa tu propio celular: le escribes "hola" a tu número y la API te responde.',
-    'Para escribir primero a un cliente nuevo necesitas una plantilla aprobada (plazbot whatsapp send-template).',
+    'The test uses your own phone: you text "hello" to your number and the API replies.',
+    'To message a new customer first you need an approved template (plazbot whatsapp send-template).',
+    'Needs an interactive terminal.',
 ]);

package/dist/commands/whatsapp/shared.js

@@ -0,0 +1,75 @@
+// Helpers shared by the WhatsApp commands (local to this folder).
+import { Agent, Message } from 'plazbot';
+import { getStoredCredentials } from '../../utils/credentials.js';
+import { CliError } from '../../utils/output.js';
+import { patchAgent } from '../../utils/agent-patch.js';
+const DEV_URL = 'http://localhost:5090';
+export async function getMessageClient(dev) {
+    const credentials = await getStoredCredentials();
+    return new Message({
+        workspaceId: credentials.workspace,
+        apiKey: credentials.apiKey,
+        zone: credentials.zone,
+        ...(dev && { customUrl: DEV_URL }),
+    });
+}
+export async function getAgentClient(dev) {
+    const credentials = await getStoredCredentials();
+    const agent = new Agent({
+        workspaceId: credentials.workspace,
+        apiKey: credentials.apiKey,
+        zone: credentials.zone,
+        ...(dev && { customUrl: DEV_URL }),
+    });
+    return { agent, credentials };
+}
+/**
+ * The SDK only throws on non-2xx; the API may still answer 200 with success:false
+ * (e.g. outside the 24h window). Surface that message instead of reporting success.
+ */
+export function ensureApiSuccess(response, fallback, hint) {
+    if (response && response.success === false) {
+        const errors = Array.isArray(response.errors) ? response.errors : [];
+        const details = errors.map(e => (typeof e === 'string' ? e : JSON.stringify(e))).join('; ');
+        const message = String(response.message || fallback).replace(/\.?$/, '.');
+        throw new CliError(details ? `${message} ${details}` : message, 'api_rejected', hint);
+    }
+}
+/**
+ * Parses `name=value` pairs from --var / --header-var. Strict: a pair without "=",
+ * without a name or with an empty value is an error (it is never dropped silently).
+ * The value may contain "=" (only the first one splits).
+ */
+export function parseVariables(vars, flag) {
+    if (!vars)
+        return [];
+    return vars.map(raw => {
+        const idx = raw.indexOf('=');
+        const variable = idx >= 0 ? raw.slice(0, idx).trim() : '';
+        const value = idx >= 0 ? raw.slice(idx + 1).trim() : '';
+        if (idx < 0 || !variable) {
+            throw new CliError(`Invalid ${flag} "${raw}".`, 'invalid_variable', `Use the format ${flag} name=value (e.g. ${flag} name=Anna).`);
+        }
+        if (!value) {
+            throw new CliError(`Variable "${variable}" in ${flag} has an empty value.`, 'empty_variable', 'WhatsApp rejects empty template variables. Pass a value, e.g. name=Anna.');
+        }
+        return { variable, value };
+    });
+}
+/** Digits only, to compare numbers stored in different formats (+51 9..., 519...). */
+export function phoneDigits(value) {
+    return String(value ?? '').replace(/\D/g, '');
+}
+/** Full agent document (getAgentById answers {agent}, {data} or the agent itself). */
+export async function fetchFullAgent(agent, agentId) {
+    const response = await agent.getAgentById({ id: agentId });
+    const current = response?.agent || response?.data || response;
+    if (!current || !current.name) {
+        throw new CliError(`Agent ${agentId} not found in the active workspace.`, 'not_found', "Check the ID with 'plazbot agent list'.");
+    }
+    return current;
+}
+/** Changes only the given fields of the agent (see utils/agent-patch.ts). */
+export async function updateAgentMerged(credentials, dev, agentId, current, patch) {
+    await patchAgent({ apiKey: credentials.apiKey, workspace: credentials.workspace, zone: credentials.zone, dev }, agentId, patch, current);
+}