Skip to content

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

feat(ai-gateway): guided gateway setup (#19231)

Tobias Wochinger02a049ca44d6
diff --git a/packages/shared/package.json b/packages/shared/package.json
index 43b58ae294..97e2761de6 100644
--- a/packages/shared/package.json
+++ b/packages/shared/package.json
@@ -55,6 +55,10 @@
"import": "./dist/src/server/transcript/types.js",
"require": "./dist/src/server/transcript/types.js"
},
+ "./src/server/services/email/aiGatewayInvitation/GatewayInvitationEmailTemplate": {
+ "import": "./dist/src/server/services/email/aiGatewayInvitation/GatewayInvitationEmailTemplate.js",
+ "require": "./dist/src/server/services/email/aiGatewayInvitation/GatewayInvitationEmailTemplate.js"
+ },
"./src/server/clickhouse": {
"import": "./dist/src/server/clickhouse/index.js",
"require": "./dist/src/server/clickhouse/index.js"
diff --git a/packages/shared/src/server/index.ts b/packages/shared/src/server/index.ts
index 5fc71e3b6e..23187b079e 100644
--- a/packages/shared/src/server/index.ts
+++ b/packages/shared/src/server/index.ts
@@ -13,6 +13,7 @@ export * from "./services/BufferedStreamUploader";
export * from "./services/S3ChunkedUploadStrategy";
export * from "./services/email/transport";
export * from "./services/email/organizationInvitation/sendMembershipInvitationEmail";
+export * from "./services/email/getEmailAppBaseUrl";
export * from "./services/email/batchExportSuccess/sendBatchExportSuccessEmail";
export * from "./services/email/passwordReset/sendResetPasswordVerificationRequest";
export * from "./services/email/cloudSpendAlert/sendCloudSpendAlertEmail";
diff --git a/packages/shared/src/server/queues.ts b/packages/shared/src/server/queues.ts
index de728ba436..128421a447 100644
--- a/packages/shared/src/server/queues.ts
+++ b/packages/shared/src/server/queues.ts
@@ -288,6 +288,20 @@ export const NotificationEventSchema = z.discriminatedUnion("type", [
projectId: z.string(),
mentionedUserIds: z.array(z.string()),
}),
+ /** One AI Gateway invitation or announcement email, rendered as-is by the worker. */
+ z.object({
+ type: z.literal("AI_GATEWAY_INVITATION"),
+ orgId: z.string(),
+ orgName: z.string(),
+ to: z.string(),
+ receiverName: z.string().optional(),
+ audience: z.discriminatedUnion("kind", [
+ z.object({ kind: z.literal("invitee"), hasAccount: z.boolean() }),
+ z.object({ kind: z.literal("member") }),
+ ]),
+ inviterName: z.string(),
+ inviterEmail: z.string(),
+ }),
// Future notification types can be added here
]);
diff --git a/packages/shared/src/server/services/email/aiGatewayInvitation/GatewayInvitationEmailTemplate.tsx b/packages/shared/src/server/services/email/aiGatewayInvitation/GatewayInvitationEmailTemplate.tsx
new file mode 100644
index 0000000000..f6071808ad
--- /dev/null
+++ b/packages/shared/src/server/services/email/aiGatewayInvitation/GatewayInvitationEmailTemplate.tsx
@@ -0,0 +1,123 @@
+import * as React from "react";
+import {
+ Body,
+ Button,
+ Container,
+ Head,
+ Heading,
+ Hr,
+ Html,
+ Img,
+ Preview,
+ Section,
+ Tailwind,
+ Text,
+} from "@react-email/components";
+
+export type GatewayInvitationEmailAudience =
+ | { kind: "invitee"; hasAccount: boolean }
+ | { kind: "member" };
+
+type GatewayInvitationEmailTemplateProps = {
+ audience: GatewayInvitationEmailAudience;
+ inviterName: string;
+ inviterEmail: string;
+ orgName: string;
+ receiverEmail: string;
+ /** Greets the receiver by name when known. */
+ receiverName?: string;
+ link: string;
+ emailFromAddress: string;
+ langfuseCloudRegion?: string;
+};
+
+export const GatewayInvitationEmailTemplate = ({
+ audience,
+ inviterName,
+ inviterEmail,
+ orgName,
+ receiverEmail,
+ receiverName,
+ link,
+ emailFromAddress,
+ langfuseCloudRegion,
+}: GatewayInvitationEmailTemplateProps) => {
+ const isInvitee = audience.kind === "invitee";
+ const previewText = isInvitee
+ ? `${inviterName} invited you to the AI Gateway`
+ : `${inviterName} set up the AI Gateway for ${orgName}`;
+ const regionSuffix = langfuseCloudRegion
+ ? ` (${langfuseCloudRegion} data region)`
+ : "";
+
+ return (
+ <Html>
+ <Head />
+ <Preview>{previewText}</Preview>
+ <Tailwind>
+ <Body className="mx-auto my-auto bg-background font-sans">
+ <Container className="mx-auto my-10 w-[465px] rounded border border-solid border-[#eaeaea] p-5">
+ <Section className="mt-8">
+ <Img
+ src="https://static.langfuse.com/langfuse_logo_transactional_email.png"
+ width="40"
+ height="26"
+ alt="Langfuse"
+ className="mx-auto my-0"
+ />
+ </Section>
+ <Heading className="mx-0 my-[30px] p-0 text-center text-2xl font-normal text-black">
+ The <strong>AI Gateway</strong> is ready in{" "}
+ <strong>{orgName}</strong>
+ </Heading>
+ <Text className="text-sm leading-6 text-black">
+ {receiverName ? `Hello ${receiverName},` : "Hello,"}
+ </Text>
+ <Text className="text-sm leading-6 text-black">
+ <strong>{inviterName}</strong> (
+ <span className="text-blue-600 no-underline">{inviterEmail}</span>
+ ){" "}
+ {isInvitee
+ ? "invited you to use the AI Gateway in the "
+ : "set up the AI Gateway for the "}
+ <strong>{orgName}</strong> organization on Langfuse
+ {regionSuffix}.
+ </Text>
+ <Text className="text-sm leading-6 text-black">
+ One key for every model your team enabled. Create a gateway key
+ and call any of them through a single endpoint, with no provider
+ keys to collect or manage.
+ </Text>
+ <Section className="mb-4 mt-8 text-center">
+ {/* Note: link always refers to a root langfuse url and is not vulnerable to hyperlink injection attacks */}
+ <Button
+ className="rounded bg-black px-5 py-3 text-center text-xs font-semibold text-white no-underline"
+ href={link}
+ >
+ {isInvitee ? "Accept invitation" : "Create a gateway key"}
+ </Button>
+ {isInvitee ? (
+ <Text className="mt-2 text-xs leading-3 text-muted-foreground">
+ {audience.hasAccount
+ ? "(sign in with your existing account)"
+ : "(you need to create an account with this email address)"}
+ </Text>
+ ) : null}
+ </Section>
+ <Text className="text-sm leading-6 text-black">
+ or copy and paste this URL into your browser:{" "}
+ <span className="text-blue-600 no-underline">{link}</span>
+ </Text>
+ <Hr className="mx-0 my-[26px] w-full border border-solid border-[#eaeaea]" />
+ <Text className="text-xs leading-6 text-[#666666]">
+ This email was intended for{" "}
+ <span className="text-black">{receiverEmail}</span>. It was sent
+ from <span className="text-black">{emailFromAddress}</span>. If
+ you were not expecting it, you can ignore this email.
+ </Text>
+ </Container>
+ </Body>
+ </Tailwind>
+ </Html>
+ );
+};
diff --git a/packages/shared/src/server/services/email/getEmailAppBaseUrl.ts b/packages/shared/src/server/services/email/getEmailAppBaseUrl.ts
new file mode 100644
index 0000000000..3ed386e709
--- /dev/null
+++ b/packages/shared/src/server/services/email/getEmailAppBaseUrl.ts
@@ -0,0 +1,19 @@
+const langfuseCloudUrls = {
+ US: "https://us.cloud.langfuse.com",
+ EU: "https://cloud.langfuse.com",
+ STAGING: "https://staging.langfuse.com",
+ HIPAA: "https://hipaa.cloud.langfuse.com",
+ JP: "https://jp.cloud.langfuse.com",
+};
+
+/** Base URL for links in transactional emails: the cloud region's public URL, else NEXTAUTH_URL. */
+export function getEmailAppBaseUrl(env: {
+ NEXT_PUBLIC_LANGFUSE_CLOUD_REGION?: string;
+ NEXTAUTH_URL?: string;
+}): string | undefined {
+ const region = env.NEXT_PUBLIC_LANGFUSE_CLOUD_REGION;
+ if (region && region in langfuseCloudUrls) {
+ return langfuseCloudUrls[region as keyof typeof langfuseCloudUrls];
+ }
+ return env.NEXTAUTH_URL;
+}
diff --git a/packages/shared/src/server/services/email/organizationInvitation/sendMembershipInvitationEmail.ts b/packages/shared/src/server/services/email/organizationInvitation/sendMembershipInvitationEmail.ts
index 1031397695..3fa94f6a79 100644
--- a/packages/shared/src/server/services/email/organizationInvitation/sendMembershipInvitationEmail.ts
+++ b/packages/shared/src/server/services/email/organizationInvitation/sendMembershipInvitationEmail.ts
@@ -3,14 +3,7 @@ import { createMailTransport } from "../transport";
import { MembershipInvitationTemplate } from "./MembershipInvitationEmailTemplate";
import { logger } from "../../../logger";
-
-const langfuseUrls = {
- US: "https://us.cloud.langfuse.com",
- EU: "https://cloud.langfuse.com",
- STAGING: "https://staging.langfuse.com",
- HIPAA: "https://hipaa.cloud.langfuse.com",
- JP: "https://jp.cloud.langfuse.com",
-};
+import { getEmailAppBaseUrl } from "../getEmailAppBaseUrl";
type SendMembershipInvitationParams = {
env: Partial<
@@ -46,16 +39,7 @@ export const sendMembershipInvitationEmail = async ({
return;
}
- const getAuthURL = () =>
- env.NEXT_PUBLIC_LANGFUSE_CLOUD_REGION === "US" ||
- env.NEXT_PUBLIC_LANGFUSE_CLOUD_REGION === "EU" ||
- env.NEXT_PUBLIC_LANGFUSE_CLOUD_REGION === "HIPAA" ||
- env.NEXT_PUBLIC_LANGFUSE_CLOUD_REGION === "JP" ||
- env.NEXT_PUBLIC_LANGFUSE_CLOUD_REGION === "STAGING"
- ? langfuseUrls[env.NEXT_PUBLIC_LANGFUSE_CLOUD_REGION]
- : env.NEXTAUTH_URL;
-
- const authUrl = getAuthURL();
+ const authUrl = getEmailAppBaseUrl(env);
if (!authUrl) {
logger.error(
"Missing NEXTAUTH_URL or NEXT_PUBLIC_LANGFUSE_CLOUD_REGION environment variable.",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index aae608dd6b..25c4846deb 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -1194,6 +1194,9 @@ importers:
'@prisma/instrumentation':
specifier: ^6.19.3
version: 6.19.3(@opentelemetry/[email protected])([email protected])
+ '@react-email/render':
+ specifier: ^1.2.1
'@repo/langfuse-skills':
specifier: workspace:*
version: link:../packages/langfuse-skills
diff --git a/web/.storybook/main.ts b/web/.storybook/main.ts
index bf35821c38..61d51d04b2 100644
--- a/web/.storybook/main.ts
+++ b/web/.storybook/main.ts
@@ -150,6 +150,22 @@ const config: StorybookConfig = {
};
viteConfig.plugins = [
flatStoryTitlesPlugin(STORY_TITLE_GROUPS),
+ {
+ // The Next.js framework aliases `react-dom` by prefix, which turns this
+ // subpath (imported by @react-email/render in email template stories)
+ // into `react-dom/index.js/server.browser`. Its aliases are merged
+ // after viteFinal, so this rule has to be prepended once resolved.
+ name: "react-dom-server-browser-alias",
+ configResolved({ resolve }) {
+ resolve.alias.unshift({
+ find: /^react-dom\/server\.browser$/,
+ replacement: fileURLToPath(
+ import.meta
+ .resolve("next/dist/compiled/react-dom/server.browser.js"),
+ ),
+ });
+ },
+ },
...(viteConfig.plugins ?? []),
{
name: "exclude-generated-icons-from-docgen",
diff --git a/web/src/__tests__/organization-settings-pages.clienttest.tsx b/web/src/__tests__/organization-settings-pages.clienttest.tsx
index 5494b8ec05..0f3f081ea9 100644
--- a/web/src/__tests__/organization-settings-pages.clienttest.tsx
+++ b/web/src/__tests__/organization-settings-pages.clienttest.tsx
@@ -113,9 +113,8 @@ vi.mock("@/src/utils/api", () => ({
vi.mock("@/src/features/ai-gateway", () => ({
GatewayApiKeysPage: () => null,
- GatewayConfigurationPage: () => null,
GatewayModelsPage: () => null,
- GatewayProvidersPage: () => null,
+ GatewaySetupPage: () => null,
}));
const organization = {
@@ -275,7 +274,6 @@ describe("useOrganizationSettingsPages", () => {
expect(gatewayPages.map((page) => page.slug)).toEqual([
"ai-gateway",
- "ai-gateway-providers",
"ai-gateway-models",
"ai-gateway-api-keys",
]);
@@ -283,7 +281,7 @@ describe("useOrganizationSettingsPages", () => {
expect(gatewayPages.every((page) => !page.disabledReason)).toBe(true);
});
- it("disables every AI Gateway page except Configuration for managers until ingestion is set up", () => {
+ it("disables every AI Gateway page except Setup for managers until ingestion is set up", () => {
vi.mocked(useHasOrganizationAccess).mockImplementation(
({ scope }) =>
scope === "gateway:manage" ||
@@ -304,7 +302,6 @@ describe("useOrganizationSettingsPages", () => {
.map((page) => [page.slug, !!page.disabledReason]),
).toEqual([
["ai-gateway", false],
- ["ai-gateway-providers", true],
["ai-gateway-models", true],
["ai-gateway-api-keys", true],
]);
diff --git a/web/src/__tests__/server/ai-gateway-control-plane.servertest.ts b/web/src/__tests__/server/ai-gateway-control-plane.servertest.ts
index d12df0cbee..a2b7ce42ed 100644
--- a/web/src/__tests__/server/ai-gateway-control-plane.servertest.ts
+++ b/web/src/__tests__/server/ai-gateway-control-plane.servertest.ts
@@ -1,19 +1,41 @@
import { testFeatureFlags } from "@/src/__tests__/fixtures/feature-flags";
-import { generateKeyPairSync, randomUUID } from "node:crypto";
+import { createHash, generateKeyPairSync, randomUUID } from "node:crypto";
import type { Session } from "next-auth";
import { afterEach, describe, expect, it, vi } from "vitest";
import * as SharedServer from "@langfuse/shared/src/server";
import { z } from "zod/v4";
+const { addNotificationJobs, getNotificationJob } = vi.hoisted(() => ({
+ getNotificationJob: vi.fn<(jobId: string) => Promise<unknown>>(),
+ addNotificationJobs:
+ vi.fn<
+ (
+ jobs: Array<{ data: { payload: SharedServer.NotificationEventType } }>,
+ ) => Promise<unknown>
+ >(),
+}));
+
vi.mock("@langfuse/shared/src/server", async (importOriginal) => {
const actual = await importOriginal<typeof SharedServer>();
return {
...actual,
testModelCall: vi.fn().mockResolvedValue(undefined),
+ NotificationQueue: {
+ getInstance: () => ({
+ addBulk: addNotificationJobs,
+ getJob: getNotificationJob,
+ }),
+ },
};
});
+function queuedNotifications(): SharedServer.NotificationEventType[] {
+ return addNotificationJobs.mock.calls.flatMap(([jobs]) =>
+ jobs.map((job) => job.data.payload),
+ );
+}
+
import { env } from "@/src/env.mjs";
import { appRouter } from "@/src/server/api/root";
import {
@@ -21,6 +43,7 @@ import {
type OrgAuthedContext,
} from "@/src/server/api/trpc";
import { GATEWAY_CONNECTION_NAME_ERRORS } from "@/src/features/ai-gateway/constants/gatewayConnection";
+import { MAX_TEAM_INVITES } from "@/src/features/ai-gateway/constants/gatewayTeamInvites";
import { GatewayApiKeyAuthenticator } from "@/src/features/ai-gateway/server/auth/gatewayApiKeyAuthenticator";
import {
type GatewayResolveError,
@@ -48,6 +71,10 @@ const cleanupUsers: string[] = [];
const originalGatewayOrganizationAllowlist = [
...env.LANGFUSE_AI_GATEWAY_ORGANIZATION_ID_ALLOWLIST,
];
+const originalEmailConfig = {
+ smtpConnectionUrl: env.SMTP_CONNECTION_URL,
+ emailFromAddress: env.EMAIL_FROM_ADDRESS,
+};
const originalGatewayJwtConfig = {
privateKey: env.LANGFUSE_AI_GATEWAY_JWT_PRIVATE_KEY,
publicKey: env.LANGFUSE_AI_GATEWAY_JWT_PUBLIC_KEY,
@@ -103,6 +130,8 @@ afterEach(async () => {
LANGFUSE_AI_GATEWAY_JWT_KEY_ID: originalGatewayJwtConfig.keyId,
LANGFUSE_AI_GATEWAY_JWT_ISSUER: originalGatewayJwtConfig.issuer,
LANGFUSE_AI_GATEWAY_JWT_AUDIENCE: originalGatewayJwtConfig.audience,
+ SMTP_CONNECTION_URL: originalEmailConfig.smtpConnectionUrl,
+ EMAIL_FROM_ADDRESS: originalEmailConfig.emailFromAddress,
});
vi.clearAllMocks();
});
@@ -246,7 +275,7 @@ describe("AI gateway control plane", () => {
try {
await expect(
- caller.aiGateway.getConfig({ orgId: org.id }),
+ caller.aiGateway.getClientSetup({ orgId: org.id }),
).resolves.toMatchObject({ gatewayBaseUrl: gatewayUrl });
} finally {
(env as { NEXTAUTH_URL: string }).NEXTAUTH_URL = originalNextAuthUrl;
@@ -389,7 +418,7 @@ describe("AI gateway control plane", () => {
).rejects.toMatchObject({ code: "FORBIDDEN" });
});
- it("redirects gateway managers to Configuration until ingestion is set up", async () => {
+ it("redirects gateway managers to Setup until ingestion is set up", async () => {
const owner = await prepare();
const memberSession = {
...owner.session,
@@ -408,11 +437,11 @@ describe("AI gateway control plane", () => {
organizationId: owner.org.id,
slug,
});
- const configurationPath = `/organization/${owner.org.id}/settings/ai-gateway`;
+ const setupPath = `/organization/${owner.org.id}/settings/ai-gateway`;
await expect(
- redirectFor(owner.session, "ai-gateway-providers"),
- ).resolves.toBe(configurationPath);
+ redirectFor(owner.session, "ai-gateway-api-keys"),
+ ).resolves.toBe(setupPath);
await expect(redirectFor(owner.session, "ai-gateway")).resolves.toBeNull();
await expect(
redirectFor(memberSession, "ai-gateway-models"),
@@ -424,10 +453,194 @@ describe("AI gateway control plane", () => {
ingestionMode: "USAGE",
});
await expect(
- redirectFor(owner.session, "ai-gateway-providers"),
+ redirectFor(owner.session, "ai-gateway-api-keys"),
).resolves.toBeNull();
});
+ it("notifies only members who can use the gateway", async () => {
+ const owner = await prepare();
+ Object.assign(env, {
+ SMTP_CONNECTION_URL: "smtp://localhost:1025",
+ EMAIL_FROM_ADDRESS: "[email protected]",
+ });
+ await createCallerForOrganizationRole(owner, Role.MEMBER);
+ await createCallerForOrganizationRole(owner, Role.VIEWER);
+ await owner.caller.aiGateway.updateConfig({
+ orgId: owner.org.id,
+ defaultIngestionProjectId: owner.project.id,
+ ingestionMode: "USAGE",
+ });
+ const memberEmails = await prisma.organizationMembership.findMany({
+ where: { orgId: owner.org.id, role: Role.MEMBER },
+ select: { user: { select: { email: true } } },
+ });
+
+ const notifiableMembers = await owner.caller.aiGateway.getNotifiableMembers(
+ {
+ orgId: owner.org.id,
+ },
+ );
+ expect(notifiableMembers).toMatchObject({
+ isEmailConfigured: true,
+ count: 1,
+ });
+
+ const inviteeEmail = `gateway-invitee-${randomUUID()}@example.test`;
+ const result = await owner.caller.aiGateway.inviteTeam({
+ orgId: owner.org.id,
+ emails: [inviteeEmail],
+ notifyMembers: true,
+ });
+ expect(result).toEqual({ invitedCount: 1, failed: [], notifiedCount: 1 });
+
+ expect(queuedNotifications()).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({
+ type: "AI_GATEWAY_INVITATION",
+ to: inviteeEmail,
+ audience: { kind: "invitee", hasAccount: false },
+ }),
+ expect.objectContaining({
+ type: "AI_GATEWAY_INVITATION",
+ to: memberEmails[0]?.user.email?.toLowerCase(),
+ audience: { kind: "member" },
+ inviterName: "Gateway tester",
+ }),
+ ]),
+ );
+ expect(queuedNotifications()).toHaveLength(2);
+ await expect(
+ prisma.membershipInvitation.findFirst({
+ where: { orgId: owner.org.id, email: inviteeEmail },
+ select: { orgRole: true },
+ }),
+ ).resolves.toEqual({ orgRole: Role.MEMBER });
+ });
+
+ it.each([false, true])(
+ "announces the gateway once to a typed address of a member (notifyMembers: %s)",
+ async (notifyMembers) => {
+ const owner = await prepare();
+ Object.assign(env, {
+ SMTP_CONNECTION_URL: "smtp://localhost:1025",
+ EMAIL_FROM_ADDRESS: "[email protected]",
+ });
+ await createCallerForOrganizationRole(owner, Role.MEMBER);
+ const membership = await prisma.organizationMembership.findFirstOrThrow({
+ where: { orgId: owner.org.id, role: Role.MEMBER },
+ select: { user: { select: { email: true } } },
+ });
+ const memberEmail = membership.user.email!;
+
+ const result = await owner.caller.aiGateway.inviteTeam({
+ orgId: owner.org.id,
+ emails: [memberEmail.toUpperCase()],
+ notifyMembers,
+ });
+
+ expect(result).toEqual({
+ invitedCount: 0,
+ failed: [],
+ notifiedCount: 1,
+ });
+ expect(queuedNotifications()).toEqual([
+ expect.objectContaining({
+ audience: { kind: "member" },
+ to: memberEmail.toLowerCase(),
+ receiverName: "Gateway member",
+ }),
+ ]);
+ },
+ );
+
+ it("re-sends an email whose earlier job failed", async () => {
+ const owner = await prepare();
+ Object.assign(env, {
+ SMTP_CONNECTION_URL: "smtp://localhost:1025",
+ EMAIL_FROM_ADDRESS: "[email protected]",
+ });
+ await createCallerForOrganizationRole(owner, Role.MEMBER);
+ const membership = await prisma.organizationMembership.findFirstOrThrow({
+ where: { orgId: owner.org.id, role: Role.MEMBER },
+ select: { user: { select: { email: true } } },
+ });
+ const memberEmail = membership.user.email!.toLowerCase();
+ const removeFailedJob = vi.fn().mockResolvedValue(undefined);
+ getNotificationJob.mockResolvedValueOnce({
+ isFailed: () => Promise.resolve(true),
+ remove: removeFailedJob,
+ });
+
+ await owner.caller.aiGateway.inviteTeam({
+ orgId: owner.org.id,
+ emails: [memberEmail],
+ notifyMembers: false,
+ });
+
+ expect(getNotificationJob).toHaveBeenCalledWith(
+ `ai-gateway-invitation-${owner.org.id}-member-${createHash("sha256").update(memberEmail).digest("hex")}`,
+ );
+ expect(removeFailedJob).toHaveBeenCalledOnce();
+ expect(removeFailedJob.mock.invocationCallOrder[0]).toBeLessThan(
+ addNotificationJobs.mock.invocationCallOrder[0]!,
+ );
+ });
+
+ it("reports typed members who cannot use the gateway and skips the sender", async () => {
+ const owner = await prepare();
+ Object.assign(env, {
+ SMTP_CONNECTION_URL: "smtp://localhost:1025",
+ EMAIL_FROM_ADDRESS: "[email protected]",
+ });
+ await createCallerForOrganizationRole(owner, Role.VIEWER);
+ const membership = await prisma.organizationMembership.findFirstOrThrow({
+ where: { orgId: owner.org.id, role: Role.VIEWER },
+ select: { user: { select: { email: true } } },
+ });
+ const viewerEmail = membership.user.email!;
+
+ const result = await owner.caller.aiGateway.inviteTeam({
+ orgId: owner.org.id,
+ emails: [viewerEmail, owner.user.email!],
+ notifyMembers: false,
+ });
+
+ expect(result).toEqual({
+ invitedCount: 0,
+ failed: [
+ {
+ email: viewerEmail,
+ message: "Already a member, but their role can't use the AI Gateway",
+ },
+ ],
+ notifiedCount: 0,
+ });
+ expect(queuedNotifications()).toEqual([]);
+ });
+
+ it("rejects more than MAX_TEAM_INVITES addresses in one request", async () => {
+ const owner = await prepare();
+ Object.assign(env, {
+ SMTP_CONNECTION_URL: "smtp://localhost:1025",
+ EMAIL_FROM_ADDRESS: "[email protected]",
+ });
+
+ await expect(
+ owner.caller.aiGateway.inviteTeam({
+ orgId: owner.org.id,
+ emails: Array.from(
+ { length: MAX_TEAM_INVITES + 1 },
+ (_, index) => `gateway-invitee-${index}@example.test`,
+ ),
+ notifyMembers: false,
+ }),
+ ).rejects.toMatchObject({ code: "BAD_REQUEST" });
+ expect(queuedNotifications()).toEqual([]);
+ await expect(
+ prisma.membershipInvitation.count({ where: { orgId: owner.org.id } }),
+ ).resolves.toBe(0);
+ });
+
it("requires an ingestion project unless ingestion mode is NONE, also on cloud", async () => {
const { caller, org } = await prepare();
const originalCloudRegion = env.NEXT_PUBLIC_LANGFUSE_CLOUD_REGION;
diff --git a/web/src/components/design-system/Avatar/Avatar.stories.tsx b/web/src/components/design-system/Avatar/Avatar.stories.tsx
index 24326b6192..7aab0bb079 100644
--- a/web/src/components/design-system/Avatar/Avatar.stories.tsx
+++ b/web/src/components/design-system/Avatar/Avatar.stories.tsx
@@ -36,6 +36,13 @@ export const Fallback = meta.story({
},
});
+export const TintedFallback = meta.story({
+ args: {
+ displayName: "Ben Bachem",
+ tone: "tinted",
+ },
+});
+
export const WithEmail = meta.story({
args: {
displayName: "Ada Lovelace",
diff --git a/web/src/components/design-system/Avatar/Avatar.tsx b/web/src/components/design-system/Avatar/Avatar.tsx
index 3948857212..c30d608a27 100644
--- a/web/src/components/design-system/Avatar/Avatar.tsx
+++ b/web/src/components/design-system/Avatar/Avatar.tsx
@@ -5,6 +5,7 @@ import * as AvatarPrimitive from "@radix-ui/react-avatar";
import { cva, type VariantProps } from "class-variance-authority";
import { Tooltip } from "@/src/components/design-system/Tooltip/Tooltip";
+import { cn } from "@/src/utils/tailwind";
const avatarVariants = cva("relative flex shrink-0 overflow-hidden", {
variants: {
@@ -24,6 +25,22 @@ const avatarVariants = cva("relative flex shrink-0 overflow-hidden", {
},
});
+const tintedFallbackClasses = [
+ "bg-light-blue text-dark-blue",
+ "bg-light-green text-dark-green",
+ "bg-light-yellow text-dark-yellow",
+ "bg-light-violet text-dark-violet",
+];
+
+/** Stable per name, so the same person keeps their color across renders. */
+function tintedFallbackClass(seed: string) {
+ let hash = 0;
+ for (const char of seed) {
+ hash = (hash * 31 + char.charCodeAt(0)) % 1_000_003;
+ }
+ return tintedFallbackClasses[hash % tintedFallbackClasses.length];
+}
+
type AvatarProps = {
"aria-hidden"?: boolean | "true" | "false";
displayName: string;
@@ -34,6 +51,8 @@ type AvatarProps = {
*/
email?: string;
src?: string;
+ /** `tinted` colors the initials fallback per person, e.g. in avatar stacks. */
+ tone?: "muted" | "tinted";
} & VariantProps<typeof avatarVariants>;
function avatarHoverLabel(displayName: string, email?: string) {
@@ -48,7 +67,7 @@ function avatarHoverLabel(displayName: string, email?: string) {
const Avatar = React.forwardRef<
React.ComponentRef<typeof AvatarPrimitive.Root>,
AvatarProps
->(({ src, displayName, email, size, shape, ...props }, ref) => {
+>(({ src, displayName, email, size, shape, tone = "muted", ...props }, ref) => {
const hoverLabel = avatarHoverLabel(displayName, email);
const accessibleName = hoverLabel.split("\n").join(", ");
const normalizedDisplayName = displayName.trim() || email?.trim() || "User";
@@ -83,7 +102,14 @@ const Avatar = React.forwardRef<
className="aspect-square h-full w-full"
/>
) : null}
- <AvatarPrimitive.Fallback className="bg-muted flex h-full w-full items-center justify-center rounded-[inherit]">
+ <AvatarPrimitive.Fallback
+ className={cn(
+ "flex h-full w-full items-center justify-center rounded-[inherit]",
+ tone === "tinted"
+ ? tintedFallbackClass(normalizedDisplayName)
+ : "bg-muted",
+ )}
+ >
{initials}
</AvatarPrimitive.Fallback>
</AvatarPrimitive.Root>
diff --git a/web/src/components/design-system/Input/Input.stories.tsx b/web/src/components/design-system/Input/Input.stories.tsx
index 8ac2d83669..c194da39d5 100644
--- a/web/src/components/design-system/Input/Input.stories.tsx
+++ b/web/src/components/design-system/Input/Input.stories.tsx
@@ -38,6 +38,22 @@ export const Disabled = meta.story({
},
});
+export const Inline = meta.story({
+ args: {
+ "aria-label": "Project name",
+ defaultValue: "ai-gateway",
+ layout: "inline",
+ },
+ render: (args) => (
+ <p className="flex items-center gap-2 text-sm">
+ Record in a new project named
+ <span className="w-fit">
+ <Input {...args} />
+ </span>
+ </p>
+ ),
+});
+
export const TestAcceptsText = meta.story({
name: "(Test) Accepts Text",
args: {
diff --git a/web/src/components/design-system/Input/Input.tsx b/web/src/components/design-system/Input/Input.tsx
index 6b922bc99f..aeb3cb7e7b 100644
--- a/web/src/components/design-system/Input/Input.tsx
+++ b/web/src/components/design-system/Input/Input.tsx
@@ -35,12 +35,18 @@ type InputProps = Pick<
> & {
allowPasswordManager?: boolean;
error?: boolean;
+ /**
+ * `inline` sits within a sentence and grows and shrinks with its value;
+ * place it in a `w-fit` container.
+ */
+ layout?: "block" | "inline";
ref?: Ref<HTMLInputElement>;
};
export function Input({
allowPasswordManager,
error,
+ layout = "block",
ref,
...props
}: InputProps) {
@@ -48,6 +54,7 @@ export function Input({
<InputControl contentLayout="text" error={error}>
<input
{...props}
+ className={layout === "inline" ? "field-sizing-content" : undefined}
{...(!allowPasswordManager && { "data-1p-ignore": true })}
ref={ref}
/>
diff --git a/web/src/components/design-system/Stepper/Stepper.stories.tsx b/web/src/components/design-system/Stepper/Stepper.stories.tsx
index 92ef1d5d5f..f78124b552 100644
--- a/web/src/components/design-system/Stepper/Stepper.stories.tsx
+++ b/web/src/components/design-system/Stepper/Stepper.stories.tsx
@@ -56,6 +56,36 @@ export const OutlineStatic = meta.story({
),
});
+export const Statuses = meta.story({
+ render: () => (
+ <div className="flex max-w-xl flex-col">
+ <Stepper
+ number={1}
+ title="Choose how traffic is recorded"
+ status="complete"
+ size="sm"
+ isCollapsible={false}
+ description="Recording usage only"
+ />
+ <Stepper
+ number={2}
+ title="Add a provider credential"
+ size="sm"
+ isCollapsible={false}
+ >
+ <div className="rounded-md border p-3 text-sm">Add credential</div>
+ </Stepper>
+ <Stepper
+ number={3}
+ title="Invite your team"
+ status="upcoming"
+ size="sm"
+ isCollapsible={false}
+ />
+ </div>
+ ),
+});
+
export const MultiStep = meta.story({
render: () => (
<div className="flex max-w-xl flex-col">
diff --git a/web/src/components/design-system/Stepper/Stepper.tsx b/web/src/components/design-system/Stepper/Stepper.tsx
index ba3b330bdb..b7d7e4603b 100644
--- a/web/src/components/design-system/Stepper/Stepper.tsx
+++ b/web/src/components/design-system/Stepper/Stepper.tsx
@@ -1,6 +1,6 @@
import { useState, type ReactNode } from "react";
import { cva } from "class-variance-authority";
-import { ChevronDown } from "@langfuse/icons";
+import { Check, ChevronDown } from "@langfuse/icons";
import { cn } from "@/src/utils/tailwind";
@@ -17,6 +17,11 @@ const markerVariants = cva(
default: "size-7 text-sm",
sm: "size-5 text-xs",
},
+ status: {
+ current: null,
+ complete: null,
+ upcoming: "bg-background text-muted-foreground border-border border",
+ },
},
},
);
@@ -36,6 +41,11 @@ const titleVariants = cva("font-bold", {
default: "text-lg",
sm: "text-sm",
},
+ status: {
+ current: null,
+ complete: null,
+ upcoming: "text-muted-foreground",
+ },
},
});
@@ -54,8 +64,10 @@ type StepperProps = {
description?: ReactNode;
variant?: "filled" | "outline";
size?: "default" | "sm";
+ /** Complete swaps the number for a check; upcoming mutes the step. */
+ status?: "current" | "complete" | "upcoming";
compactBottomSpacing?: boolean;
- children: ReactNode;
+ children?: ReactNode;
} & (
| {
/** Toggles the body from the step header; on by default. */
@@ -85,6 +97,7 @@ export function Stepper({
description,
variant = "filled",
size = "default",
+ status = "current",
compactBottomSpacing = false,
isCollapsible = true,
defaultOpen = true,
@@ -94,6 +107,7 @@ export function Stepper({
}: StepperProps) {
const [internalOpen, setInternalOpen] = useState(defaultOpen);
const expanded = !isCollapsible || (open ?? internalOpen);
+ const hasBody = Boolean(description) || Boolean(children);
const toggle = () => {
const nextOpen = !expanded;
@@ -104,7 +118,13 @@ export function Stepper({
return (
<div className="group/step flex gap-1.5">
<div className="flex flex-col items-center">
- <div className={markerVariants({ variant, size })}>{number}</div>
+ <div className={cn(markerVariants({ variant, size, status }))}>
+ {status === "complete" ? (
+ <Check size="sm" aria-label="Completed" />
+ ) : (
+ number
+ )}
+ </div>
<div className="bg-border my-1 w-px flex-1 group-last/step:hidden" />
</div>
@@ -130,14 +150,14 @@ export function Stepper({
!expanded && "-rotate-90",
)}
/>
- <span className={titleVariants({ size })}>{title}</span>
+ <span className={titleVariants({ size, status })}>{title}</span>
</button>
) : (
<div className={headerVariants({ size })}>
- <span className={titleVariants({ size })}>{title}</span>
+ <span className={titleVariants({ size, status })}>{title}</span>
</div>
)}
- {expanded && (
+ {expanded && hasBody ? (
<div
className={cn(
"flex flex-col",
@@ -149,7 +169,7 @@ export function Stepper({
) : null}
{children}
</div>
- )}
+ ) : null}
</div>
</div>
);
diff --git a/web/src/features/ai-gateway/components/GatewayApiKeysPage/GatewayApiKeysPage.tsx b/web/src/features/ai-gateway/components/GatewayApiKeysPage/GatewayApiKeysPage.tsx
index 8c107dcaec..71d116ce6d 100644
--- a/web/src/features/ai-gateway/components/GatewayApiKeysPage/GatewayApiKeysPage.tsx
+++ b/web/src/features/ai-gateway/components/GatewayApiKeysPage/GatewayApiKeysPage.tsx
@@ -17,7 +17,7 @@ export function GatewayApiKeysPage({
if (isSetupStatusPending) {
return <ApiKeysSkeleton />;
}
- /** Managers are redirected to Configuration by the settings route. */
+ /** Managers are redirected to Setup by the settings route. */
if (!canManageGateway && isIngestionConfigured === false) {
return <GatewayNotSetUpNotice title="Gateway API keys" />;
}
diff --git a/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/GeneratedKeyContent/GeneratedKeyContent.tsx b/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/GeneratedKeyContent/GeneratedKeyContent.tsx
index 0cebcf98a3..fd3012cfd0 100644
--- a/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/GeneratedKeyContent/GeneratedKeyContent.tsx
+++ b/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/GeneratedKeyContent/GeneratedKeyContent.tsx
@@ -52,16 +52,23 @@ function SetupInstructions({ organizationId }: SetupInstructionsProps) {
return (
<div className="flex flex-col gap-2">
- <div className="flex items-baseline gap-1">
+ <div className="flex flex-col gap-1">
<h3 className="font-bold">Usage instructions</h3>
- {activeEntry ? (
- <Button
- variant="text"
- size="sm"
- text="Docs"
- href={activeEntry.docsUrl}
- />
- ) : null}
+ <p className="text-muted-foreground">
+ Call the gateway from your code or connect an AI tool to it. Each tab
+ has the steps for one tool.{" "}
+ {activeEntry ? (
+ <Button
+ variant="text"
+ text={
+ activeEntry.id === "api"
+ ? "How to call the gateway API"
+ : `How to connect ${activeEntry.label}`
+ }
+ href={activeEntry.docsUrl}
+ />
+ ) : null}
+ </p>
</div>
<Tabs value={activeTab} onValueChange={setActiveTab}>
<div className="flex h-9 items-center border-b">
diff --git a/web/src/features/ai-gateway/components/GatewayConfigurationPage/GatewayConfigurationPage.tsx b/web/src/features/ai-gateway/components/GatewayConfigurationPage/GatewayConfigurationPage.tsx
deleted file mode 100644
index a9e21cee31..0000000000
--- a/web/src/features/ai-gateway/components/GatewayConfigurationPage/GatewayConfigurationPage.tsx
+++ /dev/null
@@ -1,137 +0,0 @@
-/* eslint-disable @typescript-eslint/no-use-before-define */
-import { useSession } from "next-auth/react";
-
-import Header from "@/src/components/layouts/header";
-import { Alert } from "@/src/components/design-system/Alert/Alert";
-import { Button } from "@/src/components/ui/button";
-import { Skeleton } from "@/src/components/ui/skeleton";
-import {
- GatewayConfigurationView,
- type IngestionMode,
-} from "@/src/features/ai-gateway/components/GatewayConfigurationPage/components/GatewayConfigurationView/GatewayConfigurationView";
-import { showSuccessToast } from "@/src/features/notifications";
-import { api, reportNonTrpcError } from "@/src/utils/api";
-
-type Project = {
- id: string;
- name: string;
- deletedAt?: Date | string | null;
-};
-
-export function GatewayConfigurationPage({
- organizationId,
- projects,
-}: {
- organizationId: string;
- projects: Project[];
-}) {
- const session = useSession();
- const configQuery = api.aiGateway.getConfig.useQuery({
- orgId: organizationId,
- });
- const utils = api.useUtils();
- const createProject = api.projects.create.useMutation();
- const updateConfig = api.aiGateway.updateConfig.useMutation();
-
- async function saveGatewayConfig(params: {
- projectId: string | null;
- ingestionMode: IngestionMode;
- }) {
- await updateConfig.mutateAsync({
- orgId: organizationId,
- defaultIngestionProjectId: params.projectId,
- ingestionMode: params.ingestionMode,
- });
- await Promise.all([
- utils.aiGateway.getConfig.invalidate({ orgId: organizationId }),
- utils.aiGateway.getSetupStatus.invalidate({ orgId: organizationId }),
- ]);
- showSuccessToast({
- operation: "gateway_configuration.save",
- title: "Gateway configuration saved",
- description: "New gateway requests will use this configuration.",
- });
- }
-
- if (configQuery.isPending) {
- return <ConfigurationSkeleton />;
- }
-
- if (configQuery.isError) {
- return (
- <div className="flex flex-col gap-4">
- <Header title="AI Gateway configuration" />
- <Alert variant="destructive">
- <Alert.Title>Configuration could not be loaded</Alert.Title>
- <Alert.Description>
- Retry the request to continue configuring the gateway.
- </Alert.Description>
- </Alert>
- <Button
- className="w-fit"
- variant="secondary"
- onClick={() => configQuery.refetch()}
- >
- Retry
- </Button>
- </div>
- );
- }
-
- const { config, gatewayBaseUrl } = configQuery.data;
- const initialIngestionMode = config?.ingestionMode ?? "USAGE";
-
- async function handleCreateProject(params: {
- projectName: string;
- ingestionMode: IngestionMode;
- }) {
- try {
- const project = await createProject.mutateAsync({
- orgId: organizationId,
- name: params.projectName,
- });
- await session.update();
- await saveGatewayConfig({
- projectId: project.id,
- ingestionMode: params.ingestionMode,
- });
- } catch (error) {
- reportNonTrpcError(error, "ai-gateway-configuration");
- }
- }
-
- return (
- <GatewayConfigurationView
- key={`${config?.updatedAt?.toISOString() ?? "new"}:${config?.defaultIngestionProjectId ?? "none"}:${initialIngestionMode}`}
- projects={projects}
- gatewayBaseUrl={gatewayBaseUrl}
- initialProjectId={config?.defaultIngestionProjectId ?? null}
- initialIngestionMode={initialIngestionMode}
- isSaving={createProject.isPending || updateConfig.isPending}
- saveError={createProject.isError || updateConfig.isError}
- onSave={async ({ projectId, ingestionMode }) => {
- try {
- await saveGatewayConfig({ projectId, ingestionMode });
- } catch (error) {
- reportNonTrpcError(error, "ai-gateway-configuration");
- }
- }}
- onCreateProject={handleCreateProject}
- />
- );
-}
-
-function ConfigurationSkeleton() {
- return (
- <div className="flex flex-col gap-6" data-testid="gateway-config-loading">
- <Skeleton className="h-7 w-64" />
- <Skeleton className="h-32 w-full" />
- <Skeleton className="h-40 w-full" />
- <div className="grid gap-3 md:grid-cols-3">
- <Skeleton className="h-36" />
- <Skeleton className="h-36" />
- <Skeleton className="h-36" />
- </div>
- </div>
- );
-}
diff --git a/web/src/features/ai-gateway/components/GatewayConfigurationPage/components/CreateIngestionProjectDialogController/CreateIngestionProjectDialogController.tsx b/web/src/features/ai-gateway/components/GatewayConfigurationPage/components/CreateIngestionProjectDialogController/CreateIngestionProjectDialogController.tsx
deleted file mode 100644
index 327e3d3597..0000000000
--- a/web/src/features/ai-gateway/components/GatewayConfigurationPage/components/CreateIngestionProjectDialogController/CreateIngestionProjectDialogController.tsx
+++ /dev/null
@@ -1,113 +0,0 @@
-/* eslint-disable @typescript-eslint/no-use-before-define */
-import { useId, type ReactNode } from "react";
-import { zodResolver } from "@hookform/resolvers/zod";
-import { useForm } from "react-hook-form";
-import * as z from "zod";
-
-import { Dialog } from "@/src/components/design-system/Dialog/Dialog";
-import { DialogController } from "@/src/components/design-system/DialogController/DialogController";
-import { FormField } from "@/src/components/design-system/FormField/FormField";
-import { Input } from "@/src/components/design-system/Input/Input";
-import { DEFAULT_GATEWAY_INGESTION_PROJECT_NAME } from "@/src/features/ai-gateway/constants/gatewayConfig";
-import type { GatewayIngestionMode } from "@langfuse/shared";
-
-const createIngestionProjectSchema = z.object({
- projectName: z.string().trim().min(1, "Enter a project name."),
-});
-
-export type CreateIngestionProjectDialogControllerProps = {
- ingestionMode: GatewayIngestionMode;
- isSaving: boolean;
- onCreate: (values: {
- projectName: string;
- ingestionMode: GatewayIngestionMode;
- }) => void | Promise<void>;
- children: (control: { openDialog: () => void }) => ReactNode;
-};
-
-export function CreateIngestionProjectDialogController({
- ingestionMode,
- isSaving,
- onCreate,
- children,
-}: CreateIngestionProjectDialogControllerProps) {
- function handleBeforeClose() {
- return !isSaving;
- }
-
- return (
- <DialogController
- onBeforeClose={handleBeforeClose}
- renderDialog={() => (
- <CreateIngestionProjectDialog
- ingestionMode={ingestionMode}
- isSaving={isSaving}
- onCreate={onCreate}
- />
- )}
- >
- {children}
- </DialogController>
- );
-}
-
-function CreateIngestionProjectDialog({
- ingestionMode,
- isSaving,
- onCreate,
-}: Omit<CreateIngestionProjectDialogControllerProps, "children">) {
- const formId = useId();
- const form = useForm<CreateIngestionProjectValues>({
- resolver: zodResolver(createIngestionProjectSchema),
- defaultValues: { projectName: DEFAULT_GATEWAY_INGESTION_PROJECT_NAME },
- });
-
- function handleSubmit({ projectName }: CreateIngestionProjectValues) {
- return onCreate({ projectName, ingestionMode });
- }
-
- return (
- <Dialog
- title="Create ingestion project"
- actions={[
- {
- label: "Create project",
- type: "submit",
- form: formId,
- loading: isSaving,
- disabled: isSaving,
- },
- ]}
- >
- <form id={formId} onSubmit={form.handleSubmit(handleSubmit)}>
- <Dialog.Body>
- <FormField
- control={form.control}
- name="projectName"
- label="Project name"
- description="Project access follows organization roles and can be restricted in project settings."
- >
- {({ error, id, inputDescribedById, ...field }) => (
- <div className="ph-no-capture">
- <Input
- id={id}
- name={field.name}
- value={field.value}
- onChange={field.onChange}
- onBlur={field.onBlur}
- ref={field.ref}
- error={error !== undefined}
- aria-describedby={inputDescribedById}
- />
- </div>
- )}
- </FormField>
- </Dialog.Body>
- </form>
- </Dialog>
- );
-}
-
-type CreateIngestionProjectValues = z.infer<
- typeof createIngestionProjectSchema
->;
diff --git a/web/src/features/ai-gateway/components/GatewayConfigurationPage/components/GatewayConfigurationView/GatewayConfigurationView.stories.tsx b/web/src/features/ai-gateway/components/GatewayConfigurationPage/components/GatewayConfigurationView/GatewayConfigurationView.stories.tsx
deleted file mode 100644
index e3face3286..0000000000
--- a/web/src/features/ai-gateway/components/GatewayConfigurationPage/components/GatewayConfigurationView/GatewayConfigurationView.stories.tsx
+++ /dev/null
@@ -1,38 +0,0 @@
-import type { ComponentProps } from "react";
-import { fn } from "storybook/test";
-
-import preview from "@/.storybook/preview";
-import { GatewayConfigurationView } from "./GatewayConfigurationView";
-
-const meta = preview.meta({ component: GatewayConfigurationView });
-
-const projects = [
- { id: "project-production", name: "Production", deletedAt: null },
- { id: "project-staging", name: "Staging", deletedAt: null },
-] satisfies ComponentProps<typeof GatewayConfigurationView>["projects"];
-
-export const Enabled = meta.story({
- args: {
- projects,
- gatewayBaseUrl: "https://gateway.staging.langfuse.com/v1",
- initialProjectId: "project-production",
- initialIngestionMode: "USAGE",
- isSaving: false,
- saveError: false,
- onSave: fn(),
- onCreateProject: fn(),
- },
-});
-
-export const MissingProjectWarning = meta.story({
- args: {
- projects,
- gatewayBaseUrl: "https://gateway.staging.langfuse.com/v1",
- initialProjectId: "deleted-project",
- initialIngestionMode: "FULL",
- isSaving: false,
- saveError: false,
- onSave: fn(),
- onCreateProject: fn(),
- },
-});
diff --git a/web/src/features/ai-gateway/components/GatewayConfigurationPage/components/GatewayConfigurationView/GatewayConfigurationView.tsx b/web/src/features/ai-gateway/components/GatewayConfigurationPage/components/GatewayConfigurationView/GatewayConfigurationView.tsx
deleted file mode 100644
index c627ec48c1..0000000000
--- a/web/src/features/ai-gateway/components/GatewayConfigurationPage/components/GatewayConfigurationView/GatewayConfigurationView.tsx
+++ /dev/null
@@ -1,281 +0,0 @@
-/* eslint-disable @typescript-eslint/no-use-before-define */
-import { useState } from "react";
-import {
- Check,
- Copy,
- EyeOff,
- Gauge,
- Plus,
- ScanText,
- type IconComponent,
-} from "@langfuse/icons";
-
-import Header from "@/src/components/layouts/header";
-import { Alert } from "@/src/components/design-system/Alert/Alert";
-import { Button } from "@/src/components/ui/button";
-import { CardDescription, CardTitle } from "@/src/components/ui/card";
-import {
- Select,
- SelectContent,
- SelectItem,
- SelectTrigger,
- SelectValue,
-} from "@/src/components/ui/select";
-import { Button as DesignSystemButton } from "@/src/components/design-system/Button/Button";
-import { CreateIngestionProjectDialogController } from "@/src/features/ai-gateway/components/GatewayConfigurationPage/components/CreateIngestionProjectDialogController/CreateIngestionProjectDialogController";
-import {
- GATEWAY_CONFIGURATION_DESCRIPTION,
- GATEWAY_CONFIGURATION_TITLE,
-} from "@/src/features/ai-gateway/constants/gatewayConfig";
-import { isGatewayIngestionConfigured } from "@/src/features/ai-gateway/fns/isGatewayIngestionConfigured";
-import { useCopyToClipboard } from "@/src/hooks/useCopyToClipboard";
-import { cn } from "@/src/utils/tailwind";
-
-export type IngestionMode = "NONE" | "USAGE" | "FULL";
-type Project = {
- id: string;
- name: string;
- deletedAt?: Date | string | null;
-};
-
-const ingestionModes: Array<{
- value: IngestionMode;
- title: string;
- description: string;
- icon: IconComponent;
-}> = [
- {
- value: "NONE",
- title: "None",
- description: "Route requests without capturing anything in Langfuse.",
- icon: EyeOff,
- },
- {
- value: "USAGE",
- title: "Usage",
- description: "Capture model, token usage, cost, and latency.",
- icon: Gauge,
- },
- {
- value: "FULL",
- title: "Full",
- description: "Capture full request and response payloads for tracing.",
- icon: ScanText,
- },
-];
-
-export function GatewayConfigurationView({
- projects,
- gatewayBaseUrl,
- initialProjectId,
- initialIngestionMode,
- isSaving,
- saveError,
- onSave,
- onCreateProject,
-}: {
- projects: Project[];
- gatewayBaseUrl: string;
- initialProjectId: string | null;
- initialIngestionMode: IngestionMode;
- isSaving: boolean;
- saveError: boolean;
- onSave: (values: {
- projectId: string | null;
- ingestionMode: IngestionMode;
- }) => void | Promise<void>;
- onCreateProject: (values: {
- projectName: string;
- ingestionMode: IngestionMode;
- }) => void | Promise<void>;
-}) {
- const activeProjects = projects.filter((project) => !project.deletedAt);
- const initialProjectExists =
- initialProjectId !== null &&
- activeProjects.some((project) => project.id === initialProjectId);
- const [projectSelection, setProjectSelection] = useState<string | undefined>(
- initialProjectExists ? initialProjectId : undefined,
- );
- const [showExistingProjects, setShowExistingProjects] =
- useState(initialProjectExists);
- const [ingestionMode, setIngestionMode] =
- useState<IngestionMode>(initialIngestionMode);
- const projectId = projectSelection ?? null;
- const isDirty =
- projectId !== initialProjectId || ingestionMode !== initialIngestionMode;
- const isConfigured = isGatewayIngestionConfigured({
- ingestionMode,
- hasActiveIngestionProject: projectId !== null,
- });
-
- function handleUseExistingProject() {
- setShowExistingProjects(true);
- }
-
- return (
- <div className="flex flex-col gap-6">
- <div>
- <Header title={GATEWAY_CONFIGURATION_TITLE} />
- <p className="text-muted-foreground text-sm">
- {GATEWAY_CONFIGURATION_DESCRIPTION}
- </p>
- </div>
-
- <div>
- <div className="mb-4 flex flex-col gap-1">
- <CardTitle className="text-base">Gateway endpoint</CardTitle>
- <CardDescription>
- Use this fixed base URL in any supported SDK.
- </CardDescription>
- </div>
- <GatewayUrl gatewayBaseUrl={gatewayBaseUrl} />
- </div>
-
- <div>
- <CardTitle className="mb-4 text-base">
- Default ingestion project
- </CardTitle>
- {showExistingProjects ? (
- <div className="flex max-w-md flex-row flex-wrap items-center gap-2">
- <Select
- value={projectSelection}
- onValueChange={setProjectSelection}
- >
- <SelectTrigger className="ph-no-capture w-fit max-w-full">
- <SelectValue placeholder="Select a project" />
- </SelectTrigger>
- <SelectContent className="ph-no-capture">
- {activeProjects.map((project) => (
- <SelectItem key={project.id} value={project.id}>
- {project.name}
- </SelectItem>
- ))}
- </SelectContent>
- </Select>
- <CreateIngestionProjectDialogController
- ingestionMode={ingestionMode}
- isSaving={isSaving}
- onCreate={onCreateProject}
- >
- {({ openDialog }) => (
- <DesignSystemButton
- text="or create a new project"
- variant="text"
- onClick={openDialog}
- />
- )}
- </CreateIngestionProjectDialogController>
- </div>
- ) : (
- <div className="flex flex-row items-center gap-2">
- <CreateIngestionProjectDialogController
- ingestionMode={ingestionMode}
- isSaving={isSaving}
- onCreate={onCreateProject}
- >
- {({ openDialog }) => (
- <DesignSystemButton
- text="Create ingestion project"
- icon={Plus}
- onClick={openDialog}
- />
- )}
- </CreateIngestionProjectDialogController>
- <DesignSystemButton
- text="or use an existing project"
- variant="text"
- onClick={handleUseExistingProject}
- />
- </div>
- )}
- <p className="text-muted-foreground mt-2 text-xs">
- A dedicated project keeps gateway traffic separate from your
- application traces.
- </p>
- </div>
-
- <div>
- <CardTitle className="mb-4 text-base">Ingestion mode</CardTitle>
- <div className="grid gap-2 md:grid-cols-3">
- {ingestionModes.map((option) => {
- const Icon = option.icon;
- const selected = ingestionMode === option.value;
- return (
- <button
- key={option.value}
- type="button"
- aria-pressed={selected}
- onClick={() => setIngestionMode(option.value)}
- className={cn(
- "bg-card hover:bg-muted/50 flex flex-col items-start gap-2 rounded-md border p-3 text-left transition-colors",
- selected && "border-primary ring-primary ring-1",
- )}
- >
- <div className="flex w-full items-center justify-between gap-2">
- <Icon size="base" color="muted" />
- {selected ? (
- <Check size="base" __rawClassName="text-primary " />
- ) : null}
- </div>
- <div>
- <p className="text-sm font-bold">{option.title}</p>
- <p className="text-muted-foreground mt-0.5 text-xs">
- {option.description}
- </p>
- </div>
- </button>
- );
- })}
- </div>
- </div>
-
- {saveError ? (
- <Alert variant="destructive">
- <Alert.Title>Configuration was not saved</Alert.Title>
- <Alert.Description>
- Check your selections and try again.
- </Alert.Description>
- </Alert>
- ) : null}
-
- <div className="flex items-center justify-end gap-3">
- {isConfigured ? null : (
- <p className="text-destructive text-sm">
- Select an ingestion project, or choose None to route without
- capturing.
- </p>
- )}
- <Button
- disabled={!isDirty || !isConfigured || isSaving}
- loading={isSaving}
- onClick={() => onSave({ projectId, ingestionMode })}
- >
- Save
- </Button>
- </div>
- </div>
- );
-}
-
-function GatewayUrl({ gatewayBaseUrl }: { gatewayBaseUrl: string }) {
- const { copy, isCopied } = useCopyToClipboard();
- return (
- <div className="bg-muted flex w-fit max-w-full items-center justify-between gap-3 rounded-md border px-3 py-2">
- <code className="truncate text-sm" title={gatewayBaseUrl}>
- {gatewayBaseUrl}
- </code>
- <Button
- size="icon-xs"
- variant="ghost"
- aria-label="Copy gateway base URL"
- onClick={() => copy(gatewayBaseUrl)}
- >
- {isCopied ? (
- <Check size="sm" color="default" />
- ) : (
- <Copy size="sm" color="default" />
- )}
- </Button>
- </div>
- );
-}
diff --git a/web/src/features/ai-gateway/components/GatewayConnectionModelsPage/GatewayConnectionModelsPage.tsx b/web/src/features/ai-gateway/components/GatewayConnectionModelsPage/GatewayConnectionModelsPage.tsx
index 9114b8b7bb..d515158d6a 100644
--- a/web/src/features/ai-gateway/components/GatewayConnectionModelsPage/GatewayConnectionModelsPage.tsx
+++ b/web/src/features/ai-gateway/components/GatewayConnectionModelsPage/GatewayConnectionModelsPage.tsx
@@ -70,8 +70,8 @@ function ProviderCredentialsLink({
}) {
return (
<TextLink
- path={`/organization/${encodeURIComponent(organizationId)}/settings/ai-gateway-providers`}
- value="Provider credentials"
+ path={`/organization/${encodeURIComponent(organizationId)}/settings/ai-gateway`}
+ value="Gateway setup"
icon={ArrowLeft}
/>
);
diff --git a/web/src/features/ai-gateway/components/GatewayInvitationEmail/GatewayInvitationEmail.stories.tsx b/web/src/features/ai-gateway/components/GatewayInvitationEmail/GatewayInvitationEmail.stories.tsx
new file mode 100644
index 0000000000..f51190bc22
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewayInvitationEmail/GatewayInvitationEmail.stories.tsx
@@ -0,0 +1,45 @@
+import { GatewayInvitationEmailTemplate } from "@langfuse/shared/src/server/services/email/aiGatewayInvitation/GatewayInvitationEmailTemplate";
+import { renderToStaticMarkup } from "react-dom/server";
+
+import preview from "@/.storybook/preview";
+
+const gatewayKeysUrl =
+ "https://cloud.langfuse.com/organization/org-1/settings/ai-gateway-api-keys";
+
+const meta = preview.meta({
+ component: GatewayInvitationEmailTemplate,
+ args: {
+ inviterName: "Ada Lovelace",
+ inviterEmail: "[email protected]",
+ orgName: "Acme",
+ receiverEmail: "[email protected]",
+ link: gatewayKeysUrl,
+ emailFromAddress: "[email protected]",
+ langfuseCloudRegion: "EU",
+ },
+ // Emails render a full <html> document, so they need their own frame.
+ render: (args) => (
+ <iframe
+ title="Email preview"
+ srcDoc={renderToStaticMarkup(
+ <GatewayInvitationEmailTemplate {...args} />,
+ )}
+ className="h-[820px] w-full border-0"
+ />
+ ),
+});
+
+export const InviteeWithoutAccount = meta.story({
+ args: {
+ audience: { kind: "invitee", hasAccount: false },
+ link: `https://cloud.langfuse.com/auth/sign-up?targetPath=${encodeURIComponent("/organization/org-1/settings/ai-gateway-api-keys")}&email=${encodeURIComponent("[email protected]")}`,
+ },
+});
+
+export const InviteeWithAccount = meta.story({
+ args: { audience: { kind: "invitee", hasAccount: true } },
+});
+
+export const ExistingMember = meta.story({
+ args: { audience: { kind: "member" }, receiverName: "Grace Hopper" },
+});
diff --git a/web/src/features/ai-gateway/components/GatewayModelsPage/GatewayModelsPage.tsx b/web/src/features/ai-gateway/components/GatewayModelsPage/GatewayModelsPage.tsx
index 3983abebcd..ee16e4d29d 100644
--- a/web/src/features/ai-gateway/components/GatewayModelsPage/GatewayModelsPage.tsx
+++ b/web/src/features/ai-gateway/components/GatewayModelsPage/GatewayModelsPage.tsx
@@ -20,7 +20,7 @@ export function GatewayModelsPage({
if (isSetupStatusPending) {
return <ModelsSkeleton />;
}
- /** Managers are redirected to Configuration by the settings route. */
+ /** Managers are redirected to Setup by the settings route. */
if (!canManageGateway && isIngestionConfigured === false) {
return <GatewayNotSetUpNotice title="Models" />;
}
diff --git a/web/src/features/ai-gateway/components/GatewaySetupPage/GatewaySetupPage.tsx b/web/src/features/ai-gateway/components/GatewaySetupPage/GatewaySetupPage.tsx
new file mode 100644
index 0000000000..660c6a6d31
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewaySetupPage/GatewaySetupPage.tsx
@@ -0,0 +1,64 @@
+import { useRouter } from "next/router";
+
+import Header from "@/src/components/layouts/header";
+import { Alert } from "@/src/components/design-system/Alert/Alert";
+import { Button } from "@/src/components/design-system/Button/Button";
+import { Skeleton } from "@/src/components/ui/skeleton";
+import { GatewaySetupContent } from "@/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupContent";
+import { GATEWAY_SETUP } from "@/src/features/ai-gateway/components/GatewaySetupPage/constants/gatewaySetup";
+import type { GatewayProject } from "@/src/features/ai-gateway/components/GatewaySetupPage/types/gatewaySetup";
+import { useGatewayConfig } from "@/src/features/ai-gateway/components/GatewaySetupPage/hooks/useGatewayConfig";
+
+export type GatewaySetupPageProps = {
+ organizationId: string;
+ projects: Array<GatewayProject & { deletedAt?: Date | string | null }>;
+};
+
+export function GatewaySetupPage({
+ organizationId,
+ projects,
+}: GatewaySetupPageProps) {
+ const router = useRouter();
+ const connectionId =
+ typeof router.query.connectionId === "string"
+ ? router.query.connectionId
+ : undefined;
+ const gatewayConfig = useGatewayConfig(organizationId);
+
+ if (gatewayConfig.status === "pending") {
+ return (
+ <div className="flex flex-col gap-6" data-testid="gateway-setup-loading">
+ <Skeleton className="h-7 w-64" />
+ <Skeleton className="h-64 w-full" />
+ </div>
+ );
+ }
+
+ if (gatewayConfig.status === "error") {
+ return (
+ <div className="flex flex-col items-start gap-4">
+ <Header title={GATEWAY_SETUP.title} />
+ <Alert variant="destructive">
+ <Alert.Title>Gateway setup could not be loaded</Alert.Title>
+ <Alert.Description>
+ Retry the request to continue setting up the gateway.
+ </Alert.Description>
+ </Alert>
+ <Button
+ text="Retry"
+ variant="secondary"
+ onClick={gatewayConfig.retry}
+ />
+ </div>
+ );
+ }
+
+ return (
+ <GatewaySetupContent
+ organizationId={organizationId}
+ connectionId={connectionId}
+ config={gatewayConfig.config}
+ projects={projects.filter((project) => !project.deletedAt)}
+ />
+ );
+}
diff --git a/web/src/features/ai-gateway/components/GatewaySetupPage/components/ConnectedGatewaySetupGuide.tsx b/web/src/features/ai-gateway/components/GatewaySetupPage/components/ConnectedGatewaySetupGuide.tsx
new file mode 100644
index 0000000000..9f7ab1c1dd
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewaySetupPage/components/ConnectedGatewaySetupGuide.tsx
@@ -0,0 +1,56 @@
+import { Skeleton } from "@/src/components/ui/skeleton";
+import { GatewaySetupGuide } from "@/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/GatewaySetupGuide";
+import { ProviderDialogController } from "@/src/features/ai-gateway/components/GatewaySetupPage/components/ProviderDialogController/ProviderDialogController";
+import { useGatewaySetupProgress } from "@/src/features/ai-gateway/components/GatewaySetupPage/hooks/useGatewaySetupProgress";
+import { useGatewayTeamInvite } from "@/src/features/ai-gateway/components/GatewaySetupPage/hooks/useGatewayTeamInvite";
+import { useSaveGatewayIngestion } from "@/src/features/ai-gateway/components/GatewaySetupPage/hooks/useSaveGatewayIngestion";
+import type {
+ GatewayConfig,
+ GatewayProject,
+} from "@/src/features/ai-gateway/components/GatewaySetupPage/types/gatewaySetup";
+
+export type ConnectedGatewaySetupGuideProps = {
+ organizationId: string;
+ config: GatewayConfig | null;
+ projects: GatewayProject[];
+ onFinish: () => void;
+};
+
+export function ConnectedGatewaySetupGuide({
+ organizationId,
+ config,
+ projects,
+ onFinish,
+}: ConnectedGatewaySetupGuideProps) {
+ const { activeStep, firstConnection, isPending } = useGatewaySetupProgress({
+ organizationId,
+ config,
+ });
+ const { saveIngestion, isSaving } = useSaveGatewayIngestion(organizationId);
+ const { notifiableMembers, inviteTeam, isInviting } =
+ useGatewayTeamInvite(organizationId);
+
+ if (isPending) {
+ return <Skeleton className="h-64 w-full max-w-3xl" />;
+ }
+
+ return (
+ <ProviderDialogController organizationId={organizationId}>
+ {({ openAddDialog }) => (
+ <GatewaySetupGuide
+ activeStep={activeStep}
+ config={config}
+ projects={projects}
+ firstConnection={firstConnection}
+ isSavingIngestion={isSaving}
+ onSaveIngestion={saveIngestion}
+ onAddCredential={openAddDialog}
+ notifiableMembers={notifiableMembers}
+ isInviting={isInviting}
+ onInvite={inviteTeam}
+ onFinish={onFinish}
+ />
+ )}
+ </ProviderDialogController>
+ );
+}
diff --git a/web/src/features/ai-gateway/components/GatewayProvidersPage/GatewayProvidersPage.tsx b/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewayCredentialsOverview/GatewayCredentialsOverview.tsx
similarity index 60%
rename from web/src/features/ai-gateway/components/GatewayProvidersPage/GatewayProvidersPage.tsx
rename to web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewayCredentialsOverview/GatewayCredentialsOverview.tsx
index 4c26aef0d6..5e3e7f5f31 100644
--- a/web/src/features/ai-gateway/components/GatewayProvidersPage/GatewayProvidersPage.tsx
+++ b/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewayCredentialsOverview/GatewayCredentialsOverview.tsx
@@ -8,25 +8,36 @@ import { ConfirmationDialogController } from "@/src/components/design-system/Con
import { Button } from "@/src/components/ui/button";
import { Skeleton } from "@/src/components/ui/skeleton";
import { GatewayConnectionModelsPage } from "@/src/features/ai-gateway/components/GatewayConnectionModelsPage/GatewayConnectionModelsPage";
-import { ProviderDialogController } from "@/src/features/ai-gateway/components/GatewayProvidersPage/components/ProviderDialogController/ProviderDialogController";
-import { GatewayProvidersTable } from "@/src/features/ai-gateway/components/GatewayProvidersPage/components/GatewayProvidersTable/GatewayProvidersTable";
+import { IngestionDialogController } from "@/src/features/ai-gateway/components/GatewaySetupPage/components/GatewayCredentialsOverview/components/IngestionDialogController/IngestionDialogController";
+import { ProviderDialogController } from "@/src/features/ai-gateway/components/GatewaySetupPage/components/ProviderDialogController/ProviderDialogController";
+import { GatewayProvidersTable } from "@/src/features/ai-gateway/components/GatewaySetupPage/components/GatewayCredentialsOverview/components/GatewayProvidersTable/GatewayProvidersTable";
import { gatewayConnectionsPageSize } from "@/src/features/ai-gateway/constants/gatewayConnectionsPageSize";
import { buildGatewayModelsUrl } from "@/src/features/ai-gateway/fns/gatewayUrls/buildGatewayModelsUrl";
import { isGatewayModelAllowed } from "@/src/features/ai-gateway/fns/isGatewayModelAllowed";
import { toGatewayAllowedModelsSet } from "@/src/features/ai-gateway/fns/toGatewayAllowedModelsSet";
+import type {
+ GatewayConfig,
+ GatewayProject,
+} from "@/src/features/ai-gateway/components/GatewaySetupPage/types/gatewaySetup";
+import { GATEWAY_SETUP } from "@/src/features/ai-gateway/components/GatewaySetupPage/constants/gatewaySetup";
+import { GATEWAY_INGESTION_MODES } from "@/src/features/ai-gateway/constants/gatewayIngestionModes";
import type { GatewayConnection } from "@/src/features/ai-gateway/types/gatewayProvider";
import { api, reportNonTrpcError } from "@/src/utils/api";
-export function GatewayProvidersPage({
- organizationId,
-}: {
+export type GatewayCredentialsOverviewProps = {
organizationId: string;
-}) {
+ connectionId: string | undefined;
+ config: GatewayConfig | null;
+ projects: GatewayProject[];
+};
+
+export function GatewayCredentialsOverview({
+ organizationId,
+ connectionId,
+ config,
+ projects,
+}: GatewayCredentialsOverviewProps) {
const router = useRouter();
- const connectionId =
- typeof router.query.connectionId === "string"
- ? router.query.connectionId
- : undefined;
const connectionsQuery = api.aiGateway.listConnections.useInfiniteQuery(
{ orgId: organizationId, limit: gatewayConnectionsPageSize },
{
@@ -77,7 +88,7 @@ export function GatewayProvidersPage({
]);
if (connection.id === connectionId) {
await router.push(
- `/organization/${encodeURIComponent(organizationId)}/settings/ai-gateway-providers`,
+ `/organization/${encodeURIComponent(organizationId)}/settings/ai-gateway`,
);
}
} catch (error) {
@@ -107,7 +118,7 @@ export function GatewayProvidersPage({
if (connectionsQuery.isError) {
return (
<div className="flex flex-col gap-4">
- <Header title="Provider credentials" />
+ <Header title={GATEWAY_SETUP.title} />
<Alert variant="destructive">
<Alert.Title>Provider credentials could not be loaded</Alert.Title>
<Alert.Description>
@@ -159,57 +170,87 @@ export function GatewayProvidersPage({
];
}),
);
+ const ingestionMode = GATEWAY_INGESTION_MODES.find(
+ (mode) => mode.value === config?.ingestionMode,
+ );
return (
<div className="flex h-full min-h-0 flex-col gap-4">
- <Header
- title="Provider credentials"
- actionButtons={
- <ProviderDialogController organizationId={organizationId}>
- {({ openAddDialog }) => (
- <Button onClick={openAddDialog}>
- <Plus size="base" __rawClassName="mr-1.5" />
- Add credential
- </Button>
- )}
- </ProviderDialogController>
- }
- />
- <p className="text-muted-foreground text-sm">
- Model names are prefixed with their connection name. Credentials are
- validated against the provider when they are saved.
- </p>
- <ConfirmationDialogController<GatewayConnection>
- title="Delete provider credential"
- text={(connection) =>
- `Delete “${connection.name}”? Requests will immediately stop using it.`
- }
- confirmLabel="Delete credential"
- variant="destructive"
- loading={remove.isPending}
- onConfirm={deleteConnection}
- >
- {({ openDialog: openDeleteDialog }) => (
- <ProviderDialogController organizationId={organizationId}>
- {({ openEditDialog }) => (
- <div className="flex min-h-0 flex-1 flex-col overflow-hidden">
- <GatewayProvidersTable
- connections={allConnections}
- modelCounts={modelCounts}
- onSelect={selectConnection}
- onRetry={retryConnection}
- retryDisabled={
- retry.isPending
- ? { reason: "Validation in progress" }
- : undefined
- }
- onEdit={openEditDialog}
- onDelete={openDeleteDialog}
- />
- </div>
- )}
- </ProviderDialogController>
- )}
- </ConfirmationDialogController>
+ <div>
+ <Header
+ title={GATEWAY_SETUP.title}
+ actionButtons={
+ <div className="flex items-center gap-2">
+ <IngestionDialogController
+ organizationId={organizationId}
+ config={config}
+ projects={projects}
+ >
+ {({ openDialog }) => (
+ <Button variant="outline" onClick={openDialog}>
+ {ingestionMode ? (
+ <>
+ <ingestionMode.icon
+ size="base"
+ __rawClassName="mr-1.5"
+ />
+ Ingestion: {ingestionMode.title}
+ </>
+ ) : (
+ "Set up ingestion"
+ )}
+ </Button>
+ )}
+ </IngestionDialogController>
+ <ProviderDialogController organizationId={organizationId}>
+ {({ openAddDialog }) => (
+ <Button onClick={openAddDialog}>
+ <Plus size="base" __rawClassName="mr-1.5" />
+ Add credential
+ </Button>
+ )}
+ </ProviderDialogController>
+ </div>
+ }
+ />
+ <p className="text-muted-foreground text-sm">
+ {GATEWAY_SETUP.description}
+ </p>
+ </div>
+ <section className="flex min-h-0 flex-1 flex-col">
+ <Header title="Provider credentials" />
+ <ConfirmationDialogController<GatewayConnection>
+ title="Delete provider credential"
+ text={(connection) =>
+ `Delete “${connection.name}”? Requests will immediately stop using it.`
+ }
+ confirmLabel="Delete credential"
+ variant="destructive"
+ loading={remove.isPending}
+ onConfirm={deleteConnection}
+ >
+ {({ openDialog: openDeleteDialog }) => (
+ <ProviderDialogController organizationId={organizationId}>
+ {({ openEditDialog }) => (
+ <div className="flex min-h-0 flex-1 flex-col overflow-hidden">
+ <GatewayProvidersTable
+ connections={allConnections}
+ modelCounts={modelCounts}
+ onSelect={selectConnection}
+ onRetry={retryConnection}
+ retryDisabled={
+ retry.isPending
+ ? { reason: "Validation in progress" }
+ : undefined
+ }
+ onEdit={openEditDialog}
+ onDelete={openDeleteDialog}
+ />
+ </div>
+ )}
+ </ProviderDialogController>
+ )}
+ </ConfirmationDialogController>
+ </section>
{connectionsQuery.hasNextPage ? (
<Button
className="w-fit self-center"
diff --git a/web/src/features/ai-gateway/components/GatewayProvidersPage/components/GatewayProvidersTable/GatewayProvidersTable.stories.tsx b/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewayCredentialsOverview/components/GatewayProvidersTable/GatewayProvidersTable.stories.tsx
similarity index 100%
rename from web/src/features/ai-gateway/components/GatewayProvidersPage/components/GatewayProvidersTable/GatewayProvidersTable.stories.tsx
rename to web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewayCredentialsOverview/components/GatewayProvidersTable/GatewayProvidersTable.stories.tsx
diff --git a/web/src/features/ai-gateway/components/GatewayProvidersPage/components/GatewayProvidersTable/GatewayProvidersTable.tsx b/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewayCredentialsOverview/components/GatewayProvidersTable/GatewayProvidersTable.tsx
similarity index 100%
rename from web/src/features/ai-gateway/components/GatewayProvidersPage/components/GatewayProvidersTable/GatewayProvidersTable.tsx
rename to web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewayCredentialsOverview/components/GatewayProvidersTable/GatewayProvidersTable.tsx
diff --git a/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewayCredentialsOverview/components/IngestionDialogController/IngestionDialogController.tsx b/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewayCredentialsOverview/components/IngestionDialogController/IngestionDialogController.tsx
new file mode 100644
index 0000000000..5693dd55c8
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewayCredentialsOverview/components/IngestionDialogController/IngestionDialogController.tsx
@@ -0,0 +1,55 @@
+import type { ReactNode } from "react";
+
+import { DialogController } from "@/src/components/design-system/DialogController/DialogController";
+import { IngestionDialog } from "@/src/features/ai-gateway/components/GatewaySetupPage/components/GatewayCredentialsOverview/components/IngestionDialogController/components/IngestionDialog/IngestionDialog";
+import { useSaveGatewayIngestion } from "@/src/features/ai-gateway/components/GatewaySetupPage/hooks/useSaveGatewayIngestion";
+import type {
+ GatewayConfig,
+ GatewayIngestionSettings,
+ GatewayProject,
+} from "@/src/features/ai-gateway/components/GatewaySetupPage/types/gatewaySetup";
+import { showSuccessToast } from "@/src/features/notifications";
+
+export type IngestionDialogControllerProps = {
+ organizationId: string;
+ config: GatewayConfig | null;
+ projects: GatewayProject[];
+ children: (control: { openDialog: () => void }) => ReactNode;
+};
+
+export function IngestionDialogController({
+ organizationId,
+ config,
+ projects,
+ children,
+}: IngestionDialogControllerProps) {
+ const { saveIngestion, isSaving } = useSaveGatewayIngestion(organizationId);
+
+ async function handleSave(settings: GatewayIngestionSettings) {
+ const isSaved = await saveIngestion(settings);
+ if (isSaved) {
+ showSuccessToast({
+ operation: "aiGateway.updateConfig",
+ title: "Ingestion settings saved",
+ description: "New gateway requests use these settings.",
+ });
+ }
+ return isSaved;
+ }
+
+ return (
+ <DialogController
+ renderDialog={({ closeDialog }) => (
+ <IngestionDialog
+ config={config}
+ projects={projects}
+ isSaving={isSaving}
+ onSave={handleSave}
+ onSaved={closeDialog}
+ />
+ )}
+ >
+ {children}
+ </DialogController>
+ );
+}
diff --git a/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewayCredentialsOverview/components/IngestionDialogController/components/IngestionDialog/IngestionDialog.stories.tsx b/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewayCredentialsOverview/components/IngestionDialogController/components/IngestionDialog/IngestionDialog.stories.tsx
new file mode 100644
index 0000000000..96d3fffd2d
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewayCredentialsOverview/components/IngestionDialogController/components/IngestionDialog/IngestionDialog.stories.tsx
@@ -0,0 +1,76 @@
+import { expect, fn, userEvent, within } from "storybook/test";
+
+import preview from "@/.storybook/preview";
+import { DialogController } from "@/src/components/design-system/DialogController/DialogController";
+import { IngestionDialog } from "./IngestionDialog";
+
+const meta = preview.meta({
+ component: IngestionDialog,
+ decorators: [
+ (Story) => (
+ <DialogController
+ initialState={() => true}
+ renderDialog={() => <Story />}
+ >
+ {() => null}
+ </DialogController>
+ ),
+ ],
+});
+
+const projects = [
+ { id: "project-production", name: "Production" },
+ { id: "project-gateway", name: "ai-gateway" },
+];
+
+export const SavedConfig = meta.story({
+ args: {
+ config: {
+ organizationId: "org-1",
+ ingestionMode: "USAGE",
+ defaultIngestionProjectId: "project-gateway",
+ defaultIngestionProject: {
+ id: "project-gateway",
+ orgId: "org-1",
+ deletedAt: null,
+ },
+ createdAt: new Date("2026-10-01"),
+ updatedAt: new Date("2026-10-01"),
+ },
+ projects,
+ isSaving: false,
+ onSave: fn(async () => true),
+ onSaved: fn(),
+ },
+});
+
+export const NotRecording = meta.story({
+ args: {
+ ...SavedConfig.input.args,
+ config: {
+ ...SavedConfig.input.args.config,
+ ingestionMode: "NONE",
+ },
+ },
+});
+
+export const Saving = meta.story({
+ args: {
+ ...SavedConfig.input.args,
+ isSaving: true,
+ },
+});
+
+export const TestClosesOnlyAfterSave = meta.story({
+ name: "(Test) Closes only after a successful save",
+ args: {
+ ...SavedConfig.input.args,
+ onSave: fn(async () => false),
+ },
+ play: async ({ args }) => {
+ const dialog = within(document.body).getByRole("dialog");
+ await userEvent.click(within(dialog).getByRole("button", { name: "Save" }));
+ await expect(args.onSave).toHaveBeenCalledOnce();
+ await expect(args.onSaved).not.toHaveBeenCalled();
+ },
+});
diff --git a/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewayCredentialsOverview/components/IngestionDialogController/components/IngestionDialog/IngestionDialog.tsx b/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewayCredentialsOverview/components/IngestionDialogController/components/IngestionDialog/IngestionDialog.tsx
new file mode 100644
index 0000000000..bdb270a2b9
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewayCredentialsOverview/components/IngestionDialogController/components/IngestionDialog/IngestionDialog.tsx
@@ -0,0 +1,69 @@
+import { useState } from "react";
+
+import { Button } from "@/src/components/design-system/Button/Button";
+import { Dialog } from "@/src/components/design-system/Dialog/Dialog";
+import { IngestionSettingsFields } from "@/src/features/ai-gateway/components/GatewaySetupPage/components/IngestionSettingsFields/IngestionSettingsFields";
+import { GATEWAY_SETUP } from "@/src/features/ai-gateway/components/GatewaySetupPage/constants/gatewaySetup";
+import { getInitialIngestionSettings } from "@/src/features/ai-gateway/components/GatewaySetupPage/fns/getInitialIngestionSettings";
+import { isIngestionSettingsValid } from "@/src/features/ai-gateway/components/GatewaySetupPage/fns/isIngestionSettingsValid";
+import type {
+ GatewayConfig,
+ GatewayIngestionSettings,
+ GatewayProject,
+} from "@/src/features/ai-gateway/components/GatewaySetupPage/types/gatewaySetup";
+
+export type IngestionDialogProps = {
+ config: GatewayConfig | null;
+ projects: GatewayProject[];
+ isSaving: boolean;
+ /** Resolves to whether the settings were saved; the dialog closes only then. */
+ onSave: (settings: GatewayIngestionSettings) => Promise<boolean>;
+ onSaved: () => void;
+};
+
+export function IngestionDialog({
+ config,
+ projects,
+ isSaving,
+ onSave,
+ onSaved,
+}: IngestionDialogProps) {
+ const [settings, setSettings] = useState(() =>
+ getInitialIngestionSettings({ config, projects }),
+ );
+
+ async function handleSave() {
+ if (await onSave(settings)) onSaved();
+ }
+
+ return (
+ <Dialog
+ title="Gateway ingestion"
+ size="md"
+ actions={[
+ {
+ label: "Save",
+ onClick: handleSave,
+ loading: isSaving,
+ disabled: !isIngestionSettingsValid(settings),
+ },
+ ]}
+ >
+ <Dialog.Body>
+ <p className="text-muted-foreground">
+ Choose what Langfuse records for requests sent through the gateway.{" "}
+ <Button
+ variant="text"
+ text="How ingestion modes work"
+ href={GATEWAY_SETUP.docsUrl}
+ />
+ </p>
+ <IngestionSettingsFields
+ settings={settings}
+ projects={projects}
+ onChange={setSettings}
+ />
+ </Dialog.Body>
+ </Dialog>
+ );
+}
diff --git a/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupContent.tsx b/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupContent.tsx
new file mode 100644
index 0000000000..88494cc182
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupContent.tsx
@@ -0,0 +1,67 @@
+import { useState } from "react";
+
+import Header from "@/src/components/layouts/header";
+import { GatewayCredentialsOverview } from "@/src/features/ai-gateway/components/GatewaySetupPage/components/GatewayCredentialsOverview/GatewayCredentialsOverview";
+import { ConnectedGatewaySetupGuide } from "@/src/features/ai-gateway/components/GatewaySetupPage/components/ConnectedGatewaySetupGuide";
+import { GATEWAY_SETUP } from "@/src/features/ai-gateway/components/GatewaySetupPage/constants/gatewaySetup";
+import { isGatewayConfigComplete } from "@/src/features/ai-gateway/components/GatewaySetupPage/fns/isGatewayConfigComplete";
+import type {
+ GatewayConfig,
+ GatewayProject,
+} from "@/src/features/ai-gateway/components/GatewaySetupPage/types/gatewaySetup";
+
+export type GatewaySetupContentProps = {
+ organizationId: string;
+ connectionId: string | undefined;
+ config: GatewayConfig | null;
+ projects: GatewayProject[];
+};
+
+/**
+ * Mount once the config has loaded: whether the guide shows is decided on the
+ * first render and kept for the visit, so finishing step 1 does not swap the
+ * guide for the overview mid-setup.
+ */
+export function GatewaySetupContent({
+ organizationId,
+ connectionId,
+ config,
+ projects,
+}: GatewaySetupContentProps) {
+ const [isGuideOpen, setIsGuideOpen] = useState(
+ () => !isGatewayConfigComplete(config),
+ );
+
+ function handleGuideFinish() {
+ setIsGuideOpen(false);
+ }
+
+ if (!isGuideOpen || connectionId !== undefined) {
+ return (
+ <GatewayCredentialsOverview
+ organizationId={organizationId}
+ connectionId={connectionId}
+ config={config}
+ projects={projects}
+ />
+ );
+ }
+
+ return (
+ // The settings page is locked to the screen height for the overview's table, so the guide scrolls itself.
+ <div className="flex h-full min-h-0 flex-col gap-6 overflow-y-auto">
+ <div>
+ <Header title={GATEWAY_SETUP.title} />
+ <p className="text-muted-foreground text-sm">
+ {GATEWAY_SETUP.description}
+ </p>
+ </div>
+ <ConnectedGatewaySetupGuide
+ organizationId={organizationId}
+ config={config}
+ projects={projects}
+ onFinish={handleGuideFinish}
+ />
+ </div>
+ );
+}
diff --git a/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/GatewaySetupGuide.stories.tsx b/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/GatewaySetupGuide.stories.tsx
new file mode 100644
index 0000000000..6f35356335
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/GatewaySetupGuide.stories.tsx
@@ -0,0 +1,120 @@
+import { expect, fn, userEvent, within } from "storybook/test";
+
+import preview from "@/.storybook/preview";
+import { GatewaySetupGuide } from "./GatewaySetupGuide";
+
+const meta = preview.meta({ component: GatewaySetupGuide });
+
+const projects = [
+ { id: "project-production", name: "Production" },
+ { id: "project-gateway", name: "ai-gateway" },
+];
+
+const savedConfig = {
+ organizationId: "org-1",
+ ingestionMode: "USAGE" as const,
+ defaultIngestionProjectId: "project-gateway",
+ defaultIngestionProject: {
+ id: "project-gateway",
+ orgId: "org-1",
+ deletedAt: null,
+ },
+ createdAt: new Date("2026-10-01"),
+ updatedAt: new Date("2026-10-01"),
+};
+
+const notifiableMembers = {
+ isEmailConfigured: true,
+ count: 12,
+ preview: [
+ {
+ id: "user-1",
+ name: "Ada Lovelace",
+ email: "[email protected]",
+ image: null,
+ },
+ {
+ id: "user-2",
+ name: "Grace Hopper",
+ email: "[email protected]",
+ image: null,
+ },
+ { id: "user-3", name: null, email: "[email protected]", image: null },
+ {
+ id: "user-4",
+ name: "Edsger Dijkstra",
+ email: "[email protected]",
+ image: null,
+ },
+ ],
+};
+
+export const ChoosingIngestion = meta.story({
+ args: {
+ activeStep: 1,
+ config: null,
+ projects,
+ firstConnection: undefined,
+ isSavingIngestion: false,
+ onSaveIngestion: fn(async () => true),
+ onAddCredential: fn(),
+ notifiableMembers,
+ isInviting: false,
+ onInvite: fn(async () => null),
+ onFinish: fn(),
+ },
+});
+
+export const AddingCredential = meta.story({
+ args: {
+ ...ChoosingIngestion.input.args,
+ activeStep: 2,
+ config: savedConfig,
+ },
+});
+
+export const InvitingTeam = meta.story({
+ args: {
+ ...AddingCredential.input.args,
+ activeStep: 3,
+ firstConnection: { provider: "OPENAI" },
+ },
+});
+
+export const InvitingTeamWithoutEmail = meta.story({
+ args: {
+ ...InvitingTeam.input.args,
+ notifiableMembers: { ...notifiableMembers, isEmailConfigured: false },
+ },
+});
+
+export const TestRetryDoesNotNotifyAgain = meta.story({
+ name: "(Test) Retrying failed invites does not notify members again",
+ args: {
+ ...InvitingTeam.input.args,
+ onInvite: fn(async () => ({
+ invitedCount: 0,
+ failed: [{ email: "[email protected]", message: "Already a member" }],
+ notifiedCount: 12,
+ })),
+ },
+ play: async ({ args, canvasElement }) => {
+ const canvas = within(canvasElement);
+ await userEvent.type(
+ canvas.getByRole("textbox", { name: "Email addresses" }),
+ );
+ await userEvent.click(
+ canvas.getByRole("button", { name: "Send 1 invite" }),
+ );
+
+ await expect(args.onInvite).toHaveBeenCalledWith({
+ emails: ["[email protected]"],
+ notifyMembers: true,
+ });
+ await expect(
+ await canvas.findByText("Some invitations were not sent"),
+ ).toBeVisible();
+ await expect(canvas.queryByRole("switch")).not.toBeInTheDocument();
+ },
+});
diff --git a/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/GatewaySetupGuide.tsx b/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/GatewaySetupGuide.tsx
new file mode 100644
index 0000000000..7150c45fb2
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/GatewaySetupGuide.tsx
@@ -0,0 +1,56 @@
+import { CredentialStep } from "@/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/components/CredentialStep";
+import { IngestionStep } from "@/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/components/IngestionStep/IngestionStep";
+import {
+ TeamInviteStep,
+ type TeamInviteStepProps,
+} from "@/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/components/TeamInviteStep/TeamInviteStep";
+import { getSetupStepStatus } from "@/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/fns/getSetupStepStatus";
+import type {
+ GatewayConfig,
+ GatewayIngestionSettings,
+ GatewayProject,
+} from "@/src/features/ai-gateway/components/GatewaySetupPage/types/gatewaySetup";
+import type { GatewayConnection } from "@/src/features/ai-gateway/types/gatewayProvider";
+
+export type GatewaySetupGuideProps = Omit<TeamInviteStepProps, "status"> & {
+ /** The open step: 1 ingestion, 2 credential, 3 team. */
+ activeStep: 1 | 2 | 3;
+ config: GatewayConfig | null;
+ projects: GatewayProject[];
+ firstConnection: Pick<GatewayConnection, "provider"> | undefined;
+ isSavingIngestion: boolean;
+ onSaveIngestion: (settings: GatewayIngestionSettings) => Promise<unknown>;
+ onAddCredential: () => void;
+};
+
+export function GatewaySetupGuide({
+ activeStep,
+ config,
+ projects,
+ firstConnection,
+ isSavingIngestion,
+ onSaveIngestion,
+ onAddCredential,
+ ...teamInviteProps
+}: GatewaySetupGuideProps) {
+ return (
+ <div className="flex max-w-3xl flex-col">
+ <IngestionStep
+ status={getSetupStepStatus(1, activeStep)}
+ config={config}
+ projects={projects}
+ isSaving={isSavingIngestion}
+ onContinue={onSaveIngestion}
+ />
+ <CredentialStep
+ status={getSetupStepStatus(2, activeStep)}
+ firstConnection={firstConnection}
+ onAddCredential={onAddCredential}
+ />
+ <TeamInviteStep
+ status={getSetupStepStatus(3, activeStep)}
+ {...teamInviteProps}
+ />
+ </div>
+ );
+}
diff --git a/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/components/CredentialStep.tsx b/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/components/CredentialStep.tsx
new file mode 100644
index 0000000000..d6a32ea25c
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/components/CredentialStep.tsx
@@ -0,0 +1,68 @@
+import { Plus } from "@langfuse/icons";
+
+import { Button } from "@/src/components/design-system/Button/Button";
+import { Stepper } from "@/src/components/design-system/Stepper/Stepper";
+import { GATEWAY_SETUP } from "@/src/features/ai-gateway/components/GatewaySetupPage/constants/gatewaySetup";
+import type { getSetupStepStatus } from "@/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/fns/getSetupStepStatus";
+import { providerLabels } from "@/src/features/ai-gateway/constants/providerLabels";
+import type { GatewayConnection } from "@/src/features/ai-gateway/types/gatewayProvider";
+
+export type CredentialStepProps = {
+ status: ReturnType<typeof getSetupStepStatus>;
+ firstConnection: Pick<GatewayConnection, "provider"> | undefined;
+ onAddCredential: () => void;
+};
+
+function CredentialStepDescription({
+ status,
+ firstConnection,
+}: Pick<CredentialStepProps, "status" | "firstConnection">) {
+ if (status === "complete" && firstConnection) {
+ return <>{providerLabels[firstConnection.provider]} credential added</>;
+ }
+ return (
+ <>
+ Connect {Object.values(providerLabels).join(" or ")} with an API key.
+ Available models are loaded from the provider.
+ {status === "current" ? (
+ <>
+ {" "}
+ <Button
+ variant="text"
+ size="sm"
+ text="How provider credentials work"
+ href={GATEWAY_SETUP.docsUrl}
+ />
+ </>
+ ) : null}
+ </>
+ );
+}
+
+export function CredentialStep({
+ status,
+ firstConnection,
+ onAddCredential,
+}: CredentialStepProps) {
+ return (
+ <Stepper
+ number={2}
+ title="Add a provider credential"
+ size="sm"
+ status={status}
+ isCollapsible={false}
+ description={
+ <CredentialStepDescription
+ status={status}
+ firstConnection={firstConnection}
+ />
+ }
+ >
+ {status === "current" ? (
+ <div className="flex flex-col items-start pt-1">
+ <Button text="Add credential" icon={Plus} onClick={onAddCredential} />
+ </div>
+ ) : null}
+ </Stepper>
+ );
+}
diff --git a/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/components/IngestionStep/IngestionStep.tsx b/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/components/IngestionStep/IngestionStep.tsx
new file mode 100644
index 0000000000..9cf3e91f6a
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/components/IngestionStep/IngestionStep.tsx
@@ -0,0 +1,64 @@
+import { Button } from "@/src/components/design-system/Button/Button";
+import { Stepper } from "@/src/components/design-system/Stepper/Stepper";
+import { IngestionStepForm } from "@/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/components/IngestionStep/components/IngestionStepForm";
+import type { getSetupStepStatus } from "@/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/fns/getSetupStepStatus";
+import { GATEWAY_SETUP } from "@/src/features/ai-gateway/components/GatewaySetupPage/constants/gatewaySetup";
+import { describeGatewayIngestion } from "@/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/components/IngestionStep/fns/describeGatewayIngestion";
+import type {
+ GatewayConfig,
+ GatewayIngestionSettings,
+ GatewayProject,
+} from "@/src/features/ai-gateway/components/GatewaySetupPage/types/gatewaySetup";
+
+export type IngestionStepProps = {
+ status: ReturnType<typeof getSetupStepStatus>;
+ config: GatewayConfig | null;
+ projects: GatewayProject[];
+ isSaving: boolean;
+ onContinue: (settings: GatewayIngestionSettings) => Promise<unknown>;
+};
+
+export function IngestionStep({
+ status,
+ config,
+ projects,
+ isSaving,
+ onContinue,
+}: IngestionStepProps) {
+ const description =
+ status === "complete" && config ? (
+ <span className="ph-no-capture">
+ {describeGatewayIngestion({ config, projects })}
+ </span>
+ ) : (
+ <>
+ You can change this later.{" "}
+ <Button
+ variant="text"
+ size="sm"
+ text="How ingestion modes work"
+ href={GATEWAY_SETUP.docsUrl}
+ />
+ </>
+ );
+
+ return (
+ <Stepper
+ number={1}
+ title="Choose how gateway traffic is recorded"
+ size="sm"
+ status={status}
+ isCollapsible={false}
+ description={description}
+ >
+ {status === "current" ? (
+ <IngestionStepForm
+ config={config}
+ projects={projects}
+ isSaving={isSaving}
+ onContinue={onContinue}
+ />
+ ) : null}
+ </Stepper>
+ );
+}
diff --git a/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/components/IngestionStep/components/IngestionStepForm.tsx b/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/components/IngestionStep/components/IngestionStepForm.tsx
new file mode 100644
index 0000000000..9bbb63c6bf
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/components/IngestionStep/components/IngestionStepForm.tsx
@@ -0,0 +1,48 @@
+import { useState } from "react";
+
+import { Button } from "@/src/components/design-system/Button/Button";
+import { IngestionSettingsFields } from "@/src/features/ai-gateway/components/GatewaySetupPage/components/IngestionSettingsFields/IngestionSettingsFields";
+import { getInitialIngestionSettings } from "@/src/features/ai-gateway/components/GatewaySetupPage/fns/getInitialIngestionSettings";
+import { isIngestionSettingsValid } from "@/src/features/ai-gateway/components/GatewaySetupPage/fns/isIngestionSettingsValid";
+import type {
+ GatewayConfig,
+ GatewayIngestionSettings,
+ GatewayProject,
+} from "@/src/features/ai-gateway/components/GatewaySetupPage/types/gatewaySetup";
+
+export type IngestionStepFormProps = {
+ config: GatewayConfig | null;
+ projects: GatewayProject[];
+ isSaving: boolean;
+ onContinue: (settings: GatewayIngestionSettings) => Promise<unknown>;
+};
+
+export function IngestionStepForm({
+ config,
+ projects,
+ isSaving,
+ onContinue,
+}: IngestionStepFormProps) {
+ const [settings, setSettings] = useState(() =>
+ getInitialIngestionSettings({ config, projects }),
+ );
+ async function handleContinue() {
+ await onContinue(settings);
+ }
+
+ return (
+ <div className="flex flex-col items-start gap-4 pt-2">
+ <IngestionSettingsFields
+ settings={settings}
+ projects={projects}
+ onChange={setSettings}
+ />
+ <Button
+ text="Continue"
+ loading={isSaving}
+ disabled={!isIngestionSettingsValid(settings)}
+ onClick={handleContinue}
+ />
+ </div>
+ );
+}
diff --git a/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/components/IngestionStep/fns/describeGatewayIngestion.ts b/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/components/IngestionStep/fns/describeGatewayIngestion.ts
new file mode 100644
index 0000000000..b88f70c0da
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/components/IngestionStep/fns/describeGatewayIngestion.ts
@@ -0,0 +1,28 @@
+import type { GatewayIngestionMode } from "@langfuse/shared";
+
+import type {
+ GatewayConfig,
+ GatewayProject,
+} from "@/src/features/ai-gateway/components/GatewaySetupPage/types/gatewaySetup";
+
+const INGESTION_SUMMARIES: Record<GatewayIngestionMode, string> = {
+ NONE: "Not recording gateway traffic",
+ USAGE: "Recording usage only",
+ FULL: "Recording full requests and responses",
+};
+
+/** One-line summary of a saved config, e.g. `Recording usage only in project "ai-gateway"`. */
+export function describeGatewayIngestion({
+ config,
+ projects,
+}: {
+ config: GatewayConfig;
+ projects: GatewayProject[];
+}) {
+ const summary = INGESTION_SUMMARIES[config.ingestionMode];
+ const project = projects.find(
+ (candidate) => candidate.id === config.defaultIngestionProjectId,
+ );
+ if (config.ingestionMode === "NONE" || !project) return summary;
+ return `${summary} in project "${project.name}"`;
+}
diff --git a/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/components/TeamInviteStep/TeamInviteStep.tsx b/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/components/TeamInviteStep/TeamInviteStep.tsx
new file mode 100644
index 0000000000..50eae545ef
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/components/TeamInviteStep/TeamInviteStep.tsx
@@ -0,0 +1,43 @@
+import { Button } from "@/src/components/design-system/Button/Button";
+import { Stepper } from "@/src/components/design-system/Stepper/Stepper";
+import { GATEWAY_SETUP } from "@/src/features/ai-gateway/components/GatewaySetupPage/constants/gatewaySetup";
+import {
+ TeamInviteForm,
+ type TeamInviteFormProps,
+} from "@/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/components/TeamInviteStep/components/TeamInviteForm/TeamInviteForm";
+import type { getSetupStepStatus } from "@/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/fns/getSetupStepStatus";
+
+export type TeamInviteStepProps = TeamInviteFormProps & {
+ status: ReturnType<typeof getSetupStepStatus>;
+};
+
+export function TeamInviteStep({ status, ...formProps }: TeamInviteStepProps) {
+ return (
+ <Stepper
+ number={3}
+ title="Invite your team"
+ size="sm"
+ status={status}
+ isCollapsible={false}
+ description={
+ <>
+ Members can create their own gateway keys and use the models you
+ enabled. New people join as Member.
+ {status === "current" ? (
+ <>
+ {" "}
+ <Button
+ variant="text"
+ size="sm"
+ text="How gateway keys work"
+ href={GATEWAY_SETUP.docsUrl}
+ />
+ </>
+ ) : null}
+ </>
+ }
+ >
+ {status === "current" ? <TeamInviteForm {...formProps} /> : null}
+ </Stepper>
+ );
+}
diff --git a/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/components/TeamInviteStep/components/TeamInviteForm/TeamInviteForm.tsx b/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/components/TeamInviteStep/components/TeamInviteForm/TeamInviteForm.tsx
new file mode 100644
index 0000000000..ae5d38f9ef
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/components/TeamInviteStep/components/TeamInviteForm/TeamInviteForm.tsx
@@ -0,0 +1,119 @@
+import { useState } from "react";
+import { z } from "zod/v4";
+
+import { Alert } from "@/src/components/design-system/Alert/Alert";
+import { Button } from "@/src/components/design-system/Button/Button";
+import { MAX_TEAM_INVITES } from "@/src/features/ai-gateway/constants/gatewayTeamInvites";
+import { TeamInviteFields } from "@/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/components/TeamInviteStep/components/TeamInviteForm/components/TeamInviteFields/TeamInviteFields";
+import type {
+ GatewayNotifiableMembers,
+ GatewayTeamInviteResult,
+} from "@/src/features/ai-gateway/components/GatewaySetupPage/types/gatewaySetup";
+
+export type TeamInviteFormProps = {
+ /** Undefined while loading. */
+ notifiableMembers: GatewayNotifiableMembers | undefined;
+ isInviting: boolean;
+ /** Resolves to null when the request failed and was already reported. */
+ onInvite: (params: {
+ emails: string[];
+ notifyMembers: boolean;
+ }) => Promise<GatewayTeamInviteResult | null>;
+ onFinish: () => void;
+};
+
+function getSendLabel(emailCount: number) {
+ if (emailCount === 0) return "Notify members";
+ if (emailCount === 1) return "Send 1 invite";
+ return `Send ${emailCount} invites`;
+}
+
+export function TeamInviteForm({
+ notifiableMembers,
+ isInviting,
+ onInvite,
+ onFinish,
+}: TeamInviteFormProps) {
+ const [emails, setEmails] = useState<string[]>([]);
+ const [notifyMembers, setNotifyMembers] = useState(true);
+ const [failures, setFailures] = useState<
+ Array<{ email: string; message: string }>
+ >([]);
+ // Retrying failed invites must not announce the gateway to every member again.
+ const [haveMembersBeenNotified, setHaveMembersBeenNotified] = useState(false);
+
+ const canNotify =
+ !haveMembersBeenNotified &&
+ notifiableMembers !== undefined &&
+ notifiableMembers.isEmailConfigured &&
+ notifiableMembers.count > 0;
+ const willNotify = canNotify && notifyMembers;
+ const hasInvalidEmail = emails.some(
+ (email) => !z.email().safeParse(email).success,
+ );
+ const hasTooManyEmails = emails.length > MAX_TEAM_INVITES;
+ const sendLabel = getSendLabel(emails.length);
+
+ async function handleSend() {
+ const result = await onInvite({ emails, notifyMembers: willNotify });
+ if (!result) return;
+ if (willNotify) setHaveMembersBeenNotified(true);
+ if (result.failed.length > 0) {
+ setFailures(result.failed);
+ setEmails(result.failed.map((failure) => failure.email));
+ return;
+ }
+ onFinish();
+ }
+
+ return (
+ <div className="flex flex-col gap-4 pt-1">
+ <TeamInviteFields
+ emails={emails}
+ onEmailsChange={setEmails}
+ errorMessage={
+ hasTooManyEmails
+ ? `You can invite up to ${MAX_TEAM_INVITES} people at once.`
+ : undefined
+ }
+ notifyMembers={
+ canNotify
+ ? {
+ memberCount: notifiableMembers.count,
+ previewMembers: notifiableMembers.preview,
+ checked: notifyMembers,
+ onCheckedChange: setNotifyMembers,
+ }
+ : undefined
+ }
+ />
+ {failures.length > 0 ? (
+ <Alert variant="destructive">
+ <Alert.Title>Some invitations were not sent</Alert.Title>
+ <Alert.Description>
+ <ul className="ph-no-capture">
+ {failures.map((failure) => (
+ <li key={failure.email}>
+ {failure.email}: {failure.message}
+ </li>
+ ))}
+ </ul>
+ </Alert.Description>
+ </Alert>
+ ) : null}
+ <div className="flex items-center gap-2">
+ <Button
+ text={sendLabel}
+ loading={isInviting}
+ disabled={
+ hasInvalidEmail ||
+ hasTooManyEmails ||
+ (emails.length === 0 && !willNotify)
+ }
+ onClick={handleSend}
+ />
+ <Button text="Skip for now" variant="ghost" onClick={onFinish} />
+ </div>
+ </div>
+ );
+}
diff --git a/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/components/TeamInviteStep/components/TeamInviteForm/components/TeamInviteFields/TeamInviteFields.stories.tsx b/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/components/TeamInviteStep/components/TeamInviteForm/components/TeamInviteFields/TeamInviteFields.stories.tsx
new file mode 100644
index 0000000000..3d6a2e7051
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/components/TeamInviteStep/components/TeamInviteForm/components/TeamInviteFields/TeamInviteFields.stories.tsx
@@ -0,0 +1,70 @@
+import { expect, fn, userEvent, within } from "storybook/test";
+
+import preview from "@/.storybook/preview";
+import { TeamInviteFields } from "./TeamInviteFields";
+
+const meta = preview.meta({ component: TeamInviteFields });
+
+const previewMembers = [
+ { id: "user-1", name: "Ada Lovelace", email: "[email protected]", image: null },
+ {
+ id: "user-2",
+ name: "Grace Hopper",
+ email: "[email protected]",
+ image: null,
+ },
+ { id: "user-3", name: null, email: "[email protected]", image: null },
+ {
+ id: "user-4",
+ name: "Edsger Dijkstra",
+ email: "[email protected]",
+ image: null,
+ },
+];
+
+export const Empty = meta.story({
+ args: {
+ emails: [],
+ onEmailsChange: fn(),
+ notifyMembers: {
+ memberCount: 12,
+ previewMembers,
+ checked: true,
+ onCheckedChange: fn(),
+ },
+ },
+});
+
+export const WithEmails = meta.story({
+ args: {
+ ...Empty.input.args,
+ emails: ["[email protected]", "[email protected]", "not-an-email"],
+ },
+});
+
+export const WithError = meta.story({
+ args: {
+ ...WithEmails.input.args,
+ errorMessage: "You can invite up to 50 people at once.",
+ },
+});
+
+export const WithoutMembersToNotify = meta.story({
+ args: {
+ emails: [],
+ onEmailsChange: fn(),
+ },
+});
+
+export const TestSpaceCommitsEmail = meta.story({
+ name: "(Test) Space commits an email",
+ args: { emails: [], onEmailsChange: fn() },
+ play: async ({ args, canvasElement }) => {
+ const input = within(canvasElement).getByRole("textbox", {
+ name: "Email addresses",
+ });
+ await userEvent.type(input, "[email protected] ");
+ await expect(args.onEmailsChange).toHaveBeenCalledWith(["[email protected]"]);
+ await expect(input).toHaveValue("");
+ },
+});
diff --git a/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/components/TeamInviteStep/components/TeamInviteForm/components/TeamInviteFields/TeamInviteFields.tsx b/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/components/TeamInviteStep/components/TeamInviteForm/components/TeamInviteFields/TeamInviteFields.tsx
new file mode 100644
index 0000000000..ad13c406b8
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/components/TeamInviteStep/components/TeamInviteForm/components/TeamInviteFields/TeamInviteFields.tsx
@@ -0,0 +1,60 @@
+import { useId } from "react";
+import { Mail } from "@langfuse/icons";
+
+import { EmailTagInput } from "@/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/components/TeamInviteStep/components/TeamInviteForm/components/TeamInviteFields/components/EmailTagInput/EmailTagInput";
+import {
+ NotifyMembersToggle,
+ type NotifyMembersToggleProps,
+} from "@/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/components/TeamInviteStep/components/TeamInviteForm/components/TeamInviteFields/components/NotifyMembersToggle";
+
+export type TeamInviteFieldsProps = {
+ emails: string[];
+ onEmailsChange: (emails: string[]) => void;
+ /** Replaces the input hint while set. */
+ errorMessage?: string;
+ /** Omit when there is nobody to notify or email is not configured. */
+ notifyMembers?: NotifyMembersToggleProps;
+};
+
+/** One framed field: invitee emails on top, the member announcement below. */
+export function TeamInviteFields({
+ emails,
+ onEmailsChange,
+ errorMessage,
+ notifyMembers,
+}: TeamInviteFieldsProps) {
+ const inputId = useId();
+ const hintId = useId();
+
+ return (
+ <div className="has-[input:focus]:border-ring flex max-w-xl flex-col rounded-md border">
+ <div className="flex items-start gap-2.5 px-3 py-2.5">
+ <span className="flex h-6 shrink-0 items-center">
+ <Mail size="base" color="tertiary" aria-hidden />
+ </span>
+ <div className="flex min-w-0 flex-1 flex-col gap-1">
+ <EmailTagInput
+ id={inputId}
+ value={emails}
+ onChange={onEmailsChange}
+ aria-describedby={hintId}
+ />
+ {errorMessage ? (
+ <p id={hintId} role="alert" className="text-destructive text-xs">
+ {errorMessage}
+ </p>
+ ) : (
+ <p id={hintId} className="text-muted-foreground text-xs">
+ Separate with a comma, space or Enter. They join as Member.
+ </p>
+ )}
+ </div>
+ </div>
+ {notifyMembers ? (
+ <div className="border-t px-3 py-2.5">
+ <NotifyMembersToggle {...notifyMembers} />
+ </div>
+ ) : null}
+ </div>
+ );
+}
diff --git a/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/components/TeamInviteStep/components/TeamInviteForm/components/TeamInviteFields/components/EmailTagInput/EmailTagInput.tsx b/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/components/TeamInviteStep/components/TeamInviteForm/components/TeamInviteFields/components/EmailTagInput/EmailTagInput.tsx
new file mode 100644
index 0000000000..5e2f9c9cbf
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/components/TeamInviteStep/components/TeamInviteForm/components/TeamInviteFields/components/EmailTagInput/EmailTagInput.tsx
@@ -0,0 +1,86 @@
+import { useState, type ChangeEvent, type KeyboardEvent } from "react";
+import { z } from "zod/v4";
+
+import { EmailTag } from "@/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/components/TeamInviteStep/components/TeamInviteForm/components/TeamInviteFields/components/EmailTagInput/components/EmailTag";
+import {
+ appendEmails,
+ splitEmailText,
+} from "@/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/components/TeamInviteStep/components/TeamInviteForm/components/TeamInviteFields/components/EmailTagInput/fns/emailText";
+
+export type EmailTagInputProps = {
+ id: string;
+ value: string[];
+ onChange: (emails: string[]) => void;
+ "aria-describedby"?: string;
+};
+
+/**
+ * Turns typed or pasted addresses into removable chips on comma, space, Enter, or
+ * blur. Borderless: the surrounding field draws the frame.
+ */
+export function EmailTagInput({
+ id,
+ value,
+ onChange,
+ "aria-describedby": ariaDescribedBy,
+}: EmailTagInputProps) {
+ const [draft, setDraft] = useState("");
+
+ function commit(text: string) {
+ setDraft("");
+ if (text.trim().length > 0) onChange(appendEmails(value, text));
+ }
+
+ function handleChange(event: ChangeEvent<HTMLInputElement>) {
+ const text = event.target.value;
+ if (splitEmailText(text).length > 1) commit(text);
+ else setDraft(text);
+ }
+
+ function handleKeyDown(event: KeyboardEvent<HTMLInputElement>) {
+ if (event.key === "Enter") {
+ event.preventDefault();
+ commit(draft);
+ return;
+ }
+ if (event.key === "Backspace" && draft.length === 0 && value.length > 0) {
+ onChange(value.slice(0, -1));
+ }
+ }
+
+ function handleBlur() {
+ commit(draft);
+ }
+
+ function handleRemove(email: string) {
+ onChange(value.filter((candidate) => candidate !== email));
+ }
+
+ return (
+ <div className="ph-no-capture flex min-h-6 min-w-0 flex-wrap items-center gap-1.5 text-sm">
+ {value.map((email) => (
+ <EmailTag
+ key={email}
+ email={email}
+ invalid={!z.email().safeParse(email).success}
+ onRemove={handleRemove}
+ />
+ ))}
+ <input
+ id={id}
+ type="text"
+ inputMode="email"
+ autoComplete="off"
+ data-1p-ignore
+ placeholder={value.length === 0 ? "[email protected]" : undefined}
+ aria-label="Email addresses"
+ aria-describedby={ariaDescribedBy}
+ className="placeholder:text-muted-foreground h-6 min-w-24 flex-1 border-0 bg-transparent p-0 text-sm shadow-none outline-hidden focus:ring-0"
+ value={draft}
+ onChange={handleChange}
+ onKeyDown={handleKeyDown}
+ onBlur={handleBlur}
+ />
+ </div>
+ );
+}
diff --git a/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/components/TeamInviteStep/components/TeamInviteForm/components/TeamInviteFields/components/EmailTagInput/components/EmailTag.tsx b/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/components/TeamInviteStep/components/TeamInviteForm/components/TeamInviteFields/components/EmailTagInput/components/EmailTag.tsx
new file mode 100644
index 0000000000..2772fac527
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/components/TeamInviteStep/components/TeamInviteForm/components/TeamInviteFields/components/EmailTagInput/components/EmailTag.tsx
@@ -0,0 +1,21 @@
+import { Tag } from "@/src/components/design-system/Tag/Tag";
+
+export type EmailTagProps = {
+ email: string;
+ invalid: boolean;
+ onRemove: (email: string) => void;
+};
+
+export function EmailTag({ email, invalid, onRemove }: EmailTagProps) {
+ function handleRemove() {
+ onRemove(email);
+ }
+
+ return (
+ <Tag
+ text={email}
+ status={invalid ? "error" : "default"}
+ remove={{ onRemove: handleRemove }}
+ />
+ );
+}
diff --git a/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/components/TeamInviteStep/components/TeamInviteForm/components/TeamInviteFields/components/EmailTagInput/fns/emailText.ts b/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/components/TeamInviteStep/components/TeamInviteForm/components/TeamInviteFields/components/EmailTagInput/fns/emailText.ts
new file mode 100644
index 0000000000..0026653f02
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/components/TeamInviteStep/components/TeamInviteForm/components/TeamInviteFields/components/EmailTagInput/fns/emailText.ts
@@ -0,0 +1,14 @@
+/** Splits typed or pasted text on whitespace, commas, and semicolons. */
+export function splitEmailText(text: string) {
+ return text.split(/[\s,;]+/);
+}
+
+/** Adds the addresses typed or pasted as `text`, skipping ones already listed. */
+export function appendEmails(current: string[], text: string) {
+ const emails = new Set(current);
+ for (const email of splitEmailText(text)) {
+ const normalized = email.trim().toLowerCase();
+ if (normalized.length > 0) emails.add(normalized);
+ }
+ return [...emails];
+}
diff --git a/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/components/TeamInviteStep/components/TeamInviteForm/components/TeamInviteFields/components/NotifyMembersToggle.tsx b/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/components/TeamInviteStep/components/TeamInviteForm/components/TeamInviteFields/components/NotifyMembersToggle.tsx
new file mode 100644
index 0000000000..c8c78ca1e2
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/components/TeamInviteStep/components/TeamInviteForm/components/TeamInviteFields/components/NotifyMembersToggle.tsx
@@ -0,0 +1,66 @@
+import { useId } from "react";
+
+import { Avatar } from "@/src/components/design-system/Avatar/Avatar";
+import { Switch } from "@/src/components/design-system/Switch/Switch";
+import type { RouterOutputs } from "@/src/utils/api";
+
+export type NotifyMembersToggleProps = {
+ memberCount: number;
+ previewMembers: RouterOutputs["aiGateway"]["getNotifiableMembers"]["preview"];
+ checked: boolean;
+ onCheckedChange: (checked: boolean) => void;
+};
+
+export function NotifyMembersToggle({
+ memberCount,
+ previewMembers,
+ checked,
+ onCheckedChange,
+}: NotifyMembersToggleProps) {
+ const id = useId();
+ const overflowCount = memberCount - previewMembers.length;
+
+ return (
+ <div className="flex items-center gap-3">
+ <div className="ph-no-capture flex shrink-0 items-center -space-x-1">
+ {previewMembers.map((member) => (
+ <span
+ key={member.id}
+ className="ring-background inline-flex rounded-full ring-2"
+ >
+ <Avatar
+ size="sm"
+ tone="tinted"
+ displayName={member.name ?? member.email ?? ""}
+ email={member.email ?? undefined}
+ src={member.image ?? undefined}
+ />
+ </span>
+ ))}
+ {overflowCount > 0 ? (
+ <span className="bg-muted text-foreground-secondary ring-background flex size-6 items-center justify-center rounded-full text-[10px] ring-2">
+ +{overflowCount}
+ </span>
+ ) : null}
+ </div>
+ <label
+ htmlFor={id}
+ className="flex min-w-0 flex-1 cursor-pointer flex-col"
+ >
+ <span className="text-sm">
+ Notify the {memberCount} existing member
+ {memberCount === 1 ? "" : "s"}
+ </span>
+ <span className="text-muted-foreground text-xs">
+ They get an email that the AI Gateway is available.
+ </span>
+ </label>
+ <Switch
+ id={id}
+ size="sm"
+ checked={checked}
+ onCheckedChange={onCheckedChange}
+ />
+ </div>
+ );
+}
diff --git a/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/fns/getSetupStepStatus.ts b/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/fns/getSetupStepStatus.ts
new file mode 100644
index 0000000000..b7e3b4bdda
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewaySetupPage/components/GatewaySetupGuide/fns/getSetupStepStatus.ts
@@ -0,0 +1,5 @@
+export function getSetupStepStatus(step: number, activeStep: number) {
+ if (step < activeStep) return "complete" as const;
+ if (step === activeStep) return "current" as const;
+ return "upcoming" as const;
+}
diff --git a/web/src/features/ai-gateway/components/GatewaySetupPage/components/IngestionSettingsFields/IngestionSettingsFields.stories.tsx b/web/src/features/ai-gateway/components/GatewaySetupPage/components/IngestionSettingsFields/IngestionSettingsFields.stories.tsx
new file mode 100644
index 0000000000..4fafaa2120
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewaySetupPage/components/IngestionSettingsFields/IngestionSettingsFields.stories.tsx
@@ -0,0 +1,48 @@
+import { fn } from "storybook/test";
+
+import preview from "@/.storybook/preview";
+import { IngestionSettingsFields } from "./IngestionSettingsFields";
+
+const meta = preview.meta({ component: IngestionSettingsFields });
+
+const projects = [
+ { id: "project-production", name: "Production" },
+ { id: "project-staging", name: "Staging" },
+];
+
+export const NewProject = meta.story({
+ args: {
+ settings: {
+ ingestionMode: "USAGE",
+ projectTarget: "new",
+ newProjectName: "ai-gateway",
+ existingProjectId: undefined,
+ },
+ projects,
+ onChange: fn(),
+ },
+});
+
+export const ExistingProject = meta.story({
+ args: {
+ ...NewProject.input.args,
+ settings: {
+ ingestionMode: "FULL",
+ projectTarget: "existing",
+ newProjectName: "ai-gateway",
+ existingProjectId: "project-staging",
+ },
+ },
+});
+
+export const NoRecording = meta.story({
+ args: {
+ ...NewProject.input.args,
+ settings: {
+ ingestionMode: "NONE",
+ projectTarget: "new",
+ newProjectName: "ai-gateway",
+ existingProjectId: undefined,
+ },
+ },
+});
diff --git a/web/src/features/ai-gateway/components/GatewaySetupPage/components/IngestionSettingsFields/IngestionSettingsFields.tsx b/web/src/features/ai-gateway/components/GatewaySetupPage/components/IngestionSettingsFields/IngestionSettingsFields.tsx
new file mode 100644
index 0000000000..ed0d5732f5
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewaySetupPage/components/IngestionSettingsFields/IngestionSettingsFields.tsx
@@ -0,0 +1,47 @@
+import type { GatewayIngestionMode } from "@langfuse/shared";
+
+import { IngestionModeCard } from "@/src/features/ai-gateway/components/GatewaySetupPage/components/IngestionSettingsFields/components/IngestionModeCard";
+import { IngestionProjectRow } from "@/src/features/ai-gateway/components/GatewaySetupPage/components/IngestionSettingsFields/components/IngestionProjectRow";
+import type {
+ GatewayIngestionSettings,
+ GatewayProject,
+} from "@/src/features/ai-gateway/components/GatewaySetupPage/types/gatewaySetup";
+import { GATEWAY_INGESTION_MODES } from "@/src/features/ai-gateway/constants/gatewayIngestionModes";
+
+export type IngestionSettingsFieldsProps = {
+ settings: GatewayIngestionSettings;
+ projects: GatewayProject[];
+ onChange: (settings: GatewayIngestionSettings) => void;
+};
+
+export function IngestionSettingsFields({
+ settings,
+ projects,
+ onChange,
+}: IngestionSettingsFieldsProps) {
+ function handleModeSelect(ingestionMode: GatewayIngestionMode) {
+ onChange({ ...settings, ingestionMode });
+ }
+
+ return (
+ <div className="flex flex-col gap-4">
+ <div className="grid gap-2 md:grid-cols-3">
+ {GATEWAY_INGESTION_MODES.map((option) => (
+ <IngestionModeCard
+ key={option.value}
+ option={option}
+ selected={settings.ingestionMode === option.value}
+ onSelect={handleModeSelect}
+ />
+ ))}
+ </div>
+ {settings.ingestionMode === "NONE" ? null : (
+ <IngestionProjectRow
+ settings={settings}
+ projects={projects}
+ onChange={onChange}
+ />
+ )}
+ </div>
+ );
+}
diff --git a/web/src/features/ai-gateway/components/GatewaySetupPage/components/IngestionSettingsFields/components/IngestionModeCard.tsx b/web/src/features/ai-gateway/components/GatewaySetupPage/components/IngestionSettingsFields/components/IngestionModeCard.tsx
new file mode 100644
index 0000000000..810c599043
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewaySetupPage/components/IngestionSettingsFields/components/IngestionModeCard.tsx
@@ -0,0 +1,46 @@
+import { Check } from "@langfuse/icons";
+import type { GatewayIngestionMode } from "@langfuse/shared";
+
+import type { GATEWAY_INGESTION_MODES } from "@/src/features/ai-gateway/constants/gatewayIngestionModes";
+import { cn } from "@/src/utils/tailwind";
+
+export type IngestionModeCardProps = {
+ option: (typeof GATEWAY_INGESTION_MODES)[number];
+ selected: boolean;
+ onSelect: (mode: GatewayIngestionMode) => void;
+};
+
+export function IngestionModeCard({
+ option,
+ selected,
+ onSelect,
+}: IngestionModeCardProps) {
+ const Icon = option.icon;
+
+ function handleClick() {
+ onSelect(option.value);
+ }
+
+ return (
+ <button
+ type="button"
+ aria-pressed={selected}
+ onClick={handleClick}
+ className={cn(
+ "bg-card hover:bg-muted/50 flex flex-col items-start gap-2 rounded-md border p-3 text-left transition-colors",
+ selected && "border-primary ring-primary ring-1",
+ )}
+ >
+ <div className="flex w-full items-center justify-between gap-2">
+ <Icon size="base" color="muted" />
+ {selected ? <Check size="base" __rawClassName="text-primary" /> : null}
+ </div>
+ <div>
+ <p className="text-sm font-bold">{option.title}</p>
+ <p className="text-muted-foreground mt-0.5 text-xs">
+ {option.description}
+ </p>
+ </div>
+ </button>
+ );
+}
diff --git a/web/src/features/ai-gateway/components/GatewaySetupPage/components/IngestionSettingsFields/components/IngestionProjectRow.tsx b/web/src/features/ai-gateway/components/GatewaySetupPage/components/IngestionSettingsFields/components/IngestionProjectRow.tsx
new file mode 100644
index 0000000000..bb4bb14e5b
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewaySetupPage/components/IngestionSettingsFields/components/IngestionProjectRow.tsx
@@ -0,0 +1,89 @@
+import type { ChangeEvent } from "react";
+
+import { Input } from "@/src/components/design-system/Input/Input";
+import { SelectInput } from "@/src/components/design-system/SelectInput/SelectInput";
+import type {
+ GatewayIngestionSettings,
+ GatewayProject,
+} from "@/src/features/ai-gateway/components/GatewaySetupPage/types/gatewaySetup";
+
+export type IngestionProjectRowProps = {
+ settings: GatewayIngestionSettings;
+ projects: GatewayProject[];
+ onChange: (settings: GatewayIngestionSettings) => void;
+};
+
+/** Reads as one sentence: "Record in a [new] project named [ai-gateway]". */
+export function IngestionProjectRow({
+ settings,
+ projects,
+ onChange,
+}: IngestionProjectRowProps) {
+ const targetOptions = [
+ { value: "new" as const, label: "new" },
+ projects.length > 0
+ ? { value: "existing" as const, label: "existing" }
+ : {
+ value: "existing" as const,
+ label: "existing",
+ disabled: true as const,
+ disabledReason: "This organization has no projects yet.",
+ },
+ ];
+ const projectOptions = projects.map((project) => ({
+ value: project.id,
+ label: project.name,
+ }));
+
+ function handleTargetChange(projectTarget: "new" | "existing") {
+ onChange({ ...settings, projectTarget });
+ }
+
+ function handleNameChange(event: ChangeEvent<HTMLInputElement>) {
+ onChange({ ...settings, newProjectName: event.target.value });
+ }
+
+ function handleProjectChange(existingProjectId: string) {
+ onChange({ ...settings, existingProjectId });
+ }
+
+ const isNewProject = settings.projectTarget === "new";
+
+ return (
+ <div className="flex flex-wrap items-center gap-2 text-sm">
+ <span>{isNewProject ? "Record in a" : "Record in an"}</span>
+ <div className="w-fit">
+ <SelectInput
+ aria-label="New or existing project"
+ placeholder="new"
+ value={settings.projectTarget}
+ options={targetOptions}
+ onValueChange={handleTargetChange}
+ />
+ </div>
+ <span>{isNewProject ? "project named" : "project"}</span>
+ {isNewProject ? (
+ <div className="ph-no-capture w-fit">
+ <Input
+ layout="inline"
+ aria-label="Project name"
+ value={settings.newProjectName}
+ onChange={handleNameChange}
+ error={settings.newProjectName.trim().length === 0}
+ />
+ </div>
+ ) : (
+ <div className="ph-no-capture w-fit">
+ <SelectInput
+ aria-label="Ingestion project"
+ placeholder="Select a project"
+ search={{ placeholder: "Search projects" }}
+ value={settings.existingProjectId ?? ""}
+ options={projectOptions}
+ onValueChange={handleProjectChange}
+ />
+ </div>
+ )}
+ </div>
+ );
+}
diff --git a/web/src/features/ai-gateway/components/GatewayProvidersPage/components/ProviderDialogController/ProviderDialogController.tsx b/web/src/features/ai-gateway/components/GatewaySetupPage/components/ProviderDialogController/ProviderDialogController.tsx
similarity index 96%
rename from web/src/features/ai-gateway/components/GatewayProvidersPage/components/ProviderDialogController/ProviderDialogController.tsx
rename to web/src/features/ai-gateway/components/GatewaySetupPage/components/ProviderDialogController/ProviderDialogController.tsx
index 6430810713..9910e89223 100644
--- a/web/src/features/ai-gateway/components/GatewayProvidersPage/components/ProviderDialogController/ProviderDialogController.tsx
+++ b/web/src/features/ai-gateway/components/GatewaySetupPage/components/ProviderDialogController/ProviderDialogController.tsx
@@ -13,8 +13,8 @@ import {
} from "@/src/components/ui/dialog";
import { Input } from "@/src/components/ui/input";
import { Label } from "@/src/components/ui/label";
-import { CredentialFields } from "@/src/features/ai-gateway/components/GatewayProvidersPage/components/CredentialFields";
-import { ProviderSelect } from "@/src/features/ai-gateway/components/GatewayProvidersPage/components/ProviderSelect";
+import { CredentialFields } from "@/src/features/ai-gateway/components/GatewaySetupPage/components/ProviderDialogController/components/CredentialFields/CredentialFields";
+import { ProviderSelect } from "@/src/features/ai-gateway/components/GatewaySetupPage/components/ProviderDialogController/components/ProviderSelect";
import { providerLabels } from "@/src/features/ai-gateway/constants/providerLabels";
import { isGatewayConnectionNameError } from "@/src/features/ai-gateway/fns/isGatewayConnectionNameError";
import { suggestGatewayConnectionName } from "@/src/features/ai-gateway/fns/suggestGatewayConnectionName";
@@ -27,8 +27,8 @@ import {
reportNonTrpcError,
reportTrpcErrorWithoutToast,
} from "@/src/utils/api";
-import { getLiveConnectionNameError } from "@/src/features/ai-gateway/components/GatewayProvidersPage/components/ProviderDialogController/fns/getLiveConnectionNameError";
-import { useExistingConnectionNames } from "@/src/features/ai-gateway/components/GatewayProvidersPage/components/ProviderDialogController/hooks/useExistingConnectionNames";
+import { getLiveConnectionNameError } from "@/src/features/ai-gateway/components/GatewaySetupPage/components/ProviderDialogController/fns/getLiveConnectionNameError";
+import { useExistingConnectionNames } from "@/src/features/ai-gateway/components/GatewaySetupPage/components/ProviderDialogController/hooks/useExistingConnectionNames";
export function ProviderDialogController({
organizationId,
diff --git a/web/src/features/ai-gateway/components/GatewayProvidersPage/components/CredentialFields.stories.tsx b/web/src/features/ai-gateway/components/GatewaySetupPage/components/ProviderDialogController/components/CredentialFields/CredentialFields.stories.tsx
similarity index 71%
rename from web/src/features/ai-gateway/components/GatewayProvidersPage/components/CredentialFields.stories.tsx
rename to web/src/features/ai-gateway/components/GatewaySetupPage/components/ProviderDialogController/components/CredentialFields/CredentialFields.stories.tsx
index 1c19ea26f8..53db4140ac 100644
--- a/web/src/features/ai-gateway/components/GatewayProvidersPage/components/CredentialFields.stories.tsx
+++ b/web/src/features/ai-gateway/components/GatewaySetupPage/components/ProviderDialogController/components/CredentialFields/CredentialFields.stories.tsx
@@ -3,7 +3,17 @@ import { fn } from "storybook/test";
import preview from "@/.storybook/preview";
import { CredentialFields } from "./CredentialFields";
-const meta = preview.meta({ component: CredentialFields });
+const meta = preview.meta({
+ component: CredentialFields,
+ // The fields render as siblings; the provider dialog body spaces them.
+ decorators: [
+ (Story) => (
+ <div className="flex flex-col gap-4">
+ <Story />
+ </div>
+ ),
+ ],
+});
const callbacks = {
onNameChange: fn(),
diff --git a/web/src/features/ai-gateway/components/GatewayProvidersPage/components/CredentialFields.tsx b/web/src/features/ai-gateway/components/GatewaySetupPage/components/ProviderDialogController/components/CredentialFields/CredentialFields.tsx
similarity index 100%
rename from web/src/features/ai-gateway/components/GatewayProvidersPage/components/CredentialFields.tsx
rename to web/src/features/ai-gateway/components/GatewaySetupPage/components/ProviderDialogController/components/CredentialFields/CredentialFields.tsx
diff --git a/web/src/features/ai-gateway/components/GatewayProvidersPage/components/ProviderSelect.tsx b/web/src/features/ai-gateway/components/GatewaySetupPage/components/ProviderDialogController/components/ProviderSelect.tsx
similarity index 100%
rename from web/src/features/ai-gateway/components/GatewayProvidersPage/components/ProviderSelect.tsx
rename to web/src/features/ai-gateway/components/GatewaySetupPage/components/ProviderDialogController/components/ProviderSelect.tsx
diff --git a/web/src/features/ai-gateway/components/GatewayProvidersPage/components/ProviderDialogController/fns/getLiveConnectionNameError.clienttest.ts b/web/src/features/ai-gateway/components/GatewaySetupPage/components/ProviderDialogController/fns/getLiveConnectionNameError.clienttest.ts
similarity index 100%
rename from web/src/features/ai-gateway/components/GatewayProvidersPage/components/ProviderDialogController/fns/getLiveConnectionNameError.clienttest.ts
rename to web/src/features/ai-gateway/components/GatewaySetupPage/components/ProviderDialogController/fns/getLiveConnectionNameError.clienttest.ts
diff --git a/web/src/features/ai-gateway/components/GatewayProvidersPage/components/ProviderDialogController/fns/getLiveConnectionNameError.ts b/web/src/features/ai-gateway/components/GatewaySetupPage/components/ProviderDialogController/fns/getLiveConnectionNameError.ts
similarity index 100%
rename from web/src/features/ai-gateway/components/GatewayProvidersPage/components/ProviderDialogController/fns/getLiveConnectionNameError.ts
rename to web/src/features/ai-gateway/components/GatewaySetupPage/components/ProviderDialogController/fns/getLiveConnectionNameError.ts
diff --git a/web/src/features/ai-gateway/components/GatewayProvidersPage/components/ProviderDialogController/hooks/useExistingConnectionNames.ts b/web/src/features/ai-gateway/components/GatewaySetupPage/components/ProviderDialogController/hooks/useExistingConnectionNames.ts
similarity index 100%
rename from web/src/features/ai-gateway/components/GatewayProvidersPage/components/ProviderDialogController/hooks/useExistingConnectionNames.ts
rename to web/src/features/ai-gateway/components/GatewaySetupPage/components/ProviderDialogController/hooks/useExistingConnectionNames.ts
diff --git a/web/src/features/ai-gateway/components/GatewaySetupPage/constants/gatewaySetup.ts b/web/src/features/ai-gateway/components/GatewaySetupPage/constants/gatewaySetup.ts
new file mode 100644
index 0000000000..b8239501a4
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewaySetupPage/constants/gatewaySetup.ts
@@ -0,0 +1,6 @@
+export const GATEWAY_SETUP = {
+ title: "Gateway setup",
+ description:
+ "Connect provider credentials and choose how gateway traffic is recorded in Langfuse.",
+ docsUrl: "https://langfuse.com/docs/ai-gateway",
+} as const;
diff --git a/web/src/features/ai-gateway/components/GatewaySetupPage/fns/getInitialIngestionSettings.ts b/web/src/features/ai-gateway/components/GatewaySetupPage/fns/getInitialIngestionSettings.ts
new file mode 100644
index 0000000000..2296904992
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewaySetupPage/fns/getInitialIngestionSettings.ts
@@ -0,0 +1,24 @@
+import { DEFAULT_GATEWAY_INGESTION_PROJECT_NAME } from "@/src/features/ai-gateway/constants/gatewayConfig";
+import type {
+ GatewayConfig,
+ GatewayIngestionSettings,
+ GatewayProject,
+} from "@/src/features/ai-gateway/components/GatewaySetupPage/types/gatewaySetup";
+
+export function getInitialIngestionSettings({
+ config,
+ projects,
+}: {
+ config: GatewayConfig | null;
+ projects: GatewayProject[];
+}): GatewayIngestionSettings {
+ const existingProject = projects.find(
+ (project) => project.id === config?.defaultIngestionProjectId,
+ );
+ return {
+ ingestionMode: config?.ingestionMode ?? "USAGE",
+ projectTarget: existingProject ? "existing" : "new",
+ newProjectName: DEFAULT_GATEWAY_INGESTION_PROJECT_NAME,
+ existingProjectId: existingProject?.id,
+ };
+}
diff --git a/web/src/features/ai-gateway/components/GatewaySetupPage/fns/isGatewayConfigComplete.ts b/web/src/features/ai-gateway/components/GatewaySetupPage/fns/isGatewayConfigComplete.ts
new file mode 100644
index 0000000000..7746578c15
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewaySetupPage/fns/isGatewayConfigComplete.ts
@@ -0,0 +1,11 @@
+import { isGatewayIngestionConfigured } from "@/src/features/ai-gateway/fns/isGatewayIngestionConfigured";
+import type { GatewayConfig } from "@/src/features/ai-gateway/components/GatewaySetupPage/types/gatewaySetup";
+
+export function isGatewayConfigComplete(config: GatewayConfig | null) {
+ if (!config) return false;
+ const project = config.defaultIngestionProject;
+ return isGatewayIngestionConfigured({
+ ingestionMode: config.ingestionMode,
+ hasActiveIngestionProject: project !== null && !project.deletedAt,
+ });
+}
diff --git a/web/src/features/ai-gateway/components/GatewaySetupPage/fns/isIngestionSettingsValid.ts b/web/src/features/ai-gateway/components/GatewaySetupPage/fns/isIngestionSettingsValid.ts
new file mode 100644
index 0000000000..a5d40be082
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewaySetupPage/fns/isIngestionSettingsValid.ts
@@ -0,0 +1,9 @@
+import type { GatewayIngestionSettings } from "@/src/features/ai-gateway/components/GatewaySetupPage/types/gatewaySetup";
+
+export function isIngestionSettingsValid(settings: GatewayIngestionSettings) {
+ if (settings.ingestionMode === "NONE") return true;
+ if (settings.projectTarget === "new") {
+ return settings.newProjectName.trim().length > 0;
+ }
+ return settings.existingProjectId !== undefined;
+}
diff --git a/web/src/features/ai-gateway/components/GatewaySetupPage/hooks/useGatewayConfig.ts b/web/src/features/ai-gateway/components/GatewaySetupPage/hooks/useGatewayConfig.ts
new file mode 100644
index 0000000000..da8791aaae
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewaySetupPage/hooks/useGatewayConfig.ts
@@ -0,0 +1,15 @@
+import { api } from "@/src/utils/api";
+
+export function useGatewayConfig(organizationId: string) {
+ const query = api.aiGateway.getConfig.useQuery({ orgId: organizationId });
+
+ function retry() {
+ query.refetch();
+ }
+
+ // A failed background refetch keeps the cached config, so the page stays mounted.
+ if (query.data)
+ return { status: "success" as const, config: query.data.config };
+ if (query.isError) return { status: "error" as const, retry };
+ return { status: "pending" as const };
+}
diff --git a/web/src/features/ai-gateway/components/GatewaySetupPage/hooks/useGatewaySetupProgress.ts b/web/src/features/ai-gateway/components/GatewaySetupPage/hooks/useGatewaySetupProgress.ts
new file mode 100644
index 0000000000..57530eb462
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewaySetupPage/hooks/useGatewaySetupProgress.ts
@@ -0,0 +1,28 @@
+import { isGatewayConfigComplete } from "@/src/features/ai-gateway/components/GatewaySetupPage/fns/isGatewayConfigComplete";
+import type { GatewayConfig } from "@/src/features/ai-gateway/components/GatewaySetupPage/types/gatewaySetup";
+import { api } from "@/src/utils/api";
+
+/** The open step follows saved state, so a half-finished setup resumes where it stopped. */
+export function useGatewaySetupProgress({
+ organizationId,
+ config,
+}: {
+ organizationId: string;
+ config: GatewayConfig | null;
+}) {
+ const connectionsQuery = api.aiGateway.listConnections.useQuery({
+ orgId: organizationId,
+ limit: 1,
+ });
+ const firstConnection = connectionsQuery.data?.data[0];
+
+ let activeStep: 1 | 2 | 3 = 3;
+ if (!isGatewayConfigComplete(config)) activeStep = 1;
+ else if (firstConnection === undefined) activeStep = 2;
+
+ return {
+ activeStep,
+ firstConnection,
+ isPending: connectionsQuery.isPending,
+ };
+}
diff --git a/web/src/features/ai-gateway/components/GatewaySetupPage/hooks/useGatewayTeamInvite.ts b/web/src/features/ai-gateway/components/GatewaySetupPage/hooks/useGatewayTeamInvite.ts
new file mode 100644
index 0000000000..024c993308
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewaySetupPage/hooks/useGatewayTeamInvite.ts
@@ -0,0 +1,34 @@
+import { api, reportNonTrpcError } from "@/src/utils/api";
+
+export function useGatewayTeamInvite(organizationId: string) {
+ const utils = api.useUtils();
+ const notifiableMembersQuery = api.aiGateway.getNotifiableMembers.useQuery({
+ orgId: organizationId,
+ });
+ const mutation = api.aiGateway.inviteTeam.useMutation();
+
+ async function inviteTeam(params: {
+ emails: string[];
+ notifyMembers: boolean;
+ }) {
+ try {
+ const result = await mutation.mutateAsync({
+ orgId: organizationId,
+ ...params,
+ });
+ await utils.aiGateway.getNotifiableMembers.invalidate({
+ orgId: organizationId,
+ });
+ return result;
+ } catch (error) {
+ reportNonTrpcError(error, "ai-gateway-team-invite");
+ return null;
+ }
+ }
+
+ return {
+ notifiableMembers: notifiableMembersQuery.data,
+ inviteTeam,
+ isInviting: mutation.isPending,
+ };
+}
diff --git a/web/src/features/ai-gateway/components/GatewaySetupPage/hooks/useSaveGatewayIngestion.ts b/web/src/features/ai-gateway/components/GatewaySetupPage/hooks/useSaveGatewayIngestion.ts
new file mode 100644
index 0000000000..098bd0f738
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewaySetupPage/hooks/useSaveGatewayIngestion.ts
@@ -0,0 +1,63 @@
+import { useRef, useState } from "react";
+import { useSession } from "next-auth/react";
+
+import type { GatewayIngestionSettings } from "@/src/features/ai-gateway/components/GatewaySetupPage/types/gatewaySetup";
+import { api, reportNonTrpcError } from "@/src/utils/api";
+
+/** Saves ingestion settings, creating the ingestion project first when a new one is named. */
+export function useSaveGatewayIngestion(organizationId: string) {
+ const session = useSession();
+ const utils = api.useUtils();
+ const createProject = api.projects.create.useMutation();
+ const updateConfig = api.aiGateway.updateConfig.useMutation();
+ // Spans every request and the refetch, so callers stay busy until the saved config is shown.
+ const [isSaving, setIsSaving] = useState(false);
+ // A save can fail after creating the project; the retry must not create it again.
+ const createdProjectRef = useRef<{ name: string; id: string } | null>(null);
+
+ async function resolveProjectId(settings: GatewayIngestionSettings) {
+ if (settings.projectTarget === "existing") {
+ return settings.existingProjectId ?? null;
+ }
+ // None keeps an already linked project but never creates one.
+ if (settings.ingestionMode === "NONE") return null;
+ const name = settings.newProjectName.trim();
+ if (createdProjectRef.current?.name === name) {
+ return createdProjectRef.current.id;
+ }
+ const project = await createProject.mutateAsync({
+ orgId: organizationId,
+ name,
+ });
+ createdProjectRef.current = { name, id: project.id };
+ // The organization's project list comes from the session.
+ await session.update();
+ return project.id;
+ }
+
+ async function saveIngestion(settings: GatewayIngestionSettings) {
+ setIsSaving(true);
+ try {
+ await updateConfig.mutateAsync({
+ orgId: organizationId,
+ defaultIngestionProjectId: await resolveProjectId(settings),
+ ingestionMode: settings.ingestionMode,
+ });
+ await Promise.all([
+ utils.aiGateway.getConfig.invalidate({ orgId: organizationId }),
+ utils.aiGateway.getSetupStatus.invalidate({ orgId: organizationId }),
+ ]);
+ return true;
+ } catch (error) {
+ reportNonTrpcError(error, "ai-gateway-configuration");
+ return false;
+ } finally {
+ setIsSaving(false);
+ }
+ }
+
+ return {
+ saveIngestion,
+ isSaving,
+ };
+}
diff --git a/web/src/features/ai-gateway/components/GatewaySetupPage/types/gatewaySetup.ts b/web/src/features/ai-gateway/components/GatewaySetupPage/types/gatewaySetup.ts
new file mode 100644
index 0000000000..633b1d39c9
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewaySetupPage/types/gatewaySetup.ts
@@ -0,0 +1,21 @@
+import type { GatewayIngestionMode } from "@langfuse/shared";
+
+import type { RouterOutputs } from "@/src/utils/api";
+
+export type GatewayConfig = NonNullable<
+ RouterOutputs["aiGateway"]["getConfig"]["config"]
+>;
+
+export type GatewayProject = { id: string; name: string };
+
+export type GatewayNotifiableMembers =
+ RouterOutputs["aiGateway"]["getNotifiableMembers"];
+
+export type GatewayTeamInviteResult = RouterOutputs["aiGateway"]["inviteTeam"];
+
+export type GatewayIngestionSettings = {
+ ingestionMode: GatewayIngestionMode;
+ projectTarget: "new" | "existing";
+ newProjectName: string;
+ existingProjectId: string | undefined;
+};
diff --git a/web/src/features/ai-gateway/constants/gatewayConfig.ts b/web/src/features/ai-gateway/constants/gatewayConfig.ts
index 8d929e734c..986ba41429 100644
--- a/web/src/features/ai-gateway/constants/gatewayConfig.ts
+++ b/web/src/features/ai-gateway/constants/gatewayConfig.ts
@@ -1,5 +1 @@
-export const DEFAULT_GATEWAY_INGESTION_PROJECT_NAME = "AI Gateway Ingestion";
-
-export const GATEWAY_CONFIGURATION_TITLE = "AI Gateway configuration";
-export const GATEWAY_CONFIGURATION_DESCRIPTION =
- "Configure how requests routed through the organization gateway are ingested into Langfuse.";
+export const DEFAULT_GATEWAY_INGESTION_PROJECT_NAME = "ai-gateway";
diff --git a/web/src/features/ai-gateway/constants/gatewayIngestionModes.ts b/web/src/features/ai-gateway/constants/gatewayIngestionModes.ts
new file mode 100644
index 0000000000..c5af871c58
--- /dev/null
+++ b/web/src/features/ai-gateway/constants/gatewayIngestionModes.ts
@@ -0,0 +1,28 @@
+import { EyeOff, Gauge, ScanText, type IconComponent } from "@langfuse/icons";
+import type { GatewayIngestionMode } from "@langfuse/shared";
+
+export const GATEWAY_INGESTION_MODES: ReadonlyArray<{
+ value: GatewayIngestionMode;
+ title: string;
+ description: string;
+ icon: IconComponent;
+}> = [
+ {
+ value: "NONE",
+ title: "None",
+ description: "Route requests without capturing anything in Langfuse.",
+ icon: EyeOff,
+ },
+ {
+ value: "USAGE",
+ title: "Usage",
+ description: "Capture model, token usage, cost, and latency.",
+ icon: Gauge,
+ },
+ {
+ value: "FULL",
+ title: "Full",
+ description: "Capture full request and response payloads for tracing.",
+ icon: ScanText,
+ },
+];
diff --git a/web/src/features/ai-gateway/constants/gatewayTeamInvites.ts b/web/src/features/ai-gateway/constants/gatewayTeamInvites.ts
new file mode 100644
index 0000000000..0aea625a0e
--- /dev/null
+++ b/web/src/features/ai-gateway/constants/gatewayTeamInvites.ts
@@ -0,0 +1 @@
+export const MAX_TEAM_INVITES = 50;
diff --git a/web/src/features/ai-gateway/fns/gatewayUrls/buildGatewayModelsUrl.ts b/web/src/features/ai-gateway/fns/gatewayUrls/buildGatewayModelsUrl.ts
index ff0a9801be..badd2aee4a 100644
--- a/web/src/features/ai-gateway/fns/gatewayUrls/buildGatewayModelsUrl.ts
+++ b/web/src/features/ai-gateway/fns/gatewayUrls/buildGatewayModelsUrl.ts
@@ -4,5 +4,5 @@ export function buildGatewayModelsUrl(
) {
const params = new URLSearchParams({ connectionId });
- return `/organization/${encodeURIComponent(organizationId)}/settings/ai-gateway-providers?${params.toString()}`;
+ return `/organization/${encodeURIComponent(organizationId)}/settings/ai-gateway?${params.toString()}`;
}
diff --git a/web/src/features/ai-gateway/index.ts b/web/src/features/ai-gateway/index.ts
index edb046ca3c..e868056264 100644
--- a/web/src/features/ai-gateway/index.ts
+++ b/web/src/features/ai-gateway/index.ts
@@ -1,4 +1,3 @@
export { GatewayApiKeysPage } from "@/src/features/ai-gateway/components/GatewayApiKeysPage/GatewayApiKeysPage";
-export { GatewayConfigurationPage } from "@/src/features/ai-gateway/components/GatewayConfigurationPage/GatewayConfigurationPage";
export { GatewayModelsPage } from "@/src/features/ai-gateway/components/GatewayModelsPage/GatewayModelsPage";
-export { GatewayProvidersPage } from "@/src/features/ai-gateway/components/GatewayProvidersPage/GatewayProvidersPage";
+export { GatewaySetupPage } from "@/src/features/ai-gateway/components/GatewaySetupPage/GatewaySetupPage";
diff --git a/web/src/features/ai-gateway/server/gatewaySetupRedirect.ts b/web/src/features/ai-gateway/server/gatewaySetupRedirect.ts
index a6243dfbd2..dbd747a37d 100644
--- a/web/src/features/ai-gateway/server/gatewaySetupRedirect.ts
+++ b/web/src/features/ai-gateway/server/gatewaySetupRedirect.ts
@@ -6,14 +6,13 @@ import { isGatewayEnabledForOrganization } from "@/src/features/ai-gateway/serve
import { GatewayConfigService } from "@/src/features/ai-gateway/server/config/gatewayConfigService";
const SETUP_GATED_SETTINGS_SLUGS = new Set([
- "ai-gateway-providers",
"ai-gateway-models",
"ai-gateway-api-keys",
]);
/**
- * Gateway managers cannot open provider, model or API key settings before an
- * ingestion project is configured; they are sent to the configuration page.
+ * Gateway managers cannot open model or API key settings before an ingestion
+ * project is configured; they are sent to the setup page.
* Other members are not redirected because their Models and API key pages
* explain the state.
*/
diff --git a/web/src/features/ai-gateway/server/router.ts b/web/src/features/ai-gateway/server/router.ts
index 5719fcfc10..c57d502b06 100644
--- a/web/src/features/ai-gateway/server/router.ts
+++ b/web/src/features/ai-gateway/server/router.ts
@@ -28,7 +28,9 @@ import {
} from "./apiKey/gatewayApiKeyService";
import { requireGatewayEnabledForOrganization } from "./availability";
import { getGatewayBaseUrl } from "@/src/features/ai-gateway/fns/gatewayUrls/getGatewayBaseUrl";
+import { MAX_TEAM_INVITES } from "@/src/features/ai-gateway/constants/gatewayTeamInvites";
import { GatewayConfigService } from "./config/gatewayConfigService";
+import { GatewayTeamService } from "./team/gatewayTeamService";
import {
GatewayMetadataSchema,
GatewayModelCatalogService,
@@ -123,7 +125,6 @@ export const aiGatewayRouter = createTRPCRouter({
config: await new GatewayConfigService(ctx.prisma).getConfig(
input.orgId,
),
- gatewayBaseUrl: getGatewayBaseUrl(getProductBaseUrl()),
};
}),
@@ -169,6 +170,34 @@ export const aiGatewayRouter = createTRPCRouter({
});
}),
+ getNotifiableMembers: protectedOrganizationProcedure
+ .input(organizationInput)
+ .query(async ({ input, ctx }) => {
+ requireGatewayAdmin({ session: ctx.session, orgId: input.orgId });
+ return new GatewayTeamService(ctx.prisma).getNotifiableMembers({
+ organizationId: input.orgId,
+ currentUserId: ctx.session.user.id,
+ });
+ }),
+
+ /** Invites new people as members and optionally tells existing members. */
+ inviteTeam: protectedOrganizationProcedure
+ .input(
+ organizationInput.extend({
+ emails: z.array(z.email()).max(MAX_TEAM_INVITES),
+ notifyMembers: z.boolean(),
+ }),
+ )
+ .mutation(async ({ input, ctx }) => {
+ requireGatewayAdmin({ session: ctx.session, orgId: input.orgId });
+ return new GatewayTeamService(ctx.prisma).inviteTeam({
+ ctx,
+ organizationId: input.orgId,
+ emails: input.emails,
+ notifyMembers: input.notifyMembers,
+ });
+ }),
+
listConnections: protectedOrganizationProcedure
.input(paginatedOrganizationInput)
.query(async ({ input, ctx }) => {
diff --git a/web/src/features/ai-gateway/server/team/gatewayTeamService.ts b/web/src/features/ai-gateway/server/team/gatewayTeamService.ts
new file mode 100644
index 0000000000..07cfa2b41e
--- /dev/null
+++ b/web/src/features/ai-gateway/server/team/gatewayTeamService.ts
@@ -0,0 +1,225 @@
+import { createHash, randomUUID } from "crypto";
+import { TRPCError } from "@trpc/server";
+import { getHTTPStatusCodeFromError } from "@trpc/server/http";
+
+import { Role } from "@langfuse/shared";
+import type { PrismaClient } from "@langfuse/shared/src/db";
+import {
+ logger,
+ type NotificationEventType,
+ NotificationQueue,
+ QueueJobs,
+} from "@langfuse/shared/src/server";
+
+import { env } from "@/src/env.mjs";
+import {
+ inviteOrganizationMember,
+ OrganizationMembersService,
+} from "@/src/features/rbac/server";
+import type { OrgAuthedContext } from "@/src/server/api/trpc";
+
+const MEMBER_PREVIEW_LIMIT = 4;
+const GATEWAY_USER_SCOPE = "gateway:invoke";
+
+type GatewayInvitationEmail = Extract<
+ NotificationEventType,
+ { type: "AI_GATEWAY_INVITATION" }
+>;
+
+/** Client errors carry messages written for the user; others may leak internals. */
+function getClientErrorMessage(error: unknown) {
+ if (!(error instanceof TRPCError)) return null;
+ const status = getHTTPStatusCodeFromError(error);
+ return status >= 400 && status < 500 ? error.message : null;
+}
+
+/** Job ids are logged and used as Redis keys, so they carry a hash, not the address. */
+function getInvitationJobId(payload: GatewayInvitationEmail) {
+ const recipientHash = createHash("sha256")
+ .update(payload.to.toLowerCase())
+ .digest("hex");
+ return `ai-gateway-invitation-${payload.orgId}-${payload.audience.kind}-${recipientHash}`;
+}
+
+function isEmailConfigured() {
+ return Boolean(env.SMTP_CONNECTION_URL && env.EMAIL_FROM_ADDRESS);
+}
+
+type GatewayTeamContext = Pick<OrgAuthedContext, "session" | "prisma">;
+
+/**
+ * Owns every email the gateway setup sends: invitations for new people (as
+ * organization members) and the announcement to existing members who can use
+ * the gateway. Emails are queued, one job per recipient, and sent by the worker.
+ */
+export class GatewayTeamService {
+ private readonly members: OrganizationMembersService;
+
+ constructor(prisma: PrismaClient) {
+ this.members = new OrganizationMembersService(prisma);
+ }
+
+ async getNotifiableMembers(params: {
+ organizationId: string;
+ currentUserId: string;
+ }) {
+ const query = {
+ organizationId: params.organizationId,
+ scope: GATEWAY_USER_SCOPE,
+ excludeUserId: params.currentUserId,
+ } as const;
+ const [count, preview] = await Promise.all([
+ this.members.countMembersWithScope(query),
+ this.members.findMembersWithScope({
+ ...query,
+ limit: MEMBER_PREVIEW_LIMIT,
+ }),
+ ]);
+ return { isEmailConfigured: isEmailConfigured(), count, preview };
+ }
+
+ async inviteTeam(params: {
+ ctx: GatewayTeamContext;
+ organizationId: string;
+ emails: string[];
+ notifyMembers: boolean;
+ }) {
+ const { ctx, organizationId } = params;
+ const sendsEmail = isEmailConfigured();
+ const queue = sendsEmail ? NotificationQueue.getInstance() : null;
+ // Checked before inviting so a missing queue does not leave invitations without emails.
+ if (sendsEmail && !queue) {
+ throw new TRPCError({
+ code: "INTERNAL_SERVER_ERROR",
+ message: "The email queue is unavailable. Try again later.",
+ });
+ }
+
+ const orgName = await this.members.getOrganizationName(organizationId);
+ const sender = {
+ type: "AI_GATEWAY_INVITATION",
+ orgId: organizationId,
+ orgName,
+ inviterName: ctx.session.user.name ?? ctx.session.user.email ?? "",
+ inviterEmail: ctx.session.user.email ?? "",
+ } as const;
+ const emailJobs: GatewayInvitationEmail[] = [];
+
+ const emails = [
+ ...new Set(params.emails.map((email) => email.trim().toLowerCase())),
+ ];
+ const existingMembers = new Map(
+ (
+ await this.members.findMembersByEmail({
+ organizationId,
+ emails,
+ scope: GATEWAY_USER_SCOPE,
+ })
+ ).map((member) => [member.email.toLowerCase(), member]),
+ );
+
+ const invited = new Set<string>();
+ const notified = new Set<string>();
+ const failed: Array<{ email: string; message: string }> = [];
+ for (const email of emails) {
+ const member = existingMembers.get(email);
+ // Typing a member's address means "tell them", so they get the member
+ // announcement rather than an "already a member" invitation error.
+ if (member) {
+ if (member.id === ctx.session.user.id) continue;
+ if (!member.hasScope) {
+ failed.push({
+ email,
+ message:
+ "Already a member, but their role can't use the AI Gateway",
+ });
+ continue;
+ }
+ if (sendsEmail) {
+ emailJobs.push({
+ ...sender,
+ to: email,
+ receiverName: member.name ?? undefined,
+ audience: { kind: "member" },
+ });
+ notified.add(email);
+ }
+ continue;
+ }
+
+ try {
+ await inviteOrganizationMember({
+ ctx,
+ input: { orgId: organizationId, email, orgRole: Role.MEMBER },
+ sendInvitationEmail: async ({ to, userExists }) => {
+ emailJobs.push({
+ ...sender,
+ to,
+ audience: { kind: "invitee", hasAccount: userExists },
+ });
+ },
+ });
+ invited.add(email);
+ } catch (error) {
+ const message = getClientErrorMessage(error);
+ if (!message) {
+ logger.error(
+ "Failed to invite organization member to the AI Gateway",
+ {
+ organizationId,
+ error,
+ },
+ );
+ }
+ failed.push({ email, message: message ?? "Invitation failed" });
+ }
+ }
+
+ if (params.notifyMembers && sendsEmail) {
+ const members = await this.members.findMembersWithScope({
+ organizationId,
+ scope: GATEWAY_USER_SCOPE,
+ excludeUserId: ctx.session.user.id,
+ });
+ for (const { email, name } of members) {
+ const to = email.toLowerCase();
+ if (invited.has(to) || notified.has(to)) continue;
+ emailJobs.push({
+ ...sender,
+ to,
+ receiverName: name ?? undefined,
+ audience: { kind: "member" },
+ });
+ notified.add(to);
+ }
+ }
+
+ if (queue && emailJobs.length > 0) {
+ const jobs = emailJobs.map((payload) => ({
+ name: QueueJobs.NotificationJob,
+ data: {
+ timestamp: new Date(),
+ id: randomUUID(),
+ payload,
+ name: QueueJobs.NotificationJob as const,
+ },
+ // A repeated send while the same email is still queued is dropped.
+ opts: { jobId: getInvitationJobId(payload) },
+ }));
+ // Failed jobs are kept for inspection, and a kept id would swallow the re-send.
+ await Promise.all(
+ jobs.map(async ({ opts }) => {
+ const existing = await queue.getJob(opts.jobId);
+ if (existing && (await existing.isFailed())) await existing.remove();
+ }),
+ );
+ await queue.addBulk(jobs);
+ }
+
+ return {
+ invitedCount: invited.size,
+ failed,
+ notifiedCount: notified.size,
+ };
+ }
+}
diff --git a/web/src/features/organizations/OrganizationSettingsPage.tsx b/web/src/features/organizations/OrganizationSettingsPage.tsx
index 8f336ca3f0..883052e3c6 100644
--- a/web/src/features/organizations/OrganizationSettingsPage.tsx
+++ b/web/src/features/organizations/OrganizationSettingsPage.tsx
@@ -27,9 +27,8 @@ import { useV4UpgradeUiFlag } from "@/src/features/v4-migration/useV4UpgradeUiEn
import { OrganizationFeaturePreviewsSettings } from "@/src/features/feature-flags/components/OrganizationFeaturePreviewsSettings";
import {
GatewayApiKeysPage,
- GatewayConfigurationPage,
GatewayModelsPage,
- GatewayProvidersPage,
+ GatewaySetupPage,
} from "@/src/features/ai-gateway";
import { useGatewaySettingsAccess } from "@/src/features/ai-gateway/hooks/useGatewaySettingsAccess";
import useSessionStorage from "@/src/components/useSessionStorage";
@@ -37,7 +36,7 @@ import { api } from "@/src/utils/api";
import { ConnectedLLMApiKeySettingsTable } from "@/src/features/public-api/components/LLMApiKeySettingsTable/ConnectedLLMApiKeySettingsTable";
const GATEWAY_SETUP_REQUIRED_REASON =
- "Set up an ingestion project in Configuration first.";
+ "Set up an ingestion project in Setup first.";
type OrganizationSettingsPage = {
title: string;
@@ -320,32 +319,27 @@ const getOrganizationSettingsPages = ({
show: showV4Migration,
},
{
- title: "Configuration",
+ title: "Setup",
slug: "ai-gateway",
section: "AI Gateway",
- cmdKKeywords: ["gateway", "llm", "configuration", "instrumentation"],
- content: (
- <GatewayConfigurationPage
- organizationId={organization.id}
- projects={organization.projects}
- />
- ),
- show: showAiGatewayManagement,
- },
- {
- title: "Provider credentials",
- slug: "ai-gateway-providers",
- section: "AI Gateway",
cmdKKeywords: [
"gateway",
+ "llm",
+ "setup",
+ "configuration",
+ "ingestion",
"providers",
"credentials",
"openai",
"anthropic",
],
- content: <GatewayProvidersPage organizationId={organization.id} />,
+ content: (
+ <GatewaySetupPage
+ organizationId={organization.id}
+ projects={organization.projects}
+ />
+ ),
show: showAiGatewayManagement,
- disabledReason: gatewaySetupDisabledReason,
},
{
title: "Models",
diff --git a/web/src/features/rbac/server/index.ts b/web/src/features/rbac/server/index.ts
new file mode 100644
index 0000000000..61a6903ddb
--- /dev/null
+++ b/web/src/features/rbac/server/index.ts
@@ -0,0 +1,2 @@
+export { inviteOrganizationMember } from "./inviteOrganizationMember";
+export { OrganizationMembersService } from "./organizationMembersService";
diff --git a/web/src/features/rbac/server/inviteOrganizationMember.ts b/web/src/features/rbac/server/inviteOrganizationMember.ts
new file mode 100644
index 0000000000..d1b52b3c58
--- /dev/null
+++ b/web/src/features/rbac/server/inviteOrganizationMember.ts
@@ -0,0 +1,401 @@
+import { TRPCError } from "@trpc/server";
+import { Prisma, type PrismaClient, Role } from "@langfuse/shared";
+
+import { auditLog } from "@/src/features/audit-logs/server";
+import { getSfdcService } from "@/src/ee/features/sfdc-sync/server";
+import {
+ createWithinEntitlementLimit,
+ hasEntitlement,
+} from "@/src/features/entitlements/server";
+import { throwIfNoOrganizationAccess } from "@/src/features/rbac/utils/checkOrganizationAccess";
+import { throwIfNoProjectAccess } from "@/src/features/rbac/utils/checkProjectAccess";
+import { throwIfHigherProjectRole } from "@/src/features/rbac/server/throwIfHigherProjectRole";
+import { throwIfHigherRole } from "@/src/features/rbac/server/throwIfHigherRole";
+import type { OrgAuthedContext } from "@/src/server/api/trpc";
+
+async function createProjectMembershipOrThrowIfDuplicate({
+ prisma,
+ data,
+}: {
+ prisma: PrismaClient | Prisma.TransactionClient;
+ data: {
+ userId: string;
+ projectId: string;
+ role: Role;
+ orgMembershipId: string;
+ };
+}) {
+ try {
+ return await prisma.projectMembership.create({ data });
+ } catch (error) {
+ if (
+ error instanceof Prisma.PrismaClientKnownRequestError &&
+ error.code === "P2002"
+ ) {
+ throw new TRPCError({
+ code: "BAD_REQUEST",
+ message: "User is already a member of this project",
+ });
+ }
+ throw error;
+ }
+}
+
+async function createOrgMembershipOrThrowIfDuplicate({
+ prisma,
+ data,
+}: {
+ prisma: PrismaClient | Prisma.TransactionClient;
+ data: {
+ userId: string;
+ orgId: string;
+ role: Role;
+ };
+}) {
+ try {
+ return await prisma.organizationMembership.create({ data });
+ } catch (error) {
+ if (
+ error instanceof Prisma.PrismaClientKnownRequestError &&
+ error.code === "P2002"
+ ) {
+ throw new TRPCError({
+ code: "BAD_REQUEST",
+ message: "User is already a member of this organization",
+ });
+ }
+ throw error;
+ }
+}
+
+type InviteOrganizationMemberParams = {
+ ctx: Pick<OrgAuthedContext, "session" | "prisma">;
+ input: {
+ orgId: string;
+ email: string;
+ orgRole: Role;
+ projectId?: string;
+ projectRole?: Role;
+ };
+ /** Callers pick the email, e.g. the generic organization invite or the AI Gateway invite. */
+ sendInvitationEmail: (recipient: {
+ to: string;
+ orgName: string;
+ userExists: boolean;
+ }) => Promise<void>;
+};
+
+/**
+ * Adds a user to the organization, or creates a pending invitation when no
+ * account exists yet, within the member seat limit, then sends the email.
+ */
+export async function inviteOrganizationMember({
+ ctx,
+ input,
+ sendInvitationEmail,
+}: InviteOrganizationMemberParams) {
+ /**
+ * Create a new organization membership
+ * - Checks for:
+ * - scope: organizationMembers:CUD if not only project-role is set, then projectMembers:CUD
+ * - orgRole is not higher than own role
+ * - if project role
+ * - projectRole is not higher than own role
+ * - entitlement for project roles if projectRole is set
+ * - project is in org
+ * - if user exists
+ * - if org membership exists
+ * - if only project role is set (orgRole === Role.NONE)
+ * - create project role
+ * - audit log
+ * - return
+ * - else throw error
+ * - create org membership
+ * - audit log
+ * - if project role is set
+ * - create project role
+ * - audit log
+ * - send email
+ * - else
+ * - create membership invitation
+ * - audit log
+ * - send email
+ */
+
+ if (
+ // Require only project-level access rights if no orgRole is set but a projectId is
+ input.projectId &&
+ input.orgRole === Role.NONE
+ ) {
+ throwIfNoProjectAccess({
+ session: ctx.session,
+ projectId: input.projectId,
+ scope: "projectMembers:CUD",
+ });
+ } else {
+ // Require org-level access rights
+ throwIfNoOrganizationAccess({
+ session: ctx.session,
+ organizationId: input.orgId,
+ scope: "organizationMembers:CUD",
+ });
+ }
+
+ throwIfHigherRole({
+ ownRole: ctx.session.orgRole,
+ role: input.orgRole,
+ });
+
+ // check for entilement (project role)
+ if (input.projectId && input.projectRole) {
+ const entitled = hasEntitlement({
+ entitlement: "rbac-project-roles",
+ sessionUser: ctx.session.user,
+ orgId: input.orgId,
+ });
+ if (!entitled)
+ throw new TRPCError({
+ code: "FORBIDDEN",
+ message:
+ "Organization does not have the required entitlement to set project roles",
+ });
+ }
+
+ const user = await ctx.prisma.user.findUnique({
+ where: {
+ email: input.email.toLowerCase(),
+ },
+ });
+
+ // security check if project is in org
+ const project = input.projectId
+ ? await ctx.prisma.project.findFirst({
+ where: {
+ id: input.projectId,
+ orgId: input.orgId,
+ deletedAt: null,
+ },
+ })
+ : null;
+ if (project && input.projectRole)
+ await throwIfHigherProjectRole({
+ orgCtx: ctx,
+ projectId: project.id,
+ projectRole: input.projectRole,
+ });
+
+ const org = await ctx.prisma.organization.findFirst({
+ where: {
+ id: input.orgId,
+ },
+ });
+ if (!org) {
+ throw new TRPCError({ code: "NOT_FOUND", message: "Org not found" });
+ }
+
+ // Members and pending invitations both consume a seat, so the limit
+ // check counts them together. Reads through the caller-supplied client
+ // so it can run inside the limit transaction.
+ const countSeatsInUse = async (tx: Prisma.TransactionClient) => {
+ const memberCount = await tx.organizationMembership.count({
+ where: { orgId: input.orgId },
+ });
+ const pendingInviteCount = await tx.membershipInvitation.count({
+ where: { orgId: input.orgId },
+ });
+ return memberCount + pendingInviteCount;
+ };
+
+ if (user) {
+ const existingOrgMembership =
+ await ctx.prisma.organizationMembership.findFirst({
+ where: {
+ orgId: input.orgId,
+ userId: user.id,
+ },
+ });
+
+ // early return if user is already a member of the org
+ if (existingOrgMembership) {
+ // user exists and only a project role shall be added
+ if (
+ input.orgRole === Role.NONE &&
+ project &&
+ input.projectRole &&
+ input.projectRole !== Role.NONE
+ ) {
+ // Create project role for user
+ const newProjectMembership =
+ await createProjectMembershipOrThrowIfDuplicate({
+ prisma: ctx.prisma,
+ data: {
+ userId: user.id,
+ projectId: project.id,
+ role: input.projectRole,
+ orgMembershipId: existingOrgMembership.id,
+ },
+ });
+
+ // audit log
+ await auditLog({
+ session: ctx.session,
+ resourceType: "projectMembership",
+ resourceId: project.id + "--" + user.id,
+ action: "create",
+ after: newProjectMembership,
+ });
+ return;
+ }
+ throw new TRPCError({
+ code: "BAD_REQUEST",
+ message: "User is already a member of this organization",
+ });
+ }
+
+ // A project membership can outlive this org's membership (e.g. a stray
+ // row referencing another org). Reject the duplicate before creating
+ // the org membership so a failed project insert cannot leave a
+ // committed org membership (and consumed seat) behind.
+ if (
+ project &&
+ input.projectRole &&
+ input.projectRole !== Role.NONE &&
+ (await ctx.prisma.projectMembership.findUnique({
+ where: {
+ projectId_userId: { projectId: project.id, userId: user.id },
+ },
+ }))
+ ) {
+ throw new TRPCError({
+ code: "BAD_REQUEST",
+ message: "User is already a member of this project",
+ });
+ }
+
+ // create org membership as user is not a member yet, unless that
+ // would exceed the member limit. On limited plans this runs inside the
+ // entitlement transaction, so creating the project membership here too
+ // keeps both inserts atomic: a duplicate-project-membership rejection
+ // rolls back the org membership instead of leaving a consumed seat.
+ const { orgMembership, projectMembership } =
+ await createWithinEntitlementLimit({
+ prisma: ctx.prisma,
+ orgId: input.orgId,
+ entitlementLimit: "organization-member-count",
+ sessionUser: ctx.session.user,
+ countCurrentUsage: countSeatsInUse,
+ create: async (tx) => {
+ const createdOrgMembership =
+ await createOrgMembershipOrThrowIfDuplicate({
+ prisma: tx,
+ data: {
+ userId: user.id,
+ orgId: input.orgId,
+ role: input.orgRole,
+ },
+ });
+ const createdProjectMembership =
+ project && input.projectRole && input.projectRole !== Role.NONE
+ ? await createProjectMembershipOrThrowIfDuplicate({
+ prisma: tx,
+ data: {
+ userId: user.id,
+ projectId: project.id,
+ role: input.projectRole,
+ orgMembershipId: createdOrgMembership.id,
+ },
+ })
+ : null;
+ return {
+ orgMembership: createdOrgMembership,
+ projectMembership: createdProjectMembership,
+ };
+ },
+ });
+ await auditLog({
+ session: ctx.session,
+ resourceType: "orgMembership",
+ resourceId: orgMembership.id,
+ action: "create",
+ after: orgMembership,
+ });
+ // SFDC: link existing lead to org as a member.
+ await getSfdcService()?.setUserRole({
+ orgId: input.orgId,
+ userId: user.id,
+ email: user.email,
+ role: input.orgRole,
+ });
+ if (projectMembership) {
+ await auditLog({
+ session: ctx.session,
+ resourceType: "projectMembership",
+ resourceId:
+ projectMembership.projectId + "--" + projectMembership.userId,
+ action: "create",
+ after: projectMembership,
+ });
+ }
+ await sendInvitationEmail({
+ to: input.email,
+ orgName: org.name,
+ userExists: true,
+ });
+ } else {
+ try {
+ // create the invitation unless that would exceed the member limit
+ const invitation = await createWithinEntitlementLimit({
+ prisma: ctx.prisma,
+ orgId: input.orgId,
+ entitlementLimit: "organization-member-count",
+ sessionUser: ctx.session.user,
+ countCurrentUsage: countSeatsInUse,
+ create: (tx) =>
+ tx.membershipInvitation.create({
+ data: {
+ orgId: input.orgId,
+ projectId:
+ project && input.projectRole && input.projectRole !== Role.NONE
+ ? project.id
+ : null,
+ email: input.email.toLowerCase(),
+ orgRole: input.orgRole,
+ projectRole:
+ input.projectRole && input.projectRole !== Role.NONE && project
+ ? input.projectRole
+ : null,
+ invitedByUserId: ctx.session.user.id,
+ },
+ }),
+ });
+
+ await auditLog({
+ session: ctx.session,
+ resourceType: "membershipInvitation",
+ resourceId: invitation.id,
+ action: "create",
+ after: invitation,
+ });
+ await sendInvitationEmail({
+ to: input.email,
+ orgName: org.name,
+ userExists: false,
+ });
+
+ return invitation;
+ } catch (error) {
+ if (
+ error instanceof Prisma.PrismaClientKnownRequestError &&
+ error.code === "P2002"
+ ) {
+ throw new TRPCError({
+ code: "BAD_REQUEST",
+ message:
+ "A pending membership invitation with this email and organization already exists",
+ });
+ } else {
+ throw error;
+ }
+ }
+ }
+}
diff --git a/web/src/features/rbac/server/membersRouter.ts b/web/src/features/rbac/server/membersRouter.ts
index 7f0a85d09b..6abef79611 100644
--- a/web/src/features/rbac/server/membersRouter.ts
+++ b/web/src/features/rbac/server/membersRouter.ts
@@ -14,7 +14,6 @@ import {
type FilterState,
optionalPaginationZod,
Prisma,
- type PrismaClient,
Role,
} from "@langfuse/shared";
import {
@@ -25,10 +24,7 @@ import {
} from "@langfuse/shared/src/server";
import { env } from "@/src/env.mjs";
import { getSfdcService } from "@/src/ee/features/sfdc-sync/server";
-import {
- createWithinEntitlementLimit,
- hasEntitlement,
-} from "@/src/features/entitlements/server";
+import { hasEntitlement } from "@/src/features/entitlements/server";
import {
hasProjectAccess,
throwIfNoProjectAccess,
@@ -40,7 +36,9 @@ import {
deleteUserBoundApiKeysForRole,
evictRevokedApiKeys,
} from "@/src/features/ai-gateway/server/apiKey/userBoundApiKeys";
-import { orderedRoles } from "@/src/features/rbac/constants/orderedRoles";
+import { inviteOrganizationMember } from "@/src/features/rbac/server/inviteOrganizationMember";
+import { throwIfHigherProjectRole } from "@/src/features/rbac/server/throwIfHigherProjectRole";
+import { throwIfHigherRole } from "@/src/features/rbac/server/throwIfHigherRole";
import {
userFeaturePreviewFlags,
setUserFeaturePreviewWithAuthorization,
@@ -62,118 +60,6 @@ function buildUserSearchFilter(searchQuery: string | undefined | null) {
: Prisma.empty;
}
-// Record as it allows to type check that all roles are included
-function throwIfHigherRole({ ownRole, role }: { ownRole: Role; role: Role }) {
- if (orderedRoles[ownRole] < orderedRoles[role]) {
- throw new TRPCError({
- code: "FORBIDDEN",
- message: "You cannot grant/edit a role higher than your own",
- });
- }
-}
-
-/**
- * Throw if the user tries to set a project role that is higher than their own
- * role determined by MAX(orgRole, projectRole)
- */
-async function throwIfHigherProjectRole({
- orgCtx, // context by protectedOrganizationProcedure
- projectId,
- projectRole,
-}: {
- orgCtx: {
- session: {
- orgId: string;
- orgRole: Role;
- user: {
- id: string;
- };
- };
- prisma: PrismaClient;
- };
- projectId: string;
- projectRole: Role;
-}) {
- const projectMembership = await orgCtx.prisma.projectMembership.findFirst({
- where: {
- projectId,
- userId: orgCtx.session.user.id,
- organizationMembership: {
- orgId: orgCtx.session.orgId,
- },
- },
- });
-
- const ownRoleValue: number = projectMembership
- ? Math.max(
- orderedRoles[projectMembership.role],
- orderedRoles[orgCtx.session.orgRole],
- )
- : orderedRoles[orgCtx.session.orgRole];
-
- if (ownRoleValue < orderedRoles[projectRole]) {
- throw new TRPCError({
- code: "FORBIDDEN",
- message: "You cannot grant/edit a role higher than your own",
- });
- }
-}
-
-async function createProjectMembershipOrThrowIfDuplicate({
- prisma,
- data,
-}: {
- prisma: PrismaClient | Prisma.TransactionClient;
- data: {
- userId: string;
- projectId: string;
- role: Role;
- orgMembershipId: string;
- };
-}) {
- try {
- return await prisma.projectMembership.create({ data });
- } catch (error) {
- if (
- error instanceof Prisma.PrismaClientKnownRequestError &&
- error.code === "P2002"
- ) {
- throw new TRPCError({
- code: "BAD_REQUEST",
- message: "User is already a member of this project",
- });
- }
- throw error;
- }
-}
-
-async function createOrgMembershipOrThrowIfDuplicate({
- prisma,
- data,
-}: {
- prisma: PrismaClient | Prisma.TransactionClient;
- data: {
- userId: string;
- orgId: string;
- role: Role;
- };
-}) {
- try {
- return await prisma.organizationMembership.create({ data });
- } catch (error) {
- if (
- error instanceof Prisma.PrismaClientKnownRequestError &&
- error.code === "P2002"
- ) {
- throw new TRPCError({
- code: "BAD_REQUEST",
- message: "User is already a member of this organization",
- });
- }
- throw error;
- }
-}
-
export const membersRouter = createTRPCRouter({
...allMembersRoutes,
...allInvitesRoutes,
@@ -189,322 +75,20 @@ export const membersRouter = createTRPCRouter({
}),
)
.mutation(async ({ input, ctx }) => {
- /**
- * Create a new organization membership
- * - Checks for:
- * - scope: organizationMembers:CUD if not only project-role is set, then projectMembers:CUD
- * - orgRole is not higher than own role
- * - if project role
- * - projectRole is not higher than own role
- * - entitlement for project roles if projectRole is set
- * - project is in org
- * - if user exists
- * - if org membership exists
- * - if only project role is set (orgRole === Role.NONE)
- * - create project role
- * - audit log
- * - return
- * - else throw error
- * - create org membership
- * - audit log
- * - if project role is set
- * - create project role
- * - audit log
- * - send email
- * - else
- * - create membership invitation
- * - audit log
- * - send email
- */
-
- if (
- // Require only project-level access rights if no orgRole is set but a projectId is
- input.projectId &&
- input.orgRole === Role.NONE
- ) {
- throwIfNoProjectAccess({
- session: ctx.session,
- projectId: input.projectId,
- scope: "projectMembers:CUD",
- });
- } else {
- // Require org-level access rights
- throwIfNoOrganizationAccess({
- session: ctx.session,
- organizationId: input.orgId,
- scope: "organizationMembers:CUD",
- });
- }
-
- throwIfHigherRole({
- ownRole: ctx.session.orgRole,
- role: input.orgRole,
- });
-
- // check for entilement (project role)
- if (input.projectId && input.projectRole) {
- const entitled = hasEntitlement({
- entitlement: "rbac-project-roles",
- sessionUser: ctx.session.user,
- orgId: input.orgId,
- });
- if (!entitled)
- throw new TRPCError({
- code: "FORBIDDEN",
- message:
- "Organization does not have the required entitlement to set project roles",
- });
- }
-
- const user = await ctx.prisma.user.findUnique({
- where: {
- email: input.email.toLowerCase(),
- },
- });
-
- // security check if project is in org
- const project = input.projectId
- ? await ctx.prisma.project.findFirst({
- where: {
- id: input.projectId,
- orgId: input.orgId,
- deletedAt: null,
- },
- })
- : null;
- if (project && input.projectRole)
- await throwIfHigherProjectRole({
- orgCtx: ctx,
- projectId: project.id,
- projectRole: input.projectRole,
- });
-
- const org = await ctx.prisma.organization.findFirst({
- where: {
- id: input.orgId,
- },
- });
- if (!org) {
- throw new TRPCError({ code: "NOT_FOUND", message: "Org not found" });
- }
-
- // Members and pending invitations both consume a seat, so the limit
- // check counts them together. Reads through the caller-supplied client
- // so it can run inside the limit transaction.
- const countSeatsInUse = async (tx: Prisma.TransactionClient) => {
- const memberCount = await tx.organizationMembership.count({
- where: { orgId: input.orgId },
- });
- const pendingInviteCount = await tx.membershipInvitation.count({
- where: { orgId: input.orgId },
- });
- return memberCount + pendingInviteCount;
- };
-
- if (user) {
- const existingOrgMembership =
- await ctx.prisma.organizationMembership.findFirst({
- where: {
- orgId: input.orgId,
- userId: user.id,
- },
- });
-
- // early return if user is already a member of the org
- if (existingOrgMembership) {
- // user exists and only a project role shall be added
- if (
- input.orgRole === Role.NONE &&
- project &&
- input.projectRole &&
- input.projectRole !== Role.NONE
- ) {
- // Create project role for user
- const newProjectMembership =
- await createProjectMembershipOrThrowIfDuplicate({
- prisma: ctx.prisma,
- data: {
- userId: user.id,
- projectId: project.id,
- role: input.projectRole,
- orgMembershipId: existingOrgMembership.id,
- },
- });
-
- // audit log
- await auditLog({
- session: ctx.session,
- resourceType: "projectMembership",
- resourceId: project.id + "--" + user.id,
- action: "create",
- after: newProjectMembership,
- });
- return;
- }
- throw new TRPCError({
- code: "BAD_REQUEST",
- message: "User is already a member of this organization",
- });
- }
-
- // A project membership can outlive this org's membership (e.g. a stray
- // row referencing another org). Reject the duplicate before creating
- // the org membership so a failed project insert cannot leave a
- // committed org membership (and consumed seat) behind.
- if (
- project &&
- input.projectRole &&
- input.projectRole !== Role.NONE &&
- (await ctx.prisma.projectMembership.findUnique({
- where: {
- projectId_userId: { projectId: project.id, userId: user.id },
- },
- }))
- ) {
- throw new TRPCError({
- code: "BAD_REQUEST",
- message: "User is already a member of this project",
- });
- }
-
- // create org membership as user is not a member yet, unless that
- // would exceed the member limit. On limited plans this runs inside the
- // entitlement transaction, so creating the project membership here too
- // keeps both inserts atomic: a duplicate-project-membership rejection
- // rolls back the org membership instead of leaving a consumed seat.
- const { orgMembership, projectMembership } =
- await createWithinEntitlementLimit({
- prisma: ctx.prisma,
- orgId: input.orgId,
- entitlementLimit: "organization-member-count",
- sessionUser: ctx.session.user,
- countCurrentUsage: countSeatsInUse,
- create: async (tx) => {
- const createdOrgMembership =
- await createOrgMembershipOrThrowIfDuplicate({
- prisma: tx,
- data: {
- userId: user.id,
- orgId: input.orgId,
- role: input.orgRole,
- },
- });
- const createdProjectMembership =
- project && input.projectRole && input.projectRole !== Role.NONE
- ? await createProjectMembershipOrThrowIfDuplicate({
- prisma: tx,
- data: {
- userId: user.id,
- projectId: project.id,
- role: input.projectRole,
- orgMembershipId: createdOrgMembership.id,
- },
- })
- : null;
- return {
- orgMembership: createdOrgMembership,
- projectMembership: createdProjectMembership,
- };
- },
- });
- await auditLog({
- session: ctx.session,
- resourceType: "orgMembership",
- resourceId: orgMembership.id,
- action: "create",
- after: orgMembership,
- });
- // SFDC: link existing lead to org as a member.
- await getSfdcService()?.setUserRole({
- orgId: input.orgId,
- userId: user.id,
- email: user.email,
- role: input.orgRole,
- });
- if (projectMembership) {
- await auditLog({
- session: ctx.session,
- resourceType: "projectMembership",
- resourceId:
- projectMembership.projectId + "--" + projectMembership.userId,
- action: "create",
- after: projectMembership,
- });
- }
- await sendMembershipInvitationEmail({
- inviterEmail: ctx.session.user.email!,
- inviterName: ctx.session.user.name!,
- to: input.email,
- orgName: org.name,
- orgId: input.orgId,
- userExists: true,
- env: env,
- });
- } else {
- try {
- // create the invitation unless that would exceed the member limit
- const invitation = await createWithinEntitlementLimit({
- prisma: ctx.prisma,
- orgId: input.orgId,
- entitlementLimit: "organization-member-count",
- sessionUser: ctx.session.user,
- countCurrentUsage: countSeatsInUse,
- create: (tx) =>
- tx.membershipInvitation.create({
- data: {
- orgId: input.orgId,
- projectId:
- project &&
- input.projectRole &&
- input.projectRole !== Role.NONE
- ? project.id
- : null,
- email: input.email.toLowerCase(),
- orgRole: input.orgRole,
- projectRole:
- input.projectRole &&
- input.projectRole !== Role.NONE &&
- project
- ? input.projectRole
- : null,
- invitedByUserId: ctx.session.user.id,
- },
- }),
- });
-
- await auditLog({
- session: ctx.session,
- resourceType: "membershipInvitation",
- resourceId: invitation.id,
- action: "create",
- after: invitation,
- });
- await sendMembershipInvitationEmail({
+ return inviteOrganizationMember({
+ ctx,
+ input,
+ sendInvitationEmail: ({ to, orgName, userExists }) =>
+ sendMembershipInvitationEmail({
inviterEmail: ctx.session.user.email!,
inviterName: ctx.session.user.name!,
- to: input.email,
- orgName: org.name,
+ to,
+ orgName,
orgId: input.orgId,
- userExists: false,
+ userExists,
env: env,
- });
-
- return invitation;
- } catch (error) {
- if (
- error instanceof Prisma.PrismaClientKnownRequestError &&
- error.code === "P2002"
- ) {
- throw new TRPCError({
- code: "BAD_REQUEST",
- message:
- "A pending membership invitation with this email and organization already exists",
- });
- } else {
- throw error;
- }
- }
- }
+ }),
+ });
}),
deleteMembership: protectedOrganizationProcedure
.input(
diff --git a/web/src/features/rbac/server/organizationMembersService.ts b/web/src/features/rbac/server/organizationMembersService.ts
new file mode 100644
index 0000000000..7376e3919a
--- /dev/null
+++ b/web/src/features/rbac/server/organizationMembersService.ts
@@ -0,0 +1,98 @@
+import {
+ organizationRoleAccessRights,
+ type OrganizationScope,
+} from "@langfuse/shared/rbac";
+import { type PrismaClient, Role } from "@langfuse/shared/src/db";
+
+type MembersWithScopeParams = {
+ organizationId: string;
+ scope: OrganizationScope;
+ excludeUserId?: string;
+};
+
+/** Reads organization members by what their organization role allows them to do. */
+export class OrganizationMembersService {
+ constructor(private readonly prisma: PrismaClient) {}
+
+ async getOrganizationName(organizationId: string) {
+ const organization = await this.prisma.organization.findUniqueOrThrow({
+ where: { id: organizationId },
+ select: { name: true },
+ });
+ return organization.name;
+ }
+
+ /** Counts members with an email address whose role grants `scope`. */
+ countMembersWithScope(params: MembersWithScopeParams) {
+ return this.prisma.organizationMembership.count({
+ where: this.membersWithScopeWhere(params),
+ });
+ }
+
+ /** Lists members with an email address whose role grants `scope`, oldest membership first. */
+ async findMembersWithScope(
+ params: MembersWithScopeParams & { limit?: number },
+ ) {
+ const memberships = await this.prisma.organizationMembership.findMany({
+ where: this.membersWithScopeWhere(params),
+ orderBy: { createdAt: "asc" },
+ take: params.limit,
+ select: {
+ user: { select: { id: true, name: true, email: true, image: true } },
+ },
+ });
+ return memberships.flatMap(({ user }) =>
+ user.email ? [{ ...user, email: user.email }] : [],
+ );
+ }
+
+ /**
+ * Finds the members among `emails` (lowercase, as stored) and whether their
+ * role grants `scope`.
+ */
+ async findMembersByEmail(params: {
+ organizationId: string;
+ emails: string[];
+ scope: OrganizationScope;
+ }) {
+ if (params.emails.length === 0) return [];
+ const memberships = await this.prisma.organizationMembership.findMany({
+ where: {
+ orgId: params.organizationId,
+ user: { email: { in: params.emails } },
+ },
+ select: {
+ role: true,
+ user: { select: { id: true, name: true, email: true } },
+ },
+ });
+ return memberships.flatMap(({ role, user }) =>
+ user.email
+ ? [
+ {
+ id: user.id,
+ name: user.name,
+ email: user.email,
+ hasScope: organizationRoleAccessRights[role].includes(
+ params.scope,
+ ),
+ },
+ ]
+ : [],
+ );
+ }
+
+ private membersWithScopeWhere(params: MembersWithScopeParams) {
+ const roles = Object.values(Role).filter((role) =>
+ organizationRoleAccessRights[role].includes(params.scope),
+ );
+ return {
+ orgId: params.organizationId,
+ role: { in: roles },
+ ...(params.excludeUserId
+ ? { userId: { not: params.excludeUserId } }
+ : {}),
+ user: { email: { not: null } },
+ };
+ }
+}
diff --git a/web/src/features/rbac/server/throwIfHigherProjectRole.ts b/web/src/features/rbac/server/throwIfHigherProjectRole.ts
new file mode 100644
index 0000000000..6c72d88767
--- /dev/null
+++ b/web/src/features/rbac/server/throwIfHigherProjectRole.ts
@@ -0,0 +1,51 @@
+import { TRPCError } from "@trpc/server";
+import { type PrismaClient, type Role } from "@langfuse/shared";
+
+import { orderedRoles } from "@/src/features/rbac/constants/orderedRoles";
+
+/**
+ * Throw if the user tries to set a project role that is higher than their own
+ * role determined by MAX(orgRole, projectRole)
+ */
+export async function throwIfHigherProjectRole({
+ orgCtx, // context by protectedOrganizationProcedure
+ projectId,
+ projectRole,
+}: {
+ orgCtx: {
+ session: {
+ orgId: string;
+ orgRole: Role;
+ user: {
+ id: string;
+ };
+ };
+ prisma: PrismaClient;
+ };
+ projectId: string;
+ projectRole: Role;
+}) {
+ const projectMembership = await orgCtx.prisma.projectMembership.findFirst({
+ where: {
+ projectId,
+ userId: orgCtx.session.user.id,
+ organizationMembership: {
+ orgId: orgCtx.session.orgId,
+ },
+ },
+ });
+
+ const ownRoleValue: number = projectMembership
+ ? Math.max(
+ orderedRoles[projectMembership.role],
+ orderedRoles[orgCtx.session.orgRole],
+ )
+ : orderedRoles[orgCtx.session.orgRole];
+
+ if (ownRoleValue < orderedRoles[projectRole]) {
+ throw new TRPCError({
+ code: "FORBIDDEN",
+ message: "You cannot grant/edit a role higher than your own",
+ });
+ }
+}
diff --git a/web/src/features/rbac/server/throwIfHigherRole.ts b/web/src/features/rbac/server/throwIfHigherRole.ts
new file mode 100644
index 0000000000..1b103c1d5e
--- /dev/null
+++ b/web/src/features/rbac/server/throwIfHigherRole.ts
@@ -0,0 +1,20 @@
+import { TRPCError } from "@trpc/server";
+import { type Role } from "@langfuse/shared";
+
+import { orderedRoles } from "@/src/features/rbac/constants/orderedRoles";
+
+// Record as it allows to type check that all roles are included
+export function throwIfHigherRole({
+ ownRole,
+ role,
+}: {
+ ownRole: Role;
+ role: Role;
+}) {
+ if (orderedRoles[ownRole] < orderedRoles[role]) {
+ throw new TRPCError({
+ code: "FORBIDDEN",
+ message: "You cannot grant/edit a role higher than your own",
+ });
+ }
+}
diff --git a/web/src/features/settings/SettingsPage.tsx b/web/src/features/settings/SettingsPage.tsx
index e16965ff82..fbc202b381 100644
--- a/web/src/features/settings/SettingsPage.tsx
+++ b/web/src/features/settings/SettingsPage.tsx
@@ -40,8 +40,7 @@ export function SettingsPage({ scope }: SettingsPageProps) {
typeof router.query.page === "string" ? router.query.page : undefined;
const fullHeight =
scope === "organization" &&
- (activeSlug === "ai-gateway-models" ||
- activeSlug === "ai-gateway-providers");
+ (activeSlug === "ai-gateway-models" || activeSlug === "ai-gateway");
if (scope === "organization" && !organization) {
return (
diff --git a/worker/package.json b/worker/package.json
index 377756a8b7..5b62f06a97 100644
--- a/worker/package.json
+++ b/worker/package.json
@@ -58,6 +58,7 @@
"@opentelemetry/sdk-node": "^0.220.0",
"@prisma/client": "^6.19.3",
"@prisma/instrumentation": "^6.19.3",
+ "@react-email/render": "^1.2.1",
"ai-sdk-amazon-bedrock-v4": "npm:@ai-sdk/[email protected]",
"ai-sdk-anthropic-v4": "npm:@ai-sdk/[email protected]",
"ai-sdk-google-vertex-v4": "npm:@ai-sdk/[email protected]",
diff --git a/worker/src/features/notifications/gatewayInvitationHandler.ts b/worker/src/features/notifications/gatewayInvitationHandler.ts
new file mode 100644
index 0000000000..32ccd1dbf7
--- /dev/null
+++ b/worker/src/features/notifications/gatewayInvitationHandler.ts
@@ -0,0 +1,93 @@
+import { render } from "@react-email/render";
+import {
+ createMailTransport,
+ getEmailAppBaseUrl,
+ type NotificationEventType,
+} from "@langfuse/shared/src/server";
+import {
+ GatewayInvitationEmailTemplate,
+ type GatewayInvitationEmailAudience,
+} from "@langfuse/shared/src/server/services/email/aiGatewayInvitation/GatewayInvitationEmailTemplate";
+
+import { env } from "../../env";
+
+type GatewayInvitationPayload = Omit<
+ Extract<NotificationEventType, { type: "AI_GATEWAY_INVITATION" }>,
+ "type"
+>;
+
+const getUtmContent = (audience: GatewayInvitationEmailAudience) => {
+ if (audience.kind === "member") return "member";
+ return audience.hasAccount ? "invitee_existing_user" : "invitee_new_user";
+};
+
+/**
+ * Tells someone the organization's AI Gateway is ready: either a new invitee
+ * (paired with an organization invitation) or an existing member. Missing
+ * email configuration and delivery errors are thrown, so the job fails and is
+ * kept instead of completing unsent.
+ */
+export async function handleGatewayInvitationNotification({
+ orgId,
+ orgName,
+ to,
+ receiverName,
+ audience,
+ inviterName,
+ inviterEmail,
+}: GatewayInvitationPayload) {
+ if (!env.EMAIL_FROM_ADDRESS || !env.SMTP_CONNECTION_URL) {
+ throw new Error(
+ "Missing SMTP_CONNECTION_URL or EMAIL_FROM_ADDRESS for sending gateway invitation email.",
+ );
+ }
+
+ const baseUrl = getEmailAppBaseUrl(env);
+ if (!baseUrl) {
+ throw new Error(
+ "Missing NEXTAUTH_URL or NEXT_PUBLIC_LANGFUSE_CLOUD_REGION for sending gateway invitation email.",
+ );
+ }
+
+ const gatewayKeysPath = `/organization/${orgId}/settings/ai-gateway-api-keys`;
+ const isNewUser = audience.kind === "invitee" && !audience.hasAccount;
+ const link = new URL(
+ isNewUser ? `${baseUrl}/auth/sign-up` : `${baseUrl}${gatewayKeysPath}`,
+ );
+ if (isNewUser) {
+ link.searchParams.set("targetPath", gatewayKeysPath);
+ link.searchParams.set("email", to);
+ }
+ // Read by PostHog on the landing pageview to attribute clicks and sign-ups
+ // to this email; self-hosted instances run no analytics.
+ if (env.NEXT_PUBLIC_LANGFUSE_CLOUD_REGION) {
+ link.searchParams.set("utm_source", "langfuse");
+ link.searchParams.set("utm_medium", "email");
+ link.searchParams.set("utm_campaign", "ai_gateway_invite");
+ link.searchParams.set("utm_content", getUtmContent(audience));
+ }
+
+ const html = await render(
+ GatewayInvitationEmailTemplate({
+ audience,
+ inviterName,
+ inviterEmail,
+ orgName,
+ receiverEmail: to,
+ receiverName,
+ link: link.toString(),
+ emailFromAddress: env.EMAIL_FROM_ADDRESS,
+ langfuseCloudRegion: env.NEXT_PUBLIC_LANGFUSE_CLOUD_REGION,
+ }),
+ );
+
+ await createMailTransport(env.SMTP_CONNECTION_URL).sendMail({
+ to,
+ from: `Langfuse <${env.EMAIL_FROM_ADDRESS}>`,
+ subject:
+ audience.kind === "invitee"
+ ? `${inviterName} invited you to the AI Gateway in "${orgName}" on Langfuse`
+ : `${inviterName} set up the AI Gateway for "${orgName}" on Langfuse`,
+ html,
+ });
+}
diff --git a/worker/src/queues/__tests__/notificationQueue.test.ts b/worker/src/queues/__tests__/notificationQueue.test.ts
new file mode 100644
index 0000000000..03054f8531
--- /dev/null
+++ b/worker/src/queues/__tests__/notificationQueue.test.ts
@@ -0,0 +1,55 @@
+import { Job } from "bullmq";
+import { describe, expect, it, vi } from "vitest";
+import { QueueName, TQueueJobTypes } from "@langfuse/shared/src/server";
+
+vi.mock("../../env", () => ({
+ env: {
+ // Nothing listens on port 1, so delivery fails with a connection error.
+ SMTP_CONNECTION_URL: "smtp://127.0.0.1:1",
+ EMAIL_FROM_ADDRESS: "[email protected]",
+ NEXTAUTH_URL: "http://localhost:3000",
+ },
+}));
+
+import { env } from "../../env";
+import { notificationQueueProcessor } from "../notificationQueue";
+
+function createGatewayInvitationJob() {
+ return {
+ id: "job-1",
+ data: {
+ timestamp: new Date(),
+ id: "job-1",
+ name: "notification-job",
+ payload: {
+ type: "AI_GATEWAY_INVITATION",
+ orgId: "org-1",
+ orgName: "Acme",
+ audience: { kind: "member" },
+ inviterName: "Ada Lovelace",
+ inviterEmail: "[email protected]",
+ },
+ },
+ } as Job<TQueueJobTypes[QueueName.NotificationQueue]>;
+}
+
+describe("notificationQueueProcessor", () => {
+ it("fails an AI Gateway invitation job when delivery fails, so it is retried", async () => {
+ await expect(
+ notificationQueueProcessor(createGatewayInvitationJob()),
+ ).rejects.toThrow();
+ });
+
+ it("fails an AI Gateway invitation job when the worker has no SMTP configured", async () => {
+ const smtpConnectionUrl = env.SMTP_CONNECTION_URL;
+ Object.assign(env, { SMTP_CONNECTION_URL: undefined });
+ try {
+ await expect(
+ notificationQueueProcessor(createGatewayInvitationJob()),
+ ).rejects.toThrow("Missing SMTP_CONNECTION_URL");
+ } finally {
+ Object.assign(env, { SMTP_CONNECTION_URL: smtpConnectionUrl });
+ }
+ });
+});
diff --git a/worker/src/queues/notificationQueue.ts b/worker/src/queues/notificationQueue.ts
index d29225cba9..c248aeb769 100644
--- a/worker/src/queues/notificationQueue.ts
+++ b/worker/src/queues/notificationQueue.ts
@@ -1,43 +1,51 @@
import { Job } from "bullmq";
-import { logger, QueueName, TQueueJobTypes } from "@langfuse/shared/src/server";
+import {
+ logger,
+ type NotificationEventType,
+ QueueName,
+ TQueueJobTypes,
+} from "@langfuse/shared/src/server";
import { handleCommentMentionNotification } from "../features/notifications/commentMentionHandler";
+import { handleGatewayInvitationNotification } from "../features/notifications/gatewayInvitationHandler";
+
+function notificationScope(payload: NotificationEventType) {
+ return "projectId" in payload
+ ? { projectId: payload.projectId }
+ : { orgId: payload.orgId };
+}
export const notificationQueueProcessor = async (
job: Job<TQueueJobTypes[QueueName.NotificationQueue]>,
) => {
+ const { payload } = job.data;
+ const logContext = {
+ type: payload.type,
+ ...notificationScope(payload),
+ jobId: job.id,
+ };
try {
- const { type, ...payload } = job.data.payload;
- const projectId = payload.projectId;
-
- logger.info("Processing notification job", {
- type,
- projectId,
- jobId: job.id,
- });
+ logger.info("Processing notification job", logContext);
- switch (type) {
+ switch (payload.type) {
case "COMMENT_MENTION":
await handleCommentMentionNotification(payload);
break;
+ case "AI_GATEWAY_INVITATION":
+ await handleGatewayInvitationNotification(payload);
+ break;
// Future notification types can be added here
default:
- logger.warn(`Unknown notification type: ${type}`);
+ logger.warn(`Unknown notification type: ${logContext.type}`);
}
- logger.info("Finished processing notification job", {
- type,
- projectId,
- jobId: job.id,
- });
+ logger.info("Finished processing notification job", logContext);
return true;
} catch (error) {
logger.error("Failed to process notification job", {
+ ...logContext,
error,
- jobId: job.id,
- payload: job.data.payload,
- projectId: job.data.payload.projectId,
});
throw error;
}