✨ !Feat: create waitlist service (#411)

* 📦 deps: add supertest

* ✨ feat: create waitlist and email services

* ✨ feat(core): add subscriber mapper and types

* ♻️ Refactor: reuse headers in email service

* 🧹 Chore: delete old email service

* 🧪 Test: update jest config with email alias

* ✨ Feat: update user service to use new tag flow

* ✨ !Feat: update ENV value to use TAG id

* ✨ Feat: update waitlist service and controller

* ✨ Feat: add error handling to emailer

* 🧹 Chore: delete old email service

* 🧹 Chore: update waitlist types

* ✨ Feat: persist waitlist record

* ✨ Feat: add waitlistedAt to schema

* ♻️ Refactor: remove "v" from version

* 🧹 Chore: update .env.example with updated KIT keys

Author: tyler-dane

jest.config.js

@@ -148,6 +148,7 @@ module.exports = {
           "<rootDir>/packages/backend/src/calendar/$1",
         "^@backend/common/(.*)$": "<rootDir>/packages/backend/src/common/$1",
         "^@backend/dev/(.*)$": "<rootDir>/packages/backend/src/dev/$1",
+        "^@backend/email/(.*)$": "<rootDir>/packages/backend/src/email/$1",
         "^@backend/event/(.*)$": "<rootDir>/packages/backend/src/event/$1",
         "^@backend/priority/(.*)$":
           "<rootDir>/packages/backend/src/priority/$1",

packages/backend/.env.example

@@ -66,13 +66,18 @@ PROD_DOMAIN=app.yourdomain.com
 ####################################################
 # 6. Email (optional)                              #
 ####################################################
-# Get these from your ConvertKit account
-# Does not capture email during signup if any empty EMAILER_ value
+# Get these from your Kit.com account
+# If any of these EMAILER_ values are empty, email
+# integration during signup will be skipped
 
-EMAILER_API_SECRET=UNIQUE_SECRET_FROM_YOUR_CONVERTKIT_ACCOUNT
-EMAILER_LIST_ID=YOUR_LIST_ID # get this from the URL
+EMAILER_API_SECRET=UNIQUE_SECRET_FROM_YOUR_KIT_ACCOUNT
+EMAILER_TAG_ID=YOUR_TAG_ID # get this from Kit
 
 ####################################################
 # 7. Debug (optional)                              #
 ####################################################
+# Set this to trigger socket events to a client
+# during development. This is helpful for testing
+# the sync process from local host. 
+
 SOCKET_USER=USER_ID_FROM_YOUR_MONGO_DB

packages/backend/package.json

@@ -36,9 +36,11 @@
     "@types/module-alias": "^2.0.1",
     "@types/morgan": "^1.9.4",
     "@types/node": "^22.13.10",
+    "@types/supertest": "^6.0.3",
     "alias-hq": "^6.1.0",
     "jest-environment-node": "^29.7.0",
     "socket.io-client": "^4.7.5",
+    "supertest": "^7.1.0",
     "tsconfig-paths": "^4.1.2"
   }
 }

packages/backend/src/__tests__/backend.test.init.js

@@ -12,6 +12,6 @@ process.env.CHANNEL_EXPIRATION_MIN = 5;
 process.env.SUPERTOKENS_URI = "sTUri";
 process.env.SUPERTOKENS_KEY = "sTKey";
 process.env.EMAILER_API_SECRET = "emailerApiSecret";
-process.env.EMAILER_LIST_ID = 1234567;
+process.env.EMAILER_TAG_ID = 1234567;
 process.env.TOKEN_GCAL_NOTIFICATION = "secretToken1";
 process.env.TOKEN_COMPASS_SYNC = "secretToken2";

packages/backend/src/__tests__/helpers/mock.db.queries.ts

@@ -1,4 +1,5 @@
 import { Event_Core } from "@core/types/event.types";
+import { Schema_Waitlist } from "@core/types/waitlist/waitlist.types";
 import { Collections } from "@backend/common/constants/collections";
 import mongoService from "@backend/common/services/mongo.service";
 import { Event_API } from "@backend/common/types/backend.event.types";
@@ -20,6 +21,20 @@ export const getEventsInDb = async () => {
     .toArray()) as unknown as Event_API[];
 };
 
