@mintlify/cli 4.0.1421 → 4.0.1423

package/__test__/analytics/client.test.ts

@@ -0,0 +1,180 @@
+import {
+  getAssistantThread,
+  getFeedback,
+  getFeedbackByPage,
+  getBuckets,
+  getBucketThreads,
+  getConversations,
+  getKpi,
+  getSearches,
+  getViews,
+  getVisitors,
+} from '../../src/analytics/client.js';
+
+vi.mock('../../src/keyring.js', () => ({
+  getAccessToken: vi.fn().mockResolvedValue(null),
+  getRefreshToken: vi.fn().mockResolvedValue(null),
+  storeCredentials: vi.fn().mockResolvedValue(undefined),
+}));
+
+const mockFetch = vi.fn();
+global.fetch = mockFetch;
+
+beforeEach(() => {
+  vi.stubEnv('MINTLIFY_SESSION_TOKEN', 'test-token');
+  vi.stubEnv('MINTLIFY_API_URL', 'http://test-server:5000');
+  mockFetch.mockReset();
+});
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+});
+
+function mockOk(data: unknown) {
+  mockFetch.mockResolvedValueOnce({
+    ok: true,
+    status: 200,
+    json: () => Promise.resolve(data),
+  });
+}
+
+function mockError(status: number, body: string) {
+  mockFetch.mockResolvedValueOnce({
+    ok: false,
+    status,
+    statusText: 'Bad Request',
+    text: () => Promise.resolve(body),
+  });
+}
+
+function calledUrl(): string {
+  const arg = mockFetch.mock.calls[0]![0];
+  return typeof arg === 'string' ? arg : String(arg);
+}
+
+function calledUrlObj(): URL {
+  return new URL(calledUrl());
+}
+
+describe('client auth', () => {
+  it('throws when no session token is set', async () => {
+    vi.stubEnv('MINTLIFY_SESSION_TOKEN', '');
+    await expect(getFeedback({ dateFrom: '2024-01-01', dateTo: '2024-01-31' })).rejects.toThrow(
+      'Not authenticated'
+    );
+  });
+
+  it('sends session cookie header', async () => {
+    mockOk({ feedback: [], nextCursor: null, hasMore: false });
+    await getFeedback({ dateFrom: '2024-01-01', dateTo: '2024-01-31' }, 'test');
+    expect(mockFetch).toHaveBeenCalledWith(
+      expect.any(String),
+      expect.objectContaining({
+        headers: expect.objectContaining({
+          Authorization: 'Bearer test-token',
+        }),
+      })
+    );
+  });
+});
+
+describe('client request handling', () => {
+  it('throws on API error', async () => {
+    mockError(400, 'Invalid params');
+    await expect(getFeedback({ dateFrom: '2024-01-01', dateTo: '2024-01-31' })).rejects.toThrow(
+      'API error (400): Invalid params'
+    );
+  });
+
+  it('passes subdomain as query param when provided', async () => {
+    mockOk({ feedback: [], nextCursor: null, hasMore: false });
+    await getFeedback({ dateFrom: '2024-01-01', dateTo: '2024-01-31' }, 'my-docs');
+    expect(calledUrlObj().searchParams.get('subdomain')).toBe('my-docs');
+    expect(calledUrlObj().pathname).toBe('/api/cli/analytics/feedback');
+  });
+
+  it('omits subdomain param when not provided', async () => {
+    mockOk({ feedback: [], nextCursor: null, hasMore: false });
+    await getFeedback({ dateFrom: '2024-01-01', dateTo: '2024-01-31' });
+    expect(calledUrlObj().searchParams.has('subdomain')).toBe(false);
+  });
+
+  it('sets query params and omits undefined values', async () => {
+    mockOk({ feedback: [], nextCursor: null, hasMore: false });
+    await getFeedback({
+      dateFrom: '2024-01-01',
+      dateTo: '2024-01-31',
+      limit: 10,
+      cursor: undefined,
+    });
+    expect(calledUrlObj().searchParams.get('dateFrom')).toBe('2024-01-01');
+    expect(calledUrlObj().searchParams.get('limit')).toBe('10');
+    expect(calledUrlObj().searchParams.has('cursor')).toBe(false);
+  });
+});
+
+describe('endpoint paths', () => {
+  it('getKpi', async () => {
+    mockOk({ humanVisitors: 0 });
+    await getKpi({ dateFrom: '2024-01-01', dateTo: '2024-01-31' }, 'docs');
+    expect(calledUrlObj().pathname).toBe('/api/cli/analytics/kpi');
+    expect(calledUrlObj().searchParams.get('subdomain')).toBe('docs');
+  });
+
+  it('getFeedbackByPage', async () => {
+    mockOk({ feedback: [], hasMore: false });
+    await getFeedbackByPage({ dateFrom: '2024-01-01', dateTo: '2024-01-31' }, 'docs');
+    expect(calledUrlObj().pathname).toBe('/api/cli/analytics/feedback/by-page');
+  });
+
+  it('getConversations', async () => {
+    mockOk({ conversations: [], nextCursor: null, hasMore: false });
+    await getConversations({ dateFrom: '2024-01-01', dateTo: '2024-01-31' }, 'docs');
+    expect(calledUrlObj().pathname).toBe('/api/cli/analytics/assistant');
+  });
+
+  it('getAssistantThread', async () => {
+    mockOk({ threadId: 'thread-123', createdAt: '2024-01-01', messages: [] });
+    await getAssistantThread('thread/123', 'docs');
+    expect(calledUrlObj().pathname).toBe('/api/cli/analytics/assistant/threads/thread%2F123');
+    expect(calledUrlObj().searchParams.get('subdomain')).toBe('docs');
+  });
+
+  it('getSearches', async () => {
+    mockOk({ searches: [], totalSearches: 0, nextCursor: null });
+    await getSearches({ dateFrom: '2024-01-01', dateTo: '2024-01-31' }, 'docs');
+    expect(calledUrlObj().pathname).toBe('/api/cli/analytics/searches');
+  });
+
+  it('getViews', async () => {
+    mockOk({ totals: {}, views: [], hasMore: false });
+    await getViews({ dateFrom: '2024-01-01', dateTo: '2024-01-31' }, 'docs');
+    expect(calledUrlObj().pathname).toBe('/api/cli/analytics/views');
+  });
+
+  it('getVisitors', async () => {
+    mockOk({ totals: {}, visitors: [], hasMore: false });
+    await getVisitors({ dateFrom: '2024-01-01', dateTo: '2024-01-31' }, 'docs');
+    expect(calledUrlObj().pathname).toBe('/api/cli/analytics/visitors');
+  });
+
+  it('getBuckets', async () => {
+    mockOk({ data: [], pagination: { total: 0 } });
+    await getBuckets({ dateFrom: '2024-01-01', dateTo: '2024-01-31' }, 'docs');
+    expect(calledUrlObj().pathname).toBe('/api/cli/analytics/conversations/buckets');
+    expect(calledUrlObj().searchParams.get('subdomain')).toBe('docs');
+  });
+
+  it('getBucketThreads', async () => {
+    mockOk({ data: [], pagination: { total: 0, hasMore: false, nextCursor: null } });
+    await getBucketThreads(
+      'bucket-123',
+      { dateFrom: '2024-01-01', limit: 25, cursor: 'next-thread' },
+      'docs'
+    );
+    expect(calledUrlObj().pathname).toBe('/api/cli/analytics/conversations/buckets/bucket-123');
+    expect(calledUrlObj().searchParams.get('subdomain')).toBe('docs');
+    expect(calledUrlObj().searchParams.get('limit')).toBe('25');
+    expect(calledUrlObj().searchParams.get('cursor')).toBe('next-thread');
+  });
+});

