@mintlify/cli 4.0.1083 → 4.0.1085

package/src/analytics/output.ts

@@ -0,0 +1,97 @@
+import chalk from 'chalk';
+
+export type OutputFormat = 'table' | 'plain' | 'json' | 'graph';
+
+export function resolveFormat(argv: { format?: string; agent?: boolean }): OutputFormat {
+  if (argv.agent || process.env.CLAUDECODE === '1') return 'json';
+  if (
+    argv.format === 'table' ||
+    argv.format === 'plain' ||
+    argv.format === 'json' ||
+    argv.format === 'graph'
+  )
+    return argv.format;
+  return 'plain';
+}
+
+export function formatPlainTable(headers: string[], rows: string[][]): string {
+  if (rows.length === 0) return '';
+
+  const colWidths = headers.map((h, i) =>
+    Math.max(h.length, ...rows.map((r) => (r[i] ?? '').length))
+  );
+
+  const headerLine = headers.map((h, i) => h.toUpperCase().padEnd(colWidths[i]!)).join('\t');
+  const bodyLines = rows.map((row) => row.map((cell, i) => cell.padEnd(colWidths[i]!)).join('\t'));
+
+  return [headerLine, ...bodyLines].join('\n');
+}
+
+export function formatPrettyTable(headers: string[], rows: string[][]): string {
+  if (rows.length === 0) return chalk.dim('  No data found.');
+
+  const colWidths = headers.map((h, i) =>
+    Math.max(h.length, ...rows.map((r) => (r[i] ?? '').length))
+  );
+
+  const headerLine = headers.map((h, i) => chalk.bold(h.padEnd(colWidths[i]!))).join('  ');
+  const separator = chalk.dim(colWidths.map((w) => '\u2500'.repeat(w)).join('\u2500\u2500'));
+  const bodyLines = rows.map((row) => row.map((cell, i) => cell.padEnd(colWidths[i]!)).join('  '));
+
+  return [headerLine, separator, ...bodyLines].join('\n');
+}
+
+function gradientBar(len: number, rgb: [number, number, number]): string {
+  let result = '';
+  for (let i = 0; i < len; i++) {
+    const t = len === 1 ? 1 : i / (len - 1);
+    const dim = 0.3 + t * 0.7;
+    const r = Math.round(rgb[0] * dim);
+    const g = Math.round(rgb[1] * dim);
+    const b = Math.round(rgb[2] * dim);
+    result += chalk.rgb(r, g, b)('\u2588');
+  }
+  return result;
+}
+
+const COLOR_MAP: Record<string, [number, number, number]> = {
+  cyan: [0, 255, 255],
+  magenta: [255, 0, 255],
+  yellow: [255, 255, 0],
+  green: [0, 255, 100],
+  blue: [80, 140, 255],
+  red: [255, 80, 80],
+};
+
+export function formatBarChart(
+  items: { label: string; value: number; color?: string }[],
+  opts: { maxWidth?: number } = {}
+): string {
+  if (items.length === 0) return chalk.dim('  No data found.');
+
+  const maxWidth = opts.maxWidth ?? 40;
+  const maxVal = Math.max(...items.map((i) => i.value), 1);
+  const maxLabel = Math.max(...items.map((i) => i.label.length));
+  const maxValStr = Math.max(...items.map((i) => i.value.toLocaleString('en-US').length));
+
+  return items
+    .map((item) => {
+      const barLen = Math.round((item.value / maxVal) * maxWidth);
+      const rgb = COLOR_MAP[item.color ?? 'cyan'] ?? COLOR_MAP.cyan!;
+      const bar = barLen > 0 ? gradientBar(barLen, rgb) : '';
+      const pad = ' '.repeat(maxWidth - barLen);
+      return `  ${item.label.padEnd(maxLabel)}  ${bar}${pad} ${item.value.toLocaleString('en-US').padStart(maxValStr)}`;
+    })
+    .join('\n');
+}
+
+export function formatOutput(
+  format: OutputFormat,
+  headers: string[],
+  rows: string[][],
+  jsonData: unknown
+): string {
+  if (format === 'json') return JSON.stringify(jsonData, null, 2);
+  if (format === 'plain') return formatPlainTable(headers, rows);
+  return formatPrettyTable(headers, rows);
+}

