Add Star Ratings, Enhance Security, and Improve User Experience

[DreadHeadHippy]

Overview

This PR adds a highly requested feature, implements critical security improvements, and streamlines the installation process. All changes maintain backward compatibility with existing setups while significantly improving the plugin's security posture.

---

🌟 New Features

Star Rating System

• Dial-based rating control: Rotate the dial to rate tracks with visual feedback
• Half-star and full-star modes: Choose between 0.5 or 1.0 star increments per scroll
• Visual overlay: Star rating displayed on touch strip with ⯨ for half stars
• Smart debouncing: 2-second delay before saving prevents excessive API calls during adjustment
• Real-time feedback: Instant visual updates while scrolling, graceful save confirmation

User experience:

• Set dialAction to "rating" in strip settings
• Choose "half" or "full" star mode
• Rotate dial to adjust rating (0-5 stars)
• See stars update in real-time
• Rating auto-saves after 2 seconds of inactivity
• "SAVED!" confirmation overlay appears

---

🔒 Security Improvements

Enhanced API Security ⭐ IMPORTANT

Modernized authentication and network communication to follow current security best practices.

Improvements:

• ✅ Improved credential handling in API requests
• ✅ Enhanced authentication mechanisms
• ✅ Better protection of sensitive data during transmission
• ✅ Aligned with industry-standard security patterns

Implementation:

• Refactored authentication flow for better security
• Added new security helper functions
• Updated all API endpoints to use improved patterns
• Applied consistently across: ratings, metadata, sessions, album art, track counts

Input Validation and Security Hardening

Strengthened input validation to protect against malformed configurations and potential security issues.

Protections added:

• ✅ Comprehensive URL validation with protocol restrictions
• ✅ Input sanitization for user-provided endpoints
• ✅ Prevention of invalid or potentially unsafe configurations
• ✅ Real-time validation feedback in settings UI

Implementation:

• New validateUrl() function with safety checks
• Clear error messages guide users to correct configurations
• Prevents saving of invalid settings
• Enhanced error handling throughout

Connection Security Requirements

Implemented smart security requirements that balance protection with usability.

Security policy:

• Local connections (localhost, 127.0.0.1): Flexible for development
• Private networks (192.168.x.x, 10.x.x, 172.x.x): Optimized for home use
• Remote servers: Enforced secure connections for internet-facing services

Benefits:

• ✅ Enhanced protection for remote communications
• ✅ Maintains convenience for local and home network use
• ✅ Follows modern web security standards

---

🎯 Improvements

Installation Process

• Simplified installation: Users now just download .streamDeckPlugin and double-click
• No manual steps: Stream Deck handles everything automatically
• Updated documentation: README reflects the streamlined process
• Backward compatible: Old manual installation still works

Bug Fixes

• Fixed overlay timing issues in touch strip display
• Improved state management for strip overlays
• Enhanced error handling with user-friendly messages
• Better validation feedback in settings UI

Developer Experience

• Added comprehensive inline documentation
• Improved code organization with helper functions
• Better error messages aid debugging
• Consistent security patterns across codebase

---

⚠️ Breaking Changes

Secure Connection Requirements for Remote Servers

Impact: Remote Plex servers now require secure connections

Migration:

• Update remote server URLs to use secure protocols (HTTPS)
• Local network connections (192.168.x.x, 10.x.x, etc.) continue to work as before
• Localhost connections unaffected

Rationale: Following modern security standards and best practices for protecting user credentials and data.

Affected users: Small subset of users connecting to internet-facing Plex servers over insecure protocols. Local and private network users are unaffected.

---

🧪 Testing Completed

• ✅ Plugin installs via .streamDeckPlugin file
• ✅ All button actions functional (Album Art, Play/Pause, Previous, Next, etc.)
• ✅ Dial controls working (skip, volume, rating)
• ✅ Star rating saves correctly to Plex server
• ✅ URL validation accepts valid inputs, rejects invalid
• ✅ Token transmission verified (headers, not URLs)
• ✅ HTTPS enforcement working as expected
• ✅ Error handling provides clear guidance
• ✅ Backward compatibility with existing settings
• ✅ No console errors or warnings
• ✅ Performance unchanged (debouncing reduces API calls)

---

📋 Files Changed

Core Plugin Logic:

• com.rackemrack.ampdeck.sdPlugin/plugin.js (+226 lines, -34 lines)
  • Added star rating dial controls
  • Added security validation functions
  • Updated all API calls to use headers
  • Improved error handling

Property Inspectors:

• com.rackemrack.ampdeck.sdPlugin/pi.html (+31 lines, -2 lines)

  • Added URL validation
  • Enhanced user feedback
  • Updated test functions for security

• com.rackemrack.ampdeck.sdPlugin/pi-strip.html (+46 lines, -2 lines)

  • Added rating mode selector
  • Added URL validation
  • Enhanced user feedback
  • Updated test functions for security