package/__test__/analytics/dates.test.ts

@@ -0,0 +1,12 @@
+import { formatLocalDate } from '../../src/analytics/dates.js';
+
+describe('formatLocalDate', () => {
+  it('formats the local calendar date without converting to UTC', () => {
+    const date = new Date(2024, 0, 2, 23, 30);
+    expect(formatLocalDate(date)).toBe('2024-01-02');
+  });
+
+  it('pads single-digit months and days', () => {
+    expect(formatLocalDate(new Date(2024, 8, 7))).toBe('2024-09-07');
+  });
+});

package/__test__/analytics/filters.test.ts

@@ -0,0 +1,116 @@
+import {
+  filterConversationResponse,
+  filterFeedbackByPageResponse,
+  filterFeedbackResponse,
+  filterSearchResponse,
+} from '../../src/analytics/filters.js';
+import type {
+  ConversationResponse,
+  FeedbackByPageResponse,
+  FeedbackResponse,
+  SearchResponse,
+} from '../../src/analytics/types.js';
+
+describe('analytics response filters', () => {
+  it('returns a search response whose JSON rows match query and page filters', () => {
+    const data: SearchResponse = {
+      searches: [
+        {
+          searchQuery: 'Deploy a site',
+          hits: 5,
+          ctr: 40,
+          topClickedPage: '/deploy',
+          lastSearchedAt: '2024-01-01T00:00:00Z',
+        },
+        {
+          searchQuery: 'Deploy locally',
+          hits: 3,
+          ctr: 20,
+          topClickedPage: '/development',
+          lastSearchedAt: '2024-01-02T00:00:00Z',
+        },
+        {
+          searchQuery: 'Authentication',
+          hits: 2,
+          ctr: 10,
+          topClickedPage: '/auth',
+          lastSearchedAt: '2024-01-03T00:00:00Z',
+        },
+      ],
+      totalSearches: 10,
+      nextCursor: null,
+    };
+
+    expect(filterSearchResponse(data, { query: 'deploy', page: '/deploy' }).searches).toEqual([
+      data.searches[0],
+    ]);
+  });
+
+  it('filters grouped feedback in the returned response', () => {
+    const data: FeedbackByPageResponse = {
+      feedback: [
+        { path: '/guide', thumbsUp: 1, thumbsDown: 0, code: 0, total: 1 },
+        { path: '/api', thumbsUp: 0, thumbsDown: 1, code: 0, total: 1 },
+      ],
+      hasMore: false,
+    };
+
+    expect(filterFeedbackByPageResponse(data, '/guide').feedback).toEqual([data.feedback[0]]);
+  });
+
+  it('filters individual feedback in the returned response', () => {
+    const data: FeedbackResponse = {
+      feedback: [
+        {
+          id: '1',
+          path: '/guide',
+          comment: null,
+          createdAt: null,
+          source: 'contextual',
+          status: 'pending',
+        },
+        {
+          id: '2',
+          path: '/api',
+          comment: null,
+          createdAt: null,
+          source: 'contextual',
+          status: 'pending',
+        },
+      ],
+      nextCursor: null,
+      hasMore: false,
+    };
+
+    expect(filterFeedbackResponse(data, '/guide').feedback).toEqual([data.feedback[0]]);
+  });
+
+  it('filters conversations in the returned response', () => {
+    const data: ConversationResponse = {
+      conversations: [
+        {
+          id: '1',
+          timestamp: '2024-01-01T00:00:00Z',
+          query: 'Guide question',
+          response: 'Answer',
+          sources: [{ title: 'Guide', url: 'https://docs.example.com/guide' }],
+          queryCategory: null,
+        },
+        {
+          id: '2',
+          timestamp: '2024-01-02T00:00:00Z',
+          query: 'API question',
+          response: 'Answer',
+          sources: [{ title: 'API', url: 'https://docs.example.com/api' }],
+          queryCategory: null,
+        },
+      ],
+      nextCursor: null,
+      hasMore: false,
+    };
+
+    expect(filterConversationResponse(data, '/guide').conversations).toEqual([
+      data.conversations[0],
+    ]);
+  });
+});