package/src/analytics/types.ts

@@ -0,0 +1,132 @@
+export interface KpiResponse {
+  humanVisitors: number;
+  humanViews: number;
+  humanAssistant: number;
+  humanSearches: number;
+  humanFeedback: number;
+  agentVisitors: number;
+  agentViews: number;
+  agentMcpSearches: number;
+}
+
+export interface BucketSummary {
+  id: string;
+  questionSummary: string;
+  size: number;
+  status: string;
+  lastAsked: string | null;
+  lastOccurredAt: string | null;
+  createdAt: string;
+}
+
+export interface BucketsResponse {
+  data: BucketSummary[];
+  pagination: { total: number };
+}
+
+export interface BucketThread {
+  id: string;
+  firstUserMessage: string | null;
+  feedback: { up: number; down: number };
+  resolutionStatus: string | null;
+  length: number;
+  createdAt: string;
+  lastMessageAt: string | null;
+}
+
+export interface BucketThreadsResponse {
+  data: BucketThread[];
+  pagination: { total: number; hasMore: boolean; nextCursor: string | null };
+}
+
+export interface FeedbackItem {
+  id: string;
+  path: string;
+  comment: string | null;
+  createdAt: string | null;
+  source: string;
+  status: string;
+  helpful?: boolean;
+  contact?: string;
+  code?: string;
+  filename?: string;
+  lang?: string;
+}
+
+export interface FeedbackResponse {
+  feedback: FeedbackItem[];
+  nextCursor: string | null;
+  hasMore: boolean;
+}
+
+export interface FeedbackByPageItem {
+  path: string;
+  thumbsUp: number;
+  thumbsDown: number;
+  code: number;
+  total: number;
+}
+
+export interface FeedbackByPageResponse {
+  feedback: FeedbackByPageItem[];
+  hasMore: boolean;
+}
+
+export interface ConversationSource {
+  title: string;
+  url: string;
+}
+
+export interface Conversation {
+  id: string;
+  timestamp: string;
+  query: string;
+  response: string;
+  sources: ConversationSource[];
+  queryCategory: string | null;
+}
+
+export interface ConversationResponse {
+  conversations: Conversation[];
+  nextCursor: string | null;
+  hasMore: boolean;
+}
+
+export interface SearchRow {
+  searchQuery: string;
+  hits: number;
+  ctr: number;
+  topClickedPage: string | null;
+  lastSearchedAt: string;
+}
+
+export interface SearchResponse {
+  searches: SearchRow[];
+  totalSearches: number;
+  nextCursor: string | null;
+}
+
+export interface TrafficTotals {
+  human: number;
+  ai: number;
+  total: number;
+}
+
+export interface TrafficRow {
+  path: string;
+  human: number;
+  ai: number;
+  total: number;
+}
+
+export interface ViewsResponse {
+  totals: TrafficTotals;
+  views: TrafficRow[];
+  hasMore: boolean;
+}
+
+export interface VisitorsResponse {
+  totals: TrafficTotals;
+  visitors: TrafficRow[];
+  hasMore: boolean;
+}

package/src/cli.tsx

@@ -19,7 +19,9 @@ import yargs from 'yargs';
 import { hideBin } from 'yargs/helpers';
 
 import { accessibilityCheck } from './accessibilityCheck.js';
+import { analyticsBuilder } from './analytics/index.js';
 import { setTelemetryEnabled } from './config.js';
+import { getConfigValue, setConfigValue, clearConfigValue } from './config.js';
 import { CMD_EXEC_PATH } from './constants.js';
 import {
   checkPort,
@@ -340,6 +342,91 @@ export const cli = ({ packageName = 'mint' }: { packageName?: string }) => {
           await terminate(0);
         }
       )
