plazbot-cli 0.2.26 → 0.3.2

package/src/commands/portal/list.ts

@@ -1,12 +1,13 @@
 import { Command } from 'commander';
 import { Portal } from 'plazbot';
-import { getStoredCredentials } from '../../utils/credentials';
-import { logger } from '../../utils/logger';
-import { PortalCommandOptions } from '../../types/portal';
+import { getStoredCredentials } from '../../utils/credentials.js';
+import { logger } from '../../utils/logger.js';
+import { addExamples } from '../../utils/help.js';
+import { PortalCommandOptions } from '../../types/portal.js';
 
 export const listCommand = new Command('list')
-  .description('Muestra el portal asociado al workspace')
-  .option('--dev', 'Usar ambiente de desarrollo', false)
+  .description('Show the portal associated with the workspace')
+  .option('--dev', 'Use development environment', false)
   .action(async (options: PortalCommandOptions) => {
     try {
       // Obtener credenciales guardadas
@@ -22,50 +23,57 @@ export const listCommand = new Command('list')
       const response = await portal.getExistsPortal();
       const portalDetails = response.portal;
 
-      logger.title('Portal encontrado');
+      logger.title('Portal found');
       logger.label('ID', portalDetails.id);
-      logger.label('Nombre', portalDetails.name);
+      logger.label('Name', portalDetails.name);
       logger.label('URL', portalDetails.url);
-      logger.label('Acceso', portalDetails.access || 'N/A');
-      logger.label('Estado', portalDetails.disabled ? 'Deshabilitado' : 'Habilitado');
+      logger.label('Access', portalDetails.access || 'N/A');
+      logger.label('Status', portalDetails.disabled ? 'Disabled' : 'Enabled');
 
       if (portalDetails.title) {
-        logger.label('Titulo', portalDetails.title);
+        logger.label('Title', portalDetails.title);
       }
       if (portalDetails.subtitle) {
-        logger.label('Subtitulo', portalDetails.subtitle);
+        logger.label('Subtitle', portalDetails.subtitle);
       }
 
       if (portalDetails.logo) {
-        logger.title('Recursos');
+        logger.title('Assets');
         logger.label('Logo', portalDetails.logo);
         if (portalDetails.logodark) {
-          logger.label('Logo (modo oscuro)', portalDetails.logodark);
+          logger.label('Logo (dark mode)', portalDetails.logodark);
         }
       }
 
       const portalAny = portalDetails as any;
       if (portalAny.links && portalAny.links.length > 0) {
-        logger.title('Enlaces');
+        logger.title('Links');
         portalAny.links.forEach((link: { value: string; url: string }) => {
           logger.label(link.value, link.url);
         });
       }
 
       if (portalAny.agents && portalAny.agents.length > 0) {
-        logger.title('Agentes asociados');
+        logger.title('Associated agents');
         portalAny.agents.forEach((agent: { name: string; id: string }) => {
           logger.label(agent.name, agent.id);
         });
       }
-      
+
       if (options.dev) {
-        logger.warning('\nAmbiente: desarrollo');
+        logger.warning('\nEnvironment: development');
       }
 
     } catch (error) {
-      const message = error instanceof Error ? error.message : 'Error desconocido al listar el portal';
+      const message = error instanceof Error ? error.message : 'Unknown error while listing the portal';
       logger.error(message);
       process.exit(1);
     }
-  }); 
+  });
+
+addExamples(listCommand, [
+  { description: 'Show the portal of the active workspace',
+    command: 'plazbot portal list' },
+  { description: 'Use the development backend',
+    command: 'plazbot portal list --dev' },
+]);

package/src/commands/portal/update.ts

@@ -1,21 +1,22 @@
 import { Command } from 'commander';
 import { Portal } from 'plazbot';
-import { getStoredCredentials } from '../../utils/credentials';
-import { logger } from '../../utils/logger';
-import { PortalCommandOptions } from '../../types/portal';
+import { getStoredCredentials } from '../../utils/credentials.js';
+import { logger } from '../../utils/logger.js';
+import { addExamples } from '../../utils/help.js';
+import { PortalCommandOptions } from '../../types/portal.js';
 
 export const updateCommand = new Command('update')