+export const getEmailsOnWaitlist = async () => {
+  const waitlist = (await mongoService.db
+    .collection(Collections.WAITLIST)
+    .find()
+    .toArray()) as unknown as Schema_Waitlist[];
+
+  const emails = waitlist.map((w) => w.email);
+  return emails;
+};
+
+export const isEmailOnWaitlist = async (email: string) => {
+  return (await getEmailsOnWaitlist()).includes(email);
+};
+
 export const isEventCollectionEmpty = async () => {
   return (
     (await mongoService.db.collection(Collections.EVENT).find().toArray())

packages/backend/src/__tests__/helpers/mock.db.setup.ts

@@ -3,6 +3,7 @@ import { MongoMemoryServer } from "mongodb-memory-server";
 import { Schema_Event } from "@core/types/event.types";
 import { Schema_Sync } from "@core/types/sync.types";
 import { Schema_User } from "@core/types/user.types";
+import { Schema_Waitlist } from "@core/types/waitlist/waitlist.types";
 import { Collections } from "@backend/common/constants/collections";
 import mongoService from "@backend/common/services/mongo.service";
 
@@ -11,6 +12,7 @@ export interface TestSetup {
   mongoClient: MongoClient;
   db: Db;
   userId: string;
+  email: string;
 }
 
 jest.mock("@backend/common/middleware/supertokens.middleware", () => ({
@@ -34,19 +36,24 @@ export async function setupTestDb(): Promise<TestSetup> {
   await db.createCollection(Collections.USER);
   await db.createCollection(Collections.SYNC);
   await db.createCollection(Collections.EVENT);
+  await db.createCollection(Collections.WAITLIST);
 
   // Setup mongoService mock to use our test collections
   (mongoService as any).db = db;
   (mongoService as any).user = db.collection<Schema_User>(Collections.USER);
   (mongoService as any).sync = db.collection<Schema_Sync>(Collections.SYNC);
   (mongoService as any).event = db.collection<Schema_Event>(Collections.EVENT);
+  (mongoService as any).waitlist = db.collection<Schema_Waitlist>(
+    Collections.WAITLIST,
+  );
 
   // Create test user
   const userId = new ObjectId();
+  const email = "[email protected]";
   const user: Schema_User = {
     //@ts-expect-error - overriding the _id to simulate a pre-populated collection
     _id: userId,
-    email: "[email protected]",
+    email,
     firstName: "Test",
     lastName: "User",
     name: "Test User",
@@ -83,12 +90,30 @@ export async function setupTestDb(): Promise<TestSetup> {
   };
   await mongoService.sync.insertOne(syncRecord);
 
-  return { mongoServer, mongoClient, db, userId: userId.toString() };
+  // Create waitlist user
+  await mongoService.waitlist.insertOne({
+    email,
+    waitlistedAt: new Date().toISOString(),
+    schemaVersion: "0",
+    source: "other",
+    firstName: "Test",
+    lastName: "User",
+    currentlyPayingFor: ["superhuman", "notion"],
+    howClearAboutValues: "not-clear",
+    workingTowardsMainGoal: "yes",
+    isWillingToShare: false,
+  });
+
+  return { mongoServer, mongoClient, db, userId: userId.toString(), email };
 }
 
 export async function cleanupCollections(db: Db): Promise<void> {
   const collections = await db.collections();
-  const SKIP_COLLECTIONS = [Collections.USER, Collections.SYNC];
+  const SKIP_COLLECTIONS = [
+    Collections.USER,
+    Collections.SYNC,
+    Collections.WAITLIST,
+  ];
 
   const clearPromises = collections
     .filter(

packages/backend/src/common/constants/collections.ts

@@ -7,4 +7,5 @@ export const Collections = {
   PRIORITY: IS_DEV ? "_dev.priority" : "priority",
   SYNC: IS_DEV ? "_dev.sync" : "sync",
   USER: IS_DEV ? "_dev.user" : "user",
+  WAITLIST: IS_DEV ? "_dev.waitlist" : "waitlist",
 };

packages/backend/src/common/constants/env.constants.ts

@@ -20,7 +20,7 @@ const EnvSchema = z
     CLIENT_SECRET: z.string().nonempty(),
     DB: z.string().nonempty(),
     EMAILER_SECRET: z.string().nonempty().optional(),
-    EMAILER_LIST_ID: z.string().nonempty().optional(),
+    EMAILER_TAG_ID: z.string().nonempty().optional(),
     MONGO_URI: z.string().nonempty(),
     NODE_ENV: z.nativeEnum(NodeEnv),
     ORIGINS_ALLOWED: z.array(z.string().nonempty()).default([]),
@@ -41,7 +41,7 @@ export const ENV = {
   CLIENT_SECRET: process.env["CLIENT_SECRET"],
   DB: IS_DEV ? "dev_calendar" : "prod_calendar",
   EMAILER_SECRET: process.env["EMAILER_API_SECRET"],
-  EMAILER_LIST_ID: process.env["EMAILER_LIST_ID"],
+  EMAILER_TAG_ID: process.env["EMAILER_TAG_ID"],
   MONGO_URI: process.env["MONGO_URI"],
   NODE_ENV: _nodeEnv,
   ORIGINS_ALLOWED: process.env["CORS"] ? process.env["CORS"].split(",") : [],

packages/backend/src/common/constants/error.constants.ts

@@ -1,6 +1,7 @@
+import { ErrorConstant } from "@core/errors/errors.base";
 import { Status } from "@core/errors/status.codes";
 
-export const AuthError = {
+export const AuthError: ErrorConstant = {
   DevOnly: {
     description: "Only available during development",
     status: Status.FORBIDDEN,
@@ -28,29 +29,15 @@ export const AuthError = {
   },
 };
 
-export const DbError = {
+export const DbError: ErrorConstant = {
   InvalidId: {
     description: "id is invalid (according to Mongo)",
     status: Status.BAD_REQUEST,
     isOperational: true,
   },
 };
 
-export const EmailerError = {
-  IncorrectApiKey: {
-    description:
-      "Incorrect API key. Please make sure environment variables beginning with EMAILER_ are correct",
-    status: Status.BAD_REQUEST,
-    isOperational: true,
-  },
-  AddToListFailed: {
-    description: "Failed to add email to list",
-    status: Status.UNSURE,
-    isOperational: true,
-  },
-};
-
-export const EventError = {
+export const EventError: ErrorConstant = {
   Gone: {
     description: "Resource is gone",
     status: Status.GONE,
@@ -88,7 +75,7 @@ export const EventError = {
   },
 };
 
-export const GenericError = {
+export const GenericError: ErrorConstant = {
   BadRequest: {
     description: "Request is malformed",
     status: Status.BAD_REQUEST,
@@ -111,7 +98,7 @@ export const GenericError = {
   },
 };
 
-export const GcalError = {
+export const GcalError: ErrorConstant = {
   CalendarlistMissing: {
     description: "No calendarlist",
     status: Status.BAD_REQUEST,
@@ -149,7 +136,7 @@ export const GcalError = {
   },
 };
 
-export const SocketError = {
+export const SocketError: ErrorConstant = {
   InvalidSocketId: {
     description: "Invalid socket id",
     status: Status.BAD_REQUEST,
@@ -163,7 +150,7 @@ export const SocketError = {
   },
 };
 
-export const SyncError = {
+export const SyncError: ErrorConstant = {
   AccessRevoked: {
     description: "User revoked access to their 3rd-party calendar (GCal)",
     status: Status.GONE,
@@ -201,7 +188,7 @@ export const SyncError = {
   },
 };
 
-export const UserError = {
+export const UserError: ErrorConstant = {
   InvalidValue: {
     description: "User has an invalid value",
     status: Status.BAD_REQUEST,

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

@@ -0,0 +1,28 @@
+import { Status } from "@core/errors/status.codes";
+import { ErrorMetadata } from "@backend/common/types/error.types";
+
+interface EmailerErrorMap {
+  InvalidTagId: ErrorMetadata;
+  InvalidSecret: ErrorMetadata;
+  InvalidSubscriberData: ErrorMetadata;
+}
+
+export const EmailerError: EmailerErrorMap = {
+  InvalidSubscriberData: {
+    description: "Subscriber data is missing or incorrect",
+    status: Status.BAD_REQUEST,
+    isOperational: true,
+  },
+  InvalidSecret: {
+    description:
+      "Invalid emailer API secret. Please make sure environment variables beginning with EMAILER_ are correct",
+    status: Status.INTERNAL_SERVER,
+    isOperational: true,
+  },
+  InvalidTagId: {
+    description:
+      "Invalid emailer tag id. Please make sure environment variables beginning with EMAILER_ are correct",
+    status: Status.INTERNAL_SERVER,
+    isOperational: true,
+  },
+};

packages/backend/src/common/errors/handlers/error.handler.ts

@@ -5,6 +5,12 @@ import { ErrorMetadata } from "@backend/common/types/error.types";
 
 const logger = Logger("app:error.handler");
 
+/**
+ * Transforms error metadata into a BaseError class
+ * @param cause The cause of the error
+ * @param result The result of the error
+ * @returns
+ */
 export const error = (cause: ErrorMetadata, result: string) => {
   return new BaseError(
     result,

packages/backend/src/common/services/mongo.service.ts

@@ -3,6 +3,7 @@ import { Logger } from "@core/logger/winston.logger";
 import { Schema_Event } from "@core/types/event.types";
 import { Schema_Sync } from "@core/types/sync.types";
 import { Schema_User } from "@core/types/user.types";
+import { Schema_Waitlist } from "@core/types/waitlist/waitlist.types";
 import { Collections } from "../constants/collections";
 import { ENV } from "../constants/env.constants";
 
@@ -18,6 +19,7 @@ class MongoService {
   public event!: Collection<Schema_Event>;
   public sync!: Collection<Schema_Sync>;
   public user!: Collection<Schema_User>;
+  public waitlist!: Collection<Schema_Waitlist>;
 
   constructor() {
     this._connect();
@@ -35,6 +37,9 @@ class MongoService {
         this.event = this.db.collection<Schema_Event>(Collections.EVENT);
         this.sync = this.db.collection<Schema_Sync>(Collections.SYNC);
         this.user = this.db.collection<Schema_User>(Collections.USER);
+        this.waitlist = this.db.collection<Schema_Waitlist>(
+          Collections.WAITLIST,
+        );
       })
       .catch((err) => {
         const retrySeconds = 5;
@@ -64,6 +69,7 @@ class MongoService {
       this.event = undefined as any;
       this.sync = undefined as any;
       this.user = undefined as any;
+      this.waitlist = undefined as any;
     }
 
     this.count = 0;