sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ Cognito/ UserPoolTriggerEventSource.ts

import * as Binding from "alchemy/Binding";
import type * as lambda from "aws-lambda";
import type * as Effect from "effect/Effect";
import type { UserPool, UserPoolTriggerName } from "./UserPool.ts";

/**
 * The typed event each trigger slot receives (the Cognito
 * `version`/`triggerSource`/`request`/`response` envelope from
 * `aws-lambda`).
 */
export interface UserPoolTriggerEventMap {
  PreSignUp: lambda.PreSignUpTriggerEvent;
  PostConfirmation: lambda.PostConfirmationTriggerEvent;
  PreAuthentication: lambda.PreAuthenticationTriggerEvent;
  PostAuthentication: lambda.PostAuthenticationTriggerEvent;
  CustomMessage: lambda.CustomMessageTriggerEvent;
  DefineAuthChallenge: lambda.DefineAuthChallengeTriggerEvent;
  CreateAuthChallenge: lambda.CreateAuthChallengeTriggerEvent;
  VerifyAuthChallengeResponse: lambda.VerifyAuthChallengeResponseTriggerEvent;
  PreTokenGeneration: lambda.PreTokenGenerationTriggerEvent;
  UserMigration: lambda.UserMigrationTriggerEvent;
}

export type UserPoolTriggerEvent<T extends UserPoolTriggerName> = UserPoolTriggerEventMap[T];

/**
 * The `triggerSource` prefix Cognito stamps on invocations of each trigger
 * slot (e.g. `PreSignUp` fires with `PreSignUp_SignUp`,
 * `PreSignUp_AdminCreateUser`, …; `PreTokenGeneration` fires with
 * `TokenGeneration_*`). Used by the runtime dispatcher to route events to
 * the registered handler.
 */
export const userPoolTriggerSourcePrefixes: Record<UserPoolTriggerName, string> = {
  PreSignUp: "PreSignUp_",
  PostConfirmation: "PostConfirmation_",
  PreAuthentication: "PreAuthentication_",
  PostAuthentication: "PostAuthentication_",
  CustomMessage: "CustomMessage_",
  DefineAuthChallenge: "DefineAuthChallenge_",
  CreateAuthChallenge: "CreateAuthChallenge_",
  VerifyAuthChallengeResponse: "VerifyAuthChallengeResponse_",
  PreTokenGeneration: "TokenGeneration_",
  UserMigration: "UserMigration_",
};

export interface UserPoolTriggerProps<T extends UserPoolTriggerName = UserPoolTriggerName> {
  /** The trigger slot to handle, e.g. `PreSignUp` or `CustomMessage`. */
  trigger: T;
}

/**
 * A user pool trigger handler receives the typed trigger event and returns
 * the (usually mutated) event, which becomes the Lambda's response back to
 * Cognito. Returning `void` responds with the event as-is.
 */
export type UserPoolTriggerHandler<T extends UserPoolTriggerName, Req = never> = (
  event: UserPoolTriggerEvent<T>,
) => Effect.Effect<UserPoolTriggerEvent<T> | void, never, Req>;

export type UserPoolTriggerEventSourceService = <T extends UserPoolTriggerName, Req = never>(
  userPool: UserPool,
  props: UserPoolTriggerProps<T>,
  handler: UserPoolTriggerHandler<T, Req>,
) => Effect.Effect<void, never, never>;

/**
 * Event source connecting a Cognito {@link UserPool} Lambda trigger to the
 * hosting Lambda function.
 *
 * At deploy time the Lambda implementation
 * (`Lambda.UserPoolTriggerEventSource`) injects the function ARN into the
 * pool's `LambdaConfig` (via the pool's binding contract) and creates the
 * `lambda:InvokeFunction` Permission for `cognito-idp.amazonaws.com`; at
 * runtime it dispatches matching trigger events to the handler and returns
 * the handler's (mutated) event to Cognito.
 *
 * Use the {@link onUserPoolTrigger} helper (or the per-slot shorthands
 * {@link onPreSignUp}, {@link onPostConfirmation},
 * {@link onPreTokenGeneration}, {@link onCustomMessage}) rather than the
 * service directly, and provide `Lambda.UserPoolTriggerEventSource` on the
 * hosting function.
 * ### Handling User Pool Triggers
 * **Example:** Auto-confirm Sign-ups from a Lambda Function
 * ```typescript
 * export default AuthFunction.make(
 *   { main: import.meta.url },
 *   Effect.gen(function* () {
 *     const pool = yield* Cognito.UserPool("Users", {});
 *
 *     // deploy: wires PreSignUp in the pool's LambdaConfig + invoke Permission
 *     // runtime: dispatches PreSignUp_* events to this handler
 *     yield* Cognito.onPreSignUp(pool, (event) =>
 *       Effect.sync(() => Cognito.autoConfirmUser(event, { verifyEmail: true })),
 *     );
 *
 *     return {};
 *   }).pipe(Effect.provide(Lambda.UserPoolTriggerEventSource)),
 * );
 * ```
 *
 * @binding
 */
