zudoku 0.0.0-f2fd45c → 0.0.0-f3786a4

package/src/lib/components/navigation/utils.ts

@@ -1,4 +1,4 @@
-import { useLocation } from "react-router-dom";
+import { useLocation } from "react-router";
 import type {
   SidebarItem,
   SidebarItemCategory,
@@ -44,7 +44,7 @@ export const useCurrentItem = () => {
   const location = useLocation();
   const nav = useCurrentNavigation();
 
-  const currentSidebar = nav.data.sidebar;
+  const currentSidebar = nav.sidebar;
 
   return traverseSidebar(currentSidebar, (item) => {
     if (item.type === "doc" && joinPath(item.id) === location.pathname) {
@@ -79,7 +79,7 @@ export const usePrevNext = (): {
 } => {
   const currentId = useLocation().pathname;
   const nav = useCurrentNavigation();
-  const currentSidebar = nav.data.sidebar;
+  const currentSidebar = nav.sidebar;
 
   let prev;
   let next;

package/src/lib/core/RouteGuard.tsx

@@ -0,0 +1,35 @@
+import { useEffect } from "react";
+import { matchPath, Outlet, useLocation } from "react-router";
+import { useAuth } from "../authentication/hook.js";
+import { useZudoku } from "../components/context/ZudokuContext.js";
+import { ZudokuError } from "../util/invariant.js";
+
+export const RouteGuard = () => {
+  const auth = useAuth();
+  const zudoku = useZudoku();
+  const location = useLocation();
+
+  const isProtected = zudoku.options.protectedRoutes?.some((path) =>
+    matchPath({ path, end: true }, location.pathname),
+  );
+
+  useEffect(() => {
+    if (isProtected && !auth.isAuthenticated) {
+      void zudoku.authentication?.signIn();
+    }
+  }, [isProtected, auth.isAuthenticated, zudoku.authentication]);
+
+  if (isProtected && !auth.isAuthenticated) {
+    return null;
+  }
+
+  if (isProtected && !auth.isAuthEnabled) {
+    throw new ZudokuError("Authentication is not enabled", {
+      title: "Authentication is not enabled",
+      developerHint:
+        "To use protectedRoutes you need authentication to be enabled",
+    });
+  }
+
+  return <Outlet />;
+};

package/src/lib/core/{DevPortalContext.ts → ZudokuContext.ts}

@@ -1,18 +1,17 @@
-import { QueryClient } from "@tanstack/react-query";
 import { ReactNode } from "react";
+import { TopNavigationItem } from "../../config/validators/common.js";
 import type { SidebarConfig } from "../../config/validators/SidebarSchema.js";
-import { TopNavigationItem } from "../../config/validators/validate.js";
 import { type AuthenticationProvider } from "../authentication/authentication.js";
 import type { ComponentsContextType } from "../components/context/ComponentsContext.js";
 import { Slotlets } from "../components/SlotletProvider.js";
 import { joinPath } from "../util/joinPath.js";
 import type { MdxComponentsType } from "../util/MdxComponents.js";
 import {
-  type DevPortalPlugin,
   isApiIdentityPlugin,
   isNavigationPlugin,
   type NavigationPlugin,
   needsInitialization,
+  type ZudokuPlugin,
 } from "./plugins.js";
 
 export interface ApiIdentity {
@@ -21,10 +20,7 @@ export interface ApiIdentity {
   id: string;
 }
 
-export const queryClient = new QueryClient();
-
 export type ApiKeyCache = "api-keys";
-export type DevPortalCacheKey = ApiKeyCache | string;
 
 type Metadata = Partial<{
   title: string;
@@ -63,31 +59,32 @@ export type ZudokuContextOptions = {
   authentication?: AuthenticationProvider;
   topNavigation?: TopNavigationItem[];
   sidebars?: SidebarConfig;
-  plugins?: DevPortalPlugin[];
+  plugins?: ZudokuPlugin[];
   slotlets?: Slotlets;
   mdx?: {
     components?: MdxComponentsType;
   };
   overrides?: ComponentsContextType;
+  protectedRoutes?: string[];
 };
 
-export class DevPortalContext {
+export class ZudokuContext {
   public plugins: NonNullable<ZudokuContextOptions["plugins"]>;
   public sidebars: SidebarConfig;
   public topNavigation: NonNullable<ZudokuContextOptions["topNavigation"]>;
   public meta: ZudokuContextOptions["metadata"];
   public page: ZudokuContextOptions["page"];
   public authentication?: ZudokuContextOptions["authentication"];
-  private navigationPlugins: NavigationPlugin[];
+  private readonly navigationPlugins: NavigationPlugin[];
 
-  constructor(config: ZudokuContextOptions) {
-    this.plugins = config.plugins ?? [];
-    this.topNavigation = config.topNavigation ?? [];
-    this.sidebars = config.sidebars ?? {};
+  constructor(public readonly options: ZudokuContextOptions) {
+    this.plugins = options.plugins ?? [];
+    this.topNavigation = options.topNavigation ?? [];
+    this.sidebars = options.sidebars ?? {};
     this.navigationPlugins = this.plugins.filter(isNavigationPlugin);
-    this.authentication = config.authentication;
-    this.meta = config.metadata;
-    this.page = config.page;
+    this.authentication = options.authentication;
+    this.meta = options.metadata;
+    this.page = options.page;
   }
 
   initialize = async (): Promise<void> => {
@@ -98,10 +95,6 @@ export class DevPortalContext {
     );
   };
 
-  invalidateCache = async (key: DevPortalCacheKey[]) => {
-    await queryClient.invalidateQueries({ queryKey: key });
-  };
-
   getApiIdentities = async () => {
     const keys = await Promise.all(
       this.plugins

package/src/lib/core/plugins.ts

@@ -1,10 +1,11 @@
+import type { LucideIcon } from "lucide-react";
 import { type ReactElement } from "react";
-import { type RouteObject } from "react-router-dom";
+import { type RouteObject } from "react-router";
 import type { Sidebar } from "../../config/validators/SidebarSchema.js";
 import { MdxComponentsType } from "../util/MdxComponents.js";
-import { DevPortalContext, type ApiIdentity } from "./DevPortalContext.js";
+import { ZudokuContext, type ApiIdentity } from "./ZudokuContext.js";
 
-export type DevPortalPlugin =
+export type ZudokuPlugin =
   | CommonPlugin
   | ProfileMenuPlugin
   | NavigationPlugin
@@ -19,7 +20,7 @@ export interface NavigationPlugin {
 }
 
 export interface ApiIdentityPlugin {
-  getIdentities: (context: DevPortalContext) => Promise<ApiIdentity[]>;
+  getIdentities: (context: ZudokuContext) => Promise<ApiIdentity[]>;
 }
 
 export interface SearchProviderPlugin {
@@ -30,52 +31,51 @@ export interface SearchProviderPlugin {
 }
 
 export interface ProfileMenuPlugin {
-  getProfileMenuItems: (context: DevPortalContext) => ProfileNavigationItem[];
+  getProfileMenuItems: (context: ZudokuContext) => ProfileNavigationItem[];
 }
 
 export type ProfileNavigationItem = {
   label: string;
   path?: string;
+  weight?: number;
+  category?: "top" | "middle" | "bottom";
   children?: ProfileNavigationItem[];
+  icon?: LucideIcon;
 };
 
 export interface CommonPlugin {
   initialize?: (
-    context: DevPortalContext,
+    context: ZudokuContext,
   ) => Promise<void | boolean> | void | boolean;
   getHead?: () => ReactElement | undefined;
   getMdxComponents?: () => MdxComponentsType;
 }
 
 export const isProfileMenuPlugin = (
-  obj: DevPortalPlugin,
+  obj: ZudokuPlugin,
 ): obj is ProfileMenuPlugin =>
   "getProfileMenuItems" in obj && typeof obj.getProfileMenuItems === "function";
 
 export const isNavigationPlugin = (
-  obj: DevPortalPlugin,
+  obj: ZudokuPlugin,
 ): obj is NavigationPlugin =>
   "getRoutes" in obj && typeof obj.getRoutes === "function";
 
 export const isSearchPlugin = (
-  obj: DevPortalPlugin,
+  obj: ZudokuPlugin,
 ): obj is SearchProviderPlugin =>
   "renderSearch" in obj && typeof obj.renderSearch === "function";
 
-export const needsInitialization = (
-  obj: DevPortalPlugin,
-): obj is CommonPlugin =>
+export const needsInitialization = (obj: ZudokuPlugin): obj is CommonPlugin =>
   "initialize" in obj && typeof obj.initialize === "function";
 
-export const hasHead = (obj: DevPortalPlugin): obj is CommonPlugin =>
+export const hasHead = (obj: ZudokuPlugin): obj is CommonPlugin =>
   "getHead" in obj && typeof obj.getHead === "function";
 
-export const isMdxProviderPlugin = (
-  obj: DevPortalPlugin,
-): obj is CommonPlugin =>
+export const isMdxProviderPlugin = (obj: ZudokuPlugin): obj is CommonPlugin =>
   "getMdxComponents" in obj && typeof obj.getMdxComponents === "function";
 
 export const isApiIdentityPlugin = (
-  obj: DevPortalPlugin,
+  obj: ZudokuPlugin,
 ): obj is ApiIdentityPlugin =>
   "getIdentities" in obj && typeof obj.getIdentities === "function";

package/src/lib/errors/ErrorAlert.tsx

@@ -5,6 +5,7 @@ import { ZudokuError } from "../util/invariant.js";
 export function ErrorAlert({ error }: { error: unknown }) {
   const message =
     error instanceof Error ? error.message : "Something went wrong";
+
   const hint = error instanceof ZudokuError ? error.developerHint : undefined;
   const title =
     error instanceof ZudokuError ? error.title : "Something went wrong";
@@ -12,7 +13,7 @@ export function ErrorAlert({ error }: { error: unknown }) {
   const cause = error instanceof Error ? error.cause : undefined;
 
   return (
-    <div className="flex h-screen max-h-screen min-h-full items-center justify-center bg-primary-background px-4 py-16 lg:px-8">
+    <div className="flex h-screen max-h-[calc(100vh-var(--header-height))] min-h-full items-center justify-center bg-primary-background px-4 py-16 lg:px-8">
       <div className="mx-auto max-w-[85%] sm:max-w-[50%]">
         <h1 className="text-4xl font-bold tracking-tight text-h1-text sm:text-5xl">
           {title}

package/src/lib/errors/RouterError.tsx

@@ -1,4 +1,4 @@
-import { isRouteErrorResponse, useRouteError } from "react-router-dom";
+import { isRouteErrorResponse, useRouteError } from "react-router";
 import { NotFoundPage } from "../components/NotFoundPage.js";
 import { ErrorAlert } from "./ErrorAlert.js";
 

package/src/lib/oas/graphql/circular.ts

@@ -0,0 +1,29 @@
+import { GraphQLJSON } from "graphql-type-json";
+import { GraphQLScalarType } from "graphql/index.js";
+
+export const CIRCULAR_REF = "$[Circular Reference]";
+const handleCircularRefs = (obj: any, visited = new WeakSet()): any => {
+  if (obj === CIRCULAR_REF) return CIRCULAR_REF;
+  if (obj === null || typeof obj !== "object") return obj;
+
+  if (visited.has(obj)) return CIRCULAR_REF;
+
+  visited.add(obj);
+
+  if (Array.isArray(obj)) {
+    return obj.map((item) => handleCircularRefs(item, visited));
+  }
+
+  const result: Record<string, any> = {};
+  for (const [key, value] of Object.entries(obj)) {
+    result[key] = handleCircularRefs(value, visited);
+  }
+  return result;
+};
+export const GraphQLJSONSchema = new GraphQLScalarType({
+  ...GraphQLJSON,
+  name: "JSONSchema",
+  description: "OpenAPI schema scalar type that handles circular references",
+  serialize: (value: unknown) =>
+    GraphQLJSON.serialize(handleCircularRefs(value)),
+});

package/src/lib/oas/graphql/index.ts

@@ -1,18 +1,15 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import SchemaBuilder from "@pothos/core";
 import {
-  slugifyWithCounter,
   type CountableSlugify,
+  slugifyWithCounter,
 } from "@sindresorhus/slugify";
 import { GraphQLJSON, GraphQLJSONObject } from "graphql-type-json";
 import { createYoga, type YogaServerOptions } from "graphql-yoga";
-import { LRUCache } from "lru-cache";
-import hashit from "object-hash";
 import {
-  HttpMethods,
-  validate,
   type EncodingObject,
   type ExampleObject,
+  HttpMethods,
   type OpenAPIDocument,
   type OperationObject,
   type ParameterObject,
@@ -20,7 +17,9 @@ import {
   type SchemaObject,
   type ServerObject,
   type TagObject,
+  validate,
 } from "../parser/index.js";
+import { GraphQLJSONSchema } from "./circular.js";
 
 export type {
   EncodingObject,
@@ -47,10 +46,7 @@ export const createOperationSlug = (
 ) => {
   const summary =
     (operation.summary ?? "") +
-    (operation.operationId
-      ? "-" +
-        operation.operationId.slice(0, operation.summary ? Infinity : Infinity)
-      : "");
+    (operation.operationId ? "-" + operation.operationId : "");
 
   return slugify(
     (tag ? tag + "-" : "") +
@@ -58,24 +54,26 @@ export const createOperationSlug = (
   );
 };
 
-const cache = new LRUCache<string, OpenAPIDocument>({
-  ttl: 60 * 10 * 1000,
-  ttlAutopurge: true,
-  fetchMethod: (_key, _oldValue, { context }) => validate(context as string),
-});
+export type SchemaImports = Record<
+  string,
+  () => Promise<{ schema: OpenAPIDocument }>
+>;
 
 const builder = new SchemaBuilder<{
   Scalars: {
     JSON: any;
     JSONObject: any;
+    JSONSchema: any;
   };
   Context: {
     schema: OpenAPIDocument;
+    schemaImports?: SchemaImports;
   };
 }>({});
 
 const JSONScalar = builder.addScalarType("JSON", GraphQLJSON);
 const JSONObjectScalar = builder.addScalarType("JSONObject", GraphQLJSONObject);
+const JSONSchemaScalar = builder.addScalarType("JSONSchema", GraphQLJSONSchema);
 
 const getAllTags = (schema: OpenAPIDocument): TagObject[] => {
   const tags = schema.tags ?? [];
@@ -206,7 +204,7 @@ const ExampleItem = builder
       name: t.exposeString("name"),
       summary: t.exposeString("summary", { nullable: true }),
       description: t.exposeString("description", { nullable: true }),
-      value: t.exposeString("value", { nullable: true }),
+      value: t.expose("value", { type: JSONScalar, nullable: true }),
       externalValue: t.exposeString("externalValue", { nullable: true }),
     }),
   });
@@ -240,7 +238,7 @@ const ParameterItem = builder
           })),
         nullable: true,
       }),
-      schema: t.expose("schema", { type: JSONScalar, nullable: true }),
+      schema: t.expose("schema", { type: JSONSchemaScalar, nullable: true }),
     }),
   });
 
@@ -254,7 +252,7 @@ const MediaTypeItem = builder
   .implement({
     fields: (t) => ({
       mediaType: t.exposeString("mediaType"),
-      schema: t.expose("schema", { type: JSONScalar, nullable: true }),
+      schema: t.expose("schema", { type: JSONSchemaScalar, nullable: true }),
       examples: t.expose("examples", { type: [ExampleItem], nullable: true }),
       encoding: t.expose("encoding", { type: [EncodingItem], nullable: true }),
     }),
@@ -329,9 +327,12 @@ const OperationItem = builder
             ([mediaType, content]) => ({
               mediaType,
               schema: content.schema,
-              examples: Object.entries(content.examples ?? {}).map(
-                ([name, value]) => ({ name, ...value }),
-              ),
+              examples: content.examples
+                ? Object.entries(content.examples).map(([name, value]) => ({
+                    name,
+                    ...(typeof value === "string" ? { value } : value),
+                  }))
+                : [],
               encoding: Object.entries(content.encoding ?? {}).map(
                 ([name, value]) => ({ name, ...value }),
               ),
@@ -348,12 +349,15 @@ const OperationItem = builder
               statusCode,
               description: response.description,
               content: Object.entries(response.content ?? {}).map(
-                ([mediaType, mediaTypeObject]) => ({
+                ([mediaType, { schema, examples }]) => ({
                   mediaType,
-                  schema: mediaTypeObject.schema,
-                  examples: Object.entries(mediaTypeObject.examples ?? {}).map(
-                    ([name, value]) => ({ name, ...value }),
-                  ),
+                  schema,
+                  examples: examples
+                    ? Object.entries(examples).map(([name, value]) => ({
+                        name,
+                        ...(typeof value === "string" ? { value } : value),
+                      }))
+                    : [],
                 }),
               ),
               headers: response.headers,
@@ -379,7 +383,10 @@ const OperationItem = builder
 const Schema = builder.objectRef<OpenAPIDocument>("Schema").implement({
   fields: (t) => ({
     openapi: t.string({ resolve: (root) => root.openapi }),
-    url: t.string({ resolve: (root) => root.servers?.at(0)?.url ?? "/" }),
+    url: t.string({
+      resolve: (root) => root.servers?.at(0)?.url,
+      nullable: true,
+    }),
     servers: t.field({
       type: [ServerItem],
       resolve: (root) => root.servers ?? [],
@@ -390,6 +397,10 @@ const Schema = builder.objectRef<OpenAPIDocument>("Schema").implement({
       resolve: (root) => root.info.description,
       nullable: true,
     }),
+    summary: t.string({
+      resolve: (root) => root.info.summary,
+      nullable: true,
+    }),
     paths: t.field({
       type: [PathItem],
       resolve: (root) =>
@@ -428,18 +439,12 @@ const Schema = builder.objectRef<OpenAPIDocument>("Schema").implement({
   }),
 });
 
-const loadOpenAPISchema = async (input: NonNullable<unknown>) => {
-  const hash = hashit(input);
-  return await cache.forceFetch(hash, { context: input });
-};
-
 const SchemaSource = builder.enumType("SchemaType", {
   values: ["url", "file", "raw"] as const,
 });
 
 builder.queryType({
   fields: (t) => ({
-    // https://tan-cow-main-bce8a06.d2.zuplo.dev/openapi
     schema: t.field({
       type: Schema,
       args: {
@@ -447,10 +452,21 @@ builder.queryType({
         input: t.arg({ type: JSONScalar, required: true }),
       },
       resolve: async (_, args, ctx) => {
-        const schema = await loadOpenAPISchema(args.input!);
-        // for easier access of the whole schema in children resolvers
-        ctx.schema = schema;
+        let schema: OpenAPIDocument;
+
+        if (args.type === "file" && typeof args.input === "string") {
+          const loadSchema = ctx.schemaImports?.[args.input];
 
+          if (!loadSchema) {
+            throw new Error(`No schema loader found for path: ${args.input}`);
+          }
+          const module = await loadSchema();
+          schema = module.schema;
+        } else {
+          schema = await validate(args.input as string);
+        }
+
+        ctx.schema = schema;
         return schema;
       },
     }),

package/src/lib/oas/parser/dereference/index.ts

@@ -1,4 +1,5 @@
 import type { JSONSchema4, JSONSchema6 } from "json-schema";
+import { CIRCULAR_REF } from "../../graphql/circular.js";
 import { resolveLocalRef } from "./resolveRef.js";
 
 export type JSONSchema = JSONSchema4 | JSONSchema6;
@@ -21,12 +22,12 @@ export const dereference = async (
   }
 
   const cloned = structuredClone(schema);
-  const visited = new Set();
+  const visited = new Set<unknown>();
 
   const resolve = async (current: unknown, path: string) => {
     if (isIndexableObject(current)) {
       if (visited.has(current)) {
-        return current;
+        return CIRCULAR_REF;
       }
 
       visited.add(current);
@@ -39,15 +40,18 @@ export const dereference = async (
         if ("$ref" in current && typeof current.$ref === "string") {
           for (const resolver of resolvers) {
             const resolved = await resolver(current.$ref);
-            if (resolved) return resolved;
+            if (resolved) return await resolve(resolved, path);
           }
-          return await resolveLocalRef(cloned, current.$ref);
+          const resolved = await resolveLocalRef(cloned, current.$ref);
+          return await resolve(resolved, path);
         }
 
         for (const key in current) {
           current[key] = await resolve(current[key], `${path}/${key}`);
         }
       }
+
+      visited.delete(current);
     }
 
     return current;

package/src/lib/oas/parser/upgrade/index.ts

@@ -1,4 +1,5 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
+import { type RecordAny, traverse } from "../../../util/traverse.js";
 import type { OpenAPIDocument } from "../index.js";
 /**
  * Upgrade from OpenAPI 3.0.x to 3.1.0
@@ -6,30 +7,8 @@ import type { OpenAPIDocument } from "../index.js";
  * Taken from https://github.com/scalar/openapi-parser/blob/main/packages/openapi-parser/src/utils/upgradeFromThreeToThreeOne.ts
  * https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0
  */
-export function traverse(
-  specification: Record<string, any>,
-  transform: (specification: Record<string, any>) => Record<string, any>,
-) {
-  const result: Record<string, any> = {};
 
-  for (const [key, value] of Object.entries(specification)) {
-    if (Array.isArray(value)) {
-      result[key] = value.map((item) =>
-        typeof item === "object" && item !== null
-          ? traverse(item, transform)
-          : item,
-      );
-    } else if (typeof value === "object" && value !== null) {
-      result[key] = traverse(value, transform);
-    } else {
-      result[key] = value;
-    }
-  }
-
-  return transform(result);
-}
-
-export const upgradeSchema = (schema: Record<string, any>): OpenAPIDocument => {
+export const upgradeSchema = (schema: RecordAny): OpenAPIDocument => {
   if (schema.openapi?.startsWith("3.0")) {
     schema.openapi = "3.1.0";
   }
@@ -63,19 +42,34 @@ export const upgradeSchema = (schema: Record<string, any>): OpenAPIDocument => {
 
   schema = traverse(schema, (sub) => {
     if (sub.example !== undefined) {
-      sub.examples = {
-        default: sub.example,
-      };
+      const isExampleObject =
+        typeof sub.example === "object" &&
+        (sub.example.summary !== undefined ||
+          sub.example.description !== undefined ||
+          sub.example.value !== undefined ||
+          sub.example.externalValue !== undefined);
+
+      const exampleValue = isExampleObject
+        ? sub.example
+        : { value: sub.example };
+
+      if (!sub.examples) {
+        sub.examples = { default: exampleValue };
+      } else {
+        sub.examples = {
+          default: exampleValue,
+          ...sub.examples,
+        };
+      }
       delete sub.example;
     }
-
     return sub;
   });
 
   schema = traverse(schema, (sub) => {
     if (sub.type === "object" && sub.properties !== undefined) {
       for (const [, value] of Object.entries(sub.properties)) {
-        const v = (value ?? {}) as Record<string, any>;
+        const v = (value ?? {}) as RecordAny;
         if (v.type === "string" && v.format === "binary") {
           v.contentEncoding = "application/octet-stream";
           delete v.format;