newo 1.4.0 → 1.5.1

package/src/cli.ts

@@ -0,0 +1,316 @@
+#!/usr/bin/env node
+import minimist from 'minimist';
+import dotenv from 'dotenv';
+import { makeClient, getProjectMeta, importAkbArticle } from './api.js';
+import { pullAll, pushChanged, status } from './sync.js';
+import { parseAkbFile, prepareArticlesForImport } from './akb.js';
+import { initializeEnvironment, ENV, EnvValidationError } from './env.js';
+import { parseCustomerConfigAsync, listCustomers, getCustomer, getDefaultCustomer, validateCustomerConfig } from './customerAsync.js';
+import { getValidAccessToken } from './auth.js';
+import path from 'path';
+import type { CliArgs, NewoApiError, CustomerConfig } from './types.js';
+
+// Enhanced error logging for CLI
+function logCliError(level: 'error' | 'warn' | 'info', message: string, meta?: Record<string, unknown>): void {
+  const timestamp = new Date().toISOString();
+  const logEntry = {
+    timestamp,
+    level,
+    module: 'cli',
+    message,
+    ...meta
+  };
+  
+  // Only log JSON format in verbose mode, otherwise use clean user messages
+  const verbose = process.argv.includes('--verbose') || process.argv.includes('-v');
+  
+  if (verbose) {
+    if (level === 'error') {
+      console.error(JSON.stringify(logEntry));
+    } else if (level === 'warn') {
+      console.warn(JSON.stringify(logEntry));
+    } else {
+      console.log(JSON.stringify(logEntry));
+    }
+  } else {
+    // Clean user-facing messages
+    if (level === 'error') {
+      console.error(`❌ ${message}`);
+    } else if (level === 'warn') {
+      console.warn(`⚠️  ${message}`);
+    } else {
+      console.log(`ℹ️  ${message}`);
+    }
+  }
+}
+
+// Enhanced error handling with user-friendly messages  
+function handleCliError(error: unknown, operation: string = 'operation'): never {
+  const verbose = process.argv.includes('--verbose') || process.argv.includes('-v');
+  
+  if (error instanceof Error) {
+    // Authentication errors
+    if (error.message.includes('API key') || error.message.includes('Authentication failed')) {
+      logCliError('error', 'Authentication failed. Please check your API key configuration.');
+      if (!verbose) {
+        console.error('\n💡 Troubleshooting tips:');
+        console.error('  • Verify your API key is correct in .env file');
+        console.error('  • For multi-customer setup, check NEWO_CUSTOMER_<IDN>_API_KEY');
+        console.error('  • Run with --verbose for detailed error information');
+      }
+    }
+    // Network errors
+    else if (error.message.includes('Network timeout') || error.message.includes('ENOTFOUND') || error.message.includes('ECONNREFUSED')) {
+      logCliError('error', 'Network connection failed. Please check your internet connection.');
+      if (!verbose) {
+        console.error('\n💡 Troubleshooting tips:');
+        console.error('  • Check your internet connection');
+        console.error('  • Verify NEWO_BASE_URL is correct');
+        console.error('  • Try again in a few moments');
+      }
+    }
+    // Environment configuration errors
+    else if (error instanceof EnvValidationError || error.message.includes('not set')) {
+      logCliError('error', 'Configuration error. Please check your environment setup.');
+      if (!verbose) {
+        console.error('\n💡 Setup help:');
+        console.error('  • Copy .env.example to .env and configure your settings');
+        console.error('  • Run "newo --help" to see configuration examples');
+        console.error('  • Check the README for detailed setup instructions');
+      }
+    }
+    // File system errors
+    else if (error.message.includes('ENOENT') || error.message.includes('EACCES')) {
+      logCliError('error', 'File system error. Please check file permissions and paths.');
+    }
+    // Rate limiting
+    else if (error.message.includes('Rate limit exceeded')) {
+      logCliError('error', 'Rate limit exceeded. Please wait before trying again.');
+    }
+    // General API errors
+    else if (error.message.includes('response') || error.message.includes('status')) {
+      logCliError('error', `API error during ${operation}. Please try again or contact support.`);
+    }
+    // Unknown errors
+    else {
+      logCliError('error', `Unexpected error during ${operation}: ${error.message}`);
+      if (!verbose) {
+        console.error('\n💡 For more details, run the command with --verbose flag');
+      }
+    }
+    
+    if (verbose) {
+      logCliError('error', 'Full error details', { 
+        operation,
+        errorType: error.constructor.name,
+        stack: error.stack?.split('\n').slice(0, 5).join('\n') // First 5 lines of stack
+      });
+    }
+  } else {
+    logCliError('error', `Unknown error during ${operation}: ${String(error)}`);
+  }
+  
+  process.exit(1);
+}
+
+dotenv.config();
+
+async function main(): Promise<void> {
+  try {
+    // Initialize and validate environment at startup
+    initializeEnvironment();
+  } catch (error: unknown) {
+    if (error instanceof EnvValidationError) {
+      console.error('Environment validation failed:', error.message);
+      process.exit(1);
+    }
+    throw error;
+  }
+
+  const args = minimist(process.argv.slice(2)) as CliArgs;
+  const cmd = args._[0];
+  const verbose = Boolean(args.verbose || args.v);
+  
+  // Parse customer configuration (async for API key array support)  
+  let customerConfig;
+  try {
+    customerConfig = await parseCustomerConfigAsync(ENV as any, verbose);
+    validateCustomerConfig(customerConfig);
+  } catch (error: unknown) {
+    logCliError('error', 'Failed to parse customer configuration');
+    if (error instanceof Error) {
+      logCliError('error', error.message);
+    }
+    process.exit(1);
+  }
+  
+  // Handle customer selection
+  let selectedCustomer: CustomerConfig;
+  
+  if (cmd === 'list-customers') {
+    const customers = listCustomers(customerConfig);
+    console.log('Available customers:');
+    for (const customerIdn of customers) {
+      const isDefault = customerConfig.defaultCustomer === customerIdn;
+      console.log(`  ${customerIdn}${isDefault ? ' (default)' : ''}`);
+    }
+    return;
+  }
+  
+  if (args.customer) {
+    const customer = getCustomer(customerConfig, args.customer as string);
+    if (!customer) {
+      console.error(`Unknown customer: ${args.customer}`);
+      console.error(`Available customers: ${listCustomers(customerConfig).join(', ')}`);
+      process.exit(1);
+    }
+    selectedCustomer = customer;
+  } else {
+    try {
+      selectedCustomer = getDefaultCustomer(customerConfig);
+    } catch (error: unknown) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error(message);
+      process.exit(1);
+    }
+  }
+
+  if (!cmd || ['help', '-h', '--help'].includes(cmd)) {
+    console.log(`NEWO CLI - Multi-Customer Support
+Usage:
+  newo pull [--customer <idn>]                  # download projects -> ./newo_customers/<idn>/projects/
+  newo push [--customer <idn>]                  # upload modified *.guidance/*.jinja back to NEWO
+  newo status [--customer <idn>]                # show modified files
+  newo list-customers                           # list available customers
+  newo meta [--customer <idn>]                  # get project metadata (debug)
+  newo import-akb <file> <persona_id> [--customer <idn>]  # import AKB articles from file
+  
+Flags:
+  --customer <idn>             # specify customer (if not set, uses default)
+  --verbose, -v                # enable detailed logging
+  
+Environment Variables:
+  NEWO_BASE_URL                                 # NEWO API base URL (default: https://app.newo.ai)
+  NEWO_CUSTOMER_<IDN>_API_KEY                   # API key for customer <IDN>
+  NEWO_CUSTOMER_<IDN>_PROJECT_ID               # Optional: specific project ID for customer
+  NEWO_DEFAULT_CUSTOMER                        # Optional: default customer to use
+  
+Multi-Customer Examples:
+  # Configure customers in .env:
+  NEWO_CUSTOMER_acme_API_KEY=your_acme_api_key
+  NEWO_CUSTOMER_globex_API_KEY=your_globex_api_key
+  NEWO_DEFAULT_CUSTOMER=acme
+  
+  # Commands:
+  newo pull --customer acme                    # Pull projects for Acme
+  newo push --customer globex                  # Push changes for Globex
+  newo status                                  # Status for default customer
+  
+File Structure:
+  newo_customers/
+  ├── acme/
+  │   └── projects/
+  │       └── project1/
+  └── globex/
+      └── projects/
+          └── project2/
+`);
+    return;
+  }
+
+  // Get access token for the selected customer
+  const accessToken = await getValidAccessToken(selectedCustomer);
+  const client = await makeClient(verbose, accessToken);
+
+  if (cmd === 'pull') {
+    // Use customer-specific project ID if set, otherwise pull all projects
+    const projectId = selectedCustomer.projectId || null;
+    await pullAll(client, selectedCustomer, projectId, verbose);
+  } else if (cmd === 'push') {
+    await pushChanged(client, selectedCustomer, verbose);
+  } else if (cmd === 'status') {
+    await status(selectedCustomer, verbose);
+  } else if (cmd === 'meta') {
+    if (!selectedCustomer.projectId) {
+      console.error(`No project ID configured for customer ${selectedCustomer.idn}`);
+      console.error(`Set NEWO_CUSTOMER_${selectedCustomer.idn.toUpperCase()}_PROJECT_ID in your .env file`);
+      process.exit(1);
+    }
+    const meta = await getProjectMeta(client, selectedCustomer.projectId);
+    console.log(JSON.stringify(meta, null, 2));
+  } else if (cmd === 'import-akb') {
+    const akbFile = args._[1];
+    const personaId = args._[2];
+    
+    if (!akbFile || !personaId) {
+      console.error('Usage: newo import-akb <file> <persona_id>');
+      console.error('Example: newo import-akb akb.txt da4550db-2b95-4500-91ff-fb4b60fe7be9');
+      process.exit(1);
+    }
+    
+    const filePath = path.resolve(akbFile);
+    
+    try {
+      if (verbose) console.log(`📖 Parsing AKB file: ${filePath}`);
+      const articles = await parseAkbFile(filePath);
+      console.log(`✓ Parsed ${articles.length} articles from ${akbFile}`);
+      
+      if (verbose) console.log(`🔧 Preparing articles for persona: ${personaId}`);
+      const preparedArticles = prepareArticlesForImport(articles, personaId);
+      
+      let successCount = 0;
+      let errorCount = 0;
+      
+      console.log(`📤 Importing ${preparedArticles.length} articles...`);
+      
+      for (const [index, article] of preparedArticles.entries()) {
+        try {
+          if (verbose) {
+            console.log(`  [${index + 1}/${preparedArticles.length}] Importing ${article.topic_name}...`);
+          }
+          await importAkbArticle(client, article);
+          successCount++;
+          if (!verbose) process.stdout.write('.');
+        } catch (error: unknown) {
+          errorCount++;
+          const errorMessage = error instanceof Error && 'response' in error
+            ? (error as NewoApiError)?.response?.data
+            : error instanceof Error 
+            ? error.message
+            : String(error);
+          console.error(`\n❌ Failed to import ${article.topic_name}:`, errorMessage);
+        }
+      }
+      
+      if (!verbose) console.log(''); // new line after dots
+      console.log(`✅ Import complete: ${successCount} successful, ${errorCount} failed`);
+      
+    } catch (error: unknown) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error('❌ AKB import failed:', message);
+      process.exit(1);
+    }
+  } else {
+    console.error('Unknown command:', cmd);
+    process.exit(1);
+  }
+}
+
+main().catch((error: unknown) => {
+  // Determine operation context from command line args
+  const args = process.argv.slice(2);
+  const cmd = args.find(arg => !arg.startsWith('-')) || 'unknown command';
+  
+  // Handle API errors with specific data
+  if (error instanceof Error && 'response' in error) {
+    const apiError = error as NewoApiError;
+    const responseData = apiError.response?.data;
+    const status = apiError.response?.status;
+    
+    if (responseData && status) {
+      logCliError('error', `API error (${status}): ${JSON.stringify(responseData)}`);
+    }
+  }
+  
+  handleCliError(error, cmd);
+});