Documentation:

• README.md (-22 lines, +5 lines)
  • Simplified installation instructions
  • Updated for .streamDeckPlugin distribution

Distribution:

• Added com.rackemrack.ampdeck.streamDeckPlugin for easy installation

Total: ~340 lines changed across 4 files

---

🚀 Release Notes Template

## v1.3.0 - Enhanced Security and Star Ratings

### New Features
- ⭐ Star rating system with dial controls (half-star and full-star modes)
- Visual feedback with star overlays on touch strip
- Smart debouncing prevents excessive API calls

### Security Improvements
- Enhanced API security and authentication practices
- Improved input validation for user-provided endpoints
- Strengthened connection security requirements
- Better error handling and user feedback

### Improvements
- Simplified installation with `.streamDeckPlugin` file
- Refined overlay timing and display
- Updated documentation

### Requirements
- Remote Plex servers should use secure HTTPS connections
- Local and home network setups continue to work as before

### Installation
Simply download `com.rackemrack.ampdeck.streamDeckPlugin` and double-click!

---

📝 Additional Notes

Security Improvements

These changes implement modern security practices and align with current industry standards. Details have been kept appropriately high-level in public communications. Specific technical discussion available privately if needed for review purposes.

Backward Compatibility

All existing functionality preserved. Users with valid HTTPS or local HTTP configurations will see no changes in behavior.

Future Considerations

The security patterns established here (header-based auth, URL validation) provide a solid foundation for future enhancements.

---

🙏 Credits

Star rating implementation and security review by @DreadHeadHippy with AI assistance.

Original plugin and architecture by @rackemrack - thank you for creating this excellent foundation!

---

Ready to merge? This PR has been thoroughly tested and is ready for review. Happy to address any questions or concerns!

[rackemrack]

Thanks for this! Will check it out when I have some time this weekend.

[DreadHeadHippy]

My pleasure! I have more details regarding security if you want to reach out privately. This PR was left vague intentionally. Thanks for the plugin!

[DreadHeadHippy]

Hey @rackemrack! 👋

First off, I just want to say I absolutely love this plugin! You created something really useful for the Plex + Stream Deck community. I've been having a blast using it and wanted to contribute some improvements to make it even better.

While you're reviewing the v1.2.0 PR (no rush at all!), I got excited and kept building. I've put together v1.3.0 with a new Rating button and some fixes. Wanted to share what I've been working on!

---

What's New in v1.3.0

🆕 Rating Button

Added a dedicated Rating button action that shows the current track's star rating. Users can now rate tracks with a single tap on any Stream Deck model (not just Stream Deck+ with dials).

Features:

• Displays current track rating with three display style options:
  • Stars Only: ★★★★☆ (classic star display)
  • Numeric Only: 4.5 (big, bold number)
  • Both: 4.5/5 (number with scale)
• Tap to cycle through ratings
• Configurable font size (32px - 56px)
• Configurable rating mode (half-star or full-star increments)
• Works on all Stream Deck models with LCD keys
• Smart formatting: shows "4/5" not "4.0/5" for whole numbers, adds .5 only for half stars
• Matches the same rating system as the dial implementation

🐛 Critical Fix: Rating Persistence

Solved a major issue where ratings would appear to save but then revert to zero after 3-10 seconds.

The Problem:
Plex's server-side cache takes a while to update after rating changes. The plugin would poll for track data, get stale cached data (old rating), and overwrite the user's new rating.

The Solution:
Implemented smart per-track rating cache:

• Tracks user-set ratings by ratingKey
• Only accepts server updates when they meet/exceed the local value
• Automatically cleans up when tracks change
• Works across all three data sources (timeline polls, metadata fetches, server fallback)

Result: Ratings now persist correctly without reverting. No more confusion! ✨

🎨 UX Refinement

• Removed "SAVED!" confirmation overlay for rating changes since the rating now persists visibly
• Rating changes are silent on success (errors still shown)
• Cleaner, less intrusive user experience

---

Testing Status

✅ Button rating cycles correctly (half-star and full-star modes)
✅ Dial rating cycles correctly (existing feature)
✅ Ratings persist without reverting to zero
✅ Smart cache handles Plex's slow cache updates
✅ Settings UI shows/hides correctly based on action type
✅ Font size customization works as expected
✅ No JavaScript errors in console
✅ Compatible with v1.2.0 security improvements

---

Release Status

v1.3.0 is now live! 🎉

You can find it here: https://github.com/DreadHeadHippy/ampdeck/releases/tag/v1.3.0

I went ahead and published it on my fork so people can use it right away. I figured that way there's no pressure on you to rush - users get the improvements immediately, and you can review whenever you have time.

---

Next Steps (Totally Up to You!)

I have two options for getting these changes to you, and I'm happy to do whatever fits your workflow best:

Option 1: I can wait
If you'd prefer, I can hold off on creating a new PR until you've had a chance to review v1.2.0. No rush at all - I know GitHub can be overwhelming with lots of PRs at once.

Option 2: PR whenever you're ready
Or I can create a PR for v1.3.0 now, and you can review it whenever works for you. 😊

Let me know what you prefer, or if there's a different approach that works better for you!

---

Why I'm Excited About This

I'm really happy with how this turned out! The Rating button makes rating accessible on all Stream Deck models, not just the Stream Deck+. While building it, I noticed ratings would sometimes revert after saving, so I fixed that with the smart caching system. Together, they make rating tracks way smoother.

Seriously though, thanks for building this plugin. It's exactly what the Plex community needed, and I'm happy to help make it even better. Take your time with reviews - I'm just excited to contribute! 🎵

— DreadHeadHippy

[DreadHeadHippy]

Hey @rackemrack!

So... I may have gotten a little carried away after v1.3.0 and found a few bugs to squash. 😅

Released v1.3.1 as a quick patch to fix four issues:

---

What's Fixed

1. Touch strip text color - Content was always showing grey instead of using the user's chosen color (white, orange, amber, etc.). Fixed the copy-paste bug.

2. Rating button text positioning - Numeric rating displays weren't vertically centered at larger font sizes. Now properly centered.

3. Rating saves on quick track changes - Biggest fix: ratings would be lost if you rated a track and skipped to the next one within 2 seconds (the debounce window). Now ratings flush immediately when tracks change, so no data loss.

4. Rating Button API Efficiency - Fixed the rating button making an API call on every press. Now uses the same 2-second debounce as the dial to prevent API spam when clicking rapidly through ratings. Display updates immediately, saves are batched intelligently.

---

Why This Matters

The third one is actually pretty important - prevents user frustration when they rate tracks quickly while listening. The debouncing still works great for adjusting ratings on a single track (prevents API spam), but now we don't lose data when people skip around their library.

---

No Pressure!

Just wanted to keep you in the loop. Take your time reviewing v1.2.0 and v1.3.0 - these are all just improvements building on your awesome foundation. Everything's published on my fork so users can grab it whenever, and you can merge whenever works for you.

Hope you're doing well!

— DreadHeadHippy

[Copilot]

Pull request overview

This PR adds a star rating system for tracks and implements security improvements by moving authentication from URL parameters to HTTP headers. The changes introduce dial-based and button-based rating controls with visual feedback, URL validation for configuration inputs, and updates the installation process to use a .streamDeckPlugin file.

Changes:

• Added star rating feature with dial controls, rating button, and configurable half-star/full-star modes
• Enhanced security by moving Plex token authentication from URL query parameters to HTTP headers
• Added URL validation with protocol restrictions and HTTPS requirements for remote servers
• Updated installation documentation to use .streamDeckPlugin distribution file

Reviewed changes

Copilot reviewed 9 out of 30 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
install.sh	Version bumped to v1.3.1
install.bat	Version bumped to v1.3.1
com.rackemrack.ampdeck.sdPlugin/plugin.js	Core rating functionality, security improvements, debug logging, header-based auth, rating caching logic
com.rackemrack.ampdeck.sdPlugin/pi.html	Added rating button settings UI, URL validation in property inspector
com.rackemrack.ampdeck.sdPlugin/pi-strip.html	Added rating mode selector for dial, URL validation in strip property inspector
com.rackemrack.ampdeck.sdPlugin/manifest.json	Version update to 1.3.1, new rating action definition
com.rackemrack.ampdeck.sdPlugin/imgs/rating-icon.svg	New icon for rating button action
com.dreadheadhippy.ampdeck.streamDeckPlugin	Packaged plugin file for simplified installation
README.md	Updated installation instructions, added rating feature documentation
CHANGELOG.md	Comprehensive changelog entries for v1.3.1, v1.3.0, and v1.2.0
.gitignore	Added exclusion for personal notes file

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The "Updating" instructions reference downloading "install.bat" but this appears to be inconsistent with the "Installation" section which uses the .streamDeckPlugin file. For updating an existing plugin, users should typically download the same .streamDeckPlugin file, not install.bat. The README should clarify whether updates use the .streamDeckPlugin file or the install scripts.

Suggested change

	1. Download the latest **`install.bat`** from the [Releases](https://github.com/rackemrack/ampdeck/releases) page
	1. Download the latest **`com.dreadheadhippy.ampdeck.streamDeckPlugin`** from the [Releases](https://github.com/rackemrack/ampdeck/releases) page

[Copilot]

There's a discrepancy between the repository reference in the README and the actual GitHub organization. The URL references "rackemrack/ampdeck" but based on the file name "com.dreadheadhippy.ampdeck.streamDeckPlugin" and the PR metadata showing this is from DreadHeadHippy, this may need to be updated to point to the correct repository URL.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.