package/__test__/analytics/format.test.ts

@@ -0,0 +1,137 @@
+import { num, pct, truncate } from '../../src/analytics/format.js';
+import {
+  formatBarChart,
+  formatPlainTable,
+  formatPrettyTable,
+  resolveFormat,
+} from '../../src/analytics/output.js';
+import * as helpers from '../../src/helpers.js';
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('num', () => {
+  it('formats numbers with locale separators', () => {
+    expect(num(0)).toBe('0');
+    expect(num(1234)).toBe('1,234');
+    expect(num(1000000)).toBe('1,000,000');
+  });
+});
+
+describe('pct', () => {
+  it('returns percentage string', () => {
+    expect(pct(1, 4)).toBe('25.0%');
+    expect(pct(1, 3)).toBe('33.3%');
+  });
+
+  it('returns dash when total is zero', () => {
+    expect(pct(0, 0)).toBe('\u2014');
+  });
+});
+
+describe('truncate', () => {
+  it('returns short strings unchanged', () => {
+    expect(truncate('hello', 10)).toBe('hello');
+  });
+
+  it('truncates long strings with ellipsis', () => {
+    expect(truncate('hello world', 6)).toBe('hello\u2026');
+  });
+
+  it('returns string unchanged when exactly at max', () => {
+    expect(truncate('hello', 5)).toBe('hello');
+  });
+});
+
+describe('formatPrettyTable', () => {
+  it('returns dim message for empty rows', () => {
+    const result = formatPrettyTable(['A', 'B'], []);
+    expect(result).toContain('No data found');
+  });
+
+  it('formats headers and rows with aligned columns', () => {
+    const result = formatPrettyTable(
+      ['Name', 'Count'],
+      [
+        ['foo', '10'],
+        ['barbaz', '5'],
+      ]
+    );
+    const lines = result.split('\n');
+    expect(lines).toHaveLength(4);
+    expect(lines[2]).toContain('foo');
+    expect(lines[3]).toContain('barbaz');
+  });
+});
+
+describe('formatPlainTable', () => {
+  it('returns empty string for empty rows', () => {
+    expect(formatPlainTable(['A', 'B'], [])).toBe('');
+  });
+
+  it('formats with tab separation and uppercase headers', () => {
+    const result = formatPlainTable(
+      ['Name', 'Count'],
+      [
+        ['foo', '10'],
+        ['bar', '5'],
+      ]
+    );
+    const lines = result.split('\n');
+    expect(lines[0]).toContain('NAME');
+    expect(lines[0]).toContain('\t');
+    expect(lines[1]).toContain('foo');
+  });
+});
+
+describe('resolveFormat', () => {
+  it('returns json when AI mode is active', () => {
+    vi.spyOn(helpers, 'isAI').mockReturnValue(true);
+    expect(resolveFormat({})).toBe('json');
+  });
+
+  it('returns specified format', () => {
+    vi.spyOn(helpers, 'isAI').mockReturnValue(true);
+    expect(resolveFormat({ format: 'plain' })).toBe('plain');
+    expect(resolveFormat({ format: 'json' })).toBe('json');
+    expect(resolveFormat({ format: 'graph' })).toBe('graph');
+  });
+
+  it('defaults to plain', () => {
+    vi.spyOn(helpers, 'isAI').mockReturnValue(false);
+    expect(resolveFormat({})).toBe('plain');
+  });
+});
+
+describe('formatBarChart', () => {
+  it('returns dim message for empty items', () => {
+    expect(formatBarChart([])).toContain('No data found');
+  });
+
+  it('renders bars with labels and values', () => {
+    const result = formatBarChart([
+      { label: 'Foo', value: 10 },
+      { label: 'Bar', value: 5 },
+    ]);
+    const lines = result.split('\n');
+    expect(lines).toHaveLength(2);
+    expect(lines[0]).toContain('Foo');
+    expect(lines[0]).toContain('10');
+    expect(lines[0]).toContain('\u2588');
+    expect(lines[1]).toContain('Bar');
+    expect(lines[1]).toContain('5');
+  });
+
+  it('scales bars relative to max value', () => {
+    const result = formatBarChart([
+      { label: 'Big', value: 100 },
+      { label: 'Small', value: 10 },
+    ]);
+    const bigBar = result.split('\n')[0]!;
+    const smallBar = result.split('\n')[1]!;
+    const bigBlocks = (bigBar.match(/\u2588/g) || []).length;
+    const smallBlocks = (smallBar.match(/\u2588/g) || []).length;
+    expect(bigBlocks).toBeGreaterThan(smallBlocks);
+  });
+});

