bonob/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

bonob is a Sonos SMAPI (Sonos Music API) implementation that bridges Subsonic API clones (like Navidrome and Gonic) with Sonos devices. It acts as a middleware service that translates between the Subsonic API and Sonos's proprietary music service protocol, allowing users to stream their personal music libraries to Sonos speakers.

## Development Commands

### Building and Running
```bash
# Build TypeScript to JavaScript
npm run build

# Development mode with auto-reload (requires environment variables)
npm run dev
# OR with auto-registration
npm run devr

# Register bonob service with Sonos devices
npm run register-dev
```

### Testing
```bash
# Run all tests
npm test

# Run tests in watch mode
npm run testw

# Set custom test timeout (default: 5000ms)
JEST_TIMEOUT=10000 npm test
```

### Environment Variables for Development
When running locally, you need to set several environment variables:
- `BNB_DEV_HOST_IP`: Your machine's IP address (so Sonos can reach bonob)
- `BNB_DEV_SONOS_DEVICE_IP`: IP address of a Sonos device for discovery
- `BNB_DEV_SUBSONIC_URL`: URL of your Subsonic API server (e.g., Navidrome)

## Architecture

### Core Components

**`src/app.ts`** - Application entry point
- Reads configuration from environment variables
- Initializes all services (Subsonic, Sonos, authentication)
- Wires together the Express server with appropriate dependencies
- Handles SIGTERM for graceful shutdown

**`src/server.ts`** - Express HTTP server
- Serves web UI for service registration and login
- Handles music streaming (`/stream/track/:id`)
- Generates icons and cover art (`/icon/...`, `/art/...`)
- Serves Sonos-specific XML files (strings, presentation map)
- Binds SOAP service for Sonos SMAPI communication

**`src/smapi.ts`** - Sonos SMAPI SOAP implementation (1200+ lines)
- Implements the Sonos Music API Protocol via SOAP/XML
- Core operations: `getMetadata`, `getMediaURI`, `search`, `getExtendedMetadata`
- Handles authentication flow with link codes and device auth tokens
- Manages token refresh and session management
- Maps music library concepts to Sonos browse hierarchy

**`src/subsonic.ts`** - Subsonic API client
- Implements `MusicService` and `MusicLibrary` interfaces
- Handles authentication with Subsonic servers using token-based auth
- Translates between Subsonic data models and bonob's domain types
- Supports custom player configurations for transcoding
- Special handling for Navidrome (bearer token authentication)
- Implements artist image fetching with optional caching

**`src/music_service.ts`** - Core domain types and interfaces
- Defines `MusicService` interface (auth and login)
- Defines `MusicLibrary` interface (browsing, search, streaming, rating, scrobbling)
- Domain types: `Artist`, `Album`, `Track`, `Playlist`, `Genre`, `Rating`, etc.
- Uses `fp-ts` for functional programming patterns (`TaskEither`, `Option`, `Either`)

**`src/sonos.ts`** - Sonos device discovery and registration
- Discovers Sonos devices on the network using SSDP/UPnP
- Registers/unregisters bonob as a music service with Sonos systems
- Supports both auto-discovery and seed-host based discovery
- Uses `@svrooij/sonos` library for device communication

**`src/smapi_auth.ts`** - Authentication token management
- Implements JWT-based SMAPI tokens (token + key pairs)
- Handles token verification and expiry
- Token refresh flow using `fp-ts` `TaskEither`

**`src/config.ts`** - Configuration management
- Reads and validates environment variables (all prefixed with `BNB_`)
- Legacy environment variable support (BONOB_ prefix)
- Type-safe configuration with defaults

### Key Abstractions

**BUrn (Bonob URN)** - Resource identifier system (`src/burn.ts`)
- Format: `{ system: string, resource: string }`
- Systems: `subsonic` (for cover art), `external` (for URLs like Spotify images)
- Used for abstracting art/image sources across different backends

