npm package: @pioneer-platform/integration-report-v2
Description: Clean, simple report generator for KeepKey - Gets LIVE data, outputs ASCII tables, ready for PDF
Latest version: 2.2.51

# KeepKey Report Generator v2

Clean, simple report generator that gets LIVE data from a connected KeepKey device.

## Features

✅ **LIVE Data** - No hardcoded or fake data
✅ **ASCII Tables** - Clean console output
✅ **JSON Export** - Structured data ready for PDF generation
✅ **LOD System** - Level of Detail from 0 (basic) to 5 (maximum)
✅ **Vault Compatible** - Matches vault reportGenerators structure

## Quick Start

### 1. Configure Report

Edit `src/config.ts`:

```typescript
export const REPORT_CONFIG = {
  chain: 'bitcoin',  // Chain to report on
  lod: 0,           // Level of detail (0-5)
  options: {
    includeEmpty: false,
    gapLimit: 20,
  }
};
```

### 2. Run Report

```bash
# Build and run
pnpm run dev

# Or rebuild and run
pnpm run rebuild && pnpm run dev
```

### 3. View Output

- **Console**: ASCII table output
- **JSON**: Saved to `./output/report-{chain}-lod{lod}-{timestamp}.json`

## LOD Levels

| LOD | Description | Sections |
|-----|-------------|----------|
| 0   | Basic Overview | Device features + XPUB balances |
| 1   | Account Details | + Account-level data |
| 2   | Address Details | + Address-level data |
| 3   | Transaction List | + Transaction details |
| 4   | Full History | + Complete transaction history |
| 5   | Maximum Detail | + All addresses and transactions |

**Currently Implemented**: LOD 0

## Structure

```
intergration-report-v2/
├── src/
│   ├── config.ts             # Report configuration (EDIT HERE)
│   ├── types.ts              # Type definitions (matches vault)
│   ├── report-generator.ts   # Single-file generator (ALL LOD levels)
│   ├── formatters/
│   │   └── ascii-table.ts    # ASCII table formatter
│   └── index.ts              # Main runner
├── output/                    # Generated reports (JSON)
└── dist/                      # Compiled JavaScript
```

**Single-File Design**: All LOD levels in one file (`report-generator.ts`), just like keepkey-vault!
You can copy this file directly to keepkey-vault if needed.

## Example Output

```
╔══════════════════════════════════════════════════════════════════════════════╗
║                        BITCOIN Report - LOD 0                                ║
║                           Basic Overview                                     ║
║                   Generated: 2025-10-18 12:00:00 PM                         ║
║                        Chain: bitcoin | LOD: 0                               ║
╚══════════════════════════════════════════════════════════════════════════════╝

════════════════════════════════════════════════════════════════════════════════
Device Features
════════════════════════════════════════════════════════════════════════════════

  • Vendor: keepkey.com
  • Model: K1-14AM
  • Device ID: ABC123...
  • Label: My KeepKey
  • Firmware: 7.9.3
  • Initialized: Yes
  • PIN Protection: Enabled

════════════════════════════════════════════════════════════════════════════════
XPUB Balances
════════════════════════════════════════════════════════════════════════════════

+------------------+---------------+----------+-----------+--------+------------------------+
| Path             | Type          | Balance  | USD Value | Symbol | XPUB                   |
+------------------+---------------+----------+-----------+--------+------------------------+
| m/44'/0'/0'      | p2pkh         | 0.12345  | $5,234.56 | BTC    | xpub6D3uXJmdUg4x...   |
| m/49'/0'/0'      | p2sh-p2wpkh   | 0.00000  | $0.00     | BTC    | ypub6WamSeXgTYgy...   |
+------------------+---------------+----------+-----------+--------+------------------------+
```

## Next Steps

### Implement LOD 1-5

All LOD levels are in the **single file** `src/report-generator.ts`:
- ✅ LOD 0: Basic overview (DONE)
- ⚠️  LOD 1: Account details (TODO - implement `getAccountDetails()`)
- ⚠️  LOD 2: Address details (TODO - implement `getAddressDetails()`)
- ⚠️  LOD 3: Transaction details (TODO - implement `getTransactionSummary()`)
- ⚠️  LOD 4: Full history (TODO - implement `getFullTransactionHistory()`)
- ⚠️  LOD 5: Maximum detail (TODO - implement `getAllAddresses()` + `getAllTransactions()`)

Just fill in the methods marked with `// TODO: Implement when needed`

### PDF Generation

Add PDF formatter:
- `src/formatters/pdf-generator.ts`
- Use existing JSON output
- Match vault's PDF styling

### Copy to Vault

The single-file design makes it easy:
```bash
# Copy the generator to vault
cp src/report-generator.ts /path/to/keepkey-vault/src/components/asset/reportGenerators/
```

## Important Notes

⚠️ **NO FAKE DATA**: This report generator ONLY uses live data from connected KeepKey device
⚠️ **Device Required**: A KeepKey device must be connected and unlocked
⚠️ **LOD 0 Only**: Currently only LOD 0 is implemented - other levels coming soon

### SDK Integration Note

⚠️ **Current Status**: The SDK integration needs workspace packages to be built first.

**To use this:**
1. Build the pioneer monorepo: `cd ../../../ && make`
2. Or adapt the SDK initialization to your environment (browser, node, etc.)
3. See existing e2e tests for working SDK examples

The core `report-generator.ts` is ready - just needs proper SDK initialized and passed in!

## Compatibility

Designed to match the structure of:
- `/projects/keepkey-vault/src/components/asset/reportGenerators/`

This ensures easy integration with vault's PDF generation system.