@mintlify/cli 4.0.1110 → 4.0.1112

package/__test__/telemetry.test.ts

@@ -10,7 +10,11 @@ import {
 } from '../src/middlewares/telemetryMiddleware.js';
 import { getDistinctId } from '../src/telemetry/distinctId.js';
 import * as trackModule from '../src/telemetry/track.js';
-import { trackCommand, trackTelemetryPreferenceChange } from '../src/telemetry/track.js';
+import {
+  trackCommand,
+  trackEvent,
+  trackTelemetryPreferenceChange,
+} from '../src/telemetry/track.js';
 
 vi.mock('fs-extra', () => ({ ensureDir: vi.fn().mockResolvedValue(undefined) }));
 
@@ -66,6 +70,41 @@ describe('getSanitizedCommandForTelemetry', () => {
     expect(getSanitizedCommandForTelemetry(['rename', 'a.mdx', 'b.mdx'])).toBe('rename');
     expect(getSanitizedCommandForTelemetry(['new', './my-docs'])).toBe('new');
   });
+
+  it('includes known analytics subcommands', () => {
+    expect(getSanitizedCommandForTelemetry(['analytics', 'stats'])).toBe('analytics stats');
+    expect(getSanitizedCommandForTelemetry(['analytics', 'search'])).toBe('analytics search');
+    expect(getSanitizedCommandForTelemetry(['analytics', 'feedback'])).toBe('analytics feedback');
+    expect(getSanitizedCommandForTelemetry(['analytics', 'conversation'])).toBe(
+      'analytics conversation'
+    );
+  });
+
+  it('includes analytics conversation subcommands', () => {
+    expect(getSanitizedCommandForTelemetry(['analytics', 'conversation', 'list'])).toBe(
+      'analytics conversation list'
+    );
+    expect(getSanitizedCommandForTelemetry(['analytics', 'conversation', 'view', 'abc123'])).toBe(
+      'analytics conversation view'
+    );
+  });
+
+  it('includes analytics conversation buckets subcommands', () => {
+    expect(getSanitizedCommandForTelemetry(['analytics', 'conversation', 'buckets', 'list'])).toBe(
+      'analytics conversation buckets list'
+    );
+    expect(
+      getSanitizedCommandForTelemetry(['analytics', 'conversation', 'buckets', 'view', 'abc123'])
+    ).toBe('analytics conversation buckets view');
+  });
+
+  it('includes known config subcommands', () => {
+    expect(getSanitizedCommandForTelemetry(['config', 'set', 'subdomain', 'my-docs'])).toBe(
+      'config set'
+    );
+    expect(getSanitizedCommandForTelemetry(['config', 'get', 'subdomain'])).toBe('config get');
+    expect(getSanitizedCommandForTelemetry(['config', 'clear', 'subdomain'])).toBe('config clear');
+  });
 });
 
 describe('isTelemetryEnabled', () => {
@@ -260,6 +299,72 @@ describe('trackCommand', () => {
   });
 });
 
