@orcapt/cli 1.0.3 → 1.0.4

package/bin/orca.js

@@ -335,6 +335,7 @@ lambdaCmd
   .command('invoke <function-name>')
   .description('Invoke Lambda function')
   .option('--payload <json>', 'JSON payload')
+  .option('--path <path>', 'HTTP path to invoke (e.g., health, api/v1/users)')
   .action((functionName, options) => {
     requireAuth('lambda invoke');
     lambdaInvoke(functionName, options);
@@ -345,6 +346,8 @@ lambdaCmd
   .description('Get Lambda function logs')
   .option('--tail', 'Stream logs in real-time')
   .option('--since <time>', 'Show logs since (e.g., 1h, 30m)', '10m')
+  .option('--page <number>', 'Page number (default: 1)', '1')
+  .option('--per-page <number>', 'Number of logs per page (default: 100, max: 1000)', '100')
   .action((functionName, options) => {
     requireAuth('lambda logs');
     lambdaLogs(functionName, options);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orcapt/cli",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "CLI tool for managing Orca projects - Quick setup and deployment",
   "main": "src/index.js",
   "bin": {

package/src/commands/db.js

@@ -9,6 +9,7 @@ const https = require('https');
 const http = require('http');
 const { getCredentials } = require('./login');
 const { API_BASE_URL, API_ENDPOINTS } = require('../config');
+const { handleError } = require('../utils/errorHandler');
 
 /**
  * Make API request to orcapt Deploy API
@@ -109,15 +110,7 @@ async function dbCreate(options) {
 
   } catch (error) {
     spinner.fail(chalk.red('Failed to create database'));
-    
-    if (error.statusCode === 401) {
-      console.log(chalk.red('\n✗ Authentication failed'));
-      console.log(chalk.yellow('Your session may have expired. Please run:'), chalk.white('orcapt login\n'));
-    } else if (error.response && error.response.detail) {
-      console.log(chalk.red(`\n✗ ${error.response.detail}\n`));
-    } else {
-      console.log(chalk.red(`\n✗ ${error.message}\n`));
-    }
+    handleError(error, 'Database creation');
     process.exit(1);
   }
 }
@@ -169,15 +162,7 @@ async function dbList() {
 
   } catch (error) {
     spinner.fail(chalk.red('Failed to list databases'));
-    
-    if (error.statusCode === 401) {
-      console.log(chalk.red('\n✗ Authentication failed'));
-      console.log(chalk.yellow('Your session may have expired. Please run:'), chalk.white('orcapt login\n'));
-    } else if (error.response && error.response.detail) {
-      console.log(chalk.red(`\n✗ ${error.response.detail}\n`));
-    } else {
-      console.log(chalk.red(`\n✗ ${error.message}\n`));
-    }
+    handleError(error, 'Database listing');
     process.exit(1);
   }
 }
@@ -225,17 +210,7 @@ async function dbRemove(databaseName) {
 
   } catch (error) {
     spinner.fail(chalk.red('Failed to delete database'));
-    
-    if (error.statusCode === 401) {
-      console.log(chalk.red('\n✗ Authentication failed'));
-      console.log(chalk.yellow('Your session may have expired. Please run:'), chalk.white('orcapt login\n'));
-    } else if (error.statusCode === 404) {
-      console.log(chalk.red(`\n✗ Database '${databaseName}' not found or doesn't belong to your workspace\n`));
-    } else if (error.response && error.response.detail) {
-      console.log(chalk.red(`\n✗ ${error.response.detail}\n`));
-    } else {
-      console.log(chalk.red(`\n✗ ${error.message}\n`));
-    }
+    handleError(error, 'Database deletion');
     process.exit(1);
   }
 }

package/src/commands/lambda.js

@@ -11,6 +11,7 @@ const fs = require('fs');
 const path = require('path');
 const { getCredentials } = require('./login');
 const { API_BASE_URL, API_ENDPOINTS } = require('../config');
+const { handleError } = require('../utils/errorHandler');
 const {
   checkDockerInstalled,
   checkDockerImage,
@@ -193,17 +194,7 @@ async function lambdaDeploy(functionName, options = {}) {
       });
     } catch (error) {
       spinner.fail(chalk.red('✗ Failed to request ECR credentials'));
-      console.log();
-      
-      if (error.statusCode) {
-        console.log(chalk.red('Status Code:'), error.statusCode);
-        console.log(chalk.red('Response:'), JSON.stringify(error.response, null, 2));
-      } else if (error.message) {
-        console.log(chalk.red('Error:'), error.message);
-      } else {
-        console.log(chalk.red('Error:'), error);
-      }
-      
+      handleError(error, 'ECR credentials request');
       console.log();
       console.log(chalk.yellow('💡 Troubleshooting tips:'));
       console.log(chalk.white('  1. Check if backend is running'));
@@ -289,22 +280,7 @@ async function lambdaDeploy(functionName, options = {}) {
 
   } catch (error) {
     console.log(chalk.red('\n✗ Deployment failed'));
-    
-    if (error.statusCode === 401) {
-      console.log(chalk.red('Authentication failed'));
-      console.log(chalk.yellow('Your session may have expired. Please run:'), chalk.white('orcapt login\n'));
-    } else if (error.statusCode === 404) {
-      console.log(chalk.red('Endpoint not found'));
-      console.log(chalk.yellow('The Lambda API may not be implemented yet.'));
-      console.log(chalk.cyan('See STORAGE_LAMBDA_ARCHITECTURE.md for details\n'));
-    } else if (error.code === 'ECONNREFUSED') {
-      console.log(chalk.red('Connection refused'));
-      console.log(chalk.yellow('Cannot connect to Orcapt API:'), chalk.white(API_BASE_URL));
-      console.log(chalk.cyan('Make sure the backend is running.\n'));
-    } else {
-      console.log(chalk.red(`Error: ${error.message}\n`));
-    }
-    
+    handleError(error, 'Lambda deployment');
     process.exit(1);
   }
 }
@@ -360,21 +336,7 @@ async function lambdaList() {
 
   } catch (error) {
     spinner.fail(chalk.red('Failed to list functions'));
-    
-    if (error.statusCode === 401) {
-      console.log(chalk.red('\n✗ Authentication failed'));
-      console.log(chalk.yellow('Your session may have expired. Please run:'), chalk.white('orcapt login\n'));
-    } else if (error.statusCode === 404) {
-      console.log(chalk.red('\n✗ Endpoint not found'));
-      console.log(chalk.yellow('The Lambda API may not be implemented yet.\n'));
-    } else if (error.code === 'ECONNREFUSED') {
-      console.log(chalk.red('\n✗ Connection refused'));
-      console.log(chalk.yellow('Cannot connect to Orcapt API:'), chalk.white(API_BASE_URL));
-      console.log(chalk.cyan('Make sure the backend is running.\n'));
-    } else {
-      console.log(chalk.red(`\n✗ ${error.message}\n`));
-    }
-    
+    handleError(error, 'Lambda listing');
     process.exit(1);
   }
 }
@@ -403,6 +365,10 @@ async function lambdaInvoke(functionName, options = {}) {
       process.exit(1);
     }
   }
+  
+  // Add path (default to 'health' if not provided)
+  const path = options.path || 'health';
+  console.log(chalk.white('Path:     '), chalk.yellow(path));
 
   const spinner = ora('Invoking function...').start();
 
@@ -410,11 +376,16 @@ async function lambdaInvoke(functionName, options = {}) {
     // Call backend API to invoke Lambda function
     const startTime = Date.now();
     const endpoint = API_ENDPOINTS.LAMBDA_INVOKE.replace('{functionName}', functionName);
+    const requestBody = { 
+      payload,
+      path: options.path || 'health' // Default path
+    };
+    
     const response = await makeApiRequest(
       'POST',
       endpoint,
       credentials,
-      { payload }
+      requestBody
     );
 
     const duration = Date.now() - startTime;
@@ -433,33 +404,43 @@ async function lambdaInvoke(functionName, options = {}) {
     }
 
     console.log(chalk.cyan('\nResponse:'));
-    console.log(chalk.white(JSON.stringify(response.response || response, null, 2)));
+    
+    // Parse and format the response nicely
+    const lambdaResponse = response.response || response;
+    
+    // If response has statusCode and body (API Gateway format)
+    if (lambdaResponse.statusCode && lambdaResponse.body) {
+      console.log(chalk.white('Status Code: '), chalk.green(lambdaResponse.statusCode));
+      
+      // Try to parse body as JSON
+      let bodyContent;
+      try {
+        bodyContent = JSON.parse(lambdaResponse.body);
+        console.log(chalk.white('\nBody:'));
+        console.log(chalk.green(JSON.stringify(bodyContent, null, 2)));
+      } catch (e) {
+        // If not JSON, show as string
+        console.log(chalk.white('\nBody:'));
+        console.log(chalk.green(lambdaResponse.body));
+      }
+      
+      // Show headers if available
+      if (lambdaResponse.headers && Object.keys(lambdaResponse.headers).length > 0) {
+        console.log(chalk.white('\nHeaders:'));
+        Object.entries(lambdaResponse.headers).forEach(([key, value]) => {
+          console.log(chalk.gray(`  ${key}: `), chalk.yellow(value));
+        });
+      }
+    } else {
+      // Regular response format
+      console.log(chalk.green(JSON.stringify(lambdaResponse, null, 2)));
+    }
 
     console.log(chalk.cyan('\n============================================================\n'));
 
   } catch (error) {
     spinner.fail(chalk.red('Invocation failed'));
-    
-    if (error.statusCode === 401) {
-      console.log(chalk.red('\n✗ Authentication failed'));
-      console.log(chalk.yellow('Your session may have expired. Please run:'), chalk.white('orcapt login\n'));
-    } else if (error.statusCode === 404) {
-      console.log(chalk.red('\n✗ Function not found'));
-      console.log(chalk.yellow(`Function '${functionName}' does not exist or doesn't belong to your workspace.\n`));
-    } else if (error.statusCode === 500) {
-      console.log(chalk.red('\n✗ Function execution error'));
-      if (error.response && error.response.error) {
-        console.log(chalk.yellow('Error:'), chalk.white(error.response.error));
-      }
-      console.log();
-    } else if (error.code === 'ECONNREFUSED') {
-      console.log(chalk.red('\n✗ Connection refused'));
-      console.log(chalk.yellow('Cannot connect to Orcapt API:'), chalk.white(API_BASE_URL));
-      console.log(chalk.cyan('Make sure the backend is running.\n'));
-    } else {
-      console.log(chalk.red(`\n✗ ${error.message}\n`));
-    }
-    
+    handleError(error, 'Lambda invocation');
     process.exit(1);
   }
 }
@@ -486,11 +467,24 @@ async function lambdaLogs(functionName, options = {}) {
 
   const spinner = ora('Fetching logs...').start();
   const endpoint = API_ENDPOINTS.LAMBDA_LOGS.replace('{functionName}', functionName);
+  
+  // Build query parameters for pagination
+  const queryParams = {};
+  if (options.page) {
+    queryParams.page = parseInt(options.page) || 1;
+  }
+  if (options.perPage) {
+    queryParams.per_page = Math.min(parseInt(options.perPage) || 100, 1000);
+  }
+  
+  const queryString = new URLSearchParams(queryParams).toString();
+  const fullEndpoint = queryString ? `${endpoint}?${queryString}` : endpoint;
+  
   try {
     // Call backend API to get logs
     const response = await makeApiRequest(
       'GET',
-     endpoint,
+     fullEndpoint,
       credentials
     );
 
@@ -498,12 +492,37 @@ async function lambdaLogs(functionName, options = {}) {
 
     console.log(chalk.cyan('\n============================================================'));
     
+    // Show sync statistics
+    if (response.synced_from_cloudwatch !== undefined || response.skipped_duplicates !== undefined) {
+      console.log(chalk.cyan('📊 Sync Statistics:'));
+      if (response.total_cloudwatch_logs !== undefined) {
+        console.log(chalk.white('  CloudWatch logs: '), chalk.yellow(response.total_cloudwatch_logs));
+      }
+      if (response.synced_from_cloudwatch !== undefined) {
+        console.log(chalk.white('  Newly synced:   '), chalk.green(response.synced_from_cloudwatch));
+      }
+      if (response.skipped_duplicates !== undefined) {
+        console.log(chalk.white('  Skipped (dup):  '), chalk.gray(response.skipped_duplicates));
+      }
+      console.log();
+    }
+    
     if (!response.logs || response.logs.length === 0) {
-      console.log(chalk.yellow('No logs found'));
+      console.log(chalk.yellow('No logs found in database'));
       console.log(chalk.cyan('\nTry invoking the function first:'));
       console.log(chalk.white('  orcapt lambda invoke'), chalk.cyan(functionName));
     } else {
-      console.log(chalk.green(`✓ Found ${response.logs.length} log entries`));
+      // Show pagination info
+      if (response.pagination) {
+        const pagination = response.pagination;
+        console.log(chalk.cyan('📄 Pagination:'));
+        console.log(chalk.white('  Page:         '), chalk.yellow(`${pagination.current_page} / ${pagination.total_pages}`));
+        console.log(chalk.white('  Per page:     '), chalk.yellow(pagination.per_page));
+        console.log(chalk.white('  Total logs:   '), chalk.yellow(pagination.total));
+        console.log();
+      }
+      
+      console.log(chalk.green(`✓ Showing ${response.logs.length} log entries (page ${response.pagination?.current_page || 1})`));
       console.log(chalk.cyan('============================================================\n'));
       
       response.logs.forEach(log => {
@@ -521,6 +540,21 @@ async function lambdaLogs(functionName, options = {}) {
           chalk.white(log.message)
         );
       });
+      
+      // Show pagination navigation hints
+      if (response.pagination) {
+        const pagination = response.pagination;
+        console.log(chalk.cyan('\n============================================================'));
+        if (pagination.has_prev_page) {
+          console.log(chalk.white('  Previous page: '), chalk.cyan(`orcapt lambda logs ${functionName} --page ${pagination.current_page - 1}`));
+        }
+        if (pagination.has_next_page) {
+          console.log(chalk.white('  Next page:     '), chalk.cyan(`orcapt lambda logs ${functionName} --page ${pagination.current_page + 1}`));
+        }
+        if (!pagination.has_prev_page && !pagination.has_next_page) {
+          console.log(chalk.gray('  (No more pages)'));
+        }
+      }
     }
     
     console.log(chalk.cyan('\n============================================================'));
@@ -534,21 +568,7 @@ async function lambdaLogs(functionName, options = {}) {
 
   } catch (error) {
     spinner.fail(chalk.red('Failed to fetch logs'));
-    
-    if (error.statusCode === 401) {
-      console.log(chalk.red('\n✗ Authentication failed'));
-      console.log(chalk.yellow('Your session may have expired. Please run:'), chalk.white('orcapt login\n'));
-    } else if (error.statusCode === 404) {
-      console.log(chalk.red('\n✗ Function not found'));
-      console.log(chalk.yellow(`Function '${functionName}' does not exist or doesn't belong to your workspace.\n`));
-    } else if (error.code === 'ECONNREFUSED') {
-      console.log(chalk.red('\n✗ Connection refused'));
-      console.log(chalk.yellow('Cannot connect to Orcapt API:'), chalk.white(API_BASE_URL));
-      console.log(chalk.cyan('Make sure the backend is running.\n'));
-    } else {
-      console.log(chalk.red(`\n✗ ${error.message}\n`));
-    }
-    
+    handleError(error, 'Lambda logs');
     process.exit(1);
   }
 }
@@ -595,24 +615,7 @@ async function lambdaRemove(functionName) {
 
   } catch (error) {
     spinner.fail(chalk.red('Failed to remove function'));
-    
-    if (error.statusCode === 401) {
-      console.log(chalk.red('\n✗ Authentication failed'));
-      console.log(chalk.yellow('Your session may have expired. Please run:'), chalk.white('orcapt login\n'));
-    } else if (error.statusCode === 404) {
-      console.log(chalk.red('\n✗ Function not found'));
-      console.log(chalk.yellow(`Function '${functionName}' does not exist or doesn't belong to your workspace.\n`));
-    } else if (error.statusCode === 409) {
-      console.log(chalk.red('\n✗ Conflict'));
-      console.log(chalk.yellow('Function may be currently in use. Please try again later.\n'));
-    } else if (error.code === 'ECONNREFUSED') {
-      console.log(chalk.red('\n✗ Connection refused'));
-      console.log(chalk.yellow('Cannot connect to Orcapt API:'), chalk.white(API_BASE_URL));
-      console.log(chalk.cyan('Make sure the backend is running.\n'));
-    } else {
-      console.log(chalk.red(`\n✗ ${error.message}\n`));
-    }
-    
+    handleError(error, 'Lambda removal');
     process.exit(1);
   }
 }
@@ -706,21 +709,7 @@ async function lambdaInfo(functionName) {
 
   } catch (error) {
     spinner.fail(chalk.red('Failed to fetch function details'));
-    
-    if (error.statusCode === 401) {
-      console.log(chalk.red('\n✗ Authentication failed'));
-      console.log(chalk.yellow('Your session may have expired. Please run:'), chalk.white('orcapt login\n'));
-    } else if (error.statusCode === 404) {
-      console.log(chalk.red('\n✗ Function not found'));
-      console.log(chalk.yellow(`Function '${functionName}' does not exist or doesn't belong to your workspace.\n`));
-    } else if (error.code === 'ECONNREFUSED') {
-      console.log(chalk.red('\n✗ Connection refused'));
-      console.log(chalk.yellow('Cannot connect to Orcapt API:'), chalk.white(API_BASE_URL));
-      console.log(chalk.cyan('Make sure the backend is running.\n'));
-    } else {
-      console.log(chalk.red(`\n✗ ${error.message}\n`));
-    }
-    
+    handleError(error, 'Lambda info');
     process.exit(1);
   }
 }

package/src/commands/storage.js

@@ -11,6 +11,7 @@ const https = require('https');
 const http = require('http');
 const { getCredentials } = require('./login');
 const { API_BASE_URL, API_ENDPOINTS } = require('../config');
+const { handleError } = require('../utils/errorHandler');
 
 /**
  * Make API request to orcapt Deploy API
@@ -253,18 +254,7 @@ async function bucketCreate(bucketName, options = {}) {
 
   } catch (error) {
     spinner.fail(chalk.red('✗ Failed to create bucket'));
-
-    if (error.response) {
-      console.log(chalk.red(`\n✗ ${error.response.message || 'Unknown error'}`));
-      if (error.statusCode === 409) {
-        console.log(chalk.yellow('  Bucket name already exists for this workspace'));
-      } else if (error.statusCode === 422) {
-        console.log(chalk.yellow('  Invalid bucket name or parameters'));
-      }
-    } else {
-      console.log(chalk.red(`\n✗ ${error.message}`));
-    }
-    console.log('');
+    handleError(error, 'Bucket creation');
     process.exit(1);
   }
 }
@@ -336,12 +326,7 @@ async function bucketList() {
 
   } catch (error) {
     spinner.fail(chalk.red('✗ Failed to list buckets'));
-
-    if (error.response) {
-      console.log(chalk.red(`\n✗ ${error.response.message || 'Unknown error'}\n`));
-    } else {
-      console.log(chalk.red(`\n✗ ${error.message}\n`));
-    }
+    handleError(error, 'Bucket listing');
     process.exit(1);
   }
 }
@@ -414,18 +399,7 @@ async function fileUpload(bucketName, localPath, options = {}) {
 
   } catch (error) {
     spinner.fail(chalk.red('✗ Upload failed'));
-
-    if (error.response) {
-      console.log(chalk.red(`\n✗ ${error.response.message || 'Unknown error'}`));
-      if (error.statusCode === 404) {
-        console.log(chalk.yellow('  Bucket not found'));
-      } else if (error.statusCode === 413) {
-        console.log(chalk.yellow('  File too large (max 100MB)'));
-      }
-    } else {
-      console.log(chalk.red(`\n✗ ${error.message}`));
-    }
-    console.log('');
+    handleError(error, 'File upload');
     process.exit(1);
   }
 }
@@ -504,16 +478,7 @@ async function fileDownload(bucketName, fileKey, localPath) {
 
   } catch (error) {
     spinner.fail(chalk.red('✗ Download failed'));
-
-    if (error.response) {
-      console.log(chalk.red(`\n✗ ${error.response.message || 'Unknown error'}`));
-      if (error.statusCode === 404) {
-        console.log(chalk.yellow('  File or bucket not found'));
-      }
-    } else {
-      console.log(chalk.red(`\n✗ ${error.message}`));
-    }
-    console.log('');
+    handleError(error, 'File download');
     process.exit(1);
   }
 }
@@ -560,16 +525,7 @@ async function bucketInfo(bucketName) {
 
   } catch (error) {
     spinner.fail(chalk.red('✗ Failed to get bucket info'));
-
-    if (error.response) {
-      console.log(chalk.red(`\n✗ ${error.response.message || 'Unknown error'}`));
-      if (error.statusCode === 404) {
-        console.log(chalk.yellow('  Bucket not found'));
-      }
-    } else {
-      console.log(chalk.red(`\n✗ ${error.message}`));
-    }
-    console.log('');
+    handleError(error, 'Bucket info');
     process.exit(1);
   }
 }
@@ -604,20 +560,7 @@ async function bucketDelete(bucketName, options = {}) {
 
   } catch (error) {
     spinner.fail(chalk.red('✗ Failed to delete bucket'));
-
-    if (error.response) {
-      console.log(chalk.red(`\n✗ ${error.response.message || 'Unknown error'}`));
-      if (error.statusCode === 404) {
-        console.log(chalk.yellow('  Bucket not found'));
-      } else if (error.statusCode === 400 && error.response.file_count) {
-        console.log(chalk.yellow(`  Bucket contains ${error.response.file_count} file(s)`));
-        console.log(chalk.cyan('  Use --force to delete anyway:'));
-        console.log(chalk.white('  '), chalk.yellow(`orcapt storage bucket delete ${bucketName} --force`));
-      }
-    } else {
-      console.log(chalk.red(`\n✗ ${error.message}`));
-    }
-    console.log('');
+    handleError(error, 'Bucket deletion');
     process.exit(1);
   }
 }
@@ -713,16 +656,7 @@ async function fileList(bucketName, options = {}) {
 
   } catch (error) {
     spinner.fail(chalk.red('✗ Failed to list files'));
-
-    if (error.response) {
-      console.log(chalk.red(`\n✗ ${error.response.message || 'Unknown error'}`));
-      if (error.statusCode === 404) {
-        console.log(chalk.yellow('  Bucket not found'));
-      }
-    } else {
-      console.log(chalk.red(`\n✗ ${error.message}`));
-    }
-    console.log('');
+    handleError(error, 'File listing');
     process.exit(1);
   }
 }
@@ -755,16 +689,7 @@ async function fileDelete(bucketName, fileKey) {
 
   } catch (error) {
     spinner.fail(chalk.red('✗ Failed to delete file'));
-
-    if (error.response) {
-      console.log(chalk.red(`\n✗ ${error.response.message || 'Unknown error'}`));
-      if (error.statusCode === 404) {
-        console.log(chalk.yellow('  File or bucket not found'));
-      }
-    } else {
-      console.log(chalk.red(`\n✗ ${error.message}`));
-    }
-    console.log('');
+    handleError(error, 'File deletion');
     process.exit(1);
   }
 }

package/src/utils/errorHandler.js

@@ -0,0 +1,153 @@
+/**
+ * Unified Error Handler for Orca CLI
+ * Handles errors from different API services and formats them for CLI display
+ */
+
+const chalk = require('chalk');
+
+/**
+ * Extract error message from API response
+ * Supports multiple response formats:
+ * - databaseasservice: { success: false, error: "message" }
+ * - gptclone-api/platform-api: { result: null, message: "message" }
+ * - Generic: { detail: "message" } or { message: "message" }
+ */
+function extractErrorMessage(error) {
+  if (!error.response) {
+    return error.message || 'Unknown error occurred';
+  }
+
+  const response = error.response;
+
+  // databaseasservice format: { success: false, error: "message" }
+  if (response.error) {
+    return response.error;
+  }
+
+  // gptclone-api/platform-api format: { result: null, message: "message" }
+  if (response.message) {
+    return response.message;
+  }
+
+  // Generic format: { detail: "message" }
+  if (response.detail) {
+    return response.detail;
+  }
+
+  // Laravel validation errors: { errors: { field: ["message"] } }
+  if (response.errors && typeof response.errors === 'object') {
+    const errorMessages = [];
+    for (const [field, messages] of Object.entries(response.errors)) {
+      if (Array.isArray(messages)) {
+        errorMessages.push(...messages);
+      } else {
+        errorMessages.push(messages);
+      }
+    }
+    if (errorMessages.length > 0) {
+      return errorMessages.join(', ');
+    }
+  }
+
+  // Fallback: try to stringify the response
+  if (typeof response === 'string') {
+    return response;
+  }
+
+  return 'Unknown error occurred';
+}
+
+/**
+ * Get user-friendly error message based on status code
+ */
+function getStatusMessage(statusCode) {
+  const messages = {
+    400: 'Bad Request - Please check your input parameters',
+    401: 'Authentication failed - Your session may have expired',
+    403: 'Forbidden - You don\'t have permission to perform this action',
+    404: 'Resource not found',
+    409: 'Conflict - Resource already exists',
+    422: 'Validation error - Please check your input',
+    500: 'Internal server error - Please try again later',
+    502: 'Bad Gateway - Service temporarily unavailable',
+    503: 'Service unavailable - Please try again later',
+    504: 'Gateway timeout - Request took too long',
+  };
+
+  return messages[statusCode] || `HTTP ${statusCode} error`;
+}
+
+/**
+ * Handle and display error to CLI
+ */
+function handleError(error, context = 'Operation') {
+  const statusCode = error.statusCode || error.status || (error.response && error.response.statusCode);
+  const errorMessage = extractErrorMessage(error);
+
+  // Network/connection errors
+  if (error.code === 'ECONNREFUSED') {
+    console.log(chalk.red(`\n✗ Connection refused`));
+    console.log(chalk.yellow('The API server is not reachable. Please check:'));
+    console.log(chalk.white('  1. Is the backend service running?'));
+    console.log(chalk.white('  2. Is the API URL correct?'));
+    console.log(chalk.white('  3. Check your network connection\n'));
+    return;
+  }
+
+  if (error.code === 'ETIMEDOUT' || error.code === 'ENOTFOUND') {
+    console.log(chalk.red(`\n✗ Network error: ${error.message}`));
+    console.log(chalk.yellow('Please check your network connection and API URL\n'));
+    return;
+  }
+
+  // HTTP status code errors
+  if (statusCode) {
+    const statusMessage = getStatusMessage(statusCode);
+    
+    console.log(chalk.red(`\n✗ ${context} failed`));
+    console.log(chalk.red(`  Status: ${statusCode} - ${statusMessage}`));
+    
+    if (errorMessage && errorMessage !== 'Unknown error occurred') {
+      console.log(chalk.yellow(`  Error: ${errorMessage}`));
+    }
+
+    // Specific handling for common status codes
+    if (statusCode === 401) {
+      console.log(chalk.cyan('\nPlease run:'), chalk.white('orcapt login'), chalk.cyan('to authenticate\n'));
+    } else if (statusCode === 404) {
+      console.log(chalk.yellow('\nThe requested resource was not found or doesn\'t belong to your workspace\n'));
+    } else if (statusCode === 422) {
+      console.log(chalk.yellow('\nPlease check your input parameters and try again\n'));
+    } else if (statusCode >= 500) {
+      console.log(chalk.yellow('\nThis appears to be a server-side error. Please try again later.\n'));
+      console.log(chalk.gray('If the problem persists, contact support.\n'));
+    } else {
+      console.log('');
+    }
+    return;
+  }
+
+  // Generic error
+  console.log(chalk.red(`\n✗ ${context} failed`));
+  console.log(chalk.red(`  ${errorMessage}\n`));
+}
+
+/**
+ * Format error for programmatic use (returns error object)
+ */
+function formatError(error) {
+  return {
+    statusCode: error.statusCode || error.status || (error.response && error.response.statusCode),
+    message: extractErrorMessage(error),
+    code: error.code,
+    response: error.response,
+  };
+}
+
+module.exports = {
+  handleError,
+  formatError,
+  extractErrorMessage,
+  getStatusMessage,
+};
+