# Instar v0.12.25 — Baileys v7 Migration & Complete WhatsApp Fix

## What Changed

**Migrated from Baileys v6 to v7** — the core fix for all WhatsApp setup failures.

### Issue 1: Baileys dependency resolution
- Moved from `@whiskeysockets/baileys` (v6, peer dependency) to `baileys` (v7, optional dependency)
- v7 is now bundled with instar — no separate install needed
- Import order changed: v7 tried first, v6 as fallback for backward compatibility

### Issue 2: Connection failure detection
- Fixed error detection for non-Boom errors (v6 used Boom, v7 may use plain Error objects)
- Now checks `error.output.statusCode`, `error.statusCode`, `error.data.reason`, AND `error.message`
- Terminal failures (405, 403, "Connection Failure") no longer trigger reconnect loops
- Errors now surface via `setLastError()` on the adapter for dashboard display
- Removed deprecated `printQRInTerminal` option

### Issue 3: Pairing code timing
- Moved `requestPairingCode()` inside the `connection: 'open'` handler
- Previously called immediately after socket creation (before connection was stable)
- Added try/catch with descriptive error message

### Issue 4: Dashboard QR panel timeout
- Added 30-second timeout for QR code appearance
- Timeout shows clear error message with upgrade instructions
- Dashboard now displays adapter error messages from the `/whatsapp/qr` endpoint
- Added `escapeHtml` helper for safe error display
- Poll responses now include `error` field from adapter status

### Issue 5: Wizard pre-flight check
- Added mandatory Baileys pre-flight check before WhatsApp configuration
- Detects v6 (warns + upgrades), v7 (proceeds), or missing (installs)
- Added QR timeout check with clear failure messaging and retry instructions
- Added one-retry-then-offer-Telegram fallback

### Testing
- 37 regression tests covering all 5 issues (up from 22)
- 20 setup wizard completeness tests
- 57 total WhatsApp-related tests, all passing

## What to Tell Your User

- **WhatsApp now works**: "We've upgraded to the latest Baileys version. WhatsApp pairing should actually work now — the old version was incompatible with WhatsApp's current protocol."
- **No manual install needed**: "Baileys is now included with instar. You don't need to install it separately."

## Summary of New Capabilities

| Capability | How to Use |
|-----------|-----------|
| Baileys v7 bundled | Automatic — included as optional dependency |
| Terminal failure detection | Automatic — stops reconnect loops on 405/403/"Connection Failure" |
| Dashboard error display | Automatic — errors shown in QR panel with 30s timeout |
| Pairing code after connection | Automatic — requests pairing code only after connection is open |
| Wizard pre-flight check | Automatic — verifies Baileys before WhatsApp setup |
