# @optima-chat/bi-cli

Optima BI CLI - E-commerce business intelligence tool designed for LLM agents.

## Features

- **LLM-Friendly**: Detailed help messages with JSON schemas and examples
- **JSON Output**: All commands output JSON by default for programmatic parsing
- **Pretty Tables**: Use `--pretty` flag for human-readable table format
- **Unified Auth**: Shared authentication with `commerce-cli` and `optima-agent`

## Installation

```bash
npm install -g @optima-chat/bi-cli
```

## Quick Start

```bash
# Login first (required)
bi-cli auth login

# 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 with previous period
bi-cli analytics compare --days 7
```

## Authentication

### Login

```bash
# Login to production (default)
bi-cli auth login

# Login to stage environment
bi-cli auth login --env stage

# Login to development environment
bi-cli auth login --env development
```

### Check Status

```bash
bi-cli auth whoami    # Show current user
bi-cli auth status    # Show authentication status
bi-cli auth logout    # Logout
```

### Environment Configuration

| Environment | Auth URL              | Backend URL             |
| ----------- | --------------------- | ----------------------- |
| production  | auth.optima.onl       | bi-api.optima.onl       |
| stage       | auth.stage.optima.onl | bi-api.stage.optima.onl |
| development | auth.optima.chat      | bi-api.optima.chat      |

### Token Priority

1. `BI_CLI_TOKEN` environment variable
2. `OPTIMA_TOKEN` environment variable
3. `~/.optima/token.json` file

## Commands

### Sales Analytics

```bash
bi-cli sales get                     # Get last 7 days (default)
bi-cli sales get --days 30           # Get last 30 days
bi-cli sales get --days 7 --pretty   # Output as table
```

Returns:

```json
{
  "summary": {
    "total_revenue": 10000,
    "total_orders": 100,
    "avg_order_value": 100,
    "unique_customers": 80
  },
  "daily": [{ "date": "2024-01-01", "total_revenue": 1500, "order_count": 15 }]
}
```

### Product Analytics

```bash
# Best selling products
bi-cli product best-sellers                      # Top 10 by revenue
bi-cli product best-sellers --limit 5            # Top 5
bi-cli product best-sellers --sort quantity      # Sort by quantity

# ABC inventory analysis (Pareto)
bi-cli product abc-analysis

# Price range analysis
bi-cli product price-analysis

# Product performance metrics
bi-cli product performance --days 30 --limit 20
```

### Trend Analytics

```bash
# Revenue trends with moving average
bi-cli trends revenue                        # Last 30 days, daily
bi-cli trends revenue --granularity hourly   # Hourly granularity
bi-cli trends revenue --granularity weekly   # Weekly granularity

# Orders heatmap by day and hour
bi-cli trends heatmap

# Monthly/seasonal patterns
bi-cli trends seasonality

# Revenue forecast
bi-cli trends forecast              # Next 7 days
bi-cli trends forecast --days 14    # Next 14 days
```

### Advanced Analytics

```bash
# Period comparison
bi-cli analytics compare                              # Last 30 days vs previous
bi-cli analytics compare --days 7                     # This week vs last week
bi-cli analytics compare --compare-to previous_year   # Year-over-year

# Growth trends
bi-cli analytics growth                         # Daily, last 30 periods
bi-cli analytics growth --period weekly         # Weekly
bi-cli analytics growth --period monthly        # Monthly

# Customer cohort analysis (LTV)
bi-cli analytics cohort

# Order status funnel
bi-cli analytics funnel --days 30
```

### Traffic Analytics

```bash
# Traffic overview
bi-cli traffic overview                     # Last 30 days
bi-cli traffic overview --days 7            # Last 7 days
bi-cli traffic overview --product <uuid>    # Filter by product

# Traffic sources
bi-cli traffic sources --limit 10

# Conversion funnel
bi-cli traffic funnel

# Site search analytics
bi-cli traffic search
bi-cli traffic search --zero-results        # Zero-result queries only

# Top pages
bi-cli traffic pages --limit 20
```

## Output Formats

### JSON (Default)

All commands output JSON by default, ideal for LLM agents and programmatic use:

```bash
bi-cli sales get | jq .
bi-cli product best-sellers --limit 5 | your-ai-tool
```

### Pretty Tables

Use `--pretty` flag for human-readable output:

```bash
bi-cli sales get --pretty
bi-cli product best-sellers --pretty
```

## Environment Variables

```bash
# Override token
export BI_CLI_TOKEN="your-access-token"

# Override URLs
export BI_CLI_BACKEND_URL="https://custom-api.example.com"
export BI_CLI_AUTH_URL="https://custom-auth.example.com"

# Override environment
export BI_CLI_ENV="stage"
```

## For LLM Agents

Each command includes detailed help with:

- Function description
- JSON return structure
- Usage examples
- Parameter descriptions with valid values

```bash
bi-cli sales get --help
bi-cli product abc-analysis --help
bi-cli analytics cohort --help
```

## License

MIT