plazbot-cli 0.2.26 → 0.3.2

package/src/studio/whatsapp/polling.ts

@@ -0,0 +1,93 @@
+import { activateIntegration, getWorkspaceById, type WorkspaceAuthOpts } from './api.js';
+import {
+  findNewWhatsappIntegration,
+  WA_POLL_INTERVAL_MS,
+  WA_POLL_MAX_ATTEMPTS,
+  type WhatsappLinkData,
+} from './types.js';
+
+export interface PollingCallbacks {
+  onAttempt(attempt: number): void;
+  onActivating(integrationId: string, number: string): void;
+  onConnected(number: string): void;
+  onTimeout(): void;
+  onError(message: string): void;
+}
+
+export interface PollingHandle {
+  cancel(): void;
+  /** True once the loop has stopped (success, timeout, error, or cancel). */
+  readonly stopped: boolean;
+}
+
+/**
+ * Starts the polling loop. Returns a handle to cancel it. The loop:
+ * 1. GETs the workspace every WA_POLL_INTERVAL_MS up to WA_POLL_MAX_ATTEMPTS.
+ * 2. Looks for a whatsapp integration whose id isn't in `existingIntegrationIds`.
+ * 3. When found, calls POST .../activate and reports the result.
+ */
+export function startWhatsappPolling(
+  opts: WorkspaceAuthOpts,
+  linkData: WhatsappLinkData,
+  cb: PollingCallbacks,
+): PollingHandle {
+  const knownIds = new Set(linkData.existingIntegrationIds ?? []);
+  const controller = new AbortController();
+  let attempts = 0;
+  let busy = false;
+  let stopped = false;
+  let timer: ReturnType<typeof setInterval> | null = null;
+
+  const stop = () => {
+    stopped = true;
+    if (timer) { clearInterval(timer); timer = null; }
+    controller.abort();
+  };
+
+  const tick = async () => {
+    if (busy || stopped) return;
+    busy = true;
+    attempts++;
+    cb.onAttempt(attempts);
+    try {
+      const ws = await getWorkspaceById(opts, controller.signal);
+      const newIntegration = findNewWhatsappIntegration(ws?.integrations, knownIds);
+      if (newIntegration?.id) {
+        const number =
+          newIntegration.cellphoneNumberFormat ||
+          newIntegration.cellphoneNumber ||
+          '';
+        cb.onActivating(newIntegration.id, number);
+        if (timer) { clearInterval(timer); timer = null; }
+        const res = await activateIntegration(opts, newIntegration.id, controller.signal);
+        if (res.success !== false) {
+          cb.onConnected(number);
+        } else {
+          cb.onError(res.message || 'Could not activate the integration.');
+        }
+        stopped = true;
+        return;
+      }
+    } catch (err) {
+      if ((err as Error).name === 'AbortError') return;
+      // Transient network errors: swallow and keep polling.
+    } finally {
+      busy = false;
+    }
+
+    if (attempts >= WA_POLL_MAX_ATTEMPTS) {
+      if (timer) { clearInterval(timer); timer = null; }
+      stopped = true;
+      cb.onTimeout();
+    }
+  };
+
+  timer = setInterval(() => { void tick(); }, WA_POLL_INTERVAL_MS);
+  // Trigger the first attempt immediately so the user sees activity right away.
+  void tick();
+
+  return {
+    cancel() { stop(); },
+    get stopped() { return stopped; },
+  };
+}

package/src/studio/whatsapp/types.ts