-  .description('Actualiza un portal existente')
-  .argument('<portalId>', 'ID del portal a actualizar')
-  .option('-n, --name <name>', 'Nuevo nombre del portal')
-  .option('-t, --title <title>', 'Nuevo título del portal')
-  .option('-s, --subtitle <subtitle>', 'Nuevo subtítulo del portal')
-  .option('-l, --logo <url>', 'Nueva URL del logo')
-  .option('-d, --logo-dark <url>', 'Nueva URL del logo en modo oscuro')
-  .option('-a, --access <type>', 'Tipo de acceso (direct o form)')
-  .option('--disabled <value>', 'Estado de deshabilitación (true o false)')
-  .option('--brand-off <value>', 'Estado de marca deshabilitada (true o false)')
-  .option('--dev', 'Usar ambiente de desarrollo', false)
+  .description('Update an existing portal')
+  .argument('<portalId>', 'ID of the portal to update')
+  .option('-n, --name <name>', 'New portal name')
+  .option('-t, --title <title>', 'New portal title')
+  .option('-s, --subtitle <subtitle>', 'New portal subtitle')
+  .option('-l, --logo <url>', 'New logo URL')
+  .option('-d, --logo-dark <url>', 'New dark-mode logo URL')
+  .option('-a, --access <type>', 'Access type (direct or form)')
+  .option('--disabled <value>', 'Disabled state (true or false)')
+  .option('--brand-off <value>', 'Brand-off state (true or false)')
+  .option('--dev', 'Use development environment', false)
   .action(async (portalId: string, options: PortalCommandOptions) => {
     try {
       // Obtener credenciales guardadas
@@ -31,7 +32,7 @@ export const updateCommand = new Command('update')
       // Obtener detalles actuales del portal
       const currentPortal = await portal.getPortal(portalId);
 
-      logger.title('Portal actual');
+      logger.title('Current portal');
       logger.json(currentPortal.portal);
       
       // Construir objeto de actualización solo con los campos proporcionados
@@ -44,38 +45,49 @@ export const updateCommand = new Command('update')
       if (options.logoDark) updateData.logodark = options.logoDark;
       if (options.access) {
         if (options.access !== 'direct' && options.access !== 'form') {
-          throw new Error('El tipo de acceso debe ser "direct" o "form"');
+          throw new Error('Access type must be "direct" or "form"');
         }
         updateData.access = options.access;
       }
       if (options.disabled) {
         if (options.disabled !== 'true' && options.disabled !== 'false') {
-          throw new Error('El valor de disabled debe ser "true" o "false"');
+          throw new Error('The disabled value must be "true" or "false"');
         }
         updateData.disabled = options.disabled === 'true';
       }
       if (options.brandOff) {
         if (options.brandOff !== 'true' && options.brandOff !== 'false') {
-          throw new Error('El valor de brand-off debe ser "true" o "false"');
+          throw new Error('The brand-off value must be "true" or "false"');
         }
         updateData.brandOff = options.brandOff === 'true';
       }
 
-      logger.title('Cambios a aplicar');
+      logger.title('Changes to apply');
       logger.json(updateData);
-      
+
       const result = await portal.updatePortal(updateData);
 
-      logger.success('Portal actualizado exitosamente');
-      logger.label('Mensaje', result.message);
-      
+      logger.success('Portal updated successfully');
+      logger.label('Message', result.message);
+
       if (options.dev) {
-        logger.warning('\nAmbiente: desarrollo');
+        logger.warning('\nEnvironment: development');
       }
 
     } catch (error) {
-      const message = error instanceof Error ? error.message : 'Error desconocido al actualizar el portal';
+      const message = error instanceof Error ? error.message : 'Unknown error while updating the portal';
       logger.error(message);
       process.exit(1);
     }
-  }); 
+  });
+
+addExamples(updateCommand, [
+  { description: 'Rename a portal',
+    command: 'plazbot portal update prt_AbcDef123 -n "Support Center"' },
+  { description: 'Switch access to form mode and update title',
+    command: 'plazbot portal update prt_AbcDef123 -a form -t "Sign in to continue"' },
+  { description: 'Disable a portal',
+    command: 'plazbot portal update prt_AbcDef123 --disabled true' },
+  { description: 'Hide the Plazbot brand and update the logo',
+    command: 'plazbot portal update prt_AbcDef123 --brand-off true -l https://files.example.com/logo.png' },
+]);

package/src/commands/whatsapp/broadcast.ts

@@ -1,17 +1,18 @@
 import { Command } from 'commander';
 import { Message } from 'plazbot';
