@cakemail-org/cakemail-cli 1.5.0 → 2.0.0

package/src/utils/errors.ts

@@ -0,0 +1,116 @@
+// ABOUTME: Context-aware error handling with profile-dependent display.
+// ABOUTME: Maps HTTP errors to user-friendly messages with actionable suggestions.
+
+import type { ProfileConfig } from '../types/profile.js';
+
+export interface ErrorContext {
+  command: string;
+  resource?: string;
+  resourceId?: string | number;
+  operation?: string;
+  profileConfig?: ProfileConfig;
+}
+
+interface EnhancedError {
+  message: string;
+  suggestion?: string;
+  help?: string;
+}
+
+export function enhanceError(error: any, context: ErrorContext): EnhancedError {
+  const statusCode = error.statusCode || error.status || error.response?.status;
+  const message = error.message || String(error);
+
+  if (statusCode) {
+    return enhanceHttpError(statusCode, message, context);
+  }
+
+  if (message.includes("ECONNREFUSED") || message.includes("ENOTFOUND") || message.includes("fetch failed")) {
+    return {
+      message: "Cannot connect to the API server.",
+      suggestion: "Check your internet connection and API base URL.",
+    };
+  }
+
+  if (message.includes("Missing credentials") || message.includes("accessToken")) {
+    return {
+      message: "No credentials provided.",
+      suggestion: `Set CAKEMAIL_ACCESS_TOKEN or use --access-token.`,
+      help: "Run 'cakemail --help' for authentication options.",
+    };
+  }
+
+  return { message };
+}
+
+function enhanceHttpError(statusCode: number, message: string, context: ErrorContext): EnhancedError {
+  switch (statusCode) {
+    case 400:
+      return {
+        message: `Invalid request: ${message}`,
+        suggestion: "Check your parameters. Use --help to see available options.",
+      };
+    case 401:
+      return {
+        message: "Authentication failed.",
+        suggestion: "Check your credentials. Your token may have expired.",
+        help: `Set CAKEMAIL_ACCESS_TOKEN or use --access-token.`,
+      };
+    case 403:
+      return {
+        message: `Access denied: ${message}`,
+        suggestion: "You may not have permission to access this resource.",
+      };
+    case 404: {
+      const resource = context.resource || "Resource";
+      const id = context.resourceId ? ` (${context.resourceId})` : "";
+      return {
+        message: `${resource}${id} not found.`,
+        suggestion: `Verify the ID is correct. Use 'cakemail ${context.resource || ""} list' to see available items.`,
+      };
+    }
+    case 409:
+      return {
+        message: `Conflict: ${message}`,
+        suggestion: "The resource may already exist or be in a conflicting state.",
+      };
+    case 422:
+      return {
+        message: `Validation error: ${message}`,
+        suggestion: "Check that all required fields are provided with valid values.",
+      };
+    case 429:
+      return {
+        message: "Rate limit exceeded.",
+        suggestion: "Wait a moment before retrying.",
+      };
+    case 500:
+    case 502:
+    case 503:
+      return {
+        message: "The API server encountered an error.",
+        suggestion: "Try again later. If the problem persists, contact support.",
+      };
+    default:
+      return {
+        message: `API error (${statusCode}): ${message}`,
+      };
+  }
+}
+
+export function displayError(error: any, context: ErrorContext): void {
+  const enhanced = enhanceError(error, context);
+  const verbose = context.profileConfig?.display.verbose_errors ?? false;
+
+  if (verbose) {
+    console.error(`Error: ${enhanced.message}`);
+    if (error.statusCode) console.error(`  Status: ${error.statusCode}`);
+    if (error.response?.data) console.error(`  Response: ${JSON.stringify(error.response.data)}`);
+    if (enhanced.suggestion) console.error(`  Suggestion: ${enhanced.suggestion}`);
+    if (enhanced.help) console.error(`  Help: ${enhanced.help}`);
+  } else {
+    console.error(`Error: ${enhanced.message}`);
+    if (enhanced.suggestion) console.error(`  ${enhanced.suggestion}`);
+    if (enhanced.help) console.error(`  ${enhanced.help}`);
+  }
+}