+      .command('config', 'manage CLI configuration', (yargs) =>
+        yargs
+          .command(
+            'set <key> <value>',
+            'set a configuration value',
+            (yargs) =>
+              yargs
+                .positional('key', {
+                  type: 'string',
+                  demandOption: true,
+                  description: 'Config key (e.g. subdomain)',
+                })
+                .positional('value', {
+                  type: 'string',
+                  demandOption: true,
+                  description: 'Config value',
+                }),
+            async (argv) => {
+              const validKeys = ['subdomain', 'dateFrom', 'dateTo'];
+              if (!validKeys.includes(argv.key)) {
+                addLog(
+                  <ErrorLog
+                    message={`Unknown config key: "${argv.key}". Valid keys: ${validKeys.join(', ')}`}
+                  />
+                );
+                await terminate(1);
+                return;
+              }
+              await setConfigValue(argv.key, argv.value);
+              addLog(<SuccessLog message={`${argv.key} = "${argv.value}"`} />);
+              await terminate(0);
+            }
+          )
+          .command(
+            'get <key>',
+            'get a configuration value',
+            (yargs) =>
+              yargs.positional('key', {
+                type: 'string',
+                demandOption: true,
+                description: 'Config key (e.g. subdomain, dateFrom, dateTo)',
+              }),
+            async (argv) => {
+              const validKeys = ['subdomain', 'dateFrom', 'dateTo'];
+              if (!validKeys.includes(argv.key)) {
+                addLog(
+                  <ErrorLog
+                    message={`Unknown config key: "${argv.key}". Valid keys: ${validKeys.join(', ')}`}
+                  />
+                );
+                await terminate(1);
+                return;
+              }
+              const val = getConfigValue(argv.key);
+              addLog(<Text>{val ?? 'not set'}</Text>);
+              await terminate(0);
+            }
+          )
+          .command(
+            'clear <key>',
+            'remove a configuration value',
+            (yargs) =>
+              yargs.positional('key', {
+                type: 'string',
+                demandOption: true,
+                description: 'Config key (e.g. subdomain, dateFrom, dateTo)',
+              }),
+            async (argv) => {
+              const validKeys = ['subdomain', 'dateFrom', 'dateTo'];
+              if (!validKeys.includes(argv.key)) {
+                addLog(
+                  <ErrorLog
+                    message={`Unknown config key: "${argv.key}". Valid keys: ${validKeys.join(', ')}`}
+                  />
+                );
+                await terminate(1);
+                return;
+              }
+              await clearConfigValue(argv.key);
+              addLog(<SuccessLog message={`${argv.key} cleared`} />);
+              await terminate(0);
+            }
+          )
+          .demandCommand(1, 'specify a subcommand: set, get, or clear')
+      )
       .command(
         'update',
         'update the CLI to the latest version',
@@ -463,6 +550,7 @@ export const cli = ({ packageName = 'mint' }: { packageName?: string }) => {
           }
         }
       )
+      .command('analytics', 'view analytics for your documentation', analyticsBuilder)
       // Print the help menu when the user enters an invalid command.
       .strictCommands()
       .demandCommand(1, 'unknown command. see above for the list of supported commands.')

package/src/config.ts

@@ -5,6 +5,9 @@ import { CLI_CONFIG_FILE, CONFIG_DIR } from './constants.js';
 
 interface MintlifyConfig {
   telemetryEnabled?: boolean;
+  subdomain?: string;
+  dateFrom?: string;
+  dateTo?: string;
 }
 
 function readConfig(): MintlifyConfig {
@@ -32,3 +35,16 @@ export function isTelemetryEnabled(): boolean {
 export async function setTelemetryEnabled(enabled: boolean): Promise<void> {
   await writeConfig({ telemetryEnabled: enabled });
 }
+
+export function getConfigValue(key: string): string | undefined {
+  const config = readConfig();
+  return config[key as keyof MintlifyConfig] as string | undefined;
+}
+
+export async function setConfigValue(key: string, value: string): Promise<void> {
+  await writeConfig({ [key]: value });
+}
+
+export async function clearConfigValue(key: string): Promise<void> {
+  await writeConfig({ [key]: undefined });
+}

package/src/keyring.ts

@@ -4,7 +4,9 @@ const REFRESH_TOKEN_ACCOUNT = 'refresh_token';
 
 async function getKeytar(): Promise<typeof import('keytar')> {
   try {
-    return await import('keytar');
+    const mod = await import('keytar');
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- ESM wraps CJS in { default: ... } at runtime despite types
+    return mod.default ?? mod;
   } catch {
     throw new Error(
       'keytar is required for credential storage but is not installed. Install it with: npm install keytar'