feat: user agreement api

Author: xitij2000

openedx/core/djangoapps/agreements/admin.py

@@ -3,7 +3,7 @@
 """
 
 from django.contrib import admin
-from openedx.core.djangoapps.agreements.models import IntegritySignature
+from openedx.core.djangoapps.agreements.models import IntegritySignature, UserAgreement
 from openedx.core.djangoapps.agreements.models import LTIPIITool
 from openedx.core.djangoapps.agreements.models import LTIPIISignature
 from openedx.core.djangoapps.agreements.models import ProctoringPIISignature
@@ -62,3 +62,17 @@ class Meta:
 
 
 admin.site.register(ProctoringPIISignature, ProctoringPIISignatureAdmin)
+
+
+class UserAgreementAdmin(admin.ModelAdmin):
+    """
+    Admin for the UserAgreement Model
+    """
+
+    list_display = ('type', 'name', 'url', 'created', 'updated')
+
+    class Meta:
+        model = UserAgreement
+
+
+admin.site.register(UserAgreement, UserAgreementAdmin)

openedx/core/djangoapps/agreements/api.py

@@ -240,18 +240,17 @@ def _user_signature_out_of_date(username, course_id):
         return user_lti_pii_signature_hash != course_lti_pii_tools_hash
 
 
-def get_user_agreements(user: User) -> Iterable[UserAgreementRecordData]:
+def get_user_agreement_records(user: User) -> Iterable[UserAgreementRecordData]:
     """
     Retrieves all the agreements that the specified user has acknowledged.
     """
-    for agreement_record in UserAgreementRecord.objects.filter(user=user):
+    for agreement_record in UserAgreementRecord.objects.filter(user=user).select_related("agreement"):
         yield UserAgreementRecordData.from_model(agreement_record)
 
 
 def get_latest_user_agreement_record(
     user: User,
     agreement_type: str,
-    agreed_after: datetime = None,
 ) -> Optional[UserAgreementRecordData]:
     """
     Retrieve the user agreement record for the specified user and agreement type.
