feat: add waitlist invitation functionality with tests and error handling

Author: tyler-dane

packages/backend/src/common/errors/waitlist/waitlist.errors.ts

@@ -0,0 +1,20 @@
+import { Status } from "@core/errors/status.codes";
+import { ErrorMetadata } from "@backend/common/types/error.types";
+
+interface WaitlistErrors {
+  DuplicateEmail: ErrorMetadata;
+  NotOnWaitlist: ErrorMetadata;
+}
+
+export const WaitlistError: WaitlistErrors = {
+  DuplicateEmail: {
+    description: "Email is already on waitlist",
+    status: Status.BAD_REQUEST,
+    isOperational: true,
+  },
+  NotOnWaitlist: {
+    description: "Email is not on waitlist",
+    status: Status.NOT_FOUND,
+    isOperational: true,
+  },
+};

packages/backend/src/waitlist/repo/waitlist.repo.ts

@@ -1,19 +1,66 @@
-import { Schema_Waitlist } from "@core/types/waitlist/waitlist.types";
+import {
+  Result_InviteToWaitlist,
+  Schema_Waitlist,
+} from "@core/types/waitlist/waitlist.types";
+import { error } from "@backend/common/errors/handlers/error.handler";
+import { WaitlistError } from "@backend/common/errors/waitlist/waitlist.errors";
 import mongoService from "@backend/common/services/mongo.service";
 
 export class WaitlistRepository {
   static async addToWaitlist(record: Schema_Waitlist) {
     return mongoService.waitlist.insertOne(record);
   }
 
+  static async invite(email: string): Promise<Result_InviteToWaitlist> {
+    const isOnWaitlist = await this.isAlreadyOnWaitlist(email);
+    if (!isOnWaitlist) {
+      throw error(WaitlistError.NotOnWaitlist, "Email is not on waitlist");
+    }
+
+    const result = await mongoService.waitlist.updateOne(
+      { email },
+      { $set: { status: "invited" } },
+    );
+
+    const invited = result.modifiedCount === 1;
+    return {
+      status: invited ? "invited" : "ignored",
+    };
+  }
+
   static async isAlreadyOnWaitlist(email: string) {
     const match = await mongoService.waitlist.find({ email }).toArray();
     return match.length > 0;
   }
 
-  //TODO change to include an 'invited' status
   static async isInvited(email: string) {
-    const match = await mongoService.waitlist.find({ email }).toArray();
-    return match.length > 0;
+    const record = await this._getWaitlistRecord(email);
+
+    if (!record) {
+      return false;
+    }
+
+    return record.status === "invited";
+  }
+
+  private static async _getWaitlistRecord(
+    email: string,
+  ): Promise<Schema_Waitlist | null> {
+    // Fetch up to 2 records to efficiently check for duplicates.
+    const matches = await mongoService.waitlist
+      .find({ email })
+      .limit(2)
+      .toArray();
+
+    if (matches.length > 1) {
+      throw error(WaitlistError.DuplicateEmail, "Unique email not returned");
+    }
+
+    if (matches.length === 0) {
+      return null; // No waitlist entry found for this email
+    }
+
+    // Exactly one match found
+    return matches[0] as Schema_Waitlist;
   }
 }

…aitlist/service/waitlist.service.test.ts …ist/service/waitlist.service-add.test.tspackages/backend/src/waitlist/service/waitlist.service.test.ts renamed to packages/backend/src/waitlist/service/waitlist.service-add.test.ts packages/backend/src/waitlist/service/waitlist.service.test.ts renamed to packages/backend/src/waitlist/service/waitlist.service-add.test.ts

