feat(email): make verify-email org-aware like other transactional mail

Resolve the tenant org from the verification link callback URL (custom
domain, tenant subdomain, or ?org=) and apply org logo, theme color, from
name, and subject. Falls back to ClassroomIO branding on the main app.

Co-authored-by: Rotimi Best <[email protected]>

packages/db/src/auth/email-verification.ts

@@ -1,5 +1,7 @@
 import { type BetterAuthOptions } from 'better-auth';
-import { sendEmail } from '@cio/email';
+import { buildEmailBranding, buildEmailFromName, sendEmail } from '@cio/email';
+
+import { resolveVerificationOrg } from './resolve-verification-org';
 
 type EmailVerificationOptions = Parameters<
   NonNullable<NonNullable<BetterAuthOptions['emailVerification']>['sendVerificationEmail']>
@@ -9,17 +11,38 @@ type ChangeEmailConfirmationOptions = Parameters<
   NonNullable<NonNullable<NonNullable<BetterAuthOptions['user']>['changeEmail']>['sendChangeEmailConfirmation']>
 >[0];
 
-/**
- * Email verification flow.
- *
- * 1. user says I want to change my email from [email protected] to [email protected]
- * 2. we send an email to [email protected] asking user to verify if they really want to change their email to [email protected] `sendChangeEmailConfirmation()`. [better-auth].
- * 3. user clicks the link in the email
- * 4. we update the email in the database. [better-auth].
- * 5. we send a confirmation email to [email protected] `sendVerificationEmail()`. [dashboard].
- * 6. user clicks the link in the email
- * 7. we mark [email protected] as verified. [better-auth].
- */
+function stripTriggerParam(url: string): string {
+  return url.replace('trigger=app', '').replace('trigger%3Dapp', '');
+}
+
+async function sendOrgAwareVerifyEmail(options: {
+  to: string;
+  verificationUrl: string;
+  userId: string;
+  userName?: string | null;
+  newEmail?: string;
+}) {
+  const org = await resolveVerificationOrg({
+    verificationUrl: options.verificationUrl,
+    userId: options.userId
+  });
+
+  const orgName = org?.name?.trim() || 'ClassroomIO';
+  const branding = buildEmailBranding(org ? { name: org.name, avatarUrl: org.avatarUrl, theme: org.theme } : undefined);
+
+  await sendEmail('verifyEmail', {
+    to: options.to,
+    from: org?.name ? buildEmailFromName(`${org.name} (via ClassroomIO.com)`) : undefined,
+    subject: org?.name ? `Confirm your email for ${org.name}` : undefined,
+    fields: {
+      link: stripTriggerParam(options.verificationUrl),
+      newEmail: options.newEmail,
+      userName: options.userName || undefined,
+      orgName,
+      branding
+    }
+  });
+}
 
 /**
  * Sends a verification email to the user when they sign up or change their email address.
@@ -35,15 +58,11 @@ export const sendVerificationEmail = async (options: EmailVerificationOptions) =
     return;
   }
 
-  // Remove trigger=app or trigger%3Dapp from the URL
-  const link = url.replace('trigger=app', '').replace('trigger%3Dapp', '');
-
-  await sendEmail('verifyEmail', {
+  await sendOrgAwareVerifyEmail({
     to: user.email,
-    fields: {
-      link,
-      userName: user.name || undefined
-    }
+    verificationUrl: url,
+    userId: user.id,
+    userName: user.name
   });
 };
 
@@ -56,12 +75,11 @@ export const sendChangeEmailConfirmation = async (options: ChangeEmailConfirmati
   const { user, newEmail, url } = options;
   console.log('\nsendChangeEmailConfirmation', options);
 
-  await sendEmail('verifyEmail', {
+  await sendOrgAwareVerifyEmail({
     to: user.email,
-    fields: {
-      link: url,
-      newEmail,
-      userName: user.name || undefined
-    }
+    verificationUrl: url,
+    userId: user.id,
+    userName: user.name,
+    newEmail
   });
 };

packages/db/src/auth/resolve-verification-org.ts

@@ -0,0 +1,123 @@
+import { TENANT_ROOT_DOMAIN, BRAND_ROOT_DOMAIN } from '@cio/utils/constants/domains';
+
+import type { TOrganization } from '../types';
+import {
+  getFirstOrganization,
+  getOrganizationByCustomDomain,
+  getOrganizationByProfileId,
+  getOrganizationBySiteName
+} from '../queries/organization/organization';
+
+function extractCallbackUrl(verificationUrl: string): URL | null {
+  try {
+    const parsed = new URL(verificationUrl);
+    const callback = parsed.searchParams.get('callbackURL');
+    if (!callback) {
+      return null;
+    }
+
+    return new URL(callback);
+  } catch {
+    return null;
+  }
+}
+
+function isTenantSubdomainHost(hostname: string): boolean {
+  const host = hostname.replace(/^www\./, '').toLowerCase();
+  const suffix = `.${TENANT_ROOT_DOMAIN}`;
+
+  return host.endsWith(suffix) && host.length > suffix.length;
+}
+
+function getTenantSiteName(hostname: string): string | null {
+  const host = hostname.replace(/^www\./, '').toLowerCase();
+  const suffix = `.${TENANT_ROOT_DOMAIN}`;
+  if (!host.endsWith(suffix)) {
+    return null;
+  }
+
+  const siteName = host.slice(0, -suffix.length);
+  if (!siteName || siteName.includes('.')) {
+    return null;
+  }
+
+  return siteName;
+}
+
+function isCustomDomainHost(hostname: string): boolean {
+  const host = hostname.replace(/^www\./, '').toLowerCase();
+  if (host.includes('localhost')) {
+    return false;
+  }
+
+  if (host === BRAND_ROOT_DOMAIN || host === `app.${BRAND_ROOT_DOMAIN}`) {
+    return false;
+  }
+
+  if (isTenantSubdomainHost(host)) {
+    return false;
+  }
+
+  return !host.endsWith(`.${BRAND_ROOT_DOMAIN}`);
+}
+
+async function resolveOrgFromCallbackUrl(callbackUrl: URL): Promise<TOrganization | null> {
+  const orgSiteName = callbackUrl.searchParams.get('org')?.trim();
+  if (orgSiteName) {
+    const org = await getOrganizationBySiteName(orgSiteName);
+    if (org) {
+      return org;
+    }
+  }
+
+  const hostname = callbackUrl.hostname.toLowerCase();
+
+  if (isCustomDomainHost(hostname)) {
+    const org = await getOrganizationByCustomDomain(hostname);
+    if (org) {
+      return org;
+    }
+  }
+
+  const siteName = getTenantSiteName(hostname);
+  if (siteName) {
+    return getOrganizationBySiteName(siteName);
+  }
+
+  return null;
+}
+
+/**
+ * Resolves the tenant org that should brand a verification email from the
+ * Better Auth verification URL's `callbackURL` (where the user started the
+ * flow), with fallbacks for self-hosted and existing memberships.
+ */
+export async function resolveVerificationOrg(options: {
+  verificationUrl: string;
+  userId?: string;
+}): Promise<TOrganization | null> {
+  const callbackUrl = extractCallbackUrl(options.verificationUrl);
+  if (callbackUrl) {
+    const org = await resolveOrgFromCallbackUrl(callbackUrl);
+    if (org) {
+      return org;
+    }
+  }
+
+  if (process.env.PUBLIC_IS_SELFHOSTED === 'true') {
+    const org = await getFirstOrganization();
+    if (org) {
+      return org;
+    }
+  }
+
+  if (options.userId) {
+    const memberships = await getOrganizationByProfileId(options.userId);
+    const org = memberships[0];
+    if (org) {
+      return org;
+    }
+  }
+
+  return null;
+}