refactor: remove the unused "prompt" event result

Author: d-gubert

packages/apps-engine/src/definition/eventResult/EventResult.ts

@@ -1,9 +1,5 @@
-import type { Block, TextObject } from '@rocket.chat/ui-kit';
-
 /**
  * Reserved discriminator stamped by the `EventResult.*` factories below.
- * App authors never write this by hand — see
- * docs/proposals/apps-engine-event-result-return-type.md §"The discriminator".
  */
 export const EVENT_RESULT_KIND = 'EventResult';
 
@@ -16,26 +12,14 @@ export type I18nMessage = {
 	args?: { [key: string]: string | number };
 };
 
-type PromptPayload =
-	| { message: string }
-	| { i18n: I18nMessage }
-	| {
-			title?: TextObject;
-			text?: TextObject;
-			blocks?: Block[];
-			confirmLabel?: string;
-			cancelLabel?: string;
-	  };
-
 /**
  * Author-facing, marker-free union — the type app authors annotate a handler's
  * return type against (directly, or via a per-event restricted alias).
  */
 export type EventResult<T = unknown> =
 	| { type: 'pass' }
 	| { type: 'patch'; patch: Partial<T> }
-	| ({ type: 'prevent' } & ({ reason: string } | { i18n: I18nMessage }))
-	| ({ type: 'prompt' } & PromptPayload);
+	| ({ type: 'prevent' } & ({ reason: string } | { i18n: I18nMessage }));
 
 /** Branded variant returned by `EventResult.pass()`. */
 export type PassEventResult = IMarker & { type: 'pass' };
@@ -46,22 +30,19 @@ export type PatchEventResult<T> = IMarker & { type: 'patch'; patch: Partial<T> }
 /** Branded variant returned by `EventResult.prevent()`. */
 export type PreventEventResult = IMarker & { type: 'prevent' } & ({ reason: string } | { i18n: I18nMessage });
 
-/** Branded variant returned by `EventResult.prompt()`. */
-export type PromptEventResult = IMarker & { type: 'prompt' } & PromptPayload;
-
 /**
  * The shape that actually crosses the JSON-RPC boundary and that
  * `isEventResult()` recognizes — `EventResult` widened with the `@kind` marker.
  */
