botversion-sdk 1.1.7 → 2.1.0

package/bin/scan-backend.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+"use strict";
+
+var path = require("path");
+var fs = require("fs");
+var sdk = require("../index");
+var BotVersionClient = require("../client");
+
+// Auto-load env files from the customer's project, same precedence Next.js
+// uses: .env first, then .env.local (which is allowed to override .env).
+// dotenv.config() never overwrites a variable already set in process.env,
+// so if the customer already exported the key in their shell/CI, that
+// still takes priority over anything in these files.
+(function loadEnvFiles() {
+  var dotenv;
+  try {
+    dotenv = require("dotenv");
+  } catch (e) {
+    return; // dotenv not installed for some reason — skip silently
+  }
+  var cwd = process.cwd();
+  [".env", ".env.local"].forEach(function (file) {
+    var filePath = path.join(cwd, file);
+    if (fs.existsSync(filePath)) {
+      dotenv.config({ path: filePath });
+    }
+  });
+})();
+
+var apiKey = process.env.BOTVERSION_API_KEY;
+var platformUrl =
+  process.env.BOTVERSION_PLATFORM_URL || "https://console.botversion.com";
+
+if (!apiKey) {
+  console.error(
+    "[BotVersion] BOTVERSION_API_KEY environment variable is not set. Skipping backend endpoint scan.",
+  );
+  process.exit(0);
+}
+
+var cwd = process.cwd();
+var client = new BotVersionClient({ apiKey: apiKey, platformUrl: platformUrl });
+
+var detected = sdk.detectFrameworks(cwd);
+var projectType = sdk.classifyInstallation(detected.backend, detected.frontend);
+
+var shouldScanBackend =
+  projectType === "fullstack" ||
+  projectType === "backend-only" ||
+  projectType === "mixed";
+
+if (!shouldScanBackend) {
+  process.exit(0);
+}
+
+// No live `app` instance exists at build time — pass null.
+// All scanner functions read directly from the filesystem via cwd.
+var endpoints = sdk.runBackendScanner(detected.backend, null, {}, cwd);
+
+if (endpoints.length === 0) {
+  process.exit(0);
+}
+
+client
+  .registerEndpointsNow(endpoints)
+  .then(function () {
+    process.exit(0);
+  })
+  .catch(function (err) {
+    console.error(
+      "[BotVersion] Failed to report backend endpoints:",
+      err.message,
+    );
+    process.exit(0);
+  });

package/bin/scan-frontend.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+"use strict";
+
+var path = require("path");
+var fs = require("fs");
+var scanner = require("../scanner");
+var BotVersionClient = require("../client");
+var sdk = require("../index");
+
+// Auto-load env files from the customer's project, same precedence Next.js
+// uses: .env first, then .env.local (which is allowed to override .env).
+// dotenv.config() never overwrites a variable already set in process.env,
+// so if the customer already exported the key in their shell/CI, that
+// still takes priority over anything in these files.
+(function loadEnvFiles() {
+  var dotenv;
+  try {
+    dotenv = require("dotenv");
+  } catch (e) {
+    return; // dotenv not installed for some reason — skip silently
+  }
+  var cwd = process.cwd();
+  [".env", ".env.local"].forEach(function (file) {
+    var filePath = path.join(cwd, file);
+    if (fs.existsSync(filePath)) {
+      dotenv.config({ path: filePath });
+    }
+  });
+})();
+
+var apiKey = process.env.BOTVERSION_API_KEY;
+var platformUrl =
+  process.env.BOTVERSION_PLATFORM_URL || "https://console.botversion.com";
+
+if (!apiKey) {
+  console.error(
+    "[BotVersion] BOTVERSION_API_KEY environment variable is not set. Skipping frontend route scan.",
+  );
+  process.exit(0);
+}
+
+var cwd = process.cwd();
+var client = new BotVersionClient({ apiKey: apiKey, platformUrl: platformUrl });
+
+var detected = sdk.detectFrameworks(cwd);
+var projectType = sdk.classifyInstallation(detected.backend, detected.frontend);
+var routePatterns = scanner.scanFrontendRoutes(cwd);
+
+client
+  .registerRoutePatterns(routePatterns, {
+    source: "cli",
+    projectType: projectType,
+    detectedBackend: detected.backend,
+    detectedFrontend: detected.frontend,
+    sdkLanguage: "javascript",
+  })
+  .then(function () {
+    process.exit(0);
+  })
+  .catch(function (err) {
+    console.error(
+      "[BotVersion] Failed to report frontend routes:",
+      err.message,
+    );
+    process.exit(0);
+  });

