feat: collect user phone and add as spectrum user to claim bot number

KumarVandit · KumarVandit · commit ecfc201c9b22 · 2026-05-12T11:43:57.000+05:30
Free-plan Spectrum projects don't have a phone until a user is added
with their own phone. The user-add response carries the assigned
shared bot number. Insert a phone collection step in onboarding,
pass userPhone to /api/provision, call POST /spectrum/users with it,
and scan the response for the assigned number (preferring keys like
assignedPhoneNumber / botPhoneNumber / sharedPhoneNumber and excluding
the input phone).
diff --git a/app/api/provision/route.ts b/app/api/provision/route.ts
@@ -5,6 +5,7 @@ import { isOpenAIKeyShape, verifyOpenAIKey } from "@/lib/openai-key";
 import {
   SpectrumError,
   createProject,
+  createSpectrumUser,
   getProject,
   getSession,
   imessageRedirectUrl,
@@ -19,6 +20,49 @@ import { NextResponse } from "next/server";
 export const runtime = "nodejs";
 export const dynamic = "force-dynamic";
 
+const PHONE_RE = /^\+?\d{6,}$/;
+const PREFERRED_PHONE_KEYS = [
+  "assignedPhoneNumber",
+  "botPhoneNumber",
+  "spectrumPhoneNumber",
+  "inboundPhoneNumber",
+  "sharedPhoneNumber",
+  "lineNumber",
+];
+const FALLBACK_PHONE_KEYS = ["phoneNumber", "phone", "number", "msisdn"];
+
+function pickPhoneFrom(value: unknown, exclude?: string | null, depth = 0): string | null {
+  if (depth > 6 || value === null || value === undefined) return null;
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      const hit = pickPhoneFrom(item, exclude, depth + 1);
+      if (hit) return hit;
+    }
+    return null;
+  }
+  if (typeof value !== "object") return null;
+  const obj = value as Record<string, unknown>;
+  for (const key of PREFERRED_PHONE_KEYS) {
+    const v = obj[key];
+    if (typeof v === "string" && PHONE_RE.test(v.trim())) {
+      const trimmed = v.trim();
+      if (!exclude || trimmed !== exclude) return trimmed;
+    }
+  }
+  for (const key of FALLBACK_PHONE_KEYS) {
+    const v = obj[key];
+    if (typeof v === "string" && PHONE_RE.test(v.trim())) {
+      const trimmed = v.trim();
+      if (!exclude || trimmed !== exclude) return trimmed;
+    }
+  }
+  for (const v of Object.values(obj)) {
+    const hit = pickPhoneFrom(v, exclude, depth + 1);
+    if (hit) return hit;
+  }
+  return null;
+}
+
 export async function POST(req: Request) {
   const jar = await cookies();
   const bearer = jar.get("bearer")?.value;
@@ -27,8 +71,15 @@ export async function POST(req: Request) {
   }
 
   let openaiKey: string | null = null;
+  let userPhone: string | null = null;
   try {
-    const body = (await req.json().catch(() => ({}))) as { openaiKey?: unknown };
+    const body = (await req.json().catch(() => ({}))) as {
+      openaiKey?: unknown;
+      userPhone?: unknown;
+    };
+    if (typeof body.userPhone === "string" && body.userPhone.trim().length > 0) {
+      userPhone = body.userPhone.trim();
+    }
     if (typeof body.openaiKey === "string" && body.openaiKey.trim().length > 0) {
       const candidate = body.openaiKey.trim();
       if (!isOpenAIKeyShape(candidate)) {
@@ -57,6 +108,10 @@ export async function POST(req: Request) {
     if (!session) {
       return NextResponse.json({ error: "session invalid" }, { status: 401 });
     }
+    console.log("[provision] session.user keys:", Object.keys(session.user));
+
+    const ownerPhone =
+      userPhone ?? (typeof session.user.phoneNumber === "string" ? session.user.phoneNumber : null);
 
     const db = getDb();
 
@@ -95,7 +150,50 @@ export async function POST(req: Request) {
       `[provision] dashboard id=${project.id} cloud spectrumProjectId=${details.spectrumProjectId ?? "(missing — using dashboard id)"}`,
     );
 
-    const line = await provisionImessage(bearer, cloudProjectId, projectSecret);
+    if (!ownerPhone) {
+      return NextResponse.json(
+        {
+          error:
+            "We need your phone number to assign you a Spectrum iMessage bot. Add it and continue.",
+          reason: "phone_required",
+        },
+        { status: 422 },
+      );
+    }
+
+    const fullName = session.user.name?.trim() ?? "";
+    const [firstName, ...rest] = fullName.split(/\s+/);
+    const userResp = await createSpectrumUser(bearer, project.id, {
+      firstName: firstName || "Codex",
+      lastName: rest.join(" ") || "User",
+      email: session.user.email ?? `${session.user.id}@codex.local`,
+      phoneNumber: ownerPhone,
+      sendInvite: false,
+    });
+    console.log("[provision] create-spectrum-user response:", JSON.stringify(userResp));
+
+    let line = await provisionImessage(bearer, cloudProjectId, projectSecret).catch(
+      (err: unknown) => {
+        console.warn(
+          "[provision] provisionImessage fallback after user-add:",
+          err instanceof Error ? err.message : err,
+        );
+        return null;
+      },
+    );
+
+    if (!line) {
+      const fromUser = pickPhoneFrom(userResp, ownerPhone);
+      if (fromUser) {
+        line = { id: userResp.user?.id ?? `${cloudProjectId}:imessage`, phoneNumber: fromUser };
+      } else {
+        throw new SpectrumError(
+          "Couldn't read the assigned iMessage number from Spectrum's response.",
+          500,
+          userResp,
+        );
+      }
+    }
 
     const projectSecretBlob = encrypt(projectSecret);
     const openaiBlob = openaiKey ? encrypt(openaiKey) : null;
diff --git a/app/onboard/onboard-client.tsx b/app/onboard/onboard-client.tsx
@@ -16,7 +16,7 @@ import { useRouter } from "next/navigation";
 import { useCallback, useEffect, useMemo, useState } from "react";
 import { toast } from "sonner";
 
-type Stage = "key" | "device" | "provision" | "done";
+type Stage = "key" | "device" | "phone" | "provision" | "done";
 
 interface DeviceState {
   user_code: string;
@@ -34,15 +34,17 @@ interface TenantState {
 const STEP_INDEX: Record<Stage, number> = {
   key: 0,
   device: 1,
-  provision: 1,
-  done: 2,
+  phone: 2,
+  provision: 2,
+  done: 3,
 };
-const TOTAL_STEPS = 3;
+const TOTAL_STEPS = 4;
 
 export default function OnboardClient() {
   const router = useRouter();
   const [stage, setStage] = useState<Stage>("key");
   const [apiKey, setApiKey] = useState("");
+  const [userPhone, setUserPhone] = useState("");
   const [device, setDevice] = useState<DeviceState | null>(null);
   const [tenant, setTenant] = useState<TenantState | null>(null);
   const [busy, setBusy] = useState(false);
@@ -98,7 +100,7 @@ export default function OnboardClient() {
         if (cancelled) return;
         switch (data.status) {
           case "ok":
-            setStage("provision");
+            setStage("phone");
             return;
           case "pending":
             pollTimer = setTimeout(poll, interval);
@@ -144,7 +146,7 @@ export default function OnboardClient() {
     void fetch("/api/provision", {
       method: "POST",
       headers: { "content-type": "application/json" },
-      body: JSON.stringify({ openaiKey: apiKey.trim() }),
+      body: JSON.stringify({ openaiKey: apiKey.trim(), userPhone: userPhone.trim() }),
     })
       .then(async (res) => {
         if (cancelled) return;
@@ -173,7 +175,7 @@ export default function OnboardClient() {
     return () => {
       cancelled = true;
     };
-  }, [stage, apiKey]);
+  }, [stage, apiKey, userPhone]);
 
   const activeIdx = STEP_INDEX[stage];
 
@@ -194,6 +196,9 @@ export default function OnboardClient() {
           beginSpectrum={beginSpectrum}
           device={device}
           tenant={tenant}
+          userPhone={userPhone}
+          setUserPhone={setUserPhone}
+          onPhoneSubmit={() => setStage("provision")}
         />
       </div>
     </div>
@@ -205,6 +210,7 @@ function StageIcon({ stage }: { stage: Stage }) {
     case "key":
       return <ChatGPTChip />;
     case "device":
+    case "phone":
       return <SpectrumChip />;
     case "provision":
     case "done":
@@ -243,6 +249,9 @@ interface StageContentProps {
   beginSpectrum: () => void;
   device: DeviceState | null;
   tenant: TenantState | null;
+  userPhone: string;
+  setUserPhone: (v: string) => void;
+  onPhoneSubmit: () => void;
 }
 
 function StageContent({
@@ -253,6 +262,9 @@ function StageContent({
   beginSpectrum,
   device,
   tenant,
+  userPhone,
+  setUserPhone,
+  onPhoneSubmit,
 }: StageContentProps) {
   switch (stage) {
     case "key":
@@ -271,6 +283,16 @@ function StageContent({
         </>
       );
 
+    case "phone":
+      return (
+        <PhoneStage
+          userPhone={userPhone}
+          setUserPhone={setUserPhone}
+          busy={busy}
+          onSubmit={onPhoneSubmit}
+        />
+      );
+
     case "provision":
       return (
         <>
@@ -300,6 +322,103 @@ function StageContent({
   }
 }
 
+function PhoneStage({
+  userPhone,
+  setUserPhone,
+  busy,
+  onSubmit,
+}: {
+  userPhone: string;
+  setUserPhone: (v: string) => void;
+  busy: boolean;
+  onSubmit: () => void;
+}) {
+  const [shaking, setShaking] = useState(false);
+  const [attempted, setAttempted] = useState(false);
+  const trimmed = userPhone.trim();
+  const isValid = useMemo(() => /^\+[1-9]\d{6,14}$/.test(trimmed), [trimmed]);
+  const isEmpty = trimmed.length === 0;
+
+  const state: "valid" | "invalid" | "neutral" = isValid
+    ? "valid"
+    : attempted && !isEmpty
+      ? "invalid"
+      : "neutral";
+
+  const handleSubmit = () => {
+    if (!isValid) {
+      setAttempted(true);
+      setShaking(true);
+      setTimeout(() => setShaking(false), 420);
+      toast.error("That doesn't look like a phone number", {
+        description: "Use E.164 format, e.g. +14155550123.",
+      });
+      return;
+    }
+    onSubmit();
+  };
+
+  return (
+    <>
+      <h1 className="section-title fade-up fade-up-4 mt-4">Your phone number</h1>
+      <p className="body-muted fade-up fade-up-5 mt-2 max-w-[24rem] text-balance">
+        Spectrum uses this to assign you a shared iMessage bot you can text.
+      </p>
+      <div className="fade-up fade-up-6 mt-7 w-full max-w-[28rem]">
+        <form
+          className={`flex w-full flex-col gap-3 ${shaking ? "shake" : ""}`}
+          onSubmit={(e) => {
+            e.preventDefault();
+            handleSubmit();
+          }}
+          noValidate
+        >
+          <div className="relative">
+            <input
+              className="input-glass font-mono text-center text-[15px] tracking-[0.02em] pr-10"
+              type="tel"
+              inputMode="tel"
+              placeholder="+14155550123"
+              autoComplete="tel"
+              spellCheck={false}
+              value={userPhone}
+              onChange={(e) => {
+                setUserPhone(e.target.value);
+                if (attempted) setAttempted(false);
+              }}
+              disabled={busy}
+              aria-label="Your phone number (E.164)"
+              aria-invalid={state === "invalid" || undefined}
+              data-state={state === "neutral" ? undefined : state}
+              required
+            />
+            <span className="pointer-events-none absolute right-3 top-1/2 -translate-y-1/2">
+              {state === "valid" ? (
+                <Check size={16} className="text-[var(--color-success)]" />
+              ) : state === "invalid" ? (
+                <AlertCircle size={16} className="text-[var(--color-danger)]" />
+              ) : null}
+            </span>
+          </div>
+          <button
+            type="submit"
+            className="btn-pill-primary inline-flex w-full items-center justify-center"
+            disabled={busy || isEmpty}
+          >
+            {busy ? <Loader2 size={14} className="mr-1.5 animate-spin" /> : null}
+            Continue
+            {!busy && <ArrowRight size={14} className="ml-1.5" />}
+          </button>
+          <p className="mt-1 text-[12px] text-[var(--color-text-dim)]">
+            Include the country code. We never message you — Spectrum uses this to register your
+            account.
+          </p>
+        </form>
+      </div>
+    </>
+  );
+}
+
 function KeyStage({
   apiKey,
   setApiKey,
diff --git a/lib/spectrum.ts b/lib/spectrum.ts
