featurely-site-manager 1.1.27 → 1.1.29

package/README.md

@@ -1,6 +1,6 @@
 # featurely-site-manager
 
-Powerful site management SDK for controlling maintenance mode, displaying status messages, and managing site-wide features from your Featurely dashboard.
+Powerful site management SDK for controlling maintenance mode, displaying status messages, managing site-wide features, and scanning your project's dependencies for vulnerabilities — all from your Featurely dashboard.
 
 ## 📦 Installation
 
@@ -8,7 +8,63 @@ Powerful site management SDK for controlling maintenance mode, displaying status
 npm install featurely-site-manager
 ```
 
-## 🚀 Quick Start
+## 🔍 Package Security Scanning (CLI)
+
+Scan your project's dependencies for outdated versions, known CVEs, and breaking changes. Results appear instantly in your Featurely dashboard under **Package security**.
+
+### Run a scan
+
+```bash
+npx featurely-site-manager scan packages \
+  --key YOUR_API_KEY \
+  --project YOUR_PROJECT_ID
+```
+
+Run this from the directory that contains your `package.json`. After the first scan your package list is stored — use the **Re-scan** button in the dashboard to re-check without the CLI.
+
+### What gets reported
+
+| Check                                         | Source                                       |
+| --------------------------------------------- | -------------------------------------------- |
+| Installed vs latest version                   | npm registry                                 |
+| Breaking change detection (major bump)        | semver comparison                            |
+| Known CVEs — critical / high / moderate / low | [OSV database](https://osv.dev) (GHSA + NVD) |
+| Deprecated packages                           | npm registry                                 |
+| License (SPDX)                                | npm registry                                 |
+
+### GitHub Actions — automatic scanning
+
+Add to `.github/workflows/featurely-scan.yml` and set `FEATURELY_API_KEY` + `FEATURELY_PROJECT_ID` in your repository secrets.
+
+```yaml
+name: Featurely package scan
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "package.json"
+      - "package-lock.json"
+      - "yarn.lock"
+      - "pnpm-lock.yaml"
+  workflow_dispatch:
+
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+      - name: Run Featurely package scan
+        run: |
+          npx featurely-site-manager scan packages \
+            --key ${{ secrets.FEATURELY_API_KEY }} \
+            --project ${{ secrets.FEATURELY_PROJECT_ID }}
+```
+
+## 🚀 Quick Start (SDK)
 
 ```typescript
 import { SiteManager } from "featurely-site-manager";

package/dist/index.d.mts

@@ -1,3 +1,4 @@
+declare const SDK_VERSION = "1.1.28";
 type MessageType = "info" | "warning" | "error" | "success";
 type MessagePosition = "top" | "bottom";
 type MessageStyle = "banner" | "toast";
@@ -76,11 +77,33 @@ interface VersionUpdateRules {
     minor?: "required" | "available";
     patch?: "required" | "recommended" | "available";
 }