-export type MarkedEventResult<T = unknown> = PassEventResult | PatchEventResult<T> | PreventEventResult | PromptEventResult;
+export type MarkedEventResult<T = unknown> = PassEventResult | PatchEventResult<T> | PreventEventResult;
 
 /**
  * Companion-object factories. `EventResult` is simultaneously the marker-free
  * union *type* above and this factory *value* namespace (same name, separate
  * type/value namespaces — no declaration-merging trick needed). Each factory
  * stamps `@kind` and returns a branded per-variant type so that a handler whose
  * return type is a restricted union (e.g. `pass | patch`) fails to typecheck if
- * an author returns a disallowed variant (e.g. `prompt`).
+ * an author returns a disallowed variant (e.g. `prevent`).
  */
 // eslint-disable-next-line @typescript-eslint/no-redeclare -- the union type and the factory namespace share a name on purpose
 export const EventResult = {
@@ -76,8 +57,4 @@ export const EventResult = {
 	prevent(input: { reason: string } | { i18n: I18nMessage }): PreventEventResult {
 		return { '@kind': EVENT_RESULT_KIND, 'type': 'prevent', ...input };
 	},
-
-	prompt(input: PromptPayload): PromptEventResult {
-		return { '@kind': EVENT_RESULT_KIND, 'type': 'prompt', ...input };
-	},
 };

packages/apps-engine/src/definition/eventResult/index.ts

@@ -1,10 +1,3 @@
 export { EventResult, EVENT_RESULT_KIND } from './EventResult';
-export type {
-	PassEventResult,
-	PatchEventResult,
-	PreventEventResult,
-	PromptEventResult,
-	MarkedEventResult,
-	I18nMessage,
-} from './EventResult';
+export type { PassEventResult, PatchEventResult, PreventEventResult, MarkedEventResult, I18nMessage } from './EventResult';
 export { isEventResult } from './isEventResult';

packages/apps-engine/src/definition/eventResult/isEventResult.ts

@@ -3,10 +3,7 @@ import type { MarkedEventResult } from './EventResult';
 
 /**
  * Runtime guard for the `EventResult` marker. Must run *before* any legacy
- * `typeof result === 'object'` / truthiness branch at a consumption site —
- * otherwise a `EventResult` returned from a not-yet-widened handler would be
- * misinterpreted as the legacy shape it is replacing. See
- * docs/proposals/apps-engine-event-result-return-type.md §"Non-breaking guarantee".
+ * `typeof result === 'object'` / truthiness branch at a consumption site
  */
 export function isEventResult(value: unknown): value is MarkedEventResult {
 	return typeof value === 'object' && value !== null && (value as Record<string, unknown>)['@kind'] === EVENT_RESULT_KIND;

packages/apps-engine/src/definition/mediaCalls/MediaCallEventResult.ts

@@ -2,8 +2,8 @@ import type { MediaCallCreatePatch } from './IPreMediaCallCreatedContext';
 import type { PassEventResult, PatchEventResult, PreventEventResult } from '../eventResult';
 
 /**
- * Restricted `EventResult` union for the pre-media-call-create event.
- * `prompt` is not yet permitted here — see the per-event capability matrix in
- * docs/proposals/apps-engine-event-result-return-type.md.
+ * The `EventResult` variants the pre-media-call-create event permits — see the
+ * per-event capability matrix in
+ * docs/adr/0002-unified-event-result-for-pre-events.md.
  */
 export type MediaCallCreateEventResult = PassEventResult | PatchEventResult<MediaCallCreatePatch> | PreventEventResult;

packages/apps/src/server/managers/AppListenerManager.ts

@@ -1,4 +1,5 @@
 import type { IEmailDescriptor, IPreEmailSentContext } from '@rocket.chat/apps-engine/definition/email';
+import type { MarkedEventResult } from '@rocket.chat/apps-engine/definition/eventResult';
 import { isEventResult } from '@rocket.chat/apps-engine/definition/eventResult';
 import { EssentialAppDisabledException } from '@rocket.chat/apps-engine/definition/exceptions';
 import type { IExternalComponent } from '@rocket.chat/apps-engine/definition/externalComponent';
@@ -1342,7 +1343,14 @@ export class AppListenerManager {
 				case 'pass':
 					break;
 				default:
-					console.warn(`App ${appId} returned an unsupported EventResult from ${AppMethod.EXECUTE_PRE_MEDIA_CALL_CREATED}: ${result.type}`);
+					// Unreachable for a well-formed app: the cases above cover every variant
+					// the type declares. It still has to fail open, because what arrives here
+					// is a JSON-RPC payload the types never got to check.
+					console.warn(
+						`App ${appId} returned an unsupported EventResult from ${AppMethod.EXECUTE_PRE_MEDIA_CALL_CREATED}: ${
+							(result as MarkedEventResult).type
+						}`,
+					);
 			}
 		}
 

packages/apps/tests/server/managers/AppListenerManager.mediaCalls.test.ts

@@ -1,7 +1,7 @@
 import * as assert from 'node:assert';
 import { describe, it } from 'node:test';
 
-import { EventResult } from '@rocket.chat/apps-engine/definition/eventResult';
+import { EVENT_RESULT_KIND, EventResult } from '@rocket.chat/apps-engine/definition/eventResult';
 import type {
 	IMediaCall,
 	IMediaCallEndedContext,
@@ -203,11 +203,19 @@ describe('AppListenerManager media call events', () => {
 			assert.deepStrictEqual(outcome, { prevented: false, context });
 		});
 
+		/**
+		 * The static types forbid this, so it only arrives from a bug or a tampered
+		 * JSON-RPC payload — hence the hand-built marker instead of a factory call.
+		 */
 		it('warns about and passes over an EventResult variant this event does not support', async () => {
 			const { result: outcome, warnings } = await capturingWarnings(() =>
 				runPreCallCreated([
 					mockApp('prompting', {
-						[AppMethod.EXECUTE_PRE_MEDIA_CALL_CREATED]: () => EventResult.prompt({ message: 'Are you sure?' }),
+						[AppMethod.EXECUTE_PRE_MEDIA_CALL_CREATED]: () => ({
+							'@kind': EVENT_RESULT_KIND,
+							'type': 'prompt',
+							'message': 'Are you sure?',
+						}),
 					}),
 				]),
 			);