feat: integrate Plunk email service, add email utility functions, and update package dependencies

Author: alexmarqs

apps/web/.env.example

@@ -5,4 +5,5 @@ NEXT_PUBLIC_SUPABASE_URL=
 # Make sure to enable RLS and policies to use this key in client
 NEXT_PUBLIC_SUPABASE_ANON_KEY=
 SUPABASE_SERVICE_ROLE_KEY=
-SUPABASE_URL=
+SUPABASE_URL=
+PLUNK_API_KEY=

apps/web/package.json

@@ -18,6 +18,7 @@
   },
   "dependencies": {
     "@hookform/resolvers": "5.2.1",
+    "@plunk/node": "3.0.3",
     "@radix-ui/react-alert-dialog": "1.1.15",
     "@radix-ui/react-avatar": "1.1.10",
     "@radix-ui/react-collapsible": "1.1.11",
@@ -28,6 +29,7 @@
     "@radix-ui/react-slot": "1.2.3",
     "@radix-ui/react-tabs": "1.1.12",
     "@react-email/components": "0.5.1",
+    "@react-email/render": "1.3.1",
     "@supabase/ssr": "0.6.1",
     "@supabase/supabase-js": "2.52.0",
     "@tanstack/react-query": "5.84.1",

apps/web/src/lib/email/client.ts

@@ -0,0 +1,23 @@
+import Plunk from "@plunk/node";
+
+let client: Plunk | undefined;
+
+const createClient = () => {
+  const apiKey = process.env.PLUNK_API_KEY;
+
+  if (!apiKey) {
+    throw new Error(
+      "Missing PLUNK_API_KEY environment variable. Set it to use the email service.",
+    );
+  }
+
+  return new Plunk(apiKey);
+};
+
+export const getPlunkClient = () => {
+  if (!client) {
+    client = createClient();
+  }
+
+  return client;
+};

apps/web/src/lib/email/index.ts

@@ -0,0 +1,34 @@
+import { getPlunkClient } from "./client";
+import type { EmailService } from "./types";
+import { DEFAULT_EMAIL_FROM, normalizeRecipients } from "./utils";
+
+const sendEmail: EmailService["sendEmail"] = async (payload) => {
+  const {
+    body,
+    from = DEFAULT_EMAIL_FROM,
+    name,
+    subscribed,
+    subject,
+    to,
+  } = payload;
+
+  const recipients = normalizeRecipients(to);
+
+  try {
+    await getPlunkClient().emails.send({
+      body,
+      from,
+      name,
+      subscribed,
+      subject,
+      to: recipients,
+    });
+  } catch (error) {
+    console.error("Failed to send email", error);
+    throw error instanceof Error ? error : new Error("Unknown email error");
+  }
+};
+
+export const emailService: EmailService = {
+  sendEmail,
+};

apps/web/src/lib/email/types.ts

@@ -0,0 +1,13 @@
+export type EmailServiceParams = {
+  to: string | string[];
+  subject: string;
+  body: string;
+  type?: "html" | "markdown";
+  from?: string;
+  name?: string;
+  subscribed?: boolean;
+};
+
+export type EmailService = {
+  sendEmail: (payload: EmailServiceParams) => Promise<void>;
+};

apps/web/src/lib/email/utils.ts

@@ -0,0 +1,33 @@
+import type { EmailServiceParams } from "./types";
+
+const EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const DEFAULT_EMAIL_FROM =
+  process.env.PLUNK_FROM_EMAIL ??
+  "Tech Companies Portugal <[email protected]>";
+const DEFAULT_EMAIL_TYPE: EmailServiceParams["type"] = "html";
+
+const normalizeRecipients = (to: EmailServiceParams["to"]): string[] => {
+  const recipients = Array.isArray(to) ? to : [to];
+
+  if (!recipients.length) {
+    throw new Error("Invalid 'to' field: provide at least one email address.");
+  }
+
+  return recipients.map((recipient) => {
+    const sanitized = recipient.trim();
+
+    if (!sanitized) {
+      throw new Error(
+        "Invalid 'to' field: recipients must be non-empty strings.",
+      );
+    }
+
+    if (!EMAIL_PATTERN.test(sanitized)) {
+      throw new Error(`Invalid email address: ${sanitized}`);
+    }
+
+    return sanitized;
+  });
+};
+
+export { normalizeRecipients, DEFAULT_EMAIL_FROM, DEFAULT_EMAIL_TYPE };