@@ -262,10 +261,8 @@ def get_latest_user_agreement_record(
     try:
         record_query = UserAgreementRecord.objects.filter(
             user=user,
-            agreement_type=agreement_type,
+            agreement__type=agreement_type,
         )
-        if agreed_after:
-            record_query = record_query.filter(timestamp__gte=agreed_after)
         record = record_query.latest("timestamp")
         return UserAgreementRecordData.from_model(record)
     except UserAgreementRecord.DoesNotExist:
@@ -279,7 +276,7 @@ def create_user_agreement_record(user: User, agreement_type: str) -> UserAgreeme
     """
     record = UserAgreementRecord.objects.create(
         user=user,
-        agreement_type=agreement_type,
+        agreement__type=agreement_type,
         timestamp=datetime.now(),
     )
     return UserAgreementRecordData.from_model(record)

openedx/core/djangoapps/agreements/data.py

@@ -6,7 +6,7 @@
 
 import attr
 
-from .models import UserAgreementRecord
+from .models import UserAgreementRecord, UserAgreement
 
 
 @attr.s(frozen=True, auto_attribs=True)
@@ -28,6 +28,28 @@ class LTIPIISignatureData:
     lti_tools_hash: str
 
 
+
+@dataclass
+class UserAgreementData:
+    """
+    Data for a user agreement record.
+    """
+    type: str
+    name: str
+    summary: str
+    text: str|None
+    url: str|None
+
+    @classmethod
+    def from_model(cls, model: UserAgreement):
+        return UserAgreementData(
+            type=model.type,
+            name=model.name,
+            summary=model.summary,
+            text=model.text,
+            url=model.url
+        )
+
 @dataclass
 class UserAgreementRecordData:
     """
@@ -36,11 +58,13 @@ class UserAgreementRecordData:
     username: str
     agreement_type: str
     accepted_at: datetime
+    is_current: bool = True
 
     @classmethod
     def from_model(cls, model: UserAgreementRecord):
         return UserAgreementRecordData(
             username=model.user.username,
-            agreement_type=model.agreement_type,
+            agreement_type=model.agreement.type,
             accepted_at=model.timestamp,
+            is_current=model.agreement.updated < model.timestamp
         )

openedx/core/djangoapps/agreements/migrations/0007_historicaluseragreement_useragreement_and_more.py

@@ -0,0 +1,63 @@
+# Generated by Django 5.2.10 on 2026-01-26 10:21
+
+import django.db.models.deletion
+import simple_history.models
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('agreements', '0006_useragreementrecord'),
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='HistoricalUserAgreement',
+            fields=[
+                ('id', models.IntegerField(auto_created=True, blank=True, db_index=True, verbose_name='ID')),
+                ('type', models.CharField(db_index=True, max_length=255)),
+                ('name', models.CharField(help_text='Human-readable name for the agreement type. Will be displayed to users in alert to accept the agreement.', max_length=255)),
+                ('summary', models.TextField(help_text='Brief summary of the agreement content. Will be displayed to users in alert to accept the agreement.', max_length=1024)),
+                ('text', models.TextField(blank=True, help_text='Full text of the agreement. (Required if url is not provided)', null=True)),
+                ('url', models.URLField(blank=True, help_text='URL where the full agreement can be accessed. Will be used for "Learn More" link in alert to accept the agreement.', null=True)),
+                ('created', models.DateTimeField(blank=True, editable=False)),
+                ('updated', models.DateTimeField(help_text='Timestamp of the last update to this agreement. If changed users will be prompted to accept the agreement again.')),
+                ('history_id', models.AutoField(primary_key=True, serialize=False)),
+                ('history_date', models.DateTimeField()),
+                ('history_change_reason', models.CharField(max_length=100, null=True)),
+                ('history_type', models.CharField(choices=[('+', 'Created'), ('~', 'Changed'), ('-', 'Deleted')], max_length=1)),
+                ('history_user', models.ForeignKey(null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='+', to=settings.AUTH_USER_MODEL)),
+            ],
+            options={
+                'verbose_name': 'historical user agreement',
+                'verbose_name_plural': 'historical user agreements',
+                'ordering': ('-history_date', '-history_id'),
+                'get_latest_by': ('history_date', 'history_id'),
+            },
+            bases=(simple_history.models.HistoricalChanges, models.Model),
+        ),
+        migrations.CreateModel(
+            name='UserAgreement',
+            fields=[
+                ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('type', models.CharField(max_length=255, unique=True)),
+                ('name', models.CharField(help_text='Human-readable name for the agreement type. Will be displayed to users in alert to accept the agreement.', max_length=255)),
+                ('summary', models.TextField(help_text='Brief summary of the agreement content. Will be displayed to users in alert to accept the agreement.', max_length=1024)),
+                ('text', models.TextField(blank=True, help_text='Full text of the agreement. (Required if url is not provided)', null=True)),
+                ('url', models.URLField(blank=True, help_text='URL where the full agreement can be accessed. Will be used for "Learn More" link in alert to accept the agreement.', null=True)),
+                ('created', models.DateTimeField(auto_now_add=True)),
+                ('updated', models.DateTimeField(help_text='Timestamp of the last update to this agreement. If changed users will be prompted to accept the agreement again.')),
+            ],
+            options={
+                'constraints': [models.CheckConstraint(condition=models.Q(('text__isnull', False), ('url__isnull', False), _connector='OR'), name='agreement_has_text_or_url')],
+            },
+        ),
+        migrations.AddField(
+            model_name='useragreementrecord',
+            name='agreement',
+            field=models.ForeignKey(null=True, on_delete=django.db.models.deletion.CASCADE, related_name='records', to='agreements.useragreement'),
+        ),
+    ]

openedx/core/djangoapps/agreements/migrations/0008_remove_useragreementrecord_agreement_type_and_more.py

@@ -0,0 +1,38 @@
+# Generated by Django 5.2.10 on 2026-01-26 10:22
+
+import django.db.models.deletion
+from django.db import migrations, models
+
+
+
+def migrate_agreement_type(apps, schema_editor):
+    UserAgreementRecord = apps.get_model('agreements', 'UserAgreementRecord')
+    UserAgreement = apps.get_model('agreements', 'UserAgreement')
+    for user_agreement_record in UserAgreementRecord.objects.all():
+        user_agreement_record.agreement = UserAgreement.objects.get_or_create(type=user_agreement_record.agreement_type, defaults=dict(text=''))
+
+
+def migrate_agreement_type_rev(apps, schema_editor):
+    UserAgreementRecord = apps.get_model('agreements', 'UserAgreementRecord')
+    for user_agreement_record in UserAgreementRecord.objects.all():
+        user_agreement_record.agreement_type = user_agreement_record.agreement.type
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('agreements', '0007_historicaluseragreement_useragreement_and_more'),
+    ]
+
+    operations = [
+        migrations.RunPython(migrate_agreement_type, migrate_agreement_type_rev),
+        migrations.RemoveField(
+            model_name='useragreementrecord',
+            name='agreement_type',
+        ),
+        migrations.AlterField(
+            model_name='useragreementrecord',
+            name='agreement',
+            field=models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='records', to='agreements.useragreement'),
+        ),
+    ]

