django-nativemojo 0.1.10__py3-none-any.whl → 0.1.16__py3-none-any.whl

mojo/apps/account/migrations/0006_add_device_tracking_models.py

@@ -0,0 +1,72 @@
+# Generated by Django 4.2.21 on 2025-08-28
+
+from django.conf import settings
+from django.db import migrations, models
+import django.db.models.deletion
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('account', '0005_group_last_activity'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='GeoLocatedIP',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('created', models.DateTimeField(auto_now_add=True)),
+                ('modified', models.DateTimeField(auto_now=True, db_index=True)),
+                ('ip_address', models.GenericIPAddressField(db_index=True, unique=True)),
+                ('country_code', models.CharField(blank=True, db_index=True, max_length=3, null=True)),
+                ('country_name', models.CharField(blank=True, max_length=100, null=True)),
+                ('region', models.CharField(blank=True, db_index=True, max_length=100, null=True)),
+                ('city', models.CharField(blank=True, max_length=100, null=True)),
+                ('postal_code', models.CharField(blank=True, max_length=20, null=True)),
+                ('latitude', models.FloatField(blank=True, null=True)),
+                ('longitude', models.FloatField(blank=True, null=True)),
+                ('timezone', models.CharField(blank=True, max_length=50, null=True)),
+                ('provider', models.CharField(blank=True, max_length=50, null=True)),
+                ('data', models.JSONField(blank=True, default=dict)),
+                ('expires_at', models.DateTimeField(blank=True, default=None, null=True)),
+            ],
+            options={
+                'verbose_name': 'Geolocated IP',
+                'verbose_name_plural': 'Geolocated IPs',
+            },
+        ),
+        migrations.CreateModel(
+            name='UserDevice',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('duid', models.CharField(db_index=True, max_length=255)),
+                ('device_info', models.JSONField(blank=True, default=dict)),
+                ('user_agent_hash', models.CharField(blank=True, db_index=True, max_length=64, null=True)),
+                ('last_ip', models.GenericIPAddressField(blank=True, null=True)),
+                ('first_seen', models.DateTimeField(auto_now_add=True)),
+                ('last_seen', models.DateTimeField(auto_now=True)),
+                ('user', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='devices', to=settings.AUTH_USER_MODEL)),
+            ],
+            options={
+                'ordering': ['-last_seen'],
+                'unique_together': {('user', 'duid')},
+            },
+        ),
+        migrations.CreateModel(
+            name='UserDeviceLocation',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('user', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='device_locations_direct', to=settings.AUTH_USER_MODEL)),
+                ('ip_address', models.GenericIPAddressField(db_index=True)),
+                ('first_seen', models.DateTimeField(auto_now_add=True)),
+                ('last_seen', models.DateTimeField(auto_now=True)),
+                ('geolocation', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='device_locations', to='account.geolocatedip')),
+                ('user_device', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='locations', to='account.userdevice')),
+            ],
+            options={
+                'ordering': ['-last_seen'],
+                'unique_together': {('user', 'user_device', 'ip_address')},
+            },
+        ),
+    ]

mojo/apps/account/migrations/0007_delete_userdevicelocation.py

@@ -0,0 +1,16 @@
+# Generated by Django 4.2.21 on 2025-08-28 16:24
+
+from django.db import migrations
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('account', '0006_add_device_tracking_models'),
+    ]
+
+    operations = [
+        migrations.DeleteModel(
+            name='UserDeviceLocation',
+        ),
+    ]

mojo/apps/account/migrations/0008_userdevicelocation.py

@@ -0,0 +1,33 @@
+# Generated by Django 4.2.21 on 2025-08-28 22:30
+
+from django.conf import settings
+from django.db import migrations, models
+import django.db.models.deletion
+import mojo.models.rest
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('account', '0007_delete_userdevicelocation'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='UserDeviceLocation',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('ip_address', models.GenericIPAddressField(db_index=True)),
+                ('first_seen', models.DateTimeField(auto_now_add=True)),
+                ('last_seen', models.DateTimeField(auto_now=True)),
+                ('geolocation', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='device_locations', to='account.geolocatedip')),
+                ('user', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='device_locations_direct', to=settings.AUTH_USER_MODEL)),
+                ('user_device', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='locations', to='account.userdevice')),
+            ],
+            options={
+                'ordering': ['-last_seen'],
+                'unique_together': {('user', 'user_device', 'ip_address')},
+            },
+            bases=(models.Model, mojo.models.rest.MojoModel),
+        ),
+    ]