package/__test__/telemetry.test.ts

@@ -71,6 +71,33 @@ describe('getSanitizedCommandForTelemetry', () => {
     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'

package/__test__/welcome.test.ts

@@ -0,0 +1,15 @@
+import { renderWelcome } from '../src/welcome.js';
+
+describe('welcome help menu', () => {
+  it('lists the analytics command under Insights', () => {
+    const output = renderWelcome({
+      packageName: 'mint',
+      version: '1.0.0',
+      signedIn: true,
+    });
+
+    expect(output).toContain('Insights');
+    expect(output).toContain('analytics');
+    expect(output).toContain('View analytics for your site');
+  });
+});

package/bin/analytics/client.js

@@ -0,0 +1,60 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { authenticatedFetch } from '../authenticatedFetch.js';
+import { API_URL } from '../constants.js';
+function request(path_1) {
+    return __awaiter(this, arguments, void 0, function* (path, params = {}) {
+        const url = new URL(`${API_URL}/api/cli/analytics${path}`);
+        for (const [key, value] of Object.entries(params)) {
+            if (value !== undefined)
+                url.searchParams.set(key, String(value));
+        }
+        const res = yield authenticatedFetch(url.toString(), {
+            headers: { Accept: 'application/json' },
+        });
+        if (!res.ok) {
+            const body = yield res.text().catch(() => '');
+            throw new Error(`API error (${res.status}): ${body || res.statusText}`);
+        }
+        return res.json();
+    });
+}
+export function getKpi(opts, subdomain) {
+    return request('/kpi', Object.assign(Object.assign({}, opts), { subdomain }));
+}
+export function getFeedback(opts, subdomain) {
+    return request('/feedback', Object.assign(Object.assign({}, opts), { subdomain }));
+}
+export function getFeedbackByPage(opts, subdomain) {
+    return request('/feedback/by-page', Object.assign(Object.assign({}, opts), { subdomain }));
+}
+export function getConversations(opts, subdomain) {
+    return request('/assistant', Object.assign(Object.assign({}, opts), { subdomain }));
+}
+export function getAssistantThread(threadId, subdomain) {
+    return request(`/assistant/threads/${encodeURIComponent(threadId)}`, {
+        subdomain,
+    });
+}
+export function getSearches(opts, subdomain) {
+    return request('/searches', Object.assign(Object.assign({}, opts), { subdomain }));
+}
+export function getViews(opts, subdomain) {
+    return request('/views', Object.assign(Object.assign({}, opts), { subdomain }));
+}
+export function getVisitors(opts, subdomain) {
+    return request('/visitors', Object.assign(Object.assign({}, opts), { subdomain }));
+}
+export function getBuckets(opts, subdomain) {
+    return request('/conversations/buckets', Object.assign(Object.assign({}, opts), { subdomain }));
+}
+export function getBucketThreads(bucketId, opts, subdomain) {
+    return request(`/conversations/buckets/${encodeURIComponent(bucketId)}`, Object.assign(Object.assign({}, opts), { subdomain }));
+}

package/bin/analytics/dates.js

@@ -0,0 +1,6 @@
+export function formatLocalDate(date) {
+    const year = date.getFullYear();
+    const month = String(date.getMonth() + 1).padStart(2, '0');
+    const day = String(date.getDate()).padStart(2, '0');
+    return `${year}-${month}-${day}`;
+}

package/bin/analytics/filters.js

@@ -0,0 +1,27 @@
+export function filterSearchResponse(data, filters) {
+    let searches = data.searches;
+    if (filters.query) {
+        const query = filters.query.toLowerCase();
+        searches = searches.filter((row) => row.searchQuery.toLowerCase().includes(query));
+    }
+    const page = filters.page;
+    if (page) {
+        searches = searches.filter((row) => { var _a; return (_a = row.topClickedPage) === null || _a === void 0 ? void 0 : _a.includes(page); });
+    }
+    return Object.assign(Object.assign({}, data), { searches });
+}
+export function filterFeedbackByPageResponse(data, page) {
+    if (!page)
+        return data;
+    return Object.assign(Object.assign({}, data), { feedback: data.feedback.filter((row) => row.path.includes(page)) });
+}
+export function filterFeedbackResponse(data, page) {
+    if (!page)
+        return data;
+    return Object.assign(Object.assign({}, data), { feedback: data.feedback.filter((row) => row.path.includes(page)) });
+}
+export function filterConversationResponse(data, page) {
+    if (!page)
+        return data;
+    return Object.assign(Object.assign({}, data), { conversations: data.conversations.filter((conversation) => conversation.sources.some((source) => source.url.includes(page))) });
+}

package/bin/analytics/format.js

@@ -0,0 +1,13 @@
+export function num(n) {
+    return n.toLocaleString('en-US');
+}
+export function pct(n, total) {
+    if (total === 0)
+        return '\u2014';
+    return ((n / total) * 100).toFixed(1) + '%';
+}
+export function truncate(s, max) {
+    if (s.length <= max)
+        return s;
+    return s.slice(0, max - 1) + '\u2026';
+}