Add Twilio SMS verification example (#186)

* Add Twilio SMS verification example

- Next.js OTP flow (enter phone -> verify code -> dashboard) using the official Twilio SDK against the embedded Twilio Verify emulator
- Custom SDK request client rewrites Twilio product hosts (api/verify/messaging) onto the emulator's path prefixes via TWILIO_BASE_URL
- No real SMS sent; uses seeded account/Verify Service defaults (code 123456) with a link to the Twilio inspector

* Fix Twilio example programmatic verification

* Fix Twilio example URL query preservation

Author: ctate

examples/twilio-sms-verification/.gitignore

@@ -0,0 +1,15 @@
+/node_modules
+/.next/
+/out/
+/build
+.DS_Store
+*.pem
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+.env*
+.vercel
+*.tsbuildinfo
+next-env.d.ts
+.emulate/

examples/twilio-sms-verification/README.md

@@ -0,0 +1,95 @@
+# SMS Verification with Twilio
+
+A Next.js app demonstrating phone number verification (SMS OTP) using the [Twilio Verify](https://www.twilio.com/docs/verify) API, powered by the emulated Twilio service from `emulate`.
+
+No real SMS is sent. The emulator runs the Verify flow entirely in-memory, so you can complete the verification with the seeded code or inspect state through the inspector UI.
+
+## How it works
+
+1. User enters their phone number on the home page
+2. The server starts a verification via the official Twilio SDK: `verify.v2.services(SID).verifications.create({ to, channel: "sms" })`
+3. The user is redirected to a verification page
+4. The user enters the code and the server checks it: `verify.v2.services(SID).verificationChecks.create({ to, code })`
+5. On success, a session cookie is set and the user lands on the dashboard
+
+The seeded Verify Service accepts the code `123456` for every verification, so the demo can be completed without reading an SMS.
+
+## Pointing the SDK at the emulator
+
+The official Twilio SDK builds absolute URLs against product hosts like `api.twilio.com` and `verify.twilio.com`. `src/lib/twilio.ts` installs a custom request client that rewrites those hosts onto the embedded emulator, which mounts each product under a path prefix:
+
+| Real Twilio URL                          | Emulator URL                                        |
+| ---------------------------------------- | --------------------------------------------------- |
+| `https://api.twilio.com/2010-04-01/...`  | `http://localhost:3000/emulate/twilio/2010-04-01/...` |
+| `https://verify.twilio.com/v2/...`       | `http://localhost:3000/emulate/twilio/verify/v2/...`  |
+| `https://messaging.twilio.com/v1/...`    | `http://localhost:3000/emulate/twilio/messaging/v1/...` |
+
+The base URL is set via `TWILIO_BASE_URL` in `next.config.ts`.
+
+## Getting started
+
+From the repository root:
+
+```bash
+pnpm install
+pnpm --filter twilio-sms-verification dev
+```
+
+Open [http://localhost:3000](http://localhost:3000).
+
+## Inspecting verifications
+
+### Inspector UI
+
+Visit [http://localhost:3000/emulate/twilio/?tab=verify](http://localhost:3000/emulate/twilio/?tab=verify) to browse Verify services and verifications (including the issued code) in a web interface.
+
+### Fetching the code programmatically
+
+This is useful in tests or agent workflows where you need to complete the flow without a human reading the SMS:
+
+```bash
+# Start a verification through the example API route (sets the pending_verification cookie)
+curl -s -c cookies.txt -X POST http://localhost:3000/api/verification/start \
+  --data-urlencode "phone=+15555550123"
+
+# Fetch the latest local code for that number
+curl -s -G http://localhost:3000/emulate/twilio/_twilio/simulate/verification-code \
+  --data-urlencode "To=+15555550123" \
+  --data-urlencode "ServiceSid=VA00000000000000000000000000000000" \
+  -u "AC00000000000000000000000000000000:twilio_test_auth_token" | jq -r '.code'
+```
+
+## Seeded defaults
+
+The Twilio emulator boots with a ready-to-use account and Verify Service:
+
+```text
+TWILIO_ACCOUNT_SID=AC00000000000000000000000000000000
+TWILIO_AUTH_TOKEN=twilio_test_auth_token
+TWILIO_VERIFY_SERVICE_SID=VA00000000000000000000000000000000
+Seeded Verify code=123456
+```
+
+## Project structure
+
+```
+src/
+  app/
+    page.tsx                    Phone entry form
+    phone-form.tsx              Client component for phone input
+    actions.ts                  Server actions (send code, check code, sign out)
+    verify/
+      page.tsx                  Verification page (enter code)
+      verify-form.tsx           Client component for code input
+    dashboard/
+      page.tsx                  Verified landing page
+    api/
+      verification/start/
+        route.ts                Programmatic send-code route for tests and agents
+    emulate/
+      [...path]/route.ts        Embedded emulator (Twilio)
+  lib/
+    twilio.ts                   Twilio SDK client + request client that targets the emulator
+    session.ts                  Cookie-based session helpers
+    verification.ts             Shared verification starter
+```

examples/twilio-sms-verification/eslint.config.mjs

@@ -0,0 +1,11 @@
+import { defineConfig, globalIgnores } from "eslint/config";
+import nextVitals from "eslint-config-next/core-web-vitals";
+import nextTs from "eslint-config-next/typescript";
+
+const eslintConfig = defineConfig([
+  ...nextVitals,
+  ...nextTs,
+  globalIgnores([".next/**", "out/**", "build/**", "next-env.d.ts"]),
+]);
+
+export default eslintConfig;

examples/twilio-sms-verification/next.config.ts

@@ -0,0 +1,18 @@
+import { resolve } from "path";
+import type { NextConfig } from "next";
+import { withEmulate } from "@emulators/adapter-next";
+
+const port = process.env.PORT ?? "3000";
+
+const nextConfig: NextConfig = {
+  turbopack: {
+    root: resolve(import.meta.dirname, "../.."),
+  },
+  env: {
+    // Point the official Twilio SDK at the embedded emulator. The custom request
+    // client in src/lib/twilio.ts rewrites Twilio product hosts to this base URL.
+    TWILIO_BASE_URL: `http://localhost:${port}/emulate/twilio`,
+  },
+};
+
+export default withEmulate(nextConfig);

examples/twilio-sms-verification/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "twilio-sms-verification",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "eslint"
+  },
+  "dependencies": {
+    "@base-ui/react": "^1.3.0",
+    "@emulators/adapter-next": "workspace:*",
+    "@emulators/twilio": "workspace:*",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "lucide-react": "^0.577.0",
+    "next": "16.2.0",
+    "twilio": "^6.0.2",
+    "react": "19.2.4",
+    "react-dom": "19.2.4",
+    "tailwind-merge": "^3.5.0",
+    "tw-animate-css": "^1.4.0"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4",
+    "@types/node": "^20",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "eslint": "^9",
+    "eslint-config-next": "16.2.0",
+    "tailwindcss": "^4",
+    "typescript": "^5"
+  }
+}

examples/twilio-sms-verification/postcss.config.mjs

@@ -0,0 +1,7 @@
+const config = {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};
+
+export default config;

examples/twilio-sms-verification/src/app/actions.ts

@@ -0,0 +1,57 @@
+"use server";
+
+import { cookies } from "next/headers";
+import { redirect } from "next/navigation";
+import { twilioClient, VERIFY_SERVICE_SID } from "@/lib/twilio";
+import { encodeSession, getPendingVerification } from "@/lib/session";
+import { startSmsVerification } from "@/lib/verification";
+
+export async function sendCodeAction(_prev: { error: string } | null, formData: FormData) {
+  const phone = (formData.get("phone") as string)?.trim();
+  if (!phone) return { error: "Phone number is required" };
+
+  try {
+    await startSmsVerification(phone);
+  } catch (err) {
+    return { error: err instanceof Error ? err.message : "Failed to send verification code" };
+  }
+
+  redirect("/verify");
+}
+
+export async function verifyCodeAction(_prev: { error: string } | null, formData: FormData) {
+  const code = (formData.get("code") as string)?.trim();
+  if (!code) return { error: "Code is required" };
+
+  const pending = await getPendingVerification();
+  if (!pending) return { error: "No pending verification. Please start over." };
+
+  let approved = false;
+  try {
+    const check = await twilioClient.verify.v2.services(VERIFY_SERVICE_SID).verificationChecks.create({
+      to: pending.phone,
+      code,
+    });
+    approved = check.status === "approved";
+  } catch (err) {
+    return { error: err instanceof Error ? err.message : "Failed to verify code" };
+  }
+
+  if (!approved) return { error: "Invalid code. Please try again." };
+
+  const cookieStore = await cookies();
+  cookieStore.delete("pending_verification");
+  cookieStore.set("session", encodeSession({ phone: pending.phone, verifiedAt: new Date().toISOString() }), {
+    httpOnly: true,
+    path: "/",
+    maxAge: 86400,
+  });
+
+  redirect("/dashboard");
+}
+
+export async function signOutAction() {
+  const cookieStore = await cookies();
+  cookieStore.delete("session");
+  redirect("/");
+}

examples/twilio-sms-verification/src/app/api/verification/start/route.ts

@@ -0,0 +1,32 @@
+import { NextResponse } from "next/server";
+import { startSmsVerification } from "@/lib/verification";
+
+async function phoneFromRequest(request: Request): Promise<string | null> {
+  const contentType = request.headers.get("content-type") ?? "";
+  if (contentType.includes("application/json")) {
+    const body = (await request.json()) as { phone?: unknown };
+    return typeof body.phone === "string" ? body.phone.trim() : null;
+  }
+
+  const formData = await request.formData();
+  const phone = formData.get("phone");
+  return typeof phone === "string" ? phone.trim() : null;
+}
+
+export async function POST(request: Request) {
+  const phone = await phoneFromRequest(request);
+  if (!phone) {
+    return NextResponse.json({ error: "Phone number is required" }, { status: 400 });
+  }
+
+  try {
+    await startSmsVerification(phone);
+  } catch (err) {
+    return NextResponse.json(
+      { error: err instanceof Error ? err.message : "Failed to send verification code" },
+      { status: 500 },
+    );
+  }
+
+  return NextResponse.json({ ok: true, phone, next: "/verify" });
+}

examples/twilio-sms-verification/src/app/dashboard/page.tsx

@@ -0,0 +1,31 @@
+import { redirect } from "next/navigation";
+import { getSession } from "@/lib/session";
+import { signOutAction } from "../actions";
+import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
+import { buttonVariants } from "@/components/ui/button-variants";
+import { cn } from "@/lib/utils";
+
+export default async function DashboardPage() {
+  const session = await getSession();
+  if (!session) redirect("/");
+
+  return (
+    <div className="flex flex-1 items-center justify-center p-4">
+      <Card className="w-full max-w-sm">
+        <CardHeader className="text-center">
+          <CardTitle className="text-2xl">Phone verified</CardTitle>
+        </CardHeader>
+        <CardContent className="flex flex-col gap-4 items-center">
+          <p className="text-sm text-muted-foreground">
+            Verified as <strong className="text-foreground">{session.phone}</strong>
+          </p>
+          <form action={signOutAction}>
+            <button type="submit" className={cn(buttonVariants({ variant: "outline", size: "lg" }))}>
+              Sign out
+            </button>
+          </form>
+        </CardContent>
+      </Card>
+    </div>
+  );
+}

examples/twilio-sms-verification/src/app/emulate/[...path]/route.ts

@@ -0,0 +1,10 @@
+import { createEmulateHandler } from "@emulators/adapter-next";
+import * as twilio from "@emulators/twilio";
+
+export const { GET, POST, PUT, PATCH, DELETE } = createEmulateHandler({
+  services: {
+    twilio: {
+      emulator: twilio,
+    },
+  },
+});