-import { getStoredCredentials } from '../../utils/credentials';
-import { logger } from '../../utils/logger';
-import { createSpinner, theme, section, progressBar } from '../../utils/ui';
+import { getStoredCredentials } from '../../utils/credentials.js';
+import { logger } from '../../utils/logger.js';
+import { addExamples } from '../../utils/help.js';
+import { createSpinner, theme, section, progressBar } from '../../utils/ui.js';
 import fs from 'fs/promises';
 
 export const broadcastCommand = new Command('broadcast')
-  .description('Envio masivo de mensajes de template WhatsApp')
-  .requiredOption('-t, --template <name>', 'Nombre del template')
-  .requiredOption('--phones <file>', 'Archivo CSV con numeros de telefono (uno por linea)')
-  .option('--var <vars...>', 'Variables del body (formato: name=valor)')
-  .option('--delay <ms>', 'Delay entre mensajes en ms', '1000')
-  .option('--dev', 'Usar ambiente de desarrollo', false)
+  .description('Bulk send WhatsApp template messages')
+  .requiredOption('-t, --template <name>', 'Template name')
+  .requiredOption('--phones <file>', 'CSV file with phone numbers (one per line)')
+  .option('--var <vars...>', 'Body variables (format: name=value)')
+  .option('--delay <ms>', 'Delay between messages in ms', '1000')
+  .option('--dev', 'Use development environment', false)
   .action(async (options: any) => {
     try {
       const credentials = await getStoredCredentials();
@@ -31,19 +32,19 @@ export const broadcastCommand = new Command('broadcast')
           .map(line => line.trim())
           .filter(line => line && !line.startsWith('#'));
       } catch {
-        throw new Error(`No se pudo leer el archivo: ${options.phones}`);
+        throw new Error(`Could not read file: ${options.phones}`);
       }
 
       if (phones.length === 0) {
-        throw new Error('El archivo no contiene numeros de telefono');
+        throw new Error('The file does not contain phone numbers');
       }
 
       // Parsear variables
       const variablesBody = parseVariables(options.var);
 
-      console.log(section('Broadcast WhatsApp'));
+      console.log(section('WhatsApp Broadcast'));
       logger.label('Template', options.template);
-      logger.label('Destinatarios', String(phones.length));
+      logger.label('Recipients', String(phones.length));
       logger.label('Delay', `${options.delay}ms`);
       if (variablesBody.length > 0) {
         logger.label('Variables', variablesBody.map(v => `${v.variable}=${v.value}`).join(', '));
@@ -67,7 +68,7 @@ export const broadcastCommand = new Command('broadcast')
           sent++;
         } catch {
           failed++;
-          console.log(theme.error(`  ✖ Fallo: ${phone}`));
+          console.log(theme.error(`  ✖ Failed: ${phone}`));
         }
 
         // Progress
@@ -79,18 +80,27 @@ export const broadcastCommand = new Command('broadcast')
         }
       }
 
-      console.log(section('Resultado'));
-      logger.label('Enviados', theme.success(String(sent)));
-      logger.label('Fallidos', failed > 0 ? theme.error(String(failed)) : '0');
+      console.log(section('Result'));
+      logger.label('Sent', theme.success(String(sent)));
+      logger.label('Failed', failed > 0 ? theme.error(String(failed)) : '0');
       logger.label('Total', String(phones.length));
 
     } catch (error: unknown) {
-      const message = (error as Error)?.message || 'Error desconocido';
+      const message = (error as Error)?.message || 'Unknown error';
       logger.error(message);
       process.exit(1);
     }
   });
 
