refactor: apply suggestions from code review

packages/core/src/routes/experience/classes/experience-interaction.ts

@@ -22,31 +22,28 @@ const interactionStorageGuard = z.object({
 });
 
 /**
- * ExperienceInteraction
- *
- * @overview
  * Interaction is a short-lived session session that is initiated when a user starts an interaction flow with the Logto platform.
  * This class is used to manage all the interaction data and status.
- * @see {@link https://github.com/logto-io/rfcs | Logto RFCs} for more information about RFC 0004.
  *
+ * @see {@link https://github.com/logto-io/rfcs | Logto RFCs} for more information about RFC 0004.
  */
 export default class ExperienceInteraction {
   /**
-   * Factory method to create a new ExperienceInteraction using context
+   * Factory method to create a new `ExperienceInteraction` using the current context.
    */
   static async create(ctx: WithLogContext, tenant: TenantContext) {
     const { provider } = tenant;
     const interactionDetails = await provider.interactionDetails(ctx.req, ctx.res);
     return new ExperienceInteraction(ctx, tenant, interactionDetails);
   }
 
-  /** The interaction event for the current interaction */
+  /** The interaction event for the current interaction. */
   private interactionEvent?: InteractionEvent;
-  /** The user verification record list for the current interaction */
+  /** The user verification record list for the current interaction. */
   private readonly verificationRecords: Set<VerificationRecord>;
-  /** The accountId of the user for the current interaction. Only available once the user is identified */
+  /** The accountId of the user for the current interaction. Only available once the user is identified. */
   private accountId?: string;
-  /** The user provided profile data in the current interaction that needs to be stored to user DB */
+  /** The user provided profile data in the current interaction that needs to be stored to database. */
   private readonly profile?: Record<string, unknown>; // TODO: Fix the type
 
   constructor(
@@ -80,7 +77,7 @@ export default class ExperienceInteraction {
     this.interactionEvent = event;
   }
 
-  /** Set the verified accountId of the current interaction from  the verification record */
+  /** Set the verified `accountId` of the current interaction from the verification record */
   public identifyUser(verificationRecord: VerificationRecord) {
     // Throws an 404 error if the user is not found by the given verification record
     assertThat(
@@ -96,7 +93,7 @@ export default class ExperienceInteraction {
 
   /**
    * Append a new verification record to the current interaction.
-   * @remark If a record with the same type already exists, it will be replaced.
+   * If a record with the same type already exists, it will be replaced.
    */
   public appendVerificationRecord(record: VerificationRecord) {
     const { type } = record;
@@ -114,11 +111,11 @@ export default class ExperienceInteraction {
     return this.verificationRecordsArray.find((record) => record.id === verificationId);
   }
 
-  /** Save the current interaction result */
+  /** Save the current interaction result. */
   public async save() {
-    // The "mergeWithLastSubmission" will only merge current request's interaction results,
-    // manually merge with previous interaction results
-    // refer to: https://github.com/panva/node-oidc-provider/blob/c243bf6b6663c41ff3e75c09b95fb978eba87381/lib/actions/authorization/interactions.js#L106
+    // `mergeWithLastSubmission` will only merge current request's interaction results.
+    // Manually merge with previous interaction results here.
+    // @see {@link https://github.com/panva/node-oidc-provider/blob/c243bf6b6663c41ff3e75c09b95fb978eba87381/lib/actions/authorization/interactions.js#L106}
 
     const { provider } = this.tenant;
     const details = await provider.interactionDetails(this.ctx.req, this.ctx.res);

packages/core/src/routes/experience/classes/verifications/password-verification.ts

@@ -20,7 +20,7 @@ export type PasswordVerificationRecordData = {
   id: string;
   type: VerificationType.Password;
   identifier: InteractionIdentifier;
-  /* The userId of the user that has been verified */
+  /** The userId of the user that has been verified. */
   userId?: string;
 };
 
@@ -48,9 +48,9 @@ export class PasswordVerification implements VerificationRecord<VerificationType
 
   /**
    * The constructor method is intended to be used internally by the interaction class
-   * to instantiate a VerificationRecord object from existing PasswordVerificationRecordData.
+   * to instantiate a `VerificationRecord` object from existing `PasswordVerificationRecordData`.
    * It directly sets the instance properties based on the provided data.
-   * For creating a new verification record, use the static create method instead.
+   * For creating a new verification record from context, use the static `create` method instead.
    */
   constructor(
     private readonly libraries: Libraries,
@@ -75,8 +75,7 @@ export class PasswordVerification implements VerificationRecord<VerificationType
 
   /**
    * Verifies if the password matches the record in database with the current identifier.
-   *
-   * - userId is set if the password is verified.
+   * `userId` will be set if the password can be verified.
    *
    * @throws RequestError with 401 status if user id suspended.
    * @throws RequestError with 422 status if the user is not found or the password is incorrect.

packages/core/src/routes/experience/middleware/koa-experience-interaction.ts

@@ -11,9 +11,10 @@ export type WithExperienceInteractionContext<ContextT extends WithLogContext = W
   };
 
 /**
- * @overview This middleware initializes the ExperienceInteraction for the current request.
- * The ExperienceInteraction instance is used to manage all the data related to the current interaction.
- * All the interaction data is stored using the oidc-provider's interaction session
+ * @overview This middleware initializes the `ExperienceInteraction` for the current request.
+ * The `ExperienceInteraction` instance is used to manage all the data related to the current interaction.
+ * All the interaction data is stored using oidc-provider's interaction session.
+ *
  * @see {@link https://github.com/panva/node-oidc-provider/blob/main/docs/README.md#user-flows}
  */
 export default function koaExperienceInteraction<

packages/schemas/src/types/interactions.ts

@@ -14,7 +14,7 @@ import {
 } from './verification-code.js';
 
 /**
- * User interaction events defined in Logto RFC 0004
+ * User interaction events defined in Logto RFC 0004.
  * @see {@link https://github.com/logto-io/rfcs | Logto RFCs} for more information.
  */
 export enum InteractionEvent {
@@ -23,14 +23,14 @@ export enum InteractionEvent {
   ForgotPassword = 'ForgotPassword',
 }
 
-// ====== Experience API payload guards and types definitions start ======
+// ====== Experience API payload guards and type definitions start ======
 export enum InteractionIdentifierType {
   Username = 'username',
   Email = 'email',
   Phone = 'phone',
 }
 
-/** Identifiers that can be used to uniquely identify a user */
+/** Identifiers that can be used to uniquely identify a user. */
 export type InteractionIdentifier = {
   type: InteractionIdentifierType;
   value: string;
@@ -41,7 +41,7 @@ export const interactionIdentifierGuard = z.object({
   value: z.string(),
 }) satisfies ToZodObject<InteractionIdentifier>;
 
-/** Logto supported interaction verification types */
+/** Logto supported interaction verification types. */
 export enum VerificationType {
   Password = 'Password',
   VerificationCode = 'VerificationCode',
@@ -53,7 +53,7 @@ export enum VerificationType {
 
 // REMARK: API payload guard
 
-/** Payload type for: /experience/verification/password */
+/** Payload type for `POST /api/experience/verification/password`. */
 export type PasswordVerificationPayload = {
   identifier: InteractionIdentifier;
   password: string;
@@ -63,7 +63,7 @@ export const passwordVerificationPayloadGuard = z.object({
   password: z.string().min(1),
 }) satisfies ToZodObject<PasswordVerificationPayload>;
 
-/** Payload type for: /experience/identification */
+/** Payload type for `POST /api/experience/identification`. */
 export type IdentificationApiPayload = {
   interactionEvent: InteractionEvent;
   verificationId: string;
@@ -74,8 +74,6 @@ export const identificationApiPayloadGuard = z.object({
   verificationId: z.string(),
 }) satisfies ToZodObject<IdentificationApiPayload>;
 
-/* API payload guard end */
-
 // ====== Experience API payload guards and type definitions end ======
 
 /**