@optima-chat/bi-cli 0.3.3 → 0.3.5

package/src/commands/traffic.ts

@@ -0,0 +1,454 @@
+import { Command } from 'commander';
+import axios from 'axios';
+import { getConfig } from '../config/index.js';
+import { outputJson, outputPretty, error, OutputFormat } from '../utils/output.js';
+
+interface TrafficOverview {
+  period: {
+    start: string;
+    end: string;
+    days: number;
+  };
+  summary: {
+    page_views: number;
+    unique_visitors: number;
+    sessions: number;
+    avg_session_duration: number;
+    bounce_rate: number;
+  };
+  comparison: {
+    page_views_change: number;
+    unique_visitors_change: number;
+    sessions_change: number;
+  };
+}
+
+interface TrafficSource {
+  source: string;
+  medium: string;
+  visitors: number;
+  page_views: number;
+  percentage: number;
+}
+
+interface FunnelStep {
+  step: string;
+  count: number;
+  rate: number;
+  conversion: number;
+}
+
+interface SearchItem {
+  query: string;
+  count: number;
+  unique_searchers: number;
+  avg_results: number;
+  click_rate: number;
+}
+
+interface PageItem {
+  path: string;
+  page_views: number;
+  unique_visitors: number;
+  sessions: number;
+}
+
+function formatPercent(value: number): string {
+  return `${(value * 100).toFixed(1)}%`;
+}
+
+function formatChange(value: number): string {
+  const sign = value >= 0 ? '+' : '';
+  return `${sign}${(value * 100).toFixed(1)}%`;
+}
+
+function formatDuration(seconds: number): string {
+  const mins = Math.floor(seconds / 60);
+  const secs = seconds % 60;
+  return mins > 0 ? `${mins}m ${secs}s` : `${secs}s`;
+}
+
+export function createTrafficCommand(): Command {
+  const traffic = new Command('traffic').description(
+    `Traffic analytics.
+
+Analyze website visits, traffic sources, conversion funnels, search keywords.`
+  );
+
+  // traffic overview
+  traffic
+    .command('overview')
+    .description(
+      `Traffic overview.
+
+Get page views, unique visitors, sessions, and comparison with previous period.
+
+Returns JSON:
+{
+  "period": { "start": "2024-01-01", "end": "2024-01-30", "days": 30 },
+  "summary": {
+    "page_views": 10000,
+    "unique_visitors": 3000,
+    "sessions": 5000,
+    "avg_session_duration": 180,  // seconds
+    "bounce_rate": 0.35           // 35%
+  },
+  "comparison": {
+    "page_views_change": 0.15,    // +15%
+    "unique_visitors_change": 0.10
+  }
+}
+
+Examples:
+  bi-cli traffic overview                     # Last 30 days, all pages
+  bi-cli traffic overview --days 7            # Last 7 days
+  bi-cli traffic overview --product <uuid>    # Filter by product`
+    )
+    .option('--days <number>', 'Number of days (range: 1-365, default: 30)', '30')
+    .option('--product <id>', 'Filter by product ID (UUID format)')
+    .option('--pretty', 'Output as table (default: JSON)')
+    .action(async (options) => {
+      const cfg = getConfig();
+
+      if (!cfg.accessToken) {
+        error('Not logged in. Run: bi-cli auth login');
+        process.exit(1);
+      }
+
+      const days = parseInt(options.days, 10);
+      if (isNaN(days) || days < 1 || days > 365) {
+        error('Days must be between 1 and 365');
+        process.exit(1);
+      }
+
+      const format = options.pretty ? OutputFormat.PRETTY : OutputFormat.JSON;
+
+      try {
+        const response = await axios.get<TrafficOverview>(
+          `${cfg.backendUrl}/api/v1/analytics/traffic/overview`,
+          {
+            params: { days, product_id: options.product },
+            headers: { Authorization: `Bearer ${cfg.accessToken}` },
+          }
+        );
+
+        const data = response.data;
+
+        if (format === OutputFormat.JSON) {
+          outputJson(data);
+        } else {
+          console.log('\n📊 Traffic Overview\n');
+          console.log(
+            `Period: ${data.period.start} to ${data.period.end} (${data.period.days} days)\n`
+          );
+
+          outputPretty({
+            'Page Views': `${data.summary.page_views.toLocaleString()} (${formatChange(data.comparison.page_views_change)})`,
+            'Unique Visitors': `${data.summary.unique_visitors.toLocaleString()} (${formatChange(data.comparison.unique_visitors_change)})`,
+            Sessions: `${data.summary.sessions.toLocaleString()} (${formatChange(data.comparison.sessions_change)})`,
+            'Avg Session Duration': formatDuration(data.summary.avg_session_duration),
+            'Bounce Rate': formatPercent(data.summary.bounce_rate),
+          });
+        }
+      } catch (err: unknown) {
+        handleError(err);
+      }
+    });
+
+  // traffic sources
+  traffic
+    .command('sources')
+    .description(
+      `Traffic source analysis.
+
+Analyze visitor sources (Google, WeChat, direct, etc.).
+
+Returns JSON:
+{
+  "sources": [
+    {
+      "source": "google",
+      "medium": "organic",
+      "visitors": 1000,
+      "page_views": 3000,
+      "percentage": 0.35  // 35%
+    }
+  ]
+}
+
+Use case: Evaluate channel effectiveness, optimize marketing spend.`
+    )
+    .option('--days <number>', 'Number of days (default: 30)', '30')
+    .option('--limit <number>', 'Number of results (default: 10)', '10')
+    .option('--pretty', 'Output as table (default: JSON)')
+    .action(async (options) => {
+      const cfg = getConfig();
+
+      if (!cfg.accessToken) {
+        error('Not logged in. Run: bi-cli auth login');
+        process.exit(1);
+      }
+
+      const days = parseInt(options.days, 10);
+      const limit = parseInt(options.limit, 10);
+      const format = options.pretty ? OutputFormat.PRETTY : OutputFormat.JSON;
+
+      try {
+        const response = await axios.get<{ sources: TrafficSource[] }>(
+          `${cfg.backendUrl}/api/v1/analytics/traffic/sources`,
+          {
+            params: { days, limit },
+            headers: { Authorization: `Bearer ${cfg.accessToken}` },
+          }
+        );
+
+        const { sources } = response.data;
+
+        if (format === OutputFormat.JSON) {
+          outputJson(response.data);
+        } else {
+          console.log('\n🔗 Traffic Sources\n');
+          outputPretty(
+            sources.map((s) => ({
+              Source: s.source,
+              Medium: s.medium,
+              Visitors: s.visitors.toLocaleString(),
+              'Page Views': s.page_views.toLocaleString(),
+              Share: formatPercent(s.percentage),
+            })),
+            ['Source', 'Medium', 'Visitors', 'Page Views', 'Share']
+          );
+        }
+      } catch (err: unknown) {
+        handleError(err);
+      }
+    });
+
+  // traffic funnel
+  traffic
+    .command('funnel')
+    .description(
+      `Conversion funnel analysis.
+
+Analyze user journey from visit to purchase:
+  Visit → View Product → Add to Cart → Checkout → Purchase
+
+Returns JSON:
+{
+  "funnel": [
+    { "step": "page_view", "count": 10000, "rate": 1.0, "conversion": 1.0 },
+    { "step": "product_view", "count": 5000, "rate": 0.5, "conversion": 0.5 },
+    { "step": "add_to_cart", "count": 1000, "rate": 0.1, "conversion": 0.2 },
+    { "step": "checkout", "count": 500, "rate": 0.05, "conversion": 0.5 },
+    { "step": "purchase", "count": 300, "rate": 0.03, "conversion": 0.6 }
+  ]
+}
+
+Note: rate = ratio from start, conversion = conversion from previous step.`
+    )
+    .option('--days <number>', 'Number of days (default: 30)', '30')
+    .option('--product <id>', 'Filter by product ID (UUID format)')
+    .option('--pretty', 'Output as table (default: JSON)')
+    .action(async (options) => {
+      const cfg = getConfig();
+
+      if (!cfg.accessToken) {
+        error('Not logged in. Run: bi-cli auth login');
+        process.exit(1);
+      }
+
+      const days = parseInt(options.days, 10);
+      const format = options.pretty ? OutputFormat.PRETTY : OutputFormat.JSON;
+
+      try {
+        const response = await axios.get<{ funnel: FunnelStep[] }>(
+          `${cfg.backendUrl}/api/v1/analytics/traffic/funnel`,
+          {
+            params: { days, product_id: options.product },
+            headers: { Authorization: `Bearer ${cfg.accessToken}` },
+          }
+        );
+
+        const { funnel } = response.data;
+
+        if (format === OutputFormat.JSON) {
+          outputJson(response.data);
+        } else {
+          console.log('\n🔻 Conversion Funnel\n');
+          outputPretty(
+            funnel.map((f) => ({
+              Step: f.step.replace(/_/g, ' '),
+              Users: f.count.toLocaleString(),
+              'From Start': formatPercent(f.rate),
+              Conversion: formatPercent(f.conversion),
+            })),
+            ['Step', 'Users', 'From Start', 'Conversion']
+          );
+        }
+      } catch (err: unknown) {
+        handleError(err);
+      }
+    });
+
+  // traffic search
+  traffic
+    .command('search')
+    .description(
+      `Site search analytics.
+
+Analyze search keywords, result counts, and click-through rates.
+
+Returns JSON:
+{
+  "searches": [
+    { "query": "dress", "count": 500, "avg_results": 25, "click_rate": 0.65 }
+  ],
+  "zero_results": [
+    { "query": "nonexistent product", "count": 10 }
+  ]
+}
+
+Use case: Optimize product titles, add missing products, improve search.`
+    )
+    .option('--days <number>', 'Number of days (default: 30)', '30')
+    .option('--limit <number>', 'Number of results (default: 20)', '20')
+    .option('--zero-results', 'Show only zero-result queries')
+    .option('--pretty', 'Output as table (default: JSON)')
+    .action(async (options) => {
+      const cfg = getConfig();
+
+      if (!cfg.accessToken) {
+        error('Not logged in. Run: bi-cli auth login');
+        process.exit(1);
+      }
+
+      const days = parseInt(options.days, 10);
+      const limit = parseInt(options.limit, 10);
+      const format = options.pretty ? OutputFormat.PRETTY : OutputFormat.JSON;
+
+      try {
+        const response = await axios.get<{
+          searches: SearchItem[];
+          zero_results: { query: string; count: number }[];
+        }>(`${cfg.backendUrl}/api/v1/analytics/traffic/search`, {
+          params: { days, limit, zero_results: options.zeroResults },
+          headers: { Authorization: `Bearer ${cfg.accessToken}` },
+        });
+
+        const { searches, zero_results } = response.data;
+
+        if (format === OutputFormat.JSON) {
+          outputJson(response.data);
+        } else {
+          console.log('\n🔍 Top Searches\n');
+          outputPretty(
+            searches.map((s) => ({
+              Query: s.query,
+              Searches: s.count.toLocaleString(),
+              'Avg Results': s.avg_results,
+              'Click Rate': formatPercent(s.click_rate),
+            })),
+            ['Query', 'Searches', 'Avg Results', 'Click Rate']
+          );
+
+          if (zero_results.length > 0) {
+            console.log('\n❌ Zero Results Queries\n');
+            outputPretty(
+              zero_results.map((z) => ({
+                Query: z.query,
+                Count: z.count.toLocaleString(),
+              })),
+              ['Query', 'Count']
+            );
+          }
+        }
+      } catch (err: unknown) {
+        handleError(err);
+      }
+    });
+
+  // traffic pages
+  traffic
+    .command('pages')
+    .description(
+      `Top pages analysis.
+
+View most popular pages sorted by page views.
+
+Returns JSON:
+{
+  "pages": [
+    {
+      "path": "/products/xxx",
+      "page_views": 5000,
+      "unique_visitors": 2000,
+      "sessions": 3000
+    }
+  ]
+}
+
+Use case: Understand browsing patterns, optimize popular page experience.`
+    )
+    .option('--days <number>', 'Number of days (default: 30)', '30')
+    .option('--limit <number>', 'Number of results (default: 20)', '20')
+    .option('--pretty', 'Output as table (default: JSON)')
+    .action(async (options) => {
+      const cfg = getConfig();
+
+      if (!cfg.accessToken) {
+        error('Not logged in. Run: bi-cli auth login');
+        process.exit(1);
+      }
+
+      const days = parseInt(options.days, 10);
+      const limit = parseInt(options.limit, 10);
+      const format = options.pretty ? OutputFormat.PRETTY : OutputFormat.JSON;
+
+      try {
+        const response = await axios.get<{ pages: PageItem[] }>(
+          `${cfg.backendUrl}/api/v1/analytics/traffic/pages`,
+          {
+            params: { days, limit },
+            headers: { Authorization: `Bearer ${cfg.accessToken}` },
+          }
+        );
+
+        const { pages } = response.data;
+
+        if (format === OutputFormat.JSON) {
+          outputJson(response.data);
+        } else {
+          console.log('\n📄 Top Pages\n');
+          outputPretty(
+            pages.map((p) => ({
+              Path: p.path.length > 40 ? p.path.substring(0, 37) + '...' : p.path,
+              'Page Views': p.page_views.toLocaleString(),
+              Visitors: p.unique_visitors.toLocaleString(),
+              Sessions: p.sessions.toLocaleString(),
+            })),
+            ['Path', 'Page Views', 'Visitors', 'Sessions']
+          );
+        }
+      } catch (err: unknown) {
+        handleError(err);
+      }
+    });
+
+  return traffic;
+}
+
+function handleError(err: unknown): never {
+  const axiosError = err as {
+    response?: { status?: number; data?: { error?: string } };
+  };
+  const errorObj = err as Error;
+
+  if (axiosError.response?.status === 401) {
+    error('Authentication failed. Please login again: bi-cli auth login');
+  } else if (axiosError.response?.data?.error) {
+    error(`Error: ${axiosError.response.data.error}`);
+  } else {
+    error(`Request failed: ${errorObj.message || 'Unknown error'}`);
+  }
+  process.exit(1);
+}

