v0.2.0

Release Notes v0.2.0

🚀 What's New in v0.2.0

Version v0.2.0 introduces major security features, native WSS (SSL/TLS) support, active ping latency measurement, and comprehensive deployment documentation.

---

🔑 Features & Security

• API Key Token Authorization:

  • Secure server commands and push events with optional API key authentication (SpotifyServer(api_key="your-token")).
  • Incoming messages with invalid or missing tokens are safely dropped.
  • Command execution with invalid tokens raises UnauthorizedError.

• Secure WebSockets (WSS):

  • Built-in support for encrypted WebSocket connections using certfile/keyfile paths or custom ssl.SSLContext.
  • Seamless integration with reverse proxies (e.g., Nginx, Caddy) for SSL Offloading.

• Active Ping & Latency Checks:

  • Measure round-trip latency to the connected Spicetify client using await server.ping().
  • Convenience decorator @server.on_ping to listen to client heartbeat events with typed UTC datetime objects.

---

📚 Documentation & Guides

• New Deployment Guides:

  • Local WSS Guide: Step-by-step instructions for local SSL setups via OpenSSL or native Windows 11 using mkcert.
  • VPS Deployment Guide: Production setup using Nginx as a Reverse Proxy with Let's Encrypt certificates and bot-filtering (426 Upgrade Required).

• Expanded Examples & Docs:

  • Dedicated code examples for API key authentication (examples/api_key.py) and WSS (examples/wss.py).
  • Added a dedicated Documentation & Guides section in README.md.

---

🐛 Fixes & Maintenance

• Fixed setuptools package discovery error in pyproject.toml by explicitly setting packages.find.include.
• Cleaned up Sphinx build warnings (myst.header and duplicate autodoc descriptions in docs/conf.py).
• Fixed double brackets in README.md link formatting.
• Added local SSL key files (*.pem) to .gitignore.

---

💻 Quick Example

import asyncio
from datetime import datetime
from spicetify import SpotifyServer, TrackInfo, UnauthorizedError

async def main():
    async with SpotifyServer(api_key="your-secret-key") as server:
        @server.on_song_changed
        def on_song(track: TrackInfo):
            print(f"🎵 Now playing: {track.title}")

        @server.on_ping
        def on_ping(ping_time: datetime):
            print(f"💓 Heartbeat at: {ping_time.strftime('%H:%M:%S UTC')}")

        await server.wait_for_connection()

        # Measure round-trip latency
        latency = await server.ping()
        print(f"⚡ Latency: {latency:.2f} ms")

        await asyncio.Event().wait()

if __name__ == "__main__":
    asyncio.run(main())

---

What's Changed

• feat: add api key support by @tobfd in #4

Full Changelog: 0.1.1...0.2.0