@mehdad67/apitogo 0.1.24

package/src/lib/core/RouteGuard.tsx

@@ -0,0 +1,193 @@
+import { Button } from "@lukoweb/apitogo/ui/Button.js";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "@lukoweb/apitogo/ui/Dialog.js";
+import { Helmet } from "@zudoku/react-helmet-async";
+import { use, useCallback, useEffect, useMemo } from "react";
+import {
+  matchPath,
+  Outlet,
+  useBlocker,
+  useLocation,
+  useNavigate,
+} from "react-router";
+import { REASON_CODES } from "../../config/validators/reason-codes.js";
+import { useAuth } from "../authentication/hook.js";
+import { RenderContext } from "../components/context/RenderContext.js";
+import { useZudoku } from "../components/context/ZudokuContext.js";
+import { Layout } from "../components/Layout.js";
+import { ZudokuError } from "../util/invariant.js";
+
+export const SEARCH_PROTECTED_SECTION = "protected";
+
+type LoginDialogProps = {
+  open: boolean;
+  onCancel: () => void;
+  onLogin: () => void;
+  onRegister: () => void;
+};
+
+const LoginDialog = ({
+  open,
+  onCancel,
+  onLogin,
+  onRegister,
+}: LoginDialogProps) => (
+  <Dialog open={open} onOpenChange={(nextOpen) => !nextOpen && onCancel()}>
+    <DialogContent>
+      <DialogHeader>
+        <DialogTitle>Login to continue</DialogTitle>
+      </DialogHeader>
+      <DialogDescription>Please login to access this page.</DialogDescription>
+      <DialogFooter>
+        <Button variant="outline" onClick={onCancel}>
+          Cancel
+        </Button>
+        <div className="w-full" />
+        <Button variant="secondary" onClick={onRegister}>
+          Register
+        </Button>
+        <Button onClick={onLogin}>Login</Button>
+      </DialogFooter>
+    </DialogContent>
+  </Dialog>
+);
+
+const BypassRoute = ({ isProtectedRoute }: { isProtectedRoute: boolean }) => (
+  <>
+    {isProtectedRoute && (
+      <Helmet>
+        <meta
+          name="pagefind"
+          data-pagefind-filter={`section:${SEARCH_PROTECTED_SECTION}`}
+          content="true"
+        />
+      </Helmet>
+    )}
+    <Outlet />
+  </>
+);
+
+const ForbiddenPage = () => {
+  const renderContext = use(RenderContext);
+  renderContext.status = 403;
+
+  return (
+    <Layout>
+      <div className="flex flex-col items-center justify-center min-h-[50vh] gap-4">
+        <h1 className="text-2xl font-bold">Access Denied</h1>
+        <p className="text-muted-foreground">
+          You don't have permission to access this page.
+        </p>
+      </div>
+    </Layout>
+  );
+};
+
+export const RouteGuard = () => {
+  const auth = useAuth();
+  const zudoku = useZudoku();
+  const navigate = useNavigate();
+  const location = useLocation();
+  const renderContext = use(RenderContext);
+  const shouldBypass = renderContext.bypassProtection;
+  const authCheckContext = useMemo(
+    () => ({ auth, context: zudoku, reasonCode: REASON_CODES }),
+    [auth, zudoku],
+  );
+  const { protectedRoutes } = zudoku;
+
+  const getAuthCheck = useCallback(
+    (pathname: string) => {
+      if (!protectedRoutes) return;
+      for (const [pattern, check] of Object.entries(protectedRoutes)) {
+        if (matchPath({ path: pattern, end: true }, pathname)) {
+          return check;
+        }
+      }
+    },
+    [protectedRoutes],
+  );
+
+  const currentAuthCheck = getAuthCheck(location.pathname);
+  const isProtectedRoute = currentAuthCheck !== undefined;
+  const rawResult = currentAuthCheck?.(authCheckContext) ?? true;
+  // Normalize: false is equivalent to UNAUTHORIZED
+  const authResult =
+    rawResult === false ? REASON_CODES.UNAUTHORIZED : rawResult;
+  const isForbidden = authResult === REASON_CODES.FORBIDDEN;
+  const needsToSignIn = authResult === REASON_CODES.UNAUTHORIZED;
+
+  const blocker = useBlocker(({ nextLocation }) => {
+    if (shouldBypass) return false;
+    const check = getAuthCheck(nextLocation.pathname);
+    if (!check) return false;
+    const result = check(authCheckContext);
+    // Only block for unauthorized (needs login), not for reason codes like "forbidden"
+    return result === false || result === REASON_CODES.UNAUTHORIZED;
+  });
+  const isBlocked = blocker.state === "blocked";
+
+  // Proceed after successful login
+  useEffect(() => {
+    if (!auth.isAuthenticated || !isBlocked) return;
+    const check = getAuthCheck(blocker.location.pathname);
+    if (!check) {
+      blocker.proceed?.();
+      return;
+    }
+    const result = check(authCheckContext);
+    // Proceed whenever the result is no longer UNAUTHORIZED (e.g. true or FORBIDDEN)
+    if (result !== false && result !== REASON_CODES.UNAUTHORIZED) {
+      blocker.proceed?.();
+    }
+  }, [
+    auth.isAuthenticated,
+    isBlocked,
+    blocker,
+    authCheckContext,
+    getAuthCheck,
+  ]);
+
+  if (isForbidden) {
+    return <ForbiddenPage />;
+  }
+
+  if (shouldBypass) {
+    return <BypassRoute isProtectedRoute={isProtectedRoute} />;
+  }
+
+  if (isProtectedRoute && !auth.isAuthEnabled) {
+    throw new ZudokuError("Authentication is not enabled", {
+      title: "Authentication is not enabled",
+      developerHint:
+        "To use protectedRoutes you need authentication to be enabled",
+    });
+  }
+
+  if (needsToSignIn && auth.isPending && typeof window !== "undefined") {
+    return null;
+  }
+
+  const showDialog = needsToSignIn || isBlocked;
+  const redirectTo = isBlocked
+    ? blocker.location.pathname + blocker.location.search
+    : location.pathname + location.search;
+
+  return (
+    <>
+      {!needsToSignIn && <Outlet />}
+      <LoginDialog
+        open={showDialog}
+        onCancel={needsToSignIn ? () => navigate(-1) : () => blocker.reset?.()}
+        onLogin={() => void auth.login({ redirectTo })}
+        onRegister={() => void auth.signup({ redirectTo })}
+      />
+    </>
+  );
+};

