wanas-zcrm-extractor 1.7.0 → 1.7.2

package/README.md

@@ -322,11 +322,12 @@ zcrm skill --ide claude --metadata-dir ./crm-meta
 <details>
 <summary><h3>7. <code>zcrm audit</code></h3></summary>
 
-Triggers an asynchronous export of the Zoho CRM audit log, polls until it completes (with a bounded timeout), and downloads the resulting CSV/ZIP to `storage/audit_logs/`.
+Triggers an asynchronous export of the Zoho CRM audit log, polls until it completes (with a bounded timeout), and downloads the resulting CSV/ZIP into the result folder's CRM root — `metadata/crm/audit_logs/` by default (override with `-o, --output`). A subsequent `zcrm pull` never deletes this folder.
 
 ```bash
-zcrm audit                      # last 3 years by default
+zcrm audit                      # last 3 years by default → ./metadata/crm/audit_logs/
 zcrm audit --filter input.json  # custom export criteria
+zcrm audit -o ./my-export       # save into ./my-export/crm/audit_logs/
 ```
 
 > **Requires the audit-log OAuth scopes** — `ZohoCRM.settings.audit_logs.CREATE` and `ZohoCRM.settings.audit_logs.READ` (both in the default scopes). If you authenticated *before* they were added you'll see `401 invalid oauth scope` — just re-authenticate: `zcrm logout` then `zcrm login`. *(If the download step later reports a file-scope error, add `ZohoFiles.files.READ` to `ZOHO_SCOPES` and log in again.)*

package/bin/cli.js

@@ -319,8 +319,13 @@ program
         dc = dc || answers.dc;
       }
 
