zudoku 0.0.0-eb4182d → 0.0.0-eeace45

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

@@ -1,30 +1,23 @@
-import { matchPath, useRouteError, type RouteObject } from "react-router-dom";
-import { type DevPortalPlugin } from "../../core/plugins.js";
+import { matchPath } from "react-router";
+import { type ZudokuPlugin } from "../../core/plugins.js";
 import { graphql } from "./graphql/index.js";
-import {
-  Client as UrqlClient,
-  cacheExchange,
-  fetchExchange,
-} from "./util/urql.js";
 
 import { useQuery } from "@tanstack/react-query";
 import { CirclePlayIcon, LogInIcon } from "lucide-react";
-import { createClient } from "zudoku/openapi-worker";
 import type { SidebarItem } from "../../../config/validators/SidebarSchema.js";
 import { useAuth } from "../../authentication/hook.js";
-import { ErrorPage } from "../../components/ErrorPage.js";
 import { ColorMap } from "../../components/navigation/SidebarBadge.js";
-import { SyntaxHighlight } from "../../components/SyntaxHighlight.js";
 import { Button } from "../../ui/Button.js";
 import { joinPath } from "../../util/joinPath.js";
+import { GraphQLClient } from "./client/GraphQLClient.js";
 import { OasPluginConfig } from "./interfaces.js";
 import type { PlaygroundContentProps } from "./playground/Playground.js";
 import { PlaygroundDialog } from "./playground/PlaygroundDialog.js";
-import { GetServerQuery } from "./Sidecar.js";
 
 const GetCategoriesQuery = graphql(`
   query GetCategories($input: JSON!, $type: SchemaType!) {
     schema(input: $input, type: $type) {
+      url
       tags {
         __typename
         name
@@ -42,20 +35,6 @@ const GetCategoriesQuery = graphql(`
   }
 `);
 
-const OpenApiErrorPage = () => {
-  const error = useRouteError();
-  const message =
-    error instanceof Error ? (
-      <SyntaxHighlight code={error.message} />
-    ) : (
-      "An unknown error occurred"
-    );
-
-  return (
-    <ErrorPage category="Error" title="An error occurred" message={message} />
-  );
-};
-
 type InternalOasPluginConfig = { inMemory?: boolean };
 
 const MethodColorMap: Record<string, keyof typeof ColorMap> = {
@@ -70,17 +49,12 @@ const MethodColorMap: Record<string, keyof typeof ColorMap> = {
 
 export type OpenApiPluginOptions = OasPluginConfig & InternalOasPluginConfig;
 
-export const openApiPlugin = (
-  config: OpenApiPluginOptions,
-): DevPortalPlugin => {
+export const openApiPlugin = (config: OpenApiPluginOptions): ZudokuPlugin => {
   const basePath = joinPath(config.navigationId ?? "/reference");
 
-  const client = config.server
-    ? new UrqlClient({
-        url: config.server,
-        exchanges: [cacheExchange, fetchExchange],
-      })
-    : createClient({ useMemoryClient: config.inMemory ?? false });
+  const versions = config.type === "file" ? Object.keys(config.input) : [];
+
+  const client = new GraphQLClient(config);
 
   return {
     getHead: () => {
@@ -108,15 +82,13 @@ export const openApiPlugin = (
         ...props
       }: Partial<PlaygroundContentProps> & { requireAuth: boolean }) => {
         const auth = useAuth();
+        // We don't have the GraphQL context here
         const serverQuery = useQuery({
-          queryFn: async () => {
-            const result = await client.query(GetServerQuery, {
+          queryFn: () =>
+            client.fetch(GetCategoriesQuery, {
               type: config.type,
               input: config.input,
-            });
-
-            return result.data;
-          },
+            }),
           enabled: !server,
           queryKey: ["playground-server"],
         });
@@ -154,66 +126,74 @@ export const openApiPlugin = (
         return [];
       }
 
-      const { data } = await client.query(GetCategoriesQuery, {
-        input: config.input,
-        type: config.type,
-      });
-
-      if (!data) return [];
-
-      const categories = data.schema.tags
-        .filter((tag) => tag.operations.length > 0)
-        .map<SidebarItem>((tag) => ({
-          type: "category",
-          label: tag.name || "Other endpoints",
-          collapsible: true,
-          collapsed: false,
-          items: tag.operations.map((operation) => ({
-            type: "link",
-            label: operation.summary ?? operation.path,
-            href: `#${operation.slug}`,
-            badge: {
-              label: operation.method,
-              color: MethodColorMap[operation.method.toLowerCase()],
-            },
-          })),
-        }));
+      try {
+        const version =
+          versions.find((v) => path === joinPath(basePath, v)) ??
+          Object.keys(config.input).at(0);
+
+        const data = await client.fetch(GetCategoriesQuery, {
+          type: config.type,
+          input: config.type === "file" ? config.input[version!] : config.input,
+          version,
+        });
 
-      categories.unshift({
-        type: "link",
-        label: "Overview",
-        href: "#description",
-      });
+        const categories = data.schema.tags
+          .filter((tag) => tag.operations.length > 0)
+          .map<SidebarItem>((tag) => ({
+            type: "category",
+            label: tag.name || "Other endpoints",
+            collapsible: true,
+            collapsed: false,
+            items: tag.operations.map((operation) => ({
+              type: "link",
+              label: operation.summary ?? operation.path,
+              href: `#${operation.slug}`,
+              badge: {
+                label: operation.method,
+                color: MethodColorMap[operation.method.toLowerCase()]!,
+              },
+            })),
+          }));
+
+        categories.unshift({
+          type: "link",
+          label: "Overview",
+          href: "#description",
+        });
 
-      return categories;
+        return categories;
+      } catch {
+        return [];
+      }
     },