package/src/lib/core/ZudokuContext.ts

@@ -0,0 +1,271 @@
+import type { QueryClient } from "@tanstack/react-query";
+import { createNanoEvents } from "nanoevents";
+import type { ReactNode } from "react";
+import type { Location } from "react-router";
+import type { BundledTheme, HighlighterCore } from "shiki";
+import type { z } from "zod/mini";
+import type { HeaderNavigation } from "../../config/validators/HeaderNavigationSchema.js";
+import type {
+  Navigation,
+  ResolvedNavigationRule,
+} from "../../config/validators/NavigationSchema.js";
+import type {
+  CallbackContext,
+  ProtectedRouteResult,
+  ProtectedRoutesInput,
+} from "../../config/validators/ProtectedRoutesSchema.js";
+import type {
+  AiAssistantsConfig,
+  FooterSchema,
+} from "../../config/validators/ZudokuConfig.js";
+import type { AuthenticationPlugin } from "../authentication/authentication.js";
+import { type AuthState, useAuthState } from "../authentication/state.js";
+import type { SlotType } from "../components/context/SlotProvider.js";
+import { joinUrl } from "../util/joinUrl.js";
+import type { MdxComponentsType } from "../util/MdxComponents.js";
+import { objectEntries } from "../util/objectEntries.js";
+import {
+  isApiIdentityPlugin,
+  isAuthenticationPlugin,
+  isEventConsumerPlugin,
+  isNavigationPlugin,
+  isProfileMenuPlugin,
+  needsInitialization,
+  type ProfileNavigationItem,
+  type ApitogoPlugin,
+} from "./plugins.js";
+
+export interface ApitogoEvents {
+  location: (event: { from?: Location; to: Location }) => void;
+  auth: (auth: { prev: AuthState; next: AuthState }) => void;
+}
+
+export interface ApiIdentity {
+  authorizeRequest: (request: Request) => Promise<Request> | Request;
+  authorizationFields?: {
+    headers?: string[];
+    queryParams?: string[];
+  };
+  label: string;
+  id: string;
+}
+
+export type ApiKeyCache = "api-keys";
+
+type Metadata = Partial<{
+  title: string;
+  defaultTitle?: string;
+  description: string;
+  logo: string;
+  favicon: string;
+  generator: string;
+  applicationName: string;
+  referrer: string;
+  keywords: string[];
+  authors: string[];
+  creator: string;
+  publisher: string;
+}>;
+
+type Site = Partial<{
+  dir?: "ltr" | "rtl";
+  showPoweredBy?: boolean;
+  title?: string;
+  logo?: {
+    src: {
+      light: string;
+      dark: string;
+    };
+    width?: string | number;
+    alt?: string;
+    href?: string;
+    reloadDocument?: boolean;
+  };
+  banner?: {
+    message: ReactNode;
+    color?: "note" | "tip" | "info" | "caution" | "danger" | (string & {});
+    dismissible?: boolean;
+  };
+  footer?: z.infer<typeof FooterSchema>;
+}>;
+
+type HeaderConfig = {
+  navigation?: HeaderNavigation;
+  placements?: {
+    navigation?: "start" | "center" | "end";
+    search?: "start" | "center" | "end";
+    auth?: "start" | "center" | "end" | "navigation";
+  };
+};
+
+export type ZudokuContextOptions = {
+  basePath?: string;
+  canonicalUrlOrigin?: string;
+  metadata?: Metadata;
+  site?: Site;
+  header?: HeaderConfig;
+  aiAssistants?: AiAssistantsConfig;
+  authentication?: AuthenticationPlugin;
+  navigation?: Navigation;
+  navigationRules?: ResolvedNavigationRule[];
+  plugins?: ApitogoPlugin[];
+  slots?: Record<string, SlotType>;
+  /**
+   * @deprecated Use `slots` instead
+   */
+  UNSAFE_slotlets?: Record<string, SlotType>;
+  mdx?: {
+    components?: MdxComponentsType;
+  };
+  protectedRoutes?: ProtectedRoutesInput;
+  syntaxHighlighting?: {
+    highlighterPromise: Promise<HighlighterCore>;
+    themes?: { light: BundledTheme; dark: BundledTheme };
+  };
+};
+
+export const normalizeProtectedRoutes = (
+  val: ProtectedRoutesInput,
+): Record<string, (c: CallbackContext) => ProtectedRouteResult> | undefined => {
+  if (!val) return undefined;
+
+  if (Array.isArray(val)) {
+    return Object.fromEntries(
+      val.map((route) => [
+        route,
+        (c: CallbackContext) => c.auth.isAuthenticated,
+      ]),
+    );
+  }
+
+  return val;
+};
+
+export class ZudokuContext {
+  public navigation: Navigation;
+  public navigationRules: ResolvedNavigationRule[];
+  public readonly authentication?: AuthenticationPlugin;
+  public readonly getAuthState: () => AuthState;
+  public readonly queryClient: QueryClient;
+  public readonly options: ZudokuContextOptions;
+  public readonly env: Record<string, string | undefined>;
+  public readonly protectedRoutes: ReturnType<typeof normalizeProtectedRoutes>;
+  private readonly plugins: NonNullable<ZudokuContextOptions["plugins"]>;
+  private readonly emitter = createNanoEvents<ApitogoEvents>();
+  readonly initialize: Promise<void> | undefined;
+
+  constructor(
+    options: ZudokuContextOptions,
+    queryClient: QueryClient,
+    env: Record<string, string | undefined>,
+  ) {
+    this.queryClient = queryClient;
+    this.env = env;
+    this.options = options;
+    this.plugins = options.plugins ?? [];
+    this.authentication = this.plugins.find(isAuthenticationPlugin);
+    this.getAuthState = useAuthState.getState;
+
+    const pluginsToInit = this.plugins.filter(needsInitialization);
+    this.initialize =
+      pluginsToInit.length > 0
+        ? Promise.all(
+            pluginsToInit.map((plugin) => plugin.initialize?.(this)),
+          ).then(() => {})
+        : undefined;
+
+    const pluginProtectedRoutes = Object.fromEntries(
+      this.plugins.flatMap((plugin) => {
+        if (!isNavigationPlugin(plugin)) return [];
+        const routes = plugin.getProtectedRoutes?.();
+        if (!routes) return [];
+
+        return Object.entries(normalizeProtectedRoutes(routes) ?? {});
+      }),
+    );
+
+    this.protectedRoutes = {
+      ...pluginProtectedRoutes,
+      ...normalizeProtectedRoutes(options.protectedRoutes),
+    };
+
+    this.navigation = options.navigation ?? [];
+    this.navigationRules = options.navigationRules ?? [];
+    this.plugins.forEach((plugin) => {
+      if (!isEventConsumerPlugin(plugin)) return;
+
+      objectEntries(plugin.events).forEach(([event, handler]) => {
+        // biome-ignore lint/style/noNonNullAssertion: handler is guaranteed to be defined
+        this.emitter.on(event, handler!);
+      });
+    });
+
+    useAuthState.subscribe((state, prevState) => {
+      this.emitEvent("auth", {
+        prev: prevState,
+        next: state,
+      });
+    });
+  }
+
+  getApiIdentities = async () => {
+    const keys = await Promise.all(
+      this.plugins
+        .filter(isApiIdentityPlugin)
+        .map((plugin) => plugin.getIdentities(this)),
+    );
+
+    return keys.flat();
+  };
+
+  addEventListener<E extends keyof ApitogoEvents>(
+    event: E,
+    callback: ApitogoEvents[E],
+  ) {
+    return this.emitter.on(event, callback);
+  }
+
+  emitEvent = <E extends keyof ApitogoEvents>(
+    event: E,
+    ...data: Parameters<ApitogoEvents[E]>
+  ) => {
+    return this.emitter.emit(event, ...data);
+  };
+
+  getPluginNavigation = async (path: string) => {
+    const navigations = await Promise.all(
+      this.plugins
+        .filter(isNavigationPlugin)
+        .map((plugin) => plugin.getNavigation?.(joinUrl(path), this)),
+    );
+
+    return navigations.flatMap((nav) => nav ?? []);
+  };
+
+  getProfileMenuItems = () => {
+    const accountItems = this.plugins
+      .filter((p) => isProfileMenuPlugin(p))
+      .flatMap((p) => p.getProfileMenuItems?.(this) ?? [])
+      .sort(sortByCategory(["top", "middle", "bottom"]))
+      .sort((i) => i.weight ?? 0);
+
+    return accountItems;
+  };
+
+  signRequest = async (request: Request) => {
+    if (!this.authentication) {
+      throw new Error("No authentication provider configured");
+    }
+
+    return await this.authentication.signRequest(request);
+  };
+}
+
+const sortByCategory =
+  (categories: string[]) =>
+  (a: ProfileNavigationItem, b: ProfileNavigationItem) => {
+    const aIndex = categories.indexOf(a.category ?? "middle");
+    const bIndex = categories.indexOf(b.category ?? "middle");
+
+    return aIndex - bIndex;
+  };