+      // Record the resolved, non-sensitive parameters of this run. Secrets
+      // (client secret, refresh token) are deliberately never written to disk.
+      logInfo(`Login config — DC: ${dc || 'com'}, redirect URI: ${redirectUri}, client ID set: ${!!clientId}.`, 'cli');
+
       // 1. Headless flow using direct refresh token
       if (refreshToken) {
+        logInfo('Using headless refresh-token flow (no browser callback).', 'cli');
         console.log('\n\x1b[34mℹ\x1b[0m Bypassing browser callback. Verifying refresh token credentials...');
         
         configStore.save({
@@ -336,6 +341,7 @@ program
         // Initialize and refresh to verify key validity
         authService.loadTokens();
         await authService.refreshAccessToken();
+        logInfo('Refresh token verified; access token obtained successfully.', 'cli');
 
         console.log('\n\x1b[1;32m====================================================================\x1b[0m');
         console.log('🎉 \x1b[1;32mCredentials and session authenticated successfully via Refresh Token!\x1b[0m');
@@ -344,7 +350,9 @@ program
       }
 
       // 2. Interactive Browser OAuth2 flow
+      logInfo('Starting interactive browser OAuth2 flow.', 'cli');
       await runOAuthServer(clientId, clientSecret, redirectUri, dc);
+      logInfo('OAuth2 flow completed; tokens exchanged and saved.', 'cli');
       console.log('\n\x1b[1;32m====================================================================\x1b[0m');
       console.log('🎉 \x1b[1;32mSuccessfully logged in! Access configurations saved.\x1b[0m');
       console.log('\x1b[1;32m====================================================================\x1b[0m\n');
@@ -359,7 +367,9 @@ program
   .command('logout')
   .description('Logout of Zoho CRM and clear stored configurations')
   .action(() => {
+    logInfo('Clearing stored credentials and tokens.', 'cli');
     configStore.clear();
+    logInfo('Stored configuration cleared.', 'cli');
     console.log('🎉 Stored credentials cleared successfully.');
     process.exit(0);
   });
@@ -370,6 +380,7 @@ program
   .description('Check currently authenticated Zoho CRM user and organization details')
   .action(async () => {
     console.log(getBanner());
+    logInfo('Loading stored tokens.', 'cli');
     authService.loadTokens();
 
     if (!authService.isAuthenticated()) {
@@ -378,14 +389,16 @@ program
 
     try {
       const apiClient = require('../src/utils/apiClient');
-      
+
       console.log(`\x1b[36mFetching active user and organization details...\x1b[0m\n`);
 
       // Fetch user profile and org details concurrently
+      logInfo('Fetching current user (/crm/v8/users) and org (/crm/v8/org).', 'cli');
       const [userRes, orgRes] = await Promise.all([
         apiClient.get('/crm/v8/users', { type: 'CurrentUser' }),
         apiClient.get('/crm/v8/org')
       ]);
+      logInfo('User and organization details fetched successfully.', 'cli');
 
       const user = userRes?.users?.[0] || {};
       const org = orgRes?.org?.[0] || {};
@@ -434,13 +447,16 @@ program
     console.log(`  Callback URI:     \x1b[34m${storedConfig.redirect_uri || 'Not configured'}\x1b[0m`);
     console.log(`--------------------------------------------------------------------`);
 
+    logInfo(`Auth state — has tokens: ${!!hasTokens}, DC: ${storedConfig.dc || 'none'}.`, 'cli');
+
     // 2. Check Local Metadata Directory Status
     const targetDir = path.resolve(options.dir);
     const indexPath = path.join(targetDir, '.zcrm', '.store', 'index.json');
     const functionsDir = path.join(targetDir, 'crm', 'functions');
 
     console.log(`\x1b[1m📂 Local Metadata Database (${targetDir}):\x1b[0m`);
-    
+
+    logInfo(`Inspecting local metadata directory: ${targetDir}`, 'cli');
     if (fs.existsSync(indexPath)) {
       try {
         const index = JSON.parse(fs.readFileSync(indexPath, 'utf8'));
@@ -458,6 +474,7 @@ program
           }
         }
 
+        logInfo(`Metadata database found — ${index.modules_count || 0} modules, ${fnCount} deluge scripts.`, 'cli');
         console.log(`  Status:           \x1b[1;32mDatabase Exists\x1b[0m`);
         console.log(`  Organization:     \x1b[36m${index.crm_org || 'Unknown'}\x1b[0m`);
         console.log(`  Last Synced:      \x1b[32m${index.generated_at ? new Date(index.generated_at).toLocaleString() : 'N/A'}\x1b[0m`);
@@ -467,6 +484,7 @@ program
         console.log(`  Status:           \x1b[1;33mInvalid / Corrupted Database\x1b[0m (Error: ${err.message})`);
       }
     } else {
+      logInfo('No metadata database found at target directory.', 'cli');
       console.log(`  Status:           \x1b[1;30mEmpty (No database found at target directory)\x1b[0m`);
       console.log(`  Tip:              Run \x1b[36mzcrm pull -o "${options.dir}"\x1b[0m to fetch metadata.`);
     }
@@ -616,6 +634,7 @@ program
   .command('audit')
   .description('Export the Zoho CRM audit log (asynchronous job)')
   .option('-f, --filter <path>', 'Path to a JSON file containing the audit_log_export criteria')
+  .option('-o, --output <dir>', 'Result folder to save the audit log into (its crm/audit_logs/ subfolder)', './metadata')
   .action(async (options) => {
     console.log(getBanner());
     // This command DOES read/export audit-log data, so it gets its own honest
@@ -632,10 +651,17 @@ program
     }
 
     try {
+      logInfo(`Audit output directory: ${path.resolve(options.output)}`, 'cli');
+      if (options.filter) logInfo(`Audit filter file: ${options.filter}`, 'cli');
+      logInfo('Verifying access token before export.', 'cli');
       await authService.getAccessToken(); // Refresh if necessary
-      await auditLogService.exportAuditLog(options.filter);
+      const savedPath = await auditLogService.exportAuditLog(options.filter, options.output);
       console.log('\n\x1b[1;32m====================================================================\x1b[0m');
       console.log('🎉 \x1b[1;32mAudit Log Export Completed Successfully!\x1b[0m');
+      console.log('\x1b[1;32m====================================================================\x1b[0m');
+      if (savedPath) {
+        console.log(` \x1b[1mSaved To:\x1b[0m  \x1b[34m${savedPath}\x1b[0m`);
+      }
       console.log('\x1b[1;32m====================================================================\x1b[0m\n');
       process.exit(0);
     } catch (error) {
@@ -660,8 +686,10 @@ program
     try {
       const fs = require('fs');
       const mdPath = path.join(__dirname, '../llm.md');
+      logInfo(`Reading LLM manual from ${mdPath}.`, 'cli');
       if (fs.existsSync(mdPath)) {
         const content = fs.readFileSync(mdPath, 'utf8');
+        logInfo(`LLM manual loaded (${content.length} chars); printing to console.`, 'cli');
         console.log('\n\x1b[36m📘 Wanas Extractor - LLM System Manual:\x1b[0m\n');
         console.log(content);
       } else {
@@ -706,6 +734,8 @@ program
       const projectDir = path.resolve(options.dir);
       const packageDir = path.join(__dirname, '..');
 
+      logInfo(`Generating "${ide}" skill into ${projectDir} (metadata root: ${path.resolve(options.metadataDir)}).`, 'cli');
+
       let result = skillGenerator.generateSkill({
         ide,
         projectDir,
@@ -713,6 +743,7 @@ program
         packageDir,
         force: options.force
       });
+      logInfo(`Skill generation result: ${result.status} → ${result.filePath}`, 'cli');
 
       // Standalone files that already exist require explicit confirmation.
       if (result.status === 'exists') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wanas-zcrm-extractor",
-  "version": "1.7.0",
+  "version": "1.7.2",
   "description": "Local Zoho CRM V8 Metadata Extractor CLI and Web Dashboard Utility",
   "main": "server.js",
   "bin": {

package/src/services/auditLogService.js

@@ -9,15 +9,16 @@ async function delay(ms) {
   return new Promise(resolve => setTimeout(resolve, ms));
 }
 
-async function exportAuditLog(filterFile) {
+async function exportAuditLog(filterFile, outputDir) {
   try {
-    // For a full export the request body is OPTIONAL. Sending an object WITH an
-    // empty `criteria` is rejected (400), and sending NO body trips a 415
-    // (missing content type). So the default (no filter) sends an empty JSON
-    // object `{}` — which carries the JSON content type and contains no
-    // criteria, i.e. "export everything". A filter file (which must contain a
-    // valid `audit_log_export` criteria object) overrides it when supplied.
-    let requestBody = {};
+    // For a FULL export Zoho's docs say to "skip the input request" entirely —
+    // i.e. send an EMPTY body. We send `null` (empty body); the apiClient adds
+    // the required `Content-Type: application/json` header on POSTs. This avoids
+    // BOTH the 415 (missing content type) and the 400 MANDATORY_NOT_FOUND that a
+    // present-but-incomplete object (`{}` or `[{}]`) triggers at $.audit_log_export[0].
+    // A filter file (which must contain a valid `audit_log_export[0].criteria`)
+    // overrides it when supplied.
+    let requestBody = null;
 
     if (filterFile) {
       const filterPath = path.resolve(process.cwd(), filterFile);
@@ -49,7 +50,9 @@ async function exportAuditLog(filterFile) {
 
     let downloadUrl = null;
     let attempts = 0;
-    const POLL_INTERVAL_MS = 15000;
+    // Poll cadence is overridable (mainly so the test suite doesn't wait real
+    // seconds); defaults to the documented 15s between status checks.
+    const POLL_INTERVAL_MS = parseInt(process.env.ZCRM_AUDIT_POLL_MS, 10) || 15000;
     const MAX_ATTEMPTS = 120; // 120 × 15s = 30 minutes, then give up rather than hang forever
 
     // Poll until completion (bounded so a stuck job can never hang the CLI).
@@ -87,9 +90,11 @@ async function exportAuditLog(filterFile) {
       throw new Error(`Audit log export did not finish within ${Math.round(MAX_ATTEMPTS * POLL_INTERVAL_MS / 60000)} minutes (job ${jobId}). Try a narrower filter or re-run later.`);
     }
 
-    // Download the file
-    const outputDir = path.join(process.cwd(), 'storage', 'audit_logs');
-    await fs.ensureDir(outputDir);
+    // Download the file into the result folder's CRM root, alongside the
+    // metadata `zcrm pull` produces (e.g. ./metadata/crm/audit_logs/). The pull
+    // sync sweep never touches crm/audit_logs/, so re-pulls won't delete it.
+    const targetDir = path.join(path.resolve(outputDir || './metadata'), 'crm', 'audit_logs');
+    await fs.ensureDir(targetDir);
 
     // Determine the extension from the URL *path* (signed URLs carry a query
     // string, so endsWith('.zip') on the whole URL would always miss). Default
@@ -102,7 +107,7 @@ async function exportAuditLog(filterFile) {
     } catch (urlErr) {
       // Keep the .zip default if the URL can't be parsed.
     }
-    const outputPath = path.join(outputDir, `AuditLog_${jobId}${ext}`);
+    const outputPath = path.join(targetDir, `AuditLog_${jobId}${ext}`);
 
     logInfo(`Downloading result to ${outputPath}...`);
 
@@ -133,7 +138,9 @@ async function exportAuditLog(filterFile) {
     }
 
     logInfo(`Audit log successfully downloaded and saved to: ${outputPath}`);
-    
+
+    return outputPath;
+
   } catch (error) {
     logError(error, 'auditLogService.exportAuditLog');
     throw error;