@@ -1,4 +1,3 @@
-import { Answers } from "@core/types/waitlist/waitlist.answer.types";
 import { Result_Waitlist } from "@core/types/waitlist/waitlist.types";
 import {
   getEmailsOnWaitlist,
@@ -9,51 +8,8 @@ import {
   cleanupTestMongo,
   setupTestDb,
 } from "@backend/__tests__/helpers/mock.db.setup";
-import EmailService from "../../email/email.service";
 import WaitlistService from "./waitlist.service";
-
-const answer: Answers = {
-  firstName: "Jo",
-  lastName: "Schmo",
-  source: "other",
-  email: "joe@schmo.com",
-  currentlyPayingFor: undefined,
-  howClearAboutValues: "not-clear",
-  workingTowardsMainGoal: "yes",
-  isWillingToShare: false,
-  schemaVersion: "0",
-};
-
-// Mock emailer API calls
-jest.spyOn(EmailService, "upsertSubscriber").mockResolvedValue({
-  subscriber: {
-    id: 1,
-    first_name: answer.firstName,
-    email_address: answer.email,
-    state: "active",
-    created_at: new Date().toISOString(),
-    fields: {
-      "Last name": answer.lastName,
-      Birthday: "1970-01-01",
-      Source: answer.source,
-    },
-  },
-});
-jest.spyOn(EmailService, "addTagToSubscriber").mockResolvedValue({
-  subscriber: {
-    id: 1,
-    first_name: answer.firstName,
-    email_address: answer.email,
-    state: "active",
-    created_at: new Date().toISOString(),
-    tagged_at: new Date().toISOString(),
-    fields: {
-      "Last name": answer.lastName,
-      Birthday: "1970-01-01",
-      Source: answer.source,
-    },
-  },
-});
+import { answer } from "./waitlist.service.test-setup";
 
 describe("addToWaitlist", () => {
   let setup: Awaited<ReturnType<typeof setupTestDb>>;

packages/backend/src/waitlist/service/waitlist.service-invite.test.ts

@@ -0,0 +1,76 @@
+import {
+  cleanupCollections,
+  cleanupTestMongo,
+  setupTestDb,
+} from "@backend/__tests__/helpers/mock.db.setup";
+import WaitlistService from "./waitlist.service";
+import { answer } from "./waitlist.service.test-setup";
+
+describe("isInvited", () => {
+  let setup: Awaited<ReturnType<typeof setupTestDb>>;
+
+  beforeAll(async () => {
+    setup = await setupTestDb();
+  });
+
+  beforeEach(async () => {
+    await cleanupCollections(setup.db);
+  });
+
+  afterAll(async () => {
+    await cleanupTestMongo(setup);
+  });
+
+  it("should return false if email is not invited", async () => {
+    // simulates when user was waitlisted but not invited
+    const result = await WaitlistService.isInvited(answer.email);
+    expect(result).toBe(false);
+  });
+
+  it("should return true if email is invited", async () => {
+    // Arrange
+    await WaitlistService.addToWaitlist(answer.email, answer);
+    await WaitlistService.invite(answer.email);
+
+    // Act
+    const result = await WaitlistService.isInvited(answer.email);
+
+    // Assert
+    expect(result).toBe(true);
+  });
+});
+
+describe("invite", () => {
+  let setup: Awaited<ReturnType<typeof setupTestDb>>;
+
+  beforeAll(async () => {
+    setup = await setupTestDb();
+  });
+
+  beforeEach(async () => {
+    await cleanupCollections(setup.db);
+  });
+
+  afterAll(async () => {
+    await cleanupTestMongo(setup);
+  });
+
+  it("should invite email to waitlist", async () => {
+    // Arrange
+    await WaitlistService.addToWaitlist(answer.email, answer);
+
+    // Act
+    const result = await WaitlistService.invite(answer.email);
+
+    // Assert
+    expect(result.status).toBe("invited");
+  });
+
+  it("should ignore if email is not on waitlist", async () => {
+    // Act
+    const result = await WaitlistService.invite(answer.email);
+
+    // Assert
+    expect(result.status).toBe("ignored");
+  });
+});

packages/backend/src/waitlist/service/waitlist.service.test-setup.ts

@@ -0,0 +1,49 @@
+import { Answers } from "@core/types/waitlist/waitlist.answer.types";
+import EmailService from "@backend/email/email.service";
+
+/**
+ * Create mocks for waitlist service tests
+ */
+
+export const answer: Answers = {
+  firstName: "Jo",
+  lastName: "Schmo",
+  source: "other",
+  email: "joe@schmo.com",
+  currentlyPayingFor: undefined,
+  howClearAboutValues: "not-clear",
+  workingTowardsMainGoal: "yes",
+  isWillingToShare: false,
+  schemaVersion: "0",
+};
+
+// Mock emailer API calls
+jest.spyOn(EmailService, "upsertSubscriber").mockResolvedValue({
+  subscriber: {
+    id: 1,
+    first_name: answer.firstName,
+    email_address: answer.email,
+    state: "active",
+    created_at: new Date().toISOString(),
+    fields: {
+      "Last name": answer.lastName,
+      Birthday: "1970-01-01",
+      Source: answer.source,
+    },
+  },
+});
+jest.spyOn(EmailService, "addTagToSubscriber").mockResolvedValue({
+  subscriber: {
+    id: 1,
+    first_name: answer.firstName,
+    email_address: answer.email,
+    state: "active",
+    created_at: new Date().toISOString(),
+    tagged_at: new Date().toISOString(),
+    fields: {
+      "Last name": answer.lastName,
+      Birthday: "1970-01-01",
+      Source: answer.source,
+    },
+  },
+});

packages/backend/src/waitlist/service/waitlist.service.ts

@@ -1,8 +1,9 @@
 import { Logger } from "@core/logger/winston.logger";
 import { Subscriber } from "@core/types/email/email.types";
+import { Answers } from "@core/types/waitlist/waitlist.answer.types";
 import {
+  Result_InviteToWaitlist,
   Result_Waitlist,
-  Schema_Answers,
 } from "@core/types/waitlist/waitlist.types";
 import { ENV } from "@backend/common/constants/env.constants";
 import EmailService from "../../email/email.service";
@@ -12,7 +13,7 @@ const logger = Logger("app:waitlist.service");
 class WaitlistService {
   static async addToWaitlist(
     email: string,
-    answer: Schema_Answers,
+    answer: Answers,
   ): Promise<Result_Waitlist> {
     if (ENV.EMAILER_SECRET && ENV.EMAILER_WAITLIST_TAG_ID) {
       const subscriber: Subscriber = {
@@ -45,12 +46,29 @@ class WaitlistService {
     await WaitlistRepository.addToWaitlist({
       ...answer,
       waitlistedAt: new Date().toISOString(),
+      status: "waitlisted",
     });
 
     return {
       status: "waitlisted",
     };
   }
+
+  static async invite(email: string): Promise<Result_InviteToWaitlist> {
+    try {
+      const result = await WaitlistRepository.invite(email);
+      return result;
+    } catch (error) {
+      logger.error("Failed to invite email to waitlist", error);
+      return {
+        status: "ignored",
+      };
+    }
+  }
+
+  static async isInvited(email: string): Promise<boolean> {
+    return WaitlistRepository.isInvited(email);
+  }
 }
 
 export default WaitlistService;

packages/core/src/types/waitlist/waitlist.types.ts

@@ -5,6 +5,10 @@ export interface Result_Waitlist {
   status: "waitlisted" | "ignored";
 }
 
+export interface Result_InviteToWaitlist {
+  status: "invited" | "ignored";
+}
+
 const Schema_Status = z.enum(["waitlisted", "invited", "active"]);
 
 const Schema_Waitlist_v0 = Schema_Answers_v0.extend({