+addExamples(broadcastCommand, [
+  { description: 'Broadcast a template to a phone list (default 1s delay)',
+    command: 'plazbot whatsapp broadcast -t welcome --phones ./phones.csv' },
+  { description: 'Broadcast with body variables',
+    command: 'plazbot whatsapp broadcast -t promo --phones ./contacts.csv --var amount=20 code=PROMO20' },
+  { description: 'Slow broadcast (3s delay) to avoid rate limits',
+    command: 'plazbot whatsapp broadcast -t reminder --phones ./list.csv --delay 3000' },
+]);
+
 function parseVariables(vars: string[] | undefined): { variable: string; value: string }[] {
   if (!vars) return [];
   return vars.map(v => {

package/src/commands/whatsapp/channels.ts

@@ -1,12 +1,13 @@
 import { Command } from 'commander';
 import { Agent } from 'plazbot';
-import { getStoredCredentials } from '../../utils/credentials';
-import { logger } from '../../utils/logger';
-import { createSpinner, createTable, theme, section, statusBadge } from '../../utils/ui';
+import { getStoredCredentials } from '../../utils/credentials.js';
+import { logger } from '../../utils/logger.js';
+import { addExamples } from '../../utils/help.js';
+import { createSpinner, createTable, theme, section, statusBadge } from '../../utils/ui.js';
 
 export const channelsCommand = new Command('channels')
-  .description('Listar agentes con canales de WhatsApp asignados')
-  .option('--dev', 'Usar ambiente de desarrollo', false)
+  .description('List agents with assigned WhatsApp channels')
+  .option('--dev', 'Use development environment', false)
   .action(async (options: any) => {
     try {
       const credentials = await getStoredCredentials();
@@ -17,20 +18,20 @@ export const channelsCommand = new Command('channels')
         ...(options.dev && { customUrl: "http://localhost:5090" })
       });
 
-      const spinner = createSpinner('Cargando canales...');
+      const spinner = createSpinner('Loading channels...');
       spinner.start();
       const agents = await agent.getAgents();
       spinner.stop();
 
-      console.log(section('Canales WhatsApp'));
+      console.log(section('WhatsApp Channels'));
 
       const whatsappAgents = (agents || []).filter((a: any) =>
         a.channels && a.channels.some((c: any) => c.channel === 'whatsapp')
       );
 
       if (whatsappAgents.length === 0) {
-        console.log(theme.muted('\n  No hay agentes con WhatsApp configurado'));
-        console.log(theme.muted('  Usa el wizard: plazbot agent create\n'));
+        console.log(theme.muted('\n  No agents with WhatsApp configured'));
+        console.log(theme.muted('  Use the wizard: plazbot agent create\n'));
         return;
       }
 
@@ -44,20 +45,25 @@ export const channelsCommand = new Command('channels')
         ];
       });
 
-      console.log(createTable(['Agent ID', 'Nombre', 'Numero WhatsApp', 'Estado'], rows));
+      console.log(createTable(['Agent ID', 'Name', 'WhatsApp Number', 'Status'], rows));
 
     } catch (error) {
-      const message = error instanceof Error ? error.message : 'Error desconocido';
+      const message = error instanceof Error ? error.message : 'Unknown error';
       logger.error(message);
       process.exit(1);
     }
   });
 
+addExamples(channelsCommand, [
+  { description: 'List agents that have a WhatsApp number assigned',
+    command: 'plazbot whatsapp channels' },
+]);
+
 export const assignCommand = new Command('assign')
-  .description('Asignar un agente a un numero de WhatsApp')
-  .argument('<phone>', 'Numero de WhatsApp')
-  .argument('<agentId>', 'ID del agente')
-  .option('--dev', 'Usar ambiente de desarrollo', false)
+  .description('Assign an agent to a WhatsApp number')
+  .argument('<phone>', 'WhatsApp number')
+  .argument('<agentId>', 'Agent ID')
+  .option('--dev', 'Use development environment', false)
   .action(async (phone: string, agentId: string, options: any) => {
     try {
       const credentials = await getStoredCredentials();
@@ -68,7 +74,7 @@ export const assignCommand = new Command('assign')
         ...(options.dev && { customUrl: "http://localhost:5090" })
       });
 
-      const spinner = createSpinner('Cargando agente...');
+      const spinner = createSpinner('Loading agent...');
       spinner.start();
       const agentData = await agent.getAgentById({ id: agentId });
       spinner.stop();
@@ -78,21 +84,26 @@ export const assignCommand = new Command('assign')
       // Verificar si ya tiene este canal
       const existing = channels.findIndex((c: any) => c.channel === 'whatsapp' && c.key === phone);
       if (existing >= 0) {
-        logger.warning('Este numero ya esta asignado a este agente');
+        logger.warning('This number is already assigned to this agent');
         return;
       }
 
       // Agregar canal
       channels.push({ channel: 'whatsapp', key: phone, multianswer: false });
 
-      const updateSpinner = createSpinner('Asignando...');
+      const updateSpinner = createSpinner('Assigning...');
       updateSpinner.start();
       await agent.updateAgent(agentId, { channels });
-      updateSpinner.succeed(`Agente "${agentData.name}" asignado a WhatsApp ${phone}`);
+      updateSpinner.succeed(`Agent "${agentData.name}" assigned to WhatsApp ${phone}`);
 
     } catch (error) {
-      const message = error instanceof Error ? error.message : 'Error desconocido';
+      const message = error instanceof Error ? error.message : 'Unknown error';
       logger.error(message);
       process.exit(1);
     }
   });
