minutework 0.1.39 → 0.1.41

package/assets/templates/vuilder-shell/src/lib/platform/client.server.ts

@@ -0,0 +1,540 @@
+import "server-only";
+
+import { z } from "zod";
+
+import { platformAuthEndpoints } from "@/lib/platform/endpoints.server";
+import { getEnv } from "@/lib/platform/env.server";
+import type {
+  AuthenticatedPlatformSession,
+  PlatformSession,
+  PlatformUser,
+  SessionMembership,
+  ShellContext,
+  ShellTokenResponse,
+} from "@/lib/platform/contracts";
+import {
+  platformErrorPayloadSchema,
+  shellContextCanOpenWorkspace,
+  shellContextCanViewWorkspace,
+  shellContextMatchesWorkspace,
+  shellContextSchema,
+  shellTokenResponseSchema,
+} from "@/lib/platform/contracts";
+import type { PlatformAuthState } from "@/lib/platform/session.server";
+
+export type PlatformResult<T> = {
+  data: T;
+  authState: PlatformAuthState;
+};
+
+export type WorkspaceShellSession = {
+  session: PlatformSession;
+  shellContext: ShellContext | null;
+  membership: SessionMembership | null;
+  workspaceCanView: boolean;
+  workspaceCanOpen: boolean;
+};
+
+export class PlatformClientError extends Error {
+  status: number;
+  code: string | null;
+  authState: PlatformAuthState | null;
+
+  constructor(
+    message: string,
+    status: number,
+    code: string | null = null,
+    authState: PlatformAuthState | null = null,
+  ) {
+    super(message);
+    this.name = "PlatformClientError";
+    this.status = status;
+    this.code = code;
+    this.authState = authState;
+  }
+}
+
+function normalizeAuthState(
+  input?: Partial<PlatformAuthState> | string | null,
+): PlatformAuthState {
+  if (typeof input === "string" || input == null) {
+    return {
+      shellSessionToken: input ?? null,
+    };
+  }
+
+  return {
+    shellSessionToken: input.shellSessionToken ?? null,
+  };
+}
+
+function getRequestTarget(input: string) {
+  try {
+    return new URL(input).origin;
+  } catch {
+    return input;
+  }
+}
+
+function toPlatformUnavailableError(
+  input: string,
+  cause: unknown,
+  authState: PlatformAuthState,
+) {
+  const error = new PlatformClientError(
+    `Unable to reach the platform backend at ${getRequestTarget(input)}.`,
+    503,
+    "platform_unavailable",
+    authState,
+  ) as PlatformClientError & { cause?: unknown };
+  error.cause = cause;
+  return error;
+}
+
+function toPlatformTimeoutError(
+  input: string,
+  timeoutMs: number,
+  cause: unknown,
+  authState: PlatformAuthState,
+) {
+  const error = new PlatformClientError(
+    `Timed out waiting for the platform backend at ${getRequestTarget(
+      input,
+    )} after ${timeoutMs}ms.`,
+    504,
+    "platform_timeout",
+    authState,
+  ) as PlatformClientError & { cause?: unknown };
+  error.cause = cause;
+  return error;
+}
+
+async function parseJson(response: Response): Promise<unknown> {
+  const text = await response.text();
+
+  if (!text) {
+    return null;
+  }
+
+  const trimmedText = text.trim();
+  const contentType = response.headers.get("content-type") ?? "";
+  const looksLikeJson =
+    contentType.includes("application/json") ||
+    trimmedText.startsWith("{") ||
+    trimmedText.startsWith("[");
+
+  if (!looksLikeJson) {
+    return trimmedText;
+  }
+
+  try {
+    return JSON.parse(trimmedText) as unknown;
+  } catch {
+    return trimmedText;
+  }
+}
+
+function extractErrorDetails(data: unknown) {
+  if (typeof data === "string" && data.trim()) {
+    const snippet = data.replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim();
+
+    return {
+      message: snippet.slice(0, 240) || "Platform request failed",
+      code: null,
+    };
+  }
+
+  const parsed = platformErrorPayloadSchema.safeParse(data);
+
+  if (!parsed.success) {
+    return {
+      message: "Platform request failed",
+      code: null,
+    };
+  }
+
+  const nestedError =
+    typeof parsed.data.error === "object" && parsed.data.error !== null
+      ? parsed.data.error
+      : null;
+
+  return {
+    message:
+      parsed.data.detail ??
+      (typeof parsed.data.error === "string" ? parsed.data.error : undefined) ??
+      nestedError?.message ??
+      "Platform request failed",
+    code: parsed.data.code ?? nestedError?.code ?? null,
+  };
+}
+
+function platformHeaders(
+  authState: PlatformAuthState,
+  headers?: HeadersInit,
+) {
+  const resolvedHeaders = new Headers(headers);
+  resolvedHeaders.set("Accept", "application/json");
+
+  if (authState.shellSessionToken) {
+    resolvedHeaders.set("X-Vuilder-Shell-Session", authState.shellSessionToken);
+  }
+
+  return resolvedHeaders;
+}
+
+async function performPlatformFetch(
+  input: string,
+  init: RequestInit,
+  authState: PlatformAuthState,
+) {
+  let response: Response;
+  const timeoutMs = getEnv().MW_PLATFORM_FETCH_TIMEOUT_MS;
+  const controller = new AbortController();
+  let didTimeout = false;
+  const timeoutId = globalThis.setTimeout(() => {
+    didTimeout = true;
+    controller.abort();
+  }, timeoutMs);
+
+  try {
+    response = await fetch(input, {
+      ...init,
+      cache: init.cache ?? "no-store",
+      headers: platformHeaders(authState, init.headers),
+      signal: controller.signal,
+    });
+  } catch (error) {
+    if (didTimeout) {
+      throw toPlatformTimeoutError(input, timeoutMs, error, authState);
+    }
+    throw toPlatformUnavailableError(input, error, authState);
+  } finally {
+    globalThis.clearTimeout(timeoutId);
+  }
+
+  return {
+    response,
+    authState,
+  };
+}
+
+async function requestJson<TSchema extends z.ZodTypeAny>(
+  input: string,
+  schema: TSchema,
+  init: RequestInit,
+  options?: {
+    authState?: Partial<PlatformAuthState> | string | null;
+  },
+): Promise<PlatformResult<z.output<TSchema>>> {
+  const authState = normalizeAuthState(options?.authState);
+  const { response, authState: nextAuthState } = await performPlatformFetch(
+    input,
+    init,
+    authState,
+  );
+  const data = await parseJson(response);
+
+  if (!response.ok) {
+    const { message, code } = extractErrorDetails(data);
+    throw new PlatformClientError(message, response.status, code, nextAuthState);
+  }
+
+  return {
+    data: schema.parse(data),
+    authState: nextAuthState,
+  };
+}
+
+function fallbackUser(context: ShellContext): PlatformUser {
+  return {
+    id: `tenant-member:${context.tenant_id}`,
+    username: "member",
+    email: "member@localhost.invalid",
+    display_name: context.workspace_name,
+    avatar_url: "",
+  };
+}
+
+export function shellContextToMembership(
+  context: ShellContext,
+): SessionMembership {
+  const roleSlug = context.role_slug || context.role_slugs[0] || "member";
+
+  return {
+    tenant_id: context.tenant_id,
+    tenant_slug: context.workspace_slug,
+    tenant_name: context.workspace_name,
+    workspace_slug: context.workspace_slug,
+    workspace_name: context.workspace_name,
+    role: roleSlug,
+    tenant_icon_url: "",
+    runtime_status:
+      context.affordances.workspace_shell_open === true ? "ready" : "pending",
+    roles: context.role_slugs.map((slug, index) => ({
+      slug,
+      name: slug,
+      position: index,
+    })),
+  };
+}
+
+function unauthenticatedWorkspaceShellSession(): WorkspaceShellSession {
+  return {
+    session: {
+      authenticated: false,
+    },
+    shellContext: null,
+    membership: null,
+    workspaceCanView: false,
+    workspaceCanOpen: false,
+  };
+}
+
+function toAuthenticatedPlatformSession(
+  context: ShellContext,
+): AuthenticatedPlatformSession {
+  const membership = shellContextToMembership(context);
+
+  return {
+    authenticated: true,
+    user: context.user ?? fallbackUser(context),
+    active_tenant_id: context.tenant_id,
+    active_tenant: membership,
+    memberships: [membership],
+    onboarding_completed_for_active_workspace:
+      context.affordances.workspace_shell_open === true,
+  };
+}
+
+export async function fetchTenantMemberShellContext(
+  authInput: Partial<PlatformAuthState> | string | null,
+): Promise<PlatformResult<ShellContext>> {
+  return await requestJson(
+    platformAuthEndpoints.shellTokenContext,
+    shellContextSchema,
+    {
+      method: "GET",
+    },
+    {
+      authState: authInput,
+    },
+  );
+}
+
+export async function exchangeVuilderShellSessionHandoffCode(
+  shellSessionHandoffCode: string,
+  shellState: string,
+): Promise<PlatformResult<ShellTokenResponse>> {
+  const normalizedCode = String(shellSessionHandoffCode || "").trim();
+  if (!normalizedCode) {
+    throw new PlatformClientError(
+      "Shell session handoff code is required.",
+      400,
+      "missing_shell_session_handoff_code",
+      { shellSessionToken: null },
+    );
+  }
+  const normalizedShellState = String(shellState || "").trim();
+  if (!normalizedShellState) {
+    throw new PlatformClientError(
+      "Shell handoff state is required.",
+      400,
+      "missing_shell_state",
+      { shellSessionToken: null },
+    );
+  }
+
+  return await requestJson(
+    platformAuthEndpoints.shellTokenExchange,
+    shellTokenResponseSchema,
+    {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        shell_session_handoff_code: normalizedCode,
+        shell_state: normalizedShellState,
+      }),
+    },
+    {
+      authState: null,
+    },
+  );
+}
+
+export async function revokeVuilderShellSession(
+  authInput: Partial<PlatformAuthState> | string | null,
+): Promise<void> {
+  const authState = normalizeAuthState(authInput);
+  if (!authState.shellSessionToken) {
+    return;
+  }
+  await requestJson(
+    platformAuthEndpoints.shellTokenRevoke,
+    z.null(),
+    {
+      method: "POST",
+    },
+    {
+      authState,
+    },
+  );
+}
+
+export async function loadCurrentSession(
+  authInput: Partial<PlatformAuthState> | string | null,
+): Promise<PlatformResult<PlatformSession>> {
+  const authState = normalizeAuthState(authInput);
+
+  if (!authState.shellSessionToken) {
+    return {
+      data: {
+        authenticated: false,
+      },
+      authState,
+    };
+  }
+
+  try {
+    const result = await fetchTenantMemberShellContext(authState);
+    return {
+      data: toAuthenticatedPlatformSession(result.data),
+      authState: result.authState,
+    };
+  } catch (error) {
+    if (error instanceof PlatformClientError) {
+      if (error.status === 401 || error.status === 403) {
+        return {
+          data: { authenticated: false },
+          authState: {
+            shellSessionToken: null,
+          },
+        };
+      }
+
+      if (error.status >= 500) {
+        return {
+          data: { authenticated: false },
+          authState: error.authState ?? authState,
+        };
+      }
+    }
+
+    throw error;
+  }
+}
+
+function workspaceShellSessionFromContext(
+  context: ShellContext,
+  workspaceSlug: string,
+): WorkspaceShellSession {
+  const matches = shellContextMatchesWorkspace(context, workspaceSlug);
+  const membership = matches ? shellContextToMembership(context) : null;
+  const workspaceCanView = matches && shellContextCanViewWorkspace(context);
+  const workspaceCanOpen = matches && shellContextCanOpenWorkspace(context);
+
+  return {
+    session: toAuthenticatedPlatformSession(context),
+    shellContext: context,
+    membership,
+    workspaceCanView,
+    workspaceCanOpen,
+  };
+}
+
+export async function loadCurrentWorkspaceShellSession(
+  authInput: Partial<PlatformAuthState> | string | null,
+): Promise<PlatformResult<WorkspaceShellSession>> {
+  const authState = normalizeAuthState(authInput);
+
+  if (!authState.shellSessionToken) {
+    return {
+      data: unauthenticatedWorkspaceShellSession(),
+      authState,
+    };
+  }
+
+  let contextResult: PlatformResult<ShellContext>;
+  try {
+    contextResult = await fetchTenantMemberShellContext(authState);
+  } catch (error) {
+    if (error instanceof PlatformClientError) {
+      if (error.status === 401 || error.status === 403) {
+        return {
+          data: unauthenticatedWorkspaceShellSession(),
+          authState: {
+            shellSessionToken: null,
+          },
+        };
+      }
+
+      if (error.status >= 500) {
+        return {
+          data: unauthenticatedWorkspaceShellSession(),
+          authState: error.authState ?? authState,
+        };
+      }
+    }
+
+    throw error;
+  }
+
+  return {
+    data: workspaceShellSessionFromContext(
+      contextResult.data,
+      contextResult.data.workspace_slug,
+    ),
+    authState: contextResult.authState,
+  };
+}
+
+export async function loadWorkspaceShellSession(
+  authInput: Partial<PlatformAuthState> | string | null,
+  workspaceSlug: string,
+): Promise<PlatformResult<WorkspaceShellSession>> {
+  const authState = normalizeAuthState(authInput);
+
+  if (!authState.shellSessionToken) {
+    return {
+      data: unauthenticatedWorkspaceShellSession(),
+      authState,
+    };
+  }
+
+  let contextResult: PlatformResult<ShellContext>;
+  try {
+    contextResult = await fetchTenantMemberShellContext(authState);
+  } catch (error) {
+    if (error instanceof PlatformClientError) {
+      if (error.status === 401 || error.status === 403) {
+        return {
+          data: unauthenticatedWorkspaceShellSession(),
+          authState: {
+            shellSessionToken: null,
+          },
+        };
+      }
+
+      if (error.status >= 500) {
+        return {
+          data: unauthenticatedWorkspaceShellSession(),
+          authState: error.authState ?? authState,
+        };
+      }
+    }
+
+    throw error;
+  }
+
+  return {
+    data: workspaceShellSessionFromContext(contextResult.data, workspaceSlug),
+    authState: contextResult.authState,
+  };
+}
+
+export async function resolveCurrentSession(
+  authInput: Partial<PlatformAuthState> | string | null,
+): Promise<PlatformSession> {
+  return (await loadCurrentSession(authInput)).data;
+}