openedx/core/djangoapps/agreements/models.py

@@ -6,6 +6,7 @@
 from django.db import models
 from model_utils.models import TimeStampedModel
 from opaque_keys.edx.django.models import CourseKeyField
+from simple_history.models import HistoricalRecords
 
 User = get_user_model()
 
@@ -72,6 +73,43 @@ class Meta:
         app_label = 'agreements'
 
 
+class UserAgreement(models.Model):
+    """
+    This model stores agreements that as user can accept that can gate certain
+    platform features.
+
+    .. no_pii:
+    """
+    type = models.CharField(max_length=255, unique=True)
+    name = models.CharField(
+        max_length=255,
+        help_text='Human-readable name for the agreement type. Will be displayed to users in alert to accept the agreement.',
+    )
+    summary = models.TextField(
+        max_length=1024,
+        help_text='Brief summary of the agreement content. Will be displayed to users in alert to accept the agreement.',
+    )
+    text = models.TextField(
+        help_text='Full text of the agreement. (Required if url is not provided)',
+        null=True, blank=True,
+    )
+    url = models.URLField(
+        help_text='URL where the full agreement can be accessed. Will be used for "Learn More" link in alert to accept the agreement.',
+        null=True, blank=True,
+    )
+    created = models.DateTimeField(auto_now_add=True)
+    updated = models.DateTimeField(
+        help_text='Timestamp of the last update to this agreement. If changed users will be prompted to accept the agreement again.')
+    history = HistoricalRecords()
+
+    class Meta:
+        app_label = 'agreements'
+        constraints = [
+            models.CheckConstraint(check=models.Q(text__isnull=False) | models.Q(url__isnull=False),
+                                   name='agreement_has_text_or_url')
+        ]
+
+
 class UserAgreementRecord(models.Model):
     """
     This model stores the agreements a user has accepted or acknowledged.
@@ -82,7 +120,7 @@ class UserAgreementRecord(models.Model):
     .. no_pii:
     """
     user = models.ForeignKey(User, db_index=True, on_delete=models.CASCADE)
-    agreement_type = models.CharField(max_length=255)
+    agreement = models.ForeignKey(UserAgreement, on_delete=models.CASCADE, related_name='records')
     timestamp = models.DateTimeField(auto_now_add=True)
 
     class Meta:

openedx/core/djangoapps/agreements/serializers.py

@@ -34,7 +34,19 @@ class Meta:
         fields = ('username', 'course_id', 'lti_tools', 'created_at')
 
 
-class UserAgreementsSerializer(serializers.Serializer):
+class UserAgreementSerializer(serializers.Serializer):
+    """
+    Serializer for UserAgreement model
+    """
+    type = serializers.CharField(read_only=True)
+    name = serializers.CharField(read_only=True)
+    summary = serializers.CharField(read_only=True)
+    text = serializers.CharField(read_only=True)
+    url = serializers.URLField(read_only=True)
+    updated = serializers.DateTimeField(read_only=True)
+
+
+class UserAgreementRecordSerializer(serializers.Serializer):
     """
     Serializer for UserAgreementRecord model
     """

openedx/core/djangoapps/agreements/tests/test_api.py

@@ -22,7 +22,7 @@
     get_lti_pii_signature,
     get_pii_receiving_lti_tools,
     get_latest_user_agreement_record,
-    get_user_agreements
+    get_user_agreement_records
 )
 from ..models import LTIPIITool
 
@@ -201,11 +201,11 @@ def setUp(self):
         self.user = UserFactory()
 
     def test_get_user_agreements(self, ):
-        result = list(get_user_agreements(self.user))
+        result = list(get_user_agreement_records(self.user))
         assert len(result) == 0
 
         record = create_user_agreement_record(self.user, 'test_type')
-        result = list(get_user_agreements(self.user))
+        result = list(get_user_agreement_records(self.user))
 
         assert len(result) == 1
         assert result[0].agreement_type == 'test_type'