zudoku 0.0.0-fb7d300 → 0.0.0-fc93837

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 ?? [];
@@ -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 }),
               ),
@@ -351,9 +352,12 @@ const OperationItem = builder
                 ([mediaType, { schema, examples }]) => ({
                   mediaType,
                   schema,
-                  examples: Object.entries(examples ?? {}).map(
-                    ([name, value]) => ({ name, ...value }),
-                  ),
+                  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,21 +42,34 @@ export const upgradeSchema = (schema: Record<string, any>): OpenAPIDocument => {
 
   schema = traverse(schema, (sub) => {
     if (sub.example !== undefined) {
-      sub.examples = {
-        default: {
-          value: 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;

package/src/lib/plugins/api-catalog/Catalog.tsx

@@ -0,0 +1,123 @@
+import slugify from "@sindresorhus/slugify";
+import { useSuspenseQuery } from "@tanstack/react-query";
+import { useSearchParams } from "react-router";
+import { Head, Link } from "zudoku/components";
+import { useAuthState } from "../../authentication/state.js";
+import { Markdown } from "../../components/Markdown.js";
+import { cn } from "../../util/cn.js";
+import type { ApiCatalogPluginOptions } from "./index.js";
+
+const getKey = (category: string, tag: string) => slugify(`${category}-${tag}`);
+
+export const Catalog = ({
+  items,
+  filterCatalogItems = (items) => items,
+  categories,
+  label = "API Library",
+}: Omit<ApiCatalogPluginOptions, "navigationId">) => {
+  const [searchParams, setSearchParams] = useSearchParams();
+  const activeCategory = searchParams.get("category");
+  const auth = useAuthState();
+
+  const catalogItems = useSuspenseQuery({
+    queryFn: () => filterCatalogItems(items, { auth }),
+    queryKey: ["catalogItems", auth],
+  });
+
+  return (
+    <section className="pt-[--padding-content-top] pb-[--padding-content-bottom]">
+      <Head>
+        <title>{label}</title>
+      </Head>
+      <div className="grid grid-cols-12 gap-12">
+        <div className="flex flex-col gap-4 col-span-3 not-prose sticky top-48">
+          <div className="max-w-[--side-nav-width] flex flex-col gap-4 justify-between">
+            {categories?.map((category, idx) => (
+              <div key={category.label}>
+                <div className="flex justify-between mb-2.5">
+                  <span className="font-medium text-sm">{category.label}</span>
+                  {idx === 0 && activeCategory && (
+                    <button
+                      type="button"
+                      className="text-end text-sm text-foreground/60 hover:text-foreground"
+                      onClick={() => setSearchParams({})}
+                    >
+                      Clear
+                    </button>
+                  )}
+                </div>
+                <ul className="space-y-1 [&>li]:py-2">
+                  {category.tags
+                    .map((tag) => ({
+                      tag,
+                      count: items.filter((api) =>
+                        api.categories.find((c) => c.tags.includes(tag)),
+                      ).length,
+                    }))
+                    .map(({ tag, count }) => {
+                      const slug = getKey(category.label, tag);
+                      const isActive = slug === activeCategory;
+
+                      return (
+                        <li
+                          key={slug}
+                          className={cn(
+                            "flex rounded-lg justify-between text-sm cursor-pointer hover:text-primary transition px-[--padding-nav-item] -mx-[--padding-nav-item]",
+                            isActive && "bg-border/30 rounded",
+                          )}
+                          onClick={() => setSearchParams({ category: slug })}
+                        >
+                          <span>{tag}</span>
+                          <span
+                            className={cn(
+                              "flex items-center justify-center border rounded-md w-8 text-xs font-semibold",
+                              isActive &&
+                                "bg-primary border-primary text-primary-foreground",
+                            )}
+                          >
+                            {count}
+                          </span>
+                        </li>
+                      );
+                    })}
+                </ul>
+              </div>
+            ))}
+          </div>
+        </div>
+        <div className="col-span-9">
+          <h3 className="mt-0 text-2xl font-bold mb-4">{label}</h3>
+
+          <div className="grid grid-cols-2 gap-4">
+            {catalogItems.data
+              .filter(
+                (api) =>
+                  !activeCategory ||
+                  api.categories.find((c) =>
+                    c.tags.find((t) => getKey(c.label, t) === activeCategory),
+                  ),
+              )
+              .map((api) => (
+                <Link
+                  to={{
+                    pathname: `/${api.path}`,
+                    search: activeCategory ? `category=${activeCategory}` : "",
+                  }}
+                  className="no-underline hover:!text-foreground"
+                  key={api.path}
+                >
+                  <div className="border h-full rounded p-4 flex flex-col gap-2 cursor-pointer hover:bg-border/20 font-normal">
+                    <span className="font-semibold">{api.label}</span>
+                    <Markdown
+                      className="text-sm whitespace-pre-wrap mb-6 line-clamp-2"
+                      content={api.description}
+                    />
+                  </div>
+                </Link>
+              ))}
+          </div>
+        </div>
+      </div>
+    </section>
+  );
+};

package/src/lib/plugins/api-catalog/index.tsx

@@ -0,0 +1,64 @@
+import type { AuthState } from "../../authentication/state.js";
+import type { ZudokuPlugin } from "../../core/plugins.js";
+import { Catalog } from "./Catalog.js";
+
+export type ApiCatalogItem = {
+  path: string;
+  label: string;
+  description: string;
+  categories: CatalogCategory[];
+};
+
+export type CatalogCategory = {
+  label: string;
+  tags: string[];
+};
+
+export type ApiCatalogPluginOptions = {
+  navigationId: string;
+  label: string;
+  categories?: CatalogCategory[];
+  items: ApiCatalogItem[];
+  filterCatalogItems?: filterCatalogItems;
+};
+
+export type CatalogContext<ProviderData = unknown> = {
+  auth: AuthState<ProviderData>;
+};
+
+export type filterCatalogItems<ProviderData = unknown> = (
+  items: ApiCatalogItem[],
+  { auth }: CatalogContext<ProviderData>,
+) => ApiCatalogItem[];
+
+export const apiCatalogPlugin = ({
+  navigationId,
+  items,
+  label,
+  categories,
+  filterCatalogItems,
+}: {
+  navigationId: string;
+  label: string;
+  categories?: CatalogCategory[];
+  items: ApiCatalogItem[];
+  filterCatalogItems?: filterCatalogItems;
+}): ZudokuPlugin => {
+  return {
+    getRoutes: () => {
+      return [
+        {
+          path: navigationId,
+          element: (
+            <Catalog
+              label={label}
+              items={items}
+              filterCatalogItems={filterCatalogItems}
+              categories={categories ?? []}
+            />
+          ),
+        },
+      ];
+    },
+  };
+};

package/src/lib/plugins/api-keys/CreateApiKey.tsx

@@ -1,6 +1,6 @@
 import { useMutation } from "@tanstack/react-query";
 import { useForm } from "react-hook-form";
-import { Link, useNavigate } from "react-router-dom";
+import { Link, useNavigate } from "react-router";
 import {
   Select,
   SelectContent,

package/src/lib/plugins/api-keys/ProtectedRoute.tsx

@@ -1,4 +1,4 @@
-import { Outlet } from "react-router-dom";
+import { Outlet } from "react-router";
 import { useAuth } from "../../authentication/hook.js";
 import { DeveloperHint } from "../../components/DeveloperHint.js";
 import { Button } from "../../ui/Button.js";

package/src/lib/plugins/api-keys/SettingsApiKeys.tsx

@@ -12,7 +12,7 @@ import {
   TrashIcon,
 } from "lucide-react";
 import { useState } from "react";
-import { Link } from "react-router-dom";
+import { Link } from "react-router";
 import { useZudoku } from "../../components/context/ZudokuContext.js";
 import { Slotlet } from "../../components/SlotletProvider.js";
 import { Button } from "../../ui/Button.js";

package/src/lib/plugins/api-keys/index.tsx

@@ -1,5 +1,5 @@
 import { FileKey2Icon } from "lucide-react";
-import { type RouteObject } from "react-router-dom";
+import { type RouteObject } from "react-router";
 import { ZudokuContext } from "../../core/ZudokuContext.js";
 import {
   type ApiIdentityPlugin,

package/src/lib/plugins/custom-pages/index.tsx

@@ -1,5 +1,5 @@
 import { type ComponentType, type ReactNode } from "react";
-import type { RouteObject } from "react-router-dom";
+import type { RouteObject } from "react-router";
 import { type ExposedComponentProps } from "../../components/SlotletProvider.js";
 import type { NavigationPlugin, ZudokuPlugin } from "../../core/plugins.js";
 import { CustomPage } from "./CustomPage.js";

package/src/lib/plugins/markdown/MdxPage.tsx

@@ -1,8 +1,8 @@
 import { useMDXComponents } from "@mdx-js/react";
 import slugify from "@sindresorhus/slugify";
 import { Helmet } from "@zudoku/react-helmet-async";
-import { type PropsWithChildren } from "react";
-import { Link } from "react-router-dom";
+import { type PropsWithChildren, useEffect } from "react";
+import { Link, useHref } from "react-router";
 import { CategoryHeading } from "../../components/CategoryHeading.js";
 import { Heading } from "../../components/Heading.js";
 import { ProseClasses } from "../../components/Markdown.js";
@@ -15,6 +15,14 @@ import { cn } from "../../util/cn.js";
 import { Toc } from "./Toc.js";
 import { MarkdownPluginDefaultOptions, MDXImport } from "./index.js";
 
+declare global {
+  interface Window {
+    __getReactRefreshIgnoredExports?: (args: {
+      id: string;
+    }) => string[] | undefined;
+  }
+}
+
 const MarkdownHeadings = {
   h2: ({ children, id }) => (
     <Heading level={2} id={id} registerSidebarAnchor>
@@ -30,16 +38,26 @@ const MarkdownHeadings = {
 
 export const MdxPage = ({
   mdxComponent: MdxComponent,
+  file,
   frontmatter = {},
   defaultOptions,
   tableOfContents,
+  excerpt,
 }: PropsWithChildren<
   Omit<MDXImport, "default"> & {
+    file: string;
     mdxComponent: MDXImport["default"];
     defaultOptions?: MarkdownPluginDefaultOptions;
   }
 >) => {
   const categoryTitle = useCurrentItem()?.categoryLabel;
+  let canonicalUrl = null;
+  const path = useHref("");
+  if (typeof window !== "undefined") {
+    const domain = window.location.origin;
+    canonicalUrl = `${domain}${path}`;
+  }
+
   const title = frontmatter.title;
   const category = frontmatter.category ?? categoryTitle;
   const hideToc = frontmatter.toc === false || defaultOptions?.toc === false;
@@ -57,10 +75,26 @@ export const MdxPage = ({
 
   const { prev, next } = usePrevNext();
 
+  useEffect(() => {
+    if (process.env.NODE_ENV === "development") {
+      window.__getReactRefreshIgnoredExports = ({ id }) => {
+        if (!id.endsWith(file)) return;
+
+        return ["frontmatter", "tableOfContents"];
+      };
+
+      return () => {
+        window.__getReactRefreshIgnoredExports = undefined;
+      };
+    }
+  }, [file]);
+
   return (
     <div className="xl:grid grid-cols-[--sidecar-grid-cols] gap-8 justify-between">
       <Helmet>
         <title>{pageTitle}</title>
+        {excerpt && <meta name="description" content={excerpt} />}
+        {canonicalUrl && <link rel="canonical" href={canonicalUrl} />}
       </Helmet>
       <div
         className={cn(

package/src/lib/plugins/markdown/index.tsx

@@ -1,7 +1,8 @@
 import type { Toc } from "@stefanprobst/rehype-extract-toc";
 import type { MDXProps } from "mdx/types.js";
-import { RouteObject } from "react-router-dom";
-import { ZudokuDocsConfig } from "../../../config/validators/validate.js";
+import { type JSX } from "react";
+import { RouteObject } from "react-router";
+import { ZudokuDocsConfig } from "../../../config/validators/common.js";
 import type { ZudokuPlugin } from "../../core/plugins.js";
 import { DocResolver } from "./resolver.js";
 
@@ -24,6 +25,7 @@ export type Frontmatter = {
 export type MDXImport = {
   tableOfContents: Toc;
   frontmatter: Frontmatter;
+  excerpt?: string;
   default: (props: MDXProps) => JSX.Element;
 };
 
@@ -57,6 +59,7 @@ export const markdownPlugin = (
             return {
               element: (
                 <MdxPage
+                  file={file}
                   mdxComponent={Component}
                   {...props}
                   defaultOptions={defaultOptions}

package/src/lib/plugins/markdown/resolver.ts

@@ -1,9 +1,7 @@
 import fs from "fs";
 import path from "path";
-import {
-  ZudokuConfig,
-  ZudokuDocsConfig,
-} from "../../../config/validators/validate.js";
+import { ZudokuDocsConfig } from "../../../config/validators/common.js";
+import { ZudokuConfig } from "../../../config/validators/validate.js";
 
 const DEFAULT_DOCS_FILES = "/pages/**/*.{md,mdx}";