fix: resolve session userId, guard provision, fallback to shared bot number

Author: KumarVandit

.env.example

@@ -17,5 +17,9 @@ MASTER_KEY=
 # Default model used to answer iMessage threads.
 CODEX_MODEL=gpt-5-codex
 
+# Optional: Spectrum shared-pool inbound number to display when the project is on
+# the free plan and Spectrum doesn't return a per-user bot number. E.164 format.
+# SPECTRUM_SHARED_IMESSAGE_NUMBER=+14155550123
+
 # Container entrypoint mode: "webapp" or "bridge".
 PROCESS=webapp

app/api/provision/route.ts

@@ -9,6 +9,7 @@ import {
   getProject,
   getSession,
   imessageRedirectUrl,
+  listSpectrumUsers,
   provisionImessage,
   regenerateProjectSecret,
   togglePlatform,
@@ -77,6 +78,14 @@ export async function POST(req: Request) {
       openaiKey?: unknown;
       userPhone?: unknown;
     };
+    console.log(
+      "[provision] body received: openaiKey=",
+      typeof body.openaiKey === "string"
+        ? `present(len=${body.openaiKey.length})`
+        : typeof body.openaiKey,
+      "userPhone=",
+      typeof body.userPhone === "string" ? `"${body.userPhone}"` : typeof body.userPhone,
+    );
     if (typeof body.userPhone === "string" && body.userPhone.trim().length > 0) {
       userPhone = body.userPhone.trim();
     }
@@ -113,6 +122,17 @@ export async function POST(req: Request) {
     const ownerPhone =
       userPhone ?? (typeof session.user.phoneNumber === "string" ? session.user.phoneNumber : null);
 
+    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 db = getDb();
 
     const existing = await db
@@ -150,17 +170,6 @@ export async function POST(req: Request) {
       `[provision] dashboard id=${project.id} cloud spectrumProjectId=${details.spectrumProjectId ?? "(missing — using dashboard id)"}`,
     );
 
-    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, {
@@ -172,29 +181,46 @@ export async function POST(req: Request) {
     });
     console.log("[provision] create-spectrum-user response:", JSON.stringify(userResp));
 
-    let line = await provisionImessage(bearer, cloudProjectId, projectSecret).catch(
-      (err: unknown) => {
+    let line: { id: string; phoneNumber: string } | null = null;
+
+    const fromUser = pickPhoneFrom(userResp, ownerPhone);
+    if (fromUser) {
+      line = { id: userResp.user?.id ?? `${cloudProjectId}:imessage`, phoneNumber: fromUser };
+      console.log(`[provision] picked bot number from user-add response: ${fromUser}`);
+    }
+
+    if (!line) {
+      try {
+        line = await provisionImessage(bearer, cloudProjectId, projectSecret);
+        console.log(`[provision] picked bot number from provisionImessage: ${line.phoneNumber}`);
+      } catch (err) {
         console.warn(
-          "[provision] provisionImessage fallback after user-add:",
+          "[provision] provisionImessage didn't yield a number:",
           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 usersList = await listSpectrumUsers(bearer, project.id);
+      if (usersList) {
+        console.log("[provision] users list response:", JSON.stringify(usersList).slice(0, 1500));
+        const fromList = pickPhoneFrom(usersList, ownerPhone);
+        if (fromList) {
+          line = { id: `${cloudProjectId}:imessage`, phoneNumber: fromList };
+          console.log(`[provision] picked bot number from users list: ${fromList}`);
+        }
       }
     }
 
+    if (!line) {
+      throw new SpectrumError(
+        "Couldn't read the assigned iMessage number from Spectrum. Set SPECTRUM_SHARED_IMESSAGE_NUMBER to the shared inbound number, or check the Spectrum dashboard.",
+        500,
+        { userResp },
+      );
+    }
+
     const projectSecretBlob = encrypt(projectSecret);
     const openaiBlob = openaiKey ? encrypt(openaiKey) : null;
 

app/onboard/onboard-client.tsx

@@ -141,6 +141,10 @@ export default function OnboardClient() {
 
   useEffect(() => {
     if (stage !== "provision") return;
+    if (!userPhone.trim()) {
+      setStage("phone");
+      return;
+    }
     let cancelled = false;
     setBusy(true);
     void fetch("/api/provision", {

lib/spectrum.ts

@@ -138,14 +138,38 @@ export interface SessionUser {
   [key: string]: unknown;
 }
 
+interface RawSessionEnvelope {
+  user?: Partial<SessionUser> & Record<string, unknown>;
+  session?: { userId?: string; id?: string; [key: string]: unknown };
+  [key: string]: unknown;
+}
+
 export async function getSession(bearer: string): Promise<{ user: SessionUser } | null> {
   const res = await fetch(`${dashboardHost()}/api/auth/get-session`, {
     headers: { authorization: `Bearer ${bearer}` },
   });
   if (res.status === 401) return null;
-  const body = (await expectOk<{ user?: SessionUser }>(res, "get-session")) ?? {};
-  if (!body.user) return null;
-  return { user: body.user };
+  const body = (await expectOk<RawSessionEnvelope>(res, "get-session")) ?? {};
+  const rawUser = body.user;
+  if (!rawUser) return null;
+
+  const id =
+    (typeof rawUser.id === "string" && rawUser.id) ||
+    (typeof body.session?.userId === "string" && body.session.userId) ||
+    (typeof body.session?.id === "string" && body.session.id) ||
+    null;
+
+  if (!id) {
+    console.warn("[spectrum] get-session returned user without id; body:", JSON.stringify(body));
+    return null;
+  }
+
+  return {
+    user: {
+      ...(rawUser as Record<string, unknown>),
+      id,
+    } as SessionUser,
+  };
 }
 
 export interface SpectrumUserResult {
@@ -195,6 +219,23 @@ export async function createSpectrumUser(
   return body ?? {};
 }
 
+export async function listSpectrumUsers(
+  bearer: string,
+  projectId: string,
+): Promise<Record<string, unknown> | unknown[] | null> {
+  try {
+    const res = await fetch(
+      `${dashboardHost()}/api/projects/${encodeURIComponent(projectId)}/spectrum/users`,
+      { headers: { authorization: `Bearer ${bearer}` } },
+    );
+    if (!res.ok) return null;
+    return (await asJson(res)) as Record<string, unknown> | unknown[] | null;
+  } catch (err) {
+    console.warn("[spectrum] list-users probe failed:", err instanceof Error ? err.message : err);
+    return null;
+  }
+}
+
 export interface CreateProjectInput {
   name: string;
   location?: string;
@@ -551,6 +592,11 @@ export async function provisionImessage(
   const dashboardScan = await findAssignedImessageNumber(bearer, projectId);
   if (dashboardScan) return dashboardScan;
 
+  const sharedFallback = process.env.SPECTRUM_SHARED_IMESSAGE_NUMBER?.trim();
+  if (tokens.type === "shared" && sharedFallback) {
+    return { id: `${projectId}:imessage:shared`, phoneNumber: sharedFallback };
+  }
+
   throw new SpectrumError(
     `iMessage activated but no phone number was returned (type=${tokens.type}). Check the Spectrum dashboard for the assigned number.`,
     500,