package/src/customer.ts

@@ -0,0 +1,102 @@
+import type { NewoEnvironment, CustomerConfig, MultiCustomerConfig } from './types.js';
+
+/**
+ * Parse environment variables to extract customer configurations
+ * Supports both array-based (NEWO_API_KEYS) and individual customer configs
+ */
+export function parseCustomerConfig(env: NewoEnvironment): MultiCustomerConfig {
+  const customers: Record<string, CustomerConfig> = {};
+  
+  // Parse customer-specific API keys
+  // Format: NEWO_CUSTOMER_[IDN]_API_KEY=api_key
+  for (const [key, value] of Object.entries(env)) {
+    if (key.startsWith('NEWO_CUSTOMER_') && key.endsWith('_API_KEY') && value) {
+      const idn = key.slice('NEWO_CUSTOMER_'.length, -'_API_KEY'.length).toLowerCase();
+      
+      if (!customers[idn]) {
+        customers[idn] = { idn, apiKey: value };
+      } else {
+        customers[idn].apiKey = value;
+      }
+      
+      // Check for corresponding project ID
+      const projectIdKey = `NEWO_CUSTOMER_${idn.toUpperCase()}_PROJECT_ID`;
+      if (env[projectIdKey]) {
+        customers[idn].projectId = env[projectIdKey];
+      }
+    }
+  }
+  
+  // Check for legacy single customer mode
+  if (env.NEWO_API_KEY && Object.keys(customers).length === 0) {
+    customers['default'] = { 
+      idn: 'default', 
+      apiKey: env.NEWO_API_KEY,
+      projectId: env.NEWO_PROJECT_ID
+    };
+  }
+  
+  return {
+    customers,
+    defaultCustomer: env.NEWO_DEFAULT_CUSTOMER || (Object.keys(customers).length === 1 ? Object.keys(customers)[0] : undefined)
+  };
+}
+
+/**
+ * List all available customer IDNs
+ */
+export function listCustomers(config: MultiCustomerConfig): string[] {
+  return Object.keys(config.customers).sort();
+}
+
+/**
+ * Get customer configuration by IDN
+ */
+export function getCustomer(config: MultiCustomerConfig, customerIdn: string): CustomerConfig | null {
+  return config.customers[customerIdn] || null;
+}
+
+/**
+ * Get default customer or throw error if none
+ */
+export function getDefaultCustomer(config: MultiCustomerConfig): CustomerConfig {
+  if (config.defaultCustomer) {
+    const customer = getCustomer(config, config.defaultCustomer);
+    if (customer) return customer;
+  }
+  
+  const customerIdns = listCustomers(config);
+  if (customerIdns.length === 1) {
+    const firstCustomerIdn = customerIdns[0];
+    if (firstCustomerIdn) {
+      return config.customers[firstCustomerIdn]!;
+    }
+  }
+  
+  if (customerIdns.length === 0) {
+    throw new Error('No customers configured. Please set NEWO_CUSTOMER_[IDN]_API_KEY in your .env file.');
+  }
+  
+  throw new Error(
+    `Multiple customers configured but no default specified. Available: ${customerIdns.join(', ')}. ` +
+    `Set NEWO_DEFAULT_CUSTOMER or use --customer flag.`
+  );
+}
+
+/**
+ * Validate customer configuration
+ */
+export function validateCustomerConfig(config: MultiCustomerConfig): void {
+  const customers = listCustomers(config);
+  
+  if (customers.length === 0) {
+    throw new Error('No customers configured. Please set NEWO_CUSTOMER_[IDN]_API_KEY in your .env file.');
+  }
+  
+  for (const customerIdn of customers) {
+    const customer = config.customers[customerIdn]!;
+    if (!customer.apiKey) {
+      throw new Error(`Customer ${customerIdn} missing API key`);
+    }
+  }
+}

