feat: Add Brevo list update as part of migrate_firebase_users & consistent update brevo list

[davidgamez]

Summary:

This PR updates the Firebase migration script by adding the MDB_SUBSCRIPTION_ID to Brevo per user. Uses brevo_synced_at to mark users as already synced.
To complete the Brevo announcements configuration, it also updates the is_registered_to_receive_api_announcements function to add/remove users from the Brevo list. This replaces the monthly manual imports and keeps the list up to date with the latest subscriptions.

From our AI friend

This pull request introduces a unified and consistent approach for managing a user's opt-in status for API announcements, ensuring that the database, notification subscriptions, and Brevo (email provider) are always kept in sync. The core logic is centralized in a new helper function, and all relevant API endpoints and tests are updated to use this logic. Additionally, the Firebase migration documentation and logic are improved to clarify the handling of Brevo synchronization and the brevo_synced_at field.

Announcement opt-in synchronization improvements:

• Introduced set_announcements_optin in subscription_helpers.py, which atomically reconciles a user's announcements subscription, Brevo list membership, and the is_registered_to_receive_api_announcements flag, handling both subscribe and unsubscribe flows and ensuring all representations are consistent.
• Updated all API endpoints (users_api_impl.py and subscriptions_api_impl.py) to use set_announcements_optin instead of directly manipulating subscriptions or making Brevo calls, including proper handling of DB transactions and connection pooling for slow providers. [1] [2] [3] [4] [5] [6]
• Improved unit tests to verify the new behavior, including creation, deactivation, idempotency, and error handling for the announcements opt-in logic.

Firebase migration logic and documentation:

• Clarified and expanded the documentation for the migrate_firebase_users task, describing the new logic for backfilling notification subscriptions, writing MDB_SUBSCRIPTION_ID to Brevo contacts, and updating the brevo_synced_at field only after successful synchronization. New result counters are documented. [1] [2] [3]
• Updated the migration task's description to reflect that brevo_synced_at is now the only field updated on existing users, and to highlight the idempotent Brevo write-back logic.

Codebase cleanup and consistency:

• Replaced all direct calls to sync_announcements with the new set_announcements_optin helper in both implementation files and imports, ensuring a single point of truth for the synchronization logic. [1] [2]

These changes close historical bugs where the user's opt-in flag, notification subscription, and Brevo list membership could become inconsistent, and ensure all future updates remain atomic and reliable.
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.

Testing tips

Registration / profile opt-in (user_service)

• PUT /v1/user with is_registered_to_receive_api_announcements: true → check: api.announcements subscription row created, contact added to the Brevo list with MDB_SUBSCRIPTION_ID set, and the profile flag is true.
• Set it back to false → contact removed from the list, subscription disabled (not deleted), flag false.
• Re-send the same value (or update only full_name) → no Brevo call.
• Subscribe/unsubscribe via the subscription endpoints → the profile boolean stays in sync too.

Migration task (migrate_firebase_users, #1733)

• Run with dry_run: true → check brevo_synced / brevo_sync_failed counts, no writes.
• Run with dry_run: false (start with a small limit) → SUBSCRIBED contacts get MDB_SUBSCRIPTION_ID, app_user.brevo_synced_at is stamped.
• Run again → already-synced users are skipped (idempotent); UNSUBSCRIBED/NOT_FOUND contacts are never added to the list.

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)

[davidgamez]

Brevo logs: