zudoku 0.3.0-dev.7 → 0.3.0-dev.71

package/src/lib/core/DevPortalContext.ts

@@ -1,17 +1,16 @@
 import { QueryClient } from "@tanstack/react-query";
 import { type ReactNode } from "react";
-import { create } from "zustand";
 import { type AuthenticationProvider } from "../authentication/authentication.js";
+import type { ComponentsContextType } from "../components/context/ComponentsContext.js";
+import { type DevPortalPath } from "../components/DevPortal.js";
+import { Slotlets } from "../components/SlotletProvider.js";
+import type { MdxComponentsType } from "../util/MdxComponents.js";
 import {
-  type DevPortalPath,
-  type DevPortalProps,
-} from "../components/DevPortal.js";
-import {
+  type DevPortalPlugin,
   isApiIdentityPlugin,
   isNavigationPlugin,
-  needsInitialization,
-  type DevPortalPlugin,
   type NavigationPlugin,
+  needsInitialization,
 } from "./plugins.js";
 
 export interface ApiIdentity {
@@ -55,40 +54,72 @@ export type NavigationItem = {
   categories?: NavigationCategory[];
 };
 
-export type RoutingState = {
-  path?: string;
-};
-
 export const queryClient = new QueryClient();
 
-export const useRoutingState = create<RoutingState>(() => ({}));
-
 export type ApiKeyCache = "api-keys";
 export type DevPortalCacheKey = ApiKeyCache | string;
 
+type Metadata = Partial<{
+  title: string;
+  description: string;
+  logo: string;
+  favicon: string;
+  generator: string;
+  applicationName: string;
+  referrer: string;
+  keywords: string[];
+  authors: string[];
+  creator: string;
+  publisher: string;
+}>;
+
+type Page = Partial<{
+  pageTitle?: string;
+  logo?: {
+    src: {
+      light: string;
+      dark: string;
+    };
+    width?: string;
+    alt?: string;
+  };
+}>;
+
+export type ZudokuContextOptions = {
+  metadata?: Metadata;
+  page?: Page;
+  authentication?: AuthenticationProvider;
+  navigation: NavigationItem[];
+  plugins?: DevPortalPlugin[];
+  slotlets?: Slotlets;
+  mdx?: {
+    components?: MdxComponentsType;
+  };
+  overrides?: ComponentsContextType;
+};
+
 export class DevPortalContext {
-  private plugins: DevPortalPlugin[] = [];
+  public plugins: NonNullable<ZudokuContextOptions["plugins"]> = [];
+  public navigation: ZudokuContextOptions["navigation"];
+  public meta: ZudokuContextOptions["metadata"];
+  public page: ZudokuContextOptions["page"];
+  public authentication?: ZudokuContextOptions["authentication"];
   private navigationPlugins: NavigationPlugin[];
 
-  public navigation: NavigationItem[];
-  public meta: DevPortalProps["meta"];
-  public authentication?: AuthenticationProvider;
-  public state: typeof useRoutingState;
-
-  constructor(config: DevPortalProps) {
+  constructor(config: ZudokuContextOptions) {
     this.plugins = config.plugins ?? [];
     this.navigation = config.navigation;
     this.navigationPlugins = this.plugins.filter(isNavigationPlugin);
     this.authentication = config.authentication;
-    this.meta = config.meta;
-    this.state = useRoutingState;
+    this.meta = config.metadata;
+    this.page = config.page;
   }
 
   initialize = async () => {
     await Promise.all([
       this.plugins
         .filter(needsInitialization)
-        .map((plugin) => plugin.initialize(this)),
+        .map((plugin) => plugin.initialize?.(this)),
     ]);
   };
 
@@ -116,7 +147,7 @@ export class DevPortalContext {
     return navigations.flatMap((nav) => nav ?? []);
   };
 
-  async signRequest(request: Request) {
+  signRequest = async (request: Request) => {
     if (!this.authentication) {
       throw new Error("No authentication provider configured");
     }
@@ -126,5 +157,5 @@ export class DevPortalContext {
     request.headers.set("Authorization", `Bearer ${accessToken}`);
 
     return request;
-  }
+  };
 }

package/src/lib/core/plugins.ts

@@ -1,3 +1,4 @@
+import { type ReactElement } from "react";
 import { type RouteObject } from "react-router-dom";
 import {
   DevPortalContext,
@@ -10,9 +11,10 @@ export type PluginNavigationCategory = {
 } & NavigationCategory;
 
 export type DevPortalPlugin =
+  | CommonPlugin
+  | ProfileMenuPlugin
   | NavigationPlugin
-  | ApiIdentityPlugin
-  | InitializationPlugin;
+  | ApiIdentityPlugin;
 
 export interface NavigationPlugin {
   getRoutes: () => RouteObject[];
@@ -23,10 +25,26 @@ export interface ApiIdentityPlugin {
   getIdentities: (context: DevPortalContext) => Promise<ApiIdentity[]>;
 }
 
-export interface InitializationPlugin {
-  initialize: (context: DevPortalContext) => Promise<void> | void;
+export interface ProfileMenuPlugin {
+  getProfileMenuItems: (context: DevPortalContext) => NavigationItem[];
 }
 
+export type NavigationItem = {
+  label: string;
+  path?: string;
+  children?: NavigationItem[];
+};
+
+export interface CommonPlugin {
+  initialize?: (context: DevPortalContext) => Promise<void> | void;
+  getHead?: () => ReactElement | undefined;
+}
+
+export const isProfileMenuPlugin = (
+  obj: DevPortalPlugin,
+): obj is ProfileMenuPlugin =>
+  "getProfileMenuItems" in obj && typeof obj.getProfileMenuItems === "function";
+
 export const isNavigationPlugin = (
   obj: DevPortalPlugin,
 ): obj is NavigationPlugin =>
@@ -34,9 +52,12 @@ export const isNavigationPlugin = (
 
 export const needsInitialization = (
   obj: DevPortalPlugin,
-): obj is InitializationPlugin =>
+): obj is CommonPlugin =>
   "initialize" in obj && typeof obj.initialize === "function";
 
+export const hasHead = (obj: DevPortalPlugin): obj is CommonPlugin =>
+  "getHead" in obj && typeof obj.getHead === "function";
+
 export const isApiIdentityPlugin = (
   obj: DevPortalPlugin,
 ): obj is ApiIdentityPlugin =>

package/src/lib/errors/ErrorAlert.tsx

@@ -0,0 +1,21 @@
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function ErrorAlert({ error }: { error: any }) {
+  const message = error?.message ?? "Something went wrong";
+  const stack = error?.stack;
+
+  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="mx-auto max-w-[85%] sm:max-w-[50%]">
+        <h1 className="text-4xl font-bold tracking-tight text-h1-text sm:text-5xl">
+          Something went wrong
+        </h1>
+        <p className="mt-5 text-h1-text">{message}</p>
+        {stack ? (
+          <pre className="mt-5 max-h-[400px] w-full overflow-scroll rounded-md border border-input-border bg-input-background p-3 text-property-name-text text-red-700">
+            {stack}
+          </pre>
+        ) : null}
+      </div>
+    </div>
+  );
+}

package/src/lib/errors/RouterError.tsx

@@ -0,0 +1,13 @@
+import { isRouteErrorResponse, useRouteError } from "react-router-dom";
+import { NotFoundPage } from "../components/NotFoundPage.js";
+import { ErrorAlert } from "./ErrorAlert.js";
+
+export function RouterError() {
+  const error = useRouteError();
+
+  if (isRouteErrorResponse(error) && error.status === 404) {
+    return <NotFoundPage />;
+  }
+
+  return <ErrorAlert error={error} />;
+}

package/src/lib/errors/ServerError.tsx

@@ -0,0 +1,5 @@
+import { ErrorAlert } from "./ErrorAlert.js";
+
+export function ServerError({ error }: { error: unknown }) {
+  return <ErrorAlert error={error} />;
+}

package/src/lib/errors/TopLevelError.tsx

@@ -0,0 +1,8 @@
+import { FallbackProps } from "react-error-boundary";
+import { ErrorAlert } from "./ErrorAlert.js";
+
+export function TopLevelError({ error, resetErrorBoundary }: FallbackProps) {
+  // Call resetErrorBoundary() to reset the error boundary and retry the render.
+
+  return <ErrorAlert error={error} />;
+}

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

@@ -36,16 +36,20 @@ type OperationLike = {
   method: string;
 };
 export const slugifyOperation = (operation: OperationLike, tag?: string) => {
+  const summary =
+    operation.summary +
+    (operation.operationId
+      ? "-" + operation.operationId.slice(0, operation.summary ? 4 : 12)
+      : "");
+
   return slugify(
     (tag ? tag + "-" : "") +
-      (operation.summary ??
-        operation.operationId ??
-        `${operation.method}-${operation.path}`),
+      (summary || `${operation.method}-${operation.path}`),
     { lower: true, trim: true },
   );
 };
 
-const cache = new LRUCache<string, OpenAPIDocument>({
+const cache = new LRUCache<string, Promise<OpenAPIDocument>>({
   ttl: 60 * 10 * 1000,
   ttlAutopurge: true,
 });
@@ -384,7 +388,7 @@ const loadOpenAPISchema = async (input: NonNullable<unknown>) => {
     return cache.get(hash)!;
   }
 
-  const schema = await validate(input);
+  const schema = validate(input);
 
   cache.set(hash, schema);
 

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

@@ -1,3 +1,4 @@
+import { GraphQLError } from "graphql/error/index.js";
 import { OpenAPIV3, type OpenAPIV3_1 } from "openapi-types";
 import { dereference, type JSONSchema } from "./dereference/index.js";
 import { upgradeSchema } from "./upgrade/index.js";
@@ -9,10 +10,6 @@ type DeepOmitReference<T> = T extends ReferenceObject
     ? { [K in keyof T]: DeepOmitReference<T[K]> }
     : T;
 
-// type Prettify<T> = {
-//   [K in keyof T]: T[K];
-// } & {};
-
 export type OpenAPIDocument = DeepOmitReference<OpenAPIV3_1.Document>;
 export type ResponseObject = DeepOmitReference<OpenAPIV3_1.ResponseObject>;
 export type OperationObject = DeepOmitReference<OpenAPIV3_1.OperationObject>;
@@ -46,35 +43,63 @@ export const HttpMethods = Object.values(OpenAPIV3.HttpMethods);
 // };
 
 const parseSchemaInput = async (
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  schemaInput: any,
+  schemaInput: unknown,
 ): Promise<JSONSchema & { openapi?: string }> => {
   if (typeof schemaInput === "string") {
     if (schemaInput.trim().startsWith("{")) {
-      return JSON.parse(schemaInput);
+      try {
+        return JSON.parse(schemaInput);
+      } catch (err) {
+        throw new GraphQLError("Invalid JSON schema", {
+          originalError: err,
+        });
+      }
     }
     if (schemaInput.includes("://")) {
-      const response = await fetch(schemaInput);
-      return (await response.json()) as JSONSchema;
+      let response;
+      try {
+        response = await fetch(schemaInput, {
+          cache: "force-cache",
+        });
+      } catch (err) {
+        throw new GraphQLError("Failed to fetch schema", {
+          originalError: err,
+        });
+      }
+
+      if (!response.ok) {
+        throw new GraphQLError(
+          `Failed to fetch schema: ${response.statusText}`,
+        );
+      }
+
+      try {
+        return (await response.json()) as JSONSchema;
+      } catch (err) {
+        throw new GraphQLError("Fetched invalid JSON schema", {
+          originalError: err,
+        });
+      }
     }
     const yaml = await import("yaml");
-    return yaml.parse(schemaInput);
+    const parsed = yaml.parse(schemaInput);
+
+    if (typeof parsed === "object") return parsed;
   }
 
-  if (typeof schemaInput === "object") return schemaInput;
+  if (typeof schemaInput === "object") return schemaInput as JSONSchema;
 
-  throw new Error("Unsupported schema input");
+  throw new GraphQLError("Unsupported schema input: " + schemaInput);
 };
 
 /**
  * Validates, dereferences and upgrades the OpenAPI schema (to v3.1) if necessary.
  */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export const validate = async (schemaInput: any) => {
+export const validate = async (schemaInput: unknown) => {
   const schema = await parseSchemaInput(schemaInput);
 
   if (!schema.openapi) {
-    throw new Error("OpenAPI version is not defined");
+    throw new GraphQLError("OpenAPI version is not defined");
   }
 
   // const validator = await getValidator(schema.openapi);
@@ -86,9 +111,5 @@ export const validate = async (schemaInput: any) => {
 
   const dereferenced = await dereference(schema);
 
-  const upgraded = upgradeSchema(
-    dereferenced as OpenAPIV3_1.Document | OpenAPIV3.Document,
-  );
-
-  return upgraded;
+  return upgradeSchema(dereferenced);
 };

package/src/lib/plugins/{api-key → api-keys}/CreateApiKey.tsx

@@ -2,7 +2,6 @@ import { useMutation } from "@tanstack/react-query";
 import { useForm } from "react-hook-form";
 import { Link, useNavigate } from "react-router-dom";
 import { useDevPortal } from "../../components/context/DevPortalProvider.js";
-import { Input } from "../../components/Input.js";
 import {
   Select,
   SelectContent,
@@ -12,6 +11,7 @@ import {
   SelectValue,
 } from "../../components/Select.js";
 import { Button } from "../../ui/Button.js";
+import { Input } from "../../ui/Input.js";
 import { ApiKeyService } from "./index.js";
 
 type CreateApiKey = { description: string; expiresOn?: string };
@@ -47,7 +47,7 @@ export const CreateApiKey = ({ service }: { service: ApiKeyService }) => {
 
   return (
     <div className="max-w-screen-lg pt-[--padding-content-top] pb-[--padding-content-bottom]">
-      <div className="flex justify-between mb-4 border-b border-border pb-1">
+      <div className="flex justify-between mb-4 border-b pb-1">
         <h1 className="font-medium text-2xl">New API Key</h1>
       </div>
       <form

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

@@ -0,0 +1,29 @@
+import { Outlet } from "react-router-dom";
+import { useAuth } from "../../authentication/hook.js";
+import { DeveloperHint } from "../../components/DeveloperHint.js";
+import { Button } from "../../ui/Button.js";
+
+export const ProtectedRoute = () => {
+  const auth = useAuth();
+
+  // TODO: should we suspend here somehow?
+  if (auth.isAuthEnabled && auth.isPending) {
+    return null;
+  }
+
+  return auth.isAuthenticated ? (
+    <Outlet />
+  ) : !auth.isAuthEnabled ? (
+    <div className="flex flex-col justify-center gap-2 items-center h-1/2">
+      <DeveloperHint className="max-w-[600px]">
+        Authentication needs to be enabled for API keys to work. Enable it in
+        your Zudoku configuration under <code>authentication</code>.
+      </DeveloperHint>
+    </div>
+  ) : (
+    <div className="flex flex-col justify-center gap-2 items-center h-1/2">
+      Please login first to view this page
+      <Button onClick={() => auth.login()}>Login</Button>
+    </div>
+  );
+};

package/src/lib/plugins/{api-key → api-keys}/SettingsApiKeys.tsx

@@ -7,7 +7,9 @@ import { EyeIcon, EyeOffIcon, RotateCwIcon, TrashIcon } from "lucide-react";
 import { useState } from "react";
 import { Link } from "react-router-dom";
 import { useDevPortal } from "../../components/context/DevPortalProvider.js";
+import { Slotlet } from "../../components/SlotletProvider.js";
 import { Button } from "../../ui/Button.js";
+import { cn } from "../../util/cn.js";
 import { ApiKeyService } from "./index.js";
 
 export const SettingsApiKeys = ({ service }: { service: ApiKeyService }) => {
@@ -34,7 +36,7 @@ export const SettingsApiKeys = ({ service }: { service: ApiKeyService }) => {
 
   return (
     <div className="max-w-screen-lg h-full pt-[--padding-content-top] pb-[--padding-content-bottom]">
-      <div className="flex justify-between mb-4 border-b border-border pb-3">
+      <div className="flex justify-between mb-4 border-b pb-3">
         <h1 className="font-medium text-2xl">API Keys</h1>
         {service.createKey && (
           <Button asChild>
@@ -43,6 +45,8 @@ export const SettingsApiKeys = ({ service }: { service: ApiKeyService }) => {
         )}
       </div>
 
+      <Slotlet name="api-keys-list-page-before-keys" />
+
       {data.length === 0 ? (
         <div className="flex flex-col justify-center gap-4 items-center h-1/2 my-8">
           <div className="text-center">
@@ -57,10 +61,15 @@ export const SettingsApiKeys = ({ service }: { service: ApiKeyService }) => {
           )}
         </div>
       ) : (
-        <ul className="grid grid-cols-[minmax(250px,min-content)_1fr_min-content] ">
-          {data.map((key: any) => (
+        <ul
+          className={cn(
+            "grid grid-cols-1  rounded border",
+            "lg:grid-cols-[minmax(250px,min-content)_1fr_min-content]",
+          )}
+        >
+          {data.map((key) => (
             <li
-              className="border-b border-border p-5 grid grid-cols-subgrid col-span-full gap-2 items-center"
+              className="border-b p-5 grid grid-cols-subgrid col-span-full gap-2 items-center"
               key={key.id}
             >
               <div className="flex flex-col gap-1 text-sm">
@@ -78,7 +87,7 @@ export const SettingsApiKeys = ({ service }: { service: ApiKeyService }) => {
                   )}
                 </div>
               </div>
-              <div className="items-center flex justify-center">
+              <div className="items-center flex lg:justify-center">
                 <RevealApiKey apiKey={key.key} />
               </div>
               <div className="flex gap-2">
@@ -116,10 +125,11 @@ const RevealApiKey = ({ apiKey }: { apiKey: string }) => {
   const [revealed, setRevealed] = useState(false);
 
   return (
-    <div className="flex gap-2 items-center text-sm">
-      <code className="border border-border rounded bg-gray-100 dark:bg-gray-950 p-1 font-mono">
-        {revealed ? apiKey : "•".repeat(apiKey.length)}
-      </code>
+    <div className="flex gap-2 items-center text-sm w-full">
+      <input
+        className="border rounded bg-gray-100 dark:bg-gray-950 p-1 font-mono max-w-min"
+        value={revealed ? apiKey : "•".repeat(apiKey.length)}
+      />
       <Button
         variant="outline"
         onClick={() => setRevealed((prev) => !prev)}

package/src/lib/plugins/{api-key → api-keys}/index.tsx

@@ -1,26 +1,25 @@
-import logger from "loglevel";
-import { Outlet, useRouteError } from "react-router-dom";
-import invariant from "tiny-invariant";
-import { useAuth } from "../../authentication/hook.js";
+import { type RouteObject } from "react-router-dom";
 import { DevPortalContext } from "../../core/DevPortalContext.js";
 import {
   type ApiIdentityPlugin,
   type DevPortalPlugin,
+  ProfileMenuPlugin,
 } from "../../core/plugins.js";
-import { Button } from "../../ui/Button.js";
+import { RouterError } from "../../errors/RouterError.js";
+import invariant from "../../util/invariant.js";
 import { CreateApiKey } from "./CreateApiKey.js";
+import { ProtectedRoute } from "./ProtectedRoute.js";
 import { SettingsApiKeys } from "./SettingsApiKeys.js";
 
-export type ApiKeyResults = Promise<ApiKey[]>;
 const DEFAULT_API_KEY_ENDPOINT =
   "https://zudoku-rewiringamerica-main-ef9c9c0.d2.zuplo.dev";
 
 export type ApiKeyService = {
-  getKeys: (context: DevPortalContext) => ApiKeyResults;
+  getKeys: (context: DevPortalContext) => Promise<ApiKey[]>;
   rollKey?: (id: string, context: DevPortalContext) => Promise<void>;
   deleteKey?: (id: string, context: DevPortalContext) => Promise<void>;
   updateKeyDescription?: (
-    apiKey: { jd: string; description: string },
+    apiKey: { id: string; description: string },
     context: DevPortalContext,
   ) => Promise<void>;
   getUsage?: (apiKeys: string[], context: DevPortalContext) => Promise<void>;
@@ -82,39 +81,9 @@ const createDefaultHandler = (endpoint: string): ApiKeyService => {
   };
 };
 
-const ProtectedRoute = () => {
-  const auth = useAuth();
-
-  // TODO: should we suspend here somehow?
-  if (auth.isPending) {
-    return null;
-  }
-
-  return auth.isAuthenticated ? (
-    <Outlet />
-  ) : (
-    <div className="flex flex-col justify-center gap-2 items-center h-1/2 my-12">
-      Please login first to view this page
-      <Button onClick={() => auth.login()}>Login</Button>
-    </div>
-  );
-};
-
-const SettingsErrorBoundary = () => {
-  const error = useRouteError();
-  logger.error(String(error));
-
-  return (
-    <div className="flex flex-col justify-center gap-2 items-center h-1/2 my-12">
-      <h1>Something went wrong</h1>
-      {error instanceof Error && <p>{error.message}</p>}
-    </div>
-  );
-};
-
 export const apiKeyPlugin = (
   options: ApiKeyPluginOptions,
-): DevPortalPlugin & ApiIdentityPlugin => {
+): DevPortalPlugin & ApiIdentityPlugin & ProfileMenuPlugin => {
   const endpoint =
     "endpoint" in options ? options.endpoint : DEFAULT_API_KEY_ENDPOINT;
 
@@ -122,6 +91,12 @@ export const apiKeyPlugin = (
     "getKeys" in options ? options : createDefaultHandler(endpoint);
 
   return {
+    getProfileMenuItems: () => [
+      {
+        label: "API Keys",
+        path: "/settings/api-keys",
+      },
+    ],
     getIdentities: async (context) => {
       try {
         const keys = await service.getKeys(context);
@@ -138,11 +113,12 @@ export const apiKeyPlugin = (
         return [];
       }
     },
-    getRoutes: () => {
+    getRoutes: (): RouteObject[] => {
+      // TODO: Make lazy
       return [
         {
           element: <ProtectedRoute />,
-          errorElement: <SettingsErrorBoundary />,
+          errorElement: <RouterError />,
           children: [
             {
               path: "/settings/api-keys",

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

@@ -0,0 +1,22 @@
+import type { ReactNode } from "react";
+import type { RouteObject } from "react-router-dom";
+import { ProseClasses } from "../../components/Markdown.js";
+import type { DevPortalPlugin, NavigationPlugin } from "../../core/plugins.js";
+
+type CustomPageConfig = Array<{
+  path: string;
+  element: ReactNode;
+}>;
+
+export const customPagePlugin = (
+  config: CustomPageConfig,
+): DevPortalPlugin & NavigationPlugin => {
+  return {
+    getRoutes: (): RouteObject[] =>
+      config.map(({ path, element }) => ({
+        path,
+        // TODO: we should componentize prose pages
+        element: <div className={ProseClasses + " max-w-full"}>{element}</div>,
+      })),
+  };
+};