zudoku 0.0.2-dev.0

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

@@ -0,0 +1,108 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import type { OpenAPIDocument } from "../index.js";
+/**
+ * Upgrade from OpenAPI 3.0.x to 3.1.0
+ *
+ * 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 => {
+  if (schema.openapi?.startsWith("3.0")) {
+    schema.openapi = "3.1.0";
+  }
+
+  schema = traverse(schema, (sub) => {
+    if (sub.type !== "undefined" && sub.nullable === true) {
+      sub.type = ["null", sub.type];
+      delete sub.nullable;
+    }
+
+    return sub;
+  });
+
+  schema = traverse(schema, (sub) => {
+    if (sub.exclusiveMinimum === true) {
+      sub.exclusiveMinimum = sub.minimum;
+      delete sub.minimum;
+    } else if (sub.exclusiveMinimum === false) {
+      delete sub.exclusiveMinimum;
+    }
+
+    if (sub.exclusiveMaximum === true) {
+      sub.exclusiveMaximum = sub.maximum;
+      delete sub.maximum;
+    } else if (sub.exclusiveMaximum === false) {
+      delete sub.exclusiveMaximum;
+    }
+
+    return sub;
+  });
+
+  schema = traverse(schema, (sub) => {
+    if (sub.example !== undefined) {
+      sub.examples = {
+        default: sub.example,
+      };
+      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>;
+        if (v.type === "string" && v.format === "binary") {
+          v.contentEncoding = "application/octet-stream";
+          delete v.format;
+        }
+      }
+    }
+    return sub;
+  });
+
+  schema = traverse(schema, (sub) => {
+    if (sub.type === "string" && sub.format === "binary") {
+      return undefined as any;
+    }
+
+    return sub;
+  });
+
+  schema = traverse(schema, (sub) => {
+    if (sub.type === "string" && sub.format === "base64") {
+      return {
+        type: "string",
+        contentEncoding: "base64",
+      };
+    }
+
+    return sub;
+  });
+
+  return schema as OpenAPIDocument;
+};

package/src/app/plugins/api-key/SettingsApiKeys.tsx

@@ -0,0 +1,22 @@
+import { useApiIdentities } from "../../components/context/DevPortalProvider.js";
+import { type ApiKeyPluginOptions } from "./index.js";
+
+export const SettingsApiKeys = ({
+  options,
+}: {
+  options: ApiKeyPluginOptions;
+}) => {
+  const keys = useApiIdentities();
+
+  return (
+    <div className="prose dark:prose-invert">
+      <h1>Who's who</h1>
+      <button className="border">Create API Key</button>
+      <ul>
+        {keys.data.map((key) => (
+          <li>{key.name}</li>
+        ))}
+      </ul>
+    </div>
+  );
+};

package/src/app/plugins/api-key/index.tsx

@@ -0,0 +1,123 @@
+import { DevPortalSystemPaths } from "../../DevPortal.js";
+import { DevPortalContext } from "../../core/DevPortalContext.js";
+import {
+  type ApiIdentityPlugin,
+  type DevPortalPlugin,
+} from "../../core/plugins.js";
+import { SettingsApiKeys } from "./SettingsApiKeys.js";
+
+export type GetConsumerOptions =
+  | {
+      getConsumers: (context: DevPortalContext) => Promise<ConsumerData | void>;
+    }
+  | { consumerEndpoint: string };
+
+export type ApiKeyPluginOptions = {
+  rollKey?: (
+    id: string,
+    consumerName: string,
+    context: DevPortalContext,
+  ) => Promise<void>;
+  deleteKey?: (
+    id: string,
+    consumerName: string,
+    context: DevPortalContext,
+  ) => Promise<void>;
+  updateConsumerDescription?: (
+    consumerName: string,
+    description: string,
+    context: DevPortalContext,
+  ) => Promise<void>;
+  createConsumer?: (
+    description: string,
+    context: DevPortalContext,
+  ) => Promise<void>;
+  deleteConsumer?: (
+    consumerName: string,
+    context: DevPortalContext,
+  ) => Promise<void>;
+} & GetConsumerOptions;
+
+export interface ConsumerData {
+  consumers: Consumer[];
+}
+
+export interface Consumer {
+  name: string;
+  createdOn?: string;
+  description?: string;
+  apiKeys: ConsumerApiKey[];
+}
+
+export interface ConsumerApiKey {
+  id: string;
+  description?: string;
+  createdOn?: string;
+  updatedOn?: string;
+  expiresOn?: string;
+  key: string;
+}
+
+const defaultGetConsumers = async (context: DevPortalContext) => {
+  const accessToken = await context.authentication?.getToken?.(context);
+
+  if (!accessToken) {
+    throw new Error("No token found");
+  }
+
+  const consumers = await fetch(
+    "https://zudoku-customer-main-b36fa2f.d2.zuplo.dev/v1/developer/api-keys",
+    {
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+      },
+    },
+  );
+
+  return { consumers: [await consumers.json()] };
+};
+
+export const apiKeyPlugin = (
+  options: ApiKeyPluginOptions,
+): DevPortalPlugin & ApiIdentityPlugin => {
+  const getConsumers =
+    "getConsumers" in options ? options.getConsumers : defaultGetConsumers;
+
+  return {
+    getNavigation: async (path: string) => {
+      if (path !== DevPortalSystemPaths.Settings) {
+        return [];
+      }
+
+      return [
+        {
+          path: "settings/api-keys",
+          label: "API Keys",
+          children: [],
+        },
+      ];
+    },
+    getIdentities: async (context) => {
+      return [];
+      // throw new Error("Not implemented");
+      // const keys = await getConsumers(context);
+      // return (keys ?? { consumers: [] }).consumers
+      //   .flatMap((consumer) => consumer.apiKeys)
+      //   .map((key) => ({
+      //     authorizeRequest: (request: Request) => {
+      //       request.headers.set("Authorization", `Bearer ${key.key}`);
+      //     },
+      //     id: key.id,
+      //     name: key.id,
+      //   }));
+    },
+    getRoutes: () => {
+      return [
+        {
+          path: "/settings/api-keys",
+          element: <SettingsApiKeys options={options} />,
+        },
+      ];
+    },
+  };
+};

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

@@ -0,0 +1,128 @@
+import { useMemo, type PropsWithChildren, type ReactNode } from "react";
+import { Heading } from "../../Heading.js";
+import { CategoryHeading } from "../../components/CategoryHeading.js";
+import { ProseClasses } from "../../components/Markdown.js";
+import { useTopNavigationItem } from "../../components/context/DevPortalProvider.js";
+import { isPathItem } from "../../components/navigation/util.js";
+import { Helmet } from "../../core/helmet.js";
+import { Link, useLocation } from "../../core/router.js";
+import { cn } from "../../util/cn.js";
+import slugify from "../../util/slugify.js";
+import { traverseNavigation } from "../../util/traverseNavigation.js";
+import { Toc } from "./Toc.js";
+import type { MDXImport } from "./index.js";
+
+export const MdxPage = ({
+  children,
+  frontmatter,
+  tableOfContents,
+}: PropsWithChildren<Omit<MDXImport, "default">>) => {
+  const navItem = useTopNavigationItem();
+  const location = useLocation();
+
+  const categoryTitle = navItem
+    ? traverseNavigation(navItem, (_node, fullPath, parentNodes) => {
+        if (fullPath === location.pathname) {
+          return parentNodes.at(0)?.label;
+        }
+      })
+    : undefined;
+
+  const title = frontmatter?.title;
+  const category = frontmatter?.category ?? categoryTitle;
+  const hideToc = frontmatter?.toc === false;
+
+  const pageTitle =
+    tableOfContents.find((item) => item.depth === 1)?.value ?? title;
+
+  const tocEntries =
+    tableOfContents.find((item) => item.depth === 1)?.children ??
+    // if `title` is provided by frontmatter it does not appear in the table of contents
+    tableOfContents.filter((item) => item.depth === 2);
+
+  const showToc = !hideToc && tocEntries.length > 0;
+
+  const { prev, next } = useMemo(() => {
+    let prev = { path: "", label: "" as ReactNode };
+    let next = { path: "", label: "" as ReactNode };
+    let shouldStop = false;
+
+    if (!navItem) return { prev, next };
+
+    traverseNavigation(navItem, (node, fullPath) => {
+      const item = { path: fullPath, label: node.label };
+
+      if (shouldStop && isPathItem(node) && !node.children?.length) {
+        next = item;
+        return true;
+      }
+      if (fullPath === location.pathname) {
+        shouldStop = true;
+      }
+      if (!shouldStop && isPathItem(node) && !node.children?.length) {
+        prev = item;
+      }
+    });
+
+    return { prev, next } as const;
+  }, [navItem, location.pathname]);
+
+  return (
+    <div className="xl:grid grid-cols-[--sidecar-grid-cols] gap-8 justify-between">
+      <Helmet>
+        <title>{pageTitle}</title>
+      </Helmet>
+      <div
+        className={cn(
+          ProseClasses,
+          "mx-auto max-w-full xl:w-full xl:max-w-prose flex-1 flex-shrink pt-[--padding-content-top] pb-[--padding-content-bottom]",
+        )}
+      >
+        <header className="-translate-y-1">
+          {category && <CategoryHeading>{category}</CategoryHeading>}
+          {title && (
+            <Heading level={1} id={slugify(title, { lower: true })}>
+              {title}
+            </Heading>
+          )}
+          {frontmatter?.description && (
+            <p className="prose-lg">{frontmatter.description}</p>
+          )}
+        </header>
+        {children}
+        <hr />
+        <div className="not-prose flex items-center justify-between gap-8">
+          {prev.path ? (
+            <Link
+              to={prev.path}
+              className="flex flex-col items-stretch gap-2 flex-1 truncate border border-border rounded px-6 py-4 text-start hover:border-primary/85 transition shadow-sm hover:shadow-md"
+              title={typeof prev.label === "string" ? prev.label : undefined}
+            >
+              <div className="text-sm text-muted-foreground">
+                ← Previous page
+              </div>
+              <div className="text-lg text-primary truncate">{prev.label}</div>
+            </Link>
+          ) : (
+            <div className="flex-1" />
+          )}
+          {next.path ? (
+            <Link
+              to={next.path}
+              className="flex flex-col items-stretch gap-2 flex-1 truncate border border-border rounded px-6 py-4 text-end hover:border-primary/85 transition shadow-sm hover:shadow-md"
+              title={typeof next.label === "string" ? next.label : undefined}
+            >
+              <div className="text-sm text-muted-foreground">Next page →</div>
+              <div className="text-lg text-primary truncate">{next.label}</div>
+            </Link>
+          ) : (
+            <div className="flex-1" />
+          )}
+        </div>
+      </div>
+      <div className="hidden xl:block">
+        {showToc && <Toc entries={tocEntries} />}
+      </div>
+    </div>
+  );
+};

package/src/app/plugins/markdown/Toc.tsx

@@ -0,0 +1,122 @@
+import type { TocEntry } from "@stefanprobst/rehype-extract-toc";
+import {
+  useEffect,
+  useRef,
+  useState,
+  type CSSProperties,
+  type PropsWithChildren,
+} from "react";
+import { AnchorLink } from "../../components/AnchorLink.js";
+import { useViewportAnchor } from "../../components/context/ViewportAnchorContext.js";
+import { ListTreeIcon } from "../../core/icons.js";
+import { cn } from "../../util/cn.js";
+
+const DATA_ANCHOR_ATTR = "data-active";
+
+const TocItem = ({
+  item,
+  children,
+  className,
+  isActive,
+}: PropsWithChildren<{
+  item: TocEntry;
+  isActive: boolean;
+  className?: string;
+}>) => {
+  return (
+    <li
+      className={cn(
+        "truncate",
+        isActive
+          ? "text-primary"
+          : "text-foreground/65 dark:text-foreground/75",
+        className,
+      )}
+      title={item.value}
+    >
+      <AnchorLink
+        to={`#${item.id}`}
+        {...{ [DATA_ANCHOR_ATTR]: item.id }}
+        className={cn(
+          isActive
+            ? "text-primary"
+            : "text-foreground/65 dark:text-foreground/75 hover:text-foreground",
+        )}
+      >
+        {item.value}
+      </AnchorLink>
+      {children}
+    </li>
+  );
+};
+
+export const Toc = ({ entries }: { entries: TocEntry[] }) => {
+  const { activeAnchor } = useViewportAnchor();
+  const listWrapperRef = useRef<HTMLUListElement>(null);
+  const [indicatorStyle, setIndicatorStyles] = useState<CSSProperties>({});
+
+  // synchronize active anchor indicator with the scroll position
+  useEffect(() => {
+    if (!listWrapperRef.current) return;
+
+    const activeElement = listWrapperRef.current.querySelector(
+      `[${DATA_ANCHOR_ATTR}='${activeAnchor}']`,
+    );
+
+    if (!activeElement) {
+      setIndicatorStyles({
+        "--indicator-top": "0",
+        "--indicator-opacity": 0,
+      } as CSSProperties);
+      return;
+    }
+
+    const topParent = listWrapperRef.current.getBoundingClientRect().top;
+    const topElement = activeElement.getBoundingClientRect().top;
+
+    setIndicatorStyles({
+      "--indicator-top": `${topElement - topParent}px`,
+      "--indicator-opacity": 1,
+    } as CSSProperties);
+  }, [activeAnchor]);
+
+  return (
+    <aside className="sticky top-[--header-height] h-[calc(100vh-var(--header-height))] pt-[--padding-content-top] pb-[--padding-content-bottom] overflow-y-auto ps-1 text-sm">
+      <div className="flex items-center gap-2 font-medium mb-2">
+        <ListTreeIcon size={16} />
+        On this page
+      </div>
+
+      <ul
+        ref={listWrapperRef}
+        style={indicatorStyle}
+        className={cn(
+          "relative ms-2 ps-4 font-medium list-none mt-0 space-y-2",
+          "before:absolute before:inset-0 before:right-auto before:bg-border before:w-[2px]",
+          "after:absolute after:-left-px after:-translate-y-1 after:top-[--indicator-top] after:opacity-[--indicator-opacity] after:h-6 after:bg-primary after:w-[4px] after:rounded after:ease-out after:[transition:top__150ms,opacity_325ms]",
+        )}
+      >
+        {entries.map((item) => (
+          <TocItem
+            isActive={item.id === activeAnchor}
+            key={item.id}
+            item={item}
+            className="pl-0"
+          >
+            {item.children && (
+              <ul className="list-none pl-4 pt-2 space-y-2">
+                {item.children.map((child) => (
+                  <TocItem
+                    item={child}
+                    isActive={child.id === activeAnchor}
+                    key={child.id}
+                  />
+                ))}
+              </ul>
+            )}
+          </TocItem>
+        ))}
+      </ul>
+    </aside>
+  );
+};

package/src/app/plugins/markdown/generateRoutes.tsx

@@ -0,0 +1,72 @@
+import { Heading } from "../../Heading.js";
+import { useTopNavigationItem } from "../../components/context/DevPortalProvider.js";
+import { isPathItem } from "../../components/navigation/util.js";
+import { Navigate, type RouteObject } from "../../core/router.js";
+import type { MdxComponentsType } from "../../util/MdxComponents.js";
+import { traverseNavigation } from "../../util/traverseNavigation.js";
+import { MdxPage } from "./MdxPage.js";
+import type { MarkdownPluginOptions } from "./index.js";
+
+const MarkdownHeadings = {
+  h2: ({ children, id }) => (
+    <Heading level={2} id={id} children={children} registerSidebarAnchor />
+  ),
+  h3: ({ children, id }) => (
+    <Heading level={3} id={id} children={children} registerSidebarAnchor />
+  ),
+} satisfies MdxComponentsType;
+
+export const generateRoutes = (
+  markdownFiles: MarkdownPluginOptions["markdownFiles"],
+): RouteObject[] => {
+  const routes = Object.entries(markdownFiles).flatMap(
+    ([file, importPromise]) => {
+      // @todo we can pass in the folder name and then filter the markdown files based on that path
+      const match = file.match(/pages\/(.*).mdx?$/);
+      const path = match?.at(1);
+
+      if (!path) return [];
+
+      const pathSegments = path.split("/");
+      const isIndexFile = pathSegments.at(-1) === "index";
+      const routePath = isIndexFile
+        ? pathSegments.slice(0, -1).join("/")
+        : path;
+
+      return {
+        path: routePath,
+        lazy: async () => {
+          const { default: Component, ...props } = await importPromise();
+
+          return {
+            element: (
+              <MdxPage {...props}>
+                <Component components={MarkdownHeadings} />
+              </MdxPage>
+            ),
+          };
+        },
+      } satisfies RouteObject;
+    },
+  );
+
+  const rootRoutes = Array.from(
+    new Set(routes.map((route) => route.path.split("/").at(0))),
+  ).map((dir) => ({
+    path: `/${dir}`,
+    element: <Redirect />,
+  }));
+
+  return [...routes, ...rootRoutes];
+};
+
+const Redirect = () => {
+  const navItem = useTopNavigationItem();
+
+  if (!navItem) return null;
+
+  return traverseNavigation(navItem, (node, fullPath) => {
+    if ("children" in node || !isPathItem(node)) return;
+    return <Navigate to={fullPath} replace />;
+  });
+};

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

@@ -0,0 +1,31 @@
+import type { Toc } from "@stefanprobst/rehype-extract-toc";
+import type { MDXProps } from "mdx/types.js";
+import type { DevPortalPlugin } from "../../core/plugins.js";
+import { generateRoutes } from "./generateRoutes.js";
+
+export type MarkdownPluginOptions = {
+  markdownFiles: Record<string, () => Promise<MDXImport>>;
+};
+
+export type Frontmatter = {
+  title?: string;
+  description?: string;
+  category?: string;
+  toc?: boolean;
+};
+
+export type MDXImport = {
+  tableOfContents: Toc;
+  frontmatter: Frontmatter;
+  default: (props: MDXProps) => JSX.Element;
+};
+
+export const markdownPlugin = ({
+  markdownFiles,
+}: MarkdownPluginOptions): DevPortalPlugin => {
+  return {
+    getRoutes() {
+      return generateRoutes(markdownFiles);
+    },
+  };
+};

package/src/app/plugins/openapi/ColorizedParam.tsx

@@ -0,0 +1,73 @@
+import { useEffect, useRef, type ReactNode } from "react";
+import { useTheme } from "../../components/context/ThemeContext.js";
+import { cn } from "../../util/cn.js";
+import { pastellize } from "../../util/pastellize.js";
+
+const DATA_ATTR = "data-linked-param";
+
+export const ColorizedParam = ({
+  name,
+  className,
+  backgroundOpacity = "100%",
+  slug,
+  children,
+}: {
+  name: string;
+  className?: string;
+  backgroundOpacity?: string;
+  slug?: string;
+  children?: ReactNode;
+}) => {
+  const ref = useRef<HTMLSpanElement>(null);
+  const [isDark] = useTheme();
+  const normalized = name.replace("{", "").replace("}", "");
+
+  const color = pastellize(
+    normalized,
+    !isDark ? { saturation: 100, lightness: 70 } : undefined,
+  );
+
+  const borderColor = `hsl(${color})`;
+  const backgroundColor = `hsl(${color} / ${backgroundOpacity})`;
+
+  useEffect(() => {
+    if (!ref.current) return;
+
+    const onMouseEnter = () => {
+      document.querySelectorAll(`[${DATA_ATTR}="${slug}"]`).forEach((el) => {
+        if (el instanceof HTMLElement) {
+          el.dataset.active = "true";
+        }
+      });
+    };
+    const onMouseLeave = () => {
+      document.querySelectorAll(`[${DATA_ATTR}="${slug}"]`).forEach((el) => {
+        if (el instanceof HTMLElement) {
+          el.dataset.active = "false";
+        }
+      });
+    };
+
+    ref.current.addEventListener("mouseenter", onMouseEnter);
+    ref.current.addEventListener("mouseleave", onMouseLeave);
+
+    return () => {
+      ref.current?.removeEventListener("mouseenter", onMouseEnter);
+      ref.current?.removeEventListener("mouseleave", onMouseLeave);
+    };
+  }, [slug]);
+
+  return (
+    <span
+      className={cn("inline-flex relative rounded group", className)}
+      {...{ [DATA_ATTR]: slug }}
+      ref={ref}
+    >
+      <span
+        className="absolute inset-0 border-b-2 rounded transition-opacity duration-200 opacity-30 group-data-[active=true]:opacity-100"
+        style={{ borderColor, backgroundColor }}
+      />
+      <span className="relative">{children ?? name}</span>
+    </span>
+  );
+};