@@ -0,0 +1,80 @@
+/**
+ * Types and helpers for the "connect WhatsApp from Agent Studio" flow.
+ *
+ * The backend tool `connect_whatsapp` emits a `tool_result` chunk with
+ * `type: "whatsapp_link"`. When `data.shortUrl` is present we render an
+ * inline card with the onboarding link and start polling the workspace
+ * until the new integration appears. Baseline of "known" ids comes from
+ * the server (`existingIntegrationIds`) to avoid race conditions.
+ *
+ * Mirror of /Plazbot-Front-v2.0/src/modules/agentStudio/whatsappConnect.ts
+ */
+
+export interface WhatsappLinkData {
+  shortUrl?: string | null;
+  /** "whatsapp" (Cloud API) | "whatsapp_business" (Business app / QR) */
+  linkType?: string;
+  expiresAt?: string;
+  isNewLink?: boolean;
+  alreadyConnected?: boolean;
+  connectedNumbers?: Array<{ id?: string; number?: string; alias?: string }>;
+  existingIntegrationIds?: string[];
+}
+
+export type WaConnectStatus =
+  | 'waiting'      // card visible, polling active
+  | 'activating'   // integration detected, activating via API
+  | 'connected'    // activated successfully
+  | 'timeout'      // attempts exhausted
+  | 'cancelled'    // user cancelled
+  | 'error';       // activation failed
+
+export interface WaConnectState {
+  /** Stable id used by the store + card. */
+  id: string;
+  linkData: WhatsappLinkData;
+  status: WaConnectStatus;
+  /** Message id this card anchors to in the chat log. */
+  anchorMessageId: string;
+  connectedNumber?: string;
+  errorMessage?: string;
+  attempt: number;
+}
+
+/** Minimal shape of an integration item as returned by GET /api/workspace/{id}. */
+export interface WorkspaceIntegrationItem {
+  id?: string;
+  type?: string;
+  cellphoneNumber?: string;
+  cellphoneNumberFormat?: string;
+  creationDate?: string;
+  isActive?: number | boolean;
+}
+
+export const WA_POLL_INTERVAL_MS = 5000;
+export const WA_POLL_MAX_ATTEMPTS = 60; // 5 minutes
+
+/**
+ * Returns a new whatsapp integration whose id is NOT in the baseline.
+ * If multiple are new, picks the most recently created one.
+ */
+export function findNewWhatsappIntegration(
+  integrations: WorkspaceIntegrationItem[] | undefined,
+  knownIds: Set<string>,
+): WorkspaceIntegrationItem | null {
+  if (!integrations?.length) return null;
+
+  const candidates = integrations.filter(
+    (i) =>
+      (i.type === 'whatsapp' || i.type === 'whatsapp_business') &&
+      !!i.id &&
+      !knownIds.has(i.id as string),
+  );
+  if (!candidates.length) return null;
+
+  return candidates.reduce((latest, current) => {
+    const a = latest.creationDate ? new Date(latest.creationDate).getTime() : 0;
+    const b = current.creationDate ? new Date(current.creationDate).getTime() : 0;
+    return b > a ? current : latest;
+  });
+}

package/src/types/agent.ts

@@ -1,4 +1,4 @@
-import { BaseCommandOptions } from './common';
+import { BaseCommandOptions } from './common.js';
 
 export interface AgentCommandOptions {
   dev?: boolean;

package/src/types/auth.ts

@@ -1,8 +1,9 @@
-import { BaseCommandOptions } from './common';
+import { BaseCommandOptions } from './common.js';
 
 export interface LoginOptions extends BaseCommandOptions {
-  email: string;
+  email?: string;
   apiKey: string;
   workspace: string;
   zone: "LA" | "EU";
-} 
+  userId?: string;
+}

package/src/types/portal.ts

