newo 1.4.0 → 1.5.0

package/src/{akb.js → akb.ts}

@@ -1,13 +1,12 @@
 import fs from 'fs-extra';
+import type { ParsedArticle, AkbImportArticle } from './types.js';
 
 /**
  * Parse AKB file and extract articles
- * @param {string} filePath - Path to AKB file
- * @returns {Array} Array of parsed articles
  */
-function parseAkbFile(filePath) {
+export function parseAkbFile(filePath: string): ParsedArticle[] {
   const content = fs.readFileSync(filePath, 'utf8');
-  const articles = [];
+  const articles: ParsedArticle[] = [];
   
   // Split by article separators (---)
   const sections = content.split(/^---\s*$/gm).filter(section => section.trim());
@@ -27,10 +26,8 @@ function parseAkbFile(filePath) {
 
 /**
  * Parse individual article section
- * @param {Array} lines - Lines of the article section
- * @returns {Object|null} Parsed article object
  */
-function parseArticleSection(lines) {
+function parseArticleSection(lines: string[]): ParsedArticle | null {
   let topicName = '';
   let category = '';
   let summary = '';
@@ -53,7 +50,7 @@ function parseArticleSection(lines) {
   const summaryLineIndex = lines.findIndex(line => line.startsWith('## ') && line.includes(' / '));
   if (summaryLineIndex >= 0 && summaryLineIndex + 1 < lines.length) {
     const nextLine = lines[summaryLineIndex + 1];
-    if (nextLine.startsWith('## ') && !nextLine.includes(' / ')) {
+    if (nextLine && nextLine.startsWith('## ') && !nextLine.includes(' / ')) {
       summary = nextLine.replace(/^##\s+/, '').trim();
     }
   }
@@ -63,7 +60,10 @@ function parseArticleSection(lines) {
     index > summaryLineIndex + 1 && line.startsWith('## ') && !line.includes(' / ')
   );
   if (keywordsLineIndex >= 0) {
-    keywords = lines[keywordsLineIndex].replace(/^##\s+/, '').trim();
+    const keywordsLine = lines[keywordsLineIndex];
+    if (keywordsLine) {
+      keywords = keywordsLine.replace(/^##\s+/, '').trim();
+    }
   }
   
   // Extract category content
@@ -76,11 +76,7 @@ function parseArticleSection(lines) {
   }
   
   // Create topic_facts array
-  const topicFacts = [
-    category,
-    summary,
-    keywords
-  ].filter(fact => fact.trim() !== '');
+  const topicFacts = [category, summary, keywords].filter(fact => fact.trim() !== '');
   
   return {
     topic_name: category, // Use the descriptive title as topic_name
@@ -89,24 +85,19 @@ function parseArticleSection(lines) {
     topic_facts: topicFacts,
     confidence: 100,
     source: topicName, // Use the ID (r001) as source
-    labels: ["rag_context"]
+    labels: ['rag_context']
   };
 }
 
 /**
  * Convert parsed articles to API format for bulk import
- * @param {Array} articles - Parsed articles
- * @param {string} personaId - Target persona ID
- * @returns {Array} Array of articles ready for API import
  */
-function prepareArticlesForImport(articles, personaId) {
+export function prepareArticlesForImport(
+  articles: ParsedArticle[], 
+  personaId: string
+): AkbImportArticle[] {
   return articles.map(article => ({
     ...article,
     persona_id: personaId
   }));
-}
-
-export {
-  parseAkbFile,
-  prepareArticlesForImport
-};
+}

package/src/api.ts

@@ -0,0 +1,127 @@
+import axios, { type AxiosInstance, type InternalAxiosRequestConfig, type AxiosResponse, type AxiosError } from 'axios';
+import dotenv from 'dotenv';
+import { getValidAccessToken, forceReauth } from './auth.js';
+import type { 
+  NewoEnvironment, 
+  ProjectMeta, 
+  Agent, 
+  Skill, 
+  FlowEvent, 
+  FlowState,
+  AkbImportArticle
+} from './types.js';
+
+dotenv.config();
+
+const { NEWO_BASE_URL } = process.env as NewoEnvironment;
+
+export async function makeClient(verbose: boolean = false): Promise<AxiosInstance> {
+  let accessToken = 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,
+    headers: { accept: 'application/json' }
+  });
+
+  client.interceptors.request.use(async (config: InternalAxiosRequestConfig) => {
+    config.headers = config.headers || {};
+    config.headers.Authorization = `Bearer ${accessToken}`;
+    
+    if (verbose) {
+      console.log(`→ ${config.method?.toUpperCase()} ${config.url}`);
+      if (config.data) console.log('  Data:', JSON.stringify(config.data, null, 2));
+      if (config.params) console.log('  Params:', config.params);
+    }
+    
+    return config;
+  });
+
+  let retried = false;
+  client.interceptors.response.use(
+    (response: AxiosResponse) => {
+      if (verbose) {
+        console.log(`← ${response.status} ${response.config.method?.toUpperCase()} ${response.config.url}`);
+        if (response.data && Object.keys(response.data).length < 20) {
+          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'}`);
+        }
+      }
+      return response;
+    },
+    async (error: AxiosError) => {
+      const status = error?.response?.status;
+      if (verbose) {
+        console.log(`← ${status} ${error.config?.method?.toUpperCase()} ${error.config?.url} - ${error.message}`);
+        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);
+        }
+      }
+      
+      throw error;
+    }
+  );
+
+  return client;
+}
+
+export async function listProjects(client: AxiosInstance): Promise<ProjectMeta[]> {
+  const response = await client.get<ProjectMeta[]>('/api/v1/designer/projects');
+  return response.data;
+}
+
+export async function listAgents(client: AxiosInstance, projectId: string): Promise<Agent[]> {
+  const response = await client.get<Agent[]>('/api/v1/bff/agents/list', { 
+    params: { project_id: projectId } 
+  });
+  return response.data;
+}
+
+export async function getProjectMeta(client: AxiosInstance, projectId: string): Promise<ProjectMeta> {
+  const response = await client.get<ProjectMeta>(`/api/v1/designer/projects/by-id/${projectId}`);
+  return response.data;
+}
+
+export async function listFlowSkills(client: AxiosInstance, flowId: string): Promise<Skill[]> {
+  const response = await client.get<Skill[]>(`/api/v1/designer/flows/${flowId}/skills`);
+  return response.data;
+}
+
+export async function getSkill(client: AxiosInstance, skillId: string): Promise<Skill> {
+  const response = await client.get<Skill>(`/api/v1/designer/skills/${skillId}`);
+  return response.data;
+}
+
+export async function updateSkill(client: AxiosInstance, skillObject: Skill): Promise<void> {
+  await client.put(`/api/v1/designer/flows/skills/${skillObject.id}`, skillObject);
+}
+
+export async function listFlowEvents(client: AxiosInstance, flowId: string): Promise<FlowEvent[]> {
+  const response = await client.get<FlowEvent[]>(`/api/v1/designer/flows/${flowId}/events`);
+  return response.data;
+}
+
+export async function listFlowStates(client: AxiosInstance, flowId: string): Promise<FlowState[]> {
+  const response = await client.get<FlowState[]>(`/api/v1/designer/flows/${flowId}/states`);
+  return response.data;
+}
+
+export async function importAkbArticle(client: AxiosInstance, articleData: AkbImportArticle): Promise<unknown> {
+  const response = await client.post('/api/v1/akb/append-manual', articleData);
+  return response.data;
+}

package/src/auth.ts

@@ -0,0 +1,142 @@
+import fs from 'fs-extra';
+import path from 'path';
+import axios from 'axios';
+import dotenv from 'dotenv';
+import type { NewoEnvironment, TokenResponse, StoredTokens } from './types.js';
+
+dotenv.config();
+
+const {
+  NEWO_BASE_URL,
+  NEWO_API_KEY,
+  NEWO_ACCESS_TOKEN,
+  NEWO_REFRESH_TOKEN,
+  NEWO_REFRESH_URL
+} = process.env as NewoEnvironment;
+
+const STATE_DIR = path.join(process.cwd(), '.newo');
+const TOKENS_PATH = path.join(STATE_DIR, 'tokens.json');
+
+async function saveTokens(tokens: StoredTokens): Promise<void> {
+  await fs.ensureDir(STATE_DIR);
+  await fs.writeJson(TOKENS_PATH, tokens, { spaces: 2 });
+}
+
+async function loadTokens(): Promise<StoredTokens | null> {
+  if (await fs.pathExists(TOKENS_PATH)) {
+    return fs.readJson(TOKENS_PATH) as Promise<StoredTokens>;
+  }
+  
+  if (NEWO_ACCESS_TOKEN || NEWO_REFRESH_TOKEN) {
+    const tokens: StoredTokens = {
+      access_token: NEWO_ACCESS_TOKEN || '',
+      refresh_token: NEWO_REFRESH_TOKEN || '',
+      expires_at: Date.now() + 10 * 60 * 1000
+    };
+    await saveTokens(tokens);
+    return tokens;
+  }
+  
+  return null;
+}
+
+function isExpired(tokens: StoredTokens | null): boolean {
+  if (!tokens?.expires_at) return false;
+  return Date.now() >= tokens.expires_at - 10_000;
+}
+
+export async function exchangeApiKeyForToken(): Promise<StoredTokens> {
+  if (!NEWO_API_KEY) {
+    throw new Error('NEWO_API_KEY not set. Provide an API key in .env');
+  }
+  
+  const url = `${NEWO_BASE_URL}/api/v1/auth/api-key/token`;
+  const response = await axios.post<TokenResponse>(
+    url, 
+    {}, 
+    { 
+      headers: { 
+        'x-api-key': NEWO_API_KEY, 
+        'accept': 'application/json' 
+      } 
+    }
+  );
+  
+  const data = response.data;
+  const access = data.access_token || data.token || data.accessToken;
+  const refresh = data.refresh_token || data.refreshToken || '';
+  const expiresInSec = data.expires_in || data.expiresIn || 3600;
+  
+  if (!access) {
+    throw new Error('Failed to get access token from API key exchange');
+  }
+  
+  const tokens: StoredTokens = { 
+    access_token: access, 
+    refresh_token: refresh, 
+    expires_at: Date.now() + expiresInSec * 1000 
+  };
+  
+  await saveTokens(tokens);
+  return tokens;
+}
+
+export async function refreshWithEndpoint(refreshToken: string): Promise<StoredTokens> {
+  if (!NEWO_REFRESH_URL) {
+    throw new Error('NEWO_REFRESH_URL not set');
+  }
+  
+  const response = await axios.post<TokenResponse>(
+    NEWO_REFRESH_URL, 
+    { refresh_token: refreshToken }, 
+    { headers: { 'accept': 'application/json' } }
+  );
+  
+  const data = response.data;
+  const access = data.access_token || data.token || data.accessToken;
+  const refresh = data.refresh_token ?? refreshToken;
+  const expiresInSec = data.expires_in || 3600;
+  
+  if (!access) {
+    throw new Error('Failed to get access token from refresh');
+  }
+  
+  const tokens: StoredTokens = { 
+    access_token: access, 
+    refresh_token: refresh, 
+    expires_at: Date.now() + expiresInSec * 1000 
+  };
+  
+  await saveTokens(tokens);
+  return tokens;
+}
+
+export async function getValidAccessToken(): Promise<string> {
+  let tokens = await loadTokens();
+  
+  if (!tokens || !tokens.access_token) {
+    tokens = await exchangeApiKeyForToken();
+    return tokens.access_token;
+  }
+  
+  if (!isExpired(tokens)) {
+    return tokens.access_token;
+  }
+
+  if (NEWO_REFRESH_URL && tokens.refresh_token) {
+    try {
+      tokens = await refreshWithEndpoint(tokens.refresh_token);
+      return tokens.access_token;
+    } catch (error) {
+      console.warn('Refresh failed, falling back to API key exchange…');
+    }
+  }
+  
+  tokens = await exchangeApiKeyForToken();
+  return tokens.access_token;
+}
+
+export async function forceReauth(): Promise<string> {
+  const tokens = await exchangeApiKeyForToken();
+  return tokens.access_token;
+}

package/src/{cli.js → cli.ts}

@@ -5,14 +5,15 @@ import { makeClient, getProjectMeta, importAkbArticle } from './api.js';
 import { pullAll, pushChanged, status } from './sync.js';
 import { parseAkbFile, prepareArticlesForImport } from './akb.js';
 import path from 'path';
+import type { NewoEnvironment, CliArgs, NewoApiError } from './types.js';
 
 dotenv.config();
-const { NEWO_PROJECT_ID } = process.env;
+const { NEWO_PROJECT_ID } = process.env as NewoEnvironment;
 
-async function main() {
-  const args = minimist(process.argv.slice(2));
+async function main(): Promise<void> {
+  const args = minimist(process.argv.slice(2)) as CliArgs;
   const cmd = args._[0];
-  const verbose = args.verbose || args.v;
+  const verbose = Boolean(args.verbose || args.v);
 
   if (!cmd || ['help', '-h', '--help'].includes(cmd)) {
     console.log(`NEWO CLI
@@ -49,7 +50,9 @@ Notes:
   } else if (cmd === 'status') {
     await status(verbose);
   } else if (cmd === 'meta') {
-    if (!NEWO_PROJECT_ID) throw new Error('NEWO_PROJECT_ID is not set in env');
+    if (!NEWO_PROJECT_ID) {
+      throw new Error('NEWO_PROJECT_ID is not set in env');
+    }
     const meta = await getProjectMeta(client, NEWO_PROJECT_ID);
     console.log(JSON.stringify(meta, null, 2));
   } else if (cmd === 'import-akb') {
@@ -79,13 +82,16 @@ Notes:
       
       for (const [index, article] of preparedArticles.entries()) {
         try {
-          if (verbose) console.log(`  [${index + 1}/${preparedArticles.length}] Importing ${article.topic_name}...`);
+          if (verbose) {
+            console.log(`  [${index + 1}/${preparedArticles.length}] Importing ${article.topic_name}...`);
+          }
           await importAkbArticle(client, article);
           successCount++;
           if (!verbose) process.stdout.write('.');
         } catch (error) {
           errorCount++;
-          console.error(`\n❌ Failed to import ${article.topic_name}:`, error?.response?.data || error.message);
+          const errorMessage = (error as NewoApiError)?.response?.data || (error as Error).message;
+          console.error(`\n❌ Failed to import ${article.topic_name}:`, errorMessage);
         }
       }
       
@@ -93,7 +99,7 @@ Notes:
       console.log(`✅ Import complete: ${successCount} successful, ${errorCount} failed`);
       
     } catch (error) {
-      console.error('❌ AKB import failed:', error.message);
+      console.error('❌ AKB import failed:', (error as Error).message);
       process.exit(1);
     }
   } else {
@@ -102,7 +108,8 @@ Notes:
   }
 }
 
-main().catch((e) => {
-  console.error(e?.response?.data || e);
+main().catch((error: NewoApiError | Error) => {
+  const errorData = 'response' in error ? error?.response?.data : error;
+  console.error(errorData || error);
   process.exit(1);
 });

package/src/{fsutil.js → fsutil.ts}

@@ -1,34 +1,41 @@
 import fs from 'fs-extra';
 import path from 'path';
+import type { RunnerType } from './types.js';
 
 export const ROOT_DIR = path.join(process.cwd(), 'projects');
 export const STATE_DIR = path.join(process.cwd(), '.newo');
 export const MAP_PATH = path.join(STATE_DIR, 'map.json');
 export const HASHES_PATH = path.join(STATE_DIR, 'hashes.json');
 
-export async function ensureState() {
+export async function ensureState(): Promise<void> {
   await fs.ensureDir(STATE_DIR);
   await fs.ensureDir(ROOT_DIR);
 }
 
-export function projectDir(projectIdn) {
+export function projectDir(projectIdn: string): string {
   return path.join(ROOT_DIR, projectIdn);
 }
 
-export function skillPath(projectIdn, agentIdn, flowIdn, skillIdn, runnerType = 'guidance') {
+export function skillPath(
+  projectIdn: string, 
+  agentIdn: string, 
+  flowIdn: string, 
+  skillIdn: string, 
+  runnerType: RunnerType = 'guidance'
+): string {
   const extension = runnerType === 'nsl' ? '.jinja' : '.guidance';
   return path.join(ROOT_DIR, projectIdn, agentIdn, flowIdn, `${skillIdn}${extension}`);
 }
 
-export function metadataPath(projectIdn) {
+export function metadataPath(projectIdn: string): string {
   return path.join(ROOT_DIR, projectIdn, 'metadata.json');
 }
 
-export async function writeFileAtomic(filepath, content) {
+export async function writeFileAtomic(filepath: string, content: string): Promise<void> {
   await fs.ensureDir(path.dirname(filepath));
   await fs.writeFile(filepath, content, 'utf8');
 }
 
-export async function readIfExists(filepath) {
+export async function readIfExists(filepath: string): Promise<string | null> {
   return (await fs.pathExists(filepath)) ? fs.readFile(filepath, 'utf8') : null;
-}
+}

package/src/hash.ts

@@ -0,0 +1,20 @@
+import crypto from 'crypto';
+import fs from 'fs-extra';
+import { ensureState, HASHES_PATH } from './fsutil.js';
+import type { HashStore } from './types.js';
+
+export function sha256(str: string): string {
+  return crypto.createHash('sha256').update(str, 'utf8').digest('hex');
+}
+
+export async function loadHashes(): Promise<HashStore> {
+  await ensureState();
+  if (await fs.pathExists(HASHES_PATH)) {
+    return fs.readJson(HASHES_PATH) as Promise<HashStore>;
+  }
+  return {};
+}
+
+export async function saveHashes(hashes: HashStore): Promise<void> {
+  await fs.writeJson(HASHES_PATH, hashes, { spaces: 2 });
+}