From fd2c26f024debc4e0e92a836d0857b0ff9137852 Mon Sep 17 00:00:00 2001 From: Eric Fennis Date: Tue, 17 Nov 2026 14:52:12 +0100 Subject: [PATCH] feat(docs|site): Add MCP waitlist page (#5249) * First iteration * Adjust waitlist * Adjust page * Add background * minor adjustments * Adjust hero styling * Add api backend * Adjust backend * Extract base URL * fix final things * Final touch * Format code * update lockfile --- docs/.vitepress/api/waitlist/confirm.get.ts | 74 +++ docs/.vitepress/api/waitlist/index.post.ts | 77 +++ docs/.vitepress/config.ts | 10 + .../lib/waitlist/ConfirmationEmail.tsx | 96 +++ docs/.vitepress/lib/waitlist/resend.ts | 133 +++++ docs/.vitepress/lib/waitlist/token.ts | 100 ++++ docs/.vitepress/middleware/cors.ts | 16 + .../theme/components/waitlist/McpDiagram.vue | 386 ++++++++++++ .../components/waitlist/WaitlistConfirmed.vue | 122 ++++ .../components/waitlist/WaitlistForm.vue | 198 ++++++ .../components/waitlist/WaitlistHero.vue | 145 +++++ .../components/waitlist/WaitlistSurvey.vue | 69 +++ .../theme/components/waitlist/products.ts | 38 ++ .../theme/components/waitlist/waitlist.css | 97 +++ .../theme/composables/useFetchCategories.ts | 12 +- .../theme/composables/useFetchTags.ts | 12 +- docs/.vitepress/theme/index.ts | 6 + docs/.vitepress/theme/style.css | 35 ++ docs/.vitepress/theme/utils/getBaseUrl.ts | 5 + docs/.vitepress/theme/utils/openpanel.ts | 16 +- docs/.vitepress/types.d.ts | 1 + docs/mcp.md | 16 + docs/package.json | 3 + docs/privacy.md | 14 +- docs/vercel.json | 19 + docs/waitlist/confirmed.md | 15 + pnpm-lock.yaml | 562 ++++++++++++++++-- 27 files changed, 2210 insertions(+), 67 deletions(-) create mode 100644 docs/.vitepress/api/waitlist/confirm.get.ts create mode 100644 docs/.vitepress/api/waitlist/index.post.ts create mode 100644 docs/.vitepress/lib/waitlist/ConfirmationEmail.tsx create mode 100644 docs/.vitepress/lib/waitlist/resend.ts create mode 100644 docs/.vitepress/lib/waitlist/token.ts create mode 100644 docs/.vitepress/middleware/cors.ts create mode 100644 docs/.vitepress/theme/components/waitlist/McpDiagram.vue create mode 100644 docs/.vitepress/theme/components/waitlist/WaitlistConfirmed.vue create mode 100644 docs/.vitepress/theme/components/waitlist/WaitlistForm.vue create mode 100644 docs/.vitepress/theme/components/waitlist/WaitlistHero.vue create mode 100644 docs/.vitepress/theme/components/waitlist/WaitlistSurvey.vue create mode 100644 docs/.vitepress/theme/components/waitlist/products.ts create mode 100644 docs/.vitepress/theme/components/waitlist/waitlist.css create mode 100644 docs/.vitepress/theme/utils/getBaseUrl.ts create mode 100644 docs/mcp.md create mode 100644 docs/waitlist/confirmed.md diff --git a/docs/.vitepress/api/waitlist/confirm.get.ts b/docs/.vitepress/api/waitlist/confirm.get.ts new file mode 100644 index 000000000..6e8be4b0e --- /dev/null +++ b/docs/.vitepress/api/waitlist/confirm.get.ts @@ -0,0 +1,74 @@ +import { defineEventHandler, getQuery, sendRedirect } from 'h3'; +import { waitlistProducts } from '../../theme/components/waitlist/products'; +import { + verifyConfirmToken, + type VerifyResult, + type WaitlistSignup, +} from '../../lib/waitlist/token.ts'; +import { addToWaitlist } from '../../lib/waitlist/resend.ts'; + +const CONFIRMED_PAGE = '/waitlist/confirmed'; + +function confirmedPageUrl( + product: string | undefined, + status?: 'invalid' | 'error', + confirmed?: { signup: WaitlistSignup; contactId: string }, +) { + const params = new URLSearchParams(); + + if (product && Object.hasOwn(waitlistProducts, product)) { + params.set('product', product); + } + + if (status) { + params.set('status', status); + } + + // Hidden fields for the survey. The Resend contact ID links a submission to the contact + // without putting the email address in the URL. + if (confirmed) { + params.set('contactId', confirmed.contactId); + if (confirmed.signup.useCase) params.set('use-case', confirmed.signup.useCase); + } + + const query = params.toString(); + return query ? `${CONFIRMED_PAGE}?${query}` : CONFIRMED_PAGE; +} + +/** + * GET /api/waitlist/confirm?token=… + * + * The link from the confirmation email. Verifies the signed token, creates the Resend contact + * in the Waitlist segment, then redirects to the confirmed page. The page shows the thank-you + * survey when only `product` is set, and the expired state when `status` is set. + */ +export default defineEventHandler(async (event) => { + const { token } = getQuery(event); + const result: VerifyResult = + typeof token === 'string' ? verifyConfirmToken(token) : { valid: false }; + + // `in` narrows the union even without `strictNullChecks`, unlike checking `result.valid`. + if (!('signup' in result)) { + return sendRedirect(event, confirmedPageUrl(result.product, 'invalid'), 302); + } + + const { signup } = result; + + if (!Object.hasOwn(waitlistProducts, signup.product)) { + return sendRedirect(event, confirmedPageUrl(undefined, 'invalid'), 302); + } + + let contactId: string; + try { + contactId = await addToWaitlist(signup); + } catch (error) { + console.error('[waitlist] Could not add the contact to the waitlist', error); + return sendRedirect(event, confirmedPageUrl(signup.product, 'error'), 302); + } + + return sendRedirect( + event, + confirmedPageUrl(signup.product, undefined, { signup, contactId }), + 302, + ); +}); diff --git a/docs/.vitepress/api/waitlist/index.post.ts b/docs/.vitepress/api/waitlist/index.post.ts new file mode 100644 index 000000000..91c495e9a --- /dev/null +++ b/docs/.vitepress/api/waitlist/index.post.ts @@ -0,0 +1,77 @@ +import { createError, defineEventHandler, getRequestURL, readBody } from 'h3'; +import { checkBotId } from 'botid/server'; +import { waitlistProducts } from '../../theme/components/waitlist/products'; +import { createConfirmToken } from '../../lib/waitlist/token.ts'; +import { sendConfirmationEmail } from '../../lib/waitlist/resend.ts'; + +const MAX_EMAIL_LENGTH = 254; +const MAX_USE_CASE_LENGTH = 200; +const MAX_SOURCE_LENGTH = 100; +// Deliberately loose: the confirmation email is the real check. +const EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/; + +function asTrimmedString(value: unknown, maxLength: number) { + return typeof value === 'string' ? value.trim().slice(0, maxLength) : ''; +} + +/** + * POST /api/waitlist + * + * Runs the spam checks and sends a confirmation email with a signed link. Nothing is stored yet: + * the contact is only created in Resend once the link is clicked (see `confirm.get.ts`). + */ +export default defineEventHandler(async (event) => { + const body = await readBody | undefined>(event).catch(() => undefined); + + if (!body || typeof body !== 'object') { + throw createError({ statusCode: 400, statusMessage: 'Invalid request body' }); + } + + // Honeypot: people never see this field. Answer as if it worked, so bots learn nothing. + if (typeof body.website === 'string' && body.website !== '') { + return { ok: true }; + } + + const verification = await checkBotId({ + advancedOptions: { headers: event.node.req.headers }, + }); + + if (verification.isBot) { + throw createError({ statusCode: 403, statusMessage: 'Access denied' }); + } + + const email = asTrimmedString(body.email, MAX_EMAIL_LENGTH + 1).toLowerCase(); + const product = typeof body.product === 'string' ? body.product : ''; + + if (email.length > MAX_EMAIL_LENGTH || !EMAIL_PATTERN.test(email)) { + throw createError({ statusCode: 400, statusMessage: 'Invalid email address' }); + } + + if (!Object.hasOwn(waitlistProducts, product)) { + throw createError({ statusCode: 400, statusMessage: 'Unknown product' }); + } + + const token = createConfirmToken({ + email, + product, + useCase: asTrimmedString(body.use_case, MAX_USE_CASE_LENGTH), + source: asTrimmedString(body.source, MAX_SOURCE_LENGTH), + signedUpAt: new Date().toISOString(), + }); + + const confirmUrl = new URL('/api/waitlist/confirm', getRequestURL(event).origin); + confirmUrl.searchParams.set('token', token); + + try { + await sendConfirmationEmail({ + email, + productName: waitlistProducts[product].name, + confirmUrl: confirmUrl.href, + }); + } catch (error) { + console.error('[waitlist] Could not send the confirmation email', error); + throw createError({ statusCode: 502, statusMessage: 'Could not send the confirmation email' }); + } + + return { ok: true }; +}); diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 8adfc47e8..6ab869aed 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -48,6 +48,12 @@ export default defineConfig({ }, }, vite: { + server: { + // The waitlist forms POST same-origin, and the API dev server has CORS turned off. + proxy: { + '/api/waitlist': 'http://localhost:3000', + }, + }, resolve: { alias: [ { @@ -89,6 +95,8 @@ export default defineConfig({ 'packages.md', 'showcase.md', 'sponsor.md', + 'mcp.md', + 'waitlist/confirmed.md', 'brand-logo-statement.md', 'icons/**', // Not working, need investigation ], @@ -118,6 +126,7 @@ export default defineConfig({ }, { text: 'Packages', link: '/packages' }, { text: 'Showcase', link: '/showcase' }, + { text: 'MCP SOON', link: '/mcp' }, { text: 'Merch', link: 'https://merch.lucide.dev/' }, ], sidebar, @@ -150,5 +159,6 @@ export default defineConfig({ }, sitemap: { hostname: 'https://lucide.dev/', + transformItems: (items) => items.filter(({ url }) => !url.startsWith('waitlist/')), }, }); diff --git a/docs/.vitepress/lib/waitlist/ConfirmationEmail.tsx b/docs/.vitepress/lib/waitlist/ConfirmationEmail.tsx new file mode 100644 index 000000000..4be4a605b --- /dev/null +++ b/docs/.vitepress/lib/waitlist/ConfirmationEmail.tsx @@ -0,0 +1,96 @@ +import React from 'react'; +import { + Body, + Button, + Container, + Head, + Heading, + Hr, + Html, + Link, + Preview, + Text, +} from '@react-email/components'; + +interface ConfirmationEmailProps { + productName: string; + confirmUrl: string; +} + +const colors = { + text: '#1f2328', + muted: '#59636e', + border: '#e5e7eb', + accent: '#f56565', +}; + +const styles = { + body: { + margin: 0, + padding: '32px 0', + backgroundColor: '#ffffff', + fontFamily: + '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif', + color: colors.text, + }, + container: { maxWidth: '480px', margin: '0 auto', padding: '0 24px' }, + heading: { fontSize: '22px', lineHeight: '30px', fontWeight: 600, margin: '0 0 16px' }, + text: { fontSize: '15px', lineHeight: '24px', margin: '0 0 16px' }, + button: { + display: 'inline-block', + padding: '12px 20px', + borderRadius: '8px', + backgroundColor: colors.accent, + color: '#ffffff', + fontSize: '15px', + fontWeight: 600, + textDecoration: 'none', + }, + link: { color: colors.muted, wordBreak: 'break-all' as const }, + hr: { borderColor: colors.border, margin: '32px 0 16px' }, + footer: { fontSize: '12px', lineHeight: '18px', color: colors.muted, margin: 0 }, +}; + +export default function ConfirmationEmail({ productName, confirmUrl }: ConfirmationEmailProps) { + return ( + + + Confirm your email to join the {productName} waitlist. + + + Confirm your spot on the waitlist + + Thanks for your interest in {productName}. Click the button below to confirm your email, + and we'll send you launch updates for {productName} only. + + + + Or paste this link into your browser:{' '} + + {confirmUrl} + + +
+ + The link expires in 7 days. If you didn't sign up, ignore this email and you won't hear + from us again.{' '} + + Privacy statement + + +
+ + + ); +} diff --git a/docs/.vitepress/lib/waitlist/resend.ts b/docs/.vitepress/lib/waitlist/resend.ts new file mode 100644 index 000000000..abe4cc888 --- /dev/null +++ b/docs/.vitepress/lib/waitlist/resend.ts @@ -0,0 +1,133 @@ +import React from 'react'; +import { Resend } from 'resend'; +import { render } from '@react-email/components'; +import ConfirmationEmail from './ConfirmationEmail.tsx'; +import type { WaitlistSignup } from './token.ts'; + +const FROM_ADDRESS = 'Lucide '; + +function getEnv(name: string) { + const value = process.env[name]; + + if (!value) { + throw new Error(`${name} is not set`); + } + + return value; +} + +let client: Resend | undefined; + +function getResend() { + client ??= new Resend(getEnv('RESEND_API_KEY')); + return client; +} + +/** The SDK returns errors instead of throwing, this turns them back into exceptions. */ +function unwrap( + result: { data: T; error: null } | { data: null; error: { name: string; message: string } }, + action: string, +): T { + if (result.error) { + throw new Error(`Resend: could not ${action} (${result.error.name}: ${result.error.message})`); + } + + return result.data; +} + +export async function sendConfirmationEmail({ + email, + productName, + confirmUrl, +}: { + email: string; + productName: string; + confirmUrl: string; +}) { + const message = React.createElement(ConfirmationEmail, { productName, confirmUrl }); + + const result = await getResend().emails.send({ + from: FROM_ADDRESS, + to: email, + subject: `Confirm your spot on the ${productName} waitlist`, + html: await render(message), + text: await render(message, { plainText: true }), + }); + + unwrap(result, 'send the confirmation email'); +} + +/** Contact properties only hold one value, so a contact on several waitlists gets a comma-separated list. */ +function mergeProducts(existing: string | undefined, product: string) { + const products = new Set(existing?.split(',').filter(Boolean)); + products.add(product); + return [...products].join(','); +} + +/** + * Creates the Resend contact for a confirmed signup, or updates it when the email is already a + * contact (a second product, or a confirmation link clicked twice). Either way the contact ends up + * in the Waitlist segment and opted in to the Product updates topic. + * + * Returns the contact's Resend ID, which the survey uses to link submissions to the contact. + */ +export async function addToWaitlist(signup: WaitlistSignup): Promise { + const resend = getResend(); + const segmentId = getEnv('RESEND_WAITLIST_SEGMENT_ID'); + const topicId = getEnv('RESEND_PRODUCT_UPDATES_TOPIC_ID'); + + const existing = await resend.contacts.get({ email: signup.email }); + + if (existing.error && existing.error.name !== 'not_found') { + unwrap(existing, 'look up the contact'); + } + + if (!existing.data) { + const created = await resend.contacts.create({ + email: signup.email, + properties: { + product: signup.product, + use_case: signup.useCase || null, + source: signup.source || null, + signed_up_at: signup.signedUpAt, + }, + segments: [{ id: segmentId }], + topics: [{ id: topicId, subscription: 'opt_in' }], + }); + + return unwrap(created, 'create the contact').id; + } + + const current = existing.data.properties ?? {}; + const currentValue = (key: string) => { + const value = current[key]?.value; + return value == null || value === '' ? undefined : String(value); + }; + + const updated = await resend.contacts.update({ + email: signup.email, + // Clicking the confirmation link is a fresh opt-in, even after an earlier unsubscribe. + unsubscribed: false, + properties: { + product: mergeProducts(currentValue('product'), signup.product), + use_case: signup.useCase || currentValue('use_case') || null, + source: currentValue('source') ?? (signup.source || null), + signed_up_at: currentValue('signed_up_at') ?? signup.signedUpAt, + }, + }); + unwrap(updated, 'update the contact'); + + unwrap( + await resend.contacts.segments.add({ email: signup.email, segmentId }), + 'add the contact to the Waitlist segment', + ); + unwrap( + await resend.contacts.topics.update({ + email: signup.email, + topics: [{ id: topicId, subscription: 'opt_in' }], + }), + 'opt the contact in to Product updates', + ); + + return existing.data.id; +} diff --git a/docs/.vitepress/lib/waitlist/token.ts b/docs/.vitepress/lib/waitlist/token.ts new file mode 100644 index 000000000..4c19245c3 --- /dev/null +++ b/docs/.vitepress/lib/waitlist/token.ts @@ -0,0 +1,100 @@ +import { createHmac, timingSafeEqual } from 'node:crypto'; + +/** How long a confirmation link stays valid. */ +const TOKEN_TTL_MS = 7 * 24 * 60 * 60 * 1000; + +export interface WaitlistSignup { + email: string; + product: string; + useCase: string; + source: string; + /** ISO date of the form submission, stored on the contact as `signed_up_at`. */ + signedUpAt: string; +} + +interface TokenPayload extends WaitlistSignup { + /** Expiry as a Unix timestamp in milliseconds. */ + exp: number; +} + +function getSecret() { + const secret = process.env.WAITLIST_TOKEN_SECRET; + + if (!secret) { + throw new Error('WAITLIST_TOKEN_SECRET is not set'); + } + + return secret; +} + +function sign(data: string) { + return createHmac('sha256', getSecret()).update(data).digest('base64url'); +} + +/** + * Packs the signup into a signed token for the confirmation link, so no pending signups + * need to be stored. Format: `.`. + */ +export function createConfirmToken(signup: WaitlistSignup) { + const payload: TokenPayload = { ...signup, exp: Date.now() + TOKEN_TTL_MS }; + const data = Buffer.from(JSON.stringify(payload)).toString('base64url'); + + return `${data}.${sign(data)}`; +} + +function decodePayload(data: string): Partial | undefined { + try { + const payload = JSON.parse(Buffer.from(data, 'base64url').toString('utf8')); + return payload && typeof payload === 'object' ? payload : undefined; + } catch { + return undefined; + } +} + +export type VerifyResult = + | { valid: true; signup: WaitlistSignup } + /** `product` is only set when the token was signed by us, so it is safe to redirect with. */ + | { valid: false; product?: string }; + +/** + * Checks the signature and expiry of a confirmation token. + */ +export function verifyConfirmToken(token: string): VerifyResult { + const [data, signature, ...rest] = token.split('.'); + + if (!data || !signature || rest.length) { + return { valid: false }; + } + + const expected = Buffer.from(sign(data)); + const actual = Buffer.from(signature); + + if (expected.length !== actual.length || !timingSafeEqual(expected, actual)) { + return { valid: false }; + } + + const payload = decodePayload(data); + + if ( + typeof payload?.email !== 'string' || + typeof payload.product !== 'string' || + typeof payload.exp !== 'number' + ) { + return { valid: false }; + } + + if (payload.exp < Date.now()) { + return { valid: false, product: payload.product }; + } + + return { + valid: true, + signup: { + email: payload.email, + product: payload.product, + useCase: payload.useCase ?? '', + source: payload.source ?? '', + signedUpAt: payload.signedUpAt ?? new Date().toISOString(), + }, + }; +} diff --git a/docs/.vitepress/middleware/cors.ts b/docs/.vitepress/middleware/cors.ts new file mode 100644 index 000000000..bff57653a --- /dev/null +++ b/docs/.vitepress/middleware/cors.ts @@ -0,0 +1,16 @@ +import { defineEventHandler, handleCors } from 'h3'; + +/** + * In development the VitePress dev server and the Nitro API run on different ports, so requests + * like `POST /api/waitlist` (JSON body → CORS preflight) are cross-origin. Answer the preflight and + * add CORS headers in dev only; in production the docs and API share an origin. + */ +export default defineEventHandler((event) => { + if (!import.meta.dev || !event.path.startsWith('/api/')) return; + + handleCors(event, { + origin: '*', + methods: '*', + allowHeaders: '*', + }); +}); diff --git a/docs/.vitepress/theme/components/waitlist/McpDiagram.vue b/docs/.vitepress/theme/components/waitlist/McpDiagram.vue new file mode 100644 index 000000000..eece71348 --- /dev/null +++ b/docs/.vitepress/theme/components/waitlist/McpDiagram.vue @@ -0,0 +1,386 @@ + + + + + diff --git a/docs/.vitepress/theme/components/waitlist/WaitlistConfirmed.vue b/docs/.vitepress/theme/components/waitlist/WaitlistConfirmed.vue new file mode 100644 index 000000000..d075787a8 --- /dev/null +++ b/docs/.vitepress/theme/components/waitlist/WaitlistConfirmed.vue @@ -0,0 +1,122 @@ + + + + + diff --git a/docs/.vitepress/theme/components/waitlist/WaitlistForm.vue b/docs/.vitepress/theme/components/waitlist/WaitlistForm.vue new file mode 100644 index 000000000..e1ed75411 --- /dev/null +++ b/docs/.vitepress/theme/components/waitlist/WaitlistForm.vue @@ -0,0 +1,198 @@ + + + + + diff --git a/docs/.vitepress/theme/components/waitlist/WaitlistHero.vue b/docs/.vitepress/theme/components/waitlist/WaitlistHero.vue new file mode 100644 index 000000000..454bcb906 --- /dev/null +++ b/docs/.vitepress/theme/components/waitlist/WaitlistHero.vue @@ -0,0 +1,145 @@ + + + + + diff --git a/docs/.vitepress/theme/components/waitlist/WaitlistSurvey.vue b/docs/.vitepress/theme/components/waitlist/WaitlistSurvey.vue new file mode 100644 index 000000000..0348ebce5 --- /dev/null +++ b/docs/.vitepress/theme/components/waitlist/WaitlistSurvey.vue @@ -0,0 +1,69 @@ + + +