+
+addExamples(assignCommand, [
+  { description: 'Assign a WhatsApp number to an agent',
+    command: 'plazbot whatsapp assign 51912345678 agt_AbcDef123' },
+]);

package/src/commands/whatsapp/chat.ts

@@ -1,15 +1,16 @@
 import { Command } from 'commander';
 import { Message } from 'plazbot';
-import { getStoredCredentials } from '../../utils/credentials';
-import { logger } from '../../utils/logger';
-import { createSpinner, theme } from '../../utils/ui';
+import { getStoredCredentials } from '../../utils/credentials.js';
+import { logger } from '../../utils/logger.js';
+import { addExamples } from '../../utils/help.js';
+import { createSpinner, theme } from '../../utils/ui.js';
 import readline from 'readline';
 import chalk from 'chalk';
 
 export const whatsappChatCommand = new Command('chat')
-  .description('Chat interactivo directo por WhatsApp')
-  .argument('<phone>', 'Numero de telefono destino (con codigo de pais)')
-  .option('--dev', 'Usar ambiente de desarrollo', false)
+  .description('Interactive direct chat over WhatsApp')
+  .argument('<phone>', 'Destination phone number (with country code)')
+  .option('--dev', 'Use development environment', false)
   .action(async (phone: string, options: any) => {
     try {
       const credentials = await getStoredCredentials();
@@ -30,8 +31,8 @@ export const whatsappChatCommand = new Command('chat')
       console.log();
       console.log(chalk.hex('#25D366')('  ┌' + '─'.repeat(50) + '┐'));
       console.log(chalk.hex('#25D366')('  │') + chalk.bold(`  WhatsApp Chat`).padEnd(60) + chalk.hex('#25D366')('│'));
-      console.log(chalk.hex('#25D366')('  │') + chalk.gray(`  Destino: ${phone}`).padEnd(60) + chalk.hex('#25D366')('│'));
-      console.log(chalk.hex('#25D366')('  │') + chalk.gray('  /exit para salir').padEnd(60) + chalk.hex('#25D366')('│'));
+      console.log(chalk.hex('#25D366')('  │') + chalk.gray(`  Destination: ${phone}`).padEnd(60) + chalk.hex('#25D366')('│'));
+      console.log(chalk.hex('#25D366')('  │') + chalk.gray('  /exit to quit').padEnd(60) + chalk.hex('#25D366')('│'));
       console.log(chalk.hex('#25D366')('  └' + '─'.repeat(50) + '┘'));
       console.log();
 
@@ -43,13 +44,13 @@ export const whatsappChatCommand = new Command('chat')
           }
 
           if (message.toLowerCase() === '/exit') {
-            console.log(chalk.gray('\n  Chat terminado.\n'));
+            console.log(chalk.gray('\n  Chat ended.\n'));
             rl.close();
             return;
           }
 
           try {
-            const spinner = createSpinner('Enviando...');
+            const spinner = createSpinner('Sending...');
             spinner.start();
 
             await messageClient.onWhatsappMessage({
@@ -57,7 +58,7 @@ export const whatsappChatCommand = new Command('chat')
               to: phone,
             });
 
-            spinner.succeed('Enviado');
+            spinner.succeed('Sent');
             ask();
           } catch (error) {
             const msg = error instanceof Error ? error.message : 'Error';
@@ -70,8 +71,15 @@ export const whatsappChatCommand = new Command('chat')
       ask();
 
     } catch (error) {
-      const message = error instanceof Error ? error.message : 'Error desconocido';
+      const message = error instanceof Error ? error.message : 'Unknown error';
       logger.error(message);
       process.exit(1);
     }
   });
+
+addExamples(whatsappChatCommand, [
+  { description: 'Open an interactive chat with a WhatsApp number',
+    command: 'plazbot whatsapp chat 51912345678' },
+  { description: 'Chat through the development backend',
+    command: 'plazbot whatsapp chat 51912345678 --dev' },
+]);