@strata-ds/core 2.1.21 → 2.2.2

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,66 @@ 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:
+
+During initialization, the CLI asks whether the project is public or private. Public projects can update their website URL without a token; for a private project, the CLI requests your sync token (with hidden input) when you provide a website URL. The URL is then sent to the backend:
+
+```bash
+npx strata set url
+# or provide the address directly
+npx strata set url example.com
+```
+
+If the address has no scheme, Strata adds `https://`. `npx strata set url` asks whether the project is public or private every time; the value saved in `strata.json` is offered as the default, which you can accept or change. Public projects send no sync token; private projects use `STRATA_SYNC_TOKEN` or `syncToken` from `strata.json` when set, otherwise prompting for the token without displaying it. Older configuration files without `projectType` prompt for a choice without a default. The token is not written to `strata.json` by `init`.
+
+```json
+{
+  "projectId": "YOUR_PROJECT_ID",
+  "projectType": "public",
+  "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. The website URL can also be updated from the project dashboard's Settings.
+
 ## Using Design System Components
 
 `@strata-ds/core` provides dynamic access to your components defined in Strata.

package/dist/cli/postinstall.js

@@ -175,7 +175,7 @@ async function run() {
             const headers = { 'Content-Type': 'application/json' };
             if (syncToken)
                 headers['Authorization'] = `Bearer ${syncToken}`;
-            let sdkVersion = '2.1.20';
+            let sdkVersion = '2.2.0';
             try {
                 const pkgPath = path.resolve(__dirname, '../../package.json');
                 if (fs.existsSync(pkgPath)) {

package/dist/cli/snapshot.js

@@ -136,6 +136,7 @@ Usage:
 
 Commands:
   init               Interactively initialize strata.json configuration file
+  set url [website]  Update the project website URL
   run                Fetch snapshot and generate fallbacks using strata.json
   snapshot           Legacy command to fetch snapshot using options
 
@@ -159,6 +160,117 @@ function askQuestion(query) {
         resolve(ans.trim());
     }));
 }
+async function askProjectPrivacy(defaultValue) {
+    console.log('Project visibility determines whether a sync token is needed:\n' +
+        '  Public  — readable without a sync token\n' +
+        '  Private — protected; a sync token is required to update its website URL');
+    while (true) {
+        const defaultHint = defaultValue ? ` [${defaultValue}]` : '';
+        const answer = (await askQuestion(`Is your Strata project public or private? (public/private)${defaultHint}: `)).toLowerCase() || defaultValue;
+        if (answer === 'public' || answer === 'private')
+            return answer;
+        console.log('Please enter "public" or "private".');
+    }
+}
+function askSecret(query) {
+    const input = process.stdin;
+    if (!input.isTTY || typeof input.setRawMode !== 'function') {
+        throw new Error('No interactive terminal. Set STRATA_SYNC_TOKEN or add syncToken to strata.json.');
+    }
+    return new Promise((resolve, reject) => {
+        let value = '';
+        const cleanup = () => {
+            input.removeListener('data', onData);
+            input.setRawMode(false);
+            input.pause();
+        };
+        const onData = (chunk) => {
+            const key = chunk.toString();
+            if (key === '\u0003') {
+                cleanup();
+                process.stdout.write('\n');
+                reject(new Error('Cancelled.'));
+            }
+            else if (key === '\r' || key === '\n') {
+                cleanup();
+                process.stdout.write('\n');
+                resolve(value.trim());
+            }
+            else if (key === '\u007f' || key === '\b') {
+                value = value.slice(0, -1);
+                process.stdout.write('\b \b');
+            }
+            else {
+                value += key;
+                process.stdout.write('*');
+            }
+        };
+        process.stdout.write(query);
+        input.setRawMode(true);
+        input.resume();
+        input.on('data', onData);
+    });
+}
+function normalizeWebsiteUrl(value) {
+    const trimmed = value.trim();
+    if (!trimmed)
+        return null;
+    const candidate = /^https?:\/\//i.test(trimmed) ? trimmed : `https://${trimmed}`;
+    try {
+        const url = new URL(candidate);
+        const hostname = url.hostname.toLowerCase().replace(/\.$/, '');
+        if (!['http:', 'https:'].includes(url.protocol) ||
+            !url.hostname ||
+            url.username ||
+            url.password ||
+            !hostname.includes('.') ||
+            hostname.includes(':') ||
+            /^(?:\d{1,3}\.){3}\d{1,3}$/.test(hostname) ||
+            /(?:^|\.)localhost$|\.local$|\.internal$/.test(hostname)) {
+            return null;
+        }
+        return candidate;
+    }
+    catch {
+        return null;
+    }
+}
+async function getSyncToken(config) {
+    const configuredToken = process.env.STRATA_SYNC_TOKEN || config.syncToken;
+    const token = configuredToken || await askSecret('Enter your Strata Sync Token (input hidden): ');
+    if (!token.trim())
+        throw new Error('A Strata Sync Token is required to update the website URL.');
+    return token.trim();
+}
+async function saveWebsiteUrl(projectId, websiteUrl, syncToken, apiBase) {
+    const base = (apiBase || process.env.STRATA_API_BASE || 'https://api-production-charisol-design-system-be.aws.charisol.io')
+        .replace(/\/+$/, '')
+        .replace(/\/v1$/i, '');
+    const headers = {
+        'Content-Type': 'application/json',
+    };
+    if (syncToken) {
+        headers.Authorization = `Bearer ${syncToken}`;
+    }
+    const response = await fetch(`${base}/v1/connect/${encodeURIComponent(projectId)}/website-url`, {
+        method: 'PATCH',
+        headers,
+        body: JSON.stringify({ websiteUrl }),
+    });
+    const contentType = response.headers.get('content-type') || '';
+    if (!contentType.includes('application/json')) {
+        throw new Error(`The API returned ${response.status} ${response.statusText} instead of JSON. ` +
+            `Check STRATA_API_BASE or apiBase in strata.json; it should point to the backend API host, optionally with a /v1 suffix.`);
+    }
+    const result = await response.json();
+    if (!response.ok || !result.status) {
+        throw new Error(result.message || `The API returned ${response.status} ${response.statusText}.`);
+    }
+    if (typeof result.data?.websiteUrl !== 'string') {
+        throw new Error('The API response did not contain the saved website URL.');
+    }
+    return result.data.websiteUrl;
+}
 async function runInit() {
     console.log('Strata Design System Initialization\n');
     let projectId = '';
@@ -168,23 +280,84 @@ async function runInit() {
             console.log('Error: Project ID is required.');
         }
     }