**URL Builder** (`src/url_builder.ts`)
- Wraps URL manipulation with a builder pattern
- Handles context path for reverse proxy deployments
- Used throughout for generating URLs that Sonos devices can access

**Custom Players** (`src/subsonic.ts`)
- Allows mime-type specific transcoding configurations
- Maps source mime types to transcoded types
- Creates custom "client" names in Subsonic (e.g., "bonob+audio/flac")
- Example: `BNB_SUBSONIC_CUSTOM_CLIENTS="audio/flac>audio/mp3"`

### Data Flow

1. **Sonos App Request** → SOAP endpoint (`/ws/sonos`)
2. **SOAP Service** → Verifies auth token, calls `MusicLibrary` methods
3. **MusicLibrary** → Makes Subsonic API calls, transforms data
4. **SOAP Response** → Returns XML formatted for Sonos

For streaming:
1. **Sonos Device** → `GET /stream/track/:id` with custom headers (bnbt, bnbk)
2. **Stream Handler** → Verifies token, calls `MusicLibrary.stream()`
3. **Subsonic Stream** → Proxies audio with proper mime-type handling
4. **Response** → Streams audio to Sonos, reports "now playing"

### Icon System (`src/icon.ts`)
- SVG-based icon generation with dynamic colors
- Supports foreground/background color customization via `BNB_ICON_FOREGROUND_COLOR` and `BNB_ICON_BACKGROUND_COLOR`
- Genre-specific icons
- Text overlay support (e.g., year icons like "1984")
- Holiday/festival decorations (auto-applied based on date)
- Legacy mode: renders to 80x80 PNG for older Sonos systems

### Authentication Flow
1. Sonos app requests link code via `getAppLink()`
2. User visits login URL with link code
3. User enters Subsonic credentials
4. bonob validates with Subsonic, generates service token
5. bonob associates link code with service token
6. Sonos polls `getDeviceAuthToken()` with link code
7. bonob returns SMAPI token (JWT) to Sonos
8. Subsequent requests use SMAPI token, which maps to service token

### Testing Philosophy
- Jest with ts-jest preset
- In-memory implementations for `LinkCodes`, `APITokens` for testing
- Mocking with `ts-mockito`
- Test helpers in `tests/` directory
- Console.log suppressed in tests (see `tests/setup.js`)

## Common Patterns

### Error Handling
- Use `fp-ts` `TaskEither<AuthFailure, T>` for async operations that can fail with auth errors
- SOAP faults for Sonos-specific errors (see SMAPI_FAULT_* constants)
- Promise-based error handling with `.catch()` for most async operations

### Type Safety
- Strict TypeScript (`strict: true`, `noImplicitAny: true`, `noUncheckedIndexedAccess: true`)
- Extensive use of discriminated unions
- Interface-based design for pluggable services

### Logging
- Winston-based logger (`src/logger.ts`)
- Log level controlled by `BNB_LOG_LEVEL`
- Request logging optional via `BNB_SERVER_LOG_REQUESTS`

### Functional Programming
- Heavy use of `fp-ts` for `Option`, `Either`, `TaskEither`
- Pipe-based composition (`pipe(data, fn1, fn2, ...)`)
- Immutable data transformations

## File Organization
- `src/` - TypeScript source code
- `tests/` - Jest test files (mirrors src/ structure)
- `build/` - Compiled JavaScript (gitignored)
- `web/` - HTML templates (Eta templating) and static assets
- `typings/` - Custom TypeScript definitions

## Important Constraints
- bonob must be accessible from Sonos devices at `BNB_URL`
- `BNB_URL` cannot contain "localhost" (validation error)
- Sonos requires specific XML formats (SMAPI WSDL v1.19.6)
- Streaming must handle HTTP range requests for seek functionality
- Token lifetime (`BNB_AUTH_TIMEOUT`) should be less than Subsonic session timeout