package/src/utils/interactive.ts

@@ -0,0 +1,91 @@
+// ABOUTME: Profile-aware interactive prompts that skip in scripting mode.
+// ABOUTME: Detects TTY, CI, and batch mode to decide whether to prompt.
+
+import * as readline from 'node:readline';
+import type { ProfileConfig } from '../types/profile.js';
+
+export function isInteractive(): boolean {
+  return !!(process.stdin.isTTY && process.stdout.isTTY);
+}
+
+export function isScriptingMode(): boolean {
+  return !!(
+    process.env.CI ||
+    process.env.CAKEMAIL_BATCH_MODE === 'true' ||
+    process.argv.includes('--batch') ||
+    !isInteractive()
+  );
+}
+
+export function shouldPrompt(profileConfig?: ProfileConfig): boolean {
+  const mode = profileConfig?.behavior.interactive_prompts ?? 'auto';
+  if (mode === false) return false;
+  if (mode === true) return isInteractive();
+  return isInteractive() && !isScriptingMode();
+}
+
+export async function promptText(
+  message: string,
+  options: { default?: string; required?: boolean; profileConfig?: ProfileConfig } = {},
+): Promise<string | undefined> {
+  if (!shouldPrompt(options.profileConfig)) return options.default;
+
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const defaultHint = options.default ? ` (${options.default})` : '';
+
+  return new Promise((resolve) => {
+    rl.question(`${message}${defaultHint}: `, (answer) => {
+      rl.close();
+      const value = answer.trim() || options.default;
+      if (options.required && !value) {
+        console.error('This field is required.');
+        resolve(undefined);
+      } else {
+        resolve(value);
+      }
+    });
+  });
+}
+
+export async function promptSelect<T extends string>(
+  message: string,
+  choices: { name: string; value: T }[],
+  options: { profileConfig?: ProfileConfig } = {},
+): Promise<T | undefined> {
+  if (!shouldPrompt(options.profileConfig)) return undefined;
+
+  console.log(`\n${message}`);
+  choices.forEach((c, i) => console.log(`  ${i + 1}. ${c.name}`));
+
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+
+  return new Promise((resolve) => {
+    rl.question(`Choice (1-${choices.length}): `, (answer) => {
+      rl.close();
+      const idx = parseInt(answer) - 1;
+      if (idx >= 0 && idx < choices.length) {
+        resolve(choices[idx].value);
+      } else {
+        resolve(undefined);
+      }
+    });
+  });
+}
+
+export async function promptConfirm(
+  message: string,
+  options: { default?: boolean; profileConfig?: ProfileConfig } = {},
+): Promise<boolean> {
+  if (!shouldPrompt(options.profileConfig)) return options.default ?? true;
+
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const hint = options.default ? '[Y/n]' : '[y/N]';
+
+  return new Promise((resolve) => {
+    rl.question(`${message} ${hint} `, (answer) => {
+      rl.close();
+      if (!answer.trim()) resolve(options.default ?? false);
+      else resolve(answer.trim().toLowerCase() === 'y');
+    });
+  });
+}

package/src/utils/list-defaults.ts