package/assets/templates/vuilder-shell/src/lib/platform/contracts.ts

@@ -0,0 +1,190 @@
+import { z } from "zod";
+
+export const sessionMembershipSchema = z.object({
+  tenant_id: z.string().min(1),
+  tenant_slug: z.string().min(1),
+  tenant_name: z.string().min(1),
+  workspace_slug: z.string().min(1),
+  workspace_name: z.string().min(1),
+  role: z.string().min(1),
+  tenant_icon_url: z.string().optional().default(""),
+  runtime_status: z.string().optional().default(""),
+  roles: z
+    .array(
+      z.object({
+        slug: z.string().min(1),
+        name: z.string().min(1),
+        position: z.number().int(),
+      }),
+    )
+    .optional()
+    .default([]),
+});
+
+export const activeTenantSchema = sessionMembershipSchema;
+
+export const platformUserSchema = z.object({
+  id: z.string().min(1),
+  username: z.string().min(1),
+  email: z.string().min(1),
+  display_name: z.string().optional().default(""),
+  avatar_url: z.string().optional().default(""),
+});
+
+export const upstreamSessionPayloadSchema = z
+  .object({
+    user: platformUserSchema,
+    active_tenant_id: z.string().min(1).nullable(),
+    active_tenant: activeTenantSchema.nullable(),
+    memberships: z.array(sessionMembershipSchema),
+    onboarding_completed_for_active_workspace: z
+      .boolean()
+      .nullable()
+      .optional()
+      .default(null),
+  })
+  .passthrough();
+
+export const anonymousPlatformSessionSchema = z.object({
+  authenticated: z.literal(false),
+});
+
+export const authenticatedPlatformSessionSchema = z.object({
+  authenticated: z.literal(true),
+  user: platformUserSchema,
+  active_tenant_id: z.string().min(1).nullable(),
+  active_tenant: activeTenantSchema.nullable(),
+  memberships: z.array(sessionMembershipSchema),
+  onboarding_completed_for_active_workspace: z
+    .boolean()
+    .nullable()
+    .default(null),
+});
+
+export const platformSessionSchema = z.union([
+  anonymousPlatformSessionSchema,
+  authenticatedPlatformSessionSchema,
+]);
+
+export const platformErrorPayloadSchema = z
+  .object({
+    detail: z.string().min(1).optional(),
+    error: z
+      .union([
+        z.string().min(1),
+        z.object({
+          code: z.string().min(1).optional(),
+          message: z.string().min(1).optional(),
+        }),
+      ])
+      .optional(),
+    code: z.string().min(1).optional(),
+  })
+  .passthrough();
+
+export const shellContextSchema = z
+  .object({
+    principal_kind: z.literal("tenant_member"),
+    tenant_id: z.string().min(1),
+    workspace_slug: z.string().min(1),
+    workspace_name: z.string().min(1),
+    role_slug: z.string().optional().default(""),
+    role_slugs: z.array(z.string().min(1)).optional().default([]),
+    stored_permissions: z.array(z.string().min(1)).optional().default([]),
+    affordances: z.record(z.unknown()).optional().default({}),
+    capabilities: z.record(z.unknown()).optional().default({}),
+    user: platformUserSchema.optional(),
+    expires_at: z.string().optional().default(""),
+  })
+  .passthrough();
+
+export const shellTokenResponseSchema = z
+  .object({
+    shell_session_token: z.string().min(1),
+    expires_at: z.string().min(1),
+    shell_context: shellContextSchema,
+  })
+  .strict();
+
+export type SessionMembership = z.infer<typeof sessionMembershipSchema>;
+export type PlatformUser = z.infer<typeof platformUserSchema>;
+export type PlatformSession = z.infer<typeof platformSessionSchema>;
+export type AuthenticatedPlatformSession = z.infer<
+  typeof authenticatedPlatformSessionSchema
+>;
+export type ShellContext = z.infer<typeof shellContextSchema>;
+export type ShellTokenResponse = z.infer<typeof shellTokenResponseSchema>;
+
+export function isAuthenticatedPlatformSession(
+  session: PlatformSession,
+): session is AuthenticatedPlatformSession {
+  return session.authenticated;
+}
+
+export function preferredWorkspace(
+  session: AuthenticatedPlatformSession,
+): SessionMembership | null {
+  return session.active_tenant ?? session.memberships[0] ?? null;
+}
+
+export function workspaceMembershipForSession(
+  session: PlatformSession,
+  workspaceSlug?: string | null,
+): SessionMembership | null {
+  if (!session.authenticated) {
+    return null;
+  }
+
+  const normalizedSlug = String(workspaceSlug ?? "").trim();
+  if (!normalizedSlug) {
+    return preferredWorkspace(session);
+  }
+
+  if (session.active_tenant?.workspace_slug === normalizedSlug) {
+    return session.active_tenant;
+  }
+
+  return (
+    session.memberships.find(
+      (membership) => membership.workspace_slug === normalizedSlug,
+    ) ?? null
+  );
+}
+
+function nestedBoolean(
+  value: Record<string, unknown>,
+  group: string,
+  key: string,
+) {
+  const groupValue = value[group];
+  if (
+    typeof groupValue !== "object" ||
+    groupValue === null ||
+    Array.isArray(groupValue)
+  ) {
+    return false;
+  }
+
+  return (groupValue as Record<string, unknown>)[key] === true;
+}
+
+export function shellContextMatchesWorkspace(
+  context: ShellContext,
+  workspaceSlug?: string | null,
+) {
+  return context.workspace_slug === String(workspaceSlug ?? "").trim();
+}
+
+export function shellContextCanViewWorkspace(context: ShellContext) {
+  return (
+    nestedBoolean(context.capabilities, "channels", "view") &&
+    nestedBoolean(context.capabilities, "threads", "view")
+  );
+}
+
+export function shellContextCanOpenWorkspace(context: ShellContext) {
+  return (
+    shellContextCanViewWorkspace(context) &&
+    context.affordances.workspace_shell_open === true
+  );
+}