Task/newsletter endpoint (#2692)

* Integrate pyairtable & Newsletter plumbing

- Added `pyairtable` to the project
- Implemented a barebones `AirtableClient` for quick access to the
  pyairtable api
- Implemented a NewsletterSubscriber pyairtable ORM model that:
  - Behaves similarly to SQLAlchemy models
  - Handles adding an unconfirmed subscriber, confirm subscriber,
    unsubscribe, update language, and reactivate subscription
functionality
- Added an AirtableMixin class to enhance table management allowing us
  to:
  - Check if the table associated with a model exists already
  - Create the table on the fly when creating models if it doesn't exist
    yet
  - Ensure implementing models define a table_schema with which to
    generate said table from

* Add flask ctx to model, enhance mixin impl

- The airtable mixin can now have the flask application context injected
  into it
- NewsletterSubscriber's Meta class now uses static methods for the
  `api_key` and `base_id` as they need to be dynamically fetched from
the app context
- The mixin now also overrides the `pyairtable.orm.Model.save()` method,
  encapsulating the table generation logic within
- Added unit tests

* Update env vars & squash a couple client bugs

* Add route `/newsletter` for newsletter management

Added the following new routes for interacting with the mailing list
  airtable client / model
- `/newsletter/confirm/<subscriber_id>`
- `/newsletter/unconfirmed-subscriber`
- `/newsletter/unsubscribe/<subscriber_id>`
- `/newsletter/update-language/<subscriber_id>`
- `/newsletter/find-subscriber`

* Fix typing issues and tests

* Correct route methods & cleanup tests

* Refresh poetry.lock

* Refresh poetry.lock

* Fix tests

* Use a separate airtable for staging

* Small typo fix

* Added a `/resubscribe` endpoint

- Updated endpoints to make use of `InvalidRequest` instead of
  jsonifying error messages
- Updated tests

* Update auth requirements for newsletter endpoint

- Clean up ugly tests
- Use request args for `/find-subscriber`

* Cleanup config

* Add confirmation email sending

Author: whabanks

app/__init__.py

@@ -206,6 +206,7 @@ def register_blueprint(application):
     from app.job.rest import job_blueprint
     from app.letter_branding.letter_branding_rest import letter_branding_blueprint
     from app.letters.rest import letter_job
+    from app.newsletter.rest import newsletter_blueprint
     from app.notifications.notifications_letter_callback import (
         letter_callback_blueprint,
     )
@@ -289,6 +290,8 @@ def register_blueprint(application):
 
     register_notify_blueprint(application, report_blueprint, requires_admin_auth)
 
+    register_notify_blueprint(application, newsletter_blueprint, requires_admin_auth)
+
 
 def register_v2_blueprints(application):
     from app.authentication.auth import requires_auth, requires_no_auth

app/clients/airtable/models.py

@@ -94,7 +94,7 @@ def __init__(self, **fields):
     created_at = F.DatetimeField("Created At")
     confirmed_at = F.DatetimeField("Confirmed At")
     unsubscribed_at = F.DatetimeField("Unsubscribed At")
-    has_resubscribed = F.CheckboxField("HasResubscribed")
+    has_resubscribed = F.CheckboxField("Has Resubscribed")
 
     class Languages(Enum):
         EN = "en"
@@ -152,6 +152,7 @@ def reactivate_subscription(self, language: str) -> SaveResult:
         self.status = self.Statuses.SUBSCRIBED.value
         self.language = language
         self.has_resubscribed = True
+        self.confirmed_at = datetime.now()
         return self.save()
 
     @classmethod

app/config.py

@@ -213,7 +213,7 @@ class Config(object):
 
     # Airtable
     AIRTABLE_API_KEY = os.getenv("AIRTABLE_API_KEY")
-    AIRTABLE_NEWSLETTER_BASE_ID = os.getenv("AIRTABLE_NEWSLETTER_BASE_ID")
+    AIRTABLE_NEWSLETTER_BASE_ID = os.getenv("AIRTABLE_NEWSLETTER_BASE_ID", "appCP2c4xvXxQOfhN")
     AIRTABLE_NEWSLETTER_TABLE_NAME = os.getenv("AIRTABLE_NEWSLETTER_TABLE_NAME", "Mailing List")
 
     # Salesforce

app/newsletter/__init__.py

@@ -0,0 +1,174 @@
+from flask import Blueprint, current_app, jsonify, request
+
+from app.clients.airtable.models import NewsletterSubscriber
+from app.config import QueueNames
+from app.dao.templates_dao import dao_get_template_by_id
+from app.errors import InvalidRequest, register_errors
+from app.models import EMAIL_TYPE, KEY_TYPE_NORMAL, Service
+from app.notifications.process_notifications import persist_notification, send_notification_to_queue
+
+newsletter_blueprint = Blueprint("newsletter", __name__, url_prefix="/newsletter")
+register_errors(newsletter_blueprint)
+
+
+@newsletter_blueprint.route("/unconfirmed-subscriber", methods=["POST"])
+def create_unconfirmed_subscription():
+    data = request.get_json()
+    email = data.get("email")
+    language = data.get("language", "en")
+
+    if not email:
+        raise InvalidRequest("Email is required", status_code=400)
+
+    # Create a new unconfirmed subscriber
+    subscriber = NewsletterSubscriber(email=email, language=language)
+    result = subscriber.save_unconfirmed_subscriber()
+
+    # Check if the save operation succeeded
+    if not result.saved:
+        current_app.logger.error("Failed to create unconfirmed mailing list subscriber. Record was not saved")
+        raise InvalidRequest("Failed to create unconfirmed mailing list subscriber.", status_code=500)
+
+    send_confirmation_email(subscriber.id, subscriber.email, subscriber.language)
+
+    return jsonify(result="success", subscriber_id=subscriber.id), 201
+
+
+@newsletter_blueprint.route("/confirm/<subscriber_id>", methods=["POST"])
+def confirm_subscription(subscriber_id):
+    subscriber = NewsletterSubscriber.from_id(record_id=subscriber_id)
+
+    if not subscriber:
+        raise InvalidRequest("Subscriber not found", status_code=404)
+
+    result = subscriber.confirm_subscription()
+
+    if not result.saved:
+        current_app.logger.error(
+            f"Failed to confirm newsletter subscription for subscriber_id: {subscriber.id}. Record was not saved"
+        )
+        raise InvalidRequest("Subscription confirmation failed", status_code=500)
+
+    return jsonify(result="success", message="Subscription confirmed", subscriber_id=subscriber.id), 200
+
+
+@newsletter_blueprint.route("/unsubscribe/<subscriber_id>", methods=["POST"])
+def unsubscribe(subscriber_id):
+    subscriber = NewsletterSubscriber.from_id(subscriber_id)
+
+    if not subscriber:
+        raise InvalidRequest("Subscriber not found", status_code=404)
+
+    result = subscriber.unsubscribe_user()
+
+    if not result.saved:
+        current_app.logger.error(f"Failed to unsubscribe newsletter subscriber: {subscriber.id}. Record was not saved")
+        raise InvalidRequest("Unsubscription failed", status_code=500)
+
+    return jsonify(result="success", message="Unsubscribed successfully", subscriber_id=subscriber.id), 200
+
+
+@newsletter_blueprint.route("/update-language/<subscriber_id>", methods=["POST"])
+def update_language_preferences(subscriber_id):
+    data = request.get_json()
+    new_language = data.get("language")
+
+    if not new_language:
+        raise InvalidRequest("New language is required", status_code=400)
+
+    subscriber = NewsletterSubscriber.from_id(subscriber_id)
+
+    if not subscriber:
+        raise InvalidRequest("Subscriber not found", status_code=404)
+
+    result = subscriber.update_language(new_language)
+
+    if not result.saved:
+        current_app.logger.error(
+            f"Failed to update language preferences for newsletter subscriber: {subscriber.id}. Record was not saved"
+        )
+        raise InvalidRequest("Language update failed", status_code=500)
+
+    return jsonify(result="success", message="Language updated successfully", subscriber_id=subscriber.id), 200
+
+
+@newsletter_blueprint.route("/resubscribe/<subscriber_id>", methods=["POST"])
+def reactivate_subscription(subscriber_id):
+    data = request.get_json()
+    language = data.get("language")
+
+    if not language:
+        raise InvalidRequest("Language is required to resubscribe", status_code=400)
+
+    subscriber = NewsletterSubscriber.from_id(subscriber_id)
+
+    if not subscriber:
+        raise InvalidRequest("Subscriber not found", status_code=404)
+
+    result = subscriber.reactivate_subscription(language)
+
+    if not result.saved:
+        current_app.logger.error(
+            f"Failed to reactivate newsletter subscription for subscriber: {subscriber.id}. Record was not saved"
+        )
+        raise InvalidRequest("Resubscription failed", status_code=500)
+
+    return jsonify(result="success", message="Resubscribed successfully", subscriber_id=subscriber.id), 200
+
+
+@newsletter_blueprint.route("/find-subscriber", methods=["GET"])
+def get_subscriber():
+    subscriber_id = request.args.get("subscriber_id")
+    email = request.args.get("email")
+
+    if not subscriber_id and not email:
+        raise InvalidRequest("Subscriber ID or email is required", status_code=400)
+
+    if subscriber_id:
+        subscriber = NewsletterSubscriber.from_id(subscriber_id)
+    elif email:
+        subscriber = NewsletterSubscriber.from_email(email)
+
+    if not subscriber:
+        raise InvalidRequest("Subscriber not found", status_code=404)
+
+    subscriber_data = {
+        "id": subscriber.id,
+        "email": subscriber.email,
+        "language": subscriber.language,
+        "status": subscriber.status,
+        "created_at": subscriber.created_at,
+        "confirmed_at": subscriber.confirmed_at,
+        "unsubscribed_at": subscriber.unsubscribed_at,
+    }
+
+    return jsonify(result="success", subscriber=subscriber_data), 200
+
+
+def send_confirmation_email(subscriber_id, recipient_email, language):
+    template_id = (
+        current_app.config["NEWSLETTER_CONFIRMATION_EMAIL_TEMPLATE_ID_EN"]
+        if language == "en"
+        else current_app.config["NEWSLETTER_CONFIRMATION_EMAIL_TEMPLATE_ID_FR"]
+    )
+    template = dao_get_template_by_id(template_id)
+    service = Service.query.get(current_app.config["NOTIFY_SERVICE_ID"])
+
+    from notifications_utils.url_safe_token import generate_token
+
+    token = generate_token(subscriber_id, current_app.config["SECRET_KEY"])
+    # TODO: update this URL when we know for sure what the admin endpoint will be
+    url = f"{current_app.config["ADMIN_BASE_URL"]}/newsletter-subscription/confirm/{token}"
+
+    saved_notification = persist_notification(
+        template_id=template_id,
+        template_version=template.version,
+        recipient=recipient_email,
+        service=service,
+        personalisation={"confirmation_link": url},
+        notification_type=EMAIL_TYPE,
+        api_key_id=None,
+        key_type=KEY_TYPE_NORMAL,
+    )
+
+    send_notification_to_queue(saved_notification, False, queue=QueueNames.NOTIFY)