[tobfd]

Summary

Part 4 of the extension stack, on top of #12 (merge order: #10 → #11 → #12 → this PR). Makes the WebSocket messages an explicit, tested contract between the extension, spicetify-websocket and the Home Assistant integration. Version 0.4.0.

What changes and why

Change	Why
InitialState carries protocolVersion: 1 and extensionVersion	A server can tell which message format and extension version it talks to (spicetify-websocket exposes both, and warns if the extension is newer than it knows).
Failed responses carry a code (unauthorized, invalid_params, unknown_request, unavailable, command_failed) next to error	Receivers had to guess from error texts (e.g. "does it contain unauthorized?").
protocol/messages.schema.json (JSON Schema 2020-12)	Machine-readable description of all requests, events and responses.
Tests validate every message the extension sends against the schema (ajv, dev dependency only)	The schema cannot drift from the code unnoticed.
PROTOCOL.md	One place for requests, responses, error codes, events, the state payload, authentication and versioning rules. The README's API section was outdated (it still showed the removed snake_case fields) and now links there.
CONTRIBUTING: how to change the protocol	Update doc + schema together; bump PROTOCOL_VERSION only for changes receivers must know about.

Compatibility

Additive only: old servers ignore the new fields. The end-to-end tests in spicetify-websocket (tobfd/spicetify-websocket, PR "lib error codes, protocol version, E2E") run this extension against the real server and validate all frames in both directions against this schema.

Tests

• npm test: 17 passed (2 new: version fields in InitialState, error codes), every sent message schema-validated.
• npm run lint: clean.
• Schema sanity-checked with valid and invalid messages (missing code on failure, missing protocolVersion, volume out of range, queue longer than 5 are rejected).
• spicetify-websocket end-to-end suite against this branch: 10/10 passed.

🤖 Generated with Claude Code

https://claude.ai/code/session_01E14pPhbcMWLg9j9gAfGW9f

---

Generated by Claude Code