+interface AnalyticsConfig {
+    urlWhitelist?: string[];
+    urlBlacklist?: string[];
+    userWhitelist?: string[];
+    userBlacklist?: string[];
+    sampleRate?: number;
+    trackPageViews?: boolean;
+    trackWebVitals?: boolean;
+    trackOutboundLinks?: boolean;
+    trackSessionStart?: boolean;
+    flushInterval?: number;
+}
+interface SdkVersionRequirement {
+    packageName: string;
+    displayName: string;
+    currentVersion: string;
+    minimumVersion: string;
+    updateCommand: string;
+    changelog?: string;
+}
 interface SiteConfig {
     maintenance: MaintenanceConfig;
     messages: StatusMessage[];
     featureFlags: FeatureFlag[];
     lastUpdated: string;
+    analyticsConfig?: AnalyticsConfig | null;
+    sdkVersions?: SdkVersionRequirement[];
 }
 interface SiteManagerConfig {
     apiKey: string;
@@ -117,6 +140,9 @@ declare class SiteManager {
     private config;
     private siteConfig;
     private configETag;
+    private analyticsConfig;
+    private _sessionSampled;
+    private _sdkUpdateToastShown;
     private pollIntervalId;
     private versionCheckIntervalId;
     private messageContainers;
@@ -166,6 +192,9 @@ declare class SiteManager {
     isInMaintenanceMode(): boolean;
     getActiveMessages(): StatusMessage[];
     refresh(): Promise<void>;
+    private matchesPattern;
+    private matchesAnyPattern;
+    private isSessionSampled;
     trackEvent(eventName: string, properties?: Record<string, string | number | boolean>): void;
     track404(path?: string): void;
     private fetchConfig;
@@ -190,6 +219,8 @@ declare class SiteManager {
     private trackPageExit;
     private onNavigate;
     private generateSessionId;
+    private compareVersions;
+    private showSdkUpdateToast;
     checkVersion(currentVersion?: string): Promise<VersionCheckResponse | null>;
     forceUpdateWeb(): Promise<void>;
     getLastVersionCheck(): VersionCheckResponse | null;
@@ -221,4 +252,4 @@ declare class SiteManager {
     private injectStyles;
 }
 
-export { type AppVersion, type FeatureFlag, type MaintenanceConfig, type MessagePosition, type MessageStyle, type MessageType, type SiteConfig, SiteManager, type SiteManagerConfig, type StatusMessage, type VersionCheckResponse, type VersionUpdateRules, SiteManager as default };
+export { type AnalyticsConfig, type AppVersion, type FeatureFlag, type MaintenanceConfig, type MessagePosition, type MessageStyle, type MessageType, SDK_VERSION, type SdkVersionRequirement, type SiteConfig, SiteManager, type SiteManagerConfig, type StatusMessage, type VersionCheckResponse, type VersionUpdateRules, SiteManager as default };

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+declare const SDK_VERSION = "1.1.28";
 type MessageType = "info" | "warning" | "error" | "success";
 type MessagePosition = "top" | "bottom";
 type MessageStyle = "banner" | "toast";
@@ -76,11 +77,33 @@ interface VersionUpdateRules {
     minor?: "required" | "available";
     patch?: "required" | "recommended" | "available";
 }
+interface AnalyticsConfig {
+    urlWhitelist?: string[];
+    urlBlacklist?: string[];
+    userWhitelist?: string[];
+    userBlacklist?: string[];
+    sampleRate?: number;
+    trackPageViews?: boolean;
+    trackWebVitals?: boolean;
+    trackOutboundLinks?: boolean;
+    trackSessionStart?: boolean;
+    flushInterval?: number;
+}
+interface SdkVersionRequirement {
+    packageName: string;
+    displayName: string;
+    currentVersion: string;
+    minimumVersion: string;
+    updateCommand: string;
+    changelog?: string;
+}
 interface SiteConfig {
     maintenance: MaintenanceConfig;
     messages: StatusMessage[];
     featureFlags: FeatureFlag[];
     lastUpdated: string;
+    analyticsConfig?: AnalyticsConfig | null;
+    sdkVersions?: SdkVersionRequirement[];
 }
 interface SiteManagerConfig {
     apiKey: string;
@@ -117,6 +140,9 @@ declare class SiteManager {
     private config;
     private siteConfig;
     private configETag;
+    private analyticsConfig;
+    private _sessionSampled;
+    private _sdkUpdateToastShown;
     private pollIntervalId;
     private versionCheckIntervalId;
     private messageContainers;
@@ -166,6 +192,9 @@ declare class SiteManager {
     isInMaintenanceMode(): boolean;
     getActiveMessages(): StatusMessage[];
     refresh(): Promise<void>;
+    private matchesPattern;
+    private matchesAnyPattern;
+    private isSessionSampled;
     trackEvent(eventName: string, properties?: Record<string, string | number | boolean>): void;
     track404(path?: string): void;
     private fetchConfig;
@@ -190,6 +219,8 @@ declare class SiteManager {
     private trackPageExit;
     private onNavigate;
     private generateSessionId;
+    private compareVersions;
+    private showSdkUpdateToast;
     checkVersion(currentVersion?: string): Promise<VersionCheckResponse | null>;
     forceUpdateWeb(): Promise<void>;
     getLastVersionCheck(): VersionCheckResponse | null;
@@ -221,4 +252,4 @@ declare class SiteManager {
     private injectStyles;
 }
 
-export { type AppVersion, type FeatureFlag, type MaintenanceConfig, type MessagePosition, type MessageStyle, type MessageType, type SiteConfig, SiteManager, type SiteManagerConfig, type StatusMessage, type VersionCheckResponse, type VersionUpdateRules, SiteManager as default };
+export { type AnalyticsConfig, type AppVersion, type FeatureFlag, type MaintenanceConfig, type MessagePosition, type MessageStyle, type MessageType, SDK_VERSION, type SdkVersionRequirement, type SiteConfig, SiteManager, type SiteManagerConfig, type StatusMessage, type VersionCheckResponse, type VersionUpdateRules, SiteManager as default };

package/dist/index.js

@@ -30,15 +30,20 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  SDK_VERSION: () => SDK_VERSION,
   SiteManager: () => SiteManager,
   default: () => index_default
 });
 module.exports = __toCommonJS(index_exports);
 var import_dompurify = __toESM(require("dompurify"));
+var SDK_VERSION = "1.1.28";
 var _SiteManager = class _SiteManager {
   constructor(config) {
     this.siteConfig = null;
     this.configETag = null;
+    this.analyticsConfig = null;
+    this._sessionSampled = null;
+    this._sdkUpdateToastShown = false;
     this.pollIntervalId = null;
     this.versionCheckIntervalId = null;
     this.messageContainers = /* @__PURE__ */ new Map();
@@ -147,7 +152,7 @@ var _SiteManager = class _SiteManager {
     }
     this.debugLog(
       "info",
-      `[init] v1.1.19 | project: ${this.config.projectId} | hostname: ${typeof window !== "undefined" ? window.location.hostname : "\u2014"}`
+      `[init] v${SDK_VERSION} | project: ${this.config.projectId} | hostname: ${typeof window !== "undefined" ? window.location.hostname : "\u2014"}`
     );
     this.debugLog(
       "info",
@@ -409,10 +414,56 @@ var _SiteManager = class _SiteManager {
    * @param eventName - Name of the event (e.g., 'button_clicked', 'feature_used')
    * @param properties - Optional event properties (e.g., { button: 'signup', page: '/home' })
    */
+  /** Returns true if `path` matches the given glob pattern (supports * wildcard). */
+  matchesPattern(path, pattern) {
+    if (!pattern) return false;
+    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+    try {
+      return new RegExp(`^${escaped}$`).test(path);
+    } catch {
+      return path === pattern;
+    }
+  }
+  /** Returns true if `path` matches any of the given glob patterns. */
+  matchesAnyPattern(path, patterns) {
+    return patterns.some((p) => this.matchesPattern(path, p));
+  }
+  /** Returns true if the current session should be tracked (respects sample rate). */
+  isSessionSampled() {
+    var _a, _b;
+    if (this._sessionSampled !== null) return this._sessionSampled;
+    const rate = (_b = (_a = this.analyticsConfig) == null ? void 0 : _a.sampleRate) != null ? _b : 100;
+    this._sessionSampled = rate >= 100 || Math.random() * 100 < rate;
+    return this._sessionSampled;
+  }
   trackEvent(eventName, properties) {
+    var _a, _b, _c, _d;
     if (!this.config.enableAnalytics) {
       return;
     }
+    const ac = this.analyticsConfig;
+    if (ac) {
+      if (!this.isSessionSampled()) return;
+      if (eventName === "session_start" && ac.trackSessionStart === false) return;
+      if ((eventName === "page_view" || eventName === "page_exit") && ac.trackPageViews === false) return;
+      if (eventName === "web_vital" && ac.trackWebVitals === false) return;
+      if (eventName === "outbound_link_click" && ac.trackOutboundLinks === false) return;
+      const urlEvents = ["page_view", "page_exit", "page_not_found"];
+      if (urlEvents.includes(eventName)) {
+        const path = (properties == null ? void 0 : properties.path) || (typeof window !== "undefined" ? window.location.pathname : "");
+        if (((_a = ac.urlBlacklist) == null ? void 0 : _a.length) && this.matchesAnyPattern(path, ac.urlBlacklist)) return;
+        if (((_b = ac.urlWhitelist) == null ? void 0 : _b.length) && !this.matchesAnyPattern(path, ac.urlWhitelist)) return;
+      }
+      const userId = this.config.userId || "";
+      const userEmail = this.config.userEmail || "";
+      if ((_c = ac.userBlacklist) == null ? void 0 : _c.length) {
+        if (userId && ac.userBlacklist.includes(userId) || userEmail && ac.userBlacklist.includes(userEmail)) return;
+      }
+      if ((_d = ac.userWhitelist) == null ? void 0 : _d.length) {
+        const inWhitelist = userId && ac.userWhitelist.includes(userId) || userEmail && ac.userWhitelist.includes(userEmail);
+        if (!inWhitelist) return;
+      }
+    }
     this.analyticsQueue.push({
       eventName,
       properties,
@@ -443,7 +494,7 @@ var _SiteManager = class _SiteManager {
   // Configuration Fetching
   // ============================================================================
   async fetchConfig() {
-    var _a, _b, _c, _d, _e, _f, _g, _h;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k;
     try {
       const fetchStartMs = Date.now();
       const headers = {
@@ -527,6 +578,27 @@ var _SiteManager = class _SiteManager {
           }
         }
         this.siteConfig = newConfig;
+        if (newConfig.analyticsConfig !== void 0) {
+          this.analyticsConfig = (_i = newConfig.analyticsConfig) != null ? _i : null;
+          const serverFlushInterval = (_j = this.analyticsConfig) == null ? void 0 : _j.flushInterval;
+          if (serverFlushInterval && serverFlushInterval !== this.config.analyticsFlushInterval) {
+            this.config.analyticsFlushInterval = serverFlushInterval;
+            if (this.analyticsFlushIntervalId) {
+              clearInterval(this.analyticsFlushIntervalId);
+              this.analyticsFlushIntervalId = null;
+            }
+            this.startAnalyticsFlushing();
+            this.debugLog("info", `[analytics] flush interval updated to ${serverFlushInterval}ms from server config`);
+          }
+        }
+        if (!this._sdkUpdateToastShown && ((_k = newConfig.sdkVersions) == null ? void 0 : _k.length)) {
+          const req = newConfig.sdkVersions.find((s) => s.packageName === "featurely-site-manager");
+          if (req && req.minimumVersion && this.compareVersions(SDK_VERSION, req.minimumVersion) < 0) {
+            this._sdkUpdateToastShown = true;
+            this.showSdkUpdateToast(SDK_VERSION, req.minimumVersion, req.currentVersion, req.updateCommand, req.changelog);
+            this.debugLog("warn", `[sdk] version ${SDK_VERSION} is below minimum ${req.minimumVersion} \u2014 update toast shown`);
+          }
+        }
         const isGlobalDebug = newConfig.debugMode === true;
         const isEnvDebug = (matchedEnv == null ? void 0 : matchedEnv.debugEnabled) === true;
         const shouldDebug = isGlobalDebug || isEnvDebug;
@@ -649,7 +721,6 @@ var _SiteManager = class _SiteManager {
     if (this.analyticsQueue.length === 0) {
       return;
     }
-    const url = `${this.config.apiUrl}/api/projects/${this.config.projectId}/analytics/events`;
     const eventsToSend = [...this.analyticsQueue];
     this.analyticsQueue = [];
     this.analyticsEventsSent += eventsToSend.length;
@@ -657,61 +728,62 @@ var _SiteManager = class _SiteManager {
       "info",
       `[analytics] flushing ${eventsToSend.length} event(s) (total sent: ${this.analyticsEventsSent})`
     );
-    for (const event of eventsToSend) {
-      const payload = JSON.stringify({
+    const isBatch = eventsToSend.length > 1;
+    const url = isBatch ? `${this.config.apiUrl}/api/projects/${this.config.projectId}/analytics/events/batch` : `${this.config.apiUrl}/api/projects/${this.config.projectId}/analytics/events`;
+    const commonFields = {
+      userId: this.config.userId,
+      sessionId: this.sessionId,
+      visitorId: this.visitorId || void 0,
+      userAgent: typeof navigator !== "undefined" ? navigator.userAgent : void 0,
+      platform: typeof navigator !== "undefined" ? navigator.platform : void 0,
+      appVersion: this.config.appVersion
+    };
+    const payload = isBatch ? JSON.stringify({
+      events: eventsToSend.map((event) => ({
         eventName: event.eventName,
         properties: event.properties,
-        userId: this.config.userId,
-        sessionId: this.sessionId,
-        visitorId: this.visitorId || void 0,
-        userAgent: typeof navigator !== "undefined" ? navigator.userAgent : void 0,
-        platform: typeof navigator !== "undefined" ? navigator.platform : void 0,
-        appVersion: this.config.appVersion
-      });
-      if (useBeacon) {
-        if (typeof navigator !== "undefined" && typeof navigator.sendBeacon === "function") {
-          navigator.sendBeacon(url, payload);
+        timestamp: event.timestamp,
+        ...commonFields
+      }))
+    }) : JSON.stringify({
+      eventName: eventsToSend[0].eventName,
+      properties: eventsToSend[0].properties,
+      ...commonFields
+    });
+    const shortPath = isBatch ? `/api/projects/${this.config.projectId}/analytics/events/batch` : `/api/projects/${this.config.projectId}/analytics/events`;
+    if (useBeacon) {
+      if (typeof navigator !== "undefined" && typeof navigator.sendBeacon === "function") {
+        navigator.sendBeacon(url, payload);
+      }
+    } else {
+      try {
+        const t0 = Date.now();
+        const res = await fetch(url, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: payload,
+          keepalive: true
+        });
+        this.debugNetwork(shortPath, res.status, Date.now() - t0);
+        if (!res.ok) {
+          const body = await res.text().catch(() => "(unreadable)");
+          const errDetail = `[analytics] batch rejected: ${res.status} ${res.statusText} \u2014 ${body}`;
+          console.error(`[Featurely] ${errDetail}`);
+          this.debugLog("error", errDetail);
+          this.errorCount++;
         }
-      } else {
-        try {
-          const t0 = Date.now();
-          const res = await fetch(url, {
-            method: "POST",
-            headers: { "Content-Type": "application/json" },
-            body: payload,
-            keepalive: true
-          });
-          this.debugNetwork(
-            `/api/projects/${this.config.projectId}/analytics/events`,
-            res.status,
-            Date.now() - t0
+      } catch (fetchError) {
+        const sentViaBeacon = typeof navigator !== "undefined" && typeof navigator.sendBeacon === "function" && navigator.sendBeacon(url, payload);
+        const errMsg = fetchError instanceof Error ? fetchError.message : String(fetchError);
+        if (!sentViaBeacon) {
+          console.error(`[Featurely] Failed to send analytics batch:`, fetchError);
+          this.debugLog("error", `[analytics] batch send failed: ${errMsg}`);
+          this.errorCount++;
+        } else {
+          this.debugLog(
+            "warn",
+            `[analytics] fetch failed (${errMsg}), delivered via sendBeacon`
           );
-          if (!res.ok) {
-            const body = await res.text().catch(() => "(unreadable)");
-            const errDetail = `[analytics] event "${event.eventName}" rejected: ${res.status} ${res.statusText} \u2014 ${body}`;
-            console.error(`[Featurely] ${errDetail}`);
-            this.debugLog("error", errDetail);
-            this.errorCount++;
-          }
-        } catch (fetchError) {
-          const sentViaBeacon = typeof navigator !== "undefined" && typeof navigator.sendBeacon === "function" && navigator.sendBeacon(url, payload);
-          const errMsg = fetchError instanceof Error ? fetchError.message : String(fetchError);
-          if (!sentViaBeacon) {
-            console.error(
-              `[Featurely] Failed to send analytics event "${event.eventName}":`,
-              fetchError
-            );
-            this.debugLog(
-              "error",
-              `[analytics] send failed for "${event.eventName}": ${errMsg}`
-            );
-            this.errorCount++;
-          } else {
-            this.debugLog(
-              "warn",
-              `[analytics] fetch failed for "${event.eventName}" (${errMsg}), delivered via sendBeacon`
-            );
-          }
         }
       }
     }
@@ -1331,6 +1403,69 @@ var _SiteManager = class _SiteManager {
     }
     return `${Date.now()}-${Math.random().toString(36).substring(2, 15)}`;
   }
+  /**
+   * Compare two semver strings. Returns -1 if a < b, 0 if equal, 1 if a > b.
+   * Handles "major.minor.patch" format.
+   */
+  compareVersions(a, b) {
+    const parse = (v) => v.split(".").map((n) => parseInt(n, 10) || 0);
+    const [aMaj, aMin, aPat] = parse(a);
+    const [bMaj, bMin, bPat] = parse(b);
+    if (aMaj !== bMaj) return aMaj < bMaj ? -1 : 1;
+    if (aMin !== bMin) return aMin < bMin ? -1 : 1;
+    if (aPat !== bPat) return aPat < bPat ? -1 : 1;
+    return 0;
+  }
+  /**
+   * Show a dismissible toast notification prompting developers to update the SDK.
+   * This only appears in browser DevTools / on the page when the SDK is outdated.
+   */
+  showSdkUpdateToast(currentVersion, minimumVersion, latestVersion, updateCommand, changelog) {
+    if (typeof document === "undefined") return;
+    const existing = document.getElementById("ft-sdk-update-toast");
+    if (existing) existing.remove();
+    const toast = document.createElement("div");
+    toast.id = "ft-sdk-update-toast";
+    Object.assign(toast.style, {
+      position: "fixed",
+      bottom: "16px",
+      right: "16px",
+      zIndex: "2147483647",
+      background: "#1c1917",
+      color: "#fafaf9",
+      borderLeft: "4px solid #f59e0b",
+      borderRadius: "8px",
+      padding: "14px 16px",
+      maxWidth: "360px",
+      width: "calc(100vw - 32px)",
+      fontFamily: "-apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif",
+      fontSize: "13px",
+      boxShadow: "0 4px 32px rgba(0,0,0,0.4)",
+      lineHeight: "1.5",
+      fontWeight: "400"
+    });
+    const changelogHtml = changelog ? `<p style="margin:6px 0 0;color:#a8a29e;font-size:12px;">${changelog}</p>` : "";
+    toast.innerHTML = `
+      <button id="ft-sdk-update-close" style="position:absolute;top:10px;right:10px;background:none;border:none;cursor:pointer;color:#78716c;font-size:16px;line-height:1;padding:2px 4px;" aria-label="Dismiss">\xD7</button>
+      <p style="margin:0 20px 0 0;font-weight:600;color:#fbbf24;">\u{1F4E6} SDK update required</p>
+      <p style="margin:6px 0 0;color:#a8a29e;font-size:12px;">
+        <strong style="color:#fafaf9;">featurely-site-manager</strong>
+        v${currentVersion} is below the minimum v${minimumVersion} (latest: v${latestVersion})
+      </p>
+      ${changelogHtml}
+      <p style="margin:8px 0 0;">
+        <code style="background:#292524;border-radius:4px;padding:3px 7px;font-size:11px;color:#d6d3d1;font-family:monospace;word-break:break-all;">${updateCommand}</code>
+      </p>
+    `;
+    document.body.appendChild(toast);
+    const closeBtn = document.getElementById("ft-sdk-update-close");
+    if (closeBtn) {
+      closeBtn.addEventListener("click", () => toast.remove());
+    }
+    setTimeout(() => {
+      if (toast.parentNode) toast.remove();
+    }, 6e4);
+  }
   // ============================================================================
   // Version Checking
   // ============================================================================
@@ -2226,5 +2361,6 @@ var SiteManager = _SiteManager;
 var index_default = SiteManager;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  SDK_VERSION,
   SiteManager
 });

package/dist/index.mjs

@@ -1,9 +1,13 @@
 // src/index.ts
 import DOMPurify from "dompurify";
+var SDK_VERSION = "1.1.28";
 var _SiteManager = class _SiteManager {
   constructor(config) {
     this.siteConfig = null;
     this.configETag = null;
+    this.analyticsConfig = null;
+    this._sessionSampled = null;
+    this._sdkUpdateToastShown = false;
     this.pollIntervalId = null;
     this.versionCheckIntervalId = null;
     this.messageContainers = /* @__PURE__ */ new Map();
@@ -112,7 +116,7 @@ var _SiteManager = class _SiteManager {
     }
     this.debugLog(
       "info",
-      `[init] v1.1.19 | project: ${this.config.projectId} | hostname: ${typeof window !== "undefined" ? window.location.hostname : "\u2014"}`
+      `[init] v${SDK_VERSION} | project: ${this.config.projectId} | hostname: ${typeof window !== "undefined" ? window.location.hostname : "\u2014"}`
     );
     this.debugLog(
       "info",
@@ -374,10 +378,56 @@ var _SiteManager = class _SiteManager {
    * @param eventName - Name of the event (e.g., 'button_clicked', 'feature_used')
    * @param properties - Optional event properties (e.g., { button: 'signup', page: '/home' })
    */
+  /** Returns true if `path` matches the given glob pattern (supports * wildcard). */
+  matchesPattern(path, pattern) {
+    if (!pattern) return false;
+    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+    try {
+      return new RegExp(`^${escaped}$`).test(path);
+    } catch {
+      return path === pattern;
+    }
+  }
+  /** Returns true if `path` matches any of the given glob patterns. */
+  matchesAnyPattern(path, patterns) {
+    return patterns.some((p) => this.matchesPattern(path, p));
+  }
+  /** Returns true if the current session should be tracked (respects sample rate). */
+  isSessionSampled() {
+    var _a, _b;
+    if (this._sessionSampled !== null) return this._sessionSampled;
+    const rate = (_b = (_a = this.analyticsConfig) == null ? void 0 : _a.sampleRate) != null ? _b : 100;
+    this._sessionSampled = rate >= 100 || Math.random() * 100 < rate;
+    return this._sessionSampled;
+  }
   trackEvent(eventName, properties) {
+    var _a, _b, _c, _d;
     if (!this.config.enableAnalytics) {
       return;
     }
+    const ac = this.analyticsConfig;
+    if (ac) {
+      if (!this.isSessionSampled()) return;
+      if (eventName === "session_start" && ac.trackSessionStart === false) return;
+      if ((eventName === "page_view" || eventName === "page_exit") && ac.trackPageViews === false) return;
+      if (eventName === "web_vital" && ac.trackWebVitals === false) return;
+      if (eventName === "outbound_link_click" && ac.trackOutboundLinks === false) return;
+      const urlEvents = ["page_view", "page_exit", "page_not_found"];
+      if (urlEvents.includes(eventName)) {
+        const path = (properties == null ? void 0 : properties.path) || (typeof window !== "undefined" ? window.location.pathname : "");
+        if (((_a = ac.urlBlacklist) == null ? void 0 : _a.length) && this.matchesAnyPattern(path, ac.urlBlacklist)) return;
+        if (((_b = ac.urlWhitelist) == null ? void 0 : _b.length) && !this.matchesAnyPattern(path, ac.urlWhitelist)) return;
+      }
+      const userId = this.config.userId || "";
+      const userEmail = this.config.userEmail || "";
+      if ((_c = ac.userBlacklist) == null ? void 0 : _c.length) {
+        if (userId && ac.userBlacklist.includes(userId) || userEmail && ac.userBlacklist.includes(userEmail)) return;
+      }
+      if ((_d = ac.userWhitelist) == null ? void 0 : _d.length) {
+        const inWhitelist = userId && ac.userWhitelist.includes(userId) || userEmail && ac.userWhitelist.includes(userEmail);
+        if (!inWhitelist) return;
+      }
+    }
     this.analyticsQueue.push({
       eventName,
       properties,
@@ -408,7 +458,7 @@ var _SiteManager = class _SiteManager {
   // Configuration Fetching
   // ============================================================================
   async fetchConfig() {
-    var _a, _b, _c, _d, _e, _f, _g, _h;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k;
     try {
       const fetchStartMs = Date.now();
       const headers = {
@@ -492,6 +542,27 @@ var _SiteManager = class _SiteManager {
           }
         }
         this.siteConfig = newConfig;
+        if (newConfig.analyticsConfig !== void 0) {
+          this.analyticsConfig = (_i = newConfig.analyticsConfig) != null ? _i : null;
+          const serverFlushInterval = (_j = this.analyticsConfig) == null ? void 0 : _j.flushInterval;
+          if (serverFlushInterval && serverFlushInterval !== this.config.analyticsFlushInterval) {
+            this.config.analyticsFlushInterval = serverFlushInterval;
+            if (this.analyticsFlushIntervalId) {
+              clearInterval(this.analyticsFlushIntervalId);
+              this.analyticsFlushIntervalId = null;
+            }
+            this.startAnalyticsFlushing();
+            this.debugLog("info", `[analytics] flush interval updated to ${serverFlushInterval}ms from server config`);
+          }
+        }
+        if (!this._sdkUpdateToastShown && ((_k = newConfig.sdkVersions) == null ? void 0 : _k.length)) {
+          const req = newConfig.sdkVersions.find((s) => s.packageName === "featurely-site-manager");
+          if (req && req.minimumVersion && this.compareVersions(SDK_VERSION, req.minimumVersion) < 0) {
+            this._sdkUpdateToastShown = true;
+            this.showSdkUpdateToast(SDK_VERSION, req.minimumVersion, req.currentVersion, req.updateCommand, req.changelog);
+            this.debugLog("warn", `[sdk] version ${SDK_VERSION} is below minimum ${req.minimumVersion} \u2014 update toast shown`);
+          }
+        }
         const isGlobalDebug = newConfig.debugMode === true;
         const isEnvDebug = (matchedEnv == null ? void 0 : matchedEnv.debugEnabled) === true;
         const shouldDebug = isGlobalDebug || isEnvDebug;
@@ -614,7 +685,6 @@ var _SiteManager = class _SiteManager {
     if (this.analyticsQueue.length === 0) {
       return;
     }
-    const url = `${this.config.apiUrl}/api/projects/${this.config.projectId}/analytics/events`;
     const eventsToSend = [...this.analyticsQueue];
     this.analyticsQueue = [];
     this.analyticsEventsSent += eventsToSend.length;
@@ -622,61 +692,62 @@ var _SiteManager = class _SiteManager {
       "info",
       `[analytics] flushing ${eventsToSend.length} event(s) (total sent: ${this.analyticsEventsSent})`
     );
-    for (const event of eventsToSend) {
-      const payload = JSON.stringify({
+    const isBatch = eventsToSend.length > 1;
+    const url = isBatch ? `${this.config.apiUrl}/api/projects/${this.config.projectId}/analytics/events/batch` : `${this.config.apiUrl}/api/projects/${this.config.projectId}/analytics/events`;
+    const commonFields = {
+      userId: this.config.userId,
+      sessionId: this.sessionId,
+      visitorId: this.visitorId || void 0,
+      userAgent: typeof navigator !== "undefined" ? navigator.userAgent : void 0,
+      platform: typeof navigator !== "undefined" ? navigator.platform : void 0,
+      appVersion: this.config.appVersion
+    };
+    const payload = isBatch ? JSON.stringify({
+      events: eventsToSend.map((event) => ({
         eventName: event.eventName,
         properties: event.properties,
-        userId: this.config.userId,
-        sessionId: this.sessionId,
-        visitorId: this.visitorId || void 0,
-        userAgent: typeof navigator !== "undefined" ? navigator.userAgent : void 0,
-        platform: typeof navigator !== "undefined" ? navigator.platform : void 0,
-        appVersion: this.config.appVersion
-      });
-      if (useBeacon) {
-        if (typeof navigator !== "undefined" && typeof navigator.sendBeacon === "function") {
-          navigator.sendBeacon(url, payload);
+        timestamp: event.timestamp,
+        ...commonFields
+      }))
+    }) : JSON.stringify({
+      eventName: eventsToSend[0].eventName,
+      properties: eventsToSend[0].properties,
+      ...commonFields
+    });
+    const shortPath = isBatch ? `/api/projects/${this.config.projectId}/analytics/events/batch` : `/api/projects/${this.config.projectId}/analytics/events`;
+    if (useBeacon) {
+      if (typeof navigator !== "undefined" && typeof navigator.sendBeacon === "function") {
+        navigator.sendBeacon(url, payload);
+      }
+    } else {
+      try {
+        const t0 = Date.now();
+        const res = await fetch(url, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: payload,
+          keepalive: true
+        });
+        this.debugNetwork(shortPath, res.status, Date.now() - t0);
+        if (!res.ok) {
+          const body = await res.text().catch(() => "(unreadable)");
+          const errDetail = `[analytics] batch rejected: ${res.status} ${res.statusText} \u2014 ${body}`;
+          console.error(`[Featurely] ${errDetail}`);
+          this.debugLog("error", errDetail);
+          this.errorCount++;
         }
-      } else {
-        try {
-          const t0 = Date.now();
-          const res = await fetch(url, {
-            method: "POST",
-            headers: { "Content-Type": "application/json" },
-            body: payload,
-            keepalive: true
-          });
-          this.debugNetwork(
-            `/api/projects/${this.config.projectId}/analytics/events`,
-            res.status,
-            Date.now() - t0
+      } catch (fetchError) {
+        const sentViaBeacon = typeof navigator !== "undefined" && typeof navigator.sendBeacon === "function" && navigator.sendBeacon(url, payload);
+        const errMsg = fetchError instanceof Error ? fetchError.message : String(fetchError);
+        if (!sentViaBeacon) {
+          console.error(`[Featurely] Failed to send analytics batch:`, fetchError);
+          this.debugLog("error", `[analytics] batch send failed: ${errMsg}`);
+          this.errorCount++;
+        } else {
+          this.debugLog(
+            "warn",
+            `[analytics] fetch failed (${errMsg}), delivered via sendBeacon`
           );
-          if (!res.ok) {
-            const body = await res.text().catch(() => "(unreadable)");
-            const errDetail = `[analytics] event "${event.eventName}" rejected: ${res.status} ${res.statusText} \u2014 ${body}`;
-            console.error(`[Featurely] ${errDetail}`);
-            this.debugLog("error", errDetail);
-            this.errorCount++;
-          }
-        } catch (fetchError) {
-          const sentViaBeacon = typeof navigator !== "undefined" && typeof navigator.sendBeacon === "function" && navigator.sendBeacon(url, payload);
-          const errMsg = fetchError instanceof Error ? fetchError.message : String(fetchError);
-          if (!sentViaBeacon) {
-            console.error(
-              `[Featurely] Failed to send analytics event "${event.eventName}":`,
-              fetchError
-            );
-            this.debugLog(
-              "error",
-              `[analytics] send failed for "${event.eventName}": ${errMsg}`
-            );
-            this.errorCount++;
-          } else {
-            this.debugLog(
-              "warn",
-              `[analytics] fetch failed for "${event.eventName}" (${errMsg}), delivered via sendBeacon`
-            );
-          }
         }
       }
     }
@@ -1296,6 +1367,69 @@ var _SiteManager = class _SiteManager {
     }
     return `${Date.now()}-${Math.random().toString(36).substring(2, 15)}`;
   }
+  /**
+   * Compare two semver strings. Returns -1 if a < b, 0 if equal, 1 if a > b.
+   * Handles "major.minor.patch" format.
+   */
+  compareVersions(a, b) {
+    const parse = (v) => v.split(".").map((n) => parseInt(n, 10) || 0);
+    const [aMaj, aMin, aPat] = parse(a);
+    const [bMaj, bMin, bPat] = parse(b);
+    if (aMaj !== bMaj) return aMaj < bMaj ? -1 : 1;
+    if (aMin !== bMin) return aMin < bMin ? -1 : 1;
+    if (aPat !== bPat) return aPat < bPat ? -1 : 1;
+    return 0;
+  }
+  /**
+   * Show a dismissible toast notification prompting developers to update the SDK.
+   * This only appears in browser DevTools / on the page when the SDK is outdated.
+   */
+  showSdkUpdateToast(currentVersion, minimumVersion, latestVersion, updateCommand, changelog) {
+    if (typeof document === "undefined") return;
+    const existing = document.getElementById("ft-sdk-update-toast");
+    if (existing) existing.remove();
+    const toast = document.createElement("div");
+    toast.id = "ft-sdk-update-toast";
+    Object.assign(toast.style, {
+      position: "fixed",
+      bottom: "16px",
+      right: "16px",
+      zIndex: "2147483647",
+      background: "#1c1917",
+      color: "#fafaf9",
+      borderLeft: "4px solid #f59e0b",
+      borderRadius: "8px",
+      padding: "14px 16px",
+      maxWidth: "360px",
+      width: "calc(100vw - 32px)",
+      fontFamily: "-apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif",
+      fontSize: "13px",
+      boxShadow: "0 4px 32px rgba(0,0,0,0.4)",
+      lineHeight: "1.5",
+      fontWeight: "400"
+    });
+    const changelogHtml = changelog ? `<p style="margin:6px 0 0;color:#a8a29e;font-size:12px;">${changelog}</p>` : "";
+    toast.innerHTML = `
+      <button id="ft-sdk-update-close" style="position:absolute;top:10px;right:10px;background:none;border:none;cursor:pointer;color:#78716c;font-size:16px;line-height:1;padding:2px 4px;" aria-label="Dismiss">\xD7</button>
+      <p style="margin:0 20px 0 0;font-weight:600;color:#fbbf24;">\u{1F4E6} SDK update required</p>
+      <p style="margin:6px 0 0;color:#a8a29e;font-size:12px;">
+        <strong style="color:#fafaf9;">featurely-site-manager</strong>
+        v${currentVersion} is below the minimum v${minimumVersion} (latest: v${latestVersion})
+      </p>
+      ${changelogHtml}
+      <p style="margin:8px 0 0;">
+        <code style="background:#292524;border-radius:4px;padding:3px 7px;font-size:11px;color:#d6d3d1;font-family:monospace;word-break:break-all;">${updateCommand}</code>
+      </p>
+    `;
+    document.body.appendChild(toast);
+    const closeBtn = document.getElementById("ft-sdk-update-close");
+    if (closeBtn) {
+      closeBtn.addEventListener("click", () => toast.remove());
+    }
+    setTimeout(() => {
+      if (toast.parentNode) toast.remove();
+    }, 6e4);
+  }
   // ============================================================================
   // Version Checking
   // ============================================================================
@@ -2190,6 +2324,7 @@ _SiteManager.MAX_CONSECUTIVE_FAILURES = 5;
 var SiteManager = _SiteManager;
 var index_default = SiteManager;
 export {
+  SDK_VERSION,
   SiteManager,
   index_default as default
 };

package/package.json

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