-    getRoutes: () =>
-      [
-        {
-          async lazy() {
-            const { OpenApiRoute } = await import("./Route.js");
-            return {
-              element: <OpenApiRoute client={client} config={config} />,
-            };
-          },
-          errorElement: <OpenApiErrorPage />,
-          children: [
-            {
-              path: basePath,
-              children: [
-                {
-                  index: true,
-                  async lazy() {
-                    const { OperationList } = await import(
-                      "./OperationList.js"
-                    );
-                    return { element: <OperationList /> };
-                  },
-                },
-              ],
-            },
-          ],
+    getRoutes: () => {
+      const versionsInPath = [null, ...versions];
+
+      return versionsInPath.map((version) => ({
+        path: basePath + (version ? `/${version}` : ""),
+        async lazy() {
+          const { OpenApiRoute } = await import("./Route.js");
+          return {
+            element: (
+              <OpenApiRoute
+                basePath={basePath}
+                versions={versions}
+                client={client}
+                config={config}
+              />
+            ),
+          };
         },
-      ] satisfies RouteObject[],
+        children: [
+          {
+            index: true,
+            async lazy() {
+              const { OperationList } = await import("./OperationList.js");
+              return { element: <OperationList /> };
+            },
+          },
+        ],
+      }));
+    },
   };
 };

package/src/lib/plugins/openapi/interfaces.ts

@@ -1,6 +1,19 @@
 type OasSource =
   | { type: "url"; input: string }