mojo/apps/account/migrations/0009_geolocatedip_subnet.py

@@ -0,0 +1,18 @@
+# Generated by Django 4.2.21 on 2025-08-29 00:23
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('account', '0008_userdevicelocation'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='geolocatedip',
+            name='subnet',
+            field=models.CharField(db_index=True, default=None, max_length=16, null=True),
+        ),
+    ]

mojo/apps/account/migrations/0010_group_avatar.py

@@ -0,0 +1,20 @@
+# Generated by Django 4.2.21 on 2025-08-29 03:04
+
+from django.db import migrations, models
+import django.db.models.deletion
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('fileman', '0011_alter_filerendition_original_file'),
+        ('account', '0009_geolocatedip_subnet'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='group',
+            name='avatar',
+            field=models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='+', to='fileman.file'),
+        ),
+    ]

mojo/apps/account/migrations/0011_user_org_registereddevice_pushconfig_and_more.py

@@ -0,0 +1,118 @@
+# Generated by Django 4.2.21 on 2025-08-30 02:36
+
+from django.conf import settings
+from django.db import migrations, models
+import django.db.models.deletion
+import mojo.models.rest
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('account', '0010_group_avatar'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='user',
+            name='org',
+            field=models.ForeignKey(blank=True, help_text='Default organization for this user', null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='org_users', to='account.group'),
+        ),
+        migrations.CreateModel(
+            name='RegisteredDevice',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('created', models.DateTimeField(auto_now_add=True, db_index=True)),
+                ('modified', models.DateTimeField(auto_now=True, db_index=True)),
+                ('device_token', models.TextField(db_index=True, help_text='Push token from platform')),
+                ('device_id', models.CharField(db_index=True, help_text='App-provided device ID', max_length=255)),
+                ('platform', models.CharField(choices=[('ios', 'iOS'), ('android', 'Android'), ('web', 'Web')], db_index=True, max_length=20)),
+                ('app_version', models.CharField(blank=True, max_length=50)),
+                ('os_version', models.CharField(blank=True, max_length=50)),
+                ('device_name', models.CharField(blank=True, max_length=100)),
+                ('push_enabled', models.BooleanField(db_index=True, default=True)),
+                ('push_preferences', models.JSONField(blank=True, default=dict, help_text='Category-based notification preferences')),
+                ('is_active', models.BooleanField(db_index=True, default=True)),
+                ('last_seen', models.DateTimeField(auto_now=True)),
+                ('user', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='registered_devices', to=settings.AUTH_USER_MODEL)),
+            ],
+            options={
+                'ordering': ['-last_seen'],
+                'unique_together': {('user', 'device_id'), ('device_token', 'platform')},
+            },
+            bases=(models.Model, mojo.models.rest.MojoModel),
+        ),
+        migrations.CreateModel(
+            name='PushConfig',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('mojo_secrets', models.TextField(blank=True, default=None, null=True)),
+                ('created', models.DateTimeField(auto_now_add=True, db_index=True)),
+                ('modified', models.DateTimeField(auto_now=True, db_index=True)),
+                ('name', models.CharField(help_text='Configuration name', max_length=100)),
+                ('is_active', models.BooleanField(db_index=True, default=True)),
+                ('apns_enabled', models.BooleanField(default=False)),
+                ('apns_key_id', models.CharField(blank=True, max_length=100)),
+                ('apns_team_id', models.CharField(blank=True, max_length=100)),
+                ('apns_bundle_id', models.CharField(blank=True, max_length=255)),
+                ('apns_key_file', models.TextField(blank=True, help_text='Encrypted via MojoSecrets')),
+                ('apns_use_sandbox', models.BooleanField(default=False)),
+                ('fcm_enabled', models.BooleanField(default=False)),
+                ('fcm_server_key', models.TextField(blank=True, help_text='Encrypted via MojoSecrets')),
+                ('fcm_sender_id', models.CharField(blank=True, max_length=100)),
+                ('default_sound', models.CharField(default='default', max_length=50)),
+                ('default_badge_count', models.IntegerField(default=1)),
+                ('group', models.OneToOneField(blank=True, help_text='Organization for this config. Null = system default', null=True, on_delete=django.db.models.deletion.CASCADE, related_name='push_config', to='account.group')),
+            ],
+            options={
+                'ordering': ['group__name', 'name'],
+            },
+            bases=(models.Model, mojo.models.rest.MojoModel),
+        ),
+        migrations.CreateModel(
+            name='NotificationTemplate',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('created', models.DateTimeField(auto_now_add=True, db_index=True)),
+                ('modified', models.DateTimeField(auto_now=True, db_index=True)),
+                ('name', models.CharField(db_index=True, max_length=100)),
+                ('title_template', models.CharField(max_length=200)),
+                ('body_template', models.TextField()),
+                ('action_url', models.URLField(blank=True, help_text='Template URL with variable support', null=True)),
+                ('category', models.CharField(db_index=True, default='general', max_length=50)),
+                ('priority', models.CharField(choices=[('low', 'Low'), ('normal', 'Normal'), ('high', 'High')], db_index=True, default='normal', max_length=20)),
+                ('variables', models.JSONField(blank=True, default=dict, help_text='Expected template variables and descriptions')),
+                ('is_active', models.BooleanField(db_index=True, default=True)),
+                ('group', models.ForeignKey(blank=True, help_text='Organization for this template. Null = system template', null=True, on_delete=django.db.models.deletion.CASCADE, related_name='notification_templates', to='account.group')),
+            ],
+            options={
+                'ordering': ['group__name', 'name'],
+                'unique_together': {('group', 'name')},
+            },
+            bases=(models.Model, mojo.models.rest.MojoModel),
+        ),
+        migrations.CreateModel(
+            name='NotificationDelivery',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('created', models.DateTimeField(auto_now_add=True, db_index=True)),
+                ('modified', models.DateTimeField(auto_now=True, db_index=True)),
+                ('title', models.CharField(max_length=200)),
+                ('body', models.TextField()),
+                ('category', models.CharField(db_index=True, max_length=50)),
+                ('action_url', models.URLField(blank=True, null=True)),
+                ('status', models.CharField(choices=[('pending', 'Pending'), ('sent', 'Sent'), ('delivered', 'Delivered'), ('failed', 'Failed')], db_index=True, default='pending', max_length=20)),
+                ('sent_at', models.DateTimeField(blank=True, db_index=True, null=True)),
+                ('delivered_at', models.DateTimeField(blank=True, null=True)),
+                ('error_message', models.TextField(blank=True, null=True)),
+                ('platform_data', models.JSONField(blank=True, default=dict, help_text='Platform-specific response data')),
+                ('device', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='notification_deliveries', to='account.registereddevice')),
+                ('template', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='deliveries', to='account.notificationtemplate')),
+                ('user', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='notification_deliveries', to=settings.AUTH_USER_MODEL)),
+            ],
+            options={
+                'ordering': ['-created'],
+            },
+            bases=(models.Model, mojo.models.rest.MojoModel),
+        ),
+    ]

