npm package: @pioneer-platform/integration-report
Description: Server-side Bitcoin report generation with LOD (Level of Detail) support.
Latest version: 1.15.52

# Integration Report - Bitcoin Server-Side Reports

Server-side Bitcoin report generation with LOD (Level of Detail) support.

## Quick Start

### 1. Start Pioneer Server

```bash
cd /Users/highlander/WebstormProjects/keepkey-stack/projects/pioneer/services/pioneer-server
make start
```

### 2. Build and Run Reports

```bash
cd /Users/highlander/WebstormProjects/keepkey-stack/projects/pioneer/e2e/reports/intergration-report

# Build
pnpm run build

# Generate reports at different LOD levels
pnpm run server-report:lod0  # Portfolio overview
pnpm run server-report:lod1  # XPUB summary
pnpm run server-report:lod2  # Account details (default)
pnpm run server-report:lod3  # Address level
pnpm run server-report:lod4  # Transaction IDs
pnpm run server-report:lod5  # Full details with LLM

# Or with custom LOD and account count
node dist/server-side-report-example.js 3 1  # LOD 3, 1 account
```

## Reports Output

Reports are saved to `./reports/` directory:

- `bitcoin_report_lod0_YYYY-MM-DD.json`
- `bitcoin_report_lod1_YYYY-MM-DD.json`
- etc.

## LOD Levels

| LOD | Description | Size | Time | Use Case |
|-----|-------------|------|------|----------|
| 0 | Portfolio overview | ~200B | 500ms | Dashboard widget |
| 1 | XPUB summary | ~1KB | 1s | Multi-account view |
| 2 | Account details | ~2KB | 1.5s | Account analysis |
| 3 | Address level | ~50KB | 3s | Address auditing |
| 4 | Transaction IDs | ~500KB | 10s | Tax reporting |
| 5 | Full details + LLM | ~2MB | 30s | User-facing history |

## Configuration

### Enable LLM (Optional)

Edit `/projects/pioneer/services/pioneer-server/.env`:

```bash
# Use mock LLM (default, no API calls)
ENABLE_LLM=true
LLM_PROVIDER=mock

# Or use OpenAI (requires API key)
ENABLE_LLM=true
LLM_PROVIDER=openai
OPENAI_API_KEY=sk-...
```

## Architecture

```
Client (integration-report)
    ↓
    1. Get XPUBs from KeepKey (Pioneer SDK)
    ↓
    2. POST to http://localhost:9001/api/v1/reports/bitcoin
    ↓
Pioneer Server
    ↓
    3. Bitcoin Report Service (LOD processors)
    ↓
    4. UTXO Network Module (Blockbook API)
    ↓
    5. LLM Service (optional, LOD 5 only)
    ↓
    6. Return structured JSON
    ↓
Client
    ↓
    7. Save JSON to ./reports/
    ↓
    8. (Optional) Generate PDF from JSON
```

## Example Output

### LOD 0 Response
```json
{
  "lod": 0,
  "totalBalanceBTC": 0.12345678,
  "totalBalanceUSD": 8024.69,
  "totalXpubs": 9,
  "lastUpdated": "2025-01-17T10:30:00.000Z"
}
```

### LOD 2 Response
```json
{
  "lod": 2,
  "totalBalanceBTC": 0.12345678,
  "totalBalanceUSD": 8024.69,
  "totalXpubs": 9,
  "lastUpdated": "2025-01-17T10:30:00.000Z",
  "xpubs": [
    {
      "xpub": "zpub6rFR7y4Q2AijBEqTUquhVz398htDFrtym...",
      "type": "p2wpkh",
      "path": "m/84'/0'/0'",
      "label": "Native SegWit Account 0",
      "balance": 0.05000000,
      "addressCount": 15,
      "txCount": 42,
      "receiveIndex": 14,
      "changeIndex": 8,
      "totalReceived": 0.15000000,
      "totalSent": 0.10000000
    }
  ]
}
```

## Development

### Test Single LOD Level

```bash
node dist/server-side-report-example.js 2  # LOD 2
```

### Test Multiple Accounts

```bash
node dist/server-side-report-example.js 2 5  # LOD 2, 5 accounts
```

This will generate 3 XPUBs per account (Legacy, SegWit, Native SegWit) × 5 accounts = 15 XPUBs total.

## Troubleshooting

### "No XPUBs retrieved from KeepKey"
- Ensure KeepKey is connected and unlocked
- Check Pioneer SDK initialization

### "Server returned 500"
- Check pioneer-server logs: `tail -f /projects/pioneer/services/pioneer-server/logs/server.log`
- Verify server is running: `curl http://localhost:9001/api/v1/health`

### "Connection refused"
- Start pioneer-server: `cd /projects/pioneer/services/pioneer-server && make start`

## Related Documentation

- [Bitcoin Reports API Documentation](../../../services/pioneer-server/BITCOIN_REPORTS.md)
- [Pioneer Server README](../../../services/pioneer-server/README.md)

## License

MIT