Merge branch 'dev' into payment-subscription-handling-rework

Author: nams1570

.claude/CLAUDE-KNOWLEDGE.md

@@ -355,3 +355,12 @@ Then restart the dev server. This rebuilds all packages and generates the necess
 
 ## Q: How is backwards compatibility for the offer→product rename handled in the payments purchase APIs?
 A: API v1 requests are routed through the `v2beta1` migration. The migration wraps the latest handlers, accepts legacy `offer_id`/`offer_inline` request fields, translates product-related errors back to the old offer error codes/messages, and augments responses (like `validate-code`) with `offer`/`conflicting_group_offers` aliases alongside the new `product` fields. Newer API versions keep the product-only contract.
+
+## Q: How does `/api/v1/ai/query/generate` reject invalid AI tool names?
+A: Invalid `tools` entries are rejected by `requestBodySchema` in `apps/backend/src/lib/ai/schema.ts` via `yupString().oneOf(TOOL_NAMES)`, so the endpoint returns a structured `SCHEMA_ERROR` object mentioning `body.tools[n]` rather than a custom `"Invalid tool names"` string from handler logic.
+
+## Q: Why did the internal metrics E2E snapshots need to change in April 2026?
+A: The `/api/v1/internal/metrics` response now intentionally includes `analytics_overview.daily_anonymous_visitors_fallback`, `analytics_overview.anonymous_visitors_fallback`, and `active_users_by_country`. Those additions are reflected in `packages/stack-shared/src/interface/admin-metrics.ts` and the backend route, so the E2E snapshots must include them instead of treating them as regressions.
+
+## Q: Why can environment config override writes fail with a product/product-line customer type warning after creating a preview project?
+A: The environment override endpoint validates the new environment override against the rendered branch config. Preview dummy payments data must therefore be internally coherent: products assigned to a product line need the same `customerType` as that product line, otherwise unrelated environment patches can fail with warnings like `Product "growth" has customer type "user" but its product line "workspace" has customer type "team"`.

apps/backend/.env

@@ -117,7 +117,7 @@ STACK_TELEGRAM_BOT_TOKEN= # enter you telegram bot token
 STACK_TELEGRAM_CHAT_ID=# enter your telegram chat id
 
 # Docs AI tool bundle
-STACK_DOCS_INTERNAL_BASE_URL=# override the docs origin used by the backend's AI tool bundle to call the docs app's `/api/internal/docs-tools` endpoint. Defaults to http://localhost:${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}04 in dev, https://mcp.stack-auth.com in prod
+STACK_MINTLIFY_MCP_URL=# override the Mintlify MCP server used by the backend's AI docs tool bundle. Defaults to https://stackauth-e0affa27.mintlify.app/mcp
 
 # MCP review tool (SpacetimeDB)
 STACK_SPACETIMEDB_URI=# SpacetimeDB host URI; default empty (logging disabled)

apps/backend/.env.development

@@ -78,7 +78,7 @@ STACK_STRIPE_SECRET_KEY=sk_test_mockstripekey
 STACK_STRIPE_WEBHOOK_SECRET=mock_stripe_webhook_secret
 STACK_OPENROUTER_API_KEY=FORWARD_TO_PRODUCTION
 STACK_FEEDBACK_MODE=FORWARD_TO_PRODUCTION
-# STACK_DOCS_INTERNAL_BASE_URL=http://localhost:8104
+STACK_MINTLIFY_MCP_URL=https://stackauth-e0affa27.mintlify.app/mcp
 # Email monitor configuration for tests
 STACK_EMAIL_MONITOR_VERIFICATION_CALLBACK_URL=http://localhost:8101/handler/email-verification
 STACK_EMAIL_MONITOR_PROJECT_ID=internal

apps/backend/package.json

@@ -87,6 +87,7 @@
     "@stackframe/stack-shared": "workspace:*",
     "@upstash/qstash": "^2.8.2",
     "@vercel/functions": "^2.0.0",
+    "@vercel/mcp-adapter": "^1.0.0",
     "@vercel/otel": "^1.10.4",
     "@vercel/sandbox": "^1.2.0",
     "ai": "^6.0.0",

…rc/app/api/internal/[transport]/route.ts …rc/app/api/internal/[transport]/route.tsdocs/src/app/api/internal/[transport]/route.ts renamed to apps/backend/src/app/api/internal/[transport]/route.ts docs/src/app/api/internal/[transport]/route.ts renamed to apps/backend/src/app/api/internal/[transport]/route.ts

@@ -1,10 +1,15 @@
+import { getEnvVariable } from "@stackframe/stack-shared/dist/utils/env";
 import { createMcpHandler } from "@vercel/mcp-adapter";
