@strata-ds/core 2.1.20 → 2.2.1

package/README.md

@@ -259,6 +259,9 @@ Wrap your application's root component with `StrataProvider`. This provider mana
 | `userDesignSystem` |                          `DesignSystemData`                          | Override design system data — useful for storybook, testing, or static mode. Takes precedence over `initialData`.                                                                                                                                            |
 | `onSyncError`      | `(error: { code: number; message: string; source: string }) => void` | Callback invoked when a sync cycle fails. `code` is the HTTP status (0 for non-HTTP errors), `message` is a human-readable description, and `source` is `"cdn"` or `"sync"`.                                                                                 |
 | `onSyncSuccess`    |                  `(data: DesignSystemData) => void`                  | Callback invoked whenever a sync cycle succeeds with new data.                                                                                                                                                                                               |
+| `reportUsage`      |                              `boolean`                               | Whether to send non-sensitive usage telemetry to power "See It in the Wild" in the dashboard. Defaults to `true` in production. Set to `false` to opt out.                                                                                           |
+| `appName`          |                               `string`                               | Optional human-readable display name for your app in the Strata dashboard (e.g. `"Storefront Web"`).                                                                                                                                                         |
+| `environment`      |                               `string`                               | Override automatic environment detection (`"production"`, `"staging"`, `"development"`). Heartbeat is paused when set to `"development"`.                                                                                                                   |
 
 ```tsx
 // app/layout.tsx (Next.js App Router)
@@ -307,6 +310,55 @@ Projects with `syncToken` set are only readable by clients that present the corr
 </StrataProvider>
 ```
 
+### Connected Apps Telemetry ("See It in the Wild")
+
+By default in production environments, `<StrataProvider>` sends a lightweight telemetry heartbeat every 5 minutes to report active design system surface integrations.
+
+#### What is "Connected Apps"?
+"Connected Apps" (featured as "See It in the Wild" on your public project page and Settings dashboard) provides real-time visibility into which live applications are consuming your design system, their active SDK version, environment, and health status (`Live`, `Stale`, or `Dormant`).
+
+#### Data Transmitted
+The telemetry heartbeat contains **only** non-sensitive metadata:
+- Application origin / hostname (e.g. `https://app.example.com`)
+- Strata SDK version (e.g. `2.2.0`)
+- Sync mode (`cdn`, `legacy`, `static`) and polling interval
+- User Agent string (browser family)
+- Optional `appName` prop value
+
+#### How to Opt Out
+To disable telemetry heartbeats entirely, set `reportUsage={false}`:
+
+```tsx
+<StrataProvider
+  syncEnabled={true}
+  projectId="YOUR_PROJECT_ID"
+  snapshotCdnBase="https://cdn.strata.charisol.io"
+  reportUsage={false}
+>
+  {children}
+</StrataProvider>
+```
+
+#### CLI Setup & Build-Time Registration
+You can also initialize project configuration using `npx strata init`:
+
+```bash
+npx strata init
+```
+
+This generates a `strata.json` configuration file:
+
+```json
+{
+  "projectId": "YOUR_PROJECT_ID",
+  "snapshotCdnBase": "https://cdn.strata.charisol.io",
+  "appName": "Storefront Web",
+  "reportUsage": true
+}
+```
+
+When `strata.json` is present, the `@strata-ds/core` `postinstall` script automatically registers build-time presence for your application.
+
 ## Using Design System Components
 
 `@strata-ds/core` provides dynamic access to your components defined in Strata.

package/dist/cli/postinstall.js

@@ -168,6 +168,37 @@ async function run() {
             variablesOnly: variablesOnly !== false,
         });
         console.log('[Strata] Postinstall snapshot retrieval complete.');