export interface UserPoolTriggerEventSource extends Binding.Service<
  UserPoolTriggerEventSource,
  "AWS.Cognito.UserPoolTriggerEventSource",
  UserPoolTriggerEventSourceService
> {}

export const UserPoolTriggerEventSource = Binding.Service<UserPoolTriggerEventSource>(
  "AWS.Cognito.UserPoolTriggerEventSource",
);

/**
 * Handle a Cognito user pool Lambda trigger with the current Lambda
 * function.
 *
 * Provide `Lambda.UserPoolTriggerEventSource` on the hosting function to
 * satisfy the requirement.
 *
 * @param userPool The user pool whose trigger to handle.
 * @param props The trigger slot to handle.
 * @param handler Invoked once per trigger event; the returned event is the
 * response Cognito receives.
 *
 * @example Auto-confirm every sign-up
 * ```typescript
 * yield* Cognito.onUserPoolTrigger(pool, { trigger: "PreSignUp" }, (event) =>
 *   Effect.sync(() => Cognito.autoConfirmUser(event, { verifyEmail: true })),
 * );
 * ```
 */
export function onUserPoolTrigger<T extends UserPoolTriggerName, Req = never>(
  userPool: UserPool,
  props: UserPoolTriggerProps<T>,
  handler: UserPoolTriggerHandler<T, Req>,
): Effect.Effect<void, never, UserPoolTriggerEventSource> {
  return UserPoolTriggerEventSource.use((source) => source(userPool, props, handler));
}

/**
 * Handle the `PreSignUp` trigger — runs before Cognito registers a new
 * user; the handler can auto-confirm the user (see
 * {@link autoConfirmUser}) or reject the sign-up.
 */
export const onPreSignUp = <Req = never>(
  userPool: UserPool,
  handler: UserPoolTriggerHandler<"PreSignUp", Req>,
) => onUserPoolTrigger(userPool, { trigger: "PreSignUp" }, handler);

/**
 * Handle the `PostConfirmation` trigger — runs after a user confirms their
 * account (welcome emails, provisioning rows, analytics).
 */
export const onPostConfirmation = <Req = never>(
  userPool: UserPool,
  handler: UserPoolTriggerHandler<"PostConfirmation", Req>,
) => onUserPoolTrigger(userPool, { trigger: "PostConfirmation" }, handler);

/**
 * Handle the `PreTokenGeneration` trigger — runs before Cognito issues
 * tokens; the handler can add, override, or suppress claims via
 * `event.response.claimsOverrideDetails`.
 */
export const onPreTokenGeneration = <Req = never>(
  userPool: UserPool,
  handler: UserPoolTriggerHandler<"PreTokenGeneration", Req>,
) => onUserPoolTrigger(userPool, { trigger: "PreTokenGeneration" }, handler);

/**
 * Handle the `CustomMessage` trigger — customizes the verification /
 * invitation messages Cognito sends by mutating
 * `event.response.emailSubject` / `emailMessage` / `smsMessage`.
 */
export const onCustomMessage = <Req = never>(
  userPool: UserPool,
  handler: UserPoolTriggerHandler<"CustomMessage", Req>,
) => onUserPoolTrigger(userPool, { trigger: "CustomMessage" }, handler);

/**
 * Mutate a `PreSignUp` trigger event's response to auto-confirm the user
 * (and optionally auto-verify their email / phone number), then return the
 * event so it can be handed straight back to Cognito.
 *
 * @example Sign-ups arrive CONFIRMED, no confirmation code required
 * ```typescript
 * yield* Cognito.onPreSignUp(pool, (event) =>
 *   Effect.sync(() => Cognito.autoConfirmUser(event, { verifyEmail: true })),
 * );
 * ```
 */
export const autoConfirmUser = <E extends lambda.PreSignUpTriggerEvent>(
  event: E,
  options?: {
    /** Also mark the user's email as verified. @default false */
    verifyEmail?: boolean;
    /** Also mark the user's phone number as verified. @default false */
    verifyPhone?: boolean;
  },
): E => {
  event.response.autoConfirmUser = true;
  if (options?.verifyEmail === true) {
    event.response.autoVerifyEmail = true;
  }
  if (options?.verifyPhone === true) {
    event.response.autoVerifyPhone = true;
  }
  return event;
};