newo 1.5.0 → 1.5.1

package/.env.example

@@ -1,14 +1,25 @@
 # NEWO endpoints
 NEWO_BASE_URL=https://app.newo.ai
 
-# Project you want to sync (optional - leave blank to sync all accessible projects)
-# NEWO_PROJECT_ID=b78188ba-0df0-46a8-8713-f0d7cff0a06e
+# Multi-customer configuration - Array format
+# Define API keys as JSON array - customer IDN will be auto-detected from API response
+NEWO_API_KEYS=["api_key_1", "api_key_2", "api_key_3"]
+
+# Or with optional project IDs per API key
+# NEWO_API_KEYS=[{"key":"api_key_1","project_id":"project_uuid_1"}, {"key":"api_key_2","project_id":"project_uuid_2"}]
+
+# Optional: specify default customer IDN after keys are loaded
+# NEWO_DEFAULT_CUSTOMER=NEWO_ESd2BC95
 
-# Auth (choose one)
-# 1) Recommended: API key that can be exchanged for tokens:
-NEWO_API_KEY=put_api_key_here
+# Legacy format (still supported)
+# NEWO_CUSTOMER_[IDN]_API_KEY=api_key
+# NEWO_CUSTOMER_acme_API_KEY=put_acme_api_key_here
+
+# Legacy single-customer mode (still supported)
+# NEWO_API_KEY=put_api_key_here
+# NEWO_PROJECT_ID=b78188ba-0df0-46a8-8713-f0d7cff0a06e
 
-# 2) Optional bootstrap tokens (used if present)
+# Optional bootstrap tokens (for legacy mode or manual setup)
 NEWO_ACCESS_TOKEN=
 NEWO_REFRESH_TOKEN=
 

package/CHANGELOG.md

@@ -5,6 +5,67 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.5.1] - 2025-01-14
+
+### Added
+- **Comprehensive Test Coverage**: Added extensive test suites for all major modules
+  - `test/auth.test.js`: 500+ lines covering authentication, token management, multi-customer support
+  - `test/hash.test.js`: 400+ lines covering SHA256 hashing, hash storage, and cross-platform compatibility  
+  - `test/fsutil.test.js`: 400+ lines covering file system utilities and path handling
+  - `test/akb.test.js`: 600+ lines covering AKB article parsing and import workflows
+  - Added missing test dependencies: `chai`, `sinon`, `c8` for coverage reporting
+- **Enhanced Authentication Validation**:
+  - `validateApiKey()`: Comprehensive API key format and length validation
+  - `validateTokens()`: Token format and structure validation with detailed error messages
+  - `validateUrl()`: URL format validation for API endpoints
+  - Sensitive data sanitization in logs (API keys and tokens masked)
+- **Structured Logging System**:
+  - `logAuthEvent()`: Structured authentication event logging with metadata
+  - Automatic sensitive data sanitization (keys/tokens/secrets masked in logs)
+  - JSON-formatted logs with timestamp, level, module, and context information
+- **Enhanced Error Handling**:
+  - User-friendly CLI error messages with troubleshooting tips
+  - Specific error handling for authentication, network, environment, and file system errors
+  - Verbose mode support for detailed debugging information
+  - Context-aware error messages with suggested solutions
+
+### Enhanced
+- **Authentication Robustness** (`src/auth.ts`):
+  - Added comprehensive input validation with detailed error messages
+  - Enhanced network error handling with specific status code interpretation
+  - Added request timeouts (30 seconds) and retry logic for reliability
+  - Improved token expiry handling with 60-second buffer for refresh
+  - Better handling of connection errors, timeouts, and server errors
+- **CLI Error Experience** (`src/cli.ts`):
+  - Added `handleCliError()` function with categorized error types
+  - User-friendly error messages with emoji indicators and troubleshooting tips
+  - Verbose mode toggle for detailed technical information vs. clean user messages
+  - Specific guidance for common issues (API key, network, configuration)
+- **Testing Infrastructure**:
+  - Fixed ES module/CommonJS compatibility issues in test files
+  - Enhanced `TestEnvironment` class with comprehensive cleanup and mocking
+  - Added MockHttpClient, MockFileSystem, and MockLogger utilities
+  - Comprehensive assertion helpers and test data generators
+
+### Fixed
+- **Module System Compatibility**: Resolved ES module/CommonJS conflicts in test environment
+- **Test Dependencies**: Added missing testing dependencies that were imported but not declared
+- **Integration Test Paths**: Fixed paths from `src/cli.js` to `dist/cli.js` for proper compiled code testing
+- **Error Message Consistency**: Standardized error messages across authentication and CLI modules
+
+### Technical Details
+- **Validation Constants**: Added security-focused validation thresholds (API_KEY_MIN_LENGTH, TOKEN_MIN_LENGTH)
+- **Request Configuration**: Added proper timeout handling (30s) and user-agent headers
+- **Error Recovery**: Comprehensive fallback strategies for different failure scenarios
+- **Logging Standards**: JSON-structured logs with automatic PII/sensitive data protection
+- **Test Coverage**: Achieved comprehensive test coverage across all core modules with realistic scenarios
+
+### Developer Experience
+- **Enhanced Debugging**: Verbose mode provides detailed technical information for troubleshooting
+- **Better Error Messages**: Clear, actionable error messages instead of generic API errors
+- **Comprehensive Testing**: Full test suite covering authentication, file operations, hashing, and AKB import
+- **Type Safety**: All improvements maintain strict TypeScript compliance with proper error types
+
 ## [1.5.0] - 2025-09-03
 
 ### Changed

