featurely-site-manager 1.1.14 → 1.1.17

package/README.md

@@ -23,6 +23,25 @@ siteManager.init();
 
 ## ✨ Features
 
+### 🐛 Debug Overlay
+
+- Floating debug panel injected into your site when debug mode is enabled
+- **SDK tab** — live state: environment, maintenance status, active messages, feature flags
+- **Logs tab** — real-time log stream with level-coloured rows (info / warn / error), error count badge, Clear button
+- **Network tab** — config fetch history with status codes and timestamps
+- **Events tab** — all analytics events queued or sent
+- **Test tab** — send test analytics events, check feature flags by key, trigger test errors/bugs, flush the analytics queue, refresh config
+- Intercepts `console.error` and `console.warn` — captured errors appear in the Logs tab
+- Global `window.onerror` and `unhandledrejection` listeners capture uncaught errors
+- Verbose lifecycle logging: init steps, config delta on each poll, analytics flush counts, flag lookups, maintenance state changes
+
+### 🌍 Environments
+
+- Per-environment config (maintenance, debug, messages) matched by URL
+- SDK auto-detects the current environment from `window.location.hostname`
+- Configure environment URLs in your Featurely dashboard → Environments
+- Enable/disable debug mode globally or per-environment
+
 ### 🔧 Maintenance Mode
 
 - **Default** or **custom** maintenance pages
@@ -245,6 +264,58 @@ When `enableAnalytics` is `true` (default), the SDK automatically tracks:
 
 Page tracking is SPA-compatible — it patches `history.pushState` and `history.replaceState` and listens to `popstate` so navigations in React, Next.js, Vue, and similar frameworks are captured automatically.
 
