Audiobook time tracking

alembic/versions/20230720_4476624597a5_playtime_tracking.py

@@ -0,0 +1,70 @@
+"""Playtime tracking
+
+Revision ID: 4476624597a5
+Revises: 3d380776c1bf
+Create Date: 2023-07-20 09:30:39.384787+00:00
+
+"""
+import sqlalchemy as sa
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision = "4476624597a5"
+down_revision = "3d380776c1bf"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # ### commands auto generated by Alembic ###
+    op.create_table(
+        "identifier_playtime_entries",
+        sa.Column("id", sa.Integer(), autoincrement=True, nullable=False),
+        sa.Column("identifier_id", sa.Integer(), nullable=False),
+        sa.Column("timestamp", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("total_seconds_played", sa.Integer(), nullable=False),
+        sa.Column("tracking_id", sa.String(length=64), nullable=False),
+        sa.Column("processed", sa.Boolean(), nullable=True),
+        sa.ForeignKeyConstraint(
+            ["identifier_id"],
+            ["identifiers.id"],
+            onupdate="CASCADE",
+            ondelete="CASCADE",
+        ),
+        sa.PrimaryKeyConstraint("id"),
+        sa.UniqueConstraint("identifier_id", "tracking_id"),
+    )
+    op.create_table(
+        "identifier_playtimes",
+        sa.Column("id", sa.Integer(), autoincrement=True, nullable=False),
+        sa.Column("identifier_id", sa.Integer(), nullable=True),
+        sa.Column("identifier_str", sa.String(), nullable=False),
+        sa.Column("timestamp", sa.DateTime(), nullable=False),
+        sa.Column("total_seconds_played", sa.Integer(), nullable=True),
+        sa.ForeignKeyConstraint(
+            ["identifier_id"],
+            ["identifiers.id"],
+            onupdate="CASCADE",
+            ondelete="SET NULL",
+        ),
+        sa.PrimaryKeyConstraint("id"),
+        sa.UniqueConstraint("identifier_str", "timestamp"),
+    )
+    op.create_index(
+        op.f("ix_identifier_playtimes_identifier_id"),
+        "identifier_playtimes",
+        ["identifier_id"],
+        unique=False,
+    )
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    # ### commands auto generated by Alembic ###
+    op.drop_index(
+        op.f("ix_identifier_playtimes_identifier_id"), table_name="identifier_playtimes"
+    )
+    op.drop_table("identifier_playtimes")
+    op.drop_table("identifier_playtime_entries")
+    # ### end Alembic commands ###

api/controller.py

@@ -17,11 +17,18 @@
 from flask import Response, make_response, redirect
 from flask_babel import lazy_gettext as _
 from lxml import etree
+from pydantic import ValidationError
+from sqlalchemy.exc import IntegrityError
 from sqlalchemy.orm import eagerload
 from sqlalchemy.orm.exc import NoResultFound
 
 from api.authentication.access_token import AccessTokenProvider
 from api.model.patron_auth import PatronAuthAccessToken
+from api.model.time_tracking import (
+    PlaytimeEntriesPost,
+    PlaytimeEntriesPostResponse,
+    PlaytimeEntriesPostSummary,
+)
 from api.opds2 import OPDS2NavigationsAnnotator, OPDS2PublicationsAnnotator
 from api.saml.controller import SAMLController
 from core.analytics import Analytics
@@ -66,13 +73,15 @@
     Patron,
     Representation,
     Session,
+    create,
     get_one,
 )
 from core.model.devicetokens import (
     DeviceToken,
     DuplicateDeviceTokenError,
     InvalidTokenTypeError,
 )
+from core.model.time_tracking import IdentifierPlaytimeEntry
 from core.opds import AcquisitionFeed, NavigationFacets, NavigationFeed
 from core.opds2 import AcquisitonFeedOPDS2
 from core.opensearch import OpenSearchDocument
@@ -189,6 +198,7 @@ class CirculationManager:
     odl_notification_controller: ODLNotificationController
     shared_collection_controller: SharedCollectionController
     static_files: StaticFileController