@@ -0,0 +1,74 @@
+/**
+ * Apply profile-based defaults for list commands
+ *
+ * For marketer profile (compact format):
+ * - Default to 20 items per page
+ * - Default to descending order by ID (newest first)
+ */
+
+import { ProfileConfig } from '../types/profile.js';
+
+export interface ListOptions {
+  limit?: string;
+  page?: string;
+  sort?: string;
+  [key: string]: any;
+}
+
+export interface ListParams {
+  per_page?: number;
+  page?: number;
+  sort?: string;
+  [key: string]: any;
+}
+
+/**
+ * Apply profile-based defaults to list parameters
+ *
+ * @param options - Command line options
+ * @param profileConfig - Current profile configuration
+ * @returns API parameters with defaults applied
+ */
+export function applyListDefaults(
+  options: ListOptions,
+  profileConfig?: ProfileConfig
+): ListParams {
+  const params: ListParams = {};
+
+  // Apply limit with profile default
+  if (options.limit) {
+    params.per_page = parseInt(options.limit);
+  } else if (profileConfig?.output.format === 'compact') {
+    // Marketer profile default: 25 items (half of API default of 50)
+    params.per_page = 25;
+  }
+
+  // Apply page if provided
+  if (options.page) {
+    params.page = parseInt(options.page);
+  }
+
+  // Apply sort with profile default
+  if (options.sort) {
+    params.sort = options.sort;
+  } else if (profileConfig?.output.format === 'compact') {
+    // Marketer profile default: descending by created_on (newest first)
+    // Note: -id doesn't work, but -created_on does
+    params.sort = '-created_on';
+  }
+
+  return params;
+}
+
+/**
+ * Get next page hint for pagination footer
+ */
+export function getNextPageCommand(currentCommand: string, currentPage?: number): string {
+  const page = (currentPage || 1) + 1;
+  // If command already has --page, replace it
+  if (currentCommand.includes('--page')) {
+    return currentCommand.replace(/--page\s+\d+/, `--page ${page}`);
+  }
+  // Otherwise append it
+  return `${currentCommand} --page ${page}`;
+}

package/src/utils/output.ts

@@ -0,0 +1,190 @@
+// ABOUTME: Multi-format output formatter with profile-aware styling.
+// ABOUTME: Supports JSON, table, and compact formats with colors and date formatting.
+
+import Table from 'cli-table3';
+import chalk from 'chalk';
+import type { ProfileConfig, OutputFormat, ColorScheme, DateFormat } from '../types/profile.js';
+
+export class OutputFormatter {
+  constructor(
+    private format: OutputFormat = 'json',
+    private profileConfig?: ProfileConfig,
+  ) {}
+
+  output(data: unknown, fields?: string[]): void {
+    if (data == null) return;
+
+    switch (this.format) {
+      case 'table':
+        this.outputTable(data, fields);
+        break;
+      case 'compact':
+        this.outputCompact(data);
+        break;
+      case 'json':
+      default:
+        this.outputJson(data);
+        break;
+    }
+  }
+
+  success(message: string): void {
+    console.log(this.applyColor(message, chalk.green));
+  }
+
+  error(message: string): void {
+    console.error(this.applyColor(`Error: ${message}`, chalk.red));
+  }
+
+  info(message: string): void {
+    console.log(this.applyColor(message, chalk.cyan));
+  }
+
+  warning(message: string): void {
+    console.log(this.applyColor(message, chalk.yellow));
+  }
+
+  private outputJson(data: unknown): void {
+    const pretty = this.profileConfig?.output.pretty_print ?? true;
+    console.log(JSON.stringify(data, null, pretty ? 2 : undefined));
+  }
+
+  private outputTable(data: unknown, fields?: string[]): void {
+    const items = this.extractItems(data);
+    if (items.length === 0) {
+      this.info('No results found.');
+      return;
+    }
+
+    const keys = fields || this.inferColumns(items[0]);
+    const filteredKeys = this.filterColumns(keys);
+
+    const table = new Table({
+      head: filteredKeys.map((k) => this.applyColor(this.formatHeader(k), chalk.bold)),
+      style: { head: [], border: [] },
+    });
+
+    for (const item of items) {
+      table.push(filteredKeys.map((key) => this.formatValue(item[key], key)));
+    }
+
+    console.log(table.toString());
+    this.displayPagination(data, items.length);
+  }
+
+  private outputCompact(data: unknown): void {
+    const items = this.extractItems(data);
+    if (items.length === 0) {
+      this.info('No results found.');
+      return;
+    }
+
+    for (const item of items) {
+      const id = item.id ?? item.name ?? '';
+      const name = item.name ?? item.email ?? item.tag ?? '';
+      const status = item.status ? ` [${this.formatStatus(item.status)}]` : '';
+      const idStr = this.profileConfig?.display.show_ids !== false && id ? `#${id} ` : '';
+      console.log(`${idStr}${name}${status}`);
+    }
+
+    this.displayPagination(data, items.length);
+  }
+
+  private extractItems(data: unknown): Record<string, any>[] {
+    if (Array.isArray(data)) return data;
+    if (data && typeof data === 'object') {
+      const obj = data as Record<string, unknown>;
+      if (Array.isArray(obj.data)) return obj.data;
+      return [obj as Record<string, any>];
+    }
+    return [];
+  }
+
+  private inferColumns(item: Record<string, any>): string[] {
+    return Object.keys(item);
+  }
+
+  private filterColumns(keys: string[]): string[] {
+    const showIds = this.profileConfig?.display.show_ids ?? true;
+    const exclude = new Set(['__metadata', 'links']);
+    if (!showIds) exclude.add('id');
+    return keys.filter((k) => !exclude.has(k));
+  }
+
+  private formatHeader(key: string): string {
+    return key.replace(/_/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
+  }
+
+  private formatValue(value: unknown, key: string): string {
+    if (value == null) return '';
+    if (typeof value === 'boolean') return value ? 'Yes' : 'No';
+    if (key === 'status') return this.formatStatus(String(value));
+    if (this.isDateField(key) && typeof value === 'string') return this.formatDate(value);
+    if (typeof value === 'object') return JSON.stringify(value);
+    return String(value);
+  }
+
+  private formatStatus(status: string): string {
+    const colors: Record<string, typeof chalk.green> = {
+      active: chalk.green,
+      draft: chalk.yellow,
+      scheduled: chalk.blue,
+      delivering: chalk.cyan,
+      delivered: chalk.green,
+      suspended: chalk.red,
+      archived: chalk.gray,
+    };
+    const colorFn = colors[status.toLowerCase()] || chalk.white;
+    return this.applyColor(status, colorFn);
+  }
+
+  private formatDate(dateString: string): string {
+    const dateFormat = this.profileConfig?.display.date_format ?? 'friendly';
+    const date = new Date(dateString);
+    if (isNaN(date.getTime())) return dateString;
+
+    switch (dateFormat) {
+      case 'iso8601':
+        return date.toISOString();
+      case 'relative':
+        return this.relativeDate(date);
+      case 'friendly':
+      default:
+        return date.toLocaleDateString('en-US', {
+          year: 'numeric', month: 'short', day: 'numeric',
+          hour: '2-digit', minute: '2-digit',
+        });
+    }
+  }
+
+  private relativeDate(date: Date): string {
+    const diff = Date.now() - date.getTime();
+    const minutes = Math.floor(diff / 60000);
+    if (minutes < 1) return 'just now';
+    if (minutes < 60) return `${minutes}m ago`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 24) return `${hours}h ago`;
+    const days = Math.floor(hours / 24);
+    if (days < 30) return `${days}d ago`;
+    return date.toLocaleDateString('en-US', { month: 'short', day: 'numeric', year: 'numeric' });
+  }
+
+  private isDateField(key: string): boolean {
+    return /(_at|_on|_date|created|updated|scheduled|sent)$/i.test(key);
+  }
+
+  private applyColor(text: string, colorFn: (s: string) => string): string {
+    const scheme = this.profileConfig?.output.colors ?? 'moderate';
+    if (scheme === 'none') return text;
+    return colorFn(text);
+  }
+
+  private displayPagination(data: unknown, count: number): void {
+    if (data && typeof data === 'object' && 'pagination' in (data as any)) {
+      const p = (data as any).pagination;
+      if (p?.page && p?.per_page) {
+        this.info(`Page ${p.page} (${count} items)`);
+      }
+    }
+  }
+}