package/client.js

@@ -11,7 +11,7 @@ const url = require("url");
  */
 function BotVersionClient(options) {
   this.apiKey = options.apiKey;
-  this.platformUrl = options.platformUrl || "https://botversion.com";
+  this.platformUrl = options.platformUrl || "https://console.botversion.com";
   this.debug = options.debug || false;
   this.timeout = options.timeout || 30000;
 
@@ -99,14 +99,20 @@ BotVersionClient.prototype.updateEndpoint = function (endpoint) {
   });
 };
 
-BotVersionClient.prototype.registerRoutePatterns = function (patterns) {
+BotVersionClient.prototype.registerRoutePatterns = function (
+  patterns,
+  classification,
+) {
   var self = this;
-  if (!patterns || patterns.length === 0) return Promise.resolve();
-
-  return self._post("/api/sdk/register-route-patterns", {
+  var body = {
     workspaceKey: self.apiKey,
-    patterns: patterns,
-  });
+    patterns: patterns || [],
+    classification: classification || null,
+  };
+  if ((!patterns || patterns.length === 0) && !classification) {
+    return Promise.resolve();
+  }
+  return self._post("/api/sdk/register-route-patterns", body);
 };
 
 /**

package/index.js

@@ -161,6 +161,91 @@ function runBackendScanner(detectedBackend, app, options, cwd) {
   return endpoints;
 }
 
+var FULLSTACK_FRAMEWORKS = ["nextjs", "nuxt", "sveltekit", "remix"];
+var BACKEND_ONLY_FRAMEWORKS = [
+  "express",
+  "fastify",
+  "nestjs",
+  "koa",
+  "hapi",
+  "adonis",
+];
+
+function classifyInstallation(detectedBackend, detectedFrontend) {
+  if (FULLSTACK_FRAMEWORKS.indexOf(detectedBackend) !== -1) {
+    return "fullstack";
+  }
+  if (
+    BACKEND_ONLY_FRAMEWORKS.indexOf(detectedBackend) !== -1 &&
+    detectedFrontend === "unknown"
+  ) {
+    return "backend-only";
+  }
+  if (detectedBackend === "unknown" && detectedFrontend !== "unknown") {
+    return "frontend-only";
+  }
+  if (detectedBackend === "unknown" && detectedFrontend === "unknown") {
+    return "unknown";
+  }
+  return "mixed";
+}
+
+// ── Run a full scan (backend endpoints + frontend routes) and report ────────
+// This used to run automatically 3 seconds after server start. Now it only
+// runs when the BotVersion dashboard's "Scan" button sends a request to this
+// SDK's internal scan-trigger endpoint (see interceptor.js). This fixes scans
+// not happening on serverless redeploys (Vercel, etc.) since there's no
+// "restart" event to hook into there.
+function runFullScan(
+  detectedBackend,
+  detectedFrontend,
+  app,
+  options,
+  cwd,
+  client,
+) {
+  var projectType = classifyInstallation(detectedBackend, detectedFrontend);
+
+  var result = {
+    endpointCount: 0,
+    routeCount: 0,
+    projectType: projectType,
+    detectedBackend: detectedBackend,
+    detectedFrontend: detectedFrontend,
+    sdkLanguage: "javascript",
+  };
+
+  var shouldScanBackend =
+    projectType === "fullstack" ||
+    projectType === "backend-only" ||
+    projectType === "mixed";
+
+  var shouldScanFrontend =
+    projectType === "fullstack" || projectType === "frontend-only";
+
+  if (shouldScanBackend) {
+    var endpoints = runBackendScanner(detectedBackend, app, options, cwd);
+    result.endpointCount = endpoints.length;
+
+    if (endpoints.length > 0) {
+      client.registerEndpoints(endpoints);
+    }
+  }
+
+  if (shouldScanFrontend) {
+    var routePatterns = scanner.scanFrontendRoutes(cwd);
+    result.routeCount = routePatterns.length;
+
+    if (routePatterns.length > 0) {
+      client.registerRoutePatterns(routePatterns).catch(function () {
+        // silently ignore — non-critical
+      });
+    }
+  }
+
+  return result;
+}
+
 // ── Attach the right runtime interceptor ─────────────────────────────────────
 function attachRuntimeInterceptor(detectedBackend, app, client, options) {
   switch (detectedBackend) {
@@ -169,6 +254,8 @@ function attachRuntimeInterceptor(detectedBackend, app, client, options) {
         exclude: options.exclude || [],
         apiPrefix: options.apiPrefix || null,
         debug: options.debug || false,
+        scanSecret: options.scanSecret,
+        onScanRequested: options.onScanRequested,
       });
       break;
 
@@ -177,6 +264,8 @@ function attachRuntimeInterceptor(detectedBackend, app, client, options) {
         exclude: options.exclude || [],
         apiPrefix: options.apiPrefix || "/api",
         debug: options.debug || false,
+        scanSecret: options.scanSecret,
+        onScanRequested: options.onScanRequested,
       });
       break;
 
@@ -186,6 +275,8 @@ function attachRuntimeInterceptor(detectedBackend, app, client, options) {
           exclude: options.exclude || [],
           apiPrefix: options.apiPrefix || null,
           debug: options.debug || false,
+          scanSecret: options.scanSecret,
+          onScanRequested: options.onScanRequested,
         });
       }
       break;
@@ -196,6 +287,8 @@ function attachRuntimeInterceptor(detectedBackend, app, client, options) {
           exclude: options.exclude || [],
           apiPrefix: options.apiPrefix || null,
           debug: options.debug || false,
+          scanSecret: options.scanSecret,
+          onScanRequested: options.onScanRequested,
         });
       }
       break;
@@ -206,6 +299,8 @@ function attachRuntimeInterceptor(detectedBackend, app, client, options) {
           exclude: options.exclude || [],
           apiPrefix: options.apiPrefix || null,
           debug: options.debug || false,
+          scanSecret: options.scanSecret,
+          onScanRequested: options.onScanRequested,
         });
       }
       break;
@@ -215,6 +310,8 @@ function attachRuntimeInterceptor(detectedBackend, app, client, options) {
         exclude: options.exclude || [],
         apiPrefix: options.apiPrefix || "/",
         debug: options.debug || false,
+        scanSecret: options.scanSecret,
+        onScanRequested: options.onScanRequested,
       });
       break;
 
@@ -223,6 +320,8 @@ function attachRuntimeInterceptor(detectedBackend, app, client, options) {
         exclude: options.exclude || [],
         apiPrefix: options.apiPrefix || "/",
         debug: options.debug || false,
+        scanSecret: options.scanSecret,
+        onScanRequested: options.onScanRequested,
       });
       break;
 
@@ -231,6 +330,8 @@ function attachRuntimeInterceptor(detectedBackend, app, client, options) {
         exclude: options.exclude || [],
         apiPrefix: options.apiPrefix || "/api",
         debug: options.debug || false,
+        scanSecret: options.scanSecret,
+        onScanRequested: options.onScanRequested,
       });
       break;
 
@@ -239,6 +340,8 @@ function attachRuntimeInterceptor(detectedBackend, app, client, options) {
         exclude: options.exclude || [],
         apiPrefix: options.apiPrefix || "/",
         debug: options.debug || false,
+        scanSecret: options.scanSecret,
+        onScanRequested: options.onScanRequested,
       });
       break;
 
@@ -247,6 +350,8 @@ function attachRuntimeInterceptor(detectedBackend, app, client, options) {
         exclude: options.exclude || [],
         apiPrefix: options.apiPrefix || "/",
         debug: options.debug || false,
+        scanSecret: options.scanSecret,
+        onScanRequested: options.onScanRequested,
       });
       break;
 
@@ -256,6 +361,8 @@ function attachRuntimeInterceptor(detectedBackend, app, client, options) {
         exclude: options.exclude || [],
         apiPrefix: options.apiPrefix || "/",
         debug: options.debug || false,
+        scanSecret: options.scanSecret,
+        onScanRequested: options.onScanRequested,
       });
       break;
   }
@@ -289,7 +396,22 @@ var BotVersion = {
       this._initialized = true;
       const savedOptions = global._botVersionOptions || {};
       const savedFramework = global._botVersionFramework || "nextjs";
-      attachRuntimeInterceptor(savedFramework, app, this._client, savedOptions);
+      const savedFrontend = global._botVersionFrontendFramework || "unknown";
+      const savedProjectType = classifyInstallation(
+        savedFramework,
+        savedFrontend,
+      );
+      if (
+        savedProjectType !== "frontend-only" &&
+        savedProjectType !== "unknown"
+      ) {
+        attachRuntimeInterceptor(
+          savedFramework,
+          app,
+          this._client,
+          savedOptions,
+        );
+      }
       return;
     }
 
@@ -299,7 +421,7 @@ var BotVersion = {
 
     this._client = new BotVersionClient({
       apiKey: options.apiKey,
-      platformUrl: options.platformUrl || "https://botversion.com",
+      platformUrl: options.platformUrl || "https://console.botversion.com",
       debug: options.debug || false,
       timeout: options.timeout || 30000,
     });
@@ -319,33 +441,36 @@ var BotVersion = {
     var detectedFrontend = options.frontendFramework || detected.frontend;
 
     global._botVersionFramework = detectedBackend;
+    global._botVersionFrontendFramework = detectedFrontend;
+
+    var projectType = classifyInstallation(detectedBackend, detectedFrontend);
 
     if (debug) {
-      // Detected: detectedBackend, detectedFrontend
+      // Detected: detectedBackend, detectedFrontend, projectType
     }
 
-    // ── Attach runtime interceptor ───────────────────────────────────────────
-    attachRuntimeInterceptor(detectedBackend, app, self._client, options);
-
-    // ── Static scan ──────────────────────────────────────────────────────────
-    setTimeout(function () {
-      // Run backend scanner
-      var endpoints = runBackendScanner(detectedBackend, app, options, cwd);
-
-      // Send endpoints to platform
-      if (endpoints.length > 0) {
-        self._client.registerEndpoints(endpoints);
-      }
-
-      // Run frontend route scanner
-      var routePatterns = scanner.scanFrontendRoutes(cwd);
+    // ── Wire up the on-demand scan trigger ───────────────────────────────────
+    // Instead of scanning automatically on restart, the interceptor now
+    // listens for a special request from the BotVersion dashboard and runs
+    // the scan only when the user clicks "Scan" there.
+    options.scanSecret = options.apiKey;
+    options.onScanRequested = function () {
+      return runFullScan(
+        detectedBackend,
+        detectedFrontend,
+        app,
+        options,
+        cwd,
+        self._client,
+      );
+    };
 
-      if (routePatterns.length > 0) {
-        self._client.registerRoutePatterns(routePatterns).catch(function () {
-          // silently ignore — non-critical
-        });
-      }
-    }, 3000);
+    // ── Attach runtime interceptor ───────────────────────────────────────────
+    // Skip for frontend-only or unknown projects — there's no backend
+    // server on this process worth intercepting live traffic on.
+    if (projectType !== "frontend-only" && projectType !== "unknown") {
+      attachRuntimeInterceptor(detectedBackend, app, self._client, options);
+    }
   },
 
   getEndpoints: function () {
@@ -377,3 +502,6 @@ module.exports.default = BotVersion;
 module.exports.init = BotVersion.init;
 module.exports.getEndpoints = BotVersion.getEndpoints;
 module.exports.registerEndpoint = BotVersion.registerEndpoint;
+module.exports.detectFrameworks = detectFrameworks;
+module.exports.classifyInstallation = classifyInstallation;
+module.exports.runBackendScanner = runBackendScanner;