package/src/commands/trends.ts

@@ -78,15 +78,39 @@ interface ForecastResponse {
 }
 
 export function createTrendsCommand(): Command {
-  const trends = new Command('trends').description('Trend analytics');
+  const trends = new Command('trends').description(
+    `Trend analytics.
+
+Analyze revenue trends, order heatmaps, seasonality, and forecasts.`
+  );
 
   // trends revenue
   trends
     .command('revenue')
-    .description('Get revenue trend over time')
-    .option('--days <number>', 'Number of days', '30')
-    .option('--granularity <type>', 'Granularity: hourly, daily, weekly', 'daily')
-    .option('--pretty', 'Output in pretty table format')
+    .description(
+      `Revenue trend analysis.
+
+View revenue over time with hourly/daily/weekly aggregation and 7-day moving average.
+
+Returns JSON:
+{
+  "statistics": {
+    "total_revenue": number,
+    "avg_revenue": number,
+    "trend_direction": "up" | "down" | "stable"
+  },
+  "trend": [
+    { "period": "2024-01-01", "revenue": 1000, "orders": 50, "moving_avg_7": 950 }
+  ]
+}
+
+Examples:
+  bi-cli trends revenue                        # Last 30 days, daily
+  bi-cli trends revenue --days 7 --granularity hourly  # Last 7 days, hourly`
+    )
+    .option('--days <number>', 'Number of days (default: 30)', '30')
+    .option('--granularity <type>', 'Time granularity: hourly | daily | weekly', 'daily')
+    .option('--pretty', 'Output as table')
     .action(async (options) => {
       const cfg = getConfig();
       if (!cfg.accessToken) {
@@ -152,9 +176,25 @@ export function createTrendsCommand(): Command {
   // trends heatmap
   trends
     .command('heatmap')
-    .description('Orders heatmap by day and hour')
-    .option('--days <number>', 'Number of days', '30')
-    .option('--pretty', 'Output in pretty table format')
+    .description(
+      `Orders heatmap by day and hour.
+
+Analyze order distribution by day of week and hour to find peak times.
+
+Returns JSON:
+{
+  "heatmap": [
+    { "day": "Monday", "hours": [ { "hour": 10, "orders": 15, "revenue": 500 }, ... ] }
+  ],
+  "peak_times": [
+    { "day": "Saturday", "hour": "14:00-15:00", "orders": 25 }
+  ]
+}
+
+Use case: Optimize marketing timing, schedule customer service staff.`
+    )
+    .option('--days <number>', 'Number of days (default: 30)', '30')
+    .option('--pretty', 'Output as table')
     .action(async (options) => {
       const cfg = getConfig();
       if (!cfg.accessToken) {
@@ -221,8 +261,26 @@ export function createTrendsCommand(): Command {
   // trends seasonality
   trends
     .command('seasonality')
-    .description('Monthly/seasonal patterns')
-    .option('--pretty', 'Output in pretty table format')
+    .description(
+      `Monthly/seasonal pattern analysis.
+
+Analyze sales by month to identify peak and low seasons.
+
+Returns JSON:
+{
+  "monthly_pattern": [
+    { "month": 1, "month_name": "January", "revenue": 50000, "orders": 500, "index": 120 }
+  ],
+  "insights": {
+    "peak_months": ["December", "November"],
+    "low_months": ["February"],
+    "avg_monthly_revenue": 45000
+  }
+}
+
+Note: index is percentage relative to average (>100 = above average).`
+    )
+    .option('--pretty', 'Output as table')
     .action(async (options) => {
       const cfg = getConfig();
       if (!cfg.accessToken) {
@@ -277,9 +335,28 @@ export function createTrendsCommand(): Command {
   // trends forecast
   trends
     .command('forecast')
-    .description('Revenue forecast')
-    .option('--days <number>', 'Number of days to forecast', '7')
-    .option('--pretty', 'Output in pretty table format')
+    .description(
+      `Revenue forecast.
+
+Predict future revenue based on historical data, considering trends and day-of-week patterns.
+
+Returns JSON:
+{
+  "trend": { "direction": "up", "daily_change": 50.5 },
+  "forecast": [
+    { "date": "2024-01-15", "day_of_week": "Monday", "predicted_revenue": 5000, "confidence": "medium" }
+  ],
+  "disclaimer": "For reference only..."
+}
+
+Note: Forecast based on simple linear model, for reference only.
+
+Examples:
+  bi-cli trends forecast              # Forecast next 7 days
+  bi-cli trends forecast --days 14    # Forecast next 14 days`
+    )
+    .option('--days <number>', 'Days to forecast (default: 7)', '7')
+    .option('--pretty', 'Output as table')
     .action(async (options) => {
       const cfg = getConfig();
       if (!cfg.accessToken) {

package/src/index.ts

@@ -9,6 +9,7 @@ import { createSalesCommand } from './commands/sales.js';
 import { createProductCommand } from './commands/product.js';
 import { createTrendsCommand } from './commands/trends.js';
 import { createAnalyticsCommand } from './commands/analytics.js';
+import { createTrafficCommand } from './commands/traffic.js';
 
 // Read version from package.json
 const __filename = fileURLToPath(import.meta.url);
@@ -19,7 +20,19 @@ const program = new Command();
 
 program
   .name('bi-cli')
-  .description('Optima BI CLI - AI-friendly business intelligence tool')
+  .description(
+    `Optima BI CLI - E-commerce business intelligence tool for LLM agents.
+
+IMPORTANT: Run 'bi-cli auth login' first to authenticate before using other commands.
+
+Output: All commands output JSON by default (for programmatic parsing). Use --pretty for human-readable tables.
+
+Common use cases:
+  - Get sales data → bi-cli sales get --days 7
+  - Top selling products → bi-cli product best-sellers --limit 10
+  - Revenue trends → bi-cli trends revenue --days 30
+  - Compare periods → bi-cli analytics compare --days 7`
+  )
   .version(pkg.version);
 
 // Auth commands
@@ -37,36 +50,39 @@ program.addCommand(createTrendsCommand());
 // Analytics commands
 program.addCommand(createAnalyticsCommand());
 
+// Traffic commands
+program.addCommand(createTrafficCommand());
+
 // Config commands (placeholder)
 program
   .command('config')
-  .description('Manage configuration')
+  .description('[NOT IMPLEMENTED] Configuration management')
   .action(() => {
-    console.log('Config management coming soon...');
+    console.log('This feature is not yet implemented');
   });
 
 // Customer commands (placeholder)
 program
   .command('customer')
-  .description('Customer analytics')
+  .description('[NOT IMPLEMENTED] Customer analytics')
   .action(() => {
-    console.log('Customer analytics coming soon...');
+    console.log('This feature is not yet implemented');
   });
 
 // Inventory commands (placeholder)
 program
   .command('inventory')
-  .description('Inventory analytics')
+  .description('[NOT IMPLEMENTED] Inventory analytics')
   .action(() => {
-    console.log('Inventory analytics coming soon...');
+    console.log('This feature is not yet implemented');
   });
 
 // Platform commands (admin only - placeholder)
 program
   .command('platform')
-  .description('Platform analytics (admin only)')
+  .description('[NOT IMPLEMENTED] Platform analytics (admin only)')
   .action(() => {
-    console.log('Platform analytics coming soon...');
+    console.log('This feature is not yet implemented');
   });
 
 program.parse();