mojo/apps/account/migrations/0012_remove_pushconfig_apns_key_file_and_more.py

@@ -0,0 +1,21 @@
+# Generated by Django 4.2.21 on 2025-08-30 03:28
+
+from django.db import migrations
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('account', '0011_user_org_registereddevice_pushconfig_and_more'),
+    ]
+
+    operations = [
+        migrations.RemoveField(
+            model_name='pushconfig',
+            name='apns_key_file',
+        ),
+        migrations.RemoveField(
+            model_name='pushconfig',
+            name='fcm_server_key',
+        ),
+    ]

mojo/apps/account/migrations/0013_pushconfig_test_mode_alter_pushconfig_apns_enabled_and_more.py

@@ -0,0 +1,28 @@
+# Generated by Django 4.2.21 on 2025-08-30 04:34
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('account', '0012_remove_pushconfig_apns_key_file_and_more'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='pushconfig',
+            name='test_mode',
+            field=models.BooleanField(db_index=True, default=False, help_text='Enable test mode - fake notifications for development'),
+        ),
+        migrations.AlterField(
+            model_name='pushconfig',
+            name='apns_enabled',
+            field=models.BooleanField(default=False, help_text='APNS for iOS-specific needs. FCM is preferred.'),
+        ),
+        migrations.AlterField(
+            model_name='pushconfig',
+            name='fcm_enabled',
+            field=models.BooleanField(default=True, help_text='FCM handles both iOS and Android notifications'),
+        ),
+    ]