+### Debug Overlay
+
+Enable the debug overlay from your Featurely dashboard (Maintenance → Debug Overlay) or pass `debugMode: true` directly. When active, a `[FT]` button appears in the bottom-right corner of your site.
+
+```typescript
+const manager = new SiteManager({
+  apiKey: "ft_live_your_api_key",
+  projectId: "proj_your_project_id",
+  // debugMode is read from the server config — no client code needed.
+  // You can also force it on locally:
+  // debugMode: true,
+});
+
+manager.init();
+```
+
+The overlay panel has five tabs:
+
+| Tab | Contents |
+| --- | --- |
+| **SDK** | Environment, maintenance status, active messages, feature flag count |
+| **Logs** | Real-time log stream (info / warn / error); error badge on tab; Clear button |
+| **Network** | Config fetch log with status codes and timestamps |
+| **Events** | Analytics events queued/sent |
+| **Test** | Buttons to test analytics, errors, bugs, feature flags, flush, and refresh |
+
+#### Test Tab Actions
+
+- **Send test event** — fires a `test_event` analytics event
+- **Flush queue** — immediately sends all queued analytics events
+- **Check flag** — enter a flag key to see its current enabled state
+- **Trigger test error** — throws a JS error captured in the Logs tab
+- **Trigger test bug** — fires a `test_bug_report` analytics event
+- **Refresh config** — manually polls the Featurely API
+
+### Environment-Aware Setup
+
+When you have multiple environments (production, staging, localhost) configured in your Featurely dashboard, the SDK automatically detects the current environment from `window.location.hostname` — no manual configuration needed.
+
+```typescript
+const manager = new SiteManager({
+  apiKey: "ft_live_your_api_key",
+  projectId: "proj_your_project_id",
+  // Environment is auto-detected from window.location.hostname
+  // matching the URL patterns set in your Featurely dashboard.
+});
+
+manager.init();
+```
+
+Configure environment URLs in your Featurely dashboard → **Environments**. The SDK matches the current `hostname` against each environment's configured URL. The matching environment's settings (maintenance, debug, messages) take effect.
+
 ### Custom Poll Interval
 
 ```typescript
@@ -283,6 +354,7 @@ manager.init();
 | `onUpdateAvailable`      | `function`      | ❌       | -                         | Callback when update is available         |
 | `onUpdateRequired`       | `function`      | ❌       | -                         | Callback when update is required (forced) |
 | `onError`                | `function`      | ❌       | -                         | Error callback                            |
+| `debugMode`              | `boolean`       | ❌       | `false`                   | Force-enable debug overlay locally        |
 
 ## 🎯 API Methods
 

package/dist/index.d.mts

@@ -91,7 +91,6 @@ interface SiteManagerConfig {
     onUpdateRequired?: (versionInfo: VersionCheckResponse) => void;
     onError?: (error: Error) => void;
     debugMode?: boolean;
-    environment?: string;
 }
 declare class SiteManager {
     private config;

package/dist/index.d.ts

@@ -91,7 +91,6 @@ interface SiteManagerConfig {
     onUpdateRequired?: (versionInfo: VersionCheckResponse) => void;
     onError?: (error: Error) => void;
     debugMode?: boolean;
-    environment?: string;
 }
 declare class SiteManager {
     private config;

package/dist/index.js

@@ -98,8 +98,7 @@ var _SiteManager = class _SiteManager {
       // 1 hour
       onUpdateAvailable: config.onUpdateAvailable,
       onUpdateRequired: config.onUpdateRequired,
-      debugMode: (_f = config.debugMode) != null ? _f : false,
-      environment: config.environment
+      debugMode: (_f = config.debugMode) != null ? _f : false
     };
     this.loadDismissedMessages();
   }
@@ -107,7 +106,6 @@ var _SiteManager = class _SiteManager {
    * Initialize and start the site manager
    */
   async init() {
-    var _a;
     if (typeof window === "undefined" || typeof document === "undefined") {
       console.warn(
         "Featurely Site Manager: Can only be initialized in a browser environment"
@@ -117,7 +115,7 @@ var _SiteManager = class _SiteManager {
     if (this.config.debugMode) {
       this.setupDebugOverlay();
     }
-    this.debugLog("info", `[init] v1.1.14 | project: ${this.config.projectId} | env: ${(_a = this.config.environment) != null ? _a : "\u2014"}`);
+    this.debugLog("info", `[init] v1.1.16 | project: ${this.config.projectId} | hostname: ${typeof window !== "undefined" ? window.location.hostname : "\u2014"}`);
     this.debugLog("info", `[init] analytics: ${this.config.enableAnalytics ? "on" : "off"} | poll: ${this.config.pollInterval}ms | debug: ${this.config.debugMode ? "on" : "off"}`);
     if (this.config.enableAnalytics) {
       this.debugLog("info", "[init] starting analytics + page tracking");
@@ -366,10 +364,12 @@ var _SiteManager = class _SiteManager {
         if (newConfig.debugMode === true && !this.debugOverlayEl) {
           this.setupDebugOverlay();
         }
-        if (!this.debugOverlayEl && this.config.environment) {
+        if (!this.debugOverlayEl) {
+          const hostname = typeof window !== "undefined" ? window.location.hostname : "";
           const envs = newConfig.environments;
-          const env = envs == null ? void 0 : envs.find((e) => e.slug === this.config.environment || e.name === this.config.environment);
-          if ((env == null ? void 0 : env.debugEnabled) === true) {
+          const matchedEnv = hostname ? envs == null ? void 0 : envs.find((e) => typeof e.url === "string" && e.url !== "" && e.url === hostname) : void 0;
+          if ((matchedEnv == null ? void 0 : matchedEnv.debugEnabled) === true) {
+            this.debugLog("info", `[env] matched environment "${matchedEnv.name}" (${hostname})`);
             this.setupDebugOverlay();
           }
         }
@@ -629,9 +629,9 @@ var _SiteManager = class _SiteManager {
         const flagCount = (_c = (_b = sc == null ? void 0 : sc.featureFlags) == null ? void 0 : _b.length) != null ? _c : 0;
         const msgCount = (_e = (_d = sc == null ? void 0 : sc.messages) == null ? void 0 : _d.length) != null ? _e : 0;
         content = `
-          ${row("SDK Version", "1.1.14")}
+          ${row("SDK Version", "1.1.16")}
           ${row("Project", cfg.projectId)}
-          ${row("Environment", cfg.environment || "\u2014")}
+          ${row("Hostname", typeof window !== "undefined" ? window.location.hostname : "\u2014")}
           ${row("API URL", cfg.apiUrl)}
           ${row("Maintenance", maintenance)}
           ${row("Feature Flags", `${flagCount} active`)}