package/README.md

@@ -93,8 +93,40 @@ Hashes are tracked in `.newo/hashes.json` so only changed files are pushed.
 - **AKB import**: Import knowledge base articles from structured text files
 - **Project structure export**: Generates `flows.yaml` with complete project metadata
 - **Robust authentication**: API key exchange with automatic token refresh
+- **Enhanced error handling**: User-friendly error messages with troubleshooting guidance
+- **Comprehensive testing**: Full test suite covering all major functionality
 - **CI/CD ready**: GitHub Actions workflow included
 
+## Robustness & Error Handling
+
+NEWO CLI v1.5.1+ includes comprehensive error handling and validation:
+
+### User-Friendly Error Messages
+- **Authentication Errors**: Clear guidance when API keys are invalid or missing
+- **Network Issues**: Helpful tips for connection problems and timeouts  
+- **Configuration Errors**: Step-by-step setup instructions for common issues
+- **File System Errors**: Actionable guidance for permission and path problems
+
+### Verbose Debugging
+Use the `--verbose` or `-v` flag with any command for detailed technical information:
+```bash
+npx newo pull --verbose     # Detailed pull operation logs
+npx newo push -v           # Verbose push with full error context
+```
+
+### Enhanced Validation
+- **API Key Validation**: Format and length validation with specific error messages
+- **Token Security**: Automatic sanitization of sensitive data in logs
+- **Network Timeouts**: 30-second request timeouts with proper error handling
+- **Input Validation**: Comprehensive validation for all user inputs and configuration
+
+### Troubleshooting Tips
+When errors occur, NEWO CLI provides:
+- 🔍 **Problem diagnosis** with specific error categories
+- 💡 **Solution suggestions** for common configuration issues
+- 📋 **Step-by-step guidance** for resolving authentication and network problems
+- 🔧 **Configuration validation** to ensure proper setup
+
 ## CI/CD (GitHub Actions)
 Create `.github/workflows/deploy.yml`:
 ```yaml
@@ -179,8 +211,31 @@ npm run typecheck
 
 # Run tests
 npm test
+
+# Run tests with coverage reporting
+npm run test:coverage
+
+# Run specific test suites
+npm run test:unit          # Core module tests (api, sync, auth, hash, fsutil, akb)
+npm run test:integration   # End-to-end integration tests
 ```
 
+### Test Coverage
+NEWO CLI includes comprehensive test suites:
+- **Authentication Tests** (`test/auth.test.js`): Token management, API key validation, multi-customer support
+- **Hashing Tests** (`test/hash.test.js`): SHA256 operations, hash storage, change detection
+- **File System Tests** (`test/fsutil.test.js`): Path utilities, directory management, atomic operations
+- **AKB Import Tests** (`test/akb.test.js`): Article parsing, Unicode handling, import workflows
+- **API Tests** (`test/api.test.js`): HTTP client functionality, NEWO API integration
+- **Sync Tests** (`test/sync.test.js`): Pull/push operations, project synchronization
+- **Integration Tests** (`test/integration.test.js`): End-to-end CLI functionality
+
+Test infrastructure includes:
+- **MockHttpClient**: HTTP request/response simulation
+- **MockFileSystem**: File system operation mocking
+- **TestEnvironment**: Isolated test environments with automatic cleanup
+- **Coverage Reporting**: HTML and text coverage reports via c8
+
 ### Project Structure
 - `src/` - TypeScript source files
 - `dist/` - Compiled JavaScript output (generated by `npm run build`)

package/dist/akb.d.ts

@@ -2,7 +2,7 @@ import type { ParsedArticle, AkbImportArticle } from './types.js';
 /**
  * Parse AKB file and extract articles
  */
-export declare function parseAkbFile(filePath: string): ParsedArticle[];
+export declare function parseAkbFile(filePath: string): Promise<ParsedArticle[]>;
 /**
  * Convert parsed articles to API format for bulk import
  */