+describe('trackEvent', () => {
+  const savedEnv = process.env;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockCaptureImmediate.mockResolvedValue(undefined);
+    process.env = { ...savedEnv };
+    delete process.env.CLI_TEST_MODE;
+    delete process.env.MINTLIFY_TELEMETRY_DISABLED;
+    delete process.env.DO_NOT_TRACK;
+    vi.spyOn(fs, 'readFileSync').mockReturnValue(JSON.stringify({ telemetryEnabled: true }));
+  });
+
+  afterEach(() => {
+    process.env = savedEnv;
+  });
+
+  it('captures a custom event with standard metadata', async () => {
+    await trackEvent('cli.dev.started', { subdomain: 'test-docs', port: 3000 });
+
+    expect(mockCaptureImmediate).toHaveBeenCalledWith(
+      expect.objectContaining({
+        event: 'cli.dev.started',
+        properties: expect.objectContaining({
+          subdomain: 'test-docs',
+          port: 3000,
+          cli_version: expect.any(String),
+          os: os.platform(),
+          arch: os.arch(),
+          node_version: process.version,
+        }),
+      })
+    );
+  });
+
+  it('captures event without extra properties', async () => {
+    await trackEvent('cli.validate.executed');
+
+    expect(mockCaptureImmediate).toHaveBeenCalledWith(
+      expect.objectContaining({
+        event: 'cli.validate.executed',
+        properties: expect.objectContaining({
+          os: os.platform(),
+        }),
+      })
+    );
+  });
+
+  it('does not capture when telemetry is disabled', async () => {
+    vi.spyOn(fs, 'readFileSync').mockReturnValue(JSON.stringify({ telemetryEnabled: false }));
+    await trackEvent('cli.dev.started', { subdomain: 'test-docs' });
+    expect(mockCaptureImmediate).not.toHaveBeenCalled();
+  });
+
+  it('does not capture when MINTLIFY_TELEMETRY_DISABLED is set', async () => {
+    process.env.MINTLIFY_TELEMETRY_DISABLED = '1';
+    await trackEvent('cli.dev.started');
+    expect(mockCaptureImmediate).not.toHaveBeenCalled();
+  });
+
+  it('does not throw when captureImmediate rejects', async () => {
+    mockCaptureImmediate.mockRejectedValue(new Error('network error'));
+    await expect(trackEvent('cli.dev.started')).resolves.toBeUndefined();
+  });
+});
+
 describe('trackTelemetryPreferenceChange', () => {
   const savedEnv = process.env;
 

package/bin/middlewares/telemetryMiddleware.js

@@ -11,15 +11,35 @@ import { getConfigValue } from '../config.js';
 import { getVersions } from '../helpers.js';
 import { trackCommand } from '../telemetry/track.js';
 const SCRAPE_SUBCOMMANDS = new Set(['page', 'site', 'openapi']);
+const ANALYTICS_SUBCOMMANDS = new Set(['stats', 'search', 'feedback', 'conversation']);
+const CONFIG_SUBCOMMANDS = new Set(['set', 'get', 'clear']);
+const CONVERSATION_SUBCOMMANDS = new Set(['list', 'view', 'buckets']);
+const BUCKETS_SUBCOMMANDS = new Set(['list', 'view']);
 export function getSanitizedCommandForTelemetry(_) {
     const parts = _.filter((p) => typeof p === 'string');
     if (parts.length === 0)
         return '';
     const first = parts[0];
     const second = parts[1];
+    const third = parts[2];
     if (first === 'scrape' && second !== undefined && SCRAPE_SUBCOMMANDS.has(second)) {
         return `scrape ${second}`;
     }
+    if (first === 'config' && second !== undefined && CONFIG_SUBCOMMANDS.has(second)) {
+        return `config ${second}`;
+    }
+    if (first === 'analytics' && second !== undefined && ANALYTICS_SUBCOMMANDS.has(second)) {
+        if (second === 'conversation' && third !== undefined) {
+            if (CONVERSATION_SUBCOMMANDS.has(third)) {
+                const fourth = parts[3];
+                if (third === 'buckets' && fourth !== undefined && BUCKETS_SUBCOMMANDS.has(fourth)) {
+                    return `analytics conversation buckets ${fourth}`;
+                }
+                return `analytics conversation ${third}`;
+            }
+        }
+        return `analytics ${second}`;
+    }
     return first;
 }
 export function createTelemetryMiddleware() {

package/bin/score/index.js

@@ -12,6 +12,7 @@ import { addLog, ErrorLog, SpinnerLog, removeLastLog } from '@mintlify/previewin
 import chalk from 'chalk';
 import { Text } from 'ink';
 import { terminate } from '../helpers.js';
+import { trackEvent } from '../telemetry/track.js';
 import { getScore } from './client.js';
 function resolveFormat(argv) {
     if (argv.format === 'table' || argv.format === 'plain' || argv.format === 'json')
@@ -62,6 +63,11 @@ export const scoreHandler = (argv) => __awaiter(void 0, void 0, void 0, function
         if (format === 'table')
             addLog(_jsx(SpinnerLog, { message: "Running agent readiness checks..." }));
         const data = yield getScore(argv.url);
+        void trackEvent('cli.score.executed', {
+            url: argv.url,
+            score: data.overallScore,
+            format,
+        });
         if (format === 'table')
             removeLastLog();
         if (format === 'json') {

package/bin/telemetry/track.js

@@ -74,6 +74,17 @@ export function trackLoginFailed(reason) {
         return trackLoginEvent('cli.login.failed', { reason });
     });
 }
+export function trackEvent(event, properties) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (!isTelemetryEnabled())
+            return;
+        try {
+            const { cli: cliVersion } = getVersions();
+            yield captureWithTimeout(event, Object.assign(Object.assign({}, properties), { cli_version: cliVersion, os: os.platform(), arch: os.arch(), node_version: process.version, is_ai_agent: isAI() }));
+        }
+        catch (_a) { }
+    });
+}
 export function trackTelemetryPreferenceChange(options) {
     return __awaiter(this, void 0, void 0, function* () {
         if (process.env.CLI_TEST_MODE === 'true')