plazbot-cli 0.4.0 → 0.5.0

package/dist/commands/portal/index.js

@@ -1,30 +1,30 @@
 import { Command } from 'commander';
-import { addExamples } from '../../utils/help.js';
+import { addExamples, addNotes } from '../../utils/help.js';
 import { getCommand } from './get.js';
 import { deleteCommand } from './delete.js';
 import { createCommand } from './create.js';
 import { updateCommand } from './update.js';
-import { addAgentCommand } from './add-agent.js';
+import { addAgentCommand, removeAgentCommand } from './add-agent.js';
 import { listCommand } from './list.js';
 import { addLinkCommand } from './add-link.js';
 import { clearLinksCommand } from './clear-links.js';
 export const portalCommands = new Command('portal')
-    .description('Commands related to portals')
+    .description('Manage the public web portal where customers chat with your agents')
     .addCommand(listCommand)
     .addCommand(getCommand)
-    .addCommand(deleteCommand)
     .addCommand(createCommand)
     .addCommand(updateCommand)
+    .addCommand(deleteCommand)
     .addCommand(addAgentCommand)
+    .addCommand(removeAgentCommand)
     .addCommand(addLinkCommand)
     .addCommand(clearLinksCommand);
 addExamples(portalCommands, [
-    { description: 'List the portal of the active workspace',
-        command: 'plazbot portal list' },
-    { description: 'Create a portal',
-        command: 'plazbot portal create -n "Help Center" -t "Welcome"' },
-    { description: 'Attach an agent to a portal',
-        command: 'plazbot portal add-agent-portal -p prt_AbcDef123 -a agt_AbcDef123' },
-    { description: 'Add a link to a portal',
-        command: 'plazbot portal add-link prt_AbcDef123 -t "Docs" -u https://docs.example.com' },
+    { description: 'Show the portal of the active workspace', command: 'plazbot portal list' },
+    { description: 'Create a portal', command: 'plazbot portal create -n "Help Center" -t "Welcome"' },
+    { description: 'Attach an agent to the portal', command: 'plazbot portal add-agent por_AbcDef123 -a age_AbcDef123' },
+    { description: 'Add a link to the portal', command: 'plazbot portal add-link por_AbcDef123 -t "Docs" -u https://docs.example.com' },
+]);
+addNotes(portalCommands, [
+    'Each workspace has at most one portal.',
 ]);

package/dist/commands/portal/list.js

@@ -1,68 +1,50 @@
 import { Command } from 'commander';
-import { Portal } 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 { jsonOption, isJsonMode, printJson, fail, CliError } from '../../utils/output.js';
+import { createSpinner } from '../../utils/ui.js';
+import { createPortalClient, printPortalDetails } from './shared.js';
 export const listCommand = new Command('list')