@@ -1,4 +1,4 @@
-import { BaseCommandOptions } from './common';
+import { BaseCommandOptions } from './common.js';
 
 export interface PortalCommandOptions extends BaseCommandOptions {
   portalId?: string;

package/src/types/workers.ts

@@ -1,4 +1,4 @@
-import { BaseCommandOptions } from './common';
+import { BaseCommandOptions } from './common.js';
 
 // ── Opciones de comandos ────────────────────────────────────────────────────
 

package/src/utils/agent-errors.ts

@@ -0,0 +1,67 @@
+import chalk from 'chalk';
+import type { StoredCredentials } from './credentials.js';
+
+interface AxiosLikeError {
+  response?: {
+    status?: number;
+    data?: { message?: string };
+  };
+  message?: string;
+}
+
+/**
+ * Resuelve un error proveniente del SDK/axios al cargar un agente y devuelve
+ * un mensaje legible que oriente al usuario sobre la causa real (404 = ID o
+ * workspace/zona incorrectos, 401 = token expirado, etc.).
+ */
+export function describeAgentLoadError(
+  error: unknown,
+  agentId: string,
+  credentials: Pick<StoredCredentials, 'workspace' | 'zone'>,
+  context: { dev?: boolean; workspaceOverride?: string; zoneOverride?: string } = {}
+): string {
+  const err = error as AxiosLikeError;
+  const status = err?.response?.status;
+  const workspace = context.workspaceOverride || credentials.workspace;
+  const zone = context.zoneOverride || credentials.zone;
+  const envHint = context.dev ? ' (env: --dev / localhost:5090)' : '';
+
+  if (status === 404) {
+    return [
+      `Agent "${agentId}" was not found in workspace ${workspace} (zone ${zone})${envHint}.`,
+      chalk.gray('  Verify the ID and active workspace:'),
+      chalk.gray('    plazbot status'),
+      chalk.gray('    plazbot agent list'),
+      chalk.gray('  If the agent lives in a different zone, re-init with the right one:'),
+      chalk.gray('    plazbot init -z LA   # or EU'),
+    ].join('\n');
+  }
+
+  if (status === 401) {
+    return [
+      'Authentication token rejected (401).',
+      chalk.gray('  Re-run: plazbot init -k <jwt> -w <workspace> -z LA|EU'),
+    ].join('\n');
+  }
+
+  if (status === 403) {
+    return [
+      `No permissions to access agent "${agentId}" in workspace ${workspace}.`,
+      chalk.gray('  Confirm your user has access to that workspace.'),
+    ].join('\n');
+  }
+
+  if (status === 429) {
+    return 'Rate limit reached. Try again in a few seconds.';
+  }
+
+  if (typeof status === 'number' && status >= 500) {
+    return [
+      `Backend error (HTTP ${status})${envHint}.`,
+      chalk.gray(`  ${err.response?.data?.message || err.message || ''}`).trimEnd(),
+    ].join('\n');
+  }
+
+  const fallback = err?.response?.data?.message || err?.message || 'Unknown error';
+  return fallback;
+}

package/src/utils/api.ts

@@ -22,8 +22,14 @@ export function createApiClient(options: ApiClientOptions): AxiosInstance {
     baseURL,
     headers: {
       'Content-Type': 'application/json',
+      // El apiKey almacenado en el CLI ya es un JWT válido. El backend espera
+      // Authorization: Bearer en endpoints nuevos (ej. /api/agent/studio).
+      // x-api-key se mantiene transitorio para no romper endpoints legacy.
+      'Authorization': `Bearer ${options.apiKey}`,
       'x-api-key': options.apiKey,
       'x-workspace-id': options.workspace,
     },
   });
 }
+
+export { getBaseUrl };

package/src/utils/banner.ts

@@ -1,7 +1,12 @@
 import chalk from 'chalk';
-import { getStoredCredentials } from './credentials';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { getStoredCredentials } from './credentials.js';
 