package/src/lib/core/plugins.ts

@@ -0,0 +1,138 @@
+import type { LucideIcon } from "lucide-react";
+import type { HTMLAttributeAnchorTarget, ReactNode } from "react";
+import type { Location, RouteObject } from "react-router";
+import type { Navigation } from "../../config/validators/NavigationSchema.js";
+import type { ProtectedRoutesInput } from "../../config/validators/ProtectedRoutesSchema.js";
+import type { ZudokuConfig } from "../../config/validators/ZudokuConfig.js";
+import type { AuthenticationPlugin } from "../authentication/authentication.js";
+import type { MdxComponentsType } from "../util/MdxComponents.js";
+import type {
+  ApiIdentity,
+  ApitogoEvents,
+  ZudokuContext,
+} from "./ZudokuContext.js";
+export { runPluginTransformConfig } from "./transform-config.js";
+
+export type ApitogoPlugin =
+  | CommonPlugin
+  | ProfileMenuPlugin
+  | NavigationPlugin
+  | ApiIdentityPlugin
+  | SearchProviderPlugin
+  | EventConsumerPlugin
+  | AuthenticationPlugin
+  | TransformConfigPlugin;
+
+export type { AuthenticationPlugin, RouteObject };
+
+export interface NavigationPlugin {
+  getRoutes: () => RouteObject[];
+  getNavigation?: (path: string, context: ZudokuContext) => Promise<Navigation>;
+  getProtectedRoutes?: () => ProtectedRoutesInput;
+}
+
+export const createApiIdentityPlugin = (
+  plugin: ApiIdentityPlugin,
+): ApiIdentityPlugin => plugin;
+
+export const createProfileMenuPlugin = (
+  plugin: ProfileMenuPlugin,
+): ProfileMenuPlugin => plugin;
+
+export interface ApiIdentityPlugin {
+  getIdentities: (context: ZudokuContext) => Promise<ApiIdentity[]>;
+}
+
+export interface SearchProviderPlugin {
+  renderSearch: (o: {
+    isOpen: boolean;
+    onClose: () => void;
+  }) => React.JSX.Element | null;
+}
+
+export interface ProfileMenuPlugin {
+  getProfileMenuItems: (context: ZudokuContext) => ProfileNavigationItem[];
+}
+
+export type ProfileNavigationItem = {
+  label: string;
+  path?: string;
+  target?: HTMLAttributeAnchorTarget;
+  weight?: number;
+  category?: "top" | "middle" | "bottom";
+  children?: ProfileNavigationItem[];
+  icon?: LucideIcon;
+};
+
+export interface ConfigHookContext {
+  mode: typeof process.env.ZUDOKU_ENV;
+  rootDir: string;
+  configPath: string;
+}
+
+export interface TransformConfigContext {
+  config: ZudokuConfig;
+  merge: <T extends Partial<ZudokuConfig>>(partial: T) => ZudokuConfig & T;
+}
+
+export interface TransformConfigPlugin {
+  transformConfig?: (
+    context: TransformConfigContext,
+  ) => ZudokuConfig | void | Promise<ZudokuConfig | void>;
+}
+
+export interface CommonPlugin {
+  initialize?: (
+    context: ZudokuContext,
+  ) => Promise<void | boolean> | void | boolean;
+  getHead?: (args: { location: Location }) => ReactNode | undefined;
+  getMdxComponents?: () => MdxComponentsType;
+}
+
+export type EventConsumerPlugin<Event extends ApitogoEvents = ApitogoEvents> = {
+  events: { [K in keyof Event]?: Event[K] };
+};
+
+export const isEventConsumerPlugin = (
+  obj: ApitogoPlugin,
+): obj is EventConsumerPlugin =>
+  "events" in obj && typeof obj.events === "object";
+
+export const isProfileMenuPlugin = (
+  obj: ApitogoPlugin,
+): obj is ProfileMenuPlugin =>
+  "getProfileMenuItems" in obj && typeof obj.getProfileMenuItems === "function";
+
+export const isNavigationPlugin = (
+  obj: ApitogoPlugin,
+): obj is NavigationPlugin =>
+  "getRoutes" in obj && typeof obj.getRoutes === "function";
+
+export const isAuthenticationPlugin = (
+  obj: ApitogoPlugin,
+): obj is AuthenticationPlugin =>
+  "signUp" in obj && typeof obj.signUp === "function";
+
+export const isSearchPlugin = (
+  obj: ApitogoPlugin,
+): obj is SearchProviderPlugin =>
+  "renderSearch" in obj && typeof obj.renderSearch === "function";
+
+export const needsInitialization = (obj: ApitogoPlugin): obj is CommonPlugin =>
+  "initialize" in obj && typeof obj.initialize === "function";
+
+export const hasHead = (obj: ApitogoPlugin): obj is CommonPlugin =>
+  "getHead" in obj && typeof obj.getHead === "function";
+
+export const isMdxProviderPlugin = (obj: ApitogoPlugin): obj is CommonPlugin =>
+  "getMdxComponents" in obj && typeof obj.getMdxComponents === "function";
+
+export const isApiIdentityPlugin = (
+  obj: ApitogoPlugin,
+): obj is ApiIdentityPlugin =>
+  "getIdentities" in obj && typeof obj.getIdentities === "function";
+
+export const isTransformConfigPlugin = (
+  obj: ApitogoPlugin,
+): obj is TransformConfigPlugin =>
+  "transformConfig" in obj && typeof obj.transformConfig === "function";

