fix(discord): handle interactions in gateway-only mode (vercel/chat#490)

Port of upstream b9b17cd. Discord sends interactions through either
the Gateway or an Interactions Endpoint URL, not both — deployments
without an endpoint URL receive interactions over the Gateway, and the
adapter previously dropped them ("Forwarded Gateway event (no
handler)").

The Python adapter is HTTP-interactions-only with a gateway-forwarder
receiver, so the port lands on that surface: a forwarded
GATEWAY_INTERACTION_CREATE event (raw wire-format INTERACTION_CREATE
dispatch payload) is now acknowledged via the interaction callback
REST endpoint — POST /interactions/{id}/{token}/callback with type 5
for slash commands / type 6 for components, the same wire calls
upstream's resident discord.js handler makes via deferReply() /
deferUpdate() — then routed through the existing slash-command and
action handler paths. Deferred slash responses resolve exactly like
HTTP ones (post_message PATCHes the @original webhook message).
Callback path segments are URL-quoted (hazard #12) and defer failures
are logged without dispatching the handler, matching upstream's
listener-level catch.

Also aligns slash-command boolean option flattening with TS
String(true) — "status true", not Python str(True) "status True" —
pinned by the ported upstream test.

https://claude.ai/code/session_013zwTcMek5rNqBTQvs2oF64
(cherry picked from commit 458428afc383b57704e6fe7c6d8abde23235afda)

Author: claude

src/chat_sdk/adapters/discord/adapter.py

@@ -505,10 +505,20 @@ def _parse_slash_command(
         command_parts: list[str] = [name if name.startswith("/") else f"/{name}"]
         value_parts: list[str] = []
 
+        def stringify(value: Any) -> str:
+            # Match TS `String(value)` for boolean options: JSON booleans
+            # arrive as Python bools, and `str(True)` would emit "True"
+            # where upstream emits "true" (e.g. a `verbose: true` option).
+            if value is True:
+                return "true"
+            if value is False:
+                return "false"
+            return str(value)
+
         def collect(items: list[DiscordCommandOption]) -> None:
             for option in items:
                 if option.get("value") is not None:
-                    value_parts.append(str(option["value"]))
+                    value_parts.append(stringify(option["value"]))
                     continue
                 sub_options = option.get("options", [])
                 if sub_options:
@@ -541,11 +551,110 @@ async def _handle_forwarded_gateway_event(
             await self._handle_forwarded_reaction(event.get("data", {}), True, options)
         elif event_type == "GATEWAY_MESSAGE_REACTION_REMOVE":
             await self._handle_forwarded_reaction(event.get("data", {}), False, options)
+        elif event_type == "GATEWAY_INTERACTION_CREATE":
+            await self._handle_forwarded_interaction(event.get("data", {}), options)
         else:
             self._logger.debug("Forwarded Gateway event (no handler)", {"type": event_type})
 
         return self._make_json_response(json.dumps({"ok": True}), 200)
 
+    async def _handle_forwarded_interaction(
+        self,
+        interaction: DiscordInteraction,
+        options: WebhookOptions | None = None,
+    ) -> None:
+        """Handle a forwarded INTERACTION_CREATE event (gateway-only mode).
+
+        Discord sends interactions through either the Gateway or an
+        Interactions Endpoint URL, not both (vercel/chat#490). Deployments
+        that leave the endpoint URL unset receive interactions over the
+        Gateway; the forwarder relays the raw INTERACTION_CREATE dispatch
+        payload here, which is already in wire format, so the existing HTTP
+        interaction handlers consume it unchanged.
+
+        Unlike HTTP interactions -- where the deferral rides the HTTP
+        response body -- a gateway interaction is acknowledged with an
+        explicit REST call to the interaction callback endpoint. That is
+        the same wire call upstream's gateway-only handler makes via
+        discord.js ``deferReply()`` (slash commands) and ``deferUpdate()``
+        (components). Slash commands then route through the existing slash
+        command handler path (the deferred response is later resolved by
+        ``post_message`` PATCHing the ``@original`` interaction webhook
+        message), and component interactions route through the existing
+        action handler path.
+        """
+        interaction_id = interaction.get("id")
+        interaction_token = interaction.get("token")
+        interaction_type = interaction.get("type", 0)
+
+        self._logger.info(
+            "Discord Gateway interaction received",
+            {"id": interaction_id, "type": interaction_type},
+        )
+
+        if interaction_type not in (
+            INTERACTION_TYPE_APPLICATION_COMMAND,
+            INTERACTION_TYPE_MESSAGE_COMPONENT,
+        ):
+            self._logger.debug(
+                "Forwarded Gateway interaction (no handler)",
+                {"type": interaction_type},
+            )
+            return
+
+        if not (interaction_id and interaction_token):
+            # A gateway INTERACTION_CREATE always carries id + token; a
+            # malformed forward must not produce a garbage callback URL.
+            self._logger.warn(
+                "Forwarded Gateway interaction missing id or token",
+                {"id": interaction_id, "type": interaction_type},
+            )
+            return
+
+        try:
+            if interaction_type == INTERACTION_TYPE_APPLICATION_COMMAND:
+                # deferReply: ACK now, respond via the interaction webhook later.
+                await self._defer_gateway_interaction(
+                    interaction_id,
+                    interaction_token,
+                    InteractionResponseType.DEFERRED_CHANNEL_MESSAGE_WITH_SOURCE,
+                )
+                self._handle_application_command_interaction(interaction, options)
+                return
+
+            # deferUpdate: ACK the component, update the message later.
+            await self._defer_gateway_interaction(
+                interaction_id,
+                interaction_token,
+                InteractionResponseType.DEFERRED_UPDATE_MESSAGE,
+            )
+            self._handle_component_interaction(interaction, options)
+        except Exception as error:
+            self._logger.error(
+                "Error handling Gateway interaction",
+                {"error": str(error), "interactionId": interaction_id},
+            )
+
+    async def _defer_gateway_interaction(
+        self,
+        interaction_id: str,
+        interaction_token: str,
+        response_type: int,
+    ) -> None:
+        """ACK a gateway-received interaction via the callback endpoint.
+
+        ``POST /interactions/{id}/{token}/callback`` is the REST equivalent
+        of returning the deferral as the HTTP response body on the
+        Interactions Endpoint path. Path segments are URL-quoted so a
+        crafted id/token in a forwarded payload cannot pivot the request
+        (hazard #12, same guard as :meth:`get_user`).
+        """
+        await self._discord_fetch(
+            f"/interactions/{quote(interaction_id, safe='')}/{quote(interaction_token, safe='')}/callback",
+            "POST",
+            {"type": response_type},
+        )
+
     async def _handle_forwarded_message(
         self,
         data: DiscordGatewayMessageData,

src/chat_sdk/adapters/discord/types.py

@@ -306,7 +306,13 @@ class DiscordGatewayReactionData(TypedDict, total=False):
 
 
 class DiscordForwardedEvent(TypedDict):
-    """A Gateway event forwarded to the webhook endpoint."""
+    """A Gateway event forwarded to the webhook endpoint.
+
+    Known types: ``GATEWAY_MESSAGE_CREATE``, ``GATEWAY_MESSAGE_REACTION_ADD``,
+    ``GATEWAY_MESSAGE_REACTION_REMOVE``, ``GATEWAY_INTERACTION_CREATE``.
+    For ``GATEWAY_INTERACTION_CREATE``, ``data`` is the raw wire-format
+    INTERACTION_CREATE dispatch payload (:class:`DiscordInteraction`).
+    """
 
     data: Any
     timestamp: int

tests/test_discord_adapter.py

@@ -406,7 +406,9 @@ async def test_dispatches_slash_command_to_chat(self):
         mock_chat.process_slash_command.assert_called_once()
         call_args = mock_chat.process_slash_command.call_args[0][0]
         assert call_args.command == "/test"
-        assert call_args.text == "status True"
+        # Boolean option values flatten as JSON-style "true"/"false",
+        # matching TS `String(true)` (wire parity, vercel/chat#490 test).
+        assert call_args.text == "status true"
 
     @pytest.mark.asyncio
     async def test_expands_subcommand_path(self):

tests/test_discord_extended.py

@@ -923,6 +923,218 @@ async def test_handles_reaction_remove(self):
         assert call_args.message_id == "msg123"
 
 
+# ============================================================================
+# Forwarded gateway interactions (gateway-only mode, vercel/chat#490)
+# ============================================================================
+
+
+class TestForwardedGatewayInteractions:
+    """Port of the "legacy gateway interactions" describe block.
+
+    Discord sends interactions through either the Gateway or an
+    Interactions Endpoint URL, not both. In gateway-only deployments the
+    forwarder relays the raw INTERACTION_CREATE payload; the adapter must
+    defer it via the interaction callback REST endpoint (the wire call
+    discord.js makes for deferReply/deferUpdate) and route through the
+    existing slash-command / action handler paths.
+    """
+
+    def _slash_interaction(self, **overrides):
+        interaction = {
+            "id": "interaction123",
+            "application_id": "test-app-id",
+            "token": "interaction-token",
+            "type": 2,  # APPLICATION_COMMAND
+            "version": 1,
+            "guild_id": "guild123",
+            "channel_id": "channel456",
+            "channel": {"id": "channel456", "type": 0},
+            "user": {
+                "id": "user789",
+                "username": "testuser",
+                "discriminator": "0001",
+                "global_name": "Test User",
+                "bot": False,
+            },
+            "data": {
+                "name": "test",
+                "type": 1,
+                "options": [
+                    {"name": "topic", "type": 3, "value": "status"},
+                    {"name": "verbose", "type": 5, "value": True},
+                ],
+            },
+        }
+        interaction.update(overrides)
+        return interaction
+
+    def _component_interaction(self, **overrides):
+        interaction = {
+            "id": "interaction123",
+            "application_id": "test-app-id",
+            "token": "interaction-token",
+            "type": 3,  # MESSAGE_COMPONENT
+            "version": 1,
+            "guild_id": "guild123",
+            "channel_id": "channel456",
+            "channel": {"id": "channel456", "type": 0},
+            "user": {
+                "id": "user789",
+                "username": "testuser",
+                "discriminator": "0001",
+                "global_name": "Test User",
+                "bot": False,
+            },
+            "data": {"custom_id": "approve_btn", "component_type": 2},
+            "message": {"id": "message123"},
+        }
+        interaction.update(overrides)
+        return interaction
+
+    def _forwarded(self, interaction) -> str:
+        return json.dumps(
+            {
+                "type": "GATEWAY_INTERACTION_CREATE",
+                "timestamp": 1234567890,
+                "data": interaction,
+            }
+        )
+
+    @pytest.mark.asyncio
+    async def test_handles_slash_command_interactions_from_the_gateway(self):
+        adapter = _make_adapter(logger=_make_logger())
+        mock_chat = MagicMock()
+        mock_chat.process_slash_command = MagicMock()
+        adapter._chat = mock_chat
+        adapter._discord_fetch = AsyncMock(return_value=None)
+
+        response = await adapter.handle_webhook(_gateway_request(self._forwarded(self._slash_interaction())))
+
+        assert response["status"] == 200
+        # deferReply: explicit callback REST call (type 5)
+        adapter._discord_fetch.assert_awaited_once_with(
+            "/interactions/interaction123/interaction-token/callback",
+            "POST",
+            {"type": 5},
+        )
+        mock_chat.process_slash_command.assert_called_once()
+        event = mock_chat.process_slash_command.call_args[0][0]
+        assert event.command == "/test"
+        assert event.text == "status true"
+        assert event.channel_id == "discord:guild123:channel456"
+        assert event.user.user_id == "user789"
+        assert event.user.user_name == "testuser"
+        assert event.user.full_name == "Test User"
+
+    @pytest.mark.asyncio
+    async def test_handles_component_interactions_from_the_gateway(self):
+        adapter = _make_adapter(logger=_make_logger())
+        mock_chat = MagicMock()
+        mock_chat.process_action = MagicMock()
+        adapter._chat = mock_chat
+        adapter._discord_fetch = AsyncMock(return_value=None)
+
+        response = await adapter.handle_webhook(_gateway_request(self._forwarded(self._component_interaction())))
+
+        assert response["status"] == 200
+        # deferUpdate: explicit callback REST call (type 6)
+        adapter._discord_fetch.assert_awaited_once_with(
+            "/interactions/interaction123/interaction-token/callback",
+            "POST",
+            {"type": 6},
+        )
+        mock_chat.process_action.assert_called_once()
+        event = mock_chat.process_action.call_args[0][0]
+        assert event.action_id == "approve_btn"
+        assert event.value == "approve_btn"
+        assert event.message_id == "message123"
+        assert event.thread_id == "discord:guild123:channel456"
+
+    @pytest.mark.asyncio
+    async def test_slash_command_defer_failure_skips_handler(self):
+        """If the deferral REST call fails the handler must not run --
+        matches upstream where a deferReply rejection is caught and logged
+        before the normalize+handle step."""
+        logger = _make_logger()
+        adapter = _make_adapter(logger=logger)
+        mock_chat = MagicMock()
+        mock_chat.process_slash_command = MagicMock()
+        adapter._chat = mock_chat
+        adapter._discord_fetch = AsyncMock(side_effect=NetworkError("discord", "boom"))
+
+        response = await adapter.handle_webhook(_gateway_request(self._forwarded(self._slash_interaction())))
+
+        # Forwarded-event responses stay 200; the failure is logged.
+        assert response["status"] == 200
+        mock_chat.process_slash_command.assert_not_called()
+        error_messages = [c.args[0] for c in logger.error.call_args_list]
+        assert "Error handling Gateway interaction" in error_messages
+
+    @pytest.mark.asyncio
+    async def test_unhandled_interaction_type_is_ignored_without_defer(self):
+        """PING/autocomplete-style interactions are not deferred or routed."""
+        adapter = _make_adapter(logger=_make_logger())
+        mock_chat = MagicMock()
+        mock_chat.process_slash_command = MagicMock()
+        mock_chat.process_action = MagicMock()
+        adapter._chat = mock_chat
+        adapter._discord_fetch = AsyncMock(return_value=None)
+
+        response = await adapter.handle_webhook(_gateway_request(self._forwarded(self._slash_interaction(type=4))))
+
+        assert response["status"] == 200
+        adapter._discord_fetch.assert_not_awaited()
+        mock_chat.process_slash_command.assert_not_called()
+        mock_chat.process_action.assert_not_called()
+
+    @pytest.mark.asyncio
+    async def test_interaction_missing_token_is_not_deferred_or_routed(self):
+        """A malformed forward without id/token must not produce a garbage
+        callback URL or dispatch a handler."""
+        adapter = _make_adapter(logger=_make_logger())
+        mock_chat = MagicMock()
+        mock_chat.process_action = MagicMock()
+        adapter._chat = mock_chat
+        adapter._discord_fetch = AsyncMock(return_value=None)
+
+        interaction = self._component_interaction()
+        del interaction["token"]
+        response = await adapter.handle_webhook(_gateway_request(self._forwarded(interaction)))
+
+        assert response["status"] == 200
+        adapter._discord_fetch.assert_not_awaited()
+        mock_chat.process_action.assert_not_called()
+
+    @pytest.mark.asyncio
+    async def test_gateway_slash_command_supports_deferred_response_flow(self):
+        """The gateway-deferred slash interaction resolves like an HTTP one:
+        the handler's first post_message PATCHes the @original webhook
+        message using the interaction token."""
+        adapter = _make_adapter(logger=_make_logger())
+        mock_chat = MagicMock()
+
+        def run_handler(event, options=None):
+            # Simulate Chat dispatching a handler that replies immediately.
+            import asyncio as _asyncio
+
+            task = _asyncio.get_running_loop().create_task(adapter.post_message(event.channel_id, "reply from handler"))
+            run_handler.task = task
+
+        mock_chat.process_slash_command = MagicMock(side_effect=run_handler)
+        adapter._chat = mock_chat
+        adapter._discord_fetch = AsyncMock(return_value={"id": "reply-msg-1"})
+
+        await adapter.handle_webhook(_gateway_request(self._forwarded(self._slash_interaction())))
+        await run_handler.task
+
+        paths = [c.args[0] for c in adapter._discord_fetch.await_args_list]
+        # First the deferral, then the @original PATCH (not a channel POST).
+        assert paths[0] == "/interactions/interaction123/interaction-token/callback"
+        assert paths[1] == "/webhooks/test-app-id/interaction-token/messages/@original"
+        patch_call = adapter._discord_fetch.await_args_list[1]
+        assert patch_call.args[1] == "PATCH"
+
+
 # ============================================================================
 # Forwarded message -- thread detection
 # ============================================================================