-  | { type: "file"; input: any }
+  | {
+      type: "file";
+      input: {
+        [version: string]: () => Promise<unknown>;
+      };
+    }
+  | { type: "raw"; input: string };
+
+export type ContextOasSource =
+  | { type: "url"; input: string }
+  | {
+      type: "file";
+      input: () => Promise<unknown>;
+    }
   | { type: "raw"; input: string };
 
 export type OasPluginConfig = {
@@ -8,3 +21,11 @@ export type OasPluginConfig = {
   navigationId?: string;
   skipPreload?: boolean;
 } & OasSource;
+
+export type OasPluginContext = {
+  server?: string;
+  navigationId?: string;
+  skipPreload?: boolean;
+  version?: string;
+  versions: Record<string, string>;
+} & ContextOasSource;

package/src/lib/plugins/openapi/playground/PathParams.tsx

@@ -50,6 +50,7 @@ export const PathParams = ({
                   render={({ field }) => (
                     <Input
                       {...field}
+                      required
                       placeholder="Enter value"
                       className="border-0 shadow-none ring-0 font-mono text-xs"
                     />

package/src/lib/plugins/openapi/playground/Playground.tsx

@@ -1,15 +1,15 @@
 import { useMutation } from "@tanstack/react-query";
 import { Fragment, useEffect, useRef, useTransition } from "react";
 import { FormProvider, useForm } from "react-hook-form";
-import { useSelectedServerStore } from "../../../authentication/state.js";
-import { useApiIdentities } from "../../../components/context/ZudokuContext.js";
 import {
   Select,
   SelectContent,
   SelectItem,
   SelectTrigger,
   SelectValue,
-} from "../../../components/Select.js";
+} from "zudoku/ui/Select.js";
+import { useSelectedServerStore } from "../../../authentication/state.js";
+import { useApiIdentities } from "../../../components/context/ZudokuContext.js";
 import { Spinner } from "../../../components/Spinner.js";
 import { Button } from "../../../ui/Button.js";
 import { Callout } from "../../../ui/Callout.js";
@@ -129,6 +129,7 @@ export const Playground = ({
             .filter((h) => h.name)
             .map((header) => [header.name, header.value]),
         ),
+        body: data.body ? data.body : undefined,
       });
 
       if (data.identity !== NO_IDENTITY) {
@@ -330,7 +331,7 @@ export const Playground = ({
               </TabsContent>
             </Tabs>
           </div>
-          <div className="p-8 bg-muted/70">
+          <div className="min-w-0 p-8 bg-muted/70">
             {queryMutation.error ? (
               <div className="flex flex-col gap-2">
                 {formState.pathParams.some((p) => p.value === "") && (

package/src/lib/plugins/openapi/playground/PlaygroundDialog.tsx

@@ -5,7 +5,7 @@ import {
   DialogContent,
   DialogTitle,
   DialogTrigger,
-} from "../../../components/Dialog.js";
+} from "zudoku/ui/Dialog.js";
 import { Playground, type PlaygroundContentProps } from "./Playground.js";
 
 export type PlaygroundDialogProps = PropsWithChildren<PlaygroundContentProps>;

package/src/lib/plugins/openapi/playground/ResponseTab.tsx

@@ -54,7 +54,6 @@ export const ResponseTab = ({
             view === "raw" ? (jsonContent ? "plain" : detectedLanguage) : "json"
           }
           noBackground
-          showLanguageIndicator
           // playground dialog has h-5/6 ≈ 83.333vh
           className="overflow-x-auto p-4 text-xs max-h-[calc(83.333vh-180px)]"
           code={view === "raw" ? body : beautifiedBody}

package/src/lib/plugins/openapi/post-processors/removeExtensions.test.ts

@@ -0,0 +1,144 @@
+import { describe, expect, it } from "vitest";
+import { removeExtensions } from "./removeExtensions.js";
+
+const baseDoc = {
+  openapi: "3.1.0",
+  "x-root-ext": "remove me",
+  info: {
+    title: "Test API",
+    version: "1.0.0",
+    "x-info-ext": "remove me",
+  },
+  paths: {
+    "/test": {
+      "x-path-ext": "remove me",
+      parameters: [
+        {
+          name: "param1",
+          in: "query",
+          schema: { type: "string" },
+          "x-param-ext": "remove me",
+        },
+      ],
+      get: {
+        "x-operation-ext": "remove me",
+        responses: {
+          "200": {
+            description: "OK",
+            "x-response-ext": "remove me",
+          },
+        },
+        parameters: [
+          {
+            name: "opParam1",
+            in: "header",
+            schema: { type: "string" },
+            "x-op-param-ext": "remove me",
+          },
+        ],
+      },
+    },
+  },
+  tags: [
+    {
+      name: "example",
+      "x-tag-ext": "remove me",
+    },
+  ],
+  components: {
+    securitySchemes: {
+      ApiKeyAuth: {
+        type: "apiKey",
+        name: "api_key",
+        in: "header",
+        "x-security-ext": "remove me",
+      },
+    },
+  },
+};
+
+describe("removeExtensions", () => {
+  it("removes all x- extensions by default", () => {
+    const processed = removeExtensions()(baseDoc);
+
+    const removedExtensions = [
+      "x-root-ext",
+      "info.x-info-ext",
+      "paths./test.x-path-ext",
+      "paths./test.parameters[0].x-param-ext",
+      "paths./test.get.x-operation-ext",
+      "paths./test.get.responses.200.x-response-ext",
+      "paths./test.get.parameters[0].x-op-param-ext",
+      "tags[0].x-tag-ext",
+      "components.securitySchemes.ApiKeyAuth.x-security-ext",
+    ];
+
+    removedExtensions.forEach((ext) => {
+      expect(processed).not.toHaveProperty(ext.split("."));
+    });
+
+    // Assert that non-x- fields remain unchanged
+    expect(processed.openapi).toBe("3.1.0");
+    expect(processed.info.title).toBe("Test API");
+    expect(processed).toHaveProperty(
+      ["paths", "/test", "get", "responses", "200", "description"],
+      "OK",
+    );
+    expect(processed.tags[0].name).toBe("example");
+  });
+
+  it("removes only specified x- extensions when names are provided", () => {
+    const docWithExtraExtensions = {
+      ...baseDoc,
+      info: { ...baseDoc.info, "x-other-ext": "keep me" },
+    };
+
+    const processed = removeExtensions({
+      keys: ["x-path-ext", "x-param-ext"],
+    })(docWithExtraExtensions);
+
+    // Assert specified extensions are removed
+    expect(processed.paths["/test"]["x-path-ext"]).toBeUndefined();
+    expect(
+      processed.paths["/test"].parameters[0]["x-param-ext"],
+    ).toBeUndefined();
+
+    // Assert other x- fields remain
+    expect(processed["x-root-ext"]).toBe("remove me");
+    expect(processed.info["x-info-ext"]).toBe("remove me");
+    expect(processed.info["x-other-ext"]).toBe("keep me");
+  });
+
+  it("handles deeply nested extensions", () => {
+    const deeplyNested = {
+      a: {
+        b: {
+          c: {
+            "x-deep-ext": "remove me",
+            d: {
+              e: "value",
+              "x-another-ext": "remove me",
+            },
+          },
+        },
+      },
+    };
+
+    const processed = removeExtensions()(deeplyNested);
+
+    expect(processed.a.b.c["x-deep-ext"]).toBeUndefined();
+    expect(processed.a.b.c.d["x-another-ext"]).toBeUndefined();
+    expect(processed.a.b.c.d.e).toBe("value");
+  });
+
+  it("does nothing if no x- extensions are present", () => {
+    const docWithoutExtensions = {
+      openapi: "3.1.0",
+      info: { title: "API without extensions" },
+    };
+
+    const processed = removeExtensions()(docWithoutExtensions);
+
+    expect(processed).toEqual(docWithoutExtensions);
+  });
+});

package/src/lib/plugins/openapi/post-processors/removeExtensions.ts

@@ -0,0 +1,24 @@
+import { type RecordAny, traverse } from "./traverse.js";
+
+interface RemoveExtensionsOptions {
+  keys?: string[];
+}
+
+// Remove all `x-` prefixed key/value pairs, or filter by names if provided
+export const removeExtensions =
+  ({ keys }: RemoveExtensionsOptions = {}) =>
+  (doc: RecordAny): RecordAny =>
+    traverse(doc, (spec) => {
+      const result: RecordAny = {};
+
+      for (const [key, value] of Object.entries(spec)) {
+        const isExtension = key.startsWith("x-");
+        const shouldRemove =
+          isExtension && (keys === undefined || keys.includes(key));
+
+        if (shouldRemove) continue;
+
+        result[key] = value;
+      }
+      return result;
+    });

package/src/lib/plugins/openapi/post-processors/removePaths.test.ts

@@ -0,0 +1,126 @@
+import { describe, expect, it } from "vitest";
+import { removePaths } from "./removePaths.js";
+
+const baseDoc = {
+  openapi: "3.0.3",
+  paths: {
+    "/example": {
+      get: { summary: "Get example" },
+      post: { summary: "Post example" },
+    },
+    "/remove-me": {
+      delete: { summary: "Delete example" },
+    },
+    "/another": {
+      get: { summary: "Another example" },
+    },
+  },
+};
+
+describe("removePaths", () => {
+  it("removes paths specified in the paths option", () => {
+    const processed = removePaths({
+      paths: {
+        "/remove-me": true,
+      },
+    })(baseDoc);
+
+    expect(processed.paths["/remove-me"]).toBeUndefined();
+    expect(processed.paths["/example"]).toBeDefined();
+    expect(processed.paths["/another"]).toBeDefined();
+  });
+
+  it("removes specific methods in the paths option", () => {
+    const processed = removePaths({
+      paths: {
+        "/example": ["get"],
+      },
+    })(baseDoc);
+
+    expect(processed.paths["/example"].get).toBeUndefined();
+    expect(processed.paths["/example"].post).toBeDefined();
+    expect(processed.paths["/remove-me"]).toBeDefined();
+  });
+
+  it("removes paths and methods using paths and shouldRemove together", () => {
+    const processed = removePaths({
+      paths: {
+        "/example": ["post"],
+      },
+      shouldRemove: ({ path }) => path.startsWith("/remove"),
+    })(baseDoc);
+
+    expect(processed.paths["/remove-me"]).toBeUndefined();
+    expect(processed.paths["/example"].get).toBeDefined();
+    expect(processed.paths["/example"].post).toBeUndefined();
+    expect(processed.paths["/another"]).toBeDefined();
+  });
+
+  it("removes paths based on shouldRemove callback", () => {
+    const processed = removePaths({
+      shouldRemove: ({ path }) => path.startsWith("/remove"),
+    })(baseDoc);
+
+    expect(processed.paths["/remove-me"]).toBeUndefined();
+    expect(processed.paths["/example"]).toBeDefined();
+    expect(processed.paths["/another"]).toBeDefined();
+  });
+
+  it("removes methods based on shouldRemove callback", () => {
+    const processed = removePaths({
+      shouldRemove: ({ method }) => method === "post",
+    })(baseDoc);
+
+    expect(processed.paths["/example"].post).toBeUndefined();
+    expect(processed.paths["/example"].get).toBeDefined();
+    expect(processed.paths["/remove-me"]).toBeDefined();
+  });
+
+  it("removes both paths and methods based on shouldRemove callback", () => {
+    const processed = removePaths({
+      shouldRemove: ({ path, method }) =>
+        path.startsWith("/remove") || method === "post",
+    })(baseDoc);
+
+    expect(processed.paths["/remove-me"]).toBeUndefined();
+    expect(processed.paths["/example"].post).toBeUndefined();
+    expect(processed.paths["/example"].get).toBeDefined();
+    expect(processed.paths["/another"]).toBeDefined();
+  });
+
+  it("does nothing if shouldRemove always returns false", () => {
+    const processed = removePaths({
+      shouldRemove: () => false,
+    })(baseDoc);
+
+    expect(processed).toEqual(baseDoc);
+  });
+
+  it("removes everything if shouldRemove always returns true", () => {
+    const processed = removePaths({
+      shouldRemove: () => true,
+    })(baseDoc);
+
+    expect(processed.paths).toEqual({});
+  });
+
+  it("removes entire paths via shouldRemove callback", () => {
+    const processed = removePaths({
+      shouldRemove: ({ path, method }) =>
+        method === true && path === "/remove-me",
+    })(baseDoc);
+
+    expect(processed.paths["/remove-me"]).toBeUndefined();
+    expect(processed.paths["/example"]).toBeDefined();
+    expect(processed.paths["/another"]).toBeDefined();
+  });
+
+  it("removes specific methods while keeping paths", () => {
+    const processed = removePaths({
+      shouldRemove: ({ method }) => method === "delete",
+    })(baseDoc);
+
+    expect(processed.paths["/remove-me"]).toBeDefined();
+    expect(processed.paths["/remove-me"].delete).toBeUndefined();
+  });
+});

package/src/lib/plugins/openapi/post-processors/removePaths.ts

@@ -0,0 +1,55 @@
+import { type RecordAny, traverse } from "./traverse.js";
+
+interface RemovePathsOptions {
+  // Path definitions, e.g., { '/path': true, '/path-2': ['get'] }
+  paths?: Record<string, true | string[]>;
+  shouldRemove?: (options: {
+    path: string;
+    method: true | string;
+    operation: RecordAny;
+  }) => boolean;
+}
+
+export const removePaths =
+  ({ paths = {}, shouldRemove }: RemovePathsOptions) =>
+  (doc: RecordAny): RecordAny =>
+    traverse(doc, (spec) => {
+      if (!spec.paths) return spec;
+
+      const updatedPaths: RecordAny = {};
+
+      for (const [path, methods] of Object.entries(spec.paths)) {
+        const operations = spec.paths[path];
+
+        // If the path is explicitly marked for removal in `paths`
+        if (paths[path] === true) continue;
+
+        // If the path should be removed via `shouldRemove`
+        if (shouldRemove?.({ path, method: true, operation: operations }))
+          continue;
+
+        if (typeof methods === "object" && methods !== null) {
+          const filteredPath = Object.fromEntries(
+            Object.entries(methods).filter(([method]) => {
+              const operations = spec.paths[path][method];
+              const isMethodToRemove =
+                Array.isArray(paths[path]) && paths[path].includes(method);
+
+              const isMethodFiltered = shouldRemove?.({
+                path,
+                method,
+                operation: operations,
+              });
+
+              return !isMethodToRemove && !isMethodFiltered;
+            }),
+          );
+
+          updatedPaths[path] = filteredPath;
+        } else {
+          updatedPaths[path] = methods;
+        }
+      }
+
+      return { ...spec, paths: updatedPaths };
+    });

package/src/lib/plugins/openapi/post-processors/traverse.ts

@@ -0,0 +1 @@
+export { traverse, type RecordAny } from "../../../util/traverse.js";