package/src/lib/core/react-query.ts

@@ -0,0 +1 @@
+export * from "@tanstack/react-query";

package/src/lib/core/router.ts

@@ -0,0 +1 @@
+export * from "react-router";

package/src/lib/core/transform-config.ts

@@ -0,0 +1,67 @@
+import { isValidElement } from "react";
+import type { ZudokuConfig } from "../../config/validators/ZudokuConfig.js";
+import { isTransformConfigPlugin } from "./plugins.js";
+
+export const isPlainObject = (
+  value: unknown,
+): value is Record<string, unknown> =>
+  typeof value === "object" &&
+  value !== null &&
+  !Array.isArray(value) &&
+  Object.getPrototypeOf(value) === Object.prototype;
+
+export const mergeConfig = <
+  T extends Record<string, unknown>,
+  S extends Record<string, unknown>,
+>(
+  target: T,
+  source: S,
+): T & S => {
+  const result = { ...target } as T & S;
+
+  for (const key of Object.keys(source) as (keyof S)[]) {
+    const sourceValue = source[key];
+    const targetValue = target[key as keyof T];
+
+    // Don't merge React elements, arrays, or non-plain objects - just replace
+    if (
+      isValidElement(sourceValue) ||
+      Array.isArray(sourceValue) ||
+      !isPlainObject(sourceValue)
+    ) {
+      (result as Record<string, unknown>)[key as string] = sourceValue;
+    } else if (isPlainObject(targetValue)) {
+      (result as Record<string, unknown>)[key as string] = mergeConfig(
+        targetValue,
+        sourceValue,
+      );
+    } else {
+      (result as Record<string, unknown>)[key as string] = sourceValue;
+    }
+  }
+
+  return result;
+};
+
+export const runPluginTransformConfig = async <T extends ZudokuConfig>(
+  config: T,
+): Promise<T> => {
+  const plugins = config.plugins ?? [];
+
+  let result = config;
+
+  for (const plugin of plugins.filter(isTransformConfigPlugin)) {
+    const merge = <T extends Record<string, unknown>>(partial: T) =>
+      mergeConfig(result, partial);
+
+    const transformed = await plugin.transformConfig?.({
+      config: result,
+      merge,
+    });
+    if (!transformed) continue;
+
+    result = transformed as T;
+  }
+
+  return result;
+};

package/src/lib/demo/DemoAnnouncement.tsx

@@ -0,0 +1,17 @@
+export const DemoAnnouncement = () => {
+  return (
+    <div className="text-center">
+      This demo version of your OpenAPI isn't as fast or flexible as
+      self-hosting.{" "}
+      <a
+        href="https://github.com/zuplo/zudoku"
+        className="underline hover:white"
+      >
+        Get started here
+      </a>{" "}
+      to see Zudoku at full tilt.
+    </div>
+  );
+};
+
+export default DemoAnnouncement;