package/dist/akb.js

@@ -2,8 +2,8 @@ import fs from 'fs-extra';
 /**
  * Parse AKB file and extract articles
  */
-export function parseAkbFile(filePath) {
-    const content = fs.readFileSync(filePath, 'utf8');
+export async function parseAkbFile(filePath) {
+    const content = await fs.readFile(filePath, 'utf8');
     const articles = [];
     // Split by article separators (---)
     const sections = content.split(/^---\s*$/gm).filter(section => section.trim());
@@ -22,27 +22,31 @@ export function parseAkbFile(filePath) {
  * Parse individual article section
  */
 function parseArticleSection(lines) {
-    let topicName = '';
-    let category = '';
-    let summary = '';
-    let keywords = '';
-    let topicSummary = '';
+    const state = {
+        topicName: '',
+        category: '',
+        summary: '',
+        keywords: '',
+        topicSummary: ''
+    };
     // Find topic name (# r001)
     const topicLine = lines.find(line => line.match(/^#\s+r\d+/));
-    if (!topicLine)
+    if (!topicLine) {
+        console.warn('No topic line found in section');
         return null;
-    topicName = topicLine.replace(/^#\s+/, '').trim();
+    }
+    state.topicName = topicLine.replace(/^#\s+/, '').trim();
     // Extract category/subcategory/description (first ## line)
     const categoryLine = lines.find(line => line.startsWith('## ') && line.includes(' / '));
     if (categoryLine) {
-        category = categoryLine.replace(/^##\s+/, '').trim();
+        state.category = categoryLine.replace(/^##\s+/, '').trim();
     }
     // Extract summary (second ## line)
     const summaryLineIndex = lines.findIndex(line => line.startsWith('## ') && line.includes(' / '));
     if (summaryLineIndex >= 0 && summaryLineIndex + 1 < lines.length) {
         const nextLine = lines[summaryLineIndex + 1];
         if (nextLine && nextLine.startsWith('## ') && !nextLine.includes(' / ')) {
-            summary = nextLine.replace(/^##\s+/, '').trim();
+            state.summary = nextLine.replace(/^##\s+/, '').trim();
         }
     }
     // Extract keywords (third ## line)
@@ -50,7 +54,7 @@ function parseArticleSection(lines) {
     if (keywordsLineIndex >= 0) {
         const keywordsLine = lines[keywordsLineIndex];
         if (keywordsLine) {
-            keywords = keywordsLine.replace(/^##\s+/, '').trim();
+            state.keywords = keywordsLine.replace(/^##\s+/, '').trim();
         }
     }
     // Extract category content
@@ -58,17 +62,17 @@ function parseArticleSection(lines) {
     const categoryEndIndex = lines.findIndex(line => line.includes('</Category>'));
     if (categoryStartIndex >= 0 && categoryEndIndex >= 0) {
         const categoryLines = lines.slice(categoryStartIndex, categoryEndIndex + 1);
-        topicSummary = categoryLines.join('\n');
+        state.topicSummary = categoryLines.join('\n');
     }
     // Create topic_facts array
-    const topicFacts = [category, summary, keywords].filter(fact => fact.trim() !== '');
+    const topicFacts = [state.category, state.summary, state.keywords].filter(fact => fact.trim() !== '');
     return {
-        topic_name: category, // Use the descriptive title as topic_name
+        topic_name: state.category, // Use the descriptive title as topic_name
         persona_id: null, // Will be set when importing
-        topic_summary: topicSummary,
+        topic_summary: state.topicSummary,
         topic_facts: topicFacts,
         confidence: 100,
-        source: topicName, // Use the ID (r001) as source
+        source: state.topicName, // Use the ID (r001) as source
         labels: ['rag_context']
     };
 }

package/dist/api.d.ts

@@ -1,6 +1,6 @@
 import { type AxiosInstance } from 'axios';
-import type { ProjectMeta, Agent, Skill, FlowEvent, FlowState, AkbImportArticle } from './types.js';
-export declare function makeClient(verbose?: boolean): Promise<AxiosInstance>;
+import type { ProjectMeta, Agent, Skill, FlowEvent, FlowState, AkbImportArticle, CustomerProfile } from './types.js';
+export declare function makeClient(verbose?: boolean, token?: string): Promise<AxiosInstance>;
 export declare function listProjects(client: AxiosInstance): Promise<ProjectMeta[]>;
 export declare function listAgents(client: AxiosInstance, projectId: string): Promise<Agent[]>;
 export declare function getProjectMeta(client: AxiosInstance, projectId: string): Promise<ProjectMeta>;
@@ -10,4 +10,5 @@ export declare function updateSkill(client: AxiosInstance, skillObject: Skill):
 export declare function listFlowEvents(client: AxiosInstance, flowId: string): Promise<FlowEvent[]>;
 export declare function listFlowStates(client: AxiosInstance, flowId: string): Promise<FlowState[]>;
 export declare function importAkbArticle(client: AxiosInstance, articleData: AkbImportArticle): Promise<unknown>;
+export declare function getCustomerProfile(client: AxiosInstance): Promise<CustomerProfile>;
 //# sourceMappingURL=api.d.ts.map

package/dist/api.js

@@ -1,17 +1,14 @@
-import axios from 'axios';
-import dotenv from 'dotenv';
+import axios, {} from 'axios';
 import { getValidAccessToken, forceReauth } from './auth.js';
-dotenv.config();
-const { NEWO_BASE_URL } = process.env;
-export async function makeClient(verbose = false) {
-    let accessToken = await getValidAccessToken();
+import { ENV } from './env.js';
+// Per-request retry tracking to avoid shared state issues
+const RETRY_SYMBOL = Symbol('retried');
+export async function makeClient(verbose = false, token) {
+    let accessToken = token || await getValidAccessToken();
     if (verbose)
         console.log('✓ Access token obtained');
-    if (!NEWO_BASE_URL) {
-        throw new Error('NEWO_BASE_URL is not set in environment variables');
-    }
     const client = axios.create({
-        baseURL: NEWO_BASE_URL,
+        baseURL: ENV.NEWO_BASE_URL,
         headers: { accept: 'application/json' }
     });
     client.interceptors.request.use(async (config) => {
@@ -26,7 +23,6 @@ export async function makeClient(verbose = false) {
         }
         return config;
     });
-    let retried = false;
     client.interceptors.response.use((response) => {
         if (verbose) {
             console.log(`← ${response.status} ${response.config.method?.toUpperCase()} ${response.config.url}`);
@@ -34,7 +30,8 @@ export async function makeClient(verbose = false) {
                 console.log('  Response:', JSON.stringify(response.data, null, 2));
             }
             else if (response.data) {
-                console.log(`  Response: [${typeof response.data}] ${Array.isArray(response.data) ? response.data.length + ' items' : 'large object'}`);
+                const itemCount = Array.isArray(response.data) ? response.data.length : Object.keys(response.data).length;
+                console.log(`  Response: [${typeof response.data}] ${Array.isArray(response.data) ? itemCount + ' items' : 'large object'}`);
             }
         }
         return response;
@@ -45,15 +42,17 @@ export async function makeClient(verbose = false) {
             if (error.response?.data)
                 console.log('  Error data:', error.response.data);
         }
-        if (status === 401 && !retried) {
-            retried = true;
-            if (verbose)
-                console.log('🔄 Retrying with fresh token...');
-            accessToken = await forceReauth();
-            if (error.config) {
-                error.config.headers = error.config.headers || {};
-                error.config.headers.Authorization = `Bearer ${accessToken}`;
-                return client.request(error.config);
+        // Use per-request retry tracking to avoid shared state issues
+        const config = error.config;
+        if (status === 401 && !config?.[RETRY_SYMBOL]) {
+            if (config) {
+                config[RETRY_SYMBOL] = true;
+                if (verbose)
+                    console.log('🔄 Retrying with fresh token...');
+                accessToken = await forceReauth();
+                config.headers = config.headers || {};
+                config.headers.Authorization = `Bearer ${accessToken}`;
+                return client.request(config);
             }
         }
         throw error;
@@ -97,4 +96,8 @@ export async function importAkbArticle(client, articleData) {
     const response = await client.post('/api/v1/akb/append-manual', articleData);
     return response.data;
 }
+export async function getCustomerProfile(client) {
+    const response = await client.get('/api/v1/customer/profile');
+    return response.data;
+}
 //# sourceMappingURL=api.js.map

package/dist/auth.d.ts

@@ -1,6 +1,6 @@
-import type { StoredTokens } from './types.js';
-export declare function exchangeApiKeyForToken(): Promise<StoredTokens>;
-export declare function refreshWithEndpoint(refreshToken: string): Promise<StoredTokens>;
-export declare function getValidAccessToken(): Promise<string>;
-export declare function forceReauth(): Promise<string>;
+import type { StoredTokens, CustomerConfig } from './types.js';
+export declare function exchangeApiKeyForToken(customer?: CustomerConfig): Promise<StoredTokens>;
+export declare function refreshWithEndpoint(refreshToken: string, customer?: CustomerConfig): Promise<StoredTokens>;
+export declare function getValidAccessToken(customer?: CustomerConfig): Promise<string>;
+export declare function forceReauth(customer?: CustomerConfig): Promise<string>;
 //# sourceMappingURL=auth.d.ts.map