feat(api): welcome email on fresh OAuth signup (closes #43)

Third method on the Notifier interface — notifyWelcomeOnSignup — wired
into the github-oauth.ts create-fresh outcome. Fires fire-and-forget
so the OAuth redirect latency is unaffected; the notifier's own
error-handling translates Resend failures to delivered:false without
throwing.

Template body: warm 2-3 sentence intro pointing at the user's profile,
projects directory, help-wanted board, and #welcome Slack channel.
Plain-text + HTML alternatives, fullName HTML-escaped, slug
URL-encoded.

EmailNotifier.notifyWelcomeOnSignup mirrors the existing two methods —
same Resend response-shape branching, same delivered:false on missing
email / SDK throw / Resend-reported error.

Wiring is hidden behind the existing LoggingNotifier → EmailNotifier
fallback in the services plugin. When RESEND_API_KEY is unset (sandbox
today), welcomes log to pod stdout; once sealed, real emails go out.

Tests: 7 new in email-notifier.test.ts (template renderer + 4
notifier paths), 1 new in github-oauth.test.ts (spy assertion that
the create-fresh path fires the notifier with the right payload).
310/310 API tests pass.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: themightychris

apps/api/src/auth/github-oauth.ts

@@ -169,6 +169,21 @@ export async function completeCallback(
     );
     result.value.stateApply.apply(fastify.inMemoryState, fastify.fts);
 
+    // Fire-and-forget the welcome notification — never block the OAuth
+    // redirect on notifier latency or failures. The notifier already
+    // swallows errors internally and returns `{ delivered: false }`; the
+    // outer .catch handles any unforeseen sync-throw before the SDK is
+    // reached. See plans/welcome-notification.md.
+    void fastify.notifier
+      .notifyWelcomeOnSignup({
+        email: result.value.profile.email,
+        fullName: result.value.person.fullName,
+        slug: result.value.person.slug,
+      })
+      .catch((err) => {
+        fastify.log.error({ err }, 'welcome notification threw (fire-and-forget)');
+      });
+
     const minted = await mintSessionFor(
       result.value.person.id,
       result.value.person.accountLevel,

apps/api/src/notify/email-notifier.ts

@@ -18,8 +18,9 @@ import type {
   HelpWantedFillNotification,
   HelpWantedInterestNotification,
   Notifier,
+  WelcomeNotification,
 } from './index.js';
-import { renderFilledEmail, renderInterestEmail } from './templates.js';
+import { renderFilledEmail, renderInterestEmail, renderWelcomeEmail } from './templates.js';
 
 export interface EmailNotifierOptions {
   /** Resend client (constructed at boot with the API key from env). */
@@ -100,6 +101,44 @@ export class EmailNotifier implements Notifier {
     }
   }
 
+  async notifyWelcomeOnSignup(n: WelcomeNotification): Promise<{ delivered: boolean }> {
+    if (!n.email) {
+      this.#log.warn(
+        { kind: 'auth.welcome', slug: n.slug },
+        'welcome: no email address; skipped',
+      );
+      return { delivered: false };
+    }
+    const tpl = renderWelcomeEmail(n, this.#siteHost);
+    try {
+      const result = await this.#resend.emails.send({
+        from: this.#from,
+        to: n.email,
+        subject: tpl.subject,
+        text: tpl.text,
+        html: tpl.html,
+      });
+      if (result.error) {
+        this.#log.error(
+          { kind: 'auth.welcome', err: result.error, slug: n.slug },
+          'welcome: Resend reported delivery failure',
+        );
+        return { delivered: false };
+      }
+      this.#log.info(
+        { kind: 'auth.welcome', slug: n.slug, resendId: result.data?.id },
+        'welcome: email queued for delivery',
+      );
+      return { delivered: true };
+    } catch (err) {
+      this.#log.error(
+        { kind: 'auth.welcome', err, slug: n.slug },
+        'welcome: email send threw',
+      );
+      return { delivered: false };
+    }
+  }
+
   async notifyHelpWantedFilled(
     n: HelpWantedFillNotification,
   ): Promise<{ delivered: boolean }> {

apps/api/src/notify/index.ts

@@ -30,9 +30,22 @@ export interface HelpWantedFillNotification {
   readonly filledBySlug: string | null;
 }
 
+/**
+ * Welcome notification — fires once per Person on the GitHub OAuth
+ * `create-fresh` outcome (a brand-new signup with no laddr-account-claim
+ * candidates). The email comes from the new PrivateProfile; fullName and
+ * slug from the public Person record.
+ */
+export interface WelcomeNotification {
+  readonly email: string;
+  readonly fullName: string;
+  readonly slug: string;
+}
+
 export interface Notifier {
   notifyHelpWantedInterest(n: HelpWantedInterestNotification): Promise<{ delivered: boolean }>;
   notifyHelpWantedFilled(n: HelpWantedFillNotification): Promise<{ delivered: boolean }>;
+  notifyWelcomeOnSignup(n: WelcomeNotification): Promise<{ delivered: boolean }>;
 }
 
 /**
@@ -55,4 +68,9 @@ export class LoggingNotifier implements Notifier {
     this.#log.info({ kind: 'help-wanted.filled', ...n }, 'help-wanted fill notification');
     return { delivered: true };
   }
+
+  async notifyWelcomeOnSignup(n: WelcomeNotification): Promise<{ delivered: boolean }> {
+    this.#log.info({ kind: 'auth.welcome', ...n }, 'welcome notification');
+    return { delivered: true };
+  }
 }

apps/api/src/notify/templates.ts

@@ -6,7 +6,11 @@
  * overhead than the strings themselves. URLs are absolute (resolved
  * against the configured siteHost) so links work from email clients.
  */
-import type { HelpWantedFillNotification, HelpWantedInterestNotification } from './index.js';
+import type {
+  HelpWantedFillNotification,
+  HelpWantedInterestNotification,
+  WelcomeNotification,
+} from './index.js';
 
 /** Strip an absolute URL down to scheme + host + path. Useful for log lines. */
 export function buildRoleUrl(siteHost: string, projectSlug: string, roleId: string): string {
@@ -85,6 +89,59 @@ export interface FilledTemplate {
   readonly html: string;
 }
 
+export interface WelcomeTemplate {
+  readonly subject: string;
+  readonly text: string;
+  readonly html: string;
+}
+
+export function renderWelcomeEmail(
+  n: WelcomeNotification,
+  siteHost: string,
+): WelcomeTemplate {
+  const profileUrl = `https://${siteHost}/members/${encodeURIComponent(n.slug)}`;
+  const projectsUrl = `https://${siteHost}/projects`;
+  const helpWantedUrl = `https://${siteHost}/help-wanted`;
+  const subject = `Welcome to Code for Philly, ${n.fullName}`;
+
+  const text = [
+    `Hey ${n.fullName} — welcome to Code for Philly!`,
+    '',
+    `You're signed in. A few places to start:`,
+    `  - Your profile: ${profileUrl}`,
+    `  - Browse projects: ${projectsUrl}`,
+    `  - Help wanted: ${helpWantedUrl}`,
+    '',
+    `Code for Philly's community lives in Slack — most coordination happens there.`,
+    `Drop into #welcome to introduce yourself.`,
+    '',
+    `— Code for Philly`,
+  ].join('\n');
+
+  const html = `<!DOCTYPE html>
+<html lang="en">
+<body style="font-family: system-ui, sans-serif; max-width: 32rem; margin: 0 auto; padding: 1rem; color: #111;">
+  <p>Hey <strong>${escapeHtml(n.fullName)}</strong> — welcome to Code for Philly!</p>
+  <p>You're signed in. A few places to start:</p>
+  <ul>
+    <li><a href="${profileUrl}">Your profile</a></li>
+    <li><a href="${projectsUrl}">Browse projects</a></li>
+    <li><a href="${helpWantedUrl}">Help wanted</a></li>
+  </ul>
+  <p>
+    Code for Philly's community lives in Slack — most coordination happens there.
+    Drop into #welcome to introduce yourself.
+  </p>
+  <hr style="border: none; border-top: 1px solid #eee; margin: 2rem 0;">
+  <p style="color: #666; font-size: 0.875rem;">
+    You're receiving this because you just signed in to Code for Philly with GitHub.
+  </p>
+</body>
+</html>`;
+
+  return { subject, text, html };
+}
+
 export function renderFilledEmail(
   n: HelpWantedFillNotification,
   siteHost: string,

apps/api/tests/email-notifier.test.ts

@@ -11,10 +11,15 @@
  */
 import { describe, expect, it, vi } from 'vitest';
 import { EmailNotifier } from '../src/notify/email-notifier.js';
-import { renderFilledEmail, renderInterestEmail } from '../src/notify/templates.js';
+import {
+  renderFilledEmail,
+  renderInterestEmail,
+  renderWelcomeEmail,
+} from '../src/notify/templates.js';
 import type {
   HelpWantedFillNotification,
   HelpWantedInterestNotification,
+  WelcomeNotification,
 } from '../src/notify/index.js';
 
 const noopLogger = {
@@ -51,6 +56,12 @@ const baseFill: HelpWantedFillNotification = {
   filledBySlug: 'jane-doe',
 };
 
+const baseWelcome: WelcomeNotification = {
+  email: 'new-user@example.com',
+  fullName: 'New User',
+  slug: 'new-user',
+};
+
 function makeNotifier(emails: { send: ReturnType<typeof vi.fn> }): EmailNotifier {
   return new EmailNotifier({
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -155,6 +166,76 @@ describe('EmailNotifier.notifyHelpWantedInterest', () => {
   });
 });
 
+describe('renderWelcomeEmail', () => {
+  it('builds subject + text + html with the user fullName + slug', () => {
+    const tpl = renderWelcomeEmail(baseWelcome, 'codeforphilly.org');
+    expect(tpl.subject).toContain('New User');
+    expect(tpl.text).toContain('Hey New User');
+    expect(tpl.text).toContain('https://codeforphilly.org/members/new-user');
+    expect(tpl.text).toContain('https://codeforphilly.org/projects');
+    expect(tpl.html).toContain('<strong>New User</strong>');
+    expect(tpl.html).toContain('href="https://codeforphilly.org/members/new-user"');
+  });
+
+  it('escapes HTML in fullName', () => {
+    const tpl = renderWelcomeEmail(
+      { ...baseWelcome, fullName: '<script>alert(1)</script>' },
+      'codeforphilly.org',
+    );
+    expect(tpl.html).not.toContain('<script>');
+    expect(tpl.html).toContain('&lt;script&gt;');
+  });
+
+  it('URL-encodes the slug for the profile link', () => {
+    const tpl = renderWelcomeEmail(
+      { ...baseWelcome, slug: 'name with spaces' },
+      'codeforphilly.org',
+    );
+    expect(tpl.html).toContain('href="https://codeforphilly.org/members/name%20with%20spaces"');
+  });
+});
+
+describe('EmailNotifier.notifyWelcomeOnSignup', () => {
+  it('sends via Resend and returns delivered:true', async () => {
+    const send = vi.fn().mockResolvedValue({ data: { id: 'msg-welcome' }, error: null });
+    const notifier = makeNotifier({ send });
+
+    const result = await notifier.notifyWelcomeOnSignup(baseWelcome);
+    expect(result).toEqual({ delivered: true });
+    expect(send).toHaveBeenCalledTimes(1);
+    const arg = send.mock.calls[0]![0]!;
+    expect(arg.to).toBe('new-user@example.com');
+    expect(arg.subject).toContain('Welcome');
+    expect(arg.text).toContain('New User');
+    expect(arg.html).toContain('<strong>New User</strong>');
+  });
+
+  it('returns delivered:false when Resend reports an error', async () => {
+    const send = vi.fn().mockResolvedValue({
+      data: null,
+      error: { message: 'Sender domain unverified' },
+    });
+    const notifier = makeNotifier({ send });
+    const result = await notifier.notifyWelcomeOnSignup(baseWelcome);
+    expect(result).toEqual({ delivered: false });
+  });
+
+  it('returns delivered:false when the SDK throws', async () => {
+    const send = vi.fn().mockRejectedValue(new Error('network blip'));
+    const notifier = makeNotifier({ send });
+    const result = await notifier.notifyWelcomeOnSignup(baseWelcome);
+    expect(result).toEqual({ delivered: false });
+  });
+
+  it('returns delivered:false on empty email (defensive)', async () => {
+    const send = vi.fn();
+    const notifier = makeNotifier({ send });
+    const result = await notifier.notifyWelcomeOnSignup({ ...baseWelcome, email: '' });
+    expect(result).toEqual({ delivered: false });
+    expect(send).not.toHaveBeenCalled();
+  });
+});
+
 describe('EmailNotifier.notifyHelpWantedFilled', () => {
   it('sends via Resend and returns delivered:true', async () => {
     const send = vi.fn().mockResolvedValue({ data: { id: 'msg-456' }, error: null });

apps/api/tests/github-oauth.test.ts

@@ -15,7 +15,7 @@
  * Each test uses a unique remoteAddress so the 10-req/min/IP cap on
  * /api/auth/* doesn't cause one test's setup to fail another test's run.
  */
-import { afterAll, afterEach, beforeAll, describe, expect, it } from 'vitest';
+import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from 'vitest';
 import { type FastifyInstance } from 'fastify';
 import { writeFile, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
@@ -514,6 +514,45 @@ describe('GET /api/auth/github/callback — fresh user outcome', () => {
     const claims = await verifyAccess(accessValue, JWT_KEY);
     expect(claims.sub).toBe(person!.id);
   });
+
+  it('fires the welcome notification with the new person + email', async () => {
+    const ip = nextTestIp();
+    const flow = await startFlow(app, '/', ip);
+
+    // Spy on the boot-installed LoggingNotifier (no Resend in tests).
+    // The notifier call is fire-and-forget — we await the OAuth response
+    // first, then assert the spy. The notifier's spawn is synchronous up
+    // to the await inside it, so it's guaranteed to have been called by
+    // the time the route handler returns.
+    mock.setGitHubUser({
+      id: 88888,
+      login: 'welcome-target',
+      name: 'Welcome Target',
+      avatar_url: 'x',
+    });
+    mock.setGitHubEmails([
+      { email: 'welcome-target@example.com', primary: true, verified: true, visibility: 'public' },
+    ]);
+
+    const spy = vi.spyOn(app.notifier, 'notifyWelcomeOnSignup');
+
+    const res = await app.inject({
+      method: 'GET',
+      url: `/api/auth/github/callback?code=abc&state=${encodeURIComponent(flow.state)}`,
+      remoteAddress: ip,
+      cookies: {
+        cfp_oauth_state: flow.stateCookie,
+        cfp_oauth_session: flow.oauthSessionCookie,
+      },
+    });
+    expect(res.statusCode).toBe(302);
+    expect(spy).toHaveBeenCalledWith({
+      email: 'welcome-target@example.com',
+      fullName: 'Welcome Target',
+      slug: 'welcome-target',
+    });
+    spy.mockRestore();
+  });
 });
 
 describe('GET /api/auth/github/callback — candidates outcome', () => {