@mintlify/cli 4.0.1084 → 4.0.1085

package/__test__/analytics/client.test.ts

@@ -0,0 +1,158 @@
+import {
+  getFeedback,
+  getFeedbackByPage,
+  getBuckets,
+  getBucketThreads,
+  getConversations,
+  getKpi,
+  getSearches,
+  getViews,
+  getVisitors,
+} from '../../src/analytics/client.js';
+
+vi.mock('../../src/keyring.js', () => ({
+  getAccessToken: vi.fn().mockResolvedValue(null),
+}));
+
+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,
+    json: () => Promise.resolve(data),
+  });
+}
+
+function mockError(status: number, body: string) {
+  mockFetch.mockResolvedValueOnce({
+    ok: false,
+    status,
+    statusText: 'Bad Request',
+    text: () => Promise.resolve(body),
+  });
+}
+
+function calledUrl(): URL {
+  return mockFetch.mock.calls[0]![0] as URL;
+}
+
+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(URL),
+      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(calledUrl().searchParams.get('subdomain')).toBe('my-docs');
+    expect(calledUrl().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(calledUrl().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(calledUrl().searchParams.get('dateFrom')).toBe('2024-01-01');
+    expect(calledUrl().searchParams.get('limit')).toBe('10');
+    expect(calledUrl().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(calledUrl().pathname).toBe('/api/cli/analytics/kpi');
+    expect(calledUrl().searchParams.get('subdomain')).toBe('docs');
+  });
+
+  it('getFeedbackByPage', async () => {
+    mockOk({ feedback: [], hasMore: false });
+    await getFeedbackByPage({ dateFrom: '2024-01-01', dateTo: '2024-01-31' }, 'docs');
+    expect(calledUrl().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(calledUrl().pathname).toBe('/api/cli/analytics/assistant');
+  });
+
+  it('getSearches', async () => {
+    mockOk({ searches: [], totalSearches: 0, nextCursor: null });
+    await getSearches({ dateFrom: '2024-01-01', dateTo: '2024-01-31' }, 'docs');
+    expect(calledUrl().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(calledUrl().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(calledUrl().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(calledUrl().pathname).toBe('/api/cli/analytics/conversations/buckets');
+    expect(calledUrl().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' }, 'docs');
+    expect(calledUrl().pathname).toBe('/api/cli/analytics/conversations/buckets/bucket-123');
+    expect(calledUrl().searchParams.get('subdomain')).toBe('docs');
+  });
+});

package/__test__/analytics/format.test.ts

@@ -0,0 +1,139 @@
+import { num, pct, truncate } from '../../src/analytics/format.js';
+import {
+  formatBarChart,
+  formatPlainTable,
+  formatPrettyTable,
+  resolveFormat,
+} from '../../src/analytics/output.js';
+
+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 agent flag is set', () => {
+    expect(resolveFormat({ agent: true })).toBe('json');
+  });
+
+  it('returns json when CLAUDECODE env is set', () => {
+    const prev = process.env.CLAUDECODE;
+    process.env.CLAUDECODE = '1';
+    expect(resolveFormat({})).toBe('json');
+    process.env.CLAUDECODE = prev;
+  });
+
+  it('returns specified format', () => {
+    expect(resolveFormat({ format: 'plain' })).toBe('plain');
+    expect(resolveFormat({ format: 'json' })).toBe('json');
+    expect(resolveFormat({ format: 'graph' })).toBe('graph');
+  });
+
+  it('defaults to plain', () => {
+    const prev = process.env.CLAUDECODE;
+    delete process.env.CLAUDECODE;
+    expect(resolveFormat({})).toBe('plain');
+    process.env.CLAUDECODE = prev;
+  });
+});
+
+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/bin/analytics/client.js

@@ -0,0 +1,73 @@
+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());
+    });
+};
+var _a;
+const API_BASE = (_a = process.env.MINTLIFY_API_URL) !== null && _a !== void 0 ? _a : 'http://localhost:5000';
+function getAuthHeaders() {
+    return __awaiter(this, void 0, void 0, function* () {
+        try {
+            const { getAccessToken } = yield import('../keyring.js');
+            const token = yield getAccessToken();
+            if (token) {
+                return { Authorization: `Bearer ${token}` };
+            }
+        }
+        catch (_a) { }
+        const envToken = process.env.MINTLIFY_SESSION_TOKEN;
+        if (envToken) {
+            return { Authorization: `Bearer ${envToken}` };
+        }
+        throw new Error('Not authenticated. Run `mint login` to authenticate.');
+    });
+}
+function request(path_1) {
+    return __awaiter(this, arguments, void 0, function* (path, params = {}) {
+        const url = new URL(`${API_BASE}/api/cli/analytics${path}`);
+        for (const [key, value] of Object.entries(params)) {
+            if (value !== undefined)
+                url.searchParams.set(key, String(value));
+        }
+        const authHeaders = yield getAuthHeaders();
+        const res = yield fetch(url, {
+            headers: Object.assign(Object.assign({}, authHeaders), { 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 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/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';
+}