mojo/apps/account/migrations/0014_notificationdelivery_data_payload_and_more.py

@@ -0,0 +1,48 @@
+# Generated by Django 4.2.23 on 2025-09-02 22:50
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('account', '0013_pushconfig_test_mode_alter_pushconfig_apns_enabled_and_more'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='notificationdelivery',
+            name='data_payload',
+            field=models.JSONField(blank=True, default=dict, help_text='Custom data payload sent with notification'),
+        ),
+        migrations.AddField(
+            model_name='notificationtemplate',
+            name='data_template',
+            field=models.JSONField(blank=True, default=dict, help_text='Template data payload with variable support'),
+        ),
+        migrations.AlterField(
+            model_name='notificationdelivery',
+            name='body',
+            field=models.TextField(blank=True, null=True),
+        ),
+        migrations.AlterField(
+            model_name='notificationdelivery',
+            name='title',
+            field=models.CharField(blank=True, max_length=200, null=True),
+        ),
+        migrations.AlterField(
+            model_name='notificationtemplate',
+            name='body_template',
+            field=models.TextField(blank=True, null=True),
+        ),
+        migrations.AlterField(
+            model_name='notificationtemplate',
+            name='title_template',
+            field=models.CharField(blank=True, max_length=200, null=True),
+        ),
+        migrations.AlterField(
+            model_name='notificationtemplate',
+            name='variables',
+            field=models.JSONField(blank=True, default=dict, help_text='Expected template variables and descriptions for title, body, action_url, and data_template'),
+        ),
+    ]

mojo/apps/account/models/__init__.py

@@ -1,3 +1,5 @@
 from .group import Group
 from .user import User
 from .member import GroupMember
+from .device import GeoLocatedIP, UserDevice, UserDeviceLocation
+from .push import RegisteredDevice, PushConfig, NotificationTemplate, NotificationDelivery

mojo/apps/account/models/device.py