+        // Register build-time presence (non-blocking, best-effort)
+        try {
+            const os = await import('os');
+            const apiBase = config.apiBase || 'https://api-production-charisol-design-system-be.aws.charisol.io';
+            const headers = { 'Content-Type': 'application/json' };
+            if (syncToken)
+                headers['Authorization'] = `Bearer ${syncToken}`;
+            let sdkVersion = '2.2.0';
+            try {
+                const pkgPath = path.resolve(__dirname, '../../package.json');
+                if (fs.existsSync(pkgPath)) {
+                    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+                    if (pkg.version)
+                        sdkVersion = pkg.version;
+                }
+            }
+            catch (err) { }
+            await fetch(`${apiBase}/v1/connect/${projectId}/register`, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify({
+                    hostname: os.hostname(),
+                    sdkVersion,
+                    environment: 'build',
+                }),
+            });
+            console.log('[Strata] Build-time registration complete.');
+        }
+        catch (e) {
+            // Registration failure is non-fatal
+        }
     }
     catch (error) {
         // Graceful degradation: log warning but do not throw error so install succeeds

package/dist/cli/snapshot.js

@@ -173,13 +173,20 @@ async function runInit() {
     const outputCss = (await askQuestion('Enter path to write CSS fallback file (default: ./src/styles/strata-fallbacks.css): ')) || './src/styles/strata-fallbacks.css';
     const varsOnlyInput = await askQuestion('Only output variables in snapshot JSON? (Y/n): ');
     const variablesOnly = varsOnlyInput.toLowerCase() !== 'n';
+    const appNameInput = await askQuestion('Enter Application Name (optional, e.g. "Storefront Web"): ');
+    const reportUsageInput = await askQuestion('Report usage telemetry to Strata Dashboard? (Y/n): ');
+    const reportUsage = reportUsageInput.toLowerCase() !== 'n';
     const config = {
         projectId,
         snapshotCdnBase: cdnBase,
         output,
         outputCss,
         variablesOnly,
+        reportUsage,
     };
+    if (appNameInput) {
+        config.appName = appNameInput;
+    }
     const strataJsonPath = path.join(process.cwd(), 'strata.json');
     fs.writeFileSync(strataJsonPath, JSON.stringify(config, null, 2), 'utf8');
     console.log(`\nConfig file written successfully to: ${strataJsonPath}`);

package/dist/index.d.ts

@@ -146,6 +146,12 @@ interface StrataProviderProps {
      * Defaults to true.
      */
     injectCssVars?: boolean;
+    /** Whether to report usage telemetry (heartbeat). Defaults to true in production. */
+    reportUsage?: boolean;
+    /** Human-readable app name shown in the Strata dashboard. */
+    appName?: string;
+    /** Override automatic environment detection. */
+    environment?: string;
 }
 declare const StrataProvider: React__default.FC<StrataProviderProps>;
 
@@ -862,5 +868,24 @@ declare const useAvailableComponents: () => {
     allComponents: string[];
 };
 
-export { AutoForm, Card, DefaultCard, DynamicComponent, StrataComponentFactory, StrataDebug, StrataErrorBoundary, StrataProvider, strataRegistry, useAvailableComponents, useCardData, useComponent, useComponentData, useComponents, useCustomComponent, useDynamicComponents, useStrata };
+interface HeartbeatConfig {
+    projectId: string;
+    syncToken?: string;
+    syncMode: "cdn" | "legacy" | "static";
+    syncInterval: number;
+    appName?: string;
+    environment?: string;
+    apiBase?: string;
+}
+declare class HeartbeatReporter {
+    private intervalId;
+    private config;
+    private disabled;
+    constructor(config: HeartbeatConfig);
+    start(): Promise<void>;
+    stop(): void;
+    private sendHeartbeat;
+}
+
+export { AutoForm, Card, DefaultCard, DynamicComponent, HeartbeatReporter, StrataComponentFactory, StrataDebug, StrataErrorBoundary, StrataProvider, strataRegistry, useAvailableComponents, useCardData, useComponent, useComponentData, useComponents, useCustomComponent, useDynamicComponents, useStrata };
 export type { CardComponent, CardProps, ComponentNode, ComponentProperty, ComponentVariant, CustomDesignSystemData, DesignSystemData, DesignToken, FilterType, LinkedElement, SelectedItem, SelectedType, TokenType };

package/dist/index.esm.js

@@ -1,5 +1,5 @@
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
-import React, { useState, useRef, useEffect, useMemo, useCallback, createContext, useContext } from 'react';
+import React, { useRef, useEffect, useState, useMemo, useCallback, createContext, useContext } from 'react';
 import { extendTheme, ChakraProvider, Box, Flex, Text, Image, Button, VStack, HStack } from '@chakra-ui/react';
 
 function _arrayLikeToArray(r, a) {
@@ -1089,6 +1089,141 @@ if (shouldRunPascalCaseTest) {
   }, 1000);
 }
 
+var DEFAULT_HEARTBEAT_INTERVAL = 5 * 60 * 1000; // 5 minutes
+var DEFAULT_API_BASE = "https://api-production-charisol-design-system-be.aws.charisol.io";
+var HeartbeatReporter = /*#__PURE__*/function () {
+  function HeartbeatReporter(config) {
+    _classCallCheck(this, HeartbeatReporter);
+    this.intervalId = null;
+    this.disabled = false;
+    this.config = config;
+  }
+  return _createClass(HeartbeatReporter, [{
+    key: "start",
+    value: function () {
+      var _start = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee() {
+        var _this = this;
+        return _regenerator().w(function (_context) {
+          while (1) switch (_context.n) {
+            case 0:
+              if (!(typeof window === "undefined")) {
+                _context.n = 1;
+                break;
+              }
+              return _context.a(2);
+            case 1:
+              if (!(this.config.environment === "development")) {
+                _context.n = 2;
+                break;
+              }
+              return _context.a(2);
+            case 2:
+              _context.n = 3;
+              return this.sendHeartbeat();
+            case 3:
+              // Schedule recurring heartbeats
+              this.intervalId = setInterval(function () {
+                return _this.sendHeartbeat();
+              }, DEFAULT_HEARTBEAT_INTERVAL);
+            case 4:
+              return _context.a(2);
+          }
+        }, _callee, this);
+      }));
+      function start() {
+        return _start.apply(this, arguments);
+      }
+      return start;
+    }()
+  }, {
+    key: "stop",
+    value: function stop() {
+      if (this.intervalId) {
+        clearInterval(this.intervalId);
+        this.intervalId = null;
+      }
+    }
+  }, {
+    key: "sendHeartbeat",
+    value: function () {
+      var _sendHeartbeat = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee2() {
+        var apiBase, url, headers, version, body, res;
+        return _regenerator().w(function (_context2) {
+          while (1) switch (_context2.p = _context2.n) {
+            case 0:
+              if (!this.disabled) {
+                _context2.n = 1;
+                break;
+              }
+              return _context2.a(2);
+            case 1:
+              _context2.p = 1;
+              apiBase = this.config.apiBase || DEFAULT_API_BASE;
+              url = "".concat(apiBase, "/v1/connect/").concat(this.config.projectId, "/heartbeat");
+              headers = {
+                "Content-Type": "application/json"
+              };
+              if (this.config.syncToken) {
+                headers["Authorization"] = "Bearer ".concat(this.config.syncToken);
+              }
+              version = "2.2.1" ;
+              body = {
+                origin: window.location.origin,
+                sdkVersion: version,
+                syncMode: this.config.syncMode,
+                syncInterval: this.config.syncInterval,
+                userAgent: navigator.userAgent,
+                appName: this.config.appName,
+                metadata: {
+                  pageUrl: window.location.href,
+                  referrer: document.referrer,
+                  framework: detectFramework()
+                }
+              };
+              _context2.n = 2;
+              return fetch(url, {
+                method: "POST",
+                headers: headers,
+                body: JSON.stringify(body),
+                // Don't let heartbeat affect page performance
+                keepalive: true
+              });
+            case 2:
+              res = _context2.v;
+              // If we get 401, disable heartbeat for this session
+              if (res.status === 401) {
+                console.warn("[strata] Heartbeat disabled: invalid sync token");
+                this.disabled = true;
+                this.stop();
+              }
+              _context2.n = 4;
+              break;
+            case 3:
+              _context2.p = 3;
+              _context2.v;
+            case 4:
+              return _context2.a(2);
+          }
+        }, _callee2, this, [[1, 3]]);
+      }));
+      function sendHeartbeat() {
+        return _sendHeartbeat.apply(this, arguments);
+      }
+      return sendHeartbeat;
+    }()
+  }]);
+}();
+function detectFramework() {
+  if (typeof window === "undefined") return "unknown";
+  // @ts-ignore
+  if (window.__NEXT_DATA__) return "nextjs";
+  // @ts-ignore
+  if (window.__REMIX_DEV_TOOLS) return "remix";
+  // @ts-ignore
+  if (window.__GATSBY) return "gatsby";
+  return "react";
+}
+
 var StrataContext = /*#__PURE__*/createContext(undefined);
 var useStrata = function useStrata() {
   var context = useContext(StrataContext);
@@ -1117,7 +1252,31 @@ var StrataProvider = function StrataProvider(_ref) {
     _ref$persistCache = _ref.persistCache,
     persistCache = _ref$persistCache === void 0 ? true : _ref$persistCache,
     _ref$injectCssVars = _ref.injectCssVars,
-    injectCssVars = _ref$injectCssVars === void 0 ? true : _ref$injectCssVars;
+    injectCssVars = _ref$injectCssVars === void 0 ? true : _ref$injectCssVars,
+    _ref$reportUsage = _ref.reportUsage,
+    reportUsage = _ref$reportUsage === void 0 ? true : _ref$reportUsage,
+    appName = _ref.appName,
+    environment = _ref.environment;
+  // Heartbeat reporter — ref to avoid re-creation on each render
+  var heartbeatRef = useRef(null);
+  useEffect(function () {
+    if (!reportUsage || !syncEnabled || !projectId) return;
+    var syncMode = snapshotCdnBase ? "cdn" : syncUrl ? "legacy" : "static";
+    var reporter = new HeartbeatReporter({
+      projectId: projectId,
+      syncToken: syncToken,
+      syncMode: syncMode,
+      syncInterval: syncInterval,
+      appName: appName,
+      environment: environment
+    });
+    heartbeatRef.current = reporter;
+    reporter.start();
+    return function () {
+      reporter.stop();
+      heartbeatRef.current = null;
+    };
+  }, [reportUsage, syncEnabled, projectId, syncToken, snapshotCdnBase, syncUrl, syncInterval, appName, environment]);
   var _useState = useState(function () {
       if (userDesignSystem) return "initial";
       if (initialData) return "initial";
@@ -3409,4 +3568,4 @@ var AutoForm = function AutoForm(_ref2) {
   return /*#__PURE__*/React.createElement(FormComponent, props, children);
 };
 
-export { AutoForm, Card, DefaultCard, DynamicComponent, StrataComponentFactory, StrataDebug, StrataErrorBoundary, StrataProvider, strataRegistry, useAvailableComponents, useCardData, useComponent, useComponentData, useComponents, useCustomComponent, useDynamicComponents, useStrata };
+export { AutoForm, Card, DefaultCard, DynamicComponent, HeartbeatReporter, StrataComponentFactory, StrataDebug, StrataErrorBoundary, StrataProvider, strataRegistry, useAvailableComponents, useCardData, useComponent, useComponentData, useComponents, useCustomComponent, useDynamicComponents, useStrata };

package/dist/index.js

@@ -1091,6 +1091,141 @@ if (shouldRunPascalCaseTest) {
   }, 1000);
 }
 
+var DEFAULT_HEARTBEAT_INTERVAL = 5 * 60 * 1000; // 5 minutes
+var DEFAULT_API_BASE = "https://api-production-charisol-design-system-be.aws.charisol.io";
+var HeartbeatReporter = /*#__PURE__*/function () {
+  function HeartbeatReporter(config) {
+    _classCallCheck(this, HeartbeatReporter);
+    this.intervalId = null;
+    this.disabled = false;
+    this.config = config;
+  }
+  return _createClass(HeartbeatReporter, [{
+    key: "start",
+    value: function () {
+      var _start = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee() {
+        var _this = this;
+        return _regenerator().w(function (_context) {
+          while (1) switch (_context.n) {
+            case 0:
+              if (!(typeof window === "undefined")) {
+                _context.n = 1;
+                break;
+              }
+              return _context.a(2);
+            case 1:
+              if (!(this.config.environment === "development")) {
+                _context.n = 2;
+                break;
+              }
+              return _context.a(2);
+            case 2:
+              _context.n = 3;
+              return this.sendHeartbeat();
+            case 3:
+              // Schedule recurring heartbeats
+              this.intervalId = setInterval(function () {
+                return _this.sendHeartbeat();
+              }, DEFAULT_HEARTBEAT_INTERVAL);
+            case 4:
+              return _context.a(2);
+          }
+        }, _callee, this);
+      }));
+      function start() {
+        return _start.apply(this, arguments);
+      }
+      return start;
+    }()
+  }, {
+    key: "stop",
+    value: function stop() {
+      if (this.intervalId) {
+        clearInterval(this.intervalId);
+        this.intervalId = null;
+      }
+    }
+  }, {
+    key: "sendHeartbeat",
+    value: function () {
+      var _sendHeartbeat = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee2() {
+        var apiBase, url, headers, version, body, res;
+        return _regenerator().w(function (_context2) {
+          while (1) switch (_context2.p = _context2.n) {
+            case 0:
+              if (!this.disabled) {
+                _context2.n = 1;
+                break;
+              }
+              return _context2.a(2);
+            case 1:
+              _context2.p = 1;
+              apiBase = this.config.apiBase || DEFAULT_API_BASE;
+              url = "".concat(apiBase, "/v1/connect/").concat(this.config.projectId, "/heartbeat");
+              headers = {
+                "Content-Type": "application/json"
+              };
+              if (this.config.syncToken) {
+                headers["Authorization"] = "Bearer ".concat(this.config.syncToken);
+              }
+              version = "2.2.1" ;
+              body = {
+                origin: window.location.origin,
+                sdkVersion: version,
+                syncMode: this.config.syncMode,
+                syncInterval: this.config.syncInterval,
+                userAgent: navigator.userAgent,
+                appName: this.config.appName,
+                metadata: {
+                  pageUrl: window.location.href,
+                  referrer: document.referrer,
+                  framework: detectFramework()
+                }
+              };
+              _context2.n = 2;
+              return fetch(url, {
+                method: "POST",
+                headers: headers,
+                body: JSON.stringify(body),
+                // Don't let heartbeat affect page performance
+                keepalive: true
+              });
+            case 2:
+              res = _context2.v;
+              // If we get 401, disable heartbeat for this session
+              if (res.status === 401) {
+                console.warn("[strata] Heartbeat disabled: invalid sync token");
+                this.disabled = true;
+                this.stop();
+              }
+              _context2.n = 4;
+              break;
+            case 3:
+              _context2.p = 3;
+              _context2.v;
+            case 4:
+              return _context2.a(2);
+          }
+        }, _callee2, this, [[1, 3]]);
+      }));
+      function sendHeartbeat() {
+        return _sendHeartbeat.apply(this, arguments);
+      }
+      return sendHeartbeat;
+    }()
+  }]);
+}();
+function detectFramework() {
+  if (typeof window === "undefined") return "unknown";
+  // @ts-ignore
+  if (window.__NEXT_DATA__) return "nextjs";
+  // @ts-ignore
+  if (window.__REMIX_DEV_TOOLS) return "remix";
+  // @ts-ignore
+  if (window.__GATSBY) return "gatsby";
+  return "react";
+}
+
 var StrataContext = /*#__PURE__*/React.createContext(undefined);
 var useStrata = function useStrata() {
   var context = React.useContext(StrataContext);
@@ -1119,7 +1254,31 @@ var StrataProvider = function StrataProvider(_ref) {
     _ref$persistCache = _ref.persistCache,
     persistCache = _ref$persistCache === void 0 ? true : _ref$persistCache,
     _ref$injectCssVars = _ref.injectCssVars,
-    injectCssVars = _ref$injectCssVars === void 0 ? true : _ref$injectCssVars;
+    injectCssVars = _ref$injectCssVars === void 0 ? true : _ref$injectCssVars,
+    _ref$reportUsage = _ref.reportUsage,
+    reportUsage = _ref$reportUsage === void 0 ? true : _ref$reportUsage,
+    appName = _ref.appName,
+    environment = _ref.environment;
+  // Heartbeat reporter — ref to avoid re-creation on each render
+  var heartbeatRef = React.useRef(null);
+  React.useEffect(function () {
+    if (!reportUsage || !syncEnabled || !projectId) return;
+    var syncMode = snapshotCdnBase ? "cdn" : syncUrl ? "legacy" : "static";
+    var reporter = new HeartbeatReporter({
+      projectId: projectId,
+      syncToken: syncToken,
+      syncMode: syncMode,
+      syncInterval: syncInterval,
+      appName: appName,
+      environment: environment
+    });
+    heartbeatRef.current = reporter;
+    reporter.start();
+    return function () {
+      reporter.stop();
+      heartbeatRef.current = null;
+    };
+  }, [reportUsage, syncEnabled, projectId, syncToken, snapshotCdnBase, syncUrl, syncInterval, appName, environment]);
   var _useState = React.useState(function () {
       if (userDesignSystem) return "initial";
       if (initialData) return "initial";
@@ -3415,6 +3574,7 @@ exports.AutoForm = AutoForm;
 exports.Card = Card;
 exports.DefaultCard = DefaultCard;
 exports.DynamicComponent = DynamicComponent;
+exports.HeartbeatReporter = HeartbeatReporter;
 exports.StrataComponentFactory = StrataComponentFactory;
 exports.StrataDebug = StrataDebug;
 exports.StrataErrorBoundary = StrataErrorBoundary;

package/dist/providers/StrataProvider.d.ts

@@ -71,6 +71,12 @@ interface StrataProviderProps {
      * Defaults to true.
      */
     injectCssVars?: boolean;
+    /** Whether to report usage telemetry (heartbeat). Defaults to true in production. */
+    reportUsage?: boolean;
+    /** Human-readable app name shown in the Strata dashboard. */
+    appName?: string;
+    /** Override automatic environment detection. */
+    environment?: string;
 }
 export declare const StrataProvider: React.FC<StrataProviderProps>;
 export {};

package/dist/telemetry/heartbeat.d.ts

@@ -0,0 +1,18 @@
+export interface HeartbeatConfig {
+    projectId: string;
+    syncToken?: string;
+    syncMode: "cdn" | "legacy" | "static";
+    syncInterval: number;
+    appName?: string;
+    environment?: string;
+    apiBase?: string;
+}
+export declare class HeartbeatReporter {
+    private intervalId;
+    private config;
+    private disabled;
+    constructor(config: HeartbeatConfig);
+    start(): Promise<void>;
+    stop(): void;
+    private sendHeartbeat;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@strata-ds/core",
-	"version": "2.1.20",
+	"version": "2.2.1",
 	"type": "module",
 	"description": "The runtime component library for Strata — design once, sync everywhere.",
 	"homepage": "https://strata.charisol.io",
@@ -54,6 +54,7 @@
 		"@rollup/plugin-babel": "^6.1.0",
 		"@rollup/plugin-commonjs": "^28.0.9",
 		"@rollup/plugin-node-resolve": "^16.0.3",
+		"@rollup/plugin-replace": "^6.0.3",
 		"@rollup/plugin-typescript": "^12.3.0",
 		"@types/node": "^25.0.0",
 		"@types/react": "^19.2.2",