interaction-router fallback editReply is incompatible with Components V2

[UniquePixels]

Problem

The replyWithResult function in interaction-router.ts uses editReply({ content: '...' }) as a fallback when a spark defers but never replies. This fails when the deferred interaction targets a Components V2 message, because Discord's API rejects content (a legacy field) alongside MessageFlags.IsComponentsV2.

Error: DiscordAPIError[50035]: Invalid Form Body — content[MESSAGE_CANNOT_USE_LEGACY_FIELDS_WITH_COMPONENTS_V2]

Root Cause

When a component handler calls deferUpdate() on a button inside a V2 message:

1. interaction.deferred becomes true, interaction.replied stays false
2. If the handler completes without calling editReply(), the router's fallback fires
3. The fallback calls editReply({ content: 'Something went wrong...' })
4. This attempts to edit the original V2 message with a legacy content field → API error

Relevant code: interaction-router.ts lines 38–65

Suggested Approach

The router doesn't know whether the deferred interaction targets a V2 message or a legacy one. Options:

1. Wrap fallback editReply in attempt() — prevents the secondary error from propagating, though the user still gets no response
2. Send a new ephemeral followUp instead of editReply — always safe regardless of original message type
3. Detect V2 context — check interaction.message?.flags for IsComponentsV2 and adjust the reply strategy

Option 2 seems simplest and most robust.

Workaround

For now, bot-side handlers should avoid deferUpdate() on V2 component messages without a subsequent editReply(). Use deferReply({ flags: MessageFlags.Ephemeral }) + editReply() instead.

Applied in unbound via fix/close-button-v2-compat.

[coderabbitai]

Coding Plan

Summary

• Replace deferred editReply fallbacks with ephemeral followUp messages, which create new messages rather than editing the original (potentially V2) message
• This is universally safe regardless of whether the original interaction targeted a legacy or V2 message
• The change requires extending the RepliableInteraction interface and updating 6 existing tests to assert on followUp instead of editReply

Implementation Steps

Update Fallback Reply Strategy for V2 Compatibility

Replace editReply with followUp for deferred interaction fallbacks, ensuring compatibility with Components V2 messages while maintaining the same user-facing behavior (ephemeral error messages).

Task 1: Extend RepliableInteraction Interface

Add the followUp method to the interface so TypeScript recognizes it as available on repliable interactions.

• Update src/core/sparks/interaction-router.ts to add followUp to the RepliableInteraction interface (lines 16-21)
• The method signature should accept { content: string; flags?: number } matching the reply signature
• This enables the fallback logic to use followUp instead of editReply

Task 2: Replace Deferred editReply with followUp

Modify both deferred fallback branches in replyWithResult to use followUp instead of editReply, sending new ephemeral messages rather than attempting to edit the original (potentially V2) message.

• Update src/core/sparks/interaction-router.ts in the replyWithResult function (lines 32-66)
• In the failure branch (line 41): change editReply({ content: result.reason }) to followUp({ content: result.reason, flags: MessageFlags.Ephemeral })
• In the success-no-reply branch (lines 56-58): change editReply({ content: 'Something went wrong...' }) to followUp({ content: 'Something went wrong. Please try again.', flags: MessageFlags.Ephemeral })
• Both changes add MessageFlags.Ephemeral to ensure fallback messages remain private to the user

Task 3: Add followUp to Mock Infrastructure

Update the base mock interaction factory to include a followUp mock so tests can inject and assert on it.

• Update src/core/lib/test-helpers/mock-interaction.ts in createMockBaseInteraction
• Add followUp: mock(async () => {}) alongside the existing reply mock
• This ensures test overrides for followUp work consistently with other mocked methods

Task 4: Update Deferred Fallback Tests

Modify the 6 existing tests that assert on editReply for deferred interactions to instead assert on followUp with ephemeral flags.

• Update src/core/sparks/interaction-router.test.ts for the following tests:
  • 'editReply with guard failure reason when deferred but not replied' (command, lines 202-218)
  • 'editReply with fallback when command succeeds but deferred without reply' (lines 220-239)
  • 'editReply with guard failure reason when deferred but not replied' (component, lines 354-370)
  • 'editReply with fallback when component succeeds but deferred without reply' (lines 372-391)
  • 'editReply with guard failure reason when deferred but not replied' (modal, lines 443-459)
  • 'editReply with guard failure reason when deferred but not replied' (context menu, lines 540-556)
• For each test: replace editReply mock injection with followUp mock
• Update assertions to expect followUp called with { content: '...', flags: MessageFlags.Ephemeral }
• Update test names to reflect the new behavior (e.g., replace "editReply" with "followUp" in test descriptions)

🤖 Prompt for AI agents

This phase fixes V2 message compatibility by replacing deferred `editReply`
fallbacks with ephemeral `followUp` calls across the interaction router, its
mock infrastructure, and its test suite.