package/src/customerAsync.ts

@@ -0,0 +1,78 @@
+import type { NewoEnvironment, CustomerConfig, MultiCustomerConfig } from './types.js';
+import { initializeCustomersFromApiKeys, usesArrayBasedConfig } from './customerInit.js';
+import { parseCustomerConfig } from './customer.js';
+
+/**
+ * Async version of customer configuration parsing that supports API key array initialization
+ */
+export async function parseCustomerConfigAsync(env: NewoEnvironment, verbose: boolean = false): Promise<MultiCustomerConfig> {
+  
+  // If using array-based config, initialize from API keys
+  if (usesArrayBasedConfig(env)) {
+    if (verbose) console.log('📝 Using array-based API key configuration');
+    return await initializeCustomersFromApiKeys(env, verbose);
+  }
+
+  // Fall back to synchronous individual customer parsing
+  if (verbose) console.log('📝 Using individual customer configuration');
+  return parseCustomerConfig(env);
+}
+
+/**
+ * List all available customer IDNs
+ */
+export function listCustomers(config: MultiCustomerConfig): string[] {
+  return Object.keys(config.customers).sort();
+}
+
+/**
+ * Get customer configuration by IDN
+ */
+export function getCustomer(config: MultiCustomerConfig, customerIdn: string): CustomerConfig | null {
+  return config.customers[customerIdn] || null;
+}
+
+/**
+ * Get default customer or throw error if none
+ */
+export function getDefaultCustomer(config: MultiCustomerConfig): CustomerConfig {
+  if (config.defaultCustomer) {
+    const customer = getCustomer(config, config.defaultCustomer);
+    if (customer) return customer;
+  }
+  
+  const customerIdns = listCustomers(config);
+  if (customerIdns.length === 1) {
+    const firstCustomerIdn = customerIdns[0];
+    if (firstCustomerIdn) {
+      return config.customers[firstCustomerIdn]!;
+    }
+  }
+  
+  if (customerIdns.length === 0) {
+    throw new Error('No customers configured. Please set NEWO_API_KEYS or NEWO_CUSTOMER_[IDN]_API_KEY in your .env file.');
+  }
+  
+  throw new Error(
+    `Multiple customers configured but no default specified. Available: ${customerIdns.join(', ')}. ` +
+    `Set NEWO_DEFAULT_CUSTOMER or use --customer flag.`
+  );
+}
+
+/**
+ * Validate customer configuration
+ */
+export function validateCustomerConfig(config: MultiCustomerConfig): void {
+  const customers = listCustomers(config);
+  
+  if (customers.length === 0) {
+    throw new Error('No customers configured. Please set NEWO_API_KEYS or NEWO_CUSTOMER_[IDN]_API_KEY in your .env file.');
+  }
+  
+  for (const customerIdn of customers) {
+    const customer = config.customers[customerIdn]!;
+    if (!customer.apiKey) {
+      throw new Error(`Customer ${customerIdn} missing API key`);
+    }
+  }
+}