-import { PostHog } from "posthog-node";
 import { z } from "zod";
 
-const nodeClient = process.env.NEXT_PUBLIC_POSTHOG_KEY
-  ? new PostHog(process.env.NEXT_PUBLIC_POSTHOG_KEY)
-  : null;
+import withPostHog from "@/analytics";
+
+function getBackendApiBaseUrl(): string {
+  return (
+    getEnvVariable("NEXT_PUBLIC_SERVER_STACK_API_URL", "") ||
+    getEnvVariable("NEXT_PUBLIC_STACK_API_URL")
+  ).replace(/\/$/, "");
+}
 
 const handler = createMcpHandler(
   async (server) => {
@@ -29,26 +34,19 @@ const handler = createMcpHandler(
           .string()
           .optional()
           .describe(
-            "Pass the conversationId from a previous response to group related calls into the same conversation. Omit on the first call — the server will generate one and return it.",
+            "Pass the conversationId from a previous response to group related calls into the same conversation. Omit on the first call - the server will generate one and return it.",
           ),
       },
       async ({ question, reason, userPrompt, conversationId }) => {
-        nodeClient?.capture({
-          event: "ask_stack_auth_mcp",
-          properties: { question, reason },
-          distinctId: "mcp-handler",
+        await withPostHog(async (posthog) => {
+          posthog.capture({
+            event: "ask_stack_auth_mcp",
+            properties: { question, reason },
+            distinctId: "mcp-handler",
+          });
         });
 
-        const apiBase = process.env.NEXT_PUBLIC_STACK_API_URL;
-        if (apiBase == null || apiBase === "") {
-          return {
-            content: [{ type: "text", text: "NEXT_PUBLIC_STACK_API_URL is not configured on the docs server." }],
-            isError: true,
-          };
-        }
-
-        const url = `${apiBase.replace(/\/$/, "")}/api/latest/ai/query/generate`;
-        const res = await fetch(url, {
+        const res = await fetch(`${getBackendApiBaseUrl()}/api/latest/ai/query/generate`, {
           method: "POST",
           headers: { "Content-Type": "application/json" },
           body: JSON.stringify({
@@ -86,44 +84,15 @@ const handler = createMcpHandler(
         const responseConversationId = body.conversationId ?? conversationId ?? "";
 
         return {
-          content: [{ type: "text", text: `${text.length > 0 ? text : "(empty response)"}\n\n[conversationId: ${responseConversationId} — pass this value as the conversationId parameter in your next ask_stack_auth call to continue this conversation]` }],
+          content: [{ type: "text", text: `${text.length > 0 ? text : "(empty response)"}\n\n[conversationId: ${responseConversationId} - pass this value as the conversationId parameter in your next ask_stack_auth call to continue this conversation]` }],
         };
       },
     );
   },
   {
-    capabilities: {
-      tools: {
-        ask_stack_auth: {
-          description:
-            "Ask the Stack Auth documentation assistant any question about Stack Auth (setup, APIs, SDKs, configuration, troubleshooting).",
-          parameters: {
-            type: "object",
-            properties: {
-              question: {
-                type: "string",
-                description: "The full question to ask about Stack Auth.",
-              },
-              reason: {
-                type: "string",
-                description:
-                  "Why the agent invoked this tool (for analytics and debugging). Not sent to the documentation model.",
-              },
-              userPrompt: {
-                type: "string",
-                description:
-                  "The original user message/prompt that triggered this tool call. Copy the user's exact words.",
-              },
-              conversationId: {
-                type: "string",
-                description:
-                  "Pass the conversationId from a previous response to group related calls. Omit on first call.",
-              },
-            },
-            required: ["question", "reason", "userPrompt"],
-          },
-        },
-      },
+    serverInfo: {
+      name: "stack-auth-mcp",
+      version: "0.1.0",
     },
   },
   {

apps/backend/src/app/api/latest/ai/query/[mode]/route.ts

@@ -3,18 +3,19 @@ import { selectModel } from "@/lib/ai/models";
 import { getFullSystemPrompt } from "@/lib/ai/prompts";
 import { reviewMcpCall } from "@/lib/ai/qa-reviewer";
 import { requestBodySchema } from "@/lib/ai/schema";
-import { getTools, validateToolNames } from "@/lib/ai/tools";
+import { getTools } from "@/lib/ai/tools";
 import { getVerifiedQaContext } from "@/lib/ai/verified-qa";
 import { listManagedProjectIds } from "@/lib/projects";
 import { SmartResponse } from "@/route-handlers/smart-response";
 import { createSmartRouteHandler } from "@/route-handlers/smart-route-handler";
 import { runAsynchronouslyAndWaitUntil } from "@/utils/background-tasks";
 import { validateImageAttachments } from "@stackframe/stack-shared/dist/ai/image-limits";
+import { ChatContent } from "@stackframe/stack-shared/dist/interface/admin-interface";
 import { yupMixed, yupObject, yupString } from "@stackframe/stack-shared/dist/schema-fields";
 import { getEnvVariable } from "@stackframe/stack-shared/dist/utils/env";
 import { StatusError } from "@stackframe/stack-shared/dist/utils/errors";
 import { Json } from "@stackframe/stack-shared/dist/utils/json";
-import { generateText, ModelMessage, stepCountIs, streamText } from "ai";
+import { generateText, stepCountIs, streamText, type ModelMessage } from "ai";
 
 export const POST = createSmartRouteHandler({
   metadata: {
@@ -29,11 +30,6 @@ export const POST = createSmartRouteHandler({
   response: yupMixed<SmartResponse>().defined(),
   async handler({ params, body }, fullReq) {
     const { mode } = params;
-
-    if (!validateToolNames(body.tools)) {
-      throw new StatusError(StatusError.BadRequest, `Invalid tool names in request.`);
-    }
-
     const isAuthenticated = fullReq.auth != null;
     const { quality, speed, systemPrompt: systemPromptId, tools: toolNames, messages, projectId } = body;
 
@@ -79,11 +75,17 @@ export const POST = createSmartRouteHandler({
             ? 5
             : 5;
 
+    // Cast: the schema narrows role and leaves content as unknown, but the
+    // AI SDK accepts a superset (role: "system" etc.). We've intentionally
+    // excluded `system` at the schema layer to prevent prompt-injection via
+    // client-supplied system messages — see schema.ts.
+    const modelMessages = messages as unknown as ModelMessage[];
+
     if (mode === "stream") {
       const result = streamText({
         model,
         system: systemPrompt,
-        messages: messages as ModelMessage[],
+        messages: modelMessages,
         tools: toolsArg,
         stopWhen: stepCountIs(stepLimit),
       });
@@ -99,47 +101,29 @@ export const POST = createSmartRouteHandler({
       const result = await generateText({
         model,
         system: systemPrompt,
-        messages: messages as ModelMessage[],
+        messages: modelMessages,
         tools: toolsArg,
         abortSignal: controller.signal,
         stopWhen: stepCountIs(stepLimit),
       }).finally(() => clearTimeout(timeoutId));
 
-      const contentBlocks: Array<
-        | { type: "text", text: string }
-        | {
-            type: "tool-call",
-            toolName: string,
-            toolCallId: string,
-            args: Json,
-            argsText: string,
-            result: Json,
-          }
-      > = [];
-
-      result.steps.forEach((step) => {
+      const content: ChatContent = result.steps.flatMap((step) => {
+        const blocks: ChatContent = [];
         if (step.text) {
-          contentBlocks.push({
-            type: "text",
-            text: step.text,
-          });
+          blocks.push({ type: "text", text: step.text });
         }
-
-        const toolResultsByCallId = new Map(
-          step.toolResults.map((r) => [r.toolCallId, r])
-        );
-
-        step.toolCalls.forEach((toolCall) => {
-          const toolResult = toolResultsByCallId.get(toolCall.toolCallId);
-          contentBlocks.push({
+        const outById = new Map(step.toolResults.map((r) => [r.toolCallId, r.output as Json]));
+        for (const call of step.toolCalls) {
+          blocks.push({
             type: "tool-call",
-            toolName: toolCall.toolName,
-            toolCallId: toolCall.toolCallId,
-            args: toolCall.input,
-            argsText: JSON.stringify(toolCall.input),
-            result: (toolResult?.output ?? null) as Json,
+            toolName: call.toolName,
+            toolCallId: call.toolCallId,
+            args: call.input as Json,
+            argsText: JSON.stringify(call.input),
+            result: outById.get(call.toolCallId) ?? null,
           });
-        });
+        }
+        return blocks;
       });
 
       let responseConversationId: string | undefined;
@@ -152,7 +136,7 @@ export const POST = createSmartRouteHandler({
           ? firstUserMessage.content
           : JSON.stringify(firstUserMessage?.content ?? "");
 
-        const innerToolCallsJson = JSON.stringify(contentBlocks.filter(b => b.type === "tool-call"));
+        const innerToolCallsJson = JSON.stringify(content.filter(b => b.type === "tool-call"));
 
         const logPromise = logMcpCall({
           correlationId,
@@ -183,7 +167,7 @@ export const POST = createSmartRouteHandler({
         statusCode: 200,
         bodyType: "json" as const,
         body: {
-          content: contentBlocks,
+          content,
           finalText: result.text,
           conversationId: responseConversationId ?? null,
         },