sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ IVSChat/ RoomMessageReviewEventSource.ts

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));
}