From e953be5e99da6734919a778a37707907a20f59f5 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Fri, 29 May 2026 10:17:41 +0530
Subject: [PATCH] refactor(gateway): abstract platform command handling

---
 .../app/gateway/base/commands.py              | 41 +++++++++++++++++++
 .../app/gateway/telegram/commands.py          | 38 ++++++++++++++---
 2 files changed, 73 insertions(+), 6 deletions(-)
 create mode 100644 surfsense_backend/app/gateway/base/commands.py

diff --git a/surfsense_backend/app/gateway/base/commands.py b/surfsense_backend/app/gateway/base/commands.py
new file mode 100644
index 000000000..ea5d09e20
--- /dev/null
+++ b/surfsense_backend/app/gateway/base/commands.py
@@ -0,0 +1,41 @@
+"""Provider-neutral command hooks for external chat gateways."""
+
+from __future__ import annotations
+
+from app.gateway.base.adapter import BasePlatformAdapter, ParsedInboundEvent
+
+
+def command_name(text: str | None) -> str | None:
+    if not text or not text.startswith("/"):
+        return None
+    return text.split(maxsplit=1)[0].split("@", 1)[0].lower()
+
+
+class BaseGatewayCommands:
+    """Default command behavior for platforms without slash-command onboarding."""
+
+    async def handle_start_command(
+        self,
+        *,
+        session,
+        adapter: BasePlatformAdapter,
+        event: ParsedInboundEvent,
+    ) -> bool:
+        return False
+
+    async def handle_help_command(
+        self,
+        *,
+        adapter: BasePlatformAdapter,
+        event: ParsedInboundEvent,
+    ) -> bool:
+        return False
+
+    async def send_unbound_onboarding(
+        self,
+        *,
+        adapter: BasePlatformAdapter,
+        event: ParsedInboundEvent,
+        dashboard_url: str,
+    ) -> None:
+        return None
diff --git a/surfsense_backend/app/gateway/telegram/commands.py b/surfsense_backend/app/gateway/telegram/commands.py
index bc4a64377..903330fd8 100644
--- a/surfsense_backend/app/gateway/telegram/commands.py
+++ b/surfsense_backend/app/gateway/telegram/commands.py
@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 from app.gateway.base.adapter import ParsedInboundEvent
+from app.gateway.base.commands import BaseGatewayCommands
 from app.gateway.pairing import redeem_pairing_code
 from app.gateway.ratelimit import acquire_token
 from app.gateway.telegram.adapter import TelegramAdapter
@@ -15,12 +16,6 @@ HELP_TEXT = (
 )
 
 
-def command_name(text: str | None) -> str | None:
-    if not text or not text.startswith("/"):
-        return None
-    return text.split(maxsplit=1)[0].split("@", 1)[0].lower()
-
-
 async def handle_start_command(
     *,
     session,
@@ -89,3 +84,34 @@ async def send_unbound_onboarding(
         ),
     )
 
+
+class TelegramGatewayCommands(BaseGatewayCommands):
+    async def handle_start_command(
+        self,
+        *,
+        session,
+        adapter: TelegramAdapter,
+        event: ParsedInboundEvent,
+    ) -> bool:
+        return await handle_start_command(session=session, adapter=adapter, event=event)
+
+    async def handle_help_command(
+        self,
+        *,
+        adapter: TelegramAdapter,
+        event: ParsedInboundEvent,
+    ) -> bool:
+        return await handle_help_command(adapter=adapter, event=event)
+
+    async def send_unbound_onboarding(
+        self,
+        *,
+        adapter: TelegramAdapter,
+        event: ParsedInboundEvent,
+        dashboard_url: str,
+    ) -> None:
+        await send_unbound_onboarding(
+            adapter=adapter,
+            event=event,
+            dashboard_url=dashboard_url,
+        )
\ No newline at end of file