@optima-chat/bi-cli 0.3.4 → 0.3.6

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

@@ -20,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
@@ -44,33 +56,33 @@ 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();