+    playtime_entries: PlaytimeEntriesController
 
     # Admin controllers
     admin_sign_in_controller: SignInController
@@ -458,6 +468,7 @@ def setup_one_time_controllers(self):
         self.shared_collection_controller = SharedCollectionController(self)
         self.static_files = StaticFileController(self)
         self.patron_auth_token = PatronAuthTokenController(self)
+        self.playtime_entries = PlaytimeEntriesController(self)
 
         from api.lcp.controller import LCPController
 
@@ -2421,6 +2432,67 @@ def track_event(self, identifier_type, identifier, event_type):
             return INVALID_ANALYTICS_EVENT_TYPE
 
 
+class PlaytimeEntriesController(CirculationManagerController):
+    def track_playtimes(self, identifier_type, identifier):
+        library: Library = flask.request.library
+        identifier = get_one(
+            self._db, Identifier, type=identifier_type, identifier=identifier
+        )
+
+        if not identifier:
+            return NOT_FOUND_ON_REMOTE.detailed(
+                f"The identifier {identifier_type}/{identifier} was not found."
+            )
+
+        try:
+            data = PlaytimeEntriesPost(**flask.request.json)
+        except ValidationError as ex:
+            return INVALID_INPUT.detailed(ex.json())
+
+        responses = []
+        summary = PlaytimeEntriesPostSummary()
+        for entry in data.time_entries:
+            status_code = 201
+            message = "Created"
+            transaction = self._db.begin_nested()
+            try:
+                playtime_entry, _ = create(
+                    self._db,
+                    IdentifierPlaytimeEntry,
+                    tracking_id=entry.id,
+                    identifier_id=identifier.id,
+                    timestamp=entry.during_minute,
+                    total_seconds_played=entry.seconds_played,
+                )
+            except IntegrityError as ex:
+                logging.getLogger("Time Tracking").error(
+                    f"Playtime entry failure {entry.id}: {ex}"
+                )
+                # A duplicate is reported as a success, since we have already recorded this value
+                if "UniqueViolation" in str(ex):
+                    summary.successes += 1
+                    status_code = 200
+                    message = "OK"
+                else:
+                    status_code = 400
+                    message = str(ex.orig)
+                    summary.failures += 1
+                transaction.rollback()
+            else:
+                summary.successes += 1
+                transaction.commit()
+
+            responses.append(dict(id=entry.id, status=status_code, message=message))
+            summary.total += 1
+
+        response_data = PlaytimeEntriesPostResponse(
+            summary=summary, responses=responses
+        )
+        response = flask.jsonify(response_data.dict())
+        response.status_code = 207
+        return response
+
+
 class ODLNotificationController(CirculationManagerController):
     """Receive notifications from an ODL distributor when the
     status of a loan changes.

api/model/time_tracking.py

@@ -0,0 +1,57 @@
+import datetime
+import logging
+from typing import Any, Dict, List
+
+from pydantic import Field, validator
+
+from core.util.flask_util import CustomBaseModel
+
+
+class PlaytimeTimeEntry(CustomBaseModel):
+    id: str = Field(description="An id to ensure uniqueness of the time entry")
+    during_minute: datetime.datetime = Field(
+        description="A minute bounday datetime of the format yyyy-mm-ddThh:mmZ"
+    )
+    seconds_played: int = Field(
+        description="How many seconds were played within this minute"
+    )
+
+    @validator("during_minute")
+    def validate_minute_datetime(cls, value: datetime.datetime):
+        """Coerce the datetime to a minute boundary"""
+        if value.tzname() != "UTC":
+            logging.getLogger("TimeTracking").error(
+                f"An incorrect timezone was received for a playtime ({value.tzname()})."
+            )
+            raise ValueError("Timezone MUST be UTC always")
+        value = value.replace(second=0, microsecond=0)
+        return value
+
+    @validator("seconds_played")
+    def validate_seconds_played(cls, value: int):
+        """Coerce the seconds played to a max of 60 seconds"""
+        if value > 60:
+            logging.getLogger("TimeTracking").warning(
+                "Greater than 60 seconds was received for a minute playtime."
+            )
+            value = 60
+        return value
+
+
+class PlaytimeEntriesPost(CustomBaseModel):
+    time_entries: List[PlaytimeTimeEntry] = Field(description="A List of time entries")
+
+
+class PlaytimeEntriesPostSummary(CustomBaseModel):
+    total: int = 0
+    successes: int = 0
+    failures: int = 0
+
+
+class PlaytimeEntriesPostResponse(CustomBaseModel):
+    responses: List[Dict[str, Any]] = Field(
+        description="Responses as part of the multi-reponse"
+    )
+    summary: PlaytimeEntriesPostSummary = Field(
+        description="Summary of failures and successes"
+    )

api/opds.py

@@ -32,6 +32,7 @@
     Patron,
     Session,
 )
+from core.model.constants import EditionConstants, LinkRelations
 from core.model.formats import FormatPriorities
 from core.model.integration import IntegrationConfiguration
 from core.opds import AcquisitionFeed, Annotator, UnfulfillableWork
@@ -786,6 +787,19 @@ def annotate_work_entry(
                 ),
             )
 
+        if edition.medium == EditionConstants.AUDIO_MEDIUM:
+            feed.add_link_to_entry(
+                entry,
+                rel=LinkRelations.TIME_TRACKING,
+                href=self.url_for(
+                    "track_playtime_events",
+                    identifier_type=identifier.type,
+                    identifier=identifier.identifier,
+                    library_short_name=self.library.short_name,
+                    _external=True,
+                ),
+            )
+
     @classmethod
     def related_books_available(cls, work, library):
         """:return: bool asserting whether related books might exist for a particular Work"""

api/routes.py

@@ -672,6 +672,14 @@ def track_analytics_event(identifier_type, identifier, event_type):
     )
 
 
+@library_route("/playtimes/<identifier_type>/<path:identifier>", methods=["POST"])
+@has_library
+@allows_auth
+@returns_problem_detail
+def track_playtime_events(identifier_type, identifier):
+    return app.manager.playtime_entries.track_playtimes(identifier_type, identifier)
+
+
 # Route that redirects to the authentication URL for a SAML provider
 @library_route("/saml_authenticate")
 @has_library

bin/playtime_reporting

@@ -0,0 +1,13 @@
+#!/usr/bin/env python
+"""Sum the playtimes for audiobooks."""
+import os
+import sys
+
+bin_dir = os.path.split(__file__)[0]
+package_dir = os.path.join(bin_dir, "..")
+sys.path.append(os.path.abspath(package_dir))
+
+from core.jobs.playtime_entries import PlaytimeEntriesEmailReportsScript
+from core.model import production_session
+
+PlaytimeEntriesEmailReportsScript(production_session(initialize_data=False)).run()

bin/playtime_summation

@@ -0,0 +1,13 @@
+#!/usr/bin/env python
+"""Sum the playtimes for audiobooks."""
+import os
+import sys
+
+bin_dir = os.path.split(__file__)[0]
+package_dir = os.path.join(bin_dir, "..")
+sys.path.append(os.path.abspath(package_dir))
+
+from core.jobs.playtime_entries import PlaytimeEntriesSummationScript
+from core.model import production_session
+
+PlaytimeEntriesSummationScript(production_session(initialize_data=False)).run()

core/config.py

@@ -53,6 +53,9 @@ class Configuration(ConfigurationConstants):
     # Environment variable for SirsiDynix Auth
     SIRSI_DYNIX_APP_ID = "SIMPLIFIED_SIRSI_DYNIX_APP_ID"
 
+    # Environment variable for temporary reporting email
+    REPORTING_EMAIL_ENVIRONMENT_VARIABLE = "SIMPLIFIED_REPORTING_EMAIL"
+
     # ConfigurationSetting key for the base url of the app.
     BASE_URL_KEY = "base_url"