import * as Binding from "alchemy/Binding";
import type * as Effect from "effect/Effect";
import type { Room } from "./Room.ts";
/**
* The payload Amazon IVS Chat sends to a room's message review handler for
* every `SendMessage` request — the wire shape is PascalCase, verbatim from
* the [message review handler contract](https://docs.aws.amazon.com/ivs/latest/ChatUserGuide/chat-message-review-handler.html).
*/
export interface RoomMessageEvent {
/** Original content of the message. */
Content: string;
/** The message ID, generated by IVS Chat. */
MessageId: string;
/** ARN of the room the message was sent to. */
RoomArn: string;
/** Attributes associated with the message. */
Attributes?: { [key: string]: string | undefined };
/** Information about the sender. */
Sender?: {
/** The `userId` the sender's chat token was minted with. */
UserId?: string;
/** IP address of the sender. */
Ip?: string;
/** The attributes attached to the sender's chat token. */
Attributes?: { [key: string]: string | undefined };
};
}
/**
* The review verdict a message review handler returns to Amazon IVS Chat.
* `ALLOW` delivers the message (with the possibly-edited `Content` /
* `Attributes`); `DENY` drops it — the sender receives a WebSocket 406
* whose message carries `Attributes.Reason` when provided.
*/
export interface RoomMessageReview {
/** Whether to deliver the message. */
ReviewResult: "ALLOW" | "DENY";
/**
* Content to deliver — edited or original. Defaults to the original
* message content when omitted.
*/
Content?: string;
/**
* Attributes to deliver with the message. On `DENY`, a `Reason` entry is
* surfaced to the sender in the WebSocket 406 error message.
*/
Attributes?: { [key: string]: string | undefined };
}
/**
* A message review handler receives each message sent to the bound room and
* returns the review verdict. Returning `void` allows the message with its
* original content and attributes.
*/
export type RoomMessageReviewHandlerFn<Req = never> = (
event: RoomMessageEvent,
) => Effect.Effect<RoomMessageReview | void, never, Req>;
export interface RoomMessageReviewProps {
/**
* What happens to a message if the handler errors, times out, or returns
* an invalid response: `ALLOW` delivers it, `DENY` drops it.
* @default "ALLOW"
*/
fallbackResult?: "ALLOW" | "DENY";
}
export type RoomMessageReviewEventSourceService = <Req = never>(
room: Room,
handler: RoomMessageReviewHandlerFn<Req>,
props?: RoomMessageReviewProps,
) => Effect.Effect<void, never, never>;
/**
* Event source connecting an IVS Chat {@link Room}'s message review handler
* to the hosting Lambda function — every message sent to the room is
* synchronously reviewed (allow / modify / deny) by the handler before
* delivery.
*
* At deploy time the Lambda implementation
* (`Lambda.RoomMessageReviewEventSource`) injects the function ARN into the
* room's `messageReviewHandler` (via the room's binding contract) and
* creates the `lambda:InvokeFunction` Permission for
* `ivschat.amazonaws.com`; at runtime it dispatches review invocations for
* the bound room to the handler and returns the verdict to IVS Chat.
*
* Use the {@link onReviewMessage} helper rather than the service directly,
* and provide `Lambda.RoomMessageReviewEventSource` on the hosting
* function.
* ### Reviewing Messages
* **Example:** Moderate a Room from a Lambda Function
* ```typescript
* export default ChatFunction.make(
* { main: import.meta.url },
* Effect.gen(function* () {
* const room = yield* IVSChat.Room("LiveChat");
*
* // deploy: sets the room's messageReviewHandler + invoke Permission
* // runtime: reviews every message sent to the room
* yield* IVSChat.onReviewMessage(room, (event) =>
* Effect.succeed(
* event.Content.includes("banned-word")
* ? { ReviewResult: "DENY", Attributes: { Reason: "moderated" } }
* : { ReviewResult: "ALLOW", Content: event.Content.trim() },
* ),
* );
*
* return {};
* }).pipe(Effect.provide(Lambda.RoomMessageReviewEventSource)),
* );
* ```
*
* @binding
*/
export interface RoomMessageReviewEventSource extends Binding.Service<
RoomMessageReviewEventSource,
"AWS.IVSChat.RoomMessageReviewEventSource",
RoomMessageReviewEventSourceService
> {}
export const RoomMessageReviewEventSource = Binding.Service<RoomMessageReviewEventSource>(
"AWS.IVSChat.RoomMessageReviewEventSource",
);
/**
* Review (and optionally modify or deny) every message sent to the room
* with the current Lambda function.
*
* Provide `Lambda.RoomMessageReviewEventSource` on the hosting function to
* satisfy the requirement.
*
* @param room The room whose messages to review.
* @param handler Invoked once per message; the returned
* {@link RoomMessageReview} is the verdict IVS Chat applies. `void` allows
* the message unchanged.
* @param props Optional `fallbackResult` applied when the handler errors or
* times out.
*
* @example Deny messages containing a banned word
* ```typescript
* yield* IVSChat.onReviewMessage(
* room,
* (event) =>
* Effect.succeed(
* event.Content.includes("banned-word")
* ? { ReviewResult: "DENY", Attributes: { Reason: "moderated" } }
* : undefined,
* ),
* { fallbackResult: "ALLOW" },
* );
* ```
*/
export function onReviewMessage<Req = never>(
room: Room,
handler: RoomMessageReviewHandlerFn<Req>,
props?: RoomMessageReviewProps,
): Effect.Effect<void, never, RoomMessageReviewEventSource> {
return RoomMessageReviewEventSource.use((source) => source(room, handler, props));
}