-const { version: VERSION } = require('../../package.json');
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkgPath = join(__dirname, '..', '..', 'package.json');
+const { version: VERSION } = JSON.parse(readFileSync(pkgPath, 'utf-8'));
 
 // ASCII art del logo Plazbot (burbujas de chat)
 const logo = [
@@ -45,27 +50,27 @@ export async function showBanner(): Promise<void> {
   const rightColumn: string[] = [];
 
   if (credentials) {
-    rightColumn.push(chalk.bold.hex('#4CAF50')('Workspace conectado'));
+    rightColumn.push(chalk.bold.hex('#4CAF50')('Connected workspace'));
     rightColumn.push(chalk.gray(`  ${credentials.workspace || 'N/A'}`));
-    rightColumn.push(chalk.gray(`  ${credentials.email || ''}`));
-    rightColumn.push(chalk.gray(`  Zona: ${credentials.zone || 'N/A'}`));
+    if (credentials.email) rightColumn.push(chalk.gray(`  ${credentials.email}`));
+    rightColumn.push(chalk.gray(`  Zone: ${credentials.zone || 'N/A'}`));
     rightColumn.push('');
     rightColumn.push(chalk.hex('#4CAF50')('─'.repeat(35)));
     rightColumn.push('');
-    rightColumn.push(chalk.bold.hex('#4CAF50')('Comandos rapidos'));
+    rightColumn.push(chalk.bold.hex('#4CAF50')('Quick commands'));
     rightColumn.push(chalk.white('  plazbot agent list'));
     rightColumn.push(chalk.white('  plazbot agent create'));
     rightColumn.push(chalk.white('  plazbot agent chat -a <id>'));
     rightColumn.push(chalk.white('  plazbot whatsapp send-message'));
   } else {
-    rightColumn.push(chalk.bold.hex('#FFA726')('No conectado'));
+    rightColumn.push(chalk.bold.hex('#FFA726')('Not connected'));
     rightColumn.push('');
-    rightColumn.push(chalk.bold.hex('#4CAF50')('Para comenzar'));
+    rightColumn.push(chalk.bold.hex('#4CAF50')('To get started'));
     rightColumn.push(chalk.white('  plazbot init -e <email> -k <key> -w <workspace> -z <zone>'));
     rightColumn.push('');
     rightColumn.push(chalk.hex('#4CAF50')('─'.repeat(35)));
     rightColumn.push('');
-    rightColumn.push(chalk.bold.hex('#4CAF50')('Documentacion'));
+    rightColumn.push(chalk.bold.hex('#4CAF50')('Documentation'));
     rightColumn.push(chalk.gray('  https://docs.plazbot.com'));
   }
 

package/src/utils/credentials.ts

@@ -5,22 +5,23 @@ import os from 'os';
 const configDir = path.join(os.homedir(), '.plazbot');
 const configPath = path.join(configDir, 'config.json');
 
-interface StoredCredentials {
-  email: string;
+export interface StoredCredentials {
+  email?: string;
   apiKey: string;
   workspace: string;
   zone: "LA" | "EU";
+  userId?: string;
 }
 
 export async function getStoredCredentials(): Promise<StoredCredentials> {
   try {
     const configRaw = await fs.readFile(configPath, 'utf-8');
     const config = JSON.parse(configRaw);
-    
+
     if (!config.apiKey || !config.workspace || !config.zone) {
       throw new Error('Credenciales incompletas');
     }
-    
+
     return config;
   } catch (error) {
     throw new Error("No se encontró una sesión activa. Ejecuta 'plazbot init' primero.");
@@ -34,4 +35,4 @@ export async function saveCredentials(credentials: StoredCredentials): Promise<v
 
 export async function removeCredentials(): Promise<void> {
   await fs.rm(configPath, { force: true });
-} 
+}

package/src/utils/help.ts

@@ -0,0 +1,51 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+
+export interface HelpExample {
+  /** Brief description of what the example does. */
+  description: string;
+  /** The command line to run (without the `$ ` prefix). */
+  command: string;
+}
+
+/**
+ * Appends a colored "Examples" section to a Commander command's --help output.
+ *
+ * Usage:
+ *   addExamples(myCommand, [
+ *     { description: 'List all agents in the current workspace', command: 'plazbot agent list' },
+ *     { description: 'List as JSON for scripting',               command: 'plazbot agent list --json' },
+ *   ]);
+ *
+ * Renders as:
+ *   Examples:
+ *     # List all agents in the current workspace
+ *     $ plazbot agent list
+ *
+ *     # List as JSON for scripting
+ *     $ plazbot agent list --json
+ */
+export function addExamples(cmd: Command, examples: HelpExample[]): Command {
+  if (!examples.length) return cmd;
+  const lines: string[] = ['', chalk.bold('Examples:')];
+  for (const ex of examples) {
+    lines.push('  ' + chalk.gray('# ' + ex.description));
+    lines.push('  ' + chalk.cyan('$ ') + ex.command);
+    lines.push('');
+  }
+  cmd.addHelpText('after', lines.join('\n'));
+  return cmd;
+}
+
+/**
+ * Appends a "Notes" section after Examples. Use for caveats, links, or
+ * prerequisites the user should know before running the command.
+ */
+export function addNotes(cmd: Command, notes: string[]): Command {
+  if (!notes.length) return cmd;
+  const lines: string[] = ['', chalk.bold('Notes:')];
+  for (const n of notes) lines.push('  ' + chalk.gray('• ') + n);
+  lines.push('');
+  cmd.addHelpText('after', lines.join('\n'));
+  return cmd;
+}

package/tsconfig.json

@@ -1,15 +1,18 @@
 {
   "compilerOptions": {
-    "target": "es2020", // O una versión más reciente
-    "module": "commonjs", // O "NodeNext" si configuras package.json con "type": "module"
+    "target": "es2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "jsx": "react-jsx",
     "outDir": "./dist",
     "rootDir": "./src",
     "strict": true,
     "esModuleInterop": true,
     "skipLibCheck": true,
-    "forceConsistentCasingInFileNames": true,
-    "moduleResolution": "node" // O "NodeNext"
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "forceConsistentCasingInFileNames": true
   },
   "include": ["src/**/*"],
-  "exclude": ["node_modules", "**/*.spec.ts"]
-}
+  "exclude": ["node_modules", "**/*.spec.ts", "dist"]
+}