fix(Message): throw when a message handler is missing a parameter (#3362)

Ticket: https://linear.app/stream/issue/REACT-1264

> **Stacked on #3360.** The base is `fix/pin-failure-notification-v15`,
so the diff shows only this change. Retarget to `master` once #3360 is
merged.

### 🎯 Goal

Follow-up from the review on #3360 and the comments on REACT-1264.

The message action handlers returned early without sending a request
when a required parameter was missing, and some only logged a
`console.warn`. The default `MessageActions` treat a resolved handler as
success, so the action showed "Message deleted", "{{ user }} has been
muted" and so on even though nothing happened. This only affects custom
messages and handlers, since `Message.tsx` always passes the message.

### 🛠 Implementation details

The guards now throw instead of returning:

| Handler | Before | Now |
| --- | --- | --- |
| `useMuteHandler` | `console.warn`, return | throws
`missingUseMuteHandlerParamsWarning` |
| `useFlagHandler` | `console.warn`, return | throws
`missingUseFlagHandlerParameterWarning` |
| `useDeleteHandler` | silent return | throws "useDeleteHandler was
called but it is missing one or more necessary parameters." |
| `usePinHandler` | silent return | throws "usePinHandler was called but
it is missing the message." |
| `useMarkUnreadHandler` | `console.warn`, return | throws "Mark unread
handler does not have access to message id" |

- The exported `missingUseMuteHandlerParamsWarning` /
`missingUseFlagHandlerParameterWarning` constants are kept and used as
the error message, so no exports change.
- The default actions show `error.message`, so a misconfigured custom
setup now shows this developer-facing message instead of a false
success. That is deliberate: it only happens when integrator code is
wrong, and it makes the bug visible.
- Known gap: that message is untranslated English, and the end user sees
it in the snackbar in every locale. Failed requests already show the
server's raw error text the same way. REACT-1285 tracks showing the
translated fallback (e.g. "Error deleting message") as the
notification's `message` while keeping the original in its `error` field
for logging. That fix covers these errors too, so this PR adds nothing
extra for it.
- The vite example's custom message UI catches `handleFlag` rejections,
like it already does for pin and delete.
- Tests: the mute and flag tests that expected a warning, and the
mark-unread tests that expected a silent no-op, now expect the error and
check that no request was sent. Delete and pin gain a missing-parameter
test.

Note for custom UIs: `handleDelete`, `handlePin`, `handleMute`,
`handleFlag` and `handleMarkUnread` now reject when called without the
parameters they need.

### 🎨 UI Changes

No visual changes. A handler called without its required parameters now
shows the error notification instead of the success one.


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
<!-- coderabbit-ai-generated:v1 -->

## Summary by CodeRabbit

* **Bug Fixes**
* Deleting, flagging, marking unread, muting, or pinning a message now
reports an error when required message details or client information are
missing, rather than silently doing nothing.
* The example flag-message button now handles failed requests and avoids
leaving rejected errors unhandled.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: oliverlaz

examples/vite/src/CustomMessageUi/variants.tsx

@@ -274,7 +274,16 @@ const CustomMessageUiActions = () => {
         <button onClick={handleOpenThread} title='Open thread'>
           ↩️
         </button>
-        <button onClick={handleFlag} title='Flag message'>
+        <button
+          onClick={async (event) => {
+            try {
+              await handleFlag(event);
+            } catch (error) {
+              console.error('Failed to flag the message', error);
+            }
+          }}
+          title='Flag message'
+        >
           {' '}
           🚩
         </button>

src/components/Message/hooks/__tests__/useDeleteHandler.test.tsx

@@ -59,6 +59,19 @@ describe('useDeleteHandler custom hook', () => {
     expect(typeof handleDelete).toBe('function');
   });
 
+  it('should throw without deleting when the message has no id', async () => {
+    const deleteSpy = vi.spyOn(channel.messageOperations, 'delete');
+    const handleDelete = await renderUseDeleteHandler(
+      generateMessage({ id: undefined }) as typeof testMessage,
+    );
+    await act(async () => {
+      await expect(handleDelete()).rejects.toThrow(
+        'useDeleteHandler was called but it is missing one or more necessary parameters.',
+      );
+    });
+    expect(deleteSpy).not.toHaveBeenCalled();
+  });
+
   it('should delete a message without options via the channel local-update path', async () => {
     const deleteSpy = vi
       .spyOn(channel.messageOperations, 'delete')

src/components/Message/hooks/__tests__/useFlagHandler.test.tsx

@@ -50,11 +50,13 @@ describe('useHandleFlag custom hook', () => {
     expect(typeof handleFlag).toBe('function');
   });
 
-  it('should throw a warning when there are missing parameters and the handler is called', async () => {
-    const consoleWarnSpy = vi.spyOn(console, 'warn').mockImplementationOnce(() => null);
+  it('should throw when there are missing parameters and the handler is called', async () => {
+    const flagSpy = vi.spyOn(client.moderation, 'flagMessage');
     const handleFlag = await renderUseHandleFlagHook(undefined);
-    await handleFlag(mouseEventMock);
-    expect(consoleWarnSpy).toHaveBeenCalledWith(missingUseFlagHandlerParameterWarning);
+    await expect(handleFlag(mouseEventMock)).rejects.toThrow(
+      missingUseFlagHandlerParameterWarning,
+    );
+    expect(flagSpy).not.toHaveBeenCalled();
   });
 
   it('should allow to flag a message when it is successful', async () => {

src/components/Message/hooks/__tests__/useMuteHandler.test.tsx

@@ -55,11 +55,13 @@ describe('useHandleMute custom hook', () => {
     expect(typeof handleMute).toBe('function');
   });
 
-  it('should throw a warning when there are missing parameters and the handler is called', async () => {
-    const consoleWarnSpy = vi.spyOn(console, 'warn').mockImplementationOnce(() => null);
+  it('should throw when there are missing parameters and the handler is called', async () => {
     const handleMute = await renderUseHandleMuteHook(undefined);
-    await handleMute(mouseEventMock);
-    expect(consoleWarnSpy).toHaveBeenCalledWith(missingUseMuteHandlerParamsWarning);
+    await expect(handleMute(mouseEventMock)).rejects.toThrow(
+      missingUseMuteHandlerParamsWarning,
+    );
+    expect(mute).not.toHaveBeenCalled();
+    expect(unmute).not.toHaveBeenCalled();
   });
 
   it('should allow to mute a user when it is successful', async () => {

src/components/Message/hooks/__tests__/usePinHandler.test.tsx

@@ -168,6 +168,17 @@ describe('usePinHandler custom hook', () => {
     expect(getStoredMessage(message.id)?.pinned_by).toEqual(newerPinner);
   });
 
+  it('should throw without pinning when the message is missing', async () => {
+    const pinSpy = vi.spyOn(client, 'pinMessage');
+    const { handlePin } = await renderUsePinHandler(undefined as unknown as LocalMessage);
+    await act(async () => {
+      await expect(handlePin(mouseEventMock)).rejects.toThrow(
+        'usePinHandler was called but it is missing the message.',
+      );
+    });
+    expect(pinSpy).not.toHaveBeenCalled();
+  });
+
   it('should keep a newer pin with the same pinned value that arrived while pinning', async () => {
     const rejectRequest = mockPendingRequest('pinMessage');
     const newerPinner = generateUser();

src/components/Message/hooks/__tests__/userMarkUnreadHandler.test.tsx

@@ -10,9 +10,8 @@ import { generateMessage, initClientWithChannels } from '../../../../mock-builde
 import { Channel } from '../../../Channel';
 import { Chat } from '../../../Chat';
 
-vi.spyOn(console, 'warn').mockImplementation(() => null);
-
 const event = fromPartial<React.BaseSyntheticEvent>({ preventDefault: vi.fn() });
+const missingMessageIdError = 'Mark unread handler does not have access to message id';
 const message = generateMessage() as unknown as LocalMessage;
 
 let channel: ChannelType;
@@ -47,22 +46,22 @@ describe('useMarkUnreadHandler', () => {
     vi.restoreAllMocks();
   });
 
-  it('does not call channel.markUnread if no message is provided', async () => {
+  it('throws without calling channel.markUnread if no message is provided', async () => {
     const markUnreadSpy = vi.spyOn(channel, 'markUnread');
     const handleMarkUnread = renderUseMarkUnreadHandlerHook();
     await act(async () => {
-      await handleMarkUnread(event);
+      await expect(handleMarkUnread(event)).rejects.toThrow(missingMessageIdError);
     });
     expect(markUnreadSpy).not.toHaveBeenCalled();
   });
 
-  it('does not call channel.markUnread if message is missing id', async () => {
+  it('throws without calling channel.markUnread if message is missing id', async () => {
     const markUnreadSpy = vi.spyOn(channel, 'markUnread');
     const handleMarkUnread = renderUseMarkUnreadHandlerHook({
       message: generateMessage({ id: undefined }) as unknown as LocalMessage,
     });
     await act(async () => {
-      await handleMarkUnread(event);
+      await expect(handleMarkUnread(event)).rejects.toThrow(missingMessageIdError);
     });
     expect(markUnreadSpy).not.toHaveBeenCalled();
   });

src/components/Message/hooks/useDeleteHandler.ts

@@ -27,7 +27,9 @@ export const useDeleteHandler = (
 
   return async (options?: DeleteMessageOptions) => {
     if (!message?.id || !client) {
-      return;
+      throw new Error(
+        'useDeleteHandler was called but it is missing one or more necessary parameters.',
+      );
     }
 
     try {

src/components/Message/hooks/useFlagHandler.ts

@@ -15,8 +15,7 @@ export const useFlagHandler = (message?: LocalMessage): ReactEventHandler => {
     event.preventDefault();
 
     if (!client || !t || !message?.id) {
-      console.warn(missingUseFlagHandlerParameterWarning);
-      return;
+      throw new Error(missingUseFlagHandlerParameterWarning);
     }
 
     await client.moderation.flagMessage({ message_id: message.id });

src/components/Message/hooks/useMarkUnreadHandler.ts

@@ -21,8 +21,7 @@ export const useMarkUnreadHandler = (
   return async (event) => {
     event.preventDefault();
     if (!message?.id) {
-      console.warn('Mark unread handler does not have access to message id');
-      return;
+      throw new Error('Mark unread handler does not have access to message id');
     }
 
     // Request failures propagate so the caller can report them; `notify` only reports success.

src/components/Message/hooks/useMuteHandler.ts

@@ -30,8 +30,7 @@ export const useMuteHandler = (
 
     // The action runs even without `notify` (`Message` passes none); it only reports the outcome.
     if (!message?.user || !client) {
-      console.warn(missingUseMuteHandlerParamsWarning);
-      return;
+      throw new Error(missingUseMuteHandlerParamsWarning);
     }
     const mutes = client.mutedUsersStore.getLatestValue().mutedUsers ?? [];