@@ -0,0 +1,281 @@
+from turtledemo.chaos import g
+import hashlib
+from django.db import models
+from mojo.helpers.settings import settings
+from mojo.models import MojoModel
+from mojo.helpers import dates, request as rhelper
+from mojo.apps import jobs
+from mojo.helpers.location.geolocation import refresh_geolocation_for_ip
+from fnmatch import filter
+
+GEOLOCATION_ALLOW_SUBNET_LOOKUP = settings.get('GEOLOCATION_ALLOW_SUBNET_LOOKUP', False)
+GEOLOCATION_DEVICE_LOCATION_AGE = settings.get('GEOLOCATION_DEVICE_LOCATION_AGE', 300)
+GEOLOCATION_CACHE_DURATION_DAYS = settings.get('GEOLOCATION_CACHE_DURATION_DAYS', 30)
+
+
+def trigger_refresh_task(ip_address):
+    """
+    Publishes a task to refresh the geolocation data for a given IP address.
+    """
+    jobs.publish_local(refresh_geolocation_for_ip, ip_address)
+
+
+class GeoLocatedIP(models.Model, MojoModel):
+    """
+    Acts as a cache to store geolocation results, reducing redundant and costly API calls.
+    Features a standardized, indexed schema for fast querying.
+    """
+    created = models.DateTimeField(auto_now_add=True, editable=False)
+    modified = models.DateTimeField(auto_now=True, db_index=True)
+
+    ip_address = models.GenericIPAddressField(db_index=True, unique=True)
+    subnet = models.CharField(max_length=16, db_index=True, null=True, default=None)
+
+    # Normalized and indexed fields for querying
+    country_code = models.CharField(max_length=3, db_index=True, null=True, blank=True)
+    country_name = models.CharField(max_length=100, null=True, blank=True)
+    region = models.CharField(max_length=100, db_index=True, null=True, blank=True)
+    city = models.CharField(max_length=100, null=True, blank=True)
+    postal_code = models.CharField(max_length=20, null=True, blank=True)
+    latitude = models.FloatField(null=True, blank=True)
+    longitude = models.FloatField(null=True, blank=True)
+    timezone = models.CharField(max_length=50, null=True, blank=True)
+
+    # Auditing and source tracking
+    provider = models.CharField(max_length=50, null=True, blank=True)
+    data = models.JSONField(default=dict, blank=True)
+    expires_at = models.DateTimeField(default=None, null=True, blank=True)
+
+    class RestMeta:
+        VIEW_PERMS = ['manage_users']
+        GRAPHS = {
+            'default': {
+
+            }
+        }
+
+    class Meta:
+        verbose_name = "Geolocated IP"
+        verbose_name_plural = "Geolocated IPs"
+
+    def __str__(self):
+        return f"{self.ip_address} ({self.city}, {self.country_code})"
+
+    @property
+    def is_expired(self):
+        if self.provider == 'internal':
+            return False # Internal records never expire
+        if self.expires_at:
+            return dates.utcnow() > self.expires_at
+        return True # If no expiry is set, it needs a refresh
+
+    def refresh(self):
+        """
+        Refreshes the geolocation data for this IP by calling the geolocation
+        helper and updating the model instance with the returned data.
+        """
+        from mojo.helpers.location import geolocation
+        from datetime import timedelta
+
+        geo_data = geolocation.geolocate_ip(self.ip_address)
+
+        if not geo_data:
+            return False
+
+        # Update self with new data
+        for key, value in geo_data.items():
+            setattr(self, key, value)
+
+        # Set the expiration date
+        if self.provider == 'internal':
+            self.expires_at = None
+        else:
+            cache_duration_days = GEOLOCATION_CACHE_DURATION_DAYS
+            self.expires_at = dates.utcnow() + timedelta(days=cache_duration_days)
+
+        self.save()
+        return True
+
+    @classmethod
+    def geolocate(cls, ip_address, auto_refresh=False, subdomain_only=False):
+        # Extract subnet from IP address using simple string parsing
+        subnet = ip_address[:ip_address.rfind('.')]
+        geo_ip = GeoLocatedIP.objects.filter(ip_address=ip_address).first()
+        if not geo_ip and (GEOLOCATION_ALLOW_SUBNET_LOOKUP or subdomain_only):
+            geo_ip = GeoLocatedIP.objects.filter(subnet=subnet).last()
+            if geo_ip:
+                geo_ip.id = None
+                geo_ip.pk = None
+                geo_ip.ip_address = ip_address
+                if "subnet" not in geo_ip.provider:
+                    geo_ip.provider = f"subnet:{geo_ip.provider}"
+        if not geo_ip:
+            geo_ip = GeoLocatedIP.objects.create(ip_address=ip_address, subnet=subnet)
+        if auto_refresh and geo_ip.is_expired:
+            geo_ip.refresh()
+        return geo_ip
+
+
+
+class UserDevice(models.Model, MojoModel):
+    """
+    Represents a unique device used by a user, tracked via a device ID (duid) or
+    a hash of the user agent string as a fallback.
+    """
+    user = models.ForeignKey("account.User", on_delete=models.CASCADE, related_name='devices')
+    duid = models.CharField(max_length=255, db_index=True)
+
+    device_info = models.JSONField(default=dict, blank=True)
+    user_agent_hash = models.CharField(max_length=64, db_index=True, null=True, blank=True)
+
+    last_ip = models.GenericIPAddressField(null=True, blank=True)
+    first_seen = models.DateTimeField(auto_now_add=True)
+    last_seen = models.DateTimeField(auto_now=True)
+
+    class RestMeta:
+        VIEW_PERMS = ['manage_users', 'owner']
+        GRAPHS = {
+            'default': {
+                'graphs': {
+                    'user': 'basic'
+                }
+            },
+            'basic': {
+                "fields": ["duid", "last_ip", "last_seen", "device_info"],
+            },
+            'locations': {
+                'fields': ['duid', 'last_ip', 'last_seen'],
+                'graphs': {
+                    'locations': 'default'
+                }
+            }
+        }
+
+    class Meta:
+        unique_together = ('user', 'duid')
+        ordering = ['-last_seen']
+
+    def __str__(self):
+        return f"Device {self.duid} for {self.user.username}"
+
+    @classmethod
+    def track(cls, request):
+        """
+        Tracks a user's device based on the incoming request. This is the primary
+        entry point for the device tracking system.
+        """
+        if not request.user or not request.user.is_authenticated:
+            return None
+
+        user = request.user
+        ip_address = request.ip
+        user_agent_str = request.user_agent
+        duid = request.duid
+
+        ua_hash = hashlib.sha256(user_agent_str.encode('utf-8')).hexdigest()
+        if not duid:
+            duid = f"ua-hash-{ua_hash}"
+
+        # Get or create the device
+        device, created = cls.objects.get_or_create(
+            user=user,
+            duid=duid,
+            defaults={
+                'last_ip': ip_address,
+                'user_agent_hash': ua_hash,
+                'device_info': rhelper.parse_user_agent(user_agent_str)
+            }
+        )
+
+        # If device already existed, update its last_seen and ip
+        if not created:
+            now = dates.utcnow()
+            age_seconds = (now - device.last_seen).total_seconds()
+            is_stale = age_seconds > GEOLOCATION_DEVICE_LOCATION_AGE
+            if is_stale or device.last_ip != ip_address:
+                device.last_ip = ip_address
+                device.last_seen = dates.utcnow()
+                # Optionally update device_info if user agent has changed
+                if device.user_agent_hash != ua_hash:
+                    device.user_agent_hash = ua_hash
+                    device.device_info = rhelper.parse_user_agent(user_agent_str)
+                device.save()
+
+        # Track the location (IP) used by this device
+        UserDeviceLocation.track(device, ip_address)
+
+        return device
+
+
+class UserDeviceLocation(models.Model, MojoModel):
+    """
+    A log linking a UserDevice to every IP address it uses. Geolocation is
+    handled asynchronously.
+    """
+    user = models.ForeignKey("account.User", on_delete=models.CASCADE, related_name='device_locations_direct')
+    user_device = models.ForeignKey('UserDevice', on_delete=models.CASCADE, related_name='locations')
+    ip_address = models.GenericIPAddressField(db_index=True)
+    geolocation = models.ForeignKey('GeoLocatedIP', on_delete=models.SET_NULL, null=True, blank=True, related_name='device_locations')
+
+    first_seen = models.DateTimeField(auto_now_add=True)
+    last_seen = models.DateTimeField(auto_now=True)
+
+    class RestMeta:
+        VIEW_PERMS = ['manage_users']
+        GRAPHS = {
+            'default': {
+                'graphs': {
+                    'user': 'basic',
+                    'geolocation': 'default',
+                    'user_device': 'basic'
+                }
+            },
+            'list': {
+                'graphs': {
+                    'user': 'basic',
+                    'geolocation': 'default',
+                    'user_device': 'basic'
+                }
+            }
+        }
+
+    class Meta:
+        unique_together = ('user', 'user_device', 'ip_address')
+        ordering = ['-last_seen']
+
+    def __str__(self):
+        return f"{self.user_device} @ {self.ip_address}"
+
+    @classmethod
+    def track(cls, device, ip_address):
+        """
+        Creates or updates a device location entry, links it to a GeoLocatedIP record,
+        and triggers a background refresh if the geo data is stale.
+        """
+        # First, get or create the geolocation record for this IP.
+        # The actual fetching of data is handled by the background task.
+        geo_ip = GeoLocatedIP.geolocate(ip_address)
+
+        # Now, create the actual location event log, linking the device and the geo_ip record.
+        location, loc_created = cls.objects.get_or_create(
+            user=device.user,
+            user_device=device,
+            ip_address=ip_address,
+            defaults={'geolocation': geo_ip}
+        )
+
+        if not loc_created:
+            now = dates.utcnow()
+            age_seconds = (now - location.last_seen).total_seconds()
+            if age_seconds > GEOLOCATION_DEVICE_LOCATION_AGE:
+                location.last_seen = now
+                # If the location already existed but wasn't linked to a geo_ip object yet
+                if not location.geolocation:
+                    location.geolocation = geo_ip
+                location.save(update_fields=['last_seen', 'geolocation'])
+
+        # Finally, if the geo data is stale or new, trigger a refresh.
+        if geo_ip.is_expired:
+            trigger_refresh_task(ip_address)
+
+        return location