+    const projectType = await askProjectPrivacy();
+    let websiteUrl = null;
+    while (true) {
+        const input = await askQuestion('Enter your website URL (optional, e.g. example.com): ');
+        if (!input)
+            break;
+        websiteUrl = normalizeWebsiteUrl(input);
+        if (websiteUrl)
+            break;
+        console.log('Error: Enter a public website hostname or HTTP(S) URL.');
+    }
+    const syncToken = websiteUrl && projectType === 'private' ? await getSyncToken({}) : undefined;
     const cdnBase = (await askQuestion('Enter CDN Base URL (default: https://dx2nhw7wqn4nn.cloudfront.net): ')) || 'https://dx2nhw7wqn4nn.cloudfront.net';
     const output = (await askQuestion('Enter path to write snapshot JSON file (default: ./src/data/strata-snapshot.json): ')) || './src/data/strata-snapshot.json';
     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,
+        projectType,
     };
+    if (websiteUrl) {
+        config.websiteUrl = websiteUrl;
+    }
+    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}`);
+    if (websiteUrl) {
+        try {
+            const savedUrl = await saveWebsiteUrl(projectId, websiteUrl, syncToken, config.apiBase);
+            console.log(`[Strata] Website URL updated: ${savedUrl}`);
+        }
+        catch (error) {
+            console.error(`[Strata] Website URL was not updated: ${error.message || error}`);
+            process.exitCode = 1;
+        }
+    }
     console.log('To fetch your design tokens, run: npx strata run');
 }
+async function runSetUrl(args) {
+    const strataJsonPath = path.join(process.cwd(), 'strata.json');
+    if (!fs.existsSync(strataJsonPath)) {
+        throw new Error('strata.json not found. Run "npx strata init" first.');
+    }
+    let config;
+    try {
+        config = JSON.parse(fs.readFileSync(strataJsonPath, 'utf8'));
+    }
+    catch (error) {
+        throw new Error(`Error reading strata.json: ${error.message}`);
+    }
+    if (!config.projectId)
+        throw new Error('The projectId is missing from strata.json.');
+    const input = args[2] || await askQuestion('Enter your website URL: ');
+    const websiteUrl = normalizeWebsiteUrl(input);
+    if (!websiteUrl)
+        throw new Error('Enter a public website hostname or HTTP(S) URL.');
+    const savedProjectType = config.projectType === 'public' || config.projectType === 'private'
+        ? config.projectType
+        : undefined;
+    const projectType = await askProjectPrivacy(savedProjectType);
+    const syncToken = projectType === 'private' ? await getSyncToken(config) : undefined;
+    const savedUrl = await saveWebsiteUrl(config.projectId, websiteUrl, syncToken, config.apiBase);
+    config.projectType = projectType;
+    fs.writeFileSync(strataJsonPath, JSON.stringify(config, null, 2), 'utf8');
+    console.log(`[Strata] Website URL updated: ${savedUrl}`);
+}
 async function runRetrieve(command) {
     const args = process.argv.slice(2);
     const getArgValue = (flag) => {
@@ -256,6 +429,15 @@ async function main() {
     if (command === 'init') {
         await runInit();
     }
+    else if (command === 'set' && args[1] === 'url') {
+        try {
+            await runSetUrl(args);
+        }
+        catch (error) {
+            console.error(`[Strata] ${error.message || error}`);
+            process.exitCode = 1;
+        }
+    }
     else if (command === 'run' || command === 'snapshot') {
         await runRetrieve(command);
     }

package/dist/index.esm.js

@@ -1166,7 +1166,7 @@ var HeartbeatReporter = /*#__PURE__*/function () {
               if (this.config.syncToken) {
                 headers["Authorization"] = "Bearer ".concat(this.config.syncToken);
               }
-              version = "2.1.21" ;
+              version = "2.2.2" ;
               body = {
                 origin: window.location.origin,
                 sdkVersion: version,

package/dist/index.js

@@ -1168,7 +1168,7 @@ var HeartbeatReporter = /*#__PURE__*/function () {
               if (this.config.syncToken) {
                 headers["Authorization"] = "Bearer ".concat(this.config.syncToken);
               }
-              version = "2.1.21" ;
+              version = "2.2.2" ;
               body = {
                 origin: window.location.origin,
                 sdkVersion: version,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@strata-ds/core",
-	"version": "2.1.21",
+	"version": "2.2.2",
 	"type": "module",
 	"description": "The runtime component library for Strata — design once, sync everywhere.",
 	"homepage": "https://strata.charisol.io",