package/src/customerInit.ts

@@ -0,0 +1,97 @@
+import { getCustomerProfile, makeClient } from './api.js';
+import { exchangeApiKeyForToken } from './auth.js';
+import type { NewoEnvironment, ApiKeyConfig, CustomerConfig, MultiCustomerConfig } from './types.js';
+
+/**
+ * Initialize customer configurations from API keys array
+ */
+export async function initializeCustomersFromApiKeys(
+  env: NewoEnvironment,
+  verbose: boolean = false
+): Promise<MultiCustomerConfig> {
+  if (!env.NEWO_API_KEYS) {
+    throw new Error('NEWO_API_KEYS not set. Provide API keys array in .env file.');
+  }
+
+  let apiKeyConfigs: (string | ApiKeyConfig)[];
+  
+  try {
+    apiKeyConfigs = JSON.parse(env.NEWO_API_KEYS);
+  } catch (error) {
+    throw new Error(`Invalid NEWO_API_KEYS format. Must be valid JSON array: ${error}`);
+  }
+
+  if (!Array.isArray(apiKeyConfigs)) {
+    throw new Error('NEWO_API_KEYS must be an array');
+  }
+
+  const customers: Record<string, CustomerConfig> = {};
+
+  if (verbose) console.log(`🔍 Initializing ${apiKeyConfigs.length} API keys...`);
+
+  for (const [index, keyConfig] of apiKeyConfigs.entries()) {
+    try {
+      // Normalize config
+      const apiKey = typeof keyConfig === 'string' ? keyConfig : keyConfig.key;
+      const projectId = typeof keyConfig === 'object' ? keyConfig.project_id : undefined;
+
+      if (verbose) console.log(`  [${index + 1}/${apiKeyConfigs.length}] Exchanging API key for token...`);
+
+      // Create temporary customer config for token exchange
+      const tempCustomer: CustomerConfig = { 
+        idn: 'temp', 
+        apiKey, 
+        projectId 
+      };
+
+      // Exchange API key for token
+      const tokens = await exchangeApiKeyForToken(tempCustomer);
+      
+      if (verbose) console.log(`  [${index + 1}/${apiKeyConfigs.length}] Getting customer profile...`);
+
+      // Create client with token
+      const client = await makeClient(verbose, tokens.access_token);
+
+      // Get customer profile to extract IDN
+      const profile = await getCustomerProfile(client);
+
+      if (verbose) {
+        console.log(`  [${index + 1}/${apiKeyConfigs.length}] ✓ Customer: ${profile.idn} (${profile.organization_name})`);
+      }
+
+      // Store customer config with real IDN
+      customers[profile.idn] = {
+        idn: profile.idn,
+        apiKey,
+        projectId
+      };
+
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error(`  [${index + 1}/${apiKeyConfigs.length}] ❌ Failed to initialize API key: ${message}`);
+      // Continue with other keys rather than failing entirely
+    }
+  }
+
+  const customerIdns = Object.keys(customers);
+  
+  if (customerIdns.length === 0) {
+    throw new Error('No valid API keys found. Check your NEWO_API_KEYS configuration.');
+  }
+
+  if (verbose) {
+    console.log(`✅ Initialized ${customerIdns.length} customers: ${customerIdns.join(', ')}`);
+  }
+
+  return {
+    customers,
+    defaultCustomer: env.NEWO_DEFAULT_CUSTOMER || (customerIdns.length === 1 ? customerIdns[0] : undefined)
+  };
+}
+
+/**
+ * Check if environment uses array-based configuration
+ */
+export function usesArrayBasedConfig(env: NewoEnvironment): boolean {
+  return Boolean(env.NEWO_API_KEYS);
+}