featurely-site-manager 1.1.11 → 1.1.15

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

@@ -90,6 +90,8 @@ interface SiteManagerConfig {
     onUpdateAvailable?: (versionInfo: VersionCheckResponse) => void;
     onUpdateRequired?: (versionInfo: VersionCheckResponse) => void;
     onError?: (error: Error) => void;
+    debugMode?: boolean;
+    environment?: string;
 }
 declare class SiteManager {
     private config;
@@ -109,6 +111,20 @@ declare class SiteManager {
     private pageEntryTime;
     private static readonly MAX_CONSECUTIVE_FAILURES;
     private lastVersionCheck;
+    private debugOverlayEl;
+    private debugRefreshId;
+    private debugLogs;
+    private networkLog;
+    private analyticsEventsSent;
+    private debugMinimized;
+    private debugTab;
+    private recentAnalyticsEvents;
+    private testFlagKey;
+    private testFeedback;
+    private errorCount;
+    private consoleIntercepted;
+    private originalConsoleError;
+    private originalConsoleWarn;
     constructor(config: SiteManagerConfig);
     init(): Promise<void>;
     destroy(): void;
@@ -127,6 +143,13 @@ declare class SiteManager {
     private startAnalyticsFlushing;
     private stopAnalyticsFlushing;
     private flushAnalytics;
+    private debugLog;
+    private debugNetwork;
+    private stopDebugOverlay;
+    private setupGlobalErrorCapture;
+    private setupDebugOverlay;
+    private renderDebugOverlay;
+    private handleTestAction;
     private setupPageTracking;
     private trackPageView;
     private trackPageExit;

package/dist/index.d.ts

@@ -90,6 +90,8 @@ interface SiteManagerConfig {
     onUpdateAvailable?: (versionInfo: VersionCheckResponse) => void;
     onUpdateRequired?: (versionInfo: VersionCheckResponse) => void;
     onError?: (error: Error) => void;
+    debugMode?: boolean;
+    environment?: string;
 }
 declare class SiteManager {
     private config;
@@ -109,6 +111,20 @@ declare class SiteManager {
     private pageEntryTime;
     private static readonly MAX_CONSECUTIVE_FAILURES;
     private lastVersionCheck;
+    private debugOverlayEl;
+    private debugRefreshId;
+    private debugLogs;
+    private networkLog;
+    private analyticsEventsSent;
+    private debugMinimized;
+    private debugTab;
+    private recentAnalyticsEvents;
+    private testFlagKey;
+    private testFeedback;
+    private errorCount;
+    private consoleIntercepted;
+    private originalConsoleError;
+    private originalConsoleWarn;
     constructor(config: SiteManagerConfig);
     init(): Promise<void>;
     destroy(): void;
@@ -127,6 +143,13 @@ declare class SiteManager {
     private startAnalyticsFlushing;
     private stopAnalyticsFlushing;
     private flushAnalytics;
+    private debugLog;
+    private debugNetwork;
+    private stopDebugOverlay;
+    private setupGlobalErrorCapture;
+    private setupDebugOverlay;
+    private renderDebugOverlay;
+    private handleTestAction;
     private setupPageTracking;
     private trackPageView;
     private trackPageExit;