Merge pull request #903 from gobii-ai/sms_tweak

SMS Tweaks

Author: willbonde

README.md

@@ -367,3 +367,4 @@ uv run celery -A config worker -l info --pool=threads --concurrency=4
 - Source code is licensed under [MIT](LICENSE).
 - Gobii name and logo are trademarks of Gobii, Inc. See [NOTICE](NOTICE).
 - Proprietary mode and non-MIT components require a commercial agreement with Gobii, Inc.
+

api/admin.py

@@ -44,6 +44,8 @@
 )
 from api.agent.core.schedule_parser import ScheduleParser
 from .admin_forms import (
+    FindReleaseCandidatesForm,
+    ReleaseSmsNumbersForm,
     TestSmsForm,
     GrantPlanCreditsForm,
     GrantCreditsByUserIdsForm,
@@ -97,7 +99,12 @@
 from .agent.files.filespace_service import enqueue_import_after_commit
 from .tasks import sync_ip_block, backfill_missing_proxy_records, proxy_health_check_single, garbage_collect_timed_out_tasks
 from .tasks.sms_tasks import sync_twilio_numbers, send_test_sms
-from .services.sms_number_inventory import retire_sms_number
+from .services.sms_number_inventory import (
+    SmsNumberReleaseCandidate,
+    find_sms_number_release_candidates,
+    release_sms_number,
+    retire_sms_number,
+)
 from .services.global_skill_json import (
     import_global_skill_from_payload,
     parse_global_skill_json_bytes,
@@ -116,6 +123,9 @@
 
 import zstandard as zstd
 
+SMS_RELEASE_CANDIDATES_SESSION_KEY = "admin_sms_release_candidates_phone_numbers"
+SMS_RELEASE_CANDIDATES_PREFILL_SOURCE = "release_candidates"
+
 # Replace dj-stripe's default registration
 # 2.10.1 has removed some fields we still want to see, but their own admin still references them
 admin.site.unregister(Customer)
@@ -534,12 +544,7 @@ def get_urls(self):
         return custom + urls
 
     def grant_by_plan_view(self, request):
-        from django.template.response import TemplateResponse
-        from django.contrib import messages
-        from django.db import transaction
-        from django.utils import timezone
         from django.apps import apps
-        from constants.plans import PlanNamesChoices
 
         if not request.user.has_perm("api.add_taskcredit"):
             messages.error(request, "You do not have permission to grant task credits.")
@@ -662,10 +667,6 @@ def grant_by_plan_view(self, request):
         return TemplateResponse(request, "admin/grant_plan_credits.html", context)
 
     def grant_by_user_ids_view(self, request):
-        from django.template.response import TemplateResponse
-        from django.contrib import messages
-        from django.db import transaction
-        from django.utils import timezone
         from django.apps import apps
 
         if not request.user.has_perm("api.add_taskcredit"):
@@ -692,12 +693,10 @@ def grant_by_user_ids_view(self, request):
             export_csv = form.cleaned_data['export_csv']
 
             # Parse IDs by commas or newlines
-            import re
             ids = [s for s in re.split(r"[\s,]+", raw.strip()) if s]
 
             TaskCredit = apps.get_model("api", "TaskCredit")
             User = get_user_model()
-            from constants.plans import PlanNamesChoices
 
             # ids are integers; invalid tokens are ignored by the filter
             users = list(User.objects.filter(id__in=ids, is_active=True))
@@ -4314,7 +4313,6 @@ def test_smtp_view(self, request, object_id):
                         pass
 
             # Success
-            from django.utils import timezone
             acct.connection_last_ok_at = timezone.now()
             acct.connection_error = ""
             acct.save(update_fields=['connection_last_ok_at', 'connection_error'])
@@ -4374,7 +4372,6 @@ def test_imap_view(self, request, object_id):
         # Attempt IMAP connection
         try:
             import imaplib
-            from django.utils import timezone
             if acct.imap_security == AgentEmailAccount.ImapSecurity.SSL:
                 client = imaplib.IMAP4_SSL(acct.imap_host, int(acct.imap_port or 993), timeout=30)
             else:
@@ -5134,6 +5131,12 @@ def in_use(self, obj):
         """Return True if any agent SMS endpoint uses this number."""
         return obj.is_in_use
 
+    @staticmethod
+    def _preview_items(items, limit=5, separator=", "):
+        preview = separator.join(items[:limit])
+        suffix = "..." if len(items) > limit else ""
+        return f"{preview}{suffix}"
+
     fieldsets = (
         ('Basic Information', {
             'fields': ('id', 'phone_number', 'is_active', 'released_at')
@@ -5150,25 +5153,6 @@ def in_use(self, obj):
         }),
     )
 
-    def changelist_view(self, request, extra_context=None):
-        """Inject counts of numbers in use for the change list template."""
-        if extra_context is None:
-            extra_context = {}
-
-        in_use_numbers_qs = PersistentAgentCommsEndpoint.objects.filter(
-            channel=CommsChannel.SMS,
-        ).values("address")
-
-        extra_context["in_use_count"] = SmsNumber.objects.filter(
-            phone_number__in=in_use_numbers_qs,
-        ).count()
-
-        extra_context["total_count"] = SmsNumber.objects.count()
-
-        return super().changelist_view(request, extra_context=extra_context)
-
-
-
     def get_urls(self):
         urls = super().get_urls()
         extra = [
@@ -5177,6 +5161,16 @@ def get_urls(self):
                 self.admin_site.admin_view(self.test_sms_view),
                 name="smsnumber_test_sms",
             ),
+            path(
+                "release/",
+                self.admin_site.admin_view(self.release_view),
+                name="smsnumber_release",
+            ),
+            path(
+                "release-candidates/",
+                self.admin_site.admin_view(self.release_candidates_view),
+                name="smsnumber_release_candidates",
+            ),
             path(
                 "sync/",  # /admin/api/smsnumber/sync/
                 self.admin_site.admin_view(self.sync_view),
@@ -5224,6 +5218,194 @@ def test_sms_view(self, request, object_id):
 
         return TemplateResponse(request, "admin/test_sms_form.html", context)
 
+    def changelist_view(self, request, extra_context=None):
+        """Inject counts of numbers in use for the change list template."""
+        if extra_context is None:
+            extra_context = {}
+
+        inventory_numbers_qs = SmsNumber.objects.filter(released_at__isnull=True)
+        in_use_numbers_qs = PersistentAgentCommsEndpoint.objects.filter(
+            channel=CommsChannel.SMS,
+        ).values("address")
+
+        extra_context["in_use_count"] = inventory_numbers_qs.filter(
+            phone_number__in=in_use_numbers_qs,
+        ).count()
+        extra_context["inventory_count"] = inventory_numbers_qs.count()
+        extra_context["released_count"] = SmsNumber.objects.filter(released_at__isnull=False).count()
+
+        return super().changelist_view(request, extra_context=extra_context)
+
+    def release_view(self, request):
+        changelist_url = reverse("admin:api_smsnumber_changelist")
+        if not request.user.has_perm("api.change_smsnumber"):
+            messages.error(request, "Permission denied.")
+            return HttpResponseRedirect(changelist_url)
+
+        initial = {}
+        if request.method != "POST":
+            prefilled_numbers = (request.GET.get("phone_numbers") or "").strip()
+            if not prefilled_numbers and request.GET.get("prefill") == SMS_RELEASE_CANDIDATES_PREFILL_SOURCE:
+                prefilled_numbers = (
+                    request.session.get(SMS_RELEASE_CANDIDATES_SESSION_KEY, "")
+                ).strip()
+            if prefilled_numbers:
+                initial["phone_numbers"] = prefilled_numbers
+
+        form = ReleaseSmsNumbersForm(request.POST or None, initial=initial)
+        if request.method == "POST" and form.is_valid():
+            requested_numbers = form.cleaned_data["phone_numbers"]
+            sms_numbers_by_phone = {
+                sms_number.phone_number: sms_number
+                for sms_number in SmsNumber.objects.filter(phone_number__in=requested_numbers)
+            }
+
+            released_results = []
+            partial_results = []
+            missing_numbers = []
+            validation_errors = []
+            detached_endpoint_total = 0
+
+            for phone_number in requested_numbers:
+                sms_number = sms_numbers_by_phone.get(phone_number)
+                if sms_number is None:
+                    missing_numbers.append(phone_number)
+                    continue
+
+                try:
+                    result = release_sms_number(sms_number)
+                except ValidationError as exc:
+                    validation_errors.append(f"{phone_number}: {'; '.join(exc.messages)}")
+                    continue
+
+                detached_endpoint_total += result.detached_endpoint_count
+                if result.succeeded:
+                    released_results.append(result)
+                else:
+                    partial_results.append(result)
+
+            if released_results:
+                released_numbers = [result.phone_number for result in released_results]
+                messages.success(
+                    request,
+                    f"Released {len(released_results)} SMS number(s) in Twilio: "
+                    f"{self._preview_items(released_numbers)}",
+                )
+
+            if detached_endpoint_total:
+                messages.info(
+                    request,
+                    f"Detached {detached_endpoint_total} SMS endpoint(s) from agents before release.",
+                )
+
+            if partial_results:
+                partial_preview = self._preview_items(
+                    [f"{result.phone_number} ({result.error})" for result in partial_results],
+                    limit=3,
+                    separator="; ",
+                )
+                messages.error(
+                    request,
+                    "Retired locally but failed to release in Twilio for "
+                    f"{len(partial_results)} SMS number(s): {partial_preview}",
+                )
+
+            if missing_numbers:
+                messages.error(
+                    request,
+                    f"Skipped {len(missing_numbers)} number(s) not found in SMS inventory: "
+                    f"{self._preview_items(missing_numbers)}",
+                )
+
+            if validation_errors:
+                messages.error(
+                    request,
+                    f"Could not release {len(validation_errors)} number(s): "
+                    f"{self._preview_items(validation_errors, limit=3, separator=' | ')}",
+                )
+
+            if not any([released_results, partial_results, missing_numbers, validation_errors]):
+                messages.warning(request, "No SMS numbers were released.")
+
+            return HttpResponseRedirect(changelist_url)
+
+        context = dict(
+            self.admin_site.each_context(request),
+            opts=self.model._meta,
+            form=form,
+            title="Release SMS Numbers",
+            changelist_url=changelist_url,
+        )
+
+        return TemplateResponse(request, "admin/smsnumber_release_form.html", context)
+
+    def release_candidates_view(self, request):
+        changelist_url = reverse("admin:api_smsnumber_changelist")
+        if not request.user.has_perm("api.view_smsnumber"):
+            messages.error(request, "Permission denied.")
+            return HttpResponseRedirect(changelist_url)
+
+        form = FindReleaseCandidatesForm(request.GET or None)
+        has_results = bool(request.GET)
+        candidates = []
+        if has_results and form.is_valid():
+            candidates = find_sms_number_release_candidates(
+                unused_days=form.cleaned_data["unused_days"],
+                include_detached_unused=form.cleaned_data["include_detached_unused"],
+                include_free_dormant_unused=form.cleaned_data["include_free_dormant_unused"],
+            )
+
+        grouped_candidates = {
+            SmsNumberReleaseCandidate.DETACHED_UNUSED: [],
+            SmsNumberReleaseCandidate.FREE_DORMANT_UNUSED: [],
+        }
+        for candidate in candidates:
+            grouped_candidates.setdefault(candidate.tier, []).append(
+                {
+                    "phone_number": candidate.phone_number,
+                    "friendly_name": candidate.friendly_name,
+                    "last_activity_at": candidate.last_activity_at,
+                    "owner_agent_name": candidate.owner_agent_name,
+                    "owner_email": candidate.owner_email,
+                    "owner_plan": candidate.owner_plan,
+                    "sms_number_change_url": reverse("admin:api_smsnumber_change", args=[candidate.sms_number_id]),
+                    "endpoint_change_url": (
+                        reverse("admin:api_persistentagentcommsendpoint_change", args=[candidate.endpoint_id])
+                        if candidate.endpoint_id
+                        else ""
+                    ),
+                    "owner_agent_change_url": (
+                        reverse("admin:api_persistentagent_change", args=[candidate.owner_agent_id])
+                        if candidate.owner_agent_id
+                        else ""
+                    ),
+                }
+            )
+
+        suggested_numbers = "\n".join(candidate.phone_number for candidate in candidates)
+        release_review_url = ""
+        if suggested_numbers:
+            request.session[SMS_RELEASE_CANDIDATES_SESSION_KEY] = suggested_numbers
+            release_review_url = (
+                f"{reverse('admin:smsnumber_release')}?prefill={SMS_RELEASE_CANDIDATES_PREFILL_SOURCE}"
+            )
+        else:
+            request.session.pop(SMS_RELEASE_CANDIDATES_SESSION_KEY, None)
+
+        context = dict(
+            self.admin_site.each_context(request),
+            opts=self.model._meta,
+            form=form,
+            title="Find SMS Release Candidates",
+            changelist_url=changelist_url,
+            has_results=has_results,
+            grouped_candidates=grouped_candidates,
+            suggested_numbers=suggested_numbers,
+            release_review_url=release_review_url,
+        )
+
+        return TemplateResponse(request, "admin/smsnumber_release_candidates.html", context)
+
 
 @admin.register(LinkShortener)
 class LinkShortenerAdmin(admin.ModelAdmin):