@@ -656,8 +656,9 @@ var _SiteManager = class _SiteManager {
         const logs = this.debugLogs.slice(0, 50);
         const errorsInLog = logs.filter((l) => l.level === "error").length;
         const clearBtn = `<button data-action="clear-logs" style="background:rgba(255,255,255,0.08);border:none;color:${MUTED};cursor:pointer;font-size:9px;font-family:inherit;padding:2px 7px;border-radius:3px">Clear</button>`;
+        const copyBtn = `<button data-action="copy-logs" style="background:rgba(255,255,255,0.08);border:none;color:${MUTED};cursor:pointer;font-size:9px;font-family:inherit;padding:2px 7px;border-radius:3px">Copy</button>`;
         const errBadge = errorsInLog > 0 ? `<span style="font-size:9px;color:${RED}">${errorsInLog} error${errorsInLog > 1 ? "s" : ""}</span>` : "";
-        const logHeader = `<div style="display:flex;align-items:center;justify-content:space-between;margin-bottom:4px">${errBadge || `<span></span>`}${clearBtn}</div>`;
+        const logHeader = `<div style="display:flex;align-items:center;justify-content:space-between;margin-bottom:4px">${errBadge || `<span></span>`}<div style="display:flex;gap:4px">${copyBtn}${clearBtn}</div></div>`;
         if (logs.length === 0) {
           content = logHeader + `<div style="color:${MUTED};padding:12px;text-align:center">No logs yet</div>`;
         } else {
@@ -817,6 +818,15 @@ var _SiteManager = class _SiteManager {
         await this.fetchConfig();
         feedback("Config refreshed", true);
         break;
+      case "copy-logs": {
+        const text = this.debugLogs.slice().reverse().map((l) => `[${l.ts}] [${l.level.toUpperCase()}] ${l.msg}`).join("\n");
+        void navigator.clipboard.writeText(text).then(() => {
+          feedback(`Copied ${this.debugLogs.length} log line${this.debugLogs.length !== 1 ? "s" : ""}`, true);
+        }).catch(() => {
+          feedback("Copy failed \u2014 clipboard not available", false);
+        });
+        break;
+      }
       case "clear-logs":
         this.debugLogs = [];
         this.testFeedback = [];

package/dist/index.mjs

@@ -63,8 +63,7 @@ var _SiteManager = class _SiteManager {
       // 1 hour
       onUpdateAvailable: config.onUpdateAvailable,
       onUpdateRequired: config.onUpdateRequired,
-      debugMode: (_f = config.debugMode) != null ? _f : false,
-      environment: config.environment
+      debugMode: (_f = config.debugMode) != null ? _f : false
     };
     this.loadDismissedMessages();
   }
@@ -72,7 +71,6 @@ var _SiteManager = class _SiteManager {
    * Initialize and start the site manager
    */
   async init() {
-    var _a;
     if (typeof window === "undefined" || typeof document === "undefined") {
       console.warn(
         "Featurely Site Manager: Can only be initialized in a browser environment"
@@ -82,7 +80,7 @@ var _SiteManager = class _SiteManager {
     if (this.config.debugMode) {
       this.setupDebugOverlay();
     }
-    this.debugLog("info", `[init] v1.1.14 | project: ${this.config.projectId} | env: ${(_a = this.config.environment) != null ? _a : "\u2014"}`);
+    this.debugLog("info", `[init] v1.1.16 | project: ${this.config.projectId} | hostname: ${typeof window !== "undefined" ? window.location.hostname : "\u2014"}`);
     this.debugLog("info", `[init] analytics: ${this.config.enableAnalytics ? "on" : "off"} | poll: ${this.config.pollInterval}ms | debug: ${this.config.debugMode ? "on" : "off"}`);
     if (this.config.enableAnalytics) {
       this.debugLog("info", "[init] starting analytics + page tracking");
@@ -331,10 +329,12 @@ var _SiteManager = class _SiteManager {
         if (newConfig.debugMode === true && !this.debugOverlayEl) {
           this.setupDebugOverlay();
         }
-        if (!this.debugOverlayEl && this.config.environment) {
+        if (!this.debugOverlayEl) {
+          const hostname = typeof window !== "undefined" ? window.location.hostname : "";
           const envs = newConfig.environments;
-          const env = envs == null ? void 0 : envs.find((e) => e.slug === this.config.environment || e.name === this.config.environment);
-          if ((env == null ? void 0 : env.debugEnabled) === true) {
+          const matchedEnv = hostname ? envs == null ? void 0 : envs.find((e) => typeof e.url === "string" && e.url !== "" && e.url === hostname) : void 0;
+          if ((matchedEnv == null ? void 0 : matchedEnv.debugEnabled) === true) {
+            this.debugLog("info", `[env] matched environment "${matchedEnv.name}" (${hostname})`);
             this.setupDebugOverlay();
           }
         }
@@ -594,9 +594,9 @@ var _SiteManager = class _SiteManager {
         const flagCount = (_c = (_b = sc == null ? void 0 : sc.featureFlags) == null ? void 0 : _b.length) != null ? _c : 0;
         const msgCount = (_e = (_d = sc == null ? void 0 : sc.messages) == null ? void 0 : _d.length) != null ? _e : 0;
         content = `
-          ${row("SDK Version", "1.1.14")}
+          ${row("SDK Version", "1.1.16")}
           ${row("Project", cfg.projectId)}
-          ${row("Environment", cfg.environment || "\u2014")}
+          ${row("Hostname", typeof window !== "undefined" ? window.location.hostname : "\u2014")}
           ${row("API URL", cfg.apiUrl)}
           ${row("Maintenance", maintenance)}
           ${row("Feature Flags", `${flagCount} active`)}
@@ -621,8 +621,9 @@ var _SiteManager = class _SiteManager {
         const logs = this.debugLogs.slice(0, 50);
         const errorsInLog = logs.filter((l) => l.level === "error").length;
         const clearBtn = `<button data-action="clear-logs" style="background:rgba(255,255,255,0.08);border:none;color:${MUTED};cursor:pointer;font-size:9px;font-family:inherit;padding:2px 7px;border-radius:3px">Clear</button>`;
+        const copyBtn = `<button data-action="copy-logs" style="background:rgba(255,255,255,0.08);border:none;color:${MUTED};cursor:pointer;font-size:9px;font-family:inherit;padding:2px 7px;border-radius:3px">Copy</button>`;
         const errBadge = errorsInLog > 0 ? `<span style="font-size:9px;color:${RED}">${errorsInLog} error${errorsInLog > 1 ? "s" : ""}</span>` : "";
-        const logHeader = `<div style="display:flex;align-items:center;justify-content:space-between;margin-bottom:4px">${errBadge || `<span></span>`}${clearBtn}</div>`;
+        const logHeader = `<div style="display:flex;align-items:center;justify-content:space-between;margin-bottom:4px">${errBadge || `<span></span>`}<div style="display:flex;gap:4px">${copyBtn}${clearBtn}</div></div>`;
         if (logs.length === 0) {
           content = logHeader + `<div style="color:${MUTED};padding:12px;text-align:center">No logs yet</div>`;
         } else {
@@ -782,6 +783,15 @@ var _SiteManager = class _SiteManager {
         await this.fetchConfig();
         feedback("Config refreshed", true);
         break;
+      case "copy-logs": {
+        const text = this.debugLogs.slice().reverse().map((l) => `[${l.ts}] [${l.level.toUpperCase()}] ${l.msg}`).join("\n");
+        void navigator.clipboard.writeText(text).then(() => {
+          feedback(`Copied ${this.debugLogs.length} log line${this.debugLogs.length !== 1 ? "s" : ""}`, true);
+        }).catch(() => {
+          feedback("Copy failed \u2014 clipboard not available", false);
+        });
+        break;
+      }
       case "clear-logs":
         this.debugLogs = [];
         this.testFeedback = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "featurely-site-manager",
-  "version": "1.1.14",
+  "version": "1.1.17",
   "description": "Complete site management SDK for maintenance mode, status messages, feature flags, version checking, and analytics",
   "main": "dist/index.js",
   "module": "dist/index.mjs",