feat: subscription&unsubscribe flows - support scope all

[davidgamez]

Summary:

This pull request introduces a one-click unsubscribe feature for notification emails by adding capability-based unsubscribe links, enhances the subscription deletion API to support batch unsubscription, and updates documentation and tests to reflect these changes. The unsubscribe links now point to a dedicated endpoint that securely identifies the subscription by its UUID, and the API supports both single and "unsubscribe from all" operations.

Unsubscribe link and email notification improvements:

• Added a one-click unsubscribe link to notification emails, generated by the new _unsubscribe_url function, which encodes the subscription UUID as a capability in the URL (/notifications/unsubscribe?id=...). The link is included in both single and digest email templates and only appears if a subscription ID is present. [1] [2] [3] [4]
• Updated tests to verify that unsubscribe links are correctly generated, encoded, and included in email footers. [1] [2] [3]

Subscription deletion API enhancements:

• Extended the delete_subscription API to accept an optional scope parameter. When scope='all', the API unsubscribes the user from all notification types (except for announcements, which are disabled rather than deleted); otherwise, it only unsubscribes the specified subscription. [1] [2] [3]
• Added and updated unit tests to cover the new batch unsubscription behavior and edge cases (e.g., missing subscriptions, announcements-only behavior).

Documentation updates:

• Clarified the purpose and security model of the subscriptions API in UserServiceAPI.yaml, emphasizing capability-based access and the lack of end-user authentication for these endpoints. Improved descriptions for parameters and documented the new unsubscribe flow. [1] [2] [3] [4] [5]

Internal code and test improvements:

• Refactored and documented internal helper methods for building unsubscribe URLs and managing subscription footers.
• Improved test coverage for unsubscribe URL generation and footer rendering.

These changes collectively improve the user experience for unsubscribing from notifications, enhance API flexibility, and ensure the documentation and test suite accurately reflect the new behavior.

Expected behavior:

Explain and/or show screenshots for how you expect the pull request to work in your testing (in case other devices exhibit different behavior).

Testing tips:

Provide tips, procedures and sample files on how to test the feature.
Testers are invited to follow the tips AND to try anything they deem relevant outside the bounds of the testing tips.

Please make sure these boxes are checked before submitting your pull request - thanks!

• Run the unit tests with ./scripts/api-tests.sh to make sure you didn't break anything
• Add or update any needed documentation to the repo
• Format the title like "feat: [new feature short description]". Title must follow the Conventional Commit Specification(https://www.conventionalcommits.org/en/v1.0.0/).
• Linked all relevant issues
• Include screenshot(s) showing how this pull request works and fixes the issue(s)