-    .description('Show the portal associated with the workspace')
+    .description('Show the portal of the active workspace (one portal per workspace)')
+    .addOption(jsonOption())
     .option('--dev', 'Use development environment', false)
     .action(async (options) => {
     try {
-        // Obtener credenciales guardadas
-        const credentials = await getStoredCredentials();
-        const portal = new Portal({
-            workspaceId: credentials.workspace,
-            apiKey: credentials.apiKey,
-            zone: credentials.zone,
-            ...(options.dev && { customUrl: "http://localhost:5090" })
-        });
-        const response = await portal.getExistsPortal();
-        const portalDetails = response.portal;
-        logger.title('Portal found');
-        logger.label('ID', portalDetails.id);
-        logger.label('Name', portalDetails.name);
-        logger.label('URL', portalDetails.url);
-        logger.label('Access', portalDetails.access || 'N/A');
-        logger.label('Status', portalDetails.disabled ? 'Disabled' : 'Enabled');
-        if (portalDetails.title) {
-            logger.label('Title', portalDetails.title);
+        const { portal } = await createPortalClient(options.dev);
+        const spinner = createSpinner('Loading portal...').start();
+        let details;
+        try {
+            const response = await portal.getExistsPortal();
+            details = response?.portal || undefined;
         }
-        if (portalDetails.subtitle) {
-            logger.label('Subtitle', portalDetails.subtitle);
-        }
-        if (portalDetails.logo) {
-            logger.title('Assets');
-            logger.label('Logo', portalDetails.logo);
-            if (portalDetails.logodark) {
-                logger.label('Logo (dark mode)', portalDetails.logodark);
+        catch (error) {
+            const message = error instanceof Error ? error.message : '';
+            if (!/not found/i.test(message)) {
+                spinner.stop();
+                throw error;
             }
         }
-        const portalAny = portalDetails;
-        if (portalAny.links && portalAny.links.length > 0) {
-            logger.title('Links');
-            portalAny.links.forEach((link) => {
-                logger.label(link.value, link.url);
-            });
-        }
-        if (portalAny.agents && portalAny.agents.length > 0) {
-            logger.title('Associated agents');
-            portalAny.agents.forEach((agent) => {
-                logger.label(agent.name, agent.id);
-            });
+        spinner.stop();
+        if (!details) {
+            if (isJsonMode())
+                printJson(null);
+            throw new CliError('This workspace has no portal yet.', 'portal_not_found', 'Create one with: plazbot portal create -n "Help Center" -t "Welcome"');
         }
-        if (options.dev) {
-            logger.warning('\nEnvironment: development');
+        if (isJsonMode()) {
+            printJson(details);
+            return;
         }
+        printPortalDetails(details, 'Workspace portal');
+        console.log();
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : 'Unknown error while listing the portal';
-        logger.error(message);
-        process.exit(1);
+        fail(error);
     }
 });
 addExamples(listCommand, [
-    { description: 'Show the portal of the active workspace',
-        command: 'plazbot portal list' },
-    { description: 'Use the development backend',
-        command: 'plazbot portal list --dev' },
+    { description: 'Show the portal of the active workspace', command: 'plazbot portal list' },
+    { description: 'Get the portal as JSON (null when there is none)', command: 'plazbot portal list --json' },
+    { description: 'Extract only the portal ID', command: "plazbot portal list --json | jq -r '.id'" },
+]);
+addNotes(listCommand, [
+    'A workspace can have a single portal. Exits with code 1 when there is none.',
 ]);

package/dist/commands/portal/shared.js

@@ -0,0 +1,92 @@
+// Helpers shared by the `plazbot portal` subcommands.
+import { Portal } from 'plazbot';
+import { getStoredCredentials } from '../../utils/credentials.js';
+import { logger } from '../../utils/logger.js';
+import { CliError } from '../../utils/output.js';
+/** Builds an SDK Portal client from the active session. */
+export async function createPortalClient(dev) {
+    const credentials = await getStoredCredentials();
+    const portal = new Portal({
+        workspaceId: credentials.workspace,
+        apiKey: credentials.apiKey,
+        zone: credentials.zone,
+        ...(dev && { customUrl: 'http://localhost:5090' }),
+    });
+    return { portal, credentials };
+}
+/** Resolves the portal ID from the positional argument or a legacy option. */
+export function resolvePortalId(positional, legacy) {
+    const id = (positional || legacy || '').trim();
+    if (!id) {
+        throw new CliError('Portal ID is required.', 'missing_portal_id', "Pass it as the first argument. Find it with 'plazbot portal list'.");
+    }
+    return id;
+}
+/** The SDK only accepts PNG/JPG logos given as an absolute URL or a path starting with "/". */
+export function validateLogo(value, flag) {
+    const url = value.trim();
+    if (!/^(https?:\/\/|\/)/i.test(url) || !/\.(png|jpg)$/i.test(url)) {
+        throw new CliError(`Invalid logo for ${flag}: "${value}".`, 'invalid_logo', 'Use a .png or .jpg URL (https://...) or a path starting with "/".');
+    }
+    return url;
+}
+export function validateAccess(value) {
+    const access = value.trim().toLowerCase();
+    if (access !== 'direct' && access !== 'form') {
+        throw new CliError(`Invalid access type "${value}".`, 'invalid_access', 'Use "direct" or "form".');
+    }
+    return access;
+}
+export function validateHttpUrl(value, flag) {
+    const url = value.trim();
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new CliError(`Invalid URL for ${flag}: "${value}".`, 'invalid_url', 'Use a full URL starting with http:// or https://.');
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        throw new CliError(`Invalid URL for ${flag}: "${value}".`, 'invalid_url', 'Only http:// and https:// URLs are allowed.');
+    }
+    return url;
+}
+/** Parses a `true|false` flag value (also accepts yes/no, on/off, 1/0). */
+export function parseBoolFlag(value, flag) {
+    const v = value.trim().toLowerCase();
+    if (['true', 'yes', 'on', '1'].includes(v))
+        return true;
+    if (['false', 'no', 'off', '0'].includes(v))
+        return false;
+    throw new CliError(`Invalid value for ${flag}: "${value}".`, 'invalid_boolean', `Use ${flag} true or ${flag} false.`);
+}
+/** Pretty-prints a portal (human mode). */
+export function printPortalDetails(details, title = 'Portal') {
+    logger.title(title);
+    logger.label('ID', details.id);
+    logger.label('Name', details.name);
+    logger.label('URL', details.url);
+    logger.label('Access', details.access || 'direct');
+    logger.label('Status', details.disabled ? 'Disabled' : 'Enabled');
+    if (details.title)
+        logger.label('Title', details.title);
+    if (details.subtitle)
+        logger.label('Subtitle', details.subtitle);
+    if (typeof details.brandOff === 'boolean')
+        logger.label('Plazbot brand', details.brandOff ? 'Hidden' : 'Visible');
+    if (details.logo || details.logodark) {
+        logger.title('Assets');
+        if (details.logo)
+            logger.label('Logo', details.logo);
+        if (details.logodark)
+            logger.label('Logo (dark mode)', details.logodark);
+    }
+    if (details.links && details.links.length > 0) {
+        logger.title('Links');
+        details.links.forEach((link) => logger.label(link.value, link.url));
+    }
+    if (details.agents && details.agents.length > 0) {
+        logger.title('Agents');
+        details.agents.forEach((agent) => logger.label(agent.name, agent.id));
+    }
+}

package/dist/commands/portal/update.js

@@ -1,86 +1,116 @@
-import { Command } from 'commander';
-import { Portal } from 'plazbot';
-import { getStoredCredentials } from '../../utils/credentials.js';
+import { Command, Option } from 'commander';
+import { addExamples, addNotes } from '../../utils/help.js';
+import { jsonOption, isJsonMode, printJson, fail, CliError } from '../../utils/output.js';
+import { createSpinner } from '../../utils/ui.js';
 import { logger } from '../../utils/logger.js';
-import { addExamples } from '../../utils/help.js';
+import { createPortalClient, parseBoolFlag, resolvePortalId, validateAccess, validateLogo } from './shared.js';
 export const updateCommand = new Command('update')
-    .description('Update an existing portal')
-    .argument('<portalId>', 'ID of the portal to update')
+    .description('Update a portal (only the fields you pass are changed)')
+    .argument('<portalId>', 'Portal ID (see plazbot portal list)')
     .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('-t, --title <title>', 'New welcome title')
+    .option('-s, --subtitle <subtitle>', 'New subtitle')
+    .option('-l, --logo <url>', 'New logo URL (.png or .jpg)')
+    .option('-d, --logo-dark <url>', 'New dark-mode logo URL (.png or .jpg)')
+    .option('-a, --access <type>', 'Access type: direct or form')
+    .option('--disabled <true|false>', 'Disable (true) or enable (false) the portal')
+    .option('--brand-off <true|false>', 'Hide (true) or show (false) the Plazbot brand')
+    .addOption(new Option('--enable', 'Shortcut for --disabled false').conflicts(['disabled', 'disable']))
+    .addOption(new Option('--disable', 'Shortcut for --disabled true').conflicts(['disabled', 'enable']))
+    .addOption(jsonOption())
     .option('--dev', 'Use development environment', false)
-    .action(async (portalId, options) => {
+    .action(async (portalIdArg, options) => {
     try {
-        // Obtener credenciales guardadas
-        const credentials = await getStoredCredentials();
-        const portal = new Portal({
-            workspaceId: credentials.workspace,
-            apiKey: credentials.apiKey,
-            zone: credentials.zone,
-            ...(options.dev && { customUrl: "http://localhost:5090" })
-        });
-        // Obtener detalles actuales del portal
-        const currentPortal = await portal.getPortal(portalId);
-        logger.title('Current portal');
-        logger.json(currentPortal.portal);
-        // Construir objeto de actualización solo con los campos proporcionados
-        const updateData = { id: portalId };
-        if (options.name)
-            updateData.name = options.name;
-        if (options.title)
-            updateData.title = options.title;
-        if (options.subtitle)
-            updateData.subtitle = options.subtitle;
-        if (options.logo)
-            updateData.logo = options.logo;
-        if (options.logoDark)
-            updateData.logodark = options.logoDark;
-        if (options.access) {
-            if (options.access !== 'direct' && options.access !== 'form') {
-                throw new Error('Access type must be "direct" or "form"');
-            }
-            updateData.access = options.access;
+        const portalId = resolvePortalId(portalIdArg);
+        // Validate everything before calling the API.
+        const changes = {};
+        if (options.name !== undefined) {
+            if (!options.name.trim())
+                throw new CliError('Portal name cannot be empty.', 'invalid_name');
+            changes.name = options.name.trim();
         }
-        if (options.disabled) {
-            if (options.disabled !== 'true' && options.disabled !== 'false') {
-                throw new Error('The disabled value must be "true" or "false"');
-            }
-            updateData.disabled = options.disabled === 'true';
+        if (options.title !== undefined) {
+            if (!options.title.trim())
+                throw new CliError('Portal title cannot be empty.', 'invalid_title');
+            changes.title = options.title.trim();
         }
-        if (options.brandOff) {
-            if (options.brandOff !== 'true' && options.brandOff !== 'false') {
-                throw new Error('The brand-off value must be "true" or "false"');
+        if (options.subtitle !== undefined) {
+            if (!options.subtitle.trim()) {
+                throw new CliError('Subtitle cannot be empty.', 'invalid_subtitle', 'The API ignores empty values, so a subtitle cannot be cleared from the CLI.');
             }
-            updateData.brandOff = options.brandOff === 'true';
+            changes.subtitle = options.subtitle.trim();
         }
-        logger.title('Changes to apply');
-        logger.json(updateData);
-        const result = await portal.updatePortal(updateData);
-        logger.success('Portal updated successfully');
-        logger.label('Message', result.message);
-        if (options.dev) {
-            logger.warning('\nEnvironment: development');
+        if (options.logo !== undefined)
+            changes.logo = validateLogo(options.logo, '--logo');
+        if (options.logoDark !== undefined)
+            changes.logodark = validateLogo(options.logoDark, '--logo-dark');
+        if (options.access !== undefined)
+            changes.access = validateAccess(options.access);
+        if (options.disabled !== undefined)
+            changes.disabled = parseBoolFlag(options.disabled, '--disabled');
+        if (options.enable)
+            changes.disabled = false;
+        if (options.disable)
+            changes.disabled = true;
+        if (options.brandOff !== undefined)
+            changes.brandOff = parseBoolFlag(options.brandOff, '--brand-off');
+        if (Object.keys(changes).length === 0) {
+            throw new CliError('Nothing to update.', 'nothing_to_update', 'Pass at least one option, e.g. -n "New name", -t "New title" or --disable.');
         }
+        const { portal } = await createPortalClient(options.dev);
+        const spinner = createSpinner('Updating portal...').start();
+        const response = (await portal.getPortal(portalId));
+        const current = response.portal || {};
+        // The API (and SDK) reset access=direct, theme=light, disabled=false and brandOff=false
+        // when they are missing from the request, so the current values are always sent.
+        const updateData = { id: portalId };
+        if (current.access)
+            updateData.access = current.access;
+        if (current.theme)
+            updateData.theme = current.theme;
+        if (typeof current.disabled === 'boolean')
+            updateData.disabled = current.disabled;
+        if (typeof current.brandOff === 'boolean')
+            updateData.brandOff = current.brandOff;
+        Object.assign(updateData, changes);
+        await portal.updatePortal(updateData);
+        spinner.succeed(`Portal "${changes.name || current.name || portalId}" updated`);
+        if (isJsonMode()) {
+            printJson({ id: portalId, updated: true, changes });
+            return;
+        }
+        const fieldLabels = {
+            name: 'Name', title: 'Title', subtitle: 'Subtitle', logo: 'Logo', logodark: 'Logo (dark mode)',
+            access: 'Access', disabled: 'Status', brandOff: 'Plazbot brand',
+        };
+        const show = (key, value) => {
+            if (value === undefined || value === null || value === '')
+                return '(empty)';
+            if (key === 'disabled')
+                return value ? 'Disabled' : 'Enabled';
+            if (key === 'brandOff')
+                return value ? 'Hidden' : 'Visible';
+            return String(value);
+        };
+        logger.title('Changes');
+        for (const [key, value] of Object.entries(changes)) {
+            const before = show(key, current[key]);
+            const after = show(key, value);
+            logger.label(fieldLabels[key] || key, before === after ? after : `${before} → ${after}`);
+        }
+        console.log();
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : 'Unknown error while updating the portal';
-        logger.error(message);
-        process.exit(1);
+        fail(error);
     }
 });
 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' },
+    { description: 'Rename a portal', command: 'plazbot portal update por_AbcDef123 -n "Support Center"' },
+    { description: 'Ask for contact details and change the title', command: 'plazbot portal update por_AbcDef123 -a form -t "Sign in to continue"' },
+    { description: 'Disable a portal', command: 'plazbot portal update por_AbcDef123 --disable' },
+    { description: 'Hide the Plazbot brand and change the logo', command: 'plazbot portal update por_AbcDef123 --brand-off true -l https://files.example.com/logo.png' },
+]);
+addNotes(updateCommand, [
+    'Fields you do not pass keep their current value (access, status and brand included).',
+    '--disabled and --brand-off take true or false (yes/no and on/off also work).',
 ]);