**Task 1: Extend `RepliableInteraction` Interface**
(`src/core/sparks/interaction-router.ts`, lines 16-21)
- Add a `followUp` method to the `RepliableInteraction` interface
- The method signature must accept `{ content: string; flags?: number }`,
matching the existing `reply` signature

**Task 2: Replace deferred `editReply` with `followUp`**
(`src/core/sparks/interaction-router.ts`, `replyWithResult` function, lines
32-66)
- In the failure branch (line 41): replace `editReply({ content: result.reason
})` with `followUp({ content: result.reason, flags: MessageFlags.Ephemeral })`
- In the success-no-reply branch (lines 56-58): replace `editReply({ content:
'Something went wrong...' })` with `followUp({ content: 'Something went wrong.
Please try again.', flags: MessageFlags.Ephemeral })`
- Both updated calls must include `MessageFlags.Ephemeral` to keep fallback
messages private to the user

**Task 3: Add `followUp` to mock infrastructure**
(`src/core/lib/test-helpers/mock-interaction.ts`)
- In `createMockBaseInteraction`, add `followUp: mock(async () => {})` alongside
the existing `reply` mock

**Task 4: Update deferred fallback tests**
(`src/core/sparks/interaction-router.test.ts`)
- Update the following 6 tests, replacing `editReply` mock injection and
assertions with `followUp`:
- `'editReply with guard failure reason when deferred but not replied'`
(command, lines 202-218)
- `'editReply with fallback when command succeeds but deferred without reply'`
(lines 220-239)
- `'editReply with guard failure reason when deferred but not replied'`
(component, lines 354-370)
- `'editReply with fallback when component succeeds but deferred without reply'`
(lines 372-391)
- `'editReply with guard failure reason when deferred but not replied'` (modal,
lines 443-459)
- `'editReply with guard failure reason when deferred but not replied'` (context
menu, lines 540-556)
- For each test: replace the `editReply` mock injection with a `followUp` mock,
update assertions to expect `followUp` called with `{ content: '...', flags:
MessageFlags.Ephemeral }`, and rename the test descriptions (replacing
"editReply" with "followUp")

Research

The interaction router (src/core/sparks/interaction-router.ts) is the central dispatcher for all Discord interactions. It uses a RepliableInteraction interface to abstract reply methods, and replyWithResult handles post-execution fallback replies. The test suite (interaction-router.test.ts) has comprehensive coverage including 6 tests specifically for deferred editReply scenarios. Mock interaction utilities live in src/core/lib/test-helpers/mock-interaction.ts.

---

🚀 Next Steps

🤖 All AI agent prompts combined

This phase fixes V2 message compatibility by replacing deferred `editReply`
fallbacks with ephemeral `followUp` calls across the interaction router, its
mock infrastructure, and its test suite.

**Task 1: Extend `RepliableInteraction` Interface**
(`src/core/sparks/interaction-router.ts`, lines 16-21)
- Add a `followUp` method to the `RepliableInteraction` interface
- The method signature must accept `{ content: string; flags?: number }`,
matching the existing `reply` signature

**Task 2: Replace deferred `editReply` with `followUp`**
(`src/core/sparks/interaction-router.ts`, `replyWithResult` function, lines
32-66)
- In the failure branch (line 41): replace `editReply({ content: result.reason
})` with `followUp({ content: result.reason, flags: MessageFlags.Ephemeral })`
- In the success-no-reply branch (lines 56-58): replace `editReply({ content:
'Something went wrong...' })` with `followUp({ content: 'Something went wrong.
Please try again.', flags: MessageFlags.Ephemeral })`
- Both updated calls must include `MessageFlags.Ephemeral` to keep fallback
messages private to the user

**Task 3: Add `followUp` to mock infrastructure**
(`src/core/lib/test-helpers/mock-interaction.ts`)
- In `createMockBaseInteraction`, add `followUp: mock(async () => {})` alongside
the existing `reply` mock

**Task 4: Update deferred fallback tests**
(`src/core/sparks/interaction-router.test.ts`)
- Update the following 6 tests, replacing `editReply` mock injection and
assertions with `followUp`:
- `'editReply with guard failure reason when deferred but not replied'`
(command, lines 202-218)
- `'editReply with fallback when command succeeds but deferred without reply'`
(lines 220-239)
- `'editReply with guard failure reason when deferred but not replied'`
(component, lines 354-370)
- `'editReply with fallback when component succeeds but deferred without reply'`
(lines 372-391)
- `'editReply with guard failure reason when deferred but not replied'` (modal,
lines 443-459)
- `'editReply with guard failure reason when deferred but not replied'` (context
menu, lines 540-556)
- For each test: replace the `editReply` mock injection with a `followUp` mock,
update assertions to expect `followUp` called with `{ content: '...', flags:
MessageFlags.Ephemeral }`, and rename the test descriptions (replacing
"editReply" with "followUp")

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!